Skip to content
summonpot

Quick start

Install

Section titled “Install”
Terminal window
python -m venv .venv
. .venv/bin/activate
python -m pip install "summonpot[serve,cli]"

On Windows, activate the environment with .venv\Scripts\activate.

Summonpot supports Python 3.11–3.14. To wire an endpoint without a provider account, select the built-in test model:

Terminal window
export SUMMONPOT_MODEL=test

Continue with the model-free endpoint task guide for a complete validated HTTP example, the agent-backed bound-operation guide for explicit choices, and the operation reference for supported and planned declaration shapes.

The test model is keyless, not side-effect-free: it can call capabilities with generated placeholder arguments. Use harmless capabilities only; this is not a dry-run sandbox.

Explore the restricted playground

Section titled “Explore the restricted playground”

The browser-local contract playground previews request-owned customer IDs, a bounded summary/detailed format you select, and an application-owned lookup from the bound-operation example. It neither calls a model nor executes Python; it computes the operation result in this tab.

Run the actual keyless HTTP example

Section titled “Run the actual keyless HTTP example”

The repository’s direct quote example is the recommended no-credentials demo. It accepts one validated request and invokes exactly one declared operation using only request-bound values. It does not use the test model or any AI provider. The response is application-calculated—not an AI-generated quote.

Download the example from the published 0.10.0 release into your current directory, then start it with the installed console command in the activated environment:

Terminal window
curl -fL https://raw.githubusercontent.com/tugrulguner/summonpot/v0.10.0/examples/08_direct_execution.py -o 08_direct_execution.py
summonpot serve 08_direct_execution.py --host 127.0.0.1 --port 8000

In another terminal, send a request while the server is running:

Terminal window
curl -sS -X POST http://127.0.0.1:8000/quotes/direct \
  -H 'Content-Type: application/json' \
  -d '{"unit_price_cents":1299,"quantity":3,"tax_rate_percent":"8.25"}'

For this input the actual HTTP app returns subtotal 3897 cents, tax 322 cents, and total 4219 cents. These are deterministic outputs, not an AI response. Invalid request values are rejected with HTTP 422 before execution. The test suite exercises the actual HTTP app.

Declare a typed endpoint

Section titled “Declare a typed endpoint”

Save as 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 declaration is the endpoint contract; Summonpot owns orchestration. The ellipsis is intentional, and calling the decorated function directly is rejected. See the runnable quick-start example.

Serve and call

Section titled “Serve and call”
Terminal window
summonpot serve app.py --host 127.0.0.1 --port 8000

Visit interactive API docs. Submit JSON with:

Terminal window
curl -X POST http://127.0.0.1:8000/review \
  -H 'Content-Type: application/json' \
  -d '{"text":"The setup was clear and quick."}'

For production, configure a supported provider and retain bounded request/usage limits. Review each capability as application authority: the keyless model can still execute it.