Merge branch 'main' into save-event-creator

Author: Saga4

codeflash/cli_cmds/cmd_init.py

@@ -22,7 +22,7 @@
 from codeflash.cli_cmds.console import console, logger
 from codeflash.code_utils.compat import LF
 from codeflash.code_utils.config_parser import parse_config_file
-from codeflash.code_utils.env_utils import get_codeflash_api_key
+from codeflash.code_utils.env_utils import check_formatter_installed, get_codeflash_api_key
 from codeflash.code_utils.git_utils import get_git_remotes, get_repo_owner_and_name
 from codeflash.code_utils.github_utils import get_github_secrets_page_url
 from codeflash.code_utils.shell_utils import get_shell_rc_path, save_api_key_to_rc
@@ -201,7 +201,7 @@ def collect_setup_info() -> SetupInfo:
             path_type=inquirer.Path.DIRECTORY,
         )
         if custom_module_root_answer:
-            module_root = Path(curdir) / Path(custom_module_root_answer["path"])
+            module_root = Path(custom_module_root_answer["path"])
         else:
             apologize_and_exit()
     else:
@@ -537,7 +537,7 @@ def install_github_actions(override_formatter_check: bool = False) -> None:  # n
             existing_api_key = None
         click.prompt(
             f"Next, you'll need to add your CODEFLASH_API_KEY as a secret to your GitHub repo.{LF}"
-            f"Press Enter to open your repo's secrets page at {get_github_secrets_page_url(repo)}…{LF}"
+            f"Press Enter to open your repo's secrets page at {get_github_secrets_page_url(repo)} {LF}"
             f"Then, click 'New repository secret' to add your api key with the variable name CODEFLASH_API_KEY.{LF}"
             f"{'Here is your CODEFLASH_API_KEY: ' + existing_api_key + ' ' + LF}"
             if existing_api_key
@@ -720,11 +720,7 @@ def configure_pyproject_toml(setup_info: SetupInfo) -> None:
         )
     elif formatter == "don't use a formatter":
         formatter_cmds.append("disabled")
-    if formatter in ["black", "ruff"]:
-        try:
-            subprocess.run([formatter], capture_output=True, check=False)
-        except (FileNotFoundError, NotADirectoryError):
-            click.echo(f"⚠️ Formatter not found: {formatter}, please ensure it is installed")
+    check_formatter_installed(formatter_cmds)
     codeflash_section["formatter-cmds"] = formatter_cmds
     # Add the 'codeflash' section, ensuring 'tool' section exists
     tool_section = pyproject_data.get("tool", tomlkit.table())
@@ -750,7 +746,7 @@ def install_github_app() -> None:
 
     else:
         click.prompt(
-            f"Finally, you'll need install the Codeflash GitHub app by choosing the repository you want to install Codeflash on.{LF}"
+            f"Finally, you'll need to install the Codeflash GitHub app by choosing the repository you want to install Codeflash on.{LF}"
             f"I will attempt to open the github app page - https://github.com/apps/codeflash-ai/installations/select_target {LF}"
             f"Press Enter to open the page to let you install the app…{LF}",
             default="",
@@ -924,6 +920,14 @@ def test_sort():
 
 
 def run_end_to_end_test(args: Namespace, bubble_sort_path: str, bubble_sort_test_path: str) -> None:
+    try:
+        check_formatter_installed(args.formatter_cmds)
+    except Exception:
+        logger.error(
+            "Formatter not found. Review the formatter_cmds in your pyproject.toml file and make sure the formatter is installed."
+        )
+        return
+
     command = ["codeflash", "--file", "bubble_sort.py", "--function", "sorter"]
     if args.no_pr:
         command.append("--no-pr")

codeflash/code_utils/env_utils.py

@@ -1,13 +1,52 @@
 from __future__ import annotations
 
 import os
+import shlex
+import subprocess
+import tempfile
 from functools import lru_cache
+from pathlib import Path
 from typing import Optional
 
 from codeflash.cli_cmds.console import logger
 from codeflash.code_utils.shell_utils import read_api_key_from_shell_config
 
 
+class FormatterNotFoundError(Exception):
+    """Exception raised when a formatter is not found."""
+
+    def __init__(self, formatter_cmd: str) -> None:
+        super().__init__(f"Formatter command not found: {formatter_cmd}")
+
+
+def check_formatter_installed(formatter_cmds: list[str]) -> bool:
+    return_code = True
+    if formatter_cmds[0] == "disabled":
+        return return_code
+    tmp_code = """print("hello world")"""
+    with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", suffix=".py") as f:
+        f.write(tmp_code)
+        f.flush()
+        tmp_file = Path(f.name)
+        file_token = "$file"  # noqa: S105
+        for command in set(formatter_cmds):
+            formatter_cmd_list = shlex.split(command, posix=os.name != "nt")
+            formatter_cmd_list = [tmp_file.as_posix() if chunk == file_token else chunk for chunk in formatter_cmd_list]
+            try:
+                result = subprocess.run(formatter_cmd_list, capture_output=True, check=False)
+            except (FileNotFoundError, NotADirectoryError):
+                return_code = False
+                break
+            if result.returncode:
+                return_code = False
+                break
+    tmp_file.unlink(missing_ok=True)
+    if not return_code:
+        msg = f"Error running formatter command: {command}"
+        raise FormatterNotFoundError(msg)
+    return return_code
+
+
 @lru_cache(maxsize=1)
 def get_codeflash_api_key() -> str:
     api_key = os.environ.get("CODEFLASH_API_KEY") or read_api_key_from_shell_config()

codeflash/optimization/function_optimizer.py

@@ -392,7 +392,7 @@ def determine_best_candidate(
             try:
                 candidate_index = 0
                 original_len = len(candidates)
-                while True:
+                while candidates:
                     done = True if future_line_profile_results is None else future_line_profile_results.done()
                     if done and (future_line_profile_results is not None):
                         line_profile_results = future_line_profile_results.result()
@@ -402,13 +402,7 @@ def determine_best_candidate(
                             f"Added results from line profiler to candidates, total candidates now: {original_len}"
                         )
                         future_line_profile_results = None
-                    try:
-                        candidate = candidates.popleft()
-                    except IndexError:
-                        if done:
-                            break
-                        time.sleep(0.1)
-                        continue
+                    candidate = candidates.popleft()
                     candidate_index += 1
                     get_run_tmp_file(Path(f"test_return_values_{candidate_index}.bin")).unlink(missing_ok=True)
                     get_run_tmp_file(Path(f"test_return_values_{candidate_index}.sqlite")).unlink(missing_ok=True)
@@ -517,8 +511,17 @@ def determine_best_candidate(
                     self.write_code_and_helpers(
                         self.function_to_optimize_source_code, original_helper_code, self.function_to_optimize.file_path
                     )
-                    if done and not candidates:
-                        break
+                    if (not len(candidates)) and (
+                        not done
+                    ):  # all original candidates processed but lp results haven't been processed
+                        concurrent.futures.wait([future_line_profile_results])
+                        line_profile_results = future_line_profile_results.result()
+                        candidates.extend(line_profile_results)
+                        original_len += len(line_profile_results)
+                        logger.info(
+                            f"Added results from line profiler to candidates, total candidates now: {original_len}"
+                        )
+                        future_line_profile_results = None
             except KeyboardInterrupt as e:
                 self.write_code_and_helpers(
                     self.function_to_optimize_source_code, original_helper_code, self.function_to_optimize.file_path

codeflash/optimization/optimizer.py

@@ -82,6 +82,8 @@ def run(self) -> None:
         console.rule()
         if not env_utils.ensure_codeflash_api_key():
             return
+        if not env_utils.check_formatter_installed(self.args.formatter_cmds):
+            return
         function_optimizer = None
         file_to_funcs_to_optimize: dict[Path, list[FunctionToOptimize]]
         num_optimizable_functions: int

docs/docs/getting-started/local-installation.md

@@ -8,6 +8,26 @@ Codeflash is installed and configured on a per-project basis.
 
 You can install Codeflash locally for a project by running the following command in the project's virtual environment:
 
+### Prerequisites
+
+Before installing Codeflash, ensure you have:
+
+1. **Python 3.9 or above** installed
+2. **A Python project** with a virtual environment
+3. **Project dependencies installed** in your virtual environment
+4. **Tests** (optional) for your code (Codeflash uses tests to verify optimizations)
+
+:::important[Virtual Environment Required]
+Always install Codeflash in your project's virtual environment, not globally. Make sure your virtual environment is activated before proceeding.
+
+```bash
+# Example: Activate your virtual environment
+source venv/bin/activate  # On Linux/Mac
+# or
+#venv\Scripts\activate     # On Windows
+```
+:::
+### Step 1: Install Codeflash
 ```bash
 pip install codeflash
 ```
@@ -16,22 +36,39 @@ pip install codeflash
 We recommend installing Codeflash as a development dependency.
 It doesn't need to be installed as part of your package requirements. 
 Codeflash is intended to be used locally and as part of development workflows such as CI.
+If using pyproject.toml:
+```toml
+[tool.poetry.dependencies.dev]
+codeflash = "^latest"
+```
+Or with pip:
+```bash
+pip install --dev codeflash
+````
 :::
 
-## Generate a Codeflash API Key
+### Step 2: Generate a Codeflash API Key
 
-Since Codeflash uses advanced Large Language Models (LLMs) that are hosted in the cloud, you will need to generate an API key to use Codeflash.
+Codeflash uses cloud-hosted AI models to optimize your code. You'll need an API key to use it.
 
-To generate an API key, visit the [Codeflash Web App](https://app.codeflash.ai/) and sign up for an account with GitHub login.
+1. Visit the [Codeflash Web App](https://app.codeflash.ai/) 
+2. Sign up with your GitHub account (free)
+3. Navigate to the [API Key](https://app.codeflash.ai/app/apikeys) page to generate your API key
 <!--- TODO: Do we ask for access to specific repositories here? --->
-Once you have signed up, you will be able to generate an API key from the [API Key](https://app.codeflash.ai/app/apikeys) page.
-You will need the API key in the next step.
 
-## Automatic Configuration
+:::note[Free Tier Available]
+Codeflash offers a **free tier** with a limited number of optimizations per month. Perfect for trying it out or small projects!
+:::
+
+### Step 3: Automatic Configuration
 
-To configure Codeflash for a project, in the root directory of your project where your `pyproject.toml` file is located, run the following command :
+Navigate to your project's root directory (where your `pyproject.toml` file is or should be) and run:
 
 ```bash
+# Make sure you're in your project root
+cd /path/to/your/project
+
+# Run the initialization
 codeflash init
 ```
 
@@ -56,11 +93,90 @@ After you have answered these questions, Codeflash will be configured for your p
 The configuration will be saved in the `pyproject.toml` file in the root directory of your project.
 To understand the configuration options, and set more advanced options, see the [Configuration](/configuration) page.
 
-## Install the Codeflash GitHub App
+### Step 4: Install the Codeflash GitHub App
 
+<!--- TODO: Justify to users Why we need the user to install Github App even in local Installation or local optimization? --->
 Finally, if you have not done so already, Codeflash will ask you to install the Github App in your repository.  The Codeflash GitHub App allows access to your repository to the codeflash-ai bot to open PRs, review code, and provide optimization suggestions.
 
 Please [install the Codeflash GitHub
 app](https://github.com/apps/codeflash-ai/installations/select_target) by choosing the repository you want to install
 Codeflash on.
 ## 
+
+## Try It Out!
+
+Once configured, you can start optimizing your code:
+
+```bash
+# Optimize a specific function
+codeflash --file path/to/your/file.py --function function_name
+
+# Or if want to optimize only locally without creating a PR
+codeflash --file path/to/your/file.py --function function_name --no-pr
+```
+
+### Example Project
+
+Want to see Codeflash in action? Check out our example repository:
+
+🔗 [github.com/codeflash-ai/optimize-me](https://github.com/codeflash-ai/optimize-me)
+
+This repo includes:
+- Sample Python code with performance issues
+- Tests for verification
+- Pre-configured `pyproject.toml`
+- Before/after optimization examples in PRs
+
+Clone it and try running:
+```bash
+git clone https://github.com/codeflash-ai/optimize-me.git
+cd optimize-me
+python -m venv .venv
+source .venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -r requirements.txt
+pip install codeflash
+codeflash init  # Use your own API key
+codeflash --all # optimize the entire repo
+```
+
+### 🔧 Troubleshooting
+
+#### 📦 "Module not found" errors
+Make sure:
+- ✅ Your virtual environment is activated
+- ✅ All project dependencies are installed
+- ✅ You're running `codeflash` from your project root
+
+#### 🧪 "No optimizations found" or debugging issues
+Use the `--verbose` flag for detailed output:
+```bash
+codeflash optimize --verbose
+```
+
+This will show:
+- 🔍 Which functions are being analyzed
+- 🚫 Why certain functions were skipped
+- ⚠️ Detailed error messages
+- 📊 Performance analysis results
+
+#### 🔍 "No tests found" errors
+Verify:
+- 📁 Your test directory path is correct in `pyproject.toml`
+- 🔍 Tests are discoverable by your test framework
+- 📝 Test files follow naming conventions (`test_*.py` for pytest)
+
+#### ⚙️ Configuration issues
+Check your `pyproject.toml`:
+```toml
+[tool.codeflash]
+module = "my_package"
+test-framework = "pytest"
+tests = "tests/"
+```
+
+### Next Steps
+
+- Learn about [Codeflash Concepts](/codeflash-concepts/how-codeflash-works)
+- Explore [optimization workflows](/optimizing-with-codeflash/one-function)
+- Set up [GitHub Actions integration](/getting-started/codeflash-github-actions)
+- Read [configuration options](/configuration) for advanced setups

docs/src/css/custom.css

@@ -28,3 +28,8 @@
   --ifm-color-primary-lightest: #FFECB3;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }
+
+[data-theme='dark'] {
+  /* Attempt to override Algolia's own CSS variables for the selected item's background */
+  --docsearch-highlight-color: #d08e0d !important;
+}

pyproject.toml

@@ -151,6 +151,7 @@ init_typed = true
 warn_required_dynamic_aliases = true
 
 [tool.ruff]
+target-version = "py39"
 line-length = 120
 fix = true
 show-fixes = true