Ordinance
Agentic research system for Hong Kong building regulations — hybrid retrieval, focused tools, and verification over 15,000+ chunks across 240 government documents.
Overview
Live at ordinance.maniksoin.com — ask it a Hong Kong building-regulation question and get a cited, faithfulness-scored answer.
Agentic research system that answers questions about Hong Kong building regulations with cited, verifiable responses. A lightweight router sends simple lookups through a fast RAG path and reserves the agent loop for multi-hop, freshness-sensitive, or project-specific questions.
Key numbers:
- 15,000+ regulation chunks across 240 documents
- 5 government departments (BD, FSD, EPD, EMSD, HA)
- 500x speedup on cached queries (8s to 15ms)
- Faithfulness scoring on every response
Technical highlights
Agent harness — A Thought-Action-Observation loop lets the model choose its next step, observe tool output, and continue until it has enough evidence. A hard step budget prevents runaway loops; citation verification and faithfulness scoring are mandatory exit gates.
Focused tool layer — Four tightly scoped, Zod-validated tools expose hybrid retrieval, live government data, exact cross-reference resolution, and citation verification. The model can retrieve again with a better query or follow a clause reference instead of betting everything on one search.
Context engineering — Progressive disclosure keeps document metadata compact, an external scratchpad tracks the current plan, and durable structured memory retains building type, storey count, and use class without replaying raw chat history.
Hybrid retrieval — Combines pgvector cosine similarity (3072-dim embeddings) with PostgreSQL full-text search. Reciprocal Rank Fusion merges both ranked lists, with optional Cohere reranking for precision.
Two-level query caching — Exact-match cache on normalized queries plus semantic cache using embedding similarity (0.95 cosine threshold). Repeated or near-identical questions resolve in ~15ms instead of the full 8s pipeline.
Structure-aware ingestion — Custom parser preserves Part > Section > Clause hierarchy from government PDFs. Chunks sized at 256-512 tokens with overlap, SHA-256 hashing for change detection across 200+ documents.
Citation-grounded generation — GPT-4o generates answers at temperature 0.1 with enforced citation format. Post-generation verification checks every cited section against retrieved context, flags phantom citations and uncited regulatory claims.
Quality assurance pipeline — LLM judge scores faithfulness 0-10 with reasoning. Citation verification, uncited claim detection, and per-query cost tracking run on every response.
Complexity routing — Most questions stay on the faster single-pass retrieval path. Multi-hop questions, live-data lookups, and context-dependent follow-ups enter the agent loop only when the extra latency and cost are justified.
Stack
TypeScript, Node.js, Express 5, PostgreSQL, pgvector, OpenAI (GPT-4o, text-embedding-3-large), Cohere Rerank, Zod, Railway