How cinnamon/kotaemon works
Purpose and entry points
Kotaemon is a Python 3.10+ document-question-answering platform: a Gradio RAG UI plus reusable kotaemon framework library. Runtime starts at app.py, which hosts the application assembled in libs/ktem/ktem/main.py and libs/ktem/ktem/app.py. sso_app.py is a separate SSO-oriented launch path. Deployment supports local scripts, Docker, and Fly.io (Dockerfile, fly.toml).
Two-layer architecture
• Framework layer (kotaemon) provides composable abstractions for components, schemas, LLMs, embeddings, loaders, indexing, retrieval, storage, and agents. Core contracts live in libs/kotaemon/kotaemon/base/component.py and libs/kotaemon/kotaemon/base/schema.py.
• Application layer (ktem) wires those capabilities into persistent configuration, user-facing resource management, indexing, reasoning pipelines, and Gradio pages. Its extension seam is libs/ktem/ktem/extension_protocol.py; app-wide customization is centered on flowsettings.py.
Application state, users, and managed resources
The application persists users, conversations, configured models, index metadata, and MCP configuration through its database layer: libs/ktem/ktem/db/engine.py, libs/ktem/ktem/db/models.py, and Alembic assets under libs/ktem/migrations/. Data defaults to ktem_app_data at runtime. Resource managers expose database-configured LLM, embedding, reranking, and MCP providers to UI and pipelines: libs/ktem/ktem/llms/manager.py, libs/ktem/ktem/embeddings/manager.py, libs/ktem/ktem/mcp/manager.py.
Document ingestion and indexing
File indexing begins with file-index orchestration in libs/ktem/ktem/index/file/index.py and pipelines in libs/ktem/ktem/index/file/pipelines.py. It delegates parsing/loading to pluggable loaders, including PDFs, Office documents, web sources, OCR, and multimodal services (libs/kotaemon/kotaemon/loaders/pdf_loader.py, libs/kotaemon/kotaemon/loaders/docling_loader.py, libs/kotaemon/kotaemon/loaders/azureai_document_intelligence_loader.py). Parsed documents are split, embedded, and written through the vector-index abstraction (libs/kotaemon/kotaemon/indices/vectorindex.py) into selected document/vector stores.
Retrieval and persistence boundary
The standard RAG path combines document/full-text and vector retrieval, optionally reranks results, then formats context and citations before generation. Storage adapters isolate backing services: document stores support Elasticsearch, LanceDB, file, and memory (libs/kotaemon/kotaemon/storages/docstores/elasticsearch.py, libs/kotaemon/kotaemon/storages/docstores/lancedb.py); vector stores support Chroma, LanceDB, Milvus, Qdrant, file, and memory (libs/kotaemon/kotaemon/storages/vectorstores/qdrant.py, libs/kotaemon/kotaemon/storages/vectorstores/chroma.py). Citation QA is implemented in libs/kotaemon/kotaemon/indices/qa/citation_qa.py.
Reasoning and generation
UI-selected reasoning pipelines control query execution: basic and decomposition QA, ReAct, and ReWOO reside in libs/ktem/ktem/reasoning/simple.py, libs/ktem/ktem/reasoning/react.py, and libs/ktem/ktem/reasoning/rewoo.py. Agent implementations can invoke LLM, Google, Wikipedia, or MCP tools (libs/kotaemon/kotaemon/agents/react/agent.py, libs/kotaemon/kotaemon/agents/tools/mcp.py). Model adapters isolate OpenAI-compatible endpoints, LangChain-backed models, and local llama.cpp (libs/kotaemon/kotaemon/llms/chats/openai.py, libs/kotaemon/kotaemon/llms/chats/llamacpp.py).
UI and advanced index modes
Gradio pages provide chat, login, setup, resources, and settings; chat composition is concentrated in libs/ktem/ktem/pages/chat/chat_panel.py, while resource and settings flows are in libs/ktem/ktem/pages/settings.py. File indexing can switch to GraphRAG-family strategies—native graph, LightRAG, NanoGraphRAG, or KNet—behind dedicated pipelines (libs/ktem/ktem/index/file/graph/graph_index.py, libs/ktem/ktem/index/file/graph/lightrag_pipelines.py, libs/ktem/ktem/index/file/knet/knet_index.py). Optional external services include OpenAI/Azure OpenAI, Ollama, Cohere, VoyageAI, Adobe, Azure Document Intelligence, and MCP servers.
Main entry points: main.py App assembly · chat_panel.py Chat UI · app.py Gradio application · manager.py Resource managers
Components 21
Runtime & UI
- Application launch
app.py - SSO launch
sso_app.py - Chat UI
libs/ktem/ktem/pages/chat/chat_panel.py - Resources & settings
libs/ktem/ktem/pages/settings.py
ktem Application
- App assembly
libs/ktem/ktem/main.py - Gradio application
libs/ktem/ktem/app.py - Extension protocol
libs/ktem/ktem/extension_protocol.py - Resource managers · Exposes database-configured LLM, embedding, reranking, and MCP providers.
libs/ktem/ktem/llms/manager.py - File indexing
libs/ktem/ktem/index/file/index.py - Index pipelines
libs/ktem/ktem/index/file/pipelines.py - Graph index modes · Supports native graph, LightRAG, NanoGraphRAG, and KNet modes.
libs/ktem/ktem/index/file/graph/graph_index.py - Reasoning pipelines · Selects basic, decomposition, ReAct, or ReWOO execution.
libs/ktem/ktem/reasoning/simple.py
kotaemon Framework
- Core contracts
libs/kotaemon/kotaemon/base/component.py - Document loaders · Handles PDF, Office, web, OCR, and multimodal sources.
libs/kotaemon/kotaemon/loaders/pdf_loader.py - Vector index · Splits, embeds, and writes parsed documents.
libs/kotaemon/kotaemon/indices/vectorindex.py - Citation QA · Combines retrieval, reranking, context formatting, citations, and generation.
libs/kotaemon/kotaemon/indices/qa/citation_qa.py - Tool agents · Can call LLM, web, Wikipedia, and MCP tools.
libs/kotaemon/kotaemon/agents/react/agent.py - LLM adapters · Supports OpenAI-compatible, LangChain, and llama.cpp models.
libs/kotaemon/kotaemon/llms/chats/openai.py
Persistence
- App database · Persists users, conversations, configured resources, indexes, and MCP settings.
libs/ktem/ktem/db/engine.py - Database models
libs/ktem/ktem/db/models.py - Document & vector stores · Isolates Elasticsearch, LanceDB, Chroma, Qdrant, file, memory, and Milvus backends.
libs/kotaemon/kotaemon/storages/vectorstores/qdrant.py
Connections 24
- Application launch → App assembly: starts
- SSO launch → App assembly: starts
- App assembly → Gradio application: builds
- Gradio application → Chat UI: hosts
- Gradio application → Resources & settings: hosts
- App assembly → Extension protocol: customizes via
- Resources & settings → Resource managers: configures
- Resource managers → App database: loads configuration
- App database → Database models: uses
- Chat UI → Reasoning pipelines: selects
- Chat UI → File indexing: submits files
- File indexing → Index pipelines: runs
- Index pipelines → Document loaders: parses with
- Index pipelines → Vector index: indexes
- File indexing → Graph index modes: can switch to
- Vector index → Document & vector stores: writes to
- Reasoning pipelines → Citation QA: executes RAG
- Reasoning pipelines → Tool agents: uses for tool flows
- Citation QA → Document & vector stores: retrieves from
- Citation QA → LLM adapters: generates with
- Tool agents → LLM adapters: calls
- Resource managers → LLM adapters: provisions
- Document loaders → Core contracts: implements
- Vector index → Core contracts: implements