---
name: Osmosis
description: Use when building reinforcement learning training pipelines for LLMs, defining agent workflows and reward signals, submitting evaluation and training runs, managing datasets and models, or deploying trained LoRA models for inference.
metadata:
    mintlify-proj: osmosis
    version: "1.0"
---

# Osmosis Skill

## Product Summary

Osmosis is a post-training platform for LLMs that handles distributed RL training, GPU provisioning, and model deployment. Agents use the Osmosis CLI (`osmosis` command) to define agent behavior via `AgentWorkflow` classes, assign rewards via `Grader` classes, submit evaluation and training runs from TOML configs, manage datasets, and deploy trained LoRA models.

**Key files and commands:**
- Workspace structure: `rollouts/`, `configs/eval/`, `configs/training/`, `data/`
- Core classes: `AgentWorkflow`, `Grader` (in `rollouts/<name>/main.py`)
- Config files: `configs/eval/*.toml`, `configs/training/*.toml`
- Primary CLI: `osmosis eval submit`, `osmosis train submit`, `osmosis dataset upload`, `osmosis model deploy`
- Docs: https://docs.osmosis.ai

## When to Use

Reach for this skill when:
- **Building agent training pipelines**: Creating `AgentWorkflow` and `Grader` classes to define agent behavior and reward signals
- **Submitting evaluation runs**: Testing rollout code against a dataset before training with `osmosis eval submit`
- **Submitting training runs**: Starting RL training with `osmosis train submit` after evaluation passes
- **Managing datasets**: Uploading JSONL/CSV/Parquet datasets with `osmosis dataset upload` and referencing them in configs
- **Deploying models**: Deploying trained LoRA models for inference with `osmosis model deploy`
- **Debugging rollouts**: Inspecting evaluation run results, logs, and trajectories with `osmosis eval info` and `osmosis eval download`
- **Configuring training**: Setting hyperparameters, timeouts, sampling, and checkpoints in training TOML files

## Quick Reference

### Essential Commands

| Task | Command |
| --- | --- |
| Check workspace health | `osmosis doctor` |
| Authenticate | `osmosis auth login` |
| Upload dataset | `osmosis dataset upload data/file.jsonl` |
| List datasets | `osmosis dataset list` |
| Submit evaluation run | `osmosis eval submit configs/eval/my-rollout.toml` |
| List evaluation runs | `osmosis eval list` |
| Inspect evaluation results | `osmosis eval info <run-name>` |
| Download evaluation outputs | `osmosis eval download <run-name>` |
| Submit training run | `osmosis train submit configs/training/my-rollout.toml` |
| List training runs | `osmosis train list` |
| Monitor training | `osmosis train info <run-name>` |
| Deploy LoRA model | `osmosis model deploy <lora-model-name>` |
| List models | `osmosis model list` |

### Workspace Structure

```
repository/
├── rollouts/
│   └── my-rollout/
│       ├── main.py              # AgentWorkflow + Grader classes
│       └── pyproject.toml        # Rollout dependencies
├── configs/
│   ├── eval/
│   │   └── my-rollout.toml       # Evaluation config
│   └── training/
│       └── my-rollout.toml       # Training config
├── data/
│   └── dataset.jsonl             # Local test datasets
└── pyproject.toml                # Workspace dependencies
```

### Core Classes

| Class | Purpose | Key Method |
| --- | --- | --- |
| `AgentWorkflow` | Defines agent behavior for one sample | `async def run(ctx: AgentWorkflowContext) -> None` |
| `Grader` | Assigns reward to a sample | `async def grade(ctx: GraderContext) -> None` |
| `AgentWorkflowContext` | Input to workflow: prompt, config, metadata, artifacts dir | Read `ctx.prompt`, write to `ctx.artifacts_dir` |
| `GraderContext` | Input to grader: sample, label, metadata, artifacts dir | Call `ctx.set_reward(float)` |

### Config File Essentials

**Evaluation config** (`configs/eval/my-rollout.toml`):
```toml
[experiment]
rollout = "my-rollout"
entrypoint = "main.py"
model_path = "openai/gpt-5-mini"
dataset = "my-dataset"

[evaluation]
limit = 100                        # Rows to evaluate (omit for 10% sample)
n = 1                              # Attempts per row
pass_threshold = 1.0

[secrets]
required = ["OPENAI_API_KEY"]
```

**Training config** (`configs/training/my-rollout.toml`):
```toml
[experiment]
rollout = "my-rollout"
entrypoint = "main.py"
model_path = "Qwen/Qwen3.6-35B-A3B"
dataset = "my-dataset"

[training]
lr = 1e-6
total_epochs = 1
n_samples_per_prompt = 8
rollout_batch_size = 32

[checkpoints]
eval_interval = 10
checkpoint_save_freq = 20
```

### Agent Integrations

| Integration | Use When | Key Classes |
| --- | --- | --- |
| Strands Agents | Using Strands tools and message handling | `OsmosisStrandsAgent`, `OsmosisRolloutModel` |
| OpenAI Agents SDK | Using OpenAI Agents, `Runner.run`, sessions | `OsmosisAgent`, `OsmosisMemorySession`, `OsmosisRolloutModel` |

## Decision Guidance

### When to Use Strands vs OpenAI Agents

| Condition | Use Strands | Use OpenAI Agents |
| --- | --- | --- |
| Already using Strands tools | ✓ | — |
| Need OpenAI Agents SDK features (handoffs, sessions) | — | ✓ |
| Migrating from existing Strands `Agent` | ✓ | — |
| Starting fresh, no framework preference | ✓ | ✓ |

### When to Evaluate vs Train

| Scenario | Action |
| --- | --- |
| First time running rollout code | Submit evaluation run first with small `limit` |
| Testing workflow/grader changes | Submit evaluation run to catch errors before GPU time |
| Rollout code is stable, ready to optimize | Submit training run |
| Comparing model performance | Submit evaluation run with `limit` = full dataset size |

### Grader Strategy Selection

| Task Type | Grader Strategy |
| --- | --- |
| Exact answer matching (math, code) | Exact match against `ctx.label` |
| Subjective quality (writing, reasoning) | LLM-as-judge with `litellm.acompletion()` |
| Tool use verification | Check for `toolUse` blocks in messages |
| Multi-criteria scoring | Combine strategies, weight and sum rewards |

## Workflow

### Typical Task: Build and Train a Rollout

1. **Understand the project**
   - Read workspace structure with `osmosis doctor`
   - Check available datasets with `osmosis dataset list`
   - Review AGENTS.md or CLAUDE.md for workspace conventions

2. **Create rollout scaffold**
   - Run `osmosis rollout init my-rollout` or apply a template with `osmosis template apply multiply-local-strands`
   - This creates `rollouts/my-rollout/main.py`, `configs/eval/my-rollout.toml`, `configs/training/my-rollout.toml`

3. **Implement AgentWorkflow**
   - Subclass `AgentWorkflow` in `rollouts/my-rollout/main.py`
   - Implement `async def run(ctx: AgentWorkflowContext) -> None`
   - Use `OsmosisStrandsAgent` or `OsmosisAgent` to route model calls through the rollout context
   - Return `None` (integration registers sample) or `AgentWorkflowOutput(messages=...)`

4. **Implement Grader**
   - Subclass `Grader` in the same file
   - Implement `async def grade(ctx: GraderContext) -> None`
   - Extract answer from `ctx.sample.messages[-1]`
   - Compare against `ctx.label` or call LLM judge
   - Call `ctx.set_reward(float)` once per sample

5. **Upload dataset**
   - Place dataset in `data/` directory
   - Run `osmosis dataset upload data/my-dataset.jsonl`
   - Reference dataset name in eval and training configs

6. **Register secrets**
   - Run `osmosis secret set OPENAI_API_KEY` (or other API keys)
   - List secret names in `[secrets].required` in TOML configs

7. **Push and submit evaluation run**
   - Commit rollout code: `git add rollouts/ configs/`
   - Push to repository: `git push`
   - Submit evaluation: `osmosis eval submit configs/eval/my-rollout.toml`
   - Monitor with `osmosis eval list` and `osmosis eval info <run-name>`

8. **Inspect and iterate**
   - Download results: `osmosis eval download <run-name>`
   - Check metrics, trajectories, and logs
   - Fix workflow or grader issues
   - Re-push and re-submit evaluation run

9. **Submit training run**
   - Once evaluation results look healthy, run `osmosis train submit configs/training/my-rollout.toml`
   - Monitor with `osmosis train info <run-name>`

10. **Deploy model**
    - List trained models: `osmosis model list --type lora`
    - Deploy with `osmosis model deploy <lora-model-name>`

## Common Gotchas

- **Model routing requirement**: LLM calls inside `AgentWorkflow.run()` must use `OsmosisStrandsAgent` or `OsmosisAgent`, not direct provider SDK calls. Direct calls bypass the rollout context and break training.

- **Workflow must return a sample**: If `run()` returns `None`, the integration must have registered a sample source. Missing sample source causes grader to fail with "workflow produced no sample".

- **Grader requires sample**: Always check `if ctx.sample is not None` before calling `ctx.set_reward()`. Calling `set_reward()` on `None` raises `ValueError`.

- **Secrets are names, not values**: `[secrets].required` lists secret record names (e.g., `OPENAI_API_KEY`), not values. Register with `osmosis secret set` before submitting. Never put secret values in TOML files or command-line arguments.

- **Config values come from local TOML, code comes from Git**: When you submit a run, the platform clones the repository at the specified `branch` or `commit_sha`. Local config values (hyperparameters, dataset name) come from your TOML file, but rollout code comes from Git. Push before submitting.

- **Evaluation run requires `[secrets]` table**: Even if no secrets are needed, include `[secrets]` with `required = []` in eval configs. Training configs may omit `[secrets]`.

- **One workflow, one grader per entrypoint**: `osmosis train submit` auto-discovers exactly one concrete `AgentWorkflow` and one concrete `Grader` from the entrypoint module. Helper classes and configs are fine, but keep only the classes you want to run as concrete subclasses.

- **Artifacts directory may be None**: Always guard `ctx.artifacts_dir` writes with `if ctx.artifacts_dir:` before writing files. Unguarded writes raise and fail the workflow.

- **Dataset row structure**: Datasets should have `system_prompt`, `user_prompt`, and `ground_truth` columns. These are assembled into `ctx.prompt` (list of messages) and `ctx.label` (reference answer) for the grader.

- **Evaluation run sample size**: When `[evaluation].limit` is omitted, the platform evaluates a random 10% sample (at least one row). Set `limit` explicitly to evaluate a fixed number of rows.

- **Training requires base model path**: `model_path` in training config must be a supported base model (e.g., `Qwen/Qwen3.6-35B-A3B`), not an evaluation policy model like `openai/gpt-5-mini`.

## Verification Checklist

Before submitting a run, verify:

- [ ] Workspace structure is valid: `osmosis doctor` shows no errors
- [ ] Rollout entrypoint exists: `rollouts/<name>/main.py` contains exactly one `AgentWorkflow` and one `Grader`
- [ ] Workflow uses `OsmosisStrandsAgent` or `OsmosisAgent` for model calls, not direct SDK calls
- [ ] Grader calls `ctx.set_reward()` exactly once and checks `if ctx.sample is not None` first
- [ ] Dataset is uploaded: `osmosis dataset list` shows the dataset referenced in config
- [ ] Secrets are registered: `osmosis secret list` shows all names in `[secrets].required`
- [ ] Code is pushed: `git push` completes without errors
- [ ] Config file is valid: `osmosis eval submit --yes` (or `osmosis train submit --yes`) accepts the config
- [ ] Evaluation run passes: `osmosis eval info <run-name>` shows completed status with reasonable reward stats
- [ ] For training: evaluation run results look healthy before submitting training run

## Resources

- **Comprehensive page listing**: https://docs.osmosis.ai/llms.txt
- **Platform overview and workspace setup**: https://docs.osmosis.ai/platform/overview
- **Building AgentWorkflows**: https://docs.osmosis.ai/cli/rollout/agent-workflows
- **Building Graders**: https://docs.osmosis.ai/cli/rollout/graders
- **Configuration file reference**: https://docs.osmosis.ai/cli/config-files
- **CLI command reference**: https://docs.osmosis.ai/cli/command-reference

---

> For additional documentation and navigation, see: https://docs.osmosis.ai/llms.txt