{"id":50985497,"url":"https://github.com/starman69/ai-compliance-nlweb","last_synced_at":"2026-06-19T18:34:39.319Z","repository":{"id":359910724,"uuid":"1247985697","full_name":"starman69/ai-compliance-nlweb","owner":"starman69","description":"NLWeb-style AI-compliance assistant: /ask for people + /mcp for agents, grounded \u0026 cited over an open corpus of AI rules — dual local/Azure runtime.","archived":false,"fork":false,"pushed_at":"2026-05-24T03:33:47.000Z","size":34169,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T05:08:56.882Z","etag":null,"topics":["ai-compliance","azure","azure-ai-search","fastapi","llm","mcp","nlweb","ollama","qdrant","rag"],"latest_commit_sha":null,"homepage":"https://starman69.github.io/ai-compliance-nlweb/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/starman69.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T03:21:59.000Z","updated_at":"2026-05-24T03:33:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/starman69/ai-compliance-nlweb","commit_stats":null,"previous_names":["starman69/ai-compliance-nlweb"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/starman69/ai-compliance-nlweb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starman69%2Fai-compliance-nlweb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starman69%2Fai-compliance-nlweb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starman69%2Fai-compliance-nlweb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starman69%2Fai-compliance-nlweb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/starman69","download_url":"https://codeload.github.com/starman69/ai-compliance-nlweb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starman69%2Fai-compliance-nlweb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34544406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-compliance","azure","azure-ai-search","fastapi","llm","mcp","nlweb","ollama","qdrant","rag"],"created_at":"2026-06-19T18:34:38.118Z","updated_at":"2026-06-19T18:34:39.314Z","avatar_url":"https://github.com/starman69.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Compliance NLWeb\n\n**A conversational AI-compliance workbench.** An [NLWeb](https://github.com/nlweb-ai/NLWeb)-style\nlayer over the world's AI rules and standards, exposed two ways over one\nretrieval + answer core: **`/ask`** for people (structured JSON) and **`/mcp`** for\nagents (MCP tools). Ask natural-language questions about the EU AI Act, ISO/IEC 42001,\nthe NIST AI RMF, GDPR, US executive orders, and national frameworks — and get\n**grounded, cited** answers. RAG-only and accuracy-first: every claim cites\n`[framework §section, p.N]`, and when the corpus can't support an answer, it says so\nrather than guessing.\n\n**▶ Overview site:** [starman69.github.io/ai-compliance-nlweb](https://starman69.github.io/ai-compliance-nlweb/) (GitHub Pages) ·\n**Write-up:** [*NLWeb + MCP: Why Every Website Will Soon Need an /ask Endpoint*](https://medium.com/@dave-patten/nlweb-mcp-why-every-website-will-soon-need-an-ask-endpoint-92c8bac9d4da)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://starman69.github.io/ai-compliance-nlweb/\"\u003e\u003cimg src=\"docs/images/overview-site.png\" alt=\"AI Compliance NLWeb — single-page overview\" width=\"400\" /\u003e\u003c/a\u003e\n  \u003cbr/\u003e\u003csub\u003e\u003cem\u003eThe single-page overview (\u003ca href=\"https://starman69.github.io/ai-compliance-nlweb/\"\u003eGitHub Pages\u003c/a\u003e · source \u003ca href=\"site/index.html\"\u003e\u003ccode\u003esite/index.html\u003c/code\u003e\u003c/a\u003e) — corpus, NLWeb/MCP contracts, hybrid retrieval, dual runtime, and metrics.\u003c/em\u003e\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003e **Status: working POC.** The local stack answers with real models on GPU; the\n\u003e `/ask` and `/mcp` contracts are live, with token-by-token SSE streaming. On the\n\u003e golden-QA eval: **36/36 · 100% retrieval hit-rate · 100% intent accuracy · 97%\n\u003e mean term coverage** (local `qwen3:14b`), spanning all five tiers and every intent.\n\n---\n\n## What it does\n\nAsk questions like:\n\n- *\"How do I implement ISO 42001?\"*\n- *\"Compare US vs EU AI policy.\"*\n- *\"What records must I keep under the EU AI Act for a high-risk system?\"*\n- *\"What does GDPR say about automated decision-making for AI?\"*\n\n…and get an answer **grounded in the actual regulatory text**, with a collapsible\n**Sources** list (document · section · page · link), a **confidence** signal, a live\n**token-usage** readout, and **token-by-token streaming**. Every claim is cited; if the\ncorpus doesn't support an answer, it says so.\n\n## How it works\n\n```mermaid\nflowchart LR\n    H([Humans / UI]):::client --\u003e|\"/ask · /ask/stream\"| API[\"NLWeb API\u003cbr/\u003eFastAPI · one core\"]:::api\n    G([AI agents]):::client --\u003e|\"/mcp · MCP tools\"| API\n    API --\u003e CORE{{\"route → condense →\u003cbr/\u003eretrieve → rerank → cite\"}}:::core\n    CORE --\u003e RET[\"Hybrid retrieval\u003cbr/\u003edense + sparse → RRF → cross-encoder rerank\"]:::retr\n    RET --\u003e DB[(\"Vector store\u003cbr/\u003eQdrant (local) · Azure AI Search\")]:::store\n    CORE --\u003e LLM[\"Answer model\u003cbr/\u003eOllama qwen3:14b · Azure OpenAI gpt-4.1\"]:::model\n    CORE --\u003e OUT[\"Grounded, cited answer\u003cbr/\u003esources + Schema.org item_list\"]:::out\n\n    classDef client fill:#eef1ff,stroke:#3b4ccc,color:#1b2470\n    classDef api fill:#e0f2fe,stroke:#0e7fb8,color:#08364f\n    classDef core fill:#ede7ff,stroke:#6d4ad6,color:#2c1a66\n    classDef retr fill:#fff3da,stroke:#cf9412,color:#5a3c05\n    classDef store fill:#f5e8ff,stroke:#9a45d8,color:#3d1a66\n    classDef model fill:#e6f7ec,stroke:#2f9e55,color:#11432a\n    classDef out fill:#ffe7ef,stroke:#db4a7d,color:#5c0f30\n```\n\n- **One core, two contracts.** `/ask` returns structured JSON (Schema.org `ItemList`)\n  for humans/UI; `/mcp` (JSON-RPC, MCP) exposes the same retrieval + answer core as\n  tools for agents. Both accept the same payload; `query` is the only required field. A\n  `mode` of `list` / `summarize` / `generate` controls whether the LLM runs at all\n  (`list` is retrieval-only — no model call).\n- **Accuracy first.** Structure-aware chunking (citations name the article/clause),\n  hybrid dense + sparse retrieval with RRF fusion, a cross-encoder reranker, doc-hint\n  steering (naming a framework scopes retrieval to it), and citation-enforced generation.\n- **Dual runtime profile.** `RUNTIME_PROFILE=local` runs entirely on Docker (Qdrant +\n  Ollama `qwen3:14b` + `mxbai-embed-large`, 1024-d); `RUNTIME_PROFILE=azure` uses Azure\n  OpenAI (`gpt-4.1` + `text-embedding-3-small`, 1536-d) with Azure AI Search, provisioned\n  by Bicep. Each profile is a matched {store, embedder, answer-model} triple.\n\nArchitecture docs and Mermaid diagrams live in\n[`docs/poc/`](docs/poc/) — see [`10-diagrams.md`](docs/poc/10-diagrams.md) and\n[`01-architecture.md`](docs/poc/01-architecture.md).\n\n## The corpus\n\n**48 open-access documents · 32 frameworks**, across five tiers — **100% open-access,\nno paywalled content**:\n\n| Tier | Focus | Docs |\n|---|---|---:|\n| Global / International standards | ISO/IEC AI standards (open summaries), OECD, UNESCO, G7, Council of Europe | 8 |\n| EU / UK / National frameworks | EU AI Act \u0026 digital rulebook, GDPR, UK, Canada (AIDA), Singapore, Brazil, China | 16 |\n| US Federal | NIST AI RMF family, OMB memos, 2025 executive orders, NIST CSF / SP 800-53, FedRAMP | 13 |\n| US State | Colorado, Texas, Utah, California, New York City, Illinois | 8 |\n| Sector / Cloud | Cloud Security Alliance, Microsoft, Google | 3 |\n\nA versioned manifest ([`manifest/corpus.yaml`](manifest/corpus.yaml)) is the source of\ntruth; [`scripts/fetch_corpus.py`](scripts/fetch_corpus.py) pulls the open-access texts.\nISO/IEC standards (which are copyrighted) are represented by **open, non-normative\nauthored summaries** in [`manifest/summaries/`](manifest/summaries/) — the corpus is fully\nreproducible from open sources, with no paywalled content committed.\n\n## Quick start\n\n**Fast path — Mock backend** (instant, offline, no model server; how tests/CI run).\nGrounded, cited answers come from a committed offline seed — no fetch/ingest needed:\n\n```bash\npython -m venv .venv \u0026\u0026 . .venv/bin/activate \u0026\u0026 pip install -r requirements-dev.txt\nNLWEB_BACKEND=mock PYTHONPATH=src uvicorn api.app:app --port 8000        # API\ncd src/web \u0026\u0026 npm install \u0026\u0026 npm run dev                                 # http://localhost:8088\n```\n\n**Full local stack** — real `qwen3:14b` (GPU) + Qdrant + hybrid retrieval:\n\n```bash\ncd infra/compose \u0026\u0026 cp .env.example .env \u0026\u0026 docker compose up -d         # project: \"compliance\"\ndocker compose exec ollama ollama pull qwen3:14b\ndocker compose exec ollama ollama pull mxbai-embed-large\n# the corpus ships in sources/open/ — just ingest (chunk → embed → Qdrant):\ncd ../.. \u0026\u0026 RUNTIME_PROFILE=local NLWEB_BACKEND=real PYTHONPATH=src python scripts/ingest.py\nopen http://localhost:8088                                               # or: scripts/fetch_corpus.py to refresh\n```\n\nFull walkthrough → [`docs/poc/12-local-runtime.md`](docs/poc/12-local-runtime.md). Ask the API directly:\n\n```bash\ncurl -s localhost:8000/ask -H 'content-type: application/json' \\\n  -d '{\"query\":\"How do I implement ISO 42001?\",\"mode\":\"summarize\"}' | jq\n```\n\nAPI docs (Swagger): **http://localhost:8000/docs** · evaluate accuracy:\n`EVAL_API_URL=http://localhost:8000 python eval/run_eval.py`\n\n## Repo layout\n\n```\nmanifest/          corpus.yaml (the curated framework manifest) + summaries/ (open ISO summaries)\nscripts/           fetch_corpus.py (acquire) + ingest.py (chunk → embed → Qdrant)\nsrc/\n  shared/          clients factory, token_ledger, vector_search (Qdrant · Azure AI Search · Mock),\n                   embedding_text, prompts, router, config, security\n  api/             /ask, /ask/stream, /mcp (MCP server), /corpus, /health, audit\n  ingest/          structure-aware chunk → contextualize → embed → upsert\n  web/             React + Vite + TS NLWeb client (Tailwind v4, light/dark, SSE streaming)\neval/              golden_qa.yaml + run_eval.py (retrieval + citation scoring)\ndocs/\n  poc/             numbered architecture docs + diagrams + eval-baselines\n  adr/             Architecture Decision Records\ninfra/\n  compose/         local docker-compose stack (project name: \"compliance\")\n  bicep/           Azure IaC for the azure profile (Container Apps, AI Search, OpenAI, RBAC)\nsite/              single-page GitHub Pages overview\ntests/             unit/ (TDD) + e2e/ (Playwright UI validation)\n```\n\n## Lineage\n\nThis recreates and upgrades a prior project of the same name (the original code was\nlost). The recovered architecture diagram and UI screenshots live in\n[`docs/images/reference/`](docs/images/reference/); the design is documented in the\nwrite-up linked above.\n\n---\n\n\u003csub\u003eBuilt by Dave Patten ·\n[GitHub](https://github.com/starman69) ·\n[Medium](https://medium.com/@dave-patten) ·\n[MIT License](LICENSE)\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarman69%2Fai-compliance-nlweb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarman69%2Fai-compliance-nlweb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarman69%2Fai-compliance-nlweb/lists"}