> ## 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.

> ## Agent Instructions
> Treat this site as the source of truth for public Osmosis behavior.
> Distinguish the web Platform, the open source Python SDK, and the CLI.
> Use documented commands, configuration fields, and public APIs exactly as written; do not infer internal endpoints or services.

# Osmosis Python SDK Installation

> Install the Osmosis Python SDK and the extras your rollout needs

The open source SDK and the `osmosis` CLI ship in the same [`osmosis-ai`](https://pypi.org/project/osmosis-ai/) Python package. The SDK requires Python 3.12 or later.

## Install the v0.3 Release Candidate

Pin the current v0.3 release-candidate line so your environment receives RC builds without crossing the next minor-version boundary:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
python -m pip install "osmosis-ai>=0.3.0rc1,<0.4"
```

Verify both the package and bundled CLI:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
python -c "import osmosis_ai; print(osmosis_ai.__version__)"
osmosis --version
```

<Note>
  The lower bound must include `0.3.0rc1`; a final-release lower bound such as `>=0.3` does not select pre-releases in a clean environment.
</Note>

## Optional Extras

Install only the features your project imports:

| Extra           | Adds                                                                             | Install command                                                    |
| --------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `server`        | FastAPI and Uvicorn for `create_rollout_server()`                                | `python -m pip install "osmosis-ai[server]>=0.3.0rc1,<0.4"`        |
| `strands`       | Strands Agents adapter and its LiteLLM runtime                                   | `python -m pip install "osmosis-ai[strands]>=0.3.0rc1,<0.4"`       |
| `openai-agents` | OpenAI Agents SDK adapter and its LiteLLM runtime                                | `python -m pip install "osmosis-ai[openai-agents]>=0.3.0rc1,<0.4"` |
| `harbor`        | Harbor execution backend; SkyPilot is supplied separately by the rollout runtime | `python -m pip install "osmosis-ai[harbor]>=0.3.0rc1,<0.4"`        |
| `rubric`        | LLM-as-judge rubric evaluation                                                   | `python -m pip install "osmosis-ai[rubric]>=0.3.0rc1,<0.4"`        |
| `parquet`       | Parquet dataset validation                                                       | `python -m pip install "osmosis-ai[parquet]>=0.3.0rc1,<0.4"`       |
| `full`          | All optional features above                                                      | `python -m pip install "osmosis-ai[full]>=0.3.0rc1,<0.4"`          |

Extras can be combined. A Strands rollout served over HTTP, for example, uses:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
python -m pip install "osmosis-ai[server,strands]>=0.3.0rc1,<0.4"
```

## Minimal SDK Example

This entrypoint explicitly wires a workflow and grader into `LocalBackend`, then exposes that backend as a rollout server:

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
import os

import uvicorn
from osmosis_ai.rollout import (
    AgentWorkflow,
    AgentWorkflowContext,
    AgentWorkflowOutput,
    Grader,
    GraderContext,
    LocalBackend,
)
from osmosis_ai.rollout.server import create_rollout_server


class EchoWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> AgentWorkflowOutput:
        return AgentWorkflowOutput(
            messages=[*ctx.prompt, {"role": "assistant", "content": "ready"}]
        )


class ReadyGrader(Grader):
    async def grade(self, ctx: GraderContext) -> None:
        if ctx.sample is None:
            raise ValueError("workflow produced no sample")
        ctx.set_reward(1.0)


def main() -> None:
    backend = LocalBackend(workflow=EchoWorkflow, grader=ReadyGrader)
    app = create_rollout_server(backend=backend)
    port = os.environ.get("_OSMOSIS_ROLLOUT_PORT")
    uvicorn.run(
        app,
        host="0.0.0.0" if port else "127.0.0.1",
        port=int(port or "8000"),
    )


if __name__ == "__main__":
    main()
```

Install the `server` extra, save the example as `main.py`, and run the entrypoint:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
python main.py
```

The Platform sets `_OSMOSIS_ROLLOUT_PORT` and the server then binds every interface in the managed container; local runs default to `127.0.0.1:8000`.

<Warning>
  The rollout server does not authenticate inbound callers. Keep it on loopback locally and expose it only through the Platform's managed environment.
</Warning>

This example demonstrates wiring, not a trainable policy call. For training, use the [Strands integration](/sdk/integrations/strands) or [OpenAI Agents integration](/sdk/integrations/openai-agents) so model requests route through the active rollout context.

## Platform Authentication and Upgrades

SDK-only local code does not need a Platform login. Commands that submit evaluations or training runs do; follow [CLI Installation & Authentication](/cli/installation) to run `osmosis auth login` or configure `OSMOSIS_TOKEN`.

If you are upgrading an existing v0.2 harness, read the [SDK v0.2 → v0.3 migration guide](/migration-guides/v0-3) before changing the dependency, especially if it constructs `HarborBackend`.

## Next Steps

<CardGroup cols={2}>
  <Card title="AgentWorkflow" icon="robot" href="/sdk/agent-workflow">
    Implement the behavior that produces one rollout sample.
  </Card>

  <Card title="Execution Backends" icon="server" href="/sdk/execution-backends">
    Wire your workflow and grader into Local or Harbor execution.
  </Card>
</CardGroup>