Pilota

Put agents inside Python. Keep Python in control.

Documentation · Tutorial · API reference

Pilota runs one bounded AI task as an ordinary typed expression. Your program owns the workflow. The agent receives only the context, authority, and budget you grant.

from dataclasses import dataclass

from pilota import agent
from pilota.providers.openrouter import OpenRouterModel


@dataclass
class Plan:
    steps: list[str]


with OpenRouterModel("openai/gpt-4.1-mini") as model:
    plan = agent(
        "Plan the requested change",
        model=model,
        context={"request": "Add response caching"},
        returns=Plan,
    )

for step in plan.steps:
    print(step)

• Ordinary Python: loops, branches, retries, and tests stay in your code.
• Typed contracts: request a dataclass, Pydantic model, or any TypeAdapter type.
• Explicit authority: expose selected tools, read-only resources, and a policy-controlled workspace.
• Bounded execution: limit model calls, tool calls, result retries, and wall time.
• Inspectable outcomes: keep the typed result, usage, trace, and changed-file artifacts.
• Deterministic tests: drive the full runtime with ScriptedModel, without network calls.

Installation

pip install 'pilota[openrouter]'

Python 3.11+. The core package (pip install pilota) has no HTTP client; the openrouter extra adds the OpenRouter provider.

Early development. Versions 0.0.x may contain breaking changes.

License

MIT