# halasadoumi/scientific-agent-that-corrects-itself architecture

> Architecture diagram of the GitHub repository halasadoumi/scientific-agent-that-corrects-itself, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/halasadoumi/scientific-agent-that-corrects-itself
- Repository: https://github.com/halasadoumi/scientific-agent-that-corrects-itself

## Overview

Scientific Verification Agent accepts session questions and files, extracts and chunks document evidence, retrieves and ranks passages, drafts answers, performs a separate claim-check retrieval and model call, and records results for audit. Uploads may be processed synchronously or through Redis-backed jobs; arXiv lookup and semantic embeddings are optional branches. The API owns orchestration, while catalog and object storage provide persistence. The map follows README-described flows where excerpts do not expose route internals; unsampled implementation details are not inferred.

Main entry points: [`src/agent/api/main.py`](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/api/main.py) (Session API), [`src/agent/ingestion/jobs.py`](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/ingestion/jobs.py) (Ingestion job), [`src/agent/storage/catalog.py`](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/storage/catalog.py) (Evidence catalog), [`src/agent/ingestion/pipeline.py`](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/ingestion/pipeline.py) (Document extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion"]
  node_schemas["Input schemas<br/>[ingestion.py]"]
  node_parser["Document extraction<br/>[pipeline.py]"]
  node_job["Ingestion job<br/>[jobs.py]"]
end

subgraph group_retrieve["Evidence retrieval"]
  node_planning["Query planning<br/>[planning.py]"]
  node_cache["Search cache<br/>[cache.py]"]
  node_embeddings["Semantic embeddings<br/>[embeddings.py]"]
  node_scholar["arXiv search<br/>[scholar.py]"]
end

subgraph group_answer["Answer verification"]
  node_generation["Answer and claim checks<br/>[generation.py]"]
end

subgraph group_api["API and jobs"]
  node_api["Session API<br/>[main.py]"]
  node_worker["Background worker<br/>[worker.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_persistence["Persistence"]
  node_catalog[("Evidence catalog<br/>[catalog.py]")]
  node_objects[("Original file store<br/>[objects.py]")]
end

node_user(("Researcher"))
node_bench["Browser test bench<br/>[index.html]"]
node_redis["Redis Streams"]
node_embedding_service["Embedding endpoint"]
node_model_service["Model endpoint"]

node_user -->|"uses"| node_bench
node_bench -->|"uploads through"| node_api
node_user -->|"submits inputs"| node_api
node_api -->|"validates inputs"| node_schemas
node_api -->|"stores originals"| node_objects
node_api -->|"processes uploads"| node_parser
node_parser -->|"indexes chunks"| node_catalog
node_api -->|"enqueues jobs"| node_redis
node_worker -->|"consumes jobs"| node_redis
node_worker -->|"runs"| node_job
node_job -->|"loads originals"| node_objects
node_job -->|"parses and chunks"| node_parser
node_job -->|"embeds chunks"| node_embeddings
node_job -->|"writes documents"| node_catalog
node_api -->|"searches passages"| node_catalog
node_api -->|"plans and reranks"| node_planning
node_api -->|"caches searches"| node_cache
node_api -->|"requests vectors"| node_embeddings
node_embeddings -.->|"sends text"| node_embedding_service
node_api -->|"searches scholarly metadata"| node_scholar
node_api -->|"drafts and verifies"| node_generation
node_generation -->|"requests model output"| node_model_service
node_api -->|"records audit"| node_catalog
node_api -->|"reads settings"| node_config
node_job -->|"reads settings"| node_config

click node_bench "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/api/static/index.html"
click node_api "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/api/main.py"
click node_schemas "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/schemas/ingestion.py"
click node_parser "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/ingestion/pipeline.py"
click node_job "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/ingestion/jobs.py"
click node_worker "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/ingestion/worker.py"
click node_catalog "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/storage/catalog.py"
click node_objects "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/storage/objects.py"
click node_planning "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/retrieval/planning.py"
click node_cache "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/retrieval/cache.py"
click node_embeddings "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/retrieval/embeddings.py"
click node_scholar "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/retrieval/scholar.py"
click node_generation "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/generation.py"
click node_config "https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/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_schemas,node_parser,node_job,node_bench toneBlue
class node_planning,node_cache,node_embeddings,node_scholar,node_redis toneAmber
class node_generation toneMint
class node_api,node_worker,node_config toneRose
class node_catalog,node_objects,node_user,node_embedding_service,node_model_service toneIndigo
```

## Components

### Ingestion

- [Input schemas](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/schemas/ingestion.py): `src/agent/schemas/ingestion.py`
- [Document extraction](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/ingestion/pipeline.py): `src/agent/ingestion/pipeline.py`
- [Ingestion job](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/ingestion/jobs.py): `src/agent/ingestion/jobs.py`

### Evidence retrieval

- [Query planning](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/retrieval/planning.py): `src/agent/retrieval/planning.py`
- [Search cache](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/retrieval/cache.py): `src/agent/retrieval/cache.py`
- [Semantic embeddings](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/retrieval/embeddings.py): `src/agent/retrieval/embeddings.py`
- [arXiv search](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/retrieval/scholar.py): `src/agent/retrieval/scholar.py`

### Answer verification

- [Answer and claim checks](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/generation.py): `src/agent/generation.py`

### API and jobs

- [Session API](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/api/main.py): `src/agent/api/main.py`
- [Background worker](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/ingestion/worker.py): `src/agent/ingestion/worker.py`
- [Runtime settings](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/config.py): `src/agent/config.py`

### Persistence

- [Evidence catalog](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/storage/catalog.py): `src/agent/storage/catalog.py`
- [Original file store](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/storage/objects.py): `src/agent/storage/objects.py`

### Other components

- **Researcher**
- [Browser test bench](https://github.com/halasadoumi/scientific-agent-that-corrects-itself/blob/main/src/agent/api/static/index.html): `src/agent/api/static/index.html`
- **Redis Streams**
- **Embedding endpoint**
- **Model endpoint**

## Connections

- Researcher → Browser test bench: uses (evidence: `README.md`)
- Browser test bench → Session API: uploads through (evidence: `README.md`)
- Researcher → Session API: submits inputs (evidence: `README.md`)
- Session API → Input schemas: validates inputs (evidence: `src/agent/api/main.py`)
- Session API → Original file store: stores originals (evidence: `README.md`)
- Session API → Document extraction: processes uploads (evidence: `README.md`)
- Document extraction → Evidence catalog: indexes chunks (evidence: `src/agent/ingestion/jobs.py`)
- Session API → Redis Streams: enqueues jobs (evidence: `README.md`)
- Background worker → Redis Streams: consumes jobs (evidence: `README.md`)
- Background worker → Ingestion job: runs (evidence: `src/agent/ingestion/worker.py`)
- Ingestion job → Original file store: loads originals (evidence: `src/agent/ingestion/jobs.py`)
- Ingestion job → Document extraction: parses and chunks (evidence: `src/agent/ingestion/jobs.py`)
- Ingestion job → Semantic embeddings: embeds chunks (evidence: `src/agent/ingestion/jobs.py`)
- Ingestion job → Evidence catalog: writes documents (evidence: `src/agent/ingestion/jobs.py`)
- Session API → Evidence catalog: searches passages (evidence: `README.md`)
- Session API → Query planning: plans and reranks (evidence: `src/agent/api/main.py`)
- Session API → Search cache: caches searches (evidence: `src/agent/api/main.py`)
- Session API → Semantic embeddings: requests vectors (evidence: `src/agent/api/main.py`)
- Semantic embeddings → Embedding endpoint: sends text (evidence: `README.md`)
- Session API → arXiv search: searches scholarly metadata (evidence: `README.md`)
- Session API → Answer and claim checks: drafts and verifies (evidence: `src/agent/api/main.py`)
- Answer and claim checks → Model endpoint: requests model output (evidence: `src/agent/generation.py`)
- Session API → Evidence catalog: records audit (evidence: `README.md`)
- Session API → Runtime settings: reads settings (evidence: `src/agent/api/main.py`)
- Ingestion job → Runtime settings: reads settings (evidence: `src/agent/ingestion/jobs.py`)