dataface 0.1.2__py3-none-any.whl

dataface/agent_api/validate_query.py

@@ -0,0 +1,84 @@
+"""validate_query verb — static SQL lint without warehouse access."""
+
+from __future__ import annotations
+
+import importlib.util
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from dataface.core.inspect.query_validator import (
+    RelationshipContext,
+    validate_query as _core_validate,
+)
+
+_SUPER_SCHEMA_AVAILABLE = importlib.util.find_spec("dataface_super_schema") is not None
+
+
+def _load_relationship_context() -> RelationshipContext | None:
+    """Load relationship context from the private package when available."""
+    if not _SUPER_SCHEMA_AVAILABLE:
+        return None
+    from dataface_super_schema.inspect.relationship_context import (  # noqa: PLC0415
+        load_relationship_context,
+    )
+
+    return load_relationship_context()
+
+
+class ValidateQueryResult(BaseModel):
+    has_errors: bool = Field(
+        False,
+        description="True when any active diagnostic has severity == 'error'.",
+    )
+    diagnostics: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Active diagnostic messages (non-suppressed).",
+    )
+    suppressed: list[dict[str, Any]] | None = Field(
+        None,
+        description="Suppressed diagnostics (only present when return_suppressed=True).",
+    )
+
+
+def validate_query(
+    sql: str,
+    *,
+    dialect: str | None = None,
+    return_suppressed: bool = False,
+    relationship_context: RelationshipContext | None = None,
+) -> ValidateQueryResult:
+    """Run static SQL validation and return a typed result.
+
+    Loads relationship context from the inspection cache automatically (same
+    as the CLI command). Pass relationship_context explicitly to override.
+    """
+    if relationship_context is None:
+        relationship_context = _load_relationship_context()
+
+    if return_suppressed:
+        diags, suppressed = _core_validate(
+            sql,
+            dialect=dialect,
+            relationship_context=relationship_context,
+            return_suppressed=True,
+        )
+        suppressed_dicts: list[dict[str, Any]] | None = [
+            d.to_dict() for d in suppressed
+        ]
+    else:
+        diags = _core_validate(
+            sql,
+            dialect=dialect,
+            relationship_context=relationship_context,
+        )
+        suppressed_dicts = None
+
+    diag_dicts = [d.to_dict() for d in diags]
+    has_errors = any(d.get("severity") == "error" for d in diag_dicts)
+
+    return ValidateQueryResult(
+        has_errors=has_errors,
+        diagnostics=diag_dicts,
+        suppressed=suppressed_dicts,
+    )

dataface/ai/__init__.py

@@ -0,0 +1,39 @@
+"""Core AI utilities for Dataface.
+
+This module provides shared AI service utilities used by both Playground and Suite.
+It consolidates common patterns like prompt loading, tool definitions, and YAML extraction.
+
+Modules:
+    prompts: Prompt loading and building utilities
+    tools: Common AI tool definitions (render_dashboard, execute_query, schema)
+    yaml_utils: YAML extraction from AI responses
+"""
+
+from dataface.ai.prompts import PromptLoader, load_prompt
+from dataface.ai.schema_context import get_schema_context
+from dataface.ai.tools import (
+    TOOL_EXECUTE_QUERY,
+    TOOL_RENDER_DASHBOARD,
+    TOOL_SCHEMA,
+    TOOL_SEARCH_DASHBOARDS,
+    get_tools,
+    handle_tool_call,
+)  # noqa: F401 — re-exported for public surface
+from dataface.ai.yaml_utils import extract_yaml
+
+__all__ = [
+    # Prompts
+    "load_prompt",
+    "PromptLoader",
+    # Tools
+    "get_tools",
+    "handle_tool_call",
+    "TOOL_RENDER_DASHBOARD",
+    "TOOL_EXECUTE_QUERY",
+    "TOOL_SCHEMA",
+    "TOOL_SEARCH_DASHBOARDS",
+    # Schema context
+    "get_schema_context",
+    # YAML utilities
+    "extract_yaml",
+]

dataface/ai/agent.py

@@ -0,0 +1,139 @@
+"""Provider-neutral agent loop for the terminal agent."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Generator
+from typing import TYPE_CHECKING, Any
+
+from dataface.agent_api.docs import read_full_text as _read_dataface_syntax
+from dataface.ai.context import DatafaceAIContext
+
+if TYPE_CHECKING:
+    from dataface.ai.external_mcp import ExternalMCPManager
+
+from dataface.ai.events import (
+    AgentDone,
+    AgentError,
+    AgentEvent,
+    ContentDelta,
+    ToolCallEvent,
+    ToolResultEvent,
+)
+from dataface.ai.llm import LLMClient, LLMClientError
+from dataface.ai.memories import format_memories_prompt, load_memories
+from dataface.ai.prompts import load_shared_prompt
+from dataface.ai.schema_context import get_schema_context
+from dataface.ai.tool_schemas import ALL_TOOLS
+from dataface.ai.tools import dispatch_tool_call
+
+_TOOL_GUIDANCE = """## Tool Use
+
+- Use `schema` (drill from sources → schema → table → column) and `execute_query` to inspect real data before making claims.
+- Use `search_dashboards` to reuse existing patterns when relevant.
+- Use `render_dashboard` to validate dashboard YAML and inspect resolved chart/data semantics before treating it as finished.
+- Use `render_dashboard(path=..., as_link=true)` to surface a localhost URL the user can open to view a saved dashboard in their browser.
+- If a tool returns an error, explain it clearly instead of hiding it.
+"""
+
+
+def build_agent_system_prompt(context: DatafaceAIContext) -> str:
+    """Build the terminal agent system prompt from shared skills and schema context."""
+    parts = [
+        load_shared_prompt("dashboard-build"),
+        load_shared_prompt("dashboard-design"),
+        load_shared_prompt("dashboard-review"),
+        _read_dataface_syntax(),
+    ]
+
+    schema_context = get_schema_context(
+        adapter_registry=context.adapter_registry,
+    )
+    if schema_context and not schema_context.startswith(
+        "No database connection available"
+    ):
+        parts.append(schema_context)
+
+    memory_block = format_memories_prompt(load_memories(context.default_project_dir))
+    if memory_block:
+        parts.append(memory_block)
+
+    parts.append(_TOOL_GUIDANCE)
+    return "\n\n---\n\n".join(part for part in parts if part)
+
+
+def run_agent(
+    prompt: str,
+    *,
+    client: LLMClient,
+    context: DatafaceAIContext,
+    messages: list[dict[str, Any]] | None = None,
+    max_iterations: int = 12,
+    tools: list[dict[str, Any]] | None = None,
+    external_manager: ExternalMCPManager | None = None,
+) -> Generator[AgentEvent, None, None]:
+    """Run the agent loop and stream typed events.
+
+    Args:
+        tools: Tool list to pass to the LLM. Defaults to ALL_TOOLS (built-in only).
+            Pass a merged list to include external MCP tools.
+        external_manager: ExternalMCPManager instance for routing 'server__tool' calls.
+            Must be provided when tools contains external (namespaced) entries.
+    """
+    effective_tools = tools if tools is not None else ALL_TOOLS
+    conversation = messages if messages is not None else []
+    conversation.append({"role": "user", "content": prompt})
+    system_prompt = build_agent_system_prompt(context)
+
+    for _ in range(max_iterations):
+        response_text = ""
+        tool_calls: list[ToolCallEvent] = []
+
+        try:
+            for event in client.stream_with_tools(
+                messages=conversation,
+                system_prompt=system_prompt,
+                tools=effective_tools,
+            ):
+                if isinstance(event, ContentDelta):
+                    response_text += event.delta
+                elif isinstance(event, ToolCallEvent):
+                    tool_calls.append(event)
+                yield event
+        except LLMClientError as exc:
+            yield AgentError(message=str(exc))
+            return
+
+        conversation.append(
+            {
+                "role": "assistant",
+                "content": response_text,
+                "tool_calls": [
+                    {"id": tc.id, "name": tc.name, "arguments": tc.arguments}
+                    for tc in tool_calls
+                ],
+            }
+        )
+
+        if not tool_calls:
+            yield AgentDone(response=response_text)
+            return
+
+        for tc in tool_calls:
+            result = dispatch_tool_call(
+                tc.name,
+                tc.arguments,
+                context=context,
+                external_manager=external_manager,
+            )
+            conversation.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": tc.id,
+                    "name": tc.name,
+                    "content": json.dumps(result, default=str),
+                }
+            )
+            yield ToolResultEvent(id=tc.id, name=tc.name, result=result)
+
+    yield AgentError(message="Agent stopped after reaching max iterations.")

dataface/ai/context.py

@@ -0,0 +1,45 @@
+"""Shared scoping context for Dataface AI and MCP surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dataface.core.execute.adapters import AdapterRegistry
+
+
+@dataclass(frozen=True)
+class DatafaceAIContext:
+    """Scope shared AI/MCP helpers to a specific source boundary."""
+
+    adapter_registry: AdapterRegistry
+    dashboards_directory: Path | None = None
+    default_project_dir: Path | None = None
+    default_source: str | None = None
+    # Port of the embedded HTTP preview server. Set by `dft mcp serve` and
+    # `dft chat` after binding; consumed by `_view_url` to build clickable
+    # localhost URLs in `render_dashboard` responses (including as_link=True).
+    server_port: int | None = None
+
+    def resolve_dashboard_path(self, path: Path) -> Path:
+        """Resolve a dashboard path inside the scoped dashboards directory.
+
+        When no explicit dashboards directory is configured, paths default to the
+        project's ``faces/`` directory under the current working directory.
+        """
+        if path.is_absolute():
+            raise ValueError(f"Dashboard path must be relative: {path}")
+        if self.dashboards_directory is None:
+            base_dir = (Path.cwd() / "faces").resolve()
+        else:
+            base_dir = self.dashboards_directory.resolve()
+        resolved = (base_dir / path).resolve()
+        try:
+            resolved.relative_to(base_dir)
+        except ValueError as exc:
+            raise ValueError(
+                f"Dashboard path escapes scoped directory: {path}"
+            ) from exc
+        return resolved

dataface/ai/events.py

@@ -0,0 +1,62 @@
+"""Typed event protocol for the terminal agent loop."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+# -- Stream events (yielded by LLM provider adapters) -----------------------
+
+
+@dataclass(slots=True)
+class ContentDelta:
+    """Incremental text chunk from the model."""
+
+    delta: str
+
+
+@dataclass(slots=True)
+class ThinkingStatus:
+    """Reasoning/thinking status from the model."""
+
+    status: str
+
+
+@dataclass(slots=True)
+class ToolCallEvent:
+    """Model requested a tool invocation."""
+
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+StreamEvent = ContentDelta | ThinkingStatus | ToolCallEvent
+
+# -- Agent-level events (yielded by the agent loop) -------------------------
+
+
+@dataclass(slots=True)
+class ToolResultEvent:
+    """Result of executing a tool call."""
+
+    id: str
+    name: str
+    result: Any
+
+
+@dataclass(slots=True)
+class AgentDone:
+    """Agent finished with a final text response."""
+
+    response: str
+
+
+@dataclass(slots=True)
+class AgentError:
+    """Agent encountered an error."""
+
+    message: str
+
+
+AgentEvent = StreamEvent | ToolResultEvent | AgentDone | AgentError