Metadata-Version: 2.4
Name: osmosis-ai
Version: 0.2.26
Summary: A Python SDK and CLI for building agent rollouts and managing LLM post-training workflows on Osmosis.
Author-email: Osmosis AI <jake@osmosis.ai>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Osmosis-AI/osmosis-sdk-python
Project-URL: Issues, https://github.com/Osmosis-AI/osmosis-sdk-python/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv<2.0.0,>=0.1.0
Requires-Dist: requests<3.0.0,>=2.0.0
Requires-Dist: litellm<2.0.0,>=1.83.0
Requires-Dist: tqdm<5.0.0,>=4.0.0
Requires-Dist: httpx<1.0.0,>=0.25.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: strands-agents[litellm]>=1.29.0
Requires-Dist: openai-agents[litellm]<0.15,>=0.14
Requires-Dist: keyring>=25.0.0
Requires-Dist: questionary<3.0.0,>=2.1.0
Requires-Dist: typer<0.26,>=0.16.0
Requires-Dist: rich>=14.2.0
Requires-Dist: harbor[daytona]==0.6.1
Provides-Extra: platform
Requires-Dist: pyarrow>=14.0.0; extra == "platform"
Provides-Extra: server
Requires-Dist: osmosis-ai[platform]; extra == "server"
Requires-Dist: fastapi<1.0.0,>=0.100.0; extra == "server"
Requires-Dist: uvicorn<1.0.0,>=0.23.0; extra == "server"
Provides-Extra: dev
Requires-Dist: osmosis-ai[server]; extra == "dev"
Requires-Dist: pytest<10.0.0,>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio<2.0.0,>=1.4.0; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: ruff==0.15.15; extra == "dev"
Requires-Dist: pre-commit<5.0.0,>=4.6.0; extra == "dev"
Requires-Dist: pyright[nodejs]==1.1.410; extra == "dev"
Requires-Dist: types-requests>=2.0; extra == "dev"
Provides-Extra: full
Requires-Dist: osmosis-ai[server]; extra == "full"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Osmosis-AI/osmosis-sdk-python/main/.github/osmosis-logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Osmosis-AI/osmosis-sdk-python/main/.github/osmosis-logo-light.svg">
    <img alt="Osmosis" src="https://raw.githubusercontent.com/Osmosis-AI/osmosis-sdk-python/main/.github/osmosis-logo-light.svg" width="218">
  </picture>
</p>

<p align="center">
  <a href="https://pypi.org/project/osmosis-ai/"><img alt="Platform" src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS-blue"></a>
  <a href="https://pypi.org/project/osmosis-ai/"><img alt="PyPI" src="https://img.shields.io/pypi/v/osmosis-ai?color=yellow"></a>
  <a href="https://pypi.org/project/osmosis-ai/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/osmosis-ai"></a>
  <a href="https://codecov.io/gh/Osmosis-AI/osmosis-sdk-python"><img alt="Codecov" src="https://codecov.io/gh/Osmosis-AI/osmosis-sdk-python/branch/main/graph/badge.svg"></a>
  <a href="https://opensource.org/licenses/MIT"><img alt="License" src="https://img.shields.io/badge/License-MIT-orange.svg"></a>
  <a href="https://docs.osmosis.ai"><img alt="Docs" src="https://img.shields.io/badge/docs-docs.osmosis.ai-green"></a>
</p>

# osmosis-ai

> ⚠️ **Warning**: osmosis-ai is still in active development. APIs may change between versions.

Python SDK and CLI for [Osmosis AI](https://platform.osmosis.ai), a platform for training LLMs with reinforcement learning. Implement an **AgentWorkflow** in Python, add a concrete **Grader** for evaluation runs and managed training runs, submit evaluation runs with the CLI, then submit training runs from an Osmosis workspace directory.

## Quick start

| Step | What you do |
|------|-------------|
| **Define agents** | One `AgentWorkflow` subclass (+ optional `AgentWorkflowConfig`) in your repo. The training/evaluation entrypoint must also expose a concrete `Grader` (typically with a `GraderConfig`). |
| **Layout** | Use a rollout pack directory under `rollouts/<name>/` when loading by rollout name; the CLI adds that directory to `sys.path`. |
| **Workspace directory** | Create or open a workspace in the Osmosis Platform, then clone the repository created there. |
| **Check workspace** | `osmosis doctor` — run from the workspace directory so platform commands resolve the repository from the `origin` remote. Add `--fix` to restore missing scaffold paths. |
| **Evaluate** | `osmosis eval submit configs/eval/<name>.toml` — submit an evaluation run using the same platform dataset naming as training runs. |

**Example repository:** [osmosis-remote-rollout-example](https://github.com/Osmosis-AI/osmosis-remote-rollout-example) (reference server usage - align with current SDK exports when upgrading).

**Documentation index:** [docs/README.md](docs/README.md)

## Agent-friendly CLI output

The `osmosis` CLI keeps Rich as the default output for humans, but every public command also speaks structured JSON and low-noise plain text for AI agents, CI/CD, and shell automation. The global output flags work at any position on the command line:

```bash
osmosis dataset list                         # human-friendly Rich table
osmosis --json dataset list                  # recommended for AI agents and CI/CD
osmosis dataset list --json                  # postfix placement works too
osmosis --plain dataset list                 # low-noise text for shell pipelines
```

JSON is the stable machine contract: every successful response includes `schema_version: 1`; list envelopes include `items`, `total_count`, `has_more`, and `next_offset`; detail envelopes include `data`; operation envelopes include `status`, `operation`, optional `resource`, and optional `next_steps_structured`. Sectioned list envelopes (e.g. `osmosis model list`) compose the list shape under named section keys such as `base_models` and `lora_models`, each section carrying its own `items`, `total_count`, `has_more`, and `next_offset`. Errors are JSON-structured on stderr with `code`, `message`, `details`, optional `request_id`, plus the command path and SDK `cli_version`.

Plain mode is for humans and simple shell pipelines, not a strict schema. `--json` and `--plain` are global flags accepted anywhere in the command line; prefer `osmosis --json <command>` or `osmosis <command> --json` over the default Rich output in non-interactive environments. Command-local `--output` always means a file path, not a format selector, so `osmosis dataset download my-dataset --output ./data.jsonl` works in every mode.

In JSON or plain mode, interactive commands fail fast with `INTERACTIVE_REQUIRED` unless a non-interactive flow exists, typically by passing `--yes` or `--token`. `OSMOSIS_TOKEN` is verify-only across the CLI: it activates authentication for the current process but is never written to the on-disk credentials store, never revoked, and never deletes existing credentials.

## Workspace Directory Flow

Create or open a workspace in the Osmosis Platform, clone the repository created there,
then run CLI commands from that workspace directory.

```bash
git clone <repo-url>
cd <repo>
osmosis auth login
osmosis doctor
osmosis template apply multiply              # or add your rollout under rollouts/
cp configs/training/default.toml configs/training/<run>.toml
$EDITOR configs/training/<run>.toml          # set rollout, dataset, and model_path
git add rollouts configs data
git commit -m "configure training run"
git push
osmosis train submit configs/training/<run>.toml
```

Platform-scoped commands derive scope from the workspace directory's `origin` remote and
send `X-Osmosis-Git: namespace/repo_name`. The CLI does not store or send a
workspace ID for commands scoped by the workspace directory.

Before submitting training runs from CI, push the repository and authenticate with a
token:

```bash
export OSMOSIS_TOKEN=<token>
osmosis train submit configs/training/<run>.toml --yes
```

## Installation

Requires **Python 3.12+**. For development setup, see [CONTRIBUTING.md](CONTRIBUTING.md).

- **An LLM API key** (e.g., OpenAI, Anthropic, Groq) — required for `osmosis eval rubric` (LLM-as-judge) when using hosted models. See [supported providers](https://docs.litellm.ai/docs/providers).
- **Osmosis account** (optional) — needed for `osmosis auth login` and platform-backed commands such as datasets, models, and training runs. Sign up at [platform.osmosis.ai](https://platform.osmosis.ai).

**pip**

```bash
pip install osmosis-ai            # Core SDK
pip install osmosis-ai[server]    # + FastAPI rollout server (pulls in platform extra)
pip install osmosis-ai[full]      # Same as [server] (all packaged optional features)
```

**uv**

```bash
uv add osmosis-ai                 # Core SDK
uv add osmosis-ai[server]         # + FastAPI rollout server (pulls in platform extra)
uv add osmosis-ai[full]           # Same as [server] (all packaged optional features)
```

## Testing and evaluation

- [Eval](docs/eval.md) — evaluation run configs and `osmosis eval submit`
- [CLI reference](docs/cli.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, linting, and PR guidelines.

## License

MIT License - see [LICENSE](LICENSE) file for details.
