Metadata-Version: 2.4
Name: cowboy-actor-sdk
Version: 0.2.0
Summary: SDK for developing Cowboy Actors
Author: Cowboy Labs
License-Expression: MIT
Project-URL: Homepage, https://github.com/cowboyinc/core
Project-URL: Documentation, https://github.com/cowboyinc/core/blob/devnet/pvm/docs/cowboy_sdk_developer_manual.md
Project-URL: Repository, https://github.com/cowboyinc/core.git
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: cbor2>=5.6.0

# Cowboy SDK

The official Python SDK for developing autonomous actors on the **Cowboy PVM (Python Virtual Machine)**.

With this SDK, you can write fully deterministic on-chain Python code that interacts natively with LLMs, APIs, and the broader Cowboy ecosystem.

## Features

- **Decentralized AI Agents**: Write prompt chains, FSM-based LLM logic, and MCP integrations directly in Python.
- **`@runner.continuation`**: Turn Python `async` functions into verified Finite State Machines (FSMs) capable of pausing execution, offloading heavy compute (LLM inference, HTTP requests) to Runners, and seamlessly resuming on the next block.
- **Robust Determinism**: The SDK strips away standard Python non-determinism (`time`, `random`, `set`) and replaces it with consensus-safe primitives.
- **CBOR-backed State**: The `CowboyModel` and `self.storage` dict provide automatic schema validation and canonical CBOR serialization for zero-boilerplate state management.
- **Built-in Async Primitives**: Leverage `JobGroup` for parallel Runner jobs (its `async with` lowers at a later regenesis), `Retry` for robust backoff logic, and `bounded_loop` to ensure safety limits.

## SDK 0.2.0

A breaking release for the regenesis that ships Safer Actors. Rebuild and
redeploy every actor with it.

- An actor is a class that inherits `Actor`; `@actor` is removed. Library
  bases such as `Pausable` are actors themselves.
- Continuations are `async def` methods that `await`; an `await` can sit in
  an `if` or `try` block, and `return await f()` works. Removes
  `@actor.continuation`, `capture()`, `save_cont`, `load_cont`, `delete_cont`,
  `runner.handle_runner_result` and `timeout_blocks=`. Every wait has a
  deadline: `timeout=` in seconds, 7 weeks by default.
- The caller is `self.sender`. Removes `runtime.get_sender()` and
  `runtime.sender()`.
- `runtime.emit_event` is the only event API, and a handler returns its
  value directly. Removes `ok()` and `decode_payload`.
- `@every` replaces `set_interval`; `schedule_after` takes seconds.
  `TaskGroup` is renamed `JobGroup`.
- Removes `@reentrancy_guard` and `ReentrancyError`: the node refuses any
  synchronous call into a running actor.
- A local read after an `await` must be bound on every path before it, and
  a sync handler that starts a continuation must be `@deferred`; the build
  refuses either otherwise.
- One caller may hold 10 open waits; callers a handler doesn't name share 80.
- `runtime.submit_job` is the low-level job call and skips these
  protections; start jobs with `await runner.*`.
- Adds `@limit`, `@single_flight`, `Escrow`, `Pausable` and `@exit`,
  `@every`, `runner.secret()` and `runtime.budget_left()`.

## SDK 0.1.7

- Routes take an `access` argument (`Access.SITE`, the default,
  `Access.OWNER` or `Access.PUBLIC`) on `route`, the verb decorators and
  `mount`.
- Adds `runtime.is_allowed_caller(hire_id, caller)` for Trading Post hires,
  with `mock_host.seed_hire` and `mock_host.seed_allowed_caller` for local
  tests.
- CIP-7 Feeds are pull-only. `@on_stream(feed, guard=None,
  numeric_tag_scales=None, page_limit=16)` reads pages through the SDK's
  `read_streams` handler; `stream_cursor` and `reset_stream_cursor` manage
  the cursor. `WatchtowerClient` drops `subscribe`, `unsubscribe`,
  `set_wake_allowance` and `get_subscription`, `subscription_payload` is
  removed, and its default budget inherits the caller's remaining Cycles
  (`INHERIT_CYCLES`).
- `runner.http`, `runner.agent` and `runner.mcp` stubs document awaiting
  runner jobs from plain `async` methods.

## SDK 0.1.6

- Owner identity comes from the protocol's ActorOwner record.
  `runtime.get_owner()` reads it; only a current-owner-signed
  `TransferActorOwnership` transaction changes it. Removes
  `runtime.transfer_ownership`, `runtime.renounce_ownership` and
  `runtime.assume_ownership_if_unowned`, and `__OWNER__` is no longer a
  reserved storage key.
- Adds `cowboy_sdk.mock_host.seed_actor_owner(owner, actor=None)` so local
  tests can set an actor's protocol owner.
- `init` needs an explicit permission decorator such as `@public`; it runs only
  in the creation call.
- Adds `runtime.get_chain_instance_id()`.

## SDK 0.1.5

- Adds per-call billing helpers in `cowboy_sdk.per_call` and
  `runtime.hire_id()` for calls made under a verified hire.
- Adds type stubs for `cowboy_sdk.routes`.
- Updates chain-reported job failures: guarded awaits can catch `JobFailed`
  (or `OffchainError` for off-chain calls); unguarded awaits end the method
  and free its continuation.
- Removes the old `runtime.amm_*` helpers: `amm_get_amount_out`,
  `amm_get_amount_in`, `amm_quote`, `amm_tick_to_sqrt_price`,
  `amm_sqrt_price_to_tick`, `amm_get_liquidity_for_amounts` and
  `amm_get_amounts_for_liquidity`. Replace calls with deterministic math in
  your actor code before upgrading; an older Python package cannot restore
  host functions removed from the network runtime.

Existing lockfiles remain pinned until updated. An unbounded requirement such
as `cowboy-actor-sdk>=0.1.4` can resolve 0.1.5 on a fresh install or upgrade, so
review these removals before updating the lockfile.

## Quick Start

```shell
pip install cowboy-actor-sdk
```

```python
from cowboy_sdk import Actor, public, runner

class MyAgent(Actor):
    @public
    def init(self, payload):
        self.storage["calls"] = 0
        return b"ok"

    @runner.continuation
    async def chat(self, msg):
        prompt = msg.get("message", "Hello")
        
        # Off-chain heavy compute (LLM) securely verified via consensus
        result = await runner.llm(prompt, system_prompt="You are a helpful assistant")
        
        # Execution resumes here on the next block
        chat_id = self.storage.get("calls", 0)
        self.storage[f"reply:{chat_id}"] = result
        self.storage["calls"] = chat_id + 1
        
        return b"ok"

def _a(): return MyAgent()
def init(p): return _a().init(p)
def chat(p): return _a().chat(p)
def chat__resume(p): return _a().chat__resume(p)
def on_runner_result(p): return _a().on_runner_result(p)
```

## Documentation & Tools

- **Developer Manual**: [View on GitHub](https://github.com/cowboylabs/cowboy/blob/main/refs/dev_support/cowboy_sdk_developer_manual.md)
- **Vibe Coding Blueprint (Claude Code)**: Learn how to set up autonomous development without local chain dependencies. [View Guide](https://github.com/cowboylabs/cowboy/blob/main/refs/dev_support/remote_developer_guide.md).
- **Cowboy CLI**: Pre-compiled binary required to deploy and send transactions. Download from the [GitHub Releases](https://github.com/cowboylabs/cowboy/releases).

## License

MIT License. See the repository for details.
