Metadata-Version: 2.4
Name: freesolo-agent
Version: 0.1.7
Summary: Thin CLI for queuing Freesolo backend training jobs.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: freesolo>=0.2.6
Requires-Dist: httpx>=0.27.0

# Freesolo Agent CLI

Thin interactive command-line client for queuing Freesolo backend training jobs.

The public package does not contain the Codex/GitHub/training worker. It only:

- prompts for setup input
- verifies a Freesolo API key
- uploads a local dataset file or folder when one is provided
- enqueues `/api/training/jobs`
- polls `/api/training/jobs/{job_id}` until the backend worker finishes

The private worker implementation lives under `backend/src/training_agent`.

## Install

```bash
pip install freesolo-agent
```

This installs the `freesolo` command.

From this repo checkout:

```bash
cd agent
uv sync
uv run freesolo setup
```

## Setup

Run:

```bash
freesolo setup
```

or, from a checkout:

```bash
uv run freesolo setup
```

The CLI prompts for:

- Freesolo API key
- operation: `draft`, `edit`, `optimize`, `training`, or `poll`
- source repository URL for `draft`
- the stored organization job to continue for `edit`, `optimize`, and `training`
- optional branch, dataset file or folder path, and backend-worker environment variables for `draft`

For private repositories, install the Freesolo GitHub App when prompted:

```text
https://github.com/apps/freesolo-agent/installations/new
```

The CLI prints progress while the backend job is queued and running. When the
job finishes, it writes a compact JSON result containing `ok`, `result`, and
`jobId`.

## Operations

`draft` creates the initial Freesolo training contract from a source repo. It
returns a `targetRepoUrl` for the generated training repo.

`edit` revises a drafted or previously edited training contract. The CLI lists
eligible organization jobs by stage, repo, and prompt.

`optimize` generates and checks repo-level training files for a drafted or edited
job that has not already been optimized.

`training` runs the long training workflow after the selected optimize job.

`poll` lists recent organization jobs and watches the selected job until it
finishes. It does not enqueue new work.

## Environment

The CLI does not require environment variables.

- Interactive setup prompts for the Freesolo API key.
- The backend infers the Freesolo org from that API key.
- Dataset paths are uploaded before the backend job starts.
- Backend URL and job polling interval use CLI defaults.
- Private GitHub app credentials, Codex settings, Tinker dependencies, and
  training runtime configuration belong to the backend worker, not this CLI
  package.
