Metadata-Version: 2.5
Name: tokin
Version: 0.1.0
Summary: Make any agent harness token-native.
Project-URL: Homepage, https://github.com/open-rollout/tokin
Project-URL: Repository, https://github.com/open-rollout/tokin
Project-URL: Issues, https://github.com/open-rollout/tokin/issues
Author-email: Yuan He <yuanhe.cs.ai@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx2>=2.7
Requires-Dist: jinja2>=3.1
Requires-Dist: numpy>=2
Requires-Dist: openai>=2
Requires-Dist: pydantic>=2
Requires-Dist: safetensors>=0.4
Requires-Dist: transformers>=5.6
Requires-Dist: uvicorn>=0.30
Provides-Extra: harbor
Requires-Dist: e2b>=2.25; extra == 'harbor'
Requires-Dist: harbor[e2b]<0.25,>=0.24; extra == 'harbor'
Requires-Dist: uv>=0.9; extra == 'harbor'
Description-Content-Type: text/markdown

<h1 align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/header-dark.svg">
    <img src="assets/header-light.svg" alt="tokin. Make any agent harness token-native." width="480">
  </picture>
</h1>

<p align="center">
  <a href="https://github.com/open-rollout/tokin/actions/workflows/ci.yml"><img src="https://github.com/open-rollout/tokin/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
  <a href="https://pypi.org/project/tokin/"><img src="https://img.shields.io/pypi/v/tokin" alt="PyPI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/open-rollout/tokin" alt="License"></a>
</p>

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/gateway-dark.svg">
    <img src="assets/gateway-light.svg" alt="tokin as a gateway. Harnesses, any harness, each call their own session URL with chat completions in text. Inside tokin each turn is attached to its place in its session's tree; rendered, keeping the ids the model sampled for rollouts, rollout and s, where re-encoding the text would split it as roll and outs; generated on the inference engine from input tokens to output tokens; and parsed back into an assistant message, {&quot;role&quot;: &quot;assistant&quot;, …}, with reasoning and tool calls for its harness. The turn's ids grow the session's tree at that place, each leaf a rollout with token_ids, loss_mask and logprobs, which a trainer collects to update the weights the engine serves." width="100%">
  </picture>
</p>

**tokin** makes any agent harness token-native. Train an agent in the harness it ships with, on exactly the tokens
it sampled. Point the harness at tokin instead of the inference engine and nothing else changes: it keeps speaking
text over chat completions, while the engine only ever sees token ids. tokin keeps each session as a tree of turns, so
every rollout a trainer collects is token-in, token-out at every prefix.

## Quick start

Serve a model with sglang, and put tokin in front of it, each in its own terminal:

```bash
pip install tokin
python -m sglang.launch_server --model-path Qwen/Qwen3.5-0.8B --port 30000
tokin serve --model-path Qwen/Qwen3.5-0.8B --engine-url http://localhost:30000
```

Open a session for each sample. It prints the base URL the harness takes:

```bash
URL=$(tokin open --params '{"return_logprobs": true}')
```

For [pi](https://pi.dev), add that URL as a provider in `~/.pi/agent/models.json`, then run
pi as usual:

```json
{
  "providers": {
    "tokin": {
      "baseUrl": "<URL>",
      "api": "openai-completions",
      "apiKey": "tokin",
      "models": [{ "id": "Qwen/Qwen3.5-0.8B" }]
    }
  }
}
```

```bash
pi --provider tokin --model Qwen/Qwen3.5-0.8B "Write a haiku about tokens to haiku.txt."
```

Collect the session, one JSON line per rollout with its `token_ids`, `loss_mask` and
`logprobs`:

```bash
tokin collect "$URL" -o rollouts.jsonl
```

## Examples

- [`examples/harbor_eval`](examples/harbor_eval): evaluate mini-swe-agent, opencode or pi through tokin on [Harbor](https://github.com/harbor-framework/harbor).
- [`examples/pi_mimo_rl`](examples/pi_mimo_rl): train pi with slime on MiMo-V2.6-RL-oss.
