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.
Files changed (88) hide show
  1. peen-1.0.0/LICENSE.md +21 -0
  2. peen-1.0.0/PKG-INFO +273 -0
  3. peen-1.0.0/README.md +198 -0
  4. peen-1.0.0/pyproject.toml +306 -0
  5. peen-1.0.0/setup.cfg +4 -0
  6. peen-1.0.0/src/peen/__init__.py +95 -0
  7. peen-1.0.0/src/peen/__main__.py +7 -0
  8. peen-1.0.0/src/peen/agents/__init__.py +28 -0
  9. peen-1.0.0/src/peen/agents/default.py +215 -0
  10. peen-1.0.0/src/peen/agents/interactive.py +218 -0
  11. peen-1.0.0/src/peen/agents/utils/__init__.py +0 -0
  12. peen-1.0.0/src/peen/agents/utils/prompt_user.py +26 -0
  13. peen-1.0.0/src/peen/config/README.md +8 -0
  14. peen-1.0.0/src/peen/config/__init__.py +64 -0
  15. peen-1.0.0/src/peen/config/benchmarks/__init__.py +1 -0
  16. peen-1.0.0/src/peen/config/benchmarks/programbench.yaml +277 -0
  17. peen-1.0.0/src/peen/config/benchmarks/swebench.yaml +183 -0
  18. peen-1.0.0/src/peen/config/benchmarks/swebench_backticks.yaml +247 -0
  19. peen-1.0.0/src/peen/config/benchmarks/swebench_modal.yaml +46 -0
  20. peen-1.0.0/src/peen/config/benchmarks/swebench_xml.yaml +229 -0
  21. peen-1.0.0/src/peen/config/default.yaml +171 -0
  22. peen-1.0.0/src/peen/config/inspector.tcss +56 -0
  23. peen-1.0.0/src/peen/config/mini.yaml +151 -0
  24. peen-1.0.0/src/peen/config/mini_textbased.yaml +171 -0
  25. peen-1.0.0/src/peen/config/peen.yaml +35 -0
  26. peen-1.0.0/src/peen/environments/__init__.py +33 -0
  27. peen-1.0.0/src/peen/environments/docker.py +161 -0
  28. peen-1.0.0/src/peen/environments/extra/__init__.py +0 -0
  29. peen-1.0.0/src/peen/environments/extra/bubblewrap.py +151 -0
  30. peen-1.0.0/src/peen/environments/extra/contree.py +153 -0
  31. peen-1.0.0/src/peen/environments/extra/swerex_docker.py +80 -0
  32. peen-1.0.0/src/peen/environments/extra/swerex_modal.py +124 -0
  33. peen-1.0.0/src/peen/environments/local.py +103 -0
  34. peen-1.0.0/src/peen/environments/singularity.py +139 -0
  35. peen-1.0.0/src/peen/exceptions.py +26 -0
  36. peen-1.0.0/src/peen/mcp/__init__.py +4 -0
  37. peen-1.0.0/src/peen/mcp/config.py +11 -0
  38. peen-1.0.0/src/peen/mcp/manager.py +181 -0
  39. peen-1.0.0/src/peen/models/__init__.py +113 -0
  40. peen-1.0.0/src/peen/models/extra/__init__.py +0 -0
  41. peen-1.0.0/src/peen/models/extra/roulette.py +64 -0
  42. peen-1.0.0/src/peen/models/litellm_model.py +170 -0
  43. peen-1.0.0/src/peen/models/litellm_response_model.py +98 -0
  44. peen-1.0.0/src/peen/models/litellm_textbased_model.py +48 -0
  45. peen-1.0.0/src/peen/models/openrouter_model.py +180 -0
  46. peen-1.0.0/src/peen/models/openrouter_response_model.py +133 -0
  47. peen-1.0.0/src/peen/models/openrouter_textbased_model.py +79 -0
  48. peen-1.0.0/src/peen/models/portkey_model.py +213 -0
  49. peen-1.0.0/src/peen/models/portkey_response_model.py +182 -0
  50. peen-1.0.0/src/peen/models/requesty_model.py +182 -0
  51. peen-1.0.0/src/peen/models/test_models.py +269 -0
  52. peen-1.0.0/src/peen/models/utils/__init__.py +0 -0
  53. peen-1.0.0/src/peen/models/utils/actions_text.py +70 -0
  54. peen-1.0.0/src/peen/models/utils/actions_toolcall.py +123 -0
  55. peen-1.0.0/src/peen/models/utils/actions_toolcall_response.py +141 -0
  56. peen-1.0.0/src/peen/models/utils/anthropic_utils.py +28 -0
  57. peen-1.0.0/src/peen/models/utils/cache_control.py +67 -0
  58. peen-1.0.0/src/peen/models/utils/content_string.py +92 -0
  59. peen-1.0.0/src/peen/models/utils/openai_multimodal.py +50 -0
  60. peen-1.0.0/src/peen/models/utils/retry.py +25 -0
  61. peen-1.0.0/src/peen/py.typed +0 -0
  62. peen-1.0.0/src/peen/run/__init__.py +1 -0
  63. peen-1.0.0/src/peen/run/benchmarks/__init__.py +1 -0
  64. peen-1.0.0/src/peen/run/benchmarks/programbench.py +193 -0
  65. peen-1.0.0/src/peen/run/benchmarks/swebench.py +275 -0
  66. peen-1.0.0/src/peen/run/benchmarks/swebench_single.py +100 -0
  67. peen-1.0.0/src/peen/run/benchmarks/utils/__init__.py +0 -0
  68. peen-1.0.0/src/peen/run/benchmarks/utils/batch_progress.py +178 -0
  69. peen-1.0.0/src/peen/run/benchmarks/utils/common.py +17 -0
  70. peen-1.0.0/src/peen/run/extra/__init__.py +0 -0
  71. peen-1.0.0/src/peen/run/hello_world.py +42 -0
  72. peen-1.0.0/src/peen/run/mini.py +118 -0
  73. peen-1.0.0/src/peen/run/peen.py +117 -0
  74. peen-1.0.0/src/peen/run/utilities/__init__.py +1 -0
  75. peen-1.0.0/src/peen/run/utilities/config.py +132 -0
  76. peen-1.0.0/src/peen/run/utilities/inspector.py +316 -0
  77. peen-1.0.0/src/peen/run/utilities/mini_extra.py +51 -0
  78. peen-1.0.0/src/peen/utils/__init__.py +0 -0
  79. peen-1.0.0/src/peen/utils/log.py +36 -0
  80. peen-1.0.0/src/peen/utils/serialize.py +29 -0
  81. peen-1.0.0/src/peen.egg-info/PKG-INFO +273 -0
  82. peen-1.0.0/src/peen.egg-info/SOURCES.txt +86 -0
  83. peen-1.0.0/src/peen.egg-info/dependency_links.txt +1 -0
  84. peen-1.0.0/src/peen.egg-info/entry_points.txt +9 -0
  85. peen-1.0.0/src/peen.egg-info/requires.txt +59 -0
  86. peen-1.0.0/src/peen.egg-info/top_level.txt +1 -0
  87. peen-1.0.0/tests/test_fire.py +159 -0
  88. 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: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE.md)
89
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg?style=flat-square)](https://www.python.org/downloads/)
90
+ [![MCP Ready](https://img.shields.io/badge/MCP-Protocol%202.0-8A2BE2?style=flat-square)](https://modelcontextprotocol.io/)
91
+ [![SWE-bench Verified](https://img.shields.io/badge/SWE--bench-74%25%20Verified-success?style=flat-square)](https://www.swebench.com/)
92
+ [![PyPI](https://img.shields.io/pypi/v/peen?color=blue&style=flat-square)](https://pypi.org/project/peen/)
93
+ [![CI](https://github.com/sobhit-singh/peen-swe/actions/workflows/pytest.yaml/badge.svg)](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: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE.md)
14
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg?style=flat-square)](https://www.python.org/downloads/)
15
+ [![MCP Ready](https://img.shields.io/badge/MCP-Protocol%202.0-8A2BE2?style=flat-square)](https://modelcontextprotocol.io/)
16
+ [![SWE-bench Verified](https://img.shields.io/badge/SWE--bench-74%25%20Verified-success?style=flat-square)](https://www.swebench.com/)
17
+ [![PyPI](https://img.shields.io/pypi/v/peen?color=blue&style=flat-square)](https://pypi.org/project/peen/)
18
+ [![CI](https://github.com/sobhit-singh/peen-swe/actions/workflows/pytest.yaml/badge.svg)](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).