papayya 0.1.0

Durable background jobs for AI agents

Papayya

Durable background jobs for AI agents. Bring your own LLM — Papayya handles execution, checkpointing, budgets, and deployment.

Install

pip install papayya

Quick Start

Define an agent

from papayya import agent, tool

@tool
def search_web(query: str) -> str:
    """Search the web for information."""
    # Your implementation here
    return results

@agent(name="research-bot", model="gpt-4o-mini", budget_usd=1.0)
def research_bot(input_data):
    from openai import OpenAI
    client = OpenAI()
    # Your agent logic — call your LLM directly
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": input_data}],
    )
    return response.choices[0].message.content

Durable execution

Wrap long-running work in checkpoint-able tasks. If a run crashes, it resumes from the last checkpoint instead of re-executing completed steps.

from papayya import papayya

run = papayya(agent="my-agent", budget_usd=2.0)

search = run.task("search", search_web)
summarize = run.task("summarize", summarize_results)

results = search(query)        # cached on replay
summary = summarize(results)   # cached on replay

run.complete(summary)

Budget enforcement

Set per-run spending limits by USD or token count. The run pauses when a budget is exceeded.

run = papayya(
    agent="my-agent",
    budget_usd=5.0,
    budget_input_tokens=100_000,
    budget_output_tokens=10_000,
)

# After each LLM call, record the cost:
run.record_cost(cost_usd=0.03, input_tokens=1500, output_tokens=200)

Deploy

papayya login
papayya deploy

Key Concepts

• BYOF (Bring Your Own Function) — Papayya doesn't wrap your LLM calls. You use any SDK (OpenAI, Anthropic, Bedrock, etc.) directly inside your agent function.
• @agent decorator — Registers your function for deployment. The function stays callable locally.
• @tool decorator — Defines tools your agent can call, with automatic JSON Schema generation from type hints.
• Durable runs — Checkpoint-and-replay execution. Tasks are cached so replayed runs skip completed work.
• Budgets — USD and token-based limits that pause runs before overspending.

Requirements

• Python 3.10+

License

MIT