Project Overview

Aceh Agentic RAG + OCR is the backend for a self-hosted government document intelligence platform. It serves internal Pemprov Aceh users, retrieves from the government sources with a required indexing capacity of 100,000+ documents, answers in Bahasa Indonesia and English, and is designed to keep document storage, inference, retrieval, prompt management, and observability inside client-controlled Huawei Cloud.

Platform boundary

The current service is API-first. FastAPI exposes HTTP JSON routes and Server-Sent Events (SSE) for query, search, ingestion, OCR, document lifecycle, conversations, memory, model primitives, and direct generation. Kafka/DMS consumer and stage-status publisher follow the partner event contract. frontend/ is the explicit interim-client exception: it currently delivers Pustaka Aceh plus the bounded internal query-trend dashboard while the partner frontend is late (ADR-0015).

Primary users and sources

The platform is designed for 10–50 internal concurrent users. Supported source types are JDIH, OpenData, PPID, SatuData, and upload. JDIH and PPID documents follow the parse → OCR fallback → chunk → embed → index path. Structured OpenData and SatuData records are query-time tool sources and are skipped before embedding so a stale indexed copy cannot compete with the live value.

Implemented capabilities

Capability	Current behavior
Multi-format ingestion	Upload, inline text, object-storage batch, and allow-listed URL intake share validation, storage, parsing, OCR, chunking, and indexing rules. Kafka/DMS ingestion follows the partner event contract.
OCR and review gates	POST /ocr provides extraction-only inspection. Ingestion records OCR confidence, excludes low-signal or below-threshold chunks from retrieval, and can route a document to needs_review; document-level review uses a failed-page fraction and always reviews lost pages.
Hybrid retrieval	Semantic pgvector HNSW and PostgreSQL full-text search are fused with RRF, then reranked with bge-reranker-v2-m3.
Agentic RAG	/query runs Router → Planner → Executor → Synthesizer. Vector Search is the default; Legal Check, Summarizer, Cross-Reference, Excel Query, Open Data, and BPS Statistics are registered when their seams are available. SQL Query is registered only when a structured SQL source is configured.
Grounded answers	/query and /query/stream return or reveal source citations only after faithfulness and Government Policy Guard checks.
Conversations and memory	Conversation creation, ownership-scoped history, session resume, memory listing/deletion, forget-me deletion, and nightly consolidation are implemented.
Model surfaces	/embeddings and /rerank expose bounded primitives; /generate is an authenticated raw, explicitly ungrounded model call; /models reports configured model ids.
Evaluation	The Golden dataset seed currently has 86 Bahasa Indonesia cases across JDIH, PPID, OpenData, SatuData, and OCR fixtures. Retrieval, answer, citation, OCR, policy, and per-source evaluation commands are available through make.

Current status

origin/main contains the working API, ingestion worker, Agentic RAG orchestrator, local Compose stack, evaluation runners, and deployment automation. Production serves deployed ref 2cc9a417 (2026-10-07) on apps-0002 with the client frontend at https://rag-aceh-neo.reviewstagepro.com (Studio at /studio); the former review-staging hosts are torn down (firstmate production audit 2026-10-07). The public API origin is documented in the API overview.

Several capabilities are intentionally configuration-gated:

• URL ingestion is disabled until an allow-list and operator approval are set.
• Query-time OpenData, SatuData, and BPS reads are disabled by default and require their own egress allow-lists; BPS also requires an application key.
• SQL Query is absent from the Planner until a read-only structured source is configured.
• The local A30 profile serves Qwen3-14B-AWQ, BGE-M3 (1024 dimensions), bge-reranker-v2-m3, and PaddleOCR-VL-0.9B.

See the audited production snapshot for the deployed ref, runtime settings, corpus inventory, and pending deployments.

System spine

API clients
  -> FastAPI HTTP/SSE or Kafka/DMS boundary
  -> ingestion worker or Router -> Planner -> Executor -> Synthesizer
  -> PostgreSQL + pgvector + full-text search
  -> configured model endpoints through LiteLLM
  -> Langfuse prompts/traces and append-only audit records

Non-negotiable constraints

• Data and inference stay inside Huawei Cloud for delivered operation; external LLM egress is guarded and disabled for staging/production.
• Delivered dependencies are OSI-licensed open source.
• Retrieval is hybrid by default; semantic-only retrieval is not acceptable.
• Every generated answer needs source citations and faithfulness gating.
• OCR confidence and low-signal gates prevent untrusted text from entering the searchable index.
• The Government Policy Guard wraps every /query and /query/stream answer; raw /generate is the explicit exception.