> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rotascale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install, configure, register an agent, open a trajectory, authorise an action.

```bash theme={"system"}
pip install rotascale
```

## Configuration

```bash theme={"system"}
export ROTASCALE_URL="https://rotagrant.internal.example"   # required
export ROTASCALE_API_KEY="rsk_..."                          # or ROTASCALE_TOKEN
export ROTASCALE_WORKSPACE="claims-prod"                    # optional
```

```python theme={"system"}
from rotascale import Rotascale

rs = Rotascale()                  # reads the environment
rs = Rotascale(base_url=..., api_key=..., workspace=...)
```

There is no default URL. The client raises without one, because a governance
layer that silently talks to the wrong deployment is worse than one that will
not start.

## Registering an agent

Idempotent by name within a workspace, so it is safe on every boot.

```python theme={"system"}
rs.register("claims-orchestrator",
            owner="sarah.bennett@acme.example",
            org_unit="claims",
            tier="L2")
```

## Trajectories

A trajectory is the unit of governed work, and the steps inside it are what make
a refusal readable afterwards.

```python theme={"system"}
with rs.agent("claims-orchestrator").trajectory(claim="CLM-4003") as t:
    t.plan(strategy="assess-then-settle")
    t.retrieval("claims-store:CLM-4003", trusted=True)
    t.retrieval("upload:adjuster-note.pdf")          # untrusted by default
    t.llm_call(model="internal-7b", tokens=1_840)
    t.tool_call("crm.lookup", trusted=True)

    decision = t.authorize("grt_01KZXYD62VG0",
                           {"tool": ["payments.settle"]},
                           amount_minor=250_00, currency="EUR")

    t.outcome(decision="settled", amount_minor=250_00)
```

The context manager closes the trajectory. `t.close(status=...)` does it
explicitly where you need a status other than `completed`.

## Step kinds

| Method         | Records                               |
| -------------- | ------------------------------------- |
| `plan`         | What the agent intended               |
| `llm_call`     | A model invocation                    |
| `tool_call`    | A tool, with `trusted`                |
| `retrieval`    | A source read, with `trusted`         |
| `delegation`   | Work handed to another agent          |
| `sanitise`     | A named control that discharges taint |
| `human_review` | A person looked                       |
| `disclosure`   | Something left the boundary           |
| `step`         | Anything else, by kind                |

## Closing down

```python theme={"system"}
rs.close()
```

Closes the underlying HTTP client. Not needed in short-lived processes.