dbt-agent-layer 0.1.0__py3-none-any.whl

dbt_agent_layer/__init__.py

@@ -0,0 +1,3 @@
+"""dbt-agent-layer: Make your dbt metrics queryable by AI agents via MCP."""
+
+__version__ = "0.1.0"

dbt_agent_layer/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI entrypoint."""
+
+from .main import cli
+
+__all__ = ["cli"]

dbt_agent_layer/cli/build.py

@@ -0,0 +1,138 @@
+"""dbt-agent build command."""
+
+import json
+import subprocess
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+@click.command()
+@click.option(
+    "--project-dir",
+    default=".",
+    show_default=True,
+    help="Path to dbt project directory.",
+    type=click.Path(file_okay=False),
+)
+@click.option(
+    "--skip-compile",
+    is_flag=True,
+    default=False,
+    help="Use existing manifest.json; skip dbt compile.",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Print what would be generated; write nothing.",
+)
+@click.option(
+    "--verbose",
+    is_flag=True,
+    default=False,
+    help="Print each metric as it is parsed.",
+)
+def build_cmd(
+    project_dir: str,
+    skip_compile: bool,
+    dry_run: bool,
+    verbose: bool,
+) -> None:
+    """Parse the dbt project and generate MCP tool metadata."""
+    from ..config.settings import load_config
+    from ..parser.project import DbtProject
+    from ..parser.manifest import DbtManifest
+
+    project_path = Path(project_dir).expanduser().resolve()
+    config = load_config(str(project_path))
+
+    # 1. Compile dbt if needed
+    if not skip_compile:
+        with console.status("[bold blue]Running dbt compile...[/bold blue]"):
+            result = subprocess.run(
+                ["dbt", "compile", "--project-dir", str(project_path)],
+                capture_output=True,
+                text=True,
+            )
+        if result.returncode != 0:
+            console.print("[yellow]dbt compile failed — trying existing manifest.json[/yellow]")
+            console.print(f"[dim]{result.stderr[:500]}[/dim]")
+
+    # 2. Find manifest
+    try:
+        dbt_project = DbtProject(str(project_path))
+        manifest_path = dbt_project.find_manifest()
+    except FileNotFoundError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise SystemExit(1)
+
+    # 3. Parse metrics
+    with console.status("[bold blue]Parsing metrics...[/bold blue]"):
+        manifest = DbtManifest(str(manifest_path))
+        metrics = manifest.get_metrics()
+
+    # Apply include/exclude
+    if config.include_metrics:
+        metrics = [m for m in metrics if m.name in config.include_metrics]
+    if config.exclude_metrics:
+        metrics = [m for m in metrics if m.name not in config.exclude_metrics]
+
+    if verbose:
+        for m in metrics:
+            console.print(
+                f"  [green]✓[/green] [bold]{m.name}[/bold] "
+                f"({m.type}) — {m.description or m.label}"
+            )
+
+    # 4. Write manifest cache
+    output_dir = project_path / "dbt_agent_tools"
+    if not dry_run:
+        output_dir.mkdir(exist_ok=True)
+        cache = {
+            "generated_at": __import__("datetime").datetime.now(__import__("datetime").timezone.utc).isoformat(),
+            "manifest_format": manifest.metric_format,
+            "metrics": [
+                {
+                    "name": m.name,
+                    "label": m.label,
+                    "description": m.description,
+                    "type": m.type,
+                    "sql": m.sql,
+                    "measure": m.measure,
+                    "model": m.model,
+                    "dimensions": m.dimensions,
+                    "timestamp_column": m.timestamp_column,
+                    "filters": m.filters,
+                    "meta": m.meta,
+                    "warehouse_table": m.warehouse_table,
+                    "format": m.format,
+                    "currency": m.currency,
+                }
+                for m in metrics
+            ],
+        }
+        cache_path = output_dir / "manifest_cache.json"
+        cache_path.write_text(json.dumps(cache, indent=2))
+
+    # 5. Summary table
+    table = Table(title="Metrics discovered", show_lines=True)
+    table.add_column("Name", style="cyan")
+    table.add_column("Label")
+    table.add_column("Type", style="dim")
+    table.add_column("Dimensions", style="dim")
+
+    for m in metrics:
+        table.add_row(m.name, m.label, m.type, ", ".join(m.dimensions) or "—")
+
+    console.print(table)
+
+    action = "Would generate" if dry_run else "Generated"
+    console.print(
+        f"\n[bold green]{action}[/bold green] [bold]{len(metrics)}[/bold] metric tools"
+        + (f" → [cyan]{output_dir}[/cyan]" if not dry_run else "")
+    )

dbt_agent_layer/cli/init.py

@@ -0,0 +1,74 @@
+"""dbt-agent init command."""
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+
+@click.command()
+@click.option(
+    "--project-dir",
+    default=".",
+    show_default=True,
+    help="Path to dbt project directory.",
+    type=click.Path(exists=True, file_okay=False),
+)
+@click.option(
+    "--adapter",
+    default=None,
+    help="Warehouse adapter (postgres|bigquery|snowflake|duckdb). Auto-detected if not set.",
+    type=click.Choice(["postgres", "bigquery", "snowflake", "duckdb"], case_sensitive=False),
+)
+def init_cmd(project_dir: str, adapter: str | None) -> None:
+    """Initialise dbt-agent-layer in a dbt project."""
+    import yaml
+
+    from ..config.settings import write_default_config, _detect_adapter_from_profiles
+
+    project_path = Path(project_dir).expanduser().resolve()
+
+    # Detect dbt project
+    dbt_project_yml = project_path / "dbt_project.yml"
+    if not dbt_project_yml.exists():
+        console.print(
+            f"[red]Error:[/red] dbt_project.yml not found in {project_path}. "
+            "Are you inside a dbt project directory?"
+        )
+        raise SystemExit(1)
+
+    with open(dbt_project_yml) as f:
+        dbt_cfg = yaml.safe_load(f) or {}
+    project_name = dbt_cfg.get("name", "unknown")
+
+    # Auto-detect adapter from profiles.yml
+    detected_adapter = adapter
+    if not detected_adapter:
+        target = dbt_cfg.get("target", "dev")
+        for profiles_dir in [project_path, Path.home() / ".dbt"]:
+            profiles_path = profiles_dir / "profiles.yml"
+            if profiles_path.exists():
+                detected_adapter, _ = _detect_adapter_from_profiles(profiles_path, target)
+                break
+        detected_adapter = detected_adapter or "duckdb"
+
+    # Write config
+    config_path = write_default_config(str(project_path), adapter_type=detected_adapter)
+
+    console.print(
+        Panel(
+            f"[bold green]dbt-agent-layer initialised[/bold green]\n\n"
+            f"  dbt project : [cyan]{project_name}[/cyan]\n"
+            f"  adapter     : [cyan]{detected_adapter}[/cyan]\n"
+            f"  config      : [cyan]{config_path}[/cyan]\n\n"
+            "[bold]Next steps:[/bold]\n"
+            "  1. Edit [cyan]dbt-agent.yml[/cyan] if needed\n"
+            "  2. Run [bold]dbt-agent build[/bold] to generate tools\n"
+            "  3. Run [bold]dbt-agent serve[/bold] to start the MCP server",
+            title="dbt-agent init",
+            border_style="green",
+        )
+    )

dbt_agent_layer/cli/main.py

@@ -0,0 +1,18 @@
+"""Main CLI entrypoint — groups all dbt-agent commands."""
+
+import click
+
+from .init import init_cmd
+from .build import build_cmd
+from .serve import serve_cmd
+
+
+@click.group()
+@click.version_option(package_name="dbt-agent-layer")
+def cli() -> None:
+    """dbt-agent-layer: Make your dbt metrics queryable by AI agents via MCP."""
+
+
+cli.add_command(init_cmd, name="init")
+cli.add_command(build_cmd, name="build")
+cli.add_command(serve_cmd, name="serve")

dbt_agent_layer/cli/serve.py

@@ -0,0 +1,181 @@
+"""dbt-agent serve command."""
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+logger = logging.getLogger(__name__)
+
+
+@click.command()
+@click.option(
+    "--project-dir",
+    default=".",
+    show_default=True,
+    help="Path to dbt project directory.",
+    type=click.Path(file_okay=False),
+)
+@click.option(
+    "--port",
+    default=None,
+    type=int,
+    help="Override port from dbt-agent.yml (default: 8000).",
+)
+@click.option(
+    "--transport",
+    default=None,
+    type=click.Choice(["stdio", "http"], case_sensitive=False),
+    help="MCP transport: stdio (Claude Desktop) or http.",
+)
+@click.option(
+    "--skip-build",
+    is_flag=True,
+    default=False,
+    help="Use existing ./dbt_agent_tools/; skip build step.",
+)
+@click.option(
+    "--reload",
+    is_flag=True,
+    default=False,
+    help="Hot-reload on dbt project changes (dev mode).",
+)
+def serve_cmd(
+    project_dir: str,
+    port: int | None,
+    transport: str | None,
+    skip_build: bool,
+    reload: bool,
+) -> None:
+    """Start the MCP server exposing all dbt metrics as callable tools."""
+    from ..config.settings import load_config
+    from ..executor.factory import get_executor
+    from ..parser.models import DbtMetric
+
+    project_path = Path(project_dir).expanduser().resolve()
+    config = load_config(str(project_path))
+
+    # Override config from CLI flags
+    if port is not None:
+        config.port = port
+    if transport is not None:
+        config.transport = transport
+
+    # --- Build step ---
+    metrics = _load_metrics(project_path, skip_build, config)
+
+    if not metrics:
+        console.print(
+            "[yellow]Warning:[/yellow] No metrics found. "
+            "Run [bold]dbt-agent build[/bold] or check your dbt project for metrics: blocks."
+        )
+
+    # --- Executor ---
+    try:
+        executor = get_executor(config)
+    except Exception as e:
+        console.print(f"[red]Error creating executor:[/red] {e}")
+        raise SystemExit(1)
+
+    # --- Test connection ---
+    async def _test():
+        return await executor.test_connection()
+
+    ok = asyncio.run(_test())
+    if not ok:
+        console.print(
+            f"[yellow]Warning:[/yellow] Could not connect to {config.adapter_type}. "
+            "Metric queries will fail until the connection is available."
+        )
+
+    # --- Create MCP server ---
+    from ..mcp.server import create_server
+
+    server = create_server(metrics, executor, config)
+
+    console.print(
+        Panel(
+            f"[bold green]dbt-agent-layer MCP server starting[/bold green]\n\n"
+            f"  metrics   : [cyan]{len(metrics)}[/cyan]\n"
+            f"  adapter   : [cyan]{config.adapter_type}[/cyan]\n"
+            f"  transport : [cyan]{config.transport}[/cyan]\n"
+            + (f"  port      : [cyan]{config.port}[/cyan]\n" if config.transport == "http" else "")
+            + "\n[bold]Connect with Claude Desktop:[/bold]\n"
+            '  Add to claude_desktop_config.json → mcpServers → "dbt-metrics"',
+            title="dbt-agent serve",
+            border_style="blue",
+        )
+    )
+
+    # --- Start server ---
+    if config.transport == "http":
+        server.run(transport="streamable-http", host=config.host, port=config.port)
+    else:
+        server.run(transport="stdio")
+
+
+def _load_metrics(
+    project_path: Path, skip_build: bool, config: "AgentConfig"  # noqa: F821
+) -> list["DbtMetric"]:  # noqa: F821
+    """Load metrics from manifest cache or by running the build step."""
+    from ..parser.models import DbtMetric
+
+    # Try cached manifest first if skip_build
+    cache_path = project_path / "dbt_agent_tools" / "manifest_cache.json"
+    if skip_build and cache_path.exists():
+        try:
+            with open(cache_path) as f:
+                cache = json.load(f)
+            metrics = []
+            for m in cache.get("metrics", []):
+                metrics.append(
+                    DbtMetric(
+                        name=m["name"],
+                        label=m["label"],
+                        description=m.get("description"),
+                        type=m.get("type", "simple"),
+                        sql=m.get("sql"),
+                        measure=m.get("measure"),
+                        model=m.get("model"),
+                        dimensions=m.get("dimensions", []),
+                        timestamp_column=m.get("timestamp_column"),
+                        filters=m.get("filters", []),
+                        meta=m.get("meta", {}),
+                        warehouse_table=m.get("warehouse_table"),
+                        format=m.get("format"),
+                        currency=m.get("currency"),
+                    )
+                )
+            console.print(
+                f"[dim]Loaded {len(metrics)} metrics from cache ({cache_path})[/dim]"
+            )
+            return metrics
+        except Exception as e:
+            console.print(f"[yellow]Cache load failed ({e}), rebuilding...[/yellow]")
+
+    # Build from manifest
+    from ..parser.project import DbtProject
+    from ..parser.manifest import DbtManifest
+
+    try:
+        dbt_project = DbtProject(str(project_path))
+        manifest_path = dbt_project.find_manifest()
+    except FileNotFoundError:
+        # Try schema file parsing as last resort
+        console.print(
+            "[yellow]manifest.json not found — scanning schema.yml files...[/yellow]"
+        )
+        from ..parser.semantic_layer import parse_schema_files
+        metrics = parse_schema_files(str(project_path))
+        return metrics
+
+    with console.status("[bold blue]Parsing metrics from manifest...[/bold blue]"):
+        manifest = DbtManifest(str(manifest_path))
+        metrics = manifest.get_metrics()
+
+    return metrics

dbt_agent_layer/config/__init__.py

@@ -0,0 +1,5 @@
+"""Config module."""
+
+from .settings import AgentConfig, load_config
+
+__all__ = ["AgentConfig", "load_config"]

dbt_agent_layer/config/settings.py

@@ -0,0 +1,183 @@
+"""Configuration loading and management for dbt-agent-layer."""
+
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentConfig:
+    """Full configuration for dbt-agent-layer."""
+
+    # dbt project
+    project_dir: str = "."
+    profiles_dir: str = "~/.dbt"
+    target: str = "dev"
+
+    # adapter
+    adapter_type: str = "duckdb"
+    adapter_kwargs: dict = field(default_factory=dict)
+
+    # server
+    host: str = "0.0.0.0"
+    port: int = 8000
+    transport: str = "stdio"
+
+    # metric behaviour
+    default_period: str = "current_month"
+    compare_to: str = "prior_period"
+    include_metrics: list[str] = field(default_factory=list)
+    exclude_metrics: list[str] = field(default_factory=list)
+
+    # narrative
+    narratives_enabled: bool = True
+    narrative_style: str = "concise"
+
+
+def _read_yaml(path: Path) -> dict:
+    """Read a YAML file, returning empty dict on failure."""
+    try:
+        with open(path) as f:
+            return yaml.safe_load(f) or {}
+    except FileNotFoundError:
+        return {}
+    except yaml.YAMLError as e:
+        logger.warning("Failed to parse YAML at %s: %s", path, e)
+        return {}
+
+
+def _detect_adapter_from_profiles(profiles_path: Path, target: str) -> tuple[str, dict]:
+    """
+    Read profiles.yml and extract adapter type + connection kwargs for a given target.
+    Returns ("duckdb", {}) as fallback.
+    """
+    profiles = _read_yaml(profiles_path)
+    for profile_name, profile in profiles.items():
+        if not isinstance(profile, dict):
+            continue
+        outputs = profile.get("outputs", {})
+        if target in outputs:
+            cfg = outputs[target]
+            adapter = cfg.get("type", "duckdb")
+            return adapter, cfg
+        # also check any output if target not found
+        for output_name, cfg in outputs.items():
+            if isinstance(cfg, dict):
+                adapter = cfg.get("type", "duckdb")
+                return adapter, cfg
+    return "duckdb", {}
+
+
+def load_config(project_dir: str = ".") -> AgentConfig:
+    """
+    Load configuration with priority (highest to lowest):
+    1. Environment variables (DBT_AGENT_*)
+    2. dbt-agent.yml in project_dir
+    3. Auto-detection from dbt_project.yml + profiles.yml
+    4. Defaults
+
+    Environment variables:
+      DBT_AGENT_ADAPTER_TYPE
+      DBT_AGENT_PORT
+      DBT_AGENT_TRANSPORT
+      DBT_AGENT_TARGET
+      DBT_AGENT_PROFILES_DIR
+    """
+    project_path = Path(project_dir).expanduser().resolve()
+    config = AgentConfig(project_dir=str(project_path))
+
+    # --- Step 3: auto-detect from dbt_project.yml ---
+    dbt_project = _read_yaml(project_path / "dbt_project.yml")
+    if dbt_project:
+        config.target = dbt_project.get("target", config.target)
+
+    # --- Step 2: dbt-agent.yml ---
+    agent_yml = _read_yaml(project_path / "dbt-agent.yml")
+    if agent_yml:
+        proj = agent_yml.get("project", {})
+        config.project_dir = str(
+            (project_path / proj.get("dir", ".")).resolve()
+        )
+        config.profiles_dir = proj.get("profiles_dir", config.profiles_dir)
+        config.target = proj.get("target", config.target)
+
+        adapter = agent_yml.get("adapter", {})
+        if "type" in adapter:
+            config.adapter_type = adapter["type"]
+
+        server = agent_yml.get("server", {})
+        config.host = server.get("host", config.host)
+        config.port = int(server.get("port", config.port))
+        config.transport = server.get("transport", config.transport)
+
+        metrics = agent_yml.get("metrics", {})
+        config.include_metrics = metrics.get("include", config.include_metrics) or []
+        config.exclude_metrics = metrics.get("exclude", config.exclude_metrics) or []
+        config.default_period = metrics.get("default_period", config.default_period)
+        config.compare_to = metrics.get("compare_to", config.compare_to)
+
+        narratives = agent_yml.get("narratives", {})
+        config.narratives_enabled = narratives.get("enabled", config.narratives_enabled)
+        config.narrative_style = narratives.get("style", config.narrative_style)
+
+    # --- Auto-detect adapter from profiles.yml ---
+    profiles_dir = Path(config.profiles_dir).expanduser()
+    profiles_path = profiles_dir / "profiles.yml"
+    if profiles_path.exists():
+        detected_type, detected_kwargs = _detect_adapter_from_profiles(
+            profiles_path, config.target
+        )
+        if not agent_yml.get("adapter", {}).get("type"):
+            config.adapter_type = detected_type
+        config.adapter_kwargs = detected_kwargs
+
+    # --- Step 1: environment variables ---
+    if v := os.environ.get("DBT_AGENT_ADAPTER_TYPE"):
+        config.adapter_type = v
+    if v := os.environ.get("DBT_AGENT_PORT"):
+        config.port = int(v)
+    if v := os.environ.get("DBT_AGENT_TRANSPORT"):
+        config.transport = v
+    if v := os.environ.get("DBT_AGENT_TARGET"):
+        config.target = v
+    if v := os.environ.get("DBT_AGENT_PROFILES_DIR"):
+        config.profiles_dir = v
+
+    return config
+
+
+def write_default_config(project_dir: str, adapter_type: str = "duckdb") -> Path:
+    """Write a default dbt-agent.yml to project_dir."""
+    config_path = Path(project_dir) / "dbt-agent.yml"
+    content = f"""version: 1
+
+project:
+  dir: "."                      # path to dbt project
+  profiles_dir: "~/.dbt"        # path to profiles.yml
+  target: "dev"                 # dbt target to use
+
+adapter:
+  type: {adapter_type}           # postgres | bigquery | snowflake | duckdb
+
+server:
+  host: "0.0.0.0"
+  port: 8000
+  transport: "stdio"            # stdio | http (stdio for Claude Desktop)
+
+metrics:
+  include: []                   # empty = all metrics
+  exclude: []
+  default_period: "current_month"
+  compare_to: "prior_period"    # prior_period | prior_year | both
+
+narratives:
+  enabled: true
+  style: "concise"              # concise | detailed
+"""
+    config_path.write_text(content)
+    return config_path

dbt_agent_layer/executor/__init__.py

@@ -0,0 +1,6 @@
+"""Executor module: SQL execution adapters."""
+
+from .base import BaseExecutor
+from .factory import get_executor
+
+__all__ = ["BaseExecutor", "get_executor"]

dbt_agent_layer/executor/base.py

@@ -0,0 +1,19 @@
+"""Abstract base class for SQL executors."""
+
+from abc import ABC, abstractmethod
+
+
+class BaseExecutor(ABC):
+    """Abstract interface for warehouse SQL execution."""
+
+    @abstractmethod
+    async def execute(self, sql: str) -> list[dict]:
+        """Execute SQL and return list of row dicts."""
+
+    @abstractmethod
+    async def test_connection(self) -> bool:
+        """Ping the warehouse. Used on startup."""
+
+    @abstractmethod
+    def get_adapter_type(self) -> str:
+        """Returns 'postgres' | 'bigquery' | 'snowflake' | 'duckdb'."""