# karan-17/livin-book architecture

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

- Interactive diagram: https://gitdiagram.com/karan-17/livin-book
- Repository: https://github.com/karan-17/livin-book

## Overview

Novel Agent ingests a book into chapter-aware passage and summary indexes plus structured literary knowledge, then answers multi-turn reader questions through a planned, tool-using LangGraph agent. The main query path runs from terminal or Streamlit through the event runner, graph, and tools to hybrid retrieval or knowledge lookups, with citations returned to the UI. Memory adds thread history and reader preferences/spoiler limits. The README documents several connections; some implementation details are unsampled, so those relationships are shown only where documented or indexed.

Main entry points: [`novel_agent/ingest.py`](https://github.com/karan-17/livin-book/blob/main/novel_agent/ingest.py) (Ingestion CLI), [`novel_agent/resources.py`](https://github.com/karan-17/livin-book/blob/main/novel_agent/resources.py) (Book resources), [`novel_agent/graph.py`](https://github.com/karan-17/livin-book/blob/main/novel_agent/graph.py) (Reasoning graph), [`novel_agent/config.py`](https://github.com/karan-17/livin-book/blob/main/novel_agent/config.py) (Model configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Book ingestion"]
  node_ingest_cli["Ingestion CLI<br/>[ingest.py]"]
  node_book_source["Book sources<br/>[loaders.py]"]
  node_book_metadata["Book presets<br/>[books.py]"]
  node_chapter_split["Chapter splitting<br/>[chapters.py]"]
  node_chunking["Passage chunking<br/>[chunking.py]"]
  node_enrichment["Literary enrichment<br/>[enrich.py]"]
  node_index_builder["Index builder<br/>[indexing.py]"]
end

subgraph group_query["Conversation and reasoning"]
  node_prompts["Prompt templates<br/>[prompts.py]"]
  node_agent_tools["Agent tools<br/>[tools.py]"]
  node_agent_graph["Reasoning graph<br/>[graph.py]"]
  node_turn_runner["Turn event runner<br/>[runner.py]"]
  node_terminal_chat["Terminal chat<br/>[chat.py]"]
  node_web_ui["Streamlit UI<br/>[app.py]"]
end

subgraph group_retrieval["Retrieval and knowledge"]
  node_vector_db[("Chroma indexes")]
  node_knowledge_file["Book knowledge"]
  node_resources["Book resources<br/>[resources.py]"]
  node_hybrid_retriever["Hybrid retrieval<br/>[retrieval.py]"]
  node_knowledge_lookup["Knowledge lookups<br/>[knowledge.py]"]
  node_bm25_corpus["BM25 corpus"]
end

subgraph group_memory["Reader memory"]
  node_memory[("Thread and profile memory<br/>[memory.py]")]
end

subgraph group_platform["Model services"]
  node_config["Model configuration<br/>[config.py]"]
  node_gemini{{"Gemini API"}}
  node_voyage{{"Voyage API"}}
end

node_reader(("Reader"))

node_reader -->|"asks questions"| node_terminal_chat
node_reader -->|"asks questions"| node_web_ui
node_ingest_cli -->|"loads book"| node_book_source
node_ingest_cli -->|"selects preset"| node_book_metadata
node_ingest_cli -->|"splits chapters"| node_chapter_split
node_ingest_cli -->|"creates chunks"| node_chunking
node_ingest_cli -->|"builds indexes"| node_index_builder
node_ingest_cli -->|"enriches chapters"| node_enrichment
node_enrichment -->|"uses templates"| node_prompts
node_enrichment -->|"writes knowledge"| node_knowledge_file
node_index_builder -->|"stores vectors"| node_vector_db
node_index_builder -->|"saves chunks"| node_bm25_corpus
node_index_builder -->|"gets settings"| node_config
node_config -->|"creates embeddings"| node_voyage
node_resources -->|"opens collections"| node_vector_db
node_resources -->|"loads documents"| node_bm25_corpus
node_resources -->|"loads knowledge"| node_knowledge_file
node_resources -->|"builds retrievers"| node_hybrid_retriever
node_resources -->|"loads lookups"| node_knowledge_lookup
node_config -.->|"creates reranker"| node_voyage
node_terminal_chat -->|"streams turns"| node_turn_runner
node_web_ui -->|"streams turns"| node_turn_runner
node_turn_runner -->|"streams graph"| node_agent_graph
node_agent_graph -->|"dispatches tools"| node_agent_tools
node_agent_tools -->|"uses book data"| node_resources
node_agent_tools -->|"updates profile"| node_memory
node_agent_graph -->|"manages thread"| node_memory
node_agent_graph -->|"uses templates"| node_prompts
node_agent_graph -->|"gets model"| node_config
node_config -->|"creates chat models"| node_gemini
node_hybrid_retriever -.->|"reranks results"| node_voyage
node_web_ui -->|"shows answers"| node_reader

click node_ingest_cli "https://github.com/karan-17/livin-book/blob/main/novel_agent/ingest.py"
click node_book_source "https://github.com/karan-17/livin-book/blob/main/novel_agent/loaders.py"
click node_book_metadata "https://github.com/karan-17/livin-book/blob/main/novel_agent/books.py"
click node_chapter_split "https://github.com/karan-17/livin-book/blob/main/novel_agent/chapters.py"
click node_chunking "https://github.com/karan-17/livin-book/blob/main/novel_agent/chunking.py"
click node_enrichment "https://github.com/karan-17/livin-book/blob/main/novel_agent/enrich.py"
click node_prompts "https://github.com/karan-17/livin-book/blob/main/novel_agent/prompts.py"
click node_index_builder "https://github.com/karan-17/livin-book/blob/main/novel_agent/indexing.py"
click node_resources "https://github.com/karan-17/livin-book/blob/main/novel_agent/resources.py"
click node_hybrid_retriever "https://github.com/karan-17/livin-book/blob/main/novel_agent/retrieval.py"
click node_knowledge_lookup "https://github.com/karan-17/livin-book/blob/main/novel_agent/knowledge.py"
click node_agent_tools "https://github.com/karan-17/livin-book/blob/main/novel_agent/tools.py"
click node_agent_graph "https://github.com/karan-17/livin-book/blob/main/novel_agent/graph.py"
click node_turn_runner "https://github.com/karan-17/livin-book/blob/main/novel_agent/runner.py"
click node_terminal_chat "https://github.com/karan-17/livin-book/blob/main/novel_agent/chat.py"
click node_web_ui "https://github.com/karan-17/livin-book/blob/main/app.py"
click node_memory "https://github.com/karan-17/livin-book/blob/main/novel_agent/memory.py"
click node_config "https://github.com/karan-17/livin-book/blob/main/novel_agent/config.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_ingest_cli,node_book_source,node_book_metadata,node_chapter_split,node_chunking,node_enrichment,node_index_builder toneBlue
class node_prompts,node_agent_tools,node_agent_graph,node_turn_runner,node_terminal_chat,node_web_ui toneAmber
class node_vector_db,node_knowledge_file,node_resources,node_hybrid_retriever,node_knowledge_lookup,node_bm25_corpus toneMint
class node_memory toneRose
class node_config,node_gemini,node_voyage,node_reader toneIndigo
```

## Components

### Book ingestion

- [Ingestion CLI](https://github.com/karan-17/livin-book/blob/main/novel_agent/ingest.py): `novel_agent/ingest.py`
- [Book sources](https://github.com/karan-17/livin-book/blob/main/novel_agent/loaders.py): `novel_agent/loaders.py`
- [Book presets](https://github.com/karan-17/livin-book/blob/main/novel_agent/books.py): `novel_agent/books.py`
- [Chapter splitting](https://github.com/karan-17/livin-book/blob/main/novel_agent/chapters.py): `novel_agent/chapters.py`
- [Passage chunking](https://github.com/karan-17/livin-book/blob/main/novel_agent/chunking.py): `novel_agent/chunking.py`
- [Literary enrichment](https://github.com/karan-17/livin-book/blob/main/novel_agent/enrich.py): `novel_agent/enrich.py`
- [Index builder](https://github.com/karan-17/livin-book/blob/main/novel_agent/indexing.py): `novel_agent/indexing.py`

### Conversation and reasoning

- [Prompt templates](https://github.com/karan-17/livin-book/blob/main/novel_agent/prompts.py): `novel_agent/prompts.py`
- [Agent tools](https://github.com/karan-17/livin-book/blob/main/novel_agent/tools.py): `novel_agent/tools.py`
- [Reasoning graph](https://github.com/karan-17/livin-book/blob/main/novel_agent/graph.py): `novel_agent/graph.py`
- [Turn event runner](https://github.com/karan-17/livin-book/blob/main/novel_agent/runner.py): `novel_agent/runner.py`
- [Terminal chat](https://github.com/karan-17/livin-book/blob/main/novel_agent/chat.py): `novel_agent/chat.py`
- [Streamlit UI](https://github.com/karan-17/livin-book/blob/main/app.py): `app.py`

### Retrieval and knowledge

- **Chroma indexes**
- **Book knowledge**
- [Book resources](https://github.com/karan-17/livin-book/blob/main/novel_agent/resources.py): `novel_agent/resources.py`
- [Hybrid retrieval](https://github.com/karan-17/livin-book/blob/main/novel_agent/retrieval.py): `novel_agent/retrieval.py`
- [Knowledge lookups](https://github.com/karan-17/livin-book/blob/main/novel_agent/knowledge.py): `novel_agent/knowledge.py`
- **BM25 corpus**

### Reader memory

- [Thread and profile memory](https://github.com/karan-17/livin-book/blob/main/novel_agent/memory.py): `novel_agent/memory.py`

### Model services

- [Model configuration](https://github.com/karan-17/livin-book/blob/main/novel_agent/config.py): `novel_agent/config.py`
- **Gemini API**
- **Voyage API**

### Other components

- **Reader**

## Connections

- Reader → Terminal chat: asks questions (evidence: `README.md`)
- Reader → Streamlit UI: asks questions (evidence: `README.md`)
- Ingestion CLI → Book sources: loads book (evidence: `novel_agent/ingest.py`)
- Ingestion CLI → Book presets: selects preset (evidence: `novel_agent/ingest.py`)
- Ingestion CLI → Chapter splitting: splits chapters (evidence: `novel_agent/ingest.py`)
- Ingestion CLI → Passage chunking: creates chunks (evidence: `novel_agent/ingest.py`)
- Ingestion CLI → Index builder: builds indexes (evidence: `README.md`)
- Ingestion CLI → Literary enrichment: enriches chapters (evidence: `README.md`)
- Literary enrichment → Prompt templates: uses templates (evidence: `novel_agent/enrich.py`)
- Literary enrichment → Book knowledge: writes knowledge (evidence: `novel_agent/enrich.py`)
- Index builder → Chroma indexes: stores vectors (evidence: `novel_agent/indexing.py`)
- Index builder → BM25 corpus: saves chunks (evidence: `novel_agent/indexing.py`)
- Index builder → Model configuration: gets settings (evidence: `novel_agent/indexing.py`)
- Model configuration → Voyage API: creates embeddings (evidence: `README.md`)
- Book resources → Chroma indexes: opens collections (evidence: `novel_agent/resources.py`)
- Book resources → BM25 corpus: loads documents (evidence: `novel_agent/resources.py`)
- Book resources → Book knowledge: loads knowledge (evidence: `novel_agent/resources.py`)
- Book resources → Hybrid retrieval: builds retrievers (evidence: `novel_agent/resources.py`)
- Book resources → Knowledge lookups: loads lookups (evidence: `novel_agent/resources.py`)
- Model configuration → Voyage API: creates reranker (evidence: `README.md`)
- Terminal chat → Turn event runner: streams turns (evidence: `novel_agent/chat.py`)
- Streamlit UI → Turn event runner: streams turns (evidence: `app.py`)
- Turn event runner → Reasoning graph: streams graph (evidence: `novel_agent/runner.py`)
- Reasoning graph → Agent tools: dispatches tools (evidence: `novel_agent/graph.py`)
- Agent tools → Book resources: uses book data (evidence: `novel_agent/tools.py`)
- Agent tools → Thread and profile memory: updates profile (evidence: `novel_agent/tools.py`)
- Reasoning graph → Thread and profile memory: manages thread (evidence: `novel_agent/graph.py`)
- Reasoning graph → Prompt templates: uses templates (evidence: `novel_agent/graph.py`)
- Reasoning graph → Model configuration: gets model (evidence: `novel_agent/graph.py`)
- Model configuration → Gemini API: creates chat models (evidence: `README.md`)
- Hybrid retrieval → Voyage API: reranks results (evidence: `README.md`)
- Streamlit UI → Reader: shows answers (evidence: `app.py`)
