Metadata-Version: 2.5
Name: tama-sdk
Version: 0.1.0
Summary: Agent-friendly Python SDK for Tama
Author: Tama
Requires-Python: >=3.10
Requires-Dist: grpcio<2,>=1.81.1
Requires-Dist: protobuf<7,>=6.33.5
Requires-Dist: pyyaml<7,>=6
Provides-Extra: dev
Requires-Dist: grpcio-tools==1.81.1; extra == 'dev'
Requires-Dist: mypy<2,>=1.14; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Requires-Dist: types-protobuf<7,>=5.29; extra == 'dev'
Description-Content-Type: text/markdown

# Tama Python SDK

Typed, agent-friendly access to Tama's control plane. The SDK can reuse the
credentials written by the Tama CLI, so local scripts need no token plumbing.

```bash
cd sdks/python
uv sync --extra dev
```

```python
from tama_sdk import Tama

with Tama(profile="production") as tama:
    machine = tama.new(name="worker", image="ubuntu:24.04")

    result = machine.exec(["git", "status", "--short"], check=True)
    print(result.stdout)

    prompt = machine.prompt(
        "Fix the failing tests, then summarize the change.",
        agent="codex",
    )
    print(prompt.output)
```

The common workflows mirror the CLI: `new`, `list`, `rm`, `stop`, `start`,
`fork`, `exec`, `logs`, `prompt`, `expose`, `unexpose`, `ports`, `desktop`, and
`terminal`. Returned machines keep those actions scoped:

```python
machine = tama.get("worker")
machine.stop()
machine.start()

session = machine.prompt("Review the repository", detach=True)
for event in tama.logs(session.id):
    print(event.data, end="")
```

Secondary resources use discoverable collections:

```python
tama.snapshots.list(machine="worker")
tama.templates.list()
tama.secrets.set("OPENAI_API_KEY", "...")
tama.tokens.create("ci")
```

For CI, set `TAMA_TOKEN` and optionally `TAMA_API_URL`. Configuration precedence
is explicit constructor values, environment variables, then the selected CLI
profile. The SDK never prints credentials.

The complete generated schema is available as `tama_sdk.proto`, and the
generated service stub is available as `tama.raw` when a new RPC lands before
its convenience wrapper.

## Safety and retries

Read-only RPCs retry short `UNAVAILABLE` and `DEADLINE_EXCEEDED` failures with
bounded exponential backoff. Mutations are never retried automatically: a
timed-out create or snapshot may already be running on the server.

## Development

```bash
uv run --extra dev python scripts/generate.py
uv run --extra dev pytest
uv run --extra dev ruff check .
uv run --extra dev mypy
```

The generated protobuf modules are committed so installing the wheel does not
require `protoc`.
