Metadata-Version: 2.4
Name: risorius-rl
Version: 0.15.2
Summary: Record research trajectories, model calls and metrics without controlling execution
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: SDK-LICENSE
Requires-Dist: boto3<2,>=1.43
Requires-Dist: httpx<1,>=0.28
Requires-Dist: PyYAML<7,>=6
Provides-Extra: recording
Requires-Dist: gymnasium==1.4.0; extra == "recording"
Provides-Extra: ray
Requires-Dist: ray[default]==2.54.0; extra == "ray"
Requires-Dist: gymnasium==1.4.0; extra == "ray"
Dynamic: license-file

# Risorius RL SDK

Record trajectories, model/tool calls and metrics from Python training, evaluation and agent services. Keep your existing `python`, `torchrun` or server entrypoint. Installing the SDK does not start training, allocate a GPU or collect every operation automatically: your code chooses what to record.

This guide covers [installation](#installation), [a first recording](#first-recording), [Gymnasium trajectories](#gymnasium-trajectories), [agent-and-serving requests](#agent-and-serving-requests), [supported values](#supported-values), [reading the output](#reading-the-output) and [central delivery](#central-delivery).

## Installation

Use Python 3.12 or later, in the environment that actually runs your application:

```bash
python -m pip install "risorius-rl[recording]"
```

`[recording]` is a Python packaging **extra**: it installs the Gymnasium dependency used by recording. Keep the quotation marks so your shell does not interpret the brackets. `python -m pip` installs into the selected Python environment. Cloning a repository alone does not install its dependencies.

For reproducible projects, pin the tested version in `requirements.txt`:

```text
risorius-rl[recording]==0.15.2
```

```bash
python -m pip install -r requirements.txt
```

PyTorch, vLLM, CUDA and model weights are separate dependencies. This SDK does not select their versions. The examples below need no GPU, server credentials or model download.

## First recording

Save this as `record_local.py`, then run `python record_local.py`:

<!-- example: local -->
```python
import time
from risorius_rl import RecordingSession

with RecordingSession(project="example", directory="outputs/records", upload=False) as recording:
    with recording.span(
        "policy.predict", kind="model", phase="train",
        attributes={"model_version": "policy-v1"},
        inputs={"observation": [0.2, -0.1]},
    ) as call:
        action = 1  # Replace with your policy's result.
        call.set_output({"action": action})
    recording.log_metrics({"loss": 0.25, "reward": 1.0}, step=1)

# Short-script check: allow local writes to finish before exiting.
deadline = time.monotonic() + 5
while recording.status["writer_active"] and time.monotonic() < deadline:
    time.sleep(0.05)

print("Run:", recording.run_id)
print("Directory:", recording.directory)
print("Recording:", recording.status)
```

`upload=False` records only on this machine. It does not contact a recording server. The model result and metrics above are sample values; in your training loop, pass the values your code actually computes. The SDK does not compute loss, reward or model decisions for you.

The bounded wait at the end gives this short script time to finish local writes, including first-use dependency loading. It does not wait for central delivery. Check that `writer_active` is false, `pending_operations` is zero and `rejected_operations` is zero before treating this example as fully recorded.

A span emits `span.started`, `span.output` and `span.ended` events. `log_metrics()` emits `metrics`. A new session has a new `run_id`.

## Gymnasium trajectories

Wrap the environment your training code already uses. The wrapper records `reset()` and `step()` results, including observation, action, next observation, reward, termination flags and the policy version you supply.

This short CartPole example exercises recording with a fixed policy; it is not a learning algorithm:

<!-- example: trajectory -->
```python
import time
import gymnasium as gym
from risorius_rl import RecordingSession

with RecordingSession(project="example", directory="outputs/records", upload=False) as recording:
    env = recording.record_env(
        gym.make("CartPole-v1", max_episode_steps=3),
        phase="train", stream="policy-train", policy_version="fixed-policy-v1",
    )
    try:
        observation, info = env.reset(seed=7)
        for step in range(3):
            with env.step_context():
                with recording.span(
                    "policy.predict", kind="model", phase="train",
                    inputs={"observation": observation},
                ) as call:
                    action = 0
                    call.set_output({"action": action})
                observation, reward, terminated, truncated, info = env.step(action)
            recording.log_metrics({"reward": float(reward)}, step=step)
            if terminated or truncated:
                break
    finally:
        env.close()

# Short-script check: allow local writes to finish before exiting.
deadline = time.monotonic() + 5
while recording.status["writer_active"] and time.monotonic() < deadline:
    time.sleep(0.05)

print("Directory:", recording.directory)
print("Recording:", recording.status)
```

`step_context()` connects calls made in that context to the environment's episode and step. Merely recording a model call and a transition separately does not establish that relationship. For evaluation, use `phase="eval"` on the wrapper and calls, and a distinct stream such as `policy-eval`.

This wrapper supports individual Gymnasium environments. Vector environments, automatic resets and nested recording wrappers are not supported by this API. Model training, checkpointing and environment lifecycle remain your application's responsibility.

## Agent and serving requests

Create one session per server process, use `request()` for each application request, and close the session during server shutdown. Nest `span()` around the actual model and tool calls. The following standalone example uses a simulated answer so it can run without a model server:

<!-- example: serving -->
```python
import time
from risorius_rl import RecordingSession

with RecordingSession(
    project="example", directory="outputs/records", upload=False, kind="serving",
) as recording:
    with recording.request(
        "agent.respond", model_version="chat-model-v1",
        attributes={"request_id": "request-001", "session_id": "conversation-001"},
        inputs={"message": "What is the next interview question?"},
    ) as request:
        with recording.span(
            "model.generate", kind="llm", inputs={"prompt": "Ask one clarifying question."},
        ) as model_call:
            # In your service, call the model here and record its actual response.
            answer = "Which topic would you like to discuss?"
            model_call.set_output({"text": answer})
        request.set_output({"answer": answer})
        reference = request.reference

# Short-script check: allow local writes to finish before exiting.
deadline = time.monotonic() + 5
while recording.status["writer_active"] and time.monotonic() < deadline:
    time.sleep(0.05)

print("Request reference:", reference)
print("Directory:", recording.directory)
print("Recording:", recording.status)
```

Within the same execution context, the model span has the request span's ID as its `parent_span_id`. Keep `request.reference` alongside your application response: it contains `run_id`, `stream_id` and `span_id` when recording is available, or is `None` when capture failed. A session can contain many requests. Your `session_id` groups conversations; it is application metadata, not an automatically managed chat history.

Instrument the **agent's model client** to capture the prompt, response, tool selection and tool result it sees. You do not need to modify vLLM for that. To capture additional events inside a separate model server, instrument that server too and carry explicit correlation identifiers across HTTP. Automatic cross-service trace propagation is not provided.

For streaming responses, keep the span open while consuming the stream and record the fields you need. `set_output()` can be called once per span; do not call it repeatedly for individual tokens. There is no automatic token-stream capture. Keep payload limits in mind when recording a complete response.

Reasoning text is recorded only if the model API exposes it and your code explicitly supplies it, for example as an output field. This does not reveal hidden internal reasoning or prove that text faithfully describes the model's computation. User choices, approvals, rejections and business outcomes also require explicit application instrumentation; an HTTP 200 alone does not mean task success.

## Supported values

| API | What you supply | Recorded result |
| --- | --- | --- |
| `span(name, kind=..., inputs=..., attributes=...)` | A name, `model`, `llm` or `tool` kind, explicit input and metadata; phase `train`, `eval` or `serve` | Call start, optional output, end status and timing |
| `call.set_output(value, usage=...)` | Output once per open span; optional `input_tokens`, `output_tokens`, `total_tokens` | Output and supplied token counts; usage is not calculated automatically |
| `request(name, model_version=..., ...)` | Serving input, caller-supplied version and metadata | A request span in `calls-serve` and a reference for correlation |
| `log_metrics(metrics, step=..., phase=...)` | 1–100 named finite numeric values, nonnegative integer step; phase `train` or `eval` | One metric event in `metrics-train` or `metrics-eval` |
| `record_env(env, phase=..., stream=..., policy_version=...)` | Individual Gymnasium environment and explicit policy version | Episode boundaries and transitions |
| `trace(function, ...)` | A synchronous or asynchronous callable and optional input/output extractors | A wrapped call; explicit spans are clearer for generators and streaming |

Inputs, outputs and attributes accept `None`, booleans, finite numbers, strings, lists, tuples, dictionaries with string keys, and supported NumPy numeric arrays/scalars. Arbitrary Python objects, raw PyTorch tensors, complex numbers and nonfinite values are not accepted. Convert intentionally: a scalar tensor can become `tensor.detach().item()`, and a small tensor can become a CPU array. Moving large tensors to the CPU can slow training; avoid logging full weights or activations in events.

Payload validation is bounded by depth 32, 4,096 values and a 64 KiB operation limit. Metric names start with a letter and contain letters, digits, `_`, `.`, `/` or `-` (up to 128 characters). Metric steps cannot decrease within a phase. Token counts are nonnegative integers. `model_version` and `policy_version` are supplied by your code, not verified deployment attestations.

Invalid recording operations are normally rejected without stopping application execution. Check `rejected_operations` and `last_error_type` in `recording.status`. `RecordingSession.validate(value)` provides explicit payload validation that raises an exception, useful before a long experiment; it does not validate every method-specific contract.

## Reading the output

The local-only examples create this layout under the printed run directory:

```text
outputs/records/<run_id>/
  recording-status.json
  recordings/
    calls-train/                 # Or calls-serve for a serving session
      manifest.json
      records.jsonl
    metrics-train/
      manifest.json
      records.jsonl
    policy-train/                # When record_env() is used
      manifest.json
      records.jsonl
```

Only streams you use are created. A JSONL file contains one JSON event per line. Manifests describe the stream and its recorded contents. Events include `schema_version`, `project_id`, `run_id`, `stream_id`, `sequence`, `event_id`, `occurred_at` and `event_type`. Call events also carry `span_id`; nested calls carry `parent_span_id`. Environment events use `episode_id` and transitions have `step_index`. Sequence order is per stream, not a global order across all streams.

For example, these are the relevant fields of a model output event (identity and timestamp fields omitted):

```json
{
  "event_type": "span.output",
  "output": {"type": "dict", "items": {"action": 1}}
}
```

Structured payloads use type tags to preserve dictionaries, lists, tuples and NumPy dtype/shape information. To read the first example's output, save this as `read_records.py` and run `python read_records.py outputs/records/<run_id>` with your actual run directory:

<!-- example: reader -->
```python
import json
import sys
from pathlib import Path
from risorius_rl.observability.codec import decode

root = Path(sys.argv[1])
for path in sorted((root / "recordings").glob("*/*.jsonl")):
    if path.name.startswith("."):
        continue  # An active upload chunk may still be incomplete.
    for line in path.read_text().splitlines():
        event = json.loads(line)
        print(event["stream_id"], event["sequence"], event["event_type"])
        if event["event_type"] == "span.output":
            print(decode(event["output"]))
```

Apply `decode()` to encoded payload fields, not the whole event or ordinary metric dictionaries. The SDK records explicit observations, decisions and outcomes; it does not automatically create a reward model, grader or training dataset from arbitrary logs.

## Central delivery

An administrator supplies an authorized project, a recording token and a compatible HTTPS endpoint. Store the token in an environment variable or deployment Secret, not in source code, YAML or Git. A token's recording permission does not grant GPU allocation or record-download permission.

```yaml
# riso.yaml
version: 1
project: your-project
recording:
  endpoint: https://your-recording-server.example/recording
  directory: ./outputs/records
  upload: true
auth:
  token_env: RISO_API_TOKEN
```

After securely setting `RISO_API_TOKEN`, replace the local session constructor with:

```python
from risorius_rl import RecordingSession

with RecordingSession.from_config("riso.yaml") as recording:
    recording.log_metrics({"loss": 0.25}, step=1)
```

For a service, use `RecordingSession.from_config("riso.yaml", kind="serving")` and retain the request/span instrumentation shown above. YAML is loaded only when your code calls `from_config()`. The output directory is relative to the YAML file. The endpoint must implement the RISO recording protocol; it is not an arbitrary HTTP, Kafka or S3 destination. This flow requires neither `riso login` nor `riso run`.

```text
Your code → RecordingSession → bounded local files → background HTTPS upload
                                                 → compatible recording service
```

The SDK does not connect directly to Kafka. Downstream Kafka/S3 processing, retention and access policy belong to the receiving service. In upload mode, streams use numbered chunks such as `000000.jsonl` rather than `records.jsonl`; acknowledged chunks can be removed locally. Preserve any still-pending run directory when stopping or replacing the machine. Do not publish the entire directory: transport metadata can contain credentials.

`recording.status` reports local capture and current transport state. `recording-status.json` is a snapshot of local finalization; `delivery-status.json` tracks delivery in upload mode. `closed: true` or `context_completed` means the recording context ended, not that all events reached central storage or that the model achieved its task. `uploading` is not a delivery receipt. Check for transport `complete` and, when using a hosted service, verify its central records separately.

After the application has stopped, this optional recovery command retries persisted records without rerunning training:

```bash
riso sync outputs/records/<run_id>
```

Keep the original valid credentials available, including the configured token environment variable. Authentication failures require an authorized token; a newly issued token cannot automatically take over a run bound to a different token. Upload recovery cannot reconstruct events that were never persisted or were rejected.

## Reliability and data handling

Recording failures are isolated from application control: the session does not impose training time limits, kill the model process or allocate/release infrastructure. Exceptions from your model or environment still propagate normally. This isolation is not a guarantee of zero overhead or lossless recording.

Local storage is bounded to 256 MiB by default, the writer queue is bounded, and shutdown waits at most one second. A full disk/budget, high event rate, abrupt process termination or failed transmission can leave incomplete records. Monitor `pending_operations`, `rejected_operations`, `writer_active` and delivery state; validate your workload before relying on long-running production capture. Preserve pending files for recovery.

Some sensitive key names are masked in call payloads. This is not comprehensive personal-data detection: free text, observations and outputs may contain sensitive information. Apply your own data policy before passing values to the SDK. Keep credentials separate from model inputs and restrict access to local records and central storage.

Create sessions inside worker processes, not before forking. This `RecordingSession` guide does not provide automatic distributed-rank aggregation, cross-service trace propagation or durable application execution. Retries, job scheduling and reconnecting users to a running agent remain application responsibilities.

## License and service access

The `risorius_rl` package and this SDK documentation are MIT licensed; see `SDK-LICENSE`. This license does not cover the platform's server repository, model weights or research datasets. Installing the SDK grants no access to a hosted service. Server access requires separate credentials and project authorization.
