Configure and troubleshoot

Download this guide as Markdown

Provider selection

An endpoint can set a model override in its @summon(..., model=...) declaration. Otherwise Runtime resolves SUMMONPOT_MODEL when handling a request, falling back to openai:gpt-4o-mini. Select a provider-supported model name and install the corresponding Summonpot provider extra when required. Credentials are provider-specific environment configuration; never commit them or print them in logs. The provider-neutral runtime and optional dependencies are defined in pyproject.toml.

For agent-backed local wiring, set SUMMONPOT_MODEL=test. This avoids provider credentials but does not make capability execution inert: the test model may call declared operations with placeholder arguments. Use harmless, isolated operations only. For a no-model demonstration that makes no model call, use the fully qualifying direct-execution guide.

Bound model work

Runtime accepts retries, Pydantic AI usage_limits, and timeout. Set limits deliberately for the workload; timeout applies to execution, not side-effect rollback. Provider throttling can be returned as 429; upstream provider errors are surfaced as 502. A request-level timeout maps to 504. See runtime implementation and HTTP mapping.

Troubleshooting

Symptom	Likely boundary	What to inspect
Registration raises for an explicit operation	Contract is incomplete or unsupported	Confirm every callable parameter is bound/defaulted, source vocabulary is supported, annotations are compatible, and output is declared.
HTTP 422	Invalid body/query or injected receiver mismatch	Compare payload with generated OpenAPI and receiving parameter annotations. Application code should not start for rejected request values.
HTTP 429	Usage limit or provider throttling	Logs distinguish configured usage exhaustion from upstream throttling; keep public messages redacted.
HTTP 502	Provider request failed	Check selected model, installed provider integration, credentials, and upstream availability in operator logs.
HTTP 504	Runtime timed out	Check timeout budget and operation/provider latency. A timed-out side effect may already have occurred.
test response is placeholder text	Test model is for wiring, not quality	Test schema and route behavior; do not infer semantic output quality.
Side effect occurred despite an error	Validation/timeout is not a transaction	Put authorization, transactionality, idempotency, and compensation in the application operation.

Public failure bodies are intentionally fixed rather than exposing provider text or operation details that may contain request data or secrets. Use server logs with appropriate access controls for diagnosis; do not echo sensitive exception bodies to clients.

Serve on loopback during development

Install summonpot[serve,cli], then use summonpot serve app.py --host 127.0.0.1 --port 8000. Binding to loopback avoids exposing an experimental endpoint to the network. The CLI loads a Python file containing a Summon instance named summon; package commands are defined in cli.py. Review deployment exposure, authentication, rate limits, secrets, and capability authority before binding publicly.

Security checklist

• Authorize every request inside application-owned operations; request fields are not trusted identity.
• Expose narrow operations, never ambient process/database/shell authority.
• Treat all declared functions as real side effects even under the keyless model.
• Add idempotency and transaction controls in application code when required.
• Keep timeouts and provider limits; do not claim they roll back application changes.
• Treat schema validation as structure/type enforcement, not factual or provenance verification.