Project_Parva

# Project Parva

[![CI](https://github.com/dantwoashim/Project_Parva/actions/workflows/ci.yml/badge.svg)](https://github.com/dantwoashim/Project_Parva/actions/workflows/ci.yml)
[![Public verification](https://github.com/dantwoashim/Project_Parva/actions/workflows/public-verification.yml/badge.svg)](https://github.com/dantwoashim/Project_Parva/actions/workflows/public-verification.yml)
![Benchmark](public-benchmark/results/benchmark.svg)

Project Parva is an open-source Nepali date/time API and conformance project.

It covers BS to AD, AD to BS, Nepali date validation, holidays, working days,
Nepal fiscal year logic, BS month metadata, Panchanga computation, proof
receipts, local verification, SDKs, MCP tools, and public regression fixtures.

The project exists because Nepali date bugs often hide until a boundary is hit:
a frontend calendar table disagrees with backend data, a payroll month has the
wrong number of days, a datepicker accepts an invalid BS date, or a future BS
date changes after someone already used it in a workflow.

Parva treats those cases as conformance problems, not just conversion problems.
It records source and method provenance, separates exact evidence from
review-needed evidence, and gives developers a way to test what their Nepali
calendar API or Nepali date converter is actually doing.

Three public claims define the project:

- A documented market review dated `2026-08-05` found no second Nepal-focused
  API combining BS conversion, location-aware astronomical Panchanga, Nepal
  business rules, future-BS research, replay artifacts, and public conformance.
- The future-BS engine reaches `72/72` exact month predictions in chronological
  rolling validation over the official `2078-2083 BS` window, with each target
  year trained only on earlier years.
- The public benchmark and conformance suites ship with fixtures, runners,
  named-tool results, and per-case output.

## Start Here

- Quickstart: [docs/QUICKSTART.md](docs/QUICKSTART.md)
- OpenAPI snapshot: [docs/api-docs/openapi.json](docs/api-docs/openapi.json)
- API versioning: [docs/API_VERSIONING_AND_DEPRECATION.md](docs/API_VERSIONING_AND_DEPRECATION.md)
- Proof mode: [docs/PROOF_MODE.md](docs/PROOF_MODE.md)
- Panchanga engine: [docs/PANCHANGA_ENGINE.md](docs/PANCHANGA_ENGINE.md)
- Agent tooling guide: [docs/AGENT_TOOLING_GUIDE.md](docs/AGENT_TOOLING_GUIDE.md)
- Architecture: [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md)
- Migration status: [docs/architecture/MIGRATION_STATUS.md](docs/architecture/MIGRATION_STATUS.md)
- Artifact policy: [artifacts/POLICY.md](artifacts/POLICY.md)
- Safe claims: [docs/SAFE_CLAIMS.md](docs/SAFE_CLAIMS.md)
- Public benchmark: [public-benchmark/README.md](public-benchmark/README.md)
- Real-tool comparison: [public-benchmark/results/competitor-comparison.md](public-benchmark/results/competitor-comparison.md)
- Licensing: [docs/COMMERCIAL_LICENSING.md](docs/COMMERCIAL_LICENSING.md)
- Public conformance index: [docs/benchmarks/NEPALI_DATE_CONFORMANCE_INDEX.md](docs/benchmarks/NEPALI_DATE_CONFORMANCE_INDEX.md)
- Public failure classes: [docs/benchmarks/PUBLIC_NEPALI_DATE_FAILURE_CLASSES.md](docs/benchmarks/PUBLIC_NEPALI_DATE_FAILURE_CLASSES.md)
- Nepal compliance profile: [docs/conformance/nepal-compliance-profile.md](docs/conformance/nepal-compliance-profile.md)
- Yarsa source-drift case study: [docs/case-studies/yarsa-calendar-source-drift.md](docs/case-studies/yarsa-calendar-source-drift.md)
- External reviewer packet: [docs/external/REVIEWER_PACKET.md](docs/external/REVIEWER_PACKET.md)

Live public evaluation surfaces:

- Website: [https://prabinghimire1.com.np](https://prabinghimire1.com.np)
- API docs: [https://api.prabinghimire1.com.np/docs](https://api.prabinghimire1.com.np/docs)
- OpenAPI: [https://api.prabinghimire1.com.np/openapi.json](https://api.prabinghimire1.com.np/openapi.json)

The hosted API is a public evaluation deployment. First requests may be slower when the instance wakes up.

## Why This Exists

Most Nepali date bugs are small on paper and expensive in context.

Many systems carry hardcoded Bikram Sambat month tables. A backend CSV, a
frontend Nepali datepicker bundle, and a reporting job can each have their own
copy. They may all look reasonable until one month differs by a day.

That one day can move:

- a payroll period,
- a fiscal-year boundary,
- a certificate or DOB validation,
- an invoice/report date,
- an attendance or leave record,
- a future BS date that should have stayed review-needed.

Software agents add another failure mode: if the tool does not expose source,
confidence, and boundary data, the model will often answer as if the date is
settled. Parva is built to make those boundaries visible.

The project turns public Nepali date failures into fixtures and checks where
the evidence is exact enough. When the evidence is partial, it stays marked for
review instead of becoming a fake assertion.

## Free Nepali Date Risk Audit

If you maintain Nepal-facing payroll, ERP, accounting, attendance, school,
cooperative, public-service, government-form, or datepicker software, you can
send one small workflow or sample output.

No integration required. No dependency required. No sales call required. No
authority claim.

Good inputs:

- 10 sample BS/AD date outputs
- one payroll, fiscal-year, invoice, attendance, report, certificate, or DOB workflow
- one public repo, issue, Nepali datepicker, or library case
- one real edge case your team has seen in production or testing

Checks:

- BS/AD conversion boundaries
- invalid BS dates
- month lengths
- frontend/backend calendar source drift
- fiscal and payroll month boundaries
- holiday and working-day assumptions
- future BS dates that should be marked review-needed

You get:

- a short technical report
- pass, warning, and review-needed findings
- suggested regression tests
- source and provenance notes
- authority-boundary notes

Request one:

- GitHub: [dantwoashim](https://github.com/dantwoashim)
- Email: <twodan033@gmail.com>

Fast conformance path:

```powershell
py -3.11 tools\conformance_runner\run.py --suite public-nepali-date-issues
py -3.11 tools\conformance_runner\run.py --profile nepal-compliance
py -3.11 tools\conformance_runner\run.py --suite public-nepali-date-issues --write-report reports\conformance\public-issue-suite-summary.json
```

## What Parva Does

| Area | What it provides |
| --- | --- |
| Nepali date API | BS to AD, AD to BS, today, validation, month metadata, supported-range metadata |
| Civil proof mode | Replay-verifiable membranes for conversion, validation, holidays, working days, fiscal years, and BS months |
| Panchanga engine | Method-docketed sunrise, tithi, nakshatra, yoga, karana, paksha, vara, ephemeris metadata, and proof receipts |
| Payroll/date-risk audit | CSV/API-oriented decision-support checks for invalid dates, holidays, non-working days, fiscal boundaries, and review-required cases |
| Local verification | Shared proof fixtures and a buildable `@project-parva/local-kernel` npm package for offline replay checks |
| SDKs | Python and JavaScript clients with proof modes and conservative verification helpers |
| Agent/MCP | Read-only, public-safe agent tool wrappers and MCP adapter surfaces that preserve boundaries and review gates |
| Benchmark | Public Nepali Time Reliability Benchmark for deterministic date reasoning, source awareness, and review behavior |
| Governance | Source/method dockets, public claims checker, route maturity, OpenAPI drift checks, and reproducible public verification |
| Research boundary | Future-BS research kept separate from public authority claims, with compatibility shims only where older imports need them |

## Public Conformance Work

Parva tracks public Nepali date issues and turns them into fixtures or runnable
checks when the evidence is exact enough. The suite separates verified public
issues, reported issues, partial evidence, business workflow evidence, and
future-date review cases.

Project Parva's benchmark work contributed a standalone calendar source
consistency guard to `yarsa/nepal-compliance`.

That check compared duplicated frontend/backend BS month tables. It did not add
a Parva dependency, change upstream runtime behavior, or prove production
impact.

Run the public issue conformance suite:

```powershell
py -3.11 tools\conformance_runner\run.py --suite public-nepali-date-issues
py -3.11 tools\conformance_runner\run.py --profile nepal-compliance
py -3.11 tools\conformance_runner\run.py --suite public-nepali-date-issues --write-report reports\conformance\public-issue-suite-summary.json
py -3.11 -m pytest tests/conformance -q
```

Conformance docs:

- [Public conformance index](docs/benchmarks/NEPALI_DATE_CONFORMANCE_INDEX.md)
- [Failure classes from public issues](docs/benchmarks/PUBLIC_NEPALI_DATE_FAILURE_CLASSES.md)
- [Generated artifact: public issue summary](reports/conformance/public-issue-suite-summary.md)
- [Nepal compliance profile](docs/conformance/nepal-compliance-profile.md)
- [Yarsa source-drift case study](docs/case-studies/yarsa-calendar-source-drift.md)
- [Conformance Milestone 001](docs/releases/CONFORMANCE_MILESTONE_001.md)

These fixtures are public regression and review artifacts. They are not
calendar publication, legal guidance, tax guidance, payroll approval, banking
guidance, or ritual authority.

## Who This Helps

- Date library maintainers who want regression cases from real public issues.
- ERP, payroll, accounting, school, cooperative, and attendance teams that need
  safer BS/AD boundaries.
- Reviewers of public-service or government-form workflows where invalid BS
  dates should not slip through.
- Developers building a Nepali calendar API, Bikram Sambat API, or Nepali
  datepicker regression suite.
- Software-agent and MCP tool builders who need deterministic answers with
  proof receipts instead of guessed dates.
- Auditors and maintainers who need source notes, not broad claims.