10xgraph-api 0.7.0__py3-none-any.whl

tenxgraph_api/cli/commands/api.py

@@ -0,0 +1,262 @@
+"""API server command implementation."""
+
+import ipaddress
+import os
+import socket
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode
+
+import uvicorn
+from dotenv import load_dotenv
+
+from tenxgraph_api.cli.commands import BaseCommand
+from tenxgraph_api.cli.constants import (
+    DEFAULT_CONFIG_FILE,
+    DEFAULT_HOST,
+    DEFAULT_PLAYGROUND_URL,
+    DEFAULT_PORT,
+    LEGACY_CONFIG_FILE,
+)
+from tenxgraph_api.cli.core.config import ConfigManager
+from tenxgraph_api.cli.core.validation import validate_cli_options
+from tenxgraph_api.cli.exceptions import ConfigurationError, ServerError
+
+
+class APICommand(BaseCommand):
+    """Command to start the 10xGraph API server."""
+
+    _PLAYGROUND_WAIT_TIMEOUT_SECONDS = 30.0
+    _PLAYGROUND_WAIT_INTERVAL_SECONDS = 0.25
+
+    def execute(
+        self,
+        config: str = DEFAULT_CONFIG_FILE,
+        host: str = DEFAULT_HOST,
+        port: int = DEFAULT_PORT,
+        reload: bool = True,
+        open_playground: bool = False,
+        playground_url: str = DEFAULT_PLAYGROUND_URL,
+        **kwargs: Any,
+    ) -> int:
+        """Execute the API server command.
+
+        Args:
+            config: Path to config file
+            host: Host to bind to
+            port: Port to bind to
+            reload: Enable auto-reload
+            open_playground: Open the hosted playground after the API becomes reachable
+            playground_url: Hosted playground base URL
+            **kwargs: Additional arguments
+
+        Returns:
+            Exit code
+        """
+        try:
+            self.output.command_header(
+                "play" if open_playground else "api",
+                "Starting development server via Uvicorn. Not for production use.",
+                hint="Ctrl+C to stop the development server",
+            )
+
+            timeline = self.output.timeline(
+                "Preparing the 10xGraph runtime",
+                steps=(
+                    ("config", "Validating project configuration"),
+                    ("runtime", "Loading environment and graph runtime"),
+                    ("port", f"Reserving port {port}"),
+                    ("launch", "Starting the development server"),
+                ),
+            )
+            with timeline:
+                with timeline.step("config") as step:
+                    validated_options = validate_cli_options(host, port, config)
+                    config_manager = ConfigManager()
+                    actual_config_path = config_manager.find_config_file(
+                        validated_options["config"]
+                    )
+                    config_manager.load_config(str(actual_config_path))
+                    detail = str(actual_config_path)
+                    if actual_config_path.name == LEGACY_CONFIG_FILE:
+                        detail += f" (deprecated name; rename it to {DEFAULT_CONFIG_FILE})"
+                    step.detail(detail)
+
+                with timeline.step("runtime") as step:
+                    env_file_path = config_manager.resolve_env_file()
+                    if env_file_path:
+                        self.logger.info("Loading environment from: %s", env_file_path)
+                        load_dotenv(env_file_path)
+                        step.detail(f"environment: {env_file_path}")
+                    else:
+                        load_dotenv()
+                        step.detail("environment: process defaults")
+
+                    os.environ["GRAPH_PATH"] = str(actual_config_path)
+
+                    # Add project root to sys.path for importing graph modules
+                    sys.path.insert(0, str(actual_config_path.parent))
+
+                    # Ensure we're using the correct module path
+                    sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+                browser_host = self._normalize_browser_host(validated_options["host"])
+                with timeline.step("port") as step:
+                    # Reported rather than raised: Uvicorn owns the bind, and its
+                    # own error is the authoritative one if the port is taken.
+                    if self._port_in_use(browser_host, validated_options["port"]):
+                        step.detail("already in use — Uvicorn will report the conflict")
+                    else:
+                        step.detail("available")
+
+                with timeline.step("launch") as step:
+                    self.logger.info(
+                        "Starting API with config: %s, host: %s, port: %d",
+                        actual_config_path,
+                        validated_options["host"],
+                        validated_options["port"],
+                    )
+                    launch_url = None
+                    if open_playground:
+                        launch_url = self._schedule_playground_launch(
+                            host=validated_options["host"],
+                            port=validated_options["port"],
+                            playground_base_url=playground_url,
+                        )
+                    step.detail(
+                        f"playground opens at {launch_url} once the API responds"
+                        if launch_url
+                        else f"http://{browser_host}:{validated_options['port']}"
+                    )
+
+            self.output.completion_screen(
+                "Ready to serve",
+                "10xGraph runtime configured successfully",
+                details={
+                    "API": f"http://{browser_host}:{validated_options['port']}",
+                    "Docs": f"http://{browser_host}:{validated_options['port']}/docs",
+                    "Config": actual_config_path,
+                    "Reload": "enabled" if reload else "disabled",
+                },
+                next_steps=(
+                    ["The playground will open automatically when the API becomes reachable."]
+                    if open_playground
+                    else ["Press Ctrl+C to stop the development server."]
+                ),
+            )
+
+            uvicorn.run(
+                "tenxgraph_api.src.app.main:app",
+                host=validated_options["host"],
+                port=validated_options["port"],
+                reload=reload,
+                workers=1,
+            )
+
+            return 0
+
+        except (ConfigurationError, ServerError) as e:
+            return self.handle_error(e)
+        except Exception as e:
+            server_error = ServerError(
+                f"Failed to start API server: {e}",
+                host=host,
+                port=port,
+            )
+            return self.handle_error(server_error)
+
+    @staticmethod
+    def _port_in_use(host: str, port: int) -> bool:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+            probe.settimeout(0.2)
+            return probe.connect_ex((host, port)) == 0
+
+    def _schedule_playground_launch(
+        self,
+        host: str,
+        port: int,
+        playground_base_url: str,
+    ) -> str:
+        """Start the readiness watcher and return the URL it will open."""
+        browser_host = self._normalize_browser_host(host)
+        launch_url = self._build_playground_url(browser_host, port, playground_base_url)
+        launch_thread = threading.Thread(
+            target=self._open_playground_when_ready,
+            args=(launch_url, browser_host, port),
+            daemon=True,
+            name="10xgraph-playground-launcher",
+        )
+        launch_thread.start()
+        return launch_url
+
+    def _open_playground_when_ready(
+        self,
+        launch_url: str,
+        host: str,
+        port: int,
+    ) -> None:
+        if not self._wait_for_server(host, port):
+            self.logger.warning(
+                "API server did not become reachable in time. Open the playground manually: %s",
+                launch_url,
+            )
+            return
+
+        opened = webbrowser.open_new_tab(launch_url)
+        if opened:
+            self.logger.info("Opened playground URL: %s", launch_url)
+            # A plain line, not a panel: this fires from the watcher thread while
+            # Uvicorn is already streaming logs, and a boxed reveal there would
+            # interleave with them.
+            self.output.success(f"Playground opened: {launch_url}")
+            return
+
+        message = f"Browser launch returned false. Open the playground manually: {launch_url}"
+        self.logger.warning(message)
+        self.output.warning(message)
+
+    def _wait_for_server(
+        self,
+        host: str,
+        port: int,
+    ) -> bool:
+        deadline = time.monotonic() + self._PLAYGROUND_WAIT_TIMEOUT_SECONDS
+        while time.monotonic() < deadline:
+            try:
+                with socket.create_connection((host, port), timeout=1):
+                    return True
+            except OSError:
+                time.sleep(self._PLAYGROUND_WAIT_INTERVAL_SECONDS)
+
+        return False
+
+    def _build_playground_url(
+        self,
+        host: str,
+        port: int,
+        playground_base_url: str,
+    ) -> str:
+        backend_host = host
+        if ":" in backend_host and not backend_host.startswith("["):
+            backend_host = f"[{backend_host}]"
+
+        backend_url = f"http://{backend_host}:{port}"
+        return f"{playground_base_url}?{urlencode({'backendUrl': backend_url})}"
+
+    def _normalize_browser_host(self, host: str) -> str:
+        if not host:
+            return "127.0.0.1"
+
+        normalized_host = host[1:-1] if host.startswith("[") and host.endswith("]") else host
+
+        try:
+            if ipaddress.ip_address(normalized_host).is_unspecified:
+                return "127.0.0.1"
+        except ValueError:
+            pass
+
+        return normalized_host

tenxgraph_api/cli/commands/audit.py

@@ -0,0 +1,213 @@
+"""Environment and project audit for the 10xGraph CLI.
+
+Backs ``10xgraph audit``: a read-only pass over everything that has to be true
+before ``10xgraph dev``, ``eval``, or ``build`` can work in the current
+directory. Nothing here mutates the project, the environment, or the user
+configuration, so it is always safe to run.
+
+Each check returns a :class:`Diagnostic` with one of three statuses:
+
+``pass``
+    The requirement is satisfied.
+``warn``
+    Not fatal for every workflow, but likely to surprise you. A missing
+    ``10xgraph.json`` is fine until you run ``10xgraph dev``; a busy port is
+    fine until you try to bind it.
+``fail``
+    A hard requirement is unmet and commands that depend on it will not run.
+
+The command's exit code is the aggregate of those statuses (see
+:meth:`AuditCommand.execute`), which is what makes it usable as a CI gate.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import socket
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import Any
+
+from tenxgraph_api.cli.commands import BaseCommand
+from tenxgraph_api.cli.constants import DEFAULT_CONFIG_FILE, DEFAULT_PORT
+from tenxgraph_api.cli.core.config import resolve_default_config
+from tenxgraph_api.src.app.core.config.graph_config import validate_remote_tools
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """One audit result.
+
+    Attributes:
+        name: Human-readable label for the thing that was checked.
+        status: One of ``"pass"``, ``"warn"``, or ``"fail"``.
+        detail: Supporting evidence — a version, a path, or an error message.
+    """
+
+    name: str
+    status: str
+    detail: str
+
+
+class AuditCommand(BaseCommand):
+    """Audit the local CLI, core package, project config, and default port.
+
+    Runs six checks in a fixed order and reports them twice: live, through the
+    step timeline, and again as a summary table once every check has finished.
+
+    ============  ==========================================================
+    Check         What it asserts
+    ============  ==========================================================
+    python        The interpreter running the CLI (reported, never failed).
+    cli           ``10xgraph-api`` is installed and resolvable.
+    core          ``10xgraph`` is installed and resolvable.
+    evaluation    The installed core exposes the evaluation symbols that
+                  ``10xgraph eval`` imports, catching a CLI/core version
+                  skew before it becomes an ImportError mid-run.
+    config        ``10xgraph.json`` exists here, parses, declares an
+                  ``agent`` key in ``module:attribute`` form, and contains
+                  valid ``remote_tools`` definitions if present.
+    port          The default API port is free to bind.
+    ============  ==========================================================
+    """
+
+    def execute(self, *, config: str = DEFAULT_CONFIG_FILE, **kwargs: Any) -> int:
+        """Run every check and report the outcome.
+
+        Returns:
+            ``1`` if any check failed, otherwise ``0`` — warnings are surfaced
+            but do not fail the run, so ``10xgraph audit`` can gate CI on
+            hard breakage without tripping on an absent project config.
+        """
+        self.output.command_header(
+            "audit",
+            "Auditing the current 10xGraph development environment.",
+            color="cyan",
+        )
+
+        checks: tuple[tuple[str, str, Callable[[], Diagnostic]], ...] = (
+            (
+                "python",
+                "Python interpreter",
+                lambda: Diagnostic("Python", "pass", sys.version.split()[0]),
+            ),
+            ("cli", "CLI package", lambda: self._package_check("10xgraph-api")),
+            ("core", "Core framework", lambda: self._package_check("10xgraph")),
+            ("evaluation", "Evaluation API", self._evaluation_api_check),
+            ("config", "Project configuration", lambda: self._config_check(config)),
+            ("port", f"Port {DEFAULT_PORT}", lambda: self._port_check(DEFAULT_PORT)),
+        )
+
+        diagnostics: list[Diagnostic] = []
+        timeline = self.output.timeline(
+            "Running environment audit",
+            steps=tuple((key, title) for key, title, _ in checks),
+        )
+        with timeline:
+            for key, _title, run in checks:
+                with timeline.step(key) as step:
+                    result = run()
+                    diagnostics.append(result)
+                    step.detail(f"{self._status_label(result.status)}  {result.detail}")
+
+        self.output.print_table(
+            ["Check", "Status", "Details"],
+            [[item.name, self._status_label(item.status), item.detail] for item in diagnostics],
+            title="Audit results",
+        )
+
+        failures = [item for item in diagnostics if item.status == "fail"]
+        warnings = [item for item in diagnostics if item.status == "warn"]
+        if failures:
+            self.output.error(f"{len(failures)} required check(s) failed.")
+            return 1
+        if warnings:
+            self.output.warning(f"{len(warnings)} check(s) need attention.")
+        else:
+            self.output.completion_screen(
+                "Environment ready",
+                "All required 10xGraph checks passed",
+                details={"Checks": len(diagnostics), "Project": Path.cwd()},
+            )
+        return 0
+
+    @staticmethod
+    def _package_check(distribution: str) -> Diagnostic:
+        """Report the installed version of ``distribution``, or fail if absent."""
+        try:
+            installed = version(distribution)
+        except PackageNotFoundError:
+            return Diagnostic(distribution, "fail", "not installed")
+        return Diagnostic(distribution, "pass", installed)
+
+    @staticmethod
+    def _evaluation_api_check() -> Diagnostic:
+        """Fail when the installed core lacks the symbols ``10xgraph eval`` needs.
+
+        This is the CLI/core version-skew check: both packages can be installed
+        and still be incompatible, and without this the mismatch only surfaces
+        as an ImportError partway through an evaluation run.
+        """
+        try:
+            evaluation = importlib.import_module("tenxgraph.qa.evaluation")
+        except ImportError as exc:
+            return Diagnostic("Evaluation API", "fail", str(exc))
+
+        required = ("CriteriaConfig", "CriterionConfig", "EvalConfig")
+        missing = [name for name in required if not hasattr(evaluation, name)]
+        if missing:
+            return Diagnostic(
+                "Evaluation API",
+                "fail",
+                "core package is missing: " + ", ".join(missing),
+            )
+        return Diagnostic("Evaluation API", "pass", "compatible")
+
+    @staticmethod
+    def _config_check(config: str = DEFAULT_CONFIG_FILE) -> Diagnostic:
+        """Validate ``10xgraph.json`` (or legacy ``agentflow.json``) in the working directory.
+
+        Warns when the default file is absent, because audit is also useful
+        outside a project directory. A missing explicit path, invalid JSON,
+        missing ``agent``, or invalid remote tool definition is a hard failure.
+        """
+        config_path = resolve_default_config(config).resolve()
+        if not config_path.exists():
+            status = "warn" if config == DEFAULT_CONFIG_FILE else "fail"
+            return Diagnostic("Project config", status, f"not found at {config_path}")
+        try:
+            data = json.loads(config_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            return Diagnostic("Project config", "fail", str(exc))
+        if not isinstance(data, dict):
+            return Diagnostic("Project config", "fail", f"{config_path.name} must be an object")
+        agent = data.get("agent")
+        if not isinstance(agent, str) or ":" not in agent:
+            return Diagnostic("Project config", "fail", "'agent' must be a module:attribute string")
+        try:
+            tools = validate_remote_tools(data.get("remote_tools", []))
+        except ValueError as exc:
+            return Diagnostic("Project config", "fail", str(exc))
+        return Diagnostic("Project config", "pass", f"{config_path} ({len(tools)} remote tools)")
+
+    @staticmethod
+    def _port_check(port: int) -> Diagnostic:
+        """Warn when ``port`` on loopback already has a listener.
+
+        A short connect probe, not a bind attempt, so the audit never steals
+        the port from a server that is about to start.
+        """
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.settimeout(0.2)
+            if sock.connect_ex(("127.0.0.1", port)) == 0:
+                return Diagnostic(f"Port {port}", "warn", "already in use")
+        return Diagnostic(f"Port {port}", "pass", "available")
+
+    @staticmethod
+    def _status_label(status: str) -> str:
+        """Render a status as the uppercase token used in the timeline and table."""
+        return {"pass": "PASS", "warn": "WARN", "fail": "FAIL"}[status]