Allan Simões AdegasPortuguês
Menu
Back to home

KnowledgeDesk

Open source

An internal knowledge assistant that runs 100% locally: a company chats with its own documents without any data leaving the machine.

Role
Author
Started
2026
localhost · no data leaves the machinemanual.pdf · policies.docxKnowledgeDesksource: manual.pdf, p. 12Ask about the documents…
Project illustration
100%
local, no external API
42
commits, with CI
3
test layers (pytest, Vitest, Playwright)

Overview

Many companies can't send internal documents to an external API. KnowledgeDesk uses local models through Ollama: upload PDFs, DOCX and TXT, chat with RAG, and get answers with cited sources.

Beyond chat, a LangGraph agent lists, searches and summarizes documents within explicit safety limits.

What it does

RAG with cited sources
Ingestion with chunking and embeddings into ChromaDB, retrieval with a relevance filter and streamed answers.
An agent with limits
A clarify → plan → execute_tools → respond state machine, with read-only tools and a capped number of iterations.
Conversation history
Sessions persisted in SQLite while the answer streams.

Architecture

Architecture: KnowledgeDeskReact + Vite → FastAPI. FastAPI → ChromaDB. FastAPI → SQLite. ChromaDB → Ollama. LangGraph → Ollama. SQLite → LangGraphLocal machineHTTP / SSEReact + Vitechat and uploadFastAPISSE streamingOllamaLLM and embeddingsChromaDBvectorsSQLitesessionsLangGraphread-only agent
Everything runs on the company's machine.

Decisions and trade-offs

Two stores, on purpose
Conversations are simple relational data (SQLite); documents need vector search (ChromaDB). Forcing both into one store would mix two access patterns.
SSE instead of WebSockets
The flow is one-way. Server-Sent Events work with fetch and ReadableStream, without managing a bidirectional connection.
Deterministic routing
Request intent is classified by rules, not by an LLM, to keep tests deterministic. The model is used only where it's needed: summarizing.

Quality and operations

  • Specification before code (Spec Driven Development).
  • The Ollama client is injected throughout the backend, so 100% of automated tests can mock it.
  • Playwright E2E tests against the real stack; CI with lint, tests and build.

Status and next steps

  • Record a video demo and publish a ready-to-run Docker image.

Stack

PythonFastAPILangChainLangGraphChromaDBSQLiteOllamaReactTypeScriptPlaywright