# RepoPilot

RepoPilot is a verifiable code agent for Python repositories. It turns an issue
into an evidence-backed plan, optionally asks an OpenAI-compatible model for a
unified diff, and runs the reviewed patch in an isolated workspace. Every
retrieval, tool call, patch, and test result is retained as a compact audit
trace.

![Python](https://img.shields.io/badge/Python-3.11%2B-1f6b45)
![FastAPI](https://img.shields.io/badge/FastAPI-0.115%2B-1f6b45)
![MCP](https://img.shields.io/badge/MCP-1.x-e86e3c)
![Tests](https://img.shields.io/badge/tests-pytest-d7ef52)

## Why this is not another chat-with-your-code demo

- **AST-aware indexing:** extracts classes, functions, methods, signatures,
  imports, and call edges instead of splitting source into arbitrary chunks.
- **Hybrid retrieval:** combines issue-token relevance with symbol names, file
  paths, and call-graph evidence.
- **Bounded workflow:** retrieval, planning, human review, patch validation,
  isolated execution, and test verification have explicit states.
- **Standard tools:** repository map, symbol search, file reads, and reference
  lookup are exposed through the official MCP Python SDK.
- **Guarded execution:** patch size, paths, file types, and number of changed
  files are validated before a copy of the repository is modified.
- **Objective evaluation:** a JSONL benchmark runner reports Recall@K and mean
  reciprocal rank for related-file retrieval.

## Architecture

```mermaid
flowchart LR
    UI[Web console] --> API[FastAPI]
    API --> IDX[Python AST indexer]
    IDX --> STORE[Persistent JSON indexes]
    API --> RET[Hybrid retriever]
    RET --> PLAN[Bounded planner]
    PLAN --> LLM[OpenAI-compatible LLM]
    PLAN --> MCP[MCP code tools]
    LLM --> REVIEW[Human patch review]
    REVIEW --> POLICY[Patch policy]
    POLICY --> WS[Isolated workspace]
    WS --> TEST[Fixed pytest runner]
    TEST --> TRACE[Auditable task trace]
```

The implementation deliberately separates read-only code tools from patch
execution. An MCP client can inspect code without receiving a general-purpose
shell tool.

## Quick start

```powershell
cd D:\ai-projects\repopilot
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m repopilot
```

Open <http://127.0.0.1:8765>.

The repository includes a deliberately broken demo at
`examples/buggy_calculator`. Index that directory, then use this issue:

```text
divide should raise a clear ValueError when right is zero
```

If no model is running, create the plan and paste this reviewed patch into the
execution panel:

```diff
diff --git a/calculator.py b/calculator.py
--- a/calculator.py
+++ b/calculator.py
@@ -1,2 +1,4 @@
 def divide(left: float, right: float) -> float:
+    if right == 0:
+        raise ValueError("right must not be zero")
     return left / right
```

The patch is applied only to `workspaces/<task-id>`; the indexed source
repository is not modified.

## Model configuration

RepoPilot uses the OpenAI-compatible `/chat/completions` API. The defaults target
an Ollama installation:

```env
REPOPILOT_LLM_BASE_URL=http://127.0.0.1:11434/v1
REPOPILOT_LLM_MODEL=qwen2.5-coder:7b
REPOPILOT_LLM_API_KEY=ollama
```

Planning has a deterministic fallback when the model is offline. Patch
generation requires a configured model because silently inventing a patch would
make the demo impossible to trust.

## MCP server

Start the stdio MCP server:

```powershell
.\.venv\Scripts\repopilot-mcp.exe
```

Tools:

- `repository_map`
- `search_symbol`
- `read_file`
- `find_references`

Each tool requires the ID of a previously indexed repository.

## Evaluation

After indexing the demo repository, copy its ID from the UI or
`GET /api/repositories` and run:

```powershell
.\.venv\Scripts\repopilot-eval.exe <repository-id> examples\benchmark.jsonl --k 5
```

Benchmark cases use one JSON object per line:

```json
{"id":"case-1","issue":"describe the failure","expected_files":["module.py"]}
```

The report includes per-case retrieved files, Recall@K, reciprocal rank, mean
Recall@K, and MRR. This makes retrieval changes measurable and suitable for
ablation experiments.

## API overview

| Method | Endpoint | Purpose |
|---|---|---|
| `GET` | `/api/health` | Service health |
| `POST` | `/api/repositories` | Index a local Python repository |
| `GET` | `/api/repositories` | List indexed repositories |
| `POST` | `/api/repositories/{id}/search` | Search symbols |
| `POST` | `/api/repositories/{id}/tasks` | Analyze an issue and create a plan |
| `POST` | `/api/tasks/{id}/generate-patch` | Generate a policy-checked diff |
| `POST` | `/api/tasks/{id}/execute` | Execute a reviewed patch and tests |
| `GET` | `/api/tasks/{id}` | Read the plan, trace, diff, and test result |

Interactive API documentation is available at
<http://127.0.0.1:8765/docs>.

## Safety model

The local executor is intentionally constrained:

- source repositories are copied before modification;
- patch paths must remain inside the workspace;
- at most five text/source files and 100 KB may be changed;
- test execution is fixed to `python -m pytest -q`;
- subprocesses have a timeout and capped captured output;
- network proxy variables and unrelated environment variables are not passed;
- task events store concise action summaries, not private chain-of-thought.

The local executor is a development safety boundary, not a hostile-code
sandbox. Run untrusted repositories only inside a disposable VM or container.
See [SECURITY.md](SECURITY.md).

## Development

```powershell
.\.venv\Scripts\python.exe -m pytest --cov=repopilot --cov-report=term-missing
```

The Git history is organized as reviewable implementation milestones:

1. service scaffold;
2. AST indexing and retrieval;
3. bounded planning and MCP tools;
4. guarded patch execution;
5. evaluation, UI, deployment, and documentation.