1  # Revolve
  2  
  3  **Revolve** is an agentic Python code generation and editing tool that automates the creation of REST APIs, service logic, and test cases from natural language prompts. 
  4  It uses the generated apps in a modern react UI to enable CRUD operations on tables. See our [Roadmap] for future features.
  5  
  6  ---
  7  ![Revolve](./screenshots/animated.gif)
  8  
  9  
 10  ## Langgraph model flow
 11  ![Revolve Architecture](./workflow.png)
 12  
 13  ## Features
 14  
 15  - **Prompt-driven API Generation:** Describe your requirements in natural language to generate Falcon-based REST APIs and service files.
 16  - **Automated Test Generation:** Creates comprehensive pytest-based test suites for all generated endpoints and services.
 17  - **Iterative Code Refinement:** Automatically revises code and tests based on test results until all tests pass or a stopping condition is met.
 18  - **Database Integration:** Supports PostgreSQL with configurable connection via `.env`.
 19  - **UI for Workflow Management:** React-based interface for configuring the database, sending prompts, viewing generated files, and monitoring test results.
 20  - **Version Control Integration:** Optionally auto-commits and pushes changes to a Git repository.
 21  - **Test Reporting:** Tracks test history and generates Markdown and JSON reports for all test runs.
 22  
 23  ---
 24  
 25  ## Pre-requisites
 26  - Python 3.11
 27  - OPENAI API Key
 28  - PostgreSQL database with tables
 29  
 30  ---
 31  
 32  ## Quick Start
 33  
 34  ### 1. Install Dependencies
 35  
 36  ```sh
 37  brew install uv
 38  uv sync
 39  ```
 40  
 41  ### 2. Configure Environment
 42  
 43  Create a `.env` file in the project root with the following variables:
 44  ```env
 45  # prepopulate env variables in the UI
 46  OPENAI_API_KEY=your-openai-key
 47  DB_NAME=your_db_name
 48  DB_USER=your_db_user
 49  DB_PASSWORD=your_db_password
 50  DB_HOST=localhost
 51  DB_PORT=5433
 52  SOURCE_FOLDER=absolute/path/to/src/revolve/source_generated
 53  
 54  
 55  # Optional for LangSmith tracing:
 56  LANGSMITH_TRACING=false # Set to true to enable LangSmith tracing
 57  LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
 58  LANGSMITH_API_KEY=<your-langsmith-api-key>
 59  LANGSMITH_PROJECT=<your-langsmith-project-name>
 60  
 61  
 62  
 63  # Optional for Git integration:
 64  GIT_REPO_URL=https://github.com/your/repo
 65  GIT_USER_NAME=your-git-username
 66  GIT_USER_EMAIL=your-email@example.com
 67  GIT_PUSH_CHANGES=false  # Set to true to enable auto-commit and push
 68  ```
 69  
 70  ---
 71  
 72  ### 3. Unified Start (Recommended)
 73  
 74  Start both the backend and frontend together using:
 75  
 76  ```sh
 77  python src/revolve/api.py
 78  ```
 79  
 80  This will launch both the API server and the UI automatically.
 81  
 82  ---
 83  
 84  ### 4. (Optional) Run Backend and Frontend Separately
 85  
 86  If you prefer to run the backend and frontend independently:
 87  
 88  #### a. Run the Backend (Optional)
 89  
 90  ```sh
 91  python src/revolve/main.py
 92  ```
 93  
 94  #### b. Run the Frontend (Optional)
 95  
 96  ```sh
 97  cd src/revolve/ui
 98  npm install
 99  npm run dev
100  ```
101  
102  The UI will be available at [http://localhost:5173](http://localhost:5173) by default.
103  
104  ---
105  
106  ## Usage
107  
108  1. **Configure Database:** Enter your PostgreSQL connection details in the UI or [`.env`](.env ).
109  2. **Enter a Prompt:** Describe the API or service you want to generate (e.g., "Generate CRUD operations for the doctors table").
110  3. **Review Generated Files:** Inspect and edit generated Python files and tests in the UI.
111  4. **Run & Review Tests:** The system runs tests automatically and iteratively refines code until all tests pass.
112  5. **Download or Push Code:** Download generated code or push to your configured Git repository.
113  
114  ---
115  
116  ## Project Structure
117  
118  - [`src/revolve/source_generated`](src/revolve/source_generated ) — Generated API, service, and test files.
119  - [`src/revolve/ui`](src/revolve/ui ) — React frontend (see [`App.jsx`](src/revolve/ui/App.jsx )).
120  - [`src/revolve`](src/revolve ) — Core backend logic, code generation, and workflow orchestration.
121  - [`states`](states ) — Workflow state snapshots for debugging and traceability.
122  - [`db-seeds`](db-seeds ) — Example database seed files.
123  
124  ---
125  
126  ## Testing
127  
128  - Tests are generated and run automatically for each resource.
129  - Test results and history are saved in:
130    - [`src/revolve/source_generated/test_status_history.json`](src/revolve/source_generated/test_status_history.json )
131    - [`src/revolve/source_generated/test_status_report.md`](src/revolve/source_generated/test_status_report.md )
132  
133  ---
134  
135  ## Environment Variables
136  
137  - `OPENAI_API_KEY` — Required for code generation.
138  - [`DB_NAME`](src/revolve/ui/App.jsx ), [`DB_USER`](src/revolve/ui/App.jsx ), [`DB_PASSWORD`](src/revolve/ui/App.jsx ), [`DB_HOST`](src/revolve/ui/App.jsx ), [`DB_PORT`](src/revolve/ui/App.jsx ) — PostgreSQL connection.
139  - `SOURCE_FOLDER` — Where generated code is saved.
140  - `GIT_*` variables — For optional Git integration.
141  
142  ---
143  
144  ## Development Notes
145  
146  - The backend uses Falcon for REST APIs and psycopg2 for PostgreSQL.
147  - The frontend uses React, Ant Design, and Vite.
148  - All generated code and tests are placed in the path specified in  `SOURCE_FOLDER`.
149  - Static files can be served if `STATIC_DIR` is set in [`.env`](.env ).
150  
151  ## Building the package for distribution
152  To build the package for distribution, run:
153  
154  ```sh
155  uv pip install hatch
156  hatch build
157  ```
158  This will create a `dist` directory with the built package.
159  You can then install the package using:
160  
161  ```sh
162  pip install dist/revolve-0.1.0-py3-none-any.whl
163  ```
164  and then run the app using:
165  
166  ```sh
167  revolve-api
168  
169  ---
170  
171  ## License
172  
173  MIT