{
"markdown": "# openinsurance-wiki\n\n[](https://github.com/sluyasu/OpenInsurance/actions/workflows/validate.yml)\n[](https://sluyasu.github.io/OpenInsurance/)\n[](https://pypi.org/project/openinsurance-wiki-mcp/)\n[](#licensing--provenance)\n\n> **A brain for a country's insurance market.** A self-sufficient, open-source, country-agnostic framework that\n> turns a nation's public insurance documents into a rich, interconnected, source-cited knowledge base that any\n> AI agent can read.\n\n**Read it live: [sluyasu.github.io/OpenInsurance](https://sluyasu.github.io/OpenInsurance/)** - every page in\nthis repo, browsable and searchable, no install.\n\nNot a chatbot. Not a RAG black box. A **transparent, reproducible knowledge graph**: the repo contains the whole\nchain - it finds insurers' public general-conditions PDFs, downloads them, and turns each one into a faithful\nMarkdown page that preserves the maximum of what the PDF actually says, with a citation back to the source - all\ncross-linked into a navigable graph of products, insurers, branches, regulations and concepts.\n\n
\n \n
\n\nAs far as we know, this is the **only open-source, machine-readable, source-cited database of insurance\nproducts** (the closest equivalents are commercial and closed). Point it at **any country**: the taxonomy is\ndata, not code, and adding a country is a documented recipe ([`_meta/BOOTSTRAP-COUNTRY.md`](_meta/BOOTSTRAP-COUNTRY.md)).\n\nThe dataset covers **four countries - Belgium, France, Luxembourg and Switzerland** - for a total of\n**39 insurers and 1,189 product pages** (auto, home, health, liability, travel, legal protection, ...), each\npage cited to its source document:\n\n| Country | Insurers | Product pages | Branch pages | State |\n|---|---:|---:|---:|---|\n| Belgium (`be`) | 24 | 269 | 17 | Reference country: the only complete hand-authored layer - a branch page for every populated branch, 3 regulation pages, a country glossary |\n| France (`fr`) | 10 | 714 | 24 | Largest by volume; the enumerated market is far from exhausted |\n| Luxembourg (`lu`) | 4 | 194 | 15 | Core resident insurers ingested |\n| Switzerland (`ch`) | 1 | 12 | 0 | A first vertical slice, nothing more |\n\nThe recipe was proven on Belgium first and has since been run three more times, which is what turned\n\"country-agnostic\" from a design claim into a tested one. Live counts are the generated coverage table in\n[`AGENTS.md`](AGENTS.md), rebuilt from the data on every index run.\n\n---\n\n## Use it in 2 minutes - no API key needed\n\nThe dataset **ships in the repo, already built**: 1,189 product pages across four countries, insurer pages,\nglossary, plus the structured JSON behind them. You only need an LLM key to *re-extract from scratch*, never\nto *use* it.\n\n**1. Read it.** Online at [sluyasu.github.io/OpenInsurance](https://sluyasu.github.io/OpenInsurance/), or open\nthe cloned repo as an [Obsidian](https://obsidian.md) vault and the `[[wikilinks]]` become a navigable graph.\n(github.com itself does not render `[[wikilinks]]` as links - the site or the vault is the comfortable way.)\n\n**2. Plug it into an agent (MCP).** The MCP server is keyless and read-only:\n\n```bash\ngit clone https://github.com/sluyasu/OpenInsurance.git\ncd OpenInsurance\npython3 -m venv .venv && .venv/bin/pip install \"mcp[cli]\" pyyaml\n```\n\nThen register it with any MCP client, e.g. Claude Code:\n\n```bash\nclaude mcp add insurance-wiki -- \"$(pwd)/.venv/bin/python\" \"$(pwd)/mcp/insurance_wiki_mcp.py\"\n```\n\n(Or take the released server from PyPI - `uvx openinsurance-wiki-mcp` with `INSURANCE_WIKI_REPO` pointing at\nthe clone; the in-repo server above is always the one matching the committed dataset.)\n\nYou get `search`, `get_product`, `get_coverage` (only what's relevant to one question, with verbatim quotes),\n`compare_products`, `find_overlap` (candidate duplicate cover when combining two policies), `verify_claim`\n(verbatim evidence for a fact-check), `get_branch_overview`, ... See [`mcp/README.md`](mcp/README.md).\n\n**3. Take the raw data.** `data//extracted/` holds one structured JSON per source document, validated\nagainst [`schema/`](schema/); `data//index.json` is the flat index (`cc` = `be`, `fr`, `lu`, `ch`).\n`AGENTS.md` is a generated manifest (note types, counts, per-page `path` / `source_url` / `freshness`) so a\nfile-reading agent can navigate without guessing.\n\n---\n\n## Why an MCP server (and not a chatbot, a RAG stack or a REST API)\n\nThe goal is that **any** AI agent can answer insurance questions from documents it can cite. That constraint\npicks the architecture:\n\n
\n \n
\n\n**Why MCP.** The [Model Context Protocol](https://modelcontextprotocol.io) is the standard socket between AI\nassistants and data: one server, and Claude, ChatGPT, Cursor or your own agent plugs in with three lines of\nconfig instead of a custom integration. This server is **keyless** (no account, no API key, no quota),\n**read-only**, and needs **zero hosting**: the dataset is the repo itself, so the data travels with a\n`git clone` and works offline. When the wiki is re-extracted, `git pull` is the upgrade path.\n\n**Why not a RAG chatbot.** A chatbot is a single interface; a knowledge base should serve many (a broker's\ncomparison tool, a compliance check, a market-mapping agent). RAG adds an embedding index that is a black box:\nyou cannot diff it, review it in a PR, or reproduce it, and its retrieval errors are invisible. Here the\nretrieval layer is deterministic matching over reviewed, committed files: the same query returns the same\ndocuments every time, and every answer carries the source PDF and page numbers. The LLM stays where it\nbelongs, on the client side, reasoning over exact excerpts.\n\n**Why not a REST API.** An API means a server running 24/7, uptime, keys, versioning, and one bespoke\nintegration per consumer, for a dataset that changes a few times a year. MCP gives the same programmatic\naccess at the cost of a local process.\n\n**How it works, in four stages:**\n\n1. **Sources** (`sources/`): committed YAML saying where each insurer's public PDFs live.\n2. **Frozen extraction** (`data/`): each PDF turned once into structured JSON and cited Markdown, by a prompt\n that is itself committed. Nothing is generated at query time.\n3. **Deterministic MCP server** (`mcp/`): 10 read-only tools over those files. No LLM inside, no network, no\n state. Same input, same output.\n4. **A reasoning client**: the agent on top (Claude, a broker chatbot, a script) does the semantic work,\n quoting what the tools return.\n\nThe trust boundary is explicit: everything below stage 4 is reproducible and auditable. Hallucination risk is\nconfined to the client, and the tool responses are shaped to keep that client honest: a grounding contract and\na front-loaded citation line in every single-product response, refusal of ambiguous product names (with the\ncandidates listed) instead of silent guessing, and a `verify_claim` tool so an agent can fact-check its own\ndraft against the document before answering. See the\n[response discipline notes](mcp/README.md#what-keeps-the-answering-llm-honest) in the server docs.\n\n**How fast.** The server reads every file once and serves from memory: warm latencies run 0.01 to about 3 ms\nper tool on this dataset (measured, reproducible: [`mcp/README.md`](mcp/README.md#measured-latency)). In a real\nchatbot the time a user feels is the LLM's own inference, not these tools.\n\n## Why this exists\n\nInsurance products are documented in dense PDFs scattered across dozens of insurer websites. There is no\nneutral, machine-readable, navigable map of what actually exists in a national market. This project builds\none - as a public good, and in a form an AI agent can plug into.\n\nIt also plugs into a market that is standardizing around it: EU regulation 2017/1469 gives every non-life\nproduct a standardized summary (the **IPID**), EIOPA actively promotes product comparison and switching, and\nthe **open insurance** agenda (OPIN, the EU FIDA proposal) pushes for machine-readable access to insurance\ndata. This project is the missing *public documents* layer of that picture: what the products actually say,\nin the open.\n\nFour things make it different:\n\n1. **Self-sufficient & reproducible.** Clone it, add your own LLM key, run `make all`. It scrapes, downloads\n and extracts from scratch. No hidden datasets - every input is committed, every output is regenerable.\n2. **Transparent extraction.** The exact prompt sent to the LLM is a file in this repo\n ([`extraction-agent/`](extraction-agent/)), not buried in code. You can read precisely what the model was\n asked, and run the identical extraction **with your own model** (Claude, Gemini, GPT, or a local model).\n3. **Grounded & cited.** Every product page traces back to the source PDF and cites page numbers. Quotes are\n verified against the raw text. If it isn't in the document, it isn't on the page.\n4. **Scoped.** A page is a contractual or pre-contractual document of a specific insurance product - nothing\n else. Insurers' download pages mix in company statutes, fund reports and promo riders; those are refused at\n three gates (a recorded `out_of_scope` marker in the sources, the extraction agent's own verdict, and a\n CI-blocking check). See [CONTRIBUTING](CONTRIBUTING.md#scope-what-belongs-in-the-wiki).\n\n---\n\n## What's in the wiki\n\nPer country (`wiki//`, e.g. `wiki/be/`):\n\n| Folder | What | How it's made |\n|---|---|---|\n| `products//` | One rich page per insurance product (general conditions / IPID) | **Generated** from the PDFs |\n| `insurers/` | One page per insurer, aggregating its products | **Generated** |\n| `branches/` | Overview of each line of insurance (every populated branch has one; `make validate` lists any gap) | **Hand-authored** |\n| `regulations/` | The regulator and key laws (FSMA, mandatory RC auto, cat-nat...) | **Hand-authored** |\n| `glossary/` | Country-specific terms (bonus-malus, franchise, Branche 21/23...) | **Hand-authored** |\n\nGenerated and hand-authored pages live in **separate folders** and never collide: you fix a fact by editing the\nextraction data and rebuilding, never by editing a generated page.\n\nThe generated layer exists for all four countries; the hand-authored layer is uneven and deliberately not\nhidden. Belgium has branch, regulation and glossary pages; France and Luxembourg have branch pages and one\nregulation page each; Switzerland has neither yet. `make validate` lists every populated branch that still\nlacks an overview page. Universal concepts that apply to every country live in `wiki/universal-glossary/`.\n\nEvery page is Obsidian-compatible Markdown with YAML frontmatter and `[[wikilinks]]`.\n\n---\n\n## Reproduce it from scratch\n\nThis is the only path that needs an LLM key (the extraction step). Scraping and download use a free stack\n(`httpx` + `Playwright`).\n\n```bash\ngit clone https://github.com/sluyasu/OpenInsurance.git\ncd OpenInsurance\nmake setup # deps + playwright chromium (no paid scraping dependency)\ncp .env.example .env # set LLM_PROVIDER + your API key (any provider)\n\n# Reproduce a slice end-to-end:\nmake download COUNTRY=be INSURER= # fetch the public PDFs\nmake extract COUNTRY=be INSURER= # PDFs -> rich Markdown + JSON (uses YOUR model)\nmake build COUNTRY=be # assemble the wiki\nmake validate COUNTRY=be # citation / wikilink / frontmatter gates\n\n# ...or the whole chain:\nmake all COUNTRY=be\n```\n\n`COUNTRY` takes any country present in `sources/`: `be`, `fr`, `lu` or `ch`. Extraction is resumable\n(skip-existing keyed by source checksum + prompt version), so large runs can stop and restart safely.\n\n## How the pipeline works\n\n```\nsources/be/.yml (committed: where the public PDFs live)\n │ discover.py crawl listing pages (httpx, Playwright fallback)\n ▼\ndata/be/pdfs/… (downloaded; gitignored - regenerable; manifest.json committed)\n │ extract.py PyMuPDF text ──► LLM (extraction-agent/ prompts) ──► MD + JSON\n ▼\ndata/be/extracted/… (rich Markdown + structured JSON, page-cited)\n │ build_wiki.py\n ▼\nwiki/be/… (the browsable, agent-readable knowledge base)\n```\n\n`be` is shown; the same layout exists under `fr/`, `lu/` and `ch/`, and the code is the same for all of them.\n\nDetails: [`CONTRIBUTING.md`](CONTRIBUTING.md) (how to add a country / insurer / product) and\n[`extraction-agent/`](extraction-agent/) (the exact prompts).\n\nEvery push runs the CI gates: wiki validation (frontmatter, links with `--strict-links`, citations, the data\nlayer against the schema and the scope rule), the pytest suite, build idempotence (rebuilding the committed\nwiki must produce a zero diff), and a dead-link check on the built site that gates the deploy. A monthly\nworkflow opens an issue when the dataset's freshness slips.\n\n---\n\n## Add a country\n\n1. `sources//_country.yml` - regulator, languages, branch taxonomy.\n2. `sources//.yml` - where each insurer's public PDFs live.\n3. `wiki//` - hand-author branch/regulation/glossary overviews (or start them as stubs).\n4. `make all COUNTRY=`.\n\nNothing in the schema is country-specific - the taxonomy is data, not structure. Four countries (`be`, `fr`,\n`lu`, `ch`) run through the same code with no per-country branch in the pipeline. One known limit: the\nproduct-page section titles are still hardcoded French in `pipeline/render.py`, so a country whose documents\nare not French-language will need them moved into the country config first.\n\n---\n\n## Licensing & provenance\n\nDual-licensed: **code** ([pipeline/](pipeline/), [mcp/](mcp/), adapters, schema) under **MIT**; **original\ncontent** (`wiki/`, extracted data, prompts, sources) under **CC-BY-4.0**. Short verbatim excerpts quoted from\ninsurers' public documents remain the property of their publishers and are **not** relicensed - see\n[`LICENSE`](LICENSE), [`LICENSE-CONTENT`](LICENSE-CONTENT) and [`NOTICE`](NOTICE).\n\nProduct pages are a factual extraction from insurers' **publicly published** documents, attributed to each source\nPDF. **They are not the insurers' official documents** and may contain extraction errors - always verify against\nthe cited `source_url`. This project provides **information, not personalized insurance advice**.\n",
"bytes": 15005,
"sha": "840f7bbad1950bc80b8bf4930bacb972690361f92556ea693ded536cdadace6d",
"repo_slug": "sluyasu/openinsurance",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_sluyasu_openinsurance_wiki_a999fc3c/readme"
}
![\"The](\"assets/knowledge-graph-662a0d77.png\")
\n![\"Pipeline:](\"assets/architecture-b1843d99.png\")
\n