# Ordinance

> Agentic research system for Hong Kong building regulations — hybrid retrieval, focused tools, and verification over 15,000+ chunks across 240 government documents.

URL: https://maniksoin.com/projects/ordinance/
Live: https://ordinance.maniksoin.com/
Source: https://github.com/manik-soin/ordinance
Tags: TypeScript, Agents, RAG, LLM Evals, PostgreSQL, pgvector, OpenAI, Cohere

## Overview

**Live at [ordinance.maniksoin.com](https://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

## Read the engineering notes

- [How I built the original hybrid RAG pipeline](/blog/building-rag-for-hk-regulations)
- [Why I rebuilt the complex-query path as an agent](/blog/from-rag-to-agent-harnessing-ordinance)