# mukeshram-07/spanchor architecture

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

- Interactive diagram: https://gitdiagram.com/mukeshram-07/spanchor
- Repository: https://github.com/mukeshram-07/spanchor

## Overview

SPANCHOR is a local-first library and CLI for regression-testing RAG retrieval against source-document spans rather than chunk IDs. Users prepare canonical documents and gold anchors, adapt retrieval output or provide spans, evaluate per-query evidence coverage, then compare baseline and candidate runs under thresholds and inspect reports or gate CI. The graph preserves annotation, validation, serialization, and framework adapters as supporting capabilities. Some subsystem links are based on README workflow statements because their implementation files were not excerpted.

Main entry points: [`src/spanchor/cli.py`](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/cli.py) (CLI commands), [`src/spanchor/evaluation/engine.py`](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/evaluation/engine.py) (Evaluation engine), [`src/spanchor/comparison/compare.py`](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/comparison/compare.py) (Regression comparison), [`src/spanchor/models/document.py`](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/document.py) (Source documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source and gold data"]
  node_canonical["Canonical text<br/>[normalize.py]"]
  node_documents["Source documents<br/>[document.py]"]
  node_anchors["Gold anchors<br/>[anchor.py]"]
  node_annotation["Anchor annotation<br/>[add.py]"]
  node_locate["Locate evidence<br/>[locate.py]"]
  node_validation["Corpus validation<br/>[validation.py]"]
  node_queries["Gold queries<br/>[query.py]"]
end

subgraph group_retrieval["Retrieval inputs"]
  node_adapters["Result adapters<br/>[generic.py]"]
  node_retrievalresults["Retrieval results<br/>[retrieval.py]"]
  node_mapper["Chunk-to-span mapping<br/>[mapper.py]"]
  node_frameworks["Optional adapters<br/>[langchain.py]"]
end

subgraph group_analysis["Evaluation and regression"]
  node_evaluation["Evaluation engine<br/>[engine.py]"]
  node_metrics["Span metrics<br/>[intervals.py]"]
  node_run["Evaluation run<br/>[run.py]"]
  node_comparison["Regression comparison<br/>[compare.py]"]
  node_policy["Metric policy<br/>[policy.py]"]
end

subgraph group_interfaces["Interfaces and persistence"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_reports["Run reports<br/>[markdown.py]"]
  node_jsonstore[("Run JSON storage<br/>[json_io.py]")]
  node_goldstore[("Gold JSONL storage<br/>[jsonl.py]")]
end

node_user(("Benchmark author"))
node_retriever(("RAG retriever"))

node_user -->|"runs commands"| node_cli
node_user -->|"creates anchors"| node_annotation
node_canonical -->|"normalizes text"| node_documents
node_documents -->|"anchors spans"| node_anchors
node_annotation -->|"locates evidence"| node_locate
node_cli -->|"validates corpus"| node_validation
node_cli -->|"locates text"| node_locate
node_user -->|"queries RAG"| node_retriever
node_retriever -->|"returns chunks"| node_adapters
node_frameworks -->|"converts results"| node_retrievalresults
node_adapters -->|"converts results"| node_retrievalresults
node_cli -->|"loads gold data"| node_goldstore
node_retrievalresults -->|"supplies results"| node_evaluation
node_queries -->|"supplies gold"| node_evaluation
node_documents -->|"supplies corpus"| node_evaluation
node_evaluation -->|"maps chunks"| node_mapper
node_evaluation -->|"computes metrics"| node_metrics
node_evaluation -->|"returns run"| node_run
node_run -->|"compares runs"| node_comparison
node_policy -->|"sets thresholds"| node_comparison
node_comparison -->|"feeds report"| node_reports
node_run -.->|"persists run"| node_jsonstore
node_cli -->|"runs evaluation"| node_evaluation
node_cli -->|"runs comparison"| node_comparison
node_cli -->|"writes report"| node_reports

click node_cli "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/cli.py"
click node_canonical "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/canonical/normalize.py"
click node_documents "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/document.py"
click node_anchors "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/anchor.py"
click node_annotation "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/annotation/add.py"
click node_locate "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/annotation/locate.py"
click node_validation "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/validation.py"
click node_queries "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/query.py"
click node_adapters "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/adapters/generic.py"
click node_retrievalresults "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/retrieval.py"
click node_mapper "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/mapping/mapper.py"
click node_evaluation "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/evaluation/engine.py"
click node_metrics "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/evaluation/intervals.py"
click node_run "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/run.py"
click node_comparison "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/comparison/compare.py"
click node_policy "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/comparison/policy.py"
click node_reports "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/reporting/markdown.py"
click node_jsonstore "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/storage/json_io.py"
click node_goldstore "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/storage/jsonl.py"
click node_frameworks "https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/adapters/langchain.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_canonical,node_documents,node_anchors,node_annotation,node_locate,node_validation,node_queries toneBlue
class node_adapters,node_retrievalresults,node_mapper,node_frameworks toneAmber
class node_evaluation,node_metrics,node_run,node_comparison,node_policy toneMint
class node_cli,node_reports,node_jsonstore,node_goldstore toneRose
class node_user,node_retriever toneIndigo
```

## Components

### Source and gold data

- [Canonical text](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/canonical/normalize.py): `src/spanchor/canonical/normalize.py`
- [Source documents](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/document.py): `src/spanchor/models/document.py`
- [Gold anchors](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/anchor.py): `src/spanchor/models/anchor.py`
- [Anchor annotation](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/annotation/add.py): `src/spanchor/annotation/add.py`
- [Locate evidence](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/annotation/locate.py): `src/spanchor/annotation/locate.py`
- [Corpus validation](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/validation.py): `src/spanchor/validation.py`
- [Gold queries](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/query.py): `src/spanchor/models/query.py`

### Retrieval inputs

- [Result adapters](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/adapters/generic.py): `src/spanchor/adapters/generic.py`
- [Retrieval results](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/retrieval.py): `src/spanchor/models/retrieval.py`
- [Chunk-to-span mapping](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/mapping/mapper.py): `src/spanchor/mapping/mapper.py`
- [Optional adapters](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/adapters/langchain.py): `src/spanchor/adapters/langchain.py`

### Evaluation and regression

- [Evaluation engine](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/evaluation/engine.py): `src/spanchor/evaluation/engine.py`
- [Span metrics](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/evaluation/intervals.py): `src/spanchor/evaluation/intervals.py`
- [Evaluation run](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/models/run.py): `src/spanchor/models/run.py`
- [Regression comparison](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/comparison/compare.py): `src/spanchor/comparison/compare.py`
- [Metric policy](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/comparison/policy.py): `src/spanchor/comparison/policy.py`

### Interfaces and persistence

- [CLI commands](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/cli.py): `src/spanchor/cli.py`
- [Run reports](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/reporting/markdown.py): `src/spanchor/reporting/markdown.py`
- [Run JSON storage](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/storage/json_io.py): `src/spanchor/storage/json_io.py`
- [Gold JSONL storage](https://github.com/mukeshram-07/spanchor/blob/master/src/spanchor/storage/jsonl.py): `src/spanchor/storage/jsonl.py`

### Other components

- **Benchmark author**
- **RAG retriever**

## Connections

- Benchmark author → CLI commands: runs commands (evidence: `README.md`)
- Benchmark author → Anchor annotation: creates anchors (evidence: `README.md`)
- Canonical text → Source documents: normalizes text (evidence: `src/spanchor/models/document.py`)
- Source documents → Gold anchors: anchors spans (evidence: `README.md`)
- Anchor annotation → Locate evidence: locates evidence (evidence: `src/spanchor/annotation/add.py`)
- CLI commands → Corpus validation: validates corpus (evidence: `src/spanchor/cli.py`)
- CLI commands → Locate evidence: locates text (evidence: `src/spanchor/cli.py`)
- Benchmark author → RAG retriever: queries RAG (evidence: `README.md`)
- RAG retriever → Result adapters: returns chunks (evidence: `README.md`)
- Optional adapters → Retrieval results: converts results (evidence: `src/spanchor/adapters/langchain.py`)
- Result adapters → Retrieval results: converts results (evidence: `src/spanchor/adapters/generic.py`)
- CLI commands → Gold JSONL storage: loads gold data (evidence: `src/spanchor/cli.py`)
- Retrieval results → Evaluation engine: supplies results (evidence: `README.md`)
- Gold queries → Evaluation engine: supplies gold (evidence: `README.md`)
- Source documents → Evaluation engine: supplies corpus (evidence: `README.md`)
- Evaluation engine → Chunk-to-span mapping: maps chunks (evidence: `src/spanchor/evaluation/engine.py`)
- Evaluation engine → Span metrics: computes metrics (evidence: `src/spanchor/evaluation/engine.py`)
- Evaluation engine → Evaluation run: returns run (evidence: `README.md`)
- Evaluation run → Regression comparison: compares runs (evidence: `README.md`)
- Metric policy → Regression comparison: sets thresholds (evidence: `README.md`)
- Regression comparison → Run reports: feeds report (evidence: `src/spanchor/reporting/markdown.py`)
- Evaluation run → Run JSON storage: persists run (evidence: `src/spanchor/storage/json_io.py`)
- CLI commands → Evaluation engine: runs evaluation (evidence: `src/spanchor/cli.py`)
- CLI commands → Regression comparison: runs comparison (evidence: `src/spanchor/cli.py`)
- CLI commands → Run reports: writes report (evidence: `src/spanchor/cli.py`)
