Open Source · Governed Agentic RAG
Your agent should never invent a field that doesn't exist.
AK-RAG is a reference architecture that turns enterprise attribute metadata into an AI-searchable knowledge layer — translating natural language into governed attributes with lower hallucination risk and a clear path to ask for clarification instead of guessing.
The Problem
Business language never matches enterprise metadata
Analysts describe what they want in plain English. Your data model has none of those words in it — and an agent that free-generates a filter is a compliance risk, not a convenience.
User:
"Diabetic patients with high HbA1c who were readmitted in the last 30 days"
System:
"high HbA1c" may map to one of two governed thresholds — > 8.0% or > 9.0%. Which should be used?
Vague quantifiers everywhere
"High", "recent", "active", "elderly" — every one hides a threshold decision the system has no right to guess at.
Free-form generation invents fields
An LLM asked to emit a filter directly can fabricate a field name or threshold that simply does not exist in your data model.
Regulated fields need governance
PHI, KYC, and other governed attributes carry consent, access-channel, and minimum-cohort-size rules that must be enforced before any output.
The Pattern
How It Works
One pipeline: parse → retrieve → classify → clarify → govern → emit DSL. AK-RAG demos it on healthcare, but nothing in the pipeline is healthcare-specific.
Step 1: Catalog your governed attributes
Author attributes in Excel or CSV — business name, technical field, synonyms, allowed values, and governance metadata. One attribute becomes one NDJSON document, embedded and indexed.
Step 2: LLM extracts attribute phrases
The model's only job is to split the natural-language request into individual attribute phrases — nothing else. It never writes the final query.
Step 3: Hybrid retrieval, per phrase
BM25 keyword search and kNN vector search run for each phrase independently, fused with Reciprocal Rank Fusion — more stable than comparing raw scores.
Step 4: Classify: exact, near, ambiguous, or none
Every phrase is scored against fixed confidence thresholds. Only an exact match is used automatically.
Step 5: Clarify instead of guessing
Near, ambiguous, or unmatched phrases trigger a clarifying question with real governed options — the system never assumes a threshold.
Step 6: Emit a governed DSL
The final filter can only contain attribute_ids that exist in the catalog and pass PHI, consent, and minimum-cell-size checks — never a hallucinated field.
Why It Works
Governance Built Into the Pipeline, Not Bolted On
AK-RAG is designed for teams that need agentic natural-language access without giving up control over what an agent is allowed to say.
Domain-Agnostic Pattern
The healthcare demo is one instance. Swap the attribute catalog and the same pipeline works for banking, insurance, retail, or any governed metadata set.
Hallucination Mitigation
Retrieval happens one attribute phrase at a time, and the DSL is assembled only from selected, real attribute_ids — never free-form model text.
Governance Layer
Every attribute carries PHI/PII flags, HIPAA or compliance category, consent requirements, allowed channels, and minimum cell size — enforced before output.
Pluggable Providers
LLM (Claude, OpenAI, Bedrock, Ollama), embedding (sentence-transformers, OpenAI, Gemini, Bedrock), and search (local, OpenSearch, FAISS, Chroma) — swap via env vars.
Versioned, Idempotent Ingestion
Every metadata release builds a new versioned index, runs smoke tests, then atomically swaps the serving alias — with instant rollback if validation fails.
Hybrid Search, Fused by Rank
BM25 lexical matching plus kNN semantic similarity, combined with Reciprocal Rank Fusion — more stable than averaging incompatible score scales.
Explainable by Design
Every generated filter preserves the source phrase, confidence signal, and matched attribute metadata — fully auditable, nothing implicit.
Apache 2.0 Licensed
Fully open source and free to adapt to your own attribute catalog and industry — no attribution requirement beyond the license terms.
Beyond Healthcare
One Pattern, Any Regulated Attribute Catalog
Nothing about parse → retrieve → classify → clarify → govern → emit DSL is healthcare-specific. Any industry with a governed set of enterprise attributes can plug in its own catalog.
User:
"Retail customers with high credit utilization and a recent late payment"
System:
"high credit utilization" may map to Credit Utilization Ratio > 30% (elevated) or > 50% (high risk). "recent late payment" — did you mean the last 30, 60, or 90 days?
Banking & Insurance
KYC risk tiers, credit thresholds, AML flags, policy terms, and underwriting factors — governed the same way as PHI.
Retail, CDP & Cybersecurity
Customer segments and loyalty tiers, audience-building attributes, and asset risk or entitlement classifications.
HR, Supply Chain & Data Catalogs
Compensation bands and role classifications, supplier risk and inventory thresholds, or general-purpose metadata search.
Quick Start
Try the Local Vertical Slice
The repo ships a dependency-light Python implementation you can run offline — no OpenSearch cluster, no API keys required to start.
# Validate a sample attribute catalog PYTHONPATH=src python3 -m akrag.cli validate data/sample_attributes.csv # Convert it to one-document-per-attribute NDJSON PYTHONPATH=src python3 -m akrag.cli to-ndjson data/sample_attributes.csv build/attributes.ndjson # Query: retrieval + exact/near/ambiguous/none decisioning PYTHONPATH=src python3 -m akrag.cli query build/attributes.ndjson \ "high HbA1c" "readmitted in the last 30 days"
CLI First
Install as the `akrag` command and validate, convert, index, and query your own catalog from the terminal.
No Cluster Required
The local search backend uses BM25-style lexical ranking, token vectors, and RRF — no OpenSearch needed to prototype.
Production Path Included
Swap SEARCH_PROVIDER to opensearch and EMBEDDING_PROVIDER to a hosted model when you are ready to scale.
Open source. Domain-agnostic. Free.
Apache 2.0 licensed and free to adapt to your own attribute catalog. Star the repo on GitHub and help shape the roadmap.