starforge

# Starforge

Starforge is a general-purpose autonomous agent runtime.

It is designed to run domain-agnostic objectives through tools, not through hardcoded assumptions about coding, tests, or any single workflow.

## What It Can Do

- debug code as one optional use case
- run arbitrary tasks through CLI tools or APIs
- perform research workflows such as crypto analysis
- plug into automation systems as a reusable runtime component

## Core Design

- Task-agnostic engine: `run(objective="analyze BTC trend and summarize key signals")`
- Simple adaptive loop: act -> observe -> adapt -> repeat
- Optional model-feedback replanning in autonomous mode: when the tool queue is empty, Starforge can ask a model for the next tool call and continue iterating
- Completion quality gate for model-orchestrated runs: done-token completions are scored and may be refined before stop
- Tool-based execution: the runtime acts through tools such as `run_command`, `read_file`, `write_file`, `http_request`, `web_search`, and `read_webpage`
- Structured observations: every tool returns a normalized observation payload
- Portable memory: reusable patterns live in `~/.starforge/`, not inside project repos
- Adapters configure environments without embedding business logic into the core engine

## Folder Structure

```text
starforge/
  __init__.py        # public API: run(), create_runtime()
  __main__.py        # python -m starforge
  cli.py             # CLI entrypoint
  actions.py         # action requests and action records
  adapters.py        # CLI / code / API adapter configuration
  context.py         # runtime context normalization
  engine.py          # generic execution loop
  memory.py          # portable similarity-based memory store
  observations.py    # normalized observation model
  tools/
    base.py          # tool protocol + registry
    builtin.py       # built-in tools
examples/
  code_debugging.py
  crypto_research.py
main.py              # thin CLI proxy for local repo usage
```

## Library Usage

```python
from starforge import run

result = run(
    objective="analyze BTC trend and summarize key signals",
    context={
        "working_dir": ".",
        "constraints": [],
        "api_requests": [
            {
                "url": "https://api.coingecko.com/api/v3/coins/bitcoin/market_chart",
                "params": {"vs_currency": "usd", "days": "7", "interval": "daily"},
            }
        ],
    },
    config={
        "adapter": "api",
        "max_steps": 8,
        "mode": "autonomous",
    },
)
```

Return shape:

```python
{
    "success": bool,
    "steps": int,
    "actions": [...],
    "result": any,
    "confidence": float,
}
```

Pluggable runtime usage:

```python
from starforge import create_runtime

runtime = create_runtime(adapter="cli", memory_root="/tmp/starforge-memory")
result = runtime.run(
    objective="inspect the workspace and run the smoke command",
    context={
        "working_dir": ".",
        "commands": ["python -m pytest -q"],
    },
    config={"max_steps": 3},
)
```

## CLI Usage

```bash
starforge run "analyze ETH price trend last 7 days" --adapter api
```

```bash
starforge run "inspect objective and continue autonomously" --human --model-feedback --max-model-replans 3
```

Model feedback can use:
- Ollama (`--model-provider ollama --model-name qwen2.5:7b`)
- OpenRouter (`OPENROUTER_API_KEY=...` + `--model-provider openrouter`)
- Google / Nvidia providers via their API keys.

### Model-Orchestrated Completion Gate

When model-orchestrated mode is enabled with a required completion token (default: `DONE_STOP_AUTONOMOUS`), completion is validated with a quality review before stopping:

- The model should return structured completion JSON with `self_review.score` in `[0, 1]` and a short result summary.
- Default completion threshold is `0.97` (`completion_score_threshold`).
- If score is below threshold, Starforge requests one refine cycle by default (`completion_max_refines=1`).
- After the refine budget is used, the model may still stop by setting `cannot_improve=true` in `self_review`.

Example completion payload:

```json
{
  "done": true,
  "final_answer": "All required checks passed. DONE_STOP_AUTONOMOUS",
  "self_review": {
    "score": 0.98,
    "result": "Objective satisfied with test and file evidence."
  }
}
```

Useful config keys:

- `require_done_stop_token` (bool): enforce explicit done token on completion.
- `done_stop_token` (str): completion token text (default `DONE_STOP_AUTONOMOUS`).
- `completion_score_threshold` (float): minimum acceptable self-review score.
- `completion_max_refines` (int): refine attempts before `cannot_improve` can be accepted.

```bash
starforge run --objective "fix build errors" --adapter code --working-dir ./demo_project --command "pytest -q"
```

You can also run the repo-local entrypoint:

```bash
python main.py run "analyze BTC trend and summarize key signals"
```

## Adapters

Built-in adapters keep the engine generic while configuring tool sets for different environments.

- `cli`: `run_command`, `read_file`, `write_file`, `list_files`, `web_search`, `read_webpage`
- `code`: same tool set, plus command defaults derived from `diagnostic_command`, `test_command`, and `build_command`
- `api`: `http_request`, `web_search`, `read_webpage`, `write_file`, `read_file`

## Observation Format

All tool outputs are normalized like this:

```python
{
    "type": "command_result" | "file_read" | "api_response" | "search_results" | "webpage_read",
    "content": ...,
    "metadata": {...},
}
```

`web_search` is available as an optional tool. The runtime can use it when it helps, but it is not mandatory for every objective.

## Memory

Starforge stores portable memory in `~/.starforge/patterns.jsonl`.

Each entry captures a reusable behavior pattern instead of a task-specific hack:

```python
{
    "pattern_type": "repeated_failure",
    "context": "run_command:{...}",
    "resolution_strategy": "Avoid repeating the same failing action without changing inputs or switching tools.",
    "confidence": 0.6,
    "metadata": {...},
}
```

Retrieval is similarity-based, optional, and domain-agnostic.

## Example Workflows

Code debugging:

```bash
python examples/code_debugging.py
```

Crypto research:

```bash
python examples/crypto_research.py
```

## Installation

```bash
pip install -e .
```

This exposes the `starforge` CLI and the `starforge` Python package.