Metadata-Version: 2.4
Name: papermap-air
Version: 0.1.0
Summary: Client SDK and worker runtime for the AIR platform
Project-URL: Homepage, https://papermap.ai
Project-URL: Repository, https://github.com/Papermap-ai/papermap-air
Author: Papermap
License-Expression: LicenseRef-Proprietary
Keywords: agents,ai,papermap,runtime,tools,workers
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
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 :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Description-Content-Type: text/markdown

# Papermap AIR Python SDK

Build applications and outbound tool workers for the Papermap Agentic
Infrastructure Runtime (AIR).

## Install

```bash
pip install papermap-air
```

Python 3.10 or newer is required.

## Start a run from your application

Create a project and agent in the AIR console, issue an **app key** from the
project settings page, and keep the key in your secret manager.

```python
import asyncio
import os

from air import AirClient


async def main() -> None:
    async with AirClient(
        os.environ["AIR_BASE_URL"],
        os.environ["AIR_APP_KEY"],
    ) as client:
        run = await client.runs.create(
            agent_id="support-agent",
            input={"question": "Where is order 1042?"},
            context={"tenant_id": "acme"},
        )
        result = await client.runs.wait(run.id, timeout=120)
        print(result.output)


asyncio.run(main())
```

## Run a tool worker

Put your tool declarations in `tools.py`:

```python
from air import tool


@tool
def lookup_order(order_id: str, context: dict) -> dict:
    """Look up an order in the customer's system."""

    return {
        "order_id": order_id,
        "tenant_id": context["tenant_id"],
        "status": "shipped",
    }
```

Issue a **worker key** from the AIR project, store it as an environment
variable, and start the worker:

```bash
export AIR_BASE_URL="https://airapi.example.com"
export AIR_WORKER_KEY="<worker-key>"
export AIR_WORKER_ENV="production"

air worker start --module tools
```

Newly discovered tools appear as **pending** in the AIR console. Review and
enable them before attaching them to an agent version.

## Keys

- **App keys** let an application create runs and read their results.
- **Worker keys** let an outbound worker register tools and claim tool calls.
- Never commit either key or pass a worker key through the `--key` CLI option
  in shared or production environments. Prefer `AIR_WORKER_KEY`.

## License

Proprietary. Copyright Papermap. All rights reserved.
