Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ aiida-agents chat # interactive, and the only mode that can approve a w

`ask` is one-shot and cannot approve anything, so a request that wants to submit will tell you to use `chat`.

Other commands: `check` (provider reachability), `config` (effective settings), `rag search`, `mcp` (serve the read-only tools over the Model Context Protocol).
Other commands: `doctor` (diagnose the whole setup; `--warm` also proves the model generates), `config` (effective settings), `rag search`, `mcp` (serve the read-only tools over the Model Context Protocol).

## Where to look

Expand Down
4 changes: 2 additions & 2 deletions docs/gsoc/manual-test-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ ______________________________________________________________________
## Phase 0: setup and sanity

```bash
aiida-agents doctor # profile, model reachability, RAG index, docs toolchain
aiida-agents doctor # profile, daemon, model reachability, docs toolchain, RAG index, sandbox
aiida-agents doctor --warm # the same, plus one generation to prove the model serves
aiida-agents config show # every setting, its env var, and where the value came from
aiida-agents check # provider reachability, without loading the model
aiida-agents --help
```

Expand Down
109 changes: 39 additions & 70 deletions src/aiida_agents/cli/agent.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
"""Agent lifecycle for the CLI: build it, run it, probe it.

Turns resolved settings into a ready agent (``_build_agent``), runs a one-shot
query (``ask``), and checks/warms the configured model (``_probe_model`` +
``_diagnose_probe_failure``). The heavy aiida / agent-stack imports stay local so
``--help`` and shell completion never load AiiDA.
query (``ask``), and probes the configured model for ``doctor``
(``_probe_reachable``, ``_probe_model``, ``_probe_failure_hint``). The heavy
aiida / agent-stack imports stay local so ``--help`` and shell completion never
load AiiDA.
"""

from __future__ import annotations
Expand All @@ -17,11 +18,10 @@
from pydantic_ai import Agent
from pydantic_ai.exceptions import UserError
from pydantic_ai.messages import ModelMessage
from typing_extensions import assert_never

from aiida_agents._settings import ModelSettings, _Provider, _format_validation_error
from aiida_agents.agents.planner import Specialist, Step, _as_specialist
from aiida_agents.cli.ollama import _ensure_ollama_model, _ollama_pull
from aiida_agents.cli.ollama import _ensure_ollama_model
from aiida_agents.agents.handoff import Handoff, NodeReference
from aiida_agents.cli.output import _trace_tool_calls, console

Expand Down Expand Up @@ -53,13 +53,6 @@ class _StepResult(NamedTuple):
#: not an agent, so it is never passed to ``get_agent``.
_SPECIALISTS = ("analysis", "execution", "codegen")

# Colored status glyphs so ``check`` marks success/failure the same green/red as
# ``doctor`` (which renders its rows through rich). ``click.echo`` strips the
# color automatically when the output is not a terminal.
_OK = click.style("✓", fg="green")
_FAIL = click.style("✗", fg="red")
_WARN = click.style("!", fg="yellow")


async def ask(
agent: Agent,
Expand Down Expand Up @@ -100,10 +93,9 @@ def _resolve_settings_or_fail(provider: str | None, model: str | None) -> ModelS
"""Resolve model settings, turning an invalid value into a clean CLI error.

``_resolve_model_settings`` raises pydantic's ``ValidationError`` (a raw
traceback) on a bad ``AIIDA_AGENTS_*`` value. The read-only diagnostics
commands (``check``/``warm``/``doctor``) build settings outside a ``try``, so
this converts it to a ``ClickException`` the way ``_build_agent`` does for its
other configuration errors.
traceback) on a bad ``AIIDA_AGENTS_*`` value. ``doctor`` builds settings
outside a ``try``, so this converts it to a ``ClickException`` the way
``_build_agent`` does for its other configuration errors.
"""
try:
return _resolve_model_settings(provider, model)
Expand Down Expand Up @@ -154,8 +146,8 @@ def _probe_model(settings: ModelSettings) -> None: # pragma: no cover

A failure surfaces here (before a session), and for a local Ollama model the
call loads it into memory so the first real query isn't a cold start. This is
the heavy path behind ``warm``; ``check`` uses :func:`_check_reachable`, which
never generates.
the heavy path behind ``doctor --warm``; the default report uses
:func:`_probe_reachable`, which never generates.
"""
from aiida_agents.agents._models import get_model

Expand All @@ -182,7 +174,7 @@ async def _list_model_ids(client: Any) -> set[str]:
# ``wait_for`` raises the asyncio one, a distinct class from the builtin
# ``TimeoutError`` (they were only merged into aliases in 3.11), so
# catching the builtin would let the timeout escape uncaught there.
# Phrase the message so ``_diagnose_probe_failure`` routes it to the
# Phrase the message so ``_probe_failure_hint`` routes it to the
# "unreachable" branch (it matches on "connect").
msg = f"could not connect within {_REACHABILITY_TIMEOUT:.0f}s"
raise ConnectionError(msg) from exc
Expand All @@ -203,8 +195,8 @@ def _probe_reachable(settings: ModelSettings) -> _Reachability:
Builds the model (validating provider / base_url / key presence), then lists
the endpoint's models (one cheap GET under a short timeout). ``model_ok`` is
whether the configured model is among those advertised. Raises on an
unreachable endpoint, bad key, or bad config. Shared by ``check`` and
``doctor``; never loads or runs the model.
unreachable endpoint, bad key, or bad config. Behind ``doctor``'s model
row; never loads or runs the model.
"""
from aiida_agents.agents._models import get_model

Expand All @@ -224,8 +216,8 @@ def _probe_reachable(settings: ModelSettings) -> _Reachability:
)


# How a probed model's availability maps to a single policy decision, shared by
# ``check`` and ``doctor`` so the "is it usable?" rule lives in one place.
# How a probed model's availability maps to a single policy decision, kept apart
# from the rendering so the "is it usable?" rule lives in one place.
_ModelAvailability: TypeAlias = Literal["available", "not_pulled", "unlisted"]


Expand All @@ -236,68 +228,45 @@ def _model_availability(

Ollama's ``/models`` listing is authoritative, so a model absent from it is
genuinely not pulled; a cloud (or openai-compatible) endpoint's listing may be
partial, so an absent model is only "unlisted" and may still work. Callers
render this as they need (``check`` echoes and exits; ``doctor`` builds a row).
partial, so an absent model is only "unlisted" and may still work. ``doctor``
renders the outcome as a row.
"""
if reach.model_ok:
return "available"
return "not_pulled" if provider == "ollama" else "unlisted"


def _check_reachable(settings: ModelSettings) -> None:
"""Print ``check``'s reachability report; exit non-zero on a real problem.
def _not_pulled_detail(settings: ModelSettings) -> str:
"""The one sentence for "this Ollama model is not installed".

Reachability / auth failures raise for the caller to diagnose. A configured
model the endpoint doesn't advertise is fatal for Ollama (its listing is
authoritative, so it means "not pulled"), but only a warning for cloud or
openai-compatible endpoints, whose ``/models`` listing may be partial.
Reached two ways a user cannot tell apart and should not have to: the
endpoint's listing not carrying the model, and the probe raising a 404 for
it. Both render this, so the report does not word one condition twice.
"""
reach = _probe_reachable(settings)
click.echo(f"Endpoint: {reach.endpoint}")
click.echo(f"{_OK} reachable ({reach.n_models} models advertised)")
availability = _model_availability(reach, settings.provider)
if availability == "available":
click.echo(f"{_OK} model '{settings.model}' is available")
return
if availability == "not_pulled":
click.echo(f"{_FAIL} model '{settings.model}' is not pulled.", err=True)
click.echo(f" Pull it with: ollama pull {settings.model}", err=True)
raise SystemExit(1)
if availability == "unlisted":
click.echo(
f"{_WARN} model '{settings.model}' is not in this endpoint's list "
"(it may be partial; the model may still work).",
err=True,
)
return
assert_never(availability) # pragma: no cover
return f"model not pulled (ollama pull {settings.model})"


def _probe_failure_hint(settings: ModelSettings, exc: Exception) -> str | None:
"""A model-probe failure phrased as what to do about it, or ``None``.

def _diagnose_probe_failure(settings: ModelSettings, exc: Exception) -> None:
"""Turn a probe failure into an actionable message, offering an Ollama pull."""
The three failures a user can actually fix (an unpulled Ollama model, a bad
or absent API key, a server that is not up) each surface as provider-specific
SDK wording that says what broke and never what to do. Classification is by
message text because that is the only thing those exceptions have in common.

``None`` means the failure is not one of the three, so the caller should fall
back to the exception's own message rather than print a guess.
"""
msg = str(exc).lower()
if settings.provider == "ollama" and ("not found" in msg or "404" in msg):
click.echo(f"{_FAIL} Ollama model '{settings.model}' is not pulled.", err=True)
if click.confirm(f"Pull it now (ollama pull {settings.model})?", default=True):
_ollama_pull(settings.model)
return
return _not_pulled_detail(settings)
if ("api" in msg and "key" in msg) or "401" in msg or "403" in msg:
if "not set" in msg or "environment variable" in msg or "set the" in msg:
click.echo(
f"{_FAIL} API key not set: set the provider's API key.", err=True
)
else:
click.echo(
f"{_FAIL} Authentication failed: check the provider's API key.",
err=True,
)
return
return "API key not set; set the provider's API key"
return "authentication failed; check the provider's API key"
if "connect" in msg or "connection" in msg:
click.echo(
f"{_FAIL} Could not reach the endpoint. Is the server running?", err=True
)
return
click.echo(f"{_FAIL} {exc}", err=True)
return "could not reach the endpoint; is the server running?"
return None


def _resolve_plan(
Expand Down
46 changes: 1 addition & 45 deletions src/aiida_agents/cli/commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,12 @@
and the ``doctor`` command live in their own modules and are registered onto
the root group at the bottom of this file. What stays here is the root group
(the global ``--provider`` / ``--model`` / ``--profile`` overrides and logging
setup) plus the small model-facing commands: ``chat``, ``ask``, ``check``, and
``warm``.
setup) plus the two model-facing commands: ``chat`` and ``ask``.
"""

from __future__ import annotations

import asyncio
import time

import rich_click as click
from pydantic_ai.tools import DeferredToolRequests
Expand All @@ -26,7 +24,6 @@
from aiida_agents.cli.mcp import mcp
from aiida_agents.cli.output import (
_warn_ungrounded,
_format_duration,
_print_reply,
_render_tool_calls,
console,
Expand All @@ -40,9 +37,6 @@
_StepResult,
_AGENT_CHOICES,
_build_agent,
_check_reachable,
_diagnose_probe_failure,
_probe_model,
_resolve_settings_or_fail,
ask,
)
Expand Down Expand Up @@ -189,44 +183,6 @@ def ask_cmd(ctx: click.Context, question: str, raw: bool) -> None:
)


@cli.command()
@click.pass_context
@_needs_recognized_settings
def check(ctx: click.Context) -> None:
"""Verify config, endpoint reachability, and model availability.

Fast and read-only: it never loads or runs the model. Use `warm` to
pre-load a local model before an interactive session.
"""
settings = _resolve_settings_or_fail(ctx.obj["provider"], ctx.obj["model"])
click.echo(f"Checking {settings.provider}:{settings.model} ...")
try:
_check_reachable(settings)
except Exception as exc:
_diagnose_probe_failure(settings, exc)
raise SystemExit(1) from exc


@cli.command()
@click.pass_context
@_needs_recognized_settings
def warm(ctx: click.Context) -> None:
"""Warm the model with one tiny generation, so the first query isn't cold.

Mainly useful for a local Ollama model before a session; for a cloud model
it is just a round-trip that also confirms generation works.
"""
settings = _resolve_settings_or_fail(ctx.obj["provider"], ctx.obj["model"])
click.echo(f"Warming {settings.provider}:{settings.model} ...")
start = time.monotonic()
try:
_probe_model(settings)
except Exception as exc:
_diagnose_probe_failure(settings, exc)
raise SystemExit(1) from exc
click.echo(f"✓ warmed in {_format_duration(time.monotonic() - start)}")


# Register the commands and groups that live in their own modules onto the root.
cli.add_command(config)
cli.add_command(sandbox)
Expand Down
2 changes: 1 addition & 1 deletion src/aiida_agents/cli/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ def _invalid_fields(exc: ValidationError) -> dict[str, str]:

Whole-model errors (a cross-field ``model_validator``, which carry no field
location) are omitted; those fields still render as ``(invalid)`` and the
full reason is available from ``aiida-agents check``.
full reason is available from ``aiida-agents doctor``.
"""
return {
str(err["loc"][-1]): err["msg"].removeprefix("Value error, ")
Expand Down
Loading
Loading