Metadata-Version: 2.4
Name: papayya
Version: 0.1.0
Summary: Durable background jobs for AI agents
Project-URL: Homepage, https://papayya.com
Project-URL: Documentation, https://docs.papayya.com
Project-URL: Repository, https://github.com/tribe-agents/papayya
Author: Kingsley Torlowei
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,background-jobs,durable,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: click<9,>=8
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# Papayya

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

## Install

```bash
pip install papayya
```

## Quick Start

### Define an agent

```python
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.

```python
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.

```python
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

```bash
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
