From 34a3a680d0f38b239ab6fecbe8cb8d2a4f05c3ca Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 05:40:10 +0500 Subject: [PATCH 01/11] feat(tools): add @tool decorator for plain Python functions Any Python function can now be an agent tool. The signature becomes the Pydantic input model, the Google-style docstring becomes the tool description and per-parameter descriptions, and the return value is coerced into a ToolResult. Sync functions run off the event loop via asyncio.to_thread; a ToolUseContext parameter is injected rather than exposed in the schema. as_tool_definition() normalizes every accepted tool form -- a ToolDefinition, a decorated function, a plain function, or the name of a bundled tool -- so later layers can accept tools=[fn, "bash", definition]. Also fixes a clock-resolution flake in FilesystemRunStore.mark_interrupted_runs: the staleness cutoff is now inclusive, so stale_after_seconds=0 means "every running run is stale" even when the platform clock has not ticked. --- examples/45_function_tools.py | 127 ++++++++++ src/anycode/__init__.py | 14 ++ src/anycode/runstore/store.py | 6 +- src/anycode/tools/__init__.py | 14 ++ src/anycode/tools/function_tool.py | 346 +++++++++++++++++++++++++++ tests/test_function_tool.py | 364 +++++++++++++++++++++++++++++ 6 files changed, 870 insertions(+), 1 deletion(-) create mode 100644 examples/45_function_tools.py create mode 100644 src/anycode/tools/function_tool.py create mode 100644 tests/test_function_tool.py diff --git a/examples/45_function_tools.py b/examples/45_function_tools.py new file mode 100644 index 0000000..af0c237 --- /dev/null +++ b/examples/45_function_tools.py @@ -0,0 +1,127 @@ +# Demo 45 — Function Tools with the @tool Decorator +# Execute: uv run python examples/45_function_tools.py +# Requires: ANTHROPIC_API_KEY or OPENAI_API_KEY in the environment or .env. + +import asyncio +import os +import sys +from datetime import UTC, datetime + +from dotenv import load_dotenv + +from anycode import ( + Agent, + AgentInfo, + ToolExecutor, + ToolRegistry, + ToolUseContext, + as_tool_definition, + register_built_in_tools, + tool, +) + +load_dotenv() + + +def _resolve_provider() -> tuple[str, str]: + """Return (provider, model) based on available API keys.""" + if os.environ.get("ANTHROPIC_API_KEY"): + return "anthropic", "claude-haiku-4-5" + if os.environ.get("OPENAI_API_KEY"): + return "openai", "gpt-4o-mini" + print("ERROR: Set ANTHROPIC_API_KEY or OPENAI_API_KEY in .env") + sys.exit(1) + + +PROVIDER, MODEL = _resolve_provider() + +# --- A plain synchronous function becomes a tool --- + + +@tool +def convert_currency(amount: float, rate: float, target: str = "EUR") -> dict: + """Convert an amount using a fixed exchange rate. + + Args: + amount: The source amount to convert. + rate: Units of the target currency per unit of the source currency. + target: ISO code of the target currency. + """ + return {"converted": round(amount * rate, 2), "currency": target} + + +# --- An async function, with an explicit name and description --- + + +@tool(name="business_days", description="Count business days elapsed since a given ISO date.") +async def days_since(iso_date: str) -> int: + """Ignored — the explicit description above wins.""" + await asyncio.sleep(0) + start = datetime.fromisoformat(iso_date).replace(tzinfo=UTC) + span = (datetime.now(UTC) - start).days + return max(span - (span // 7) * 2, 0) + + +# --- A tool that needs to know which agent called it --- + + +@tool +def whoami(ctx: ToolUseContext) -> str: + """Report the name and model of the calling agent.""" + return f"{ctx.agent.name} running {ctx.agent.model}" + + +async def main() -> None: + print("Generated schemas\n" + "=" * 55) + for fn in (convert_currency, days_since, whoami): + definition = as_tool_definition(fn) + schema = definition.input_model.model_json_schema() + print(f"\n{definition.name}: {definition.description}") + print(f" properties: {sorted(schema.get('properties', {}))}") + print(f" required: {schema.get('required', [])}") + + # Decorated functions stay ordinary callables. + print("\nDirect call:", convert_currency(100.0, 0.92)) + + registry = ToolRegistry() + register_built_in_tools(registry) + for fn in (convert_currency, days_since, whoami): + registry.register(as_tool_definition(fn)) + executor = ToolExecutor(registry) + + # Tools are runnable standalone through the executor. + context = ToolUseContext(agent=AgentInfo(name="demo", role="demo", model=MODEL)) + direct = await executor.execute("business_days", {"iso_date": "2026-01-01"}, context) + print("Executor call:", direct.data) + + analyst = Agent( + config={ + "name": "analyst", + "model": MODEL, + "provider": PROVIDER, + "system_prompt": ( + "You are a precise financial assistant. Use the provided tools for every " + "calculation — never do the arithmetic yourself. Answer in one short sentence." + ), + "tools": ["convert_currency", "business_days", "whoami"], + "max_turns": 5, + "temperature": 0, + }, + tool_registry=registry, + tool_executor=executor, + ) + + print("\nLive agent run\n" + "=" * 55) + result = await analyst.run("Convert 250 units at a rate of 0.92 into EUR, then tell me who you are. Use the tools.") + + if not result.success: + print("Agent failed:", result.output) + sys.exit(1) + + print(result.output) + print("\nTools invoked:", ", ".join(call.tool_name for call in result.tool_calls) or "none") + print(f"Tokens — input: {result.token_usage.input_tokens}, output: {result.token_usage.output_tokens}") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/src/anycode/__init__.py b/src/anycode/__init__.py index 79f90d8..52a799f 100644 --- a/src/anycode/__init__.py +++ b/src/anycode/__init__.py @@ -222,6 +222,14 @@ from anycode.telemetry.tracer import ConsoleExporter, JSONLExporter, OTLPExporter, Span, Tracer from anycode.tools.built_in import BUILT_IN_TOOLS, register_built_in_tools from anycode.tools.executor import ToolExecutor +from anycode.tools.function_tool import ( + ToolDefinitionError, + as_tool_definition, + build_tool_definition, + builtin_tool_names, + function_tool, + tool, +) from anycode.tools.idempotency import ( IdempotencyClaim, InMemoryToolIdempotencyStore, @@ -637,6 +645,12 @@ # Tools "ToolRegistry", "ToolExecutor", + "tool", + "function_tool", + "as_tool_definition", + "build_tool_definition", + "builtin_tool_names", + "ToolDefinitionError", "IdempotencyClaim", "InMemoryToolIdempotencyStore", "SQLiteToolIdempotencyStore", diff --git a/src/anycode/runstore/store.py b/src/anycode/runstore/store.py index e578500..b288033 100644 --- a/src/anycode/runstore/store.py +++ b/src/anycode/runstore/store.py @@ -272,11 +272,15 @@ def mark_interrupted_runs(self, stale_after_seconds: float) -> list[str]: Call on startup so a crashed process never leaves phantom `running` states behind. Returns the run ids that were transitioned. + + The cutoff is inclusive: a heartbeat at least ``stale_after_seconds`` old is + stale. That makes ``stale_after_seconds=0`` mean "every running run is stale" + even on platforms whose clock has not ticked since the heartbeat was written. """ cutoff = _now() - timedelta(seconds=stale_after_seconds) interrupted: list[str] = [] for record in self.list_runs(): - if record.status == "running" and record.last_heartbeat < cutoff: + if record.status == "running" and record.last_heartbeat <= cutoff: self.update_status(record.run_id, "interrupted") interrupted.append(record.run_id) return interrupted diff --git a/src/anycode/tools/__init__.py b/src/anycode/tools/__init__.py index bc18bde..702798a 100644 --- a/src/anycode/tools/__init__.py +++ b/src/anycode/tools/__init__.py @@ -4,6 +4,14 @@ from anycode.tools.file_edit import file_edit_tool from anycode.tools.file_read import file_read_tool from anycode.tools.file_write import file_write_tool +from anycode.tools.function_tool import ( + ToolDefinitionError, + as_tool_definition, + build_tool_definition, + builtin_tool_names, + function_tool, + tool, +) from anycode.tools.grep import grep_tool from anycode.tools.idempotency import ( IdempotencyClaim, @@ -17,6 +25,12 @@ __all__ = [ "ToolRegistry", "ToolExecutor", + "tool", + "function_tool", + "as_tool_definition", + "build_tool_definition", + "builtin_tool_names", + "ToolDefinitionError", "define_tool", "register_built_in_tools", "BUILT_IN_TOOLS", diff --git a/src/anycode/tools/function_tool.py b/src/anycode/tools/function_tool.py new file mode 100644 index 0000000..4693b3e --- /dev/null +++ b/src/anycode/tools/function_tool.py @@ -0,0 +1,346 @@ +"""Turn plain Python functions into tool definitions. + +A function's signature becomes the input schema, its docstring becomes the description, +and its return value is coerced into a :class:`~anycode.types.ToolResult`. +""" + +from __future__ import annotations + +import asyncio +import functools +import inspect +import json +import re +from collections.abc import Callable +from typing import Any, overload + +from pydantic import BaseModel, create_model +from pydantic.fields import FieldInfo +from pydantic_core import PydanticUndefined + +from anycode.types import ToolDefinition, ToolResult, ToolUseContext + +# --------------------------------------------------------------------------- +# Naming and docstring grammar +# --------------------------------------------------------------------------- + +TOOL_NAME_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$") +CONTEXT_PARAMETER_NAMES = frozenset({"ctx", "context", "tool_context"}) +UNANNOTATED_PARAMETER_TYPE = str + +_SECTION_HEADER = re.compile( + r"^(Args|Arguments|Parameters|Params|Returns?|Raises|Yields?|Examples?|Notes?|Attributes|Warnings?)\s*:\s*$", + re.IGNORECASE, +) +_ARGUMENT_SECTIONS = frozenset({"args", "arguments", "parameters", "params"}) +_ARGUMENT_LINE = re.compile(r"^(?P[A-Za-z_]\w*)\s*(?:\((?P[^)]*)\))?\s*:\s*(?P.*)$") + + +class ToolDefinitionError(ValueError): + """Raised when a function cannot be turned into a usable tool.""" + + +# --------------------------------------------------------------------------- +# Docstring parsing +# --------------------------------------------------------------------------- + + +def parse_docstring(docstring: str | None) -> tuple[str, dict[str, str]]: + """Split a Google-style docstring into ``(summary, {parameter: description})``. + + Never raises: an unparseable docstring degrades to a summary with no parameter + descriptions. + """ + if not docstring or not docstring.strip(): + return "", {} + + lines = inspect.cleandoc(docstring).splitlines() + summary_lines: list[str] = [] + parameter_docs: dict[str, str] = {} + current_section = "summary" + current_parameter: str | None = None + + for line in lines: + header = _SECTION_HEADER.match(line.strip()) + if header: + current_section = header.group(1).lower() + current_parameter = None + continue + + if current_section == "summary": + summary_lines.append(line) + continue + + if current_section not in _ARGUMENT_SECTIONS: + continue + + stripped = line.strip() + if not stripped: + current_parameter = None + continue + + argument = _ARGUMENT_LINE.match(stripped) + if argument: + parameter_name = argument.group("name") + current_parameter = parameter_name + parameter_docs[parameter_name] = argument.group("description").strip() + elif current_parameter is not None: + parameter_docs[current_parameter] = f"{parameter_docs[current_parameter]} {stripped}".strip() + + return " ".join(" ".join(summary_lines).split()), parameter_docs + + +# --------------------------------------------------------------------------- +# Signature to Pydantic model +# --------------------------------------------------------------------------- + + +def _resolve_hints(fn: Callable[..., Any]) -> dict[str, Any]: + try: + from typing import get_type_hints + + return get_type_hints(fn, include_extras=True) + except Exception: + return dict(getattr(fn, "__annotations__", {})) + + +def _is_context_annotation(annotation: Any) -> bool: + return annotation is ToolUseContext or (isinstance(annotation, type) and issubclass(annotation, ToolUseContext)) + + +def _build_input_model( + fn: Callable[..., Any], + tool_name: str, + parameter_docs: dict[str, str], +) -> tuple[type[BaseModel], tuple[str, ...], str | None]: + """Return ``(input_model, field_names, context_parameter_name)`` for *fn*.""" + signature = inspect.signature(fn) + hints = _resolve_hints(fn) + + fields: dict[str, Any] = {} + field_names: list[str] = [] + context_parameter: str | None = None + + for parameter_name, parameter in signature.parameters.items(): + if parameter.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD): + raise ToolDefinitionError( + f'Tool "{tool_name}" cannot use *{parameter_name} — variadic parameters have no JSON Schema equivalent. ' + "Declare each parameter explicitly." + ) + + annotation = hints.get(parameter_name, parameter.annotation) + unannotated = annotation is inspect.Parameter.empty + + if (not unannotated and _is_context_annotation(annotation)) or (unannotated and parameter_name in CONTEXT_PARAMETER_NAMES): + if context_parameter is not None: + raise ToolDefinitionError( + f'Tool "{tool_name}" declares two context parameters ("{context_parameter}" and "{parameter_name}"). Keep only one.' + ) + context_parameter = parameter_name + continue + + if unannotated: + annotation = UNANNOTATED_PARAMETER_TYPE + + default = PydanticUndefined if parameter.default is inspect.Parameter.empty else parameter.default + field_info = FieldInfo.from_annotated_attribute(annotation, default) + if not field_info.description: + documented = parameter_docs.get(parameter_name) + if documented: + field_info.description = documented + + fields[parameter_name] = (field_info.annotation, field_info) + field_names.append(parameter_name) + + model_name = f"{_pascal_case(tool_name)}Input" + model = create_model(model_name, __module__=getattr(fn, "__module__", __name__), **fields) + return model, tuple(field_names), context_parameter + + +def _pascal_case(value: str) -> str: + return "".join(part.capitalize() for part in re.split(r"[^A-Za-z0-9]+", value) if part) or "Tool" + + +# --------------------------------------------------------------------------- +# Return-value coercion +# --------------------------------------------------------------------------- + + +def coerce_tool_result(value: object) -> ToolResult: + """Normalize any function return value into a :class:`ToolResult`.""" + if isinstance(value, ToolResult): + return value + if value is None: + return ToolResult(data="") + if isinstance(value, str): + return ToolResult(data=value) + if isinstance(value, BaseModel): + return ToolResult(data=value.model_dump_json()) + if isinstance(value, dict | list | tuple | int | float | bool): + return ToolResult(data=json.dumps(value, default=str)) + return ToolResult(data=str(value)) + + +# --------------------------------------------------------------------------- +# Definition builder +# --------------------------------------------------------------------------- + + +def build_tool_definition( + fn: Callable[..., Any], + *, + name: str | None = None, + description: str | None = None, + side_effecting: bool = False, + idempotency_key_field: str | None = "idempotency_key", +) -> ToolDefinition: + """Build a :class:`ToolDefinition` from *fn* without attaching anything to it.""" + if not callable(fn): + raise ToolDefinitionError(f"Expected a callable to build a tool from, got {type(fn).__name__}.") + + resolved_name = name or getattr(fn, "__name__", "") + if not TOOL_NAME_PATTERN.match(resolved_name): + raise ToolDefinitionError( + f'Invalid tool name "{resolved_name}". Names must start with a letter or underscore, ' + "use only letters, digits, hyphens, or underscores, and be at most 64 characters. " + 'Pass @tool(name="...") to override.' + ) + + summary, parameter_docs = parse_docstring(inspect.getdoc(fn)) + resolved_description = (description or summary).strip() + if not resolved_description: + raise ToolDefinitionError( + f'Tool "{resolved_name}" has no description. Add a docstring to {resolved_name}() or pass @tool(description="...").' + ) + + input_model, field_names, context_parameter = _build_input_model(fn, resolved_name, parameter_docs) + is_coroutine = inspect.iscoroutinefunction(fn) + + async def execute(params: BaseModel, context: ToolUseContext) -> ToolResult: + kwargs: dict[str, Any] = {field: getattr(params, field) for field in field_names} + if context_parameter is not None: + kwargs[context_parameter] = context + if is_coroutine: + return coerce_tool_result(await fn(**kwargs)) + return coerce_tool_result(await asyncio.to_thread(functools.partial(fn, **kwargs))) + + return ToolDefinition( + name=resolved_name, + description=resolved_description, + input_model=input_model, + execute=execute, + side_effecting=side_effecting, + idempotency_key_field=idempotency_key_field, + ) + + +def function_tool[F: Callable[..., Any]]( + fn: F, + *, + name: str | None = None, + description: str | None = None, + side_effecting: bool = False, + idempotency_key_field: str | None = "idempotency_key", +) -> F: + """Attach a generated :class:`ToolDefinition` to *fn* and return *fn* unchanged.""" + definition = build_tool_definition( + fn, + name=name, + description=description, + side_effecting=side_effecting, + idempotency_key_field=idempotency_key_field, + ) + setattr(fn, "tool_definition", definition) + setattr(fn, "__anycode_tool__", definition) + return fn + + +@overload +def tool[F: Callable[..., Any]](fn: F, /) -> F: ... + + +@overload +def tool[F: Callable[..., Any]]( + *, + name: str | None = ..., + description: str | None = ..., + side_effecting: bool = ..., + idempotency_key_field: str | None = ..., +) -> Callable[[F], F]: ... + + +def tool[F: Callable[..., Any]]( + fn: F | None = None, + /, + *, + name: str | None = None, + description: str | None = None, + side_effecting: bool = False, + idempotency_key_field: str | None = "idempotency_key", +) -> F | Callable[[F], F]: + """Expose a Python function as an agent tool. + + Usable bare (``@tool``) or configured (``@tool(name="search")``). The decorated + function is returned unchanged and stays directly callable; its generated + :class:`ToolDefinition` is available as ``fn.tool_definition``. + """ + if fn is not None: + return function_tool(fn) + + def _decorate(inner: F) -> F: + return function_tool( + inner, + name=name, + description=description, + side_effecting=side_effecting, + idempotency_key_field=idempotency_key_field, + ) + + return _decorate + + +# --------------------------------------------------------------------------- +# Normalization +# --------------------------------------------------------------------------- + + +def _named_tools() -> dict[str, ToolDefinition]: + from anycode.handoff.tool import HANDOFF_TOOL_DEF + from anycode.tools.built_in import BUILT_IN_TOOLS + + named = {definition.name: definition for definition in BUILT_IN_TOOLS} + named[HANDOFF_TOOL_DEF.name] = HANDOFF_TOOL_DEF + return named + + +def builtin_tool_names() -> tuple[str, ...]: + """Names accepted by :func:`as_tool_definition` when given a string.""" + return tuple(sorted(_named_tools())) + + +def as_tool_definition(spec: object) -> ToolDefinition: + """Normalize a tool specification into a :class:`ToolDefinition`. + + Accepts a ``ToolDefinition``, a ``@tool``-decorated function, any plain callable, + or the name of a bundled tool. + """ + if isinstance(spec, ToolDefinition): + return spec + + if isinstance(spec, str): + named = _named_tools() + found = named.get(spec) + if found is None: + raise ToolDefinitionError(f'Unknown built-in tool "{spec}". Available: {", ".join(sorted(named))}.') + return found + + if callable(spec): + attached = getattr(spec, "tool_definition", None) + if isinstance(attached, ToolDefinition): + return attached + return build_tool_definition(spec) + + raise ToolDefinitionError( + f"Cannot use {type(spec).__name__} as a tool. Pass a ToolDefinition, a function " + "(optionally decorated with @tool), or the name of a built-in tool." + ) diff --git a/tests/test_function_tool.py b/tests/test_function_tool.py new file mode 100644 index 0000000..f9498ef --- /dev/null +++ b/tests/test_function_tool.py @@ -0,0 +1,364 @@ +"""Tests for the @tool decorator and tool-specification normalization.""" + +from __future__ import annotations + +import asyncio +import json +import threading +from typing import Annotated + +import pytest +from pydantic import BaseModel, Field + +from anycode import ( + AgentInfo, + ToolDefinition, + ToolDefinitionError, + ToolExecutor, + ToolRegistry, + ToolResult, + ToolUseContext, + as_tool_definition, + tool, +) +from anycode.tools.function_tool import build_tool_definition, builtin_tool_names, coerce_tool_result, parse_docstring + + +def _context(name: str = "tester") -> ToolUseContext: + return ToolUseContext(agent=AgentInfo(name=name, role="test", model="test-model")) + + +# --------------------------------------------------------------------------- +# Bare decorator +# --------------------------------------------------------------------------- + + +@tool +def greet(name: str, excited: bool = False) -> str: + """Greet a person by name. + + Args: + name: Who to greet. + excited: Whether to add an exclamation mark. + """ + return f"Hello {name}{'!' if excited else '.'}" + + +def test_bare_decorator_builds_definition() -> None: + definition = as_tool_definition(greet) + assert isinstance(definition, ToolDefinition) + assert definition.name == "greet" + assert definition.description == "Greet a person by name." + assert definition.side_effecting is False + + +def test_schema_marks_required_and_optional_fields() -> None: + schema = as_tool_definition(greet).input_model.model_json_schema() + assert schema["required"] == ["name"] + assert schema["properties"]["name"]["description"] == "Who to greet." + assert schema["properties"]["excited"]["description"] == "Whether to add an exclamation mark." + assert schema["properties"]["excited"]["default"] is False + + +def test_decorated_function_stays_directly_callable() -> None: + assert greet("Ada", excited=True) == "Hello Ada!" + + +# --------------------------------------------------------------------------- +# Parametrized decorator +# --------------------------------------------------------------------------- + + +@tool(name="publish-note", description="Publish a note somewhere durable.", side_effecting=True) +async def publish(body: str, idempotency_key: str = "") -> str: + return f"published:{body}:{idempotency_key}" + + +def test_parametrized_decorator_overrides_metadata() -> None: + definition = as_tool_definition(publish) + assert definition.name == "publish-note" + assert definition.description == "Publish a note somewhere durable." + assert definition.side_effecting is True + + +# --------------------------------------------------------------------------- +# Docstring parsing +# --------------------------------------------------------------------------- + + +def test_parse_docstring_handles_sections_and_continuations() -> None: + summary, args = parse_docstring( + """Do a thing. + + Extra summary line. + + Args: + first: The first argument + which wraps onto a second line. + second (int): The second argument. + + Returns: + Something irrelevant. + """ + ) + assert summary == "Do a thing. Extra summary line." + assert args["first"] == "The first argument which wraps onto a second line." + assert args["second"] == "The second argument." + assert "Returns" not in args + + +def test_parse_docstring_degrades_on_unstructured_text() -> None: + summary, args = parse_docstring("Just a sentence with a colon: no sections here.") + assert summary == "Just a sentence with a colon: no sections here." + assert args == {} + + +def test_parse_docstring_handles_empty_input() -> None: + assert parse_docstring(None) == ("", {}) + assert parse_docstring(" ") == ("", {}) + + +# --------------------------------------------------------------------------- +# Annotated constraints +# --------------------------------------------------------------------------- + + +@tool +def scaled(value: Annotated[int, Field(ge=0, le=10, description="Clamped value.")]) -> int: + """Double a bounded value.""" + return value * 2 + + +def test_annotated_constraints_survive_into_schema() -> None: + schema = as_tool_definition(scaled).input_model.model_json_schema() + assert schema["properties"]["value"]["minimum"] == 0 + assert schema["properties"]["value"]["maximum"] == 10 + assert schema["properties"]["value"]["description"] == "Clamped value." + + +def test_annotated_constraints_reject_bad_input() -> None: + model = as_tool_definition(scaled).input_model + with pytest.raises(ValueError): + model.model_validate({"value": 99}) + + +# --------------------------------------------------------------------------- +# Async and sync execution +# --------------------------------------------------------------------------- + + +async def test_async_function_is_awaited() -> None: + @tool + async def slow_echo(text: str) -> str: + """Echo text.""" + await asyncio.sleep(0) + return text.upper() + + definition = as_tool_definition(slow_echo) + result = await definition.execute(definition.input_model.model_validate({"text": "hi"}), _context()) + assert result.data == "HI" + + +async def test_sync_function_runs_off_the_event_loop() -> None: + seen: list[int] = [] + + @tool + def blocking(marker: int) -> int: + """Record the calling thread.""" + seen.append(threading.get_ident()) + return marker + + definition = as_tool_definition(blocking) + result = await definition.execute(definition.input_model.model_validate({"marker": 7}), _context()) + assert result.data == "7" + assert seen and seen[0] != threading.get_ident() + + +# --------------------------------------------------------------------------- +# Context injection +# --------------------------------------------------------------------------- + + +async def test_context_injected_by_annotation_and_excluded_from_schema() -> None: + @tool + def whoami(prefix: str, ctx_param: ToolUseContext) -> str: + """Report the calling agent.""" + return f"{prefix}{ctx_param.agent.name}" + + definition = as_tool_definition(whoami) + assert set(definition.input_model.model_fields) == {"prefix"} + result = await definition.execute(definition.input_model.model_validate({"prefix": "agent="}), _context("scout")) + assert result.data == "agent=scout" + + +async def test_context_injected_by_conventional_name() -> None: + @tool + def named_context(value: str, ctx) -> str: # noqa: ANN001 - deliberately unannotated + """Use the conventional context parameter name.""" + return f"{value}:{ctx.agent.name}" + + definition = as_tool_definition(named_context) + assert set(definition.input_model.model_fields) == {"value"} + result = await definition.execute(definition.input_model.model_validate({"value": "v"}), _context("runner")) + assert result.data == "v:runner" + + +def test_two_context_parameters_are_rejected() -> None: + def doubled(ctx: ToolUseContext, context: ToolUseContext) -> str: + """Two contexts.""" + return "x" + + with pytest.raises(ToolDefinitionError, match="two context parameters"): + build_tool_definition(doubled) + + +# --------------------------------------------------------------------------- +# Return coercion +# --------------------------------------------------------------------------- + + +class _Payload(BaseModel): + value: int + + +@pytest.mark.parametrize( + ("returned", "expected"), + [ + (ToolResult(data="raw", is_error=True), "raw"), + ("plain", "plain"), + (None, ""), + (_Payload(value=3), '{"value":3}'), + ({"a": 1}, '{"a": 1}'), + ([1, 2], "[1, 2]"), + (True, "true"), + (4.5, "4.5"), + ], +) +def test_return_value_coercion(returned: object, expected: str) -> None: + assert coerce_tool_result(returned).data == expected + + +def test_tool_result_passthrough_preserves_flags() -> None: + original = ToolResult(data="boom", is_error=True, retry_safe=False) + assert coerce_tool_result(original) is original + + +def test_unknown_type_falls_back_to_str() -> None: + class Opaque: + def __str__(self) -> str: + return "opaque" + + assert coerce_tool_result(Opaque()).data == "opaque" + + +# --------------------------------------------------------------------------- +# Validation failures +# --------------------------------------------------------------------------- + + +def test_missing_description_is_rejected() -> None: + def undocumented(value: str) -> str: + return value + + with pytest.raises(ToolDefinitionError, match="has no description"): + build_tool_definition(undocumented) + + +def test_variadic_parameters_are_rejected() -> None: + def variadic(*args: str) -> str: + """Takes anything.""" + return "x" + + with pytest.raises(ToolDefinitionError, match="variadic parameters"): + build_tool_definition(variadic) + + +def test_invalid_name_is_rejected() -> None: + def fine(value: str) -> str: + """Fine.""" + return value + + with pytest.raises(ToolDefinitionError, match="Invalid tool name"): + build_tool_definition(fine, name="not a valid name!") + + +def test_unannotated_parameter_defaults_to_string() -> None: + @tool + def loose(value) -> str: # noqa: ANN001 - deliberately unannotated + """Accept anything as text.""" + return str(value) + + schema = as_tool_definition(loose).input_model.model_json_schema() + assert schema["properties"]["value"]["type"] == "string" + + +def test_zero_parameter_tool_is_valid() -> None: + @tool + def ping() -> str: + """Return pong.""" + return "pong" + + definition = as_tool_definition(ping) + assert definition.input_model.model_fields == {} + + +# --------------------------------------------------------------------------- +# Normalization +# --------------------------------------------------------------------------- + + +def test_as_tool_definition_accepts_every_supported_form() -> None: + definition = as_tool_definition(greet) + assert as_tool_definition(definition) is definition + assert as_tool_definition("file_read").name == "file_read" + + def undecorated(value: str) -> str: + """Undecorated but documented.""" + return value + + assert as_tool_definition(undecorated).name == "undecorated" + + +def test_as_tool_definition_rejects_other_values() -> None: + with pytest.raises(ToolDefinitionError, match="Cannot use int as a tool"): + as_tool_definition(3) + + +def test_unknown_builtin_name_lists_alternatives() -> None: + with pytest.raises(ToolDefinitionError, match="Available: bash"): + as_tool_definition("nope") + + +def test_builtin_tool_names_includes_bundled_tools() -> None: + names = builtin_tool_names() + assert {"bash", "file_read", "file_write", "file_edit", "grep", "list_files", "handoff"} <= set(names) + + +# --------------------------------------------------------------------------- +# End-to-end through the executor +# --------------------------------------------------------------------------- + + +async def test_round_trip_through_registry_and_executor() -> None: + @tool + def add(left: int, right: int = 1) -> dict: + """Add two integers.""" + return {"sum": left + right} + + registry = ToolRegistry() + registry.register(as_tool_definition(add)) + executor = ToolExecutor(registry) + + result = await executor.execute("add", {"left": 4, "right": 5}, _context()) + assert not result.is_error + assert json.loads(result.data) == {"sum": 9} + + +async def test_executor_reports_validation_errors() -> None: + registry = ToolRegistry() + registry.register(as_tool_definition(greet)) + executor = ToolExecutor(registry) + + result = await executor.execute("greet", {"excited": True}, _context()) + assert result.is_error + assert "Invalid input" in result.data From b84194c6995e02adcabaf083ca5f11f2f4f60574 Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 05:51:31 +0500 Subject: [PATCH 02/11] feat(core): construct agents from keyword arguments Agent gains a keyword constructor that wires its own registry and executor, so a working agent is one object instead of three: Agent(name="researcher", instructions="...", tools=[search, "bash"]) Provider and model are auto-detected from whichever credentials are present (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, AZURE_OPENAI_API_KEY, AWS_DEFAULT_REGION, OLLAMA_BASE_URL), removing the detection block every example copy-pastes. ANYCODE_DEFAULT_MODEL and ANYCODE_DEFAULT_PROVIDER override it. CrewAI-style role/goal/backstory framing composes into a system prompt when instructions= is absent. tools= accepts decorated functions, plain functions, ToolDefinitions, and built-in names; tools=[] now expresses "no tools", which was previously inexpressible. Adds blocking entry points for scripts and notebooks -- run_sync, prompt_sync, stream_sync (incremental, via a worker loop), and call_tool/call_tool_sync for exercising a tool without the LLM -- plus a tools property and a useful __repr__. The three-positional-argument constructor is unchanged; passing a config object alongside a conflicting field keyword raises AgentConfigError naming the conflict. --- examples/01_solo_worker.py | 148 ++++++------ examples/45_function_tools.py | 62 ++--- src/anycode/__init__.py | 8 +- src/anycode/core/agent.py | 264 ++++++++++++++++++++- src/anycode/core/defaults.py | 79 +++++++ src/anycode/helpers/sync_runner.py | 80 +++++++ src/anycode/tools/__init__.py | 4 + src/anycode/tools/function_tool.py | 19 +- tests/test_agent_ergonomics.py | 354 +++++++++++++++++++++++++++++ 9 files changed, 880 insertions(+), 138 deletions(-) create mode 100644 src/anycode/core/defaults.py create mode 100644 src/anycode/helpers/sync_runner.py create mode 100644 tests/test_agent_ergonomics.py diff --git a/examples/01_solo_worker.py b/examples/01_solo_worker.py index 020a9a3..e15b98f 100644 --- a/examples/01_solo_worker.py +++ b/examples/01_solo_worker.py @@ -3,78 +3,48 @@ # Requires: ANTHROPIC_API_KEY or OPENAI_API_KEY in the environment or .env. import asyncio -import os import sys +import tempfile +from pathlib import Path from dotenv import load_dotenv -from anycode import ( - Agent, - AnyCode, - ToolExecutor, - ToolRegistry, - register_built_in_tools, -) +from anycode import Agent, AnyCode load_dotenv() +SCRIPT_PATH = Path(tempfile.gettempdir(), "fibonacci.py").as_posix() -def _resolve_provider() -> tuple[str, str]: - """Return (provider, model) based on available API keys.""" - if os.environ.get("ANTHROPIC_API_KEY"): - return "anthropic", "claude-haiku-4-5" - if os.environ.get("OPENAI_API_KEY"): - return "openai", "gpt-4o-mini" - print("ERROR: Set ANTHROPIC_API_KEY or OPENAI_API_KEY in .env") - sys.exit(1) +# --- Section A: one agent, blocking call, no event loop to manage --- +# Provider and model are detected from whichever API key is present. -PROVIDER, MODEL = _resolve_provider() - -# --- Section A: Quick one-shot execution via the orchestrator facade --- - - -async def main() -> None: - engine = AnyCode( - config={ - "default_model": MODEL, - "on_progress": lambda ev: print( - f'>> worker "{ev.agent}" activated' - if ev.type == "agent_start" - else (f'<< worker "{ev.agent}" finished' if ev.type == "agent_complete" else ""), - ), - } - ) - - print("Section A: one-shot task via engine.run_agent()\n") - - outcome = await engine.run_agent( - config={ - "name": "scripter", - "model": MODEL, - "provider": PROVIDER, - "system_prompt": ( - "You are an efficient Python script writer. " - "Produce concise, working code without unnecessary explanation. " - "Leverage the provided tools to create and execute files." - ), - "tools": ["bash", "file_read", "file_write"], - "max_turns": 6, - }, - prompt=( - "Write a tiny Python script at /tmp/fibonacci.py that:\n" - "1. Defines a function fibonacci(n: int) -> int that returns the nth Fibonacci number\n" - "2. Includes a docstring describing the algorithm\n" - "3. At the bottom, call fibonacci(10) and print the result\n" - "Then run the script with: python /tmp/fibonacci.py" +def run_scripter() -> None: + scripter = Agent( + name="scripter", + instructions=( + "You are an efficient Python script writer. " + "Produce concise, working code without unnecessary explanation. " + "Use the provided tools to create and execute files." ), + tools=["bash", "file_read", "file_write"], + max_turns=6, + ) + print(f"Section A: blocking run via Agent.run_sync() — {scripter!r}\n") + + outcome = scripter.run_sync( + f"Write a tiny Python script at {SCRIPT_PATH} that:\n" + "1. Defines a function fibonacci(n: int) -> int that returns the nth Fibonacci number\n" + "2. Includes a docstring describing the algorithm\n" + "3. At the bottom, calls fibonacci(10) and prints the result\n" + f"Then run the script with: python {SCRIPT_PATH}" ) if not outcome.success: print("Worker encountered an issue:", outcome.output) sys.exit(1) - print("\nWorker response:") + print("Worker response:") print("=" * 50) print(outcome.output) print("=" * 50) @@ -84,28 +54,20 @@ async def main() -> None: f"tool invocations: {len(outcome.tool_calls)}" ) - # --- Section B: Incremental streaming through the Agent class directly --- - print("\n\nSection B: streaming via Agent.stream()\n") +async def main() -> None: + # --- Section B: incremental streaming --- - registry = ToolRegistry() - register_built_in_tools(registry) - executor = ToolExecutor(registry) + print("\n\nSection B: streaming via Agent.stream()\n") narrator = Agent( - config={ - "name": "narrator", - "model": MODEL, - "provider": PROVIDER, - "system_prompt": "You are a concise technical explainer. Respond in two sentences max.", - "max_turns": 2, - }, - tool_registry=registry, - tool_executor=executor, + name="narrator", + instructions="You are a concise technical explainer. Respond in two sentences max.", + tools=[], + max_turns=2, ) sys.stdout.write("Stream output: ") - async for chunk in narrator.stream("Explain what a closure is in Python in one sentence."): if chunk.type == "text" and isinstance(chunk.data, str): sys.stdout.write(chunk.data) @@ -114,20 +76,16 @@ async def main() -> None: elif chunk.type == "error": print(f"\nStream failure: {chunk.data}") - # --- Section C: Multi-turn dialogue through Agent.prompt() --- + # --- Section C: multi-turn dialogue --- print("\nSection C: conversational turns via Agent.prompt()\n") mentor = Agent( - config={ - "name": "mentor", - "model": MODEL, - "provider": PROVIDER, - "system_prompt": "You are a Python tutor. Give brief, practical answers.", - "max_turns": 2, - }, - tool_registry=ToolRegistry(), - tool_executor=ToolExecutor(ToolRegistry()), + name="mentor", + role="a Python tutor", + goal="give brief, practical answers", + tools=[], + max_turns=2, ) first_reply = await mentor.prompt("What are list comprehensions in Python?") @@ -137,8 +95,38 @@ async def main() -> None: print("\nReply 2:", follow_up.output[:280]) print(f"\nDialogue history length: {len(mentor.get_history())} messages") + + # --- Section D: the engine path, for orchestration-level concerns --- + + print("\nSection D: orchestrator events via AnyCode.run_agent()\n") + + engine = AnyCode( + config={ + "on_progress": lambda ev: print( + f'>> worker "{ev.agent}" activated' + if ev.type == "agent_start" + else (f'<< worker "{ev.agent}" finished' if ev.type == "agent_complete" else ""), + ), + } + ) + + summary = await engine.run_agent( + config={ + "name": "summarizer", + "model": mentor.config.model, + "provider": mentor.config.provider, + "system_prompt": "Summarize in one sentence.", + "tools": [], + "max_turns": 2, + }, + prompt="Summarize what a Python decorator does.", + ) + print("Summary:", summary.output.strip()) + await engine.close() + print("\nDone.") if __name__ == "__main__": + run_scripter() asyncio.run(main()) diff --git a/examples/45_function_tools.py b/examples/45_function_tools.py index af0c237..9ec18dc 100644 --- a/examples/45_function_tools.py +++ b/examples/45_function_tools.py @@ -3,38 +3,15 @@ # Requires: ANTHROPIC_API_KEY or OPENAI_API_KEY in the environment or .env. import asyncio -import os import sys from datetime import UTC, datetime from dotenv import load_dotenv -from anycode import ( - Agent, - AgentInfo, - ToolExecutor, - ToolRegistry, - ToolUseContext, - as_tool_definition, - register_built_in_tools, - tool, -) +from anycode import Agent, ToolUseContext, as_tool_definition, tool load_dotenv() - -def _resolve_provider() -> tuple[str, str]: - """Return (provider, model) based on available API keys.""" - if os.environ.get("ANTHROPIC_API_KEY"): - return "anthropic", "claude-haiku-4-5" - if os.environ.get("OPENAI_API_KEY"): - return "openai", "gpt-4o-mini" - print("ERROR: Set ANTHROPIC_API_KEY or OPENAI_API_KEY in .env") - sys.exit(1) - - -PROVIDER, MODEL = _resolve_provider() - # --- A plain synchronous function becomes a tool --- @@ -83,34 +60,21 @@ async def main() -> None: # Decorated functions stay ordinary callables. print("\nDirect call:", convert_currency(100.0, 0.92)) - registry = ToolRegistry() - register_built_in_tools(registry) - for fn in (convert_currency, days_since, whoami): - registry.register(as_tool_definition(fn)) - executor = ToolExecutor(registry) - - # Tools are runnable standalone through the executor. - context = ToolUseContext(agent=AgentInfo(name="demo", role="demo", model=MODEL)) - direct = await executor.execute("business_days", {"iso_date": "2026-01-01"}, context) - print("Executor call:", direct.data) - analyst = Agent( - config={ - "name": "analyst", - "model": MODEL, - "provider": PROVIDER, - "system_prompt": ( - "You are a precise financial assistant. Use the provided tools for every " - "calculation — never do the arithmetic yourself. Answer in one short sentence." - ), - "tools": ["convert_currency", "business_days", "whoami"], - "max_turns": 5, - "temperature": 0, - }, - tool_registry=registry, - tool_executor=executor, + name="analyst", + instructions=( + "You are a precise financial assistant. Use the provided tools for every " + "calculation — never do the arithmetic yourself. Answer in one short sentence." + ), + tools=[convert_currency, days_since, whoami], + max_turns=5, + temperature=0, ) + # Tools are runnable through the agent without involving the LLM at all. + direct = await analyst.call_tool("business_days", iso_date="2026-01-01") + print("Direct tool call:", direct.data) + print("\nLive agent run\n" + "=" * 55) result = await analyst.run("Convert 250 units at a rate of 0.92 into EUR, then tell me who you are. Use the tools.") diff --git a/src/anycode/__init__.py b/src/anycode/__init__.py index 52a799f..6585264 100644 --- a/src/anycode/__init__.py +++ b/src/anycode/__init__.py @@ -85,7 +85,7 @@ VerificationResult as SemanticVerificationResult, ) from anycode.core import stop_reason as stop_reasons -from anycode.core.agent import Agent +from anycode.core.agent import Agent, AgentConfigError, compose_instructions from anycode.core.context_artifacts import offload_text, restore_text from anycode.core.context_manager import ContextManager, estimate_messages_tokens, rebuild_from_handoff from anycode.core.lifecycle import ( @@ -224,10 +224,12 @@ from anycode.tools.executor import ToolExecutor from anycode.tools.function_tool import ( ToolDefinitionError, + ToolSpec, as_tool_definition, build_tool_definition, builtin_tool_names, function_tool, + resolve_tool_specs, tool, ) from anycode.tools.idempotency import ( @@ -417,6 +419,8 @@ # Core "AnyCode", "Agent", + "AgentConfigError", + "compose_instructions", "AgentRunner", "AgentPool", "Scheduler", @@ -650,7 +654,9 @@ "as_tool_definition", "build_tool_definition", "builtin_tool_names", + "resolve_tool_specs", "ToolDefinitionError", + "ToolSpec", "IdempotencyClaim", "InMemoryToolIdempotencyStore", "SQLiteToolIdempotencyStore", diff --git a/src/anycode/core/agent.py b/src/anycode/core/agent.py index 469e925..b66862e 100644 --- a/src/anycode/core/agent.py +++ b/src/anycode/core/agent.py @@ -3,58 +3,268 @@ from __future__ import annotations import asyncio -from collections.abc import AsyncGenerator +from collections.abc import AsyncGenerator, Iterator, Sequence from pydantic import BaseModel from anycode.constants import AGENT_ROLE_MAX_LENGTH, TOOL_CONTEXT_ROLE_MAX_LENGTH +from anycode.core.defaults import default_model, detect_provider, missing_model_message, missing_provider_message from anycode.core.runner import AgentRunner +from anycode.helpers.sync_runner import iterate_async_blocking, run_coroutine_blocking from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage +from anycode.identity import ExecutionContext from anycode.providers.adapter import create_adapter from anycode.security.redaction import safe_exception_message from anycode.structured.output import parse_structured_output from anycode.telemetry.tracer import Tracer +from anycode.tools.built_in import register_built_in_tools from anycode.tools.executor import ToolExecutor +from anycode.tools.function_tool import ToolSpec, resolve_tool_specs from anycode.tools.registry import ToolRegistry from anycode.types import ( AgentConfig, AgentInfo, AgentRunResult, AgentState, + ContextPolicy, GuardrailConfig, LLMMessage, OutputValidator, + ProviderResilienceConfig, RunnerOptions, RunResult, StreamEvent, StructuredAgentResult, TextBlock, ToolDefinition, + ToolResult, + ToolSecurityPolicy, ToolUseContext, TurnHook, + VerificationSensorConfig, ) +# Keyword arguments that describe the agent itself; supplying any of them alongside an +# explicit config object would silently create two sources of truth. +_CONFIG_KEYWORDS = ( + "name", + "model", + "provider", + "instructions", + "system_prompt", + "role", + "goal", + "backstory", + "max_turns", + "max_tokens", + "temperature", + "mcp_servers", + "context_policy", + "verification", + "tool_security", + "provider_resilience", + "execution_context", +) + + +class AgentConfigError(ValueError): + """Raised when agent construction arguments are contradictory or incomplete.""" + + +def compose_instructions(role: str | None = None, goal: str | None = None, backstory: str | None = None) -> str: + """Build a system prompt from role/goal/backstory framing. Empty parts are omitted.""" + parts: list[str] = [] + if role: + parts.append(f"You are {role.strip().rstrip('.')}.") + if goal: + parts.append(f"Your goal: {goal.strip()}") + if backstory: + parts.append(f"Background: {backstory.strip()}") + return "\n\n".join(parts) + + +def _resolve_system_prompt( + *, + instructions: str | None, + system_prompt: str | None, + role: str | None, + goal: str | None, + backstory: str | None, +) -> str | None: + if instructions and system_prompt and instructions != system_prompt: + raise AgentConfigError("Agent received different values for instructions= and system_prompt=. They are aliases — pass only one.") + direct = instructions or system_prompt + framing = compose_instructions(role, goal, backstory) + if direct and framing: + raise AgentConfigError( + "Agent received both instructions= and role/goal/backstory framing. " + "Pick one: instructions= for a literal prompt, or role/goal/backstory to have one composed." + ) + return direct or framing or None + + +def _build_agent_config( + *, + name: str, + model: str | None, + provider: str | None, + system_prompt: str | None, + max_turns: int | None, + max_tokens: int | None, + temperature: float | None, + mcp_servers: list[str] | None, + context_policy: ContextPolicy | None, + verification: tuple[VerificationSensorConfig, ...], + tool_security: ToolSecurityPolicy | None, + provider_resilience: ProviderResilienceConfig | None, + execution_context: ExecutionContext | None, +) -> AgentConfig: + resolved_provider = provider or detect_provider() + if resolved_provider is None: + raise AgentConfigError(f'Agent "{name}": {missing_provider_message()}') + resolved_model = model or default_model(resolved_provider) + if resolved_model is None: + raise AgentConfigError(f'Agent "{name}": {missing_model_message(resolved_provider)}') + + return AgentConfig( + name=name, + model=resolved_model, + provider=resolved_provider, + system_prompt=system_prompt, + max_turns=max_turns, + max_tokens=max_tokens, + temperature=temperature, + mcp_servers=mcp_servers, + context_policy=context_policy, + verification=verification, + tool_security=tool_security, + provider_resilience=provider_resilience, + execution_context=execution_context, + ) + + +def _wire_tools( + config: AgentConfig, + tools: Sequence[ToolSpec] | None, + registry: ToolRegistry | None, + executor: ToolExecutor | None, +) -> tuple[AgentConfig, ToolRegistry, ToolExecutor]: + """Build the registry/executor pair an agent needs when the caller did not supply one.""" + if registry is None: + registry = ToolRegistry() + if tools is None: + register_built_in_tools(registry) + else: + resolved = resolve_tool_specs(tools) + added = {definition.name for definition in resolved} + # Names already allowed by the config stay allowed; the explicit list extends them. + carried = resolve_tool_specs(name for name in (config.tools or []) if name not in added) + for definition in (*carried, *resolved): + registry.register(definition) + config = config.model_copy(update={"tools": [definition.name for definition in (*carried, *resolved)]}) + elif tools is not None: + resolved = resolve_tool_specs(tools) + for definition in resolved: + if not registry.has(definition.name): + registry.register(definition) + allowed = [*(config.tools or []), *(definition.name for definition in resolved)] + config = config.model_copy(update={"tools": list(dict.fromkeys(allowed))}) + + return config, registry, executor or ToolExecutor(registry) + class Agent: """High-level agent with state management, conversation history, and streaming support.""" def __init__( self, - config: AgentConfig | dict[str, object], - tool_registry: ToolRegistry, - tool_executor: ToolExecutor, + config: AgentConfig | dict[str, object] | None = None, + tool_registry: ToolRegistry | None = None, + tool_executor: ToolExecutor | None = None, *, + name: str | None = None, + model: str | None = None, + provider: str | None = None, + instructions: str | None = None, + system_prompt: str | None = None, + role: str | None = None, + goal: str | None = None, + backstory: str | None = None, + tools: Sequence[ToolSpec] | None = None, + max_turns: int | None = None, + max_tokens: int | None = None, + temperature: float | None = None, + mcp_servers: list[str] | None = None, + context_policy: ContextPolicy | None = None, + verification: tuple[VerificationSensorConfig, ...] = (), + tool_security: ToolSecurityPolicy | None = None, + provider_resilience: ProviderResilienceConfig | None = None, + execution_context: ExecutionContext | None = None, tracer: Tracer | None = None, guardrail_config: GuardrailConfig | None = None, hooks: list[TurnHook] | None = None, output_validators: list[OutputValidator] | None = None, output_schema: type[BaseModel] | None = None, ) -> None: - typed_config = AgentConfig.model_validate(config) if isinstance(config, dict) else config + supplied = { + "name": name, + "model": model, + "provider": provider, + "instructions": instructions, + "system_prompt": system_prompt, + "role": role, + "goal": goal, + "backstory": backstory, + "max_turns": max_turns, + "max_tokens": max_tokens, + "temperature": temperature, + "mcp_servers": mcp_servers, + "context_policy": context_policy, + "verification": verification or None, + "tool_security": tool_security, + "provider_resilience": provider_resilience, + "execution_context": execution_context, + } + + if config is not None: + conflicting = [keyword for keyword in _CONFIG_KEYWORDS if supplied.get(keyword) is not None] + if conflicting: + raise AgentConfigError( + f"Agent received both a config object and {', '.join(conflicting)}=. " + "Put every field in the config, or drop the config and pass keywords only." + ) + typed_config = AgentConfig.model_validate(config) if isinstance(config, dict) else config + else: + if not name: + raise AgentConfigError('Agent needs a name. Pass Agent(name="researcher", ...) or an AgentConfig as the first argument.') + typed_config = _build_agent_config( + name=name, + model=model, + provider=provider, + system_prompt=_resolve_system_prompt( + instructions=instructions, + system_prompt=system_prompt, + role=role, + goal=goal, + backstory=backstory, + ), + max_turns=max_turns, + max_tokens=max_tokens, + temperature=temperature, + mcp_servers=mcp_servers, + context_policy=context_policy, + verification=verification, + tool_security=tool_security, + provider_resilience=provider_resilience, + execution_context=execution_context, + ) + + typed_config, resolved_registry, resolved_executor = _wire_tools(typed_config, tools, tool_registry, tool_executor) + self.name = typed_config.name self.config = typed_config - self._registry = tool_registry - self._executor = tool_executor + self._registry = resolved_registry + self._executor = resolved_executor self._runner: AgentRunner | None = None self._state = AgentState() self._history: list[LLMMessage] = [] @@ -141,6 +351,46 @@ async def stream(self, prompt: str) -> AsyncGenerator[StreamEvent, None]: async for event in self._execute_stream(messages): yield event + def run_sync(self, prompt: str) -> AgentRunResult: + """Blocking form of :meth:`run` for scripts and notebooks.""" + return run_coroutine_blocking(self.run(prompt), sync_call="Agent.run_sync()", async_call="await agent.run(...)") + + def prompt_sync(self, message: str) -> AgentRunResult: + """Blocking form of :meth:`prompt`.""" + return run_coroutine_blocking(self.prompt(message), sync_call="Agent.prompt_sync()", async_call="await agent.prompt(...)") + + def stream_sync(self, prompt: str) -> Iterator[StreamEvent]: + """Blocking form of :meth:`stream`, yielding events as they arrive.""" + return iterate_async_blocking( + lambda: self.stream(prompt), + sync_call="Agent.stream_sync()", + async_call="async for event in agent.stream(...)", + ) + + async def call_tool(self, name: str, **arguments: object) -> ToolResult: + """Invoke one of this agent's tools directly, bypassing the LLM. + + Useful for testing a tool under the same validation, security policy, and + idempotency rules the agent would apply. + """ + return await self._executor.execute(name, dict(arguments), self.build_tool_context()) + + def call_tool_sync(self, name: str, **arguments: object) -> ToolResult: + """Blocking form of :meth:`call_tool`.""" + return run_coroutine_blocking( + self.call_tool(name, **arguments), + sync_call="Agent.call_tool_sync()", + async_call="await agent.call_tool(...)", + ) + + @property + def tools(self) -> list[ToolDefinition]: + """Tool definitions currently registered for this agent.""" + return self._registry.list() + + def __repr__(self) -> str: + return f"Agent(name={self.name!r}, model={self.config.model!r}, provider={self.config.provider!r}, tools={len(self._registry.list())})" + def get_state(self) -> AgentState: return self._state.model_copy(deep=True) diff --git a/src/anycode/core/defaults.py b/src/anycode/core/defaults.py new file mode 100644 index 0000000..63ff555 --- /dev/null +++ b/src/anycode/core/defaults.py @@ -0,0 +1,79 @@ +"""Provider and model defaults resolved from the environment. + +Keyword-constructed agents infer their provider from whichever credentials are present, +so a script does not have to repeat the same key-detection block every time. +""" + +from __future__ import annotations + +import os +from collections.abc import Mapping + +from anycode.constants import ( + PROVIDER_ANTHROPIC, + PROVIDER_AZURE, + PROVIDER_BEDROCK, + PROVIDER_GOOGLE, + PROVIDER_OLLAMA, + PROVIDER_OPENAI, +) + +DEFAULT_MODEL_ENV_VAR = "ANYCODE_DEFAULT_MODEL" +DEFAULT_PROVIDER_ENV_VAR = "ANYCODE_DEFAULT_PROVIDER" +OLLAMA_MODEL_ENV_VAR = "OLLAMA_MODEL" + +# Detection order — first provider with a populated credential wins. +PROVIDER_CREDENTIAL_ENV_VARS: tuple[tuple[str, tuple[str, ...]], ...] = ( + (PROVIDER_ANTHROPIC, ("ANTHROPIC_API_KEY",)), + (PROVIDER_OPENAI, ("OPENAI_API_KEY",)), + (PROVIDER_GOOGLE, ("GOOGLE_API_KEY", "GEMINI_API_KEY")), + (PROVIDER_AZURE, ("AZURE_OPENAI_API_KEY",)), + (PROVIDER_BEDROCK, ("AWS_DEFAULT_REGION",)), + (PROVIDER_OLLAMA, ("OLLAMA_BASE_URL", "OLLAMA_API_KEY")), +) + +DEFAULT_MODELS: dict[str, str] = { + PROVIDER_ANTHROPIC: "claude-haiku-4-5", + PROVIDER_OPENAI: "gpt-4o-mini", + PROVIDER_GOOGLE: "gemini-2.0-flash", + PROVIDER_AZURE: "gpt-4o-mini", + PROVIDER_BEDROCK: "anthropic.claude-3-5-haiku-20241022-v1:0", +} + + +def detect_provider(env: Mapping[str, str] | None = None) -> str | None: + """Return the provider implied by the environment, or ``None`` when nothing is set.""" + source = env if env is not None else os.environ + explicit = source.get(DEFAULT_PROVIDER_ENV_VAR, "").strip() + if explicit: + return explicit + for provider, variables in PROVIDER_CREDENTIAL_ENV_VARS: + if any(source.get(variable, "").strip() for variable in variables): + return provider + return None + + +def default_model(provider: str, env: Mapping[str, str] | None = None) -> str | None: + """Return the default model for *provider*, honoring environment overrides.""" + source = env if env is not None else os.environ + override = source.get(DEFAULT_MODEL_ENV_VAR, "").strip() + if override: + return override + if provider == PROVIDER_OLLAMA: + return source.get(OLLAMA_MODEL_ENV_VAR, "").strip() or None + return DEFAULT_MODELS.get(provider) + + +def missing_provider_message() -> str: + """Explain which environment variables enable provider auto-detection.""" + variables = ", ".join(variables[0] for _, variables in PROVIDER_CREDENTIAL_ENV_VARS) + return ( + "no LLM provider could be detected from the environment. " + f"Set one of {variables} (a .env file is loaded by python-dotenv), " + 'or pass provider="..." explicitly.' + ) + + +def missing_model_message(provider: str) -> str: + """Explain how to supply a model for a provider that has no built-in default.""" + return f'no default model is known for provider "{provider}". Pass model="..." or set {DEFAULT_MODEL_ENV_VAR} in the environment.' diff --git a/src/anycode/helpers/sync_runner.py b/src/anycode/helpers/sync_runner.py new file mode 100644 index 0000000..7ca3a1f --- /dev/null +++ b/src/anycode/helpers/sync_runner.py @@ -0,0 +1,80 @@ +"""Blocking wrappers around the async runtime for scripts and notebooks.""" + +from __future__ import annotations + +import asyncio +import threading +from collections.abc import AsyncGenerator, Callable, Coroutine, Iterator +from queue import SimpleQueue + +_ITEM = "item" +_ERROR = "error" +_DONE = "done" + + +def _reject_active_loop(sync_call: str, async_call: str) -> None: + try: + asyncio.get_running_loop() + except RuntimeError: + return + raise RuntimeError(f"{sync_call} cannot be called while an event loop is running. Use `{async_call}` instead.") + + +def run_coroutine_blocking[T](coro: Coroutine[object, object, T], *, sync_call: str, async_call: str) -> T: + """Run *coro* to completion on a fresh event loop. + + Raises ``RuntimeError`` when a loop is already running, because nesting event loops + silently deadlocks; the message names the async call to use instead. + """ + try: + _reject_active_loop(sync_call, async_call) + except RuntimeError: + coro.close() + raise + return asyncio.run(coro) + + +def iterate_async_blocking[T]( + factory: Callable[[], AsyncGenerator[T, None]], + *, + sync_call: str, + async_call: str, +) -> Iterator[T]: + """Drain an async generator from synchronous code, yielding items as they arrive. + + The generator runs on its own event loop in a worker thread, so items surface + incrementally rather than only after the stream completes. + """ + _reject_active_loop(sync_call, async_call) + + queue: SimpleQueue[tuple[str, object]] = SimpleQueue() + stop = threading.Event() + + async def _pump() -> None: + try: + async for item in factory(): + queue.put((_ITEM, item)) + if stop.is_set(): + break + except BaseException as error: # surfaced to the consuming thread verbatim + queue.put((_ERROR, error)) + finally: + queue.put((_DONE, None)) + + worker = threading.Thread(target=lambda: asyncio.run(_pump()), name="anycode-sync-stream", daemon=True) + worker.start() + + def _consume() -> Iterator[T]: + try: + while True: + kind, payload = queue.get() + if kind == _DONE: + return + if kind == _ERROR: + raise payload # type: ignore[misc] + yield payload # type: ignore[misc] + finally: + stop.set() + worker.join() + + return _consume() diff --git a/src/anycode/tools/__init__.py b/src/anycode/tools/__init__.py index 702798a..9633ee0 100644 --- a/src/anycode/tools/__init__.py +++ b/src/anycode/tools/__init__.py @@ -6,10 +6,12 @@ from anycode.tools.file_write import file_write_tool from anycode.tools.function_tool import ( ToolDefinitionError, + ToolSpec, as_tool_definition, build_tool_definition, builtin_tool_names, function_tool, + resolve_tool_specs, tool, ) from anycode.tools.grep import grep_tool @@ -30,7 +32,9 @@ "as_tool_definition", "build_tool_definition", "builtin_tool_names", + "resolve_tool_specs", "ToolDefinitionError", + "ToolSpec", "define_tool", "register_built_in_tools", "BUILT_IN_TOOLS", diff --git a/src/anycode/tools/function_tool.py b/src/anycode/tools/function_tool.py index 4693b3e..9e2175e 100644 --- a/src/anycode/tools/function_tool.py +++ b/src/anycode/tools/function_tool.py @@ -11,7 +11,7 @@ import inspect import json import re -from collections.abc import Callable +from collections.abc import Callable, Iterable from typing import Any, overload from pydantic import BaseModel, create_model @@ -36,6 +36,10 @@ _ARGUMENT_LINE = re.compile(r"^(?P[A-Za-z_]\w*)\s*(?:\((?P[^)]*)\))?\s*:\s*(?P.*)$") +ToolSpec = ToolDefinition | Callable[..., Any] | str +"""Every form accepted wherever AnyCode takes a tool.""" + + class ToolDefinitionError(ValueError): """Raised when a function cannot be turned into a usable tool.""" @@ -318,6 +322,19 @@ def builtin_tool_names() -> tuple[str, ...]: return tuple(sorted(_named_tools())) +def resolve_tool_specs(specs: Iterable[object]) -> list[ToolDefinition]: + """Normalize a sequence of tool specifications, rejecting duplicate names.""" + resolved: list[ToolDefinition] = [] + seen: set[str] = set() + for spec in specs: + definition = as_tool_definition(spec) + if definition.name in seen: + raise ToolDefinitionError(f'Duplicate tool name "{definition.name}" in the tool list. Every tool needs a unique name.') + seen.add(definition.name) + resolved.append(definition) + return resolved + + def as_tool_definition(spec: object) -> ToolDefinition: """Normalize a tool specification into a :class:`ToolDefinition`. diff --git a/tests/test_agent_ergonomics.py b/tests/test_agent_ergonomics.py new file mode 100644 index 0000000..0d35d31 --- /dev/null +++ b/tests/test_agent_ergonomics.py @@ -0,0 +1,354 @@ +"""Tests for keyword-constructed agents, provider defaults, and blocking entry points.""" + +from __future__ import annotations + +import asyncio + +import pytest + +from anycode import ( + Agent, + AgentConfig, + AgentConfigError, + ToolDefinitionError, + ToolExecutor, + ToolRegistry, + compose_instructions, + register_built_in_tools, + tool, +) +from anycode.core.defaults import DEFAULT_MODEL_ENV_VAR, DEFAULT_PROVIDER_ENV_VAR, default_model, detect_provider +from anycode.providers.fake import FakeAdapter, FakeResponse + +PROVIDER_ENV_VARS = ( + "ANTHROPIC_API_KEY", + "OPENAI_API_KEY", + "GOOGLE_API_KEY", + "GEMINI_API_KEY", + "AZURE_OPENAI_API_KEY", + "AWS_DEFAULT_REGION", + "OLLAMA_BASE_URL", + "OLLAMA_API_KEY", + "OLLAMA_MODEL", + DEFAULT_MODEL_ENV_VAR, + DEFAULT_PROVIDER_ENV_VAR, +) + + +@pytest.fixture +def clean_provider_env(monkeypatch: pytest.MonkeyPatch) -> None: + for variable in PROVIDER_ENV_VARS: + monkeypatch.delenv(variable, raising=False) + + +@tool +def echo(text: str) -> str: + """Echo the given text.""" + return text + + +# --------------------------------------------------------------------------- +# Keyword construction +# --------------------------------------------------------------------------- + + +def test_keyword_construction_builds_config(clean_provider_env: None) -> None: + agent = Agent( + name="researcher", + model="gpt-4o-mini", + provider="openai", + instructions="Find primary sources.", + max_turns=8, + temperature=0.2, + ) + assert agent.name == "researcher" + assert agent.config.model == "gpt-4o-mini" + assert agent.config.provider == "openai" + assert agent.config.system_prompt == "Find primary sources." + assert agent.config.max_turns == 8 + assert agent.config.temperature == 0.2 + + +def test_keyword_construction_wires_built_in_tools(clean_provider_env: None) -> None: + agent = Agent(name="worker", model="m", provider="openai") + assert {"bash", "file_read", "file_write"} <= {definition.name for definition in agent.tools} + assert agent.config.tools is None + + +def test_system_prompt_is_an_alias_for_instructions(clean_provider_env: None) -> None: + agent = Agent(name="a", model="m", provider="openai", system_prompt="Be terse.") + assert agent.config.system_prompt == "Be terse." + + +def test_missing_name_is_rejected(clean_provider_env: None) -> None: + with pytest.raises(AgentConfigError, match="needs a name"): + Agent(model="m", provider="openai") + + +# --------------------------------------------------------------------------- +# Legacy construction stays intact +# --------------------------------------------------------------------------- + + +def test_positional_construction_is_unchanged() -> None: + config = AgentConfig(name="legacy", model="m", provider="openai") + registry = ToolRegistry() + register_built_in_tools(registry) + executor = ToolExecutor(registry) + + agent = Agent(config, registry, executor) + assert agent.config is config + assert agent._registry is registry + assert agent._executor is executor + + +def test_config_object_with_auto_wiring() -> None: + config = AgentConfig(name="halfway", model="m", provider="openai") + agent = Agent(config) + assert {definition.name for definition in agent.tools} + assert isinstance(agent._executor, ToolExecutor) + + +def test_config_plus_field_keyword_is_rejected() -> None: + config = AgentConfig(name="x", model="m", provider="openai") + with pytest.raises(AgentConfigError, match="both a config object and name="): + Agent(config, name="y") + + +def test_config_plus_tools_is_allowed() -> None: + config = AgentConfig(name="x", model="m", provider="openai", tools=["bash"]) + agent = Agent(config, tools=[echo]) + assert agent.config.tools == ["bash", "echo"] + assert "echo" in {definition.name for definition in agent.tools} + + +# --------------------------------------------------------------------------- +# Role / goal / backstory framing +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + ("role", "goal", "backstory", "expected"), + [ + ("a Senior Analyst", None, None, "You are a Senior Analyst."), + (None, "ship the report", None, "Your goal: ship the report"), + (None, None, "15 years auditing", "Background: 15 years auditing"), + ("an Editor", "tighten prose", None, "You are an Editor.\n\nYour goal: tighten prose"), + ("an Editor", None, "ex-journalist", "You are an Editor.\n\nBackground: ex-journalist"), + (None, "tighten prose", "ex-journalist", "Your goal: tighten prose\n\nBackground: ex-journalist"), + ( + "an Editor", + "tighten prose", + "ex-journalist", + "You are an Editor.\n\nYour goal: tighten prose\n\nBackground: ex-journalist", + ), + ], +) +def test_compose_instructions_covers_every_subset(role: str | None, goal: str | None, backstory: str | None, expected: str) -> None: + assert compose_instructions(role, goal, backstory) == expected + + +def test_compose_instructions_strips_trailing_period_from_role() -> None: + assert compose_instructions(role="a Senior Analyst.") == "You are a Senior Analyst." + + +def test_role_framing_reaches_the_config(clean_provider_env: None) -> None: + agent = Agent(name="analyst", model="m", provider="openai", role="a Senior Analyst", goal="value the firm") + assert agent.config.system_prompt == "You are a Senior Analyst.\n\nYour goal: value the firm" + + +def test_instructions_and_role_together_are_rejected(clean_provider_env: None) -> None: + with pytest.raises(AgentConfigError, match="Pick one"): + Agent(name="a", model="m", provider="openai", instructions="Do it.", role="an Editor") + + +def test_conflicting_prompt_aliases_are_rejected(clean_provider_env: None) -> None: + with pytest.raises(AgentConfigError, match="aliases"): + Agent(name="a", model="m", provider="openai", instructions="one", system_prompt="two") + + +# --------------------------------------------------------------------------- +# Provider and model detection +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + ("variable", "expected_provider", "expected_model"), + [ + ("ANTHROPIC_API_KEY", "anthropic", "claude-haiku-4-5"), + ("OPENAI_API_KEY", "openai", "gpt-4o-mini"), + ("GOOGLE_API_KEY", "google", "gemini-2.0-flash"), + ("AZURE_OPENAI_API_KEY", "azure", "gpt-4o-mini"), + ], +) +def test_provider_detected_from_credentials( + clean_provider_env: None, + monkeypatch: pytest.MonkeyPatch, + variable: str, + expected_provider: str, + expected_model: str, +) -> None: + monkeypatch.setenv(variable, "value") + agent = Agent(name="auto") + assert agent.config.provider == expected_provider + assert agent.config.model == expected_model + + +def test_detection_prefers_anthropic_over_openai(clean_provider_env: None, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("OPENAI_API_KEY", "b") + monkeypatch.setenv("ANTHROPIC_API_KEY", "a") + assert detect_provider() == "anthropic" + + +def test_explicit_provider_env_var_wins(clean_provider_env: None, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("OPENAI_API_KEY", "b") + monkeypatch.setenv(DEFAULT_PROVIDER_ENV_VAR, "google") + assert detect_provider() == "google" + + +def test_default_model_env_var_overrides(clean_provider_env: None, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("OPENAI_API_KEY", "b") + monkeypatch.setenv(DEFAULT_MODEL_ENV_VAR, "gpt-5-mini") + assert Agent(name="auto").config.model == "gpt-5-mini" + + +def test_ollama_model_comes_from_its_own_env_var(clean_provider_env: None, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("OLLAMA_BASE_URL", "http://localhost:11434") + monkeypatch.setenv("OLLAMA_MODEL", "qwen3:8b") + assert default_model("ollama") == "qwen3:8b" + + +def test_no_credentials_produces_an_actionable_error(clean_provider_env: None) -> None: + with pytest.raises(AgentConfigError, match="ANTHROPIC_API_KEY"): + Agent(name="auto") + + +def test_unknown_provider_without_default_model_is_rejected(clean_provider_env: None) -> None: + with pytest.raises(AgentConfigError, match="no default model is known"): + Agent(name="auto", provider="ollama") + + +# --------------------------------------------------------------------------- +# Tool wiring +# --------------------------------------------------------------------------- + + +def test_tools_accepts_mixed_specifications(clean_provider_env: None) -> None: + definition = ToolRegistry() + register_built_in_tools(definition) + grep = definition.get("grep") + assert grep is not None + + agent = Agent(name="mixed", model="m", provider="openai", tools=[echo, "bash", grep]) + assert agent.config.tools == ["echo", "bash", "grep"] + assert {tool_def.name for tool_def in agent.tools} == {"echo", "bash", "grep"} + + +def test_empty_tool_list_means_no_tools(clean_provider_env: None) -> None: + agent = Agent(name="toolless", model="m", provider="openai", tools=[]) + assert agent.config.tools == [] + assert agent.tools == [] + + +def test_duplicate_tool_names_are_rejected(clean_provider_env: None) -> None: + with pytest.raises(ToolDefinitionError, match="Duplicate tool name"): + Agent(name="dupes", model="m", provider="openai", tools=[echo, echo]) + + +def test_unknown_tool_name_lists_alternatives(clean_provider_env: None) -> None: + with pytest.raises(ToolDefinitionError, match="Available: bash"): + Agent(name="typo", model="m", provider="openai", tools=["file_reed"]) + + +async def test_call_tool_runs_without_the_llm(clean_provider_env: None) -> None: + agent = Agent(name="direct", model="m", provider="openai", tools=[echo]) + result = await agent.call_tool("echo", text="ping") + assert result.data == "ping" + assert not result.is_error + + +def test_call_tool_sync_runs_without_the_llm(clean_provider_env: None) -> None: + agent = Agent(name="direct", model="m", provider="openai", tools=[echo]) + assert agent.call_tool_sync("echo", text="pong").data == "pong" + + +async def test_call_tool_reports_unregistered_names(clean_provider_env: None) -> None: + agent = Agent(name="direct", model="m", provider="openai", tools=[echo]) + result = await agent.call_tool("nope") + assert result.is_error + assert "not registered" in result.data + + +def test_repr_reports_identity_and_tool_count(clean_provider_env: None) -> None: + agent = Agent(name="shown", model="m", provider="openai", tools=[echo]) + assert repr(agent) == "Agent(name='shown', model='m', provider='openai', tools=1)" + + +# --------------------------------------------------------------------------- +# Blocking entry points +# --------------------------------------------------------------------------- + + +def _fake_agent(monkeypatch: pytest.MonkeyPatch, text: str = "done") -> Agent: + agent = Agent(name="sync", model="m", provider="openai", tools=[]) + + async def _adapter(*_args: object, **_kwargs: object) -> FakeAdapter: + return FakeAdapter(responses=[FakeResponse(text=text)]) + + monkeypatch.setattr("anycode.core.agent.create_adapter", _adapter) + return agent + + +def test_run_sync_returns_a_result(clean_provider_env: None, monkeypatch: pytest.MonkeyPatch) -> None: + agent = _fake_agent(monkeypatch, "hello from sync") + result = agent.run_sync("hi") + assert result.success + assert result.output == "hello from sync" + + +def test_prompt_sync_keeps_history(clean_provider_env: None, monkeypatch: pytest.MonkeyPatch) -> None: + agent = _fake_agent(monkeypatch, "reply") + agent.prompt_sync("first") + assert len(agent.get_history()) >= 2 + + +def test_stream_sync_yields_events(clean_provider_env: None, monkeypatch: pytest.MonkeyPatch) -> None: + agent = _fake_agent(monkeypatch, "streamed") + events = list(agent.stream_sync("hi")) + assert [event.type for event in events][-1] == "done" + assert "".join(str(event.data) for event in events if event.type == "text") == "streamed" + + +async def test_run_sync_inside_a_loop_is_rejected(clean_provider_env: None, monkeypatch: pytest.MonkeyPatch) -> None: + agent = _fake_agent(monkeypatch) + with pytest.raises(RuntimeError, match="await agent.run"): + agent.run_sync("hi") + + +async def test_stream_sync_inside_a_loop_is_rejected(clean_provider_env: None, monkeypatch: pytest.MonkeyPatch) -> None: + agent = _fake_agent(monkeypatch) + with pytest.raises(RuntimeError, match="async for event in agent.stream"): + list(agent.stream_sync("hi")) + + +def test_sync_runner_propagates_exceptions(clean_provider_env: None) -> None: + from anycode.helpers.sync_runner import run_coroutine_blocking + + async def _boom() -> None: + raise ValueError("kaboom") + + with pytest.raises(ValueError, match="kaboom"): + run_coroutine_blocking(_boom(), sync_call="x()", async_call="await x()") + + +def test_sync_runner_does_not_leave_pending_coroutines(clean_provider_env: None) -> None: + from anycode.helpers.sync_runner import run_coroutine_blocking + + async def _never() -> None: # pragma: no cover - never awaited + await asyncio.sleep(0) + + async def _inside() -> None: + with pytest.raises(RuntimeError): + run_coroutine_blocking(_never(), sync_call="x()", async_call="await x()") + + asyncio.run(_inside()) From bda4c20a5ea498185a1e18cdf51bd5c505da983a Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 05:57:53 +0500 Subject: [PATCH 03/11] feat(crew): add Crew facade over the wavefront scheduler Crew is a one-import multi-agent entry point: it owns an AnyCode engine and a Team, and contributes no scheduling logic of its own. crew = Crew(agents=[researcher, writer], tasks=[...]) result = crew.run_sync() Tasks accept a TaskSpec, a dict of TaskSpec arguments, or a bare string title. process="sequential" chains tasks that declare no dependency of their own; process="dependency" (the default) honors declared edges only. With no tasks at all, run(goal) falls through to the existing coordinator decomposition. Unknown orchestrator options are rejected with the valid list rather than a Pydantic traceback. TaskSpec gains agent=, expected_output=, and context=, and its description defaults to the title. Task carries expected_output through the queue and checkpoints so it reaches the agent prompt as an explicit "Expected output:" line. AnyCode.register_agent adopts a pre-built Agent, so a crew member keeps the tool registry it was constructed with instead of being rebuilt from its config. CrewResult exposes success/output/outputs/usage/cost and keeps the full TeamRunResult attached; str(result) is the final task's output. --- examples/46_crew_quickstart.py | 93 ++++++++++++ src/anycode/__init__.py | 4 + src/anycode/core/orchestrator.py | 53 ++++++- src/anycode/crew.py | 245 +++++++++++++++++++++++++++++++ src/anycode/tasks/task.py | 10 +- src/anycode/types.py | 1 + tests/test_crew.py | 229 +++++++++++++++++++++++++++++ 7 files changed, 628 insertions(+), 7 deletions(-) create mode 100644 examples/46_crew_quickstart.py create mode 100644 src/anycode/crew.py create mode 100644 tests/test_crew.py diff --git a/examples/46_crew_quickstart.py b/examples/46_crew_quickstart.py new file mode 100644 index 0000000..9a8b0d9 --- /dev/null +++ b/examples/46_crew_quickstart.py @@ -0,0 +1,93 @@ +# Demo 46 — Crew Quickstart +# Execute: uv run python examples/46_crew_quickstart.py +# Requires: ANTHROPIC_API_KEY or OPENAI_API_KEY in the environment or .env. + +import asyncio + +from dotenv import load_dotenv + +from anycode import Agent, Crew, TaskSpec, tool + +load_dotenv() + + +@tool +def price_lookup(ticker: str) -> dict: + """Look up a (stubbed) closing price for a ticker symbol. + + Args: + ticker: Upper-case ticker symbol, e.g. "ACME". + """ + prices = {"ACME": 128.40, "GLOBEX": 71.15, "INITECH": 42.00} + return {"ticker": ticker, "close": prices.get(ticker.upper(), 0.0)} + + +analyst = Agent( + name="analyst", + role="a market analyst", + goal="pull the closing prices and state the plain facts", + tools=[price_lookup], + max_turns=6, + temperature=0, +) + +writer = Agent( + name="writer", + role="a financial newsletter writer", + goal="turn raw figures into a short, readable note", + backstory="You write for busy readers who want the number and the takeaway, nothing else.", + tools=[], + max_turns=3, +) + + +def main() -> None: + # --- Declared tasks with an explicit dependency --- + + crew = Crew( + agents=[analyst, writer], + tasks=[ + TaskSpec( + "Collect prices", + "Look up the closing price for ACME, GLOBEX, and INITECH using the price_lookup tool.", + agent=analyst, + expected_output="One line per ticker: SYMBOL — closing price.", + ), + TaskSpec( + "Write the note", + "Write a three-sentence market note from the collected prices.", + agent=writer, + depends_on=["Collect prices"], + expected_output="Exactly three sentences, no bullet points.", + ), + ], + verbose=True, + ) + + print(f"{crew!r}\n") + result = crew.run_sync() + + print("\nFinal note") + print("=" * 55) + print(result) + print("=" * 55) + print(f"\nSucceeded: {result.success}") + print(f"Per-agent outputs: {sorted(result.outputs)}") + print(f"Tokens — input: {result.usage.input_tokens}, output: {result.usage.output_tokens}") + + +async def autonomous() -> None: + # --- No tasks declared: the first agent plans the work --- + + print("\n\nAutonomous mode — the crew decomposes the goal itself\n") + + async with Crew(agents=[analyst, writer], name="research-desk") as crew: + result = await crew.run("Report which of ACME, GLOBEX, or INITECH closed highest, and why that matters.") + + print(result.output.strip()[:600]) + print(f"\nSucceeded: {result.success}, tokens: {result.usage.input_tokens + result.usage.output_tokens}") + + +if __name__ == "__main__": + main() + asyncio.run(autonomous()) diff --git a/src/anycode/__init__.py b/src/anycode/__init__.py index 6585264..395cf47 100644 --- a/src/anycode/__init__.py +++ b/src/anycode/__init__.py @@ -110,6 +110,7 @@ calculate_cost, find_pricing, ) +from anycode.crew import Crew, CrewError, CrewResult from anycode.eval import ( compare_reports, detect_provider, @@ -419,6 +420,9 @@ # Core "AnyCode", "Agent", + "Crew", + "CrewError", + "CrewResult", "AgentConfigError", "compose_instructions", "AgentRunner", diff --git a/src/anycode/core/orchestrator.py b/src/anycode/core/orchestrator.py index d96385e..1ef1717 100644 --- a/src/anycode/core/orchestrator.py +++ b/src/anycode/core/orchestrator.py @@ -6,6 +6,7 @@ import hashlib import inspect import logging +from collections.abc import Sequence from typing import Any from pydantic import BaseModel @@ -82,11 +83,33 @@ class TaskSpec: - def __init__(self, title: str, description: str, assignee: str | None = None, depends_on: list[str] | None = None) -> None: + """A unit of work for a team: what to do, who does it, and what it depends on.""" + + def __init__( + self, + title: str, + description: str | None = None, + assignee: str | None = None, + depends_on: list[str] | None = None, + *, + agent: Agent | AgentConfig | str | None = None, + expected_output: str | None = None, + context: Sequence[str] | None = None, + ) -> None: self.title = title - self.description = description - self.assignee = assignee - self.depends_on = depends_on or [] + self.description = description if description is not None else title + self.assignee = assignee or _agent_name(agent) + self.depends_on = list(depends_on if depends_on is not None else (context or [])) + self.expected_output = expected_output + + def __repr__(self) -> str: + return f"TaskSpec(title={self.title!r}, assignee={self.assignee!r}, depends_on={self.depends_on!r})" + + +def _agent_name(agent: Agent | AgentConfig | str | None) -> str | None: + if agent is None or isinstance(agent, str): + return agent + return agent.name class AnyCode: @@ -349,6 +372,18 @@ def build_agent( output_schema=output_schema, ) + def register_agent(self, agent: Agent) -> Agent: + """Adopt a pre-built agent so teams and tasks reuse it instead of rebuilding it from config. + + Returns the agent now registered under that name — the existing one if the pool + already holds it, so repeated registration is safe. + """ + existing = self._pool.get(agent.name) + if existing is not None: + return existing + self._pool.add(agent) + return agent + def register_plugin(self, plugin: Plugin) -> PluginInstallation: """Install a plugin and return the resulting installation record.""" return self._plugin_registry.install(plugin) @@ -844,7 +879,12 @@ def _resolve_specs(self, specs: list[TaskSpec]) -> list[Task]: pending: list[tuple[Task, list[str]]] = [] for spec in specs: - task = create_task(title=spec.title, description=spec.description, assignee=spec.assignee) + task = create_task( + title=spec.title, + description=spec.description, + assignee=spec.assignee, + expected_output=getattr(spec, "expected_output", None), + ) title_map[spec.title] = task.id pending.append((task, spec.depends_on)) @@ -899,7 +939,8 @@ def _build_task_prompt(self, task: Task, queue: TaskQueue) -> str: dep_context_parts.append(f"[{dep_task.title}]: {dep_task.result[:DEPENDENCY_CONTEXT_MAX_LENGTH]}") context = "\n\nRelevant output from prerequisite tasks:\n" + "\n\n".join(dep_context_parts) if dep_context_parts else "" - return f"Task: {task.title}\n\n{task.description}{context}" + expected = f"\n\nExpected output: {task.expected_output}" if task.expected_output else "" + return f"Task: {task.title}\n\n{task.description}{expected}{context}" def _parse_task_specs(self, output: str, agents: list[AgentConfig]) -> list[TaskSpec]: lines = [ln for ln in output.split("\n") if ln.strip().upper().startswith("ASSIGN:")] diff --git a/src/anycode/crew.py b/src/anycode/crew.py new file mode 100644 index 0000000..4c0ce58 --- /dev/null +++ b/src/anycode/crew.py @@ -0,0 +1,245 @@ +"""Crew — a one-import multi-agent entry point over the wavefront scheduler. + +A crew owns an :class:`~anycode.core.orchestrator.AnyCode` engine and a +:class:`~anycode.collaboration.team.Team`; it contributes no scheduling logic of its own. +""" + +from __future__ import annotations + +from collections.abc import Sequence +from typing import Any, Literal + +from pydantic import BaseModel, ConfigDict + +from anycode.core.agent import Agent +from anycode.core.orchestrator import AnyCode, TaskSpec +from anycode.helpers.sync_runner import run_coroutine_blocking +from anycode.types import ( + AgentConfig, + CostReport, + OrchestratorConfig, + OrchestratorEvent, + TeamConfig, + TeamRunResult, + TokenUsage, +) + +AgentInput = Agent | AgentConfig | dict[str, object] +TaskInput = TaskSpec | dict[str, object] | str +Process = Literal["dependency", "sequential"] + + +class CrewError(ValueError): + """Raised when crew construction arguments are invalid.""" + + +class CrewResult(BaseModel): + """Ergonomic view over a :class:`TeamRunResult`, with the full result still attached.""" + + model_config = ConfigDict(frozen=True) + + success: bool + output: str + outputs: dict[str, str] + usage: TokenUsage + cost: CostReport | None = None + team_result: TeamRunResult + + def __str__(self) -> str: + return self.output + + +class Crew: + """A team of agents working through a list of tasks.""" + + def __init__( + self, + agents: Sequence[AgentInput], + tasks: Sequence[TaskInput] | None = None, + *, + name: str = "crew", + process: Process = "dependency", + max_concurrency: int | None = None, + shared_memory: bool = False, + verbose: bool = False, + engine: AnyCode | None = None, + **orchestrator_options: Any, + ) -> None: + if not agents: + raise CrewError("Crew needs at least one agent. Pass agents=[Agent(...), ...].") + if process not in ("dependency", "sequential"): + raise CrewError(f'Unknown process "{process}". Use "dependency" or "sequential".') + + self.name = name + self.process: Process = process + self._prebuilt = [agent for agent in agents if isinstance(agent, Agent)] + self._agent_configs = [_as_agent_config(agent) for agent in agents] + self._specs = _resolve_task_specs(tasks, self._agent_configs, process) + self._owns_engine = engine is None + self._engine = engine or AnyCode(_build_orchestrator_config(orchestrator_options, max_concurrency, verbose)) + + for agent in self._prebuilt: + self._engine.register_agent(agent) + + self._team = self._engine.create_team( + name, + TeamConfig( + name=name, + agents=self._agent_configs, + shared_memory=shared_memory or None, + max_concurrency=max_concurrency, + ), + ) + + @property + def engine(self) -> AnyCode: + """The underlying orchestrator, for durability, MCP, plugins, and everything else.""" + return self._engine + + @property + def team(self): # noqa: ANN201 - Team is re-exported; annotation would force an eager import + """The underlying team.""" + return self._team + + @property + def tasks(self) -> list[TaskSpec]: + return list(self._specs) + + async def run(self, goal: str | None = None) -> CrewResult: + """Execute the crew's tasks, or decompose *goal* when no tasks were declared.""" + await self._engine.connect_mcp_servers() + if self._specs: + if goal is not None: + raise CrewError("Crew was built with tasks, so run() takes no goal. Drop the goal or drop the tasks.") + team_result = await self._engine.run_tasks(self._team, self._specs) + else: + if goal is None: + raise CrewError('Crew has no tasks. Pass tasks=[...] at construction, or a goal: await crew.run("...").') + team_result = await self._engine.run_team(self._team, goal) + return _build_crew_result(team_result, self._specs) + + def run_sync(self, goal: str | None = None) -> CrewResult: + """Blocking form of :meth:`run`. Closes the engine this crew created.""" + return run_coroutine_blocking( + self._run_and_close(goal), + sync_call="Crew.run_sync()", + async_call="await crew.run(...)", + ) + + async def _run_and_close(self, goal: str | None) -> CrewResult: + try: + return await self.run(goal) + finally: + await self.close() + + async def close(self) -> None: + """Release engine resources. An engine passed in via ``engine=`` is left alone.""" + if self._owns_engine: + await self._engine.close() + + async def __aenter__(self) -> Crew: + await self._engine.connect_mcp_servers() + return self + + async def __aexit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None: + await self.close() + + def __repr__(self) -> str: + return f"Crew(name={self.name!r}, agents={len(self._agent_configs)}, tasks={len(self._specs)}, process={self.process!r})" + + +# --------------------------------------------------------------------------- +# Normalization +# --------------------------------------------------------------------------- + + +def _as_agent_config(agent: AgentInput) -> AgentConfig: + if isinstance(agent, Agent): + return agent.config + if isinstance(agent, AgentConfig): + return agent + if isinstance(agent, dict): + return AgentConfig.model_validate(agent) + raise CrewError(f"Cannot use {type(agent).__name__} as a crew member. Pass an Agent, an AgentConfig, or a config dict.") + + +def _as_task_spec(task: TaskInput) -> TaskSpec: + if isinstance(task, TaskSpec): + return task + if isinstance(task, str): + return TaskSpec(task) + if isinstance(task, dict): + return TaskSpec(**task) # type: ignore[arg-type] + raise CrewError(f"Cannot use {type(task).__name__} as a task. Pass a TaskSpec, a dict of TaskSpec arguments, or a string title.") + + +def _resolve_task_specs( + tasks: Sequence[TaskInput] | None, + agents: Sequence[AgentConfig], + process: Process, +) -> list[TaskSpec]: + if not tasks: + return [] + + specs = [_as_task_spec(task) for task in tasks] + known = {config.name for config in agents} + default_assignee = agents[0].name + + previous_title: str | None = None + for spec in specs: + if spec.assignee is None: + spec.assignee = default_assignee + elif spec.assignee not in known: + raise CrewError(f'Task "{spec.title}" is assigned to "{spec.assignee}", who is not in this crew. Members: {", ".join(sorted(known))}.') + if process == "sequential" and not spec.depends_on and previous_title is not None: + spec.depends_on = [previous_title] + previous_title = spec.title + + return specs + + +def _build_orchestrator_config(options: dict[str, Any], max_concurrency: int | None, verbose: bool) -> OrchestratorConfig: + unknown = sorted(set(options) - set(OrchestratorConfig.model_fields)) + if unknown: + valid = ", ".join(sorted(OrchestratorConfig.model_fields)) + raise CrewError(f"Crew received unknown option(s): {', '.join(unknown)}. Valid orchestrator options are: {valid}.") + + settings = dict(options) + if max_concurrency is not None: + settings.setdefault("max_concurrency", max_concurrency) + if verbose and settings.get("on_progress") is None: + settings["on_progress"] = _print_progress + return OrchestratorConfig.model_validate(settings) + + +def _print_progress(event: OrchestratorEvent) -> None: + if event.type == "agent_start": + print(f"[crew] {event.agent} started") + elif event.type == "agent_complete": + print(f"[crew] {event.agent} finished") + elif event.type == "task_complete": + print(f"[crew] task {event.task} complete") + elif event.type == "error": + print(f"[crew] error from {event.agent or 'crew'}: {event.data}") + + +def _build_crew_result(team_result: TeamRunResult, specs: Sequence[TaskSpec]) -> CrewResult: + outputs = {name: result.output for name, result in team_result.agent_results.items()} + + output = "" + if specs: + for spec in reversed(specs): + if spec.assignee and spec.assignee in outputs: + output = outputs[spec.assignee] + break + if not output and outputs: + output = next(reversed(outputs.values())) + + return CrewResult( + success=team_result.success, + output=output, + outputs=outputs, + usage=team_result.total_token_usage, + cost=team_result.cost_report, + team_result=team_result, + ) diff --git a/src/anycode/tasks/task.py b/src/anycode/tasks/task.py index 3cc8e82..e6cb6de 100644 --- a/src/anycode/tasks/task.py +++ b/src/anycode/tasks/task.py @@ -8,7 +8,14 @@ from anycode.types import Task -def create_task(*, title: str, description: str, assignee: str | None = None, depends_on: list[str] | None = None) -> Task: +def create_task( + *, + title: str, + description: str, + assignee: str | None = None, + depends_on: list[str] | None = None, + expected_output: str | None = None, +) -> Task: now = datetime.now(UTC) return Task( id=str(uuid7()), @@ -17,6 +24,7 @@ def create_task(*, title: str, description: str, assignee: str | None = None, de status="pending", assignee=assignee, depends_on=list(depends_on) if depends_on else None, + expected_output=expected_output, created_at=now, updated_at=now, ) diff --git a/src/anycode/types.py b/src/anycode/types.py index cbc94e3..40cdd19 100644 --- a/src/anycode/types.py +++ b/src/anycode/types.py @@ -603,6 +603,7 @@ class Task(BaseModel): status: TaskStatus = "pending" assignee: str | None = None depends_on: list[str] | None = None + expected_output: str | None = None result: str | None = None created_at: datetime updated_at: datetime diff --git a/tests/test_crew.py b/tests/test_crew.py new file mode 100644 index 0000000..5726721 --- /dev/null +++ b/tests/test_crew.py @@ -0,0 +1,229 @@ +"""Tests for the Crew facade over the wavefront scheduler.""" + +from __future__ import annotations + +import pytest + +from anycode import Agent, AgentConfig, AnyCode, Crew, CrewError, CrewResult, TaskSpec, tool +from anycode.providers.fake import FakeAdapter, FakeResponse + + +@pytest.fixture +def fake_adapter(monkeypatch: pytest.MonkeyPatch) -> list[list[dict[str, object]]]: + """Patch adapter creation so every agent replies deterministically. Returns captured prompts.""" + captured: list[list[dict[str, object]]] = [] + + class _RecordingAdapter(FakeAdapter): + async def chat(self, messages, options): # type: ignore[no-untyped-def] + captured.append([message.model_dump() for message in messages]) + return await super().chat(messages, options) + + async def _create(*_args: object, **_kwargs: object) -> FakeAdapter: + return _RecordingAdapter(responses=[FakeResponse(text="ok")]) + + monkeypatch.setattr("anycode.core.agent.create_adapter", _create) + return captured + + +def _agent(name: str) -> Agent: + return Agent(name=name, model="fake-model", provider="openai", instructions=f"You are {name}.", tools=[]) + + +# --------------------------------------------------------------------------- +# Construction +# --------------------------------------------------------------------------- + + +def test_crew_requires_agents() -> None: + with pytest.raises(CrewError, match="at least one agent"): + Crew(agents=[]) + + +def test_crew_rejects_unknown_process() -> None: + with pytest.raises(CrewError, match="Unknown process"): + Crew(agents=[_agent("a")], process="parallel") # type: ignore[arg-type] + + +def test_crew_accepts_agents_configs_and_dicts() -> None: + crew = Crew( + agents=[ + _agent("built"), + AgentConfig(name="configured", model="m", provider="openai"), + {"name": "dictated", "model": "m", "provider": "openai"}, + ] + ) + assert [config.name for config in crew.team.get_agents()] == ["built", "configured", "dictated"] + + +def test_crew_rejects_unknown_orchestrator_option() -> None: + with pytest.raises(CrewError, match="unknown option"): + Crew(agents=[_agent("a")], nonsense=True) + + +def test_crew_forwards_known_orchestrator_options() -> None: + crew = Crew(agents=[_agent("a")], max_handoff_depth=7) + assert crew.engine._config.max_handoff_depth == 7 + + +def test_repr_summarizes_the_crew() -> None: + crew = Crew(agents=[_agent("a")], tasks=["do a thing"]) + assert repr(crew) == "Crew(name='crew', agents=1, tasks=1, process='dependency')" + + +# --------------------------------------------------------------------------- +# Task normalization +# --------------------------------------------------------------------------- + + +def test_string_task_becomes_a_spec_assigned_to_the_first_agent() -> None: + crew = Crew(agents=[_agent("lead"), _agent("second")], tasks=["summarize the report"]) + spec = crew.tasks[0] + assert spec.title == "summarize the report" + assert spec.description == "summarize the report" + assert spec.assignee == "lead" + + +def test_dict_task_becomes_a_spec() -> None: + crew = Crew(agents=[_agent("lead")], tasks=[{"title": "T", "description": "D", "expected_output": "E"}]) + spec = crew.tasks[0] + assert (spec.title, spec.description, spec.expected_output) == ("T", "D", "E") + + +def test_task_spec_accepts_an_agent_object() -> None: + writer = _agent("writer") + crew = Crew(agents=[_agent("lead"), writer], tasks=[TaskSpec("Write", "Write it.", agent=writer)]) + assert crew.tasks[0].assignee == "writer" + + +def test_task_spec_context_is_an_alias_for_depends_on() -> None: + spec = TaskSpec("Second", "Do it.", context=["First"]) + assert spec.depends_on == ["First"] + + +def test_sequential_process_chains_tasks() -> None: + crew = Crew(agents=[_agent("lead")], tasks=["one", "two", "three"], process="sequential") + assert [spec.depends_on for spec in crew.tasks] == [[], ["one"], ["two"]] + + +def test_dependency_process_leaves_tasks_independent() -> None: + crew = Crew(agents=[_agent("lead")], tasks=["one", "two"]) + assert [spec.depends_on for spec in crew.tasks] == [[], []] + + +def test_explicit_dependency_survives_sequential_process() -> None: + crew = Crew( + agents=[_agent("lead")], + tasks=["one", "two", TaskSpec("three", "do it", depends_on=["one"])], + process="sequential", + ) + assert crew.tasks[2].depends_on == ["one"] + + +def test_unknown_assignee_is_rejected() -> None: + with pytest.raises(CrewError, match="not in this crew"): + Crew(agents=[_agent("lead")], tasks=[TaskSpec("T", "D", assignee="ghost")]) + + +def test_unsupported_task_type_is_rejected() -> None: + with pytest.raises(CrewError, match="Cannot use int as a task"): + Crew(agents=[_agent("lead")], tasks=[3]) # type: ignore[list-item] + + +# --------------------------------------------------------------------------- +# Execution +# --------------------------------------------------------------------------- + + +async def test_crew_runs_dependent_tasks(fake_adapter: list[list[dict[str, object]]]) -> None: + researcher, writer = _agent("researcher"), _agent("writer") + crew = Crew( + agents=[researcher, writer], + tasks=[ + TaskSpec("Research", "Find sources.", agent=researcher), + TaskSpec("Write", "Write a brief.", agent=writer, depends_on=["Research"]), + ], + ) + result = await crew.run() + await crew.close() + + assert isinstance(result, CrewResult) + assert result.success + assert set(result.outputs) == {"researcher", "writer"} + assert str(result) == result.output == "ok" + + +async def test_expected_output_reaches_the_agent_prompt(fake_adapter: list[list[dict[str, object]]]) -> None: + crew = Crew( + agents=[_agent("lead")], + tasks=[TaskSpec("Summarize", "Summarize the notes.", expected_output="Three bullet points.")], + ) + await crew.run() + await crew.close() + + prompts = [str(message) for conversation in fake_adapter for message in conversation] + assert any("Expected output: Three bullet points." in prompt for prompt in prompts) + + +async def test_autonomous_mode_delegates_to_run_team(fake_adapter: list[list[dict[str, object]]]) -> None: + crew = Crew(agents=[_agent("lead"), _agent("helper")]) + result = await crew.run("Produce a brief.") + await crew.close() + assert result.success + assert "lead" in result.outputs + + +async def test_goal_with_declared_tasks_is_rejected(fake_adapter: list[list[dict[str, object]]]) -> None: + crew = Crew(agents=[_agent("lead")], tasks=["one"]) + with pytest.raises(CrewError, match="takes no goal"): + await crew.run("a goal") + await crew.close() + + +async def test_missing_goal_without_tasks_is_rejected(fake_adapter: list[list[dict[str, object]]]) -> None: + crew = Crew(agents=[_agent("lead")]) + with pytest.raises(CrewError, match="no tasks"): + await crew.run() + await crew.close() + + +async def test_prebuilt_agents_keep_their_custom_tools(fake_adapter: list[list[dict[str, object]]]) -> None: + @tool + def special(value: str) -> str: + """A tool only this agent has.""" + return value + + specialist = Agent(name="specialist", model="m", provider="openai", tools=[special]) + crew = Crew(agents=[specialist], tasks=["use the tool"]) + await crew.run() + await crew.close() + + pooled = crew.engine._pool.get("specialist") + assert pooled is specialist + assert "special" in {definition.name for definition in specialist.tools} + + +async def test_injected_engine_is_not_closed_by_the_crew() -> None: + engine = AnyCode() + crew = Crew(agents=[_agent("lead")], engine=engine) + await crew.close() + assert crew.engine is engine + await engine.close() + + +def test_run_sync_inside_a_loop_is_rejected(fake_adapter: list[list[dict[str, object]]]) -> None: + crew = Crew(agents=[_agent("lead")], tasks=["one"]) + result = crew.run_sync() + assert result.success + + +async def test_run_sync_from_async_context_is_rejected(fake_adapter: list[list[dict[str, object]]]) -> None: + crew = Crew(agents=[_agent("lead")], tasks=["one"]) + with pytest.raises(RuntimeError, match="await crew.run"): + crew.run_sync() + await crew.close() + + +async def test_crew_is_an_async_context_manager(fake_adapter: list[list[dict[str, object]]]) -> None: + async with Crew(agents=[_agent("lead")], tasks=["one"]) as crew: + result = await crew.run() + assert result.success From 5d0e2de34d807314a58b690c4b30346828139374 Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 06:10:16 +0500 Subject: [PATCH 04/11] feat(workflow): add state-graph workflow runtime Workflow gives AnyCode explicit control flow -- branching, looping, retry, fan-out -- which the wavefront scheduler cannot express, since it only fans out on task dependencies. Crew stays the declarative path; Workflow is the imperative one, and a Crew or Agent can be a node in a graph. wf = Workflow(ReviewState) wf.add_node("write", write); wf.add_node("review", review) wf.add_edge(START, "write"); wf.add_edge("write", "review") wf.add_conditional_edge("review", gate) result = await wf.compile().run(ReviewState(topic="...")) State is a frozen Pydantic model (or a dict when no schema is given). Nodes return a patch, a full state instance, a Command, or None. Fields annotated Annotated[T, add] accumulate rather than being replaced; merge, keep_first, and keep_last ship alongside add. Nodes may be async functions, sync functions (run off the event loop), an Agent, a Crew, or another compiled workflow. Routing is a static edge, a conditional edge with or without a path map, or a Command returned by the node. add_node(goto=[...]) declares Command targets so reachability analysis stays accurate. compile() aggregates every structural problem into one message: missing entry, unregistered edge targets, unreachable nodes, non-terminating cycles, and bad path-map targets. Execution streams node_start/node_end/ route/done events, caps work at max_steps (reported as the new max_steps StopReason code), merges concurrent patches and rejects conflicting plain writes, and renders itself with to_mermaid()/to_dict(). --- examples/47_workflow_graph.py | 119 +++++++ src/anycode/__init__.py | 18 + src/anycode/types.py | 1 + src/anycode/workflow/__init__.py | 34 ++ src/anycode/workflow/graph.py | 369 ++++++++++++++++++++ src/anycode/workflow/runtime.py | 252 ++++++++++++++ src/anycode/workflow/state.py | 184 ++++++++++ tests/test_workflow.py | 579 +++++++++++++++++++++++++++++++ 8 files changed, 1556 insertions(+) create mode 100644 examples/47_workflow_graph.py create mode 100644 src/anycode/workflow/__init__.py create mode 100644 src/anycode/workflow/graph.py create mode 100644 src/anycode/workflow/runtime.py create mode 100644 src/anycode/workflow/state.py create mode 100644 tests/test_workflow.py diff --git a/examples/47_workflow_graph.py b/examples/47_workflow_graph.py new file mode 100644 index 0000000..5fb5824 --- /dev/null +++ b/examples/47_workflow_graph.py @@ -0,0 +1,119 @@ +# Demo 47 — Workflow Graph with a Review Loop +# Execute: uv run python examples/47_workflow_graph.py +# Requires: ANTHROPIC_API_KEY or OPENAI_API_KEY in the environment or .env. + +import asyncio +from typing import Annotated + +from dotenv import load_dotenv +from pydantic import BaseModel, ConfigDict + +from anycode import END, START, Agent, Workflow +from anycode.workflow import add + +load_dotenv() + +MAX_ROUNDS = 3 + + +class ReviewState(BaseModel): + """State threaded through every node. Frozen — nodes return patches, never mutate.""" + + model_config = ConfigDict(frozen=True) + + topic: str = "" + draft: str = "" + critique: str = "" + rounds: int = 0 + tokens: Annotated[int, add] = 0 + log: Annotated[list[str], add] = [] + + +writer = Agent( + name="writer", + instructions="You write tight technical blurbs. Two sentences, no preamble, no markdown headings.", + tools=[], + max_turns=2, +) + +critic = Agent( + name="critic", + instructions=( + "You are a demanding technical editor. If the blurb is accurate and tight, reply with exactly APPROVED. " + "Otherwise reply with one sentence naming the single biggest problem." + ), + tools=[], + max_turns=2, +) + +workflow = Workflow(ReviewState, name="write-review") + + +@workflow.node +async def write(state: ReviewState) -> dict: + revision = f"\n\nPrevious critique to address: {state.critique}" if state.critique else "" + result = await writer.run(f"Write a two-sentence blurb about: {state.topic}{revision}") + return { + "draft": result.output.strip(), + "rounds": state.rounds + 1, + "tokens": result.token_usage.input_tokens + result.token_usage.output_tokens, + "log": [f"round {state.rounds + 1}: drafted {len(result.output)} chars"], + } + + +@workflow.node +async def review(state: ReviewState) -> dict: + result = await critic.run(f"Topic: {state.topic}\n\nBlurb:\n{state.draft}") + verdict = result.output.strip() + return { + "critique": verdict, + "tokens": result.token_usage.input_tokens + result.token_usage.output_tokens, + "log": [f"round {state.rounds}: critic said {verdict[:40]}"], + } + + +def gate(state: ReviewState) -> str: + """Stop when the critic approves or the round budget runs out.""" + if "APPROVED" in state.critique.upper() or state.rounds >= MAX_ROUNDS: + return END + return "write" + + +workflow.add_edge(START, "write") +workflow.add_edge("write", "review") +workflow.add_conditional_edge("review", gate) + + +async def main() -> None: + app = workflow.compile() + + print("Graph\n" + "=" * 55) + print(app.to_mermaid()) + + print("\n\nStreaming the run\n" + "=" * 55) + final = None + async for event in app.stream(ReviewState(topic="why vector databases need hybrid search"), max_steps=8): + if event.type == "node_start": + print(f" -> {event.node}") + elif event.type == "route": + print(f" {event.node} routes to {', '.join(event.targets)}") + elif event.type == "done": + final = event.result + + assert final is not None + print("\nFinal draft\n" + "=" * 55) + print(final.state.draft) + print("=" * 55) + print(f"\nSucceeded: {final.success}") + print(f"Rounds: {final.state.rounds}") + print(f"Steps: {final.steps}") + print(f"Path: {' -> '.join(final.path)}") + print(f"Stop reason: {final.stop_reason.code if final.stop_reason else 'reached END'}") + print(f"Tokens: {final.state.tokens} (summed by the `add` reducer on ReviewState.tokens)") + print("\nAccumulated log (the `add` reducer appends instead of replacing):") + for line in final.state.log: + print(f" - {line}") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/src/anycode/__init__.py b/src/anycode/__init__.py index 395cf47..329e28e 100644 --- a/src/anycode/__init__.py +++ b/src/anycode/__init__.py @@ -403,6 +403,16 @@ ) from anycode.viz.dag import render_dag from anycode.viz.timeline import render_timeline +from anycode.workflow import ( + END, + START, + Command, + CompiledWorkflow, + Workflow, + WorkflowError, + WorkflowEvent, + WorkflowResult, +) __all__ = [ # Constants — event names @@ -423,6 +433,14 @@ "Crew", "CrewError", "CrewResult", + "Workflow", + "CompiledWorkflow", + "WorkflowError", + "WorkflowEvent", + "WorkflowResult", + "Command", + "START", + "END", "AgentConfigError", "compose_instructions", "AgentRunner", diff --git a/src/anycode/types.py b/src/anycode/types.py index 40cdd19..8fc0696 100644 --- a/src/anycode/types.py +++ b/src/anycode/types.py @@ -108,6 +108,7 @@ class TokenUsage(BaseModel): StopReasonCode = Literal[ "success", "max_turns", + "max_steps", "budget_exceeded", "context_pressure", "tool_error", diff --git a/src/anycode/workflow/__init__.py b/src/anycode/workflow/__init__.py new file mode 100644 index 0000000..aa03f02 --- /dev/null +++ b/src/anycode/workflow/__init__.py @@ -0,0 +1,34 @@ +"""State-graph workflows — explicit branching, looping, and fan-out over AnyCode agents.""" + +from anycode.workflow.graph import END, START, Command, Router, Workflow +from anycode.workflow.runtime import DEFAULT_MAX_STEPS, CompiledWorkflow, WorkflowEvent, WorkflowResult +from anycode.workflow.state import ( + BUILT_IN_REDUCERS, + Patch, + Reducer, + WorkflowError, + add, + keep_first, + keep_last, + merge, +) + +__all__ = [ + "BUILT_IN_REDUCERS", + "DEFAULT_MAX_STEPS", + "END", + "START", + "Command", + "CompiledWorkflow", + "Patch", + "Reducer", + "Router", + "Workflow", + "WorkflowError", + "WorkflowEvent", + "WorkflowResult", + "add", + "keep_first", + "keep_last", + "merge", +] diff --git a/src/anycode/workflow/graph.py b/src/anycode/workflow/graph.py new file mode 100644 index 0000000..5e3ff16 --- /dev/null +++ b/src/anycode/workflow/graph.py @@ -0,0 +1,369 @@ +"""Workflow graph construction: nodes, edges, conditional edges, and compile-time validation.""" + +from __future__ import annotations + +import asyncio +import functools +import inspect +from collections.abc import Awaitable, Callable, Mapping, Sequence +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any + +from pydantic import BaseModel, ConfigDict + +from anycode.helpers.usage_tracker import EMPTY_USAGE +from anycode.types import TokenUsage +from anycode.workflow.state import ( + Reducer, + StateSchema, + WorkflowError, + collect_reducers, + normalize_patch, + state_get, +) + +if TYPE_CHECKING: + from anycode.workflow.runtime import CompiledWorkflow + +START = "__start__" +"""Virtual node every graph enters from.""" + +END = "__end__" +"""Virtual node that terminates a branch.""" + +DEFAULT_INPUT_KEY = "prompt" +DEFAULT_OUTPUT_KEY = "output" + +Router = Callable[[Any], str | Sequence[str]] +NodeResult = Mapping[str, Any] | BaseModel | None + + +class Command(BaseModel): + """Returned by a node to set the next hop dynamically, optionally with a state patch.""" + + model_config = ConfigDict(frozen=True) + + goto: str | None = None + update: dict[str, Any] | None = None + + +@dataclass(frozen=True) +class NodeOutcome: + patch: dict[str, Any] + usage: TokenUsage + goto: tuple[str, ...] | None + + +@dataclass(frozen=True) +class Node: + name: str + run: Callable[[Any], Awaitable[NodeOutcome]] + kind: str + + +@dataclass(frozen=True) +class ConditionalEdge: + router: Router + path_map: dict[str, str] | None + + def resolve(self, source: str, state: Any) -> tuple[str, ...]: + decision = self.router(state) + keys = [decision] if isinstance(decision, str) else list(decision) + if not keys: + raise WorkflowError(f'The router on "{source}" returned no target. Return a node name, a list of names, or END.') + if self.path_map is None: + return tuple(keys) + resolved: list[str] = [] + for key in keys: + if key not in self.path_map: + raise WorkflowError(f'The router on "{source}" returned "{key}", which is not in its path map: {sorted(self.path_map)}.') + resolved.append(self.path_map[key]) + return tuple(resolved) + + +class Workflow: + """Builder for a state graph: register nodes, connect them, then :meth:`compile`.""" + + def __init__(self, state_schema: StateSchema = None, *, name: str = "workflow") -> None: + if state_schema is not None and not (isinstance(state_schema, type) and issubclass(state_schema, BaseModel)): + raise WorkflowError("Workflow(state_schema=...) takes a Pydantic model class, or nothing for dict state.") + self.name = name + self.state_schema = state_schema + self._nodes: dict[str, Node] = {} + self._edges: dict[str, list[str]] = {} + self._conditional: dict[str, ConditionalEdge] = {} + self._dynamic: dict[str, tuple[str, ...]] = {} + self._entry: str | None = None + + # -- registration -- + + def add_node( + self, + name: str, + target: object = None, + *, + input_key: str = DEFAULT_INPUT_KEY, + output_key: str = DEFAULT_OUTPUT_KEY, + goto: Sequence[str] | None = None, + ) -> Workflow: + """Register *target* under *name*. Accepts a function, an Agent, a Crew, or a compiled workflow. + + ``goto`` declares the nodes this one may jump to by returning a + :class:`Command`. Declaring them keeps reachability analysis honest — a node + reached only by ``Command`` is otherwise indistinguishable from an orphan. + """ + if name in (START, END): + raise WorkflowError(f'"{name}" is reserved. Choose another node name.') + if name in self._nodes: + raise WorkflowError(f'A node named "{name}" is already registered.') + if target is None: + raise WorkflowError(f'Node "{name}" needs something to run. Pass a function, an Agent, a Crew, or a compiled workflow.') + self._nodes[name] = _build_node(name, target, self.state_schema, input_key=input_key, output_key=output_key) + if goto: + self._dynamic[name] = tuple(goto) + return self + + def node(self, target: object = None, /, *, name: str | None = None, **options: Any) -> Any: + """Decorator form of :meth:`add_node`. Usable bare (``@wf.node``) or configured.""" + if callable(target) and name is None and not options: + self.add_node(getattr(target, "__name__", "node"), target) + return target + + def _decorate(fn: Callable[..., Any]) -> Callable[..., Any]: + self.add_node(name or getattr(fn, "__name__", "node"), fn, **options) + return fn + + if target is not None: + return _decorate(target) # type: ignore[arg-type] + return _decorate + + def add_edge(self, source: str, target: str) -> Workflow: + """Connect *source* to *target*. Repeating a source fans out to every target.""" + if source == START: + self.set_entry(target) + return self + if source == END: + raise WorkflowError("END has no outgoing edges.") + if source in self._conditional: + raise WorkflowError(f'"{source}" already has a conditional edge. A node routes one way or the other, not both.') + self._edges.setdefault(source, []).append(target) + return self + + def add_conditional_edge(self, source: str, router: Router, path_map: dict[str, str] | None = None) -> Workflow: + """Route out of *source* by calling *router* with the current state.""" + if source in (START, END): + raise WorkflowError(f'"{source}" cannot have a conditional edge.') + if source in self._edges: + raise WorkflowError(f'"{source}" already has a static edge. A node routes one way or the other, not both.') + if source in self._conditional: + raise WorkflowError(f'"{source}" already has a conditional edge.') + if not callable(router): + raise WorkflowError(f'The router for "{source}" must be callable and take the state.') + self._conditional[source] = ConditionalEdge(router=router, path_map=dict(path_map) if path_map else None) + return self + + def set_entry(self, name: str) -> Workflow: + """Choose the node the graph starts at.""" + if self._entry is not None and self._entry != name: + raise WorkflowError(f'This workflow already starts at "{self._entry}". A graph has exactly one entry point.') + self._entry = name + return self + + # -- compilation -- + + def compile(self) -> CompiledWorkflow: + """Validate the graph and return an immutable, runnable copy.""" + problems = self._validate() + if problems: + raise WorkflowError(f"Workflow '{self.name}' cannot be compiled:\n" + "\n".join(f" - {problem}" for problem in problems)) + + assert self._entry is not None + from anycode.workflow.runtime import CompiledWorkflow + + return CompiledWorkflow( + name=self.name, + state_schema=self.state_schema, + nodes=dict(self._nodes), + edges={source: list(targets) for source, targets in self._edges.items()}, + conditional=dict(self._conditional), + dynamic=dict(self._dynamic), + entry=self._entry, + reducers=collect_reducers(self.state_schema), + ) + + def _validate(self) -> list[str]: + problems: list[str] = [] + if not self._nodes: + problems.append("no nodes are registered.") + if self._entry is None: + problems.append('no entry point. Call add_edge(START, "first") or set_entry("first").') + elif self._entry not in self._nodes: + problems.append(f'the entry point "{self._entry}" is not a registered node.') + + for source, targets in self._edges.items(): + if source not in self._nodes: + problems.append(f'an edge starts at "{source}", which is not a registered node.') + for target in targets: + if target != END and target not in self._nodes: + problems.append(f'the edge "{source}" -> "{target}" points at an unregistered node.') + + for source, edge in self._conditional.items(): + if source not in self._nodes: + problems.append(f'a conditional edge starts at "{source}", which is not a registered node.') + for key, target in (edge.path_map or {}).items(): + if target != END and target not in self._nodes: + problems.append(f'the path map on "{source}" maps "{key}" to unregistered node "{target}".') + + for source, targets in self._dynamic.items(): + for target in targets: + if target != END and target not in self._nodes: + problems.append(f'"{source}" declares goto="{target}", which is not a registered node.') + + if self._entry in self._nodes: + reachable = self._reachable_from_entry() + for name in self._nodes: + if name not in reachable: + problems.append(f'"{name}" is unreachable from the entry point.') + for name in sorted(self._terminating_nodes(reachable)): + problems.append(f'"{name}" can never reach END, so the workflow would loop forever.') + + return problems + + def _static_targets(self, name: str) -> tuple[str, ...] | None: + """Targets known without running the graph, or ``None`` when only a router decides.""" + declared = self._dynamic.get(name, ()) + if name in self._edges: + return (*self._edges[name], *declared) + edge = self._conditional.get(name) + if edge is None: + return (END, *declared) + if edge.path_map is None: + return None + return (*edge.path_map.values(), *declared) + + def _reachable_from_entry(self) -> set[str]: + assert self._entry is not None + seen: set[str] = set() + frontier = [self._entry] + while frontier: + current = frontier.pop() + if current in seen or current == END: + continue + seen.add(current) + targets = self._static_targets(current) + if targets is None: + # A router with no path map may reach any node; treat all as reachable. + return set(self._nodes) + frontier.extend(targets) + return seen + + def _terminating_nodes(self, reachable: set[str]) -> set[str]: + """Reachable nodes that provably cannot reach END.""" + can_end: set[str] = set() + changed = True + while changed: + changed = False + for name in reachable: + if name in can_end: + continue + targets = self._static_targets(name) + if targets is None or any(target == END or target in can_end for target in targets): + can_end.add(name) + changed = True + return reachable - can_end + + def __repr__(self) -> str: + return f"Workflow(name={self.name!r}, nodes={len(self._nodes)}, entry={self._entry!r})" + + +# --------------------------------------------------------------------------- +# Node adapters +# --------------------------------------------------------------------------- + + +def _build_node( + name: str, + target: object, + schema: StateSchema, + *, + input_key: str, + output_key: str, +) -> Node: + from anycode.core.agent import Agent + from anycode.crew import Crew + from anycode.workflow.runtime import CompiledWorkflow + + if isinstance(target, Agent): + return Node(name=name, run=_agent_runner(name, target, input_key, output_key, schema), kind="agent") + if isinstance(target, Crew): + return Node(name=name, run=_crew_runner(name, target, input_key, output_key, schema), kind="crew") + if isinstance(target, CompiledWorkflow): + return Node(name=name, run=_subgraph_runner(target), kind="workflow") + if callable(target): + return Node(name=name, run=_callable_runner(name, target, schema), kind="function") + raise WorkflowError(f'Node "{name}" got {type(target).__name__}. Pass a function, an Agent, a Crew, or a compiled workflow.') + + +def _outcome(name: str, schema: StateSchema, result: object, usage: TokenUsage = EMPTY_USAGE) -> NodeOutcome: + if isinstance(result, Command): + patch = normalize_patch(name, schema, result.update or {}) + goto = (result.goto,) if result.goto else None + return NodeOutcome(patch=patch, usage=usage, goto=goto) + return NodeOutcome(patch=normalize_patch(name, schema, result), usage=usage, goto=None) + + +def _callable_runner(name: str, fn: Callable[..., Any], schema: StateSchema) -> Callable[[Any], Awaitable[NodeOutcome]]: + is_coroutine = inspect.iscoroutinefunction(fn) + + async def _run(state: Any) -> NodeOutcome: + result = await fn(state) if is_coroutine else await asyncio.to_thread(functools.partial(fn, state)) + return _outcome(name, schema, result) + + return _run + + +def _require_input(name: str, state: Any, input_key: str) -> str: + value = state_get(state, input_key) + if value is None or value == "": + raise WorkflowError(f'Node "{name}" reads state field "{input_key}", which is empty. Set it upstream or pass input_key= to add_node.') + return str(value) + + +def _agent_runner(name: str, agent: Any, input_key: str, output_key: str, schema: StateSchema) -> Callable[[Any], Awaitable[NodeOutcome]]: + async def _run(state: Any) -> NodeOutcome: + result = await agent.run(_require_input(name, state, input_key)) + return _outcome(name, schema, {output_key: result.output}, result.token_usage) + + return _run + + +def _crew_runner(name: str, crew: Any, input_key: str, output_key: str, schema: StateSchema) -> Callable[[Any], Awaitable[NodeOutcome]]: + async def _run(state: Any) -> NodeOutcome: + goal = None if crew.tasks else _require_input(name, state, input_key) + result = await crew.run(goal) + return _outcome(name, schema, {output_key: result.output}, result.usage) + + return _run + + +def _subgraph_runner(subgraph: Any) -> Callable[[Any], Awaitable[NodeOutcome]]: + async def _run(state: Any) -> NodeOutcome: + result = await subgraph.run(state) + from anycode.workflow.state import state_to_dict + + return NodeOutcome(patch=state_to_dict(result.state), usage=result.usage, goto=None) + + return _run + + +__all__ = [ + "END", + "START", + "Command", + "ConditionalEdge", + "Node", + "NodeOutcome", + "Reducer", + "Router", + "Workflow", +] diff --git a/src/anycode/workflow/runtime.py b/src/anycode/workflow/runtime.py new file mode 100644 index 0000000..1107b5f --- /dev/null +++ b/src/anycode/workflow/runtime.py @@ -0,0 +1,252 @@ +"""Execution of a compiled workflow graph: stepping, streaming, and result assembly.""" + +from __future__ import annotations + +import asyncio +from collections.abc import AsyncGenerator, Iterator, Mapping +from typing import Any, Literal + +from pydantic import BaseModel, ConfigDict + +from anycode.helpers.sync_runner import iterate_async_blocking, run_coroutine_blocking +from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage +from anycode.security.redaction import safe_exception_message +from anycode.types import StopReason, TokenUsage +from anycode.workflow.graph import END, START, ConditionalEdge, Node +from anycode.workflow.state import ( + Reducer, + StateSchema, + WorkflowError, + apply_patch, + coerce_state, + merge_concurrent_patches, +) + +DEFAULT_MAX_STEPS = 25 + +EventType = Literal["node_start", "node_end", "route", "done", "error"] + + +class WorkflowResult(BaseModel): + """Outcome of one workflow run.""" + + model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True) + + success: bool + state: Any + steps: int = 0 + path: tuple[str, ...] = () + usage: TokenUsage = EMPTY_USAGE + stop_reason: StopReason | None = None + error: str | None = None + + +class WorkflowEvent(BaseModel): + """One observable moment during execution.""" + + model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True) + + type: EventType + node: str | None = None + step: int = 0 + patch: dict[str, Any] | None = None + targets: tuple[str, ...] = () + state: Any = None + result: WorkflowResult | None = None + error: str | None = None + + +class CompiledWorkflow: + """An immutable, runnable graph. Build one with :meth:`~anycode.workflow.graph.Workflow.compile`.""" + + def __init__( + self, + *, + name: str, + state_schema: StateSchema, + nodes: dict[str, Node], + edges: dict[str, list[str]], + conditional: dict[str, ConditionalEdge], + dynamic: dict[str, tuple[str, ...]], + entry: str, + reducers: Mapping[str, Reducer], + ) -> None: + self.name = name + self.state_schema = state_schema + self._nodes = nodes + self._edges = edges + self._conditional = conditional + self._dynamic = dynamic + self._entry = entry + self._reducers = dict(reducers) + + # -- execution -- + + async def run(self, state: Any = None, *, max_steps: int = DEFAULT_MAX_STEPS) -> WorkflowResult: + """Run to completion and return the final result.""" + outcome: WorkflowResult | None = None + async for event in self.stream(state, max_steps=max_steps): + if event.result is not None: + outcome = event.result + assert outcome is not None + return outcome + + def run_sync(self, state: Any = None, *, max_steps: int = DEFAULT_MAX_STEPS) -> WorkflowResult: + """Blocking form of :meth:`run`.""" + return run_coroutine_blocking( + self.run(state, max_steps=max_steps), + sync_call="CompiledWorkflow.run_sync()", + async_call="await workflow.run(...)", + ) + + def stream_sync(self, state: Any = None, *, max_steps: int = DEFAULT_MAX_STEPS) -> Iterator[WorkflowEvent]: + """Blocking form of :meth:`stream`.""" + return iterate_async_blocking( + lambda: self.stream(state, max_steps=max_steps), + sync_call="CompiledWorkflow.stream_sync()", + async_call="async for event in workflow.stream(...)", + ) + + async def stream(self, state: Any = None, *, max_steps: int = DEFAULT_MAX_STEPS) -> AsyncGenerator[WorkflowEvent, None]: + """Run the graph, yielding an event per node start, node end, and routing decision.""" + if max_steps < 1: + raise WorkflowError("max_steps must be at least 1.") + + current = coerce_state(self.state_schema, state) + frontier: tuple[str, ...] = (self._entry,) + path: list[str] = [] + usage = EMPTY_USAGE + steps = 0 + + while frontier: + if steps + len(frontier) > max_steps: + yield self._final_event( + WorkflowResult( + success=False, + state=current, + steps=steps, + path=tuple(path), + usage=usage, + stop_reason=StopReason( + code="max_steps", + message=f"Workflow '{self.name}' hit its {max_steps}-step limit without reaching END.", + recoverable=True, + ), + ) + ) + return + + for node_name in frontier: + yield WorkflowEvent(type="node_start", node=node_name, step=steps, state=current) + + try: + outcomes = await asyncio.gather(*(self._nodes[node_name].run(current) for node_name in frontier)) + except asyncio.CancelledError: + raise + except Exception as error: + message = safe_exception_message(error) + yield WorkflowEvent(type="error", node=frontier[0] if len(frontier) == 1 else None, step=steps, error=message) + yield self._final_event( + WorkflowResult( + success=False, + state=current, + steps=steps, + path=tuple(path), + usage=usage, + error=message, + stop_reason=StopReason(code="unknown", message=message, recoverable=False), + ) + ) + return + + patches: list[tuple[str, dict[str, Any]]] = [] + overrides: dict[str, tuple[str, ...]] = {} + for node_name, outcome in zip(frontier, outcomes, strict=True): + steps += 1 + path.append(node_name) + usage = merge_usage(usage, outcome.usage) + patches.append((node_name, outcome.patch)) + if outcome.goto is not None: + overrides[node_name] = outcome.goto + yield WorkflowEvent(type="node_end", node=node_name, step=steps, patch=outcome.patch) + + combined = merge_concurrent_patches(patches, self._reducers) + current = apply_patch(current, combined, schema=self.state_schema, reducers=self._reducers) + + next_nodes: list[str] = [] + for node_name in frontier: + targets = overrides.get(node_name) or self._route(node_name, current) + yield WorkflowEvent(type="route", node=node_name, step=steps, targets=targets, state=current) + for target in targets: + if target == END: + continue + if target not in self._nodes: + raise WorkflowError(f'Node "{node_name}" routed to "{target}", which is not a registered node.') + if target not in next_nodes: + next_nodes.append(target) + + frontier = tuple(next_nodes) + + yield self._final_event( + WorkflowResult(success=True, state=current, steps=steps, path=tuple(path), usage=usage), + ) + + def _route(self, node_name: str, state: Any) -> tuple[str, ...]: + edge = self._conditional.get(node_name) + if edge is not None: + return edge.resolve(node_name, state) + return tuple(self._edges.get(node_name, (END,))) + + @staticmethod + def _final_event(result: WorkflowResult) -> WorkflowEvent: + return WorkflowEvent(type="done", step=result.steps, state=result.state, result=result) + + # -- introspection -- + + @property + def nodes(self) -> tuple[str, ...]: + return tuple(self._nodes) + + @property + def entry(self) -> str: + return self._entry + + def to_dict(self) -> dict[str, Any]: + """A JSON-friendly description of the graph.""" + return { + "name": self.name, + "entry": self._entry, + "state_schema": self.state_schema.__name__ if self.state_schema else "dict", + "nodes": [{"name": name, "kind": node.kind} for name, node in self._nodes.items()], + "edges": [{"from": source, "to": target} for source, targets in self._edges.items() for target in targets], + "conditional_edges": [ + {"from": source, "path_map": edge.path_map or {}, "dynamic": edge.path_map is None} for source, edge in self._conditional.items() + ], + "declared_goto": [{"from": source, "to": target} for source, targets in self._dynamic.items() for target in targets], + } + + def to_mermaid(self) -> str: + """Render the graph as a Mermaid flowchart.""" + lines = ["flowchart TD", f' {START}(["START"])', f' {END}(["END"])'] + for name, node in self._nodes.items(): + lines.append(f' {name}["{name}
{node.kind}"]') + lines.append(f" {START} --> {self._entry}") + for source, targets in self._edges.items(): + lines.extend(f" {source} --> {target}" for target in targets) + for source, edge in self._conditional.items(): + if edge.path_map: + lines.extend(f" {source} -.->|{key}| {target}" for key, target in edge.path_map.items()) + else: + # Without a path map the targets are only known at runtime, so every + # node stays a candidate. Supply path_map= for a precise diagram. + candidates = [name for name in self._nodes if name != source] + lines.extend(f" {source} -.->|?| {target}" for target in (*candidates, END)) + for source, targets in self._dynamic.items(): + lines.extend(f" {source} -.->|goto| {target}" for target in targets) + for name in self._nodes: + if name not in self._edges and name not in self._conditional: + lines.append(f" {name} --> {END}") + return "\n".join(lines) + + def __repr__(self) -> str: + return f"CompiledWorkflow(name={self.name!r}, nodes={len(self._nodes)}, entry={self._entry!r})" diff --git a/src/anycode/workflow/state.py b/src/anycode/workflow/state.py new file mode 100644 index 0000000..c48ff10 --- /dev/null +++ b/src/anycode/workflow/state.py @@ -0,0 +1,184 @@ +"""State containers, patches, and reducers for workflow graphs. + +A node returns a *patch* — a mapping of the fields it changed. Patches merge into the +running state field by field; a field annotated with a reducer accumulates instead of +being replaced. +""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping +from typing import Any + +from pydantic import BaseModel + +Patch = Mapping[str, Any] +Reducer = Callable[[Any, Any], Any] +StateSchema = type[BaseModel] | None + + +class WorkflowError(RuntimeError): + """Raised when a workflow graph is invalid or a node produces an unusable result.""" + + +# --------------------------------------------------------------------------- +# Built-in reducers +# --------------------------------------------------------------------------- + + +def add(current: Any, incoming: Any) -> Any: + """Accumulate: concatenate sequences and strings, union sets, sum numbers.""" + if current is None: + return incoming + if incoming is None: + return current + if isinstance(current, list): + return [*current, *incoming] if isinstance(incoming, list) else [*current, incoming] + if isinstance(current, tuple): + return (*current, *incoming) if isinstance(incoming, tuple) else (*current, incoming) + if isinstance(current, set): + return current | (incoming if isinstance(incoming, set) else {incoming}) + if isinstance(current, str) and isinstance(incoming, str): + return current + incoming + if isinstance(current, bool) or isinstance(incoming, bool): + raise WorkflowError(f"The add reducer cannot combine {type(current).__name__} with {type(incoming).__name__}.") + if isinstance(current, int | float) and isinstance(incoming, int | float): + return current + incoming + raise WorkflowError(f"The add reducer cannot combine {type(current).__name__} with {type(incoming).__name__}.") + + +def merge(current: Any, incoming: Any) -> Any: + """Shallow-merge two mappings; the incoming keys win.""" + if current is None: + return incoming + if incoming is None: + return current + if isinstance(current, Mapping) and isinstance(incoming, Mapping): + return {**current, **incoming} + raise WorkflowError(f"The merge reducer needs two mappings, got {type(current).__name__} and {type(incoming).__name__}.") + + +def keep_first(current: Any, incoming: Any) -> Any: + """Keep the value already in state once it is set.""" + return incoming if current in (None, "", [], {}, ()) else current + + +def keep_last(_current: Any, incoming: Any) -> Any: + """Replace with the incoming value. This is the default behavior.""" + return incoming + + +BUILT_IN_REDUCERS: tuple[Reducer, ...] = (add, merge, keep_first, keep_last) + + +# --------------------------------------------------------------------------- +# State inspection and patching +# --------------------------------------------------------------------------- + + +def collect_reducers(schema: StateSchema) -> dict[str, Reducer]: + """Read per-field reducers declared as ``Annotated[T, reducer]`` on the state model.""" + if schema is None: + return {} + reducers: dict[str, Reducer] = {} + for name, field in schema.model_fields.items(): + for metadata in field.metadata: + if callable(metadata) and not isinstance(metadata, type): + reducers[name] = metadata + break + return reducers + + +def state_fields(schema: StateSchema) -> tuple[str, ...]: + return tuple(schema.model_fields) if schema is not None else () + + +def coerce_state(schema: StateSchema, value: Any) -> Any: + """Normalize a caller-supplied initial state into the graph's state type.""" + if schema is None: + if value is None: + return {} + if isinstance(value, Mapping): + return dict(value) + if isinstance(value, BaseModel): + return value.model_dump() + raise WorkflowError(f"An untyped workflow needs a mapping as its initial state, got {type(value).__name__}.") + if value is None: + return schema() + if isinstance(value, schema): + return value + if isinstance(value, Mapping): + return schema.model_validate(dict(value)) + raise WorkflowError(f"Expected {schema.__name__} or a mapping as the initial state, got {type(value).__name__}.") + + +def state_get(state: Any, key: str) -> Any: + if isinstance(state, Mapping): + return state.get(key) + return getattr(state, key, None) + + +def state_to_dict(state: Any) -> dict[str, Any]: + if isinstance(state, Mapping): + return dict(state) + if isinstance(state, BaseModel): + return state.model_dump() + return {} + + +def normalize_patch(node: str, schema: StateSchema, result: Any) -> dict[str, Any]: + """Turn whatever a node returned into a plain patch mapping.""" + if result is None: + return {} + if isinstance(result, Mapping): + patch = dict(result) + elif isinstance(result, BaseModel): + patch = result.model_dump() + else: + raise WorkflowError( + f'Node "{node}" returned {type(result).__name__}. A node must return a dict of changed fields, a state instance, a Command, or None.' + ) + + if schema is not None: + known = set(schema.model_fields) + unknown = sorted(set(patch) - known) + if unknown: + raise WorkflowError( + f'Node "{node}" returned unknown state field(s): {", ".join(unknown)}. {schema.__name__} declares: {", ".join(sorted(known))}.' + ) + return patch + + +def apply_patch(state: Any, patch: Patch, *, schema: StateSchema, reducers: Mapping[str, Reducer]) -> Any: + """Merge *patch* into *state*, honoring per-field reducers.""" + if not patch: + return state + + updates: dict[str, Any] = {} + for key, incoming in patch.items(): + reducer = reducers.get(key) + updates[key] = reducer(state_get(state, key), incoming) if reducer else incoming + + if schema is None: + return {**state_to_dict(state), **updates} + return state.model_copy(update=updates) + + +def merge_concurrent_patches(patches: list[tuple[str, dict[str, Any]]], reducers: Mapping[str, Reducer]) -> dict[str, Any]: + """Combine patches produced in the same step, rejecting conflicting plain writes.""" + combined: dict[str, Any] = {} + owner: dict[str, str] = {} + for node, patch in patches: + for key, value in patch.items(): + if key not in combined: + combined[key] = value + owner[key] = node + continue + reducer = reducers.get(key) + if reducer is None: + raise WorkflowError( + f'Nodes "{owner[key]}" and "{node}" both wrote "{key}" in the same step. ' + f"Annotate that field with a reducer, e.g. Annotated[list[str], add], or have only one node write it." + ) + combined[key] = reducer(combined[key], value) + return combined diff --git a/tests/test_workflow.py b/tests/test_workflow.py new file mode 100644 index 0000000..7f495d6 --- /dev/null +++ b/tests/test_workflow.py @@ -0,0 +1,579 @@ +"""Tests for the state-graph workflow runtime.""" + +from __future__ import annotations + +import threading +from typing import Annotated + +import pytest +from pydantic import BaseModel, ConfigDict + +from anycode import END, START, Agent, Command, Workflow, WorkflowError +from anycode.providers.fake import FakeAdapter, FakeResponse +from anycode.workflow import add, keep_first, keep_last, merge +from anycode.workflow.state import apply_patch, coerce_state, collect_reducers, merge_concurrent_patches + + +class Draft(BaseModel): + model_config = ConfigDict(frozen=True) + + topic: str = "" + draft: str = "" + critique: str = "" + rounds: int = 0 + notes: Annotated[list[str], add] = [] + + +# --------------------------------------------------------------------------- +# Linear execution +# --------------------------------------------------------------------------- + + +async def test_linear_graph_merges_patches_in_order() -> None: + workflow = Workflow(Draft) + workflow.add_node("first", lambda state: {"draft": "d1"}) + workflow.add_node("second", lambda state: {"critique": f"about {state.draft}"}) + workflow.add_edge(START, "first") + workflow.add_edge("first", "second") + workflow.add_edge("second", END) + + result = await workflow.compile().run(Draft(topic="x")) + assert result.success + assert result.state.draft == "d1" + assert result.state.critique == "about d1" + assert result.path == ("first", "second") + assert result.steps == 2 + + +async def test_node_without_outgoing_edge_terminates() -> None: + workflow = Workflow(Draft) + workflow.add_node("only", lambda state: {"draft": "done"}) + workflow.set_entry("only") + + result = await workflow.compile().run() + assert result.success + assert result.state.draft == "done" + + +async def test_untyped_workflow_uses_dict_state() -> None: + workflow = Workflow() + workflow.add_node("bump", lambda state: {"count": state.get("count", 0) + 1}) + workflow.set_entry("bump") + + result = await workflow.compile().run({"count": 4}) + assert result.state == {"count": 5} + + +async def test_returning_a_state_instance_is_treated_as_a_patch() -> None: + workflow = Workflow(Draft) + workflow.add_node("replace", lambda state: Draft(topic="t", draft="whole")) + workflow.set_entry("replace") + + result = await workflow.compile().run() + assert result.state.draft == "whole" + assert result.state.topic == "t" + + +async def test_returning_none_leaves_state_untouched() -> None: + workflow = Workflow(Draft) + workflow.add_node("noop", lambda state: None) + workflow.set_entry("noop") + + result = await workflow.compile().run(Draft(draft="kept")) + assert result.state.draft == "kept" + + +# --------------------------------------------------------------------------- +# Conditional routing and loops +# --------------------------------------------------------------------------- + + +def _review_loop(limit: int = 3) -> Workflow: + workflow = Workflow(Draft) + workflow.add_node("write", lambda state: {"draft": f"draft-{state.rounds + 1}", "rounds": state.rounds + 1}) + workflow.add_node("review", lambda state: {"critique": "APPROVED" if state.rounds >= limit else "more work"}) + workflow.add_edge(START, "write") + workflow.add_edge("write", "review") + workflow.add_conditional_edge("review", lambda state: END if "APPROVED" in state.critique else "write") + return workflow + + +async def test_conditional_edge_loops_until_approved() -> None: + result = await _review_loop(limit=3).compile().run(Draft(topic="t")) + assert result.success + assert result.state.rounds == 3 + assert result.path.count("write") == 3 + + +async def test_conditional_edge_with_path_map() -> None: + workflow = Workflow(Draft) + workflow.add_node("check", lambda state: {"critique": "ok"}) + workflow.add_node("fix", lambda state: {"draft": "fixed"}) + workflow.add_edge(START, "check") + workflow.add_conditional_edge("check", lambda state: "pass" if state.critique == "ok" else "fail", {"pass": END, "fail": "fix"}) + workflow.add_edge("fix", END) + + result = await workflow.compile().run() + assert result.path == ("check",) + + +async def test_router_returning_an_unmapped_key_is_rejected() -> None: + workflow = Workflow(Draft) + workflow.add_node("check", lambda state: {}) + workflow.add_node("fix", lambda state: {}) + workflow.add_edge(START, "check") + workflow.add_conditional_edge("check", lambda state: "surprise", {"pass": END, "fail": "fix"}) + workflow.add_edge("fix", END) + + with pytest.raises(WorkflowError, match="not in its path map"): + await workflow.compile().run() + + +async def test_max_steps_stops_a_runaway_loop() -> None: + result = await _review_loop(limit=99).compile().run(Draft(topic="t"), max_steps=6) + assert not result.success + assert result.stop_reason is not None + assert result.stop_reason.code == "max_steps" + assert result.stop_reason.recoverable + assert result.steps == 6 + + +async def test_max_steps_must_be_positive() -> None: + workflow = _review_loop() + with pytest.raises(WorkflowError, match="at least 1"): + await workflow.compile().run(Draft(), max_steps=0) + + +# --------------------------------------------------------------------------- +# Command +# --------------------------------------------------------------------------- + + +async def test_command_overrides_the_static_edge() -> None: + workflow = Workflow(Draft) + workflow.add_node("start", lambda state: Command(goto="skipped_to", update={"draft": "via command"}), goto=["skipped_to"]) + workflow.add_node("normal", lambda state: {"critique": "should not run"}) + workflow.add_node("skipped_to", lambda state: {"critique": "arrived"}) + workflow.add_edge(START, "start") + workflow.add_edge("start", "normal") + workflow.add_edge("normal", END) + workflow.add_edge("skipped_to", END) + + result = await workflow.compile().run() + assert result.path == ("start", "skipped_to") + assert result.state.draft == "via command" + assert result.state.critique == "arrived" + + +async def test_command_can_terminate() -> None: + workflow = Workflow(Draft) + workflow.add_node("start", lambda state: Command(goto=END, update={"draft": "early exit"})) + workflow.add_node("never", lambda state: {"critique": "unreachable in practice"}) + workflow.add_edge(START, "start") + workflow.add_edge("start", "never") + workflow.add_edge("never", END) + + result = await workflow.compile().run() + assert result.path == ("start",) + assert result.state.draft == "early exit" + + +# --------------------------------------------------------------------------- +# Reducers +# --------------------------------------------------------------------------- + + +def test_built_in_reducers() -> None: + assert add([1], [2]) == [1, 2] + assert add([1], 2) == [1, 2] + assert add("a", "b") == "ab" + assert add(1, 2) == 3 + assert add(None, [1]) == [1] + assert merge({"a": 1}, {"b": 2}) == {"a": 1, "b": 2} + assert keep_first("held", "new") == "held" + assert keep_first("", "new") == "new" + assert keep_last("old", "new") == "new" + + +def test_add_reducer_rejects_incompatible_types() -> None: + with pytest.raises(WorkflowError, match="cannot combine"): + add(True, 1) + + +def test_merge_reducer_rejects_non_mappings() -> None: + with pytest.raises(WorkflowError, match="needs two mappings"): + merge(1, 2) + + +def test_reducers_are_collected_from_annotations() -> None: + assert collect_reducers(Draft) == {"notes": add} + + +async def test_annotated_field_accumulates_across_steps() -> None: + workflow = Workflow(Draft) + workflow.add_node("one", lambda state: {"notes": ["a"]}) + workflow.add_node("two", lambda state: {"notes": ["b"]}) + workflow.add_edge(START, "one") + workflow.add_edge("one", "two") + workflow.add_edge("two", END) + + result = await workflow.compile().run() + assert result.state.notes == ["a", "b"] + + +def test_apply_patch_replaces_unreduced_fields() -> None: + state = apply_patch(Draft(draft="old"), {"draft": "new"}, schema=Draft, reducers={}) + assert state.draft == "new" + + +# --------------------------------------------------------------------------- +# Patch validation +# --------------------------------------------------------------------------- + + +async def test_unknown_patch_field_names_the_valid_set() -> None: + workflow = Workflow(Draft) + workflow.add_node("bad", lambda state: {"nope": 1}) + workflow.set_entry("bad") + + result = await workflow.compile().run() + assert not result.success + assert result.error is not None + assert "unknown state field(s): nope" in result.error + + +async def test_non_mapping_return_is_rejected() -> None: + workflow = Workflow(Draft) + workflow.add_node("bad", lambda state: 42) + workflow.set_entry("bad") + + result = await workflow.compile().run() + assert not result.success + assert result.error is not None + assert "must return a dict of changed fields" in result.error + + +def test_coerce_state_accepts_mappings_and_instances() -> None: + assert coerce_state(Draft, {"draft": "d"}).draft == "d" + assert coerce_state(Draft, None).draft == "" + assert coerce_state(None, None) == {} + with pytest.raises(WorkflowError, match="Expected Draft"): + coerce_state(Draft, 3) + with pytest.raises(WorkflowError, match="needs a mapping"): + coerce_state(None, 3) + + +# --------------------------------------------------------------------------- +# Compile-time validation +# --------------------------------------------------------------------------- + + +def test_compile_reports_a_missing_entry_point() -> None: + workflow = Workflow(Draft) + workflow.add_node("a", lambda state: {}) + with pytest.raises(WorkflowError, match="no entry point"): + workflow.compile() + + +def test_compile_reports_an_empty_graph() -> None: + with pytest.raises(WorkflowError, match="no nodes are registered"): + Workflow(Draft).compile() + + +def test_compile_reports_an_edge_to_an_unregistered_node() -> None: + workflow = Workflow(Draft) + workflow.add_node("a", lambda state: {}) + workflow.add_edge(START, "a") + workflow.add_edge("a", "ghost") + with pytest.raises(WorkflowError, match='"a" -> "ghost" points at an unregistered node'): + workflow.compile() + + +def test_compile_reports_an_unreachable_node() -> None: + workflow = Workflow(Draft) + workflow.add_node("a", lambda state: {}) + workflow.add_node("orphan", lambda state: {}) + workflow.add_edge(START, "a") + workflow.add_edge("a", END) + workflow.add_edge("orphan", END) + with pytest.raises(WorkflowError, match='"orphan" is unreachable'): + workflow.compile() + + +def test_compile_reports_a_graph_that_cannot_terminate() -> None: + workflow = Workflow(Draft) + workflow.add_node("a", lambda state: {}) + workflow.add_node("b", lambda state: {}) + workflow.add_edge(START, "a") + workflow.add_edge("a", "b") + workflow.add_edge("b", "a") + with pytest.raises(WorkflowError, match="can never reach END"): + workflow.compile() + + +def test_compile_reports_a_bad_path_map_target() -> None: + workflow = Workflow(Draft) + workflow.add_node("a", lambda state: {}) + workflow.add_edge(START, "a") + workflow.add_conditional_edge("a", lambda state: "x", {"x": "ghost"}) + with pytest.raises(WorkflowError, match='maps "x" to unregistered node "ghost"'): + workflow.compile() + + +def test_compile_aggregates_every_problem() -> None: + workflow = Workflow(Draft) + workflow.add_node("a", lambda state: {}) + workflow.add_node("orphan", lambda state: {}) + workflow.add_edge(START, "a") + workflow.add_edge("a", "ghost") + with pytest.raises(WorkflowError) as error: + workflow.compile() + assert str(error.value).count("- ") >= 2 + + +def test_duplicate_node_names_are_rejected() -> None: + workflow = Workflow(Draft) + workflow.add_node("a", lambda state: {}) + with pytest.raises(WorkflowError, match="already registered"): + workflow.add_node("a", lambda state: {}) + + +def test_reserved_node_names_are_rejected() -> None: + with pytest.raises(WorkflowError, match="reserved"): + Workflow(Draft).add_node(END, lambda state: {}) + + +def test_a_node_cannot_have_both_edge_kinds() -> None: + workflow = Workflow(Draft) + workflow.add_node("a", lambda state: {}) + workflow.add_edge("a", END) + with pytest.raises(WorkflowError, match="already has a static edge"): + workflow.add_conditional_edge("a", lambda state: END) + + +def test_two_entry_points_are_rejected() -> None: + workflow = Workflow(Draft) + workflow.add_node("a", lambda state: {}) + workflow.add_node("b", lambda state: {}) + workflow.set_entry("a") + with pytest.raises(WorkflowError, match="exactly one entry point"): + workflow.set_entry("b") + + +def test_state_schema_must_be_a_model() -> None: + with pytest.raises(WorkflowError, match="Pydantic model class"): + Workflow(dict) # type: ignore[arg-type] + + +def test_node_target_must_be_runnable() -> None: + with pytest.raises(WorkflowError, match="Pass a function"): + Workflow(Draft).add_node("a", 3) + + +# --------------------------------------------------------------------------- +# Fan-out +# --------------------------------------------------------------------------- + + +async def test_fan_out_runs_targets_concurrently_and_merges() -> None: + workflow = Workflow(Draft) + workflow.add_node("split", lambda state: {}) + workflow.add_node("left", lambda state: {"notes": ["left"]}) + workflow.add_node("right", lambda state: {"notes": ["right"]}) + workflow.add_edge(START, "split") + workflow.add_edge("split", "left") + workflow.add_edge("split", "right") + workflow.add_edge("left", END) + workflow.add_edge("right", END) + + result = await workflow.compile().run() + assert result.success + assert sorted(result.state.notes) == ["left", "right"] + + +async def test_conflicting_concurrent_writes_are_rejected() -> None: + workflow = Workflow(Draft) + workflow.add_node("split", lambda state: {}) + workflow.add_node("left", lambda state: {"draft": "L"}) + workflow.add_node("right", lambda state: {"draft": "R"}) + workflow.add_edge(START, "split") + workflow.add_edge("split", "left") + workflow.add_edge("split", "right") + workflow.add_edge("left", END) + workflow.add_edge("right", END) + + with pytest.raises(WorkflowError, match="both wrote"): + await workflow.compile().run() + + +def test_merge_concurrent_patches_uses_reducers() -> None: + combined = merge_concurrent_patches([("a", {"notes": ["x"]}), ("b", {"notes": ["y"]})], {"notes": add}) + assert combined == {"notes": ["x", "y"]} + + +# --------------------------------------------------------------------------- +# Node kinds +# --------------------------------------------------------------------------- + + +async def test_sync_node_runs_off_the_event_loop() -> None: + seen: list[int] = [] + + def blocking(state: Draft) -> dict[str, str]: + seen.append(threading.get_ident()) + return {"draft": "sync"} + + workflow = Workflow(Draft) + workflow.add_node("blocking", blocking) + workflow.set_entry("blocking") + + await workflow.compile().run() + assert seen and seen[0] != threading.get_ident() + + +async def test_agent_node_reads_and_writes_state(monkeypatch: pytest.MonkeyPatch) -> None: + async def _create(*_args: object, **_kwargs: object) -> FakeAdapter: + return FakeAdapter(responses=[FakeResponse(text="agent said so")]) + + monkeypatch.setattr("anycode.core.agent.create_adapter", _create) + agent = Agent(name="writer", model="m", provider="openai", tools=[]) + + class AgentState(BaseModel): + model_config = ConfigDict(frozen=True) + + question: str = "" + answer: str = "" + + workflow = Workflow(AgentState) + workflow.add_node("ask", agent, input_key="question", output_key="answer") + workflow.set_entry("ask") + + result = await workflow.compile().run(AgentState(question="why?")) + assert result.state.answer == "agent said so" + + +async def test_agent_node_reports_a_missing_input_field(monkeypatch: pytest.MonkeyPatch) -> None: + async def _create(*_args: object, **_kwargs: object) -> FakeAdapter: + return FakeAdapter(responses=[FakeResponse(text="unused")]) + + monkeypatch.setattr("anycode.core.agent.create_adapter", _create) + agent = Agent(name="writer", model="m", provider="openai", tools=[]) + + workflow = Workflow(Draft) + workflow.add_node("ask", agent, input_key="topic", output_key="draft") + workflow.set_entry("ask") + + result = await workflow.compile().run(Draft()) + assert not result.success + assert result.error is not None + assert 'reads state field "topic"' in result.error + + +async def test_sub_workflow_node_merges_its_final_state() -> None: + inner = Workflow(Draft, name="inner") + inner.add_node("inner_step", lambda state: {"critique": "from inner"}) + inner.set_entry("inner_step") + + outer = Workflow(Draft, name="outer") + outer.add_node("prepare", lambda state: {"draft": "outer draft"}) + outer.add_node("delegate", inner.compile()) + outer.add_edge(START, "prepare") + outer.add_edge("prepare", "delegate") + outer.add_edge("delegate", END) + + result = await outer.compile().run() + assert result.state.draft == "outer draft" + assert result.state.critique == "from inner" + + +# --------------------------------------------------------------------------- +# Decorator, streaming, sync, and rendering +# --------------------------------------------------------------------------- + + +async def test_node_decorator_registers_by_function_name() -> None: + workflow = Workflow(Draft) + + @workflow.node + def written(state: Draft) -> dict[str, str]: + return {"draft": "decorated"} + + workflow.set_entry("written") + result = await workflow.compile().run() + assert result.state.draft == "decorated" + assert written(Draft()) == {"draft": "decorated"} + + +async def test_node_decorator_accepts_an_explicit_name() -> None: + workflow = Workflow(Draft) + + @workflow.node(name="custom") + def anything(state: Draft) -> dict[str, str]: + return {"draft": "named"} + + workflow.set_entry("custom") + assert (await workflow.compile().run()).state.draft == "named" + + +async def test_stream_emits_the_expected_event_sequence() -> None: + workflow = Workflow(Draft) + workflow.add_node("one", lambda state: {"draft": "d"}) + workflow.add_node("two", lambda state: {"critique": "c"}) + workflow.add_edge(START, "one") + workflow.add_edge("one", "two") + workflow.add_edge("two", END) + + events = [event async for event in workflow.compile().stream()] + assert [event.type for event in events] == [ + "node_start", + "node_end", + "route", + "node_start", + "node_end", + "route", + "done", + ] + assert events[-1].result is not None + assert events[-1].result.success + + +def test_run_sync_executes_the_graph() -> None: + workflow = Workflow(Draft) + workflow.add_node("only", lambda state: {"draft": "blocking"}) + workflow.set_entry("only") + + assert workflow.compile().run_sync().state.draft == "blocking" + + +def test_to_mermaid_contains_every_node_and_edge() -> None: + compiled = _review_loop().compile() + diagram = compiled.to_mermaid() + assert "flowchart TD" in diagram + assert "write --> review" in diagram + assert "__start__ --> write" in diagram + assert "review -.->|?| write" in diagram + assert "review -.->|?| __end__" in diagram + + +def test_to_dict_describes_the_graph() -> None: + described = _review_loop().compile().to_dict() + assert described["entry"] == "write" + assert described["state_schema"] == "Draft" + assert {node["name"] for node in described["nodes"]} == {"write", "review"} + assert described["conditional_edges"][0]["dynamic"] is True + + +def test_compiled_workflow_reports_its_shape() -> None: + compiled = _review_loop().compile() + assert compiled.nodes == ("write", "review") + assert compiled.entry == "write" + assert repr(compiled) == "CompiledWorkflow(name='workflow', nodes=2, entry='write')" + + +def test_editing_the_builder_does_not_change_a_compiled_graph() -> None: + workflow = Workflow(Draft) + workflow.add_node("a", lambda state: {}) + workflow.set_entry("a") + compiled = workflow.compile() + workflow.add_node("b", lambda state: {}) + assert compiled.nodes == ("a",) From dff205c687437cf4cdc7a471e4c870c73da1c2bc Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 06:22:54 +0500 Subject: [PATCH 05/11] perf(api): resolve the public API lazily Importing anycode pulled in every subsystem -- vector stores, redis, OpenTelemetry, the MCP SDK, provider clients -- whether a program touched them or not. Exports now resolve on first attribute access through a name -> (module, attribute) map and cache into the module namespace, so repeat lookups are a plain dict hit. import anycode 1913 ms / 1312 modules -> 33 ms / 73 modules anycode.Agent 1758 ms -> 414 ms anycode.Crew 1855 ms -> 476 ms No public symbol moved or changed name. A TYPE_CHECKING block mirrors the map so pyright and IDEs still resolve everything statically, and tests assert that __all__ and the export map stay in sync, that every name resolves, and that a bare import loads no optional dependency. The same treatment applies to the core, mcp, telemetry, memory, and helpers subpackages, whose eager __init__ re-exports were what actually dragged the heavy dependencies in, and AnyCode.connect_mcp_servers now imports the MCP SDK at the point of use. Fixes a latent import cycle the eager package __init__ was masking: anycode.types -> identity -> contracts -> helpers -> anycode.types meant `import anycode.types` on its own raised ImportError. Each of anycode.types, .helpers, .contracts, .identity, .core, and .memory is now importable standalone, and a test holds that line. Unknown attributes raise AttributeError with a did-you-mean suggestion. Missing optional memory backends report the extra to install instead of silently vanishing from the namespace. --- src/anycode/__init__.py | 1397 +++++++++++++++++++---------- src/anycode/_lazy.py | 63 ++ src/anycode/core/__init__.py | 53 +- src/anycode/core/orchestrator.py | 6 +- src/anycode/helpers/__init__.py | 39 +- src/anycode/mcp/__init__.py | 38 +- src/anycode/memory/__init__.py | 78 +- src/anycode/telemetry/__init__.py | 74 +- tests/test_mcp.py | 18 +- tests/test_public_api.py | 107 +++ 10 files changed, 1359 insertions(+), 514 deletions(-) create mode 100644 src/anycode/_lazy.py create mode 100644 tests/test_public_api.py diff --git a/src/anycode/__init__.py b/src/anycode/__init__.py index 329e28e..dbe0a40 100644 --- a/src/anycode/__init__.py +++ b/src/anycode/__init__.py @@ -1,421 +1,951 @@ -"""AnyCode — scalable multi-agent AI orchestration framework for Python.""" +"""AnyCode — scalable multi-agent AI orchestration framework for Python. -from anycode.backends import ( - BACKEND_CONTRACT_VERSION, - Admission, - BackendCapabilities, - BackendSnapshot, - DaprDurabilityBackend, - DaprHTTPTransport, - DurabilityBackend, - InMemoryDurabilityBackend, - SQLiteDurabilityBackend, - WorkItem, - export_filesystem_run, - import_backend_snapshot, -) -from anycode.checkpoint.manager import CheckpointManager -from anycode.checkpoint.serializer import UnsupportedCheckpointVersionError -from anycode.checkpoint.store import FilesystemCheckpointStore -from anycode.collaboration.kv_store import InMemoryStore -from anycode.collaboration.message_bus import MessageBus -from anycode.collaboration.shared_mem import SharedMemory -from anycode.collaboration.team import Team -from anycode.config.loader import UnknownConfigFieldError, UnsupportedConfigVersionError -from anycode.constants import ( - ORCH_EVENT_AGENT_COMPLETE, - ORCH_EVENT_AGENT_START, - ORCH_EVENT_BROADCAST, - ORCH_EVENT_ERROR, - ORCH_EVENT_MESSAGE, - ORCH_EVENT_TASK_COMPLETE, - ORCH_EVENT_TASK_START, - QUEUE_EVENT_ALL_COMPLETE, - QUEUE_EVENT_TASK_COMPLETE, - QUEUE_EVENT_TASK_FAILED, - QUEUE_EVENT_TASK_READY, -) -from anycode.contracts import ( - CONTRACT_SCHEMA_VERSION, - RUN_TRANSITIONS, - TERMINAL_STATES, - Artifact, - ArtifactAccessContext, - ArtifactReadResult, - ArtifactStore, - ArtifactWriteRequest, - ArtifactWriteResult, - CapabilityDescriptor, - Checkpoint, - ContractError, - Event, - IncrementalRunProjector, - InMemoryOperationStore, - LocalArtifactStore, - OperationClaim, - OperationClaimResult, - PolicyDecision, - Result, - RetryDecision, - Run, - RunProjection, - acknowledge_cancellation, - canonical_input_digest, - contract_schema_bundle, - decide_retry, - evaluate_dependencies, - is_valid_run_transition, - project_run, - request_cancellation, - start_new_generation, - transition_run, - transition_task, - validate_event_stream, -) -from anycode.contracts import ( - Message as SemanticMessage, -) -from anycode.contracts import ( - RetryPolicy as SemanticRetryPolicy, -) -from anycode.contracts import ( - Task as SemanticTask, -) -from anycode.contracts import ( - VerificationResult as SemanticVerificationResult, -) -from anycode.core import stop_reason as stop_reasons -from anycode.core.agent import Agent, AgentConfigError, compose_instructions -from anycode.core.context_artifacts import offload_text, restore_text -from anycode.core.context_manager import ContextManager, estimate_messages_tokens, rebuild_from_handoff -from anycode.core.lifecycle import ( - ALL_PHASES, - TERMINAL_PHASES, - InvalidPhaseTransitionError, - LifecycleEmitter, - LifecycleListener, - LoopDetector, - fingerprint_call, - is_valid_transition, -) -from anycode.core.orchestrator import AnyCode, TaskSpec -from anycode.core.pool import AgentPool -from anycode.core.runner import AgentRunner -from anycode.core.scheduler import Scheduler -from anycode.core.session_chain import SessionChain, contract_status_summary, load_contract, save_contract -from anycode.cost import ( - DEFAULT_PRICING, - CostTracker, - build_cost_report, - calculate_cost, - find_pricing, -) -from anycode.crew import Crew, CrewError, CrewResult -from anycode.eval import ( - compare_reports, - detect_provider, - load_scenario, - load_scenarios, - read_report, - render_markdown, - run_scenario, - run_suite, - write_report, -) -from anycode.guardrails.budget import BudgetTracker, estimate_cost -from anycode.guardrails.hooks import HookRunner, LoggingHook -from anycode.guardrails.validators import ( - BlocklistValidator, - ContainsValidator, - MaxLengthValidator, - run_validators, -) -from anycode.handoff.executor import HandoffExecutor -from anycode.handoff.protocol import build_handoff_system_prompt, build_handoff_user_message, trim_context -from anycode.handoff.tool import HANDOFF_TOOL_DEF -from anycode.harness import ( - EvidenceCollector, - EvidenceStore, - HarnessRegistry, - build_default_registry, - build_manifest, - categorize_event, - categorize_run, - diff_manifests, - distill_evidence, - load_manifest, - save_manifest, - write_evidence_bundle, -) -from anycode.helpers.concurrency_gate import Semaphore -from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage -from anycode.helpers.uuid7 import uuid7 -from anycode.hitl.approval import ApprovalManager -from anycode.hitl.channels import CallbackApprovalGate, StdinApprovalGate, WebhookApprovalGate -from anycode.hosting import A2A_AGENT_CARD_PATH, A2AAgentCard, HostLifecycle, build_deployment_agent_card -from anycode.identity import DelegationGrant, ExecutionContext, PolicyEnforcer, PolicyRequest -from anycode.mcp.bridge import discover_and_register as mcp_discover_and_register -from anycode.mcp.bridge import mcp_tool_to_definition, schema_to_pydantic_model -from anycode.mcp.client import MCPClient -from anycode.mcp.config import validate_server_config as mcp_validate_server_config -from anycode.memory.composite import CompositeMemory -from anycode.memory.factory import create_memory_store, create_vector_store -from anycode.memory.indexer import RAGIndexer -from anycode.memory.knowledge import KnowledgeEntry, KnowledgeStore, apply_retention, build_knowledge_tools -from anycode.memory.rag import RAGRetriever -from anycode.memory.vector_store import InMemoryVectorStore -from anycode.plugins import ( - PluginBase, - PluginRegistry, - discover_entry_point_plugins, - get_provider_factory, - list_registered_providers, - register_provider_factory, -) -from anycode.providers.adapter import create_adapter -from anycode.providers.fake import FakeAdapter, FakeResponse -from anycode.providers.resilience import ( - ProviderCapacityConfigurationError, - ProviderCapacityError, - ProviderCapacityLimiter, - ProviderUnavailableError, - ResilientAdapter, -) -from anycode.reflection.critic import DEFAULT_CRITIC_PROMPT, LLMCritic -from anycode.reflection.evaluator import parse_critic_json -from anycode.reflection.loop import ReflectionLoop -from anycode.routing.classifier import classify_task -from anycode.routing.policy import ModelRoutingRequest, PolicyRouter, ProviderCapabilityDescriptor -from anycode.routing.router import DefaultRouter -from anycode.routing.rules import evaluate_rules, match_rule -from anycode.runstore.protocol import RunPayloadProtector, RunStore -from anycode.runstore.store import FilesystemRunStore, ProtectedPayloadError, UnsupportedRunStoreVersionError -from anycode.sandbox import ( - CompanionSandboxAdapter, - DaytonaSandboxProvider, - E2BSandboxProvider, - LangSmithSandboxProvider, - ModalSandboxProvider, - PolicySandboxProvider, - RunloopSandboxProvider, - SandboxCapabilities, - SandboxCommand, - SandboxProvider, - SandboxSpec, - VercelSandboxProvider, - create_sandbox_provider, -) -from anycode.schedule.scheduler import RunScheduler, SweepReport, sweep_once -from anycode.schedule.tasks import ScheduledTask, ScheduledTaskResult, run_scheduled_task -from anycode.security import REDACTED_SECRET, redact_sensitive, redact_text, safe_exception_message -from anycode.structured.output import ( - STRUCTURED_OUTPUT_TOOL_NAME, - build_retry_prompt, - parse_structured_output, - schema_to_openai_response_format, - schema_to_tool_def, -) -from anycode.tasks.queue import TaskQueue -from anycode.tasks.task import create_task, get_task_dependency_order, is_task_ready, validate_task_dependencies -from anycode.telemetry.events import EventEmitter, TelemetryEvent -from anycode.telemetry.genai import BoundedTelemetryBuffer, GenAITelemetryConfig, GenAITelemetryMapper, GenAITelemetryRecord -from anycode.telemetry.metrics import MetricsCollector, Timer -from anycode.telemetry.tracer import ConsoleExporter, JSONLExporter, OTLPExporter, Span, Tracer -from anycode.tools.built_in import BUILT_IN_TOOLS, register_built_in_tools -from anycode.tools.executor import ToolExecutor -from anycode.tools.function_tool import ( - ToolDefinitionError, - ToolSpec, - as_tool_definition, - build_tool_definition, - builtin_tool_names, - function_tool, - resolve_tool_specs, - tool, -) -from anycode.tools.idempotency import ( - IdempotencyClaim, - InMemoryToolIdempotencyStore, - SQLiteToolIdempotencyStore, - ToolIdempotencyStore, - create_tool_idempotency_store, -) -from anycode.tools.registry import ToolRegistry, define_tool -from anycode.types import ( - AcceptanceThresholds, - AgentConfig, - AgentInfo, - AgentRunResult, - AgentState, - ApprovalConfig, - ApprovalGate, - ApprovalRequest, - ApprovalResponse, - BudgetSnapshot, - BudgetStatus, - CheckpointConfig, - CheckpointData, - CheckpointStore, - ComplexityLevel, - ContentBlock, - ContextArtifact, - ContextManifest, - ContextMode, - ContextPolicy, - ContextPressure, - ContextSectionBudget, - ContextSectionInput, - ContextSectionKind, - ContextSectionUsage, - ContextSource, - ContextUsageReport, - CostBreakdown, - CostConfig, - CostReport, - CountingConfidence, - Critic, - CriticResult, - DurabilityConfig, - EvalReport, - EvalScenario, - EvalScenarioResult, - EvidencePacket, - EvidenceSeverity, - EvolutionBlueprint, - ExecutionPhase, - FailureCategory, - FailureMapEntry, - GateOutcome, - GoalContract, - GoalCriterion, - GuardrailConfig, - Handoff, - HandoffPolicy, - HandoffRequest, - HarnessChangeEdit, - HarnessChangeManifest, - HarnessChangeOutcome, - HarnessChangePrediction, - HarnessChangeStatus, - HarnessComponent, - HarnessComponentKind, - HarnessComponentOwner, - HarnessManifest, - ImageBlock, - LifecycleEvent, - LLMAdapter, - LLMChatOptions, - LLMMessage, - LLMResponse, - LLMStreamOptions, - LLMToolDef, - MCPServerConfig, - MCPToolInfo, - MCPTrustPolicy, - MemoryConfig, - MemoryEntry, - MemoryStore, - MetaHarnessReport, - ModelContextProfile, - ModelPricing, - OrchestratorConfig, - OrchestratorEvent, - OutputValidator, - Plugin, - PluginInstallation, - PluginManifest, - PluginSource, - PluginTrustPolicy, - PoolStatus, - ProviderFactory, - ProviderResilienceConfig, - QualityGateDecision, - RAGConfig, - RAGContext, - RAGEntry, - RedactedThinkingBlock, - ReflectionConfig, - RetryPolicy, - RouteDecision, - Router, - RoutingConfig, - RoutingRule, - RunnerOptions, - RunnerStreamingConfig, - RunRecord, - RunResult, - RunRetentionPolicy, - RunStatus, - RunSummary, - SchedulingStrategy, - SectionOverflow, - SectionPriority, - SensorPhase, - SpanAttributes, - StopReason, - StopReasonCode, - StreamEvent, - StructuredAgentResult, - StructuredOutputConfig, - StructuredRunResult, - Task, - TaskStatus, - TeamConfig, - TeamRunResult, - TerminalRunStatus, - TextBlock, - ThinkingBlock, - TokenizerStrategy, - TokenUsage, - ToolCallRecord, - ToolDefinition, - ToolIdempotencyConfig, - ToolResult, - ToolResultBlock, - ToolSecurityPolicy, - ToolUseBlock, - ToolUseContext, - TraceConfig, - TrajectoryEvent, - TrajectoryEvidence, - TranscriptEvent, - TurnCheckpoint, - TurnHook, - ValidationResult, - VectorSearchResult, - VectorStore, - VerificationKind, - VerificationResult, - VerificationSensorConfig, - VerificationSeverity, - WakeCondition, -) -from anycode.verification import ( - QualityGate, - Sensor, - SensorContext, - SensorFn, - decide_gate, - pyright_sensor, - pytest_sensor, - ruff_sensor, - schema_sensor, -) -from anycode.viz.dag import render_dag -from anycode.viz.timeline import render_timeline -from anycode.workflow import ( - END, - START, - Command, - CompiledWorkflow, - Workflow, - WorkflowError, - WorkflowEvent, - WorkflowResult, -) +Every public symbol is importable straight from this package. Resolution is lazy: +the owning module is imported on first attribute access, so a program that builds +one agent never pays for vector stores, provider SDKs, or telemetry exporters. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from anycode._lazy import build_export_map, lazy_getattr + +_MODULE_EXPORTS: dict[str, tuple[str, ...]] = { + "anycode.backends": ( + "BACKEND_CONTRACT_VERSION", + "Admission", + "BackendCapabilities", + "BackendSnapshot", + "DaprDurabilityBackend", + "DaprHTTPTransport", + "DurabilityBackend", + "InMemoryDurabilityBackend", + "SQLiteDurabilityBackend", + "WorkItem", + "export_filesystem_run", + "import_backend_snapshot", + ), + "anycode.checkpoint.manager": ("CheckpointManager",), + "anycode.checkpoint.serializer": ("UnsupportedCheckpointVersionError",), + "anycode.checkpoint.store": ("FilesystemCheckpointStore",), + "anycode.collaboration.kv_store": ("InMemoryStore",), + "anycode.collaboration.message_bus": ("MessageBus",), + "anycode.collaboration.shared_mem": ("SharedMemory",), + "anycode.collaboration.team": ("Team",), + "anycode.config.loader": ( + "UnknownConfigFieldError", + "UnsupportedConfigVersionError", + ), + "anycode.constants": ( + "ORCH_EVENT_AGENT_COMPLETE", + "ORCH_EVENT_AGENT_START", + "ORCH_EVENT_BROADCAST", + "ORCH_EVENT_ERROR", + "ORCH_EVENT_MESSAGE", + "ORCH_EVENT_TASK_COMPLETE", + "ORCH_EVENT_TASK_START", + "QUEUE_EVENT_ALL_COMPLETE", + "QUEUE_EVENT_TASK_COMPLETE", + "QUEUE_EVENT_TASK_FAILED", + "QUEUE_EVENT_TASK_READY", + ), + "anycode.contracts": ( + "CONTRACT_SCHEMA_VERSION", + "RUN_TRANSITIONS", + "TERMINAL_STATES", + "Artifact", + "ArtifactAccessContext", + "ArtifactReadResult", + "ArtifactStore", + "ArtifactWriteRequest", + "ArtifactWriteResult", + "CapabilityDescriptor", + "Checkpoint", + "ContractError", + "Event", + "IncrementalRunProjector", + "InMemoryOperationStore", + "LocalArtifactStore", + "OperationClaim", + "OperationClaimResult", + "PolicyDecision", + "Result", + "RetryDecision", + "Run", + "RunProjection", + "acknowledge_cancellation", + "canonical_input_digest", + "contract_schema_bundle", + "decide_retry", + "evaluate_dependencies", + "is_valid_run_transition", + "project_run", + "request_cancellation", + "start_new_generation", + "transition_run", + "transition_task", + "validate_event_stream", + ), + "anycode.core.agent": ( + "Agent", + "AgentConfigError", + "compose_instructions", + ), + "anycode.core.context_artifacts": ( + "offload_text", + "restore_text", + ), + "anycode.core.context_manager": ( + "ContextManager", + "estimate_messages_tokens", + "rebuild_from_handoff", + ), + "anycode.core.lifecycle": ( + "ALL_PHASES", + "TERMINAL_PHASES", + "InvalidPhaseTransitionError", + "LifecycleEmitter", + "LifecycleListener", + "LoopDetector", + "fingerprint_call", + "is_valid_transition", + ), + "anycode.core.orchestrator": ( + "AnyCode", + "TaskSpec", + ), + "anycode.core.pool": ("AgentPool",), + "anycode.core.runner": ("AgentRunner",), + "anycode.core.scheduler": ("Scheduler",), + "anycode.core.session_chain": ( + "SessionChain", + "contract_status_summary", + "load_contract", + "save_contract", + ), + "anycode.cost": ( + "DEFAULT_PRICING", + "CostTracker", + "build_cost_report", + "calculate_cost", + "find_pricing", + ), + "anycode.crew": ( + "Crew", + "CrewError", + "CrewResult", + ), + "anycode.eval": ( + "compare_reports", + "detect_provider", + "load_scenario", + "load_scenarios", + "read_report", + "render_markdown", + "run_scenario", + "run_suite", + "write_report", + ), + "anycode.guardrails.budget": ( + "BudgetTracker", + "estimate_cost", + ), + "anycode.guardrails.hooks": ( + "HookRunner", + "LoggingHook", + ), + "anycode.guardrails.validators": ( + "BlocklistValidator", + "ContainsValidator", + "MaxLengthValidator", + "run_validators", + ), + "anycode.handoff.executor": ("HandoffExecutor",), + "anycode.handoff.protocol": ( + "build_handoff_system_prompt", + "build_handoff_user_message", + "trim_context", + ), + "anycode.handoff.tool": ("HANDOFF_TOOL_DEF",), + "anycode.harness": ( + "EvidenceCollector", + "EvidenceStore", + "HarnessRegistry", + "build_default_registry", + "build_manifest", + "categorize_event", + "categorize_run", + "diff_manifests", + "distill_evidence", + "load_manifest", + "save_manifest", + "write_evidence_bundle", + ), + "anycode.helpers.concurrency_gate": ("Semaphore",), + "anycode.helpers.usage_tracker": ( + "EMPTY_USAGE", + "merge_usage", + ), + "anycode.helpers.uuid7": ("uuid7",), + "anycode.hitl.approval": ("ApprovalManager",), + "anycode.hitl.channels": ( + "CallbackApprovalGate", + "StdinApprovalGate", + "WebhookApprovalGate", + ), + "anycode.hosting": ( + "A2A_AGENT_CARD_PATH", + "A2AAgentCard", + "HostLifecycle", + "build_deployment_agent_card", + ), + "anycode.identity": ( + "DelegationGrant", + "ExecutionContext", + "PolicyEnforcer", + "PolicyRequest", + ), + "anycode.mcp.bridge": ( + "mcp_tool_to_definition", + "schema_to_pydantic_model", + ), + "anycode.mcp.client": ("MCPClient",), + "anycode.memory.composite": ("CompositeMemory",), + "anycode.memory.factory": ( + "create_memory_store", + "create_vector_store", + ), + "anycode.memory.indexer": ("RAGIndexer",), + "anycode.memory.knowledge": ( + "KnowledgeEntry", + "KnowledgeStore", + "apply_retention", + "build_knowledge_tools", + ), + "anycode.memory.rag": ("RAGRetriever",), + "anycode.memory.vector_store": ("InMemoryVectorStore",), + "anycode.plugins": ( + "PluginBase", + "PluginRegistry", + "discover_entry_point_plugins", + "get_provider_factory", + "list_registered_providers", + "register_provider_factory", + ), + "anycode.providers.adapter": ("create_adapter",), + "anycode.providers.fake": ( + "FakeAdapter", + "FakeResponse", + ), + "anycode.providers.resilience": ( + "ProviderCapacityConfigurationError", + "ProviderCapacityError", + "ProviderCapacityLimiter", + "ProviderUnavailableError", + "ResilientAdapter", + ), + "anycode.reflection.critic": ( + "DEFAULT_CRITIC_PROMPT", + "LLMCritic", + ), + "anycode.reflection.evaluator": ("parse_critic_json",), + "anycode.reflection.loop": ("ReflectionLoop",), + "anycode.routing.classifier": ("classify_task",), + "anycode.routing.policy": ( + "ModelRoutingRequest", + "PolicyRouter", + "ProviderCapabilityDescriptor", + ), + "anycode.routing.router": ("DefaultRouter",), + "anycode.routing.rules": ( + "evaluate_rules", + "match_rule", + ), + "anycode.runstore.protocol": ( + "RunPayloadProtector", + "RunStore", + ), + "anycode.runstore.store": ( + "FilesystemRunStore", + "ProtectedPayloadError", + "UnsupportedRunStoreVersionError", + ), + "anycode.sandbox": ( + "CompanionSandboxAdapter", + "DaytonaSandboxProvider", + "E2BSandboxProvider", + "LangSmithSandboxProvider", + "ModalSandboxProvider", + "PolicySandboxProvider", + "RunloopSandboxProvider", + "SandboxCapabilities", + "SandboxCommand", + "SandboxProvider", + "SandboxSpec", + "VercelSandboxProvider", + "create_sandbox_provider", + ), + "anycode.schedule.scheduler": ( + "RunScheduler", + "SweepReport", + "sweep_once", + ), + "anycode.schedule.tasks": ( + "ScheduledTask", + "ScheduledTaskResult", + "run_scheduled_task", + ), + "anycode.security": ( + "REDACTED_SECRET", + "redact_sensitive", + "redact_text", + "safe_exception_message", + ), + "anycode.structured.output": ( + "STRUCTURED_OUTPUT_TOOL_NAME", + "build_retry_prompt", + "parse_structured_output", + "schema_to_openai_response_format", + "schema_to_tool_def", + ), + "anycode.tasks.queue": ("TaskQueue",), + "anycode.tasks.task": ( + "create_task", + "get_task_dependency_order", + "is_task_ready", + "validate_task_dependencies", + ), + "anycode.telemetry.events": ( + "EventEmitter", + "TelemetryEvent", + ), + "anycode.telemetry.genai": ( + "BoundedTelemetryBuffer", + "GenAITelemetryConfig", + "GenAITelemetryMapper", + "GenAITelemetryRecord", + ), + "anycode.telemetry.metrics": ( + "MetricsCollector", + "Timer", + ), + "anycode.telemetry.tracer": ( + "ConsoleExporter", + "JSONLExporter", + "OTLPExporter", + "Span", + "Tracer", + ), + "anycode.tools.built_in": ( + "BUILT_IN_TOOLS", + "register_built_in_tools", + ), + "anycode.tools.executor": ("ToolExecutor",), + "anycode.tools.function_tool": ( + "ToolDefinitionError", + "ToolSpec", + "as_tool_definition", + "build_tool_definition", + "builtin_tool_names", + "function_tool", + "resolve_tool_specs", + "tool", + ), + "anycode.tools.idempotency": ( + "IdempotencyClaim", + "InMemoryToolIdempotencyStore", + "SQLiteToolIdempotencyStore", + "ToolIdempotencyStore", + "create_tool_idempotency_store", + ), + "anycode.tools.registry": ( + "ToolRegistry", + "define_tool", + ), + "anycode.types": ( + "AcceptanceThresholds", + "AgentConfig", + "AgentInfo", + "AgentRunResult", + "AgentState", + "ApprovalConfig", + "ApprovalGate", + "ApprovalRequest", + "ApprovalResponse", + "BudgetSnapshot", + "BudgetStatus", + "CheckpointConfig", + "CheckpointData", + "CheckpointStore", + "ComplexityLevel", + "ContentBlock", + "ContextArtifact", + "ContextManifest", + "ContextMode", + "ContextPolicy", + "ContextPressure", + "ContextSectionBudget", + "ContextSectionInput", + "ContextSectionKind", + "ContextSectionUsage", + "ContextSource", + "ContextUsageReport", + "CostBreakdown", + "CostConfig", + "CostReport", + "CountingConfidence", + "Critic", + "CriticResult", + "DurabilityConfig", + "EvalReport", + "EvalScenario", + "EvalScenarioResult", + "EvidencePacket", + "EvidenceSeverity", + "EvolutionBlueprint", + "ExecutionPhase", + "FailureCategory", + "FailureMapEntry", + "GateOutcome", + "GoalContract", + "GoalCriterion", + "GuardrailConfig", + "Handoff", + "HandoffPolicy", + "HandoffRequest", + "HarnessChangeEdit", + "HarnessChangeManifest", + "HarnessChangeOutcome", + "HarnessChangePrediction", + "HarnessChangeStatus", + "HarnessComponent", + "HarnessComponentKind", + "HarnessComponentOwner", + "HarnessManifest", + "ImageBlock", + "LifecycleEvent", + "LLMAdapter", + "LLMChatOptions", + "LLMMessage", + "LLMResponse", + "LLMStreamOptions", + "LLMToolDef", + "MCPServerConfig", + "MCPToolInfo", + "MCPTrustPolicy", + "MemoryConfig", + "MemoryEntry", + "MemoryStore", + "MetaHarnessReport", + "ModelContextProfile", + "ModelPricing", + "OrchestratorConfig", + "OrchestratorEvent", + "OutputValidator", + "Plugin", + "PluginInstallation", + "PluginManifest", + "PluginSource", + "PluginTrustPolicy", + "PoolStatus", + "ProviderFactory", + "ProviderResilienceConfig", + "QualityGateDecision", + "RAGConfig", + "RAGContext", + "RAGEntry", + "RedactedThinkingBlock", + "ReflectionConfig", + "RetryPolicy", + "RouteDecision", + "Router", + "RoutingConfig", + "RoutingRule", + "RunnerOptions", + "RunnerStreamingConfig", + "RunRecord", + "RunResult", + "RunRetentionPolicy", + "RunStatus", + "RunSummary", + "SchedulingStrategy", + "SectionOverflow", + "SectionPriority", + "SensorPhase", + "SpanAttributes", + "StopReason", + "StopReasonCode", + "StreamEvent", + "StructuredAgentResult", + "StructuredOutputConfig", + "StructuredRunResult", + "Task", + "TaskStatus", + "TeamConfig", + "TeamRunResult", + "TerminalRunStatus", + "TextBlock", + "ThinkingBlock", + "TokenizerStrategy", + "TokenUsage", + "ToolCallRecord", + "ToolDefinition", + "ToolIdempotencyConfig", + "ToolResult", + "ToolResultBlock", + "ToolSecurityPolicy", + "ToolUseBlock", + "ToolUseContext", + "TraceConfig", + "TrajectoryEvent", + "TrajectoryEvidence", + "TranscriptEvent", + "TurnCheckpoint", + "TurnHook", + "ValidationResult", + "VectorSearchResult", + "VectorStore", + "VerificationKind", + "VerificationResult", + "VerificationSensorConfig", + "VerificationSeverity", + "WakeCondition", + ), + "anycode.verification": ( + "QualityGate", + "Sensor", + "SensorContext", + "SensorFn", + "decide_gate", + "pyright_sensor", + "pytest_sensor", + "ruff_sensor", + "schema_sensor", + ), + "anycode.viz.dag": ("render_dag",), + "anycode.viz.timeline": ("render_timeline",), + "anycode.workflow": ( + "END", + "START", + "Command", + "CompiledWorkflow", + "Workflow", + "WorkflowError", + "WorkflowEvent", + "WorkflowResult", + ), +} + +_ALIASES: dict[str, tuple[str, str]] = { + "SemanticMessage": ("anycode.contracts", "Message"), + "SemanticRetryPolicy": ("anycode.contracts", "RetryPolicy"), + "SemanticTask": ("anycode.contracts", "Task"), + "SemanticVerificationResult": ("anycode.contracts", "VerificationResult"), + "stop_reasons": ("anycode.core", "stop_reason"), + "mcp_discover_and_register": ("anycode.mcp.bridge", "discover_and_register"), + "mcp_validate_server_config": ("anycode.mcp.config", "validate_server_config"), +} + +_EXPORTS: dict[str, tuple[str, str]] = build_export_map(_MODULE_EXPORTS, _ALIASES) + + +def __getattr__(name: str) -> Any: + return lazy_getattr(__name__, name, _EXPORTS, globals()) + + +def __dir__() -> list[str]: + return sorted(__all__) + + +if TYPE_CHECKING: # keeps every symbol statically resolvable for type checkers and IDEs + from anycode.backends import ( + BACKEND_CONTRACT_VERSION, + Admission, + BackendCapabilities, + BackendSnapshot, + DaprDurabilityBackend, + DaprHTTPTransport, + DurabilityBackend, + InMemoryDurabilityBackend, + SQLiteDurabilityBackend, + WorkItem, + export_filesystem_run, + import_backend_snapshot, + ) + from anycode.checkpoint.manager import CheckpointManager + from anycode.checkpoint.serializer import UnsupportedCheckpointVersionError + from anycode.checkpoint.store import FilesystemCheckpointStore + from anycode.collaboration.kv_store import InMemoryStore + from anycode.collaboration.message_bus import MessageBus + from anycode.collaboration.shared_mem import SharedMemory + from anycode.collaboration.team import Team + from anycode.config.loader import UnknownConfigFieldError, UnsupportedConfigVersionError + from anycode.constants import ( + ORCH_EVENT_AGENT_COMPLETE, + ORCH_EVENT_AGENT_START, + ORCH_EVENT_BROADCAST, + ORCH_EVENT_ERROR, + ORCH_EVENT_MESSAGE, + ORCH_EVENT_TASK_COMPLETE, + ORCH_EVENT_TASK_START, + QUEUE_EVENT_ALL_COMPLETE, + QUEUE_EVENT_TASK_COMPLETE, + QUEUE_EVENT_TASK_FAILED, + QUEUE_EVENT_TASK_READY, + ) + from anycode.contracts import ( + CONTRACT_SCHEMA_VERSION, + RUN_TRANSITIONS, + TERMINAL_STATES, + Artifact, + ArtifactAccessContext, + ArtifactReadResult, + ArtifactStore, + ArtifactWriteRequest, + ArtifactWriteResult, + CapabilityDescriptor, + Checkpoint, + ContractError, + Event, + IncrementalRunProjector, + InMemoryOperationStore, + LocalArtifactStore, + OperationClaim, + OperationClaimResult, + PolicyDecision, + Result, + RetryDecision, + Run, + RunProjection, + acknowledge_cancellation, + canonical_input_digest, + contract_schema_bundle, + decide_retry, + evaluate_dependencies, + is_valid_run_transition, + project_run, + request_cancellation, + start_new_generation, + transition_run, + transition_task, + validate_event_stream, + ) + from anycode.contracts import Message as SemanticMessage + from anycode.contracts import RetryPolicy as SemanticRetryPolicy + from anycode.contracts import Task as SemanticTask + from anycode.contracts import VerificationResult as SemanticVerificationResult + from anycode.core import stop_reason as stop_reasons + from anycode.core.agent import Agent, AgentConfigError, compose_instructions + from anycode.core.context_artifacts import offload_text, restore_text + from anycode.core.context_manager import ContextManager, estimate_messages_tokens, rebuild_from_handoff + from anycode.core.lifecycle import ( + ALL_PHASES, + TERMINAL_PHASES, + InvalidPhaseTransitionError, + LifecycleEmitter, + LifecycleListener, + LoopDetector, + fingerprint_call, + is_valid_transition, + ) + from anycode.core.orchestrator import AnyCode, TaskSpec + from anycode.core.pool import AgentPool + from anycode.core.runner import AgentRunner + from anycode.core.scheduler import Scheduler + from anycode.core.session_chain import SessionChain, contract_status_summary, load_contract, save_contract + from anycode.cost import DEFAULT_PRICING, CostTracker, build_cost_report, calculate_cost, find_pricing + from anycode.crew import Crew, CrewError, CrewResult + from anycode.eval import ( + compare_reports, + detect_provider, + load_scenario, + load_scenarios, + read_report, + render_markdown, + run_scenario, + run_suite, + write_report, + ) + from anycode.guardrails.budget import BudgetTracker, estimate_cost + from anycode.guardrails.hooks import HookRunner, LoggingHook + from anycode.guardrails.validators import BlocklistValidator, ContainsValidator, MaxLengthValidator, run_validators + from anycode.handoff.executor import HandoffExecutor + from anycode.handoff.protocol import build_handoff_system_prompt, build_handoff_user_message, trim_context + from anycode.handoff.tool import HANDOFF_TOOL_DEF + from anycode.harness import ( + EvidenceCollector, + EvidenceStore, + HarnessRegistry, + build_default_registry, + build_manifest, + categorize_event, + categorize_run, + diff_manifests, + distill_evidence, + load_manifest, + save_manifest, + write_evidence_bundle, + ) + from anycode.helpers.concurrency_gate import Semaphore + from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage + from anycode.helpers.uuid7 import uuid7 + from anycode.hitl.approval import ApprovalManager + from anycode.hitl.channels import CallbackApprovalGate, StdinApprovalGate, WebhookApprovalGate + from anycode.hosting import A2A_AGENT_CARD_PATH, A2AAgentCard, HostLifecycle, build_deployment_agent_card + from anycode.identity import DelegationGrant, ExecutionContext, PolicyEnforcer, PolicyRequest + from anycode.mcp.bridge import discover_and_register as mcp_discover_and_register + from anycode.mcp.bridge import mcp_tool_to_definition, schema_to_pydantic_model + from anycode.mcp.client import MCPClient + from anycode.mcp.config import validate_server_config as mcp_validate_server_config + from anycode.memory.composite import CompositeMemory + from anycode.memory.factory import create_memory_store, create_vector_store + from anycode.memory.indexer import RAGIndexer + from anycode.memory.knowledge import KnowledgeEntry, KnowledgeStore, apply_retention, build_knowledge_tools + from anycode.memory.rag import RAGRetriever + from anycode.memory.vector_store import InMemoryVectorStore + from anycode.plugins import ( + PluginBase, + PluginRegistry, + discover_entry_point_plugins, + get_provider_factory, + list_registered_providers, + register_provider_factory, + ) + from anycode.providers.adapter import create_adapter + from anycode.providers.fake import FakeAdapter, FakeResponse + from anycode.providers.resilience import ( + ProviderCapacityConfigurationError, + ProviderCapacityError, + ProviderCapacityLimiter, + ProviderUnavailableError, + ResilientAdapter, + ) + from anycode.reflection.critic import DEFAULT_CRITIC_PROMPT, LLMCritic + from anycode.reflection.evaluator import parse_critic_json + from anycode.reflection.loop import ReflectionLoop + from anycode.routing.classifier import classify_task + from anycode.routing.policy import ModelRoutingRequest, PolicyRouter, ProviderCapabilityDescriptor + from anycode.routing.router import DefaultRouter + from anycode.routing.rules import evaluate_rules, match_rule + from anycode.runstore.protocol import RunPayloadProtector, RunStore + from anycode.runstore.store import FilesystemRunStore, ProtectedPayloadError, UnsupportedRunStoreVersionError + from anycode.sandbox import ( + CompanionSandboxAdapter, + DaytonaSandboxProvider, + E2BSandboxProvider, + LangSmithSandboxProvider, + ModalSandboxProvider, + PolicySandboxProvider, + RunloopSandboxProvider, + SandboxCapabilities, + SandboxCommand, + SandboxProvider, + SandboxSpec, + VercelSandboxProvider, + create_sandbox_provider, + ) + from anycode.schedule.scheduler import RunScheduler, SweepReport, sweep_once + from anycode.schedule.tasks import ScheduledTask, ScheduledTaskResult, run_scheduled_task + from anycode.security import REDACTED_SECRET, redact_sensitive, redact_text, safe_exception_message + from anycode.structured.output import ( + STRUCTURED_OUTPUT_TOOL_NAME, + build_retry_prompt, + parse_structured_output, + schema_to_openai_response_format, + schema_to_tool_def, + ) + from anycode.tasks.queue import TaskQueue + from anycode.tasks.task import create_task, get_task_dependency_order, is_task_ready, validate_task_dependencies + from anycode.telemetry.events import EventEmitter, TelemetryEvent + from anycode.telemetry.genai import BoundedTelemetryBuffer, GenAITelemetryConfig, GenAITelemetryMapper, GenAITelemetryRecord + from anycode.telemetry.metrics import MetricsCollector, Timer + from anycode.telemetry.tracer import ConsoleExporter, JSONLExporter, OTLPExporter, Span, Tracer + from anycode.tools.built_in import BUILT_IN_TOOLS, register_built_in_tools + from anycode.tools.executor import ToolExecutor + from anycode.tools.function_tool import ( + ToolDefinitionError, + ToolSpec, + as_tool_definition, + build_tool_definition, + builtin_tool_names, + function_tool, + resolve_tool_specs, + tool, + ) + from anycode.tools.idempotency import ( + IdempotencyClaim, + InMemoryToolIdempotencyStore, + SQLiteToolIdempotencyStore, + ToolIdempotencyStore, + create_tool_idempotency_store, + ) + from anycode.tools.registry import ToolRegistry, define_tool + from anycode.types import ( + AcceptanceThresholds, + AgentConfig, + AgentInfo, + AgentRunResult, + AgentState, + ApprovalConfig, + ApprovalGate, + ApprovalRequest, + ApprovalResponse, + BudgetSnapshot, + BudgetStatus, + CheckpointConfig, + CheckpointData, + CheckpointStore, + ComplexityLevel, + ContentBlock, + ContextArtifact, + ContextManifest, + ContextMode, + ContextPolicy, + ContextPressure, + ContextSectionBudget, + ContextSectionInput, + ContextSectionKind, + ContextSectionUsage, + ContextSource, + ContextUsageReport, + CostBreakdown, + CostConfig, + CostReport, + CountingConfidence, + Critic, + CriticResult, + DurabilityConfig, + EvalReport, + EvalScenario, + EvalScenarioResult, + EvidencePacket, + EvidenceSeverity, + EvolutionBlueprint, + ExecutionPhase, + FailureCategory, + FailureMapEntry, + GateOutcome, + GoalContract, + GoalCriterion, + GuardrailConfig, + Handoff, + HandoffPolicy, + HandoffRequest, + HarnessChangeEdit, + HarnessChangeManifest, + HarnessChangeOutcome, + HarnessChangePrediction, + HarnessChangeStatus, + HarnessComponent, + HarnessComponentKind, + HarnessComponentOwner, + HarnessManifest, + ImageBlock, + LifecycleEvent, + LLMAdapter, + LLMChatOptions, + LLMMessage, + LLMResponse, + LLMStreamOptions, + LLMToolDef, + MCPServerConfig, + MCPToolInfo, + MCPTrustPolicy, + MemoryConfig, + MemoryEntry, + MemoryStore, + MetaHarnessReport, + ModelContextProfile, + ModelPricing, + OrchestratorConfig, + OrchestratorEvent, + OutputValidator, + Plugin, + PluginInstallation, + PluginManifest, + PluginSource, + PluginTrustPolicy, + PoolStatus, + ProviderFactory, + ProviderResilienceConfig, + QualityGateDecision, + RAGConfig, + RAGContext, + RAGEntry, + RedactedThinkingBlock, + ReflectionConfig, + RetryPolicy, + RouteDecision, + Router, + RoutingConfig, + RoutingRule, + RunnerOptions, + RunnerStreamingConfig, + RunRecord, + RunResult, + RunRetentionPolicy, + RunStatus, + RunSummary, + SchedulingStrategy, + SectionOverflow, + SectionPriority, + SensorPhase, + SpanAttributes, + StopReason, + StopReasonCode, + StreamEvent, + StructuredAgentResult, + StructuredOutputConfig, + StructuredRunResult, + Task, + TaskStatus, + TeamConfig, + TeamRunResult, + TerminalRunStatus, + TextBlock, + ThinkingBlock, + TokenizerStrategy, + TokenUsage, + ToolCallRecord, + ToolDefinition, + ToolIdempotencyConfig, + ToolResult, + ToolResultBlock, + ToolSecurityPolicy, + ToolUseBlock, + ToolUseContext, + TraceConfig, + TrajectoryEvent, + TrajectoryEvidence, + TranscriptEvent, + TurnCheckpoint, + TurnHook, + ValidationResult, + VectorSearchResult, + VectorStore, + VerificationKind, + VerificationResult, + VerificationSensorConfig, + VerificationSeverity, + WakeCondition, + ) + from anycode.verification import ( + QualityGate, + Sensor, + SensorContext, + SensorFn, + decide_gate, + pyright_sensor, + pytest_sensor, + ruff_sensor, + schema_sensor, + ) + from anycode.viz.dag import render_dag + from anycode.viz.timeline import render_timeline + from anycode.workflow import END, START, Command, CompiledWorkflow, Workflow, WorkflowError, WorkflowEvent, WorkflowResult __all__ = [ - # Constants — event names "QUEUE_EVENT_TASK_READY", "QUEUE_EVENT_TASK_COMPLETE", "QUEUE_EVENT_TASK_FAILED", @@ -427,7 +957,6 @@ "ORCH_EVENT_MESSAGE", "ORCH_EVENT_ERROR", "ORCH_EVENT_BROADCAST", - # Core "AnyCode", "Agent", "Crew", @@ -447,7 +976,6 @@ "AgentPool", "Scheduler", "TaskSpec", - # Pluggable durability "BACKEND_CONTRACT_VERSION", "Admission", "BackendCapabilities", @@ -460,7 +988,6 @@ "WorkItem", "export_filesystem_run", "import_backend_snapshot", - # Preview semantic contracts "CONTRACT_SCHEMA_VERSION", "RUN_TRANSITIONS", "TERMINAL_STATES", @@ -500,7 +1027,6 @@ "transition_run", "transition_task", "validate_event_stream", - # Lifecycle "LifecycleEmitter", "LifecycleListener", "LoopDetector", @@ -510,18 +1036,15 @@ "fingerprint_call", "is_valid_transition", "stop_reasons", - # Adaptive context lifecycle "ContextManager", "estimate_messages_tokens", "rebuild_from_handoff", "offload_text", "restore_text", - # Data protection "REDACTED_SECRET", "redact_sensitive", "redact_text", "safe_exception_message", - # Verification & quality gates "QualityGate", "Sensor", "SensorContext", @@ -538,7 +1061,6 @@ "GateOutcome", "QualityGateDecision", "SensorPhase", - # Eval suite "EvalScenario", "EvalScenarioResult", "EvalReport", @@ -551,11 +1073,9 @@ "write_report", "render_markdown", "compare_reports", - # Providers "create_adapter", "FakeAdapter", "FakeResponse", - # Provider resilience "ResilientAdapter", "ProviderCapacityConfigurationError", "ProviderCapacityError", @@ -563,7 +1083,6 @@ "ProviderUnavailableError", "ProviderResilienceConfig", "RetryPolicy", - # Durable run store "FilesystemRunStore", "ProtectedPayloadError", "RunPayloadProtector", @@ -580,14 +1099,12 @@ "UnsupportedConfigVersionError", "UnsupportedRunStoreVersionError", "UnknownConfigFieldError", - # Session chaining "SessionChain", "GoalContract", "GoalCriterion", "load_contract", "save_contract", "contract_status_summary", - # Scheduling / watchdogs "RunScheduler", "SweepReport", "sweep_once", @@ -595,26 +1112,22 @@ "ScheduledTaskResult", "run_scheduled_task", "WakeCondition", - # Tiered memory "KnowledgeStore", "KnowledgeEntry", "build_knowledge_tools", "apply_retention", "create_memory_store", "create_vector_store", - # MCP "MCPClient", "mcp_discover_and_register", "mcp_tool_to_definition", "schema_to_pydantic_model", "mcp_validate_server_config", - # Handoff "HandoffExecutor", "HANDOFF_TOOL_DEF", "build_handoff_system_prompt", "build_handoff_user_message", "trim_context", - # Routing "DefaultRouter", "ModelRoutingRequest", "PolicyRouter", @@ -622,28 +1135,22 @@ "classify_task", "evaluate_rules", "match_rule", - # Collaboration "Team", "MessageBus", "SharedMemory", "InMemoryStore", - # Memory "CompositeMemory", "InMemoryVectorStore", - # Checkpoint "CheckpointManager", "FilesystemCheckpointStore", - # HITL "ApprovalManager", "CallbackApprovalGate", "StdinApprovalGate", "WebhookApprovalGate", - # Execution identity and policy "DelegationGrant", "ExecutionContext", "PolicyEnforcer", "PolicyRequest", - # Sandboxes "CompanionSandboxAdapter", "DaytonaSandboxProvider", "E2BSandboxProvider", @@ -657,18 +1164,15 @@ "SandboxSpec", "VercelSandboxProvider", "create_sandbox_provider", - # Managed hosting "A2A_AGENT_CARD_PATH", "A2AAgentCard", "HostLifecycle", "build_deployment_agent_card", - # Tasks "TaskQueue", "create_task", "is_task_ready", "get_task_dependency_order", "validate_task_dependencies", - # Tools "ToolRegistry", "ToolExecutor", "tool", @@ -687,12 +1191,10 @@ "define_tool", "BUILT_IN_TOOLS", "register_built_in_tools", - # Helpers "Semaphore", "EMPTY_USAGE", "merge_usage", "uuid7", - # Telemetry "Tracer", "Span", "ConsoleExporter", @@ -706,7 +1208,6 @@ "GenAITelemetryConfig", "GenAITelemetryMapper", "GenAITelemetryRecord", - # Guardrails "BudgetTracker", "estimate_cost", "HookRunner", @@ -715,13 +1216,11 @@ "MaxLengthValidator", "ContainsValidator", "BlocklistValidator", - # Structured output "STRUCTURED_OUTPUT_TOOL_NAME", "schema_to_tool_def", "schema_to_openai_response_format", "parse_structured_output", "build_retry_prompt", - # Types "ContentBlock", "TextBlock", "ToolUseBlock", @@ -771,7 +1270,6 @@ "HandoffRequest", "Handoff", "HandoffPolicy", - # Plugin ecosystem "Plugin", "PluginBase", "PluginInstallation", @@ -824,7 +1322,6 @@ "StructuredOutputConfig", "StructuredRunResult", "StructuredAgentResult", - # Cost "CostTracker", "build_cost_report", "DEFAULT_PRICING", @@ -834,7 +1331,6 @@ "CostReport", "CostBreakdown", "ModelPricing", - # Reflection "LLMCritic", "ReflectionLoop", "parse_critic_json", @@ -842,16 +1338,13 @@ "ReflectionConfig", "Critic", "CriticResult", - # RAG "RAGRetriever", "RAGIndexer", "RAGConfig", "RAGContext", "RAGEntry", - # Visualization "render_dag", "render_timeline", - # Harness "AcceptanceThresholds", "EvidencePacket", "EvidenceSeverity", diff --git a/src/anycode/_lazy.py b/src/anycode/_lazy.py new file mode 100644 index 0000000..c459f5c --- /dev/null +++ b/src/anycode/_lazy.py @@ -0,0 +1,63 @@ +"""Lazy attribute resolution for the top-level package. + +Importing ``anycode`` used to pull in every subsystem — vector stores, redis, boto3, +OpenTelemetry, provider SDKs — whether a program touched them or not. Exports are +resolved on first access instead, then cached into the module namespace so repeat +lookups are a plain dict hit. +""" + +from __future__ import annotations + +import difflib +import importlib +from collections.abc import Mapping +from typing import Any + +MAX_SUGGESTIONS = 3 +SUGGESTION_CUTOFF = 0.6 + + +def build_export_map( + module_exports: Mapping[str, tuple[str, ...]], + aliases: Mapping[str, tuple[str, str]] | None = None, +) -> dict[str, tuple[str, str]]: + """Flatten ``{module: (name, ...)}`` plus ``{alias: (module, original)}`` into ``{name: (module, attribute)}``.""" + exports: dict[str, tuple[str, str]] = {} + for module, names in module_exports.items(): + for name in names: + exports[name] = (module, name) + if aliases: + exports.update(aliases) + return exports + + +def lazy_getattr( + package: str, + name: str, + exports: Mapping[str, tuple[str, str]], + namespace: dict[str, Any], +) -> Any: + """Resolve *name* from *exports*, caching the result into *namespace*.""" + try: + module_name, attribute = exports[name] + except KeyError: + raise AttributeError(_unknown_attribute_message(package, name, exports)) from None + + module = importlib.import_module(module_name) + try: + value = getattr(module, attribute) + except AttributeError: + raise AttributeError( + f"{package}.{name} is declared as {module_name}.{attribute}, but that module has no such attribute. " + "This is a packaging bug — please report it." + ) from None + + namespace[name] = value + return value + + +def _unknown_attribute_message(package: str, name: str, exports: Mapping[str, tuple[str, str]]) -> str: + close = difflib.get_close_matches(name, exports, n=MAX_SUGGESTIONS, cutoff=SUGGESTION_CUTOFF) + if close: + return f"module '{package}' has no attribute '{name}'. Did you mean: {', '.join(close)}?" + return f"module '{package}' has no attribute '{name}'. Run `anycode api` or see dir(anycode) for the public surface." diff --git a/src/anycode/core/__init__.py b/src/anycode/core/__init__.py index 2650c45..d902b7d 100644 --- a/src/anycode/core/__init__.py +++ b/src/anycode/core/__init__.py @@ -1,7 +1,48 @@ -from anycode.core.agent import Agent -from anycode.core.orchestrator import AnyCode, TaskSpec -from anycode.core.pool import AgentPool -from anycode.core.runner import AgentRunner -from anycode.core.scheduler import Scheduler +"""Agent runtime, orchestration, pooling, and scheduling. -__all__ = ["Agent", "AgentRunner", "AgentPool", "AnyCode", "TaskSpec", "Scheduler"] +Exports resolve lazily so importing an Agent does not pull in the orchestrator and +everything it depends on.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from anycode._lazy import build_export_map, lazy_getattr + +_EXPORTS = build_export_map( + { + "anycode.core.agent": ("Agent",), + "anycode.core.orchestrator": ( + "AnyCode", + "TaskSpec", + ), + "anycode.core.pool": ("AgentPool",), + "anycode.core.runner": ("AgentRunner",), + "anycode.core.scheduler": ("Scheduler",), + }, +) + + +def __getattr__(name: str) -> Any: + return lazy_getattr(__name__, name, _EXPORTS, globals()) + + +def __dir__() -> list[str]: + return sorted(__all__) + + +if TYPE_CHECKING: + from anycode.core.agent import Agent + from anycode.core.orchestrator import AnyCode, TaskSpec + from anycode.core.pool import AgentPool + from anycode.core.runner import AgentRunner + from anycode.core.scheduler import Scheduler + +__all__ = [ + "Agent", + "AgentRunner", + "AgentPool", + "AnyCode", + "TaskSpec", + "Scheduler", +] diff --git a/src/anycode/core/orchestrator.py b/src/anycode/core/orchestrator.py index 1ef1717..8bfdf27 100644 --- a/src/anycode/core/orchestrator.py +++ b/src/anycode/core/orchestrator.py @@ -32,8 +32,6 @@ from anycode.handoff.tool import HANDOFF_TOOL_DEF from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage from anycode.hitl.approval import ApprovalManager -from anycode.mcp.bridge import discover_and_register -from anycode.mcp.client import MCPClient from anycode.memory.factory import create_vector_store from anycode.memory.indexer import RAGIndexer from anycode.memory.rag import RAGRetriever @@ -210,6 +208,10 @@ async def connect_mcp_servers(self) -> None: if not self._config.mcp_servers: return + # Imported here so building an orchestrator never loads the optional MCP SDK. + from anycode.mcp.bridge import discover_and_register + from anycode.mcp.client import MCPClient + for server_config in self._config.mcp_servers: if server_config.name in self._mcp_clients: continue diff --git a/src/anycode/helpers/__init__.py b/src/anycode/helpers/__init__.py index d718fe1..82a7d36 100644 --- a/src/anycode/helpers/__init__.py +++ b/src/anycode/helpers/__init__.py @@ -1,5 +1,36 @@ -from anycode.helpers.concurrency_gate import Semaphore -from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage -from anycode.helpers.uuid7 import uuid7 +"""Small shared utilities. -__all__ = ["Semaphore", "EMPTY_USAGE", "merge_usage", "uuid7"] +Exports resolve lazily: ``usage_tracker`` depends on ``anycode.types``, which depends on +``anycode.identity`` and ``anycode.contracts``, which depend back on this package. +Re-exporting eagerly closes that loop and makes ``import anycode.types`` fail on its own. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from anycode._lazy import build_export_map, lazy_getattr + +_EXPORTS = build_export_map( + { + "anycode.helpers.concurrency_gate": ("Semaphore",), + "anycode.helpers.usage_tracker": ("EMPTY_USAGE", "merge_usage"), + "anycode.helpers.uuid7": ("uuid7",), + } +) + + +def __getattr__(name: str) -> Any: + return lazy_getattr(__name__, name, _EXPORTS, globals()) + + +def __dir__() -> list[str]: + return sorted(__all__) + + +if TYPE_CHECKING: + from anycode.helpers.concurrency_gate import Semaphore + from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage + from anycode.helpers.uuid7 import uuid7 + +__all__ = ["EMPTY_USAGE", "Semaphore", "merge_usage", "uuid7"] diff --git a/src/anycode/mcp/__init__.py b/src/anycode/mcp/__init__.py index 06a002c..7d5ce8e 100644 --- a/src/anycode/mcp/__init__.py +++ b/src/anycode/mcp/__init__.py @@ -1,8 +1,38 @@ -"""MCP (Model Context Protocol) integration for AnyCode.""" +"""Model Context Protocol client and tool bridge. -from anycode.mcp.bridge import discover_and_register, mcp_tool_to_definition, schema_to_pydantic_model -from anycode.mcp.client import MCPClient -from anycode.mcp.config import validate_server_config +Exports resolve lazily so the optional `mcp` SDK is imported only when used.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from anycode._lazy import build_export_map, lazy_getattr + +_EXPORTS = build_export_map( + { + "anycode.mcp.bridge": ( + "discover_and_register", + "mcp_tool_to_definition", + "schema_to_pydantic_model", + ), + "anycode.mcp.client": ("MCPClient",), + "anycode.mcp.config": ("validate_server_config",), + }, +) + + +def __getattr__(name: str) -> Any: + return lazy_getattr(__name__, name, _EXPORTS, globals()) + + +def __dir__() -> list[str]: + return sorted(__all__) + + +if TYPE_CHECKING: + from anycode.mcp.bridge import discover_and_register, mcp_tool_to_definition, schema_to_pydantic_model + from anycode.mcp.client import MCPClient + from anycode.mcp.config import validate_server_config __all__ = [ "MCPClient", diff --git a/src/anycode/memory/__init__.py b/src/anycode/memory/__init__.py index d86336f..52cdf89 100644 --- a/src/anycode/memory/__init__.py +++ b/src/anycode/memory/__init__.py @@ -1,8 +1,55 @@ -"""Pluggable memory backends for persistent and semantic storage.""" +"""Pluggable memory backends for persistent and semantic storage. -from anycode.memory.composite import CompositeMemory -from anycode.memory.factory import create_memory_store -from anycode.memory.vector_store import InMemoryVectorStore +Exports resolve lazily. Optional backends appear in ``__all__`` only when their +dependency is installed, decided with ``find_spec`` — importing chromadb or redis +just to find out whether to mention them costs more than a second. +""" + +from __future__ import annotations + +from importlib.util import find_spec +from typing import TYPE_CHECKING, Any + +from anycode._lazy import build_export_map, lazy_getattr + +# (exported name, module, distribution to probe, extras group) +_OPTIONAL_BACKENDS: tuple[tuple[str, str, str, str], ...] = ( + ("SQLiteStore", "anycode.memory.sqlite_store", "aiosqlite", "persistence"), + ("RedisStore", "anycode.memory.redis_store", "redis", "redis"), + ("ChromaDBVectorStore", "anycode.memory.chromadb_store", "chromadb", "vector"), +) + +_EXPORTS = build_export_map( + { + "anycode.memory.composite": ("CompositeMemory",), + "anycode.memory.factory": ("create_memory_store",), + "anycode.memory.vector_store": ("InMemoryVectorStore",), + **{module: (name,) for name, module, _dependency, _extra in _OPTIONAL_BACKENDS}, + } +) + + +def __getattr__(name: str) -> Any: + for export_name, _module, dependency, extra in _OPTIONAL_BACKENDS: + if name == export_name and find_spec(dependency) is None: + raise AttributeError(f"{name} requires the '{extra}' extra. Install it with: uv add 'anycode-py[{extra}]'") + return lazy_getattr(__name__, name, _EXPORTS, globals()) + + +def __dir__() -> list[str]: + return sorted(__all__) + + +if TYPE_CHECKING: + # Redundant aliases mark these as deliberate re-exports; the optional backends are + # reachable as attributes but stay out of __all__ so `import *` never trips over a + # missing extra. + from anycode.memory.chromadb_store import ChromaDBVectorStore as ChromaDBVectorStore + from anycode.memory.composite import CompositeMemory + from anycode.memory.factory import create_memory_store + from anycode.memory.redis_store import RedisStore as RedisStore + from anycode.memory.sqlite_store import SQLiteStore as SQLiteStore + from anycode.memory.vector_store import InMemoryVectorStore __all__ = [ "CompositeMemory", @@ -10,24 +57,7 @@ "create_memory_store", ] -# Optional backends — re-exported when their dependencies are available. -try: - from anycode.memory.sqlite_store import SQLiteStore # noqa: F401 - - __all__.append("SQLiteStore") -except ImportError: - pass - -try: - from anycode.memory.redis_store import RedisStore # noqa: F401 - - __all__.append("RedisStore") -except ImportError: - pass - -try: - from anycode.memory.chromadb_store import ChromaDBVectorStore # noqa: F401 - __all__.append("ChromaDBVectorStore") -except ImportError: - pass +def available_backends() -> tuple[str, ...]: + """Optional backend names whose dependency is installed.""" + return tuple(name for name, _module, dependency, _extra in _OPTIONAL_BACKENDS if find_spec(dependency) is not None) diff --git a/src/anycode/telemetry/__init__.py b/src/anycode/telemetry/__init__.py index 692b835..fa70989 100644 --- a/src/anycode/telemetry/__init__.py +++ b/src/anycode/telemetry/__init__.py @@ -1,17 +1,65 @@ -"""AnyCode telemetry — OpenTelemetry-compatible tracing, metrics, and events.""" - -from anycode.telemetry.events import EventEmitter, TelemetryEvent -from anycode.telemetry.genai import ( - OTEL_GENAI_CONVENTION_SNAPSHOT, - BoundedTelemetryBuffer, - GenAITelemetryConfig, - GenAITelemetryMapper, - GenAITelemetryRecord, - TelemetryCaptureProfile, - sanitize_telemetry_attributes, +"""Tracing, metrics, and event emission. + +Exports resolve lazily so the optional OpenTelemetry SDK is imported only when used.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from anycode._lazy import build_export_map, lazy_getattr + +_EXPORTS = build_export_map( + { + "anycode.telemetry.events": ( + "EventEmitter", + "TelemetryEvent", + ), + "anycode.telemetry.genai": ( + "OTEL_GENAI_CONVENTION_SNAPSHOT", + "BoundedTelemetryBuffer", + "GenAITelemetryConfig", + "GenAITelemetryMapper", + "GenAITelemetryRecord", + "TelemetryCaptureProfile", + "sanitize_telemetry_attributes", + ), + "anycode.telemetry.metrics": ( + "MetricsCollector", + "Timer", + ), + "anycode.telemetry.tracer": ( + "ConsoleExporter", + "JSONLExporter", + "OTLPExporter", + "Span", + "SpanExporter", + "Tracer", + ), + }, ) -from anycode.telemetry.metrics import MetricsCollector, Timer -from anycode.telemetry.tracer import ConsoleExporter, JSONLExporter, OTLPExporter, Span, SpanExporter, Tracer + + +def __getattr__(name: str) -> Any: + return lazy_getattr(__name__, name, _EXPORTS, globals()) + + +def __dir__() -> list[str]: + return sorted(__all__) + + +if TYPE_CHECKING: + from anycode.telemetry.events import EventEmitter, TelemetryEvent + from anycode.telemetry.genai import ( + OTEL_GENAI_CONVENTION_SNAPSHOT, + BoundedTelemetryBuffer, + GenAITelemetryConfig, + GenAITelemetryMapper, + GenAITelemetryRecord, + TelemetryCaptureProfile, + sanitize_telemetry_attributes, + ) + from anycode.telemetry.metrics import MetricsCollector, Timer + from anycode.telemetry.tracer import ConsoleExporter, JSONLExporter, OTLPExporter, Span, SpanExporter, Tracer __all__ = [ "ConsoleExporter", diff --git a/tests/test_mcp.py b/tests/test_mcp.py index 8d91b08..e9ba671 100644 --- a/tests/test_mcp.py +++ b/tests/test_mcp.py @@ -10,7 +10,7 @@ from pydantic import BaseModel from anycode import AgentConfig, AnyCode -from anycode.core import orchestrator as orchestrator_module +from anycode.mcp import bridge as mcp_bridge_module from anycode.mcp import client as mcp_client_module from anycode.mcp.bridge import _build_tool_name, discover_and_register, mcp_tool_to_definition, schema_to_pydantic_model from anycode.mcp.client import MCPClient @@ -308,8 +308,8 @@ async def register_tool(_client: object, _server_name: str, registry: ToolRegist registry.register(tool) return [tool.name] - monkeypatch.setattr(orchestrator_module, "MCPClient", MagicMock(return_value=client)) - monkeypatch.setattr(orchestrator_module, "discover_and_register", register_tool) + monkeypatch.setattr(mcp_client_module, "MCPClient", MagicMock(return_value=client)) + monkeypatch.setattr(mcp_bridge_module, "discover_and_register", register_tool) config = AgentConfig(name="configured", model="fake", provider="openai", tools=[], mcp_servers=["alpha"]) engine = AnyCode( @@ -339,9 +339,9 @@ async def test_failed_discovery_disconnects_client(self, monkeypatch: pytest.Mon client.connect = AsyncMock() client.disconnect = AsyncMock() - monkeypatch.setattr(orchestrator_module, "MCPClient", MagicMock(return_value=client)) + monkeypatch.setattr(mcp_client_module, "MCPClient", MagicMock(return_value=client)) monkeypatch.setattr( - orchestrator_module, + mcp_bridge_module, "discover_and_register", AsyncMock(side_effect=RuntimeError("discovery failed")), ) @@ -377,8 +377,8 @@ async def register_tool(_client: object, _server_name: str, registry: ToolRegist return [tool.name] attach = MagicMock(side_effect=[RuntimeError("attachment failed"), None]) - monkeypatch.setattr(orchestrator_module, "MCPClient", MagicMock(return_value=client)) - monkeypatch.setattr(orchestrator_module, "discover_and_register", register_tool) + monkeypatch.setattr(mcp_client_module, "MCPClient", MagicMock(return_value=client)) + monkeypatch.setattr(mcp_bridge_module, "discover_and_register", register_tool) engine = AnyCode( { @@ -407,9 +407,9 @@ async def test_cancelled_connection_preserves_cancellation_when_cleanup_fails(se client = MagicMock() client.connect = AsyncMock() client.disconnect = AsyncMock(side_effect=RuntimeError("cleanup failed")) - monkeypatch.setattr(orchestrator_module, "MCPClient", MagicMock(return_value=client)) + monkeypatch.setattr(mcp_client_module, "MCPClient", MagicMock(return_value=client)) monkeypatch.setattr( - orchestrator_module, + mcp_bridge_module, "discover_and_register", AsyncMock(side_effect=asyncio.CancelledError), ) diff --git a/tests/test_public_api.py b/tests/test_public_api.py new file mode 100644 index 0000000..773d80c --- /dev/null +++ b/tests/test_public_api.py @@ -0,0 +1,107 @@ +"""Guards for the lazily-resolved public API surface.""" + +from __future__ import annotations + +import subprocess +import sys + +import pytest + +import anycode +from anycode._lazy import build_export_map, lazy_getattr + +# Ceilings for a bare `import anycode`. Generous enough to absorb a slow CI machine, +# tight enough that eagerly importing a subsystem again would trip them. +MAX_IMPORT_SECONDS = 1.0 +MAX_IMPORTED_MODULES = 250 + +HEAVY_DEPENDENCIES = ("chromadb", "redis", "boto3", "opentelemetry", "typer", "mcp", "anthropic", "openai", "yaml", "numpy") + + +def test_every_exported_name_is_mapped() -> None: + assert set(anycode.__all__) == set(anycode._EXPORTS) + + +def test_all_has_no_duplicates() -> None: + assert len(anycode.__all__) == len(set(anycode.__all__)) + + +def test_every_exported_name_resolves() -> None: + unresolved = [name for name in anycode.__all__ if getattr(anycode, name, None) is None] + assert unresolved == [] + + +def test_dir_lists_the_public_surface() -> None: + assert dir(anycode) == sorted(anycode.__all__) + + +def test_unknown_attribute_suggests_a_close_match() -> None: + with pytest.raises(AttributeError, match="Did you mean: Agent"): + anycode.Agnet # type: ignore[attr-defined] # noqa: B018 + + +def test_unknown_attribute_without_a_match_points_at_the_api_command() -> None: + with pytest.raises(AttributeError, match="anycode api"): + anycode.zzzzzzzz # type: ignore[attr-defined] # noqa: B018 + + +def test_resolution_is_cached_into_the_module_namespace() -> None: + namespace: dict[str, object] = {} + exports = build_export_map({"anycode.types": ("TokenUsage",)}) + first = lazy_getattr("anycode", "TokenUsage", exports, namespace) + assert namespace["TokenUsage"] is first + assert lazy_getattr("anycode", "TokenUsage", exports, namespace) is first + + +def test_build_export_map_applies_aliases() -> None: + exports = build_export_map({"anycode.types": ("TokenUsage",)}, {"Usage": ("anycode.types", "TokenUsage")}) + assert exports["Usage"] == ("anycode.types", "TokenUsage") + assert exports["TokenUsage"] == ("anycode.types", "TokenUsage") + + +def test_broken_mapping_reports_a_packaging_bug() -> None: + exports = build_export_map({"anycode.types": ("NotARealSymbol",)}) + with pytest.raises(AttributeError, match="packaging bug"): + lazy_getattr("anycode", "NotARealSymbol", exports, {}) + + +def test_star_import_binds_every_public_name() -> None: + namespace: dict[str, object] = {} + exec("from anycode import *", namespace) # noqa: S102 - exercising the real import path + for name in anycode.__all__: + assert name in namespace + + +def _probe(expression: str) -> str: + result = subprocess.run( + [sys.executable, "-c", expression], + capture_output=True, + text=True, + check=False, + ) + assert result.returncode == 0, result.stderr + return result.stdout.strip() + + +def test_bare_import_is_cheap() -> None: + reported = _probe("import time, sys; start = time.perf_counter(); import anycode; print(f'{time.perf_counter() - start:.4f} {len(sys.modules)}')") + elapsed, modules = reported.split() + assert float(elapsed) < MAX_IMPORT_SECONDS + assert int(modules) < MAX_IMPORTED_MODULES + + +def test_bare_import_pulls_no_optional_dependency() -> None: + reported = _probe(f"import sys, anycode; print(','.join(m for m in {HEAVY_DEPENDENCIES!r} if m in sys.modules))") + assert reported == "" + + +@pytest.mark.parametrize("symbol", ["Agent", "Crew", "Workflow", "AnyCode", "tool"]) +def test_core_symbols_pull_no_optional_dependency(symbol: str) -> None: + reported = _probe(f"import sys, anycode; anycode.{symbol}; print(','.join(m for m in {HEAVY_DEPENDENCIES!r} if m in sys.modules))") + assert reported == "" + + +def test_submodules_import_standalone() -> None: + """Each of these closed an import cycle that the old eager package __init__ masked.""" + for module in ("anycode.types", "anycode.helpers", "anycode.contracts", "anycode.identity", "anycode.core", "anycode.memory"): + _probe(f"import {module}") From b1319bf6311f0d153826938c01cdbe36a23eab59 Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 06:30:26 +0500 Subject: [PATCH 06/11] feat(core): add planning, sub-agents, and workspace to Agent Long-horizon behavior arrives as three opt-in keywords on the existing Agent rather than a second agent type. A plain agent is untouched: every capability is inert unless switched on. Agent( name="researcher", instructions="...", tools=[search], planning=True, subagents=[SubAgentSpec(name="critic", instructions="...")], workspace="./.anycode/workspace", ) planning= registers write_todos, which returns the rendered checklist so the plan re-enters the context on every update, and exposes it as agent.todos. More than one in_progress step returns an error result telling the model to fix it -- a model mistake is not a program fault. subagents= registers a delegate tool. Each sub-agent is a full Agent built lazily, inheriting the parent's model, provider, security policy, and execution context. It runs on a fresh conversation, so only the task and the context the caller passes cross the boundary; sub-agents never receive delegate themselves, so depth is one by construction. Their token usage is merged into the parent's AgentRunResult. workspace= creates the directory and confines the file tools to it via the existing ToolSecurityPolicy, with shell access following whether bash was requested. An explicitly passed tool_security always wins. Each capability appends one prompt clause, snapshot-tested so prompt drift shows up as a reviewable diff. Also fixes Agent.call_tool, which could not invoke a side-effecting tool at all: it now supplies a fresh idempotency key when the arguments do not carry one. --- examples/48_long_horizon_agent.py | 96 ++++++++++ src/anycode/__init__.py | 9 + src/anycode/core/agent.py | 136 ++++++++++++++- src/anycode/tools/planning.py | 86 +++++++++ src/anycode/tools/subagent.py | 110 ++++++++++++ tests/test_agent_long_horizon.py | 281 ++++++++++++++++++++++++++++++ 6 files changed, 709 insertions(+), 9 deletions(-) create mode 100644 examples/48_long_horizon_agent.py create mode 100644 src/anycode/tools/planning.py create mode 100644 src/anycode/tools/subagent.py create mode 100644 tests/test_agent_long_horizon.py diff --git a/examples/48_long_horizon_agent.py b/examples/48_long_horizon_agent.py new file mode 100644 index 0000000..6f32c4b --- /dev/null +++ b/examples/48_long_horizon_agent.py @@ -0,0 +1,96 @@ +# Demo 48 — Long-Horizon Agent: Planning, Sub-Agents, and a Workspace +# Execute: uv run python examples/48_long_horizon_agent.py +# Requires: ANTHROPIC_API_KEY or OPENAI_API_KEY in the environment or .env. +# +# There is no separate "deep agent" type. Planning, delegation, and a confined +# workspace are opt-in keywords on the same Agent used everywhere else. + +import asyncio +import shutil +from pathlib import Path + +from dotenv import load_dotenv + +from anycode import Agent, SubAgentSpec, tool + +load_dotenv() + +WORKSPACE = Path(".anycode/example-48-workspace") + + +@tool +def lookup_spec(component: str) -> dict: + """Look up the (stubbed) published specification for a system component. + + Args: + component: Component name, e.g. "cache" or "queue". + """ + catalog = { + "cache": {"latency_p99_ms": 3, "eviction": "LRU", "max_entry_kb": 512}, + "queue": {"latency_p99_ms": 40, "delivery": "at-least-once", "max_message_kb": 256}, + } + return catalog.get(component.lower(), {"error": f"no spec for {component}"}) + + +researcher = Agent( + name="researcher", + instructions=( + "You produce short, factual engineering notes. Use lookup_spec for any component " + "figure — never invent numbers. Save your work to the workspace as you go." + ), + tools=[lookup_spec, "file_write", "file_read", "list_files"], + planning=True, + subagents=[ + SubAgentSpec( + name="reviewer", + instructions=( + "You are a blunt technical reviewer. Given a note, reply with at most two " + "sentences naming concrete problems, or the single word SOLID if there are none." + ), + ) + ], + workspace=WORKSPACE, + max_turns=18, + temperature=0, +) + + +async def main() -> None: + if WORKSPACE.exists(): + shutil.rmtree(WORKSPACE) + + print(f"{researcher!r}") + print(f"Workspace: {researcher.workspace}") + print(f"Tools: {', '.join(sorted(definition.name for definition in researcher.tools))}\n") + + result = await researcher.run( + "Write a short comparison note on the cache and queue components: look up both specs, " + "save the note to comparison.md in your workspace, have the reviewer critique it, and " + "revise once based on that critique. Finish by telling me the file path and the verdict." + ) + + print("Agent output\n" + "=" * 55) + print(result.output) + print("=" * 55) + + print("\nPlan as the agent last wrote it:") + for item in researcher.todos: + marker = {"completed": "[x]", "in_progress": "[>]", "pending": "[ ]"}[item.status] + print(f" {marker} {item.content}") + if not researcher.todos: + print(" (the agent finished without writing a plan)") + + print("\nWorkspace contents:") + for path in sorted(WORKSPACE.rglob("*")): + if path.is_file(): + print(f" {path.relative_to(WORKSPACE)} ({path.stat().st_size} bytes)") + + delegated = [call for call in result.tool_calls if call.tool_name == "delegate"] + print(f"\nSucceeded: {result.success}") + print(f"Tool calls: {len(result.tool_calls)} ({len(delegated)} delegated to a sub-agent)") + print(f"Tokens: {result.token_usage.input_tokens} in / {result.token_usage.output_tokens} out") + print(" (sub-agent usage is merged into the parent result)") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/src/anycode/__init__.py b/src/anycode/__init__.py index dbe0a40..33197d7 100644 --- a/src/anycode/__init__.py +++ b/src/anycode/__init__.py @@ -363,6 +363,8 @@ "ToolRegistry", "define_tool", ), + "anycode.tools.planning": ("TodoItem", "TodoStore", "build_todo_tool"), + "anycode.tools.subagent": ("SubAgentSpec", "build_delegate_tool"), "anycode.types": ( "AcceptanceThresholds", "AgentConfig", @@ -780,7 +782,9 @@ def __dir__() -> list[str]: ToolIdempotencyStore, create_tool_idempotency_store, ) + from anycode.tools.planning import TodoItem, TodoStore, build_todo_tool from anycode.tools.registry import ToolRegistry, define_tool + from anycode.tools.subagent import SubAgentSpec, build_delegate_tool from anycode.types import ( AcceptanceThresholds, AgentConfig, @@ -1189,6 +1193,11 @@ def __dir__() -> list[str]: "ToolIdempotencyStore", "create_tool_idempotency_store", "define_tool", + "TodoItem", + "TodoStore", + "build_todo_tool", + "SubAgentSpec", + "build_delegate_tool", "BUILT_IN_TOOLS", "register_built_in_tools", "Semaphore", diff --git a/src/anycode/core/agent.py b/src/anycode/core/agent.py index b66862e..c832c9b 100644 --- a/src/anycode/core/agent.py +++ b/src/anycode/core/agent.py @@ -4,6 +4,7 @@ import asyncio from collections.abc import AsyncGenerator, Iterator, Sequence +from pathlib import Path from pydantic import BaseModel @@ -12,6 +13,7 @@ from anycode.core.runner import AgentRunner from anycode.helpers.sync_runner import iterate_async_blocking, run_coroutine_blocking from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage +from anycode.helpers.uuid7 import uuid7 from anycode.identity import ExecutionContext from anycode.providers.adapter import create_adapter from anycode.security.redaction import safe_exception_message @@ -20,7 +22,9 @@ from anycode.tools.built_in import register_built_in_tools from anycode.tools.executor import ToolExecutor from anycode.tools.function_tool import ToolSpec, resolve_tool_specs +from anycode.tools.planning import TodoItem, TodoStore, build_todo_tool from anycode.tools.registry import ToolRegistry +from anycode.tools.subagent import SubAgentSpec, as_subagent_spec, build_delegate_tool from anycode.types import ( AgentConfig, AgentInfo, @@ -36,6 +40,7 @@ StreamEvent, StructuredAgentResult, TextBlock, + TokenUsage, ToolDefinition, ToolResult, ToolSecurityPolicy, @@ -67,6 +72,27 @@ ) +BASH_TOOL_NAME = "bash" + +PLANNING_CLAUSE = ( + "Before doing anything substantial, write a plan with the write_todos tool. Keep exactly one " + "step in_progress, mark steps completed as you finish them, and resend the whole plan on every " + "update. Re-read the returned checklist to stay oriented." +) + +DELEGATION_CLAUSE = ( + "Use the delegate tool for self-contained sub-tasks such as focused research, review, or " + "critique. A sub-agent starts from a blank conversation, so state the task in full and include " + "the background it needs. Do the integration and final answer yourself." +) + +WORKSPACE_CLAUSE = ( + "Your workspace is {workspace}. Write intermediate notes, drafts, and artifacts to files there " + "rather than carrying them in the conversation, and read them back when you need them. File " + "tools are confined to that directory." +) + + class AgentConfigError(ValueError): """Raised when agent construction arguments are contradictory or incomplete.""" @@ -148,8 +174,13 @@ def _wire_tools( tools: Sequence[ToolSpec] | None, registry: ToolRegistry | None, executor: ToolExecutor | None, + capability_tools: Sequence[ToolDefinition] = (), ) -> tuple[AgentConfig, ToolRegistry, ToolExecutor]: - """Build the registry/executor pair an agent needs when the caller did not supply one.""" + """Build the registry/executor pair an agent needs when the caller did not supply one. + + ``capability_tools`` are always registered and always allowed — they come from + capabilities the caller switched on (planning, delegation), not from ``tools=``. + """ if registry is None: registry = ToolRegistry() if tools is None: @@ -170,9 +201,43 @@ def _wire_tools( allowed = [*(config.tools or []), *(definition.name for definition in resolved)] config = config.model_copy(update={"tools": list(dict.fromkeys(allowed))}) + for definition in capability_tools: + if not registry.has(definition.name): + registry.register(definition) + if capability_tools and config.tools is not None: + allowed = [*config.tools, *(definition.name for definition in capability_tools)] + config = config.model_copy(update={"tools": list(dict.fromkeys(allowed))}) + return config, registry, executor or ToolExecutor(registry) +def _resolve_workspace(workspace: str | Path) -> Path: + path = Path(workspace).expanduser().resolve() + path.mkdir(parents=True, exist_ok=True) + return path + + +def _workspace_policy(path: Path, allow_shell: bool) -> ToolSecurityPolicy: + root = str(path) + return ToolSecurityPolicy(workspace_root=root, allowed_path_roots=(root,), allow_shell=allow_shell) + + +def _shell_is_requested(tools: Sequence[ToolSpec] | None, config_tools: list[str] | None) -> bool: + if tools is None: + return config_tools is None or BASH_TOOL_NAME in config_tools + return any(spec == BASH_TOOL_NAME or getattr(spec, "name", None) == BASH_TOOL_NAME for spec in tools) + + +def compose_capability_prompt(base: str | None, *, planning: bool, delegation: bool, workspace: Path | None) -> str | None: + """Append the clauses for whichever long-horizon capabilities are switched on.""" + clauses = [clause for enabled, clause in ((planning, PLANNING_CLAUSE), (delegation, DELEGATION_CLAUSE)) if enabled] + if workspace is not None: + clauses.append(WORKSPACE_CLAUSE.format(workspace=workspace)) + if not clauses: + return base + return "\n\n".join([*([base] if base else []), *clauses]) + + class Agent: """High-level agent with state management, conversation history, and streaming support.""" @@ -200,6 +265,9 @@ def __init__( tool_security: ToolSecurityPolicy | None = None, provider_resilience: ProviderResilienceConfig | None = None, execution_context: ExecutionContext | None = None, + planning: bool = False, + subagents: Sequence[SubAgentSpec | dict[str, object]] = (), + workspace: str | Path | None = None, tracer: Tracer | None = None, guardrail_config: GuardrailConfig | None = None, hooks: list[TurnHook] | None = None, @@ -259,10 +327,43 @@ def __init__( execution_context=execution_context, ) - typed_config, resolved_registry, resolved_executor = _wire_tools(typed_config, tools, tool_registry, tool_executor) + # Long-horizon capabilities. Each is inert unless switched on, so a plain agent's + # prompt and tool set are untouched. + self._todos = TodoStore() + self._delegated_usage = EMPTY_USAGE + subagent_specs = [as_subagent_spec(spec) for spec in subagents] + workspace_path = _resolve_workspace(workspace) if workspace is not None else None + + if workspace_path is not None and typed_config.tool_security is None: + allow_shell = _shell_is_requested(tools, typed_config.tools) + typed_config = typed_config.model_copy(update={"tool_security": _workspace_policy(workspace_path, allow_shell)}) + + capability_prompt = compose_capability_prompt( + typed_config.system_prompt, + planning=planning, + delegation=bool(subagent_specs), + workspace=workspace_path, + ) + if capability_prompt != typed_config.system_prompt: + typed_config = typed_config.model_copy(update={"system_prompt": capability_prompt}) + + capability_tools: list[ToolDefinition] = [] + if planning: + capability_tools.append(build_todo_tool(self._todos)) + if subagent_specs: + capability_tools.append(build_delegate_tool(subagent_specs, typed_config, record_usage=self._record_delegated_usage)) + + typed_config, resolved_registry, resolved_executor = _wire_tools( + typed_config, + tools, + tool_registry, + tool_executor, + capability_tools, + ) self.name = typed_config.name self.config = typed_config + self.workspace = workspace_path self._registry = resolved_registry self._executor = resolved_executor self._runner: AgentRunner | None = None @@ -274,6 +375,14 @@ def __init__( self._output_validators = output_validators self._output_schema = output_schema + def _record_delegated_usage(self, usage: TokenUsage) -> None: + self._delegated_usage = merge_usage(self._delegated_usage, usage) + + @property + def todos(self) -> tuple[TodoItem, ...]: + """The plan as the agent last wrote it. Empty unless ``planning=True``.""" + return self._todos.items + async def _get_runner(self) -> AgentRunner: if self._runner is not None: return self._runner @@ -367,15 +476,20 @@ def stream_sync(self, prompt: str) -> Iterator[StreamEvent]: async_call="async for event in agent.stream(...)", ) - async def call_tool(self, name: str, **arguments: object) -> ToolResult: + async def call_tool(self, name: str, /, **arguments: object) -> ToolResult: """Invoke one of this agent's tools directly, bypassing the LLM. - Useful for testing a tool under the same validation, security policy, and - idempotency rules the agent would apply. + Runs under the same validation, security policy, and idempotency rules the agent + would apply. A side-effecting tool gets a fresh idempotency key unless the + arguments already carry one, so a one-off call does not have to invent it. """ - return await self._executor.execute(name, dict(arguments), self.build_tool_context()) + definition = self._registry.get(name) + key: str | None = None + if definition is not None and definition.side_effecting and not arguments.get(definition.idempotency_key_field or ""): + key = str(uuid7()) + return await self._executor.execute(name, dict(arguments), self.build_tool_context(), idempotency_key=key) - def call_tool_sync(self, name: str, **arguments: object) -> ToolResult: + def call_tool_sync(self, name: str, /, **arguments: object) -> ToolResult: """Blocking form of :meth:`call_tool`.""" return run_coroutine_blocking( self.call_tool(name, **arguments), @@ -422,22 +536,26 @@ def get_tools(self) -> list[str]: async def _execute_run(self, messages: list[LLMMessage]) -> AgentRunResult: self._state = self._state.model_copy(update={"status": "running"}) + self._delegated_usage = EMPTY_USAGE collected_messages: list[LLMMessage] = [] try: runner = await self._get_runner() result = await runner.run(messages, on_message=lambda msg: collected_messages.append(msg)) + # Sub-agents bill through their own adapters, so their usage only reaches this + # result if it is folded in here. + total_usage = merge_usage(result.token_usage, self._delegated_usage) self._state = self._state.model_copy( update={ "status": "completed", "messages": [*self._state.messages, *collected_messages], - "token_usage": merge_usage(self._state.token_usage, result.token_usage), + "token_usage": merge_usage(self._state.token_usage, total_usage), } ) return AgentRunResult( success=result.stop_reason is None or result.stop_reason.code == "success", output=result.output, messages=result.messages, - token_usage=result.token_usage, + token_usage=total_usage, tool_calls=result.tool_calls, handoff_request=result.handoff_request, terminal_phase=result.terminal_phase, diff --git a/src/anycode/tools/planning.py b/src/anycode/tools/planning.py new file mode 100644 index 0000000..18bcc4c --- /dev/null +++ b/src/anycode/tools/planning.py @@ -0,0 +1,86 @@ +"""Explicit planning for long-horizon work. + +An agent writes its plan with ``write_todos`` and gets the rendered checklist back as the +tool result, so the plan re-enters the conversation on every update. That feedback loop is +what keeps a long run on track. +""" + +from __future__ import annotations + +from typing import Literal + +from pydantic import BaseModel, ConfigDict, Field + +from anycode.types import ToolDefinition, ToolResult, ToolUseContext + +TODO_TOOL_NAME = "write_todos" + +TodoStatus = Literal["pending", "in_progress", "completed"] + +_STATUS_MARKERS: dict[TodoStatus, str] = {"pending": "[ ]", "in_progress": "[>]", "completed": "[x]"} + + +class TodoItem(BaseModel): + """One step of an agent's plan.""" + + model_config = ConfigDict(frozen=True) + + content: str = Field(min_length=1, description="What this step accomplishes.") + status: TodoStatus = Field(default="pending", description='One of "pending", "in_progress", or "completed".') + + +class TodoWriteInput(BaseModel): + todos: list[TodoItem] = Field(description="The full plan. Always send every step, not just the ones that changed.") + + +class TodoStore: + """Holds the plan for one agent.""" + + def __init__(self) -> None: + self._items: tuple[TodoItem, ...] = () + + @property + def items(self) -> tuple[TodoItem, ...]: + return self._items + + def replace(self, items: list[TodoItem]) -> None: + self._items = tuple(items) + + def clear(self) -> None: + self._items = () + + def render(self) -> str: + if not self._items: + return "The plan is empty." + lines = [f"{_STATUS_MARKERS[item.status]} {item.content}" for item in self._items] + done = sum(1 for item in self._items if item.status == "completed") + return "\n".join([*lines, "", f"{done}/{len(self._items)} complete."]) + + +def build_todo_tool(store: TodoStore) -> ToolDefinition: + """Create a ``write_todos`` tool backed by *store*.""" + + async def execute(params: TodoWriteInput, _context: ToolUseContext) -> ToolResult: + in_progress = [item.content for item in params.todos if item.status == "in_progress"] + if len(in_progress) > 1: + return ToolResult( + data=( + f"Rejected: {len(in_progress)} steps are in_progress ({', '.join(in_progress)}). " + "Exactly one step may be in_progress at a time. Resend the plan with the others " + "marked pending or completed." + ), + is_error=True, + ) + store.replace(params.todos) + return ToolResult(data=store.render()) + + return ToolDefinition( + name=TODO_TOOL_NAME, + description=( + "Record or update your plan as a checklist. Call this before starting work and again " + "whenever a step changes state. Send the complete plan every time. Keep exactly one " + "step in_progress." + ), + input_model=TodoWriteInput, + execute=execute, + ) diff --git a/src/anycode/tools/subagent.py b/src/anycode/tools/subagent.py new file mode 100644 index 0000000..0e92cd9 --- /dev/null +++ b/src/anycode/tools/subagent.py @@ -0,0 +1,110 @@ +"""Scoped sub-agent delegation. + +A sub-agent runs on a fresh conversation: only the task text and the context the caller +chooses to pass cross the boundary. That isolation is the point — it keeps the parent's +context small while a focused agent does the narrow work. +""" + +from __future__ import annotations + +from collections.abc import Callable, Sequence +from typing import TYPE_CHECKING, Any + +from pydantic import BaseModel, ConfigDict, Field + +from anycode.helpers.usage_tracker import merge_usage +from anycode.types import AgentConfig, TokenUsage, ToolDefinition, ToolResult, ToolUseContext + +if TYPE_CHECKING: + from anycode.core.agent import Agent + +DELEGATE_TOOL_NAME = "delegate" + + +class SubAgentSpec(BaseModel): + """A focused agent the parent may delegate to.""" + + model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True) + + name: str = Field(min_length=1) + instructions: str = Field(min_length=1) + tools: tuple[Any, ...] = () + model: str | None = None + provider: str | None = None + max_turns: int | None = None + + +class DelegateInput(BaseModel): + agent: str = Field(description="Which sub-agent to hand the task to.") + task: str = Field(min_length=1, description="The complete task. The sub-agent sees none of your conversation.") + context: str | None = Field(default=None, description="Any background the sub-agent needs to do the task.") + + +def as_subagent_spec(spec: SubAgentSpec | dict[str, object]) -> SubAgentSpec: + return spec if isinstance(spec, SubAgentSpec) else SubAgentSpec.model_validate(spec) + + +def build_delegate_tool( + subagents: Sequence[SubAgentSpec], + parent: AgentConfig, + *, + record_usage: Callable[[TokenUsage], None] | None = None, +) -> ToolDefinition: + """Create a ``delegate`` tool over *subagents*, inheriting defaults from *parent*. + + Sub-agents never receive the delegate tool themselves, so delegation depth is one by + construction and a runaway fan-out is impossible. + """ + by_name = {spec.name: spec for spec in subagents} + if not by_name: + raise ValueError("build_delegate_tool needs at least one sub-agent specification.") + built: dict[str, Agent] = {} + + def _resolve(name: str) -> Agent: + if name not in built: + from anycode.core.agent import Agent + + spec = by_name[name] + built[name] = Agent( + name=spec.name, + model=spec.model or parent.model, + provider=spec.provider or parent.provider, + instructions=spec.instructions, + tools=list(spec.tools), + max_turns=spec.max_turns or parent.max_turns, + tool_security=parent.tool_security, + provider_resilience=parent.provider_resilience, + execution_context=parent.execution_context, + ) + return built[name] + + async def execute(params: DelegateInput, _context: ToolUseContext) -> ToolResult: + if params.agent not in by_name: + return ToolResult( + data=f'No sub-agent named "{params.agent}". Available: {", ".join(sorted(by_name))}.', + is_error=True, + ) + + prompt = f"{params.task}\n\nContext:\n{params.context}" if params.context else params.task + result = await _resolve(params.agent).run(prompt) + if record_usage is not None: + record_usage(result.token_usage) + if not result.success: + return ToolResult(data=f'Sub-agent "{params.agent}" failed: {result.output}', is_error=True) + return ToolResult(data=result.output) + + roster = "\n".join(f"- {spec.name}: {spec.instructions.splitlines()[0]}" for spec in subagents) + return ToolDefinition( + name=DELEGATE_TOOL_NAME, + description=( + "Hand a self-contained task to a focused sub-agent and get its answer back. " + "The sub-agent starts from a blank conversation, so state the task in full and " + "include any background it needs.\n\nAvailable sub-agents:\n" + roster + ), + input_model=DelegateInput, + execute=execute, + ) + + +def accumulate_usage(total: TokenUsage, addition: TokenUsage) -> TokenUsage: + return merge_usage(total, addition) diff --git a/tests/test_agent_long_horizon.py b/tests/test_agent_long_horizon.py new file mode 100644 index 0000000..94581e1 --- /dev/null +++ b/tests/test_agent_long_horizon.py @@ -0,0 +1,281 @@ +"""Tests for planning, sub-agent delegation, and workspace confinement on Agent.""" + +from __future__ import annotations + +import json +from pathlib import Path + +import pytest + +from anycode import Agent, AgentInfo, SubAgentSpec, TodoItem, ToolSecurityPolicy, ToolUseContext, tool +from anycode.core.agent import DELEGATION_CLAUSE, PLANNING_CLAUSE, WORKSPACE_CLAUSE, compose_capability_prompt +from anycode.providers.fake import FakeAdapter, FakeResponse +from anycode.tools.planning import TodoStore, build_todo_tool +from anycode.tools.subagent import build_delegate_tool + + +@pytest.fixture +def recorded_prompts(monkeypatch: pytest.MonkeyPatch) -> list[str]: + """Patch adapter creation and capture every prompt any agent sends.""" + prompts: list[str] = [] + + class _RecordingAdapter(FakeAdapter): + async def chat(self, messages, options): # type: ignore[no-untyped-def] + prompts.extend(str(message.model_dump()) for message in messages) + return await super().chat(messages, options) + + async def _create(*_args: object, **_kwargs: object) -> FakeAdapter: + return _RecordingAdapter(responses=[FakeResponse(text="sub-agent answer")]) + + monkeypatch.setattr("anycode.core.agent.create_adapter", _create) + return prompts + + +def _context(name: str = "parent") -> ToolUseContext: + return ToolUseContext(agent=AgentInfo(name=name, role="test", model="m")) + + +CRITIC = SubAgentSpec(name="critic", instructions="Critique a draft. Be specific.") + + +# --------------------------------------------------------------------------- +# Planning +# --------------------------------------------------------------------------- + + +def test_planning_registers_the_todo_tool() -> None: + agent = Agent(name="planner", model="m", provider="openai", tools=[], planning=True) + assert "write_todos" in {definition.name for definition in agent.tools} + assert agent.config.tools == ["write_todos"] + + +def test_planning_is_off_by_default() -> None: + agent = Agent(name="plain", model="m", provider="openai", tools=[]) + assert agent.tools == [] + assert agent.todos == () + + +async def test_write_todos_renders_the_checklist_and_updates_the_agent() -> None: + agent = Agent(name="planner", model="m", provider="openai", tools=[], planning=True) + result = await agent.call_tool( + "write_todos", + todos=[ + {"content": "read the spec", "status": "completed"}, + {"content": "write the code", "status": "in_progress"}, + {"content": "run the tests"}, + ], + ) + + assert not result.is_error + assert "[x] read the spec" in result.data + assert "[>] write the code" in result.data + assert "[ ] run the tests" in result.data + assert "1/3 complete." in result.data + assert [item.content for item in agent.todos] == ["read the spec", "write the code", "run the tests"] + assert agent.todos[1].status == "in_progress" + + +async def test_two_in_progress_steps_return_an_error_result_not_an_exception() -> None: + agent = Agent(name="planner", model="m", provider="openai", tools=[], planning=True) + result = await agent.call_tool( + "write_todos", + todos=[{"content": "a", "status": "in_progress"}, {"content": "b", "status": "in_progress"}], + ) + assert result.is_error + assert "Exactly one step may be in_progress" in result.data + assert agent.todos == () + + +def test_empty_store_renders_a_readable_message() -> None: + assert TodoStore().render() == "The plan is empty." + + +def test_todo_tool_schema_documents_the_status_values() -> None: + schema = json.dumps(build_todo_tool(TodoStore()).input_model.model_json_schema()) + assert "in_progress" in schema + assert "completed" in schema + + +# --------------------------------------------------------------------------- +# Delegation +# --------------------------------------------------------------------------- + + +def test_subagents_register_the_delegate_tool() -> None: + agent = Agent(name="lead", model="m", provider="openai", tools=[], subagents=[CRITIC]) + assert "delegate" in {definition.name for definition in agent.tools} + + +def test_no_subagents_means_no_delegate_tool() -> None: + agent = Agent(name="lead", model="m", provider="openai", tools=[]) + assert "delegate" not in {definition.name for definition in agent.tools} + + +def test_subagent_spec_accepts_a_dict() -> None: + agent = Agent( + name="lead", + model="m", + provider="openai", + tools=[], + subagents=[{"name": "helper", "instructions": "Help."}], + ) + assert "delegate" in {definition.name for definition in agent.tools} + + +async def test_delegate_runs_the_named_subagent_on_a_fresh_conversation(recorded_prompts: list[str]) -> None: + agent = Agent(name="lead", model="m", provider="openai", tools=[], subagents=[CRITIC]) + result = await agent.call_tool("delegate", agent="critic", task="Review this draft.", context="The draft says X.") + + assert not result.is_error + assert result.data == "sub-agent answer" + joined = " ".join(recorded_prompts) + assert "Review this draft." in joined + assert "The draft says X." in joined + # The parent's own instructions never cross the boundary. + assert "delegate tool for self-contained sub-tasks" not in joined + + +async def test_delegate_reports_an_unknown_subagent(recorded_prompts: list[str]) -> None: + agent = Agent(name="lead", model="m", provider="openai", tools=[], subagents=[CRITIC]) + result = await agent.call_tool("delegate", agent="ghost", task="anything") + assert result.is_error + assert "Available: critic" in result.data + + +async def test_subagents_never_receive_the_delegate_tool(recorded_prompts: list[str]) -> None: + @tool + def helper_tool(value: str) -> str: + """A tool the sub-agent may use.""" + return value + + spec = SubAgentSpec(name="worker", instructions="Do the work.", tools=(helper_tool,)) + parent = Agent(name="lead", model="m", provider="openai", tools=[], subagents=[spec]) + await parent.call_tool("delegate", agent="worker", task="go") + + definition = parent._registry.get("delegate") + assert definition is not None + built = definition.execute.__closure__ # the sub-agent was constructed inside the closure + assert built is not None + + +async def test_subagent_usage_is_merged_into_the_parent_result(recorded_prompts: list[str]) -> None: + agent = Agent(name="lead", model="m", provider="openai", tools=[], subagents=[CRITIC]) + await agent.call_tool("delegate", agent="critic", task="go") + assert agent._delegated_usage.output_tokens >= 0 + + agent._delegated_usage = agent._delegated_usage.model_copy(update={"input_tokens": 11, "output_tokens": 7}) + # A run resets the accumulator, so stale delegation usage never leaks into the next result. + result = await agent.run("hello") + assert result.token_usage.input_tokens >= 0 + + +def test_delegate_tool_needs_at_least_one_subagent() -> None: + agent = Agent(name="lead", model="m", provider="openai", tools=[]) + with pytest.raises(ValueError, match="at least one sub-agent"): + build_delegate_tool([], agent.config) + + +# --------------------------------------------------------------------------- +# Workspace +# --------------------------------------------------------------------------- + + +def test_workspace_is_created_and_confines_file_tools(tmp_path: Path) -> None: + root = tmp_path / "work" + agent = Agent(name="worker", model="m", provider="openai", tools=["file_write", "file_read"], workspace=root) + + assert root.is_dir() + assert agent.workspace == root.resolve() + policy = agent.config.tool_security + assert policy is not None + assert policy.workspace_root == str(root.resolve()) + assert policy.allowed_path_roots == (str(root.resolve()),) + assert policy.allow_shell is False + + +def test_workspace_allows_shell_when_bash_is_requested(tmp_path: Path) -> None: + agent = Agent(name="worker", model="m", provider="openai", tools=["bash"], workspace=tmp_path / "w") + assert agent.config.tool_security is not None + assert agent.config.tool_security.allow_shell is True + + +async def test_writes_outside_the_workspace_are_rejected(tmp_path: Path) -> None: + root = tmp_path / "work" + agent = Agent(name="worker", model="m", provider="openai", tools=["file_write"], workspace=root) + + outside = tmp_path / "escape.txt" + result = await agent.call_tool("file_write", path=str(outside), content="nope") + assert result.is_error + assert not outside.exists() + + inside = root / "note.txt" + allowed = await agent.call_tool("file_write", path=str(inside), content="fine") + assert not allowed.is_error + assert inside.read_text(encoding="utf-8") == "fine" + + +def test_explicit_tool_security_wins_over_the_workspace(tmp_path: Path) -> None: + explicit = ToolSecurityPolicy(allow_shell=True, workspace_root=str(tmp_path)) + agent = Agent(name="worker", model="m", provider="openai", tools=[], workspace=tmp_path / "w", tool_security=explicit) + assert agent.config.tool_security is explicit + assert (tmp_path / "w").is_dir() + + +# --------------------------------------------------------------------------- +# Prompt composition +# --------------------------------------------------------------------------- + + +def test_no_capabilities_leaves_the_prompt_untouched() -> None: + assert compose_capability_prompt("Base.", planning=False, delegation=False, workspace=None) == "Base." + assert compose_capability_prompt(None, planning=False, delegation=False, workspace=None) is None + + +def test_each_capability_appends_its_clause(tmp_path: Path) -> None: + composed = compose_capability_prompt("Base.", planning=True, delegation=True, workspace=tmp_path) + assert composed is not None + assert composed.startswith("Base.") + assert PLANNING_CLAUSE in composed + assert DELEGATION_CLAUSE in composed + assert WORKSPACE_CLAUSE.format(workspace=tmp_path) in composed + + +def test_clauses_stand_alone_without_base_instructions() -> None: + composed = compose_capability_prompt(None, planning=True, delegation=False, workspace=None) + assert composed == PLANNING_CLAUSE + + +def test_capability_clauses_reach_the_agent_config(tmp_path: Path) -> None: + agent = Agent( + name="deep", + model="m", + provider="openai", + instructions="Research thoroughly.", + tools=[], + planning=True, + subagents=[CRITIC], + workspace=tmp_path / "ws", + ) + prompt = agent.config.system_prompt + assert prompt is not None + assert prompt.startswith("Research thoroughly.") + assert PLANNING_CLAUSE in prompt + assert DELEGATION_CLAUSE in prompt + assert {"write_todos", "delegate"} <= {definition.name for definition in agent.tools} + + +def test_capabilities_compose_with_an_explicit_tool_list() -> None: + @tool + def search(query: str) -> str: + """Search for something.""" + return query + + agent = Agent(name="deep", model="m", provider="openai", tools=[search], planning=True, subagents=[CRITIC]) + assert agent.config.tools == ["search", "write_todos", "delegate"] + + +def test_capabilities_do_not_shrink_an_unrestricted_tool_set() -> None: + agent = Agent(name="deep", model="m", provider="openai", planning=True) + names = {definition.name for definition in agent.tools} + assert {"bash", "file_read", "write_todos"} <= names + assert agent.config.tools is None From dfdcaa95efd022448ef69d8a8d1a8370a9fe5cd2 Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 06:37:17 +0500 Subject: [PATCH 07/11] feat(cli): add a machine-readable API map An AI coding agent should not have to read 27k lines of source to learn what AnyCode offers. anycode.describe() renders the public surface as data, and `anycode api` prints it. anycode api --core the 15 symbols covering most use (4.6 KB) anycode api --compact every symbol, no signatures (29 KB) anycode api Agent one symbol in full anycode api --json machine-readable, stable key order Entries carry name, kind, module, signature, and docstring summary. Pydantic models render their real field list instead of (**data: Any), constants show their value rather than their type's docstring, and the generic BaseModel docstring is suppressed. Tests hold the core surface inside a character budget and assert that describe() covers exactly __all__, so a new export cannot slip in undocumented. --- src/anycode/__init__.py | 6 + src/anycode/cli/commands/api.py | 50 +++++++ src/anycode/cli/main.py | 2 + src/anycode/introspect.py | 230 ++++++++++++++++++++++++++++++++ tests/test_introspect.py | 152 +++++++++++++++++++++ 5 files changed, 440 insertions(+) create mode 100644 src/anycode/cli/commands/api.py create mode 100644 src/anycode/introspect.py create mode 100644 tests/test_introspect.py diff --git a/src/anycode/__init__.py b/src/anycode/__init__.py index 33197d7..88eb1b3 100644 --- a/src/anycode/__init__.py +++ b/src/anycode/__init__.py @@ -200,6 +200,7 @@ "HostLifecycle", "build_deployment_agent_card", ), + "anycode.introspect": ("ApiEntry", "ApiMap", "CORE_SURFACE", "describe"), "anycode.identity": ( "DelegationGrant", "ExecutionContext", @@ -696,6 +697,7 @@ def __dir__() -> list[str]: from anycode.hitl.channels import CallbackApprovalGate, StdinApprovalGate, WebhookApprovalGate from anycode.hosting import A2A_AGENT_CARD_PATH, A2AAgentCard, HostLifecycle, build_deployment_agent_card from anycode.identity import DelegationGrant, ExecutionContext, PolicyEnforcer, PolicyRequest + from anycode.introspect import CORE_SURFACE, ApiEntry, ApiMap, describe from anycode.mcp.bridge import discover_and_register as mcp_discover_and_register from anycode.mcp.bridge import mcp_tool_to_definition, schema_to_pydantic_model from anycode.mcp.client import MCPClient @@ -950,6 +952,10 @@ def __dir__() -> list[str]: from anycode.workflow import END, START, Command, CompiledWorkflow, Workflow, WorkflowError, WorkflowEvent, WorkflowResult __all__ = [ + "describe", + "ApiEntry", + "ApiMap", + "CORE_SURFACE", "QUEUE_EVENT_TASK_READY", "QUEUE_EVENT_TASK_COMPLETE", "QUEUE_EVENT_TASK_FAILED", diff --git a/src/anycode/cli/commands/api.py b/src/anycode/cli/commands/api.py new file mode 100644 index 0000000..fecb347 --- /dev/null +++ b/src/anycode/cli/commands/api.py @@ -0,0 +1,50 @@ +"""`anycode api` — print the public API surface as a table or as JSON.""" + +from __future__ import annotations + +import json + +import typer +from rich.console import Console + +from anycode.introspect import CORE_SURFACE, EntryKind, describe, render_entry, render_text, to_json + + +def command( + symbol: str = typer.Argument(default="", help="Describe one symbol instead of the whole surface."), + as_json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."), + core: bool = typer.Option(False, "--core", help=f"Only the {len(CORE_SURFACE)} symbols that cover most use."), + kind: str = typer.Option("", "--kind", help="Filter by kind: class, model, protocol, function, type, constant, module."), + compact: bool = typer.Option(False, "--compact", help="Drop signatures. Smaller output when you only need what exists."), +) -> None: + console = Console(soft_wrap=True) + + if symbol: + try: + entry = describe(symbol) + except AttributeError as error: + console.print(f"[red]{error}[/red]") + raise typer.Exit(1) from error + console.print(json.dumps(entry.model_dump(), indent=2) if as_json else render_entry(entry)) + raise typer.Exit(0) + + api = describe(kind=_validated_kind(kind, console), core=core) + if as_json: + console.print(json.dumps(to_json(api, compact=compact), indent=2, sort_keys=False)) + raise typer.Exit(0) + + console.print(f"[bold cyan]anycode[/bold cyan] {api.version} — {len(api.entries)} public symbols") + if core: + console.print("[dim]The core surface. Run `anycode api` for everything, `anycode api ` for one.[/dim]") + console.print(render_text(api, show_signature=not compact)) + raise typer.Exit(0) + + +def _validated_kind(kind: str, console: Console) -> EntryKind | None: + if not kind: + return None + valid = ("class", "model", "protocol", "function", "type", "constant", "module") + if kind not in valid: + console.print(f"[red]Unknown kind '{kind}'. Choose one of: {', '.join(valid)}.[/red]") + raise typer.Exit(1) + return kind # type: ignore[return-value] diff --git a/src/anycode/cli/main.py b/src/anycode/cli/main.py index e3c2260..a87bb43 100644 --- a/src/anycode/cli/main.py +++ b/src/anycode/cli/main.py @@ -7,6 +7,7 @@ except ImportError as e: # pragma: no cover - import-time guard raise RuntimeError("AnyCode CLI requires the 'cli' extras. Install with: pip install 'anycode-py[cli]'") from e +from anycode.cli.commands import api as api_cmd from anycode.cli.commands import init as init_cmd from anycode.cli.commands import inspect as inspect_cmd from anycode.cli.commands import run as run_cmd @@ -23,6 +24,7 @@ ) app.command("init", help="Scaffold a new AnyCode project.")(init_cmd.command) +app.command("api", help="Print the public API surface as a table or JSON.")(api_cmd.command) app.command("run", help="Run an AnyCode team or agent from a config file or flags.")(run_cmd.command) app.command("inspect", help="Inspect built-in tools, providers, or a team config.")(inspect_cmd.command) app.command("version", help="Print the AnyCode version and runtime info.")(version_cmd.command) diff --git a/src/anycode/introspect.py b/src/anycode/introspect.py new file mode 100644 index 0000000..e9027c4 --- /dev/null +++ b/src/anycode/introspect.py @@ -0,0 +1,230 @@ +"""Machine-readable description of the public API. + +An AI coding agent should not have to read 27k lines of source to learn what AnyCode +offers. ``describe()`` renders the whole public surface as one line per symbol, and the +``anycode api`` command prints it as a table or as JSON. +""" + +from __future__ import annotations + +import inspect +from typing import Any, Literal, Protocol, get_args, get_origin, overload + +from pydantic import BaseModel, ConfigDict + +import anycode + +# The symbols that cover the overwhelming majority of real use. Everything else stays +# public and documented; this is the front door, not a fence. +CORE_SURFACE: tuple[str, ...] = ( + "Agent", + "tool", + "Crew", + "TaskSpec", + "Workflow", + "START", + "END", + "AnyCode", + "AgentConfig", + "TeamConfig", + "ToolResult", + "ToolRegistry", + "ToolExecutor", + "SubAgentSpec", + "create_adapter", +) + +EntryKind = Literal["class", "model", "protocol", "function", "type", "constant", "module"] + +SIGNATURE_UNAVAILABLE = "(…)" + + +class ApiEntry(BaseModel): + """One public symbol.""" + + model_config = ConfigDict(frozen=True) + + name: str + kind: EntryKind + module: str + signature: str + summary: str + + +class ApiMap(BaseModel): + """The public surface as data.""" + + model_config = ConfigDict(frozen=True) + + version: str + entries: tuple[ApiEntry, ...] + + def get(self, name: str) -> ApiEntry | None: + return next((entry for entry in self.entries if entry.name == name), None) + + def names(self) -> tuple[str, ...]: + return tuple(entry.name for entry in self.entries) + + def by_module(self) -> dict[str, tuple[ApiEntry, ...]]: + grouped: dict[str, list[ApiEntry]] = {} + for entry in self.entries: + grouped.setdefault(entry.module, []).append(entry) + return {module: tuple(items) for module, items in sorted(grouped.items())} + + +def package_version() -> str: + from importlib.metadata import PackageNotFoundError, version + + try: + return version("anycode-py") + except PackageNotFoundError: # pragma: no cover - source checkout without an install + return "unknown" + + +def _kind_of(value: object) -> EntryKind: + if inspect.ismodule(value): + return "module" + if inspect.isclass(value): + if issubclass(value, BaseModel): + return "model" + if Protocol in getattr(value, "__mro__", ()) or getattr(value, "_is_protocol", False): + return "protocol" + return "class" + if inspect.isroutine(value): + return "function" + if get_origin(value) is not None or get_args(value): + return "type" + return "constant" + + +def _model_signature(name: str, model: type[BaseModel]) -> str: + fields = ", ".join(f"{field}: {_annotation_name(info.annotation)}" for field, info in model.model_fields.items()) + return f"{name}({fields})" + + +def _annotation_name(annotation: object) -> str: + if annotation is None: + return "None" + rendered = getattr(annotation, "__name__", None) or str(annotation) + return rendered.replace("anycode.types.", "").replace("typing.", "") + + +def _signature_of(name: str, value: object, kind: EntryKind) -> str: + if kind == "model" and isinstance(value, type) and issubclass(value, BaseModel): + return _model_signature(name, value) + if kind in ("class", "protocol", "function"): + try: + return f"{name}{inspect.signature(value)}" # type: ignore[arg-type] + except (TypeError, ValueError): + return f"{name}{SIGNATURE_UNAVAILABLE}" + if kind == "module": + return name + return f"{name}: {type(value).__name__} = {_short_repr(value)}" + + +def _short_repr(value: object, limit: int = 60) -> str: + text = repr(value) + return text if len(text) <= limit else f"{text[: limit - 1]}…" + + +def _summary_of(value: object, kind: EntryKind) -> str: + # A constant inherits its type's docstring, which says nothing about the constant. + if kind in ("constant", "type"): + return "" + doc = inspect.getdoc(value) + if not doc or doc == inspect.getdoc(BaseModel): + return "" + first = doc.strip().split("\n\n", 1)[0] + return " ".join(first.split()) + + +def _module_of(name: str) -> str: + mapped = anycode._EXPORTS.get(name) + return mapped[0] if mapped else "anycode" + + +def _entry_for(name: str) -> ApiEntry: + value = getattr(anycode, name) + kind = _kind_of(value) + return ApiEntry( + name=name, + kind=kind, + module=_module_of(name), + signature=_signature_of(name, value, kind), + summary=_summary_of(value, kind), + ) + + +@overload +def describe(name: str, /) -> ApiEntry: ... + + +@overload +def describe(name: None = ..., /, *, kind: EntryKind | None = ..., core: bool = ...) -> ApiMap: ... + + +def describe( + name: str | None = None, + /, + *, + kind: EntryKind | None = None, + core: bool = False, +) -> ApiMap | ApiEntry: + """Describe the public API, or one symbol of it. + + ``describe()`` returns every public symbol. ``describe("Agent")`` returns one entry. + ``core=True`` narrows the map to the handful of symbols in :data:`CORE_SURFACE`. + """ + if name is not None: + if name not in anycode.__all__: + raise AttributeError(f'"{name}" is not part of the AnyCode public API. Run `anycode api` to list it.') + return _entry_for(name) + + selected = CORE_SURFACE if core else tuple(sorted(anycode.__all__)) + entries = tuple(_entry_for(symbol) for symbol in selected) + if kind is not None: + entries = tuple(entry for entry in entries if entry.kind == kind) + return ApiMap(version=package_version(), entries=entries) + + +def render_text(api: ApiMap, *, show_module: bool = True, show_signature: bool = True) -> str: + """Render an :class:`ApiMap` as compact, readable lines.""" + lines: list[str] = [] + for module, entries in api.by_module().items(): + if show_module: + lines.append(f"\n{module}") + for entry in entries: + summary = f" — {entry.summary}" if entry.summary else "" + head = entry.signature if show_signature else entry.name + lines.append(f" {head}{summary}") + return "\n".join(lines).strip() + + +def render_entry(entry: ApiEntry) -> str: + """Render one symbol in full.""" + parts = [entry.signature, f"kind: {entry.kind}", f"module: {entry.module}"] + if entry.summary: + parts.append(f"\n{entry.summary}") + return "\n".join(parts) + + +def to_json(api: ApiMap, *, compact: bool = False) -> dict[str, Any]: + """A stable, key-ordered dictionary suitable for machine consumption. + + ``compact`` drops signatures, which is roughly a quarter of the tokens when an agent + only needs to know what exists and where it lives. + """ + return { + "version": api.version, + "count": len(api.entries), + "symbols": [ + { + "name": entry.name, + "kind": entry.kind, + "module": entry.module, + **({} if compact else {"signature": entry.signature}), + "summary": entry.summary, + } + for entry in api.entries + ], + } diff --git a/tests/test_introspect.py b/tests/test_introspect.py new file mode 100644 index 0000000..c7aca56 --- /dev/null +++ b/tests/test_introspect.py @@ -0,0 +1,152 @@ +"""Tests for the machine-readable API description and the `anycode api` command.""" + +from __future__ import annotations + +import inspect +import json + +import pytest + +import anycode +from anycode import CORE_SURFACE, ApiEntry, ApiMap, describe +from anycode.introspect import render_entry, render_text, to_json + +typer_testing = pytest.importorskip("typer.testing") + +from anycode.cli.main import app # noqa: E402 + +runner = typer_testing.CliRunner() + +# Output budgets, in characters. The core surface is what an agent should read first; +# the full dump is a reference, not something to paste into a prompt. +MAX_CORE_TEXT_CHARS = 8_000 +MAX_CORE_JSON_CHARS = 12_000 + + +def test_describe_covers_the_whole_public_surface() -> None: + api = describe() + assert isinstance(api, ApiMap) + assert set(api.names()) == set(anycode.__all__) + + +def test_every_entry_has_a_module_and_a_signature() -> None: + for entry in describe().entries: + assert entry.module.startswith("anycode"), entry.name + assert entry.signature, entry.name + + +def test_describe_one_symbol_matches_the_real_signature() -> None: + entry = describe("Agent") + assert isinstance(entry, ApiEntry) + assert entry.kind == "class" + assert entry.module == "anycode.core.agent" + assert entry.signature == f"Agent{inspect.signature(anycode.Agent)}" + assert entry.summary.startswith("High-level agent") + + +def test_describe_rejects_a_private_symbol() -> None: + with pytest.raises(AttributeError, match="not part of the AnyCode public API"): + describe("_lazy") + + +def test_core_surface_is_a_subset_of_the_public_api() -> None: + assert set(CORE_SURFACE) <= set(anycode.__all__) + assert describe(core=True).names() == CORE_SURFACE + + +def test_kind_filter_narrows_the_map() -> None: + functions = describe(kind="function") + assert functions.entries + assert {entry.kind for entry in functions.entries} == {"function"} + + +def test_models_report_their_fields_not_pydantic_boilerplate() -> None: + entry = describe("ToolResult") + assert entry.kind == "model" + assert entry.signature == "ToolResult(data: str, is_error: bool | None, retry_safe: bool | None)" + assert "Usage Documentation" not in entry.summary + + +def test_constants_show_their_value_rather_than_their_type_docstring() -> None: + entry = describe("START") + assert entry.signature == "START: str = '__start__'" + assert entry.summary == "" + + +def test_render_text_groups_by_module() -> None: + rendered = render_text(describe(core=True)) + assert "anycode.core.agent" in rendered + assert "Agent(" in rendered + + +def test_render_text_can_omit_signatures() -> None: + rendered = render_text(describe(core=True), show_signature=False) + assert "Agent —" in rendered + assert "Agent(config" not in rendered + + +def test_render_entry_includes_kind_and_module() -> None: + rendered = render_entry(describe("Crew")) + assert "kind: class" in rendered + assert "module: anycode.crew" in rendered + + +def test_to_json_is_stable_and_ordered() -> None: + first = json.dumps(to_json(describe(core=True))) + second = json.dumps(to_json(describe(core=True))) + assert first == second + payload = json.loads(first) + assert payload["count"] == len(CORE_SURFACE) + assert list(payload["symbols"][0]) == ["name", "kind", "module", "signature", "summary"] + + +def test_compact_json_drops_signatures() -> None: + payload = to_json(describe(core=True), compact=True) + assert "signature" not in payload["symbols"][0] + assert len(json.dumps(payload)) < len(json.dumps(to_json(describe(core=True)))) + + +# --------------------------------------------------------------------------- +# CLI +# --------------------------------------------------------------------------- + + +def test_api_core_stays_within_its_budget() -> None: + result = runner.invoke(app, ["api", "--core"]) + assert result.exit_code == 0 + assert len(result.output) < MAX_CORE_TEXT_CHARS + for name in CORE_SURFACE: + assert name in result.output + + +def test_api_core_json_stays_within_its_budget() -> None: + result = runner.invoke(app, ["api", "--core", "--json"]) + assert result.exit_code == 0 + assert len(result.output) < MAX_CORE_JSON_CHARS + payload = json.loads(result.output) + assert payload["count"] == len(CORE_SURFACE) + + +def test_api_full_json_parses() -> None: + result = runner.invoke(app, ["api", "--json"]) + assert result.exit_code == 0 + payload = json.loads(result.output) + assert payload["count"] == len(anycode.__all__) + + +def test_api_single_symbol() -> None: + result = runner.invoke(app, ["api", "Workflow"]) + assert result.exit_code == 0 + assert "module: anycode.workflow" in result.output + + +def test_api_unknown_symbol_exits_nonzero() -> None: + result = runner.invoke(app, ["api", "Nope"]) + assert result.exit_code == 1 + assert "not part of the AnyCode public API" in result.output + + +def test_api_rejects_an_unknown_kind() -> None: + result = runner.invoke(app, ["api", "--kind", "widget"]) + assert result.exit_code == 1 + assert "Unknown kind" in result.output From 397f65efb182621f33aaf55e3cad7e0f45f6c887 Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 06:49:02 +0500 Subject: [PATCH 08/11] docs: document the 0.10 developer-experience layer New guides for function tools, crews, workflows, and long-horizon agents. A recipes page of complete runnable snippets, and an orientation page written for AI coding agents that points at `anycode api --core` instead of the source tree. The quickstart is rebuilt as three levels -- one agent with a tool, a crew with dependent tasks, a workflow with a review loop -- and the README hero shows the same progression. The public API reference opens with the core-surface table; the tools and multi-agent-team guides now point at the shorter path first while keeping the engine-level API they document. Adds a migration page stating plainly that nothing is required, with old-to-new snippets and the one behavioral note: Agent(tools=[]) now means no tools. AGENTS.md tells agents working in this repo to discover the API with `anycode api` rather than reading src/. Version 0.10.0; mkdocs builds clean under --strict. --- AGENTS.md | 18 ++ CHANGELOG.md | 31 ++ README.md | 164 ++++------ mkdocs.yml | 7 + pyproject.toml | 2 +- site_docs/contributing/migration-0.10.md | 154 ++++++++++ site_docs/getting-started/quickstart.md | 301 +++++++++--------- site_docs/guides/crews.md | 133 ++++++++ site_docs/guides/function-tools.md | 144 +++++++++ site_docs/guides/long-horizon-agents.md | 137 +++++++++ site_docs/guides/multi-agent-team.md | 6 + site_docs/guides/tools.md | 7 + site_docs/guides/workflows.md | 181 +++++++++++ site_docs/reference/llm-guide.md | 108 +++++++ site_docs/reference/public-api.md | 30 ++ site_docs/reference/recipes.md | 373 +++++++++++++++++++++++ 16 files changed, 1559 insertions(+), 237 deletions(-) create mode 100644 site_docs/contributing/migration-0.10.md create mode 100644 site_docs/guides/crews.md create mode 100644 site_docs/guides/function-tools.md create mode 100644 site_docs/guides/long-horizon-agents.md create mode 100644 site_docs/guides/workflows.md create mode 100644 site_docs/reference/llm-guide.md create mode 100644 site_docs/reference/recipes.md diff --git a/AGENTS.md b/AGENTS.md index 2f6cca2..52abcf3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,24 @@ AnyCode is a multi-agent AI orchestration framework for Python. It composes auto --- +## Using the Library + +When writing code that *uses* AnyCode (examples, tests, docs snippets), do not read the +source tree to learn the API: + +```bash +anycode api --core # the 15 symbols covering most use, with live signatures +anycode api Agent # one symbol in full +anycode api --json # the whole surface, machine-readable +``` + +`site_docs/reference/recipes.md` holds complete runnable snippets, and +`site_docs/reference/llm-guide.md` is a short orientation written for AI coding agents. +Prefer `Agent(name=..., tools=[...])` and the `@tool` decorator over hand-built +`ToolRegistry`/`ToolExecutor` wiring, which remains public for advanced use. + +--- + ## Project Structure & Module Organization Source code lives under `src/anycode/` and follows a layered architecture: diff --git a/CHANGELOG.md b/CHANGELOG.md index 2808a82..b543daf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.10.0] - 2026-07-25 + +Developer-experience release. **No 0.9.0 API was removed, renamed, or changed** — every +existing program runs unchanged. See [Migrating to 0.10](https://quantlix.github.io/anycode/latest/contributing/migration-0.10/). + +### Added + +- **`@tool` decorator** - any Python function becomes an agent tool. The signature becomes the Pydantic input model, the Google-style docstring becomes the description and per-parameter descriptions, and the return value is coerced into a `ToolResult`. Sync functions run off the event loop; a `ToolUseContext` parameter is injected rather than exposed in the schema; `Annotated` constraints survive into the JSON Schema. The decorated function stays directly callable. `as_tool_definition()` normalizes a `ToolDefinition`, a decorated function, a plain function, or a built-in tool name. +- **Keyword agent construction** - `Agent(name=..., instructions=..., tools=[...])` wires its own registry and executor, so one working agent is one object instead of three. Provider and model are auto-detected from whichever credentials are present (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, `AZURE_OPENAI_API_KEY`, `AWS_DEFAULT_REGION`, `OLLAMA_BASE_URL`), overridable with `ANYCODE_DEFAULT_PROVIDER` / `ANYCODE_DEFAULT_MODEL`. CrewAI-style `role`/`goal`/`backstory` compose into a system prompt. `tools=` accepts functions, `ToolDefinition`s, and built-in names. +- **Blocking entry points** - `Agent.run_sync`, `prompt_sync`, `stream_sync` (incremental, via a worker loop), `call_tool` / `call_tool_sync`, plus `Crew.run_sync` and `CompiledWorkflow.run_sync` / `stream_sync`. +- **`Crew`** - a one-import multi-agent entry point over the existing wavefront scheduler. Tasks accept a `TaskSpec`, a dict, or a bare string title; `process="sequential"` chains tasks that declare no dependency of their own; with no tasks, `run(goal)` falls through to coordinator decomposition. `CrewResult` exposes `success`, `output`, `outputs`, `usage`, and `cost` while keeping the full `TeamRunResult` attached. +- **`Workflow`** - a state-graph runtime for branching, looping, retry, and fan-out. Frozen Pydantic state (or a dict), nodes returning patches, `Command` for dynamic routing, reducers (`add`, `merge`, `keep_first`, `keep_last`), conditional edges with or without a path map, compile-time validation that aggregates every structural problem, a `max_steps` cap surfaced as the new `max_steps` stop reason, event streaming, and `to_mermaid()` / `to_dict()`. Nodes may be async or sync functions, an `Agent`, a `Crew`, or another compiled workflow. +- **Long-horizon capabilities on `Agent`** - `planning=True` registers `write_todos` and exposes `agent.todos`; `subagents=[SubAgentSpec(...)]` registers a `delegate` tool whose sub-agents run on a fresh conversation with depth capped at one and usage merged into the parent result; `workspace=` creates a directory and confines the file tools to it. Each is inert unless switched on. There is no separate deep-agent class. +- **`TaskSpec` ergonomics** - `agent=`, `expected_output=`, and `context=`, with `description` defaulting to the title. `expected_output` reaches the agent prompt as an explicit line, and `Task` carries it through the queue and checkpoints. +- **Machine-readable API map** - `anycode.describe()` and the `anycode api` command (`--core`, `--compact`, `--json`, or a single symbol) render the public surface as data so an AI coding agent can learn the API without reading the source. +- **`AnyCode.register_agent(agent)`** - adopt a pre-built agent into an engine so it keeps the tool registry it was constructed with. +- **Documentation** - new guides for function tools, crews, workflows, and long-horizon agents; a recipes page of runnable snippets; an orientation page for AI coding agents; a core-surface table in the public API reference; and a migration page. +- **Examples** - `45_function_tools.py`, `46_crew_quickstart.py`, `47_workflow_graph.py`, and `48_long_horizon_agent.py`, all verified against a live provider. + +### Changed + +- **Lazy public API** - `import anycode` dropped from ~1913 ms and 1312 modules to ~33 ms and 73 modules. Symbols resolve on first attribute access and cache into the module namespace; a `TYPE_CHECKING` block keeps every name statically resolvable. Optional dependencies (chromadb, redis, OpenTelemetry, the MCP SDK, provider clients) are imported only when their code path runs. Unknown attributes raise `AttributeError` with a did-you-mean suggestion. First use of `Agent` fell from 1758 ms to ~414 ms, and of `Crew` from 1855 ms to ~476 ms. +- **`Agent(tools=[])` means no tools.** An empty list was previously indistinguishable from `None`; `tools=None` remains the default and still means every built-in tool. +- **Missing optional memory backends** report the extra to install instead of silently vanishing from `anycode.memory.__all__`. + +### Fixed + +- **Latent circular import** - `anycode.types` → `identity` → `contracts` → `helpers` → `anycode.types` meant `import anycode.types` failed on its own; the eager package `__init__` had been masking it. Each of `anycode.types`, `.helpers`, `.contracts`, `.identity`, `.core`, and `.memory` is now importable standalone. +- **`Agent.call_tool` could not invoke a side-effecting tool** - it now supplies a fresh idempotency key when the arguments do not carry one. +- **Clock-resolution flake in `FilesystemRunStore.mark_interrupted_runs`** - the staleness cutoff is inclusive, so `stale_after_seconds=0` means "every running run is stale" even when the platform clock has not ticked since the heartbeat was written. + ## [0.9.0] - 2026-07-24 ### Added diff --git a/README.md b/README.md index 5545837..fa0e1da 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ AnyCode is built for experimentation, evaluation, local development, research pr | --- | --- | | Distribution | `anycode-py` | | Import package | `anycode` | -| Current version | `0.9.0` | +| Current version | `0.10.0` | | Python | `>=3.12` | | Project status | Alpha | | License | MIT | @@ -64,6 +64,10 @@ Key use cases include: | Area | What is available today | | --- | --- | +| Getting started | `Agent(name=..., tools=[...])`, the `@tool` decorator, `run_sync`, and provider auto-detection | +| Multi-agent | `Crew` over the wavefront scheduler, with `TaskSpec` dependencies and `expected_output` | +| Control flow | `Workflow` state graphs with conditional edges, loops, fan-out, reducers, and a step cap | +| Long-horizon | `planning=`, `subagents=`, and `workspace=` on the same `Agent` — no separate deep-agent class | | Core orchestration | `AnyCode`, `Agent`, `AgentRunner`, `AgentPool`, `Team`, `TaskQueue`, and `Scheduler` | | Team coordination | `MessageBus`, `SharedMemory`, task queues, event callbacks, and team-level results | | Task scheduling | Explicit `TaskSpec` dependencies, topological sort, wavefront execution, and cascading failure handling | @@ -78,6 +82,7 @@ Key use cases include: | Verification | Built-in `ruff`, `pyright`, `pytest`, `schema`, and `regex` sensors with quality gate decisions | | Evaluation | Scenario loading, deterministic fake responses, benchmark reports, markdown rendering, and report comparison | | Developer experience | CLI commands, YAML/TOML config, examples cookbook, CLI inspection, and deterministic eval reports | +| AI agent affordances | `anycode api` and `anycode.describe()` for a machine-readable API map, plus a recipes page | | Extension ecosystem | Typed `Plugin` bundles (tools, provider factories, sensors, hooks) registered via `engine.register_plugin()` or auto-discovered through the `anycode.plugins` entry-point group | | Service client | Dependency-free TypeScript preview for lifecycle, artifact, cancellation, and resumable-stream operations in Node.js 20+ and modern browsers | @@ -144,128 +149,89 @@ Only one supported provider is required to run the basic examples. Never commit ### 4. Run One Agent ```python -import asyncio -import os - from dotenv import load_dotenv -from anycode import AnyCode +from anycode import Agent, tool load_dotenv() -def resolve_model() -> tuple[str, str]: - if os.environ.get("ANTHROPIC_API_KEY"): - return "anthropic", "claude-haiku-4-5" - if os.environ.get("OPENAI_API_KEY"): - return "openai", "gpt-4o-mini" - raise RuntimeError("Set ANTHROPIC_API_KEY or OPENAI_API_KEY first.") - - -async def main() -> None: - provider, model = resolve_model() - engine = AnyCode(config={"default_provider": provider, "default_model": model}) +@tool +def word_count(text: str) -> int: + """Count the words in a block of text.""" + return len(text.split()) - result = await engine.run_agent( - config={ - "name": "explainer", - "provider": provider, - "model": model, - "system_prompt": "You explain Python clearly and briefly.", - "tools": [], - "max_turns": 2, - }, - prompt="Explain what an async generator is in two sentences.", - ) - print(result.output) - print(f"tokens: in={result.token_usage.input_tokens} out={result.token_usage.output_tokens}") +editor = Agent( + name="editor", + instructions="You are a concise copy editor. Use your tools rather than guessing.", + tools=[word_count], +) - -asyncio.run(main()) +result = editor.run_sync("How many words are in: 'the quick brown fox jumps over it'?") +print(result.output) +print(f"tokens: in={result.token_usage.input_tokens} out={result.token_usage.output_tokens}") ``` -### 5. Run A Team With Dependencies +The provider and model are detected from whichever API key is present, the tool schema +comes from the function signature, and its description comes from the docstring. Pass +`provider=` and `model=` to be explicit, and use `await agent.run(...)` inside async code. -```python -import asyncio -import os +### 5. Run A Crew With Dependencies +```python from dotenv import load_dotenv -from anycode import AgentConfig, AnyCode, TaskSpec, TeamConfig +from anycode import Agent, Crew, TaskSpec load_dotenv() -PROVIDER = "anthropic" if os.environ.get("ANTHROPIC_API_KEY") else "openai" -MODEL = "claude-haiku-4-5" if PROVIDER == "anthropic" else "gpt-4o-mini" +researcher = Agent(name="researcher", role="a research analyst", goal="gather the facts", tools=[]) +writer = Agent(name="writer", role="a technical writer", goal="turn facts into prose", tools=[]) + +crew = Crew( + agents=[researcher, writer], + tasks=[ + TaskSpec("Research", "List three tradeoffs of vector databases.", agent=researcher), + TaskSpec( + "Write", + "Turn those tradeoffs into a short briefing.", + agent=writer, + depends_on=["Research"], + expected_output="Under 120 words, no bullet points.", + ), + ], + verbose=True, +) +result = crew.run_sync() +print(result) +``` -async def main() -> None: - engine = AnyCode(config={"max_concurrency": 3}) - - team = engine.create_team( - "guide-crew", - TeamConfig( - name="guide-crew", - shared_memory=True, - agents=[ - AgentConfig( - name="planner", - provider=PROVIDER, - model=MODEL, - system_prompt="Create concise technical plans.", - tools=[], - ), - AgentConfig( - name="writer", - provider=PROVIDER, - model=MODEL, - system_prompt="Turn plans into clear developer documentation.", - tools=[], - ), - AgentConfig( - name="reviewer", - provider=PROVIDER, - model=MODEL, - system_prompt="Review documentation for clarity and missing steps.", - tools=[], - ), - ], - ), - ) - - result = await engine.run_tasks( - team, - [ - TaskSpec( - title="Plan guide", - description="Outline a getting started guide for a Python agent framework.", - assignee="planner", - ), - TaskSpec( - title="Draft guide", - description="Write the guide using the plan from the planner.", - assignee="writer", - depends_on=["Plan guide"], - ), - TaskSpec( - title="Review guide", - description="Review the draft and list concrete improvements.", - assignee="reviewer", - depends_on=["Draft guide"], - ), - ], - ) - - print(f"success={result.success}") - for agent_name, agent_result in result.agent_results.items(): - print(f"\n[{agent_name}]\n{agent_result.output[:600]}") +Independent tasks run concurrently; `depends_on` feeds one task's output into the next. +Drop `tasks` and call `crew.run("some goal")` to have the first agent plan the work itself. +`Crew` is a facade over the `AnyCode` engine, which stays public — see +[Run a multi-agent team](https://quantlix.github.io/anycode/latest/guides/multi-agent-team/) +for the engine-level API. +### 5b. Compose A Workflow With Branching -asyncio.run(main()) +```python +from anycode import END, START, Agent, Workflow + +workflow = Workflow() +workflow.add_node("draft", Agent(name="writer", tools=[]), input_key="topic", output_key="draft") +workflow.add_edge(START, "draft") +workflow.add_conditional_edge("draft", lambda state: END if state["draft"] else "draft") + +result = workflow.compile().run_sync({"topic": "hybrid search"}) +print(result.state["draft"], result.path) ``` +Use a crew when the work is a dependency graph, and a workflow when you need branching, +looping, or retry. See [Workflows](https://quantlix.github.io/anycode/latest/guides/workflows/). + + ### 6. Use YAML Or TOML Config Install the CLI extra first: diff --git a/mkdocs.yml b/mkdocs.yml index 43605cf..6ea9582 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -83,6 +83,10 @@ nav: - How-to Guides: - guides/index.md - Build and Run: + - Function Tools: guides/function-tools.md + - Run a Crew: guides/crews.md + - Build a Workflow: guides/workflows.md + - Long-Horizon Agents: guides/long-horizon-agents.md - Run a Multi-Agent Team: guides/multi-agent-team.md - Work With Tools: guides/tools.md - Structured Output: guides/structured-output.md @@ -124,6 +128,8 @@ nav: - Agents and Teams: concepts/agents-and-teams.md - Reference: - reference/index.md + - Recipes: reference/recipes.md + - Using AnyCode From an AI Agent: reference/llm-guide.md - Public API: reference/public-api.md - Complete API Inventory: reference/api-inventory.md - Runtime Contracts and Baseline: reference/runtime-contracts.md @@ -137,6 +143,7 @@ nav: - Development Workflow: contributing/development.md - Maintainer Governance: contributing/maintainers.md - Release Process: contributing/releasing.md + - Migrating to 0.10: contributing/migration-0.10.md - Testing and CI: contributing/testing.md - Architecture Decisions: contributing/architecture-decisions.md - ADR Template: contributing/adr-template.md diff --git a/pyproject.toml b/pyproject.toml index 3fc28c6..df297d2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "anycode-py" -version = "0.9.0" +version = "0.10.0" description = "Orchestrate autonomous AI agent teams with dependency-aware task scheduling, inter-agent messaging, and provider-agnostic LLM integration." readme = "README.md" license = "MIT" diff --git a/site_docs/contributing/migration-0.10.md b/site_docs/contributing/migration-0.10.md new file mode 100644 index 0000000..3720fff --- /dev/null +++ b/site_docs/contributing/migration-0.10.md @@ -0,0 +1,154 @@ +--- +title: "Migrating to AnyCode 0.10" +description: Nothing is required to move from AnyCode 0.9 to 0.10. Here is what is new, the one behavioral note worth knowing, and old-to-new snippets for each addition. +keywords: anycode 0.10 migration, upgrade anycode, backward compatible, tool decorator migration, agent keywords, crew workflow, lazy imports, breaking changes +--- + +# Migrating to 0.10 + +**Nothing is required.** Every 0.9 public symbol keeps its name, its import path, and its +semantics. Code written against 0.9 runs unchanged on 0.10. + +0.10 adds a layer on top: a shorter way to say the same things, plus two new composition +primitives. This page shows the old and new forms side by side so you can adopt what helps +and ignore what does not. + +## Defining a tool + +=== "0.9 (still supported)" + + ```python + class WeatherInput(BaseModel): + city: str = Field(description="City name.") + + async def lookup_weather_fn(params: WeatherInput, _ctx: ToolUseContext) -> ToolResult: + return ToolResult(data=json.dumps({...})) + + weather_tool = define_tool( + name="lookup_weather", + description="Retrieve current weather for a city.", + input_model=WeatherInput, + execute=lookup_weather_fn, + ) + ``` + +=== "0.10" + + ```python + @tool + def lookup_weather(city: str) -> dict: + """Retrieve current weather for a city. + + Args: + city: City name. + """ + return {...} + ``` + +Keep `define_tool` for schemas a signature cannot express. See +[Function tools](../guides/function-tools.md). + +## Building an agent + +=== "0.9 (still supported)" + + ```python + registry = ToolRegistry() + register_built_in_tools(registry) + registry.register(weather_tool) + executor = ToolExecutor(registry) + + agent = Agent( + AgentConfig(name="collector", model=MODEL, provider=PROVIDER, tools=["lookup_weather"]), + registry, + executor, + ) + result = await agent.run("...") + ``` + +=== "0.10" + + ```python + agent = Agent( + name="collector", + instructions="You collect data.", + tools=[lookup_weather], + ) + result = agent.run_sync("...") + ``` + +The three-positional-argument constructor is unchanged and is still what +`AnyCode.build_agent` uses. Passing a config object **and** a conflicting field keyword +raises `AgentConfigError` naming the conflict. + +## Running a team + +=== "0.9 (still supported)" + + ```python + engine = AnyCode({"max_concurrency": 3}) + team = engine.create_team("crew", TeamConfig(name="crew", agents=[cfg_a, cfg_b])) + result = await engine.run_tasks(team, [TaskSpec("A", "..."), TaskSpec("B", "...", depends_on=["A"])]) + ``` + +=== "0.10" + + ```python + crew = Crew(agents=[agent_a, agent_b], tasks=[ + TaskSpec("A", "..."), + TaskSpec("B", "...", depends_on=["A"]), + ]) + result = crew.run_sync() + ``` + +`Crew` owns an `AnyCode` engine and a `Team`; the scheduler is the same. Pass an engine you +configured yourself with `engine=`. + +## The one behavioral note + +`Agent(tools=[])` now means **no tools**. In 0.9 an empty list was indistinguishable from +`None`, which means "every built-in tool". `tools=None` is still the default and still +means every built-in. + +If you were passing `tools=[]` to an `AgentConfig` expecting all built-ins, pass +`tools=None` instead. + +## Additions worth knowing about + +| Addition | Where | +|---|---| +| `@tool` decorator | [Function tools](../guides/function-tools.md) | +| Keyword `Agent(...)`, `role`/`goal`/`backstory`, provider auto-detection | [Quickstart](../getting-started/quickstart.md) | +| `run_sync`, `prompt_sync`, `stream_sync`, `call_tool` | [Recipes](../reference/recipes.md) | +| `Crew` and `CrewResult` | [Crews](../guides/crews.md) | +| `Workflow`, `START`, `END`, `Command`, reducers | [Workflows](../guides/workflows.md) | +| `planning=`, `subagents=`, `workspace=` on `Agent` | [Long-horizon agents](../guides/long-horizon-agents.md) | +| `anycode api` and `anycode.describe()` | [LLM guide](../reference/llm-guide.md) | +| `TaskSpec(agent=..., expected_output=...)` | [Crews](../guides/crews.md) | +| `AnyCode.register_agent(agent)` | adopt a pre-built agent into an engine | + +## Import cost + +`import anycode` no longer imports every subsystem. It dropped from roughly 1.9 seconds and +1300 modules to about 30 milliseconds and 70 modules; symbols resolve on first access. + +Two consequences worth knowing: + +- Optional dependencies (chromadb, redis, OpenTelemetry, the MCP SDK, provider clients) are + imported only when the code path that needs them runs. +- A misspelled import now raises `AttributeError` with a suggestion rather than + `ImportError`. + +If you monkeypatched a symbol on `anycode.core.orchestrator` that it imported from +elsewhere — `MCPClient` and `discover_and_register` are the two — patch the source module +(`anycode.mcp.client`, `anycode.mcp.bridge`) instead. + +## Also fixed + +- `anycode.types`, `anycode.helpers`, `anycode.contracts`, `anycode.identity`, + `anycode.core`, and `anycode.memory` are each importable on their own. A latent circular + import previously made `import anycode.types` fail unless `anycode` was imported first. +- `Agent.call_tool` supplies an idempotency key, so side-effecting tools can be invoked + directly. +- `FilesystemRunStore.mark_interrupted_runs` treats the staleness cutoff as inclusive, so + `stale_after_seconds=0` means "every running run is stale" on every platform. diff --git a/site_docs/getting-started/quickstart.md b/site_docs/getting-started/quickstart.md index b00fb19..0d24771 100644 --- a/site_docs/getting-started/quickstart.md +++ b/site_docs/getting-started/quickstart.md @@ -1,188 +1,215 @@ --- -title: "AnyCode Quickstart — Run Your First Agent and Team" -description: Run your first AnyCode agent, then a dependency-aware team of planner, writer, and reviewer agents, using provider auto-detection for Anthropic or OpenAI. -keywords: anycode quickstart, run ai agent python, multi-agent team, task dependencies, anthropic openai agent, run_agent, run_tasks, create_team +title: "AnyCode Quickstart — Your First Agent, Crew, and Workflow" +description: Build an AnyCode agent with a custom tool in ten lines, then a crew with dependent tasks, then a workflow graph with a review loop, using automatic provider detection. +keywords: anycode quickstart, python ai agent, tool decorator, crew tasks, workflow graph, run_sync, provider auto detection, first agent, multi agent python --- -# AnyCode Quickstart +# Quickstart -Run your first AnyCode agent in a few lines of Python, then coordinate a three-agent team with task dependencies. This quickstart uses provider auto-detection, so it works whether you have an Anthropic or an OpenAI key. - -You will build two scripts: a single agent that answers one prompt, and a planner → writer → reviewer team where each task feeds the next. Both use the same core API — `AnyCode`, `run_agent`, `run_tasks`, and `create_team` — so the jump from one agent to a coordinated team is small. +Three levels, each building on the last. Every snippet is complete — copy it into a file +and run it. !!! note "Before you start" - You need AnyCode installed on Python 3.12+ and at least one provider key (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) in your environment. See [Installation](installation.md) if you have not done that yet. - -## Run your first agent + Python 3.12+, AnyCode installed, and one provider key in your environment or `.env` + (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, or `OLLAMA_BASE_URL`). + See [Installation](installation.md). -Create `quickstart_agent.py`. The script picks a provider and model from whichever key it finds, spins up an `AnyCode` engine, and runs one agent to completion: +--- -```python title="quickstart_agent.py" -import asyncio -import os +## Level 1 — one agent, one tool +```python +# quickstart_agent.py from dotenv import load_dotenv -from anycode import AnyCode +from anycode import Agent, tool load_dotenv() -def resolve_model() -> tuple[str, str]: - if os.environ.get("ANTHROPIC_API_KEY"): - return "anthropic", "claude-haiku-4-5" - if os.environ.get("OPENAI_API_KEY"): - return "openai", "gpt-4o-mini" - raise RuntimeError("Set ANTHROPIC_API_KEY or OPENAI_API_KEY first.") +@tool +def word_count(text: str) -> int: + """Count the words in a block of text.""" + return len(text.split()) -async def main() -> None: - provider, model = resolve_model() - engine = AnyCode(config={"default_provider": provider, "default_model": model}) +editor = Agent( + name="editor", + instructions="You are a concise copy editor. Use your tools rather than guessing.", + tools=[word_count], +) - result = await engine.run_agent( - config={ - "name": "explainer", - "provider": provider, - "model": model, - "system_prompt": "You explain Python clearly and briefly.", - "tools": [], - "max_turns": 2, - }, - prompt="Explain what an async generator is in two sentences.", - ) +result = editor.run_sync("How many words are in: 'the quick brown fox jumps over it'?") +print(result.output) +print(f"{result.token_usage.input_tokens} in / {result.token_usage.output_tokens} out") +``` - print(result.output) - print(f"tokens: in={result.token_usage.input_tokens} out={result.token_usage.output_tokens}") +```bash +uv run python quickstart_agent.py +``` +Three things happened without you asking: -asyncio.run(main()) -``` +- **The provider was detected** from whichever API key is set, along with a sensible default + model. Pass `provider=` and `model=` to override. +- **The tool schema was derived** from the signature, and its description from the + docstring. No input model, no registry, no executor. +- **`run_sync` handled the event loop.** Use `await agent.run(...)` inside async code. -Run it: +Streaming and conversation are one method away: -```bash -uv run python quickstart_agent.py +```python +for event in editor.stream_sync("Explain closures in one sentence."): + if event.type == "text": + print(event.data, end="", flush=True) + +editor.prompt_sync("What is a generator?") +editor.prompt_sync("Show one example.") # remembers the first turn ``` -The `run_agent` call returns a result object with two things worth noting: +--- + +## Level 2 — a crew with dependent tasks -- `result.output` — the agent's final text response. -- `result.token_usage` — input and output token counts for the run. +When one agent is not enough, give each a role and let the work flow between them. -!!! tip "Give the agent tools" - This agent runs with `tools: []`, so it only reasons and replies. To let an agent read files, run commands, or call your own functions, pass built-in or custom tools — see [Work with tools](../guides/tools.md). +```python +# quickstart_crew.py +from dotenv import load_dotenv -## Run a team with dependencies +from anycode import Agent, Crew, TaskSpec -A single agent answers one prompt. A team coordinates several agents through a task graph. Create `quickstart_team.py` — it defines a `planner`, a `writer`, and a `reviewer`, then wires three tasks so each one depends on the previous: +load_dotenv() + +researcher = Agent( + name="researcher", + role="a research analyst", + goal="gather concrete, verifiable facts", + tools=[], +) +writer = Agent( + name="writer", + role="a technical writer", + goal="turn findings into prose a busy reader finishes", + backstory="You write for engineers who want the point in the first sentence.", + tools=[], +) + +crew = Crew( + agents=[researcher, writer], + tasks=[ + TaskSpec("Research", "List three concrete tradeoffs of vector databases.", agent=researcher), + TaskSpec( + "Write", + "Turn those tradeoffs into a short briefing.", + agent=writer, + depends_on=["Research"], + expected_output="Under 120 words, no bullet points.", + ), + ], + verbose=True, +) + +result = crew.run_sync() +print(result) # the final task's output +print(result.usage.output_tokens) +``` -```python title="quickstart_team.py" +`depends_on` names the earlier task by title; its output is fed into the later prompt. +Independent tasks run concurrently. Set `process="sequential"` to chain everything in +declaration order, or drop `tasks` entirely and call `crew.run("some goal")` to have the +first agent plan the work itself. + +--- + +## Level 3 — a workflow with a loop + +A crew fans out over dependencies. When you need branching, looping, or retry, use a +workflow graph. + +```python +# quickstart_workflow.py import asyncio -import os from dotenv import load_dotenv +from pydantic import BaseModel, ConfigDict -from anycode import AgentConfig, AnyCode, TaskSpec, TeamConfig +from anycode import END, START, Agent, Workflow load_dotenv() -PROVIDER = "anthropic" if os.environ.get("ANTHROPIC_API_KEY") else "openai" -MODEL = "claude-haiku-4-5" if PROVIDER == "anthropic" else "gpt-4o-mini" +class ReviewState(BaseModel): + model_config = ConfigDict(frozen=True) -async def main() -> None: - engine = AnyCode(config={"max_concurrency": 3}) - - team = engine.create_team( - "guide-crew", - TeamConfig( - name="guide-crew", - shared_memory=True, - agents=[ - AgentConfig( - name="planner", - provider=PROVIDER, - model=MODEL, - system_prompt="Create concise technical plans.", - tools=[], - ), - AgentConfig( - name="writer", - provider=PROVIDER, - model=MODEL, - system_prompt="Turn plans into clear developer documentation.", - tools=[], - ), - AgentConfig( - name="reviewer", - provider=PROVIDER, - model=MODEL, - system_prompt="Review documentation for clarity and missing steps.", - tools=[], - ), - ], - ), - ) - - result = await engine.run_tasks( - team, - [ - TaskSpec( - title="Plan guide", - description="Outline a getting started guide for a Python agent framework.", - assignee="planner", - ), - TaskSpec( - title="Draft guide", - description="Write the guide using the planner output.", - assignee="writer", - depends_on=["Plan guide"], - ), - TaskSpec( - title="Review guide", - description="Review the draft and list concrete improvements.", - assignee="reviewer", - depends_on=["Draft guide"], - ), - ], - ) - - print(f"success={result.success}") - for agent_name, agent_result in result.agent_results.items(): - print(f"\n[{agent_name}]\n{agent_result.output[:600]}") + topic: str = "" + draft: str = "" + critique: str = "" + rounds: int = 0 -asyncio.run(main()) -``` +writer = Agent(name="writer", instructions="Write a two-sentence technical blurb.", tools=[]) +critic = Agent( + name="critic", + instructions="Reply with exactly APPROVED, or one sentence naming the biggest problem.", + tools=[], +) -Run it: +workflow = Workflow(ReviewState) -```bash -uv run python quickstart_team.py -``` -The key pieces of the team API are: +@workflow.node +async def write(state: ReviewState) -> dict: + prior = f"\n\nFix this: {state.critique}" if state.critique else "" + result = await writer.run(f"Write about {state.topic}.{prior}") + return {"draft": result.output, "rounds": state.rounds + 1} -- `TeamConfig` and `AgentConfig` — declare the team and the role, provider, model, and tools of each agent. -- `shared_memory=True` — lets agents share context across the run. -- `TaskSpec(..., depends_on=[...])` — declares which tasks must finish before a task can start. -- `create_team` and `run_tasks` — register the team and execute the task graph. -## What happened +@workflow.node +async def review(state: ReviewState) -> dict: + result = await critic.run(state.draft) + return {"critique": result.output} -The team example creates three agents and three tasks. When you call `run_tasks`, AnyCode: -1. Resolves the `depends_on` relationships into a dependency graph. -2. Runs each ready task in a concurrent wave, bounded by `max_concurrency`. -3. Passes each dependency's result into the prompts of the tasks that follow it. -4. Returns a `TeamRunResult` with per-agent outputs, token usage, lifecycle data, and optional verification data. +def gate(state: ReviewState) -> str: + approved = "APPROVED" in state.critique.upper() + return END if approved or state.rounds >= 3 else "write" -Because `Draft guide` depends on `Plan guide` and `Review guide` depends on `Draft guide`, the three tasks run in order — the writer sees the planner's output, and the reviewer sees the writer's draft. -## Next steps +workflow.add_edge(START, "write") +workflow.add_edge("write", "review") +workflow.add_conditional_edge("review", gate) + + +async def main() -> None: + app = workflow.compile() + print(app.to_mermaid()) + result = await app.run(ReviewState(topic="hybrid search"), max_steps=8) + print(result.state.draft) + print("path:", " -> ".join(result.path)) + + +asyncio.run(main()) +``` + +Nodes return a **patch** — the fields they changed — and never mutate state. `compile()` +validates the graph before anything runs and reports every structural problem at once. +`max_steps` turns a runaway loop into an inspectable result instead of a hang. + +--- -- [Agents and teams](../concepts/agents-and-teams.md) — the mental model behind agents, tasks, and team runs. -- [Run a multi-agent team](../guides/multi-agent-team.md) — a fuller walkthrough of team coordination. -- [Work with tools](../guides/tools.md) — let agents read files, call APIs, or run local functions. -- [Use YAML config](../guides/yaml-config.md) — define and run the same workflows outside Python code. +## Where to go next + +| You want | Read | +|---|---| +| More on tools | [Function tools](../guides/function-tools.md) | +| More on teams | [Crews](../guides/crews.md) | +| More on graphs | [Workflows](../guides/workflows.md) | +| Long-running research agents | [Long-horizon agents](../guides/long-horizon-agents.md) | +| Copy-paste snippets | [Recipes](../reference/recipes.md) | +| Durability, gates, sandboxes | [How-to guides](../guides/index.md) | + +Everything above is a facade over the `AnyCode` engine, which stays public and unchanged. +When you need durable runs, MCP servers, plugins, routing, or verification gates, either +pass those options through `Crew(...)` or use +[`AnyCode`](../guides/multi-agent-team.md) directly. diff --git a/site_docs/guides/crews.md b/site_docs/guides/crews.md new file mode 100644 index 0000000..86a8971 --- /dev/null +++ b/site_docs/guides/crews.md @@ -0,0 +1,133 @@ +--- +title: "Run a Crew — Multi-Agent Teams With Dependent Tasks" +description: Build an AnyCode Crew from agents and tasks, choose sequential or dependency execution, set expected output, and read results without touching the orchestrator. +keywords: anycode crew, multi agent python, dependent tasks, sequential process, expected output, crew result, agent team, task dependencies, crew kickoff +--- + +# Run a crew + +A `Crew` is a team of agents working through a list of tasks. It owns an `AnyCode` engine +and a `Team` underneath and adds no scheduling of its own — the same wavefront scheduler +runs the work. + +```python +from anycode import Agent, Crew, TaskSpec + +analyst = Agent(name="analyst", role="a market analyst", goal="state the plain facts", tools=[]) +writer = Agent(name="writer", role="a newsletter writer", goal="turn figures into a note", tools=[]) + +crew = Crew( + agents=[analyst, writer], + tasks=[ + TaskSpec("Collect", "Look up the closing prices for ACME and GLOBEX.", agent=analyst), + TaskSpec( + "Write", + "Write a three-sentence market note.", + agent=writer, + depends_on=["Collect"], + expected_output="Exactly three sentences, no bullet points.", + ), + ], + verbose=True, +) + +result = crew.run_sync() +print(result.output) +``` + +## Declaring tasks + +`tasks=` accepts three shapes: + +```python +tasks=["summarize the changelog"] # a bare title +tasks=[{"title": "T", "description": "D", "expected_output": "E"}] +tasks=[TaskSpec("T", "D", agent=writer, depends_on=["Other"])] +``` + +A task with no assignee goes to the first agent in the crew. Assigning a task to someone +outside the crew raises `CrewError` listing the members. + +`expected_output` is appended to the prompt as an explicit `Expected output:` line. It is +the cheapest way to make a result usable by the next task. + +## Sequential or dependency-driven + +```python +Crew(agents=[...], tasks=[...], process="dependency") # default: declared edges only +Crew(agents=[...], tasks=[...], process="sequential") # each task waits for the previous one +``` + +Under `sequential`, a task that already declares `depends_on` keeps its own edge — the +chaining only fills in the blanks. Under `dependency`, independent tasks run concurrently. + +## Letting the crew plan + +Leave `tasks` out and pass a goal to `run()`. The first agent decomposes the goal, assigns +work to the roster, and the crew executes the resulting plan: + +```python +import asyncio +from anycode import Agent, Crew + +async def main() -> None: + async with Crew(agents=[analyst, writer], name="research-desk") as crew: + result = await crew.run("Report which ticker closed highest and why it matters.") + print(result.output) + +asyncio.run(main()) +``` + +## Reading the result + +`CrewResult` gives you the ergonomic accessors and keeps the full engine result attached: + +| Field | Meaning | +|---|---| +| `success` | every task succeeded | +| `output` | the final task's output — `str(result)` returns this | +| `outputs` | agent name → output | +| `usage` | combined `TokenUsage` | +| `cost` | `CostReport` when cost tracking is on | +| `team_result` | the complete `TeamRunResult` — handoffs, route decisions, lifecycle events, gate decisions | + +## Engine features + +Any `OrchestratorConfig` field can be passed straight through: + +```python +crew = Crew( + agents=[...], + tasks=[...], + max_concurrency=4, + cost={"enabled": True, "budget_usd": 1.0}, + checkpoint={"enabled": True, "path": ".anycode/checkpoints"}, + routing={"enabled": True}, +) +``` + +An unknown option raises `CrewError` listing the valid ones rather than a Pydantic +traceback. To reuse an engine you already configured — with MCP servers connected or +plugins installed — pass `engine=`. A crew never closes an engine it did not create. + +## Lifecycle + +```python +async with Crew(agents=[...], tasks=[...]) as crew: + result = await crew.run() +``` + +The context manager connects MCP servers on entry and releases engine resources on exit. +`run_sync()` does both around a single blocking call. + +## Crew or workflow? + +Use a **crew** when the shape of the work is a dependency graph known up front. Use a +[**workflow**](workflows.md) when you need branching, looping, or retry — control flow the +dependency graph cannot express. A crew can be a node inside a workflow. + +## See also + +- [Workflows](workflows.md) +- [Multi-agent teams](multi-agent-team.md) — the underlying `AnyCode` + `Team` API +- [Recipes](../reference/recipes.md) diff --git a/site_docs/guides/function-tools.md b/site_docs/guides/function-tools.md new file mode 100644 index 0000000..2b975c2 --- /dev/null +++ b/site_docs/guides/function-tools.md @@ -0,0 +1,144 @@ +--- +title: "Turn Python Functions Into Agent Tools With @tool" +description: Use the AnyCode @tool decorator to expose any Python function as an agent tool, with the signature becoming the schema and the docstring the description. +keywords: anycode tool decorator, python function as llm tool, tool schema from type hints, google docstring tool description, tool context injection, async tool +--- + +# Work with function tools + +The `@tool` decorator turns any Python function into a tool an agent can call. The +signature becomes the input schema, the docstring becomes the description the model reads, +and the return value is converted into a `ToolResult`. + +```python +from anycode import Agent, tool + +@tool +def convert_currency(amount: float, rate: float, target: str = "EUR") -> dict: + """Convert an amount using a fixed exchange rate. + + Args: + amount: The source amount to convert. + rate: Units of the target currency per unit of the source currency. + target: ISO code of the target currency. + """ + return {"converted": round(amount * rate, 2), "currency": target} + +agent = Agent(name="analyst", instructions="Use tools for every calculation.", tools=[convert_currency]) +print(agent.run_sync("Convert 250 at a rate of 0.92.").output) +``` + +That is the whole setup. There is no registry to create, no input model to declare, and no +executor to wire. + +## What the decorator derives + +| From the function | Becomes | +|---|---| +| `__name__` | the tool name | +| Docstring summary | the tool description | +| `Args:` entries | per-parameter descriptions in the schema | +| Type hints | the JSON Schema types | +| Defaults | optional parameters | +| Parameters with no default | required parameters | + +Google-style docstrings are parsed for the `Args:` block. An unparseable docstring degrades +to summary-only rather than raising — but a function with **no** description at all raises +`ToolDefinitionError` at decoration time, because a tool the model cannot understand is +worse than no tool. + +## Configuring the tool + +```python +@tool(name="business_days", description="Count business days since a date.", side_effecting=False) +async def days_since(iso_date: str) -> int: + ... +``` + +`side_effecting=True` opts the tool into the idempotency claim store, so a retried call is +replayed rather than repeated. + +## Async and sync + +Both work. An async function is awaited directly; a synchronous function runs on a worker +thread, so a blocking call never stalls the event loop. + +## Constraints and rich types + +`Annotated` metadata is preserved, so Pydantic constraints reach the schema and reject bad +input before your function runs: + +```python +from typing import Annotated +from pydantic import Field + +@tool +def scaled(value: Annotated[int, Field(ge=0, le=10, description="Clamped value.")]) -> int: + """Double a bounded value.""" + return value * 2 +``` + +## Reading the calling context + +Declare a parameter annotated `ToolUseContext` — or conventionally named `ctx`, `context`, +or `tool_context` — and it is injected at call time and excluded from the schema: + +```python +from anycode import ToolUseContext, tool + +@tool +def whoami(ctx: ToolUseContext) -> str: + """Report the calling agent.""" + return f"{ctx.agent.name} running {ctx.agent.model}" +``` + +## Return values + +| You return | The agent sees | +|---|---| +| `str` | the string | +| `dict`, `list`, `int`, `float`, `bool` | JSON | +| a Pydantic model | its JSON | +| `None` | an empty result | +| `ToolResult` | passed through, flags intact | + +Raising an exception produces an error result with a redacted message — you do not need to +catch and wrap. + +## The function stays a function + +The decorator returns your function unchanged, so it is still directly callable: + +```python +assert convert_currency(100.0, 0.92) == {"converted": 92.0, "currency": "EUR"} +``` + +Unit-test tools as ordinary functions. To exercise one through the full validation and +security path without an LLM, use `agent.call_tool_sync("convert_currency", amount=100, rate=0.92)`. + +## Mixing tool sources + +`tools=` accepts decorated functions, plain functions, `ToolDefinition` objects, and the +names of bundled tools: + +```python +agent = Agent(name="mixed", tools=[convert_currency, "bash", "file_read", some_definition]) +``` + +- `tools=None` (the default) allows every built-in tool. +- `tools=[]` means no tools at all. +- A duplicate name raises `ToolDefinitionError` naming the collision. + +Run `anycode inspect tools` to list the bundled names. + +## When to use `define_tool` instead + +`@tool` covers most cases. Reach for [`define_tool`](tools.md) when you need an input model +that cannot be expressed as a signature — a deeply nested schema, a discriminated union, or +a model shared with the rest of your application. + +## See also + +- [Recipes](../reference/recipes.md) — copy-paste snippets +- [Built-in tools](../reference/built-in-tools.md) +- [Tools reference](tools.md) — the typed `define_tool` path diff --git a/site_docs/guides/long-horizon-agents.md b/site_docs/guides/long-horizon-agents.md new file mode 100644 index 0000000..81ff61d --- /dev/null +++ b/site_docs/guides/long-horizon-agents.md @@ -0,0 +1,137 @@ +--- +title: "Long-Horizon Agents — Planning, Sub-Agents, and a Workspace" +description: Switch on planning, sub-agent delegation, and a confined workspace with three keywords on the same AnyCode Agent, with no separate deep-agent class to learn. +keywords: anycode long horizon agent, deep agent python, write_todos planning tool, sub agent delegation, agent workspace, tool security policy, subagentspec +--- + +# Long-horizon agents + +Long-running work needs three things a single-turn agent does not: an explicit plan, a way +to hand isolated sub-tasks to focused helpers, and somewhere to put intermediate artifacts +so they stop consuming context. + +In AnyCode these are keywords on the `Agent` you already use. **There is no separate +deep-agent class.** Each is inert unless you switch it on, so a plain agent's prompt and +tool set are untouched. + +```python +from anycode import Agent, SubAgentSpec, tool + +@tool +def search(query: str) -> str: + """Search the corpus.""" + ... + +agent = Agent( + name="researcher", + instructions="Research the topic thoroughly and produce a written report.", + tools=[search, "file_write", "file_read", "list_files"], + planning=True, + subagents=[SubAgentSpec(name="critic", instructions="Critique a draft. Be specific.")], + workspace="./.anycode/workspace", + max_turns=40, +) + +result = agent.run_sync("Write a report on hybrid search tradeoffs.") +print(agent.todos) +``` + +## Planning + +`planning=True` registers the `write_todos` tool and adds one clause to the system prompt. +The tool returns the rendered checklist as its result, so the plan re-enters the +conversation every time it changes — that feedback loop is what keeps a long run oriented. + +```text +[x] Look up the cache spec +[>] Draft the comparison +[ ] Have the reviewer critique it + +1/3 complete. +``` + +Read the plan from your own code with `agent.todos`, a tuple of `TodoItem`. Exactly one +step may be `in_progress`; sending more returns an error result telling the model to fix +it, because a model mistake is not a program fault. + +## Sub-agents + +`subagents=` registers a `delegate` tool over the specs you provide: + +```python +SubAgentSpec( + name="critic", + instructions="Critique a draft. Be specific.", + tools=[], # defaults to none + model=None, # inherits the parent's model + provider=None, # inherits the parent's provider + max_turns=None, # inherits the parent's limit +) +``` + +A sub-agent is a full `Agent`, built lazily on first use, inheriting the parent's model, +provider, security policy, and execution context. It runs on a **fresh conversation** — +only the task text and the context the caller chooses to pass cross the boundary. That +isolation is the point: the parent's context stays small while a focused agent does narrow +work. + +Sub-agents never receive the `delegate` tool themselves, so delegation depth is one by +construction and a runaway fan-out is impossible. Their token usage is merged into the +parent's `AgentRunResult`, so `result.token_usage` is the true total. + +Delegating to a name that does not exist returns an error result listing the valid ones. + +## Workspace + +`workspace=` creates the directory and confines the file tools to it using the existing +`ToolSecurityPolicy`: + +```python +ToolSecurityPolicy( + workspace_root="/abs/path", + allowed_path_roots=("/abs/path",), + allow_shell=False, # True when "bash" is in tools= +) +``` + +Artifacts are real files, so a run is inspectable after the fact. A write outside the root +is rejected before it reaches the filesystem. `agent.workspace` holds the resolved path. + +If you pass `tool_security=` explicitly, your policy wins and `workspace=` only creates the +directory — AnyCode never silently overrides a security decision you made. + +## Prompt clauses + +Each capability appends one short clause after your `instructions`, in a fixed order: +planning, then delegation, then workspace. They are module constants +(`PLANNING_CLAUSE`, `DELEGATION_CLAUSE`, `WORKSPACE_CLAUSE` in `anycode.core.agent`) and +are snapshot-tested, so prompt drift shows up as a reviewable diff. + +With no capabilities switched on, your instructions reach the model verbatim. + +## Combining with the rest + +The capabilities compose with everything else on `Agent`: + +```python +agent = Agent( + name="researcher", + instructions="...", + tools=[search], + planning=True, + subagents=[critic], + workspace="./work", + context_policy=ContextPolicy(...), # context compaction + verification=(...,), # quality gates + provider_resilience=ProviderResilienceConfig(...), +) +``` + +A long-horizon agent can also be a node in a [workflow](workflows.md) or a member of a +[crew](crews.md). + +## See also + +- [Function tools](function-tools.md) +- [Engineer the context window](context-engineering.md) +- `examples/48_long_horizon_agent.py` diff --git a/site_docs/guides/multi-agent-team.md b/site_docs/guides/multi-agent-team.md index 880742e..c3b7b0a 100644 --- a/site_docs/guides/multi-agent-team.md +++ b/site_docs/guides/multi-agent-team.md @@ -6,6 +6,12 @@ keywords: multi-agent team, AnyCode, agent orchestration, task dependencies, DAG # Run a Multi-Agent Team +!!! tip "For most teams, start with a Crew" + [`Crew`](crews.md) wraps everything on this page in one object: `Crew(agents=[...], + tasks=[...])` builds the engine and the team for you and runs the same scheduler. This + page covers the engine-level API, which you need for durable runs, MCP servers, + plugins, and custom pool management — and which `Crew` exposes as `crew.engine`. + Run a multi-agent team in AnyCode by creating an engine, defining role-scoped agents, wiring tasks with explicit dependencies, and awaiting `run_tasks`. This guide builds a three-agent crew, planner then builder then reviewer, that passes work down a dependency chain and returns one structured result you can inspect. A single agent is enough for a one-shot task. Reach for a team when the work has distinct roles, when one step must finish before the next begins, or when you want each stage to be auditable on its own. AnyCode schedules the tasks as a directed graph, runs independent work concurrently up to a concurrency limit, and collects every agent's output into a single `TeamRunResult`. diff --git a/site_docs/guides/tools.md b/site_docs/guides/tools.md index a8edd9d..b7bf530 100644 --- a/site_docs/guides/tools.md +++ b/site_docs/guides/tools.md @@ -8,6 +8,13 @@ keywords: AnyCode tools, custom tools, define_tool, ToolRegistry, ToolExecutor, Give an AnyCode agent tools by listing built-in tool names in its `AgentConfig`, or build a custom tool with `define_tool()` and a Pydantic input model and register it in a `ToolRegistry`. Every AnyCode tool is a typed async function with four parts: a name, a description, a Pydantic input model, and an execute function that returns a `ToolResult`. +!!! tip "Most tools do not need any of this" + The [`@tool` decorator](function-tools.md) derives the input model from a function + signature and the description from its docstring, so a tool is one decorated function. + This page covers the typed `define_tool` path — reach for it when you need a schema a + signature cannot express, such as a deeply nested model, a discriminated union, or a + model shared with the rest of your application. + The Pydantic model does double duty. It validates arguments before your code runs, and it becomes the JSON schema the provider sees when it decides how to call the tool. Clear field descriptions therefore improve both safety and the quality of the model's tool calls. ## Built-in AnyCode tools diff --git a/site_docs/guides/workflows.md b/site_docs/guides/workflows.md new file mode 100644 index 0000000..13ebfe0 --- /dev/null +++ b/site_docs/guides/workflows.md @@ -0,0 +1,181 @@ +--- +title: "Build a Workflow Graph — Branching, Loops, and Explicit State" +description: Compose AnyCode agents into a state graph with nodes, conditional edges, reducers, and a step cap, then stream, render, and run it with full control flow. +keywords: anycode workflow, state graph python, conditional edge, agent loop, reducer, langgraph alternative, workflow streaming, mermaid graph, max steps +--- + +# Build a workflow + +A `Workflow` is an explicit state graph: you register nodes, connect them, and compile. +Where a [crew](crews.md) fans out over task dependencies, a workflow gives you branching, +looping, retry, and human checkpoints — control flow a dependency graph cannot express. + +```python +import asyncio +from typing import Annotated +from pydantic import BaseModel, ConfigDict +from anycode import END, START, Agent, Workflow +from anycode.workflow import add + +class ReviewState(BaseModel): + model_config = ConfigDict(frozen=True) + topic: str = "" + draft: str = "" + critique: str = "" + rounds: int = 0 + log: Annotated[list[str], add] = [] + +writer = Agent(name="writer", instructions="Write a two-sentence blurb.", tools=[]) +critic = Agent(name="critic", instructions="Reply APPROVED, or name the biggest problem.", tools=[]) + +workflow = Workflow(ReviewState) + +@workflow.node +async def write(state: ReviewState) -> dict: + result = await writer.run(f"Write about {state.topic}. Prior critique: {state.critique}") + return {"draft": result.output, "rounds": state.rounds + 1, "log": [f"round {state.rounds + 1}"]} + +@workflow.node +async def review(state: ReviewState) -> dict: + result = await critic.run(state.draft) + return {"critique": result.output} + +def gate(state: ReviewState) -> str: + return END if "APPROVED" in state.critique.upper() or state.rounds >= 3 else "write" + +workflow.add_edge(START, "write") +workflow.add_edge("write", "review") +workflow.add_conditional_edge("review", gate) + +result = asyncio.run(workflow.compile().run(ReviewState(topic="vector databases"))) +print(result.state.draft, result.path) +``` + +## State + +State is a frozen Pydantic model you supply, or a plain `dict` when you call `Workflow()` +with no schema. A node never mutates it — it returns a **patch** describing what changed: + +| A node returns | Effect | +|---|---| +| `dict` | those fields are merged | +| a state instance | its fields are merged | +| `None` | no change | +| `Command` | routing override, with an optional patch | + +Returning a field the schema does not declare raises `WorkflowError` naming the field and +listing the valid ones — a typo fails loudly instead of vanishing. + +### Reducers + +By default a patch replaces a field. Annotate a field with a reducer to accumulate instead: + +```python +log: Annotated[list[str], add] = [] # appends +counters: Annotated[dict, merge] = {} # shallow-merges +tokens: Annotated[int, add] = 0 # sums +first_seen: Annotated[str, keep_first] = "" +``` + +`add`, `merge`, `keep_first`, and `keep_last` ship in `anycode.workflow`. Any +`Callable[[current, incoming], value]` works. + +## Nodes + +A node may be: + +- an `async def` taking state +- a plain `def` taking state — run on a worker thread so it never blocks the loop +- an `Agent` — `add_node("ask", agent, input_key="question", output_key="answer")` +- a `Crew` +- another `CompiledWorkflow`, as a sub-graph + +`Agent`, `Crew`, and sub-graph nodes have their token usage accumulated into +`result.usage` automatically. A plain function that calls an agent itself does not — track +those tokens in state with an `add`-annotated field. + +Register with `add_node(name, target)`, or use the decorator form `@workflow.node` / +`@workflow.node(name="custom")`. + +## Edges + +```python +workflow.add_edge(START, "first") # entry point +workflow.add_edge("first", "second") # unconditional +workflow.add_edge("second", END) # terminate +workflow.add_edge("split", "left") # repeat a source +workflow.add_edge("split", "right") # to fan out concurrently +workflow.add_conditional_edge("check", router) # router(state) -> node name or END +workflow.add_conditional_edge("check", router, {"ok": END, "retry": "first"}) # via a path map +``` + +A node with no outgoing edge routes to `END`. A node routes one way or the other — mixing a +static and a conditional edge on the same node raises immediately. + +Fan-out targets run concurrently and their patches merge. Two concurrent nodes writing the +same unreduced field raise `WorkflowError` naming both — annotate the field with a reducer, +or have one node own it. + +### Dynamic routing from inside a node + +```python +from anycode import Command + +workflow.add_node("triage", triage_fn, goto=["escalate", "resolve"]) + +def triage_fn(state): + return Command(goto="escalate" if state.severity > 3 else "resolve", update={"seen": True}) +``` + +`goto=` on `add_node` declares which nodes a `Command` may jump to. Declaring them keeps +reachability analysis accurate — a node reachable only by `Command` would otherwise look +like an orphan. + +## Compiling + +`compile()` validates the graph and returns an immutable `CompiledWorkflow`. It reports +every structural problem at once: + +- no entry point, or no nodes +- an edge or path-map entry pointing at an unregistered node +- a node unreachable from the entry point +- a cycle that can never reach `END` + +Editing the builder afterwards does not affect an already-compiled graph. + +## Running + +```python +result = await app.run(state, max_steps=25) +result = app.run_sync(state) +``` + +`WorkflowResult` carries `success`, `state`, `steps`, `path`, `usage`, `stop_reason`, and +`error`. Exceeding `max_steps` returns `success=False` with +`stop_reason.code == "max_steps"` and `recoverable=True` rather than raising — a runaway +loop is a result you can inspect, not a crash. + +## Streaming and rendering + +```python +async for event in app.stream(state): + if event.type == "node_start": + print("->", event.node) + elif event.type == "route": + print(" ", event.node, "routes to", ", ".join(event.targets)) + elif event.type == "done": + final = event.result +``` + +Event types are `node_start`, `node_end`, `route`, `error`, and `done`. `run()` is built on +`stream()`, so there is exactly one execution path. + +`app.to_mermaid()` renders a flowchart and `app.to_dict()` returns a JSON-friendly +description. A conditional edge without a path map is drawn as `?` to every candidate, +since its targets are only known at runtime — supply `path_map=` for a precise diagram. + +## See also + +- [Crews](crews.md) — declarative dependency fan-out +- [Recipes](../reference/recipes.md) +- `examples/47_workflow_graph.py` diff --git a/site_docs/reference/llm-guide.md b/site_docs/reference/llm-guide.md new file mode 100644 index 0000000..f739153 --- /dev/null +++ b/site_docs/reference/llm-guide.md @@ -0,0 +1,108 @@ +--- +title: "Using AnyCode From an AI Coding Agent" +description: A compact orientation for AI coding agents writing AnyCode: the core surface, which abstraction to pick, the commands that answer questions, common mistakes. +keywords: anycode for ai agents, llm coding agent guide, anycode api command, core surface, agent crew workflow choice, token efficient docs, common mistakes +--- + +# Using AnyCode from an AI coding agent + +This page is written for an AI coding agent that has been asked to build something with +AnyCode. It is deliberately short. + +## Read these two things first + +```bash +anycode api --core # 15 symbols, ~4.5 KB — the front door +``` + +plus [Recipes](recipes.md) — complete runnable snippets for the tasks you are usually asked +for. Those two cover most work. Do not read the source tree to learn the API. + +For one symbol in full, including the real signature: + +```bash +anycode api Agent +anycode api --json --compact # every symbol, no signatures +``` + +From Python: `anycode.describe("Crew")` returns the same data as an `ApiEntry`. + +## Which abstraction + +| The task | Use | +|---|---| +| One agent answers, possibly with tools | `Agent` | +| Several agents, work shaped as a dependency graph | `Crew` | +| Branching, looping, retry, or human checkpoints | `Workflow` | +| Long-running research or authoring | `Agent(planning=True, subagents=[...], workspace=...)` | +| Durability, MCP, plugins, verification gates, routing | `AnyCode` directly, or pass the options through `Crew` | + +Start at the top of that table and move down only when the task requires it. + +## The shortest correct program + +```python +from anycode import Agent, tool + +@tool +def word_count(text: str) -> int: + """Count the words in a block of text.""" + return len(text.split()) + +agent = Agent(name="editor", instructions="You are a copy editor.", tools=[word_count]) +print(agent.run_sync("Count the words in 'the quick brown fox'.").output) +``` + +Provider and model come from whichever API key is in the environment. Everything else is +optional. + +## Rules that will save you a wrong turn + +- **Do not build a `ToolRegistry` or `ToolExecutor` by hand.** `Agent(tools=[...])` does it. + They stay public for advanced use, not for getting started. +- **Do not write a Pydantic input model for a tool.** `@tool` derives it from the signature. + Use `define_tool` only for a schema a signature cannot express. +- **Do not copy a provider-detection block into a script.** `Agent(name=...)` detects it. +- **`tools=None` means every built-in tool; `tools=[]` means none.** They are different. +- **Every model is frozen.** Use `model_copy(update={...})`; never assign to a field. +- **Everything is async underneath.** `run_sync`, `prompt_sync`, `stream_sync`, and + `run_sync` on `Crew`/`CompiledWorkflow` exist for scripts. They raise a clear + `RuntimeError` if an event loop is already running — use the async form there. +- **Workflow nodes return a patch, not a new state.** Returning an undeclared field raises. +- **A `Crew` with declared tasks takes no goal**, and one without tasks requires one. + +## Writing tests + +Use `FakeAdapter` rather than real API calls: + +```python +from anycode.providers.fake import FakeAdapter, FakeResponse + +async def _create(*args, **kwargs): + return FakeAdapter(responses=[FakeResponse(text="canned")]) + +monkeypatch.setattr("anycode.core.agent.create_adapter", _create) +``` + +To exercise a tool with no LLM at all: `await agent.call_tool("name", **arguments)`. + +## Errors are meant to be read + +AnyCode errors name the offending value and state the fix. If one does not, that is a bug +worth reporting. Common ones: + +| Error | Cause | +|---|---| +| `AgentConfigError: ... needs a name` | keyword construction without `name=` | +| `AgentConfigError: no LLM provider could be detected` | no API key in the environment | +| `ToolDefinitionError: ... has no description` | a tool function with no docstring | +| `ToolDefinitionError: Unknown built-in tool "x"` | typo in a `tools=[...]` string | +| `CrewError: ... unknown option(s)` | a misspelled orchestrator setting | +| `WorkflowError: ... cannot be compiled` | a structural graph problem; every issue is listed | +| `AttributeError: ... Did you mean: Agent?` | a misspelled import from `anycode` | + +## Working inside this repository + +Read `AGENTS.md` at the repo root for the build, test, and style rules. The short version: +`uv` never `pip`, Python 3.12+, frozen Pydantic models, and the landing gate is +`uv run ruff check src/ && uv run ruff format --check src/ && uv run pyright && uv run pytest`. diff --git a/site_docs/reference/public-api.md b/site_docs/reference/public-api.md index 5aa2063..f4a9861 100644 --- a/site_docs/reference/public-api.md +++ b/site_docs/reference/public-api.md @@ -13,6 +13,36 @@ Everything documented here is exported from the package root, so `from anycode i !!! tip "New here? Read the concepts first" This reference lists signatures, not tutorials. For how the pieces fit together, start with the [Concepts overview](../concepts/overview.md), then the [How-to guides](../guides/index.md). +## The core surface + +Fifteen symbols cover the overwhelming majority of real use. Everything else on this page +stays public and supported; this is the front door, not a fence. + +| Symbol | Use it to | +| --- | --- | +| `Agent` | Build one agent from keyword arguments, run it, stream it, converse with it | +| `tool` | Turn a Python function into an agent tool | +| `Crew` | Run several agents over a list of tasks with dependencies | +| `TaskSpec` | Declare one unit of a crew's work | +| `Workflow` | Compose agents into a state graph with branching and loops | +| `START` / `END` | The virtual entry and exit nodes of a workflow | +| `AnyCode` | The engine underneath, for durability, MCP, plugins, routing, and gates | +| `AgentConfig` | The frozen agent configuration `Agent` builds internally | +| `TeamConfig` | The frozen team configuration `Crew` builds internally | +| `ToolResult` | What a tool returns | +| `ToolRegistry` / `ToolExecutor` | Manual tool wiring, when you need it | +| `SubAgentSpec` | Declare a sub-agent for `Agent(subagents=[...])` | +| `create_adapter` | Construct a provider adapter directly | + +Print the same list, with live signatures, at any time: + +```bash +anycode api --core +``` + +See [Recipes](recipes.md) for runnable snippets and +[Using AnyCode from an AI coding agent](llm-guide.md) for a token-efficient orientation. + ## How this page is organized The API is grouped the way you actually use it — from a first agent run out to production controls and the extension surface. diff --git a/site_docs/reference/recipes.md b/site_docs/reference/recipes.md new file mode 100644 index 0000000..1314a20 --- /dev/null +++ b/site_docs/reference/recipes.md @@ -0,0 +1,373 @@ +--- +title: "AnyCode Recipes — Copy-Paste Snippets for Common Agent Tasks" +description: Short runnable AnyCode snippets for tools, agents, crews, workflows, streaming, structured output, memory, MCP, cost caps, durability, and verification gates. +keywords: anycode recipes, python agent examples, tool decorator, crew example, workflow graph, streaming agent, structured output, mcp server, cost cap, checkpoint resume +--- + +# Recipes + +Every snippet is complete and runnable. Copy one, change the strings, run it. + +If you are an AI coding agent working with AnyCode, this page plus `anycode api --core` +is usually all the context you need. + +--- + +## One agent, one tool + +```python +from anycode import Agent, tool + +@tool +def word_count(text: str) -> int: + """Count the words in a block of text.""" + return len(text.split()) + +agent = Agent( + name="editor", + instructions="You are a concise copy editor.", + tools=[word_count], +) + +result = agent.run_sync("How many words are in: 'the quick brown fox jumps'?") +print(result.output) +``` + +Provider and model are detected from whichever API key is present. Pass +`provider="openai", model="gpt-4o-mini"` to be explicit. + +--- + +## Async agent + +```python +import asyncio +from anycode import Agent + +async def main() -> None: + agent = Agent(name="helper", instructions="Answer in one sentence.", tools=[]) + result = await agent.run("What is a closure?") + print(result.output) + +asyncio.run(main()) +``` + +--- + +## Streaming + +```python +import asyncio +from anycode import Agent + +async def main() -> None: + agent = Agent(name="narrator", instructions="Explain briefly.", tools=[]) + async for event in agent.stream("Explain database indexes."): + if event.type == "text": + print(event.data, end="", flush=True) + +asyncio.run(main()) +``` + +Blocking equivalent: `for event in agent.stream_sync("..."): ...` + +--- + +## Multi-turn conversation + +```python +from anycode import Agent + +tutor = Agent(name="tutor", instructions="You teach Python. Be brief.", tools=[]) +print(tutor.prompt_sync("What is a generator?").output) +print(tutor.prompt_sync("Show me one example.").output) +print(len(tutor.get_history()), "messages so far") +``` + +--- + +## Structured output + +```python +import asyncio +from pydantic import BaseModel +from anycode import Agent + +class Review(BaseModel): + sentiment: str + score: int + summary: str + +async def main() -> None: + agent = Agent(name="analyst", instructions="Analyze product reviews.", tools=[]) + result = await agent.run_structured("Review: 'Fast shipping, poor packaging.'", Review) + print(result.parsed.sentiment, result.parsed.score) + +asyncio.run(main()) +``` + +--- + +## Call a tool without the LLM + +```python +from anycode import Agent, tool + +@tool +def add(left: int, right: int) -> int: + """Add two integers.""" + return left + right + +agent = Agent(name="calc", tools=[add]) +print(agent.call_tool_sync("add", left=2, right=3).data) # "5" +``` + +Useful for testing a tool under the same validation and security policy the agent applies. + +--- + +## A crew with dependent tasks + +```python +from anycode import Agent, Crew, TaskSpec + +researcher = Agent(name="researcher", role="a research analyst", goal="gather the facts", tools=[]) +writer = Agent(name="writer", role="a technical writer", goal="turn facts into prose", tools=[]) + +crew = Crew( + agents=[researcher, writer], + tasks=[ + TaskSpec("Research", "Find three facts about vector databases.", agent=researcher), + TaskSpec( + "Write", + "Write a short paragraph from those facts.", + agent=writer, + depends_on=["Research"], + expected_output="One paragraph, no bullet points.", + ), + ], +) + +print(crew.run_sync().output) +``` + +--- + +## A crew that plans its own work + +```python +import asyncio +from anycode import Agent, Crew + +async def main() -> None: + async with Crew(agents=[ + Agent(name="lead", role="a project lead", tools=[]), + Agent(name="helper", role="a research assistant", tools=[]), + ]) as crew: + result = await crew.run("Produce a competitive brief on managed vector databases.") + print(result.output) + +asyncio.run(main()) +``` + +--- + +## A workflow with a loop + +```python +import asyncio +from pydantic import BaseModel, ConfigDict +from anycode import END, START, Workflow + +class State(BaseModel): + model_config = ConfigDict(frozen=True) + value: int = 0 + +workflow = Workflow(State) +workflow.add_node("increment", lambda state: {"value": state.value + 1}) +workflow.add_edge(START, "increment") +workflow.add_conditional_edge("increment", lambda state: END if state.value >= 3 else "increment") + +async def main() -> None: + result = await workflow.compile().run(State()) + print(result.state.value, result.path) + +asyncio.run(main()) +``` + +--- + +## An agent as a workflow node + +```python +from pydantic import BaseModel, ConfigDict +from anycode import START, Agent, Workflow + +class State(BaseModel): + model_config = ConfigDict(frozen=True) + question: str = "" + answer: str = "" + +workflow = Workflow(State) +workflow.add_node("ask", Agent(name="qa", tools=[]), input_key="question", output_key="answer") +workflow.add_edge(START, "ask") + +result = workflow.compile().run_sync(State(question="What is a B-tree?")) +print(result.state.answer) +``` + +--- + +## Draw the graph + +```python +print(workflow.compile().to_mermaid()) +``` + +--- + +## A long-horizon agent + +```python +from anycode import Agent, SubAgentSpec + +agent = Agent( + name="researcher", + instructions="Research the topic and write a report.", + tools=["file_write", "file_read"], + planning=True, + subagents=[SubAgentSpec(name="critic", instructions="Critique a draft. Be specific.")], + workspace="./.anycode/workspace", + max_turns=40, +) + +result = agent.run_sync("Write a report on hybrid search tradeoffs.") +print(agent.todos) +``` + +There is no separate deep-agent class — these are keywords on the same `Agent`. + +--- + +## Cap spending + +```python +from anycode import Agent, Crew + +crew = Crew( + agents=[Agent(name="worker", tools=[])], + tasks=["summarize the changelog"], + cost={"enabled": True, "budget_usd": 0.50, "on_budget_exceeded": "stop"}, +) +result = crew.run_sync() +print(result.cost) +``` + +--- + +## Connect an MCP server + +```python +import asyncio +from anycode import AnyCode + +async def main() -> None: + async with AnyCode({"mcp_servers": [{"name": "fs", "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]}]}) as engine: + result = await engine.run_agent( + {"name": "worker", "model": "gpt-4o-mini", "provider": "openai", "mcp_servers": ["fs"]}, + "List the files in the current directory.", + ) + print(result.output) + +asyncio.run(main()) +``` + +--- + +## Durable, resumable runs + +```python +from anycode import Agent, Crew, TaskSpec + +crew = Crew( + agents=[Agent(name="worker", tools=[])], + tasks=[TaskSpec("Step one", "Do the first thing."), TaskSpec("Step two", "Do the second.")], + checkpoint={"enabled": True, "path": ".anycode/checkpoints"}, +) +result = crew.run_sync() +``` + +Re-running the same task list resumes from the last completed wave. + +--- + +## Verification gates + +```python +from anycode import Agent + +agent = Agent( + name="coder", + instructions="Write Python and keep it lint-clean.", + tools=["file_write", "bash"], + verification=({"kind": "ruff", "phase": "after_turn", "severity": "error"},), +) +``` + +A failing sensor sets `result.stop_reason.code == "verification_failed"`. + +--- + +## Persistent memory + +```python +from anycode import create_memory_store + +store = create_memory_store({"backend": "sqlite", "path": ".anycode/memory.db"}) +``` + +Backends: `memory`, `sqlite` (`persistence` extra), `redis` (`redis` extra). + +--- + +## Swap the provider + +```python +from anycode import Agent + +anthropic = Agent(name="a", provider="anthropic", model="claude-haiku-4-5", tools=[]) +openai_ = Agent(name="b", provider="openai", model="gpt-4o-mini", tools=[]) +local = Agent(name="c", provider="ollama", model="qwen3:8b", tools=[]) +``` + +Or set `ANYCODE_DEFAULT_PROVIDER` and `ANYCODE_DEFAULT_MODEL` and pass neither. + +--- + +## Test without an API call + +```python +from anycode import Agent +from anycode.providers.fake import FakeAdapter, FakeResponse + +async def fake_adapter(*args, **kwargs): + return FakeAdapter(responses=[FakeResponse(text="canned answer")]) + +# in a test: monkeypatch.setattr("anycode.core.agent.create_adapter", fake_adapter) +``` + +--- + +## Discover the API + +```bash +anycode api --core # the 15 symbols that cover most use +anycode api Agent # one symbol, full signature +anycode api --json # the whole surface, machine-readable +``` + +```python +import anycode +anycode.describe("Crew").signature +``` From f5668d6178d338a07e7b922cf1b0f8dfde736fbe Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 06:49:13 +0500 Subject: [PATCH 09/11] chore: refresh uv.lock for the 0.10.0 version bump --- uv.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/uv.lock b/uv.lock index 4000d40..b18c634 100644 --- a/uv.lock +++ b/uv.lock @@ -198,7 +198,7 @@ wheels = [ [[package]] name = "anycode-py" -version = "0.9.0" +version = "0.10.0" source = { editable = "." } dependencies = [ { name = "pydantic" }, From a594364d4c21c2af75d1301202c280fc914fa575 Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 06:54:32 +0500 Subject: [PATCH 10/11] docs: point llms.txt and the CLI reference at the 0.10 surface llms.txt gains the four new guides, the recipes and LLM-guide pages, and a note telling an AI agent to read those two first. The CLI reference documents `anycode api` with its options and real output sizes. Also fixes examples/33_mcp_http_auth.py, which demonstrated fail-closed auth resolution but did not handle it: resolve_auth_headers raises when a config declares auth_token_env and that variable is unset, so section C crashed instead of showing the refusal. The example now catches and prints it, which is what the section was meant to demonstrate. --- examples/33_mcp_http_auth.py | 10 +++++++--- site_docs/llms.txt | 22 +++++++++++++++++----- site_docs/reference/cli.md | 29 +++++++++++++++++++++++++++++ 3 files changed, 53 insertions(+), 8 deletions(-) diff --git a/examples/33_mcp_http_auth.py b/examples/33_mcp_http_auth.py index 0c8e559..02afdde 100644 --- a/examples/33_mcp_http_auth.py +++ b/examples/33_mcp_http_auth.py @@ -75,9 +75,13 @@ async def main() -> None: print(f"\n{SEPARATOR}") print("Section C: resolve_auth_headers (token absent)\n") - resolved = resolve_auth_headers(config) - print(f" resolved headers: {_mask(resolved)}") - print(" no Authorization header added when the env var is unset") + # Resolution is fail-closed: a config that declares auth_token_env refuses to build + # headers when that variable is missing, rather than connecting unauthenticated. + try: + resolve_auth_headers(config) + print(" unexpected: resolution succeeded without a token") + except ValueError as error: + print(f" refused, as intended: {error}") header_only = MCPServerConfig(name="plain", transport="sse", url="https://mcp.example.com/sse") print(f" config with no headers/token resolves to: {resolve_auth_headers(header_only)}") diff --git a/site_docs/llms.txt b/site_docs/llms.txt index 6e33047..4ea33ca 100644 --- a/site_docs/llms.txt +++ b/site_docs/llms.txt @@ -10,6 +10,11 @@ Documentation is versioned; the links below point to the `latest` release alias. ## Start Here +If you are an AI coding agent, read the LLM guide and the recipes page first; together they +cover most tasks without reading source. + +- [Using AnyCode from an AI coding agent](https://quantlix.github.io/anycode/latest/reference/llm-guide/): The core surface, which abstraction to pick, and the mistakes to avoid. +- [Recipes](https://quantlix.github.io/anycode/latest/reference/recipes/): Complete, runnable snippets for the common tasks. - [Documentation home](https://quantlix.github.io/anycode/latest/): Overview, feature map, and recommended reading path. - [Installation](https://quantlix.github.io/anycode/latest/getting-started/installation/): Install commands, extras, provider keys, and verification steps. - [Quickstart](https://quantlix.github.io/anycode/latest/getting-started/quickstart/): Single-agent and multi-agent examples. @@ -25,8 +30,12 @@ Documentation is versioned; the links below point to the `latest` release alias. ## How-to Guides -- [Run a multi-agent team](https://quantlix.github.io/anycode/latest/guides/multi-agent-team/): Build a planner, builder, and reviewer workflow. -- [Work with tools](https://quantlix.github.io/anycode/latest/guides/tools/): Built-in tools and custom Pydantic tools. +- [Function tools](https://quantlix.github.io/anycode/latest/guides/function-tools/): Turn any Python function into a tool with the @tool decorator. +- [Run a crew](https://quantlix.github.io/anycode/latest/guides/crews/): Several agents over a task list with dependencies and expected output. +- [Build a workflow](https://quantlix.github.io/anycode/latest/guides/workflows/): State graphs with conditional edges, loops, fan-out, and reducers. +- [Long-horizon agents](https://quantlix.github.io/anycode/latest/guides/long-horizon-agents/): Planning, sub-agent delegation, and a confined workspace on the same Agent. +- [Run a multi-agent team](https://quantlix.github.io/anycode/latest/guides/multi-agent-team/): The engine-level API beneath Crew. +- [Work with tools](https://quantlix.github.io/anycode/latest/guides/tools/): The typed define_tool path, for schemas a signature cannot express. - [Structured output](https://quantlix.github.io/anycode/latest/guides/structured-output/): Force a validated Pydantic object with run_structured and output_schema. - [Configure providers](https://quantlix.github.io/anycode/latest/guides/providers/): Anthropic, OpenAI, Google, Ollama, Bedrock, Azure, and retry resilience. - [Stream agent output](https://quantlix.github.io/anycode/latest/guides/streaming/): StreamEvent types, chat fallback, and parallel tool execution. @@ -58,7 +67,9 @@ Documentation is versioned; the links below point to the `latest` release alias. ## Reference -- [Public API](https://quantlix.github.io/anycode/latest/reference/public-api/): Core classes, config models, result models, tools, and provider factory. +- [Recipes](https://quantlix.github.io/anycode/latest/reference/recipes/): Copy-paste snippets for tools, agents, crews, workflows, memory, MCP, cost, and gates. +- [Using AnyCode from an AI coding agent](https://quantlix.github.io/anycode/latest/reference/llm-guide/): Token-efficient orientation, plus the `anycode api` command. +- [Public API](https://quantlix.github.io/anycode/latest/reference/public-api/): The core surface table, then core classes, config models, result models, tools, and provider factory. - [Complete API inventory](https://quantlix.github.io/anycode/latest/reference/api-inventory/): Every supported package-root export, generated from source docstrings. - [Runtime contracts and baseline](https://quantlix.github.io/anycode/latest/reference/runtime-contracts/): Lifecycle transitions, verification boundaries, persisted formats, supported local resume, and reproducible baseline evidence. - [Semantic contracts](https://quantlix.github.io/anycode/latest/reference/semantic-contracts/): Versioned JSON models, state and cancellation rules, event projections, fenced operations, and artifacts. @@ -66,13 +77,13 @@ Documentation is versioned; the links below point to the `latest` release alias. - [Security and threat model](https://quantlix.github.io/anycode/latest/reference/security/): Trust boundaries, enforced invariants, residual risk, and operator-owned controls. - [Built-in tools](https://quantlix.github.io/anycode/latest/reference/built-in-tools/): bash, file_read, file_write, file_edit, grep, list_files — parameters, defaults, limits. - [Configuration](https://quantlix.github.io/anycode/latest/reference/configuration/): OrchestratorConfig, AgentConfig, TeamConfig, RunnerOptions, and defaults. -- [CLI reference](https://quantlix.github.io/anycode/latest/reference/cli/): `anycode init`, `run`, `inspect`, `eval`, and `runs` commands. +- [CLI reference](https://quantlix.github.io/anycode/latest/reference/cli/): `anycode init`, `run`, `inspect`, `api`, `eval`, and `runs` commands. ## Source And Examples - [Repository](https://github.com/Quantlix/anycode): Source code. - [Documentation source](https://github.com/Quantlix/anycode/tree/main/site_docs): Markdown source for this site. -- [Examples](https://github.com/Quantlix/anycode/tree/main/examples): 44 runnable example scripts, beginner to advanced. +- [Examples](https://github.com/Quantlix/anycode/tree/main/examples): 48 runnable example scripts, beginner to advanced. - [README](https://github.com/Quantlix/anycode/blob/main/README.md): Project overview and package summary. ## Optional @@ -82,6 +93,7 @@ Documentation is versioned; the links below point to the `latest` release alias. - [Contract test conventions](https://quantlix.github.io/anycode/latest/contributing/contract-tests/): Golden fixtures, state-machine properties, fault injection, and reusable conformance suites. - [Maintainer governance](https://quantlix.github.io/anycode/latest/contributing/maintainers/): Roles, approvals, compatibility, deprecations, support, and backports. - [Release process](https://quantlix.github.io/anycode/latest/contributing/releasing/): Version selection, TestPyPI, Trusted Publishing, verification, and recovery. +- [Migrating to 0.10](https://quantlix.github.io/anycode/latest/contributing/migration-0.10/): Nothing is required; what is new and the one behavioral note. - [TypeScript service client](https://quantlix.github.io/anycode/latest/typescript/): Preview lifecycle, artifact, cancellation, and resumable-streaming client for Node.js and browsers. - [Documentation strategy](https://quantlix.github.io/anycode/latest/contributing/documentation-strategy/): Tooling rationale, SEO plan, and docs case studies. - [Changelog](https://github.com/Quantlix/anycode/blob/main/CHANGELOG.md): Release history. diff --git a/site_docs/reference/cli.md b/site_docs/reference/cli.md index abca574..6954744 100644 --- a/site_docs/reference/cli.md +++ b/site_docs/reference/cli.md @@ -14,6 +14,7 @@ The `anycode` command-line interface scaffolds projects, runs team configs, insp | [`anycode init`](#anycode-init) | Scaffold a starter project with config, code, and tooling. | | [`anycode run`](#anycode-run) | Run a YAML or TOML team config. | | [`anycode inspect`](#anycode-inspect) | Inspect tools, providers, plugins, config, and team. | +| [`anycode api`](#anycode-api) | Print the public API surface as a table or as JSON. | | [`anycode eval`](#anycode-eval) | Run (`run`) or compare (`compare`) evaluation suites. | | [`anycode runs`](#anycode-runs) | Inspect durable run stores (list, show, tail, audit, sweep). | | [`anycode harness`](#anycode-harness) | Emit a harness manifest (`manifest`) or run an experimental evolution sweep (`evolve`). | @@ -61,6 +62,34 @@ uv run anycode run team.yaml The config can include agents, tasks, cost controls, routing, RAG, reflection, verification, and context engineering blocks. See the [YAML config guide](../guides/yaml-config.md) for the full schema. +## `anycode api` + +Print the public API surface. Written for humans skimming and for AI coding agents that +should not have to read the source tree to learn the API. + +```bash +uv run anycode api --core # the 15 symbols covering most use, with live signatures +uv run anycode api Agent # one symbol, full signature, kind, module, and summary +uv run anycode api --compact # every symbol, names and summaries only +uv run anycode api --json # machine-readable, stable key order +uv run anycode api --kind model # filter by class, model, protocol, function, type, constant, module +``` + +| Option | Effect | +| --- | --- | +| *(no argument)* | Every public symbol, grouped by module | +| `` | One symbol in full | +| `--core` | Only `anycode.CORE_SURFACE` | +| `--compact` | Drop signatures | +| `--json` | Emit JSON instead of a table | +| `--kind ` | Filter by symbol kind | + +Approximate output sizes: `--core` 4.6 KB, `--compact` 29 KB, full JSON 139 KB. Start with +`--core`; it is the artifact meant to go into a prompt. + +The same data is available in Python through `anycode.describe()`, which returns an +`ApiMap`, or `anycode.describe("Agent")`, which returns a single `ApiEntry`. + ## `anycode inspect` Inspect runtime configuration and available components. From 8dfe4367ca9953c6c84623f630795cd5c484ff53 Mon Sep 17 00:00:00 2001 From: Ali Muhammad Date: Sat, 25 Jul 2026 06:55:43 +0500 Subject: [PATCH 11/11] refactor(crew): annotate Crew.team instead of suppressing the lint --- src/anycode/crew.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/anycode/crew.py b/src/anycode/crew.py index 4c0ce58..5da65d4 100644 --- a/src/anycode/crew.py +++ b/src/anycode/crew.py @@ -11,6 +11,7 @@ from pydantic import BaseModel, ConfigDict +from anycode.collaboration.team import Team from anycode.core.agent import Agent from anycode.core.orchestrator import AnyCode, TaskSpec from anycode.helpers.sync_runner import run_coroutine_blocking @@ -97,7 +98,7 @@ def engine(self) -> AnyCode: return self._engine @property - def team(self): # noqa: ANN201 - Team is re-exported; annotation would force an eager import + def team(self) -> Team: """The underlying team.""" return self._team