dataface 0.1.2__py3-none-any.whl

dataface/ai/llm.py

@@ -0,0 +1,403 @@
+"""Thin LLM client adapters for the terminal agent."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterator
+from typing import Any, Protocol
+
+import httpx
+
+from dataface._install_hint import install_hint
+from dataface.ai.events import ContentDelta, StreamEvent, ThinkingStatus, ToolCallEvent
+from dataface.ai.tool_schemas import ALL_TOOLS
+
+DEFAULT_OPENAI_MODEL = "gpt-4.1-mini"
+DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-5"
+
+
+def infer_provider(model: str | None) -> str:
+    if model and model.startswith("anthropic:"):
+        return "anthropic"
+    if model and model.startswith("openai:"):
+        return "openai"
+    if model and model.lower().startswith("claude"):
+        return "anthropic"
+    if model and model.lower().startswith(("gpt", "o1", "o3", "o4")):
+        return "openai"
+    if not model and not os.getenv("OPENAI_API_KEY") and os.getenv("ANTHROPIC_API_KEY"):
+        return "anthropic"
+    return "openai"
+
+
+def _strip_provider_prefix(model: str | None) -> str | None:
+    if model and ":" in model:
+        provider, _, raw_model = model.partition(":")
+        if provider in {"openai", "anthropic"} and raw_model:
+            return raw_model
+    return model
+
+
+def _resolve_model(
+    explicit_model: str | None,
+    env_var: str,
+    default_model: str,
+) -> str:
+    return _strip_provider_prefix(explicit_model) or os.getenv(env_var) or default_model
+
+
+def _normalize_openai_tools(
+    tools: list[dict[str, Any]] | None,
+) -> list[dict[str, Any]]:
+    source_tools = tools or ALL_TOOLS
+    if not source_tools:
+        return []
+    if "input_schema" in source_tools[0]:
+        return [
+            {
+                "type": "function",
+                "name": tool["name"],
+                "description": tool["description"],
+                "parameters": tool["input_schema"],
+            }
+            for tool in source_tools
+        ]
+    return source_tools
+
+
+def _normalize_anthropic_tools(
+    tools: list[dict[str, Any]] | None,
+) -> list[dict[str, Any]]:
+    source_tools = tools or ALL_TOOLS
+    if not source_tools:
+        return []
+    if "input_schema" in source_tools[0]:
+        return [
+            {
+                "name": tool["name"],
+                "description": tool["description"],
+                "input_schema": tool["input_schema"],
+            }
+            for tool in source_tools
+        ]
+    return source_tools
+
+
+class LLMClientError(RuntimeError):
+    """Raised when a provider request fails."""
+
+
+def _is_openai_api_error(exc: Exception) -> bool:
+    try:
+        from openai import APIError
+    except ImportError:
+        return isinstance(exc, httpx.HTTPError)
+    return isinstance(exc, (APIError, httpx.HTTPError))
+
+
+def _is_anthropic_api_error(exc: Exception) -> bool:
+    try:
+        from anthropic import APIError
+    except ImportError:
+        return isinstance(exc, httpx.HTTPError)
+    return isinstance(exc, (APIError, httpx.HTTPError))
+
+
+# -- Provider stream adapter ------------------------------------------------
+
+
+def _iter_anthropic_stream(stream_ctx: Any) -> Iterator[StreamEvent]:
+    """Parse Anthropic Messages API stream context manager into typed events."""
+    with stream_ctx as stream:
+        for event in stream:
+            if event.type == "content_block_delta" and event.delta.type == "text_delta":
+                yield ContentDelta(delta=event.delta.text)
+
+        final_message = stream.get_final_message()
+
+    for block in final_message.content:
+        if block.type == "tool_use":
+            yield ToolCallEvent(
+                id=block.id, name=block.name, arguments=dict(block.input)
+            )
+
+
+# -- Client protocol and implementations ------------------------------------
+
+
+class LLMClient(Protocol):
+    """Provider-neutral streaming interface."""
+
+    provider: str
+    model: str
+
+    def stream_with_tools(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        system_prompt: str,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> Iterator[StreamEvent]: ...
+
+
+class OpenAIClient:
+    """Responses API client with streaming output and tool calls."""
+
+    provider = "openai"
+
+    def __init__(self, model: str | None = None, api_key: str | None = None) -> None:
+        self.model = _resolve_model(
+            model,
+            "OPENAI_MODEL",
+            DEFAULT_OPENAI_MODEL,
+        )
+        self.api_key = api_key or os.getenv("OPENAI_API_KEY")
+        self._client: Any = None
+        self._previous_response_id: str | None = None
+        self._sent_message_count = 0
+
+    @property
+    def client(self) -> Any:
+        if self._client is None:
+            try:
+                from openai import OpenAI
+            except ImportError as exc:
+                raise RuntimeError(
+                    f"OpenAI client is not installed. Install with: {install_hint('chat')}"
+                ) from exc
+            self._client = OpenAI(api_key=self.api_key)
+        return self._client
+
+    def create(self, **kwargs: Any) -> Any:
+        """Non-streaming Responses API call with unified error handling.
+
+        Wraps ``client.responses.create()`` with the same exception
+        handling used by the streaming path, translating API and network
+        errors into :class:`LLMClientError`.
+        """
+        try:
+            return self.client.responses.create(**kwargs)
+        except Exception as exc:
+            if _is_openai_api_error(exc):
+                raise LLMClientError(str(exc)) from exc
+            raise
+
+    def _messages_to_input(
+        self, messages: list[dict[str, Any]], incremental: bool
+    ) -> list[dict[str, Any]]:
+        source_messages = (
+            messages[self._sent_message_count :] if incremental else messages
+        )
+        items: list[dict[str, Any]] = []
+        for message in source_messages:
+            role = message["role"]
+            if not incremental and (
+                role == "tool" or (role == "assistant" and message.get("tool_calls"))
+            ):
+                raise LLMClientError(
+                    "OpenAI client requires an unbroken previous_response_id chain for tool-use history."
+                )
+            if role in {"user", "assistant"}:
+                content = message.get("content")
+                if content:
+                    items.append({"role": role, "content": content})
+            elif role == "tool":
+                items.append(
+                    {
+                        "type": "function_call_output",
+                        "call_id": message["tool_call_id"],
+                        "output": message["content"],
+                    }
+                )
+        return items
+
+    def stream_with_tools(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        system_prompt: str,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> Iterator[StreamEvent]:
+        incremental = self._previous_response_id is not None
+        input_items = self._messages_to_input(messages, incremental=incremental)
+        if not input_items:
+            return
+
+        previous_response_id = self._previous_response_id
+        pending_response_id = previous_response_id
+
+        kwargs: dict[str, Any] = {
+            "model": self.model,
+            "instructions": system_prompt,
+            "input": input_items,
+            "tools": _normalize_openai_tools(tools),
+            "stream": True,
+        }
+        if self._previous_response_id:
+            kwargs["previous_response_id"] = self._previous_response_id
+
+        try:
+            stream = self.client.responses.create(**kwargs)
+        except Exception as exc:
+            if _is_openai_api_error(exc):
+                raise LLMClientError(str(exc)) from exc
+            raise
+        try:
+            # Keep OpenAI parsing inline here because previous_response_id tracking
+            # and rollback on stream failure are part of the same control flow.
+            for event in stream:
+                event_type = getattr(event, "type", "")
+
+                if event_type == "response.created":
+                    pending_response_id = event.response.id
+                    continue
+
+                if event_type == "response.output_text.delta":
+                    yield ContentDelta(delta=event.delta)
+                    continue
+
+                if event_type == "response.reasoning_summary_text.delta":
+                    yield ThinkingStatus(status=event.delta)
+                    continue
+
+                if event_type != "response.output_item.done":
+                    continue
+
+                item = event.item
+                if item.type != "function_call":
+                    continue
+
+                arguments = json.loads(item.arguments) if item.arguments else {}
+                yield ToolCallEvent(
+                    id=item.call_id, name=item.name, arguments=arguments
+                )
+        except Exception as exc:
+            self._previous_response_id = previous_response_id
+            if _is_openai_api_error(exc):
+                raise LLMClientError(str(exc)) from exc
+            raise
+
+        self._previous_response_id = pending_response_id
+        self._sent_message_count = len(messages)
+
+
+class AnthropicClient:
+    """Messages API client with tool-use support."""
+
+    provider = "anthropic"
+
+    def __init__(self, model: str | None = None, api_key: str | None = None) -> None:
+        self.model = _resolve_model(
+            model,
+            "ANTHROPIC_MODEL",
+            DEFAULT_ANTHROPIC_MODEL,
+        )
+        self.api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
+        self._client: Any = None
+
+    @property
+    def client(self) -> Any:
+        if self._client is None:
+            try:
+                from anthropic import Anthropic
+            except ImportError as exc:
+                raise RuntimeError(
+                    f"Anthropic client is not installed. Install with: {install_hint('chat')}"
+                ) from exc
+            self._client = Anthropic(api_key=self.api_key)
+        return self._client
+
+    def _messages_to_input(
+        self, messages: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        converted: list[dict[str, Any]] = []
+        pending_tool_results: list[dict[str, Any]] = []
+
+        def flush_tool_results() -> None:
+            if pending_tool_results:
+                converted.append(
+                    {"role": "user", "content": list(pending_tool_results)}
+                )
+                pending_tool_results.clear()
+
+        for message in messages:
+            role = message["role"]
+            if role == "tool":
+                pending_tool_results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": message["tool_call_id"],
+                        "content": message["content"],
+                    }
+                )
+                continue
+
+            flush_tool_results()
+
+            if role == "assistant" and message.get("tool_calls"):
+                blocks: list[dict[str, Any]] = []
+                if message.get("content"):
+                    blocks.append({"type": "text", "text": message["content"]})
+                for tool_call in message["tool_calls"]:
+                    blocks.append(
+                        {
+                            "type": "tool_use",
+                            "id": tool_call["id"],
+                            "name": tool_call["name"],
+                            "input": tool_call["arguments"],
+                        }
+                    )
+                converted.append({"role": "assistant", "content": blocks})
+                continue
+
+            content = message.get("content")
+            if content:
+                converted.append(
+                    {"role": role, "content": [{"type": "text", "text": content}]}
+                )
+
+        flush_tool_results()
+        return converted
+
+    def stream_with_tools(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        system_prompt: str,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> Iterator[StreamEvent]:
+        try:
+            yield from _iter_anthropic_stream(
+                self.client.messages.stream(
+                    model=self.model,
+                    system=system_prompt,
+                    messages=self._messages_to_input(messages),
+                    tools=_normalize_anthropic_tools(tools),
+                    max_tokens=4096,
+                )
+            )
+        except Exception as exc:
+            if _is_anthropic_api_error(exc):
+                raise LLMClientError(str(exc)) from exc
+            raise
+
+
+def create_client(provider: str | None = None, model: str | None = None) -> LLMClient:
+    """Create an LLM client from explicit provider or model naming."""
+    if (
+        not provider
+        and not model
+        and not os.getenv("OPENAI_API_KEY")
+        and not os.getenv("ANTHROPIC_API_KEY")
+    ):
+        raise RuntimeError(
+            "No LLM API key found. Set OPENAI_API_KEY or ANTHROPIC_API_KEY "
+            "in the environment, or pass --model to select a provider explicitly."
+        )
+    resolved_provider = provider or infer_provider(model)
+    if resolved_provider == "anthropic":
+        return AnthropicClient(model=model)
+    if resolved_provider == "openai":
+        return OpenAIClient(model=model)
+    raise ValueError(f"Unsupported provider: {resolved_provider}")

dataface/ai/mcp/__init__.py

@@ -0,0 +1,51 @@
+"""Dataface MCP (Model Context Protocol) Server.
+
+This module provides an MCP server that enables AI assistants (Claude, Cursor,
+ChatGPT, etc.) to interact with Dataface dashboards through a standardized
+protocol.
+
+Architecture:
+    Resources (read-only context):
+        - dataface://dashboards - List of dashboards in project
+        - dataface://dashboard/{path} - Dashboard content and structure
+        - dataface://docs/all - Whole DATAFACE_SYNTAX.md (full YAML reference)
+        - dataface://docs/{topic} - One H2 section of the YAML reference
+        - dataface://guide/dashboard-design - Dashboard design principles
+        - dataface://guide/report-design - Report design principles
+        - dataface://guide/dashboard-build - Build-test-iterate workflow
+        - dataface://guide/dashboard-review - Dashboard review (structural + visual)
+
+    Tools (actions):
+        - render_dashboard - Validate + render; pass as_link=true for URL-only (folds view_dashboard)
+        - execute_query - Run SQL against data sources
+        - query_face - Run one named query from a face YAML and return columns + rows
+        - schema - Drill the data hierarchy: source → schema → table → column
+        - search_dashboards - Search dashboards by keyword/structure
+        - docs - Browse Dataface YAML reference docs offline
+
+Usage:
+    # Configure MCP for your AI client
+    dft init mcp cursor     # or: vscode, claude, claude-code, codex, copilot, print
+    dft init mcp --all
+
+    # Start the MCP server (stdio mode)
+    dft mcp serve
+
+    # Or programmatically
+    from dataface.ai.mcp import create_server
+    server = create_server()
+    await server.run()
+
+For more information about MCP, see:
+    https://modelcontextprotocol.io/
+"""
+
+from dataface.ai.context import DatafaceAIContext
+from dataface.ai.mcp.server import create_server, run_server
+
+__all__ = [
+    # Server
+    "create_server",
+    "run_server",
+    "DatafaceAIContext",
+]