[laithalsaadoon]

Summary

Adds ai_functions.experimental.methods, the @ai_function decorator applied to methods. An agent written as a class usually funnels each capability through one request: str parameter, which drops three things @ai_function gives for free: a typed tool schema, the docstring as the prompt template, and call arguments the optimizer can reach. A bound method keeps all three, because Python already removes self from its signature.

class Analyst(MethodAgent):
    def __init__(self, plane: str):
        self.plane = plane

    @ai_method(Finding, description="Analyze one plane over a window")
    def analyze(self, window: str, max_records: int = 20) -> Finding:
        """Analyze the {self.plane} plane over {window}."""

Analyst("metrics").compiled("analyze") is an AIFunction whose tool schema carries window and max_records, with the prompt rendered from the docstring for this instance. Analyst("metrics").spawn("analyze", coordinator) is the same capability on a live thread whose run calls share history.

The package uses only public core API (AIFunction, ThreadConfig, Coordinator.spawn, ThreadHandle) and imports no other experimental package.

What's in it

• core: @ai_method, MethodAgent and MethodThread. agents() hands an object's capabilities to another agent as typed tools named {owner}_{method}, where the owner is the agent's name or its lowercased class name. The separator is an underscore because Bedrock and the Strands tool-use check accept only letters, digits, _ and - in a tool name. MethodThread keeps one capability's thread alive between calls; retire is idempotent and every call after it raises RetiredThreadError.
• gated: GatedProposer runs a Gate as the method's post-condition, so a caller can't skip the check. propose_k takes k proposals from one shared context by forking one thread k - 1 times, and returns the ones the gate admits. The branches are spawned without the coordinator's list_threads and send_message tools, so each proposal is an independent draw and no branch can wait on a sibling.
• recall: Recalled declares memory as a call argument and Recall fills it fresh from a MemoryBackend on every call, so the recalled values reach TextGradOptimizer as parameters instead of hiding on self.

A capability's model comes from the call's model=, then the decorator's model=, then the agent's model attribute. With none of them set, it runs on the Strands default model, as a plain @ai_function does.

The package docstring lists its invariants, M1 to M9.

Docs and examples

• docs/methods.md covers @ai_method and MethodAgent, model choice, agents(), spawn(), GatedProposer with gated() and propose_k, and Recall, and ends with an errors table.
• README.md gains a "Method agents" subsection under Multi-Agent Workflows that links to it.
• examples/methods/analyst_team.py calls a method once, hands every method to an orchestrating @ai_function as a typed tool, and keeps one method on a live thread.
• examples/methods/gated_proposer.py checks discount proposals against a cap the prompt doesn't state, retries with the gate's report through gated(), and filters a three-branch propose_k beam.

Both examples use example_helpers.models.medium, so they run on the Strands default model.

Testing

hatch run lint, hatch run check-spec and hatch run test pass on Python 3.12 (721 passed, 2 skipped). tests/methods/test_methods_ai_functions_contract.py pins the core behaviors the package relies on (one config_hook per cycle, notify starting no cycle, ThreadKwargs keys, LocalWorker.close() idempotence, load_tools schema building), so a change to any of them fails there first.

Both examples ran against Bedrock in us-east-1 on the Strands default model (global.anthropic.claude-sonnet-4-6 in strands-agents 1.61.1). The orchestrator in analyst_team.py called the analyst tools under their default names, and the propose_k beam in gated_proposer.py returned a verdict for each of its three branches; that whole example took 28 seconds.

ruff format --check reports one file, src/ai_functions/memory/base.py, which is already unformatted on main under ruff 0.17.