known-path

<p align="center"> <img src="assets/logo.svg" alt="known-path logo" width="560"/> </p>

<p align="center"> <strong>Light only the trusted catalog assets for a data job — then leave the route behind.</strong> </p>

<p align="center"> <a href="https://github.com/SeraKah-1/known-path/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"/></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python"/></a> <a href="https://datahub.devpost.com"><img src="https://img.shields.io/badge/DataHub-Agent%20Hackathon-0f766e.svg" alt="Hackathon"/></a> <a href="https://datahubproject.io"><img src="https://img.shields.io/badge/built%20for-DataHub-orange.svg" alt="DataHub"/></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-tools-black.svg" alt="MCP"/></a> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome"/> </p>

<p align="center"> <a href="#quickstart">Quickstart</a> · <a href="#how-it-works">How it works</a> · <a href="#demo">Demo</a> · <a href="#mcp--agents">MCP & agents</a> · <a href="#hackathon">Hackathon</a> · <a href="docs/HACKATHON.md">Compliance</a> </p>

---

Why this exists

Data catalogs already know which table is canonical, which is deprecated, and who owns it.
Agents still thrash search and join the wrong revenue_* table.

known-path is a small activation layer on top of that catalog truth:

1. Load a short route sheet for the job
2. Light only the few assets that matter
3. Stop if trust is red (no invented replacements)
4. Emit SQL you could open a PR with
5. Write a route note so the next run starts smarter

Built for the DataHub Agent Hackathon — tracks Metadata-Aware Code Generation and Agents That Do Real Work.

<p align="center"> <img src="assets/demo-flow.svg" alt="Demo flow" width="820"/> </p>

---

How it works

flowchart LR
  A[Job intent] --> B[Route sheet]
  B --> C[Score & shortlist]
  C --> D{Trust check}
  D -->|red| E[Fail closed<br/>leave block note]
  D -->|green| F[Fetch detail<br/>budgeted]
  F --> G[SQL artifact]
  G --> H[Write route note<br/>back to catalog/files]
  subgraph Catalog truth
    DH[(DataHub GMS<br/>or fixture stand-in)]
  end
  C -.-> DH
  F -.-> DH
  H -.-> DH

Mode	Behavior
baseline	Naive name thrash — more fetches, often lights finance.revenue_old
known-path	Route sheet + trust — lights canonical + region only
blocked	Forces red trust — stops, does not invent a table

This is not a second catalog, not a lineage UI, and not “dump all metadata into the prompt.”

---

Quickstart

git clone https://github.com/SeraKah-1/known-path.git
cd known-path
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

kp doctor
kp demo

Artifacts land in:

examples/baseline_wrong.sql
examples/revenue_by_region.sql
examples/runs/last_*.json
examples/runs/writeback_route_note.md

Optional live DataHub

export DATAHUB_GMS_URL=http://localhost:8080
export DATAHUB_GMS_TOKEN=your_token
kp doctor

See also: DataHub Quickstart · DataHub MCP · DataHub Skills

Web workbench (enterprise UI)

No extra deps (stdlib server). Every button runs the real CLI (python -m known_path.cli …).

kp web
# or:
python -m known_path.webapp --host 0.0.0.0 --port 8088
# open http://127.0.0.1:8088

Panel	What you get
Job intent + CTAs	Baseline / Known path / Fail closed / Full demo
Activation graph	SVG nodes lit from last CLI plan
Fetch comparison	Honest shared-axis bars (baseline vs known-path vs blocked)
Catalog table	demo-finance assets + usage bars
Agent terminal	Type run known-path, demo, doctor — bridged to CLI

kp dataset   # list assets + path

UX notes: docs/UX_AND_RESOURCES.md

---

Demo

kp demo

Expected story:

Step	Result
Baseline	Higher fetch count; trap table can activate
Known path	finance.revenue_canonical + dim.region; fewer fetches
Blocked	Status BLOCKED_TRUST; no SQL invention

kp run --mode baseline  -i "revenue by region last quarter"
kp run --mode known-path -i "revenue by region last quarter"
kp run --mode blocked   -i "revenue by region last quarter"

Sample SQL (generated):

-- known-path generated SQL
-- job: job.revenue_by_region_quarter
-- fact_urn: urn:li:dataset:(urn:li:dataPlatform:snowflake,finance.revenue_canonical,PROD)
SELECT
  d.region_name AS region,
  SUM(f.revenue_amount) AS revenue
FROM finance.revenue_canonical AS f
JOIN dim.region AS d
  ON f.region_id = d.region_id
...

---

MCP & agents

Install MCP extra and run the server:

pip install -e ".[mcp]"
python -m known_path.mcp_server

Tools: match_job · activate · ping_required · commit_route · explain_last_run

Skill package: skills/known-path/SKILL.md — workflow instructions agents load on demand (pairs with tools, does not replace them).

Example Cursor / Claude MCP snippet:

{
  "mcpServers": {
    "known-path": {
      "command": "python",
      "args": ["-m", "known_path.mcp_server"],
      "cwd": "/path/to/known-path"
    }
  }
}

---

Project layout

known-path/
├── assets/                 # logo + diagrams
├── cards/                  # route sheets (YAML)
├── datasets/demo-finance/  # demo catalog.json + CSV samples
├── docs/HACKATHON.md       # Devpost compliance map
├── docs/demo-recording/    # recorded demo video + evidence
├── examples/               # SQL + run records
├── skills/known-path/      # agent skill
├── src/known_path/         # library + CLI + MCP + web
├── apps/web/               # optional FastAPI wrapper
└── tests/                  # real scoring/activation tests

---

Hackathon

Event	datahub.devpost.com
Compliance	docs/HACKATHON.md
License	Apache-2.0
Video script	docs/demo-script.md

Remaining human step: record the <3 minute YouTube/Vimeo video and complete the Devpost form (not automated here).

---

Development

pip install -e ".[dev]"
pytest -q

Core policy lives in pure functions (scoring.py, ping.py, activate.py) so tests exercise the real logic with trap-vs-trusted fixtures.

---

Links

• DataHub · Docs · MCP guide
• Model Context Protocol
• Hackathon rules · Resources

---

License

Copyright 2026 SeraKah-1
Licensed under the Apache License, Version 2.0.