LLM Extraction & Synthesis Integration
Relevant source files
The following files were used as context for generating this wiki page:
The LLM Extraction & Synthesis Integration is the core intelligence engine of Archivum. It enables the system to transform raw, unstructured data—such as PDFs, text files, and URLs—into a structured, interlinked knowledge base. The integration serves two primary purposes: Extraction, where a specialized "Wiki Agent" parses documents into Markdown pages, entities, and relationships; and Synthesis, where the system answers natural language queries by synthesizing information from retrieved context across the wiki.
Sources: archivum-prd-v1.0.md:14-18, apps/backend/archivum/ingest/agent.py:1-6
Architecture and Provider Integration
Archivum utilizes a multi-provider strategy to interface with Large Language Models (LLMs). The system is designed to be provider-agnostic, supporting high-performance hosted models as well as local, air-gapped alternatives.
Supported Providers
The system implements specialized clients for different LLM backends:
| Provider | Description | Core Implementation File |
|---|---|---|
| Anthropic | Default provider for high-quality extraction and synthesis using Claude models. | apps/backend/archivum/ingest/agent.py |
| OpenRouter | Aggregator service providing access to various models (e.g., Mistral, GPT). | apps/backend/archivum/llm/openrouter_client.py |
| OpenAI Compatible | Generic client for any OpenAI-spec API, including Together, Fireworks, and local instances. | apps/backend/archivum/llm/openai_compat_client.py |
| Ollama | Local LLM provider for fully private, air-gapped operations. | README.md, apps/backend/archivum/ingest/agent.py |
Sources: apps/backend/archivum/ingest/agent.py:100-112, README.md:148-154, apps/backend/archivum/llm/openai_compat_client.py:1-5
Provider Selection Logic
The WikiAgent and MCP query tools determine which client to invoke based on environment configuration (LLM_EXTRACTION_PROVIDER and LLM_SYNTHESIS_PROVIDER).
The diagram shows the decision flow for selecting an LLM client based on system settings.
Sources: apps/backend/archivum/ingest/agent.py:100-112, apps/backend/archivum/mcp/server.py:230-245
Wiki Agent: Extraction Pipeline
The WikiAgent is responsible for the "Ingest" epic. It processes ParsedDoc objects to generate structured ExtractionResult data.
Extraction Logic
The agent uses a rigorous system prompt (WIKI_SYSTEM_PROMPT) to instruct the LLM to identify main topics, extract named entities (people, concepts, orgs), and define relationships. It enforces a strict JSON return format to ensure reliability.
Key Data Structures:
- WikiPage: Contains the kebab-case slug, title, Markdown content, and tags.
- ExtractionResult: A container for a list of
WikiPageobjects, extracted entities, and relationships.
Sources: apps/backend/archivum/ingest/agent.py:19-72
Processing Flow
- Truncation: Documents exceeding 12,000 characters are truncated to maintain token efficiency.
- Prompting: The system prompt is combined with source metadata (URLs, titles) and the document text.
- LLM Call: The agent invokes the configured provider (e.g., using
claude-haikuwith prompt caching viacache_control: {"type": "ephemeral"}). - Parsing & Cleanup: The agent strips Markdown code fences from the LLM response and validates the JSON structure.
- Fallback: If the LLM fails or returns invalid data, a
_fallback_extractionmethod generates a basic page and extracts entities using regex-based proper noun detection.
Sources: apps/backend/archivum/ingest/agent.py:114-160, apps/backend/archivum/ingest/agent.py:270-305
Query Synthesis Engine
The synthesis integration allows users to ask questions against the accumulated wiki knowledge via the query tool.
RAG (Retrieval-Augmented Generation) Workflow
The synthesis process follows a classic RAG pattern combined with multi-hop graph retrieval:
- Semantic Retrieval: Queries the Qdrant vector database for the top 6 relevant snippets.
- Context Construction: Aggregates excerpts and maps them to their respective wiki pages/slugs.
- Synthesis Prompt: Constructs a prompt instructing the LLM to answer using ONLY the provided context snippets.
- Citations: Returns the generated answer along with a list of citations (titles and slugs) derived from the source pages.
The sequence diagram illustrates the data flow from an initial user question to the final synthesized response with citations.
Sources: apps/backend/archivum/mcp/server.py:207-268
Configuration and Implementation Details
The integration is controlled through specific environment variables that define model names and provider endpoints.
LLM Integration Configuration
| Variable | Default | Description |
|---|---|---|
LLM_MODEL | claude-haiku-... | Used for entity/relationship extraction. |
LLM_SYNTHESIS_MODEL | claude-sonnet-... | Used for generating cited answers. |
LLM_EXTRACTION_PROVIDER | anthropic | Backend for the WikiAgent. |
LLM_SYNTHESIS_PROVIDER | anthropic | Backend for the query tool. |
Sources: README.md:143-154
Extraction System Prompt Implementation
The system prompt is a critical architectural component that ensures the LLM acts as a structured "wiki agent."
# From apps/backend/archivum/ingest/agent.py:21-39
WIKI_SYSTEM_PROMPT = """\
You are a wiki agent that extracts structured knowledge from documents and writes \
clean Markdown wiki pages.
Given a document, you must:
1. Identify the main topic and write a comprehensive wiki page for it
2. Extract named entities (people, concepts, organizations, technologies, places)
3. Identify relationships between entities
4. Write factual, encyclopedic content — no meta-commentary
...
Rules:
- slug must be kebab-case (lowercase, hyphens only, no special chars)
- content must be valid Markdown with YAML frontmatter
- Use [[Entity Name]] wikilink syntax for all named entities
"""
Sources: apps/backend/archivum/ingest/agent.py:21-48
Conclusion
The LLM Extraction & Synthesis Integration provides Archivum with its "self-writing" capabilities. By offloading document parsing, entity linking, and knowledge synthesis to advanced LLMs while maintaining a local-first, provider-agnostic architecture, the system ensures that user knowledge compounds over time without manual bookkeeping overhead.
Sources: archivum-prd-v1.0.md:14-25, README.md:3-8