Skip to main content

HAWKI-RAG Documentation Portal

This portal is organized as a guided flow: from prerequisites to deployment, with chapter-by-chapter operational detail.

Start with Requirements

HAWKI RAG Screen

Overview​

HAWKI-RAG is a containerized, dataset-scoped retrieval-augmented generation platform that turns uploaded documents and crawled sources into grounded, searchable knowledge. Laravel provides the admin UI, canonical API, dataset management, and operational status. The Python FastAPI service owns the ML data plane, while Temporal coordinates durable scraping, conversion, ingestion, retries, cancellation, and recovery. Documents are converted to normalized Markdown and split into searchable chunks. Local Ollama creates embeddings by default, and Qdrant stores the chunk vectors and retrieval payloads. When graph ingestion is enabled, RAG-Anything coordinates the document and multimodal extraction flow, LightRAG extracts entities and relations inside that flow, and HAWKI-RAG normalizes and deduplicates the resulting dataset-scoped facts before storing them in Neo4j. At query time, Laravel supplies the caller's authorized dataset, and the Python service combines vector, lexical, and optional graph evidence. Retrieval scores are normalized across stages, duplicate chunks are removed by chunk identity, and an optional reranker orders the strongest evidence before answer generation.

Read in Order​

  • ✔️ 1. Requirements Hardware, software, ports, and platform prerequisites before you run anything. Open chapter

  • 🛠️ 2. Setup with Makefile Startup, lifecycle, health, logging, and maintenance commands with practical guidance. Open chapter

  • 🏠️ 3. Architecture Beginner-friendly explanation of the full RAG system and service interactions. Open chapter

  • 🚀 4. Installation Zero-to-running installation sequence with expected outputs and failure fixes. Open chapter

  • 💾 5. Environment, DB, Queue Complete environment variable map, migrations, and queue setup details. Open chapter

  • 👨‍🍳 6. Ingestion and Embeddings End-to-end ingest flow, chunking/embedding behavior, and monitoring. Open chapter

  • 📚️ 7. MCP Query Search Contract Authenticated input, trusted dataset scope, bridge payload, and normalized MCP output. Open chapter

  • 🗺️ 8. Repository Map Developer map from a requested change to its Laravel/Python source and tests. Open chapter

Quick Start​

make up-core
make test-services