diff --git a/docs/configuration.mdx b/docs/configuration.mdx index 3f388a531..b264f6bde 100644 --- a/docs/configuration.mdx +++ b/docs/configuration.mdx @@ -57,6 +57,15 @@ Optional Configuration: - `git-remote`: The git remote to use for pull requests. Defaults to `"origin"`. - `override-fixtures`: Override pytest fixtures during optimization. Defaults to `false`. +### Overriding configuration from the CLI + +You can temporarily override `pyproject.toml` settings when running the CLI: + +- **`--config-file PATH`**: Use a different `pyproject.toml` file. +- **`--module-root PATH`**: Override the configured `module-root`. +- **`--tests-root PATH`**: Override the configured `tests-root`. +- **`--benchmarks-root PATH`**: Override the configured `benchmarks-root` (also required when using `--benchmark` if it is not set here). + ## Example Configuration Here's an example project with the following structure: diff --git a/docs/editor-plugins/vscode/configuration.mdx b/docs/editor-plugins/vscode/configuration.mdx index d8a113a2d..f6b9c8509 100644 --- a/docs/editor-plugins/vscode/configuration.mdx +++ b/docs/editor-plugins/vscode/configuration.mdx @@ -40,14 +40,10 @@ The Codeflash extension provides a configuration interface in the sidebar where - The configuration page also appears automatically when: - - The extension detects your project needs configuration - - You need to update existing settings - - The extension detects configuration issues - - - - **Configuration is project-specific** — All settings are stored in your project's `pyproject.toml` file, not in VS Code settings. This ensures your configuration is version-controlled and shared with your team. + The configuration page appears automatically when the extension detects + configuration issues, and any changes you make are written to your project's + `pyproject.toml` file (so they are version-controlled and shared with your + team). --- diff --git a/docs/editor-plugins/vscode/features.mdx b/docs/editor-plugins/vscode/features.mdx index 5f8c76832..8ae634283 100644 --- a/docs/editor-plugins/vscode/features.mdx +++ b/docs/editor-plugins/vscode/features.mdx @@ -65,20 +65,11 @@ The **Optimization** tab is your main interface for selecting code to optimize. ![Optimization tab with file and function selectors](../../images/optimization-tab.png) -At the top of the Optimization tab, you'll find two dropdown selectors: +At the top of the Optimization tab, you'll find: -1. **FILE** — Select a Python file from your workspace - - - Click the dropdown to browse and select a Python file - - The placeholder shows "Select a Python file" until you make a selection - -2. **FUNCTION/METHOD** — Select a specific function to optimize - - - This dropdown is disabled until you select a file first - - Once a file is selected, it populates with all optimizable functions (qualified names) - - Functions are displayed with their fully qualified names (e.g., `MyClass.my_method` or `module.function_name`) - -3. **Optimize Button** — Click the **Optimize** button (with lightning bolt icon) to queue the selected function for optimization +1. **FILE** — pick a Python file from your workspace. +2. **FUNCTION/METHOD** — pick a specific function or method in that file. +3. **Optimize** — click the lightning button to queue that function for optimization. **Qualified Names** — Functions are displayed with their fully qualified @@ -123,93 +114,16 @@ When you first open the Optimization tab, you'll see a "Ready to Optimize" secti --- -## Tasks Tab - -The **Tasks** tab shows your optimization queue and completed optimizations. Switch to this tab to: - -- View all queued optimizations -- Track progress of running optimizations -- Review completed optimizations - -### Empty State - -When you haven't started any optimizations yet, the Tasks tab shows: - -- A rocket icon -- "No optimizations yet" message -- Instructions: "Add functions to the queue by clicking the small optimize button above a function" - -### Completed Optimizations - -Once optimizations complete, you'll see a list showing: - -![Completed optimizations list in Tasks tab](../../images/optimized-function-tab-tasks.png) -- **Function Name** — The name of the optimized function -- **Status Badge** — Shows completion status with speedup information: - - "Completed (Xx Faster)" — Displays the performance improvement - - Example: "Completed (2.5x Faster)" or "Completed (Speedup: 338.66x Faster)" -- **Optimization Quality** — Some optimizations show quality ratings (e.g., "Optimization Quality: High") -- **Actions:** - - **View Optimization** button — Opens the diff view to see changes and apply them - - **View PR** button — Opens the associated pull request (if optimization was created via PR) - - - The Tasks tab shows a badge count (e.g., "Tasks 19") indicating how many - optimization tasks you have in total. - - ---- - -## Optimization Workflow - -Once you've selected functions to optimize (via any method above), here's what happens: - - - - Selected functions are added to the optimization queue. You can see them in - the Tasks tab. - - - Watch the Tasks tab for real-time updates: - Generating optimization - candidates - Running tests to verify correctness - Benchmarking performance - - - When complete, you'll see the optimization in the Tasks tab with: - Speedup - information (e.g., "2.5x Faster") - Optimization quality rating - **View - Optimization** button to see the diff - - - Click **View Optimization** to see the full diff, then **Accept** to apply - the optimization, or **Reject** to dismiss it. - - - ---- - -## Reviewing Optimizations - -After an optimization completes, you can review it in the Tasks tab or via inline comments. - -![Detailed optimization explanation view](../../images/optimization-details-explaination.png) - -### In the Tasks Tab - -Click **View Optimization** on any completed optimization to see: - -- Side-by-side comparison of original vs. optimized code -- Performance improvement percentage (speedup) -- Runtime comparison (original vs. optimized) -- Optimization quality rating -- Detailed explanation of what changed and why -- **Apply Optimization** button to accept the changes +## Tasks Tab and reviewing optimizations -### Inline Comments +The **Tasks** tab shows your optimization queue and completed optimizations. You can: -The extension also shows inline comments on the optimized function in your editor with options to: +- See which functions are queued or running +- Inspect completed optimizations, including speedup and quality +- Open the related PR (when the optimization was created via PR) -- **View Patch** — See the full diff of changes -- **Accept** — Apply the optimization to your code -- **Reject** — Dismiss the suggestion without changes +Click **View Optimization** on any completed item to see the diff and explanation, then apply or reject the changes. +You will also see inline comments on optimized functions in the editor with actions to **View Patch**, **Accept**, or **Reject**. --- diff --git a/docs/editor-plugins/vscode/index.mdx b/docs/editor-plugins/vscode/index.mdx index 8cf0f3b10..c5e6fc519 100644 --- a/docs/editor-plugins/vscode/index.mdx +++ b/docs/editor-plugins/vscode/index.mdx @@ -102,18 +102,9 @@ When you first open a Python file, the extension guides you through setup: **This step is critical.** The extension uses the Python interpreter selected in VS Code to run Codeflash. Make sure you select the interpreter from the environment where Codeflash is installed. - - - 1. Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS) - 2. Type **"Python: Select Interpreter"** - 3. Choose the Python environment where you installed Codeflash (e.g., your project's virtual environment) - - - 1. Look at the bottom-left status bar in VS Code - 2. Click on the Python version shown - 3. Select your project's Python interpreter from the list - - + 1. Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS) + 2. Type **"Python: Select Interpreter"** + 3. Pick the environment where you installed Codeflash (for example, your project virtual environment) If you see "No Python interpreter selected" or "Codeflash not installed" errors, verify that: @@ -135,7 +126,8 @@ When you first open a Python file, the extension guides you through setup: - Click **"Sign in with Browser"** to authenticate via OAuth. This opens your browser where you can log in with your Codeflash account. + - Click **"Sign in with Browser"** + - Log in with your Codeflash account in the browser This is the easiest method — no need to copy/paste API keys! @@ -145,9 +137,9 @@ When you first open a Python file, the extension guides you through setup: If you prefer to use an API key, you can: - 1. **Generate an API key** in the [Codeflash web app](https://app.codeflash.ai) - 2. **Copy the API key** from your account settings - 3. **Paste it** into the extension's authentication prompt + 1. Generate an API key in the [Codeflash web app](https://app.codeflash.ai) + 2. Copy the API key from your account settings + 3. Paste it into the extension's authentication prompt Don't have an account? [Sign up free at app.codeflash.ai](https://app.codeflash.ai/login) diff --git a/docs/editor-plugins/vscode/troubleshooting.mdx b/docs/editor-plugins/vscode/troubleshooting.mdx index 09a408ec1..69b5f6b03 100644 --- a/docs/editor-plugins/vscode/troubleshooting.mdx +++ b/docs/editor-plugins/vscode/troubleshooting.mdx @@ -29,8 +29,7 @@ Solutions for common issues with the Codeflash VS Code extension. **Solutions:** 1. **Check Python file is open** — The extension activates when you open a `.py` file 2. **Verify Python extension** — Ensure Microsoft Python extension is installed - 3. **Check Output logs** — Go to `View → Output` and select "Codeflash" from the dropdown - 4. **Reload extension** — Restart VS Code or reload the window + 3. **Reload extension** — Restart VS Code or reload the window @@ -83,7 +82,7 @@ Solutions for common issues with the Codeflash VS Code extension. 1. **Reload extension** — Restart VS Code or reload the window 2. **Check network** — Ensure you can reach `app.codeflash.ai` 3. **Verify API key** — Check your API key is valid - 4. **View logs** — Check `View → Output → Codeflash` for details + 4. **View logs** — See the "Viewing Logs" section below diff --git a/docs/getting-started/local-installation.mdx b/docs/getting-started/local-installation.mdx index 9642a401d..5144300a5 100644 --- a/docs/getting-started/local-installation.mdx +++ b/docs/getting-started/local-installation.mdx @@ -176,6 +176,20 @@ codeflash --all # optimize the entire repo +### Common CLI flags + +For everyday use, these are the most important flags: + +- **`--file PATH`**: Optimize only this file. +- **`--function NAME`**: Optimize only this function (requires `--file`). +- **`--all [PATH]`**: Optimize all functions, optionally under a path. +- **`--no-pr`**: Apply changes locally instead of creating a pull request. +- **`--no-gen-tests`**: Use only existing tests, skip test generation. +- **`--benchmark` / `--benchmarks-root PATH`**: Enable benchmark mode and point to the benchmarks directory. +- **`--verbose` / `-v`**: Show detailed logs of what Codeflash is doing. +- **`--verify-setup`**: Run a sample optimization to verify your installation. +- **`--version`**: Print the Codeflash CLI version. + ## Troubleshooting diff --git a/docs/optimizing-with-codeflash/benchmarking.mdx b/docs/optimizing-with-codeflash/benchmarking.mdx index ade7eb023..9c4b35392 100644 --- a/docs/optimizing-with-codeflash/benchmarking.mdx +++ b/docs/optimizing-with-codeflash/benchmarking.mdx @@ -74,6 +74,12 @@ It will then try to optimize the new code for the benchmark and calculate the im codeflash --file test_file.py --benchmark --benchmarks-root path/to/benchmarks ``` + + If you see **"benchmarks-root must be specified"**, either set + `benchmarks-root` in your `pyproject.toml` or pass + `--benchmarks-root` on the CLI. + + 4. **Run Codeflash :** Benchmark mode is best used together with Codeflash as a GitHub Action. This way, diff --git a/docs/optimizing-with-codeflash/one-function.mdx b/docs/optimizing-with-codeflash/one-function.mdx index 8f60db0a7..5ff60be37 100644 --- a/docs/optimizing-with-codeflash/one-function.mdx +++ b/docs/optimizing-with-codeflash/one-function.mdx @@ -37,6 +37,11 @@ If you want to optimize a function locally, you can add a `--no-pr` argument as codeflash --file path/to/your/file.py --function function_name --no-pr ``` + + If you see **"Functions outside module-root"**, make sure the file lives + under the `module-root` directory configured in your `pyproject.toml`. + + ### Optimizing class methods To optimize a method `method_name` in a class `ClassName`, you can run the following command: diff --git a/docs/optimizing-with-codeflash/trace-and-optimize.mdx b/docs/optimizing-with-codeflash/trace-and-optimize.mdx index 3f4e23465..6a7f746bd 100644 --- a/docs/optimizing-with-codeflash/trace-and-optimize.mdx +++ b/docs/optimizing-with-codeflash/trace-and-optimize.mdx @@ -100,6 +100,12 @@ Codeflash script optimizer can be used in three ways: - `--timeout`: The maximum time in seconds to trace the entire workflow. Default is indefinite. This is useful while tracing really long workflows. + + Replay test files are named based on the traced script path. If you are + unsure where they were written, list files like + `tests/test_*replay*.py` in your tests directory. + + 3. **As a Context Manager -** To trace only specific sections of your code, You can also use the Codeflash Tracer as a context manager.