Examples
The Metatate examples repository is the public, runnable cookbook for Metatate Cloud. Every notebook works against one synthetic B2B SaaS company, AcmeCloud — the same governed estate the in-app sample workspace loads — so what you learn in a notebook matches what you see in the product: eight governed tables plus a deliberately ungoverned legacy corner, fifteen policies, and one live publication.
Offline and live modesDirect link to Offline and live modes
Every notebook runs in two modes:
- Offline (default): replays recorded Metatate Cloud answers with typed-answer shapes identical to the live endpoint. No account needed — clone and run.
- Live: the same pack against your own workspace's MCP endpoint, authenticated with a workspace access token. See Connect to MCP for endpoints and tokens.
export METATATE_EXAMPLES_MODE=live
export METATATE_MCP_URL=https://<your-workspace-mcp-endpoint>/mcp
export METATATE_SAAS_MCP_TOKEN=mtt_...
The full live-mode walkthrough is in the repo's docs/live-mode-saas.md.
The notebooksDirect link to The notebooks
Thirteen notebooks, from first contact to full estate patterns:
| Notebook | What it shows |
|---|---|
00_setup_live_or_offline | Environment check and context discovery. |
01_decision_layer_cookbook | The core Metatate flow: discover, inspect, authorize, validate, explain. |
02_governed_sql_agent_langgraph | A small governed SQL-agent pattern with optional LangGraph. |
03_transfer_governance_before_export | Destination-aware transfer decisions before export. |
04_governed_text_to_sql_agent | Text-to-SQL that validates and revises SQL before returning it. |
05_agent_red_team_evaluation_harness | Repeatable risky-prompt checks for governed agents. |
06_ci_gate_for_data_ai_changes | A runnable CI/CD policy gate for SQL, export, and AI workflow changes. |
07_governed_rag_embedding_ingestion_gate | Pre-ingestion checks before data enters RAG or embedding workflows. |
08_openai_agents_tool_guard_pattern | A deterministic tool guard pattern for OpenAI Agents SDK-style apps. |
09_human_approval_packet_for_conditional_export | A human-in-the-loop exception workflow for safe, conditional, and denied requests. |
10_llamaindex_governed_retrieval_pattern | A governed retrieval function that can be wrapped as a LlamaIndex tool. |
11_langgraph_governed_sql_agent_runtime | A LangGraph runtime SQL agent with approve, revise, and block routes. |
12_governance_states_and_the_wider_estate | Honest states (ungoverned, review-required), role gating, the AI lifecycle, collection targeting, and taxonomy-targeted masking. |
Notebooks are generated from scripts/build_notebooks.py and drift-gated in CI — edits go into the generator, and CI fails if a notebook drifts from it.
Beyond the notebooks, the repo's docs include three live walkthroughs: the publish flip (author, approve, then watch the answer change only at publish), the Claude Code hero demo, and the governance-lead coverage review that finds and fixes the deliberately ungoverned corner.
Repository mapDirect link to Repository map
| Path | What it holds |
|---|---|
notebooks/ | The generated notebook pack above. |
sample-data/acmecloud/ | The machine-readable estate spec: catalog, real policy YAML, expected decisions, synthetic tables, and recorded offline response fixtures. |
common/ | Shared Python client helpers, including metatate_client.py. |
cicd_policy_gate/ | A reusable CI/CD policy gate package behind notebook 06. |
human_exception_workflow/ | A reusable human review and exception workflow package behind notebook 09. |
The policy files in sample-data/acmecloud/policies/ are real Metatate Cloud policy documents — the Policy YAML reference quotes one as its worked example.
Run it in five minutesDirect link to Run it in five minutes
Offline needs nothing but Python. To feel the decision layer live against your own workspace:
- Create a free account at app.getmetatate.com/sign-up and create a workspace.
- On the dashboard, follow the "New here?" banner to Load the demo, then choose Load the full estate — the notebooks expect the complete governed domain, not the smaller starter sample.
- Open MCP Tools → Tokens and issue an access token (shown once). Copy your endpoint from MCP Tools → Connect.
- Clone the repo, install, and point it at your workspace:
git clone https://github.com/metatateai/metatate-examples.git
cd metatate-examples
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export METATATE_EXAMPLES_MODE=live
export METATATE_MCP_URL=https://<your-workspace-mcp-endpoint>/mcp
export METATATE_SAAS_MCP_TOKEN=mtt_...
jupyter notebook notebooks
Every answer you get back is a typed, cited decision from your workspace's current deployment publication — see the governance model for what that means.