freesolo-agent 0.1.0__tar.gz

freesolo_agent-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: freesolo-agent
+Version: 0.1.0
+Summary: Thin CLI for queuing Freesolo backend training jobs.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: freesolo>=0.2.4
+Requires-Dist: httpx>=0.27.0
+
+# Freesolo Agent CLI
+
+Thin command-line client for queuing Freesolo backend training jobs.
+
+The public package does not contain the Codex/GitHub/training worker. It only:
+
+- validates JSON or interactive setup input
+- verifies `FREESOLO_API_KEY`
+- uploads a local dataset file or folder when `datasetPath` 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`.
+
+## Run
+
+Interactive setup starts when the CLI is launched from a terminal without JSON
+input:
+
+```bash
+uv run freesolo
+```
+
+Automation can call the JSON interface:
+
+```bash
+uv run freesolo '{"operation":"draft","orgId":"org_123","input":{"sourceRepoUrl":"https://github.com/acme/app.git","prompt":"Create a contract for the feature behavior..."}}'
+```
+
+Supported operations are `draft`, `edit`, `optimize`, and `training`.
+
+To provide a local dataset, pass `datasetPath` as either a file or folder path.
+The CLI uploads it to the backend first, then the backend worker materializes it
+as read-only context for the training agent:
+
+```bash
+uv run freesolo '{"operation":"training","orgId":"org_123","input":{"targetRepoUrl":"https://github.com/acme/app-freesolo-training","datasetPath":"/mnt/data/my_dataset"}}'
+```
+
+## Environment
+
+- `FREESOLO_API_KEY`: required.
+- `FREESOLO_BASE_URL`: optional backend URL override. Defaults to production.
+- `FREESOLO_TRAINING_JOB_POLL_INTERVAL_SECONDS`: optional polling interval.
+
+Private GitHub app credentials, Codex settings, Tinker dependencies, and training
+runtime configuration belong to the backend worker, not this CLI package.

freesolo_agent-0.1.0/README.md

@@ -0,0 +1,47 @@
+# Freesolo Agent CLI
+
+Thin command-line client for queuing Freesolo backend training jobs.
+
+The public package does not contain the Codex/GitHub/training worker. It only:
+
+- validates JSON or interactive setup input
+- verifies `FREESOLO_API_KEY`
+- uploads a local dataset file or folder when `datasetPath` 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`.
+
+## Run
+
+Interactive setup starts when the CLI is launched from a terminal without JSON
+input:
+
+```bash
+uv run freesolo
+```
+
+Automation can call the JSON interface:
+
+```bash
+uv run freesolo '{"operation":"draft","orgId":"org_123","input":{"sourceRepoUrl":"https://github.com/acme/app.git","prompt":"Create a contract for the feature behavior..."}}'
+```
+
+Supported operations are `draft`, `edit`, `optimize`, and `training`.
+
+To provide a local dataset, pass `datasetPath` as either a file or folder path.
+The CLI uploads it to the backend first, then the backend worker materializes it
+as read-only context for the training agent:
+
+```bash
+uv run freesolo '{"operation":"training","orgId":"org_123","input":{"targetRepoUrl":"https://github.com/acme/app-freesolo-training","datasetPath":"/mnt/data/my_dataset"}}'
+```
+
+## Environment
+
+- `FREESOLO_API_KEY`: required.
+- `FREESOLO_BASE_URL`: optional backend URL override. Defaults to production.
+- `FREESOLO_TRAINING_JOB_POLL_INTERVAL_SECONDS`: optional polling interval.
+
+Private GitHub app credentials, Codex settings, Tinker dependencies, and training
+runtime configuration belong to the backend worker, not this CLI package.

freesolo_agent-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "freesolo-agent"
+version = "0.1.0"
+description = "Thin CLI for queuing Freesolo backend training jobs."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "freesolo>=0.2.4",
+  "httpx>=0.27.0",
+]
+
+[project.scripts]
+freesolo = "commands.main:main"
+
+[tool.setuptools]
+py-modules = ["config"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_ignores = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.uv.sources]
+freesolo = { path = "../../freesolo-sdk", editable = true }

freesolo_agent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

freesolo_agent-0.1.0/src/client/__init__.py

@@ -0,0 +1 @@
+"""Backend API clients used by the public CLI."""

freesolo_agent-0.1.0/src/client/auth.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import os
+
+import httpx
+from freesolo.utils.storage import FreesoloStorageClient
+
+
+def require_freesolo_api_key() -> None:
+    value = os.getenv("FREESOLO_API_KEY")
+    if not value or not value.strip():
+        raise ValueError("FREESOLO_API_KEY is required to run the Freesolo Agent CLI")
+
+
+def verify_freesolo_api_key() -> None:
+    try:
+        FreesoloStorageClient().verify_api_key()
+    except httpx.HTTPStatusError as error:
+        if error.response.status_code in {401, 403}:
+            raise ValueError(
+                "FREESOLO_API_KEY was rejected by Freesolo. Create a new API key "
+                "in the Freesolo app for the org that should own this run."
+            ) from error
+        raise

freesolo_agent-0.1.0/src/client/datasets.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+from freesolo.utils.storage import FreesoloStorageClient
+
+from core.types import TrainingInputPayload
+
+
+def dataset_path_from_input(bot_input: TrainingInputPayload) -> str | None:
+    return bot_input.dataset_path
+
+
+def sync_dataset_if_present(bot_input: TrainingInputPayload) -> str | None:
+    dataset_path = dataset_path_from_input(bot_input)
+    if dataset_path is None:
+        return None
+    try:
+        return FreesoloStorageClient().upload_dataset(dataset_path, name=Path(dataset_path).name)
+    except httpx.HTTPStatusError as error:
+        if error.response.status_code in {401, 403}:
+            raise ValueError(
+                "Freesolo API key was rejected while uploading the dataset. Use an active "
+                "key for the org that should own datasets and training runs."
+            ) from error
+        raise

freesolo_agent-0.1.0/src/client/jobs.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from collections.abc import Mapping
+from typing import Any, cast
+
+import httpx
+from freesolo.utils.storage import FreesoloStorageClient
+
+from config import (
+    DEFAULT_JOB_POLL_INTERVAL_SECONDS,
+    JOB_HEARTBEAT_SECONDS,
+    TRAINING_JOBS_PATH,
+)
+from core.output import print_human
+from core.types import (
+    DraftInput,
+    EditInput,
+    OptimizeInput,
+    TrainingInput,
+    TrainingInputPayload,
+)
+
+
+def job_poll_interval_seconds() -> float:
+    raw_value = os.getenv("FREESOLO_TRAINING_JOB_POLL_INTERVAL_SECONDS")
+    if raw_value is None or not raw_value.strip():
+        return DEFAULT_JOB_POLL_INTERVAL_SECONDS
+    try:
+        value = float(raw_value)
+    except ValueError as error:
+        raise ValueError("FREESOLO_TRAINING_JOB_POLL_INTERVAL_SECONDS must be a number") from error
+    if value <= 0:
+        raise ValueError("FREESOLO_TRAINING_JOB_POLL_INTERVAL_SECONDS must be positive")
+    return value
+
+
+def environment_variables_from_input(bot_input: TrainingInputPayload) -> dict[str, str]:
+    return dict(bot_input.environment_variables)
+
+
+def backend_training_payload(
+    operation: str,
+    org_id: str,
+    bot_input: TrainingInputPayload,
+    dataset_id: str | None = None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {"action": operation, "orgId": org_id}
+    if dataset_id is not None:
+        payload["datasetId"] = dataset_id
+
+    environment_variables = environment_variables_from_input(bot_input)
+    if environment_variables:
+        payload["environmentVariables"] = environment_variables
+
+    if operation == "draft":
+        draft_input = cast(DraftInput, bot_input)
+        payload.update(
+            {
+                "sourceRepoUrl": draft_input.source_repo_url,
+                "sourceBranch": draft_input.source_branch,
+                "prompt": draft_input.prompt,
+            }
+        )
+        return payload
+    if operation == "edit":
+        edit_input = cast(EditInput, bot_input)
+        payload.update(
+            {
+                "targetRepoUrl": edit_input.target_repo_url,
+                "targetBranch": edit_input.target_branch,
+                "targetWorktreePath": edit_input.target_worktree_path,
+                "prompt": edit_input.prompt,
+            }
+        )
+        return payload
+    if operation == "optimize":
+        optimize_input = cast(OptimizeInput, bot_input)
+        payload.update(
+            {
+                "targetRepoUrl": optimize_input.target_repo_url,
+                "targetBranch": optimize_input.target_branch,
+                "targetWorktreePath": optimize_input.target_worktree_path,
+            }
+        )
+        return payload
+
+    training_input = cast(TrainingInput, bot_input)
+    payload.update(
+        {
+            "targetRepoUrl": training_input.target_repo_url,
+            "targetBranch": training_input.target_branch,
+            "targetWorktreePath": training_input.target_worktree_path,
+        }
+    )
+    return payload
+
+
+def backend_headers(
+    storage_client: FreesoloStorageClient,
+    *,
+    track_usage: bool = False,
+) -> dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {storage_client.api_key}",
+        "Content-Type": "application/json",
+    }
+    if track_usage:
+        headers["X-Freesolo-Function"] = "freesolo_agent.run_backend_training_job"
+    return headers
+
+
+def backend_json_response(response: httpx.Response, path: str) -> dict[str, Any]:
+    try:
+        payload = response.json() if response.content else {}
+    except ValueError:
+        payload = {}
+    if response.is_error:
+        raise RuntimeError(backend_error_message(payload, f"Freesolo {path} failed"))
+    if not isinstance(payload, dict):
+        raise RuntimeError(f"Freesolo {path} returned a non-object response")
+    return payload
+
+
+def backend_error_message(payload: object, fallback: str) -> str:
+    if not isinstance(payload, dict):
+        return fallback
+    error = payload.get("error")
+    if isinstance(error, str) and error.strip():
+        return error
+    detail = payload.get("detail")
+    if isinstance(detail, str) and detail.strip():
+        return detail
+    return fallback
+
+
+def job_from_response(payload: dict[str, Any]) -> dict[str, Any]:
+    job = payload.get("job")
+    if not isinstance(job, dict):
+        raise RuntimeError("Freesolo training job response did not include a job object")
+    return dict(job)
+
+
+def job_id(job: Mapping[str, Any]) -> str:
+    value = job.get("jobId")
+    if not isinstance(value, str) or not value:
+        raise RuntimeError("Freesolo training job response missing jobId")
+    return value
+
+
+def job_status(job: Mapping[str, Any]) -> str:
+    value = job.get("status")
+    if not isinstance(value, str) or not value:
+        raise RuntimeError("Freesolo training job response missing status")
+    return value
+
+
+def job_result(job: Mapping[str, Any]) -> dict[str, Any]:
+    result = job.get("result")
+    if not isinstance(result, dict):
+        raise RuntimeError("Freesolo training job succeeded without a result object")
+    return dict(result)
+
+
+async def run_backend_training_job(
+    operation: str,
+    org_id: str,
+    bot_input: TrainingInputPayload,
+    dataset_id: str | None = None,
+) -> tuple[dict[str, Any], str]:
+    storage_client = FreesoloStorageClient()
+    enqueue_headers = backend_headers(storage_client, track_usage=True)
+    poll_headers = backend_headers(storage_client)
+    poll_interval_seconds = job_poll_interval_seconds()
+    payload = backend_training_payload(operation, org_id, bot_input, dataset_id=dataset_id)
+
+    async with httpx.AsyncClient(timeout=storage_client.timeout_seconds) as client:
+        enqueue_response = await client.post(
+            f"{storage_client.base_url}{TRAINING_JOBS_PATH}",
+            headers=enqueue_headers,
+            json=payload,
+        )
+        job = job_from_response(backend_json_response(enqueue_response, TRAINING_JOBS_PATH))
+        current_job_id = job_id(job)
+        print_human(f"Queued backend {operation} job {current_job_id}.")
+        return await poll_backend_training_job(
+            client=client,
+            base_url=storage_client.base_url,
+            headers=poll_headers,
+            job_id=current_job_id,
+            initial_job=job,
+            poll_interval_seconds=poll_interval_seconds,
+        )
+
+
+async def poll_backend_training_job(
+    *,
+    client: httpx.AsyncClient,
+    base_url: str,
+    headers: dict[str, str],
+    job_id: str,
+    initial_job: dict[str, Any],
+    poll_interval_seconds: float,
+) -> tuple[dict[str, Any], str]:
+    job = initial_job
+    last_status: str | None = None
+    last_heartbeat_at = 0.0
+    path = f"{TRAINING_JOBS_PATH}/{job_id}"
+    while True:
+        status = job_status(job)
+        now = time.monotonic()
+        if status != last_status:
+            print_human(f"Backend job {job_id} is {status}.")
+            last_status = status
+            last_heartbeat_at = now
+        elif now - last_heartbeat_at >= JOB_HEARTBEAT_SECONDS:
+            print_human(f"Backend job {job_id} is still {status}.")
+            last_heartbeat_at = now
+
+        if status == "succeeded":
+            return job_result(job), job_id
+        if status in {"failed", "cancelled"}:
+            error = job.get("error")
+            if not isinstance(error, str) or not error.strip():
+                error = f"Backend training job {job_id} {status}"
+            raise RuntimeError(error)
+
+        await asyncio.sleep(poll_interval_seconds)
+        poll_response = await client.get(f"{base_url}{path}", headers=headers)
+        job = job_from_response(backend_json_response(poll_response, path))

freesolo_agent-0.1.0/src/commands/__init__.py

@@ -0,0 +1 @@
+"""Console command entrypoints."""

freesolo_agent-0.1.0/src/commands/main.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import traceback
+from typing import cast
+
+from client.auth import require_freesolo_api_key, verify_freesolo_api_key
+from client.jobs import run_backend_training_job
+from config import HELP_COMMANDS, INTERACTIVE_COMMANDS
+from client.datasets import sync_dataset_if_present
+from commands.setup import run_interactive
+from core.output import print_human, write_json
+from core.types import JsonDict
+from core.validation import validate_request
+
+
+def load_dotenv_if_available() -> None:
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        return
+    load_dotenv()
+
+
+def read_input() -> str:
+    if len(sys.argv) > 1:
+        return sys.argv[1]
+    return sys.stdin.read()
+
+
+def usage() -> str:
+    return "\n".join(
+        [
+            "Usage:",
+            "  freesolo",
+            "  freesolo setup",
+            "  freesolo '<json request>'",
+            "",
+            "No-argument TTY usage starts interactive setup. JSON usage enqueues backend",
+            "draft, edit, optimize, and training jobs, then polls until completion.",
+            "Pass top-level orgId for backend jobs.",
+            "Pass input.datasetPath as a local dataset file or folder path when you want",
+            "the backend worker to use uploaded data as a read-only source.",
+            "Pass environmentVariables or input.environmentVariables as KEY/value pairs",
+            "to make ephemeral env vars available only during the backend worker run.",
+        ]
+    )
+
+
+async def run() -> int:
+    try:
+        load_dotenv_if_available()
+
+        if len(sys.argv) > 1 and sys.argv[1] in HELP_COMMANDS:
+            print(usage())
+            return 0
+
+        if (len(sys.argv) > 1 and sys.argv[1] in INTERACTIVE_COMMANDS) or (
+            len(sys.argv) == 1 and sys.stdin.isatty()
+        ):
+            return await run_interactive()
+
+        parsed_json = json.loads(read_input())
+        operation, bot_input, org_id = validate_request(parsed_json)
+        require_freesolo_api_key()
+        verify_freesolo_api_key()
+        dataset_id = sync_dataset_if_present(bot_input)
+        result_json, job_id = await run_backend_training_job(
+            operation,
+            org_id,
+            bot_input,
+            dataset_id=dataset_id,
+        )
+        if dataset_id:
+            result_json["datasetId"] = dataset_id
+        write_json(
+            sys.stdout,
+            cast(JsonDict, {"ok": True, "result": result_json, "jobId": job_id}),
+        )
+        return 0
+    except ValueError as error:
+        print_human(str(error))
+        write_json(sys.stderr, {"ok": False, "error": str(error)})
+        return 1
+    except Exception as error:
+        traceback.print_exc(file=sys.stderr)
+        write_json(sys.stderr, {"ok": False, "error": str(error)})
+        return 1
+
+
+def main() -> None:
+    raise SystemExit(asyncio.run(run()))

freesolo_agent-0.1.0/src/commands/setup.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import getpass
+import os
+import sys
+import webbrowser
+from typing import cast
+
+from client.auth import verify_freesolo_api_key
+from client.jobs import run_backend_training_job
+from config import GITHUB_APP_INSTALL_URL, MAX_ENVIRONMENT_VARIABLES
+from client.datasets import sync_dataset_if_present
+from core.output import print_human, write_json
+from core.types import DraftInput, JsonDict
+from core.validation import (
+    required_string,
+    validate_dataset_path,
+    validate_environment_variables,
+)
+
+
+def prompt_required_line(label: str, *, default: str | None = None) -> str:
+    default_suffix = f" [{default}]" if default else ""
+    while True:
+        print(f"{label}{default_suffix}: ", file=sys.stderr, end="", flush=True)
+        value = sys.stdin.readline()
+        if value == "":
+            raise EOFError(f"Missing input for {label}")
+        trimmed = value.strip()
+        if trimmed:
+            return trimmed
+        if default:
+            return default
+        print_human(f"{label} is required.")
+
+
+def prompt_optional_line(label: str) -> str | None:
+    print(f"{label} (optional, press Enter to skip): ", file=sys.stderr, end="", flush=True)
+    value = sys.stdin.readline()
+    if value == "":
+        return None
+    trimmed = value.strip()
+    return trimmed or None
+
+
+def prompt_optional_dataset_path() -> str | None:
+    while True:
+        try:
+            return validate_dataset_path(prompt_optional_line("Dataset file or folder path"))
+        except ValueError as error:
+            print_human(str(error))
+
+
+def prompt_environment_variables() -> dict[str, str]:
+    variables: dict[str, str] = {}
+    print_human("Environment variables for the backend training worker are optional.")
+    print_human("Enter variable names one at a time. Press Enter on the name prompt to finish.")
+    while True:
+        raw_name = prompt_optional_line("Environment variable name")
+        if raw_name is None:
+            return variables
+        name = raw_name.strip()
+        try:
+            validate_environment_variables({name: ""}, "environmentVariables")
+        except ValueError as error:
+            print_human(str(error))
+            continue
+        variables[name] = getpass.getpass(f"Value for {name}: ", stream=sys.stderr)
+        if len(variables) >= MAX_ENVIRONMENT_VARIABLES:
+            print_human(f"Reached the limit of {MAX_ENVIRONMENT_VARIABLES} variables.")
+            return variables
+
+
+def prompt_secret(label: str) -> str:
+    while True:
+        try:
+            value = getpass.getpass(f"{label}: ", stream=sys.stderr).strip()
+        except EOFError as error:
+            raise EOFError(f"Missing input for {label}") from error
+        if value:
+            return value
+        print_human(f"{label} is required.")
+
+
+def ensure_freesolo_api_key() -> None:
+    if os.getenv("FREESOLO_API_KEY"):
+        try:
+            verify_freesolo_api_key()
+            print_human("Using FREESOLO_API_KEY from environment.")
+            return
+        except ValueError as error:
+            print_human(str(error))
+            print_human("Enter a different Freesolo API key.")
+
+    while True:
+        os.environ["FREESOLO_API_KEY"] = prompt_secret("Freesolo API key")
+        try:
+            verify_freesolo_api_key()
+            print_human("Freesolo API key accepted.")
+            return
+        except ValueError as error:
+            print_human(str(error))
+
+
+def prompt_multiline_description() -> str:
+    while True:
+        print_human("Describe what you are trying to do.")
+        print_human("Finish with a blank line.")
+        lines: list[str] = []
+        while True:
+            line = sys.stdin.readline()
+            if line == "":
+                if not lines:
+                    raise EOFError("Missing prompt")
+                break
+            stripped = line.rstrip("\n")
+            if not stripped:
+                if lines:
+                    break
+                print_human("Prompt is required.")
+                continue
+            lines.append(stripped)
+
+        prompt = "\n".join(lines)
+        try:
+            return required_string(prompt, "prompt", 20, 8_000)
+        except ValueError as error:
+            print_human(str(error))
+
+
+def offer_github_app_install() -> None:
+    print_human("If the source repository is private, connect the Freesolo GitHub App:")
+    print_human(GITHUB_APP_INSTALL_URL)
+    opened = webbrowser.open(GITHUB_APP_INSTALL_URL, new=2)
+    if not opened:
+        print_human("Open the URL above in your browser.")
+    print(
+        "Press Enter once GitHub access is connected, or press Enter to continue for public repos: ",
+        file=sys.stderr,
+        end="",
+        flush=True,
+    )
+    sys.stdin.readline()
+
+
+async def run_interactive() -> int:
+    ensure_freesolo_api_key()
+    org_id = required_string(
+        prompt_required_line("Freesolo org ID"),
+        "orgId",
+        1,
+        100,
+    )
+
+    source_repo_url = required_string(
+        prompt_required_line("Source repository URL"),
+        "sourceRepoUrl",
+        1,
+        300,
+    )
+    offer_github_app_install()
+    prompt = prompt_multiline_description()
+    source_branch = prompt_optional_line("Source branch")
+    dataset_path = prompt_optional_dataset_path()
+    environment_variables = prompt_environment_variables()
+    input_data = DraftInput(
+        source_repo_url=source_repo_url,
+        source_branch=source_branch,
+        prompt=prompt,
+        dataset_path=dataset_path,
+        environment_variables=environment_variables,
+    )
+    print_human("Setup inputs collected. Queuing backend draft job.")
+    dataset_id = sync_dataset_if_present(input_data)
+    result_json, job_id = await run_backend_training_job(
+        "draft",
+        org_id,
+        input_data,
+        dataset_id=dataset_id,
+    )
+    if dataset_id:
+        result_json["datasetId"] = dataset_id
+    target_repo_url = result_json.get("targetRepoUrl")
+    if isinstance(target_repo_url, str) and target_repo_url:
+        print_human(f"Drafted training contract in {target_repo_url}")
+    write_json(
+        sys.stdout,
+        cast(JsonDict, {"ok": True, "result": result_json, "jobId": job_id}),
+    )
+    return 0

freesolo_agent-0.1.0/src/config.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import re
+
+HELP_COMMANDS = {"help", "-h", "--help"}
+INTERACTIVE_COMMANDS = {"setup"}
+
+TRAINING_JOBS_PATH = "/api/training/jobs"
+DEFAULT_JOB_POLL_INTERVAL_SECONDS = 5.0
+JOB_HEARTBEAT_SECONDS = 30.0
+
+GITHUB_APP_SLUG = "freesolo-agent"
+GITHUB_APP_INSTALL_URL = f"https://github.com/apps/{GITHUB_APP_SLUG}/installations/new"
+
+MAX_ENVIRONMENT_VARIABLES = 100
+MAX_ENVIRONMENT_VALUE_LENGTH = 100_000
+ENVIRONMENT_VARIABLE_NAME_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")

freesolo_agent-0.1.0/src/core/__init__.py

@@ -0,0 +1 @@
+"""Shared public CLI helpers."""

freesolo_agent-0.1.0/src/core/output.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import TextIO
+
+from core.types import JsonDict
+
+
+def print_human(message: str = "") -> None:
+    print(message, file=sys.stderr, flush=True)
+
+
+def write_json(stream: TextIO, payload: JsonDict) -> None:
+    stream.write(f"{json.dumps(payload, separators=(',', ':'))}\n")

freesolo_agent-0.1.0/src/core/types.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TypeAlias
+
+JsonValue: TypeAlias = str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
+JsonDict: TypeAlias = dict[str, JsonValue]
+
+
+@dataclass(frozen=True)
+class DraftInput:
+    source_repo_url: str
+    prompt: str
+    source_branch: str | None = None
+    dataset_path: str | None = None
+    environment_variables: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class EditInput:
+    target_repo_url: str
+    prompt: str
+    target_branch: str | None = None
+    target_worktree_path: str | None = None
+    dataset_path: str | None = None
+    environment_variables: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class OptimizeInput:
+    target_repo_url: str
+    target_branch: str | None = None
+    target_worktree_path: str | None = None
+    dataset_path: str | None = None
+    environment_variables: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class TrainingInput:
+    target_repo_url: str
+    target_branch: str | None = None
+    target_worktree_path: str | None = None
+    dataset_path: str | None = None
+    environment_variables: dict[str, str] = field(default_factory=dict)
+
+
+TrainingInputPayload: TypeAlias = DraftInput | EditInput | OptimizeInput | TrainingInput

freesolo_agent-0.1.0/src/core/validation.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+from config import (
+    ENVIRONMENT_VARIABLE_NAME_PATTERN,
+    MAX_ENVIRONMENT_VALUE_LENGTH,
+    MAX_ENVIRONMENT_VARIABLES,
+)
+from core.types import DraftInput, EditInput, OptimizeInput, TrainingInput
+
+
+def as_mapping(value: object) -> Mapping[str, object]:
+    if not isinstance(value, dict):
+        raise ValueError("Input must be a JSON object")
+    return value
+
+
+def optional_string(value: object, name: str, max_length: int) -> str | None:
+    if value is None or value == "":
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"{name} must be a string")
+    trimmed = value.strip()
+    if not trimmed:
+        return None
+    if len(trimmed) > max_length:
+        raise ValueError(f"{name} must be at most {max_length} characters")
+    return trimmed
+
+
+def required_string(value: object, name: str, min_length: int, max_length: int) -> str:
+    if not isinstance(value, str):
+        raise ValueError(f"{name} must be a string")
+    trimmed = value.strip()
+    if len(trimmed) < min_length:
+        raise ValueError(f"{name} must be at least {min_length} characters")
+    if len(trimmed) > max_length:
+        raise ValueError(f"{name} must be at most {max_length} characters")
+    return trimmed
+
+
+def validate_dataset_path(value: object) -> str | None:
+    raw_path = optional_string(value, "datasetPath", 2_000)
+    if raw_path is None:
+        return None
+
+    try:
+        resolved = Path(raw_path).expanduser().resolve(strict=True)
+    except OSError as error:
+        raise ValueError(f"datasetPath must exist: {raw_path}") from error
+    if not resolved.is_file() and not resolved.is_dir():
+        raise ValueError("datasetPath must be a file or folder")
+    return str(resolved)
+
+
+def validate_environment_variables(value: object, name: str) -> dict[str, str]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ValueError(f"{name} must be an object of environment variable names to values")
+    if len(value) > MAX_ENVIRONMENT_VARIABLES:
+        raise ValueError(f"{name} must include at most {MAX_ENVIRONMENT_VARIABLES} variables")
+
+    variables: dict[str, str] = {}
+    for raw_key, raw_value in value.items():
+        if not isinstance(raw_key, str):
+            raise ValueError(f"{name} keys must be strings")
+        key = raw_key.strip()
+        if not ENVIRONMENT_VARIABLE_NAME_PATTERN.fullmatch(key):
+            raise ValueError(f"{name} key {raw_key!r} must be a valid environment variable name")
+        if not isinstance(raw_value, str):
+            raise ValueError(f"{name}.{key} must be a string")
+        if len(raw_value) > MAX_ENVIRONMENT_VALUE_LENGTH:
+            raise ValueError(f"{name}.{key} is too large")
+        variables[key] = raw_value
+    return variables
+
+
+def merged_environment_variables(
+    request_environment_variables: dict[str, str],
+    input_payload: Mapping[str, object],
+) -> dict[str, str]:
+    variables = dict(request_environment_variables)
+    variables.update(
+        validate_environment_variables(
+            input_payload.get("environmentVariables"),
+            "input.environmentVariables",
+        )
+    )
+    return variables
+
+
+def validate_draft_input(
+    value: object,
+    request_environment_variables: dict[str, str] | None = None,
+) -> DraftInput:
+    payload = as_mapping(value)
+    return DraftInput(
+        source_repo_url=required_string(payload.get("sourceRepoUrl"), "sourceRepoUrl", 1, 300),
+        source_branch=optional_string(payload.get("sourceBranch"), "sourceBranch", 120),
+        prompt=required_string(payload.get("prompt"), "prompt", 20, 8_000),
+        dataset_path=validate_dataset_path(payload.get("datasetPath")),
+        environment_variables=merged_environment_variables(
+            request_environment_variables or {},
+            payload,
+        ),
+    )
+
+
+def validate_edit_input(
+    value: object,
+    request_environment_variables: dict[str, str] | None = None,
+) -> EditInput:
+    payload = as_mapping(value)
+    return EditInput(
+        target_repo_url=required_string(payload.get("targetRepoUrl"), "targetRepoUrl", 1, 300),
+        target_branch=optional_string(payload.get("targetBranch"), "targetBranch", 120),
+        target_worktree_path=optional_string(
+            payload.get("targetWorktreePath"),
+            "targetWorktreePath",
+            2_000,
+        ),
+        prompt=required_string(payload.get("prompt"), "prompt", 20, 8_000),
+        dataset_path=validate_dataset_path(payload.get("datasetPath")),
+        environment_variables=merged_environment_variables(
+            request_environment_variables or {},
+            payload,
+        ),
+    )
+
+
+def validate_optimize_input(
+    value: object,
+    request_environment_variables: dict[str, str] | None = None,
+) -> OptimizeInput:
+    payload = as_mapping(value)
+    return OptimizeInput(
+        target_repo_url=required_string(payload.get("targetRepoUrl"), "targetRepoUrl", 1, 300),
+        target_branch=optional_string(payload.get("targetBranch"), "targetBranch", 120),
+        target_worktree_path=optional_string(
+            payload.get("targetWorktreePath"),
+            "targetWorktreePath",
+            2_000,
+        ),
+        dataset_path=validate_dataset_path(payload.get("datasetPath")),
+        environment_variables=merged_environment_variables(
+            request_environment_variables or {},
+            payload,
+        ),
+    )
+
+
+def validate_training_input(
+    value: object,
+    request_environment_variables: dict[str, str] | None = None,
+) -> TrainingInput:
+    payload = as_mapping(value)
+    return TrainingInput(
+        target_repo_url=required_string(payload.get("targetRepoUrl"), "targetRepoUrl", 1, 300),
+        target_branch=optional_string(payload.get("targetBranch"), "targetBranch", 120),
+        target_worktree_path=optional_string(
+            payload.get("targetWorktreePath"),
+            "targetWorktreePath",
+            2_000,
+        ),
+        dataset_path=validate_dataset_path(payload.get("datasetPath")),
+        environment_variables=merged_environment_variables(
+            request_environment_variables or {},
+            payload,
+        ),
+    )
+
+
+def validate_request(
+    value: object,
+) -> tuple[str, DraftInput | EditInput | OptimizeInput | TrainingInput, str]:
+    payload = as_mapping(value)
+    org_id = request_org_id(payload)
+    if org_id is None:
+        raise ValueError(
+            "orgId is required for backend training jobs."
+        )
+
+    request_environment_variables = validate_environment_variables(
+        payload.get("environmentVariables"),
+        "environmentVariables",
+    )
+    operation = payload.get("operation")
+    if operation == "draft":
+        return (
+            operation,
+            validate_draft_input(payload.get("input"), request_environment_variables),
+            org_id,
+        )
+    if operation == "edit":
+        return (
+            operation,
+            validate_edit_input(payload.get("input"), request_environment_variables),
+            org_id,
+        )
+    if operation == "optimize":
+        return (
+            operation,
+            validate_optimize_input(payload.get("input"), request_environment_variables),
+            org_id,
+        )
+    if operation == "training":
+        return (
+            operation,
+            validate_training_input(payload.get("input"), request_environment_variables),
+            org_id,
+        )
+    raise ValueError("operation must be 'draft', 'edit', 'optimize', or 'training'")
+
+
+def request_org_id(payload: Mapping[str, object]) -> str | None:
+    return optional_string(payload.get("orgId"), "orgId", 100)

freesolo_agent-0.1.0/src/freesolo_agent.egg-info/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: freesolo-agent
+Version: 0.1.0
+Summary: Thin CLI for queuing Freesolo backend training jobs.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: freesolo>=0.2.4
+Requires-Dist: httpx>=0.27.0
+
+# Freesolo Agent CLI
+
+Thin command-line client for queuing Freesolo backend training jobs.
+
+The public package does not contain the Codex/GitHub/training worker. It only:
+
+- validates JSON or interactive setup input
+- verifies `FREESOLO_API_KEY`
+- uploads a local dataset file or folder when `datasetPath` 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`.
+
+## Run
+
+Interactive setup starts when the CLI is launched from a terminal without JSON
+input:
+
+```bash
+uv run freesolo
+```
+
+Automation can call the JSON interface:
+
+```bash
+uv run freesolo '{"operation":"draft","orgId":"org_123","input":{"sourceRepoUrl":"https://github.com/acme/app.git","prompt":"Create a contract for the feature behavior..."}}'
+```
+
+Supported operations are `draft`, `edit`, `optimize`, and `training`.
+
+To provide a local dataset, pass `datasetPath` as either a file or folder path.
+The CLI uploads it to the backend first, then the backend worker materializes it
+as read-only context for the training agent:
+
+```bash
+uv run freesolo '{"operation":"training","orgId":"org_123","input":{"targetRepoUrl":"https://github.com/acme/app-freesolo-training","datasetPath":"/mnt/data/my_dataset"}}'
+```
+
+## Environment
+
+- `FREESOLO_API_KEY`: required.
+- `FREESOLO_BASE_URL`: optional backend URL override. Defaults to production.
+- `FREESOLO_TRAINING_JOB_POLL_INTERVAL_SECONDS`: optional polling interval.
+
+Private GitHub app credentials, Codex settings, Tinker dependencies, and training
+runtime configuration belong to the backend worker, not this CLI package.

freesolo_agent-0.1.0/src/freesolo_agent.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+src/config.py
+src/client/__init__.py
+src/client/auth.py
+src/client/datasets.py
+src/client/jobs.py
+src/commands/__init__.py
+src/commands/main.py
+src/commands/setup.py
+src/core/__init__.py
+src/core/output.py
+src/core/types.py
+src/core/validation.py
+src/freesolo_agent.egg-info/PKG-INFO
+src/freesolo_agent.egg-info/SOURCES.txt
+src/freesolo_agent.egg-info/dependency_links.txt
+src/freesolo_agent.egg-info/entry_points.txt
+src/freesolo_agent.egg-info/requires.txt
+src/freesolo_agent.egg-info/top_level.txt

freesolo_agent-0.1.0/src/freesolo_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

freesolo_agent-0.1.0/src/freesolo_agent.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+freesolo = commands.main:main

freesolo_agent-0.1.0/src/freesolo_agent.egg-info/requires.txt

@@ -0,0 +1,2 @@
+freesolo>=0.2.4
+httpx>=0.27.0

freesolo_agent-0.1.0/src/freesolo_agent.egg-info/top_level.txt

@@ -0,0 +1,4 @@
+client
+commands
+config
+core