Skip to content

Commit cd58194

Browse files
Sparkieryimothysu
Sparkier
and
yimothysu
authored
docs(docs): start implementing docs website (OpenHands#1372)
* docs(docs): start implementing docs website * update video url * add autogenerated codebase docs for backend * precommit * update links * fix config and video * gh actions * rename * workdirs * path * path * fix doc1 * redo markdown * docs * change main folder name * simplify readme * add back architecture * Fix lint errors * lint * update poetry lock --------- Co-authored-by: Jim Su <[email protected]>
1 parent 46bd836 commit cd58194

114 files changed

Lines changed: 19187 additions & 647 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy-docs.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Deploy Docs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
11+
jobs:
12+
build:
13+
name: Build Docusaurus
14+
runs-on: ubuntu-latest
15+
defaults:
16+
run:
17+
working-directory: docs
18+
steps:
19+
- uses: actions/checkout@v4
20+
with:
21+
fetch-depth: 0
22+
- uses: actions/setup-node@v4
23+
with:
24+
node-version: 18
25+
cache: npm
26+
cache-dependency-path: docs/package-lock.json
27+
28+
- name: Install dependencies
29+
run: npm ci
30+
- name: Build website
31+
run: npm run build
32+
33+
- name: Upload Build Artifact
34+
if: github.ref == 'refs/heads/main'
35+
uses: actions/upload-pages-artifact@v3
36+
with:
37+
path: build
38+
39+
deploy:
40+
name: Deploy to GitHub Pages
41+
needs: build
42+
if: github.ref == 'refs/heads/main'
43+
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
44+
permissions:
45+
pages: write # to deploy to Pages
46+
id-token: write # to verify the deployment originates from an appropriate source
47+
# Deploy to the github-pages environment
48+
environment:
49+
name: github-pages
50+
url: ${{ steps.deployment.outputs.page_url }}
51+
runs-on: ubuntu-latest
52+
defaults:
53+
run:
54+
working-directory: docs
55+
steps:
56+
- name: Deploy to GitHub Pages
57+
id: deployment
58+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 3 additions & 164 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
[English](README.md) | [中文](docs/README-zh.md)
2-
31
<a name="readme-top"></a>
42

53
<!--
@@ -32,168 +30,17 @@
3230

3331
<!-- PROJECT LOGO -->
3432
<div align="center">
35-
<img src="./logo.png" alt="Logo" width="200" height="200">
33+
<img src="./docs/static/img/logo.png" alt="Logo" width="200" height="200">
3634
<h1 align="center">OpenDevin: Code Less, Make More</h1>
3735
</div>
3836

39-
<!-- TABLE OF CONTENTS -->
40-
<details>
41-
<summary>🗂️ Table of Contents</summary>
42-
<ol>
43-
<li><a href="#-mission">🎯 Mission</a></li>
44-
<li><a href="#-what-is-devin">🤔 What is Devin?</a></li>
45-
<li><a href="#-why-opendevin">🐚 Why OpenDevin?</a></li>
46-
<li><a href="#-project-status">🚧 Project Status</a></li>
47-
<a href="#-get-started">🚀 Get Started</a>
48-
<ul>
49-
<li><a href="#1-requirements">1. Requirements</a></li>
50-
<li><a href="#2-build-and-setup">2. Build and Setup</a></li>
51-
<li><a href="#3-run-the-application">3. Run the Application</a></li>
52-
<li><a href="#4-individual-server-startup">4. Individual Server Startup</a></li>
53-
<li><a href="#5-help">5. Help</a></li>
54-
</ul>
55-
</li>
56-
<li><a href="#%EF%B8%8F-research-strategy">⭐️ Research Strategy</a></li>
57-
<li><a href="#-how-to-contribute">🤝 How to Contribute</a></li>
58-
<li><a href="#-join-our-community">🤖 Join Our Community</a></li>
59-
<li><a href="#%EF%B8%8F-built-with">🛠️ Built With</a></li>
60-
<li><a href="#-license">📜 License</a></li>
61-
</ol>
62-
</details>
63-
6437
## 🎯 Mission
6538

66-
[Project Demo Video](https://github.com/OpenDevin/OpenDevin/assets/38853559/71a472cc-df34-430c-8b1d-4d7286c807c9)
39+
[Project Demo Video](./docs/static/img/teaser.mp4)
6740

6841
Welcome to OpenDevin, an open-source project aiming to replicate Devin, an autonomous AI software engineer who is capable of executing complex engineering tasks and collaborating actively with users on software development projects. This project aspires to replicate, enhance, and innovate upon Devin through the power of the open-source community.
6942

70-
<p align="right" style="font-size: 14px; color: #555; margin-top: 20px;">
71-
<a href="#readme-top" style="text-decoration: none; color: #007bff; font-weight: bold;">
72-
↑ Back to Top ↑
73-
</a>
74-
</p>
75-
76-
## 🤔 What is Devin?
77-
78-
Devin represents a cutting-edge autonomous agent designed to navigate the complexities of software engineering. It leverages a combination of tools such as a shell, code editor, and web browser, showcasing the untapped potential of LLMs in software development. Our goal is to explore and expand upon Devin's capabilities, identifying both its strengths and areas for improvement, to guide the progress of open code models.
79-
80-
<p align="right" style="font-size: 14px; color: #555; margin-top: 20px;">
81-
<a href="#readme-top" style="text-decoration: none; color: #007bff; font-weight: bold;">
82-
↑ Back to Top ↑
83-
</a>
84-
</p>
85-
86-
## 🐚 Why OpenDevin?
87-
88-
The OpenDevin project is born out of a desire to replicate, enhance, and innovate beyond the original Devin model. By engaging the open-source community, we aim to tackle the challenges faced by Code LLMs in practical scenarios, producing works that significantly contribute to the community and pave the way for future advancements.
89-
90-
<p align="right" style="font-size: 14px; color: #555; margin-top: 20px;">
91-
<a href="#readme-top" style="text-decoration: none; color: #007bff; font-weight: bold;">
92-
↑ Back to Top ↑
93-
</a>
94-
</p>
95-
96-
## 🚧 Project Status
97-
98-
OpenDevin is currently a work in progress, but you can already run the alpha version to see the end-to-end system in action. The project team is actively working on the following key milestones:
99-
100-
- **UI**: Developing a user-friendly interface, including a chat interface, a shell demonstrating commands, and a web browser.
101-
- **Architecture**: Building a stable agent framework with a robust backend that can read, write, and run simple commands.
102-
- **Agent Capabilities**: Enhancing the agent's abilities to generate bash scripts, run tests, and perform other software engineering tasks.
103-
- **Evaluation**: Establishing a minimal evaluation pipeline that is consistent with Devin's evaluation criteria.
104-
105-
After completing the MVP, the team will focus on research in various areas, including foundation models, specialist capabilities, evaluation, and agent studies.
106-
107-
<p align="right" style="font-size: 14px; color: #555; margin-top: 20px;">
108-
<a href="#readme-top" style="text-decoration: none; color: #007bff; font-weight: bold;">
109-
↑ Back to Top ↑
110-
</a>
111-
</p>
112-
113-
## ⚠️ Caveats and Warnings
114-
115-
- OpenDevin is still an alpha project. It is changing very quickly and is unstable. We are working on getting a stable release out in the coming weeks.
116-
- OpenDevin will issue many prompts to the LLM you configure. Most of these LLMs cost money--be sure to set spending limits and monitor usage.
117-
- OpenDevin runs `bash` commands within a Docker sandbox, so it should not affect your machine. But your workspace directory will be attached to that sandbox, and files in the directory may be modified or deleted.
118-
- Our default Agent is currently the MonologueAgent, which has limited capabilities, but is fairly stable. We're working on other Agent implementations, including [SWE Agent](https://swe-agent.com/). You can [read about our current set of agents here](./docs/Agents.md).
119-
120-
## 🚀 Get Started
121-
122-
The easiest way to run OpenDevin is inside a Docker container.
123-
124-
To start the app, run these commands, replacing `$(pwd)/workspace` with the path to the code you want OpenDevin to work with.
125-
126-
```bash
127-
# Your OpenAI API key, or any other LLM API key
128-
export LLM_API_KEY="sk-..."
129-
130-
# The directory you want OpenDevin to modify. MUST be an absolute path!
131-
export WORKSPACE_BASE=$(pwd)/workspace
132-
133-
docker run \
134-
-e LLM_API_KEY \
135-
-e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
136-
-v $WORKSPACE_BASE:/opt/workspace_base \
137-
-v /var/run/docker.sock:/var/run/docker.sock \
138-
-p 3000:3000 \
139-
--add-host host.docker.internal=host-gateway \
140-
ghcr.io/opendevin/opendevin:0.4.0
141-
```
142-
143-
You'll find opendevin running at `http://localhost:3000`.
144-
145-
If you want to use the (unstable!) bleeding edge, you can use `ghcr.io/opendevin/opendevin:main` as the image.
146-
147-
See [Development.md](Development.md) for instructions on running OpenDevin without Docker.
148-
149-
Having trouble? Check out our [Troubleshooting Guide](./docs/guides/Troubleshooting.md).
150-
151-
## 🤖 LLM Backends
152-
153-
OpenDevin can work with any LLM backend.
154-
For a full list of the LM providers and models available, please consult the
155-
[litellm documentation](https://docs.litellm.ai/docs/providers).
156-
157-
The `LLM_MODEL` environment variable controls which model is used in programmatic interactions.
158-
But when using the OpenDevin UI, you'll need to choose your model in the settings window (the gear
159-
wheel on the bottom left).
160-
161-
The following environment variables might be necessary for some LLMs:
162-
163-
- `LLM_API_KEY`
164-
- `LLM_BASE_URL`
165-
- `LLM_EMBEDDING_MODEL`
166-
- `LLM_EMBEDDING_DEPLOYMENT_NAME`
167-
- `LLM_API_VERSION`
168-
169-
We have a few guides for running OpenDevin with specific model providers:
170-
171-
- [ollama](./docs/guides/LocalLLMs.md)
172-
- [Azure](./docs/guides/AzureLLMs.md)
173-
174-
If you're using another provider, we encourage you to open a PR to share your setup!
175-
176-
**Note on Alternative Models:**
177-
The best models are GPT-4 and Claude 3. Current local and open source models are
178-
not nearly as powerful. When using an alternative model,
179-
you may see long wait times between messages,
180-
poor responses, or errors about malformed JSON. OpenDevin
181-
can only be as powerful as the models driving it--fortunately folks on our team
182-
are actively working on building better open source models!
183-
184-
**Note on API retries and rate limits:**
185-
Some LLMs have rate limits and may require retries. OpenDevin will automatically retry requests if it receives a 429 error or API connection error.
186-
You can set LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT, LLM_RETRY_MAX_WAIT environment variables to control the number of retries and the time between retries.
187-
By default, LLM_NUM_RETRIES is 5 and LLM_RETRY_MIN_WAIT, LLM_RETRY_MAX_WAIT are 3 seconds and respectively 60 seconds.
188-
189-
## ⭐️ Research Strategy
190-
191-
Achieving full replication of production-grade applications with LLMs is a complex endeavor. Our strategy involves:
192-
193-
1. **Core Technical Research:** Focusing on foundational research to understand and improve the technical aspects of code generation and handling.
194-
2. **Specialist Abilities:** Enhancing the effectiveness of core components through data curation, training methods, and more.
195-
3. **Task Planning:** Developing capabilities for bug detection, codebase management, and optimization.
196-
4. **Evaluation:** Establishing comprehensive evaluation metrics to better understand and improve our models.
43+
To learn more and to use OpenDevin, check out our [documentation](https://opendevin.github.io/OpenDevin/).
19744

19845
<p align="right" style="font-size: 14px; color: #555; margin-top: 20px;">
19946
<a href="#readme-top" style="text-decoration: none; color: #007bff; font-weight: bold;">
@@ -230,14 +77,6 @@ If you would love to contribute, feel free to join our community (note that now
23077

23178
[![Star History Chart](https://api.star-history.com/svg?repos=OpenDevin/OpenDevin&type=Date)](https://star-history.com/#OpenDevin/OpenDevin&Date)
23279

233-
## 🛠️ Built With
234-
235-
OpenDevin is built using a combination of powerful frameworks and libraries, providing a robust foundation for its development. Here are the key technologies used in the project:
236-
237-
![FastAPI](https://img.shields.io/badge/FastAPI-black?style=for-the-badge) ![uvicorn](https://img.shields.io/badge/uvicorn-black?style=for-the-badge) ![LiteLLM](https://img.shields.io/badge/LiteLLM-black?style=for-the-badge) ![Docker](https://img.shields.io/badge/Docker-black?style=for-the-badge) ![Ruff](https://img.shields.io/badge/Ruff-black?style=for-the-badge) ![MyPy](https://img.shields.io/badge/MyPy-black?style=for-the-badge) ![LlamaIndex](https://img.shields.io/badge/LlamaIndex-black?style=for-the-badge) ![React](https://img.shields.io/badge/React-black?style=for-the-badge)
238-
239-
Please note that the selection of these technologies is in progress, and additional technologies may be added or existing ones may be removed as the project evolves. We strive to adopt the most suitable and efficient tools to enhance the capabilities of OpenDevin.
240-
24180
<p align="right" style="font-size: 14px; color: #555; margin-top: 20px;">
24281
<a href="#readme-top" style="text-decoration: none; color: #007bff; font-weight: bold;">
24382
↑ Back to Top ↑

‎dev_config/python/.pre-commit-config.yaml‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@ repos:
33
rev: v4.5.0
44
hooks:
55
- id: trailing-whitespace
6+
exclude: docs/modules/python
67
- id: end-of-file-fixer
8+
exclude: docs/modules/python
79
- id: check-yaml
810
- id: debug-statements
911

@@ -16,26 +18,31 @@ repos:
1618
hooks:
1719
- id: validate-pyproject
1820

19-
2021
- repo: https://github.com/astral-sh/ruff-pre-commit
2122
# Ruff version.
2223
rev: v0.3.7
2324
hooks:
2425
# Run the linter.
2526
- id: ruff
2627
entry: ruff check --config dev_config/python/ruff.toml opendevin/ agenthub/
27-
types_or: [ python, pyi, jupyter ]
28-
args: [ --fix ]
28+
types_or: [python, pyi, jupyter]
29+
args: [--fix]
2930
# Run the formatter.
3031
- id: ruff-format
3132
entry: ruff check --config dev_config/python/ruff.toml opendevin/ agenthub/
32-
types_or: [ python, pyi, jupyter ]
33+
types_or: [python, pyi, jupyter]
3334

3435
- repo: https://github.com/pre-commit/mirrors-mypy
3536
rev: v1.9.0
3637
hooks:
3738
- id: mypy
38-
additional_dependencies: [types-requests, types-setuptools, types-pyyaml, types-toml]
39+
additional_dependencies:
40+
[types-requests, types-setuptools, types-pyyaml, types-toml]
3941
entry: mypy --config-file dev_config/python/mypy.ini opendevin/ agenthub/
4042
always_run: true
4143
pass_filenames: false
44+
45+
- repo: https://github.com/NiklasRosenstein/pydoc-markdown
46+
rev: develop
47+
hooks:
48+
- id: pydoc-markdown

‎docs/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

0 commit comments

Comments
 (0)