# krishnamanikanisetty/un-plugged_edition architecture

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

- Interactive diagram: https://gitdiagram.com/krishnamanikanisetty/un-plugged_edition
- Repository: https://github.com/krishnamanikanisetty/un-plugged_edition

## Overview

UNPLLM is an offline-first local assistant with retrieval-augmented generation and an opportunistic Wikipedia sync loop. Users query the FastAPI service; RAG requests are embedded, matched against a local Chroma knowledge base, logged as covered or gap queries, then answered by Ollama. Documents can be ingested separately. When connectivity returns, the watcher clusters unresolved gaps, filters and fetches suitable Wikipedia articles, stores their chunks, and marks successful or unsyncable topics resolved. Gap reporting shares that clustering logic. Source excerpts establish these calls; README content was absent, so broader undocumented capabilities are not assumed.

Main entry points: [`sync_watcher.py`](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/sync_watcher.py) (Connectivity watcher), [`rag_utils.py`](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/rag_utils.py) (Retrieval utilities), [`main.py`](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/main.py) (Inference API), [`ingest.py`](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/ingest.py) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assistant["Assistant runtime"]
  node_api["Inference API<br/>[main.py]"]
  node_ollama["Local Ollama"]
end

subgraph group_knowledge["Knowledge base"]
  node_retrieval["Retrieval utilities<br/>[rag_utils.py]"]
  node_embedder["Sentence embedder"]
  node_vectorstore[("Chroma collection")]
  node_ingestion["Document ingestion<br/>[ingest.py]"]
end

subgraph group_sync["Gap sync"]
  node_watcher["Connectivity watcher<br/>[sync_watcher.py]"]
end

subgraph group_observability["Gap tracking"]
  node_querylog[("Query log<br/>[unpllm_queries.db]")]
  node_logger["Query logger<br/>[query_logger.py]"]
  node_gapengine["Gap clustering<br/>[gap_engine.py]"]
  node_report["Gap report<br/>[analyze_gaps.py]"]
end

node_user(("API user"))
node_documents["Local documents"]
node_internet["Connectivity check"]
node_wikipedia["Wikipedia API"]

node_user -->|"sends request"| node_api
node_api -->|"generates answer"| node_ollama
node_api -->|"retrieves chunks"| node_retrieval
node_api -->|"logs query"| node_logger
node_retrieval -->|"embeds text"| node_embedder
node_retrieval -->|"queries collection"| node_vectorstore
node_ingestion -->|"reads files"| node_documents
node_ingestion -->|"chunks and embeds"| node_retrieval
node_ingestion -->|"upserts chunks"| node_vectorstore
node_logger -->|"writes gaps"| node_querylog
node_gapengine -->|"reads unresolved"| node_querylog
node_report -->|"clusters gaps"| node_gapengine
node_watcher -->|"checks connectivity"| node_internet
node_watcher -->|"loads and clusters"| node_gapengine
node_watcher -->|"classifies and keywords"| node_ollama
node_watcher -.->|"searches and fetches"| node_wikipedia
node_watcher -->|"embeds article"| node_embedder
node_watcher -->|"upserts and evicts"| node_vectorstore
node_watcher -->|"marks resolved"| node_querylog
node_watcher -->|"enforces storage cap"| node_retrieval

click node_api "https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/main.py"
click node_retrieval "https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/rag_utils.py"
click node_vectorstore "https://github.com/krishnamanikanisetty/un-plugged_edition/tree/main/chroma_db"
click node_ingestion "https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/ingest.py"
click node_documents "https://github.com/krishnamanikanisetty/un-plugged_edition/tree/main/documents"
click node_querylog "https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/unpllm_queries.db"
click node_logger "https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/query_logger.py"
click node_gapengine "https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/gap_engine.py"
click node_report "https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/analyze_gaps.py"
click node_watcher "https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/sync_watcher.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_api,node_ollama,node_user toneBlue
class node_retrieval,node_embedder,node_vectorstore,node_ingestion toneAmber
class node_watcher,node_wikipedia toneMint
class node_querylog,node_logger,node_gapengine,node_report toneRose
class node_documents toneTeal
class node_internet toneIndigo
```

## Components

### Assistant runtime

- [Inference API](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/main.py): `main.py`
- **Local Ollama**

### Knowledge base

- [Retrieval utilities](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/rag_utils.py): `rag_utils.py`
- **Sentence embedder**
- [Chroma collection](https://github.com/krishnamanikanisetty/un-plugged_edition/tree/main/chroma_db): `chroma_db`
- [Document ingestion](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/ingest.py): `ingest.py`

### Gap sync

- [Connectivity watcher](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/sync_watcher.py): `sync_watcher.py`

### Gap tracking

- [Query log](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/unpllm_queries.db): `unpllm_queries.db`
- [Query logger](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/query_logger.py): `query_logger.py`
- [Gap clustering](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/gap_engine.py): `gap_engine.py`
- [Gap report](https://github.com/krishnamanikanisetty/un-plugged_edition/blob/main/analyze_gaps.py): `analyze_gaps.py`

### Other components

- **API user**
- [Local documents](https://github.com/krishnamanikanisetty/un-plugged_edition/tree/main/documents): `documents`
- **Connectivity check**
- **Wikipedia API**

## Connections

- API user → Inference API: sends request
- Inference API → Local Ollama: generates answer
- Inference API → Retrieval utilities: retrieves chunks
- Inference API → Query logger: logs query
- Retrieval utilities → Sentence embedder: embeds text
- Retrieval utilities → Chroma collection: queries collection
- Document ingestion → Local documents: reads files
- Document ingestion → Retrieval utilities: chunks and embeds
- Document ingestion → Chroma collection: upserts chunks
- Query logger → Query log: writes gaps
- Gap clustering → Query log: reads unresolved
- Gap report → Gap clustering: clusters gaps
- Connectivity watcher → Connectivity check: checks connectivity
- Connectivity watcher → Gap clustering: loads and clusters
- Connectivity watcher → Local Ollama: classifies and keywords
- Connectivity watcher → Wikipedia API: searches and fetches
- Connectivity watcher → Sentence embedder: embeds article
- Connectivity watcher → Chroma collection: upserts and evicts
- Connectivity watcher → Query log: marks resolved
- Connectivity watcher → Retrieval utilities: enforces storage cap