Skip to content

Commit 6da50a4

Browse files
KRRT7KRRT7
authored
Merge pull request #633 from codeflash-ai/add-warp.md
Create WARP.md
2 parents 5823492 + c586456 commit 6da50a4

File tree

1 file changed

+191
-0
lines changed

1 file changed

+191
-0
lines changed

‎WARP.md

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# WARP.md
2+
3+
This file provides guidance to WARP (warp.dev) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Codeflash is a general-purpose optimizer for Python that helps improve code performance while maintaining correctness. It uses advanced LLMs to generate optimization ideas, tests them for correctness, and benchmarks them for performance, then creates merge-ready pull requests.
8+
9+
## Development Environment Setup
10+
11+
### Prerequisites
12+
- Python 3.9+ (project uses uv for dependency management)
13+
- Git (for version control and PR creation)
14+
- Codeflash API key (for AI services)
15+
16+
### Initial Setup
17+
```bash
18+
# Install dependencies using uv (preferred over pip)
19+
uv sync
20+
21+
# Initialize codeflash configuration
22+
uv run codeflash init
23+
```
24+
25+
## Core Development Commands
26+
27+
### Code Quality & Linting
28+
```bash
29+
# Format code with ruff (includes check and format)
30+
uv run ruff check --fix codeflash/
31+
uv run ruff format codeflash/
32+
33+
# Type checking with mypy
34+
uv run mypy codeflash/
35+
36+
# Pre-commit hooks (ruff check + format)
37+
uv run pre-commit run --all-files
38+
```
39+
40+
### Testing
41+
```bash
42+
# Run all tests
43+
uv run pytest
44+
45+
# Run specific test file
46+
uv run pytest tests/test_specific_file.py
47+
48+
# Run tests matching pattern
49+
uv run pytest -k "pattern"
50+
51+
```
52+
53+
### Running Codeflash
54+
```bash
55+
# Optimize entire codebase
56+
uv run codeflash --all
57+
58+
# Optimize specific file
59+
uv run codeflash --file path/to/file.py
60+
61+
# Optimize specific function
62+
uv run codeflash --function "module.function"
63+
64+
# Optimize a script end-to-end
65+
uv run codeflash optimize script.py
66+
67+
# Run with benchmarking
68+
uv run codeflash --benchmark
69+
70+
# Verify setup
71+
uv run codeflash --verify-setup
72+
```
73+
74+
## Architecture Overview
75+
76+
### Main Components
77+
78+
**Core Modules:**
79+
- `codeflash/main.py` - CLI entry point and command coordination
80+
- `codeflash/cli_cmds/` - Command-line interface implementations
81+
- `codeflash/optimization/` - Core optimization engine and algorithms
82+
- `codeflash/verification/` - Code correctness verification
83+
- `codeflash/benchmarking/` - Performance measurement and comparison
84+
- `codeflash/discovery/` - Code analysis and function discovery
85+
- `codeflash/tracing/` - Runtime tracing and profiling
86+
- `codeflash/context/` - Code context extraction and analysis
87+
- `codeflash/result/` - Result processing, PR creation, and explanations
88+
89+
**Supporting Systems:**
90+
- `codeflash/api/` - Backend API communication
91+
- `codeflash/github/` - GitHub integration for PR creation
92+
- `codeflash/models/` - Data models and schemas
93+
- `codeflash/telemetry/` - Analytics and error reporting
94+
- `codeflash/code_utils/` - Code parsing, formatting, and manipulation utilities
95+
96+
### Key Workflows
97+
98+
1. **Code Discovery**: Analyzes codebase to identify optimization candidates
99+
2. **Context Extraction**: Extracts relevant code context and dependencies
100+
3. **Optimization Generation**: Uses LLMs to generate optimization candidates
101+
4. **Verification**: Tests optimizations for correctness using existing tests
102+
5. **Benchmarking**: Measures performance improvements
103+
6. **Result Processing**: Creates explanations and pull requests
104+
105+
### Configuration
106+
107+
Configuration is stored in `pyproject.toml` under `[tool.codeflash]`:
108+
- `module-root` - Source code location (default: "codeflash")
109+
- `tests-root` - Test location (default: "tests")
110+
- `benchmarks-root` - Benchmark location (default: "tests/benchmarks")
111+
- `test-framework` - Testing framework ("pytest" or "unittest")
112+
- `formatter-cmds` - Commands for code formatting
113+
114+
## Project Structure
115+
116+
```
117+
codeflash/
118+
├── api/ # Backend API communication
119+
├── benchmarking/ # Performance measurement
120+
├── cli_cmds/ # CLI command implementations
121+
├── code_utils/ # Code analysis and manipulation
122+
├── context/ # Code context extraction
123+
├── discovery/ # Function and test discovery
124+
├── github/ # GitHub API integration
125+
├── lsp/ # Language server protocol support
126+
├── models/ # Data models and schemas
127+
├── optimization/ # Core optimization engine
128+
├── result/ # Result processing and PR creation
129+
├── telemetry/ # Analytics and monitoring
130+
├── tracing/ # Runtime tracing and profiling
131+
├── verification/ # Correctness verification
132+
└── main.py # CLI entry point
133+
134+
tests/ # Test suite
135+
├── benchmarks/ # Performance benchmarks
136+
└── scripts/ # Test utilities
137+
138+
docs/ # Documentation
139+
code_to_optimize/ # Example code for optimization
140+
codeflash-benchmark/ # Benchmark workspace member
141+
```
142+
143+
## Development Notes
144+
145+
### Code Style
146+
- Uses ruff for linting and formatting (configured in pyproject.toml)
147+
- Strict mypy type checking enabled
148+
- Pre-commit hooks enforce code quality
149+
150+
### Testing
151+
- pytest-based test suite with extensive coverage
152+
- Parameterized tests for multiple scenarios
153+
- Benchmarking tests for performance validation
154+
- Test discovery supports both pytest and unittest frameworks
155+
156+
### Workspace Structure
157+
- Uses uv workspace with `codeflash-benchmark` as a member
158+
- Dependencies managed through uv.lock
159+
- Dynamic versioning from git tags using uv-dynamic-versioning
160+
161+
### Build & Distribution
162+
- Uses hatchling as build backend
163+
- BSL-1.1 license
164+
- Excludes development files from distribution packages
165+
166+
### CI/CD Integration
167+
- GitHub Actions workflow for automatic optimization of PR code
168+
- Pre-commit hooks for code quality enforcement
169+
- Automated testing and benchmarking
170+
171+
## Important Patterns
172+
173+
### Error Handling
174+
- Uses `either.py` for functional error handling patterns
175+
- Comprehensive error tracking through Sentry integration
176+
- Graceful degradation when AI services are unavailable
177+
178+
### Instrumentation
179+
- Extensive tracing capabilities for performance analysis
180+
- Line profiler integration for detailed performance metrics
181+
- Custom tracer implementation for code execution analysis
182+
183+
### AI Integration
184+
- Structured prompts and response handling for LLM interactions
185+
- Critic module for evaluating optimization quality
186+
- Context-aware code generation and explanation
187+
188+
### Git Integration
189+
- GitPython for repository operations
190+
- Automated PR creation with detailed explanations
191+
- Branch management for optimization experiments

0 commit comments

Comments
 (0)