SDK Reference

The Papayya SDK is available for Python and TypeScript.

# Python
pip install papayya
 
# TypeScript
npm install papayya

Papayya does not ship LLM provider adapters. You bring your own LLM SDK (anthropic, openai, bedrock, ollama, ...) and call it directly — Papayya wraps the call with durable checkpointing via run.task(...). This keeps provider SDK churn out of your critical path and guarantees we never break your runs when a provider ships a breaking SDK change.

Local Execution (Primary Path — BYOF)

Wrap your existing code with Papayya for checkpointing, cost tracking, and observability.

Python

from papayya.durable import papayya
 
t = papayya()  # auto-detects API key from env or config
run = t.run("my-agent", budget_usd=5.0)
 
# Each task is checkpointed — survives crashes, replays on restart.
# Your code owns the LLM call; Papayya captures the result as a checkpoint.
@run.task("search")
def search(query: str):
    return my_search_fn(query)
 
@run.task("summarize")
def summarize(results):
    import anthropic
    client = anthropic.Anthropic()
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=[{"role": "user", "content": f"Summarize: {results}"}],
    )
    # Record cost using your own pricing contract
    # run.record_cost(computed_cost_usd)
    return response.content[0].text
 
results = search("AI agents")
summary = summarize(results)
run.complete(summary)

TypeScript

import { papayya } from "papayya";
 
const t = papayya();
const run = t.run({ agent: "my-agent", budgetUsd: 5.0 });
 
const search = run.task("search", mySearchFn);
const summarize = run.task("summarize", async (results: string) => {
  // Call your LLM SDK directly — you own this
  const res = await myAnthropicClient.messages.create({ /* ... */ });
  return res.content[0].text;
});
 
const results = await search("AI agents");
const summary = await summarize(results);
await run.complete(summary);

How it works

papayya() auto-detects your API key from PAPAYYA_API_KEY or ~/.papayya/config.json
If a key is found, checkpoints persist to the cloud (visible in dashboard)
If no key, falls back to in-memory (local development)
run.task(label, fn) returns a wrapped function. On first call, it executes and checkpoints. On replay (same run_id), it returns the cached result.
Cost tracking is explicit — call run.record_cost(usd) after your LLM call with a number you compute from your own pricing contract. Papayya does not monkey-patch provider SDKs.

Agent Definition (Convenience Layer)

For developers who want an opinionated starting point for agents they plan to deploy to the cloud runtime. Agent is a declarative description — it does not call LLMs on your behalf. The model field is a display label, not a provider selector.

See Agent for full details and BYOF examples in both languages.

Papayya Client (Cloud Operations)

For managing runs, agents, secrets, schedules, and webhooks programmatically.

TypeScript

import { Papayya } from "papayya";
 
const papayya = new Papayya({ apiKey: "cpk_..." });
 
const run = await papayya.runs.create({ agentId: "...", input: "Summarize the news" });
await papayya.schedules.create({ agentId: "...", cron: "0 9 * * *" });
const usage = await papayya.usage.summary({ from: "2026-03-01", to: "2026-03-31" });

Python

from papayya import Papayya
 
papayya = Papayya(api_key="cpk_...")
 
run = papayya.runs.create(agent_id="...", input="Summarize the news")
papayya.schedules.create(agent_id="...", cron="0 9 * * *")

Resources

Resource	Methods
`papayya.runs`	`create`, `get`, `list`, `cancel`, `replay`, `steps`, `logs`
`papayya.agents`	`create`, `list`, `get`, `update`
`papayya.schedules`	`create`, `list`, `get`, `update`, `delete`
`papayya.webhooks`	`create`, `list`, `delete`
`papayya.deployments`	`create`, `get`, `list`
`papayya.secrets`	`set`, `list`, `delete`
`papayya.projects`	`create`, `list`, `get`, `update`, `delete`
`papayya.apiKeys`	`create`, `list`, `revoke`
`papayya.usage`	`summary`, `breakdown`

Detailed references

Module	Description
Agent	Agent declarative description and BYOF execution
Tools	`@tool` decorator (Python), `defineTool` (TypeScript)
Budget Tracker	Track and enforce spend limits
Types	TypeScript types and interfaces

Schedules & Webhooks Agent