datacharter 0.2.0__tar.gz → 0.3.1__tar.gz

{datacharter-0.2.0 → datacharter-0.3.1}/.github/workflows/banned-terms.yml

@@ -14,7 +14,7 @@ jobs:
   scan:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Scan for banned terms
         run: |
           set -e

{datacharter-0.2.0 → datacharter-0.3.1}/.github/workflows/release.yml

@@ -17,20 +17,20 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: 22
           cache: npm
           cache-dependency-path: ui/package-lock.json
-      - uses: astral-sh/setup-uv@v4
+      - uses: astral-sh/setup-uv@v7
       - name: Build UI into the package
         run: ./scripts/build_ui.sh
       - name: Build sdist + wheel
         run: uv build
       - name: Validate metadata and README rendering
         run: uvx twine check dist/*
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -44,7 +44,7 @@ jobs:
     permissions:
       id-token: write # OIDC token for PyPI Trusted Publishing
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{datacharter-0.2.0 → datacharter-0.3.1}/.github/workflows/test.yml

@@ -8,8 +8,8 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v4
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
       - name: Install
         run: uv venv && uv pip install -e ".[dev]"
       - name: Lint
@@ -44,8 +44,8 @@ jobs:
           --health-cmd "mysqladmin ping -h 127.0.0.1 -pcharter_test_pw -ucharter"
           --health-interval 2s --health-timeout 2s --health-retries 60
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v4
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
       - name: Install
         run: uv venv && uv pip install -e ".[dev]"
       - name: Seed databases
@@ -61,8 +61,8 @@ jobs:
   ui:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: 22
           cache: npm
@@ -75,15 +75,28 @@ jobs:
   package:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: 22
           cache: npm
           cache-dependency-path: ui/package-lock.json
-      - uses: astral-sh/setup-uv@v4
+      - uses: astral-sh/setup-uv@v7
       - name: Build UI into package
         run: ./scripts/build_ui.sh
+      - name: Fetch VidaiMock (e2e mock LLM; Apache-2.0, checksum-pinned)
+        run: |
+          ver=v0.2.9
+          base="https://github.com/vidaiUK/VidaiMock/releases/download/$ver"
+          curl -fsSL -o vm.tar.gz "$base/vidaimock-linux-x64.tar.gz"
+          curl -fsSL -o vm.sha256 "$base/vidaimock-linux-x64.sha256"
+          got=$(sha256sum vm.tar.gz | awk '{print $1}')
+          want=$(awk '{print $1}' vm.sha256)
+          test "$got" = "$want" || { echo "VidaiMock checksum mismatch: $got != $want"; exit 1; }
+          mkdir -p vidaimock-bin && tar -xzf vm.tar.gz -C vidaimock-bin
+          bin=$(find "$PWD/vidaimock-bin" -type f -name vidaimock | head -1)
+          chmod +x "$bin"
+          echo "VIDAIMOCK_BIN=$bin" >> "$GITHUB_ENV"
       - name: Install + e2e
         run: |
           uv venv

{datacharter-0.2.0 → datacharter-0.3.1}/CHANGELOG.md

@@ -5,6 +5,83 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-07-24
+
+### Changed
+
+- Internal: extracted the origin/host request guard (DC-SEC-006) from the
+  server into an importable `datacharter.server.security` module. No behavior
+  change; the existing anti-DNS-rebinding / cross-origin protections are intact.
+
+## [0.3.0] - 2026-07-24
+
+### Added
+
+- Agent view: a toggle on the results grid that masks the contract's PII columns
+  in place, showing exactly what the agent and MCP server see (the model never
+  sees raw PII) — right in the SQL editor, no LLM required.
+- Source tree: collapsible `+`/`−` disclosure on every source and table, and
+  expand a table to see its columns inline.
+- Instant SQL preview: results update live a beat after you stop typing (row-capped,
+  and errors stay silent until you press Run) — no Run click needed to see output.
+- Chart captions: auto-detected charts (results) and agent-emitted charts (chat)
+  now show a one-line plain-language caption of what they show — e.g. "bar of
+  revenue by customer_id".
+- `datacharter explain <sql>` — show a query's plan and row estimates without
+  running it: a pre-flight cost check that surfaces per-source scans and what
+  would push down.
+- `datacharter sample <relation>` — print a PII-masked CSV sample of a relation
+  (columns marked PII in the contract come back as `•••`), safe to paste into a
+  bug ticket or share.
+- Contract-scoped metrics: declare named `metrics:` in `charter.yaml` (a base
+  relation + an aggregate expression + optional dimensions); `datacharter metric
+  <name> [--by cols]` resolves each to one governed SELECT and runs it, so a
+  certified `revenue` always means the same thing. Joins across sources and time
+  grains are a later refinement.
+- NL→SQL cache: when the agent answers via a query, its SQL is cached against a
+  contract fingerprint; a repeat or normalized-reworded question re-runs the
+  cached SQL on current data and skips the LLM round-trip (fresh data, no stale
+  answers). Embedding-based semantic similarity is a follow-up.
+- `datacharter serve --offline` — no-egress mode: the LLM agent is disabled (no
+  data can reach any model endpoint) and connecting one at runtime is refused. It
+  prints and writes a no-egress attestation to `.datacharter/attestation.json`.
+- `datacharter snapshot <name> <sql>` and `datacharter recheck <name>` — save a
+  query's result as `local.<name>` alongside its SQL, then later re-run it and
+  diff against the saved result to answer "did this number change?". `recheck`
+  exits non-zero when the result has changed.
+- `datacharter drift` — report schema drift between the charter and the live
+  sources: declared tables or PII columns that no longer exist. A missing PII
+  column is a silent masking gap, so this is caught explicitly. Exits non-zero
+  when drift is found, for use in CI.
+- `datacharter scan` — introspect the configured sources and suggest PII columns
+  for `charter.yaml`, both by column name and by sampled values (catches an
+  email/SSN/IP column whose name gives nothing away). Turns "author a contract"
+  into "review a generated one" for the PII map. Prints suggestions, or `--write`
+  merges them into `charter.yaml` (round-trip; credential refs left untouched).
+- `datacharter diff <left> <right>` and `Engine.diff` — a full-row set difference
+  between two relations, across sources (postgres vs a file, prod vs staging, …)
+  via the federation engine. Reports rows only in each side plus the common count,
+  through the read-only guard. With `--key`, rows are matched by key and changed
+  rows (same key, differing values) are counted separately.
+- Per-query provenance: query results (API, agent tool results) now report the
+  source relations and columns the query read — plus column lineage, mapping each
+  output column to the input columns that feed it — parsed from the same AST the
+  read-only guard uses. This is the trust signal for an agent answer: it shows
+  which real columns an answer came from.
+- `datacharter mcp` — an MCP (Model Context Protocol) server over stdio that
+  exposes the four governed query tools (`list_sources`, `list_tables`,
+  `describe_table`, `query`) to any MCP client. The read-only guard, PII masking,
+  and credential scrubbing are inherited from the same toolbox the agent uses, so
+  an external agent can explore your data without seeing raw PII or being able to
+  write. Hand-rolled JSON-RPC 2.0, no new dependency.
+
+### Changed
+
+- Toolbar: **Snapshot** moved next to the query actions (away from the export
+  format menu); hover tooltips on Run/Snapshot/Export/Explain.
+- Demo workspace: bundled as one sqlite `store` contract holding `customers`
+  and `orders`, so the sidebar reads contract → table → columns.
+
 ## [0.2.0] - 2026-07-24
 
 ### Added

datacharter-0.3.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,72 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers privately through GitHub's private reporting on the
+repository (Security → Advisories, or a direct message to a maintainer). All
+complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

datacharter-0.3.1/CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contributing to DataCharter
+
+Thanks for your interest in DataCharter. Contributions of all kinds — bug
+reports, docs, tests, and code — are welcome. The project is licensed under
+[Apache-2.0](LICENSE); contributions are accepted under the same license.
+
+## Ways to contribute
+
+- **Report a bug or request a feature** — open an issue with steps to reproduce
+  or a clear description of the use case.
+- **Improve docs** — fixes to the guides under `docs/` and the README are always
+  welcome.
+- **Send a pull request** — for anything beyond a trivial fix, open (or comment
+  on) an issue first so we can agree on the approach before you invest the work.
+
+## Development setup
+
+DataCharter is one Python package with a bundled web UI. You need Python 3.11+
+and [uv](https://docs.astral.sh/uv/); UI work additionally needs Node.
+
+```sh
+# Python environment (creates .venv)
+uv sync
+
+# Run the app from source
+uv run datacharter serve
+
+# Web UI (only if you're changing the frontend)
+cd ui && npm ci && npm run build
+```
+
+## Tests and linting
+
+Every change lands with tests, and the working tree must be lint-clean. These
+are the same commands CI runs:
+
+```sh
+uv run pytest -q                 # unit tests (fast; the default set)
+uv run pytest -m integration -q  # integration tests (require Docker)
+uv run pytest -m e2e -q          # end-to-end (see below)
+uv run ruff check .              # lint
+cd ui && npm run build           # type-check + build the UI
+```
+
+The end-to-end agent test drives a real
+[VidaiMock](https://github.com/vidaiUK/VidaiMock) server (an Apache-2.0 mock LLM);
+it skips unless `VIDAIMOCK_BIN` points at the binary or `vidaimock` is on `PATH`.
+
+Write tests that describe behavior, keep unit tests fast, and put anything that
+needs Docker or a live server behind the `integration` / `e2e` markers so the
+default run stays quick.
+
+## Commit and pull-request conventions
+
+- **[Conventional Commits](https://www.conventionalcommits.org/)**:
+  `feat:`, `fix:`, `docs:`, `chore:`, `test:`, `refactor:`. Keep the subject
+  under ~72 characters, imperative mood.
+- Small, focused commits over large omnibus ones. Every commit should build and
+  pass tests so history stays bisectable.
+- Never commit secrets, tokens, or real hostnames — in code, tests, or fixtures.
+- Keep the PR scoped to one change; describe the "why," not just the "what."
+
+## Developer Certificate of Origin (sign-off required)
+
+DataCharter uses the **Developer Certificate of Origin (DCO)** instead of a CLA.
+Every commit must be signed off, certifying that you wrote the change (or
+otherwise have the right to submit it under Apache-2.0). This is a lightweight,
+one-time habit — no separate agreement to sign.
+
+Add the sign-off automatically with the `-s` flag:
+
+```sh
+git commit -s -m "fix: correct off-by-one in row cap"
+```
+
+That appends a line matching your configured `git` name and email:
+
+```
+Signed-off-by: Jane Developer <jane@example.com>
+```
+
+Use your real name and a valid email. If you forget the sign-off on your last
+commit, amend it with `git commit --amend -s`; for a whole branch, use
+`git rebase --signoff <base>`. PRs whose commits are not signed off cannot be
+merged.
+
+By signing off, you agree to the DCO, version 1.1:
+
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```

datacharter-0.3.1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: datacharter
+Version: 0.3.1
+Summary: Charter your data — contract-governed local data exploration, powered by DuckDB
+Project-URL: Homepage, https://github.com/datacharter/datacharter
+Project-URL: Repository, https://github.com/datacharter/datacharter
+Project-URL: Documentation, https://datacharter.github.io/datacharter/
+Project-URL: Changelog, https://github.com/datacharter/datacharter/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/datacharter/datacharter/issues
+Author: DataCharter
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: data-contracts,data-exploration,duckdb,federation,local-first,sql
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=1.5
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python>=3.12; extra == 'snowflake'
+Description-Content-Type: text/markdown
+
+# DataCharter
+
+> Explore all your data locally, in one place — contract-governed data exploration, powered by DuckDB
+
+[![PyPI](https://img.shields.io/pypi/v/datacharter)](https://pypi.org/project/datacharter/)
+[![Python](https://img.shields.io/pypi/pyversions/datacharter)](https://pypi.org/project/datacharter/)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue)](LICENSE)
+
+Contract-governed local data exploration, **powered by [DuckDB](https://duckdb.org)**.
+Define your sources as data contracts
+([ODCS](https://bitol-io.github.io/open-data-contract-standard/)-compatible YAML),
+query them through DuckDB's SQL federation engine with real source pushdowns,
+and explore in a local web UI — SQL editor with live preview, auto-charts,
+profiling. Every answer shows which source columns it read; ask questions in
+plain language or serve the whole thing to an AI agent over [MCP](docs/mcp.md),
+with PII masked from the model — all on your machine.
+
+## What you can do
+
+- **Drop a file, query it instantly.** Drag a CSV, Parquet, or JSON onto the window and run SQL on it right away — no import, no schema setup.
+- **Join across sources — no pipelines.** Query and JOIN a Postgres table, a Parquet file, and a Snowflake table in a *single* SQL statement. No ETL, no copying everything into a warehouse first.
+- **Connect all your data.** Postgres, MySQL, SQLite, SQL Server, BigQuery, Snowflake, files on S3/GCS/Azure, and Iceberg/Delta tables — all through one engine.
+- **See answers as you type.** Live results preview while you write SQL, one-click auto-charts, and a profiling panel (missing values, distributions, outliers) — no separate BI tool.
+- **Ask in plain English (optional).** Turn a question into SQL and an answer with the built-in agent — bring your own model, or run one fully local with no API key.
+- **Keep sensitive data away from the AI.** Mark PII columns once; the agent and any connected AI see masked values (`•••`) while you still see the real data locally. Flip **Agent view** to see exactly what the model sees.
+- **Safe by design.** The engine is read-only by construction — no query can write, delete, or touch the filesystem — so pointing an AI (or a teammate) at your real databases can't do damage.
+- **Point AI tools at your data, safely.** A governed MCP server exposes read-only, PII-masked query tools to Cursor, Cline, or your own agent.
+- **Trust every answer.** Each result shows exactly which source columns it read — so you always know where a number came from.
+- **Save, reuse, export.** Snapshot a result as a reusable local table; export to CSV, Parquet, JSON, or XLSX.
+- **Governance you can automate.** Catch schema/PII drift in CI, auto-detect PII columns, diff data across sources, and define certified metrics — from the command line.
+
+![DataCharter — live SQL preview, auto-charts, per-query provenance, and PII masking](https://raw.githubusercontent.com/datacharter/datacharter/main/brand/demo.gif)
+
+**Status: pre-release.** V1 in development.
+
+## Quick start
+
+```sh
+# Try it instantly on generated demo data — no install, no config:
+uvx datacharter serve          # needs `uv` → https://astral.sh/uv
+# → serves at http://127.0.0.1:8321 (open it in your browser)
+
+# Or install it:
+pip install datacharter        # Python 3.11+
+
+# Start your own workspace:
+datacharter init               # scaffolds charter.yaml, queries/, .env.example
+# → add a source: edit charter.yaml, or use the "Sources" panel in the UI
+datacharter serve              # → http://127.0.0.1:8321
+```
+
+Then, once it's running, **drag a CSV, Parquet, or JSON file onto the window** to
+query it instantly — no config needed.
+
+**Optional natural-language agent** — point it at any OpenAI-compatible endpoint:
+
+```sh
+export OPENAI_BASE_URL=...     # any OpenAI-compatible API
+export OPENAI_API_KEY=...
+datacharter serve
+```
+
+…or run **fully local** — no API key, no data leaves your machine (requires
+[Ollama](https://ollama.com)):
+
+```sh
+ollama pull qwen3:8b           # once
+datacharter serve --local      # qwen3:8b by default (--model to change)
+```
+
+## Why DataCharter
+
+- **Your contracts are the catalog.** `charter.yaml` describes sources, tables,
+  and PII fields — the same contract spec your data team already writes, so
+  there's no separate metadata store to maintain.
+- **Real federation, not just a shared connection.** Filters and projections are
+  pushed down to each source — even across a cross-source join, every leg is
+  filtered where its data lives. (Snowflake runs via connector extract,
+  `datacharter[snowflake]`, with the same pushdown into the extract.)
+- **Local-first.** One process, your machine, no cloud dependency. The optional
+  `--local` agent runs a small open model via Ollama — no API key, no data leaves
+  your machine.
+- **The workspace is a directory.** `charter.yaml` + `queries/*.sql` +
+  `.env.example` — commit it, clone it, `datacharter serve`. Your team's whole
+  exploration environment travels as a repo; secrets and local state never do.
+
+DataCharter governs and audits your data, not just displays it. The full command
+set (`drift`, `scan`, `diff`, `metric`, `mcp`, and more) is in the
+[CLI reference](docs/cli.md); the security model is in [security](docs/security.md).
+
+## Built on
+
+DataCharter stands on excellent open-source foundations:
+
+- **[DuckDB](https://duckdb.org)** — the analytical engine at our core:
+  federation (`ATTACH`), file formats, Iceberg/Delta, encryption, autocomplete.
+- **[Open Data Contract Standard](https://bitol-io.github.io/open-data-contract-standard/)** /
+  [datacontract.com](https://datacontract-specification.com/) — the contract format `charter.yaml` speaks.
+- **[Model Context Protocol](https://modelcontextprotocol.io)** — the open protocol
+  the `datacharter mcp` server speaks to agents and MCP clients.
+- **[Vega-Lite](https://vega.github.io/vega-lite/)** — declarative charting.
+- **[Monaco Editor](https://microsoft.github.io/monaco-editor/)** — the SQL editor.
+- **[TanStack Table & Virtual](https://tanstack.com/)** — the virtualized results grid.
+- And the Python & React ecosystems — FastAPI, pydantic, httpx, keyring, and
+  ruamel.yaml on the backend; React and Vite on the front.
+
+Testing uses **[VidaiMock](https://github.com/vidaiUK/VidaiMock)**, an
+Apache-2.0 mock LLM server, as the offline agent endpoint in CI.
+
+DuckDB is a trademark of the DuckDB Foundation. DataCharter is an independent
+project and is not affiliated with or endorsed by the DuckDB Foundation.
+
+## License
+
+[Apache-2.0](LICENSE)

datacharter-0.3.1/README.md

@@ -0,0 +1,115 @@
+# DataCharter
+
+> Explore all your data locally, in one place — contract-governed data exploration, powered by DuckDB
+
+[![PyPI](https://img.shields.io/pypi/v/datacharter)](https://pypi.org/project/datacharter/)
+[![Python](https://img.shields.io/pypi/pyversions/datacharter)](https://pypi.org/project/datacharter/)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue)](LICENSE)
+
+Contract-governed local data exploration, **powered by [DuckDB](https://duckdb.org)**.
+Define your sources as data contracts
+([ODCS](https://bitol-io.github.io/open-data-contract-standard/)-compatible YAML),
+query them through DuckDB's SQL federation engine with real source pushdowns,
+and explore in a local web UI — SQL editor with live preview, auto-charts,
+profiling. Every answer shows which source columns it read; ask questions in
+plain language or serve the whole thing to an AI agent over [MCP](docs/mcp.md),
+with PII masked from the model — all on your machine.
+
+## What you can do
+
+- **Drop a file, query it instantly.** Drag a CSV, Parquet, or JSON onto the window and run SQL on it right away — no import, no schema setup.
+- **Join across sources — no pipelines.** Query and JOIN a Postgres table, a Parquet file, and a Snowflake table in a *single* SQL statement. No ETL, no copying everything into a warehouse first.
+- **Connect all your data.** Postgres, MySQL, SQLite, SQL Server, BigQuery, Snowflake, files on S3/GCS/Azure, and Iceberg/Delta tables — all through one engine.
+- **See answers as you type.** Live results preview while you write SQL, one-click auto-charts, and a profiling panel (missing values, distributions, outliers) — no separate BI tool.
+- **Ask in plain English (optional).** Turn a question into SQL and an answer with the built-in agent — bring your own model, or run one fully local with no API key.
+- **Keep sensitive data away from the AI.** Mark PII columns once; the agent and any connected AI see masked values (`•••`) while you still see the real data locally. Flip **Agent view** to see exactly what the model sees.
+- **Safe by design.** The engine is read-only by construction — no query can write, delete, or touch the filesystem — so pointing an AI (or a teammate) at your real databases can't do damage.
+- **Point AI tools at your data, safely.** A governed MCP server exposes read-only, PII-masked query tools to Cursor, Cline, or your own agent.
+- **Trust every answer.** Each result shows exactly which source columns it read — so you always know where a number came from.
+- **Save, reuse, export.** Snapshot a result as a reusable local table; export to CSV, Parquet, JSON, or XLSX.
+- **Governance you can automate.** Catch schema/PII drift in CI, auto-detect PII columns, diff data across sources, and define certified metrics — from the command line.
+
+![DataCharter — live SQL preview, auto-charts, per-query provenance, and PII masking](https://raw.githubusercontent.com/datacharter/datacharter/main/brand/demo.gif)
+
+**Status: pre-release.** V1 in development.
+
+## Quick start
+
+```sh
+# Try it instantly on generated demo data — no install, no config:
+uvx datacharter serve          # needs `uv` → https://astral.sh/uv
+# → serves at http://127.0.0.1:8321 (open it in your browser)
+
+# Or install it:
+pip install datacharter        # Python 3.11+
+
+# Start your own workspace:
+datacharter init               # scaffolds charter.yaml, queries/, .env.example
+# → add a source: edit charter.yaml, or use the "Sources" panel in the UI
+datacharter serve              # → http://127.0.0.1:8321
+```
+
+Then, once it's running, **drag a CSV, Parquet, or JSON file onto the window** to
+query it instantly — no config needed.
+
+**Optional natural-language agent** — point it at any OpenAI-compatible endpoint:
+
+```sh
+export OPENAI_BASE_URL=...     # any OpenAI-compatible API
+export OPENAI_API_KEY=...
+datacharter serve
+```
+
+…or run **fully local** — no API key, no data leaves your machine (requires
+[Ollama](https://ollama.com)):
+
+```sh
+ollama pull qwen3:8b           # once
+datacharter serve --local      # qwen3:8b by default (--model to change)
+```
+
+## Why DataCharter
+
+- **Your contracts are the catalog.** `charter.yaml` describes sources, tables,
+  and PII fields — the same contract spec your data team already writes, so
+  there's no separate metadata store to maintain.
+- **Real federation, not just a shared connection.** Filters and projections are
+  pushed down to each source — even across a cross-source join, every leg is
+  filtered where its data lives. (Snowflake runs via connector extract,
+  `datacharter[snowflake]`, with the same pushdown into the extract.)
+- **Local-first.** One process, your machine, no cloud dependency. The optional
+  `--local` agent runs a small open model via Ollama — no API key, no data leaves
+  your machine.
+- **The workspace is a directory.** `charter.yaml` + `queries/*.sql` +
+  `.env.example` — commit it, clone it, `datacharter serve`. Your team's whole
+  exploration environment travels as a repo; secrets and local state never do.
+
+DataCharter governs and audits your data, not just displays it. The full command
+set (`drift`, `scan`, `diff`, `metric`, `mcp`, and more) is in the
+[CLI reference](docs/cli.md); the security model is in [security](docs/security.md).
+
+## Built on
+
+DataCharter stands on excellent open-source foundations:
+
+- **[DuckDB](https://duckdb.org)** — the analytical engine at our core:
+  federation (`ATTACH`), file formats, Iceberg/Delta, encryption, autocomplete.
+- **[Open Data Contract Standard](https://bitol-io.github.io/open-data-contract-standard/)** /
+  [datacontract.com](https://datacontract-specification.com/) — the contract format `charter.yaml` speaks.
+- **[Model Context Protocol](https://modelcontextprotocol.io)** — the open protocol
+  the `datacharter mcp` server speaks to agents and MCP clients.
+- **[Vega-Lite](https://vega.github.io/vega-lite/)** — declarative charting.
+- **[Monaco Editor](https://microsoft.github.io/monaco-editor/)** — the SQL editor.
+- **[TanStack Table & Virtual](https://tanstack.com/)** — the virtualized results grid.
+- And the Python & React ecosystems — FastAPI, pydantic, httpx, keyring, and
+  ruamel.yaml on the backend; React and Vite on the front.
+
+Testing uses **[VidaiMock](https://github.com/vidaiUK/VidaiMock)**, an
+Apache-2.0 mock LLM server, as the offline agent endpoint in CI.
+
+DuckDB is a trademark of the DuckDB Foundation. DataCharter is an independent
+project and is not affiliated with or endorsed by the DuckDB Foundation.
+
+## License
+
+[Apache-2.0](LICENSE)