# liyuan551408-bot/smart-context architecture

> Architecture diagram of the GitHub repository liyuan551408-bot/smart-context, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/liyuan551408-bot/smart-context
- Repository: https://github.com/liyuan551408-bot/smart-context

## Overview

Smart Context indexes a target codebase, then retrieves a compact context set for an AI coding agent. The main workflow runs from a developer query through embedding, candidate ranking, and token-budgeted context construction. A separate indexing workflow chunks and embeds repository files, reusing unchanged content. The README also documents adaptive chunking and benchmark/evaluation capabilities; benchmark internals are represented only at directory level. Relationships for unsampled benchmark code are documented rather than inferred from its implementation.

Main entry points: [`scripts/retrieve.py`](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/retrieve.py) (Retrieval CLI), [`scripts/update_index.py`](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/update_index.py) (Index updater), [`scripts/semantic_chunker.py`](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/semantic_chunker.py) (Adaptive chunking), [`scripts/utils.py`](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/utils.py) (Query embedding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_retrieval["Context retrieval"]
  node_retrieve_cli["Retrieval CLI<br/>[retrieve.py]"]
  node_query_embedding["Query embedding<br/>[utils.py]"]
  node_semantic_search["Semantic candidates<br/>[retrieve.py]"]
  node_dependency_expansion["Dependency expansion"]
  node_hybrid_reranking["Hybrid reranking<br/>[retrieve.py]"]
  node_context_builder["Context selection<br/>[retrieve.py]"]
end

subgraph group_indexing["Repository indexing"]
  node_index_updater["Index updater<br/>[update_index.py]"]
  node_file_discovery["Source discovery<br/>[update_index.py]"]
  node_adaptive_chunker["Adaptive chunking"]
  node_local_chunker["Deterministic chunking<br/>[chunker.py]"]
  node_chunk_quality["Chunk quality checks<br/>[chunk_quality.py]"]
  node_embedding_builder["Embedding generation<br/>[utils.py]"]
end

subgraph group_shared["Shared infrastructure"]
  node_index_store[("Cached index")]
  node_shared_utils["Index utilities<br/>[utils.py]"]
end

subgraph group_evaluation["Evaluation capabilities"]
  node_benchmark_suite["Benchmark evaluation"]
end

node_developer(("Developer"))
node_siliconflow["SiliconFlow API"]
node_coding_agent(("Coding agent"))
node_glm_api["GLM boundary service"]

node_developer -->|"submits query"| node_retrieve_cli
node_retrieve_cli -->|"embeds query"| node_query_embedding
node_query_embedding -->|"requests embedding"| node_siliconflow
node_retrieve_cli -->|"retrieves candidates"| node_semantic_search
node_semantic_search -->|"loads vectors"| node_index_store
node_retrieve_cli -->|"expands candidates"| node_dependency_expansion
node_retrieve_cli -->|"ranks candidates"| node_hybrid_reranking
node_retrieve_cli -->|"selects within budget"| node_context_builder
node_context_builder -->|"returns context"| node_coding_agent
node_index_updater -->|"scans files"| node_file_discovery
node_index_updater -->|"chunks changed files"| node_adaptive_chunker
node_adaptive_chunker -->|"starts with local chunks"| node_local_chunker
node_adaptive_chunker -->|"checks refinement need"| node_chunk_quality
node_adaptive_chunker -.->|"proposes boundaries"| node_glm_api
node_index_updater -->|"embeds fresh chunks"| node_embedding_builder
node_embedding_builder -->|"requests embeddings"| node_siliconflow
node_index_updater -->|"writes index"| node_index_store
node_retrieve_cli -->|"loads index"| node_shared_utils
node_index_updater -->|"uses cache and hashes"| node_shared_utils
node_developer -.->|"evaluates retrieval"| node_benchmark_suite

click node_retrieve_cli "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/retrieve.py"
click node_query_embedding "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/utils.py"
click node_semantic_search "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/retrieve.py"
click node_dependency_expansion "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/dependency_graph.py"
click node_hybrid_reranking "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/retrieve.py"
click node_context_builder "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/retrieve.py"
click node_index_updater "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/update_index.py"
click node_file_discovery "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/update_index.py"
click node_adaptive_chunker "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/semantic_chunker.py"
click node_local_chunker "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/chunker.py"
click node_chunk_quality "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/chunk_quality.py"
click node_embedding_builder "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/utils.py"
click node_index_store "https://github.com/liyuan551408-bot/smart-context/tree/main/cache"
click node_shared_utils "https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/utils.py"
click node_benchmark_suite "https://github.com/liyuan551408-bot/smart-context/tree/main/benchmarks"

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_retrieve_cli,node_query_embedding,node_semantic_search,node_dependency_expansion,node_hybrid_reranking,node_context_builder toneBlue
class node_index_updater,node_file_discovery,node_adaptive_chunker,node_local_chunker,node_chunk_quality,node_embedding_builder toneAmber
class node_index_store,node_shared_utils,node_siliconflow toneMint
class node_benchmark_suite toneRose
class node_developer,node_coding_agent,node_glm_api toneIndigo
```

## Components

### Context retrieval

- [Retrieval CLI](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/retrieve.py): `scripts/retrieve.py`
- [Query embedding](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/utils.py): `scripts/utils.py`
- [Semantic candidates](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/retrieve.py): `scripts/retrieve.py`
- [Dependency expansion](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/dependency_graph.py): `scripts/dependency_graph.py`
- [Hybrid reranking](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/retrieve.py): `scripts/retrieve.py`
- [Context selection](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/retrieve.py): `scripts/retrieve.py`

### Repository indexing

- [Index updater](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/update_index.py): `scripts/update_index.py`
- [Source discovery](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/update_index.py): `scripts/update_index.py`
- [Adaptive chunking](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/semantic_chunker.py): `scripts/semantic_chunker.py`
- [Deterministic chunking](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/chunker.py): `scripts/chunker.py`
- [Chunk quality checks](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/chunk_quality.py): `scripts/chunk_quality.py`
- [Embedding generation](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/utils.py): `scripts/utils.py`

### Shared infrastructure

- [Cached index](https://github.com/liyuan551408-bot/smart-context/tree/main/cache): `cache`
- [Index utilities](https://github.com/liyuan551408-bot/smart-context/blob/main/scripts/utils.py): `scripts/utils.py`

### Evaluation capabilities

- [Benchmark evaluation](https://github.com/liyuan551408-bot/smart-context/tree/main/benchmarks): `benchmarks`

### Other components

- **Developer**
- **SiliconFlow API**
- **Coding agent**
- **GLM boundary service**

## Connections

- Developer → Retrieval CLI: submits query (evidence: `README.md`)
- Retrieval CLI → Query embedding: embeds query (evidence: `scripts/retrieve.py`)
- Query embedding → SiliconFlow API: requests embedding (evidence: `scripts/utils.py`)
- Retrieval CLI → Semantic candidates: retrieves candidates (evidence: `scripts/retrieve.py`)
- Semantic candidates → Cached index: loads vectors
- Retrieval CLI → Dependency expansion: expands candidates (evidence: `scripts/retrieve.py`)
- Retrieval CLI → Hybrid reranking: ranks candidates (evidence: `scripts/retrieve.py`)
- Retrieval CLI → Context selection: selects within budget (evidence: `scripts/retrieve.py`)
- Context selection → Coding agent: returns context (evidence: `README.md`)
- Index updater → Source discovery: scans files (evidence: `scripts/update_index.py`)
- Index updater → Adaptive chunking: chunks changed files (evidence: `scripts/update_index.py`)
- Adaptive chunking → Deterministic chunking: starts with local chunks (evidence: `scripts/semantic_chunker.py`)
- Adaptive chunking → Chunk quality checks: checks refinement need (evidence: `scripts/semantic_chunker.py`)
- Adaptive chunking → GLM boundary service: proposes boundaries (evidence: `README.md`)
- Index updater → Embedding generation: embeds fresh chunks (evidence: `scripts/update_index.py`)
- Embedding generation → SiliconFlow API: requests embeddings (evidence: `scripts/utils.py`)
- Index updater → Cached index: writes index (evidence: `scripts/update_index.py`)
- Retrieval CLI → Index utilities: loads index (evidence: `scripts/retrieve.py`)
- Index updater → Index utilities: uses cache and hashes (evidence: `scripts/update_index.py`)
- Developer → Benchmark evaluation: evaluates retrieval (evidence: `README.md`)