Project Parva

Project Parva

网站 | API 文档 | 快速开始 | 公开基准测试 | 许可

Project Parva 是一个开源的尼泊尔日期/时间 API 与一致性项目。

它涵盖 BS 转 AD、AD 转 BS、尼泊尔日期校验、节假日、工作日、尼泊尔财年逻辑、BS 月份元数据、Panchanga 计算、证明回执、本地验证、SDK、MCP 工具以及公开回归测试夹具。

该项目之所以存在，是因为尼泊尔日期 bug 往往要到触及边界时才会暴露：前端日历表格与后端数据不一致、某个工资发放月份的天数错误、日期选择器接受了无效的 BS 日期，或者某个未来的 BS 日期在有人已将其用于工作流之后发生变化。

Parva 将这类情况视为一致性问题，而不仅仅是转换问题。它记录来源与方法溯源，区分精确证据与需要复核的证据，并为开发者提供一种方式来测试其尼泊尔日历 API 或尼泊尔日期转换器实际在做什么。

三项公开声明定义了该项目：

• 一份日期为 2026-08-05 的书面市场调研发现，不存在第二个聚焦尼泊尔的 API 能同时结合 BS 转换、位置感知的天文 Panchanga、尼泊尔业务规则、未来 BS 研究、回放产物以及公开一致性测试。
• 未来 BS 引擎在官方 2078-2083 BS 窗口上进行按时间顺序的滚动验证，达到 72/72 的精确月份预测，且每个目标年份仅使用更早的年份进行训练。
• 公开基准测试与一致性测试套件随附夹具、运行器、具名工具结果以及逐用例输出。

从这里开始

• 快速入门：docs/QUICKSTART.md
• OpenAPI 快照：docs/api-docs/openapi.json
• API 版本管理：docs/API_VERSIONING_AND_DEPRECATION.md
• 证明模式：docs/PROOF_MODE.md
• Panchanga 引擎：docs/PANCHANGA_ENGINE.md
• Agent 工具指南：docs/AGENT_TOOLING_GUIDE.md
• 架构：docs/architecture/ARCHITECTURE.md
• 迁移状态：docs/architecture/MIGRATION_STATUS.md
• 制品策略：artifacts/POLICY.md
• 安全声明：docs/SAFE_CLAIMS.md
• 公开基准：public-benchmark/README.md
• 真实工具对比：public-benchmark/results/competitor-comparison.md
• 许可：docs/COMMERCIAL_LICENSING.md
• 公开一致性索引：docs/benchmarks/NEPALI_DATE_CONFORMANCE_INDEX.md
• 公开失败类别：docs/benchmarks/PUBLIC_NEPALI_DATE_FAILURE_CLASSES.md
• 尼泊尔合规配置：docs/conformance/nepal-compliance-profile.md
• Yarsa 来源漂移案例研究：docs/case-studies/yarsa-calendar-source-drift.md
• 外部评审人资料包：docs/external/REVIEWER_PACKET.md

在线公开评估入口：

• 网站：https://prabinghimire1.com.np
• API 文档：https://api.prabinghimire1.com.np/docs
• OpenAPI：https://api.prabinghimire1.com.np/openapi.json

托管 API 是一个公开评估部署。实例唤醒时，首次请求可能会较慢。

为什么会有这个项目

大多数尼泊尔日期 bug 在纸面上很小，但在实际语境中代价高昂。

许多系统带有硬编码的 Bikram Sambat 月份表。一个后端 CSV、一个 前端尼泊尔日期选择器包，以及一个报表任务，可能各自都有一份自己的 副本。它们可能看起来都很合理，直到某个月相差了一天。

那一天可能会改变：

• 一个薪资周期，
• 一个财年边界，
• 一项证书或 DOB 验证，
• 一个发票/报表日期，
• 一条考勤或休假记录，
• 一个本应保持待审核状态的未来 BS 日期。

软件 Agent 还会带来另一种失败模式：如果工具没有暴露来源、 置信度和边界数据，模型往往会像日期已经确定一样作答。Parva 的构建目的 就是让这些边界变得可见。

该项目将公开的尼泊尔日期失败转化为夹具和检查，条件是证据足够精确。 当证据不完整时，它会保持标记为待审核，而不是变成一个虚假的断言。

免费尼泊尔日期风险审计

如果你维护面向尼泊尔的薪资、ERP、会计、考勤、学校、 合作社、公共服务、政府表单或日期选择器软件，你可以 发送一个小型工作流或示例输出。

无需集成。无需依赖。无需销售通话。不主张任何权威。

好的输入：

• 10 个 BS/AD 日期输出示例
• 一个薪资、财年、发票、考勤、报告、证书或 DOB 工作流
• 一个公开仓库、issue、尼泊尔日期选择器或库案例
• 你的团队在生产或测试中见过的一个真实边缘案例

检查：

• BS/AD 转换边界
• 无效的 BS 日期
• 月份长度
• 前端/后端日历来源漂移
• 财年和薪资月份边界
• 节假日和工作日假设
• 应标记为需要复核的未来 BS 日期

你会得到：

• 一份简短技术报告
• 通过、警告和需要复核的发现
• 建议的回归测试
• 来源和出处说明
• 权威边界说明

申请一份：

• GitHub：dantwoashim
• 邮箱：[email protected]

快速一致性路径：

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

Parva 做什么

领域	它提供什么
尼泊尔日期 API	BS 转 AD、AD 转 BS、今天、验证、月份元数据、支持范围元数据
民事证明模式	用于转换、验证、节假日、工作日、财年和 BS 月份的可重放验证膜
Panchanga 引擎	方法备案的日出、tithi、nakshatra、yoga、karana、paksha、vara、星历元数据和证明回执
薪资/日期风险审计	面向 CSV/API 的决策支持检查，用于无效日期、节假日、非工作日、财年边界和需要复核的案例
本地验证	共享证明夹具和可构建的 @project-parva/local-kernel npm 包，用于离线重放检查
SDK	带证明模式和保守验证辅助工具的 Python 和 JavaScript 客户端
Agent/MCP	只读、公开安全的 Agent 工具封装和 MCP 适配器接口，保留边界和复核关口
基准	公开的尼泊尔时间可靠性基准，用于确定性日期推理、来源意识和复核行为
治理	来源/方法备案、公开声明检查器、路由成熟度、OpenAPI 漂移检查和可复现的公开验证
研究边界	未来 BS 研究与公开权威声明保持分离，仅在较旧导入需要时提供兼容垫片

公开一致性工作

Parva 跟踪公开的尼泊尔日期问题，并在证据足够精确时将其转化为夹具或可运行 检查。该套件区分已验证的公开问题、已报告问题、部分证据、业务工作流证据和 未来日期复核案例。

Project Parva 的基准工作向 yarsa/nepal-compliance 贡献了一个独立的日历来源 一致性守护。

该检查比较了重复的前端/后端 BS 月份表。它没有添加 Parva 依赖、改变上游运行时行为或证明生产影响。

运行公开问题一致性套件：

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

一致性文档：

• 公开一致性索引
• 来自公开问题的失败类别
• 生成的产物：公开问题摘要
• 尼泊尔合规概况
• Yarsa 来源漂移案例研究
• 一致性里程碑 001

这些夹具是公开回归和复核产物。它们不是 日历发布、法律指导、税务指导、薪资批准、银行 指导或仪式权威。

适用对象

• 希望从真实公开 issue 中获取回归用例的日期库维护者。
• 需要更安全的 BS/AD 边界的 ERP、薪资、会计、学校、合作社和考勤团队。
• 审查公共服务或政府表单工作流的评审者，这些场景中无效的 BS 日期不应被放过。
• 正在构建尼泊尔历 API、Bikram Sambat API 或尼泊尔日期选择器回归测试套件的开发者。
• 需要带有证明凭据的确定性答案、而非猜测日期的软件 Agent 和 MCP 工具构建者。
• 需要来源说明而非宽泛主张的审计者和维护者。

快速开始

基础 URL：

https://api.prabinghimire1.com.np/v3/api

AD 转 BS：

curl "https://api.prabinghimire1.com.np/v3/api/calendar/convert?date=2025-04-14"

BS 转 AD：

curl -X POST "https://api.prabinghimire1.com.np/v3/api/calendar/bs-to-gregorian" \
  -H "Content-Type: application/json" \
  -d '{"year":2082,"month":1,"day":1}'

校验 BS 日期：

curl "https://api.prabinghimire1.com.np/v3/api/calendar/validate-bs-date?year=2082&month=1&day=32"

节假日判定：

curl "https://api.prabinghimire1.com.np/v3/api/compliance/holiday?bs_date=2082-01-01"

工作日决策支持：

curl -X POST "https://api.prabinghimire1.com.np/v3/api/compliance/evaluate-date" \
  -H "Content-Type: application/json" \
  -d '{"profile_id":"nepal_private_company_default","bs_date":"2082-01-01","decision_intent":"general"}'

财年：

curl "https://api.prabinghimire1.com.np/v3/api/enterprise/fiscal-year/2082"

BS 月份元数据：

curl "https://api.prabinghimire1.com.np/v3/api/enterprise/bs-months/2082?mode=compare"

Panchanga 摘要：

curl "https://api.prabinghimire1.com.np/v3/api/calendar/panchanga?date=2025-04-14"

证明模式

稳定的民用路由和 Panchanga 可以返回证明凭据：

curl "https://api.prabinghimire1.com.np/v3/api/calendar/convert?date=2025-04-14&proof=replay"

curl "https://api.prabinghimire1.com.np/v3/api/calendar/panchanga?date=2025-04-14&proof=replay&lat=27.7172&lon=85.324&tz=Asia/Kathmandu"

证明响应包含膜胶囊、身份哈希、见证哈希、字段来源、边界向量、来源或方法案卷引用、策略追踪以及重放说明。验证者必须重放操作语义或校验固定的证明内容；仅有哈希存在是不够的。

支持证明的民用操作：

• convert_bs_to_ad
• ad_to_bs
• validate_bs_date
• holiday
• working_day
• fiscal_year
• bs_months

Panchanga 证明目前覆盖方法案卷化的 panchanga_summary，带有固定测试夹具重放和显式星历元数据。

Panchanga 引擎

Parva 将 Panchanga 信号计算为有方法支撑的天文输出，而非最终历书、出版物或仪式决策来源。

携带证明的 Panchanga 层记录：

• 日期、纬度、经度、时区
• 星历提供方和提供方类型
• 适用时的测试夹具或内核哈希
• ayanamsa 和恒星模式
• 日出归因规则
• 日出、tithi、nakshatra、yoga、karana 及相关计算的方法案卷
• 字段来源和边界向量
• computed_not_official、not_panchanga_authority 和 not_ritual_final_authority

JPL 支持是显式且有边界的。仓库暴露了 JPL DE440 系列的提供方接口和内核哈希披露路径。大型 JPL 内核不随包捆绑。如果未配置内核，Parva 不得静默声称输出由 JPL 支撑。

参见 docs/PANCHANGA_ENGINE.md、docs/spec/PARVA_EPHEMERIS_PROVIDER_v1.md 和 docs/spec/PARVA_PANCHANGA_PROOF_v1.md。

薪资与日期风险审计

Parva 包含一个携带证明的薪资/日期风险工作流，用于决策支持。它会检查各行是否存在：

• 无效 BS 日期
• BS/AD 不匹配
• 节假日冲突
• 非工作日冲突
• 财年边界问题
• 不支持或需要复核的范围
• 来源或方法权威性不足

该工作流可以输出行级证明包和 Timepack 风格的聚合报告。它是预检/审计辅助工具，不是法律、税务、薪资、银行或合规权威。

本地与离线验证

生成共享证明夹具：

py -3.11 scripts/release/generate_proof_fixtures.py

运行后端夹具重放：

py -3.11 -m pytest tests/integration/test_shared_proof_fixtures.py -q

运行本地内核：

cd packages/parva-local-kernel
npm install
npm test

本地内核是一个可构建的 npm 包：@project-parva/local-kernel。它无需调用实时 API 即可验证共享民用夹具、Panchanga 夹具、证明包和 Timepack 形式的产物。

SDK

Python：

from parva import ParvaClient

client = ParvaClient()
payload = client.ad_to_bs("2025-04-14", proof="replay")
print(payload["proof"]["identity_hash"])

JavaScript：

import { ParvaClient } from "@project-parva/parva-js";

const client = new ParvaClient();
const payload = await client.getPanchanga({
  date: "2025-04-14",
  proof: "replay",
  lat: 27.7172,
  lon: 85.324,
  tz: "Asia/Kathmandu",
});
console.log(payload.proof.identity_hash);

本仓库中的包已为公开测试版试运行做好准备。本 README 不声称已发布到 PyPI、已发布到 npm、已通过注册表审核、已获得外部认证或已被客户采用。

Agent 与 MCP 用法

Parva 对软件 Agent 很有用，因为它提供确定性的时间工具，而不是让模型猜测尼泊尔日期。

Agent 安全接口必须保留：

• 来源或方法状态
• 置信度与边界向量
• review_required
• not_authority
• 字段溯源
• 可用时的证明链接或凭据

包：

• Agent 工具：packages/parva-agent-tools
• MCP 服务：packages/parva-mcp-server
• Agent 指南：docs/AGENT_TOOLING_GUIDE.md

未来 BS 研究预测

Parva 通过三个只读端点发布 2084-2200 BS 的确定性研究快照：

GET /v4/api/future-bs/capabilities
GET /v4/api/future-bs/methodology
GET /v4/api/future-bs/forecast/{bs_year}

所选流水线结合了恒星太阳入宫求解、尼泊尔民用时间分配、独立的广泛参考塔与官方权威塔、仅基于过去的民用规则学习、来源感知的月初对账、完整年份约束、预测集以及边界风险标签。预测响应包含全部十二个月的长度、归一化模型支持度、一致性、边界距离、风险标志、方法版本和验证范围。

官方 2078-2083 BS 窗口在按时间顺序滚动验证下达到 72/72 精确月份匹配，每个目标年份仅用更早年份训练。这仍然是一个小型开发窗口结果，而非广泛的独立准确性证明。广泛验证仍低于项目 528 个已验证月份的证明阈值。每个预测都带有 computed_prediction_not_official、review_required=true 以及权威发布覆盖。

v7 预测现在已由一个公开源提交、快照摘要、117 个逐年承诺以及一个 Merkle 根锁定。之后的官方日历仅根据由两人审查过的哈希源工件进行评分；历史来源恢复仍是一个独立的溯源通道。

• 公共 API 契约：docs/future_bs/API.md
• 所选方法：docs/future_bs/METHODOLOGY.md
• 冻结的 v7 预测：docs/future_bs/V7_FORECAST_FREEZE.md
• 官方来源获取：docs/future_bs/OFFICIAL_CALENDAR_ACQUISITION_PROTOCOL.md
• BS 2082 边界诊断：docs/future_bs/2082_BOUNDARY_DIAGNOSIS.md
• 研究边界：docs/future_bs/RESEARCH_BOUNDARY.md

架构概览

当前代码按职责划分：

• 公共 API/运行时代码位于 backend/app 下的各模块，如 calendar、panchanga、sources、membranes、rules、timegraph、trust 和 services
• Future-BS 研究与模型风险相关工作位于 backend/app/research/future_bs
• backend/app/future_bs 是兼容性命名空间，并非规范的实现位置
• 后端运行时测试位于 tests/backend_runtime
• 本地内核测试位于 tests/local_kernel
• 纳入版本管理的 MoHA 公共假日源 PDF 位于 data/source_archive/moha，并带有 data/source_archive/moha/manifest.json
• 生成的或对发布敏感的产物遵循 artifacts/POLICY.md

public route / SDK / MCP tool
  -> canonical query
  -> source or method coverage resolution
  -> policy decision trace
  -> field-level provenance
  -> boundary vector
  -> membrane capsule
  -> proof pack / Timepack
  -> backend replay verifier and local-kernel verifier

核心架构文件：

• 架构图：docs/architecture/ARCHITECTURE.md
• 迁移状态：docs/architecture/MIGRATION_STATUS.md
• Membranes 与重放：backend/app/membranes
• 源覆盖：backend/app/sources/coverage.py
• Panchanga 证明：backend/app/panchanga
• Future-BS 研究边界：backend/app/research/future_bs
• 本地内核：packages/parva-local-kernel
• 公共验证：scripts/release/verify_public.py
• 语义深度门禁：scripts/release/check_ceiling_depth_semantics.py

公共验证

运行：

py -3.11 scripts/release/verify_public.py

针对性检查：

py -3.11 scripts/release/check_public_claims.py
py -3.11 scripts/check_path_leaks.py
py -3.11 scripts/check_future_bs_public_leakage.py
py -3.11 scripts/release/check_public_openapi_drift.py
py -3.11 scripts/release/check_ceiling_depth_semantics.py

前端：

cd frontend
npm test -- --run
npm run build

安全声明

在相关验证命令通过的前提下，可以安全地声明：

• Parva 提供具备源感知能力的尼泊尔时间 API。
• Parva 支持针对稳定的民用时间操作提供证明回执。
• Parva 支持带有方法归档的 Panchanga 计算，并明确划定非权威边界。
• Parva 可以针对已提交的证明固定装置（fixture）运行本地/离线验证。
• Parva 可以帮助软件 Agent 避免对尼泊尔日期进行猜测。
• Parva 可以支持薪资/日期风险预检和供应商合规性审查。

禁止声明

不得声明：

• 政府批准或公共机构背书
• 法律、税务、薪资或银行决策权威
• 宗教或仪式的最终权威
• 对不受支持的未来 BS 日期的既定权威
• 最终的 Panchanga 或仪式权威
• 外部认证
• PyPI/npm 发布，除非该包确实已发布
• MCP 注册中心收录，除非已被某个注册中心收录
• 客户、采用或设计合作伙伴，除非存在真实证据
• 无保留的 Future-BS 确定性或权威性声明

项目状态

公共可复现性门禁是发布就绪状态的唯一事实来源：

py -3.11 scripts/release/verify_public.py

民用时间核心具备可重放验证的证明支持和本地固定装置。Panchanga 具备带证明的方法归档路径，支持固定装置重放，并具有有界的 JPL 提供方接口。Future-BS 发布经过整理的研究快照，而原始模型工作流仍处于受控状态。

外部上限尚未完成。本仓库中不存在真实的外部见证、机构签名、官方批准、第三方认证或客户/采用证明。

许可证与源码可用性

Project Parva 采用 AGPL-3.0-or-later 许可。网络部署必须将 PARVA_SOURCE_URL 设置为所部署版本对应的源码仓库或源码归档。应用会将 /source 暴露为指向该配置位置的跳转，并在 HTTP 响应中添加 rel="source" 链接。

针对专有产品的商业嵌入许可同样可用，价格为每供应商每年 NPR 100,000-300,000，具体取决于所指定的产品范围。参见 docs/COMMERCIAL_LICENSING.md。

部署详情记录于 docs/DEPLOYMENT.md。

路线图

近期：

• 将本地内核重放扩展到当前测试夹具之外
• 扩展 Panchanga 证明夹具和提供方覆盖范围
• 深化 proof-pack 和 Timepack CLI 工作流
• 加强薪资/日期风险审计报告，以供外部审查
• 增加更多具备证明感知能力的 UI 界面
• 扩展基准测试和一致性测试用例
• 收集有边界的外部技术审查意见，同时避免过度声称权威性

贡献

贡献应遵循 Parva 的核心规则：

• 任何低权威数据都不得成为高权威输出
• 任何证明验证器都不得仅检查对象结构或哈希是否存在
• 有证明支持的操作需要重放测试和篡改测试
• 公开文档不得过度声称权威性
• 面向未来的输出必须保持可审查性

在提交 pull request 之前，请运行：

py -3.11 -m pytest -q -m "not private_source and not wide_corpus and not research_artifact" --maxfail=20
py -3.11 scripts/release/check_public_claims.py
py -3.11 scripts/release/check_ceiling_depth_semantics.py

使用 Python 3.11 和 Node 20 进行可复现验证。