# samuraigpt/llm-wiki-agent architecture

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

- Interactive diagram: https://gitdiagram.com/samuraigpt/llm-wiki-agent
- Repository: https://github.com/samuraigpt/llm-wiki-agent

## Overview

LLM Wiki Agent is an agent-operated knowledge system: users submit source documents, which are converted when needed and ingested into linked wiki pages; queries synthesize answers from that accumulated knowledge. Separate workflows refresh stale sources, inspect wiki health, repair missing entity pages, and build an interactive graph. The README documents additional supported formats and graph features; sampled excerpts do not expose every internal call, so uncertain wiring is omitted.

Main entry points: [`wiki`](https://github.com/samuraigpt/llm-wiki-agent/tree/main/wiki) (Wiki Pages), [`tools/query.py`](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/query.py) (Query Wiki), [`tools/ingest.py`](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/ingest.py) (Ingest Sources), [`tools/build_graph.py`](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/build_graph.py) (Build Knowledge Graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Source Ingestion"]
  node_pdfconvert["PDF Converter<br/>[pdf2md.py]"]
  node_ingestflow["Ingest Sources<br/>[ingest.py]"]
  node_raw[("Raw Documents")]
end

subgraph group_wiki["Persistent Wiki"]
  node_wikistore[("Wiki Pages")]
  node_utils["Shared Utilities<br/>[_utils.py]"]
end

subgraph group_explore["Knowledge Exploration"]
  node_query["Query Wiki<br/>[query.py]"]
  node_answer["Query Answer"]
  node_graphbuild["Build Knowledge Graph<br/>[build_graph.py]"]
  node_graphdata[("Graph Data")]
  node_graphview["Interactive Graph<br/>[build_graph.py]"]
end

subgraph group_maintain["Wiki Maintenance"]
  node_refresh["Refresh Sources<br/>[refresh.py]"]
  node_lint["Lint Wiki<br/>[lint.py]"]
  node_health["Structural Health<br/>[health.py]"]
  node_heal["Heal Entity Pages<br/>[heal.py]"]
  node_report["Health Reports"]
end

node_user(("User / Agent"))
node_llm{{"LLM Service"}}

node_user -->|"adds documents"| node_raw
node_user -->|"requests ingest"| node_ingestflow
node_user -.->|"requests conversion"| node_pdfconvert
node_pdfconvert -->|"writes Markdown"| node_raw
node_ingestflow -->|"reads sources"| node_raw
node_ingestflow -->|"writes wiki pages"| node_wikistore
node_ingestflow -->|"requests extraction"| node_llm
node_ingestflow -->|"uses helpers"| node_utils
node_user -->|"asks question"| node_query
node_query -->|"reads relevant pages"| node_wikistore
node_query -.->|"reads related links"| node_graphdata
node_query -->|"requests synthesis"| node_llm
node_query -->|"returns answer"| node_answer
node_query -.->|"saves synthesis"| node_wikistore
node_user -->|"requests graph"| node_graphbuild
node_graphbuild -->|"reads wiki links"| node_wikistore
node_graphbuild -->|"infers relationships"| node_llm
node_graphbuild -->|"writes graph"| node_graphdata
node_graphbuild -->|"generates visualization"| node_graphview
node_user -->|"requests refresh"| node_refresh
node_refresh -->|"checks source changes"| node_raw
node_refresh -->|"re-ingests stale source"| node_ingestflow
node_user -->|"requests lint"| node_lint
node_lint -->|"checks wiki pages"| node_wikistore
node_lint -->|"checks graph structure"| node_graphdata
node_lint -->|"checks semantic gaps"| node_llm
node_user -->|"requests health check"| node_health
node_health -->|"checks consistency"| node_wikistore
node_health -.->|"writes report"| node_report
node_user -->|"requests repair"| node_heal
node_heal -->|"reads page context"| node_wikistore
node_heal -->|"generates entity pages"| node_llm
node_heal -->|"uses wiki helpers"| node_utils
node_heal -->|"writes entity pages"| node_wikistore

click node_pdfconvert "https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/pdf2md.py"
click node_ingestflow "https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/ingest.py"
click node_raw "https://github.com/samuraigpt/llm-wiki-agent/tree/main/raw"
click node_wikistore "https://github.com/samuraigpt/llm-wiki-agent/tree/main/wiki"
click node_utils "https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/_utils.py"
click node_refresh "https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/refresh.py"
click node_query "https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/query.py"
click node_graphbuild "https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/build_graph.py"
click node_graphdata "https://github.com/samuraigpt/llm-wiki-agent/tree/main/graph"
click node_graphview "https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/build_graph.py"
click node_lint "https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/lint.py"
click node_health "https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/health.py"
click node_heal "https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/heal.py"
click node_report "https://github.com/samuraigpt/llm-wiki-agent/tree/main/wiki"

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_pdfconvert,node_ingestflow,node_raw,node_user toneBlue
class node_wikistore,node_utils toneAmber
class node_query,node_answer,node_graphbuild,node_graphdata,node_graphview toneMint
class node_refresh,node_lint,node_health,node_heal,node_report toneRose
class node_llm toneIndigo
```

## Components

### Source Ingestion

- [PDF Converter](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/pdf2md.py): `tools/pdf2md.py`
- [Ingest Sources](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/ingest.py): `tools/ingest.py`
- [Raw Documents](https://github.com/samuraigpt/llm-wiki-agent/tree/main/raw): `raw`

### Persistent Wiki

- [Wiki Pages](https://github.com/samuraigpt/llm-wiki-agent/tree/main/wiki): `wiki`
- [Shared Utilities](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/_utils.py): `tools/_utils.py`

### Knowledge Exploration

- [Query Wiki](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/query.py): `tools/query.py`
- **Query Answer**
- [Build Knowledge Graph](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/build_graph.py): `tools/build_graph.py`
- [Graph Data](https://github.com/samuraigpt/llm-wiki-agent/tree/main/graph): `graph`
- [Interactive Graph](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/build_graph.py): `tools/build_graph.py`

### Wiki Maintenance

- [Refresh Sources](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/refresh.py): `tools/refresh.py`
- [Lint Wiki](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/lint.py): `tools/lint.py`
- [Structural Health](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/health.py): `tools/health.py`
- [Heal Entity Pages](https://github.com/samuraigpt/llm-wiki-agent/blob/main/tools/heal.py): `tools/heal.py`
- [Health Reports](https://github.com/samuraigpt/llm-wiki-agent/tree/main/wiki): `wiki`

### Other components

- **User / Agent**
- **LLM Service**

## Connections

- User / Agent → Raw Documents: adds documents
- User / Agent → Ingest Sources: requests ingest
- User / Agent → PDF Converter: requests conversion
- PDF Converter → Raw Documents: writes Markdown
- Ingest Sources → Raw Documents: reads sources
- Ingest Sources → Wiki Pages: writes wiki pages
- Ingest Sources → LLM Service: requests extraction
- Ingest Sources → Shared Utilities: uses helpers
- User / Agent → Query Wiki: asks question
- Query Wiki → Wiki Pages: reads relevant pages
- Query Wiki → Graph Data: reads related links
- Query Wiki → LLM Service: requests synthesis
- Query Wiki → Query Answer: returns answer
- Query Wiki → Wiki Pages: saves synthesis
- User / Agent → Build Knowledge Graph: requests graph
- Build Knowledge Graph → Wiki Pages: reads wiki links
- Build Knowledge Graph → LLM Service: infers relationships
- Build Knowledge Graph → Graph Data: writes graph
- Build Knowledge Graph → Interactive Graph: generates visualization
- User / Agent → Refresh Sources: requests refresh
- Refresh Sources → Raw Documents: checks source changes
- Refresh Sources → Ingest Sources: re-ingests stale source
- User / Agent → Lint Wiki: requests lint
- Lint Wiki → Wiki Pages: checks wiki pages
- Lint Wiki → Graph Data: checks graph structure
- Lint Wiki → LLM Service: checks semantic gaps
- User / Agent → Structural Health: requests health check
- Structural Health → Wiki Pages: checks consistency
- Structural Health → Health Reports: writes report
- User / Agent → Heal Entity Pages: requests repair
- Heal Entity Pages → Wiki Pages: reads page context
- Heal Entity Pages → LLM Service: generates entity pages
- Heal Entity Pages → Shared Utilities: uses wiki helpers
- Heal Entity Pages → Wiki Pages: writes entity pages