diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index a4c8f6a89..d932516f7 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -21,7 +21,7 @@ jobs: runs-on: ubuntu-latest permissions: contents: read - pull-requests: read + pull-requests: write issues: read id-token: write @@ -35,7 +35,8 @@ jobs: id: claude-review uses: anthropics/claude-code-action@v1 with: - anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + use_foundry: "true" + use_sticky_comment: true prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} @@ -49,9 +50,10 @@ jobs: Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback. - Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR. - # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md # or https://code.claude.com/docs/en/cli-reference for available options - claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"' + claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"' + env: + ANTHROPIC_FOUNDRY_API_KEY: ${{ secrets.AZURE_ANTHROPIC_API_KEY }} + ANTHROPIC_FOUNDRY_BASE_URL: ${{ secrets.AZURE_ANTHROPIC_ENDPOINT }} diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index 79fe05647..24acf1ffd 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -34,17 +34,10 @@ jobs: id: claude uses: anthropics/claude-code-action@v1 with: - anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - - # This is an optional setting that allows Claude to read CI results on PRs + use_foundry: "true" additional_permissions: | actions: read - - # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it. - # prompt: 'Update the pull request description to include a summary of changes.' - - # Optional: Add claude_args to customize behavior and configuration - # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md - # or https://code.claude.com/docs/en/cli-reference for available options - # claude_args: '--allowed-tools Bash(gh pr:*)' + env: + ANTHROPIC_FOUNDRY_API_KEY: ${{ secrets.AZURE_ANTHROPIC_API_KEY }} + ANTHROPIC_FOUNDRY_BASE_URL: ${{ secrets.AZURE_ANTHROPIC_ENDPOINT }} diff --git a/.github/workflows/pr_agent.yml b/.github/workflows/pr_agent.yml deleted file mode 100644 index 4f6d48de6..000000000 --- a/.github/workflows/pr_agent.yml +++ /dev/null @@ -1,20 +0,0 @@ -on: - pull_request: - types: [opened, reopened, ready_for_review] - issue_comment: -jobs: - pr_agent_job: - if: ${{ github.event.sender.type != 'Bot' }} - runs-on: ubuntu-latest - permissions: - issues: write - pull-requests: write - contents: write - name: Run pr agent on every pull request, respond to user comments - steps: - - name: PR Agent action step - id: pragent - uses: qodo-ai/pr-agent@main - env: - OPENAI_KEY: ${{ secrets.OPENAI_KEY }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index fe6acacc4..5acea2bdb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,113 +1,47 @@ # CodeFlash AI Agent Instructions -This file provides comprehensive guidance to any coding agent (Warp, GitHub Copilot, Claude, Gemini, etc.) when working with the CodeFlash repository. - ## Project Overview -CodeFlash is an AI-powered Python code optimizer that automatically improves code performance while maintaining correctness. It uses LLMs to analyze code, generate optimization ideas, validate correctness through comprehensive testing, benchmark performance improvements, and create merge-ready pull requests. - -**Key Capabilities:** -- Optimize entire codebases with `codeflash --all` -- Optimize specific files or functions with targeted commands -- End-to-end workflow optimization with `codeflash optimize script.py` -- Automated GitHub Actions integration for CI/CD pipelines -- Comprehensive benchmarking and performance analysis -- Git worktree isolation for safe optimization - -## Core Architecture - -### Data Flow Pipeline -Discovery → Context → Optimization → Verification → Benchmarking → PR - -1. **Discovery** (`codeflash/discovery/`) - Find optimizable functions via static analysis or execution tracing -2. **Context Extraction** (`codeflash/context/`) - Extract dependencies, imports, and related code -3. **Optimization** (`codeflash/optimization/`) - Generate optimized code via AI service calls -4. **Verification** (`codeflash/verification/`) - Run deterministic tests with custom pytest plugin -5. **Benchmarking** (`codeflash/benchmarking/`) - Performance measurement and comparison -6. **GitHub Integration** (`codeflash/github/`) - Automated PR creation with detailed analysis - -### Key Components - -**Main Entry Points:** -- `codeflash/main.py` - CLI entry point and main orchestration -- `codeflash/cli_cmds/cli.py` - Command-line argument parsing and validation - -**Core Optimization Pipeline:** -- `codeflash/optimization/optimizer.py` - Main optimization orchestrator -- `codeflash/optimization/function_optimizer.py` - Individual function optimization -- `codeflash/tracing/` - Function call tracing and profiling - -**Code Analysis & Manipulation:** -- `codeflash/code_utils/` - Code parsing, AST manipulation, static analysis -- `codeflash/context/` - Code context extraction and analysis -- `codeflash/verification/` - Code correctness verification through testing - -**External Integrations:** -- `codeflash/api/aiservice.py` - LLM communication with rate limiting and retries -- `codeflash/github/` - GitHub integration for PR creation -- `codeflash/benchmarking/` - Performance benchmarking and measurement +CodeFlash is an AI-powered Python code optimizer that automatically improves code performance while maintaining correctness. -**Supporting Systems:** -- `codeflash/models/models.py` - Pydantic models and type definitions -- `codeflash/telemetry/` - Usage analytics (PostHog) and error reporting (Sentry) -- `codeflash/ui/` - User interface components (Rich console output) -- `codeflash/lsp/` - Language Server Protocol support for IDE integration +## Architecture -### Key Optimization Workflows - -**1. Full Codebase Optimization (`--all`)** -- Discovers all optimizable functions in the project -- Runs benchmarks if configured -- Optimizes functions in parallel -- Creates PRs for successful optimizations - -**2. Targeted Optimization (`--file`, `--function`)** -- Focuses on specific files or functions -- Performs detailed analysis and context extraction -- Applies targeted optimizations - -**3. Workflow Tracing (`optimize`)** -- Traces Python script execution -- Identifies performance bottlenecks -- Generates optimizations for traced functions -- Uses checkpoint system to resume interrupted runs +``` +codeflash/ +├── main.py # CLI entry point +├── cli_cmds/ # Command handling, console output (Rich) +├── discovery/ # Find optimizable functions +├── context/ # Extract code dependencies and imports +├── optimization/ # Generate optimized code via AI +├── verification/ # Run deterministic tests (pytest plugin) +├── benchmarking/ # Performance measurement +├── github/ # PR creation +├── api/ # AI service communication +├── code_utils/ # Code parsing, git utilities +├── models/ # Pydantic models and types +├── tracing/ # Function call tracing +├── lsp/ # IDE integration +├── telemetry/ # Sentry, PostHog +└── either.py # Functional error handling +``` ## Critical Development Patterns -### Package Management with uv (NOT pip) +### Use uv, NEVER pip +**NEVER use `pip install` or `pip` commands.** This project uses `uv` exclusively for package management. ```bash -# Always use uv, never pip -uv sync # Install dependencies -uv sync --group dev # Install dev dependencies -uv run pytest # Run commands -uv add package # Add new packages -uv build # Build package +uv sync # Install dependencies (NOT pip install -r requirements.txt) +uv sync --group dev # Dev dependencies (NOT pip install -e .) +uv run pytest # Run commands (NOT python -m pytest) +uv add package # Add packages (NOT pip install package) ``` -### Code Manipulation with LibCST (NOT ast) -Always use `libcst` for code parsing/modification to preserve formatting: -```python -from libcst import parse_module, PartialPythonCodeGen -# Never use ast module for code transformations -``` - -### Testing with Deterministic Execution -Custom pytest plugin (`codeflash/verification/pytest_plugin.py`) ensures reproducible tests: -- Patches time, random, uuid for deterministic behavior -- Environment variables: `CODEFLASH_TEST_MODULE`, `CODEFLASH_TEST_CLASS`, `CODEFLASH_TEST_FUNCTION` -- Always use `uv run pytest`, never `python -m pytest` - -### Git Worktree Isolation -Optimizations run in isolated git worktrees to avoid affecting main repo: -```python -from codeflash.code_utils.git_utils import create_detached_worktree, remove_worktree -# Pattern: create_detached_worktree() → optimize → create_diff_patch_from_worktree() -``` +### Use libcst, not ast +Always use `libcst` for code parsing/modification to preserve formatting. -### Error Handling with Either Pattern -Use functional error handling instead of exceptions: +### Use Either pattern for errors ```python -from codeflash.either import is_successful, Either +from codeflash.either import is_successful result = aiservice_client.call_llm(...) if is_successful(result): optimized_code = result.value @@ -115,207 +49,21 @@ else: error = result.error ``` -## Configuration - -All configuration in `pyproject.toml` under `[tool.codeflash]`: -```toml -[tool.codeflash] -module-root = "codeflash" # Source code location -tests-root = "tests" # Test directory -benchmarks-root = "tests/benchmarks" # Benchmark tests -test-framework = "pytest" # Always pytest -formatter-cmds = [ # Auto-formatting commands - "uvx ruff check --exit-zero --fix $file", - "uvx ruff format $file", -] -``` - -## Development Commands - -### Environment Setup -```bash -# Install dependencies (always use uv) -uv sync - -# Install development dependencies -uv sync --group dev - -# Install pre-commit hooks -uv run pre-commit install -``` - -### Code Quality & Linting -```bash -# Run linting and formatting with ruff (primary tool) -uv run ruff check --fix . -uv run ruff format . - -# Type checking with mypy (strict mode) -uv run mypy . - -# Clean Python cache files -uvx pyclean . -``` - -### Testing -```bash -# Run all tests -uv run pytest - -# Run tests with coverage -uv run coverage run -m pytest tests/ - -# Run specific test file -uv run pytest tests/test_code_utils.py - -# Run tests with verbose output -uv run pytest -v - -# Run benchmarks -uv run pytest tests/benchmarks/ - -# Run end-to-end tests -uv run pytest tests/scripts/ - -# Run with specific markers -uv run pytest -m "not ci_skip" -``` - -### Running CodeFlash -```bash -# Initialize CodeFlash in a project -uv run codeflash init - -# Optimize entire codebase -uv run codeflash --all - -# Optimize specific file -uv run codeflash --file path/to/file.py - -# Optimize specific function -uv run codeflash --file path/to/file.py --function function_name - -# Trace and optimize a workflow -uv run codeflash optimize script.py - -# Verify setup with test optimization -uv run codeflash --verify-setup - -# Run with verbose logging -uv run codeflash --verbose --all - -# Run with benchmarking enabled -uv run codeflash --benchmark --file target_file.py - -# Use replay tests for debugging -uv run codeflash --replay-test tests/specific_test.py -``` - -## Development Guidelines - -### Code Style -- Uses Ruff for linting and formatting (configured in pyproject.toml) -- Strict mypy type checking enabled -- Pre-commit hooks enforce code quality -- Line length: 120 characters -- Python 3.10+ syntax - -### Testing Strategy -- Primary test framework: pytest -- Tests located in `tests/` directory -- End-to-end tests in `tests/scripts/` -- Benchmarks in `tests/benchmarks/` -- Extensive use of `@pytest.mark.parametrize` -- Shared fixtures in conftest.py -- Test isolation via custom pytest plugin - -### Key Dependencies -- **Core**: `libcst`, `jedi`, `gitpython`, `pydantic` -- **Testing**: `pytest`, `coverage`, `crosshair-tool` -- **Performance**: `line_profiler`, `timeout-decorator` -- **UI**: `rich`, `inquirer`, `click` -- **AI**: Custom API client for LLM interactions - -### Data Models & Types -- `codeflash/models/models.py` - Pydantic models for all data structures -- Extensive use of `@dataclass(frozen=True)` for immutable data -- Core types: `FunctionToOptimize`, `ValidCode`, `BenchmarkKey` - -## AI Service Integration - -### Rate Limiting & Retries -- Built-in rate limiting and exponential backoff -- Handle `Either` return types for error handling -- AI service endpoint: `codeflash/api/aiservice.py` - -### Telemetry & Monitoring -- **Sentry**: Error tracking with `codeflash.telemetry.sentry` -- **PostHog**: Usage analytics with `codeflash.telemetry.posthog_cf` -- **Environment Variables**: `CODEFLASH_EXPERIMENT_ID` for testing modes - -## Performance & Benchmarking - -### Line Profiler Integration -- Uses `line_profiler` for detailed performance analysis -- Instruments functions with `@profile` decorator -- Generates before/after profiling reports -- Calculates precise speedup measurements - -### Benchmark Test Framework -- Custom benchmarking in `tests/benchmarks/` -- Generates replay tests from execution traces -- Validates performance improvements statistically - -## Debugging & Development - -### Verbose Logging -```bash -uv run codeflash --verbose --file target_file.py +### Git worktree isolation +Optimizations run in isolated worktrees: +```python +from codeflash.code_utils.git_worktree_utils import create_detached_worktree, remove_worktree ``` -### Important Environment Variables -- `CODEFLASH_TEST_MODULE` - Current test module during verification -- `CODEFLASH_TEST_CLASS` - Current test class during verification -- `CODEFLASH_TEST_FUNCTION` - Current test function during verification -- `CODEFLASH_LOOP_INDEX` - Current iteration in pytest loops -- `CODEFLASH_EXPERIMENT_ID` - Enables local AI service for testing - -### LSP Integration -Language Server Protocol support in `codeflash/lsp/` enables IDE integration during optimization. - -### Common Debugging Patterns -1. Use verbose logging to trace optimization flow -2. Check git worktree operations for isolation issues -3. Verify deterministic test execution with environment variables -4. Use replay tests to debug specific optimization scenarios -5. Monitor AI service calls with rate limiting logs - -## Best Practices - -### Path Handling -- Always use absolute paths -- Handle encoding explicitly (UTF-8) -- Extensive path validation and cleanup utilities in `codeflash/code_utils/` - -### Git Operations -- All optimizations run in isolated worktrees -- Never modify the main repository directly -- Use git utilities in `codeflash/code_utils/git_utils.py` - -### Code Transformations -- Always use libcst, never ast module -- Preserve code formatting and comments -- Validate transformations with deterministic tests - -### Error Handling -- Use Either pattern for functional error handling -- Log errors to Sentry for monitoring -- Provide clear user feedback via Rich console +## Code Style & Conventions -### Performance Optimization -- Profile before and after changes -- Use benchmarks to validate improvements -- Generate detailed performance reports +- **Tooling**: Ruff for linting/formatting, mypy strict mode, pre-commit hooks +- **Line length**: 120 characters +- **Python**: 3.9+ syntax +- **Comments**: Minimal - only explain "why", not "what" +- **Docstrings**: Do not add unless explicitly requested +- **Naming**: Prefer public functions (no leading underscore) - Python doesn't have true private functions +- **Paths**: Always use absolute paths, handle encoding explicitly (UTF-8) # Agent Rules