dataface 0.1.2__py3-none-any.whl

dataface/ai/tools/__init__.py

@@ -0,0 +1,312 @@
+"""OpenAI function-calling adapters and MCP dispatch shim.
+
+Thin wrappers over dataface.agent_api. No business logic here.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import dataface.agent_api.describe_query as _describe_query
+from dataface.agent_api import (
+    dashboards as _dash,
+    query as _query,
+    schema as _schema_mod,
+    schema_search as _schema_search_mod,
+    search as _search,
+    skills as _skills,
+)
+from dataface.agent_api.validate import (
+    ValidateDashboardArgs as _ValidateDashboardArgs,
+    validate as _validate_func,
+)
+from dataface.ai.context import DatafaceAIContext
+from dataface.ai.tool_schemas import (
+    DESCRIBE_QUERY,
+    DOCS,
+    EXECUTE_QUERY,
+    QUERY_FACE,
+    RENDER_DASHBOARD,
+    SCHEMA,
+    SEARCH_DASHBOARDS,
+    to_openai_tool,
+)
+
+if TYPE_CHECKING:
+    from dataface.ai.external_mcp import ExternalMCPManager
+
+ToolHandler = Callable[[dict[str, Any], DatafaceAIContext], dict[str, Any]]
+
+TOOL_RENDER_DASHBOARD: dict[str, Any] = to_openai_tool(
+    RENDER_DASHBOARD,
+    property_subset=[
+        "path",
+        "yaml_content",
+        "project_dir",
+        "variables",
+        "format",
+        "as_link",
+    ],
+)
+TOOL_EXECUTE_QUERY: dict[str, Any] = to_openai_tool(
+    EXECUTE_QUERY, property_subset=["sql", "variables", "limit"]
+)
+TOOL_DESCRIBE_QUERY: dict[str, Any] = to_openai_tool(
+    DESCRIBE_QUERY, property_subset=["sql", "source", "dialect"]
+)
+TOOL_SCHEMA: dict[str, Any] = to_openai_tool(
+    SCHEMA, property_subset=["source", "schema", "table", "column", "table_search"]
+)
+TOOL_SEARCH_DASHBOARDS: dict[str, Any] = to_openai_tool(SEARCH_DASHBOARDS)
+TOOL_QUERY_FACE: dict[str, Any] = to_openai_tool(QUERY_FACE)
+TOOL_DOCS: dict[str, Any] = to_openai_tool(DOCS)
+
+
+def get_tools(include_data_tools: bool = True) -> list[dict[str, Any]]:
+    tools: list[dict[str, Any]] = [TOOL_RENDER_DASHBOARD, TOOL_DOCS]
+    if include_data_tools:
+        tools.extend(
+            [
+                TOOL_EXECUTE_QUERY,
+                TOOL_DESCRIBE_QUERY,
+                TOOL_QUERY_FACE,
+                TOOL_SCHEMA,
+                TOOL_SEARCH_DASHBOARDS,
+            ]
+        )
+    return tools
+
+
+def _render_project_dir(args: dict[str, Any], ctx: DatafaceAIContext) -> Path | None:
+    project_dir = args.get("project_dir")
+    if project_dir is not None:
+        return Path(project_dir)
+    if ctx.default_project_dir is not None:
+        return ctx.default_project_dir
+    return ctx.adapter_registry.project_root
+
+
+def _render_path(path: str | None, project_dir: Path | None) -> Path | None:
+    if not path:
+        return None
+    raw_path = Path(path)
+    if project_dir is None or not raw_path.is_absolute():
+        return raw_path
+    try:
+        return raw_path.resolve().relative_to(project_dir.resolve())
+    except ValueError:
+        return raw_path
+
+
+def _handle_render(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any]:
+    parsed = _dash.RenderDashboardArgs.model_validate(args)
+    project_dir = _render_project_dir(args, ctx)
+    return _dash.render_dashboard(
+        path=_render_path(str(parsed.path) if parsed.path else None, project_dir),
+        yaml_content=parsed.yaml_content,
+        project_dir=project_dir,
+        variables=parsed.variables,
+        format=parsed.format or "json",
+        as_link=parsed.as_link,
+        adapter_registry=ctx.adapter_registry,
+        server_port=ctx.server_port,
+    ).model_dump(mode="json", exclude_none=True)
+
+
+def _handle_query(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any]:
+    return _query.execute_query(
+        sql=args.get("sql", ""),
+        variables=args.get("variables"),
+        source=args.get("source"),
+        limit=args.get("limit", 50),
+        adapter_registry=ctx.adapter_registry,
+    ).model_dump(mode="json", exclude_none=True)
+
+
+def _handle_describe_query(
+    args: dict[str, Any], ctx: DatafaceAIContext
+) -> dict[str, Any]:
+    return _describe_query.describe_query(
+        sql=args.get("sql", ""),
+        source=args.get("source"),
+        dialect=args.get("dialect"),
+        adapter_registry=ctx.adapter_registry,
+    ).model_dump(mode="json", exclude_none=True)
+
+
+def _handle_query_face(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any]:
+    parsed = _query.QueryFaceArgs.model_validate(args)
+    return _query.query_face(
+        name=parsed.name,
+        path=parsed.path,
+        project_dir=_render_project_dir(args, ctx),
+        vars=parsed.vars,
+        limit=parsed.limit,
+        adapter_registry=ctx.adapter_registry,
+    ).model_dump(mode="json", exclude_none=True)
+
+
+def _force_refresh_arg(args: dict[str, Any]) -> bool:
+    raw = args.get("force_refresh", False)
+    if raw is None:
+        return False
+    if isinstance(raw, bool):
+        return raw
+    raise ValueError("force_refresh must be a JSON boolean")
+
+
+def _handle_schema(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any]:
+    try:
+        force_refresh = _force_refresh_arg(args)
+    except ValueError as exc:
+        return {"success": False, "sources": {}, "errors": [str(exc)]}
+
+    return _schema_mod.schema(
+        source=args.get("source"),
+        schema=args.get("schema"),
+        table=args.get("table"),
+        column=args.get("column"),
+        force_refresh=force_refresh,
+        table_search=args.get("table_search"),
+        adapter_registry=ctx.adapter_registry,
+    ).model_dump(mode="json", by_alias=True, exclude_none=True)
+
+
+def _handle_schema_search(
+    args: dict[str, Any], ctx: DatafaceAIContext
+) -> dict[str, Any]:
+    parsed = _schema_search_mod.SchemaSearchArgs.model_validate(args)
+    return _schema_search_mod.schema_search(
+        **parsed.model_dump(),
+        adapter_registry=ctx.adapter_registry,
+    ).model_dump(mode="json", by_alias=True, exclude_none=True)
+
+
+def _handle_search(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any]:
+    parsed = _search.SearchDashboardsArgs.model_validate(args)
+    kwargs: dict[str, Any] = {
+        "query": parsed.query,
+        "project_dir": parsed.project_dir or ctx.dashboards_directory,
+        "tags": parsed.tags,
+    }
+    if parsed.limit is not None:
+        kwargs["limit"] = parsed.limit
+    return _search.search_dashboards(**kwargs).model_dump(
+        mode="json", exclude_none=True
+    )
+
+
+def _handle_docs(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any]:
+    from dataface.agent_api.docs import DocsArgs, docs as _docs
+
+    parsed = DocsArgs.model_validate(args)
+    return _docs(
+        topic=parsed.topic,
+        search=parsed.search,
+        limit=parsed.limit,
+    ).model_dump(mode="json")
+
+
+def _handle_describe_dashboard(
+    args: dict[str, Any], ctx: DatafaceAIContext
+) -> dict[str, Any]:
+    from dataface.agent_api.describe import DescribeFaceArgs, describe_face
+
+    parsed = DescribeFaceArgs.model_validate(args)
+    return describe_face(
+        path=parsed.path,
+        project_dir=_render_project_dir(args, ctx),
+    ).model_dump(mode="json", exclude_none=True)
+
+
+# Wheel-internal bookkeeping fields that MCP clients don't need on the wire.
+# `surfaces` is the per-skill visibility filter; `rendered_for` is the marker
+# the registry stamps on after macro expansion. Both are useful for in-process
+# callers (tests, the CLI) but only add noise to MCP tool responses.
+_SKILL_FIELDS_INTERNAL = {"surfaces", "rendered_for"}
+
+
+def _handle_list_skills(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any]:
+    return _skills.list_skills(surface="mcp").model_dump(
+        mode="json",
+        exclude_none=True,
+        exclude={"skills": {"__all__": _SKILL_FIELDS_INTERNAL}},
+    )
+
+
+def _handle_get_skill(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any]:
+    parsed = _skills.GetSkillArgs.model_validate(args)
+    try:
+        skill = _skills.get_skill(parsed.name, surface="mcp")
+    except _skills.SkillNotFound as exc:
+        return {"success": False, "errors": [str(exc)]}
+    return skill.model_dump(
+        mode="json", exclude_none=True, exclude=_SKILL_FIELDS_INTERNAL
+    )
+
+
+def _handle_search_skills(
+    args: dict[str, Any], ctx: DatafaceAIContext
+) -> dict[str, Any]:
+    parsed = _skills.SearchSkillsArgs.model_validate(args)
+    return _skills.search_skills(
+        parsed.query, limit=parsed.limit, surface="mcp"
+    ).model_dump(mode="json", exclude_none=True)
+
+
+def _handle_validate(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any]:
+    parsed = _ValidateDashboardArgs.model_validate(args)
+    return _validate_func(
+        path=parsed.path,
+        project_dir=_render_project_dir(args, ctx),
+    ).model_dump(mode="json", exclude_none=True)
+
+
+TOOL_HANDLERS: dict[str, ToolHandler] = {
+    "validate_dashboard": _handle_validate,
+    "render_dashboard": _handle_render,
+    "execute_query": _handle_query,
+    "describe_query": _handle_describe_query,
+    "query_face": _handle_query_face,
+    "schema": _handle_schema,
+    "schema_search": _handle_schema_search,
+    "search_dashboards": _handle_search,
+    "docs": _handle_docs,
+    "describe_dashboard": _handle_describe_dashboard,
+    "list_skills": _handle_list_skills,
+    "get_skill": _handle_get_skill,
+    "search_skills": _handle_search_skills,
+}
+
+
+def handle_tool_call(
+    function_name: str, function_args: dict[str, Any], *, context: DatafaceAIContext
+) -> str:
+    return json.dumps(
+        dispatch_tool_call(function_name, function_args, context=context), default=str
+    )
+
+
+def dispatch_tool_call(
+    function_name: str,
+    function_args: dict[str, Any],
+    *,
+    context: DatafaceAIContext,
+    external_manager: ExternalMCPManager | None = None,
+) -> dict[str, Any]:
+    if "__" in function_name:
+        if external_manager is None:
+            return {
+                "error": f"External tool '{function_name}' called but no MCP manager available"
+            }
+        return external_manager.call_tool(function_name, function_args)
+    handler = TOOL_HANDLERS.get(function_name)
+    if handler is None:
+        return {"error": f"Unknown tool: {function_name}"}
+    try:
+        return handler(dict(function_args), context)
+    except Exception as exc:  # noqa: BLE001 — last-resort catch at dispatch boundary
+        return {"success": False, "errors": [str(exc)]}

dataface/ai/yaml_utils.py

@@ -0,0 +1,57 @@
+"""YAML extraction utilities for AI responses.
+
+This module provides utilities for extracting YAML content from AI-generated
+text responses.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+def extract_yaml(text: str) -> str | None:
+    """Extract YAML code block from text.
+
+    Looks for YAML content in markdown code blocks. Supports both
+    explicit ```yaml blocks and generic ``` blocks that contain
+    YAML-like content.
+
+    Args:
+        text: Text that may contain YAML code blocks
+
+    Returns:
+        Extracted YAML content or None if not found
+
+    Example:
+        >>> text = '''Here's the dashboard:
+        ... ```yaml
+        ... title: "My Dashboard"
+        ... queries:
+        ...   sales: { sql: "SELECT * FROM sales" }
+        ... ```
+        ... '''
+        >>> extract_yaml(text)
+        'title: "My Dashboard"\\nqueries:\\n  sales: { sql: "SELECT * FROM sales" }'
+    """
+    # Look for ```yaml ... ``` blocks (most specific)
+    # Allow optional whitespace before closing backticks (handles indented code blocks)
+    pattern = r"```yaml\s*\n(.*?)\n\s*```"
+    matches = re.findall(pattern, text, re.DOTALL)
+    if matches:
+        return matches[0].strip()
+
+    # Also try ``` ... ``` (without yaml tag) - check if it looks like YAML
+    pattern = r"```\s*\n(.*?)\n\s*```"
+    matches = re.findall(pattern, text, re.DOTALL)
+    if matches:
+        content = matches[0].strip()
+        # Check if it looks like YAML (starts with common YAML keys)
+        if content.startswith(("title:", "queries:", "charts:", "rows:", "variables:")):
+            return content
+        # Also check if it contains YAML-like structure
+        if ":" in content and (
+            "queries:" in content or "charts:" in content or "rows:" in content
+        ):
+            return content
+
+    return None

dataface/cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI tooling for Dataface."""
+
+__all__ = []

dataface/cli/_console.py

@@ -0,0 +1,48 @@
+"""Console factory and agent/pipe context detection for the dft CLI."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from rich.console import Console
+
+# The list of env vars to check is fixed at module load; values are looked
+# up per call via os.environ.get.
+AGENT_ENV_VARS = (
+    "CLAUDECODE",  # Claude Code (official)
+    "GEMINI_CLI",  # Gemini CLI (official)
+    "CLINE_ACTIVE",  # Cline v3.24+ (official)
+    "CURSOR_AGENT",  # Cursor (acknowledged, undocumented)
+    "COPILOT_CLI",  # GitHub Copilot CLI (community-observed)
+    "GOOSE_TERMINAL",  # Goose (official)
+    "AGENT",  # Goose + Amp + emerging cross-agent convention
+    "AI_AGENT",  # Vercel-proposed universal fallback
+)
+
+
+def is_plain_output() -> bool:
+    """Return True when output should be plain (no Rich chrome).
+
+    True when running inside a known AI agent or when stdout is not a TTY
+    (e.g. piped to cat, redirected to a file).
+    """
+    return any(os.environ.get(v) for v in AGENT_ENV_VARS) or not sys.stdout.isatty()
+
+
+def dft_console(*, stderr: bool = False) -> Console:
+    """Build a Rich Console that honors is_plain_output() at call time.
+
+    Use this in CLI command modules instead of bare Console(...) so that
+    agent-PTY and piped contexts (CLAUDECODE=1, stdout-to-file, ...) get
+    plain output uniformly.
+    """
+    plain = is_plain_output()
+    return Console(
+        stderr=stderr,
+        force_terminal=not plain,
+        no_color=plain,
+    )
+
+
+__all__ = ["AGENT_ENV_VARS", "dft_console", "is_plain_output"]

dataface/cli/_error_format.py

@@ -0,0 +1,83 @@
+"""Rich-formatted output for StructuredError lists.
+
+In plain mode (agent or pipe context) we construct the Console with
+``force_terminal=False, no_color=True`` and skip the surrounding
+``Panel`` wrapper. Inline Rich markup like ``[bold]``, ``[dim]`` is
+consumed by Rich's parser either way — when the Console isn't emitting
+ANSI, the markup leaves no trace in the output. So a single body
+composition handles both surfaces; only the Panel wrapper needs gating.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Literal
+
+from rich.panel import Panel
+
+from dataface.cli._console import dft_console
+from dataface.core.errors import StructuredError
+from dataface.core.render.warnings.base import RenderWarning
+
+
+def print_structured_errors(
+    errs: list[StructuredError],
+    *,
+    json_output: bool = False,
+    severity: Literal["error", "warning"] = "error",
+) -> None:
+    """Print structured errors as Rich panels (stderr) or JSON (stdout)."""
+    if json_output:
+        print(
+            json.dumps(
+                {"errors": [e.model_dump(exclude_none=True) for e in errs]}, indent=2
+            )
+        )
+        return
+    style = "red" if severity == "error" else "yellow"
+    console = dft_console(stderr=True)
+    for e in errs:
+        body_parts = [f"[bold {style}]{e.code}[/]  {e.message}"]
+        if e.hint:
+            body_parts.append(f"[dim]Hint:[/] {e.hint}")
+        if e.file:
+            loc = e.file + (f":{e.line}" if e.line else "")
+            body_parts.append(f"[dim]At:[/] {loc}")
+        if e.docs_topic:
+            body_parts.append(f"[dim]Docs:[/] dft docs {e.docs_topic}")
+        elif e.doc_url:
+            body_parts.append(f"[dim]Docs:[/] {e.doc_url}")
+        for cmd in e.next_commands:
+            body_parts.append(f"[dim]→[/] {cmd.label}: [bold]$ {cmd.command}[/]")
+        body = "\n".join(body_parts)
+        if console.no_color:
+            console.print(body)
+        else:
+            console.print(Panel(body, border_style=style, expand=False))
+
+
+def print_render_warnings(
+    warnings: list[RenderWarning],
+    *,
+    path: Path | None = None,
+) -> None:
+    """Print RenderWarning objects as yellow Rich panels (stderr).
+
+    Mirrors print_structured_errors' panel style at severity=warning so the
+    visual treatment matches across error and warning surfaces.
+    """
+    style = "yellow"
+    console = dft_console(stderr=True)
+    for w in warnings:
+        chart_prefix = f"{w.chart}: " if w.chart else ""
+        body_parts = [f"[bold {style}]{w.code}[/]  {chart_prefix}{w.message}"]
+        if w.fix:
+            body_parts.append(f"[dim]Fix:[/] {w.fix}")
+        if path is not None:
+            body_parts.append(f"[dim]At:[/] {path}")
+        body = "\n".join(body_parts)
+        if console.no_color:
+            console.print(body)
+        else:
+            console.print(Panel(body, border_style=style, expand=False))

dataface/cli/_extras.py

@@ -0,0 +1,190 @@
+"""Optional-dependency gate for CLI commands that need heavyweight extras."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import importlib.util
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+from typing import Literal
+
+import typer
+from rich.markup import escape
+from rich.panel import Panel
+
+from dataface._install_hint import install_hint
+from dataface.cli._console import dft_console
+
+# dist-name → import-name overrides for packages where they differ
+_DIST_TO_IMPORT: dict[str, str] = {
+    "prompt-toolkit": "prompt_toolkit",
+}
+
+_console = dft_console(stderr=True)
+
+
+def _dist_to_import_name(dist_name: str) -> str:
+    """Convert a distribution name to its top-level import name."""
+    if dist_name in _DIST_TO_IMPORT:
+        return _DIST_TO_IMPORT[dist_name]
+    return dist_name.replace("-", "_")
+
+
+def _agent_extra_packages(extra: str) -> list[str]:
+    """Return bare dist names declared under [project.optional-dependencies.<extra>]."""
+    try:
+        reqs = importlib.metadata.requires("dataface") or []
+    except importlib.metadata.PackageNotFoundError as exc:
+        _console.print(
+            f"[red]Cannot read package metadata for 'dataface' in {sys.executable}. "
+            "The package may not be installed correctly.[/red]"
+        )
+        raise typer.Exit(1) from exc
+
+    pattern = re.compile(rf"""extra\s*==\s*['"]({re.escape(extra)})['"]""")
+    result = []
+    for req in reqs:
+        if pattern.search(req):
+            # strip version specifier — take only the dist name before any space/>;
+            dist = re.split(r"[><=!;\s]", req)[0]
+            result.append(dist)
+    return result
+
+
+def _missing_packages(extra: str) -> list[str]:
+    """Return dist names from <extra> whose top-level module cannot be imported."""
+    missing = []
+    for dist in _agent_extra_packages(extra):
+        import_name = _dist_to_import_name(dist)
+        if importlib.util.find_spec(import_name) is None:
+            missing.append(dist)
+    return missing
+
+
+def _resolve_installer() -> Literal["pip", "uv"] | None:
+    """Detect the active installer. Returns 'pip', 'uv', or None if neither available.
+
+    Priority: UV env var (uv set this when it spawned us) → pip importable → uv on PATH.
+    """
+    if os.environ.get("UV"):
+        return "uv"
+    if importlib.util.find_spec("pip") is not None:
+        return "pip"
+    if shutil.which("uv"):
+        return "uv"
+    return None
+
+
+def _installer_command(
+    installer: Literal["pip", "uv"], missing: list[str]
+) -> list[str]:
+    """Return the subprocess argv to install missing packages."""
+    if installer == "pip":
+        return [sys.executable, "-m", "pip", "install", "--no-input", *missing]
+    return ["uv", "pip", "install", "--python", sys.executable, *missing]
+
+
+def _installer_prefix(installer: Literal["pip", "uv"]) -> str:
+    """Return the human-readable installer prefix for copy-paste commands."""
+    if installer == "pip":
+        return "pip install"
+    return f"uv pip install --python {shlex.quote(sys.executable)}"
+
+
+def _installer_display_command(
+    installer: Literal["pip", "uv"], missing: list[str]
+) -> str:
+    """Return the human-readable install command for the missing packages."""
+    return f"{_installer_prefix(installer)} {' '.join(missing)}"
+
+
+def _build_extras_panel(
+    extra: str,
+    missing: list[str],
+    installer: Literal["pip", "uv"] | None,
+) -> Panel:
+    if installer is None:
+        return Panel(
+            "[bold]dft chat[/bold] requires optional packages that are not installed:\n\n"
+            + "\n".join(f"  • [cyan]{escape(p)}[/cyan]" for p in missing)
+            + "\n\nNo installer found in this environment. "
+            "Install uv (https://docs.astral.sh/uv/getting-started/installation/) "
+            "or [dim]pip[/dim] into this interpreter, then re-run — "
+            "or install these packages by whatever mechanism you used to install "
+            "[dim]dataface[/dim] itself.",
+            title="[yellow]Optional dependencies required for `dft chat`[/yellow]",
+            expand=False,
+        )
+    pip_cmd = _installer_display_command(installer, missing)
+    canonical_hint = install_hint(extra)
+    return Panel(
+        "[bold]dft chat[/bold] requires optional packages that are not installed:\n\n"
+        + "\n".join(f"  • [cyan]{escape(p)}[/cyan]" for p in missing)
+        + f"\n\nTo install manually:\n  [dim]{escape(pip_cmd)}[/dim]\n\n"
+        + f"Or reinstall Dataface with the {escape('[' + extra + ']')} extra:\n"
+        + f"  [dim]{escape(canonical_hint)}[/dim]",
+        title="[yellow]Optional dependencies required for `dft chat`[/yellow]",
+        expand=False,
+    )
+
+
+def install_extras(extra: str, *, interactive: bool) -> None:
+    """Install missing packages for <extra>.
+
+    interactive=False: silently install without prompting (caller already confirmed).
+    interactive=True: show info panel and prompt before installing.
+    Raises typer.Exit(1) on install failure or (when interactive) user decline.
+    """
+    missing = _missing_packages(extra)
+    if not missing:
+        return
+
+    installer = _resolve_installer()
+    if installer is None:
+        _console.print(_build_extras_panel(extra, missing, installer=None))
+        raise typer.Exit(1)
+
+    if interactive:
+        _console.print(_build_extras_panel(extra, missing, installer=installer))
+        answer = _console.input("Install now? [Y/n] ").strip().lower()
+        if answer not in ("", "y", "yes"):
+            raise typer.Exit(1)
+
+    display_cmd = _installer_display_command(installer, missing)
+    try:
+        subprocess.check_call(_installer_command(installer, missing))
+    except subprocess.CalledProcessError as exc:
+        _console.print(f"[red]Install failed. Try manually:\n  {display_cmd}[/red]")
+        raise typer.Exit(1) from exc
+    importlib.invalidate_caches()
+    still_missing = _missing_packages(extra)
+    if still_missing:
+        _console.print(
+            f"[red]Install reported success but packages are still missing "
+            f"in {sys.executable}. Try:\n  {display_cmd}[/red]"
+        )
+        raise typer.Exit(1)
+
+
+def require_extras(extra: str) -> None:
+    """Raise typer.Exit(1) (or offer to install) if <extra> packages are missing.
+
+    - On a TTY without DFT_NO_AUTO_INSTALL=1: prompt the user; install on yes.
+    - Otherwise: print the install command and raise Exit(1).
+    """
+    missing = _missing_packages(extra)
+    if not missing:
+        return
+
+    interactive = sys.stdin.isatty() and os.environ.get("DFT_NO_AUTO_INSTALL") != "1"
+
+    if interactive:
+        install_extras(extra, interactive=True)
+    else:
+        installer = _resolve_installer()
+        _console.print(_build_extras_panel(extra, missing, installer=installer))
+        raise typer.Exit(1)