dbt-cortex-agent 0.0.3__py3-none-any.whl

dbt_cortex_agent/commands/skill.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import argparse
+
+from ..config import Config
+from ..identifiers import identifier
+from ..invoke import smoke_skills
+from ..manifest import (
+    assert_resource_databases_allowed,
+    physical_agent_name,
+    select_agents,
+    skill_declarations,
+)
+from ..skills import assert_apply_safety, build_upload_plan, upload_skills
+from .common import add_allowlists, emit_json, fresh_manifest, require_explicit_connection
+
+
+def register(subparsers: argparse._SubParsersAction, shared: argparse.ArgumentParser) -> None:
+    parser = subparsers.add_parser(
+        "skill",
+        help="plan, upload, or smoke Agent skills",
+        description="Plan skill files locally; upload and live smoke require explicit --apply.",
+        epilog=(
+            "Examples:\n"
+            "  dbt-cortex-agent skill plan --agent orders_assistant --json\n"
+            "  dbt-cortex-agent skill upload --agent orders_assistant --apply --connection dev"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    commands = parser.add_subparsers(dest="skill_command", required=True)
+    for name in ("plan", "upload"):
+        help_text = "build a non-mutating upload plan" if name == "plan" else "preview or apply skill upload [MUTATION with --apply]"
+        command = commands.add_parser(name, parents=[shared], help=help_text)
+        command.add_argument("--agent", action="append", dest="agents", help="logical Agent name; repeatable")
+        if name == "upload":
+            command.add_argument("--apply", action="store_true", help="[MUTATION] upload files; default is preview")
+            add_allowlists(command)
+        command.set_defaults(handler=handle)
+    smoke = commands.add_parser("smoke", parents=[shared], help="preview or run live skill smoke [RUNTIME with --apply]")
+    smoke.add_argument("--agent", action="append", dest="agents", help="logical Agent name; repeatable")
+    smoke.add_argument("--agent-object", help="physical Agent override for exactly one selected Agent")
+    smoke.add_argument("--endpoint", help="HTTPS Snowflake Agent endpoint override")
+    smoke.add_argument("--apply", action="store_true", help="[RUNTIME] invoke Agents; default is preview")
+    add_allowlists(smoke)
+    smoke.set_defaults(handler=handle)
+
+
+def _plan_payload(plan: list) -> list[dict]:
+    return [
+        {
+            "stage_path": item.stage_path,
+            "local_dir": str(item.local_dir),
+            "skills": list(item.skill_names),
+            "agents": list(item.agent_names),
+        }
+        for item in plan
+    ]
+
+
+def handle(args: argparse.Namespace, config: Config) -> int:
+    manifest = fresh_manifest(config, no_parse=args.no_parse)
+    selected = select_agents(manifest, args.agents)
+    selected_names = [item["name"] for item in selected]
+    if args.skill_command in {"plan", "upload"}:
+        plan = build_upload_plan(manifest, config.project_dir, selected_names)
+        applied = args.skill_command == "upload" and args.apply
+        if applied:
+            require_explicit_connection(config, "Skill upload")
+            assert_apply_safety(config, args.allow_target, args.allow_database)
+            assert_resource_databases_allowed(
+                {item.stage_fqn.split(".", 1)[0] for item in plan}, args.allow_database
+            )
+            upload_skills(plan, config)
+        payload = {"command": f"skill {args.skill_command}", "applied": applied, "uploads": _plan_payload(plan)}
+        if args.json:
+            emit_json(payload)
+        else:
+            for item in plan:
+                print(
+                    f"{item.stage_path} <- {item.local_dir} "
+                    f"(skills={','.join(item.skill_names)}; agents={','.join(item.agent_names)})"
+                )
+        return 0
+
+    declarations = skill_declarations(manifest, config.project_dir, selected_names)
+    if args.agent_object and len(selected) != 1:
+        raise ValueError("--agent-object may be used only when exactly one Agent is selected")
+    physical_agents = {
+        agent["name"]: {
+            "database": agent["database"],
+            "schema": agent["schema"],
+            "object_name": (
+                identifier(args.agent_object, "Agent object override")
+                if args.agent_object
+                else physical_agent_name(agent, config.target)
+            ),
+        }
+        for agent in selected
+    }
+    planned = [
+        {
+            "skill": skill.skill_name,
+            "agent": ".".join(physical_agents[skill.agent_name].values()),
+        }
+        for skill in declarations
+    ]
+    verified: list[str] = []
+    if args.apply:
+        require_explicit_connection(config, "Skill smoke")
+        assert_apply_safety(config, args.allow_target, args.allow_database)
+        assert_resource_databases_allowed(
+            {identity["database"] for identity in physical_agents.values()},
+            args.allow_database,
+        )
+        verified = smoke_skills(
+            declarations,
+            agent_names=physical_agents,
+            connection=str(config.connection),
+            endpoint=args.endpoint,
+        )
+    if args.json:
+        emit_json({"command": "skill smoke", "applied": bool(args.apply), "planned": planned, "verified": verified})
+    elif args.apply:
+        for skill_name in verified:
+            print(f"PASS {skill_name}: server_skill selected")
+    else:
+        for item in planned:
+            print(f"[DRY RUN] would smoke {item['skill']} via {item['agent']}")
+    return 0

dbt_cortex_agent/config.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+import yaml
+
+from .execution_context import SnowflakeExecutionContext
+
+
+@dataclass(frozen=True)
+class Config:
+    project_dir: Path
+    manifest: Path
+    target: str | None
+    connection: str | None
+    connection_explicit: bool
+    database: str | None
+    database_explicit: bool
+    schema: str | None
+    warehouse: str | None
+    warehouse_explicit: bool
+    artifact_dir: Path
+    dbt_executable: str
+    snow_executable: str
+    execution_context: SnowflakeExecutionContext | None = None
+
+    @property
+    def dbt_env(self) -> Mapping[str, str] | None:
+        return self.execution_context.dbt_env if self.execution_context else None
+
+
+def load_yaml_mapping(path: Path, *, strict: bool = True) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    value = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        if strict:
+            raise ValueError(f"Expected a YAML mapping in {path}")
+        return {}
+    return value
+
+
+def _value(explicit: str | None, env: Mapping[str, str], name: str) -> str | None:
+    return explicit if explicit is not None else env.get(name)
+
+
+def resolve_config(args: object, env: Mapping[str, str] | None = None) -> Config:
+    values = os.environ if env is None else env
+    project_dir = Path(
+        _value(getattr(args, "project_dir", None), values, "DBT_PROJECT_DIR") or "."
+    ).expanduser().resolve()
+    manifest_value = _value(getattr(args, "manifest", None), values, "DBT_MANIFEST")
+    artifact_value = _value(
+        getattr(args, "artifact_dir", None), values, "DBT_CORTEX_AGENT_ARTIFACT_DIR"
+    )
+    manifest = Path(manifest_value).expanduser() if manifest_value else Path("target/manifest.json")
+    artifact_dir = Path(artifact_value).expanduser() if artifact_value else Path("target/dbt_cortex_agent")
+
+    return Config(
+        project_dir=project_dir,
+        manifest=manifest.resolve() if manifest.is_absolute() else (project_dir / manifest).resolve(),
+        target=_value(getattr(args, "target", None), values, "DBT_TARGET"),
+        connection=_value(getattr(args, "connection", None), values, "SNOWFLAKE_CONNECTION_NAME"),
+        connection_explicit=getattr(args, "connection", None) is not None,
+        database=_value(getattr(args, "database", None), values, "SNOWFLAKE_DATABASE"),
+        database_explicit=getattr(args, "database", None) is not None,
+        schema=_value(getattr(args, "schema", None), values, "SNOWFLAKE_SCHEMA"),
+        warehouse=_value(getattr(args, "warehouse", None), values, "SNOWFLAKE_WAREHOUSE"),
+        warehouse_explicit=getattr(args, "warehouse", None) is not None,
+        artifact_dir=(
+            artifact_dir.resolve()
+            if artifact_dir.is_absolute()
+            else (project_dir / artifact_dir).resolve()
+        ),
+        dbt_executable=_value(
+            getattr(args, "dbt_executable", None), values, "DBT_EXECUTABLE"
+        )
+        or "dbt",
+        snow_executable=_value(
+            getattr(args, "snow_executable", None), values, "SNOW_EXECUTABLE"
+        )
+        or "snow",
+    )

dbt_cortex_agent/dbt_runner.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+
+RunCallable = Callable[..., subprocess.CompletedProcess[str]]
+
+
+@dataclass
+class CommandRunner:
+    run_callable: RunCallable = subprocess.run
+
+    def run(
+        self,
+        command: Sequence[str],
+        *,
+        cwd: str | Path | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> subprocess.CompletedProcess[str]:
+        kwargs = {"cwd": cwd, "text": True, "capture_output": True, "check": False}
+        if env is not None:
+            kwargs["env"] = dict(env)
+        return self.run_callable(list(command), **kwargs)
+
+
+def executable_version(executable: str, runner: CommandRunner) -> subprocess.CompletedProcess[str]:
+    return runner.run([executable, "--version"])
+
+
+def _run(
+    runner: CommandRunner,
+    command: Sequence[str],
+    *,
+    cwd: str | Path,
+    env: Mapping[str, str] | None,
+) -> subprocess.CompletedProcess[str]:
+    if env is None:
+        return runner.run(command, cwd=cwd)
+    return runner.run(command, cwd=cwd, env=env)
+
+
+def run_dbt_deps(
+    executable: str,
+    project_dir: str | Path,
+    target: str | None,
+    runner: CommandRunner,
+    env: Mapping[str, str] | None = None,
+) -> subprocess.CompletedProcess[str]:
+    command = [executable, "deps", "--project-dir", str(project_dir)]
+    if target:
+        command.extend(["--target", target])
+    return _run(runner, command, cwd=project_dir, env=env)
+
+
+def run_dbt_parse(
+    executable: str,
+    project_dir: str | Path,
+    target: str | None,
+    runner: CommandRunner,
+    env: Mapping[str, str] | None = None,
+) -> subprocess.CompletedProcess[str]:
+    command = [executable, "parse", "--project-dir", str(project_dir)]
+    if target:
+        command.extend(["--target", target])
+    return _run(runner, command, cwd=project_dir, env=env)
+
+
+def run_dbt_operation(
+    executable: str,
+    project_dir: str | Path,
+    target: str | None,
+    macro: str,
+    arguments: dict[str, object],
+    runner: CommandRunner,
+    env: Mapping[str, str] | None = None,
+) -> subprocess.CompletedProcess[str]:
+    command = [
+        executable,
+        "run-operation",
+        macro,
+        "--args",
+        json.dumps(arguments, separators=(",", ":")),
+        "--project-dir",
+        str(project_dir),
+    ]
+    if target:
+        command.extend(["--target", target])
+    return _run(runner, command, cwd=project_dir, env=env)

dbt_cortex_agent/doctor.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .config import Config, load_yaml_mapping
+from .dbt_runner import CommandRunner, executable_version
+from .manifest import cortex_agents, cortex_evals, load_manifest, skill_declarations
+from .snow import connection_test
+
+
+_FULL_GIT_SHA = re.compile(r"^[0-9a-fA-F]{40}$")
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    name: str
+    status: str
+    detail: str
+
+
+def _declared_revisions(project_dir: Path) -> list[str]:
+    revisions: list[str] = []
+    for filename in ("packages.yml", "package-lock.yml"):
+        document = load_yaml_mapping(project_dir / filename, strict=False)
+        for item in document.get("packages", []) or []:
+            if not isinstance(item, dict):
+                continue
+            source = str(item.get("git") or item.get("package") or "")
+            if "dbt-cortex-agent" in source or "dbt_cortex_agent" in source:
+                revision = item.get("revision") or item.get("version")
+                if revision:
+                    revisions.append(str(revision).removeprefix("v"))
+    return revisions
+
+
+def _dbt_package_versions(project_dir: Path) -> list[str]:
+    versions: list[str] = []
+    candidates = (project_dir / "dbt_packages" / "dbt_cortex_agent" / "dbt_project.yml",)
+    for candidate in candidates:
+        project = load_yaml_mapping(candidate, strict=False)
+        if project.get("name") == "dbt_cortex_agent" and project.get("version"):
+            versions.append(str(project["version"]).removeprefix("v"))
+    return versions
+
+
+def run_doctor(config: Config, runner: CommandRunner | None = None) -> list[Diagnostic]:
+    command_runner = runner or CommandRunner()
+    diagnostics: list[Diagnostic] = []
+    for name, executable in (("dbt executable", config.dbt_executable), ("snow executable", config.snow_executable)):
+        try:
+            result = executable_version(executable, command_runner)
+        except OSError as exc:
+            diagnostics.append(Diagnostic(name, "FAIL", str(exc)))
+            continue
+        output = result.stdout.strip() or result.stderr.strip()
+        diagnostics.append(
+            Diagnostic(name, "PASS" if result.returncode == 0 else "FAIL", output)
+        )
+
+    dbt_package_versions = _dbt_package_versions(config.project_dir)
+    if dbt_package_versions:
+        mismatches = sorted({version for version in dbt_package_versions if version != __version__})
+        diagnostics.append(
+            Diagnostic(
+                "installed package version",
+                "FAIL" if mismatches else "PASS",
+                f"CLI={__version__}; dbt={', '.join(sorted(set(dbt_package_versions)))}",
+            )
+        )
+
+    manifest: dict[str, Any] | None = None
+    try:
+        manifest = load_manifest(config.manifest)
+        diagnostics.append(Diagnostic("manifest v12", "PASS", str(config.manifest)))
+    except (FileNotFoundError, ValueError, OSError) as exc:
+        diagnostics.append(Diagnostic("manifest v12", "FAIL", str(exc)))
+
+    revisions = _declared_revisions(config.project_dir)
+    if revisions:
+        mismatches = sorted(
+            {
+                version
+                for version in revisions
+                if version != __version__
+                and not (_FULL_GIT_SHA.fullmatch(version) and __version__ in dbt_package_versions)
+            }
+        )
+        diagnostics.append(
+            Diagnostic(
+                "consumer package version",
+                "FAIL" if mismatches else "PASS",
+                f"CLI={__version__}; declared={', '.join(sorted(set(revisions)))}",
+            )
+        )
+    else:
+        diagnostics.append(
+            Diagnostic("consumer package version", "WARN", "no package version metadata found")
+        )
+
+    if manifest:
+        agents = cortex_agents(manifest)
+        evals = cortex_evals(manifest)
+        diagnostics.append(
+            Diagnostic(
+                "enabled Agents",
+                "PASS",
+                ", ".join(item["physical_fqn"] for item in agents) or "none",
+            )
+        )
+        diagnostics.append(
+            Diagnostic("enabled evals", "PASS", ", ".join(item.model_name for item in evals) or "none")
+        )
+        try:
+            skills = skill_declarations(manifest, config.project_dir)
+            missing = [str(item.local_dir) for item in skills if not item.local_dir.is_dir()]
+            diagnostics.append(
+                Diagnostic(
+                    "configured local skills",
+                    "FAIL" if missing else "PASS",
+                    "missing: " + ", ".join(missing) if missing else f"{len(skills)} found",
+                )
+            )
+        except ValueError as exc:
+            diagnostics.append(Diagnostic("configured local skills", "FAIL", str(exc)))
+
+    project = load_yaml_mapping(config.project_dir / "dbt_project.yml", strict=False)
+    variables = project.get("vars") if isinstance(project.get("vars"), dict) else {}
+    legacy_target = variables.get("cortex_agent_deploy_target")
+    allowed_targets = variables.get("cortex_agent_allowed_targets") or (
+        [legacy_target] if legacy_target else []
+    )
+    allowed_databases = variables.get("cortex_agent_allowed_databases") or []
+    resolved_databases = sorted(
+        {item["database"] for item in cortex_agents(manifest)} if manifest else set()
+    )
+    if not allowed_targets or not allowed_databases:
+        diagnostics.append(
+            Diagnostic(
+                "deployment safety",
+                "FAIL",
+                "cortex_agent_allowed_targets and cortex_agent_allowed_databases must be non-empty; "
+                "configure them explicitly or preview init with --target and --allow-database",
+            )
+        )
+    elif not config.target:
+        diagnostics.append(
+            Diagnostic(
+                "deployment safety",
+                "WARN",
+                f"allowed targets={allowed_targets}; allowed databases={allowed_databases}; "
+                "active target unknown, supply --target to check it",
+            )
+        )
+    elif config.target not in allowed_targets:
+        diagnostics.append(
+            Diagnostic(
+                "deployment safety",
+                "PASS",
+                f"active target {config.target!r} cannot mutate allowlisted targets {allowed_targets}",
+            )
+        )
+    elif missing := sorted(
+        set(resolved_databases) - {str(item).upper() for item in allowed_databases}
+    ):
+        diagnostics.append(
+            Diagnostic(
+                "deployment safety",
+                "FAIL",
+                f"Agent databases missing from allowlist: {', '.join(missing)}",
+            )
+        )
+    else:
+        diagnostics.append(
+            Diagnostic(
+                "deployment safety",
+                "PASS",
+                f"active target is allowed; Agent databases={resolved_databases}; "
+                f"allowed databases={allowed_databases}",
+            )
+        )
+
+    if config.connection_explicit and config.connection:
+        try:
+            result = connection_test(config.snow_executable, config.connection, command_runner)
+            output = result.stdout.strip() or result.stderr.strip()
+            diagnostics.append(
+                Diagnostic("Snowflake connection", "PASS" if result.returncode == 0 else "FAIL", output)
+            )
+        except OSError as exc:
+            diagnostics.append(Diagnostic("Snowflake connection", "FAIL", str(exc)))
+    else:
+        diagnostics.append(
+            Diagnostic("Snowflake connection", "SKIP", "no explicit --connection supplied")
+        )
+    return diagnostics
+
+
+def diagnostics_json(diagnostics: list[Diagnostic]) -> str:
+    return json.dumps([item.__dict__ for item in diagnostics], indent=2)

dbt_cortex_agent/eval/baseline.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..artifacts import ARTIFACT_SCHEMA_VERSION, contained_path
+from .results import _identity_components, validate_result
+
+
+def build_baseline(candidate: dict[str, Any]) -> dict[str, Any]:
+    validate_result(candidate, "candidate")
+    if candidate.get("passed") is not True:
+        raise ValueError("Failed evaluation candidates cannot become baselines")
+    metadata = dict(candidate.get("run_metadata") or {})
+    metadata.pop("git_sha", None)
+    keys = (
+        "agent", "suite", "eval_model", "run_name", "timestamp", "summary", "thresholds",
+        "regression_tolerances", "passed", "total_records", "plan_schema_version",
+        "suite_signature", "plan_identity", "agent_fqn", "dataset_fqn", "stage_fqn",
+        "metric_names", "ordered_ground_truth_refs", "status",
+    )
+    baseline = {key: candidate.get(key) for key in keys}
+    baseline["schema_version"] = ARTIFACT_SCHEMA_VERSION
+    baseline["artifact_type"] = "baseline"
+    baseline["run_metadata"] = metadata
+    validate_result(baseline, "baseline")
+    return baseline
+
+
+def accept_baseline(
+    candidate: dict[str, Any], baseline_dir: str | Path, *, force: bool = False
+) -> Path:
+    baseline = build_baseline(candidate)
+    target_name, database, schema, agent_object = _identity_components(baseline)
+    target = contained_path(
+        baseline_dir, target_name, database, schema, agent_object,
+        f"{baseline['suite']}.json",
+    )
+    if target.exists() and not force:
+        raise FileExistsError(f"Baseline already exists: {target}; use --force after recording the ratchet decision")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(baseline, indent=2, default=str) + "\n", encoding="utf-8")
+    return target

dbt_cortex_agent/eval/compare.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .results import threshold_failures, validate_result
+
+
+def metric_averages(result: dict[str, Any]) -> dict[str, float]:
+    return {
+        name: float(stats["avg"])
+        for name, stats in (result.get("summary") or {}).items()
+        if isinstance(stats, dict) and stats.get("avg") is not None
+    }
+
+
+def suite_change(baseline: dict[str, Any], candidate: dict[str, Any]) -> str | None:
+    if baseline.get("ordered_ground_truth_refs") != candidate.get("ordered_ground_truth_refs"):
+        return "ordered ground-truth refs changed"
+    if baseline.get("metric_names") != candidate.get("metric_names"):
+        return "metric contract changed"
+    if baseline.get("thresholds") != candidate.get("thresholds"):
+        return "threshold policy changed"
+    if baseline.get("regression_tolerances") != candidate.get("regression_tolerances"):
+        return "regression tolerance policy changed"
+    if baseline.get("suite_signature") != candidate.get("suite_signature"):
+        return "suite signature changed"
+    return None
+
+
+def compare_results(
+    baseline: dict[str, Any], candidate: dict[str, Any], default_tolerance: float = 0.01
+) -> dict[str, Any]:
+    validate_result(baseline, "baseline")
+    validate_result(candidate, "candidate")
+    reason = suite_change(baseline, candidate)
+    before, after = metric_averages(baseline), metric_averages(candidate)
+    tolerances = {
+        name: float(value)
+        for name, value in (baseline.get("regression_tolerances") or {}).items()
+    }
+    gated = set(baseline.get("thresholds") or {}) | set(tolerances)
+    rows: list[dict[str, Any]] = []
+    regressions: list[str] = []
+    for metric in sorted(set(before) | set(after)):
+        old, new = before.get(metric), after.get(metric)
+        tolerance = tolerances.get(metric, default_tolerance)
+        delta = None if old is None or new is None else new - old
+        status = "new" if old is None else "missing" if new is None else "flat"
+        if old is not None and new is None and metric in gated:
+            status = "regressed"
+        elif delta is not None and delta < -tolerance:
+            status = "regressed" if metric in gated else "advisory"
+        elif delta is not None and delta > tolerance:
+            status = "improved"
+        if status == "regressed":
+            regressions.append(metric)
+        rows.append({
+            "metric": metric, "baseline": old, "candidate": new, "delta": delta,
+            "tolerance": tolerance, "status": status,
+        })
+    failures = threshold_failures(candidate.get("summary") or {}, candidate.get("thresholds") or {})
+    return {
+        "passed": reason is None and not regressions and not failures,
+        "suite_change": reason,
+        "regressions": regressions,
+        "threshold_failures": failures,
+        "metrics": rows,
+    }