Metadata-Version: 2.4
Name: freesolo
Version: 0.4.0
Summary: Environment and dataset helpers for Freesolo-generated repos.
Requires-Python: >=3.10
Requires-Dist: openai>=1.0.0
Requires-Dist: typing-extensions>=4.8.0
Provides-Extra: bson
Requires-Dist: pymongo>=4.0.0; extra == 'bson'
Provides-Extra: dev
Requires-Dist: gepa>=0.1.1; (python_version >= '3.10') and extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: jsonschema>=4.0.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pymongo>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
Requires-Dist: ruff>=0.11.0; extra == 'dev'
Requires-Dist: wandb>=0.17.0; (python_version >= '3.10') and extra == 'dev'
Provides-Extra: examples
Requires-Dist: openai>=1.0.0; extra == 'examples'
Provides-Extra: full
Requires-Dist: gepa>=0.1.1; (python_version >= '3.10') and extra == 'full'
Requires-Dist: httpx>=0.27.0; extra == 'full'
Requires-Dist: jsonschema>=4.0.0; extra == 'full'
Requires-Dist: pymongo>=4.0.0; extra == 'full'
Requires-Dist: python-dotenv>=1.0.0; extra == 'full'
Requires-Dist: wandb>=0.17.0; (python_version >= '3.10') and extra == 'full'
Provides-Extra: gepa
Requires-Dist: gepa>=0.1.1; (python_version >= '3.10') and extra == 'gepa'
Requires-Dist: wandb>=0.17.0; (python_version >= '3.10') and extra == 'gepa'
Description-Content-Type: text/markdown

# freesolo

`freesolo` is the published Python SDK for Freesolo's recording OpenAI
drop-in client and the environment and dataset contracts used by generated
repositories.

The public SDK surface includes:

- `freesolo.OpenAI` and `freesolo.AsyncOpenAI`
- `freesolo.environments`
- `freesolo.datasets`

## Install

```bash
pip install freesolo
```

From source:

```bash
cd freesolo-sdk
export PYTHONPATH="$PWD/pypi"
```

## OpenAI Drop-in Client

Use `OpenAI` or `AsyncOpenAI` anywhere you would use the official Python
client. A Freesolo API key is required through `FREESOLO_API_KEY` or the client
options. Requests go through the Freesolo recording proxy and chat completions
are recorded by default.

```python
from freesolo import AsyncOpenAI, OpenAI

client = OpenAI()
async_client = AsyncOpenAI()

completion = client.chat.completions.create(
    model="openai/gpt-5.2",
    messages=[{"role": "user", "content": "hello"}],
    extra_body={"metadata": {"dataset": "support"}},
)
```

Set `model` to a deployed Freesolo model id to call that fine-tuned model with
the same API. Recording controls use the official `extra_body` escape hatch, so
the native OpenAI method signatures and return types remain unchanged.

```python
completion = client.chat.completions.create(
    model="adapter-123",
    messages=[{"role": "user", "content": "hello"}],
    extra_body={"store": False},
)
```

## Dataset Contract

Dataset records use `input` and optional `output`.

```json
{ "id": "example-1", "input": "Say yes.", "output": "yes" }
```

The SDK does not accept aliases such as `prompt`, `query`, `task`,
`ground_truth`, `expected_output`, or `completion`.

## Environment Contract

Environments are Python modules that expose `load_environment()` and return an
`EnvironmentSingleTurn` or `EnvironmentMultiTurn` instance. Environment code
uses `TaskExample.input` and `TaskExample.output` when building prompts and
scoring responses.

Single-turn environments build their initial episode through `start_episode()`.
The SDK prepends the supplied contract text as a `system` message when the
environment did not already provide one, so SFT rows and environment scoring see
the same policy prompt. Multi-turn environments own their `start_episode()`
implementation and should include any task-specific initial system message
there.

The SDK does not handle remote artifact publishing or resolution.

## Example

```python
from freesolo.datasets import load_dataset
from freesolo.environments import load_environment

dataset = load_dataset("support.jsonl")
environment = load_environment("freesolo/environment.py:load_environment")

print(len(dataset.examples))
print(type(environment).__name__)
```

## API Guidance

Use `freesolo.datasets` for task examples and `freesolo.environments` for environment
loading/scoring interfaces.

- No command-line help surface is published as part of the SDK contract.
- Hidden modules remain available in source history for internal tooling only.
