dbt-agent-layer 0.1.0__tar.gz

dbt_agent_layer-0.1.0/.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip install:*)",
+      "Bash(pip3 install:*)",
+      "Bash(python3 -m pip --version)",
+      "Read(//usr/local/bin/**)",
+      "Read(//opt/homebrew/bin/**)",
+      "Read(//Users/abdeljalilsadouk/.pyenv/**)",
+      "Read(//Users/abdeljalilsadouk/Library/Python/**)",
+      "Bash(command -v uv)",
+      "Bash(command -v pipx)",
+      "Bash(uv venv:*)",
+      "Bash(source .venv/bin/activate)",
+      "Bash(uv pip:*)",
+      "Bash(python -m pytest tests/ -x -q)",
+      "Bash(python -m pytest tests/ -q)",
+      "Bash(dbt-agent --help)",
+      "Bash(python -m pip show build twine)",
+      "Bash(python -m build)"
+    ]
+  }
+}

dbt_agent_layer-0.1.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: dbt-agent-layer
+Version: 0.1.0
+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: asyncpg>=0.29; extra == 'all'
+Requires-Dist: duckdb>=0.10; extra == 'all'
+Requires-Dist: google-cloud-bigquery>=3.0; 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: dev
+Requires-Dist: duckdb>=0.10; extra == 'dev'
+Requires-Dist: mypy>=1.10; 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

dbt_agent_layer-0.1.0/README.md

@@ -0,0 +1,224 @@
+# 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