Metadata-Version: 2.4
Name: dbt-agent-layer
Version: 0.1.8
Summary: Make your dbt metrics queryable by AI agents via MCP
Project-URL: Homepage, https://github.com/dbt-agent-layer/dbt-agent-layer
Project-URL: Documentation, https://github.com/dbt-agent-layer/dbt-agent-layer#readme
Project-URL: Repository, https://github.com/dbt-agent-layer/dbt-agent-layer
License: Apache-2.0
Keywords: agents,analytics,dbt,llm,mcp,metrics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dateutil>=2.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: asyncpg>=0.29; extra == 'all'
Requires-Dist: duckdb>=0.10; extra == 'all'
Requires-Dist: google-cloud-bigquery>=3.0; extra == 'all'
Requires-Dist: openai>=1.30; extra == 'all'
Requires-Dist: snowflake-connector-python>=3.0; extra == 'all'
Provides-Extra: bigquery
Requires-Dist: google-cloud-bigquery>=3.0; extra == 'bigquery'
Provides-Extra: chat
Requires-Dist: anthropic>=0.40; extra == 'chat'
Requires-Dist: openai>=1.30; extra == 'chat'
Provides-Extra: dev
Requires-Dist: anthropic>=0.40; extra == 'dev'
Requires-Dist: duckdb>=0.10; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: openai>=1.30; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-mock>=3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: duckdb
Requires-Dist: duckdb>=0.10; extra == 'duckdb'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
Provides-Extra: snowflake
Requires-Dist: snowflake-connector-python>=3.0; extra == 'snowflake'
Description-Content-Type: text/markdown

# dbt-agent-layer

> Make your dbt metrics queryable by AI agents via MCP.

```bash
pip install dbt-agent-layer
cd my_dbt_project
dbt-agent serve
# → MCP server running, connect Claude Desktop, ask questions grounded in real data
```

---

## Quick start

```bash
# 1. Install
pip install "dbt-agent-layer[duckdb]"   # or [postgres], [bigquery], [snowflake]

# 2. Initialise (inside your dbt project)
cd my_dbt_project
dbt-agent init

# 3. Build tool registry
dbt-agent build

# 4. Start the MCP server
dbt-agent serve
```

---

## How it works

```
dbt project on disk
       ↓
[Parser] reads manifest.json + schema.yml + metrics.yml
       ↓
[Generator] produces async Python tool functions per metric
       ↓
[MCP Server] registers tools, starts server
       ↓
MCP client (Claude Desktop, any agent) calls tool
       ↓
[Executor] runs SQL against your warehouse
       ↓
[Delta + Narrative] enriches raw number with context
       ↓
MetricResult returned to agent (value + delta + narrative + anomaly flag)
```

---

## Supported warehouses

| Adapter    | Install extra          | dbt adapter      |
|------------|------------------------|------------------|
| DuckDB     | `[duckdb]`             | `dbt-duckdb`     |
| PostgreSQL | `[postgres]`           | `dbt-postgres`   |
| BigQuery   | `[bigquery]`           | `dbt-bigquery`   |
| Snowflake  | `[snowflake]`          | `dbt-snowflake`  |

### dbt version compatibility

| dbt version | Metric format    | Support |
|-------------|------------------|---------|
| < 1.0       | None             | Warns, skips gracefully |
| 1.0 – 1.5   | Legacy `metrics:` | Full support |
| 1.6+        | Semantic layer    | Full support |
| dbt Cloud   | Artifact API      | Roadmap (v0.2) |

---

## Claude Desktop setup

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "dbt-metrics": {
      "command": "dbt-agent",
      "args": ["serve", "--project-dir", "/path/to/your/dbt/project"],
      "env": {}
    }
  }
}
```

Restart Claude Desktop. You can now ask:
- *"What's our MRR this month vs last month?"*
- *"Show me revenue broken down by channel for Q1 2024."*
- *"Is churn rate anomalous this month?"*

---

## Configuration reference (`dbt-agent.yml`)

```yaml
version: 1

project:
  dir: "."                      # path to dbt project
  profiles_dir: "~/.dbt"        # path to profiles.yml
  target: "dev"                 # dbt target to use

adapter:
  type: postgres                # postgres | bigquery | snowflake | duckdb
  # Connection details pulled from profiles.yml automatically.
  # Override individual fields here if needed.

server:
  host: "0.0.0.0"
  port: 8000
  transport: "stdio"            # stdio (Claude Desktop) | http (web clients)

metrics:
  include: []                   # empty = all metrics
  exclude: []                   # metric names to hide from agents
  default_period: "current_month"
  compare_to: "prior_period"    # prior_period | prior_year

narratives:
  enabled: true
  style: "concise"              # concise | detailed
```

### Environment variable overrides

| Variable                  | Description                    |
|---------------------------|--------------------------------|
| `DBT_AGENT_ADAPTER_TYPE`  | Override adapter type          |
| `DBT_AGENT_PORT`          | Override server port           |
| `DBT_AGENT_TRANSPORT`     | Override transport (stdio/http)|
| `DBT_AGENT_TARGET`        | Override dbt target            |
| `DBT_AGENT_PROFILES_DIR`  | Override profiles directory    |

---

## CLI reference

### `dbt-agent init`
Detect your dbt project, auto-detect the warehouse adapter, and create `dbt-agent.yml`.

```
dbt-agent init [--project-dir PATH] [--adapter postgres|bigquery|snowflake|duckdb]
```

### `dbt-agent build`
Parse `manifest.json`, extract all metric definitions, write `dbt_agent_tools/manifest_cache.json`.

```
dbt-agent build [--project-dir PATH] [--skip-compile] [--dry-run] [--verbose]
```

### `dbt-agent serve`
Start the MCP server with all metrics registered as callable tools.

```
dbt-agent serve [--project-dir PATH] [--port INT] [--transport stdio|http] [--skip-build] [--reload]
```

---

## Built-in MCP tools (always available)

| Tool             | Description                                              |
|------------------|----------------------------------------------------------|
| `list_metrics`   | List all available metrics with dimensions               |
| `describe_metric`| Full metadata for a named metric                         |
| `query_metric`   | Generic query when metric name is dynamic                |
| `get_<name>`     | Auto-generated per-metric tool (e.g. `get_monthly_revenue`) |

Each auto-generated tool returns a `MetricResult` containing:
- `value` + `formatted_value` (e.g. `"$142,500"`)
- `delta` — period-over-period comparison
- `narrative` — factual one-sentence summary
- `anomaly` — statistical anomaly flag (>2σ from baseline)
- `breakdown` — dimension breakdown rows (if `breakdown_by` used)
- `sql_executed` — exact SQL run (for debugging)

---

## Adding a new adapter

1. Create `dbt_agent_layer/executor/mydb_exec.py` implementing `BaseExecutor`:
   ```python
   from .base import BaseExecutor

   class MyDBExecutor(BaseExecutor):
       async def execute(self, sql: str) -> list[dict]: ...
       async def test_connection(self) -> bool: ...
       def get_adapter_type(self) -> str: return "mydb"
   ```
2. Add a case to `executor/factory.py`:`get_executor()`.
3. Add optional dependency to `pyproject.toml`.
4. Open a PR — contributions welcome!

---

## Development

```bash
git clone https://github.com/dbt-agent-layer/dbt-agent-layer
cd dbt-agent-layer
pip install -e ".[dev,duckdb]"
pytest
ruff check .
mypy dbt_agent_layer/
```

---

## License

Apache 2.0 — see [LICENSE](LICENSE).

---

## Roadmap

- v0.2: Result caching, dbt Cloud artifact API, web UI
- Cloud tier: Team collaboration, audit logs, SSO
