Metadata-Version: 2.4
Name: forge-engine
Version: 0.1.0
Summary: FORGE, a terminal AI harness engine for coding-agent workflows.
Author: Devanadhan
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/forge-engine/
Keywords: ai,agent,cli,coding-agent,harness,llm,openrouter
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.31
Requires-Dist: rich<14,>=13.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Dynamic: license-file

# FORGE

FORGE is a small Python coding-agent harness that uses an OpenAI-compatible chat-completions API. By default it calls OpenRouter with `nvidia/nemotron-3-ultra-550b-a55b:free`. It gives the model a fixed set of tools for reading files, writing files, listing the sandbox, and running shell commands, then independently verifies completion instead of trusting the model's own claim.

Cloud API calls are used by default through OpenRouter.

## Prerequisites

Set your OpenRouter API key before running the harness:

```bash
export OPENROUTER_API_KEY="your-openrouter-api-key"
```

The default API base URL is `https://openrouter.ai/api/v1` and the default model is `nvidia/nemotron-3-ultra-550b-a55b:free`.

## Installation

Install FORGE from PyPI:

```bash
pip install forge-engine
```

Then launch it from any terminal:

```bash
forge
```

## Development Installation

Install FORGE in editable mode from the project root:

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

Run the test suite with:

```bash
python3 -m pytest -q
```

## Usage

Without arguments, `forge` launches interactive mode. Type a task, watch the agent work, then get the prompt back for another task.

One-shot mode is available for scripting:

```bash
forge --task "Fix the bug in calc.py" --verify pytest
```

The sample task can still target `sandbox_project/calc.py`. The verifier runs the configured command inside the active sandbox and only reports success when the check really passes.

For source-tree compatibility, the old entry point still works:

```bash
python3 run_agent.py
```

`pip install -e .` installs the required runtime dependencies, including `requests` and `rich`.

When the model writes a file, the CLI prints a unified code diff after the tool result. This lets you watch what changed in the sandbox as the agent builds, similar to a coding-agent terminal view.

## Examples

Start an interactive session:

```bash
forge
```

Run a one-shot coding task:

```bash
forge --task "Fix the bug in calc.py" --verify pytest
```

Use another OpenAI-compatible API base URL:

```bash
forge --base-url http://localhost:11434/v1 --model qwen2.5-coder:7b
```

## Interactive Commands

| Command | Behavior |
|---|---|
| `/cwd <path>` | Change the active sandbox root to `<path>`. |
| `/verify <command>` | Set the verification command for the current project, such as `pytest` or `npm test`. |
| `/model <name>` | Swap the OpenRouter model for subsequent tasks without restarting. |
| `/new-react <name>` | Scaffold a Vite React app without interactive `create-vite` prompts, install dependencies, switch into it, and set `npm run build` as verification. |
| `/clear` | Reset the session transcript while keeping project/model/verify settings. |
| `/help` | List all commands. |
| `/exit` or `/quit` | Exit cleanly. |

The CLI persists `sandbox_root`, `verify_command`, and `model` in `.qwenagent-session.json` in the active project directory.

## Verification Fallback

If no verification command is set when the agent calls `task_complete`, the harness first tries to auto-detect one: `pytest`, `npm test`, or `make test`.

If nothing is detected, the CLI asks you what command to run. Pressing Enter explicitly accepts the agent's claim without automated verification. That is a visible human decision, not an automatic trust fallback.

## Architecture

| Concept | This project |
|---|---|
| Agentic loop | `harness/orchestrator.py` |
| Tool use | `harness/tools.py` |
| Sandboxing / permissions | `harness/sandbox.py` |
| Context management | `harness/transcript.py` |
| Knowing when a task is done | `harness/verifier.py` |
| The model (swappable) | `harness/llm_client.py` |

## Model Behavior

Models vary in how reliably they produce tool calls. Expect occasional malformed tool-call JSON, premature `task_complete` calls that bounce off the verifier, and loop-guard triggers on harder tasks.

Those outcomes are expected guardrail behavior, not harness bugs. The model's `task_complete` call is only a request for independent verification.

## Next Steps

- Add real sandbox isolation with Docker instead of only path confinement.
- Replace exact-repeat loop detection with richer "no progress" detection.
- Try another OpenRouter model by changing the `model` value with `/model <name>` or `forge --model <name>`.

## Contributing

Contributions are welcome. For local development, install the package in editable mode, run the tests, and keep changes focused on one behavior at a time:

```bash
pip install -e .[test]
python3 -m pytest -q
```

## License

FORGE is licensed under the MIT License. See `LICENSE` for details.
