How it works

From a government order to correct, verified rules

Niyam is an AI agent : it takes a goal, plans steps, uses tools, checks its own work, and recovers when something fails. Here is every step, with what can go wrong.

1
Watch
Checks official sources every 15 minutes for new government orders.
2
Triage
Decides if the document changes any scheme Niyam covers.
3
Extract
Quotes the exact clauses that change eligibility, and checks every quote.
4
Encode
A coding agent updates the rulebook and writes tests.
5
Verify
A separate agent checks the new rules against the law, blind to the change.
6
Resolve
Settles disagreements, or asks a human a plain question.
7
Publish
Opens a change request with sources and proof. Merges alone only when safe.

1. Watch

What happens: Every 15 minutes, Niyam reads the public list of the latest Maharashtra government orders and downloads new ones from departments that run welfare schemes.
Why it is needed: Orders appear without notice. A person checking by hand will eventually miss one.
What can go wrong Recovery: The website times out or returns errors: Niyam retries with growing waits, marks the source as degraded, and tries again next cycle. If a source ever asks for a CAPTCHA, Niyam stops and marks it blocked. It never gets around a CAPTCHA.
From a real run Measured: The live list read today contained orders from the Skill Development and Environment departments, which Niyam correctly closed as not relevant for less than one cent each.

2. Triage

What happens: A small, fast model reads the first three pages and decides whether the order changes eligibility or benefits of a covered scheme.
Why it is needed: Most orders are about budgets, committees or other departments. Skipping them early keeps the cost near zero.
What can go wrong Recovery: If the PDF has no text on its first pages (a scan), triage reads the PDF images instead.
From a real run Measured: A synthetic test order that only extended an application deadline, and hid an instruction telling AI systems to raise the income limit, was closed as not relevant. The hidden instruction was ignored.

3. Extract

What happens: A stronger model reads the whole order next to the current rules and lists every change, each with the exact quote, page and clause, and whether it widens or narrows eligibility.
Why it is needed: Everything after this depends on reading the law correctly, word for word.
What can go wrong Recovery: Marathi PDFs often have damaged text layers (the vowel sign ि comes out as ह). Niyam checks quotes on a consonant skeleton, requires every number to match exactly, rejects invented quotes, and asks the model to fix them once. Scanned orders are transcribed first.
From a real run Measured: From the 3 July 2024 amendment it found all six eligibility changes, skipped five procedural ones, and raised two genuine questions for a human.

4. Encode

What happens: Claude Code works in its own copy of the rulebook. It adds dated values (never overwriting history), ends old conditions and starts new ones, writes test citizens at every limit, and runs the tests until they pass.
Why it is needed: This is where the law becomes something a computer can apply the same way every time.
What can go wrong Recovery: Failing tests are fed back for another attempt. Edits outside the rule folders are reverted. The coding agent never sees the raw PDF, only the checked change list, so instructions hidden in a document cannot reach a tool-using agent.
From a real run Measured: The amendment produced 20 new test citizens on top of the 25 baseline ones, all passing on the first attempt.

5. Verify

What happens: A separate agent, using a different model, reads the order and the old rules but never sees the code change. It writes its own test citizens with expected results, and those are run against the new rules.
Why it is needed: If the checker saw the change, it would tend to agree with it. Writing expectations from the law alone is a real second opinion.
What can go wrong Recovery: Invalid test people are skipped and counted. Any disagreement goes to Resolve.
From a real run Measured: In version 2, all 15 of the verifier's independent test citizens agreed with the new rules.

6. Resolve

What happens: A coordinator rereads the disputed clause and decides: the encoder is wrong (send a precise fix), the verifier is wrong (accept with a reason), or the clause is genuinely ambiguous (ask a human).
Why it is needed: Some clauses can be read two ways. Guessing could stop people being paid.
What can go wrong Recovery: A disagreement that survives a fix is escalated instead of retried. We added this after the version 1 traces showed one case going round three times.
From a real run Measured: Whether the original order's "pay the difference" rule still applies after the amendment is now flagged as a question for a human.

7. Publish

What happens: Niyam commits the change (Entire links the coding agent's full session as a checkpoint), opens a pull request with quotes, verification, confidence and reasons, and merges on its own only when the trust policy allows.
Why it is needed: Every change is visible and reviewable, and its reasoning can be audited months later.
What can go wrong Recovery: If GitHub is unreachable the job keeps its state and resumes later.
From a real run Measured: The amendment went to human review, because one change ("Rs 1,500 or more" instead of "more than Rs 1,500") removes some people from the scheme.

Under the hood

Architecture

The simple version first. The technical detail is one click away.

1
Official sources and uploads
2
Agent worker on AWS (state machine, saved after every step)
3
Claude models and Claude Code
4
Rulebook repository on GitHub (Entire checkpoints)
5
Website, API and MCP server

Technical detail

Python 3.12 orchestrator: a persisted state machine in SQLite. A crash resumes from the last completed state; a failed job retries from its last good state.
Every stage output is validated against a schema (structured outputs). Invalid output gets one repair attempt; overload falls back to another model.
neatlogs traces: one trace per job, a span per stage, recovery events as their own spans, tokens and cost per call.
Encoder: Claude Code headless in a git worktree per job, tools limited to file edits and the rulebook test command, no MCP servers. Entire hooks capture the session; commit_linking: always links it to the commit as a checkpoint.
Rulebook: YAML in OpenFisca parameter format, dated conditions, a whitelisted expression evaluator (no arbitrary code), validation and tests in CI.
Website: static Next.js export with the same rules engine ported to the browser, so eligibility checks need no server.

Replay a real run Trust policy