Parva Python SDK Alpha

Public-safe Python SDK for Project Parva calendar APIs.

This alpha package uses the stable public calendar surface plus curated Future-BS capability, methodology, and single-year forecast routes. It does not call bulk export, model-run, backtest, comparison, corrected-value, or schedule-impact endpoints.

Install

From PyPI:

python -m pip install parva-python

From this repository for local development:

python -m pip install -e packages/parva-python

Quick Start

from parva import ParvaClient

client = ParvaClient()

today = client.get_today()
ad_to_bs = client.ad_to_bs("2026-04-14")
bs_to_ad = client.bs_to_ad(2083, 1, 1)
validation = client.validate_bs_date(2083, 1, 32)
month = client.get_month_calendar(2026, 4)
fiscal_year = client.get_fiscal_year(2082)
bs_months = client.get_bs_months(2082)
business_days = client.get_business_days("2082-01-01", "2082-01-07")
enterprise = client.get_enterprise_capabilities()
compliance = client.evaluate_date(
    profile_id="nepal_private_company_default",
    bs_date="2082-04-02",
)
trust = client.get_trust_capabilities()
evidence = client.create_date_conversion_evidence(ad_date="2026-04-14")
timegraph = client.get_timegraph_capabilities()
facts = client.get_facts_for_date("BS", "2083-01-01")
trace = client.trace_fact("fact_bs_ad_2083_01_01")
rule = client.evaluate_rule(
    "last_working_day_of_nepali_month",
    input_payload={
        "bs_month": "2082-04",
        "profile_id": "nepal_private_company_default",
    },
)
policy = client.get_policy()
capabilities = client.get_future_bs_capabilities()
methodology = client.get_future_bs_methodology()
forecast = client.get_future_bs_forecast(2084)

Covered Public Surfaces

• current calendar context
• AD to BS conversion
• BS to AD conversion
• BS date validation through conversion
• month calendar
• fiscal-year boundaries
• BS month metadata
• weekend-rule business-day helper
• enterprise capability metadata
• compliance profile listing and decision support helpers
• trust source, release, diff, log, and evidence packet helpers
• TimeGraph fact, relationship, trace, and conflict helpers
• RuleLang registry, validation, execution, test, and explanation helpers
• public policy metadata
• Future-BS capabilities, selected methodology, and single-year forecast

Maturity Policy

TimeGraph

TimeGraph helpers expose public-safe temporal facts and traces. They preserve fact ids, relationships, source ids, release ids, confidence, warnings, trace ids, and conflict metadata.

date_facts = client.get_facts_for_date("BS", "2083-01-01", limit=10)
fact = client.get_fact("fact_bs_ad_2083_01_01")
trace = client.trace_fact("fact_bs_ad_2083_01_01", depth=2)
conflicts = client.list_conflicts()

TimeGraph responses are audit support and not legal, tax, payroll, banking-contract, or government authority.

RuleLang

RuleLang helpers evaluate structured temporal rules with bounded execution, reason codes, traces, metadata, and fact ids.

rules = client.list_rules()
result = client.evaluate_rule(
    "last_working_day_of_nepali_month",
    input_payload={
        "bs_month": "2082-04",
        "profile_id": "nepal_private_company_default",
    },
)
explanation = client.explain_rule(
    rule_id="last_working_day_of_nepali_month",
    input_payload={
        "bs_month": "2082-04",
        "profile_id": "nepal_private_company_default",
    },
)

RuleLang is decision support and not legal, tax, payroll, banking-contract, or government authority.

API Base

Default public API base:

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

Future-BS public endpoint root:

https://api.prabinghimire1.com.np/v4/api/future-bs/capabilities

Private deployments can override both values:

client = ParvaClient(
    base_url="https://calendar.example.com/v3/api",
    future_bs_capabilities_url="https://calendar.example.com/v4/api/future-bs/capabilities",
)

The default base is the public demo service, not a required production host. Private deployments should pass their own base_url.

Command Line

The installed SDK provides the public API commands today, convert, validate-bs, and capabilities.

A full repository checkout also enables verify-proofpack, verify-timepack, and audit payroll. Those offline commands use the repository backend and committed evidence data, so they stay hidden in a standalone PyPI installation.

Retry Behavior

The SDK retries 429, 500, 502, 503, and 504 responses with conservative backoff. Retry-After is honored for 429 responses.

client = ParvaClient(max_retries=2, retry_base_delay=0.25)

Set max_retries=0 to disable retries.

Review-Required Behavior

Do not discard review_required, claim_boundary, confidence, source_tier, warnings, or publication_status fields from SDK responses. Invalid dates, unsupported ranges, private route denials, and computed_prediction_not_official labels are decision boundaries, not transient transport failures.

The SDK has named helpers for conversion, validation, fiscal-year, business-day, compliance, trust, TimeGraph, RuleLang, protocol, and capability metadata. Holiday, festival-detail, and panchanga examples can use the REST routes directly until those helpers are promoted into the canonical alpha surface.

Claim Boundary

Future-BS responses are computed research and must preserve:

computed_prediction_not_official