Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.osmosis.ai/llms.txt

Use this file to discover all available pages before exploring further.

When you run osmosis init my-project, the following directory structure is created: 
my-project/
├── .osmosis/
│   ├── workspace.toml                   # Workspace metadata
│   └── skills/
│       ├── create-rollout/SKILL.md      # AI assistant skill
│       ├── evaluate-rollout/SKILL.md    # AI assistant skill
│       └── submit-training/SKILL.md     # AI assistant skill
├── rollouts/                            # AgentWorkflow + Grader code
├── configs/
│   ├── eval/                            # Eval configs
│   ├── AGENTS.md                        # AI assistant instructions for configs
│   └── training/
│       └── default.toml                 # Training config template
├── data/                                # Local test datasets
├── pyproject.toml                       # Python project config
├── README.md                            # Project readme
├── AGENTS.md                            # AI coding assistant instructions
├── CLAUDE.md                            # Claude Code instructions
└── .gitignore                           # Git ignore rules

​
.osmosis/workspace.toml

Workspace metadata file that tracks how and when the workspace was created. This file is auto-generated and should not be edited manually.
.osmosis/workspace.toml
# Osmosis Workspace Configuration
# Generated by `osmosis init`

[workspace]
sdk_version = "0.20.0"
created_at = "2026-04-14T12:00:00+00:00"
setup_source = "osmosis init"
FieldDescription
sdk_versionVersion of osmosis-ai used to create or last update the workspace
created_atISO 8601 timestamp of initial workspace creation
updated_atISO 8601 timestamp of last update (added after first update)
setup_sourceAlways "osmosis init"

​
.osmosis/skills/

AI coding assistant skill files for Claude Code, GitHub Copilot, and other AI-powered editors. These provide context-aware instructions so your AI assistant understands the Osmosis workspace structure and can help you create rollouts, run evaluations, and submit training runs. Skills are automatically kept up-to-date when you run osmosis init on an existing workspace (see Update Mode below).

​
rollouts/

The directory where your AgentWorkflow and Grader code lives. Each rollout is a subdirectory containing an entrypoint file (typically main.py) that defines the agent workflow and grading logic. 
rollouts/
└── my-rollout/
    ├── main.py          # Entrypoint: defines AgentWorkflow + Grader
    ├── tools.py         # Tool definitions
    └── prompts.py       # System prompts
See Building AgentWorkflows for how to write your AgentWorkflow entrypoint.

​
configs/

Configuration files for the two CLI operations: training and eval.
SubdirectoryPurposeReference
configs/training/Training run configs for osmosis train submitTraining Config
configs/eval/Eval configs for osmosis eval runEval Config
The configs/training/default.toml template is pre-populated with the required fields and commented-out optional settings. See Configuration Files for the full TOML schema reference.

​
data/

Directory for local test datasets used during evaluation. Place JSONL, CSV, or Parquet files here and reference them from your eval configs. 
# Example: run eval against a local dataset
osmosis eval run configs/eval/default.toml

​
pyproject.toml

Standard Python project configuration with the osmosis-ai dependency pre-configured:
pyproject.toml
[project]
name = "my-project"
description = "Osmosis workspace with training rollouts"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "osmosis-ai>=0.20.0",
]

​
AGENTS.md & CLAUDE.md

Instruction files for AI coding assistants. AGENTS.md provides general guidance for any AI assistant (GitHub Copilot, Cursor, etc.), while CLAUDE.md contains Claude Code-specific instructions. Both files describe the workspace structure, conventions, and Osmosis-specific patterns so your AI assistant can effectively help you write rollout code.

​
Update Mode

Running osmosis init my-project on an existing workspace (detected by the presence of .osmosis/workspace.toml) enters update mode instead of failing:
  • Overwrites: AGENTS.md, CLAUDE.md, configs/AGENTS.md, and all files under .osmosis/skills/
  • Updates: workspace.toml metadata (sdk_version, updated_at timestamp)
  • Leaves untouched: rollout code, configs, data, pyproject.toml, .gitignore, and everything else
This lets you upgrade to the latest AI assistant instructions and skills after updating the osmosis-ai package, without affecting your existing code.
# Upgrade the SDK, then update workspace scaffolding
pip install --upgrade osmosis-ai
osmosis init my-project