dataface 0.1.2__py3-none-any.whl

dataface/agent_api/describe.py

@@ -0,0 +1,366 @@
+"""Typed describe verb — face structure inspection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from dataface.core.compile.models.chart.compiled import (
+    Chart,
+)
+from dataface.core.compile.models.face.compiled import Layout
+from dataface.core.compile.models.query.compiled import (
+    CsvQuery,
+    DbtModelQuery,
+    HttpQuery,
+    MetricFlowQuery,
+    Query,
+    SqlQuery,
+    ValuesQuery,
+)
+from dataface.core.errors import DF_UNKNOWN_INTERNAL, StructuredError
+
+# Chart-encoding fields surfaced to agents. Covers the stable channel fields
+# across chart families. `label` is excluded — it's a KPI-specific render hint,
+# not an encoding channel that binds a column.
+_ENCODING_FIELDS: tuple[str, ...] = (
+    "x",
+    "y",
+    "color",
+    "size",
+    "shape",
+    "theta",
+    "value",
+)
+
+
+# ---------------------------------------------------------------------------
+# Sub-models
+# ---------------------------------------------------------------------------
+
+
+class QueryDescription(BaseModel):
+    name: str
+    type: str
+    summary: str
+    source: str | None = None
+    sql: str | None = None
+
+
+class ChartDescription(BaseModel):
+    name: str
+    type: str
+    query: str
+    title: str | None = None
+    encoding: dict[str, Any] = Field(
+        default_factory=dict, description="Vega-Lite encoding channels keyed by role."
+    )
+
+
+class VariableDescription(BaseModel):
+    name: str
+    type: str
+    default: Any | None = None
+    options: list[str] | None = None
+
+
+class LayoutDescription(BaseModel):
+    primitive: str
+    items: list[str] = Field(
+        default_factory=list,
+        description="Layout item identifiers (chart IDs, text keys).",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Result models
+# ---------------------------------------------------------------------------
+
+
+class DescribeFaceArgs(BaseModel):
+    """Describe the structure of a face file: queries (with type and source), charts (with query bindings and encoding), variables, and layout. Use this for orientation when picking up an unfamiliar dashboard — it reads the YAML and returns a curated narrative summary without executing any queries."""
+
+    path: Path = Field(description="Path to the dashboard YAML file to describe")
+    project_dir: Path | None = Field(
+        None, description="Project root for resolving relative paths"
+    )
+
+
+class DescribeFaceResult(BaseModel):
+    success: bool
+    path: Path
+    title: str | None = None
+    description: str | None = None
+    queries: list[QueryDescription] = Field(
+        default_factory=list, description="Queries defined in the face."
+    )
+    charts: list[ChartDescription] = Field(
+        default_factory=list, description="Charts defined in the face."
+    )
+    variables: list[VariableDescription] = Field(
+        default_factory=list, description="Variables defined in the face."
+    )
+    layout: LayoutDescription | None = None
+    errors: list[StructuredError] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_query_description(name: str, query: Query) -> QueryDescription:
+    """Map an AnyQuery union variant onto a typed description."""
+    match query:
+        case SqlQuery():
+            # SqlQuery.source can be a dict for inline configs; only surface the
+            # name when it's a plain string reference.
+            source = query.source if isinstance(query.source, str) else None
+            sql = query.sql or None
+            summary = f"SQL query{f' against `{source}`' if source else ''}"
+            return QueryDescription(
+                name=name, type="sql", summary=summary, source=source, sql=sql
+            )
+        case CsvQuery():
+            return QueryDescription(
+                name=name, type="csv", summary=f"CSV file: {query.file}"
+            )
+        case DbtModelQuery():
+            return QueryDescription(
+                name=name, type="dbt_model", summary=f"dbt model: {query.model}"
+            )
+        case HttpQuery():
+            return QueryDescription(
+                name=name, type="http", summary=f"HTTP request: {query.url}"
+            )
+        case MetricFlowQuery():
+            return QueryDescription(
+                name=name, type="metricflow", summary="MetricFlow query"
+            )
+        case ValuesQuery():
+            return QueryDescription(name=name, type="values", summary="Inline values")
+        case _:
+            return QueryDescription(
+                name=name, type=query.query_type, summary=f"{query.query_type} query"
+            )
+
+
+def _collect_layout_items(layout: Layout, prefix: str = "") -> list[str]:
+    """Walk a Layout, returning chart names in display order.
+
+    Nested faces recurse with a prefix so the caller can tell layers apart.
+    """
+    out: list[str] = []
+    for item in layout.items:
+        if item.type == "chart" and item.chart is not None:
+            out.append(f"{prefix}{item.chart.id}" if prefix else item.chart.id)
+        elif item.type == "face" and item.face is not None:
+            sub_prefix = f"{item.face.id or '<nested>'}."
+            out.extend(_collect_layout_items(item.face.layout, sub_prefix))
+    return out
+
+
+def _encoding_for_chart(chart: Chart) -> dict[str, Any]:
+    """Surface chart encoding bindings (column names) as JSON-friendly values.
+
+    `y` is `str | list[str]` (multi-series), and `color` accepts
+    dicts. Pass scalars and lists through unchanged so multi-series faces
+    don't get their `y: [revenue, profit]` flattened into Python repr. The
+    `value` is always a column reference string; pass through unchanged.
+    """
+    enc: dict[str, Any] = {}
+    for field in _ENCODING_FIELDS:
+        # No default on getattr — a typo in _ENCODING_FIELDS should raise
+        # loudly, not be silently skipped.
+        v = getattr(chart, field)
+        if v is None or v == "":
+            continue
+        enc[field] = v
+    return enc
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def describe_face(path: Path, project_dir: Path | None = None) -> DescribeFaceResult:
+    """Describe the structure of a face: queries, charts, variables, layout."""
+    from dataface.agent_api._paths import no_project_hint, resolve_scoped_path
+    from dataface.core.compile.compiler import compile_file
+    from dataface.core.compile.errors import DatafaceError
+
+    try:
+        resolved = resolve_scoped_path(path, project_dir)
+    except ValueError as exc:
+        return DescribeFaceResult(
+            success=False,
+            path=path,
+            errors=[
+                DatafaceError.from_code(
+                    DF_UNKNOWN_INTERNAL, message=str(exc)
+                ).to_structured()
+            ],
+        )
+
+    if not resolved.exists():
+        hint = no_project_hint(project_dir)
+        return DescribeFaceResult(
+            success=False,
+            path=path,
+            errors=[
+                DatafaceError.from_code(
+                    DF_UNKNOWN_INTERNAL,
+                    message=f"File not found: {resolved}{hint}",
+                ).to_structured()
+            ],
+        )
+
+    try:
+        result = compile_file(resolved)
+    except OSError as exc:
+        return DescribeFaceResult(
+            success=False,
+            path=resolved,
+            errors=[
+                DatafaceError.from_code(
+                    DF_UNKNOWN_INTERNAL, message=str(exc)
+                ).to_structured(file=str(resolved))
+            ],
+        )
+
+    if result.errors:
+        return DescribeFaceResult(
+            success=False,
+            path=resolved,
+            errors=list(result.errors),
+        )
+
+    face = result.face
+    if face is None:
+        return DescribeFaceResult(
+            success=False,
+            path=resolved,
+            errors=[
+                DatafaceError.from_code(
+                    DF_UNKNOWN_INTERNAL, message="Compilation produced no face"
+                ).to_structured(file=str(resolved))
+            ],
+        )
+
+    query_descs = [
+        _build_query_description(name, query) for name, query in face.queries.items()
+    ]
+
+    chart_descs = [
+        ChartDescription(
+            name=name,
+            type=chart.type,
+            query=chart.query_name or name,
+            title=chart.title or None,
+            encoding=_encoding_for_chart(chart),
+        )
+        for name, chart in face.charts.items()
+    ]
+
+    var_descs: list[VariableDescription] = []
+    for name, var in face.variables.items():
+        static = var.options.static if var.options is not None else None
+        var_descs.append(
+            VariableDescription(
+                name=name,
+                type=str(var.input),
+                default=var.default,
+                options=[str(o) for o in static] if static else None,
+            )
+        )
+
+    layout_type = face.layout.type
+    layout_primitive = (
+        layout_type.value if hasattr(layout_type, "value") else str(layout_type)
+    )
+    layout_desc = LayoutDescription(
+        primitive=layout_primitive,
+        items=_collect_layout_items(face.layout),
+    )
+
+    return DescribeFaceResult(
+        success=True,
+        path=resolved,
+        title=face.title or None,
+        description=face.description or None,
+        queries=query_descs,
+        charts=chart_descs,
+        variables=var_descs,
+        layout=layout_desc,
+    )
+
+
+def describe_paths(
+    paths: list[Path],
+    project_dir: Path | None = None,
+) -> list[DescribeFaceResult]:
+    """Describe N face files / directories.
+
+    Each argv path expands like the single-path verb: a file describes directly,
+    a directory walks recursively (skipping ``_*.yml`` partials and ejected
+    inspect-template directories). Results are concatenated in argv order.
+    """
+    out: list[DescribeFaceResult] = []
+    for p in paths:
+        out.extend(_describe_one_path(p, project_dir=project_dir))
+    return out
+
+
+def _describe_one_path(
+    path: Path,
+    project_dir: Path | None = None,
+) -> list[DescribeFaceResult]:
+    """Per-argv expansion: file → [one], dir → walk."""
+    # WHY: dataface.core.inspect.manifest_utils triggers the inspect package
+    # __init__, which eagerly imports TableInspector + grain/quality/semantic
+    # detectors. Keep this lazy so `dft --help` doesn't pay that startup cost.
+    from dataface.agent_api._paths import resolve_scoped_path
+    from dataface.core.compile.errors import DatafaceError
+    from dataface.core.inspect.manifest_utils import INSPECT_TEMPLATE_MANIFEST
+
+    try:
+        resolved = resolve_scoped_path(path, project_dir)
+    except ValueError as exc:
+        return [
+            DescribeFaceResult(
+                success=False,
+                path=path,
+                errors=[
+                    DatafaceError.from_code(
+                        DF_UNKNOWN_INTERNAL, message=str(exc)
+                    ).to_structured()
+                ],
+            )
+        ]
+
+    if not resolved.is_dir():
+        return [describe_face(resolved, project_dir=project_dir)]
+
+    template_dirs = {m.parent for m in resolved.glob(f"**/{INSPECT_TEMPLATE_MANIFEST}")}
+    yaml_files = sorted(
+        f
+        for f in (list(resolved.glob("**/*.yml")) + list(resolved.glob("**/*.yaml")))
+        if not f.name.startswith("_") and f.parent not in template_dirs
+    )
+    if not yaml_files:
+        return [
+            DescribeFaceResult(
+                success=False,
+                path=resolved,
+                errors=[
+                    DatafaceError.from_code(
+                        DF_UNKNOWN_INTERNAL,
+                        message=f"No face files found in {resolved}",
+                    ).to_structured()
+                ],
+            )
+        ]
+    return [describe_face(f, project_dir=project_dir) for f in yaml_files]

dataface/agent_api/describe_query.py

@@ -0,0 +1,120 @@
+"""describe_query verb — return column schema for a SQL string without fetching rows."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from dataface.core.execute.adapters import AdapterRegistry
+from dataface.core.execute.adapters.dbt_adapter_factory import build_adapter
+from dataface.core.inspect.query_validator import validate_query
+
+
+class DescribeQueryArgs(BaseModel):
+    """Return the column schema (names + types) for a SQL string without executing it for data.
+
+    Gates on validate_query first — short-circuits on parse errors and missing join
+    predicates with actionable diagnostics; otherwise returns columns alongside any
+    non-error diagnostics (e.g. fanout_risk warnings) so the agent can read them
+    without being blocked from the column shape.
+    """
+
+    sql: str = Field(..., description="SQL query to describe.")
+    source: str | None = Field(
+        None, description="Data source name to describe against."
+    )
+    dialect: str | None = Field(
+        None, description="SQL dialect hint for the validator (duckdb, bigquery, etc.)."
+    )
+
+
+class DescribeQueryColumn(BaseModel):
+    name: str
+    type: str
+    char_size: int | None = None
+    numeric_precision: int | None = None
+    numeric_scale: int | None = None
+
+
+class DescribeQueryResult(BaseModel):
+    success: bool
+    columns: list[DescribeQueryColumn] | None = None
+    diagnostics: list[dict] = Field(
+        default_factory=list,
+        description="Dialect-specific diagnostic messages from the query runner.",
+    )
+    error: str | None = None
+
+
+def describe_query(
+    sql: str,
+    *,
+    source: str | None = None,
+    dialect: str | None = None,
+    adapter_registry: AdapterRegistry,
+) -> DescribeQueryResult:
+    """Return the column schema for a SQL string using the dbt adapter.
+
+    Runs validate_query first; short-circuits on error-severity diagnostics
+    (parse_error, missing_join_predicate) without calling the warehouse.
+    Non-error diagnostics are surfaced on the result alongside the column schema.
+    """
+    try:
+        diags = validate_query(sql, dialect=dialect)
+
+        error_diags = [d for d in diags if d.severity == "error"]
+        if error_diags:
+            return DescribeQueryResult(
+                success=False,
+                columns=None,
+                diagnostics=[d.to_dict() for d in diags],
+                error=error_diags[0].message,
+            )
+
+        cfg = adapter_registry.resolve_source_config(source)
+
+        if cfg.get("type") == "duckdb":
+            # Run DESCRIBE via the registry's existing read-only SqlAdapter so
+            # we don't open a writable dbt-duckdb connection that would conflict
+            # with dft serve.
+            cols = _duckdb_describe(sql, source, adapter_registry)
+        else:
+            adapter = build_adapter(cfg, read_only=True)
+            with adapter.connection_named("dataface_describe"):
+                raw = adapter.get_column_schema_from_query(sql)
+            cols = [
+                DescribeQueryColumn(
+                    name=c.name,
+                    type=c.dtype,
+                    char_size=c.char_size,
+                    numeric_precision=c.numeric_precision,
+                    numeric_scale=c.numeric_scale,
+                )
+                for c in raw
+            ]
+
+        return DescribeQueryResult(
+            success=True,
+            columns=cols,
+            diagnostics=[d.to_dict() for d in diags],
+        )
+
+    except Exception as e:  # noqa: BLE001 — adapter boundary, mirrors execute_query
+        return DescribeQueryResult(
+            success=False,
+            error=str(e),
+        )
+
+
+def _duckdb_describe(
+    sql: str, source: str | None, adapter_registry: AdapterRegistry
+) -> list[DescribeQueryColumn]:
+    """Run DESCRIBE ({sql}) via the registry's read-only SqlAdapter."""
+    from dataface.core.compile.models.query.compiled import SqlQuery
+
+    result = adapter_registry.execute(SqlQuery(sql=f"DESCRIBE ({sql})", source=source))
+    if result.error:
+        raise RuntimeError(result.error)
+    return [
+        DescribeQueryColumn(name=row["column_name"], type=row["column_type"])
+        for row in result.data
+    ]

dataface/agent_api/docs/__init__.py

@@ -0,0 +1,25 @@
+"""dataface.agent_api.docs — single-file syntax reference, sliced by H2."""
+
+from dataface.agent_api.docs._loader import (
+    DocsArgs,
+    DocsCorpusMissingError,
+    DocsResult,
+    DocsSearchHit,
+    Topic,
+    TopicEntry,
+    docs,
+    read_full_text,
+    slugify,
+)
+
+__all__ = [
+    "docs",
+    "read_full_text",
+    "slugify",
+    "TopicEntry",
+    "DocsArgs",
+    "DocsCorpusMissingError",
+    "DocsResult",
+    "DocsSearchHit",
+    "Topic",
+]