Metadata-Version: 2.4
Name: dbt-cortex-agent
Version: 0.0.5
Summary: dbt-native Snowflake Cortex Agent materialization with skill and evaluation tooling
Author: Jeremy Demlow
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Jeremy-Demlow/dbt-cortex-agent
Project-URL: Documentation, https://github.com/Jeremy-Demlow/dbt-cortex-agent/tree/v0.0.5/docs
Project-URL: Repository, https://github.com/Jeremy-Demlow/dbt-cortex-agent.git
Project-URL: Issues, https://github.com/Jeremy-Demlow/dbt-cortex-agent/issues
Requires-Python: <4,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7,>=6.0
Provides-Extra: test
Requires-Dist: build>=1.2; extra == "test"
Requires-Dist: Jinja2<4,>=3.1; extra == "test"
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "test"
Provides-Extra: runtime
Requires-Dist: snowflake-connector-python<5,>=3.18; extra == "runtime"
Dynamic: license-file

# dbt_cortex_agent

`dbt_cortex_agent` 0.0.5 is a Snowflake-only dbt package and Python companion for
defining, versioning, and evaluating Cortex Agents from dbt models. A
`materialized='cortex_agent'` model body is the native Agent YAML specification.
dbt owns the complete Agent lifecycle; Python is limited to local skill files,
runtime smoke, and evaluation coordination.

## Install one immutable version on two surfaces

Install the Python companion from PyPI:

```bash
pipx install 'dbt-cortex-agent[runtime]==0.0.5'
```

For a managed Python environment, use:

```bash
python -m pip install 'dbt-cortex-agent[runtime]==0.0.5'
```

dbt does not install packages from PyPI. Pin the dbt package separately to the
public HTTPS `v0.0.5` Git tag in `packages.yml`:

```yaml
packages:
  - git: "https://github.com/Jeremy-Demlow/dbt-cortex-agent.git"
    revision: v0.0.5
```

PyPI version `0.0.5` and Git tag `v0.0.5` identify the same immutable release
across the CLI and dbt surfaces. Run `dbt deps`, then
`dbt-cortex-agent doctor --project-dir . --json`; `doctor` verifies that the CLI,
declared dbt dependency, and installed consumer dbt package versions align. A
full immutable Git SHA is accepted only when actual installed package metadata
under `dbt_packages/dbt_cortex_agent` reports the matching version; a source
checkout's root `dbt_project.yml` is not installation evidence. The supported
runtime is Python `>=3.10,<4`, dbt
`>=1.10,<2.0`, and `dbt-snowflake`; see [compatibility](docs/reference/compatibility.md)
and [installation](docs/getting-started/installation.md).

The CLI also requires the Snowflake CLI (`snow`) on `PATH`; `doctor` checks both
the `dbt` and `snow` executables. By default, `dbt-cortex-agent init` configures an existing
dbt project by appending missing dependency and safety-variable entries. It does
not create a dbt project or scaffold Agent models, semantic views, evaluation
models, seeds, or skill files.

For the fixed synthetic tutorial, preview the package-owned Orders starter in an
existing dbt project:

```bash
dbt-cortex-agent init --project-dir . --starter orders \
  --package-source https://github.com/Jeremy-Demlow/dbt-cortex-agent.git --json
```

The preview reports the exact seed, semantic-view, Agent, optional eval, dependency, and
`.dbtignore` actions without writing. After review, add `--apply`. The command
validates every destination before writing, keeps identical files unchanged,
and fails closed if any generated file already has different content. It has no
force mode and is not a generic project or Agent wizard.

## Five-minute non-mutating quickstart

From a consumer dbt project with a full-body Agent model:

```bash
dbt-cortex-agent doctor --project-dir . --target sandbox --json
dbt-cortex-agent manifest validate --project-dir . --target sandbox --json
dbt compile --select orders_assistant
```

These commands do not mutate Snowflake. `dbt compile` renders and validates the
full Agent body without invoking its materialization. Follow the
[quickstart](docs/getting-started/quickstart.md) to create the metadata and
bootstrap explicit allowlists.

For Cortex Code-guided adoption, use the project-local
[`dbt-cortex-agent-project` skill](.cortex/skills/dbt-cortex-agent-project/SKILL.md).
It discovers an existing dbt project, establishes objective/levers/data/proof,
and guides an existing semantic view, the fixed Orders starter, or an existing
Agent into dbt-owned metadata. It is script-free, shows manual 0.0.5 command
parity, and stops separately before local writes, Snowflake mutation/runtime,
paid evaluation, and baseline movement. The checked-in skill is not a claim of
catalog publication or live Snowflake verification.

## Controlled deploy

Deploy selected Agents and their declared skills through one package workflow:

```bash
dbt-cortex-agent agent deploy --project-dir . --target sandbox \
  --agent orders_assistant --connection sandbox --database ANALYTICS_DEV \
  --allow-target sandbox --allow-database ANALYTICS_DEV --apply
```

The model relation determines the physical Agent FQN. The model body is passed
directly to the materialization, which validates explicit orchestration, checks
staged skills, updates LIVE, commits immutable `VERSION$N`, and reconciles the
configured alias. The package preflights and uploads selected skills before it
invokes the dbt dependency closure. dbt remains the sole Agent DDL authority.
No Makefile or copied adopter Python script is required.

A target-resolved manifest may contain Agents in multiple approved databases.
The package carries each selected Agent's complete `database.schema.object`
identity through skill and runtime operations and validates every Agent, stage,
eval table, evaluation stage, and result database against repeatable allowlists.

```text
one dbt target manifest
  +-- FINANCE.AGENTS.FINANCE_ANALYST
  +-- MARKETING.AGENTS.CAMPAIGN_ANALYST
  +-- AI_FOCUS.AGENTS.ENTERPRISE_ASSISTANT

selected resource FQN -> allowlist validation -> bounded operation
```

One package invocation consumes one dbt target and its fresh manifest. Parsing
and coordinating several dbt targets belongs to adopter CI, where each target
has a separately reviewed role, warehouse, and approval boundary.
Read [lifecycle](docs/guides/lifecycle.md) and [Snowflake setup](docs/getting-started/snowflake-setup.md)
before crossing this boundary.

## CLI or dbt macros

| Need | Shipped CLI | Public dbt macro |
|---|---|---|
| Diagnose a project | `doctor` | — |
| Validate resolved metadata | `manifest validate` | `cortex_agent__validate` |
| Render the full Agent spec | — | `dbt compile --select <agent_model>` |
| Deploy/version an Agent | `agent deploy` | `dbt build --select <agent_model>` |
| Preview/invoke any Agent | `agent smoke` | — |
| Plan/upload/smoke skills | `skill plan/upload/smoke` | deploy validates staged skills |
| Render/run optional evaluation | `eval run`, `eval verify` | `cortex_eval__execution_plan`, `cortex_eval__run` |
| Compare/gate/accept artifacts | `eval compare/gate/accept-baseline` | threshold macros only |

Use dbt for Agent render and deployment. Use Python when local file upload,
stable process exits/JSON, connector clients, or durable evaluation artifacts
are required. Python owns no Agent lifecycle operation and provisions no stage.

## Lifecycle and evaluation

The materialization validates and hashes the rendered spec plus staged skills,
skips unchanged versions, modifies LIVE, commits an immutable version, and
applies the requested alias. Promotion, rollback, grants, MCP attachment, and
skill smoke remain explicit operations.

Evaluation is optional and targets the same Agent selected by the model relation.
`eval run` is a client for that already deployed Agent, a materialized
eval table, and an evaluation stage; `--apply` incurs Cortex spend. It never
deploys or changes an Agent. It writes candidate JSON with plan identity,
ordered ground-truth refs, policy, and pre/post DEFAULT provenance for threshold
and accepted-baseline gates. See [evaluations](docs/guides/evaluations.md).

For a complete evaluation workflow, `eval verify` materializes and tests the
selected eval model, executes native evaluation, consumes the exact candidate,
and applies intrinsic thresholds or an established baseline. Preview is free;
`--apply` is paid. Baseline acceptance remains a separate explicit command.

## Documentation

- Start: [installation](docs/getting-started/installation.md), [quickstart](docs/getting-started/quickstart.md), [Snowflake setup](docs/getting-started/snowflake-setup.md)
- Configure: [configuration model](docs/guides/configuration-model.md), [Agent metadata](docs/reference/agent-metadata.md), [eval metadata](docs/reference/eval-metadata.md), [variables](docs/reference/variables.md)
- Operate: [lifecycle](docs/guides/lifecycle.md), [skills](docs/guides/skills.md), [evaluations](docs/guides/evaluations.md), [CI](docs/guides/ci.md), [releasing](docs/guides/releasing.md)
- Reference: [CLI](docs/reference/cli.md), [macros](docs/reference/macros.md), [compatibility](docs/reference/compatibility.md), [architecture](docs/concepts/end-to-end-flow.md), [troubleshooting](docs/troubleshooting.md)
- Change: [changelog](CHANGELOG.md)

## Limitations and policies

- Snowflake and dbt Core with `dbt-snowflake` are the release authority; DuckDB is unsupported and Fusion is advisory.
- `dbt build --select <agent_model>` deploys model Agents; `dbt compile` is the non-mutating preview.
- Property YAML may use `target`, `var`, and `env_var`, but cannot call package macros.
- Skills and MCP connectors are excluded from built-in native Agent Evaluation and require separate smoke/integration proof.
- Live mutation, runtime smoke, and evaluation spend are never default operations.
- This independent, maintainer-led package is not sponsored, endorsed, supported, or maintained by Snowflake Inc.

Apache License 2.0. See [LICENSE](LICENSE), [contributing](CONTRIBUTING.md),
[security](SECURITY.md), [support](SUPPORT.md), and [Code of Conduct](CODE_OF_CONDUCT.md).
