The plugin contract, the model task and the tools roledesk imports, copied rather than reached through an editable install of news, which also exposes a package named pipeline. news stays the source of truth for desk. Refreshed from news/desk at a275c38a1aa0fe80a7ec7dd5781ecccf683f71c6 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
462 lines
20 KiB
Python
462 lines
20 KiB
Python
"""Who answers when a job needs a model.
|
|
|
|
There is one question this module exists to answer — *ask Claude this, get JSON
|
|
back* — and two ways to answer it. They are interchangeable, so a handler
|
|
asks without knowing which one ran:
|
|
|
|
api One call to the Claude API. Wants ANTHROPIC_API_KEY (or an
|
|
`ant auth login` profile). No local install, no subprocess,
|
|
per-token billing.
|
|
claude_code The Claude Agent SDK drives the `claude` CLI already on this
|
|
machine, on the subscription it is already signed in with.
|
|
No key, nothing to bill. This is what the server runs on
|
|
today, authenticated by CLAUDE_CODE_OAUTH_TOKEN.
|
|
|
|
`backend()` answers `""` when neither can run, and that is a failure rather
|
|
than a third way: the caller says so with a notice naming the reason — no
|
|
key, no CLI, `backend: off` — and the batch fails without asking anybody.
|
|
Nothing waits for a person to answer it by hand.
|
|
|
|
The seam is deliberately narrow: `ask_json` takes a system prompt, a payload
|
|
and a JSON schema, and returns parsed JSON. Both backends take the *same*
|
|
schema — the Agent SDK accepts the Messages API's `json_schema` output format
|
|
and hands the parsed object back on `ResultMessage.structured_output` — so
|
|
neither path is the degraded one, and moving between them is a config line
|
|
rather than a second implementation.
|
|
|
|
Both also *stream*, and hand the text out through `on_partial` as it arrives.
|
|
Nothing here does anything with it — this module still knows only "JSON in,
|
|
JSON out" — but a batch of twenty-five articles is one request that takes the
|
|
best part of a minute, and the answers inside it are finished one at a time
|
|
long before the request is. Passing the pieces up is what lets the layer that
|
|
knows what an answer looks like count them, and a progress bar move per
|
|
article instead of per batch.
|
|
|
|
What the `claude_code` backend deliberately does not get: no tools
|
|
(`tools=[]`), no filesystem settings (`setting_sources=None`, so no CLAUDE.md,
|
|
no skills, no MCP servers leak into a tagging call), no session to resume. One
|
|
text-in, JSON-out turn — the same shape as the API call it stands in for.
|
|
|
|
`thinking` is the one knob a caller turns, and it is stated to both backends
|
|
rather than left to either. It has to be: the CLI is built for agent work and
|
|
thinks unprompted, the Messages API thinks only when asked, so "say nothing"
|
|
means opposite things on the two sides. Saying `disabled` out loud is what
|
|
makes them the interchangeable pair this module claims — and it is worth
|
|
saying, because on a batch of twenty-five headlines the CLI's default cost
|
|
128s against 17s for the same tags. What to think about is the task's business
|
|
(`ModelTaskConfig.thinking`); making both backends agree on it is this one's.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import importlib.util
|
|
import json
|
|
import logging
|
|
import os
|
|
from collections.abc import Callable
|
|
from concurrent.futures import ThreadPoolExecutor
|
|
from dataclasses import dataclass, field
|
|
from typing import Any
|
|
|
|
from desk.config import AgentConfig
|
|
from desk.tools import credentials
|
|
|
|
log = logging.getLogger(__name__)
|
|
|
|
#: The backends `backend()` can name, best first. `auto` walks this list.
|
|
BACKENDS = ("api", "claude_code")
|
|
|
|
#: Where the answer goes as it arrives, a piece at a time. Called with raw
|
|
#: text, not parsed anything — half a JSON object is not a JSON object, and
|
|
#: what to make of a partial answer is the caller's business, not this
|
|
#: module's.
|
|
Partial = Callable[[str], None]
|
|
|
|
|
|
class AgentError(Exception):
|
|
"""The backend was there and the call still didn't produce an answer.
|
|
|
|
Raised for every failure mode of both paths — no SDK installed, no CLI on
|
|
PATH, an API error, a timeout, a response that isn't the shape asked for.
|
|
Callers treat it as "no answer this time", which for a job means either
|
|
moving on to the next batch or handing off to a human-driven agent.
|
|
"""
|
|
|
|
|
|
@dataclass(slots=True)
|
|
class Reply:
|
|
"""One answer, and enough about where it came from to say so in the UI."""
|
|
|
|
data: dict[str, Any]
|
|
backend: str = ""
|
|
model: str = ""
|
|
#: Filled by the `claude_code` path only, which is the reverse of what you
|
|
#: would expect: the SDK's `ResultMessage` prices the turn, so a
|
|
#: subscription that is billed nothing for it still reports a figure, while
|
|
#: the API path — the one actually billed — leaves this at zero because the
|
|
#: Messages response does not price itself. An estimate of what the run
|
|
#: would have cost on the API, then, and never a bill. `usage` is the field
|
|
#: to trust if you want to price it yourself.
|
|
cost_usd: float = 0.0
|
|
usage: dict[str, Any] = field(default_factory=dict)
|
|
|
|
|
|
# ------------------------------------------------------------ which backend
|
|
|
|
def has_api_credentials() -> bool:
|
|
"""Whether the API path can run unattended.
|
|
|
|
An unset ANTHROPIC_API_KEY isn't proof there are no credentials — the SDK
|
|
also reads ANTHROPIC_AUTH_TOKEN and an `ant auth login` profile — but env
|
|
vars are the only part we can check without importing the SDK.
|
|
"""
|
|
return any(os.environ.get(name) for name in (
|
|
"ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_PROFILE",
|
|
))
|
|
|
|
|
|
def has_claude_code() -> bool:
|
|
"""Whether the Agent SDK is here, and so whether there is a CLI to drive.
|
|
|
|
The SDK bundles its own `claude`, so having the package is enough — a
|
|
binary on PATH is a bonus, not a requirement, and checking for one would
|
|
wrongly rule out a machine where the SDK is the only install.
|
|
|
|
Not proof the call will work — the CLI may be signed out — but it is the
|
|
check that can be made in microseconds, which is what a job asking "can I
|
|
do this myself?" needs. A signed-out CLI surfaces as an `AgentError` on
|
|
the call, and the caller falls back exactly as if this had returned False.
|
|
"""
|
|
return importlib.util.find_spec("claude_agent_sdk") is not None
|
|
|
|
|
|
def backend(settings: AgentConfig) -> str:
|
|
"""Which backend will answer, or `""` for nobody.
|
|
|
|
`agent.backend: auto` prefers the API when there are credentials, because
|
|
that is the unattended path and the one production will use; it falls back
|
|
to the local Claude Code subscription, which is the one that costs nothing
|
|
while you are building. Naming a backend skips the detection — including
|
|
`off`, which is how you make everything that wants a model fail.
|
|
"""
|
|
want = settings.backend
|
|
if want == "off":
|
|
return ""
|
|
if want in BACKENDS:
|
|
return want
|
|
if has_api_credentials():
|
|
return "api"
|
|
if has_claude_code():
|
|
return "claude_code"
|
|
return ""
|
|
|
|
|
|
# ------------------------------------------------------------------ the ask
|
|
|
|
def _thinking(setting: str) -> Any:
|
|
"""One `thinking` setting in the form both SDKs take.
|
|
|
|
Returns `Any` on purpose. Each SDK declares its own TypedDict for the same
|
|
two-word object — `ThinkingConfigDisabledParam` on one side,
|
|
`ThinkingConfigDisabled` on the other — and neither can be named here
|
|
without importing an SDK this module is careful to keep optional. One
|
|
honest `Any` at the seam beats a hard dependency at the top of the file.
|
|
|
|
Anything that is not a mode we offer is off, rather than an error. This is
|
|
reached from config pydantic has already constrained to the same two words,
|
|
so a third one arriving here would be a bug in our own plumbing — and the
|
|
honest answer to that is the same one the default gives, not a failed run
|
|
the model would happily have answered.
|
|
"""
|
|
return {"type": "adaptive"} if setting == "adaptive" else {"type": "disabled"}
|
|
|
|
|
|
def ask_json(
|
|
settings: AgentConfig,
|
|
*,
|
|
system: str,
|
|
question: dict[str, Any],
|
|
schema: dict[str, Any],
|
|
model: str = "",
|
|
using: str = "",
|
|
thinking: str = "off",
|
|
on_partial: Partial | None = None,
|
|
) -> Reply:
|
|
"""Ask Claude `question`, constrained to `schema`, and parse the answer.
|
|
|
|
`system` is expected to be byte-identical across the calls in a run — it is
|
|
what the API path caches. `question` is the part that changes. `using`
|
|
forces a backend for one call; otherwise `backend()` decides. `thinking` is
|
|
`off` or `adaptive`, and defaults to off because the caller who wants it is
|
|
rarer than the caller who would be surprised to be waiting for it.
|
|
|
|
`on_partial` is called with each piece of the answer as it arrives, in
|
|
order, on the thread this was called on. It is a courtesy, not a contract:
|
|
a backend that cannot stream simply never calls it, and the return value
|
|
is the same either way.
|
|
"""
|
|
name = using or backend(settings)
|
|
model = model or settings.model
|
|
if thinking == "adaptive" and model.startswith(
|
|
("claude-haiku-4-5", "claude-sonnet-4-5", "claude-opus-4-5")):
|
|
# These models support manual extended thinking only; fail before spend.
|
|
# https://platform.claude.com/docs/en/build-with-claude/extended-thinking
|
|
raise AgentError(f"{model} does not support adaptive thinking; set thinking: off "
|
|
"or choose a model supporting adaptive thinking")
|
|
if not name:
|
|
raise AgentError("no model backend is available")
|
|
if name == "api":
|
|
return _ask_api(settings, system, question, schema, model, thinking, on_partial)
|
|
if name == "claude_code":
|
|
return _ask_claude_code(settings, system, question, schema, model, thinking,
|
|
on_partial)
|
|
raise AgentError(f"unknown backend {name!r}")
|
|
|
|
|
|
def _ask_api(settings: AgentConfig, system: str, question: dict[str, Any],
|
|
schema: dict[str, Any], model: str, thinking: str = "off",
|
|
on_partial: Partial | None = None) -> Reply:
|
|
try:
|
|
import anthropic
|
|
except ImportError as exc:
|
|
raise AgentError(
|
|
"the anthropic SDK isn't installed — `uv pip install anthropic`"
|
|
) from exc
|
|
|
|
try:
|
|
client = anthropic.Anthropic(timeout=settings.timeout)
|
|
# Streamed rather than awaited whole, always — not only when someone
|
|
# passed `on_partial`. One code path is worth more than the few lines a
|
|
# non-streaming branch would save, and a minute-long request held open
|
|
# by a single response is the shape that trips idle timeouts in
|
|
# whatever sits between here and the API.
|
|
with client.messages.stream(
|
|
model=model,
|
|
max_tokens=settings.max_tokens,
|
|
system=[{
|
|
"type": "text",
|
|
"text": system,
|
|
# The instructions are byte-identical across every batch and
|
|
# every run; only the payload below changes.
|
|
"cache_control": {"type": "ephemeral"},
|
|
}],
|
|
messages=[{"role": "user", "content": _dumps(question)}],
|
|
thinking=_thinking(thinking),
|
|
output_config={"format": {"type": "json_schema", "schema": schema}},
|
|
) as stream:
|
|
for event in stream:
|
|
if on_partial is not None and (piece := _delta(event)):
|
|
on_partial(piece)
|
|
response = stream.get_final_message()
|
|
except (anthropic.APIError, TypeError) as exc:
|
|
# The status code carried through in the text on purpose: it is what
|
|
# `notices.classify` reads to tell "your key is wrong" (401) apart from
|
|
# "you are being rate limited" (429), which want different reactions
|
|
# from you and which the message body alone does not always separate.
|
|
status = getattr(exc, "status_code", "")
|
|
raise AgentError(
|
|
f"the API call failed: {f'{status} ' if status else ''}{exc}") from exc
|
|
|
|
text = next((b.text for b in response.content if b.type == "text"), "")
|
|
return Reply(
|
|
data=_parse(text),
|
|
backend="api",
|
|
model=response.model or model,
|
|
usage=response.usage.model_dump() if response.usage else {},
|
|
)
|
|
|
|
|
|
def _ask_claude_code(settings: AgentConfig, system: str, question: dict[str, Any],
|
|
schema: dict[str, Any], model: str, thinking: str = "off",
|
|
on_partial: Partial | None = None) -> Reply:
|
|
try:
|
|
from claude_agent_sdk import (
|
|
ClaudeAgentOptions, ClaudeSDKError, ResultMessage, StreamEvent, query,
|
|
)
|
|
except ImportError as exc:
|
|
raise AgentError(
|
|
"the Claude Agent SDK isn't installed — "
|
|
"`uv pip install claude-agent-sdk`"
|
|
) from exc
|
|
|
|
options = ClaudeAgentOptions(
|
|
system_prompt=system,
|
|
model=model or None,
|
|
# A classification call, not an agent: nothing to run, nothing to
|
|
# read, and no project settings — so no CLAUDE.md, no skills and no
|
|
# MCP servers get in front of the model on the way to a tag list.
|
|
tools=[],
|
|
allowed_tools=[],
|
|
permission_mode="dontAsk",
|
|
setting_sources=None,
|
|
# Always stated, never left to the CLI's default, which is on. With
|
|
# it on the progress bar also stops meaning anything: thinking emits
|
|
# nothing `_Answered` can count, so a chunk streams no `"uid"` until
|
|
# the thinking is done, and the bar sits on the previous chunk's
|
|
# number until the answer arrives in a rush.
|
|
thinking=_thinking(thinking),
|
|
output_format={"type": "json_schema", "schema": schema},
|
|
# Only when someone is listening. The partials are the same bytes as
|
|
# the final answer sent again in pieces, and asking the CLI for them
|
|
# when nothing reads them is noise on the pipe for no one's benefit.
|
|
include_partial_messages=on_partial is not None,
|
|
cli_path=settings.cli_path or None,
|
|
# `max_tokens` has to mean the same thing on both backends or it means
|
|
# nothing. The Messages API takes it as a parameter and the CLI takes
|
|
# it only as an environment variable, so without this the setting was
|
|
# quietly API-only — which is how a call configured for 8,192 tokens
|
|
# answered with 11,706 and nothing objected. The SDK merges this into
|
|
# the inherited environment rather than replacing it, so naming one
|
|
# variable does not cost the CLI its PATH.
|
|
env={"CLAUDE_CODE_MAX_OUTPUT_TOKENS": str(settings.max_tokens),
|
|
**({"CLAUDE_CODE_OAUTH_TOKEN": oauth} if (oauth := credentials.token(settings)) else {})},
|
|
stderr=lambda line: log.debug("claude: %s", line.rstrip()),
|
|
)
|
|
|
|
async def ask() -> Reply:
|
|
answer: Reply | None = None
|
|
async for message in query(prompt=_dumps(question), options=options):
|
|
if isinstance(message, StreamEvent) and on_partial is not None:
|
|
piece = _delta(message.event)
|
|
if piece:
|
|
on_partial(piece)
|
|
continue
|
|
if not isinstance(message, ResultMessage):
|
|
continue
|
|
if message.is_error:
|
|
raise AgentError(_explain(
|
|
"; ".join(message.errors or []) or message.result
|
|
or f"the agent ended as {message.subtype}"))
|
|
data = message.structured_output
|
|
if not isinstance(data, dict):
|
|
# A run that ended without structured output — a limit, an
|
|
# interruption. `result` is the raw text if there is any, and
|
|
# that is worth one attempt at parsing before giving up.
|
|
data = _parse(message.result or "")
|
|
answer = Reply(
|
|
data=data,
|
|
backend="claude_code",
|
|
model=model,
|
|
cost_usd=message.total_cost_usd or 0.0,
|
|
usage=message.usage or {},
|
|
)
|
|
if answer is None:
|
|
raise AgentError("the agent returned no result")
|
|
return answer
|
|
|
|
try:
|
|
return _sync(ask(), settings.timeout)
|
|
except ClaudeSDKError as exc:
|
|
# The SDK has its own exception hierarchy — a CLI that exited, a line
|
|
# it could not parse, an answer that overran `max_tokens` — and none of
|
|
# it is an `AgentError`. Left alone those escape the per-chunk `except
|
|
# AgentError` in `with_model`, so one bad chunk takes down a run that
|
|
# is contractually supposed to leave its rows for next time. Every
|
|
# failure of this backend is an `AgentError` or none of them are.
|
|
#
|
|
# The text is passed through intact rather than summarised: `notices`
|
|
# matches on prose, by its own deliberate design, so the wording *is*
|
|
# the thing that decides which sentence you get told.
|
|
raise AgentError(_explain(str(exc))) from exc
|
|
|
|
|
|
# --------------------------------------------------------------- plumbing
|
|
|
|
def _field(event: Any, name: str) -> Any:
|
|
"""One field of a stream event, whichever shape it arrived in.
|
|
|
|
The two backends carry the same events in different clothes: the API SDK
|
|
parses them into objects, and the CLI passes the wire format straight
|
|
through as dicts. Reading both through here is what lets `_delta` be
|
|
written once.
|
|
"""
|
|
return event.get(name) if isinstance(event, dict) else getattr(event, name, None)
|
|
|
|
|
|
def _delta(event: Any) -> str:
|
|
"""The answer text one stream event carries, or "" for the many with none.
|
|
|
|
The events worth anything here are `content_block_delta`, whose delta is
|
|
`text` for a plain answer and `partial_json` when the schema is enforced
|
|
through a tool. Everything else — message start and stop, block
|
|
boundaries, usage — is dropped.
|
|
|
|
Deliberately reads defensively rather than by type. An event shape nobody
|
|
here recognises must be nothing, not an exception: this drives a progress
|
|
bar, and it does not get to fail a run the model is answering correctly.
|
|
"""
|
|
if _field(event, "type") != "content_block_delta":
|
|
return ""
|
|
delta = _field(event, "delta")
|
|
if delta is None:
|
|
return ""
|
|
piece = _field(delta, "text") or _field(delta, "partial_json") or ""
|
|
return piece if isinstance(piece, str) else ""
|
|
|
|
|
|
def _sync(coro: Any, timeout: float) -> Reply:
|
|
"""Run one coroutine to completion from synchronous code.
|
|
|
|
Jobs are synchronous by design and the worker runs them on a thread, so
|
|
there is normally no loop here and `asyncio.run` is exactly right. The
|
|
thread pool is for the other caller — anything asking from inside a
|
|
running loop, where `asyncio.run` would raise.
|
|
"""
|
|
import asyncio
|
|
|
|
async def bounded() -> Reply:
|
|
try:
|
|
return await asyncio.wait_for(coro, timeout)
|
|
except TimeoutError as exc:
|
|
raise AgentError(f"no answer within {timeout:g}s") from exc
|
|
|
|
try:
|
|
asyncio.get_running_loop()
|
|
except RuntimeError:
|
|
return asyncio.run(bounded())
|
|
with ThreadPoolExecutor(max_workers=1) as pool:
|
|
return pool.submit(asyncio.run, bounded()).result()
|
|
|
|
|
|
def _explain(error: str) -> str:
|
|
"""Keep the raw failure text intact for the layer that classifies it.
|
|
|
|
This used to append advice ("the `claude` login looks expired, run…"),
|
|
which was the right instinct in the wrong place: the message was built here
|
|
and then swallowed three frames up by a `except AgentError: continue`, so
|
|
the advice never reached anyone. Recognising the failure and deciding what
|
|
to say about it now lives in `desk/notices.py`, which has somewhere to
|
|
put the answer.
|
|
|
|
What stays here is the part only this module knows: the CLI can end a run
|
|
with an empty error and a subtype, and "" is not something to classify.
|
|
"""
|
|
return error.strip() or "the agent ended without saying why"
|
|
|
|
|
|
def _dumps(payload: dict[str, Any]) -> str:
|
|
return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
|
|
|
|
|
|
def _parse(text: str) -> dict[str, Any]:
|
|
"""The answer as a dict. Tolerant of a fenced or chatty response.
|
|
|
|
Both backends are asked for JSON through a schema, so this should be a
|
|
plain `json.loads`. It isn't, because "should be" is not a guarantee worth
|
|
losing a batch over — a model that wrapped its answer in a code fence has
|
|
still done the work.
|
|
"""
|
|
body = text.strip()
|
|
if body.startswith("```"):
|
|
body = body.split("\n", 1)[-1].rsplit("```", 1)[0]
|
|
start, end = body.find("{"), body.rfind("}")
|
|
if start == -1 or end <= start:
|
|
raise AgentError(f"no JSON object in the response: {text[:200]!r}")
|
|
try:
|
|
data = json.loads(body[start:end + 1])
|
|
except ValueError as exc:
|
|
raise AgentError(f"the response wasn't valid JSON: {exc}") from exc
|
|
if not isinstance(data, dict):
|
|
raise AgentError("the response wasn't a JSON object")
|
|
return data
|