# satyarth98/tracelean architecture

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

- Interactive diagram: https://gitdiagram.com/satyarth98/tracelean
- Repository: https://github.com/satyarth98/tracelean

## Overview

TraceLean is a local document-indexing and question-answering product. Its main workflow is CLI or Python caller → configured pipeline → document chunking and index build → ReAct reasoning → selected tools and retrieval → citation-checked answer. Retrieval can use the built-in local index or optional LEANN; reasoning can use several providers. Benchmarking and tracing are separate product capabilities. The graph follows documented wiring and source-index references; unsampled implementation details are represented only where the README documents them.

Main entry points: [`src/tracelean/pipeline.py`](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/pipeline.py) (Pipeline), [`src/tracelean/agent/react.py`](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/agent/react.py) (ReAct agent), [`src/tracelean/tools/base.py`](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/tools/base.py) (Tool registry), [`src/tracelean/retrieval/base.py`](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/retrieval/base.py) (Retriever interfaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_pipeline["Pipeline<br/>[pipeline.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_agent["Reasoning and tools"]
  node_agent_loop["ReAct agent<br/>[react.py]"]
  node_parser["Step parser<br/>[parser.py]"]
  node_prompts["Prompt builder<br/>[prompts.py]"]
  node_tool_registry["Tool registry<br/>[base.py]"]
  node_knowledge["Knowledge search<br/>[knowledge.py]"]
  node_calculator["Calculator<br/>[calculator.py]"]
  node_web_tools["Web search and fetch<br/>[web.py]"]
end

subgraph group_retrieval["Index and retrieval"]
  node_chunking["Document chunking<br/>[chunking.py]"]
  node_retriever_api["Retriever interfaces<br/>[base.py]"]
  node_local[("Local backend<br/>[local_backend.py]")]
  node_leann[("LEANN backend<br/>[leann_backend.py]")]
  node_embedding["Hash embeddings<br/>[embedding.py]"]
end

subgraph group_integrations["Providers and tracing"]
  node_llm["LLM providers<br/>[llm.py]"]
  node_observability["Trace instrumentation<br/>[observability.py]"]
end

subgraph group_operations["Diagnostics and measurement"]
  node_benchmark["Storage benchmark<br/>[storage_model.py]"]
  node_benchmark_runner["Benchmark runner<br/>[run_benchmark.py]"]
end

node_user(("User"))
node_model_service{{"Model service"}}
node_web_service{{"Web services"}}
node_opik{{"Opik"}}

node_user -->|"runs commands"| node_cli
node_user -->|"uses API"| node_pipeline
node_cli -->|"invokes"| node_pipeline
node_pipeline -->|"loads settings"| node_config
node_pipeline -->|"prepares documents"| node_chunking
node_pipeline -->|"builds and searches"| node_retriever_api
node_pipeline -->|"runs questions"| node_agent_loop
node_retriever_api -->|"implemented by"| node_local
node_retriever_api -->|"implemented by"| node_leann
node_local -->|"embeds text"| node_embedding
node_agent_loop -->|"parses steps"| node_parser
node_agent_loop -->|"builds prompts"| node_prompts
node_agent_loop -->|"requests reasoning"| node_llm
node_agent_loop -->|"dispatches calls"| node_tool_registry
node_tool_registry -->|"registers tool"| node_knowledge
node_tool_registry -->|"registers tool"| node_calculator
node_tool_registry -->|"registers tools"| node_web_tools
node_knowledge -->|"searches passages"| node_retriever_api
node_llm -->|"calls provider"| node_model_service
node_web_tools -->|"searches and fetches"| node_web_service
node_pipeline -->|"configures tracing"| node_observability
node_observability -->|"exports spans"| node_opik
node_cli -->|"runs benchmark"| node_benchmark_runner
node_benchmark_runner -->|"checks storage model"| node_benchmark

click node_cli "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/cli.py"
click node_pipeline "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/pipeline.py"
click node_config "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/config.py"
click node_chunking "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/chunking.py"
click node_retriever_api "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/retrieval/base.py"
click node_local "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/retrieval/local_backend.py"
click node_leann "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/retrieval/leann_backend.py"
click node_embedding "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/retrieval/embedding.py"
click node_agent_loop "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/agent/react.py"
click node_parser "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/agent/parser.py"
click node_prompts "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/agent/prompts.py"
click node_tool_registry "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/tools/base.py"
click node_knowledge "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/tools/knowledge.py"
click node_calculator "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/tools/calculator.py"
click node_web_tools "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/tools/web.py"
click node_llm "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/llm.py"
click node_observability "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/observability.py"
click node_benchmark "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/bench/storage_model.py"
click node_benchmark_runner "https://github.com/satyarth98/tracelean/blob/main/src/tracelean/bench/run_benchmark.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_cli,node_pipeline,node_config,node_user toneBlue
class node_agent_loop,node_parser,node_prompts,node_tool_registry,node_knowledge,node_calculator,node_web_tools toneAmber
class node_chunking,node_retriever_api,node_local,node_leann,node_embedding toneMint
class node_llm,node_observability toneRose
class node_benchmark,node_benchmark_runner,node_model_service,node_web_service,node_opik toneIndigo
```

## Components

### Entry and orchestration

- [CLI commands](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/cli.py): `src/tracelean/cli.py`
- [Pipeline](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/pipeline.py): `src/tracelean/pipeline.py`
- [Configuration](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/config.py): `src/tracelean/config.py`

### Reasoning and tools

- [ReAct agent](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/agent/react.py): `src/tracelean/agent/react.py`
- [Step parser](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/agent/parser.py): `src/tracelean/agent/parser.py`
- [Prompt builder](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/agent/prompts.py): `src/tracelean/agent/prompts.py`
- [Tool registry](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/tools/base.py): `src/tracelean/tools/base.py`
- [Knowledge search](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/tools/knowledge.py): `src/tracelean/tools/knowledge.py`
- [Calculator](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/tools/calculator.py): `src/tracelean/tools/calculator.py`
- [Web search and fetch](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/tools/web.py): `src/tracelean/tools/web.py`

### Index and retrieval

- [Document chunking](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/chunking.py): `src/tracelean/chunking.py`
- [Retriever interfaces](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/retrieval/base.py): `src/tracelean/retrieval/base.py`
- [Local backend](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/retrieval/local_backend.py): `src/tracelean/retrieval/local_backend.py`
- [LEANN backend](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/retrieval/leann_backend.py): `src/tracelean/retrieval/leann_backend.py`
- [Hash embeddings](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/retrieval/embedding.py): `src/tracelean/retrieval/embedding.py`

### Providers and tracing

- [LLM providers](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/llm.py): `src/tracelean/llm.py`
- [Trace instrumentation](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/observability.py): `src/tracelean/observability.py`

### Diagnostics and measurement

- [Storage benchmark](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/bench/storage_model.py): `src/tracelean/bench/storage_model.py`
- [Benchmark runner](https://github.com/satyarth98/tracelean/blob/main/src/tracelean/bench/run_benchmark.py): `src/tracelean/bench/run_benchmark.py`

### Other components

- **User**
- **Model service**
- **Web services**
- **Opik**

## Connections

- User → CLI commands: runs commands (evidence: `README.md`)
- User → Pipeline: uses API (evidence: `src/tracelean/pipeline.py`)
- CLI commands → Pipeline: invokes (evidence: `src/tracelean/cli.py`)
- Pipeline → Configuration: loads settings (evidence: `src/tracelean/pipeline.py`)
- Pipeline → Document chunking: prepares documents (evidence: `src/tracelean/pipeline.py`)
- Pipeline → Retriever interfaces: builds and searches (evidence: `src/tracelean/pipeline.py`)
- Pipeline → ReAct agent: runs questions (evidence: `src/tracelean/pipeline.py`)
- Retriever interfaces → Local backend: implemented by (evidence: `src/tracelean/retrieval/__init__.py`)
- Retriever interfaces → LEANN backend: implemented by (evidence: `src/tracelean/retrieval/__init__.py`)
- Local backend → Hash embeddings: embeds text (evidence: `src/tracelean/retrieval/local_backend.py`)
- ReAct agent → Step parser: parses steps (evidence: `src/tracelean/agent/react.py`)
- ReAct agent → Prompt builder: builds prompts (evidence: `src/tracelean/agent/react.py`)
- ReAct agent → LLM providers: requests reasoning (evidence: `src/tracelean/agent/react.py`)
- ReAct agent → Tool registry: dispatches calls (evidence: `src/tracelean/agent/react.py`)
- Tool registry → Knowledge search: registers tool (evidence: `src/tracelean/tools/__init__.py`)
- Tool registry → Calculator: registers tool (evidence: `src/tracelean/tools/__init__.py`)
- Tool registry → Web search and fetch: registers tools (evidence: `src/tracelean/tools/__init__.py`)
- Knowledge search → Retriever interfaces: searches passages (evidence: `src/tracelean/tools/knowledge.py`)
- LLM providers → Model service: calls provider (evidence: `README.md`)
- Web search and fetch → Web services: searches and fetches (evidence: `README.md`)
- Pipeline → Trace instrumentation: configures tracing (evidence: `src/tracelean/pipeline.py`)
- Trace instrumentation → Opik: exports spans (evidence: `src/tracelean/observability.py`)
- CLI commands → Benchmark runner: runs benchmark (evidence: `src/tracelean/cli.py`)
- Benchmark runner → Storage benchmark: checks storage model (evidence: `src/tracelean/cli.py`)