# chadoshamot/paper-librarian architecture

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

- Interactive diagram: https://gitdiagram.com/chadoshamot/paper-librarian
- Repository: https://github.com/chadoshamot/paper-librarian

## Overview

Paper Librarian is a local AI paper-management application. Its central workflow takes a PDF through metadata extraction, full-text summarization, classification, filing, and knowledge-base indexing; users then search and open papers or maintain the library through CLI, Web, and desktop interfaces. Separate capabilities cover multi-source daily discovery and scoring, the librarian agent, and optional cloud and Zotero integration. The README documents these capabilities; sampled excerpts chiefly support the ingestion, retrieval, daily, and interface relationships, so uncertain wiring is omitted.

Main entry points: [`service/pipeline.py`](https://github.com/chadoshamot/paper-librarian/blob/main/service/pipeline.py) (Ingest pipeline), [`service/daily.py`](https://github.com/chadoshamot/paper-librarian/blob/main/service/daily.py) (Daily discovery), [`service/librarian.py`](https://github.com/chadoshamot/paper-librarian/blob/main/service/librarian.py) (Librarian agent), [`service/cli.py`](https://github.com/chadoshamot/paper-librarian/blob/main/service/cli.py) (Interactive CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Interactive CLI<br/>[cli.py]"]
  node_web["Web interface<br/>[web.py]"]
  node_desktop["Desktop shell<br/>[desktop.py]"]
end

subgraph group_library["Paper library"]
  node_ingest["Ingest entry<br/>[ingest.py]"]
  node_pipeline["Ingest pipeline<br/>[pipeline.py]"]
  node_metadata["Metadata extraction<br/>[metadata.py]"]
  node_pdftext["PDF text<br/>[pdftext.py]"]
  node_classifier["Classification<br/>[classifier.py]"]
  node_manifest[("Paper manifest<br/>[manifest.py]")]
  node_kb[("Bilingual knowledge base<br/>[retrieval.py]")]
  node_readstate[("Read state<br/>[read_state.py]")]
end

subgraph group_discovery["Search and discovery"]
  node_search["Search and retrieval<br/>[retrieval.py]"]
  node_daily["Daily discovery<br/>[daily.py]"]
  node_dedup["Duplicate detection<br/>[dedup.py]"]
end

subgraph group_agent["Librarian agent"]
  node_librarian["Librarian agent<br/>[librarian.py]"]
end

subgraph group_integrations["External integrations"]
  node_llm["LLM client<br/>[llm.py]"]
  node_cloud["Cloud synchronization<br/>[cloud.py]"]
  node_zotero["Zotero client<br/>[zotero_client.py]"]
  node_chat["Web search chat<br/>[chat.py]"]
end

node_user(("Paper manager"))
node_modelscope[("ModelScope storage")]
node_zotero_service[("Zotero service")]
node_paper_sources(("Paper sources"))
node_kimi["Kimi search"]

node_user -->|"uses"| node_cli
node_user -->|"uses"| node_web
node_user -->|"opens"| node_desktop
node_desktop -->|"hosts"| node_web
node_user -->|"submits PDF"| node_ingest
node_ingest -->|"runs"| node_pipeline
node_pipeline -->|"extracts metadata"| node_metadata
node_pipeline -->|"reads PDF"| node_pdftext
node_pipeline -->|"classifies"| node_classifier
node_pipeline -->|"summarizes with"| node_llm
node_pipeline -->|"updates"| node_manifest
node_pipeline -->|"writes card"| node_kb
node_pipeline -.->|"creates item"| node_zotero
node_zotero -.->|"updates"| node_zotero_service
node_cli -->|"searches"| node_search
node_web -->|"searches"| node_search
node_search -->|"reads documents"| node_kb
node_search -->|"reads status"| node_readstate
node_cli -->|"marks read"| node_readstate
node_cli -->|"runs discovery"| node_daily
node_web -->|"runs discovery"| node_daily
node_daily -->|"fetches candidates"| node_paper_sources
node_daily -->|"filters known papers"| node_manifest
node_daily -->|"judges candidates"| node_llm
node_cli -->|"checks duplicates"| node_dedup
node_librarian -->|"searches library"| node_search
node_librarian -->|"maintains papers"| node_pipeline
node_librarian -->|"runs retrieval"| node_daily
node_librarian -->|"requests sync"| node_cloud
node_librarian -.->|"requests web search"| node_chat
node_chat -.->|"searches web"| node_kimi
node_cloud -.->|"syncs library"| node_modelscope
node_pipeline -.->|"syncs changes"| node_cloud

click node_cli "https://github.com/chadoshamot/paper-librarian/blob/main/service/cli.py"
click node_web "https://github.com/chadoshamot/paper-librarian/blob/main/service/web.py"
click node_desktop "https://github.com/chadoshamot/paper-librarian/blob/main/service/desktop.py"
click node_ingest "https://github.com/chadoshamot/paper-librarian/blob/main/service/ingest.py"
click node_pipeline "https://github.com/chadoshamot/paper-librarian/blob/main/service/pipeline.py"
click node_metadata "https://github.com/chadoshamot/paper-librarian/blob/main/service/metadata.py"
click node_pdftext "https://github.com/chadoshamot/paper-librarian/blob/main/service/pdftext.py"
click node_classifier "https://github.com/chadoshamot/paper-librarian/blob/main/service/classifier.py"
click node_manifest "https://github.com/chadoshamot/paper-librarian/blob/main/service/manifest.py"
click node_kb "https://github.com/chadoshamot/paper-librarian/blob/main/service/retrieval.py"
click node_readstate "https://github.com/chadoshamot/paper-librarian/blob/main/service/read_state.py"
click node_search "https://github.com/chadoshamot/paper-librarian/blob/main/service/retrieval.py"
click node_daily "https://github.com/chadoshamot/paper-librarian/blob/main/service/daily.py"
click node_dedup "https://github.com/chadoshamot/paper-librarian/blob/main/service/dedup.py"
click node_librarian "https://github.com/chadoshamot/paper-librarian/blob/main/service/librarian.py"
click node_llm "https://github.com/chadoshamot/paper-librarian/blob/main/service/llm.py"
click node_cloud "https://github.com/chadoshamot/paper-librarian/blob/main/service/cloud.py"
click node_zotero "https://github.com/chadoshamot/paper-librarian/blob/main/service/zotero_client.py"
click node_chat "https://github.com/chadoshamot/paper-librarian/blob/main/service/chat.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_web,node_desktop toneBlue
class node_ingest,node_pipeline,node_metadata,node_pdftext,node_classifier,node_manifest,node_kb,node_readstate,node_modelscope,node_zotero_service toneAmber
class node_search,node_daily,node_dedup toneMint
class node_librarian toneRose
class node_llm,node_cloud,node_zotero,node_chat,node_user,node_paper_sources,node_kimi toneIndigo
```

## Components

### User interfaces

- [Interactive CLI](https://github.com/chadoshamot/paper-librarian/blob/main/service/cli.py): `service/cli.py`
- [Web interface](https://github.com/chadoshamot/paper-librarian/blob/main/service/web.py): `service/web.py`
- [Desktop shell](https://github.com/chadoshamot/paper-librarian/blob/main/service/desktop.py): `service/desktop.py`

### Paper library

- [Ingest entry](https://github.com/chadoshamot/paper-librarian/blob/main/service/ingest.py): `service/ingest.py`
- [Ingest pipeline](https://github.com/chadoshamot/paper-librarian/blob/main/service/pipeline.py): `service/pipeline.py`
- [Metadata extraction](https://github.com/chadoshamot/paper-librarian/blob/main/service/metadata.py): `service/metadata.py`
- [PDF text](https://github.com/chadoshamot/paper-librarian/blob/main/service/pdftext.py): `service/pdftext.py`
- [Classification](https://github.com/chadoshamot/paper-librarian/blob/main/service/classifier.py): `service/classifier.py`
- [Paper manifest](https://github.com/chadoshamot/paper-librarian/blob/main/service/manifest.py): `service/manifest.py`
- [Bilingual knowledge base](https://github.com/chadoshamot/paper-librarian/blob/main/service/retrieval.py): `service/retrieval.py`
- [Read state](https://github.com/chadoshamot/paper-librarian/blob/main/service/read_state.py): `service/read_state.py`

### Search and discovery

- [Search and retrieval](https://github.com/chadoshamot/paper-librarian/blob/main/service/retrieval.py): `service/retrieval.py`
- [Daily discovery](https://github.com/chadoshamot/paper-librarian/blob/main/service/daily.py): `service/daily.py`
- [Duplicate detection](https://github.com/chadoshamot/paper-librarian/blob/main/service/dedup.py): `service/dedup.py`

### Librarian agent

- [Librarian agent](https://github.com/chadoshamot/paper-librarian/blob/main/service/librarian.py): `service/librarian.py`

### External integrations

- [LLM client](https://github.com/chadoshamot/paper-librarian/blob/main/service/llm.py): `service/llm.py`
- [Cloud synchronization](https://github.com/chadoshamot/paper-librarian/blob/main/service/cloud.py): `service/cloud.py`
- [Zotero client](https://github.com/chadoshamot/paper-librarian/blob/main/service/zotero_client.py): `service/zotero_client.py`
- [Web search chat](https://github.com/chadoshamot/paper-librarian/blob/main/service/chat.py): `service/chat.py`

### Other components

- **Paper manager**
- **ModelScope storage**
- **Zotero service**
- **Paper sources**
- **Kimi search**

## Connections

- Paper manager → Interactive CLI: uses
- Paper manager → Web interface: uses
- Paper manager → Desktop shell: opens
- Desktop shell → Web interface: hosts
- Paper manager → Ingest entry: submits PDF
- Ingest entry → Ingest pipeline: runs
- Ingest pipeline → Metadata extraction: extracts metadata
- Ingest pipeline → PDF text: reads PDF
- Ingest pipeline → Classification: classifies
- Ingest pipeline → LLM client: summarizes with
- Ingest pipeline → Paper manifest: updates
- Ingest pipeline → Bilingual knowledge base: writes card
- Ingest pipeline → Zotero client: creates item
- Zotero client → Zotero service: updates
- Interactive CLI → Search and retrieval: searches
- Web interface → Search and retrieval: searches
- Search and retrieval → Bilingual knowledge base: reads documents
- Search and retrieval → Read state: reads status
- Interactive CLI → Read state: marks read
- Interactive CLI → Daily discovery: runs discovery
- Web interface → Daily discovery: runs discovery
- Daily discovery → Paper sources: fetches candidates
- Daily discovery → Paper manifest: filters known papers
- Daily discovery → LLM client: judges candidates
- Interactive CLI → Duplicate detection: checks duplicates
- Librarian agent → Search and retrieval: searches library
- Librarian agent → Ingest pipeline: maintains papers
- Librarian agent → Daily discovery: runs retrieval
- Librarian agent → Cloud synchronization: requests sync
- Librarian agent → Web search chat: requests web search
- Web search chat → Kimi search: searches web
- Cloud synchronization → ModelScope storage: syncs library
- Ingest pipeline → Cloud synchronization: syncs changes