lexis-cli 0.4.2__py3-none-any.whl

lexis/dispatch.py

@@ -0,0 +1,66 @@
+"""Shared target-dispatch logic: pick the right emitter for a transpile request.
+
+Used by both the CLI (`cli.py`) and the web API (`lexis_api`) so the mapping from
+`--target` to an emitter lives in exactly one place.
+"""
+
+from dataclasses import dataclass
+
+from lexis._vendor.ossie import OssieDocument
+from lexis.resolved_model import ResolvedModel
+from lexis.sml.emit import emit_sml_files
+from lexis.transpilers.cube import emit_cube_yaml
+from lexis.transpilers.dbt_ossie import emit_dbt_ossie_document
+from lexis.transpilers.mcp import emit_mcp_tool_manifest
+from lexis.transpilers.snowflake_semantic_view import emit_snowflake_semantic_view
+from lexis.transpilers.sql import EMITTERS as SQL_EMITTERS
+
+TARGETS = [*SQL_EMITTERS.keys(), "cube", "dbt", "mcp", "snowflake_semantic_view", "sml"]
+
+# Short alternate spellings accepted alongside the canonical TARGETS name - resolved
+# to the canonical name before dispatch, so callers/tests only ever need to branch on
+# the canonical spelling below.
+TARGET_ALIASES = {"ssv": "snowflake_semantic_view"}
+
+
+@dataclass(frozen=True)
+class TranspileResult:
+    # `sml` is the one multi-file target - one YAML file per SML object - so
+    # `content` is a `dict[str, str]` (relative filename -> content) there;
+    # every other target still returns a single `str`.
+    content: str | dict[str, str]
+    warnings: list[str]
+
+
+def transpile(
+    document: OssieDocument,
+    model: ResolvedModel,
+    target: str,
+    metric: str | None = None,
+    group_by: list[str] | None = None,
+) -> TranspileResult:
+    """Emit `model` (parsed from `document`) in the given `target` format.
+
+    Raises ValueError for a missing/unknown target or a missing metric on a SQL target.
+    """
+    target = TARGET_ALIASES.get(target, target)
+    if target in SQL_EMITTERS:
+        if not metric:
+            raise ValueError(f"metric is required for target {target!r}")
+        emitter = SQL_EMITTERS[target]()
+        content = emitter.emit_metric_query(model, metric, group_by=group_by or None)
+        return TranspileResult(content=content, warnings=[])
+    elif target == "cube":
+        return TranspileResult(content=emit_cube_yaml(model), warnings=[])
+    elif target == "dbt":
+        result = emit_dbt_ossie_document(document)
+        return TranspileResult(content=result.artifact.content, warnings=result.warnings)
+    elif target == "mcp":
+        return TranspileResult(content=emit_mcp_tool_manifest(model), warnings=[])
+    elif target == "snowflake_semantic_view":
+        return TranspileResult(content=emit_snowflake_semantic_view(model), warnings=[])
+    elif target == "sml":
+        result = emit_sml_files(document)
+        return TranspileResult(content=result.files, warnings=result.warnings)
+    else:
+        raise ValueError(f"Unknown target {target!r}")

lexis/mcp_server.py

@@ -0,0 +1,158 @@
+"""Live MCP server: turn a resolved model's metrics into callable, query-executing
+MCP tools (not just the static schema `transpilers/mcp.py` emits).
+
+Callers (the CLI's `mcp-serve` command, the API's mounted HTTP endpoint) supply an
+`ExecuteMetric` closure that knows how to actually run a metric query against
+whichever connection they've opened - this module only knows about the MCP protocol
+and the tool schema, never about DuckDB/Snowflake/FastAPI/SQLAlchemy, so it works the
+same from a local stdio process or a per-request HTTP handler.
+"""
+
+from collections.abc import Callable
+from datetime import date, datetime
+from typing import Any
+
+import anyio
+from mcp import types
+from mcp.server.lowlevel import Server
+
+from lexis._vendor.ossie import OssieDialect
+from lexis.resolved_model import ResolvedModel
+from lexis.transpilers.mcp import build_metric_tool_specs, model_instructions, resolve_time_axis
+from lexis.transpilers.sql.base import SqlDialectEmitter
+
+# A metric result has no natural row limit of its own (it's an aggregate query, not a
+# table scan) - this only guards against a pathological `group_by` fanning out to an
+# enormous number of groups.
+MAX_RESULT_ROWS = 1000
+
+
+def _json_safe(value: Any) -> Any:
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    return value
+
+
+def run_metric_query(
+    con: Any,
+    emitter: SqlDialectEmitter,
+    model: ResolvedModel,
+    metric: str,
+    group_by: list[str] | None,
+) -> dict:
+    """Driver-agnostic metric execution - same shape as
+    `lexis_api.query_runtime.run_metric_query`, duplicated here (rather than
+    imported) so this core module stays free of the `lexis_api` (FastAPI/
+    SQLAlchemy) dependency chain; both copies are small enough that the duplication
+    is cheaper than relocating that module."""
+    sql = emitter.emit_metric_query(model, metric, group_by=group_by)
+    return _run(con, sql)
+
+
+def _run(con: Any, sql: str) -> dict:
+    cursor = con.cursor()
+    cursor.execute(sql)
+    columns = [d[0] for d in cursor.description]
+    rows = cursor.fetchmany(MAX_RESULT_ROWS)
+    return {
+        "columns": columns,
+        "rows": [[_json_safe(v) for v in r] for r in rows],
+        "row_count": len(rows),
+        "sql": sql,
+    }
+
+
+def run_timeseries_query(
+    con: Any,
+    emitter: SqlDialectEmitter,
+    model: ResolvedModel,
+    metric: str,
+    time_dataset: str,
+    time_field: str,
+    grain: str,
+) -> dict:
+    """`metric` bucketed by `DATE_TRUNC(grain, time_dataset.time_field)`, one row per
+    period. Core mirror of `lexis_api.query_runtime.run_timeseries_query` (drill-down
+    filters omitted - the MCP tool doesn't expose them)."""
+    sql = emitter.emit_timeseries_query(model, metric, time_dataset, time_field, grain)
+    return _run(con, sql)
+
+
+def query_datasets(
+    model: ResolvedModel,
+    metric: str,
+    group_by: list[str] | None,
+    time_grain: str | None = None,
+    time_field: str | None = None,
+) -> set[str]:
+    """Every dataset a `run_metric_or_timeseries` call touches - the caller passes
+    this to its connection opener so a duckdb_file connection ATTACHes the right
+    files first."""
+    metric_expr = model.resolve_expression(model.metrics[metric].expression, OssieDialect.ANSI_SQL)
+    datasets = set(model.referenced_datasets(metric_expr))
+    if time_grain:
+        datasets.add(resolve_time_axis(model, time_field)[0])
+    else:
+        datasets |= {ref.split(".", 1)[0] for ref in (group_by or [])}
+    return datasets
+
+
+def run_metric_or_timeseries(
+    con: Any,
+    emitter: SqlDialectEmitter,
+    model: ResolvedModel,
+    metric: str,
+    group_by: list[str] | None,
+    time_grain: str | None = None,
+    time_field: str | None = None,
+) -> dict:
+    """Dispatch a `query_<metric>` tool call: a `DATE_TRUNC`-bucketed timeseries when
+    `time_grain` is set, otherwise a plain (optionally grouped) total. Raises
+    `ValueError` (a clean MCP tool error) on an unsupported combination."""
+    if time_grain:
+        if group_by:
+            raise ValueError("time_grain and group_by cannot be combined in one query yet")
+        time_dataset, column = resolve_time_axis(model, time_field)
+        return run_timeseries_query(con, emitter, model, metric, time_dataset, column, time_grain)
+    return run_metric_query(con, emitter, model, metric, group_by)
+
+
+# execute(metric, group_by, time_grain, time_field) -> result dict. `time_grain`
+# (day/week/month/quarter/year) buckets the metric into consecutive periods via the
+# emitter's timeseries query instead of a single total; `time_field` picks the date
+# axis (see lexis.transpilers.mcp.resolve_time_axis). Both None for a plain total.
+ExecuteMetric = Callable[[str, list[str] | None, str | None, str | None], dict]
+
+
+def build_server(model: ResolvedModel, execute: ExecuteMetric, name: str | None = None) -> Server:
+    """Build an MCP `Server` with one `query_<metric>` tool per Ossie metric, dispatching
+    tool calls to `execute(metric_name, group_by, time_grain, time_field)`."""
+    tools = [types.Tool(**spec) for spec in build_metric_tool_specs(model)]
+    server: Server = Server(
+        name or model.semantic_model.name, instructions=model_instructions(model) or None
+    )
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return tools
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict) -> dict:
+        if not name.startswith("query_"):
+            raise ValueError(f"unknown tool {name!r}")
+        metric = name.removeprefix("query_")
+        if metric not in model.metrics:
+            raise ValueError(f"unknown metric {metric!r}")
+        # `execute` runs a blocking DB-API call (DuckDB/Snowflake) - offload it so it
+        # doesn't stall the event loop driving the MCP session (matters most for the
+        # HTTP transport, which - unlike a normal FastAPI route - isn't already
+        # running inside FastAPI's own sync-endpoint threadpool).
+        return await anyio.to_thread.run_sync(
+            execute,
+            metric,
+            arguments.get("group_by") or None,
+            arguments.get("time_grain"),
+            arguments.get("time_field"),
+        )
+
+    return server

lexis/parser.py

@@ -0,0 +1,19 @@
+"""Parse and validate Ossie YAML/JSON documents into OssieDocument objects."""
+
+from pathlib import Path
+
+import yaml
+
+from lexis._vendor.ossie import OssieDocument
+
+
+def parse_ossie_yaml(text: str) -> OssieDocument:
+    """Parse Ossie YAML source text into a validated OssieDocument."""
+    data = yaml.safe_load(text)
+    return OssieDocument.model_validate(data)
+
+
+def load_ossie_document(path: str | Path) -> OssieDocument:
+    """Load and validate an Ossie document from a YAML file on disk."""
+    text = Path(path).read_text()
+    return parse_ossie_yaml(text)

lexis/resolved_model.py

@@ -0,0 +1,128 @@
+"""Index an OssieSemanticModel and resolve join paths / dialect expressions."""
+
+import re
+from collections import deque
+from dataclasses import dataclass, field
+
+from lexis._vendor.ossie import (
+    OssieDataset,
+    OssieDialect,
+    OssieExpression,
+    OssieMetric,
+    OssieRelationship,
+    OssieSemanticModel,
+)
+
+_QUALIFIED_REF_RE = re.compile(r"\b([A-Za-z_][A-Za-z0-9_]*)\.[A-Za-z_][A-Za-z0-9_]*\b")
+
+
+class UnresolvedJoinError(ValueError):
+    """Raised when a set of referenced datasets can't be connected via relationships."""
+
+
+class MissingExpressionError(ValueError):
+    """Raised when neither the requested dialect nor ANSI_SQL has an expression."""
+
+
+@dataclass
+class ResolvedModel:
+    """Indexed view of an OssieSemanticModel: fast lookups + join-graph resolution."""
+
+    semantic_model: OssieSemanticModel
+    datasets: dict[str, OssieDataset] = field(default_factory=dict)
+    metrics: dict[str, OssieMetric] = field(default_factory=dict)
+    relationships: list[OssieRelationship] = field(default_factory=list)
+    _adjacency: dict[str, list[tuple[str, OssieRelationship]]] = field(default_factory=dict)
+
+    @classmethod
+    def build(cls, semantic_model: OssieSemanticModel) -> "ResolvedModel":
+        model = cls(semantic_model=semantic_model)
+        for dataset in semantic_model.datasets:
+            model.datasets[dataset.name] = dataset
+        for metric in semantic_model.metrics or []:
+            model.metrics[metric.name] = metric
+        model.relationships = list(semantic_model.relationships or [])
+
+        adjacency: dict[str, list[tuple[str, OssieRelationship]]] = {
+            name: [] for name in model.datasets
+        }
+        for rel in model.relationships:
+            adjacency.setdefault(rel.from_dataset, []).append((rel.to, rel))
+            adjacency.setdefault(rel.to, []).append((rel.from_dataset, rel))
+        model._adjacency = adjacency
+        return model
+
+    def referenced_datasets(self, expression: str) -> list[str]:
+        """Datasets referenced as `dataset.column` qualifiers, in first-occurrence order."""
+        seen: dict[str, None] = {}
+        for match in _QUALIFIED_REF_RE.findall(expression):
+            if match in self.datasets:
+                seen[match] = None
+        return list(seen)
+
+    def join_path(self, dataset_names: list[str] | set[str]) -> list[OssieRelationship]:
+        """Relationships connecting the given datasets: union of shortest paths from
+        the root to each target dataset (not a full BFS spanning tree — irrelevant
+        datasets that merely happen to be closer to the root than a target are not
+        pulled in).
+
+        The first element of `dataset_names` (order preserved for lists; arbitrary for
+        sets) is used as the root, e.g. the base table in a generated FROM clause.
+        """
+        ordered = list(dict.fromkeys(dataset_names))
+        if not ordered:
+            return []
+        for name in ordered:
+            if name not in self.datasets:
+                raise UnresolvedJoinError(f"Unknown dataset: {name!r}")
+
+        root = ordered[0]
+        targets = ordered[1:]
+        if not targets:
+            return []
+
+        # BFS from root, recording the edge/predecessor used to first reach each node.
+        predecessor_edge: dict[str, OssieRelationship] = {}
+        predecessor_node: dict[str, str] = {}
+        visited = {root}
+        queue: deque[str] = deque([root])
+        while queue:
+            current = queue.popleft()
+            for neighbor, rel in self._adjacency.get(current, []):
+                if neighbor in visited:
+                    continue
+                visited.add(neighbor)
+                predecessor_edge[neighbor] = rel
+                predecessor_node[neighbor] = current
+                queue.append(neighbor)
+
+        missing = [t for t in targets if t not in visited]
+        if missing:
+            raise UnresolvedJoinError(
+                f"No relationship path connects dataset(s) {missing} to {root!r}"
+            )
+
+        # Union the shortest root->target path edges, in root-to-leaf order, dedup'd.
+        edges: list[OssieRelationship] = []
+        added_nodes = {root}
+        for target in targets:
+            path_nodes: list[str] = []
+            node = target
+            while node not in added_nodes:
+                path_nodes.append(node)
+                node = predecessor_node[node]
+            for n in reversed(path_nodes):
+                edges.append(predecessor_edge[n])
+                added_nodes.add(n)
+        return edges
+
+    def resolve_expression(self, expression: OssieExpression, dialect: OssieDialect) -> str:
+        """Pick the expression text for `dialect`, falling back to ANSI_SQL."""
+        by_dialect = {d.dialect: d.expression for d in expression.dialects}
+        if dialect in by_dialect:
+            return by_dialect[dialect]
+        if OssieDialect.ANSI_SQL in by_dialect:
+            return by_dialect[OssieDialect.ANSI_SQL]
+        raise MissingExpressionError(
+            f"No expression for dialect {dialect!r} or ANSI_SQL fallback"
+        )