प्रमाण · Pramaan

Plan PR — every client plan is a pull request.

Facts in → deterministic gates run → adviser reviews → approval = merge. Any fact change = new commit → gates re-run → approval auto-revoked. Every number has blame.

Built for the Zeckathon (Zetheta) 24h hackathon — solo.

---

What is this?

An AI co-pilot for a SEBI-registered Investment Adviser (RIA) in India. Not a chatbot — a research assistant + adviser console where:

• the LLM never emits a material number (NAV, SIP, corpus, returns — all from a verified vault or deterministic calculators),
• every factual claim carries blame (source doc, page, quote, date) or says "unavailable",
• nothing reaches a client without adviser approval bound to a content hash,
• and any fact change dominoes: new commit → gates re-run → approval revoked.

Layer	What it is
A — Research chat	Perplexity-style cited answers with live steps, a Devin-style workbench (files change in front of you), multi-provider model picker with TTFT-based routing + hedging + failover
B — Plan PR	The console becomes an adviser workflow: case repo (hash-chained commits), deterministic planner, 9+ gates, slot-filled drafts, approval fingerprints, client view, receipts, policy packs, red-team arcade

Screenshots

Research chat (cited, live steps, workbench)	Plan PR console (facts, gates, draft)

Client view (approved, fingerprint, teach-back)	Red-team arcade (10 attacks)	Policy pack (gates, quarantine, rule compiler)

Architecture

flowchart LR
    subgraph Client["Browser"]
        UI["Chat console<br/>(SSE stream)"]
        CASEUI["Case / PR page"]
        CLIENTVIEW["Client view"]
    end

    subgraph Next["Next.js (Node runtime)"]
        API["/api/chat (SSE)"]
        LOOP["Agent loop<br/>intent → tools → scrub → done"]
        ROUTER["Model router<br/>TTFT EWMA · hedge · failover"]
        GATES["Planner + Gates<br/>(deterministic, no LLM)"]
        APPROVE["Approval fingerprint<br/>sha256(facts+plan+gates+draft)"]
    end

    subgraph Providers["Model providers"]
        OR["OpenRouter"]
        GQ["Groq"]
        NV["NVIDIA NIM"]
    end

    subgraph Tools["Tool layer"]
        WS["web_search<br/>Tavily → Exa fallback"]
        FU["fetch_url<br/>SSRF guard + injection screen"]
        CALC["calc (mathjs)"]
        VL["vault_lookup / vault_universe"]
        FT["write/append/export_csv<br/>sandboxed workspace"]
    end

    subgraph Data["Data (seed = committed, runtime = writable root)"]
        VAULT[("Fund vault<br/>12 funds · AMFI blame")]
        CASES[("Case repo<br/>hash-chained commits")]
        POLICY[("Policy packs<br/>assumptions + rules")]
        WSDB[("SQLite<br/>threads + kv")]
    end

    UI --> API --> LOOP
    LOOP --> ROUTER --> OR & GQ & NV
    LOOP --> WS & FU & CALC & VL & FT
    LOOP --> WSDB
    CASEUI --> GATES --> VAULT & POLICY
    CASEUI --> APPROVE --> CASES
    CLIENTVIEW --> APPROVE

The Plan-PR lifecycle

sequenceDiagram
    participant A as Adviser
    participant C as Case repo
    participant P as Planner+Gates
    participant V as Client view

    A->>C: create case from persona (facts = commit #1)
    C->>P: domino: facts → plan → 9 gates → slot draft → numeric lint
    A->>C: edit any fact
    C->>C: new commit (hash-chained)
    C->>P: gates re-run (only affected checks change colour)
    C-->>A: ⚠ approval revoked (fingerprint mismatch)
    A->>C: review diffs + blame popovers → approve
    C->>C: approval commit + receipt.json/md + evidence.csv
    V->>C: renders ONLY if fingerprint still matches
    Note over V: fact change ⇒ client view flips to "being updated"

Core functionality

Layer A — research chat

Feature	Detail
Cited answers	Every claim carries [n] → source chips (title, domain, snippet, URL, retrieval time). Invented citations are stripped server-side (I2)
Live web research	web_search = Tavily first, Exa fallback; fetch_url = Tavily extract or SSRF-guarded direct fetch; HTML stripped; prompt-injection screened + flagged
Visible steps	Perplexity-style thinking (real streamed reasoning text), Devin-style tool cards with real diffs (+6 −0 183b), line counts, result values, per-call source chips
Model gateway	13 live-probed models across OpenRouter/Groq/NVIDIA; TTFT EWMA routing, cross-provider hedging (900ms), failover on any pre-content error, per-model cooldowns, transient-retry
Workbench	Sandboxed per-session FS: create/modify/delete with snapshots + undo, auto-saved audit trail (trace.txt, sources.csv, telemetry.jsonl)
Intent routing	Code-first heuristics (typos, Hinglish) → LLM classifier fallback; chat vs research routes

This is the beginning of the README. Read the rest at the original. Read the full README ↗