Metadata-Version: 2.4
Name: once-agent-sdk
Version: 0.1.0
Summary: Execution safety for side-effecting AI agent tools.
Author: Once
License: MIT
Project-URL: Homepage, https://onceexec.pages.dev/
Project-URL: Repository, https://github.com/stringsofthemind-oss/once
Project-URL: Documentation, https://onceexec.pages.dev/agent.md
Project-URL: Issues, https://github.com/stringsofthemind-oss/once/issues
Keywords: ai,agents,idempotency,reliability,execution-safety
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 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# once-agent-sdk

Execution safety for consequential AI agent tool calls.

Once helps applications avoid blindly repeating real-world side effects after ambiguous outcomes such as timeouts, crashes, lost responses, queue redelivery, or agent retries.

Examples include refunds, payments, payouts, bookings, orders, provisioning, deployments, API mutations, and other operations that change external state.

## Install

```bash
pip install once-agent-sdk
```

## Quick start

```python
from once_agent import Once

once = Once()

order_id = "order_123"
operation_id = Once.id("refund", order_id)

result = once.execute(
    operation_id=operation_id,
    provider="my-provider",
    action={
        "type": "refund",
        "order_id": order_id,
    },
)
```

Set your Once API key in the environment:

```text
ONCE_API_KEY=your_api_key
```

Do not commit API keys to source control.

## Why stable operation identity matters

If an external action succeeds but its response is lost, retrying the action without knowing the prior outcome can duplicate the real-world side effect.

`Once.id(...)` generates a deterministic operation ID, so retries of the same logical operation can retain the same identity.

```python
a = Once.id("refund", "order_123")
b = Once.id("refund", "order_123")

assert a == b
```

## Claim boundary

Once does not claim universal exactly-once execution.

Execution safety depends on stable operation identity, durable Once state, the provider integration, and sufficiently authoritative provider truth. When an outcome cannot be established safely, Once can preserve uncertainty instead of blindly repeating the external action.

## Links

- Website: https://onceexec.pages.dev/
- GitHub: https://github.com/stringsofthemind-oss/once
- Agent guide: https://onceexec.pages.dev/agent.md
- MCP package: https://www.npmjs.com/package/@once-agent/mcp
