← Portfolio

DAEMON-KP

ARCH

A Django architecture template for knowledge platforms — an end-to-end RAG pipeline from source ingestion to citation-grounded answers.

Private repository · Available on request

Type Architecture template
Role Designer & sole author
Repository Private · available on request
Built on it SportsIQ
DjangoHTMXpgvectorpg_searchGemini APIPydantic AITaskiqDockerCoolify

Why It Exists

Every knowledge product faces the same structural problem: getting from raw sources to answers a user can actually trust. The pipeline sounds simple — ingest, chunk, search, answer — but the failure modes compound: hallucinated citations, keyword-only search missing semantic intent, semantic search missing exact terms. DAEMON-KP is the architecture I designed to solve that, purpose-built for knowledge-heavy products where answer quality is the product.

Pipeline

Source → Document → Chunk → Search → Answer → Citation

Each stage is a typed Pydantic boundary — a chunk that doesn't meet quality criteria never reaches the search index. An answer that can't be grounded in retrieved context is flagged, not surfaced.

StageStatus
Chunking (heading-aware, 1200 chars / 150 overlap) Complete
Lexical Search (Django FTS) Complete
Hybrid Search (45% lexical + 55% semantic) Complete
AI Answer + Citation (Gemini 2.5-flash) Complete
Semantic Search (pgvector HNSW) 60% — embedding task stub
Source Ingestion (URL/File parser) 30% — parsers.py stub

Core RAG flow (chunking → lexical search → AI answer) works out of the box.

Detailed Flow

Source
URL · File · API
↓ parse (parsers.py)
Document
title · body · slug · summary
↓ auto-chunk on save (1200 chars, 150 overlap)
Chunks
heading-aware · content_hash dedup
↓ embed → pgvector HNSW · index → pg_search BM25
Search Index
BM25 (45%) + cosine similarity (55%) → fused score
↓ top-K chunks passed to LLM
Answer
Gemini 2.5-flash · grounded generation · structured output
↓ source_ids in response
Citation
Chunk → Document · always traceable

Domain Map

Knowledge Core

sources documents chunks topics

Intelligence

search answers entities

Interaction

discussions workspace

Pipeline

ingestion

Foundation

core accounts

Key Decisions

  • Hybrid Search (BM25 + vector similarity)

    pg_search (BM25 ranking) + pgvector (semantic similarity), scores fused at query time with a 45/55 split. Handles both "what is X" and "find the document that mentions Y" — neither alone is sufficient.

  • Citation-First Answers

    Answers are generated only from retrieved chunks. Gemini receives chunk IDs directly and returns structured output with source_ids alongside the answer text — no post-hoc attribution. If context doesn't support an answer, the system says so.

  • PostgreSQL-Only (no separate vector DB)

    pgvector + pg_search inside the same PostgreSQL instance. No Pinecone, no Elasticsearch, no sync overhead. The search index is always consistent with the document store by construction.

  • Built on DAEMON-ONE

    DAEMON-KP is a domain-layer extension of DAEMON-ONE. 12 domains — documents, chunks, search, answers, sources, topics, discussions, entities, ingestion, workspace, accounts, core — each following the same Vertical Slicing and interface.py boundary rules. Drop the knowledge/ domain folder and the RAG system is gone cleanly.

Target Products

  • Sports Science Platform  · University Wiki  · Research Explorer  · Recipe Archive
  • Any product where documents are the data model and answers need to cite their sources.

Related Writing

Built On DAEMON-KP

  • → SportsIQ — Sports knowledge platform, in development

Status

Private repository. The pipeline evolves with SportsIQ as the proving ground. Available on request.