# adityasingh0912/grabon-agentic-challenge architecture

> Architecture diagram of the GitHub repository adityasingh0912/grabon-agentic-challenge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adityasingh0912/grabon-agentic-challenge
- Repository: https://github.com/adityasingh0912/grabon-agentic-challenge

## Overview

1. **What this repo is**
   - This is an autonomous merchant-onboarding document agent.
   - Its job is to take in KYC-like document text, extract structured fields, verify them against tools/mock APIs, cross-check consistency, and output an onboarding decision with confidence.

2. **Top-level orchestration**
   - `main.py` is the primary entry point for running the agent on a single document, a demo set, or a batch file.
   - `run_eval.py` and `eval/eval.py` provide a separate evaluation path that runs the same agent logic against a fixed fixture set and scores the outputs.
   - The orchestration layer is responsible for loading inputs, invoking the agent loop, and collecting final decisions/reports.

3. **Core state model**
   - `agent/state.py` holds the central document state object, described in the README as a Pydantic model.
   - This state is the shared contract between preprocessing, planning, tool execution, observation, and final decision-making.
   - It likely carries extracted fields, verification results, reasoning history, budget counters, confidence, and final status.

4. **Agent loop as the main control boundary**
   - `agent/loop.py` is the heart of the system.
   - It implements the PAOD-style cycle: pre-process, plan, act, observe, decide.
   - This is where budget enforcement, retry handling, and phase transitions happen; it is the main architectural boundary between orchestration and actual document-processing logic.

5. **Deterministic vs LLM-driven work**
   - The repo intentionally separates cheap deterministic work from LLM work.
   - Deterministic stages handle OCR cleanup, regex extraction, field merging, expiry checks, and cross-reference validation.
   - LLMs are reserved for planning which tools to call next and for the final onboarding decision, which matches the README’s cost/control philosophy.

6. **Tool subsystem**
   - `tools/registry.py` is the abstraction layer for all executable capabilities.
   - Tools are registered dynamically and discovered at runtime rather than hardcoded into the loop.
   - The tool set includes extraction, verification, cross-checking, and expiry logic; some tools are deterministic while others simulate unstable external services such as GST/PAN/bank verification.

7. **External verification and failure handling**
   - The tool layer acts as the boundary to mock external dependencies.
   - The architecture explicitly expects failures such as timeouts, rate limits, server errors, invalid input, and missing tools.
   - Retry/backoff behavior is part of the control plane, not the tools themselves, which keeps the tool interface simple and the recovery policy centralized in the agent loop.

8. **LLM routing layer**
   - `agent/router.py` selects which model/provider to use for each LLM-backed phase.
   - The README indicates cost-aware routing across multiple providers, with cheaper models for planning and stronger models for final decisions.
   - Architecturally, this is a policy layer that sits between the loop and the model APIs, allowing provider fallback without changing the agent logic.

9. **Observability and operator feedback**
   - `observability/terminal_ui.py` provides a rich terminal dashboard for live runs.
   - It surfaces current phase, budget progress, extracted fields, tool call history, retries, and the final decision.
   - This is an operator-facing view rather than part of the decision pipeline, but it is important for understanding runtime behavior and diagnosing failures.

10. **Evaluation pipeline**
    - The `eval/` directory contains the offline/online scoring harness and fixtures.
    - `eval/fixtures/documents.json` defines representative documents and expected outcomes.
    - `eval/eval.py` runs the agent against the fixtures and computes correctness and safety metrics, making evaluation a first-class subsystem rather than an afterthought.

11. **UI and server surfaces**
    - `ui/index.html` suggests a minimal browser-facing UI, likely for presenting or embedding run results.
    - `server.py` likely exposes a local service boundary for the UI or for triggering runs over HTTP.
    - These are peripheral interfaces; the core architecture remains the agent loop plus tool registry.

12. **Operational constraints**
    - Budget enforcement is a key architectural control: step count, tool calls, tokens, wall-clock time, and cost all cap execution.
    - This means the system is designed for bounded autonomy, not open-ended reasoning.
    - In diagram terms, the budget checker is a guardrail around every loop iteration and every retry path.

13. **End-to-end data flow**
    - Input document text enters through `main.py` or the eval harness.
    - The document is normalized and stored in the shared state.
    - The loop plans tool usage, executes tools, folds observations back into state, and repeats until budget exhaustion or completion.
    - The final decision and confidence are emitted to the caller, with observability and eval consumers reading the same underlying run state.

14. **How to draw the architecture**
    - Model this repo as three layers: orchestration/eval at the top, the agent loop in the middle, and tools/LLM providers at the bottom.
    - Put `agent/state.py` as the shared data backbone spanning the middle layer.
    - Show observability and eval as sidecars that read the same state and outputs, not as part of the core decision path.

Main entry points: [`agent/loop.py`](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/agent/loop.py) (Agent Loop), [`agent/state.py`](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/agent/state.py) (State Model), [`tools/registry.py`](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/tools/registry.py) (Tool Registry), [`observability/terminal_ui.py`](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/observability/terminal_ui.py) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Orchestration"]
  node_n1["Main<br/>entrypoint<br/>[main.py]"]
  node_n2["Eval CLI<br/>entrypoint<br/>[run_eval.py]"]
end

subgraph group_g2["Agent Core"]
  node_n3(("Agent Loop<br/>control loop<br/>[loop.py]"))
  node_n4[("State Model<br/>shared state<br/>[state.py]")]
  node_n5{{"Budget Guard<br/>policy"}}
  node_n6["Preprocess<br/>deterministic"]
  node_n7(("Planner<br/>llm phase"))
  node_n8["Observe<br/>merge phase"]
  node_n9(("Decision<br/>llm phase"))
end

subgraph group_g3["Execution Layer"]
  node_n10["Tool Registry<br/>tool host<br/>[registry.py]"]
  node_n11["Deterministic Tools<br/>extract/validate"]
  node_n12[("Mock Verifiers<br/>external checks")]
  node_n13{{"LLM Router<br/>provider policy<br/>[router.py]"}}
end

subgraph group_g4["Sidecars"]
  node_n14["Terminal UI<br/>observer<br/>[terminal_ui.py]"]
  node_n15["Eval Harness<br/>scoring pipeline<br/>[eval.py]"]
  node_n16["Fixtures<br/>test corpus<br/>[documents.json]"]
  node_n17["Web UI<br/>frontend<br/>[index.html]"]
  node_n18["HTTP Server<br/>[server.py]"]
end

node_n1 -->|"runs"| node_n3
node_n2 -->|"runs"| node_n15
node_n15 -->|"loads"| node_n16
node_n3 -->|"reads/writes"| node_n4
node_n3 -->|"checks"| node_n5
node_n3 -->|"starts"| node_n6
node_n6 -->|"updates"| node_n4
node_n3 -->|"plans"| node_n7
node_n7 -->|"routes through"| node_n13
node_n3 -->|"dispatches"| node_n10
node_n10 -->|"executes"| node_n11
node_n10 -->|"calls"| node_n12
node_n3 -->|"observes"| node_n8
node_n8 -->|"merges into"| node_n4
node_n3 -->|"decides"| node_n9
node_n9 -->|"routes through"| node_n13
node_n14 -.->|"watches"| node_n3
node_n14 -.->|"reads"| node_n4
node_n18 -->|"serves"| node_n17
node_n18 -->|"triggers"| node_n3

click node_n1 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/main.py"
click node_n2 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/run_eval.py"
click node_n3 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/agent/loop.py"
click node_n4 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/agent/state.py"
click node_n10 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/tools/registry.py"
click node_n13 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/agent/router.py"
click node_n14 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/observability/terminal_ui.py"
click node_n15 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/eval/eval.py"
click node_n16 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/eval/fixtures/documents.json"
click node_n17 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/ui/index.html"
click node_n18 "https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2 toneBlue
class node_n3,node_n4,node_n5,node_n6,node_n7,node_n8,node_n9 toneAmber
class node_n10,node_n11,node_n12,node_n13 toneMint
class node_n14,node_n15,node_n16,node_n17,node_n18 toneRose
```

## Components

### Orchestration

Entry points that load inputs, run the agent, and collect results.

- [Main](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/main.py): entrypoint · Primary CLI for single runs, demos, and batches. · `main.py`
- [Eval CLI](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/run_eval.py): entrypoint · Batch evaluation entrypoint for fixture-based scoring. · `run_eval.py`

### Agent Core

Shared state and the control loop that drive document processing.

- [Agent Loop](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/agent/loop.py): control loop · PAOD-style cycle: preprocess, plan, act, observe, decide. · `agent/loop.py`
- [State Model](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/agent/state.py): shared state · Central document state shared across all phases. · `agent/state.py`
- **Budget Guard**: policy · Execution limits and retry boundaries enforced by the loop.
- **Preprocess**: deterministic · Normalization, cleanup, and field preparation before planning.
- **Planner**: llm phase · Chooses the next action or tool call.
- **Observe**: merge phase · Folds tool outputs back into shared state.
- **Decision**: llm phase · Produces the final onboarding outcome and confidence.

### Execution Layer

Tool registry and model routing used by the loop to act and decide.

- [Tool Registry](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/tools/registry.py): tool host · Runtime discovery and dispatch for executable capabilities. · `tools/registry.py`
- **Deterministic Tools**: extract/validate · Regex extraction, merge, expiry checks, and cross-reference logic.
- **Mock Verifiers**: external checks · Simulated GST, PAN, and bank verification services.
- [LLM Router](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/agent/router.py): provider policy · Selects models/providers with cost-aware fallback. · `agent/router.py`

### Sidecars

Evaluation, observability, and lightweight UI/server surfaces.

- [Terminal UI](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/observability/terminal_ui.py): observer · Live dashboard for phases, budgets, tool history, and results. · `observability/terminal_ui.py`
- [Eval Harness](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/eval/eval.py): scoring pipeline · Runs fixtures through the agent and computes metrics. · `eval/eval.py`
- [Fixtures](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/eval/fixtures/documents.json): test corpus · Representative documents and expected outcomes. · `eval/fixtures/documents.json`
- [Web UI](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/ui/index.html): frontend · Minimal browser-facing results surface. · `ui/index.html`
- [HTTP Server](https://github.com/adityasingh0912/grabon-agentic-challenge/blob/main/server.py): service · Local service boundary for UI or run triggering. · `server.py`

## Connections

- Main → Agent Loop: runs · Main loads input and invokes the core agent loop.
- Eval CLI → Eval Harness: runs · Eval CLI feeds fixtures into the scoring harness.
- Eval Harness → Fixtures: loads · Evaluation uses fixture documents and expected results.
- Agent Loop → State Model: reads/writes · The loop mutates the shared document state throughout execution.
- Agent Loop → Budget Guard: checks · Every iteration is bounded by budget and retry policy.
- Agent Loop → Preprocess: starts · Processing begins with deterministic preprocessing.
- Preprocess → State Model: updates · Preprocessing normalizes and seeds the state model.
- Agent Loop → Planner: plans · The loop asks the planner for the next action.
- Planner → LLM Router: routes through · Planning and decision phases select models via the router.
- Agent Loop → Tool Registry: dispatches · Planned actions are resolved through the tool registry.
- Tool Registry → Deterministic Tools: executes · Registry dispatches deterministic extraction and validation tools.
- Tool Registry → Mock Verifiers: calls · Registry also fronts mock external verification services.
- Agent Loop → Observe: observes · Tool outputs are folded back into state after each action.
- Observe → State Model: merges into · Observations enrich extracted fields and verification results.
- Agent Loop → Decision: decides · Final decision is produced once the run completes or stops.
- Decision → LLM Router: routes through · The final decision can use a stronger model/provider.
- Terminal UI → Agent Loop: watches · Terminal UI reads the live run state for display.
- Terminal UI → State Model: reads · Dashboard surfaces extracted fields, retries, and confidence.
- HTTP Server → Web UI: serves · Server exposes the browser UI surface.
- HTTP Server → Agent Loop: triggers · Server can initiate or proxy agent runs.
