I Built a Verified Temporal API for AI Agents - Swiss Ephemeris, FastAPI, and a Calendar That Changes Every Year

Prabin Ghimire — Fri, 15 May 2026 18:00:46 +0000

AI Agents Should Call Tools for Time: Building Nepali Temporal Infrastructure with FastAPI and Swiss Ephemeris

dantwoashim / Project_Parva

Open-source Nepali temporal infrastructure for BS/AD conversion, fiscal-year logic, panchanga computation, festivals, and source-aware calendar validation.

Project Parva

Project Parva is open-source Nepali temporal infrastructure for Bikram Sambat conversion, fiscal-year logic, panchanga computation, festivals, and source-aware calendar validation.

It also includes a controlled future-BS risk research layer for evaluating month-length assumptions before they affect financial, contractual, reporting, or operational systems.

Why This Exists

Nepali calendar logic is infrastructure, not decoration.

BS dates affect fiscal reports, payroll, contracts, transaction records, holidays, reporting periods, renewals, interest periods, compliance exports, and audit trails. Fragile calendar tables can quietly become operational risk when they are copied, extended, or updated without source policy.

Parva treats calendar behavior as something that should be explainable, source-aware, reproducible, and honest about confidence.

What Parva Provides

Area	Purpose
Calendar conversion	BS to AD, AD to BS, today endpoints, and month metadata
Fiscal-year logic	Nepali fiscal boundaries, fiscal labels, periods, and date-range helpers
Date validation	BS date validation and published-range checks
Panchanga and lunar computation	Tithi,

…

View on GitHub

A Claude, GPT, Gemini, or Cursor agent receives a simple task.

Check whether a date falls inside a valid reporting period.

The date uses Bikram Sambat, the official calendar used across Nepal.

The agent answers confidently. The output passes the application schema. The log shows a successful run. The downstream system accepts the result.

The date is wrong.

That is the failure mode that pushed me deeper into Project Parva.

Date bugs already create enough damage in normal software. Date bugs inside agentic systems feel worse because the model can wrap a wrong answer in fluent reasoning, structured JSON, and an explanation that sounds operationally correct.

Project Parva is my attempt to build the grounding layer that Nepali time deserves.

It started as an open-source Nepali calendar API. It has grown into source-aware temporal infrastructure for software systems, AI agents, and backend workflows that need reliable Bikram Sambat conversion, panchanga computation, holidays, fiscal logic, festivals, working days, and review-aware temporal decisions.

Repository:

https://github.com/dantwoashim/Project_Parva
`

......

The real problem is temporal grounding

Most systems treat calendars as formatting utilities.

That works until the calendar carries legal, fiscal, religious, cultural, or institutional meaning.

Bikram Sambat is an excellent stress test for modern software. A basic integration often starts with a simple need:

Convert this BS date to AD.

Then the real requirements appear.

Validate this BS date.
Find the fiscal year.
Check whether this is a working day.
Resolve a festival date.
Compute tithi at sunrise.
Handle location-aware panchanga.
Explain the source of the result.
Flag future-sensitive results for review.
Give an AI agent a safe tool response.

At that point, a calendar library becomes infrastructure.

A bare response like this gives the caller a value:

json
{
"bs_date": "2082-01-01",
"ad_date": "2025-04-14"
}

A serious system needs the value plus its trust con:

json
{
"bs_date": "2082-01-01",
"ad_date": "2025-04-14",
"source_tier": "source_backed",
"confidence": "high",
"supported_range": {
"start": "2000-01-01",
"end": "2099-12-30"
},
"claim_boundary": "technical_reference",
"review_required": false
}

That second response is the heart of Project Parva.

The API gives software a date and tells the software what kind of date it received.

......

Bikram Sambat is a backend systems problem

The civil Bikram Sambat calendar, the panchanga layer, and Nepal’s institutional date workflows create a combined systems problem.

The civil calendar needs verified month-length behavior. Panchanga needs solar and lunar computation. Festivals often depend on tithi, sunrise, and published convention. Working-day behavior depends on institution profiles. Fiscal logic depends on Nepali accounting conventions. Future-sensitive dates need clear review boundaries.

A single “convert date” function covers only a small part of this surface.

Project Parva separates the layers:

civil date conversion
astronomical panchanga computation
festival and observance logic
holiday and working-day profiles
fiscal-year logic
source metadata
confidence metadata
public verification gates
research boundaries
AI tool boundaries
MCP adapter boundaries

This separation makes the project larger than a date converter, and it makes the architecture much more interesting.

......

The astronomical layer

Panchanga computation involves astronomy.

Tithi comes from the angular separation between the Moon and the Sun.

Nakshatra comes from sidereal lunar longitude.

Yoga comes from combined solar and lunar longitude.

Karana comes from half-tithi boundaries.

Sunrise matters for udaya-tithi style decisions.

Muhurta windows depend on date, location, timezone, and astronomical intervals.

Project Parva uses Swiss Ephemeris through Python for this layer. The project also contains JPL and DE440-oriented policy work for higher-precision ephemeris research and differential verification.

The important engineering decision is the separation between astronomical evidence and civil authority.

Astronomy can tell the system where the Sun and Moon were.

A source authority decides what a government, institution, calendar publication, or panchanga tradition actually recognizes.

That distinction appears directly in the project’s data model.

json
{
"astronomy_status": "fallback_computed",
"civil_authority_status": "computed_not_official",
"boundary_risk": "medium",
"claim_boundary": "astronomy_evidence_not_civil_authority",
"review_required": true
}

This keeps the computation powerful while keeping the output honest enough for real software.

......

FastAPI as a temporal infrastructure surface

The backend is Python 3.11 and FastAPI.

FastAPI works well here because the API surface is part of the trust model.

Typed request models, response models, OpenAPI generation, structured validation, and route-level boundaries matter when downstream systems use the output for automation.

A route that returns a date carries more than data. It carries a contract.

Project Parva uses a stable v3 API surface for public integrations. The broader repository also tracks route maturity, public/private/research boundaries, OpenAPI drift, source metadata, verification scripts, and SDK behavior.

The route family includes stable public operations around:

today
BS to AD conversion
AD to BS conversion
date validation
fiscal year
working day logic
festivals
panchanga
muhurta
source metadata
trust metadata
policy metadata

For example, a location-sensitive panchanga request needs date, latitude, longitude, and timezone.

bash
curl -X POST "https://api.prabinghimire1.com.np/v3/api/personal/panchanga" \
-H "Content-Type: application/json" \
-d '{
"date": "2026-10-21",
"lat": 27.7172,
"lon": 85.3240,
"tz": "Asia/Kathmandu"
}'

The important part is the response shape. The caller should receive the computed result and the metadata needed to handle that result safely.

......

Why AI agents need this kind of API

LLMs are impressive at language and weak at grounded temporal authority.

A model can produce a Nepali date, a festival date, a fiscal-year answer, or a panchanga explanation with perfect confidence. The confidence comes from language fluency, not source verification.

Agent systems built around Claude, GPT, Gemini, LangChain, LlamaIndex, Cursor, and MCP need tools for this category of problem.

They need tools that return:

answer
source tier
confidence
supported range
claim boundary
review requirement
machine-readable metadata

This turns a date answer from model memory into a tool-grounded system output.

A safe tool response looks like this:

json
{
"answer": {
"bs_date": "2082-01-01",
"ad_date": "2025-04-14"
},
"source_tier": "source_backed",
"confidence": "high",
"supported_range": "public_supported_range",
"claim_boundary": "decision_support_not_authority",
"review_required": false
}

That structure matters because agents pass outputs into other tools.

A scheduling agent may call a calendar API.

A payroll agent may compute a cutoff.

A finance agent may label a reporting period.

A government-service agent may answer a citizen.

A school ERP assistant may generate a schedule.

An AI system that guesses time creates quiet failure. An AI system that calls a deterministic temporal tool creates auditable behavior.

That is the role Parva is designed to play.

......

MCP as a thin adapter

MCP is useful because it gives AI clients a common way to discover and call external tools.

It also creates a new safety surface.

A tool descriptor can make a system safer or more dangerous. A vague tool description can teach an agent to overuse a route. An overpowered tool can expose admin or research behavior. A missing boundary can make a computed value look authoritative.

Project Parva treats MCP as a thin adapter over the verified public surface.

The MCP resources are shaped around things an agent can safely inspect:

parva://capabilities
parva://route-maturity
parva://source-policy
parva://supported-ranges
parva://known-limitations
parva://benchmark-summary

The public-safe tools are intentionally small:

convert_bs_to_ad
convert_ad_to_bs
get_nepali_today
check_holiday
check_working_day
get_fiscal_year
get_festival_date
get_panchanga_summary
check_temporal_claim

The server is read-only by design. The manifest tests check route safety, descriptor safety, digest stability, resource exposure, and tool boundaries.

MCP is useful here because time is a perfect tool-use domain. The model should delegate the temporal fact to a system built for temporal facts.

......

Source metadata is a first-class feature

Most calendar systems store dates.

Project Parva stores dates with con.

For source-backed results, the response can include provenance information, source tiers, release metadata, confidence labels, and calculation method details.

A festival result can carry data like:

json
{
"data": {
"festival": "Dashain",
"bs_date": "2082-06-29",
"ad_date": "2025-10-15",
"quality_band": "source_backed",
"provenance": {
"source_tier": "published",
"method": "festival_rule_with_source_metadata",
"review_required": false
}
},
"meta": {
"calculation_trace_id": "trace_...",
"method_profile": "public_reference",
"claim_boundary": "technical_reference"
}
}

This feels closer to supply-chain thinking than ordinary calendar programming.

The system should know where the value came from, how it was produced, what confidence it carries, and how far the caller can safely use it.

That design becomes especially valuable when the caller is another machine.

......

Public verification is part of the product

The project now treats verification as a product surface.

A temporal infrastructure project needs more than unit tests. It needs checks that enforce trust boundaries across generated artifacts, docs, OpenAPI, routes, SDKs, AI tools, and reports.

The repository includes public verification around:

bash
python scripts/parva_trust_verify.py
python scripts/check_future_bs_public_leakage.py
python scripts/release/check_public_openapi_drift.py
python scripts/check_docs_links.py
python scripts/check_path_leaks.py
python -m pytest -q -m "not private_source and not wide_corpus and not research_artifact"
python scripts/release/verify_public.py

These checks answer questions that normal test suites miss:

Did a private path leak into public files?
Did a public OpenAPI artifact expose a research route?
Did Future-BS exact output cross into the public surface?
Did docs link to local generated files?
Did public tests start depending on private data?
Did trust manifests drift?

That is infrastructure work.

The output of the project should be correct. The boundary around the output should be correct too.

......

Nepali Time Reliability Benchmark

Project Parva also includes an initial Nepali Time Reliability Benchmark.

The benchmark tests the kind of behavior that real systems need:

BS/AD conversion
invalid BS dates
holidays
working days
fiscal-year boundaries
festival dates
panchanga and tithi-at-sunrise behavior
payroll and repayment review gates
Future-BS review behavior
source and confidence metadata
machine-readable structure

The scoring model includes:

Correctness
Source awareness
Uncertainty handling
Review gate behavior
Machine-readable structure

This is important because date infrastructure deserves benchmark pressure.

A system can return the correct date and still fail the reliability test if it loses source metadata, hides uncertainty, or makes a future-sensitive output look final.

For AI systems, that benchmark matters even more.

An agent needs a tool that gets the answer and keeps the boundary.

......

Future-BS as a boundary problem

Future Bikram Sambat work is one of the most sensitive areas in the project.

The tempting version is simple:

Compute future dates and return them.

The serious version is better:

Compute candidates, preserve source status, expose risk, require review, and keep official-source claims separate.

Project Parva uses language like:

computed_prediction_not_official
review_required
unsupported
source_unavailable
human_review_required

This makes the system useful for research, planning, and risk analysis while keeping public integration behavior safe.

A future-sensitive response should look more like:

json
{
"publication_status": "computed_prediction_not_official",
"review_required": true,
"claim_boundary": "future_calendar_decision_support",
"confidence": "research"
}

That design is less flashy than pretending to own the future.

It is also the version that belongs inside serious software.

......

External rules are separate from astronomy

Another lesson from the project is that time infrastructure needs institutional rule modeling.

Astronomy gives the system one class of evidence.

Institutions give the system another.

Project Parva tracks external temporal rules for things like:

holiday releases
panchanga festival decisions
fiscal-year assumptions
working-day profiles
bank holiday profiles
payroll cutoff rules
school calendar profiles
municipality holiday notices
regional observance variants
Nepal Sambat observances
udaya-tithi festival conventions

Each rule can carry fields like:

rule_id
authority_type
source_tier
jurisdiction
evidence_required
public_safe
review_required_when
conflict_resolution
examples

That registry lets a system distinguish:

The astronomy says X.
A published source says Y.
An institution policy says Z.
This case needs review.

This separation makes the architecture far cleaner.

It also makes the project more useful to payroll systems, cooperatives, ERP tools, school systems, government portals, and AI agents.

......

Non-Gregorian calendars are frontier infrastructure

Nepal is one example of a broader problem.

Many jurisdictions operate with calendar systems that differ from the Gregorian assumptions built into most global software stacks.

Examples include:

Bikram Sambat
Nepal Sambat
Ethiopian calendar
Hebrew calendar
Islamic Hijri calendars
Solar Hijri calendar
traditional lunisolar calendars
regional festival calendars

The infrastructure pattern repeats:

local calendar rules
source authority
astronomical computation
institution-specific policy
software integration
AI tool grounding

This is why Project Parva feels bigger than a Nepali date converter.

The domain is Nepal.

The pattern is global.

As AI agents become normal parts of workflows, every non-Gregorian time system needs a grounded tool layer.

Project Parva is one implementation of that idea.

......

API, SDKs, and integration surface

The project includes:

FastAPI backend
OpenAPI docs
Python SDK work
JavaScript SDK work
LangChain and LlamaIndex tool wrappers
MCP manifest and server work
public benchmark runners
trust verification scripts
route maturity profiles
digital Panchanga sample release
vendor conformance packet
government proposal packet

This gives the project several integration paths:

Direct REST API
OpenAPI clients
Python SDK
JavaScript SDK
AI tool wrappers
MCP-compatible clients
benchmark runners
self-hosted deployments

The goal is practical.

A developer should be able to call stable public routes.

An AI engineer should be able to wrap those routes safely.

A vendor should be able to test date behavior.

A reviewer should be able to inspect verification gates.

A future government or institutional workflow should be able to see how machine-readable temporal releases could work.

......

Getting started

Repository:

https://github.com/dantwoashim/Project_Parva

Typical API use looks like:

bash
curl "https://api.prabinghimire1.com.np/v3/api/calendar/today"

BS to AD conversion:

bash
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}'

Upcoming festivals:

bash
curl "https://api.prabinghimire1.com.np/v3/api/festivals/upcoming?days=30"

Panchanga:

bash
curl -X POST "https://api.prabinghimire1.com.np/v3/api/personal/panchanga" \
-H "Content-Type: application/json" \
-d '{
"date":"2026-10-21",
"lat":27.7172,
"lon":85.3240,
"tz":"Asia/Kathmandu"
}'

Public verification from the repository:

bash
python scripts/release/verify_public.py

Benchmark runners:

bash
python public-benchmark/runners/run_against_static_baseline.py
python public-benchmark/runners/run_against_parva.py

......

The core idea

Project Parva exists because Nepali time deserves better infrastructure.

A calendar API should return dates.

A temporal infrastructure layer should return dates, sources, confidence, review boundaries, supported ranges, and machine-readable safety metadata.

That distinction matters for backend systems.

It matters for government digitization.

It matters for fintech and payroll.

It matters for panchanga and festival software.

It matters for AI agents.

The sentence that captures the project is simple:

AI agents should call tools for time.

For Nepal, Project Parva is building that tool layer.

DEV Community: Prabin Ghimire

I Built a Verified Temporal API for AI Agents - Swiss Ephemeris, FastAPI, and a Calendar That Changes Every Year

dantwoashim / Project_Parva

Open-source Nepali temporal infrastructure for BS/AD conversion, fiscal-year logic, panchanga computation, festivals, and source-aware calendar validation.

Project Parva

Why This Exists

What Parva Provides