dataface 0.1.2__py3-none-any.whl

dataface/agent_api/chat.py

@@ -0,0 +1,221 @@
+"""Chat session API for the Dataface agent."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from dataface.agent_api._session_store import (
+    SessionIndex,
+    SessionWriter,
+    load_session_for_resume,
+    new_session,
+)
+from dataface.ai.agent import run_agent
+from dataface.ai.context import DatafaceAIContext
+from dataface.ai.events import AgentEvent
+from dataface.ai.llm import create_client
+
+if TYPE_CHECKING:
+    from dataface.ai.external_mcp import ExternalMCPManager
+
+
+def _now_iso() -> str:
+    return datetime.now(tz=timezone.utc).astimezone().isoformat()
+
+
+@dataclass
+class ChatSession:
+    """Runtime handle for an active chat session."""
+
+    session_id: str
+    messages: list[dict[str, Any]]
+    context: DatafaceAIContext
+    model: str
+    created_at: str
+    last_used_at: str
+    client: Any = field(repr=False)
+    writer: SessionWriter = field(repr=False)
+
+
+@dataclass
+class ChatSessionSummary:
+    """Persisted metadata for a saved session."""
+
+    session_id: str
+    cwd: Path
+    started_at: str
+    model: str = ""
+
+
+def start_session(
+    *,
+    model: str | None = None,
+    project_dir: Path | None = None,
+    server_port: int | None = None,
+) -> ChatSession:
+    """Create a new chat session.
+
+    Args:
+        model: LLM model name, optionally provider-prefixed.
+        project_dir: Working directory for the session. Defaults to cwd.
+        server_port: Port of the embedded HTTP preview server, if running.
+    """
+    from dataface.core.execute.adapters import (
+        LOCAL_AUTHORING_REGISTRY_KWARGS,
+        build_adapter_registry,
+    )
+
+    cwd = (project_dir or Path.cwd()).resolve()
+    client = create_client(model=model)
+    context = DatafaceAIContext(
+        adapter_registry=build_adapter_registry(
+            cwd,
+            **LOCAL_AUTHORING_REGISTRY_KWARGS,
+        ),
+        default_project_dir=cwd,
+        server_port=server_port,
+    )
+    writer, _ = new_session(cwd, provider=client.provider, model=client.model)
+    return ChatSession(
+        session_id=writer.session_id,
+        messages=[],
+        context=context,
+        model=client.model,
+        created_at=writer.started_at,
+        last_used_at=writer.started_at,
+        client=client,
+        writer=writer,
+    )
+
+
+def resume_session(
+    session_id: str,
+    *,
+    project_dir: Path | None = None,
+    server_port: int | None = None,
+    model: str | None = None,
+    max_tokens: int = 32_000,
+) -> ChatSession:
+    """Load and resume a previously saved session.
+
+    Args:
+        session_id: The session id to resume.
+        project_dir: Working directory for the resumed session. Defaults to cwd.
+        server_port: Port of the embedded HTTP preview server, if running.
+        model: LLM model to use. Defaults to the same provider as the session.
+        max_tokens: Token budget for trimming old messages. 0 disables trimming.
+
+    Raises:
+        ValueError: If session not found, provider mismatch, or context window exceeded.
+    """
+    from dataface.core.execute.adapters import (
+        LOCAL_AUTHORING_REGISTRY_KWARGS,
+        build_adapter_registry,
+    )
+
+    cwd = (project_dir or Path.cwd()).resolve()
+    client = create_client(model=model)
+
+    messages, meta, _ = load_session_for_resume(
+        session_id,
+        expected_provider=client.provider,
+        max_tokens=max_tokens or None,
+    )
+
+    if client.provider == "openai" and _has_tool_history(messages):
+        raise ValueError(
+            f"Cannot resume session {session_id[:8]}: "
+            "OpenAI sessions with tool-call history cannot be resumed "
+            "(no previous_response_id chain). Start a new session."
+        )
+
+    context = DatafaceAIContext(
+        adapter_registry=build_adapter_registry(
+            cwd,
+            **LOCAL_AUTHORING_REGISTRY_KWARGS,
+        ),
+        default_project_dir=cwd,
+        server_port=server_port,
+    )
+    writer, _ = new_session(cwd, provider=client.provider, model=client.model)
+    return ChatSession(
+        session_id=session_id,
+        messages=messages,
+        context=context,
+        model=client.model,
+        created_at=meta.get("started_at", _now_iso()),
+        last_used_at=_now_iso(),
+        client=client,
+        writer=writer,
+    )
+
+
+def send_message(
+    session: ChatSession,
+    prompt: str,
+    *,
+    tools: list[dict[str, Any]] | None = None,
+    external_manager: ExternalMCPManager | None = None,
+) -> Generator[AgentEvent, None, None]:
+    """Send a prompt and stream typed agent events.
+
+    Mutates ``session.messages`` in place (run_agent appends as it goes).
+    Persists the new messages to disk after the turn completes.
+
+    Yields:
+        AgentEvent instances (ContentDelta, ToolCallEvent, ToolResultEvent,
+        ThinkingStatus, AgentDone, AgentError).
+    """
+    msg_count_before = len(session.messages)
+    try:
+        yield from run_agent(
+            prompt,
+            client=session.client,
+            context=session.context,
+            messages=session.messages,
+            tools=tools,
+            external_manager=external_manager,
+        )
+    finally:
+        session.last_used_at = _now_iso()
+        new_msgs = session.messages[msg_count_before:]
+        if new_msgs:
+            session.writer.write_turn(new_msgs)
+
+
+def list_sessions(*, owner: Path | None = None) -> list[ChatSessionSummary]:
+    """List all saved sessions.
+
+    A session-index entry missing or empty cwd indicates a corrupt index;
+    raise rather than coerce to Path(".") and mask the corruption.
+
+    Args:
+        owner: When set, filter to sessions whose cwd equals this path.
+    """
+    idx = SessionIndex()
+    entries = idx.list_all() if owner is None else idx.list_for_cwd(owner)
+    summaries: list[ChatSessionSummary] = []
+    for e in entries:
+        cwd = e.get("cwd", "")
+        if not cwd:
+            raise ValueError(
+                f"Session index entry {e.get('session_id', '?')} has no cwd; "
+                "the index is corrupt. Delete ~/.dft/sessions/index.json to rebuild."
+            )
+        summaries.append(
+            ChatSessionSummary(
+                session_id=e["session_id"],
+                cwd=Path(cwd),
+                started_at=e.get("started_at", ""),
+                model=e.get("model", ""),
+            )
+        )
+    return summaries
+
+
+def _has_tool_history(messages: list[dict[str, Any]]) -> bool:
+    return any(m.get("role") == "tool" or bool(m.get("tool_calls")) for m in messages)

dataface/agent_api/dashboards.py

@@ -0,0 +1,257 @@
+"""Typed dashboard verbs for the Dataface agent API.
+
+All public functions have concrete typed arguments and typed Pydantic return
+values. No bare dict[str, Any] in any return position. MCP/CLI callers use
+.model_dump() at the wire boundary.
+
+`RenderedDashboard` and `render_dashboard` live in `dataface.core.dashboard`
+so the embedded HTTP server can call them without inverting the layer stack; they
+are re-exported here so the agent_api thin-wrapper rule still holds.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, Field
+
+from dataface.agent_api._paths import resolve_scoped_path
+from dataface.core.compile import Face, compile_file
+from dataface.core.compile.errors import DatafaceError
+from dataface.core.dashboard import (
+    RenderedDashboard as RenderedDashboard,
+    render_dashboard as render_dashboard,
+)
+from dataface.core.errors import DF_UNKNOWN_INTERNAL, StructuredError
+from dataface.core.render.warnings.base import RenderWarning
+
+# ---------------------------------------------------------------------------
+# Return-type models
+# ---------------------------------------------------------------------------
+
+
+class DashboardSummary(BaseModel):
+    path: Path
+    absolute_path: Path
+    title: str
+    description: str = ""
+    queries: list[str] = []
+    charts: list[str] = []
+    variables: list[str] = []
+
+
+class SkippedFile(BaseModel):
+    path: Path
+    reason: str
+
+
+class ListDashboardsResult(BaseModel):
+    success: bool
+    errors: list[StructuredError] = []
+    dashboards: list[DashboardSummary] = []
+    count: int = 0
+    directory: Path
+    skipped_files: list[SkippedFile] = []
+
+
+class CompiledDashboard(BaseModel):
+    success: bool
+    dashboard: Face | None = None
+    errors: list[StructuredError] = []
+    warnings: list[RenderWarning] = []
+    raw_yaml: str | None = None
+
+
+class RenderDashboardArgs(BaseModel):
+    """Validate, compile, and render a Dataface dashboard, returning resolved chart semantics + executed data for reasoning. Use this to verify YAML is valid, inspect query results, and iterate on a dashboard. When 'path' is provided, the response also includes a localhost URL the user can open in a browser to view the live dashboard (the embedded HTTP server runs alongside `dft mcp serve`). Pass `as_link=true` with a path to skip execution and return only the preview URL."""
+
+    path: Path | None = Field(
+        None, description="Path to dashboard YAML file (use this OR yaml_content)"
+    )
+    yaml_content: str | None = Field(
+        None, description="YAML content to render directly (use this OR path)"
+    )
+    project_dir: Path | None = Field(
+        None, description="Project root for resolving relative paths"
+    )
+    variables: dict[str, Any] | None = Field(
+        None, description="Variable values to apply to the dashboard"
+    )
+    format: Literal["json", "text", "yaml", "svg"] | None = Field(
+        None,
+        description=(
+            "Output format. 'json' (default) returns resolved chart "
+            "semantics and executed data as structured JSON. 'text' "
+            "returns a compact markdown summary of charts and data "
+            "(most token-efficient). 'yaml' returns resolved Dataface "
+            "YAML with inline data — valid input for re-compilation, "
+            "ideal for round-trip editing. 'svg' returns the rendered "
+            "dashboard as inline SVG (under result['data']) for hosts "
+            "that embed the rendered output directly."
+        ),
+    )
+    as_link: bool = Field(
+        False,
+        description=(
+            "When true and 'path' is provided, skip query execution and return only "
+            "the preview URL. Use this to surface an existing dashboard in the browser "
+            "without paying the render cost — replaces the old view_dashboard tool."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public verbs
+# ---------------------------------------------------------------------------
+
+
+def list_dashboards(
+    directory: Path = Path("."),
+    recursive: bool = True,
+) -> ListDashboardsResult:
+    """List all available dashboards in a directory."""
+    dir_path = directory.resolve()
+
+    if not dir_path.exists():
+        return ListDashboardsResult(
+            success=False,
+            errors=[
+                DatafaceError.from_code(
+                    DF_UNKNOWN_INTERNAL,
+                    message=f"Directory not found: {directory}",
+                ).to_structured()
+            ],
+            directory=dir_path,
+        )
+    if not dir_path.is_dir():
+        return ListDashboardsResult(
+            success=False,
+            errors=[
+                DatafaceError.from_code(
+                    DF_UNKNOWN_INTERNAL,
+                    message=f"Not a directory: {directory}",
+                ).to_structured()
+            ],
+            directory=dir_path,
+        )
+
+    pattern = "**/*.yml" if recursive else "*.yml"
+    yaml_files = list(dir_path.glob(pattern))
+    yaml_files.extend(dir_path.glob(pattern.replace(".yml", ".yaml")))
+
+    dashboards: list[DashboardSummary] = []
+    skipped: list[SkippedFile] = []
+
+    for yaml_file in sorted(yaml_files):
+        if yaml_file.name.startswith("_"):
+            continue
+        try:
+            content = yaml.safe_load(yaml_file.read_text())
+            if not isinstance(content, dict):
+                skipped.append(
+                    SkippedFile(
+                        path=yaml_file.relative_to(dir_path),
+                        reason="Not a YAML mapping",
+                    )
+                )
+                continue
+            dashboard_keys = {"queries", "charts", "rows", "cols", "grid", "tabs"}
+            if not any(key in content for key in dashboard_keys):
+                continue
+            dashboards.append(
+                DashboardSummary(
+                    path=yaml_file.relative_to(dir_path),
+                    absolute_path=yaml_file,
+                    title=content.get("title", yaml_file.stem),
+                    description=content.get("description", ""),
+                    queries=list(content.get("queries", {}).keys()),
+                    charts=list(content.get("charts", {}).keys()),
+                    variables=list(content.get("variables", {}).keys()),
+                )
+            )
+        except yaml.YAMLError as e:
+            skipped.append(
+                SkippedFile(
+                    path=yaml_file.relative_to(dir_path),
+                    reason=f"YAML parse error: {e}",
+                )
+            )
+        except OSError as e:
+            skipped.append(
+                SkippedFile(
+                    path=yaml_file.relative_to(dir_path),
+                    reason=f"Read error: {e}",
+                )
+            )
+
+    return ListDashboardsResult(
+        success=True,
+        dashboards=dashboards,
+        count=len(dashboards),
+        directory=dir_path,
+        skipped_files=skipped,
+    )
+
+
+def get_dashboard(
+    path: Path,
+    include_raw: bool = False,
+    project_dir: Path | None = None,
+) -> CompiledDashboard:
+    """Get the compiled structure of a dashboard."""
+    try:
+        file_path = resolve_scoped_path(path, project_dir)
+    except ValueError as exc:
+        return CompiledDashboard(
+            success=False,
+            errors=[
+                DatafaceError.from_code(
+                    DF_UNKNOWN_INTERNAL, message=str(exc)
+                ).to_structured()
+            ],
+        )
+
+    if not file_path.exists():
+        return CompiledDashboard(
+            success=False,
+            errors=[
+                DatafaceError.from_code(
+                    DF_UNKNOWN_INTERNAL,
+                    message=f"File not found: {path}",
+                ).to_structured(file=str(file_path))
+            ],
+        )
+    if not file_path.is_file():
+        return CompiledDashboard(
+            success=False,
+            errors=[
+                DatafaceError.from_code(
+                    DF_UNKNOWN_INTERNAL,
+                    message=f"Not a file: {path}",
+                ).to_structured(file=str(file_path))
+            ],
+        )
+
+    try:
+        raw_yaml = file_path.read_text()
+    except OSError as e:
+        return CompiledDashboard(
+            success=False,
+            errors=[
+                DatafaceError.from_code(
+                    DF_UNKNOWN_INTERNAL,
+                    message=f"Failed to read file: {e}",
+                ).to_structured(file=str(file_path))
+            ],
+        )
+
+    result = compile_file(file_path)
+    return CompiledDashboard(
+        success=result.success,
+        dashboard=result.face if result.success else None,
+        errors=list(result.errors),
+        warnings=result.warnings,
+        raw_yaml=raw_yaml if include_raw else None,
+    )