hud-python 0.4.45__py3-none-any.whl → 0.5.1__py3-none-any.whl

hud/cli/flows/dev.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import base64
+import contextlib
+import json
+import logging
+from typing import Any
+
+from hud.settings import settings
+from hud.shared.requests import make_request
+from hud.utils.hud_console import hud_console
+
+logger = logging.getLogger(__name__)
+
+
+async def create_dynamic_trace(
+    *,
+    mcp_config: dict[str, dict[str, Any]],
+    build_status: bool,
+    environment_name: str,
+) -> tuple[str | None, str | None]:
+    """
+    Create a dynamic trace for HUD dev sessions when running in HTTP mode.
+
+    Sends a POST to the HUD API with:
+      - mcp_config: points to the local MCP config (same as Cursor)
+      - build_status: True if Docker mode (built image), False if basic Python mode
+      - environment_name: Name of the environment/server/image
+      - git_info: Repository information (if available)
+
+    Returns the full URL to the live trace when successful, otherwise None.
+    """
+    api_base = settings.hud_api_url.rstrip("/")
+    # Endpoint TBD; use a sensible default path that the backend can wire up
+    url = f"{api_base}/dev/dynamic-traces"
+
+    # Get git repository information
+    from hud.cli.utils.git import get_git_info
+
+    git_info = get_git_info()
+
+    payload = {
+        "mcp_config": mcp_config,
+        "build_status": bool(build_status),
+        "environment_name": environment_name,
+    }
+
+    # Add git info if available
+    if git_info and git_info.get("remote_url"):
+        payload["git_info"] = git_info
+        logger.info("Detected git repository: %s", git_info.get("remote_url"))
+    else:
+        logger.info("No git repository detected")
+
+    # Require API key for dev mode
+    api_key = settings.api_key
+    if not api_key:
+        hud_console.error("HUD_API_KEY is required for hud dev command")
+        hud_console.info("")
+        hud_console.info("Please set your API key using one of these methods:")
+        hud_console.info("  1. Set environment variable: export HUD_API_KEY=your_key")
+        hud_console.info("  2. Use hud set command: hud set api_key your_key")
+        hud_console.info("")
+        hud_console.info("Get your API key at: https://hud.ai/settings")
+        import sys
+
+        sys.exit(1)
+
+    try:
+        resp = await make_request("POST", url=url, json=payload, api_key=api_key)
+        # New API returns an id; construct the URL as https://hud.ai/trace/{id}
+        trace_id = resp.get("id")
+
+        if isinstance(trace_id, str) and trace_id:
+            return trace_id, f"https://hud.ai/trace/{trace_id}"
+        return None, None
+    except Exception as e:
+        # Do not interrupt dev flow
+        try:
+            preview = json.dumps(payload)[:500]
+            logger.warning("Failed to create dynamic dev trace: %s | payload=%s", e, preview)
+        except Exception:
+            logger.warning("Failed to create dynamic dev trace: %s", e)
+        return None, None
+
+
+def show_dev_ui(
+    *,
+    live_trace_url: str,
+    server_name: str,
+    port: int,
+    cursor_deeplink: str,
+    is_docker: bool = False,
+) -> None:
+    """
+    Show the minimal dev UI with live trace link.
+
+    This is called only when we have a successful trace URL.
+    For full UI mode, the caller should use show_dev_server_info() directly.
+
+    Args:
+        live_trace_url: URL to the live trace
+        server_name: Name of the server/image
+        port: Port the server is running on
+        cursor_deeplink: Pre-generated Cursor deeplink URL
+        is_docker: Whether this is Docker mode (affects hot-reload message)
+    """
+    import webbrowser
+
+    from rich.panel import Panel
+
+    # Show header first
+    hud_console.header("HUD Development Server", icon="🚀")
+
+    # Try to open the live trace in the default browser
+    with contextlib.suppress(Exception):
+        # new=2 -> open in a new tab, if possible
+        webbrowser.open(live_trace_url, new=2)
+
+    # Show panel with just the link
+    # Center the link and style it: blue, bold, underlined
+    link_markup = f"[bold underline rgb(108,113,196)][link={live_trace_url}]{live_trace_url}[/link][/bold underline rgb(108,113,196)]"  # noqa: E501
+    # Use center alignment by surrounding with spaces via justify
+    from rich.align import Align
+
+    panel = Panel(
+        Align.center(link_markup),
+        title="🔗 Live Dev Trace",
+        border_style="rgb(192,150,12)",  # HUD gold
+        padding=(1, 2),
+    )
+    hud_console.console.print(panel)
+
+    # Show other info below
+    label = "Base image" if is_docker else "Server"
+    hud_console.info("")
+    hud_console.info(f"{hud_console.sym.ITEM} {label}: {server_name}")
+    hud_console.info(f"{hud_console.sym.ITEM} Cursor:")
+    # Display the Cursor link on its own line to prevent wrapping
+    hud_console.link(cursor_deeplink)
+    hud_console.info("")
+    hud_console.info(f"{hud_console.sym.SUCCESS} Hot-reload enabled")
+    if is_docker:
+        hud_console.dim_info(
+            "",
+            "Container restarts on file changes in watched folders (-w), "
+            "rebuild with 'hud dev' if changing other files",
+        )
+    hud_console.info("")
+
+
+def generate_cursor_deeplink(server_name: str, port: int) -> str:
+    """Generate a Cursor deeplink for the MCP server.
+
+    Args:
+        server_name: Name of the server
+        port: Port the server is running on
+
+    Returns:
+        Cursor deeplink URL
+    """
+    server_config = {"url": f"http://localhost:{port}/mcp"}
+    config_json = json.dumps(server_config, indent=2)
+    config_base64 = base64.b64encode(config_json.encode()).decode()
+    return (
+        f"cursor://anysphere.cursor-deeplink/mcp/install?name={server_name}&config={config_base64}"
+    )

hud/cli/flows/init.py

@@ -0,0 +1,191 @@
+"""Smart HUD environment initialization."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from hud.utils.hud_console import HUDConsole
+
+from .templates import DOCKERFILE_HUD, ENV_PY, PYPROJECT_TOML
+
+# Files that indicate this might be an existing project
+PROJECT_INDICATORS = {
+    "pyproject.toml",
+    "package.json",
+    "requirements.txt",
+    "setup.py",
+    "Cargo.toml",
+    "go.mod",
+}
+
+
+def _normalize_name(name: str) -> str:
+    """Normalize name for Python identifiers."""
+    name = name.replace("-", "_").replace(" ", "_")
+    return "".join(c if c.isalnum() or c == "_" else "_" for c in name)
+
+
+def _has_hud_dependency(directory: Path) -> bool:
+    """Check if hud-python is already in pyproject.toml."""
+    pyproject = directory / "pyproject.toml"
+    if not pyproject.exists():
+        return False
+    content = pyproject.read_text()
+    return "hud-python" in content or "hud_python" in content
+
+
+def _add_hud_dependency(directory: Path) -> str:
+    """Add hud-python using uv if available.
+
+    Returns:
+        "exists" if already present, "added" if added, "failed" if failed
+    """
+    if _has_hud_dependency(directory):
+        return "exists"
+
+    try:
+        result = subprocess.run(
+            ["uv", "add", "hud-python", "openai"],  # noqa: S607
+            capture_output=True,
+            text=True,
+            cwd=directory,
+            check=False,
+        )
+        if result.returncode == 0 or "already" in result.stderr.lower():
+            return "added"
+        return "failed"
+    except FileNotFoundError:
+        return "failed"
+
+
+def _is_empty_or_trivial(directory: Path) -> bool:
+    """Check if directory is empty or only has trivial files."""
+    if not directory.exists():
+        return True
+    files = list(directory.iterdir())
+    # Empty
+    if not files:
+        return True
+    # Only has hidden files or common trivial files
+    trivial = {".git", ".gitignore", ".DS_Store", "README.md", "LICENSE"}
+    return all(f.name in trivial or f.name.startswith(".") for f in files)
+
+
+def _has_project_files(directory: Path) -> bool:
+    """Check if directory has files indicating an existing project."""
+    if not directory.exists():
+        return False
+    return any(f.name in PROJECT_INDICATORS for f in directory.iterdir())
+
+
+def smart_init(
+    name: str | None = None,
+    directory: str = ".",
+    force: bool = False,
+) -> None:
+    """Initialize HUD environment files in a directory.
+
+    - If directory is empty: delegate to preset selection
+    - If directory has project files: add HUD files to existing project
+    - Otherwise: create new HUD environment
+    """
+    from hud.settings import settings
+
+    hud_console = HUDConsole()
+
+    # Check for API key first
+    if not settings.api_key:
+        hud_console.error("HUD_API_KEY not found")
+        hud_console.info("")
+        hud_console.info("Set your API key:")
+        hud_console.info("  hud set HUD_API_KEY=your-key-here")
+        hud_console.info("  Or: export HUD_API_KEY=your-key")
+        hud_console.info("")
+        hud_console.info("Get your key at: https://hud.ai/settings/api-keys")
+        return
+
+    target = Path(directory).resolve()
+
+    # If directory is empty, use preset selection
+    if _is_empty_or_trivial(target):
+        from hud.cli.init import create_environment
+
+        hud_console.info("Empty directory - showing preset selection")
+        create_environment(name, directory, force, preset=None)
+        return
+
+    # Directory has files - use smart init
+    target.mkdir(parents=True, exist_ok=True)
+    env_name = _normalize_name(name or target.name)
+    has_pyproject = (target / "pyproject.toml").exists()
+
+    hud_console.header(f"HUD Init: {env_name}")
+
+    if has_pyproject:
+        hud_console.info("Found pyproject.toml - adding HUD files")
+    else:
+        hud_console.info("Creating HUD environment in existing directory")
+
+    created = []
+
+    # Create pyproject.toml if needed
+    if not has_pyproject:
+        pyproject = target / "pyproject.toml"
+        pyproject.write_text(PYPROJECT_TOML.format(name=env_name.replace("_", "-")))
+        created.append("pyproject.toml")
+
+    # Create Dockerfile.hud
+    dockerfile = target / "Dockerfile.hud"
+    if not dockerfile.exists() or force:
+        dockerfile.write_text(DOCKERFILE_HUD)
+        created.append("Dockerfile.hud")
+    else:
+        hud_console.warning("Dockerfile.hud exists, skipping (use --force)")
+
+    # Create env.py
+    env_py = target / "env.py"
+    if not env_py.exists() or force:
+        env_py.write_text(ENV_PY.format(env_name=env_name))
+        created.append("env.py")
+    else:
+        hud_console.warning("env.py exists, skipping (use --force)")
+
+    # Add dependency
+    dep_result = _add_hud_dependency(target)
+    if dep_result == "added":
+        hud_console.success("Added hud-python dependency")
+    elif dep_result == "exists":
+        hud_console.info("hud-python already in dependencies")
+    else:
+        hud_console.info("Run manually: uv add hud-python openai")
+
+    # Summary
+    if created:
+        hud_console.section_title("Created")
+        for f in created:
+            hud_console.status_item(f, "✓")
+
+    hud_console.section_title("Next Steps")
+    hud_console.info("")
+    hud_console.info("1. Define your tools in env.py")
+    hud_console.info("   Tools are functions the agent can call. Wrap existing code")
+    hud_console.info("   with @env.tool() or connect FastAPI/OpenAPI servers.")
+    hud_console.info("")
+    hud_console.info("2. Write scripts that test agent behavior")
+    hud_console.info("   Scripts define prompts and scoring. The agent runs between")
+    hud_console.info("   two yields: first sends the task, second scores the result.")
+    hud_console.info("")
+    hud_console.info("3. Run locally to iterate")
+    hud_console.command_example("python env.py", "Run the test script")
+    hud_console.info("")
+    hud_console.info("4. Deploy for scale")
+    hud_console.info("   Push to GitHub, connect on hud.ai. Then run hundreds of")
+    hud_console.info("   evals in parallel and collect training data.")
+    hud_console.info("")
+    hud_console.section_title("Files")
+    hud_console.info("• env.py         Your tools, scripts, and test code")
+    hud_console.info("• Dockerfile.hud Container config for remote deployment")
+
+
+__all__ = ["smart_init"]