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

# Python SDK types

> Python type definitions for the Reactor SDK

## `FileRef`

A reference to an uploaded file, returned by [`upload_file()`](/sdk-reference/python/reactor#upload_file). Pass into `send_command()` to attach files to a command.

```python Definition theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
@dataclass(frozen=True)
class FileRef:
    upload_id: str    # Upload identifier
    name: str         # Filename
    mime_type: str    # MIME type (e.g. "image/jpeg")
    size: int         # File size in bytes
```

See [File Uploads](/concepts/file-uploads) for usage examples.

***

## `ReactorStatus`

Connection state enum.

```python Definition theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
from reactor_sdk import ReactorStatus

class ReactorStatus(Enum):
    DISCONNECTED = "disconnected"  # No active connection
    CONNECTING   = "connecting"    # Negotiating with the coordinator
    WAITING      = "waiting"       # Waiting for a GPU to be assigned
    READY        = "ready"         # Connected to the model
```

***

## `ReactorState`

```python Definition theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
@dataclass
class ReactorState:
    status: ReactorStatus
    last_error: ReactorError | None = None
```

***

## `ReactorError`

```python Definition theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
@dataclass
class ReactorError:
    code: str
    message: str
    timestamp: float          # Unix timestamp
    recoverable: bool
    component: Literal["api", "gpu"]
    retry_after: float | None = None  # Suggested retry delay in seconds
```

Supports string conversion:

```python Example theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
print(error)  # "[api:CONNECTION_FAILED] Failed to connect"
```

### Error codes

| Code                   | Component | Recoverable | Description                             |
| ---------------------- | --------- | ----------- | --------------------------------------- |
| `CONNECTION_FAILED`    | api       | Yes         | Failed to establish a connection        |
| `GPU_CONNECTION_ERROR` | gpu       | Yes         | Connection to GPU dropped               |
| `RECONNECTION_FAILED`  | gpu       | Yes         | Failed to reconnect to existing session |

***

## `ReactorEvent`

```python Definition theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
ReactorEvent = Literal[
    "status_changed",
    "session_id_changed",
    "message",
    "runtime_message",
    "track_received",
    "error",
    "session_expiration_changed",
    "capabilities_received",
]
```

***

## `FrameCallback`

```python Definition theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
FrameCallback = Callable[[NDArray[np.uint8]], None]
```

The callback receives a NumPy array with:

* **Shape:** `(H, W, 3)`: height, width, 3 color channels
* **Dtype:** `uint8`: values 0 to 255
* **Color order:** RGB

***

## `ConflictError`

Raised when a connection is superseded by a newer request to the same session.

```python Definition theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
class ConflictError(Exception):
    pass
```

***

## `VersionMismatchError`

Raised when the SDK's protocol version is incompatible with the server. Update your SDK to resolve.

```python Definition theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
class VersionMismatchError(Exception):
    pass
```

***

## `fetch_jwt_token()`

Fetches a token from the Reactor API using an API key.

```python Signature theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
async def fetch_jwt_token(
    api_key: str,
    api_url: str = "https://api.reactor.inc",
) -> str
```

<ParamField path="api_key" type="str" required>
  Your Reactor API key (`rk_...`).
</ParamField>

<ParamField path="api_url" type="str" default="https://api.reactor.inc">
  The API URL.
</ParamField>

Returns the token as a `str`. Raises `RuntimeError` if authentication fails.

<Note>
  In most cases you don't need this directly. Pass `api_key` to the `Reactor` constructor and the SDK handles the exchange automatically during `connect()`.
</Note>