Capabilities

Summonpot offers one declaration style for endpoints whose operations resolve deterministically and endpoints that permit bounded agent-owned decisions. The contract vocabulary includes Operation, FromRequest, AgentChoice, Depends, Required, and call bounds such as Exactly(1).

Version 0.15.0 bounded repeated calls

One required typed operation may run a finite positive number of times (1 <= minimum <= maximum, maximum > 1) with a Pydantic request, at least one FromRequest, direct closed Literal[str] AgentChoice inputs, supported request/context bindings or immutable defaults, and exact full operation-output/endpoint-response annotation identity. Summonpot owns sequential decisions; business functions are not selector tools. It locally validates selections, shares one usage budget and deadline, resolves the model lazily, auto-finishes at maximum, and returns only the final successful canonical result; any failure aborts. Previous-result evidence is limited to 65,536 characters per decision, not an aggregate prompt budget. Explicit tool_calls_limit fails before provider/effects. No producer choices, FromResult, after, zero-minimum/unbounded bounds, implicit batch, or general graph. Existing Exactly(1) and producer-choice routes remain unchanged. Published v0.14.0 is untouched; milestone 3 remains partial and a narrow repeated-stage consumer is now documented below. Broader repeated-result addressing remains planned.

Version 0.15.0 repeated-stage final-result consumer

The original two-operation form lets one bounded repeated producer feed one required, choice-free terminal operation after the producer stage closes. The terminal uses FromResult(producer, field, invocation="final") to bind the final successful canonical result from one immutable closure record; meeting the minimum alone does not make it ready, and a failed or uncertain invocation aborts without earlier-result fallback. This two-operation shape is version 0.15.0, not published v0.14.0 behavior. It does not add aggregation, repeated consumers, inspect/correct/verify workflows, or general graphs. See the repeated-stage contract.

Version 0.15.0 single-stage sequential chains

Version 0.15.0 supports a uniquely ordered chain with one nonterminal bounded repeated operation, an optional resolved prefix and a nonempty resolved suffix. Every other operation is required Exactly(1) with no agent choices. A Pydantic request needs at least one FromRequest across the whole chain, not necessarily on the repeated operation; supported request/result/authenticated-context bindings and immutable defaults remain required. The repeated operation has positive finite bounds (minimum >= 1, maximum > 1), direct closed plain-string Literal choices and a Pydantic intermediate distinct from the response. Ordinary FromResult reads single-invocation results; repeated results require invocation="final", with at least one suffix consumer. Exactly one terminal operation owns the endpoint’s exact full response annotation. Prefix operations run before one lazy model resolution; suffix operations run after immutable stage closure without further model decisions or acknowledgment. One principal, ledger, absolute deadline and usage budget span the request. Prefix results/context/ledger are not implicitly projected into model prompts; receiving constraints are checked before each start. Explicit function-tool quotas reject before all work. No feedback cycles, external choices, multiple repeated stages, aggregation, parallelism or durable recovery are added. Published behavior before v0.15.0 remains unchanged. See the single-stage chain contract.

Version 0.15.0 prefix selection before repetition

Version 0.15.0 also composes exactly one producer-backed choice argument on one required Exactly(1) prefix consumer with one nonterminal bounded repeated stage and a resolved suffix. The candidate producer is an earlier single-start operation returning list[ConcreteModel]; repeated choices remain direct closed string Literal values, and all other operations remain resolved required Exactly(1). Pydantic request/response, chain-wide FromRequest, unique ordering, final-invocation addressing and exact terminal response ownership remain required. Empty/unavailable/oversized candidate domains stop before selection or repeated work; a singleton binds locally, while ambiguity uses canonical request-local tokens. Singleton selection still leads to model-backed repeated decisions. One lazy model-configuration lookup, run, principal, ledger, deadline and usage budget span both phases. No business-function tools, reselection after same-run failure, effect replay or final model acknowledgment are added. A fresh request starts a fresh run. Published behavior before v0.15.0 remains unchanged. See the composed selection/stage contract. See the canonical contract.

Version 0.15.0 framework-owned progression

Version 0.15.0 supports one or more producer-backed choices with framework-owned progression. In an otherwise eligible uniquely ordered required Exactly(1) chain, a Pydantic request, at least one FromRequest, supported request/result/authenticated-context bindings or immutable defaults, and exact full terminal response annotation identity remain required. All current consumer domains are checked before selection or start. Singleton bindings resolve locally; a decision-only selector returns ambiguous tokens with no business-operation tools. The shared kernel validates and invokes the operation, then continues locally until another genuine decision is needed. The canonical terminal result returns without a final model acknowledgment. Request/principal, reservations, token domains, usage budgets and one deadline remain request-local across frontiers and corrections. Explicit tool_calls_limit retains the previous one-way agent suffix; allow_direct=False and other noneligible declarations retain their existing route. Limits remain 128 candidates and 65,536 evidence characters per binding, not an aggregate prompt/context budget. Prefix effects may precede provider-configuration failure; no rollback, effect replay or durable resume is added. Historical v0.14.0 remains exactly-one-choice. See the operation reference for details.

An Operation wraps an exact callable. Its inputs must have enforceable bindings; the supported runtime slice rejects unsupported explicit shapes during registration. FromRequest sources values from the validated caller model. A direct AgentChoice marks an argument the agent can choose; it does not grant authority beyond that registered callable.

operation = Operation(
    lookup_record,
    bind={"record_id": FromRequest("record_id")},
    output=RecordResponse,
)

@summon("/records/lookup")
def lookup(request: LookupRequest, record=Required(operation, calls=Exactly(1))) -> RecordResponse:
    """Return the requested record."""
    ...

This fully resolved single-operation shape can bypass model setup when all supported deterministic-path requirements are met. Adding an explicit AgentChoice normally keeps execution in the agent runtime; the result-dependent source exception included from version 0.14.0 is documented in the operation reference. Consult the capability guide for complete contract details; fully resolved uniquely ordered chains run model-free from version 0.12.0 when every operation is required Exactly(1), the endpoint has a Pydantic request with at least one FromRequest binding, arguments use only supported request/result bindings or immutable defaults, and the terminal output exactly matches the full endpoint response annotation. An AgentChoice normally keeps the chain agent-mediated; the result-dependent source exception included from version 0.14.0 is specified in the operation reference. Broader graph execution remains planned.

Authenticated FromContext is included from version 0.13.0 for the supported single required Exactly(1) operation and uniquely ordered required chain. The application authenticates credentials through Summon(context=authenticate); caller JSON and model arguments cannot supply identity. Context may resolve a model-free path only when the existing Pydantic request, at least one FromRequest, immutable-default, and exact full terminal response requirements also hold. AgentChoice is ordinarily agent-mediated; see the result-dependent source exception included from version 0.14.0. See the authenticated context contract.