Metadata-Version: 2.4
Name: execution-agent
Version: 0.1.0
Summary: Automated project building and test execution inside Docker containers
Author: Islem Bouzenia
License: MIT License
        
        Copyright (c) 2025 Islem BOUZENIA - SOFTWARELAB
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        THIS SOFTWARE IS BASED ON THE MINI-SWE-AGENT PROJECT, 
        ORIGINAL LICENSE OF MINI-SWE-AGENT BELOW:
        
        MIT License
        
        Copyright (c) 2025 Kilian A. Lieret and Carlos E. Jimenez
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Repository, https://github.com/sola-st/ExecutionAgent
Keywords: testing,docker,automation,agents,ci
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: mini-swe-agent
Requires-Dist: docker
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Execution Agent

[![PyPI version](https://img.shields.io/pypi/v/execution-agent)](https://pypi.org/project/execution-agent/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An LLM-powered agent that automatically sets up, builds, and runs test suites for software projects inside Docker containers. Given a Git repository, it analyzes the project, creates a Dockerfile, installs dependencies, and executes the test suite — all autonomously.

## Installation

```bash
pip install execution-agent
```

Requires Python 3.10+ and Docker installed on the host.

## Quick Start

```bash
# 1. Set your API key
export OPENAI_API_KEY="your-api-key"

# 2. Create a project metadata file
cat > project_meta_data.json << 'EOF'
{
  "project_path": "my_project",
  "project_url": "https://github.com/username/my_project",
  "language": "Python",
  "budget": 40
}
EOF

# 3. Run the agent
execution-agent --experiment-file project_meta_data.json
```

## How It Works

1. **Context gathering** — Clones the repository, inspects CI configs, README, and dependency files
2. **Dockerfile generation** — Creates a Docker environment tailored to the project
3. **Build & test** — Iteratively runs commands inside the container to install, build, and test
4. **Retry with learning** — If the budget is exhausted, retries with lessons from previous attempts
5. **Forced exit** — As a last resort, a knowledge model synthesizes a final solution from all context

The task is considered successful when ~80%+ of tests pass.

## Command-Line Options

```
execution-agent --experiment-file META.json [OPTIONS]
```

| Option | Description | Default |
|--------|-------------|---------|
| `--experiment-file` | Path to project metadata JSON **(required)** | — |
| `--task` | Custom task string | Auto-generated |
| `--task-file` | File containing custom task instructions | — |
| `--model` | LLM model for the agent | `gpt-5-nano` |
| `--knowledge-model` | LLM model for context analysis | `gpt-5-mini` |
| `--api-key` | OpenAI API key | `$OPENAI_API_KEY` |
| `--workspace-root` | Output directory | `execution_agent_workspace` |
| `--prompt-files` | Custom prompt templates directory | Bundled defaults |
| `--log-level` | `DEBUG` / `INFO` / `WARNING` / `ERROR` | `INFO` |
| `--run-log-dir` | Custom directory for run logs | Auto-generated |
| `--max-retries` | Retries after budget exhaustion | `2` |

You can also run it as a module:

```bash
python -m execution_agent --experiment-file project_meta_data.json
```

## Project Metadata Format

```json
{
  "project_path": "scipy",
  "project_name": "SciPy",
  "project_url": "https://github.com/scipy/scipy",
  "language": "Python",
  "budget": 40
}
```

| Field | Description |
|-------|-------------|
| `project_path` | Directory name for the project |
| `project_name` | Human-readable name (optional) |
| `project_url` | Git repository URL |
| `language` | Primary language: `Python`, `Java`, `Javascript`, `C`, `C++`, `Rust` |
| `budget` | Maximum execution cycles (steps) |

## Agent Tools

The agent can use these tools during execution:

| Tool | Description |
|------|-------------|
| `linux_terminal` | Execute bash commands inside the Docker container |
| `read_file` | Read file contents |
| `write_to_file` | Write files (Dockerfiles, scripts, etc.) |
| `search_docker_image` | Search Docker Hub for base images |
| `goals_accomplished` | Signal successful task completion |

## Output Structure

```
execution_agent_workspace/
├── _run_logs/<project>/<timestamp>/
│   ├── run.log                    # Human-readable log
│   ├── run.jsonl                  # Structured JSON log
│   ├── messages.json              # Full LLM conversation history
│   ├── replay_trace.sh            # Bash script to replay all commands
│   ├── tool_metrics.json          # Tool execution statistics
│   ├── cycles_chats/              # Per-cycle LLM prompts
│   ├── success_artifacts/         # On success: Dockerfile, commands.sh, launch.sh
│   └── forced_exit_cycle/         # On budget exhaustion: final attempt artifacts
└── <project>/                     # Cloned repository
```

### Reproducing a Successful Run

```bash
cd execution_agent_workspace/_run_logs/<project>/<timestamp>/success_artifacts/
./launch.sh
```

## Retry Mechanism

1. **Attempt 1**: Initial run with full budget
2. **Attempts 2–N**: Retries informed by lessons from previous attempts
3. **Forced exit cycle**: If all retries fail, a knowledge model generates a final Dockerfile and test script based on everything learned

Each attempt produces a summary with problems encountered, progress made, and suggestions for the next attempt.

## Language Support

Built-in guidelines are included for:
Python, Java, JavaScript/TypeScript, C, C++, and Rust.

## Environment Variables

| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | API key for LLM access (required) |
| `OPENAI_MODEL` | Default model (fallback for `--model`) |
| `KNOWLEDGE_MODEL` | Default knowledge model (fallback for `--knowledge-model`) |

## License

MIT — see [LICENSE.md](LICENSE.md) for details.

Based on [mini-swe-agent](https://github.com/SWE-agent/mini-SWE-agent) by Kilian Lieret and Carlos E. Jimenez.
