Metadata-Version: 2.4
Name: micro-swe-agent
Version: 1.0.0.dev3
Summary: Nano SWE Agent - A simple AI software engineering agent
Author-email: Kilian Lieret <kilian.lieret@posteo.de>
License: MIT License
        
        Copyright (c) 2025 Kilian Adriano Lieret
        
        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.
Keywords: nlp,agents,code
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pyyaml
Requires-Dist: requests
Requires-Dist: jinja2
Requires-Dist: litellm
Requires-Dist: tenacity
Requires-Dist: rich
Requires-Dist: python-dotenv
Requires-Dist: typer
Requires-Dist: platformdirs
Requires-Dist: textual
Provides-Extra: full
Requires-Dist: micro-swe-agent[dev]; extra == "full"
Requires-Dist: swe-rex; extra == "full"
Provides-Extra: dev
Requires-Dist: datasets; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mkdocs-include-markdown-plugin; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.18; extra == "dev"
Requires-Dist: mike; extra == "dev"
Requires-Dist: mkdocs-material; extra == "dev"
Requires-Dist: mkdocs-glightbox; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="docs/assets/micro-swe-agent-banner.svg" alt="micro-swe-agent banner" style="height: 12em"/>
<h1>The 100 line AI agent that solves GitHub issues & more</h1>
</div>

In 2024, [SWE-bench](https://swe-bench.com) & [SWE-agent](https://swe-agent.com) helped kickstart the agentic AI for software revolution. In 2025, we ask:
**What if the agent was 100x smaller, and still worked nearly as well?**

`micro` is for

- 🧪 **Researchers** who want to **benchmark, fine-tune or RL** without assumptions, bloat, or surprises
- 🧑‍💻 **Hackers & power users** who like their tools like their scripts: **short, sharp, and readable**
- 🐳 **Engineers** who want something **trivial to sandbox & to deploy anywhere**

Here's some details:

- **🐜 Minimal**: Just [100 lines of python](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/agents/default.py) (+100 total for [env](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/environments/local.py),
[model model](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/models/litellm_model.py), [script](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/run/hello_world.py)) — no fancy dependencies!
- **💪 Powerful:** Resolves XX% of GitHub issues in the [SWE-bench verified benchmark](https://www.swebench.com/).
- **🤗 Friendly:** Comes with **two convenient UIs** that will turn this into your daily dev swiss army knife!
- **🍀 Environments:** In addition to local envs, you can use **docker**, **podman**, **singularity**, **apptainer**, and more
- **🎓 Cutting edge:** Built by the Princeton & Stanford team behind [SWE-bench](https://swe-bench.com) and [SWE-agent](https://swe-agent.com).


<details>

<summary>More motivation (for research)</summary>

[SWE-agent](https://swe-agent.com/latest/) jump-started the development of AI agents in 2024. Back then, we placed a lot of emphasis on tools and special interfaces for the agent.
However, one year later, a lot of this is not needed at all to build a useful agent!
In fact, micro-SWE-agent

- Does not have any tools other than bash — it doesn't even use the tool-calling interface of the LMs.
  This means that you can run it with literally any model. When running in sandboxed environments you also don't need to to take care
  of installing a single package — all it needs is bash.
- Has a completely linear history — every step of the agent just appends to the messages and that's it.
  So there's no difference between the trajectory and the messages that you pass on to the LM.
- Executes actions with `subprocess.run` — every action is completely independent (as opposed to keeping a stateful shell session running).
  This makes it trivial to execute the actions in sandboxes (literally just switch out `subprocess.run` with `docker exec`) and to
  scale up effortlessly.

This makes it perfect as a baseline system and for a system that puts the language model (rather than
the agent scaffold) in the middle of our attention.

</details>

<details>
<summary>More motivation (as a tool)</summary>

Some agents are overfitted research artifacts.
Others are UI-heavy tools, highly optimized for a specific user experience.
Both variants are hard to understand.

`micro` wants to be

- **Simple** enough to understand at a glance
- **Convenient** enough to use in daily workflows
- **Flexible** to extend

A hackable tool, not a black box.

Unlike other agents (including our own [swe-agent](https://swe-agent.com/latest/)),
it is radically simpler, because it

- Does not have any tools other than bash — it doesn't even use the tool-calling interface of the LMs.
- Has a completely linear history — every step of the agent just appends to the messages and that's it.
- Executes actions with `subprocess.run` — every action is completely independent (as opposed to keeping a stateful shell session running).

</details>
<table>
<tr>
<td width="50%">
<strong>Simple UI</strong> (<code>micro</code>)
</td>
<td>
<strong>Textual UI</strong> (<code>micro2</code>)
</td>
</tr>
<tr>
<td width="50%">
<img width="600px" src="docs/assets/micro.png">
</td>
<td>
<img width="600px" src="docs/assets/micro2.png">
</td>
</tr>
<tr>
<td>
<strong>Python bindings</strong>
</td>
<td>
<strong>More in the docs</strong>
</td>
</tr>
<tr>
<td>

```python
agent = DefaultAgent(
    LitellmModel(model_name=...),
    LocalEnvironment(),
)
agent.run("Write a python sudoku game for me")
```
</td>
<td>

- TBD
</td>
</tr>
</table>

## 🔥 Try it!

(This will get simpler once we publish to pypi)

```bash
pip install pipx
# Simple UI
pipx run --spec git+ssh://git@github.com/SWE-agent/micro-swe-agent micro
# Textual UI
pipx run --spec git+ssh://git@github.com/SWE-agent/micro-swe-agent micro2
```

<details>

<summary>Details</summary>

[pipx](https://pipx.pypa.io/stable/) will install `micro-swe-agent` in an isolated environment and directly run it.
If the invocation doesn't immediately work, you might need to run `pipx ensurepath`.
After the first time, it's enough to just run `pipx run micro-swe-agent`.

</details>

<details>

<summary>Example prompts</summary>

- Implement a Sudoku solver in python in the `sudoku` folder. Make sure the codebase is modular and well tested with pytest.
- Please run pytest on the current project, discover failing unittests and help me fix them. Always make sure to test the final solution.
- Help me document & type my codebase by adding short docstrings and type hints.

</details>

## 🚀 Developer version

```bash
git clone https://github.com/SWE-agent/micro-swe-agent.git
cd micro-swe-agent
pip install -e .
```

And welcome your new friend:

```bash
# Simple UI (microsweagent/run/local.py)
micro
# Textual UI (microsweagent/run/local2.py)
micro2
```

## ⚙️ Configure

All global configuration can be either set as environment variables, or
in the `.env` file (the exact location is printed when you run `micro`).

```bash
# set default config for micro
MSWEA_LOCAL_CONFIG_PATH="/path/to/your/own/config"
# set default model
MSWEA_MODEL_NAME="claude-sonnet-4-20250514"
```

## ⚡️ Power up <a target="powerup"/>

We provide several different entry points to the agent,
for example [hello world](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/run/hello_world.py),
or the [default when calling `micro`](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/run/local.py).

Want to cook up your custom version and the config is not enough?
Just follow the recipe below:

1. What's the control flow you need? Pick an [agent class](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/agents) (e.g., [simplest example](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/agents/default.py), [with human in the loop](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/agents/interactive.py))
2. How should actions be executed? Pick an [environment class](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/environments) (e.g., [local](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/environments/local.py), or [docker](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/environments/docker.py))
3. How is the LM queried? Pick a [model class](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/models) (e.g., [litellm](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/models/litellm_model.py))
4. How to invoke the agent? Bind them all together in a [run script](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/run), possibly reading from a [config](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/config) (e.g., [hello world](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/run/hello_world.py), or [`micro` entry point](https://github.com/SWE-agent/micro-swe-agent/blob/main/src/microsweagent/run/local.py))

We aim to keep all of these components very simple, but offer lots of choice between them -- enough to cover a broad range of
things that you might want to do.

You can override the default entry point by setting the `MSWEA_DEFAULT_RUN` environment variable to the import path of your run script.

## ❤️ Contributing

We happily accept contributions!

<details>
<summary>Areas of help</summary>

- Support for more models (anything where `litellm` doesn't work out of the box)
- Documentation, examples, tutorials, etc.
- Support for more environments & deployments (e.g., run it as a github action, etc.)
- Take a look at the [issues](https://github.com/SWE-agent/micro-swe-agent/issues) and see if there's anything you'd like to work on!

</details>

<details>
<summary>Design & Architecture</summary>

- `micro-swe-agent` aims to stay minimalistic & hackable
- To extend features, we prefer to add a new version of the one of the four components above, rather than making the existing components more complex
- Components should be relatively self-contained, but if there are utilities that might be shared, add a `utils` folder (like [this one](https://github.com/SWE-agent/micro-swe-agent/tree/main/src/microsweagent/models/utils)). But keep it simple!
- If your component is a bit more specific, add it into an `extra` folder (like [this one](https://github.com/SWE-agent/micro-swe-agent/tree/main/src/microsweagent/run/extra))
- Our target audience is anyone who doesn't shy away from modifying a bit of code (especially a run script) to get what they want
- Therefore, not everything needs to be configurable with the config files, but it should be easy to use with a run script
- Many LMs write very verbose code -- please clean it up! Same goes for the tests. They should still be concise and readable.
- Please install `pre-commit` (`pip install pre-commit && pre-commit install`) and run it before committing. This will enforce our style guide.

</details>
