How It Works

KaaS uses a compile-then-retrieve architecture. Instead of chunking raw text into a vector store (the typical RAG approach), it compiles your content through an LLM pipeline into structured, human-readable Markdown articles — then retrieves from those at query time.

The Two Phases

Phase 1: Compile

When you submit content (paste text, upload a file, or provide a URL), it enters a 4-stage pipeline:

Raw Content → Extract → Classify → Write → Index → Structured Wiki

Each stage is an LLM call that transforms the material further:

Stage	What it does
Extract	Pulls out concepts, entities, decisions, and action items from raw text
Classify	Maps extracted items to existing wiki articles or marks them for creation
Write	Creates new articles or merges into existing ones (Markdown output)
Index	Updates the master-index and topic-indexes for retrieval navigation

The result is a set of interlinked Markdown files — readable by humans, manageable with git, and structured for LLM retrieval.

Phase 2: Retrieve

When you ask a question, KaaS uses LLM-iterative retrieval (no embeddings, no vector database):

1. Feed the master-index.md to the LLM as a navigation catalog
2. The LLM selects the most relevant wiki pages
3. Read those pages in full and feed them as context
4. Generate a cited answer via SSE streaming

This approach eliminates the noise of chunk-based retrieval — the LLM reads complete, well-structured articles rather than arbitrary text fragments.

Why Compile First?

Compile-then-retrieve	Chunk-and-embed (naive RAG)
Structured, deduplicated articles	Raw chunks with redundancy
Human-readable output you can edit	Opaque vector store
LLM navigates a curated index	Similarity search on noisy embeddings
Context is a complete article	Context is a 512-token fragment
Zero embedding dependencies	Requires embedding model + vector DB

Worker Acceleration

The compile phase is parallelized by a Go Worker Pool that manages concurrency, fault tolerance, and incremental processing:

Key mechanisms:

• Dispatcher — semaphore-based concurrency control; per-user goroutine limit
• Extract Worker Pool — multiple parallel workers for the Extract stage (configurable via extract_workers)
• Pipeline Worker — batches Classify/Write/Index per user
• Circuit Breaker — halts LLM calls after N consecutive failures; auto-recovers via half-open probe after cooldown
• Lease + Heartbeat — prevents duplicate processing; recovers orphaned tasks after crashes

See Compile Pipeline for a detailed breakdown of each stage.