# ContextGuard SQL Agent

**A metadata-guided, read-only SQL analysis MVP for DataHub.**

**Demo video (2:44):** https://youtu.be/btmJJWMFe4g

The video shows a real local self-hosted DataHub MCP run with a Reader-only
identity, seven read-only tools, a deterministic planner, local read-only
synthetic SQLite, and zero mutation or proposal calls. All business data shown
is synthetic.

ContextGuard answers a narrow analytical question without turning an agent into
a database writer. It uses DataHub metadata through the official MCP server to
find a synthetic asset, inspect schema and lineage, generate bounded SQL, and
run that SQL only against a local synthetic SQLite database.

## The problem

Analytical agents need more than table names. They need trustworthy schema,
ownership, tags, lineage, and safe query boundaries. Without them, an agent can
select an unsuitable asset, expose sensitive fields, scan too broadly, or issue
write operations.

## Architecture

```mermaid
flowchart LR
  DH[DataHub] --> MCP[Official MCP Server]
  MCP --> AD[Read-only Adapter]
  AD --> PL[Deterministic Planner]
  PL --> SL[SQL Safety Layer]
  SL --> DB[Local Synthetic SQLite]
  DB --> EA[Evidence-backed Analysis]
  EA --> RA[Redacted Audit]
```

The planner is deterministic. This MVP does not claim to use an external LLM.

## What is real, and what is synthetic

The project was validated locally against a self-hosted DataHub instance and
the official `mcp-server-datahub`. The DataHub reads, MCP protocol, client
adapter, SQLite safeguards, and end-to-end execution are real.

All business-like values, names, markets, emails, assets, and results in this
repository are fictional synthetic demo data. The project does not connect to
company MySQL, production databases, or external network databases.

## DataHub MCP integration

The client accepts only these Reader-safe tools:

- `search`
- `get_entities`
- `list_schema_fields`
- `get_lineage`
- `get_lineage_paths_between` when exposed by the server
- `get_dataset_queries`
- `get_me`

Mutation, proposal, administrator, and token-management tools are hard-blocked
in the client before any server call. The local MCP process is additionally
configured with mutations disabled.

## SQLite read-only safeguards

- Opens the local fixture with `mode=ro`.
- Enables `PRAGMA query_only` and an SQLite authorizer.
- Rejects writes, DDL, `ATTACH`, `DETACH`, extension loading, writable PRAGMA,
  multiple statements, `SELECT *`, and `alias.*`.
- Requires explicit allowed fields, a numeric `LIMIT`, and date bounds for
  larger synthetic assets.

## Installation

Python 3.11+ is recommended.

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
python -m pip install -r requirements.txt
```

## Local offline mode

```bash
pytest tests -q
python -m app.cli offline-demo
```

Offline mode uses a fixture strictly for local testing. It is not presented as
a real DataHub integration.

## Real DataHub mode

Real mode requires a locally running self-hosted DataHub and an official MCP
executable. Put any Reader credential in a private, user-owned environment
file outside this repository. Never place a token in a command line, Git,
screenshots, or logs.

```text
DATAHUB_GMS_URL=http://localhost:8080
DATAHUB_GMS_TOKEN=<reader-token>
CONTEXTGUARD_SQLITE_PATH=<path-to-synthetic-db>
```

Then provide the MCP command through the local private environment and run:

```bash
python -m app.cli real --question "Why did sales decline this period?" \
  --period-start 2026-07-13 --period-end 2026-07-20 --limit 20
```

Real mode fails closed if the MCP command is unavailable; it never falls back
to an offline fixture.

## Example result

For the synthetic weekly sales scenario, building sets explain most of the
fictional decline: CNY 900 of the CNY 950 period-over-period decrease. See
[the example analysis](examples/sales_decline_analysis.md).

## Demo and tests

- [Architecture](docs/architecture.md)
- [Security model](docs/security-model.md)
- [Demo walkthrough](docs/demo-walkthrough.md)
- [Three-minute script](demo/demo_script_3min.md)
- [Final demo video (2:44)](https://youtu.be/btmJJWMFe4g)
- [Submission draft](SUBMISSION.md)

The project has 29 offline tests covering read-only policy enforcement,
no-fallback behavior, token/error redaction, subprocess cleanup, and SQLite
database-layer controls. The real MCP MVP was validated locally against a
self-hosted DataHub instance; raw runtime logs are intentionally not public.

## Known limitations

- Local MVP only; not a production authorization design.
- Deterministic planner for one synthetic sales-decline scenario.
- No public deployment or UI is included.
- `get_dataset_queries` may honestly return an empty set because the demo does
  not import query history.

## No-mutation guarantee

This public MVP does not support metadata write-back. It does not call DataHub
mutation or proposal tools.

## Hackathon submission status

The local technical MVP has completed its real read-only acceptance. This
repository is a publication candidate only: it has no remote configured, has
not been pushed, and has not been submitted to Devpost.

## License

Licensed under [Apache License 2.0](LICENSE).