Bring in desk from news
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>
This commit is contained in:
1 parent
9d666d0937
commit
248ea1636d
36 files changed
+8393
No files matched your search
@@ -0,0 +1,461 @@
|
||||
"""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
|
||||
Reference in new issue
Block a user