peen 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- peen-1.0.0/LICENSE.md +21 -0
- peen-1.0.0/PKG-INFO +273 -0
- peen-1.0.0/README.md +198 -0
- peen-1.0.0/pyproject.toml +306 -0
- peen-1.0.0/setup.cfg +4 -0
- peen-1.0.0/src/peen/__init__.py +95 -0
- peen-1.0.0/src/peen/__main__.py +7 -0
- peen-1.0.0/src/peen/agents/__init__.py +28 -0
- peen-1.0.0/src/peen/agents/default.py +215 -0
- peen-1.0.0/src/peen/agents/interactive.py +218 -0
- peen-1.0.0/src/peen/agents/utils/__init__.py +0 -0
- peen-1.0.0/src/peen/agents/utils/prompt_user.py +26 -0
- peen-1.0.0/src/peen/config/README.md +8 -0
- peen-1.0.0/src/peen/config/__init__.py +64 -0
- peen-1.0.0/src/peen/config/benchmarks/__init__.py +1 -0
- peen-1.0.0/src/peen/config/benchmarks/programbench.yaml +277 -0
- peen-1.0.0/src/peen/config/benchmarks/swebench.yaml +183 -0
- peen-1.0.0/src/peen/config/benchmarks/swebench_backticks.yaml +247 -0
- peen-1.0.0/src/peen/config/benchmarks/swebench_modal.yaml +46 -0
- peen-1.0.0/src/peen/config/benchmarks/swebench_xml.yaml +229 -0
- peen-1.0.0/src/peen/config/default.yaml +171 -0
- peen-1.0.0/src/peen/config/inspector.tcss +56 -0
- peen-1.0.0/src/peen/config/mini.yaml +151 -0
- peen-1.0.0/src/peen/config/mini_textbased.yaml +171 -0
- peen-1.0.0/src/peen/config/peen.yaml +35 -0
- peen-1.0.0/src/peen/environments/__init__.py +33 -0
- peen-1.0.0/src/peen/environments/docker.py +161 -0
- peen-1.0.0/src/peen/environments/extra/__init__.py +0 -0
- peen-1.0.0/src/peen/environments/extra/bubblewrap.py +151 -0
- peen-1.0.0/src/peen/environments/extra/contree.py +153 -0
- peen-1.0.0/src/peen/environments/extra/swerex_docker.py +80 -0
- peen-1.0.0/src/peen/environments/extra/swerex_modal.py +124 -0
- peen-1.0.0/src/peen/environments/local.py +103 -0
- peen-1.0.0/src/peen/environments/singularity.py +139 -0
- peen-1.0.0/src/peen/exceptions.py +26 -0
- peen-1.0.0/src/peen/mcp/__init__.py +4 -0
- peen-1.0.0/src/peen/mcp/config.py +11 -0
- peen-1.0.0/src/peen/mcp/manager.py +181 -0
- peen-1.0.0/src/peen/models/__init__.py +113 -0
- peen-1.0.0/src/peen/models/extra/__init__.py +0 -0
- peen-1.0.0/src/peen/models/extra/roulette.py +64 -0
- peen-1.0.0/src/peen/models/litellm_model.py +170 -0
- peen-1.0.0/src/peen/models/litellm_response_model.py +98 -0
- peen-1.0.0/src/peen/models/litellm_textbased_model.py +48 -0
- peen-1.0.0/src/peen/models/openrouter_model.py +180 -0
- peen-1.0.0/src/peen/models/openrouter_response_model.py +133 -0
- peen-1.0.0/src/peen/models/openrouter_textbased_model.py +79 -0
- peen-1.0.0/src/peen/models/portkey_model.py +213 -0
- peen-1.0.0/src/peen/models/portkey_response_model.py +182 -0
- peen-1.0.0/src/peen/models/requesty_model.py +182 -0
- peen-1.0.0/src/peen/models/test_models.py +269 -0
- peen-1.0.0/src/peen/models/utils/__init__.py +0 -0
- peen-1.0.0/src/peen/models/utils/actions_text.py +70 -0
- peen-1.0.0/src/peen/models/utils/actions_toolcall.py +123 -0
- peen-1.0.0/src/peen/models/utils/actions_toolcall_response.py +141 -0
- peen-1.0.0/src/peen/models/utils/anthropic_utils.py +28 -0
- peen-1.0.0/src/peen/models/utils/cache_control.py +67 -0
- peen-1.0.0/src/peen/models/utils/content_string.py +92 -0
- peen-1.0.0/src/peen/models/utils/openai_multimodal.py +50 -0
- peen-1.0.0/src/peen/models/utils/retry.py +25 -0
- peen-1.0.0/src/peen/py.typed +0 -0
- peen-1.0.0/src/peen/run/__init__.py +1 -0
- peen-1.0.0/src/peen/run/benchmarks/__init__.py +1 -0
- peen-1.0.0/src/peen/run/benchmarks/programbench.py +193 -0
- peen-1.0.0/src/peen/run/benchmarks/swebench.py +275 -0
- peen-1.0.0/src/peen/run/benchmarks/swebench_single.py +100 -0
- peen-1.0.0/src/peen/run/benchmarks/utils/__init__.py +0 -0
- peen-1.0.0/src/peen/run/benchmarks/utils/batch_progress.py +178 -0
- peen-1.0.0/src/peen/run/benchmarks/utils/common.py +17 -0
- peen-1.0.0/src/peen/run/extra/__init__.py +0 -0
- peen-1.0.0/src/peen/run/hello_world.py +42 -0
- peen-1.0.0/src/peen/run/mini.py +118 -0
- peen-1.0.0/src/peen/run/peen.py +117 -0
- peen-1.0.0/src/peen/run/utilities/__init__.py +1 -0
- peen-1.0.0/src/peen/run/utilities/config.py +132 -0
- peen-1.0.0/src/peen/run/utilities/inspector.py +316 -0
- peen-1.0.0/src/peen/run/utilities/mini_extra.py +51 -0
- peen-1.0.0/src/peen/utils/__init__.py +0 -0
- peen-1.0.0/src/peen/utils/log.py +36 -0
- peen-1.0.0/src/peen/utils/serialize.py +29 -0
- peen-1.0.0/src/peen.egg-info/PKG-INFO +273 -0
- peen-1.0.0/src/peen.egg-info/SOURCES.txt +86 -0
- peen-1.0.0/src/peen.egg-info/dependency_links.txt +1 -0
- peen-1.0.0/src/peen.egg-info/entry_points.txt +9 -0
- peen-1.0.0/src/peen.egg-info/requires.txt +59 -0
- peen-1.0.0/src/peen.egg-info/top_level.txt +1 -0
- peen-1.0.0/tests/test_fire.py +159 -0
- peen-1.0.0/tests/test_init.py +17 -0
peen-1.0.0/LICENSE.md
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Kilian A. Lieret and Carlos E. Jimenez
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
peen-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: peen
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Compact, workshop-forged terminal agent built to shape and refine code with zero black-box bloat — powered by native Bash & Model Context Protocol (MCP).
|
|
5
|
+
Author: Sobhit Singh
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://sobhit-singh.github.io/peen-swe/
|
|
8
|
+
Project-URL: Documentation, https://sobhit-singh.github.io/peen-swe/
|
|
9
|
+
Project-URL: Repository, https://github.com/sobhit-singh/peen-swe
|
|
10
|
+
Project-URL: Bug Tracker, https://github.com/sobhit-singh/peen-swe/issues
|
|
11
|
+
Keywords: agents,code,terminal,mcp,llm,developer-tools,swe-bench
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE.md
|
|
20
|
+
Requires-Dist: pyyaml
|
|
21
|
+
Requires-Dist: requests
|
|
22
|
+
Requires-Dist: jinja2
|
|
23
|
+
Requires-Dist: pydantic>=2.0
|
|
24
|
+
Requires-Dist: litellm!=1.82.7,!=1.82.8,>=1.75.5
|
|
25
|
+
Requires-Dist: tenacity
|
|
26
|
+
Requires-Dist: rich
|
|
27
|
+
Requires-Dist: python-dotenv
|
|
28
|
+
Requires-Dist: typer
|
|
29
|
+
Requires-Dist: platformdirs
|
|
30
|
+
Requires-Dist: textual
|
|
31
|
+
Requires-Dist: prompt_toolkit
|
|
32
|
+
Requires-Dist: datasets
|
|
33
|
+
Requires-Dist: openai!=1.100.0,!=1.100.1
|
|
34
|
+
Provides-Extra: dev
|
|
35
|
+
Requires-Dist: pytest; extra == "dev"
|
|
36
|
+
Requires-Dist: pytest-cov; extra == "dev"
|
|
37
|
+
Requires-Dist: pytest-asyncio; extra == "dev"
|
|
38
|
+
Requires-Dist: pytest-xdist; extra == "dev"
|
|
39
|
+
Requires-Dist: pre-commit; extra == "dev"
|
|
40
|
+
Requires-Dist: ruff; extra == "dev"
|
|
41
|
+
Requires-Dist: mkdocs-include-markdown-plugin; extra == "dev"
|
|
42
|
+
Requires-Dist: mkdocstrings[python]>=0.18; extra == "dev"
|
|
43
|
+
Requires-Dist: mike; extra == "dev"
|
|
44
|
+
Requires-Dist: mkdocs-material; extra == "dev"
|
|
45
|
+
Requires-Dist: mkdocs-glightbox; extra == "dev"
|
|
46
|
+
Requires-Dist: mkdocs-redirects; extra == "dev"
|
|
47
|
+
Requires-Dist: portkey-ai; extra == "dev"
|
|
48
|
+
Requires-Dist: swe-rex; extra == "dev"
|
|
49
|
+
Provides-Extra: mcp
|
|
50
|
+
Requires-Dist: mcp>=2.0.0; extra == "mcp"
|
|
51
|
+
Provides-Extra: modal
|
|
52
|
+
Requires-Dist: modal; extra == "modal"
|
|
53
|
+
Requires-Dist: boto3; extra == "modal"
|
|
54
|
+
Provides-Extra: contree
|
|
55
|
+
Requires-Dist: contree-sdk>=0.2.0; extra == "contree"
|
|
56
|
+
Provides-Extra: full
|
|
57
|
+
Requires-Dist: pytest; extra == "full"
|
|
58
|
+
Requires-Dist: pytest-cov; extra == "full"
|
|
59
|
+
Requires-Dist: pytest-asyncio; extra == "full"
|
|
60
|
+
Requires-Dist: pytest-xdist; extra == "full"
|
|
61
|
+
Requires-Dist: pre-commit; extra == "full"
|
|
62
|
+
Requires-Dist: ruff; extra == "full"
|
|
63
|
+
Requires-Dist: mkdocs-include-markdown-plugin; extra == "full"
|
|
64
|
+
Requires-Dist: mkdocstrings[python]>=0.18; extra == "full"
|
|
65
|
+
Requires-Dist: mike; extra == "full"
|
|
66
|
+
Requires-Dist: mkdocs-material; extra == "full"
|
|
67
|
+
Requires-Dist: mkdocs-glightbox; extra == "full"
|
|
68
|
+
Requires-Dist: mkdocs-redirects; extra == "full"
|
|
69
|
+
Requires-Dist: portkey-ai; extra == "full"
|
|
70
|
+
Requires-Dist: swe-rex>=1.4.0; extra == "full"
|
|
71
|
+
Requires-Dist: modal; extra == "full"
|
|
72
|
+
Requires-Dist: boto3; extra == "full"
|
|
73
|
+
Requires-Dist: mcp>=2.0.0; extra == "full"
|
|
74
|
+
Dynamic: license-file
|
|
75
|
+
|
|
76
|
+
<div align="center">
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
___ ___ ___ _ _ ______ _____
|
|
80
|
+
| _ \/ __| __| \| |___/ __\ \ / / __|
|
|
81
|
+
| _/ (__| _|| .` |___\__ \\ \/\/ /| _|
|
|
82
|
+
|_| \___|___|_|\_| |___/ \_/\_/ |___|
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### **Peen-SWE**
|
|
86
|
+
*Compact, workshop-forged terminal agent built to shape and refine code with zero black-box bloat.*
|
|
87
|
+
|
|
88
|
+
[](LICENSE.md)
|
|
89
|
+
[](https://www.python.org/downloads/)
|
|
90
|
+
[](https://modelcontextprotocol.io/)
|
|
91
|
+
[](https://www.swebench.com/)
|
|
92
|
+
[](https://pypi.org/project/peen/)
|
|
93
|
+
[](https://github.com/sobhit-singh/peen-swe/actions)
|
|
94
|
+
|
|
95
|
+
[Quick Start](#-quick-start) • [Why Peen-SWE](#-why-peen-swe) • [MCP Superpowers](#-mcp-superpowers) • [Configuration](#-configuration) • [Credits & Attribution](#-credits--upstream-attribution)
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
</div>
|
|
100
|
+
|
|
101
|
+
## 🔨 Why Peen-SWE?
|
|
102
|
+
|
|
103
|
+
Most AI coding assistants have become heavy, opaque black boxes filled with proprietary scaffolding, silent prompt injections, and rigid execution harnesses.
|
|
104
|
+
|
|
105
|
+
Like a **ball-peen hammer** in a master craftsman's workshop, **Peen-SWE** is built to do one thing with surgical precision: shape, anneal, and refine code directly in your terminal without getting in your way.
|
|
106
|
+
|
|
107
|
+
* **Ultra-Transparent Control Flow**: The entire agent loop fits in readable, unbloated Python. No complex agent graphs, no buried telemetry, and no magic abstractions.
|
|
108
|
+
* **Dual Execution Engine**: Pairs native, stateless subshell Bash commands with standardized **Model Context Protocol (MCP)** tool discovery and calling.
|
|
109
|
+
* **Human-in-the-Loop Safeguards**: Displays exact shell commands and MCP calls with interactive confirmation before execution, or toggle into autonomous `--yolo` mode when you trust the run.
|
|
110
|
+
* **Proven Benchmark Pedigree**: Inherits the battle-tested, linear SWE-bench architecture that solves >74% of real-world GitHub issues.
|
|
111
|
+
* **Model Agnostic**: Works out of the box with Claude 3.7 / 3.5 Sonnet, GPT-4o, DeepSeek-R1, Qwen, or local models via LiteLLM, Ollama, OpenRouter, and Portkey.
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## ⚡ Architecture
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
┌──────────────────────┐
|
|
119
|
+
│ User Prompt │
|
|
120
|
+
└──────────┬───────────┘
|
|
121
|
+
│
|
|
122
|
+
▼
|
|
123
|
+
┌──────────────────────┐
|
|
124
|
+
│ Peen-SWE Agent │ ◄── [peen.yaml]
|
|
125
|
+
│ (Minimal Control Loop│
|
|
126
|
+
└──────────┬───────────┘
|
|
127
|
+
│
|
|
128
|
+
┌────────────────────────┴────────────────────────┐
|
|
129
|
+
▼ ▼
|
|
130
|
+
┌──────────────────┐ ┌──────────────────┐
|
|
131
|
+
│ Bash Subshell │ │ MCP Stdio Hub │
|
|
132
|
+
│ (Local / Docker) │ │ (ClientSession) │
|
|
133
|
+
└────────┬─────────┘ └────────┬─────────┘
|
|
134
|
+
│ │
|
|
135
|
+
[ls, git, edit, tests] [sqlite, fetch, custom APIs]
|
|
136
|
+
│ │
|
|
137
|
+
└────────────────────────┬────────────────────────┘
|
|
138
|
+
│ Observation Messages
|
|
139
|
+
▼
|
|
140
|
+
┌──────────────────────┐
|
|
141
|
+
│ Next Action Loop │
|
|
142
|
+
└──────────────────────┘
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 🚀 Quick Start
|
|
148
|
+
|
|
149
|
+
### 1. Installation & Usage
|
|
150
|
+
|
|
151
|
+
**Run instantly with `uvx` (no install required):**
|
|
152
|
+
```bash
|
|
153
|
+
# Run directly from PyPI (once published)
|
|
154
|
+
uvx peen
|
|
155
|
+
|
|
156
|
+
# Or run directly from GitHub before publishing
|
|
157
|
+
uvx --from git+https://github.com/sobhit-singh/peen-swe peen
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
**Install via `pip`:**
|
|
161
|
+
```bash
|
|
162
|
+
# Install with Model Context Protocol (MCP) support
|
|
163
|
+
pip install "peen[mcp]"
|
|
164
|
+
|
|
165
|
+
# Or install editable from source
|
|
166
|
+
git clone https://github.com/sobhit-singh/peen-swe.git
|
|
167
|
+
cd peen-swe
|
|
168
|
+
pip install -e ".[mcp]"
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### 2. Configure Your API Key
|
|
172
|
+
|
|
173
|
+
Set the API key for your model of choice:
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
# Anthropic
|
|
177
|
+
export ANTHROPIC_API_KEY="sk-ant-..."
|
|
178
|
+
|
|
179
|
+
# OpenAI
|
|
180
|
+
export OPENAI_API_KEY="sk-..."
|
|
181
|
+
|
|
182
|
+
# OpenRouter
|
|
183
|
+
export OPENROUTER_API_KEY="sk-or-..."
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### 3. Launch Peen-SWE
|
|
187
|
+
|
|
188
|
+
Run the interactive terminal interface:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
peen
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Or pass a specific task and model directly:
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
peen -m anthropic/claude-3-7-sonnet-20250219 -t "Fix bug in auth middleware where token expiration throws 500"
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
To run autonomously without manual confirmation prompts:
|
|
201
|
+
```bash
|
|
202
|
+
peen -y -t "Write unit tests for utils/date_parser.py and make sure they pass"
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## 🔌 MCP Superpowers
|
|
208
|
+
|
|
209
|
+
Peen-SWE natively connects to any local or remote **Model Context Protocol (MCP)** server via standard stdio pipes.
|
|
210
|
+
|
|
211
|
+
All MCP tools are automatically namespaced as `{server_name}__{tool_name}` to prevent name collisions with standard shell commands.
|
|
212
|
+
|
|
213
|
+
### Defining MCP Servers in `peen.yaml`
|
|
214
|
+
|
|
215
|
+
Create a `peen.yaml` in your workspace or home directory:
|
|
216
|
+
|
|
217
|
+
```yaml
|
|
218
|
+
mcp:
|
|
219
|
+
servers:
|
|
220
|
+
# Query databases directly without manual shell pipelines
|
|
221
|
+
db:
|
|
222
|
+
command: "uvx"
|
|
223
|
+
args: ["mcp-server-sqlite", "--db-path", "./analytics.db"]
|
|
224
|
+
|
|
225
|
+
# Provide safe file access outside current repo
|
|
226
|
+
docs:
|
|
227
|
+
command: "npx"
|
|
228
|
+
args: ["-y", "@modelcontextprotocol/server-filesystem", "../shared-docs"]
|
|
229
|
+
|
|
230
|
+
# Web browsing & documentation fetcher
|
|
231
|
+
web:
|
|
232
|
+
command: "uvx"
|
|
233
|
+
args: ["mcp-server-fetch"]
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
When you start `peen`, it automatically connects all servers, introspects their tool definitions, registers them with the model, and routes execution through an isolated async thread pool.
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## ⚙️ Configuration
|
|
241
|
+
|
|
242
|
+
Peen-SWE supports hierarchical configuration:
|
|
243
|
+
1. Built-in defaults (`src/peen/config/peen.yaml`)
|
|
244
|
+
2. Local workspace config (`./peen.yaml`)
|
|
245
|
+
3. CLI overrides (`-c key=value` or `--mcp-config <path>`)
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
# Run with a dedicated MCP config file
|
|
249
|
+
peen --mcp-config ./my_tools.yaml
|
|
250
|
+
|
|
251
|
+
# Set a hard cost limit in USD
|
|
252
|
+
peen -l 2.50 -t "Refactor the payment webhook handler"
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## 📋 CLI Reference
|
|
258
|
+
|
|
259
|
+
| Flag | Short | Description |
|
|
260
|
+
|---|---|---|
|
|
261
|
+
| `--model` | `-m` | Model name (e.g. `anthropic/claude-3-7-sonnet`, `openai/gpt-4o`, `ollama/deepseek-r1`) |
|
|
262
|
+
| `--task` | `-t` | Problem statement or task to solve |
|
|
263
|
+
| `--yolo` | `-y` | Autonomous mode (skip confirmation prompts) |
|
|
264
|
+
| `--config` | `-c` | Config spec path, file, or `key=value` override |
|
|
265
|
+
| `--mcp-config` | | Path to standalone JSON/YAML MCP server configuration |
|
|
266
|
+
| `--cost-limit` | `-l` | Cost limit in USD (set `0` to disable) |
|
|
267
|
+
| `--output` | `-o` | Output trajectory file path (`.traj.json`) |
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## 📄 License
|
|
272
|
+
|
|
273
|
+
This project is licensed under the [MIT License](LICENSE.md).
|
peen-1.0.0/README.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
```
|
|
4
|
+
___ ___ ___ _ _ ______ _____
|
|
5
|
+
| _ \/ __| __| \| |___/ __\ \ / / __|
|
|
6
|
+
| _/ (__| _|| .` |___\__ \\ \/\/ /| _|
|
|
7
|
+
|_| \___|___|_|\_| |___/ \_/\_/ |___|
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
### **Peen-SWE**
|
|
11
|
+
*Compact, workshop-forged terminal agent built to shape and refine code with zero black-box bloat.*
|
|
12
|
+
|
|
13
|
+
[](LICENSE.md)
|
|
14
|
+
[](https://www.python.org/downloads/)
|
|
15
|
+
[](https://modelcontextprotocol.io/)
|
|
16
|
+
[](https://www.swebench.com/)
|
|
17
|
+
[](https://pypi.org/project/peen/)
|
|
18
|
+
[](https://github.com/sobhit-singh/peen-swe/actions)
|
|
19
|
+
|
|
20
|
+
[Quick Start](#-quick-start) • [Why Peen-SWE](#-why-peen-swe) • [MCP Superpowers](#-mcp-superpowers) • [Configuration](#-configuration) • [Credits & Attribution](#-credits--upstream-attribution)
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
</div>
|
|
25
|
+
|
|
26
|
+
## 🔨 Why Peen-SWE?
|
|
27
|
+
|
|
28
|
+
Most AI coding assistants have become heavy, opaque black boxes filled with proprietary scaffolding, silent prompt injections, and rigid execution harnesses.
|
|
29
|
+
|
|
30
|
+
Like a **ball-peen hammer** in a master craftsman's workshop, **Peen-SWE** is built to do one thing with surgical precision: shape, anneal, and refine code directly in your terminal without getting in your way.
|
|
31
|
+
|
|
32
|
+
* **Ultra-Transparent Control Flow**: The entire agent loop fits in readable, unbloated Python. No complex agent graphs, no buried telemetry, and no magic abstractions.
|
|
33
|
+
* **Dual Execution Engine**: Pairs native, stateless subshell Bash commands with standardized **Model Context Protocol (MCP)** tool discovery and calling.
|
|
34
|
+
* **Human-in-the-Loop Safeguards**: Displays exact shell commands and MCP calls with interactive confirmation before execution, or toggle into autonomous `--yolo` mode when you trust the run.
|
|
35
|
+
* **Proven Benchmark Pedigree**: Inherits the battle-tested, linear SWE-bench architecture that solves >74% of real-world GitHub issues.
|
|
36
|
+
* **Model Agnostic**: Works out of the box with Claude 3.7 / 3.5 Sonnet, GPT-4o, DeepSeek-R1, Qwen, or local models via LiteLLM, Ollama, OpenRouter, and Portkey.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## ⚡ Architecture
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
┌──────────────────────┐
|
|
44
|
+
│ User Prompt │
|
|
45
|
+
└──────────┬───────────┘
|
|
46
|
+
│
|
|
47
|
+
▼
|
|
48
|
+
┌──────────────────────┐
|
|
49
|
+
│ Peen-SWE Agent │ ◄── [peen.yaml]
|
|
50
|
+
│ (Minimal Control Loop│
|
|
51
|
+
└──────────┬───────────┘
|
|
52
|
+
│
|
|
53
|
+
┌────────────────────────┴────────────────────────┐
|
|
54
|
+
▼ ▼
|
|
55
|
+
┌──────────────────┐ ┌──────────────────┐
|
|
56
|
+
│ Bash Subshell │ │ MCP Stdio Hub │
|
|
57
|
+
│ (Local / Docker) │ │ (ClientSession) │
|
|
58
|
+
└────────┬─────────┘ └────────┬─────────┘
|
|
59
|
+
│ │
|
|
60
|
+
[ls, git, edit, tests] [sqlite, fetch, custom APIs]
|
|
61
|
+
│ │
|
|
62
|
+
└────────────────────────┬────────────────────────┘
|
|
63
|
+
│ Observation Messages
|
|
64
|
+
▼
|
|
65
|
+
┌──────────────────────┐
|
|
66
|
+
│ Next Action Loop │
|
|
67
|
+
└──────────────────────┘
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## 🚀 Quick Start
|
|
73
|
+
|
|
74
|
+
### 1. Installation & Usage
|
|
75
|
+
|
|
76
|
+
**Run instantly with `uvx` (no install required):**
|
|
77
|
+
```bash
|
|
78
|
+
# Run directly from PyPI (once published)
|
|
79
|
+
uvx peen
|
|
80
|
+
|
|
81
|
+
# Or run directly from GitHub before publishing
|
|
82
|
+
uvx --from git+https://github.com/sobhit-singh/peen-swe peen
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
**Install via `pip`:**
|
|
86
|
+
```bash
|
|
87
|
+
# Install with Model Context Protocol (MCP) support
|
|
88
|
+
pip install "peen[mcp]"
|
|
89
|
+
|
|
90
|
+
# Or install editable from source
|
|
91
|
+
git clone https://github.com/sobhit-singh/peen-swe.git
|
|
92
|
+
cd peen-swe
|
|
93
|
+
pip install -e ".[mcp]"
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### 2. Configure Your API Key
|
|
97
|
+
|
|
98
|
+
Set the API key for your model of choice:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
# Anthropic
|
|
102
|
+
export ANTHROPIC_API_KEY="sk-ant-..."
|
|
103
|
+
|
|
104
|
+
# OpenAI
|
|
105
|
+
export OPENAI_API_KEY="sk-..."
|
|
106
|
+
|
|
107
|
+
# OpenRouter
|
|
108
|
+
export OPENROUTER_API_KEY="sk-or-..."
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### 3. Launch Peen-SWE
|
|
112
|
+
|
|
113
|
+
Run the interactive terminal interface:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
peen
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Or pass a specific task and model directly:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
peen -m anthropic/claude-3-7-sonnet-20250219 -t "Fix bug in auth middleware where token expiration throws 500"
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
To run autonomously without manual confirmation prompts:
|
|
126
|
+
```bash
|
|
127
|
+
peen -y -t "Write unit tests for utils/date_parser.py and make sure they pass"
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## 🔌 MCP Superpowers
|
|
133
|
+
|
|
134
|
+
Peen-SWE natively connects to any local or remote **Model Context Protocol (MCP)** server via standard stdio pipes.
|
|
135
|
+
|
|
136
|
+
All MCP tools are automatically namespaced as `{server_name}__{tool_name}` to prevent name collisions with standard shell commands.
|
|
137
|
+
|
|
138
|
+
### Defining MCP Servers in `peen.yaml`
|
|
139
|
+
|
|
140
|
+
Create a `peen.yaml` in your workspace or home directory:
|
|
141
|
+
|
|
142
|
+
```yaml
|
|
143
|
+
mcp:
|
|
144
|
+
servers:
|
|
145
|
+
# Query databases directly without manual shell pipelines
|
|
146
|
+
db:
|
|
147
|
+
command: "uvx"
|
|
148
|
+
args: ["mcp-server-sqlite", "--db-path", "./analytics.db"]
|
|
149
|
+
|
|
150
|
+
# Provide safe file access outside current repo
|
|
151
|
+
docs:
|
|
152
|
+
command: "npx"
|
|
153
|
+
args: ["-y", "@modelcontextprotocol/server-filesystem", "../shared-docs"]
|
|
154
|
+
|
|
155
|
+
# Web browsing & documentation fetcher
|
|
156
|
+
web:
|
|
157
|
+
command: "uvx"
|
|
158
|
+
args: ["mcp-server-fetch"]
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
When you start `peen`, it automatically connects all servers, introspects their tool definitions, registers them with the model, and routes execution through an isolated async thread pool.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## ⚙️ Configuration
|
|
166
|
+
|
|
167
|
+
Peen-SWE supports hierarchical configuration:
|
|
168
|
+
1. Built-in defaults (`src/peen/config/peen.yaml`)
|
|
169
|
+
2. Local workspace config (`./peen.yaml`)
|
|
170
|
+
3. CLI overrides (`-c key=value` or `--mcp-config <path>`)
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
# Run with a dedicated MCP config file
|
|
174
|
+
peen --mcp-config ./my_tools.yaml
|
|
175
|
+
|
|
176
|
+
# Set a hard cost limit in USD
|
|
177
|
+
peen -l 2.50 -t "Refactor the payment webhook handler"
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## 📋 CLI Reference
|
|
183
|
+
|
|
184
|
+
| Flag | Short | Description |
|
|
185
|
+
|---|---|---|
|
|
186
|
+
| `--model` | `-m` | Model name (e.g. `anthropic/claude-3-7-sonnet`, `openai/gpt-4o`, `ollama/deepseek-r1`) |
|
|
187
|
+
| `--task` | `-t` | Problem statement or task to solve |
|
|
188
|
+
| `--yolo` | `-y` | Autonomous mode (skip confirmation prompts) |
|
|
189
|
+
| `--config` | `-c` | Config spec path, file, or `key=value` override |
|
|
190
|
+
| `--mcp-config` | | Path to standalone JSON/YAML MCP server configuration |
|
|
191
|
+
| `--cost-limit` | `-l` | Cost limit in USD (set `0` to disable) |
|
|
192
|
+
| `--output` | `-o` | Output trajectory file path (`.traj.json`) |
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## 📄 License
|
|
197
|
+
|
|
198
|
+
This project is licensed under the [MIT License](LICENSE.md).
|