summonpot

Declare deterministic operations and agentic decisions through one framework.

A contract-first Python framework for combining application-owned execution and agent-owned choices in one typed HTTP API.

Quick start · Why summonpot · Capabilities · How it works · Examples · Community · Contributing

The ellipsis is declaration syntax, not an unfinished implementation. The signature, docstring, operations, argument bindings, and return type are the executable contract. Depends(...) and Required(...) attach deterministic application code. AgentChoice() marks the exact arguments where the agent may decide. Deterministic and agentic endpoints use the same declaration style, request/response validation, routing, and OpenAPI instead of separate API and agent frameworks. Summonpot owns the bounded agent loop, operation enforcement, and structured output. Calling a registered declaration directly raises a clear error; serve the application or invoke its generated HTTP route instead.

A conventional API puts deterministic work in a handler. An agent-first stack starts from an agent workflow and then wraps it in HTTP. Summonpot declares both through the same contract-first framework, so applications keep one public API as the balance changes between exact operations and semantic decisions:

The following conceptual declaration omits the application-specific models and service implementation; the quick start is the standalone example.

from typing import Literal

from summonpot import AgentChoice, Exactly, FromRequest, Operation, Required, Summon


summon = Summon("research-api")


def build_deterministic_report(topic: str) -> ResearchReport:
    """Run the application's fully resolved research operation."""
    return research_service.build(topic=topic, format="detailed")


deterministic_report_operation = Operation(
    build_deterministic_report,
    bind={"topic": FromRequest("topic")},
    output=ResearchReport,
)


def build_agentic_report(
    topic: str,
    format: Literal["summary", "detailed"],
) -> ResearchReport:
    """Run the exact operation with one declared semantic choice."""
    return research_service.build(topic=topic, format=format)


agentic_report_operation = Operation(
    build_agentic_report,
    bind={
        "topic": FromRequest("topic"),
        "format": AgentChoice(),
    },
    output=ResearchReport,
)


@summon("/reports/deterministic")
def deterministic_report(
    request: ResearchRequest,
    report=Required(deterministic_report_operation, calls=Exactly(1)),
) -> ResearchResponse:
    """Return the detailed report through a fully resolved operation path."""
    ...


@summon("/reports/agentic")
def agentic_report(
    request: ResearchRequest,
    report=Required(agentic_report_operation, calls=Exactly(1)),
) -> ResearchResponse:
    """Choose the report format and return the sourced report."""
    ...

Those declarations answer the questions an API framework needs to answer:

The request carries business data only. The endpoint goal is fixed in code. Exact operations remain application-owned, while the agent can choose only within the authority declared for that endpoint. A response is not accepted until every Required(...) operation has completed successfully.

/reports/deterministic binds every operation argument to validated application data; it contains no agent-owned operation choice. /reports/agentic uses the same declaration style but adds one explicit AgentChoice(). Both keep typed request/response contracts, operation enforcement, routing, and OpenAPI under Summonpot. Today the agent runtime handles every request, including the fully resolved endpoint; direct execution without the agent runtime remains planned for that declaration.

• One declaration style for deterministic operations and agentic decisions, sharing the same request, response, route, validation, and OpenAPI contract.
• Contract-first endpoints with a required goal and typed request/response contracts.
• Closed capability sets made from exact application-owned callables.
• Optional and mandatory operations through Depends(...) and Required(...).
• Runtime-enforced required use, tracked per request rather than trusted to a prompt.
• Bound exactly-once operations for the first complete runtime slice: trusted FromRequest values and callable defaults are removed from the operation tool schema, direct AgentChoice arguments remain visible, one start is permitted, and output= is locally validated before success.
• Typed Operation contracts that declare request, prior-result, context, or agent-chosen argument sources without expanding the endpoint API.
• Registration-time contract validation that rejects missing sources, invalid result references, unsupported choices, and provably incompatible types before serving.
• Provider-neutral model selection for OpenAI, Anthropic, Google, Groq, Mistral, OpenRouter, and xAI.
• Generated HTTP and OpenAPI contracts for body and query endpoints.
• GET, POST, PUT, PATCH, DELETE, and HEAD routes, keyed by (path, method).
• Local response validation, bounded retries, usage limits, timeouts, and redacted public failures.
• A keyless test model for exercising routes and schemas before adding provider credentials.
• Coding-agent skills for Claude Code, Cursor, Windsurf, GitHub Copilot, Cline, and OpenAI Codex, including typed operation bindings and their current runtime boundary.

pip install "summonpot[serve,cli]"

Start without a provider account by selecting the built-in test model:

export SUMMONPOT_MODEL=test

The test model is keyless, not side-effect-free. An endpoint with capabilities may call them using generated placeholder arguments. Use harmless capabilities when testing wiring; do not attach destructive operations or treat the model as a dry-run sandbox.

Create app.py:

from typing import Literal

from pydantic import BaseModel, Field
from summonpot import Summon


class ReviewRequest(BaseModel):
    text: str = Field(min_length=1, max_length=2_000)


class ReviewResponse(BaseModel):
    sentiment: Literal["positive", "negative", "neutral"]
    summary: str


summon = Summon("review-api")


@summon("/review")
def review(request: ReviewRequest) -> ReviewResponse:
    """Classify the text's sentiment and summarize it in one short sentence."""
    ...

The ellipsis marks a complete endpoint declaration. Summonpot never calls that body, and direct Python calls are rejected at the decorator boundary.

summonpot serve app.py --host 127.0.0.1 --port 8000

Open the generated API documentation at http://127.0.0.1:8000/docs, or call the endpoint directly:

curl -X POST http://127.0.0.1:8000/review \
  -H 'Content-Type: application/json' \
  -d '{"text":"The endpoint contract is surprisingly small."}'

The test model returns schema-valid placeholder data. To receive a real agent-generated answer, install a provider extra and select a provider-qualified model:

pip install "summonpot[serve,cli,anthropic]"
export SUMMONPOT_MODEL=anthropic:claude-sonnet-4-5
export ANTHROPIC_API_KEY='<your key>'

The endpoint code and HTTP contract do not change when the provider changes.

A capability is ordinary application code. It runs for real; summonpot never replaces its implementation.

def calculate_quote(
    unit_price_cents: int,
    quantity: int,
    tax_rate_percent: str,
) -> dict[str, int]:
    """Calculate an exact quote using the service's approved pricing rules."""
    return pricing_service.calculate(
        unit_price_cents=unit_price_cents,
        quantity=quantity,
        tax_rate_percent=tax_rate_percent,
    )

Attach it to one endpoint, continuing from the application and models defined above:

from summonpot import Required


@summon("/quotes")
def create_quote(
    request: QuoteRequest,
    calculation=Required(calculate_quote),
) -> QuoteResponse:
    """Calculate and return the exact approved quote."""
    ...

For bare callables and broader operation graphs, Required(...) proves only that the operation returned successfully at least once during that request. The narrow bound form shown below additionally enforces trusted request injection, local operation-output validation, and Exactly(1). Ordering, idempotency, and provenance-backed final claims remain separate concerns.

Capabilities do not become request-body fields or OpenAPI parameters. Their docstrings and annotations define the tool schema visible to the agent, while their implementations define the real application behavior.

The capability set is closed. For one required typed operation with Exactly(1), the runtime injects FromRequest values, removes them and callable defaults from the operation tool schema, offers only direct AgentChoice arguments, validates the declared operation output, and rejects a second start. Request values still appear in the agent's user message; tool-schema hiding is not prompt secrecy. Other operation shapes remain on the legacy agent-supplied path until their execution semantics ship. Every operation must still enforce authorization. Pass exact operations, never raw database sessions, engines, connections, cursors, arbitrary SQL, shell access, or ambient filesystem authority.

See the complete executable Required(...) quote example.

Use Operation when a capability's dataflow is part of the endpoint contract rather than something the agent should invent:

from my_service.models import Customer, CustomerRequest, CustomerResponse
from my_service.operations import load_customer
from summonpot import AgentChoice, Exactly, FromRequest, Operation, Required, Summon


summon = Summon("customer-api")

customer_from_request = Operation(
    load_customer,
    bind={
        "customer_id": FromRequest("customer_id"),
        "format": AgentChoice(),
    },
    output=Customer,
)


@summon("/customers")
def get_customer(
    request: CustomerRequest,
    customer=Required(customer_from_request, calls=Exactly(1)),
) -> CustomerResponse:
    """Load this customer and return the approved customer view."""
    ...

The contract is immutable after construction. At registration, summonpot verifies that:

• every required operation argument has an explicit source;
• FromRequest(...) names a real request field;
• FromResult(...) names a declared producer and a readable, typed output field;
• AgentChoice(...) selects from a supported collection and fits its receiving argument;
• known source, element, and destination types are compatible; and
• ordering references name operations declared by the same endpoint.

The rule is deliberately conservative: a declaration is rejected only when its incompatibility is provable. Missing annotations, Any, framework context, and type relationships the checker cannot establish remain unknown rather than becoming false registration errors. An annotation that names a type Python cannot resolve is still an invalid endpoint declaration and fails at import.

For example, binding an int request field to a str operation argument fails while the module is imported. A Customer value may feed a Person argument when Customer is a subclass, and Python's numeric widening permits int or bool to feed float.

HTTP request
    |
    v
Pydantic request validation + OpenAPI contract
    |
    v
Runtime.call(...)
    |
    v
Configured provider-neutral model
    |
    +---- may call only declared capabilities
    |          |
    |          +---- successful Required(...) calls recorded per request
    |
    v
Required-operation gate
    |
    v
Local Pydantic response validation
    |
    v
HTTP response

The endpoint docstring becomes the fixed goal. Request data becomes the user message. Capabilities become the complete set of callable operations. The response model becomes both the structured-output schema and the final local validator.

Pydantic AI is an internal runtime dependency. Applications use Summon, @summon, Pydantic models, and declarative capabilities; they do not construct provider clients or Pydantic AI agents.

The roadmap adds a no-model executor without adding a second endpoint API:

Broader graph compilation and ordering, automatic no-model execution, SQLAlchemy/SQLite operation adapters, write receipts, streaming, and built-in authentication are planned, not shipped. See ROADMAP.md for the design boundaries and implementation order.

POST is the default. Body endpoints take one Pydantic request model. Bodyless methods such as GET, DELETE, and HEAD declare scalar or scalar-sequence query parameters:

This fragment continues from an existing module-level summon application:

from typing import Literal

from pydantic import BaseModel


class TicketPage(BaseModel):
    tickets: list[str]


@summon("/tickets", method="GET")
def list_tickets(
    status: Literal["open", "closed"] = "open",
    ids: list[int] | None = None,
) -> TicketPage:
    """List tickets matching the requested filters."""
    ...

GET /tickets and POST /tickets may coexist. Registering the same normalized (path, method) twice fails at import time, as do missing docstrings, unresolved type annotations, invalid capability callables, duplicate capability names, unsupported query types, and stream=True.

Set one default for the Summon application through SUMMONPOT_MODEL or in Python:

summon = Summon("research-api", model="openrouter:anthropic/claude-sonnet-4")

Override it for one endpoint without changing that endpoint's HTTP contract:

@summon("/research", model="anthropic:claude-sonnet-4-5")
def research(request: ResearchRequest) -> ResearchResponse:
    """Research the topic and return a sourced report."""
    ...

OpenRouter keeps the upstream provider and model after the first colon. Legacy unprefixed model names resolve through OpenAI for backward compatibility.

Binding and exposure: A reachable endpoint can spend the operator's provider credit, so set explicit usage limits and a timeout:

from summonpot import Summon, UsageLimits
from summonpot.runtime import Runtime


summon = Summon(
    "my-service",
    runtime=Runtime(
        usage_limits=UsageLimits(
            request_limit=8,
            total_tokens_limit=40_000,
        ),
        timeout=30.0,
    ),
)

Provider text, agent output, and capability details stay in operator logs rather than public error bodies.

The timeout bounds how long summonpot waits. It cannot terminate a synchronous capability already running in a worker thread, so give irreversible or long-running operations an internal deadline and idempotency policy of their own. Open thread-affine resources such as default SQLite connections inside the capability call rather than capturing them outside it.

Summonpot currently has no authentication layer. Bind local development to 127.0.0.1. Before exposing a service, put authentication in front of it and configure runtime limits.

The examples/ directory grows from one endpoint to a multi-file service:

The examples guide includes a real HTTP call for every level and explains what runs today and what remains planned.

Summonpot uses an ellipsis as a declaration body, which is easy for a coding agent to mistake for an unfinished handler. Install the bundled skill so the agent knows the endpoint shape, typed operation sources, registration rules, capability boundary, HTTP behavior, and runtime caveats:

summonpot add skills

With no arguments, summonpot detects agent configuration already present in the project. Choose one explicitly when needed:

summonpot add skills --agent claude
summonpot add skills --agent cursor
summonpot add skills --agent windsurf
summonpot add skills --agent copilot
summonpot add skills --agent cline
summonpot add skills --agent codex

Use --path ./myproject to target another project directory. Shared files such as AGENTS.md and .github/copilot-instructions.md are updated inside a managed block so surrounding project instructions remain intact.

The ModePot Discord is the shared community for summonpot, intpot, dexpot, and the rest of the project family. Join to discuss use cases, ask implementation questions, and help shape declaration-first Python frameworks.

Use GitHub issues for reproducible bugs and scoped feature proposals. Use Discord for open-ended design discussion, early ideas, and help applying the frameworks to real projects.

Summonpot is early enough that a focused contribution can still shape the framework, not just polish its edges.

Useful places to contribute include:

• executable examples for real application workflows;
• provider and HTTP acceptance coverage;
• clearer errors, safer defaults, and API ergonomics;
• FromResult/FromContext binding, broader capability-graph execution, and ordering;
• exact database-operation adapters;
• the deterministic execution compiler described in the roadmap;
• documentation, diagrams, and reproducible bug reports.

For substantial behavior or architecture changes, open an issue first so the public contract and security boundary stay coherent.

Development uses uv:

git clone https://github.com/tugrulguner/summonpot.git
cd summonpot
uv sync --all-extras
make check

Every user-facing change needs an issue-backed or generated orphan Towncrier fragment. Read CONTRIBUTING.md before opening a pull request.

The long-term goal is one stable endpoint declaration with the least-powerful sufficient executor behind it:

one fully resolved operation path  -> no-model deterministic executor
bounded semantic choice remains    -> agentic executor
no legal path                      -> typed deterministic error

The ordering, security constraints, non-goals, and shipped foundation live in ROADMAP.md.

If the endpoint-first approach is useful to you:

• Star the repository so more Python developers can find it.
• Build one small endpoint and report the friction.
• Share a real use case, add an executable example, or contribute to a roadmap milestone.

Early feedback is especially valuable because the public contract is small and the next execution layers are being designed around it now.

MIT