dataface 0.3.2.dev22__py3-none-any.whl → 0.3.2.dev111__py3-none-any.whl

dataface/agent_api/serve.py

@@ -0,0 +1,115 @@
+"""Typed startup composition for `dft serve`: validation, resolution, and app construction."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict
+
+from dataface.core.diagnostics import Diagnostic
+from dataface.core.diagnostics.base import DatafaceError
+
+if TYPE_CHECKING:
+    from dataface.cli.filesystem_project import FilesystemProject
+
+
+class ServeSetup(BaseModel):
+    """The resolved outcome of a successful `prepare_serve` call.
+
+    `app` is `Any` rather than `FastAPI`: `create_server`'s real return value is
+    a `FastAPI` instance, but the ASGI-app contract `uvicorn.run` actually needs
+    is duck-typed (any ASGI-callable) — pinning it to `FastAPI` would reject the
+    test doubles `dataface/tests/cli/test_serve_cli.py` legitimately passes in
+    place of a real server.
+    """
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    app: Any
+    port: int
+    dialect: str
+    dialect_inferred: bool
+
+
+def prepare_serve(
+    project: FilesystemProject,
+    *,
+    port: int | None,
+    host: str,
+    dialect: str | None,
+    target: str | None,
+    max_workers: int | None,
+    no_cache: bool,
+    cache_path: Path | None,
+    allow_external_access: bool,
+) -> ServeSetup | Diagnostic:
+    """Validate startup config, resolve port/dialect, and build the ASGI app.
+
+    Returns a `Diagnostic` (not a raise) when `DFT_DEFAULT_THEME` names an
+    unknown theme — the CLI formats and exits on either return shape. A
+    `dataface.yml` validation failure (`load_config`) raises `ValidationError`
+    uncaught; the CLI's own `try/except` around this call handles that,
+    unchanged from before this function existed.
+    """
+    from dataface.core.compile.config import list_built_in_themes, load_config
+    from dataface.core.diagnostics import ERR_INVALID_DEFAULT_THEME
+    from dataface.core.project_roots import infer_dialect_from_dbt
+    from dataface.core.serve.port import resolve_port
+    from dataface.core.serve.server import create_server
+
+    env_theme = os.environ.get(
+        "DFT_DEFAULT_THEME"
+    )  # noqa: TID251 — DFT_DEFAULT_THEME knob
+    # Empty string is treated as unset (matches get_default_theme_name, which
+    # falls back to the shipped default) — only a non-empty unknown name errors.
+    if env_theme:
+        available = list_built_in_themes()
+        if env_theme not in available:
+            return DatafaceError.from_code(
+                ERR_INVALID_DEFAULT_THEME,
+                source="DFT_DEFAULT_THEME env var",
+                theme=env_theme,
+                available=available,
+            ).to_diagnostic()
+
+    # Validate dataface.yml wholesale: stray keys (style:, board:, theme:, etc.) are a
+    # hard error here at startup rather than silently ignored.
+    load_config(project)
+
+    project_dir = project.root
+    resolved_port = resolve_port(explicit_port=port, project_dir=project_dir, host=host)
+
+    effective_target = target or os.environ.get("DBT_TARGET") or None
+
+    dialect_inferred = False
+    effective_dialect = dialect
+    if effective_dialect is None:
+        inferred = infer_dialect_from_dbt(project_dir, effective_target)
+        effective_dialect = inferred or "duckdb"
+        dialect_inferred = bool(inferred)
+
+    app = create_server(
+        project,
+        dialect=effective_dialect,
+        target=effective_target,
+        max_workers=max_workers,
+        no_cache=no_cache,
+        cache_path=cache_path,
+        allow_external_access_in_readonly=allow_external_access,
+    )
+
+    return ServeSetup(
+        app=app,
+        port=resolved_port,
+        dialect=effective_dialect,
+        dialect_inferred=dialect_inferred,
+    )
+
+
+def format_startup_failure(exc: Exception) -> Diagnostic:
+    """Wrap an uncaught uvicorn startup exception in the ERR-STARTUP-FAILED envelope."""
+    from dataface.core.diagnostics import ERR_STARTUP_FAILED
+
+    return DatafaceError.from_code(ERR_STARTUP_FAILED, detail=str(exc)).to_diagnostic()

dataface/ai/agent.py

@@ -103,7 +103,7 @@ def schema_exploration_guidance(adapter_registry: AdapterRegistry) -> str:
     Reads only registered connection config (source types) — never the
     warehouse. Returns "" when no sources are configured (nothing to explore).
     """
-    types = {str(s.get("type", "")) for s in adapter_registry.list_sql_sources()}
+    types = {s["type"] for s in adapter_registry.list_sql_sources()}
     if not types:
         return ""
     hints = [
@@ -125,7 +125,7 @@ def build_sources_context(adapter_registry: AdapterRegistry) -> str:
     sources = adapter_registry.list_sql_sources()
     if not sources:
         return ""
-    lines = [f"- {s['name']} ({s.get('type', 'unknown')})" for s in sources]
+    lines = [f"- {s['name']} ({s['type']})" for s in sources]
     return (
         "## Data sources (use these exact names in `source:` and queries)\n\n"
         + "\n".join(lines)
@@ -248,6 +248,7 @@ def run_agent(
     context: DatafaceAIContext,
     messages: list[AgentMessage] | None = None,
     max_iterations: int = 25,
+    max_identical_calls: int = 3,
     profile: AgentProfile | None = None,
     tools: list[dict[str, Any]] | None = None,
     extra_handlers: dict[str, ToolHandler] | None = None,
@@ -255,6 +256,9 @@ def run_agent(
     """Run the agent loop and stream typed events.
 
     Args:
+        max_identical_calls: Consecutive iterations issuing an identical tool-call
+            batch (same names and arguments) before the loop errors instead of
+            dispatching again; any different call resets the count.
         profile: An `AgentProfile` supplying the tool surface + system prompt. The
             way to scope the agent (dashboard vs SQL-specialist vs an experiment).
             Defaults to the dashboard analyst.
@@ -272,6 +276,9 @@ def run_agent(
     conversation.append(UserMessage(content=prompt))
     system_prompt = active.build_system_prompt(context)
 
+    last_call_key: tuple[tuple[str, str], ...] | None = None
+    identical_count = 0
+
     for _ in range(max_iterations):
         response_text = ""
         tool_calls: list[ToolCallEvent] = []
@@ -306,6 +313,25 @@ def run_agent(
             yield AgentDone(response=response_text)
             return
 
+        call_key = tuple(
+            (tc.name, json.dumps(tc.arguments, sort_keys=True)) for tc in tool_calls
+        )
+        if call_key == last_call_key:
+            identical_count += 1
+        else:
+            identical_count = 1
+            last_call_key = call_key
+
+        if identical_count >= max_identical_calls:
+            names = ", ".join(dict.fromkeys(tc.name for tc in tool_calls))
+            yield AgentError(
+                message=(
+                    f"Stopped: {names} called with identical arguments "
+                    f"{identical_count} times in a row without making progress."
+                )
+            )
+            return
+
         for tc in tool_calls:
             result = dispatch_tool_call(
                 tc.name,

dataface/cli/_project.py

@@ -10,6 +10,7 @@ fallback. `with_project` is that one rule, injected once.
 from __future__ import annotations
 
 from collections.abc import Callable
+from dataclasses import dataclass
 from functools import wraps
 from pathlib import Path
 from typing import Any, TypeVar
@@ -17,7 +18,11 @@ from typing import Any, TypeVar
 import typer
 
 from dataface.agent_api import Project
-from dataface.agent_api._paths import find_dft_root
+from dataface.agent_api._paths import (
+    DFT_ROOT_MARKERS as DFT_ROOT_MARKERS,
+    find_dft_root,
+    find_repo_root,
+)
 from dataface.cli._error_format import print_error
 from dataface.cli.filesystem_project import FilesystemProject
 
@@ -55,6 +60,100 @@ def resolve_project_dir(project_dir: Path | None) -> Path:
     return found
 
 
+def has_faces_marker(start: Path) -> bool:
+    """True iff *start* sits inside a Dataface project that has a ``faces/`` directory.
+
+    Anchors on ``find_dft_root`` so the walk-up stops at the project root rather
+    than blindly hunting upward for stray ``faces/`` dirs elsewhere on the filesystem.
+    """
+    if (start / "faces").is_dir():
+        return True
+    project = find_dft_root(start)
+    return project is not None and (project / "faces").is_dir()
+
+
+@dataclass(frozen=True)
+class InitRootResolution:
+    """Result of ``resolve_init_root``.
+
+    ``git_root`` is set only for the ambiguous case (no dft project found, but a git
+    root diverges from cwd); ``None`` means unambiguous, use ``root`` as-is.
+    """
+
+    root: Path
+    git_root: Path | None = None
+
+
+def resolve_init_root(explicit: Path | None, cwd: Path) -> InitRootResolution:
+    """Determine the init scaffold root without prompting the user.
+
+    Explicit dir wins (resolved, no git_root). Else walks up for a dft project —
+    if found, that's unambiguous. Else checks for a git repo: git root == cwd is
+    unambiguous; git root above cwd is ambiguous and the caller must prompt.
+    """
+    if explicit is not None:
+        return InitRootResolution(root=explicit.resolve())
+
+    project_root = find_dft_root(cwd)
+    if project_root is not None:
+        return InitRootResolution(root=project_root)
+
+    git_root = find_repo_root(cwd)
+    if git_root is None or git_root == cwd.resolve():
+        return InitRootResolution(root=cwd.resolve())
+
+    return InitRootResolution(root=cwd.resolve(), git_root=git_root)
+
+
+@dataclass(frozen=True)
+class McpProjectDirResolution:
+    """Result of ``resolve_mcp_project_dir``.
+
+    ``ai_config_root`` is always set (nearest dft project root, else git repo root,
+    else cwd) — where AI-client configs get written.  ``project_dir`` is the project
+    the MCP server actually serves, ``None`` when unresolvable; ``nearest_root``
+    gives the caller a "did you mean" hint.
+    """
+
+    ai_config_root: Path
+    project_dir: Path | None
+    nearest_root: Path | None
+
+
+def resolve_mcp_project_dir(
+    explicit: Path | None, cwd: Path
+) -> McpProjectDirResolution:
+    """Determine both where AI configs are written and which project the MCP server serves."""
+    dft_root = find_dft_root(cwd)
+    ai_config_root = dft_root or find_repo_root(cwd) or cwd
+
+    if explicit is not None:
+        nearest = find_dft_root(explicit)
+        project_dir = explicit.resolve() if nearest == explicit.resolve() else None
+        return McpProjectDirResolution(
+            ai_config_root=ai_config_root,
+            project_dir=project_dir,
+            nearest_root=nearest,
+        )
+
+    return McpProjectDirResolution(
+        ai_config_root=ai_config_root,
+        project_dir=dft_root,
+        nearest_root=dft_root,
+    )
+
+
+def resolve_skill_install_root(start: Path) -> Path:
+    """Return the directory where skills should be installed.
+
+    Skills are agent tooling that belong at the git root so monorepos with nested
+    dft projects don't accumulate divergent skill copies.
+    """
+    project_root = find_dft_root(start) or start.resolve()
+    git_root = find_repo_root(project_root)
+    return git_root if git_root is not None else project_root
+
+
 def with_project(func: Callable[..., R]) -> Callable[..., R]:
     """Replace a command body's `project_dir: Path | None` with an injected `project`.
 

dataface/cli/commands/board_artifact.py

@@ -6,8 +6,7 @@ from pathlib import Path
 
 import typer
 
-from dataface.agent_api import Project, ProjectSession
-from dataface.agent_api.board_artifact import render_board_from_files
+from dataface.agent_api import Project
 from dataface.cli._console import dft_console
 from dataface.cli._error_format import print_diagnostics
 from dataface.cli._parsing import parse_kv_pairs
@@ -28,6 +27,8 @@ def emit_board_command(
     json_output: bool = False,
 ) -> None:
     """Compile, resolve, and execute a face; write its board artifact + recording."""
+    from dataface.agent_api import ProjectSession
+
     boards_dir = face_path.parent / "boards"
     artifact_path = artifact or boards_dir / f"{face_path.stem}.board.json"
     recording_path = recording or boards_dir / f"{face_path.stem}.recording.json"
@@ -66,6 +67,8 @@ def render_board_command(
     json_output: bool = False,
 ) -> None:
     """Render a board from its artifact + recording — no compile, no warehouse."""
+    from dataface.agent_api.board_artifact import render_board_from_files
+
     result = render_board_from_files(artifact_path, recording_path)
 
     if json_output:

dataface/cli/commands/describe.py

@@ -4,17 +4,19 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import typer
 from rich.table import Table
 
-from dataface.agent_api import Project, ProjectSession
-from dataface.agent_api.describe import DescribeFaceResult
+from dataface.agent_api import Project
 from dataface.cli._console import dft_console
 from dataface.cli._error_format import print_diagnostics
 from dataface.cli._project import with_project
 
+if TYPE_CHECKING:
+    from dataface.agent_api.describe import DescribeFaceResult
+
 console = dft_console()
 
 
@@ -23,6 +25,8 @@ def describe_command(
     paths: list[Path], *, project: Project, json_output: bool = False
 ) -> None:
     """Describe the structure of one or more face files."""
+    from dataface.agent_api import ProjectSession
+
     with ProjectSession.from_project(project) as project_session:
         results = project_session.describe_paths(paths)
     _emit(results, json_output=json_output)

dataface/cli/commands/docs.py

@@ -1,6 +1,8 @@
 """CLI command for `dft docs`."""
 
-from typing import Literal
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
 
 import typer
 from rich.markdown import Markdown
@@ -8,11 +10,12 @@ from rich.padding import Padding
 from rich.table import Table
 
 from dataface._docs_site import docs_site_url
-from dataface.agent_api.diagnostics import get_diagnostic_code, list_diagnostic_codes
-from dataface.agent_api.docs import TopicEntry, docs as _docs
 from dataface.cli._console import dft_console, is_plain_output
 from dataface.cli._json_output import print_json_result
 
+if TYPE_CHECKING:
+    from dataface.agent_api.docs import TopicEntry
+
 console = dft_console()
 
 # The two user-facing CLI verbs over the one diagnostic registry.
@@ -26,6 +29,8 @@ def docs_diagnostics_list(
     level: Literal["error", "warning"], json_output: bool
 ) -> None:
     """Print all registered codes at `level` with one-line descriptions, sorted."""
+    from dataface.agent_api.diagnostics import list_diagnostic_codes
+
     result = list_diagnostic_codes(level=level)
 
     if json_output:
@@ -61,6 +66,8 @@ def docs_diagnostic_detail(
     code" for a code we ship — with a note pointing at the verb that matches
     its actual level.
     """
+    from dataface.agent_api.diagnostics import get_diagnostic_code
+
     result = get_diagnostic_code(code)
 
     if json_output:
@@ -113,6 +120,8 @@ def docs_command(
             docs_diagnostics_list(level, json_output)
         return
 
+    from dataface.agent_api.docs import docs as _docs
+
     result = _docs(topic=topic, search=search, limit=limit)
 
     if json_output:

dataface/cli/commands/init.py

@@ -8,10 +8,7 @@ from pathlib import Path
 
 import typer
 
-from dataface.agent_api.init import init_project
-
-# tach-ignore(cli->core debt: route via agent_api; burn-down task)
-from dataface.core.project_roots import find_dft_root, find_repo_root
+from dataface.cli._project import resolve_init_root
 
 
 def _resolve(
@@ -30,17 +27,11 @@ def _resolve(
 
 def _resolve_init_root(project_dir: Path | None, *, yes: bool) -> Path:
     """Choose the init root for the wizard without changing lower-level API defaults."""
-    if project_dir is not None:
-        return project_dir.resolve()
-
     cwd = Path.cwd().resolve()
-    project_root = find_dft_root(cwd)
-    if project_root is not None:
-        return project_root
-
-    git_root = find_repo_root(cwd)
-    if git_root is None or git_root == cwd:
-        return cwd
+    resolution = resolve_init_root(project_dir, cwd)
+    git_root = resolution.git_root
+    if git_root is None:
+        return resolution.root
 
     typer.echo(f"  No Dataface or dbt project found above {cwd}.")
     typer.echo(f"  git root: {git_root}")
@@ -70,6 +61,8 @@ def run_wizard(
     cursor: bool | None,
 ) -> None:
     """Run the dft init wizard: prompt, scaffold, dispatch opt-ins."""
+    from dataface.agent_api.init import init_project
+
     root = _resolve_init_root(project_dir, yes=yes)
 
     if skills is not None:

dataface/cli/commands/inspect.py

@@ -12,7 +12,6 @@ from pathlib import Path
 
 import typer
 
-from dataface.agent_api import inspect as _api
 from dataface.cli._console import dft_console
 
 console = dft_console()
@@ -24,6 +23,8 @@ def eject_command(
     force: bool = False,
     output_dir: Path | None = None,
 ) -> None:
+    from dataface.agent_api import inspect as _api
+
     target_dir = output_dir or (Path.cwd() / "faces" / "inspect")
     to_eject: list[str] | None = None if all_templates else (templates or None)
     if not all_templates and not templates:
@@ -55,6 +56,8 @@ def eject_command(
 
 
 def validate_ejected_templates_command(output_dir: Path | None = None) -> None:
+    from dataface.agent_api import inspect as _api
+
     target = output_dir or (Path.cwd() / "faces" / "inspect")
     try:
         result = _api.validate_ejected_templates(target_dir=target)
@@ -85,6 +88,8 @@ def validate_ejected_templates_command(output_dir: Path | None = None) -> None:
 
 
 def templates_command() -> None:
+    from dataface.agent_api import inspect as _api
+
     console.print("\n[bold]Available Inspect Templates[/bold]\n")
     for t in _api.list_templates():
         console.print(f"  • {t.name}")

dataface/cli/commands/mcp_init.py

@@ -8,43 +8,7 @@ from pathlib import Path
 import typer
 
 from dataface.agent_api import mcp_install
-
-# tach-ignore(cli->core debt: route via agent_api; burn-down task)
-from dataface.core.project_roots import (
-    DFT_ROOT_MARKERS,
-    find_dft_root,
-    find_repo_root,
-)
-
-
-def _resolve_project_dir(explicit: Path | None, discovered: Path | None) -> Path:
-    """The dft project the MCP server points at: an explicit --project-dir (validated)
-    or the project discovered from cwd. Exits with an error when neither resolves."""
-    markers_str = ", ".join(DFT_ROOT_MARKERS)
-    if explicit is not None:
-        nearest = find_dft_root(explicit)
-        if nearest != explicit:
-            msg = (
-                f"Error: --project-dir {explicit} does not contain a Dataface "
-                f"or dbt project.\n"
-                f"Looked for: {markers_str}."
-            )
-            if nearest is not None:
-                msg += f"\nTip: did you mean {nearest}?"
-            typer.echo(msg, err=True)
-            raise typer.Exit(1)
-        return explicit
-
-    if discovered is None:
-        typer.echo(
-            f"Error: No Dataface or dbt project found at or above {Path.cwd()}.\n"
-            f"Looked for: {markers_str}.\n"
-            f"Re-run from inside your Dataface project, "
-            f"or pass --project-dir <path>.",
-            err=True,
-        )
-        raise typer.Exit(1)
-    return discovered
+from dataface.cli._project import DFT_ROOT_MARKERS, resolve_mcp_project_dir
 
 
 def run_init(
@@ -54,13 +18,29 @@ def run_init(
     project_dir: Path | None = None,
 ) -> None:
     """Shared implementation for `dft init mcp`."""
-    # Where the AI-client configs get written (.cursor/mcp.json, .vscode/mcp.json,
-    # .mcp.json, …): the dft project root if we're in one, else the repo root, else
-    # cwd. Distinct from project_dir below — the project the server actually serves.
     cwd = Path.cwd()
-    dft_root = find_dft_root(cwd)
-    ai_config_root = dft_root or find_repo_root(cwd) or cwd
-    project_dir = _resolve_project_dir(project_dir, dft_root)
+    resolution = resolve_mcp_project_dir(project_dir, cwd)
+    if resolution.project_dir is None:
+        markers_str = ", ".join(DFT_ROOT_MARKERS)
+        if project_dir is not None:
+            msg = (
+                f"Error: --project-dir {project_dir} does not contain a Dataface "
+                f"or dbt project.\n"
+                f"Looked for: {markers_str}."
+            )
+            if resolution.nearest_root is not None:
+                msg += f"\nTip: did you mean {resolution.nearest_root}?"
+        else:
+            msg = (
+                f"Error: No Dataface or dbt project found at or above {cwd}.\n"
+                f"Looked for: {markers_str}.\n"
+                f"Re-run from inside your Dataface project, "
+                f"or pass --project-dir <path>."
+            )
+        typer.echo(msg, err=True)
+        raise typer.Exit(1)
+    ai_config_root = resolution.ai_config_root
+    project_dir = resolution.project_dir
 
     dft_executable = mcp_install.resolve_dft_executable(ai_config_root)
     server_args: list[str] = ["mcp", "serve"]

dataface/cli/commands/migrate.py

@@ -3,15 +3,17 @@
 from __future__ import annotations
 
 from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING
 
 import typer
 
-from dataface.agent_api import Project, ProjectSession
-from dataface.agent_api._paths import resolve_face_path
-from dataface.agent_api.migrate import MigrateSummary
+from dataface.agent_api import Project
 from dataface.cli._console import dft_console
 from dataface.cli._project import with_project
 
+if TYPE_CHECKING:
+    from dataface.agent_api.migrate import MigrateSummary
+
 _console = dft_console()
 
 
@@ -23,6 +25,9 @@ def migrate_command(
     dry_run: bool,
 ) -> None:
     """Rewrite supported retired face syntax in the selected paths."""
+    from dataface.agent_api import ProjectSession
+    from dataface.agent_api._paths import resolve_face_path
+
     relpaths = (
         [PurePosixPath(resolve_face_path(path, project).relpath) for path in paths]
         if paths

dataface/cli/commands/query.py

@@ -14,14 +14,15 @@ from rich.table import Table
 if TYPE_CHECKING:
     from rich.console import Console
 
-from dataface.agent_api import Project, ProjectSession
-from dataface.agent_api.describe_query import DescribeQueryResult
-from dataface.agent_api.query import (
-    ExecuteQueryResult,
-    FaceQueryLookupResult,
-    QueryFaceResult,
-)
-from dataface.agent_api.validate_query import QueryDiagnostic
+    from dataface.agent_api.describe_query import DescribeQueryResult
+    from dataface.agent_api.query import (
+        ExecuteQueryResult,
+        FaceQueryLookupResult,
+        QueryFaceResult,
+    )
+    from dataface.agent_api.validate_query import QueryDiagnostic
+
+from dataface.agent_api import Project
 from dataface.cli._console import dft_console
 from dataface.cli._json_output import print_json_result
 from dataface.cli._project import with_project
@@ -278,6 +279,8 @@ def query_command(
     project: Project,
 ) -> None:
     """Run a named face query, raw SQL, or static SQL lint/describe — selected from the input args."""
+    from dataface.agent_api import ProjectSession
+
     # --- 1. Resolve input shape ---
     sql_text, mode_is_named, query_name, face, source = _resolve_query_input(
         context, query_text, file