Metadata-Version: 2.4
Name: valved
Version: 0.1.1
Summary: AI-first data engineering framework. Control the flow of your data.
Project-URL: Homepage, https://github.com/valved-labs/valved
Project-URL: Repository, https://github.com/valved-labs/valved
Project-URL: Issues, https://github.com/valved-labs/valved/issues
Author: Valved contributors
License: Apache-2.0
License-File: LICENSE
Keywords: agents,anthropic,data-engineering,dbt,snowflake
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: alembic>=1.13
Requires-Dist: anthropic>=0.34
Requires-Dist: argon2-cffi>=23.1
Requires-Dist: croniter>=2.0
Requires-Dist: cryptography>=42
Requires-Dist: dlt>=1.0
Requires-Dist: duckdb>=1.0
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: mcp<2,>=1.28
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: pydantic>=2.6
Requires-Dist: pygments>=2.15
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: snowflake-connector-python>=3.7
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: sqlglot>=25
Requires-Dist: sqlparse>=0.5
Requires-Dist: tomlkit>=0.13
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: watchdog>=4.0
Provides-Extra: dbt-test
Requires-Dist: dbt-core>=1.8; extra == 'dbt-test'
Requires-Dist: dbt-duckdb>=1.8; extra == 'dbt-test'
Provides-Extra: dev
Requires-Dist: hatchling>=1.24; extra == 'dev'
Requires-Dist: html5lib>=1.1; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: openapi-spec-validator>=0.7; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: testcontainers[postgres]>=4.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Valved

[![CI](https://github.com/valved-labs/valved/actions/workflows/ci.yml/badge.svg)](https://github.com/valved-labs/valved/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/valved.svg)](https://pypi.org/project/valved/)
[![Python](https://img.shields.io/pypi/pyversions/valved.svg)](https://pypi.org/project/valved/)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](./LICENSE)

**Agent-native data engineering, from natural language to production pipelines.**

Valved takes a goal in plain English — *"make `stg_orders` incremental"*, *"ingest the Stripe charges API into a Snowflake table"* — turns it into a **reviewable plan**, and, when you approve, materializes the working code and opens a **pull request** in your repo: dbt models, Python `dlt` sources, SQL, tests, schema docs. All the boring parts of building and maintaining a warehouse pipeline, executed by agents that read your conventions and respect your existing project. It's an AI-first, open-source **control plane** over `dlt` + `dbt` — self-hosted, Apache 2.0.

> **Status: `v0.1.0` — the first release.** The full loop (`init → plan → build → run → deploy → schedule`) is built and green across 3,000+ tests, with CLI / REST / MCP parity. Pre-1.0: it's usable and complete, with room to refine the API before committing to 1.0 stability.

## Install

```bash
pip install valved
```

Requires Python 3.11+. Valved runs against your own Postgres (a bundled `docker compose` is scaffolded for you) and your own warehouse (Snowflake is first-class).

## Quickstart

```bash
valved init --with-dbt              # scaffold a dlt + dbt project (+ bundled Postgres)
docker compose up -d                # start the state store
cp .env.example .env                # add ANTHROPIC_API_KEY + your Snowflake target

# intent → reviewable plan → working code
valved plan "ingest the Stripe charges API into raw_stripe, then a staging model stg_charges"
valved build <plan_id>              # writes the dlt source, the dbt model, and pipelines/<name>.toml
valved run <pipeline> --watch       # execute on demand; data lands in your warehouse
valved deploy <pipeline>            # open a reviewable PR with the built code (default handoff)
```

`valved` auto-loads a project-local `.env` on startup (existing shell vars win). Set `VALVED_NO_DOTENV=1` to disable it if you manage env vars elsewhere (direnv, mise, 1Password CLI).

## What it does

**The core loop** — every step is a `valved` verb, with a REST + MCP equivalent:

- **`plan` → `build`** — an AI harness turns intent into a reviewable Plan, then materializes it (dlt sources, dbt models, pipeline composition). It verifies by *executing*, not guessing. `plan-and-build` is the one-shot path.
- **`run` / `serve` / `worker`** — on-demand and **scheduled** execution over a durable job queue + worker pool (cron scheduler, crash-recovery reaper, graceful drain).
- **`deploy`** — promote built code to version control via a **configurable handoff** (`files → commit → push → pr`, default PR), including **cross-repo linked PRs**. Valved opens and orders the PRs; you merge.
- **`ask`** — a read-only **investigative explorer**: *"where does `net_revenue` come from?"*, *"what breaks if I change `raw_stripe.charges`?"* — answered with citations by investigating dbt's manifest + dlt's schema + your code.
- **Recovery** — when a scheduled run fails, Valved **diagnoses** it (grounded in dlt's real exceptions) and **proposes a reviewable fix** — it never writes to prod autonomously.

**Surfaces** — the same functionality, four ways:

- **CLI** — the full `valved` command set ([reference](./specs/reference/cli-reference.md)).
- **REST API** — FastAPI with full CLI parity, auth, streaming, webhooks (`/api/openapi.json`).
- **MCP server** — auto-generated from REST; drive Valved from Claude Desktop / Cursor / Claude Code (`valved mcp-serve`).
- **Static HTML UI** — run history + per-run logs (`valved docs serve`).

## Documentation

- **First run:** [with bundled Postgres](./docs/first-run-with-bundled-postgres.md) · [with external Postgres](./docs/first-run-with-external-postgres.md) · [installation](./docs/installation.md)
- **Reference:** [CLI](./specs/reference/cli-reference.md) · [config schema](./specs/reference/config-schema.md) · [glossary](./specs/reference/glossary.md)
- **Design:** [`specs/PRD.md`](./specs/PRD.md) (what/why) · [`specs/ARCHITECTURE.md`](./specs/ARCHITECTURE.md) (how) · [`specs/DELIVERY.md`](./specs/DELIVERY.md) (build history)

## Open source & governance

Valved is **Apache 2.0** and feature-complete for single-team self-hosters — **no API endpoints or MCP tools are gated** behind any commercial offering. See [`OSS_COMMITMENT.md`](./OSS_COMMITMENT.md) for what's permanently open, and [`governance`](./specs/reference/governance.md) for the model.

## Contributing

Contributions welcome — DCO sign-off (`git commit -s`), dev setup, and PR expectations are in [`CONTRIBUTING.md`](./CONTRIBUTING.md). Report security issues privately (see [`SECURITY.md`](./SECURITY.md)).

## License

Apache 2.0. See [`LICENSE`](./LICENSE).
