langgraph-r2d

langgraph-r2d is a LangGraph-based graduation project for analyzing GitHub repositories, preparing isolated execution environments, diagnosing dependency and test-collection issues, and generating reproducible Dockerfiles for target projects.

The system can be used in two ways:

• Batch mode: read GitHub repository URLs from a text file and process them one by one.
• API mode: expose the workflow as a FastAPI service for a web frontend or external clients.

Project Goals

This project focuses on a practical problem in software engineering experiments: many open-source repositories cannot be executed directly because of missing dependencies, environment mismatches, broken test setups, or unclear runtime requirements.

langgraph-r2d attempts to solve that problem by:

• validating GitHub repository URLs before analysis
• cloning repositories into an isolated workspace
• using Docker containers to avoid polluting the host machine
• inspecting project metadata, dependency files, and test configuration
• diagnosing import errors, missing binaries, and version conflicts
• coordinating repair steps through a graph-based workflow
• exporting logs, summaries, and a generated Dockerfile for reproducible reruns

Key Features

• LangGraph workflow for validation, download, analysis, repair, verification, and export
• FastAPI backend for job submission, polling, result retrieval, and Dockerfile download
• React + Vite frontend for interactive task submission and result viewing
• Docker-backed runtime isolation for target repositories
• Dependency bootstrap fallback when Python dependency files are missing
• LLM-assisted planning and summarization through a DashScope OpenAI-compatible endpoint
• Pytest-based validation and coverage-aware automated tests for core modules

Workflow Overview

The system follows this high-level pipeline:

1. Validate the submitted GitHub URL.
2. Clone the repository into a session workspace.
3. Start an isolated Docker execution environment.
4. Inspect repository structure, dependency files, and Python metadata.
5. Bootstrap requirements when the target repository is missing usable dependency files.
6. Run test collection and environment diagnosis inside Docker.
7. Use graph nodes and tools to propose or apply repair actions.
8. Export logs, summaries, experiment metadata, and a generated Dockerfile.

Tech Stack

• Python 3.11+
• LangGraph
• LangChain Core / LangChain OpenAI
• FastAPI + Uvicorn
• Docker SDK for Python
• React 19 + Vite
• Pytest + Coverage

Repository Structure

.
|-- agent_tools/      # Tool wrappers used by the workflow agent
|-- api/              # FastAPI app, schemas, and job management
|-- core_tools/       # URL validation, download, LLM integration, diagnostics
|-- docker_tools/     # Docker lifecycle, bootstrap, and snapshot management
|-- frontend/         # React + Vite user interface
|-- graph/            # Workflow graph, state, routing, and node logic
|-- output/           # Generated logs, summaries, metadata, and Dockerfiles
|-- prompt/           # Prompt templates for planner, analyzer, and summary nodes
|-- runtime/          # Session, timer, logger, runner, and experiment utilities
|-- tests/            # Unit tests
|-- waiting_url/      # Batch input URLs
|-- workspace/        # Cloned repositories and intermediate runtime data
|-- .env.example      # Example environment configuration
|-- app.py            # Batch / API entry point
|-- langgraph.json    # Workflow runtime configuration
|-- pytest.ini        # Test and coverage configuration
|-- requirements.txt  # Python dependencies
`-- README.md

Prerequisites

Before running the project, make sure the following tools are available:

• Python 3.11 or newer
• Docker Desktop or a working Docker Engine
• Git
• Node.js 18 or newer if you want to run the frontend
• Internet access to GitHub and the configured LLM endpoint

Quick Start

1. Create a virtual environment

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Linux or macOS:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

2. Configure environment variables

Create a local .env file based on .env.example and fill in the required values.

Required:

• DASHSCOPE_API_KEY

Optional but recommended:

• GITHUB_TOKEN
• LANGGRAPH_LLM_TIMEOUT
• DOCKER_COMMIT_TIMEOUT
• LANGGARPH_ENABLE_GPU

Example:

DASHSCOPE_API_KEY=your_dashscope_api_key
GITHUB_TOKEN=your_github_token
LANGGRAPH_LLM_TIMEOUT=120
DOCKER_COMMIT_TIMEOUT=300
LANGGARPH_ENABLE_GPU=0

Note: the current codebase uses the environment variable name LANGGARPH_ENABLE_GPU exactly as written above.

3. Run in batch mode

Put one GitHub repository URL per line into waiting_url/waiting_url.txt:

https://github.com/owner/project-one
https://github.com/owner/project-two

Then run:

python app.py

4. Run in API mode

Start the backend:

python app.py --api --port 8000

You can also run it directly with Uvicorn:

uvicorn api.main:app --reload --port 8000

Health check:

curl http://localhost:8000/health

5. Run the frontend

cd frontend
npm install
npm run dev

Open the development URL shown by Vite after the backend is running.

Environment Variables

The project loads .env from the repository root.

Variable	Required	Description
DASHSCOPE_API_KEY	Yes	API key used by the LLM client.
GITHUB_TOKEN	No	Helps with GitHub rate limits and private repository access.
LANGGRAPH_LLM_TIMEOUT	No	LLM request timeout in seconds. Default: 120.
DOCKER_COMMIT_TIMEOUT	No	Timeout for Docker snapshot commits in seconds. Default: 300.
LANGGARPH_ENABLE_GPU	No	Set to 0 to disable GPU-related Docker runtime options.
LANGSMITH_TRACING	No	Reserved for local experimentation if you add tracing yourself.
LANGSMITH_API_KEY	No	Reserved for local experimentation if you add tracing yourself.
LANGSMITH_PROJECT	No	Reserved for local experimentation if you add tracing yourself.

API Endpoints

Method	Endpoint	Description
POST	/jobs	Create a new repository analysis job
GET	/jobs/{job_id}	Poll progress and current status
GET	/jobs/{job_id}/result	Get the full result for a finished job
GET	/jobs/{job_id}/dockerfile	Download the generated Dockerfile
GET	/jobs	List all jobs
DELETE	/jobs/{job_id}	Clean up session resources
GET	/health	Health check

Example request:

curl -X POST http://localhost:8000/jobs \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"https://github.com/owner/project-name\",\"max_workers\":3}"

Output Artifacts

For each analysis session, generated artifacts are written to output/<session_id>/.

Common files include:

• logs.txt
• session.log
• tool.log
• experiment.json
• summary.txt
• Dockerfile

Testing

Run the test suite with:

pytest

Generate terminal coverage output:

pytest --cov-report=term-missing

Generate HTML coverage output:

pytest --cov-report=html

The default coverage setup currently focuses on:

• api
• core_tools.check_url
• core_tools.token_counter
• graph.version_rules

Notes for Open-Source Use

• Do not commit your real .env file or any API keys.
• frontend/node_modules/, output/, workspace/, cache files, and logs are intentionally excluded from version control.
• The current LLM client is configured for the DashScope OpenAI-compatible endpoint in core_tools/llm.py.
• The system is mainly designed for Python-centric GitHub repositories, even though it can inspect other dependency manifests.

Limitations

• Docker must be available and working on the host machine.
• The quality of automated repair depends on repository structure, dependency metadata quality, and LLM responses.
• The current implementation is strongest on Python repositories and pytest-based validation flows.
• Internet connectivity is required for GitHub cloning and LLM requests.

Acknowledgements

This project was developed as an independent graduation project. The overall problem framing and some naming inspiration were informed by Repo2Run, and that influence is gratefully acknowledged here.

License

This project is released under the MIT License. See the LICENSE file for details.