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 planned 100,000+ document corpus, 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 code exists, but live partner upload handoff is blocked pending reconciliation of the partner's doc.uploaded payload with the consumer contract. This repository does not deliver a chatbot or dashboard frontend.

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 consumer code follows the same pipeline, but live partner events are blocked pending doc.uploaded contract reconciliation.
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 guarded but explicitly ungrounded; /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. Review staging is a non-production, single-host environment; its public API origin is documented in the API overview. The production Huawei Cloud topology and acceptance benchmark remain deployment and validation work, not a claim that production is served by this repository.

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 default A30 staging profile serves Qwen3-14B-AWQ, BGE-M3 (1024 dimensions), bge-reranker-v2-m3, and PaddleOCR-VL-0.9B. Qwen3.8-27B is the production LLM target, not the staging default.

Production serves Qwen3.8-27B FP16 with tensor parallelism (TP=2) across 2x NVIDIA A100 40GB cards. Its ~54 GB of weights are split at ~27 GB per card, giving 80 GB aggregate VRAM and roughly ~22 GB aggregate for KV cache. Huawei's published P3/P3snl A100-40GB line removes the former 80 GB-card availability risk; residual risk is quota and lead time for 2x A100 40GB in ap-southeast-4 (Jakarta) plus confirmation of an NVLink-connected pair. PCIe-only pairing adds token-latency overhead.

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 generated answer.