Skip to content

Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.

11.9 KB
Raw Blame
"""`design-agent doctor`: explain what is configured and what is missing, never print a secret."""

from __future__ import annotations

import importlib.metadata
import json
import os
import platform
import shutil
import sys
from dataclasses import asdict, dataclass
from pathlib import Path
from typing import Literal

from design_agent.brand.schema import BrandPackError, load_brand_pack
from design_agent.config import Settings
from design_agent.models.factory import Role, resolve_model
from design_agent.models.registry import ModelConfigurationError, ToolDisclosure

Status = Literal["ok", "warn", "fail"]
PACKAGES = (
    "managed-deepagents",
    "deepagents",
    "langchain",
    "langgraph",
    "langchain-anthropic",
    "langchain-openai",
)
PROVIDER_KEYS = {
    "anthropic": "anthropic_api_key",
    "openai": "openai_api_key",
    "google_genai": "google_api_key",
}
#: Keys a self-hosted install reads. `mda deploy` forwards every `.env` key but LangSmith's as a
#: deployment secret, so these must not sit in the `.env` an MDA deploy runs from.
SELF_HOSTED_KEYS = (
    "SLACK_BOT_TOKEN",
    "SLACK_APP_TOKEN",
    "SLACK_SIGNING_SECRET",
    "DATABASE_URL",
    "POSTGRES_PASSWORD",
    "DESIGN_AGENT_API_TOKENS",
)
#: MDA refuses a source archive over 200 MB; renders under `workspace/out/` are archived too.
RENDERS_WARN_BYTES = 150 * 1024 * 1024
MDA_FILES = (
    "agent.py",
    "identity.py",
    "instructions.md",
    "channels/slack.py",
    "sandbox/__init__.py",
    "sandbox/setup.sh",
)


@dataclass(frozen=True)
class Check:
    name: str
    status: Status
    detail: str


def _check_python() -> Check:
    ok = sys.version_info >= (3, 11)
    return Check("python", "ok" if ok else "fail", f"{platform.python_version()} (3.11+ required)")


def _check_packages() -> Check:
    versions = []
    for name in PACKAGES:
        try:
            versions.append(f"{name} {importlib.metadata.version(name)}")
        except importlib.metadata.PackageNotFoundError:
            return Check("packages", "fail", f"{name} is not installed; run `uv sync`")
    return Check("packages", "ok", ", ".join(versions))


def _check_models(settings: Settings) -> list[Check]:
    checks: list[Check] = []
    roles: tuple[Role, ...] = ("lead", "helper", "look")
    for role in roles:
        try:
            resolved = resolve_model(settings, role)
        except (ModelConfigurationError, ValueError) as error:
            checks.append(Check(f"model:{role}", "fail", str(error)))
            continue
        caps = resolved.caps
        note = (
            "registered"
            if caps.verified
            else "not in the registry: portable path, no provider features assumed"
        )
        disclosure = (
            "native tool search"
            if caps.disclosure is ToolDisclosure.PROVIDER_NATIVE
            else "portable tool selector"
        )
        checks.append(
            Check(
                f"model:{role}",
                "ok" if caps.verified else "warn",
                f"{resolved.spec} effort={resolved.effort or 'default'} ({note}; {disclosure})",
            )
        )
    spec = settings.lead_model()
    provider = spec.upstream.provider if spec.via_gateway else spec.provider
    if spec.via_gateway:
        has_key = (
            settings.langsmith_gateway_api_key is not None or settings.langsmith_api_key is not None
        )
        checks.append(
            Check(
                "model:key",
                "ok" if has_key else "warn",
                "LangSmith Gateway key " + ("set" if has_key else "missing"),
            )
        )
    elif field := PROVIDER_KEYS.get(provider):
        has_key = getattr(settings, field) is not None
        name = field.upper()
        checks.append(
            Check(
                "model:key",
                "ok" if has_key else "warn",
                f"{name} {'set' if has_key else 'missing: `demo` works without it, `ask` does not'}",
            )
        )
    return checks


def missing_model_key(settings: Settings) -> str | None:
    """The setting the lead model needs and lacks, or None (the CLI checks this before a turn)."""
    for check in _check_models(settings):
        if check.name == "model:key" and check.status != "ok":
            return (
                check.detail.split(" ")[0]
                if not check.detail.startswith("LangSmith")
                else "LANGSMITH_GATEWAY_API_KEY"
            )
    return None


def _check_brand(settings: Settings, root: Path) -> Check:
    path = settings.resolved_brand_path(root)
    try:
        pack = load_brand_pack(path, project_root=root)
    except BrandPackError as error:
        return Check("brand", "fail", "; ".join(error.problems[:6]))
    sample = "sample brand" if "examples/brands" in str(path) else "your brand"
    return Check(
        "brand",
        "ok",
        f"{pack.brand.name} ({sample}, {path.relative_to(root) if path.is_relative_to(root) else path}); fonts: {', '.join(pack.required_families())}",
    )


def _check_sandbox(settings: Settings) -> Check:
    if settings.sandbox == "host":
        return Check(
            "sandbox", "warn", "host mode: renderers run on this machine (development only)"
        )
    if settings.sandbox == "langsmith" or (
        settings.sandbox == "auto" and settings.sandbox_snapshot
    ):
        ok = settings.langsmith_api_key is not None and bool(settings.sandbox_snapshot)
        return Check(
            "sandbox",
            "ok" if ok else "fail",
            "LangSmith snapshot "
            + (settings.sandbox_snapshot or "not set")
            + ("" if settings.langsmith_api_key else "; LANGSMITH_API_KEY missing"),
        )
    from design_agent.runtime.sandbox.docker import DockerSandboxRunner

    available, reason = DockerSandboxRunner(image=settings.sandbox_image).available()
    return Check(
        "sandbox",
        "ok" if available else "warn",
        f"Docker image {settings.sandbox_image}"
        if available
        else f"{reason} (only local runs need it; an MDA deploy does not)",
    )


def _check_node() -> Check:
    node = shutil.which("node")
    return Check(
        "node",
        "ok" if node else "warn",
        "host Node found (gate unit tests)"
        if node
        else "Node not on PATH: gate unit tests skip; the sandbox has its own Node",
    )


def _check_mda_project(root: Path) -> Check:
    from design_agent.runtime.sandbox.publish import declared_base

    missing = [p for p in MDA_FILES if not (root / p).is_file()]
    if missing:
        return Check("mda-project", "warn", "missing " + ", ".join(missing))
    published = declared_base(root) != "docker_image"
    return Check(
        "mda-project",
        "ok",
        "declarations present" + ("; sandbox declares the published snapshot" if published else ""),
    )


def deploy_model_key(settings: Settings) -> str | None:
    """The `.env` key the deployed lead model needs, or None when it goes through the gateway."""
    spec = settings.lead_model()
    if spec.via_gateway:
        return None
    field = PROVIDER_KEYS.get(spec.provider)
    return field.upper() if field else None


def _check_mda_deploy(root: Path, settings: Settings | None = None) -> Check:
    """What would make a plain `mda deploy` of this checkout fail or ship the wrong thing.

    "Ready" means a deploy works as it stands: the snapshot is published and the lead model's key
    is in `.env` (a deploy ships `.env`, never the shell). Until then the check says what to do
    first, as a warning, since a checkout that only runs the local demo needs neither.
    """
    from dotenv import dotenv_values

    from design_agent.runtime.sandbox.publish import declared_base
    from design_agent.skills_lock import is_text, verify

    problems: list[str] = []
    warnings: list[str] = []
    first: list[str] = []
    binary = [
        path.relative_to(root).as_posix()
        for path in sorted((root / "skills").rglob("*"))
        if path.is_file() and not is_text(path)
    ]
    if binary:
        problems.append(
            f"Context Hub takes only UTF-8 text: move {', '.join(binary[:3])} to skill-binaries/"
        )
    if not verify(root).ok:
        warnings.append("vendored skills differ from skills-lock.json (`skills verify`)")
    env_file = root / ".env"
    env = dotenv_values(env_file) if env_file.is_file() else {}
    if (root / "sandbox" / "__init__.py").is_file() and declared_base(root) == "docker_image":
        if settings is not None and settings.langsmith_api_key is None:
            first.append("put LANGSMITH_API_KEY in .env (`config set LANGSMITH_API_KEY`)")
        first.append("publish the sandbox snapshot (`sandbox publish`)")
    key = deploy_model_key(settings) if settings is not None else None
    if key and not (env.get(key) or "").strip():
        first.append(f"put {key} in .env (`config set {key}`); a deploy ships .env, not your shell")
    forwarded = [key for key in SELF_HOSTED_KEYS if (env.get(key) or "").strip()]
    if forwarded:
        warnings.append(
            f"`mda deploy` would ship {', '.join(forwarded)} as deployment secrets; "
            "deploy from an .env without self-hosting keys"
        )
    out = root / "workspace" / "out"
    size = sum(p.stat().st_size for p in out.rglob("*") if p.is_file()) if out.is_dir() else 0
    if size > RENDERS_WARN_BYTES:
        warnings.append(
            f"workspace/out holds {size // (1024 * 1024)} MB of renders, which `mda deploy` "
            "archives (200 MB limit): clear old ones"
        )
    if first:
        warnings.insert(0, "before `mda deploy`: " + ", then ".join(first))
    status: Status = "fail" if problems else "warn" if warnings else "ok"
    detail = "; ".join(problems + warnings) or "ready for `mda deploy`"
    return Check("mda-deploy", status, detail)


def _check_paper(settings: Settings) -> Check:
    from design_agent.tools.paper import PaperConfigError, paper_server

    if settings.paper_mode == "off":
        return Check("paper", "ok", "off: boards render in the sandbox")
    try:
        server = paper_server(settings, runtime="local")
    except PaperConfigError as error:
        return Check("paper", "fail", str(error))
    where = server.url if server is not None and server.url else "stdio `paper mcp`"
    return Check("paper", "ok", f"{settings.paper_mode} via {where}")


def _check_mcp(root: Path) -> Check:
    from design_agent.tools.mcp import McpConfigError, declared_servers

    try:
        servers = declared_servers(root)
    except McpConfigError as error:
        return Check("mcp", "fail", f"config/mcp.toml: {error}")
    if not servers:
        return Check("mcp", "ok", "no MCP servers declared")
    unset = [s.name for s in servers if s.headers_env and s.headers(dict(os.environ)) is None]
    names = ", ".join(s.name for s in servers)
    return Check(
        "mcp",
        "warn" if unset else "ok",
        f"{names}" + (f"; missing credentials for {', '.join(unset)}" if unset else ""),
    )


def run_checks(settings: Settings, root: Path) -> list[Check]:
    return [
        _check_python(),
        _check_packages(),
        *_check_models(settings),
        _check_brand(settings, root),
        _check_sandbox(settings),
        _check_node(),
        _check_mda_project(root),
        _check_mda_deploy(root, settings),
        _check_mcp(root),
        _check_paper(settings),
    ]


def doctor_main(root: Path, *, as_json: bool = False) -> int:
    try:
        settings = Settings()
    except Exception as error:  # noqa: BLE001 - pydantic errors carry field names, not values
        print(f"configuration error: {type(error).__name__}: {str(error).splitlines()[0]}")
        return 1
    checks = run_checks(settings, root)
    if as_json:
        print(json.dumps([asdict(c) for c in checks], indent=2))
    else:
        marks = {"ok": "ok  ", "warn": "warn", "fail": "FAIL"}
        for check in checks:
            print(f"[{marks[check.status]}] {check.name:14} {check.detail}")
    return 1 if any(c.status == "fail" for c in checks) else 0