# marlenezw/open-swe-python architecture

> Architecture diagram of the GitHub repository marlenezw/open-swe-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marlenezw/open-swe-python
- Repository: https://github.com/marlenezw/open-swe-python

## Overview

##### Project Type and Purpose
- This is an open-source Python tool (“Open-SWE Python”), not a traditional full-stack web app.
- Purpose: provide a multi-agent workflow (Manager, Planner, Programmer) that automates coding tasks by interacting with Large Language Models (LLMs).
- Supports two clients: a standalone CLI (`open-swe-cli.py`) and an MCP server endpoint for VS Code Copilot (`open-swe-copilot.py` + `.vscode/mcp.json`).

##### File-Structure Analysis
- Top-level scripts:
- `open-swe-cli.py` – CLI entry point
- `open-swe-copilot.py` – MCP server for VS Code integration
- `src/` – core library
- `agents/` – contains three roles:
– `manager.py` (workflow orchestrator)
– `planner.py` (requirements → plan)
– `programmer.py` (plan → code)
- `enhanced_graph.py` – graph-based workflow engine (built on LangGraph)
- `state.py` – tracks task state across agents
- `llm.py` – LLM provider abstraction
- `config.py` – configuration loader
- `tools/` – utility tools the agents can invoke
- Tests: `tests/`
- Config: `pyproject.toml`, `.vscode/mcp.json`

##### Architecture Insights from README
- Three-agent pipeline
- Graph-based orchestration
- Extensible tool-integration layer
- Two usage modes: CLI vs. MCP server (for VS Code)

a. Main Components
1. **Clients**
- CLI Interface (open-swe-cli.py)
- MCP Server (open-swe-copilot.py + `.vscode/mcp.json`)
2. **Orchestrator**
- Manager Agent
3. **Agent Pipeline**
- Planner Agent
- Programmer Agent
4. **Workflow Engine**
- Enhanced Graph (LangGraph core)
- State Manager
- Tools registry (src/tools)
5. **LLM Integration**
- llm.py abstracts calls to OpenAI/other providers
6. **Configuration**
- config.py (env vars, file-based)
7. **External Systems**
- VS Code Copilot Chat
- Python environment
- Third-party LLM API

b. Relationships & Data Flow
- **User Request** → Client (CLI or MCP server) → Manager Agent
- Manager submits subtasks to the **Graph Engine**, which spins up Planner & Programmer in sequence
- Planner queries `llm.py` for plan generation → outputs a plan node in the graph → State updated
- Programmer reads plan node → calls `llm.py` to generate code → writes to workspace or returns result
- Manager collates results, updates State, returns final output to client

c. Architectural Patterns
- Multi-agent pipeline (separation of concerns: orchestration, planning, coding)
- Graph-driven workflow (LangGraph)
- Adapter pattern for LLM providers (`llm.py`)
- Plugin/Tool registry (`tools/`) for extensibility

d. Key Technologies & Libraries
- Python 3.12+
- LangGraph (graph orchestration)
- Rich (console UI)
- MCP protocol (VS Code integration)
- pytest, black, ruff for dev workflow

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        direction TB
        CLI["CLI Interface"]:::external
        MCP["MCP Server"]:::external
    end

    %% Agents
    subgraph "Agent Pipeline"
        direction TB
        Manager["Manager Agent"]:::agent
        Planner["Planner Agent"]:::agent
        Programmer["Programmer Agent"]:::agent
    end

    %% Workflow Engine
    subgraph "Workflow Engine"
        direction TB
        EnhancedGraph["Enhanced Graph Engine"]:::engine
        GraphCore["LangGraph Core Adapter"]:::engine
        StateMgr["State Manager"]:::datastore
    end

    %% Extensions & Config
    subgraph "Extensions & Config"
        direction TB
        Tools["Tool Registry"]:::extension
        Config["Configuration Loader"]:::extension
    end

    %% LLM Integration
    subgraph "LLM Integration"
        direction TB
        LLM["LLM Provider Abstraction"]:::integration
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        VSCode["VS Code Copilot"]:::external
        PythonEnv["Python Environment"]:::external
        LLMAPI["Third-Party LLM API"]:::external
    end

    %% Project & Tests
    subgraph "Project Artifacts"
        direction TB
        PyProj["pyproject.toml"]:::artifact
        Tests["tests/"]:::artifact
        Visuals["visuals.py"]:::artifact
    end

    %% Data Flows
    CLI -->|"CLI request"| Manager
    MCP -->|"MCP protocol (JSON over HTTP)"| Manager
    Manager -->|"orchestrates"| EnhancedGraph
    EnhancedGraph -->|"uses"| GraphCore
    EnhancedGraph -->|"subtasks"| Planner
    Planner -->|"plan request"| LLM
    LLM -->|"LLM API call"| LLMAPI
    LLMAPI -->|"response"| LLM
    LLM -->|"plan result"| Planner
    Planner -->|"writes plan"| StateMgr
    StateMgr -->|"plan node"| EnhancedGraph
    EnhancedGraph -->|"next task"| Programmer
    Programmer -->|"code request"| LLM
    LLM -->|"code response"| Programmer
    Programmer -->|"writes output"| PythonEnv
    Programmer -->|"updates state"| StateMgr
    StateMgr -->|"final state"| Manager
    Manager -->|"outputs result"| CLI
    Manager -->|"outputs result"| MCP

    %% Extension usage
    Manager -->|"config load"| Config
    Planner -->|"tool plugins"| Tools
    Programmer -->|"tool plugins"| Tools

    %% Integrations
    MCP --> VSCode
    CLI --> PythonEnv

    %% Project artifacts references
    CLI --> PyProj
    Manager --> Tests
    Visuals -.-> EnhancedGraph

    %% Click Events
    click CLI "https://github.com/marlenezw/open-swe-python/blob/main/open-swe-cli.py"
    click MCP "https://github.com/marlenezw/open-swe-python/blob/main/open-swe-copilot.py"
    click Manager "https://github.com/marlenezw/open-swe-python/blob/main/src/agents/manager.py"
    click Planner "https://github.com/marlenezw/open-swe-python/blob/main/src/agents/planner.py"
    click Programmer "https://github.com/marlenezw/open-swe-python/blob/main/src/agents/programmer.py"
    click EnhancedGraph "https://github.com/marlenezw/open-swe-python/blob/main/src/enhanced_graph.py"
    click GraphCore "https://github.com/marlenezw/open-swe-python/blob/main/src/graph.py"
    click StateMgr "https://github.com/marlenezw/open-swe-python/blob/main/src/state.py"
    click LLM "https://github.com/marlenezw/open-swe-python/blob/main/src/llm.py"
    click Config "https://github.com/marlenezw/open-swe-python/blob/main/src/config.py"
    click Tools "https://github.com/marlenezw/open-swe-python/tree/main/src/tools/"
    click PyProj "https://github.com/marlenezw/open-swe-python/blob/main/pyproject.toml"
    click Tests "https://github.com/marlenezw/open-swe-python/tree/main/tests/"
    click Visuals "https://github.com/marlenezw/open-swe-python/blob/main/visuals.py"

    %% Styles
    classDef agent fill:#cce5ff,stroke:#3399ff,stroke-width:2px
    classDef engine fill:#e6ffe6,stroke:#33cc33,stroke-width:2px
    classDef datastore fill:#ccffcc,stroke:#339933,stroke-width:2px,stroke-dasharray: 5 5
    classDef extension fill:#fff2cc,stroke:#ffcc33,stroke-width:2px,stroke-dasharray: 2 2
    classDef integration fill:#ffe6f2,stroke:#ff33aa,stroke-width:2px
    classDef external fill:#f2f2f2,stroke:#999999,stroke-width:1px,stroke-dasharray: 2 2
    classDef artifact fill:#e6e6ff,stroke:#6666cc,stroke-width:1px,stroke-dasharray: 3 3
```
