Epistemic Envelope
# Epistemic Envelope — Keep certified, observed, and inferred claims apart
[](LICENSE)
## Why
Data tools mix a rule that passed, a measurement from last year, and a model's guess in one paragraph. Agents then repeat the guess as if someone certified it. This library keeps those three kinds of claim in separate layers, for catalog teams that expose data through MCP tools.
## Quickstart
```bash
uv run python -m examples.catalog_server
```
That starts the reference catalog server on stdio and waits for an MCP client. `EPIENV_INFERENCE=off` withholds AI inferences.
## How it works
```mermaid
flowchart LR
Tool[MCP tool] --> Shape[Shape into layers]
Shape --> Policy[Inference policy]
Policy --> Text[Deterministic text]
```
A tool returns catalog facts. The decorator places approved rule results in certified findings, profiler metrics in observations, and model text in AI inferences. Policy can drop the inferences. The rendered text names the layer of every line.
## Results / example output
`describe_asset` for fixture column `col_email`, from the reference server:
```text
## Certified findings (authoritative)
- [cf-1] Email format rule passed — rule DQ-17, pass, certified by steward_a on 2026-09-20
## Profiling observations (measured; may be stale)
- [po-1] null_pct = 0.02 (observed 2026-09-20, run pr_9)
## AI inferences (unverified; do not present as fact)
- [ai-1] Likely contains personal email addresses — model static/canned, based on [po-1], review: unreviewed
Governance notice: AI-generated content is unverified and not certified.
```
## Design decisions
- [FastMCP integration](docs/adr/0001-fastmcp-integration.md)
- [Level 1 rule mapping](docs/adr/0002-level-1-rule-mapping.md)
- [OpenMetadata endpoint paths](docs/adr/0003-openmetadata-endpoints.md)
## Roadmap
- A recorded demo GIF (the image above is a placeholder)
- An MCP Governance Auditor report for this server
- A decision on whether the curated layer ships
- Name and IP clearance
## Licence
Code is Apache-2.0. The specification text is CC BY 4.0.
TDQS
Scored across 4 tools
list_assets is distinct, but get_asset_profile, describe_asset, and get_quality overlap: describe_asset returns profile, quality, and inferences, making the narrower tools seem redundant and boundaries unclear. An agent could reasonably choose describe_asset for most per-asset queries.
All names use a snake_case verb_noun format: list_assets, get_asset_profile, describe_asset, get_quality. Verb choices vary naturally by action, with no mixed conventions.
Four tools is a reasonable, focused count for a read-oriented catalog/quality server. It is slightly thin and includes some redundant coverage, but not too many or too few.
Core per-asset inspection is covered (list, profile, description, quality), but there is no catalog-level quality listing, search, or lineage/update operation. For a read-only epistemic catalog this is a notable gap, though not a severe failure.