# ronakparmar11/buildingblocks_maharashtra_round architecture

> Architecture diagram of the GitHub repository ronakparmar11/buildingblocks_maharashtra_round, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ronakparmar11/buildingblocks_maharashtra_round
- Repository: https://github.com/ronakparmar11/buildingblocks_maharashtra_round

## Overview

Black Box records AI-agent task executions, then helps engineers locate a failing step, verify blame through replay, and assess or apply targeted repairs. The main workflow runs an agent under tracing, persists runs and steps, and exposes them for inspection; replay can reuse prior work with overrides. Separate capabilities support fault injection, feature-based failure prediction, evaluation, and a web UI. The excerpts show core replay, tracing, retrieval, and persistence behavior; several API and analysis modules are represented from the source index, so their internal links are limited to documented references.

Main entry points: [`blackbox/replay/engine.py`](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/replay/engine.py) (Replay Engine), [`blackbox/api/app.py`](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/app.py) (HTTP API), [`blackbox/store/db.py`](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/store/db.py) (SQLite Store), [`blackbox/sdk/tracer.py`](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/sdk/tracer.py) (Execution Tracer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web["Web Console<br/>[App.tsx]"]
  node_api["HTTP API<br/>[app.py]"]
  node_run_views["Run Views<br/>[runs.py]"]
  node_compare_eval["Compare and Eval<br/>[compare.py]"]
  node_fleet_lab["Fleet and Lab<br/>[fleet.py]"]
  node_replay_api["Replay API<br/>[replay.py]"]
end

subgraph group_execution["Agent Execution"]
  node_agent["Task Agent<br/>[agent.py]"]
  node_retriever["Passage Retrieval<br/>[retriever.py]"]
  node_tracer["Execution Tracer<br/>[tracer.py]"]
  node_context["Execution Context<br/>[context.py]"]
end

subgraph group_diagnosis["Failure Diagnosis"]
  node_faults["Fault Injection<br/>[inject.py]"]
  node_features["Feature Extraction<br/>[extract.py]"]
  node_labeling["Blame Verification<br/>[counterfactual.py]"]
  node_model["Failure Prediction<br/>[predict.py]"]
  node_evaluation["Evaluation<br/>[evaluate.py]"]
end

subgraph group_recovery["Replay and Repair"]
  node_replay["Replay Engine<br/>[engine.py]"]
  node_repair["Targeted Repair<br/>[repair.py]"]
end

subgraph group_platform["Data and Integrations"]
  node_llm["LLM Clients<br/>[base.py]"]
  node_cassette["Call Cassette<br/>[cassette.py]"]
  node_store["Run Repository<br/>[repo.py]"]
  node_database[("SQLite Store<br/>[db.py]")]
  node_config["Settings<br/>[config.py]"]
end

node_engineer(("Engineer"))

node_engineer -.->|"inspects runs"| node_web
node_web -.->|"requests data"| node_api
node_api -->|"registers routes"| node_run_views
node_api -->|"registers routes"| node_compare_eval
node_api -->|"registers routes"| node_fleet_lab
node_api -->|"registers routes"| node_replay_api
node_api -->|"initializes"| node_database
node_replay_api -->|"invokes replay"| node_replay
node_replay_api -->|"invokes repair"| node_repair
node_replay -->|"runs task"| node_agent
node_replay -->|"gets retriever"| node_retriever
node_replay -->|"builds context"| node_context
node_replay -->|"creates tracer"| node_tracer
node_agent -->|"records steps"| node_tracer
node_agent -->|"searches passages"| node_retriever
node_tracer -->|"caches calls"| node_cassette
node_tracer -->|"persists steps"| node_store
node_cassette -->|"reads and writes"| node_database
node_store -.->|"persists records"| node_database
node_tracer -->|"requests completion"| node_llm
node_faults -->|"injects faults"| node_agent
node_features -->|"reads run data"| node_database
node_labeling -->|"tests counterfactuals"| node_replay
node_model -->|"extracts features"| node_features
node_model -->|"loads model data"| node_database
node_evaluation -->|"evaluates predictions"| node_model
node_evaluation -->|"evaluates repairs"| node_repair
node_repair -->|"tries repairs"| node_replay
node_repair -->|"uses prediction"| node_model
node_config -->|"configures retrieval"| node_retriever
node_config -->|"configures database"| node_database

click node_web "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/app.py"
click node_run_views "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/runs.py"
click node_compare_eval "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/compare.py"
click node_fleet_lab "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/fleet.py"
click node_replay_api "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/replay.py"
click node_agent "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/agent/agent.py"
click node_retriever "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/corpus/retriever.py"
click node_llm "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/llm/base.py"
click node_tracer "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/sdk/tracer.py"
click node_context "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/sdk/context.py"
click node_cassette "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/sdk/cassette.py"
click node_store "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/store/repo.py"
click node_database "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/store/db.py"
click node_faults "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/faults/inject.py"
click node_features "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/features/extract.py"
click node_labeling "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/labeling/counterfactual.py"
click node_model "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/model/predict.py"
click node_evaluation "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/model/evaluate.py"
click node_replay "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/replay/engine.py"
click node_repair "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/repair/repair.py"
click node_config "https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/config.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_web,node_api,node_run_views,node_compare_eval,node_fleet_lab,node_replay_api toneBlue
class node_agent,node_retriever,node_tracer,node_context toneAmber
class node_faults,node_features,node_labeling,node_model,node_evaluation toneMint
class node_replay,node_repair toneRose
class node_llm,node_cassette,node_store,node_database,node_config,node_engineer toneIndigo
```

## Components

### User Experience

- [Web Console](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [HTTP API](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/app.py): `blackbox/api/app.py`
- [Run Views](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/runs.py): `blackbox/api/runs.py`
- [Compare and Eval](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/compare.py): `blackbox/api/compare.py`
- [Fleet and Lab](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/fleet.py): `blackbox/api/fleet.py`
- [Replay API](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/api/replay.py): `blackbox/api/replay.py`

### Agent Execution

- [Task Agent](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/agent/agent.py): `blackbox/agent/agent.py`
- [Passage Retrieval](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/corpus/retriever.py): `blackbox/corpus/retriever.py`
- [Execution Tracer](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/sdk/tracer.py): `blackbox/sdk/tracer.py`
- [Execution Context](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/sdk/context.py): `blackbox/sdk/context.py`

### Failure Diagnosis

- [Fault Injection](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/faults/inject.py): `blackbox/faults/inject.py`
- [Feature Extraction](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/features/extract.py): `blackbox/features/extract.py`
- [Blame Verification](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/labeling/counterfactual.py): `blackbox/labeling/counterfactual.py`
- [Failure Prediction](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/model/predict.py): `blackbox/model/predict.py`
- [Evaluation](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/model/evaluate.py): `blackbox/model/evaluate.py`

### Replay and Repair

- [Replay Engine](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/replay/engine.py): `blackbox/replay/engine.py`
- [Targeted Repair](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/repair/repair.py): `blackbox/repair/repair.py`

### Data and Integrations

- [LLM Clients](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/llm/base.py): `blackbox/llm/base.py`
- [Call Cassette](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/sdk/cassette.py): `blackbox/sdk/cassette.py`
- [Run Repository](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/store/repo.py): `blackbox/store/repo.py`
- [SQLite Store](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/store/db.py): `blackbox/store/db.py`
- [Settings](https://github.com/ronakparmar11/buildingblocks_maharashtra_round/blob/main/blackbox/config.py): `blackbox/config.py`

### Other components

- **Engineer**

## Connections

- Engineer → Web Console: inspects runs
- Web Console → HTTP API: requests data
- HTTP API → Run Views: registers routes (evidence: `blackbox/api/app.py`)
- HTTP API → Compare and Eval: registers routes (evidence: `blackbox/api/app.py`)
- HTTP API → Fleet and Lab: registers routes (evidence: `blackbox/api/app.py`)
- HTTP API → Replay API: registers routes (evidence: `blackbox/api/app.py`)
- HTTP API → SQLite Store: initializes (evidence: `blackbox/api/app.py`)
- Replay API → Replay Engine: invokes replay (evidence: `blackbox/api/replay.py`)
- Replay API → Targeted Repair: invokes repair (evidence: `blackbox/api/replay.py`)
- Replay Engine → Task Agent: runs task (evidence: `blackbox/replay/engine.py`)
- Replay Engine → Passage Retrieval: gets retriever (evidence: `blackbox/replay/engine.py`)
- Replay Engine → Execution Context: builds context (evidence: `blackbox/replay/engine.py`)
- Replay Engine → Execution Tracer: creates tracer (evidence: `blackbox/replay/engine.py`)
- Task Agent → Execution Tracer: records steps (evidence: `blackbox/agent/agent.py`)
- Task Agent → Passage Retrieval: searches passages (evidence: `blackbox/agent/agent.py`)
- Execution Tracer → Call Cassette: caches calls (evidence: `blackbox/sdk/tracer.py`)
- Execution Tracer → Run Repository: persists steps (evidence: `blackbox/sdk/tracer.py`)
- Call Cassette → SQLite Store: reads and writes (evidence: `blackbox/sdk/cassette.py`)
- Run Repository → SQLite Store: persists records
- Execution Tracer → LLM Clients: requests completion (evidence: `blackbox/sdk/tracer.py`)
- Fault Injection → Task Agent: injects faults (evidence: `blackbox/faults/inject.py`)
- Feature Extraction → SQLite Store: reads run data (evidence: `blackbox/features/extract.py`)
- Blame Verification → Replay Engine: tests counterfactuals (evidence: `blackbox/labeling/counterfactual.py`)
- Failure Prediction → Feature Extraction: extracts features (evidence: `blackbox/model/predict.py`)
- Failure Prediction → SQLite Store: loads model data (evidence: `blackbox/model/predict.py`)
- Evaluation → Failure Prediction: evaluates predictions (evidence: `blackbox/model/evaluate.py`)
- Evaluation → Targeted Repair: evaluates repairs (evidence: `blackbox/model/evaluate.py`)
- Targeted Repair → Replay Engine: tries repairs (evidence: `blackbox/repair/repair.py`)
- Targeted Repair → Failure Prediction: uses prediction (evidence: `blackbox/repair/repair.py`)
- Settings → Passage Retrieval: configures retrieval (evidence: `blackbox/corpus/retriever.py`)
- Settings → SQLite Store: configures database (evidence: `blackbox/store/db.py`)
