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

dbt_cortex_agent/manifest.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .identifiers import fqn, identifier, stage_path
+
+
+SUPPORTED_MANIFEST_SCHEMA_VERSIONS = {"v12"}
+
+
+@dataclass(frozen=True)
+class SkillDeclaration:
+    agent_name: str
+    skill_name: str
+    source_type: str
+    stage_path: str
+    local_dir: Path
+
+
+@dataclass(frozen=True)
+class EvalDeclaration:
+    model_name: str
+    table_fqn: str
+    meta: dict[str, Any]
+
+
+def agent_database(agent: dict[str, Any]) -> str:
+    return identifier(str(agent.get("database") or ""), f"database for {agent.get('name')}")
+
+
+def agent_schema(agent: dict[str, Any]) -> str:
+    return identifier(str(agent.get("schema") or ""), f"schema for {agent.get('name')}")
+
+
+def selected_agent_databases(agents: list[dict[str, Any]]) -> tuple[str, ...]:
+    return tuple(sorted({agent_database(agent) for agent in agents}))
+
+
+def assert_config_database(
+    manifest: dict[str, Any], database: str | None, agent_names: list[str] | None = None
+) -> str:
+    """Compatibility assertion scoped to selected Agents, never unrelated models."""
+    if not database:
+        raise ValueError("Operation requires explicit --database or SNOWFLAKE_DATABASE")
+    configured = identifier(database, "configured database")
+    resolved = selected_agent_databases(select_agents(manifest, agent_names))
+    if resolved != (configured,):
+        raise ValueError(
+            f"Configured database {configured!r} does not match selected Agent databases "
+            f"{', '.join(resolved) or 'none'}"
+        )
+    return configured
+
+
+def assert_resource_databases_allowed(
+    databases: list[str] | tuple[str, ...] | set[str], allowed_databases: list[str]
+) -> tuple[str, ...]:
+    resolved = tuple(sorted({identifier(value, "resource database") for value in databases}))
+    allowed = {identifier(value, "allowed database") for value in allowed_databases}
+    missing = [value for value in resolved if value not in allowed]
+    if missing:
+        raise ValueError(
+            "Refusing operation for resource databases not in the allowlist: "
+            f"{', '.join(missing)}; allowed databases: {', '.join(sorted(allowed)) or 'none'}"
+        )
+    return resolved
+
+
+def load_manifest(path: str | Path) -> dict[str, Any]:
+    manifest_path = Path(path)
+    if not manifest_path.is_file():
+        raise FileNotFoundError(
+            f"dbt manifest not found: {manifest_path}. Run `dbt parse` for this project first."
+        )
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON in dbt manifest {manifest_path}: {exc}") from exc
+    if not isinstance(manifest, dict):
+        raise ValueError(f"dbt manifest {manifest_path} must contain a JSON object")
+    validate_manifest(manifest, manifest_path)
+    return manifest
+
+
+def validate_manifest(manifest: dict[str, Any], manifest_path: str | Path | None = None) -> None:
+    metadata = manifest.get("metadata")
+    schema_version = metadata.get("dbt_schema_version") if isinstance(metadata, dict) else None
+    if not schema_version:
+        location = f" in {manifest_path}" if manifest_path else ""
+        raise ValueError(f"dbt manifest{location} is missing metadata.dbt_schema_version")
+    version = str(schema_version).rstrip("/").split("/")[-1].removesuffix(".json")
+    if version not in SUPPORTED_MANIFEST_SCHEMA_VERSIONS:
+        supported = ", ".join(sorted(SUPPORTED_MANIFEST_SCHEMA_VERSIONS))
+        raise ValueError(
+            f"Unsupported dbt manifest schema version {schema_version!r}; supported versions: "
+            f"{supported}. Run a supported dbt version or upgrade dbt-cortex-agent."
+        )
+
+
+def _meta(obj: dict[str, Any]) -> dict[str, Any]:
+    direct = obj.get("meta")
+    if isinstance(direct, dict) and direct:
+        return direct
+    config = obj.get("config")
+    configured = config.get("meta") if isinstance(config, dict) else None
+    return configured if isinstance(configured, dict) else {}
+
+
+def _relation_fqn(node: dict[str, Any]) -> str:
+    database = str(node.get("database") or "")
+    schema = str(node.get("schema") or "")
+    relation = str(node.get("alias") or node.get("name") or "")
+    if not all((database, schema, relation)):
+        raise ValueError(f"Eval model is missing database, schema, or name: {node.get('unique_id')}")
+    return fqn(f"{database}.{schema}.{relation}", "eval model")
+
+
+def _model_agent_spec(node: dict[str, Any]) -> dict[str, Any]:
+    compiled = node.get("compiled_code")
+    if not isinstance(compiled, str) or not compiled.strip():
+        return {}
+    try:
+        value = json.loads(compiled)
+    except json.JSONDecodeError:
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def _stage_suffix(stage_path: str) -> Path:
+    _, suffix = stage_path_parts(stage_path)
+    return Path(suffix)
+
+
+def stage_path_parts(value: str) -> tuple[str, str]:
+    return stage_path(value, "skill stage path")
+
+
+def local_skill_dir(project_dir: str | Path, stage_path: str) -> Path:
+    project_path = Path(project_dir)
+    suffix = _stage_suffix(stage_path)
+    parts = suffix.parts
+    if parts and parts[0] == "agents":
+        if len(parts) < 3:
+            raise ValueError(
+                f"Private skill stage path must be agents/<agent>/<name>: {stage_path!r}"
+            )
+        return project_path / "models" / "agents" / parts[1] / "skills" / Path(*parts[2:])
+    return project_path / "skills" / suffix
+
+
+def cortex_agents(manifest: dict[str, Any]) -> list[dict[str, Any]]:
+    agents: list[dict[str, Any]] = []
+    nodes = manifest.get("nodes") or {}
+    for node in nodes.values():
+        config = node.get("config") if isinstance(node, dict) else None
+        if not isinstance(config, dict) or config.get("materialized") != "cortex_agent":
+            continue
+        agent_meta = _meta(node).get("cortex_agent", {})
+        if agent_meta is None:
+            agent_meta = {}
+        if not isinstance(agent_meta, dict):
+            raise ValueError(
+                f"cortex_agent model {node.get('unique_id')!r} meta.cortex_agent must be a mapping"
+            )
+        if agent_meta.get("enabled") is False:
+            continue
+        name = node.get("name")
+        if not name:
+            raise ValueError("Enabled cortex_agent model is missing a name")
+        database = identifier(str(node.get("database") or ""), "cortex_agent model database")
+        schema = identifier(str(node.get("schema") or ""), "cortex_agent model schema")
+        physical_name = identifier(
+            str(node.get("alias") or name), f"physical Agent for {name}"
+        )
+        normalized_meta = {
+            **agent_meta,
+            "compiled_spec": _model_agent_spec(node),
+            "snowflake_name": physical_name,
+        }
+        agents.append(
+            {
+                "name": str(name),
+                "meta": normalized_meta,
+                "resource_type": "model",
+                "unique_id": node.get("unique_id"),
+                "database": database,
+                "schema": schema,
+                "object_name": physical_name,
+                "physical_fqn": f"{database}.{schema}.{physical_name}",
+            }
+        )
+    return sorted(agents, key=lambda item: item["name"])
+
+
+def select_agents(
+    manifest: dict[str, Any], names: list[str] | tuple[str, ...] | None = None
+) -> list[dict[str, Any]]:
+    agents = cortex_agents(manifest)
+    by_name: dict[str, list[dict[str, Any]]] = {}
+    for agent in agents:
+        by_name.setdefault(agent["name"], []).append(agent)
+    duplicates = sorted(name for name, values in by_name.items() if len(values) > 1)
+    if duplicates:
+        raise ValueError(
+            "Enabled cortex_agent model names must be unique: "
+            f"{', '.join(duplicates)}"
+        )
+    physical: dict[str, list[str]] = {}
+    for agent in agents:
+        physical_name = agent.get("physical_fqn")
+        if physical_name:
+            physical.setdefault(str(physical_name).upper(), []).append(agent["name"])
+    duplicate_physical = sorted(
+        name for name, logical_names in physical.items() if len(logical_names) > 1
+    )
+    if duplicate_physical:
+        raise ValueError(
+            "Enabled cortex_agent physical identities must be unique: "
+            f"{', '.join(duplicate_physical)}"
+        )
+    if not names:
+        return agents
+    requested = list(dict.fromkeys(names))
+    missing = sorted(set(requested) - set(by_name))
+    if missing:
+        available = ", ".join(sorted(by_name)) or "none"
+        raise ValueError(
+            f"Unknown enabled cortex_agent selection: {', '.join(missing)}; available: {available}"
+        )
+    return [by_name[name][0] for name in requested]
+
+
+def skill_declarations(
+    manifest: dict[str, Any], project_dir: str | Path, agent_names: list[str] | None = None
+) -> list[SkillDeclaration]:
+    declarations: list[SkillDeclaration] = []
+    for agent in select_agents(manifest, agent_names):
+        configured = agent["meta"].get("skills") or []
+        spec_skills = agent["meta"].get("compiled_spec", {}).get("skills") or []
+        skills = configured or spec_skills
+        for skill in skills:
+            source = skill.get("source") or {}
+            if str(source.get("type", "")).lower() != "stage":
+                continue
+            stage_path = source.get("path")
+            if not stage_path or not skill.get("name"):
+                raise ValueError(f"Agent {agent['name']!r} has an incomplete stage skill declaration")
+            declarations.append(
+                SkillDeclaration(
+                    agent_name=agent["name"],
+                    skill_name=skill["name"],
+                    source_type=source["type"],
+                    stage_path=stage_path,
+                    local_dir=local_skill_dir(project_dir, stage_path),
+                )
+            )
+    return declarations
+
+
+def cortex_evals(manifest: dict[str, Any]) -> list[EvalDeclaration]:
+    declarations: list[EvalDeclaration] = []
+    nodes = manifest.get("nodes") or {}
+    for node in nodes.values():
+        eval_meta = _meta(node).get("cortex_eval")
+        if isinstance(eval_meta, dict) and eval_meta and eval_meta.get("enabled") is not False:
+            declarations.append(
+                EvalDeclaration(
+                    model_name=node["name"], table_fqn=_relation_fqn(node), meta=eval_meta
+                )
+            )
+    return sorted(declarations, key=lambda item: item.model_name)
+
+
+def physical_agent_name(agent: dict[str, Any], target: str | None) -> str:
+    return identifier(
+        agent["meta"].get("snowflake_name"),
+        f"physical Agent for {agent['name']}",
+    )
+
+
+def physical_agent_fqn(agent: dict[str, Any]) -> str:
+    return fqn(str(agent.get("physical_fqn") or ""), f"physical Agent for {agent.get('name')}")

dbt_cortex_agent/skills.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import Config
+from .dbt_runner import CommandRunner
+from .manifest import SkillDeclaration, select_agents, skill_declarations, stage_path_parts
+
+
+@dataclass(frozen=True)
+class SkillUpload:
+    stage_fqn: str
+    stage_path: str
+    local_dir: Path
+    skill_names: tuple[str, ...]
+    agent_names: tuple[str, ...]
+
+
+def _stage_parts(stage_path: str) -> tuple[str, str]:
+    return stage_path_parts(stage_path)
+
+
+def stage_database(stage_path: str) -> str:
+    stage_fqn, _ = _stage_parts(stage_path)
+    return stage_fqn.split(".", 1)[0]
+
+
+def _ignored_private_skill(project_dir: Path, local_dir: Path) -> bool:
+    try:
+        relative = local_dir.resolve().relative_to(project_dir.resolve()).as_posix()
+    except ValueError:
+        return False
+    if not relative.startswith("models/agents/") or "/skills/" not in relative:
+        return True
+    ignore_file = project_dir / ".dbtignore"
+    if not ignore_file.is_file():
+        return False
+    candidate = f"{relative}/SKILL.md"
+    patterns = [
+        line.strip()
+        for line in ignore_file.read_text(encoding="utf-8").splitlines()
+        if line.strip() and not line.lstrip().startswith("#") and not line.startswith("!")
+    ]
+    return any(fnmatch.fnmatch(candidate, pattern) for pattern in patterns)
+
+
+def build_upload_plan(
+    manifest: dict, project_dir: str | Path, agent_names: list[str] | None = None
+) -> list[SkillUpload]:
+    project_path = Path(project_dir).resolve()
+    for agent in select_agents(manifest, agent_names):
+        names: set[str] = set()
+        configured = agent["meta"].get("skills") or []
+        spec_skills = agent["meta"].get("compiled_spec", {}).get("skills") or []
+        for skill in configured or spec_skills:
+            skill_name = skill.get("name")
+            if skill_name in names:
+                raise ValueError(
+                    f"Agent {agent['name']!r} declares duplicate skill name {skill_name!r}"
+                )
+            if skill_name:
+                names.add(skill_name)
+    declarations = skill_declarations(manifest, project_path, agent_names)
+    stage_sources: dict[str, tuple[str, Path]] = {}
+    grouped: dict[str, list[SkillDeclaration]] = {}
+
+    for declaration in declarations:
+        _stage_parts(declaration.stage_path)
+        local_dir = declaration.local_dir.resolve()
+        skill_file = local_dir / "SKILL.md"
+        if not skill_file.is_file():
+            raise FileNotFoundError(
+                f"Declared skill {declaration.skill_name!r} for Agent "
+                f"{declaration.agent_name!r} is missing {skill_file}"
+            )
+        if not _ignored_private_skill(project_path, local_dir):
+            raise ValueError(
+                f"Private skill directory {local_dir} is not protected by "
+                f"{project_path / '.dbtignore'}"
+            )
+        collision_key = declaration.stage_path.casefold()
+        prior = stage_sources.get(collision_key)
+        if prior is not None and prior[1] != local_dir:
+            raise ValueError(
+                f"Skill stage path collision for {declaration.stage_path}: {prior[1]} and {local_dir}"
+            )
+        if prior is None:
+            stage_sources[collision_key] = (declaration.stage_path, local_dir)
+        grouped.setdefault(collision_key, []).append(declaration)
+
+    plan: list[SkillUpload] = []
+    for collision_key, values in grouped.items():
+        stage_path, local_dir = stage_sources[collision_key]
+        stage_fqn, _ = _stage_parts(stage_path)
+        plan.append(
+            SkillUpload(
+                stage_fqn=stage_fqn,
+                stage_path=stage_path,
+                local_dir=local_dir,
+                skill_names=tuple(sorted({item.skill_name for item in values})),
+                agent_names=tuple(sorted({item.agent_name for item in values})),
+            )
+        )
+    return sorted(plan, key=lambda item: item.stage_path.casefold())
+
+
+def assert_apply_safety(
+    config: Config, allowed_targets: list[str], allowed_databases: list[str]
+) -> None:
+    if not config.target:
+        raise ValueError("Apply requires an explicit --target or DBT_TARGET")
+    if config.target not in allowed_targets:
+        raise ValueError(
+            f"Refusing apply for target {config.target!r}; allowed targets: "
+            f"{', '.join(allowed_targets) or 'none'}"
+        )
+    if not config.database:
+        raise ValueError("Apply requires an explicit --database or SNOWFLAKE_DATABASE")
+    allowed = {name.upper() for name in allowed_databases}
+    if config.database.upper() not in allowed:
+        raise ValueError(
+            f"Refusing apply for database {config.database!r}; allowed databases: "
+            f"{', '.join(allowed_databases) or 'none'}"
+        )
+    if not config.connection_explicit or not config.connection:
+        raise ValueError("Apply requires an explicitly supplied --connection")
+
+
+def upload_skills(
+    plan: list[SkillUpload], config: Config, runner: CommandRunner | None = None
+) -> None:
+    command_runner = runner or CommandRunner()
+    validated: set[str] = set()
+    for upload in plan:
+        stage_key = upload.stage_fqn.casefold()
+        if stage_key in validated:
+            continue
+        result = command_runner.run(
+            [
+                config.snow_executable,
+                "sql",
+                "--connection",
+                str(config.connection),
+                "--query",
+                f"DESCRIBE STAGE {upload.stage_fqn}",
+            ],
+            cwd=config.project_dir,
+        )
+        if result.returncode != 0:
+            detail = result.stderr.strip() or result.stdout.strip() or "stage is missing"
+            raise RuntimeError(
+                f"Skill stage {upload.stage_fqn} is missing or inaccessible; "
+                "provision it through the environment infrastructure owner before "
+                f"uploading skills: {detail}"
+            )
+        validated.add(stage_key)
+
+    for upload in plan:
+        result = command_runner.run(
+            [
+                config.snow_executable,
+                "stage",
+                "copy",
+                "--connection",
+                str(config.connection),
+                str(upload.local_dir / "*"),
+                f"{upload.stage_path}/",
+                "--overwrite",
+                "--recursive",
+                "--parallel",
+                "4",
+            ],
+            cwd=config.project_dir,
+        )
+        if result.returncode != 0:
+            names = ", ".join(upload.skill_names)
+            raise RuntimeError(
+                result.stderr.strip() or result.stdout.strip() or f"skill upload failed: {names}"
+            )

dbt_cortex_agent/snow.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import subprocess
+
+from .dbt_runner import CommandRunner
+
+
+def connection_test(
+    executable: str, connection: str, runner: CommandRunner
+) -> subprocess.CompletedProcess[str]:
+    return runner.run([executable, "connection", "test", "--connection", connection])

dbt_cortex_agent/starters/orders/models/agents/orders_assistant/agent.yml

@@ -0,0 +1,7 @@
+version: 2
+
+models:
+  - name: orders_assistant
+    description: Full-body Cortex Agent model for governed order analytics.
+    config:
+      access: protected

dbt_cortex_agent/starters/orders/models/agents/orders_assistant/evals/core.yml

@@ -0,0 +1,54 @@
+version: 2
+
+models:
+  - name: orders_assistant_core
+    description: Minimal evaluation dataset for Orders Assistant.
+    config:
+      materialized: table
+      schema: eval
+      meta:
+        cortex_eval:
+          name: core
+          agent: orders_assistant
+          description: Core routing, correctness, and boundary checks.
+          metrics:
+            - answer_correctness
+            - logical_consistency
+            - tool_selection_accuracy
+            - tool_execution_accuracy
+          thresholds:
+            answer_correctness: 0.60
+            logical_consistency: 0.60
+            tool_selection_accuracy: 0.80
+            tool_execution_accuracy: 0.70
+          questions:
+            - id: total_revenue
+              test_type: in_scope
+              expected_tools: [OrdersAnalytics]
+              ground_truth_ref: total_revenue
+            - id: out_of_scope_competitor_inventory
+              test_type: out_of_scope
+              expected_tools: []
+              ground_truth_ref: out_of_scope_competitor_inventory
+            - id: negative_future_revenue
+              test_type: negative
+              expected_tools: []
+              ground_truth_ref: negative_future_revenue
+    data_tests:
+      - dbt_cortex_agent.cortex_eval_question_coverage:
+          arguments:
+            min_out_of_scope: 1
+            min_negative: 1
+            expected_tools: [OrdersAnalytics]
+            expected_refs:
+              - total_revenue
+              - out_of_scope_competitor_inventory
+              - negative_future_revenue
+    columns:
+      - name: input_query
+        data_tests:
+          - not_null
+          - unique
+      - name: output
+        data_tests:
+          - not_null

dbt_cortex_agent/starters/orders/models/agents/orders_assistant/evals/orders_assistant_core.sql

@@ -0,0 +1,50 @@
+{{ config(materialized='table', schema='eval') }}
+
+WITH total_revenue AS (
+    SELECT
+        'What was total order revenue?' AS input_query,
+        'Total order revenue was $' || TO_VARCHAR(ROUND(COALESCE(SUM(revenue), 0), 2), 'FM9999999990.00') || '.' AS ground_truth_output,
+        ARRAY_CONSTRUCT(
+            OBJECT_CONSTRUCT(
+                'tool_name', 'OrdersAnalytics',
+                'tool_input', 'Calculate total order revenue.',
+                'tool_output', 'Semantic view result with total_revenue.'
+            )
+        ) AS ground_truth_invocations,
+        OBJECT_CONSTRUCT(
+            'category', 'orders',
+            'test_type', 'in_scope',
+            'ground_truth_ref', 'total_revenue'
+        ) AS custom_criteria
+    FROM {{ ref('orders') }}
+),
+
+out_of_scope_competitor_inventory AS (
+    SELECT
+        'How many units does our largest competitor have in inventory?' AS input_query,
+        'The Agent should decline because competitor inventory is outside the governed order data.' AS ground_truth_output,
+        ARRAY_CONSTRUCT() AS ground_truth_invocations,
+        OBJECT_CONSTRUCT(
+            'category', 'boundary',
+            'test_type', 'out_of_scope',
+            'ground_truth_ref', 'out_of_scope_competitor_inventory'
+        ) AS custom_criteria
+),
+
+negative_future_revenue AS (
+    SELECT
+        'What will exact order revenue be next year?' AS input_query,
+        'The Agent should explain that the available order history cannot determine exact future revenue.' AS ground_truth_output,
+        ARRAY_CONSTRUCT() AS ground_truth_invocations,
+        OBJECT_CONSTRUCT(
+            'category', 'boundary',
+            'test_type', 'negative',
+            'ground_truth_ref', 'negative_future_revenue'
+        ) AS custom_criteria
+)
+
+{{ dbt_cortex_agent.cortex_eval__assemble([
+    'total_revenue',
+    'out_of_scope_competitor_inventory',
+    'negative_future_revenue'
+]) }}

dbt_cortex_agent/starters/orders/models/agents/orders_assistant/orders_assistant.sql

@@ -0,0 +1,54 @@
+{% do ref('sem_orders') %}
+{{
+  config(
+    materialized='cortex_agent',
+    database=target.database,
+    schema='AGENTS',
+    alias='ORDERS_ASSISTANT_SANDBOX',
+    meta={
+      'agent_display_name': 'Orders Assistant',
+      'agent_comment': 'Governed order analytics assistant',
+      'deploy_alias': 'latest',
+      'cortex_agent': {
+        'enabled': true,
+        'access': {
+          'usage_roles': [env_var('CORTEX_AGENT_RUNTIME_ROLE', 'ORDERS_AGENT_USER')],
+          'monitor_roles': [env_var('CORTEX_AGENT_MONITOR_ROLE', 'ORDERS_AGENT_MONITOR')]
+        },
+        'evaluation': {'native_tools': ['OrdersAnalytics']}
+      }
+    }
+  )
+}}
+
+models:
+  orchestration: claude-sonnet-4-6
+
+orchestration:
+  budget:
+    seconds: 60
+    tokens: 16000
+
+instructions:
+  orchestration: Use OrdersAnalytics for governed order questions. Do not invent unavailable facts.
+  response: Answer concisely and state the requested time scope and units.
+  sample_questions:
+    - question: What was total order revenue?
+    - question: Which region generated the most revenue?
+
+tools:
+  - tool_spec:
+      type: cortex_analyst_text_to_sql
+      name: OrdersAnalytics
+      description: |
+        Analyzes governed order revenue, count, average value, dates, and regions.
+        Use for aggregate order questions and comparisons. Not for competitor data,
+        inventory, support tickets, or forecasts.
+
+tool_resources:
+  OrdersAnalytics:
+    semantic_view: "{{ target.database }}.SEMANTIC.SEM_ORDERS"
+    execution_environment:
+      type: warehouse
+      warehouse: "{{ target.warehouse }}"
+      query_timeout: 60

dbt_cortex_agent/starters/orders/models/semantic/sem_orders.sql

@@ -0,0 +1,40 @@
+{{ config(materialized='semantic_view') }}
+
+TABLES (
+    orders AS {{ ref('orders') }}
+      PRIMARY KEY (order_id)
+      WITH SYNONYMS ('sales orders')
+      COMMENT = 'Completed customer orders'
+)
+
+FACTS (
+    orders.revenue AS revenue
+      COMMENT = 'Revenue recorded for the order'
+)
+
+DIMENSIONS (
+    orders.order_date AS order_date
+      WITH SYNONYMS ('sale date')
+      COMMENT = 'Date the order was completed',
+    orders.region AS region
+      WITH SYNONYMS ('sales region')
+      COMMENT = 'Region credited with the order'
+)
+
+METRICS (
+    orders.total_revenue AS SUM(orders.revenue)
+      WITH SYNONYMS ('sales', 'revenue')
+      COMMENT = 'Total order revenue',
+    orders.total_orders AS COUNT(orders.order_id)
+      WITH SYNONYMS ('order count')
+      COMMENT = 'Number of completed orders',
+    orders.average_order_value AS AVG(orders.revenue)
+      WITH SYNONYMS ('average sale')
+      COMMENT = 'Average revenue per order'
+)
+
+COMMENT = 'Starter semantic view for governed order analysis'
+
+AI_SQL_GENERATION 'Use only the declared dimensions and metrics. Use order_date for time filters and region for geographic comparisons.'
+
+AI_QUESTION_CATEGORIZATION 'Accept questions about order revenue, count, average value, dates, and regions. Reject unrelated operational or competitor questions.'