weco 0.2.19__py3-none-any.whl → 0.2.22__py3-none-any.whl

{weco-0.2.19.dist-info → weco-0.2.22.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weco
-Version: 0.2.19
+Version: 0.2.22
 Summary: Documentation for `weco`, a CLI for using Weco AI's code optimizer.
 Author-email: Weco AI Team <contact@weco.ai>
 License: MIT
@@ -15,6 +15,7 @@ License-File: LICENSE
 Requires-Dist: requests
 Requires-Dist: rich
 Requires-Dist: packaging
+Requires-Dist: gitingest
 Provides-Extra: dev
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: build; extra == "dev"
@@ -23,12 +24,18 @@ Dynamic: license-file
 
 <div align="center">
 
-# Weco: The Platform for Self-Improving Code
+<div align="center">
+  <img src="assets/weco.svg" alt="Weco Logo" width="120" height="120" style="margin-bottom: 20px;">
+  <h1>Weco: The Platform for Self-Improving Code</h1>
+</div>
 
 [![Python](https://img.shields.io/badge/Python-3.8.0+-blue)](https://www.python.org)
 [![docs](https://img.shields.io/website?url=https://docs.weco.ai/&label=docs)](https://docs.weco.ai/)
 [![PyPI version](https://badge.fury.io/py/weco.svg)](https://badge.fury.io/py/weco)
 [![AIDE](https://img.shields.io/badge/AI--Driven_Exploration-arXiv-orange?style=flat-square&logo=arxiv)](https://arxiv.org/abs/2502.13138)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/WecoAI/weco-cli/blob/main/examples/hello-kernel-world/colab_notebook_walkthrough.ipynb)
+
+`pip install weco`
 
 </div>
 
@@ -48,7 +55,7 @@ Example applications include:
 
 ## Overview
 
-The `weco` CLI leverages a tree search approach guided by Large Language Models (LLMs) to iteratively explore and refine your code. It automatically applies changes, runs your evaluation script, parses the results, and proposes further improvements based on the specified goal.
+The `weco` CLI leverages a tree search approach guided by LLMs to iteratively explore and refine your code. It automatically applies changes, runs your evaluation script, parses the results, and proposes further improvements based on the specified goal.
 
 ![image](https://github.com/user-attachments/assets/a6ed63fa-9c40-498e-aa98-a873e5786509)
 
@@ -64,28 +71,48 @@ The `weco` CLI leverages a tree search approach guided by Large Language Models
 
 2.  **Set Up LLM API Keys (Required):**
 
-    `weco` requires API keys for the Large Language Models (LLMs) it uses internally. You **must** provide these keys via environment variables:
+    `weco` requires API keys for the LLMs it uses internally. You **must** provide these keys via environment variables:
 
-    - **OpenAI:** `export OPENAI_API_KEY="your_key_here"`
-    - **Anthropic:** `export ANTHROPIC_API_KEY="your_key_here"`
-    - **Google DeepMind:** `export GEMINI_API_KEY="your_key_here"` (Google AI Studio has a free API usage quota. Create a key [here](https://aistudio.google.com/apikey) to use `weco` for free.)
+    - **OpenAI:** `export OPENAI_API_KEY="your_key_here"` (Create your API key [here](https://platform.openai.com/api-keys))
+    - **Anthropic:** `export ANTHROPIC_API_KEY="your_key_here"` (Create your API key [here](https://console.anthropic.com/settings/keys))
+    - **Google:** `export GEMINI_API_KEY="your_key_here"` (Google AI Studio has a free API usage quota. Create your API key [here](https://aistudio.google.com/apikey) to use `weco` for free.)
 
 ---
 
 ## Get Started
 
+### Quick Start (Recommended for New Users)
+
+The easiest way to get started with Weco is to use the **interactive copilot**. Simply navigate to your project directory and run:
+
+```bash
+weco
+```
+
+Or specify a project path:
+
+```bash
+weco /path/to/your/project
+```
+
+This launches Weco's interactive copilot that will:
+
+1. **Analyze your codebase** using AI to understand your project structure and identify optimization opportunities
+2. **Suggest specific optimizations** tailored to your code (e.g., GPU kernel optimization, model improvements, prompt engineering)
+3. **Generate evaluation scripts** automatically or help you configure existing ones
+4. **Set up the complete optimization pipeline** with appropriate metrics and commands
+5. **Run the optimization** or provide you with the exact command to execute
+
 <div style="background-color: #fff3cd; border: 1px solid #ffeeba; padding: 15px; border-radius: 4px; margin-bottom: 15px;">
   <strong>⚠️ Warning: Code Modification</strong><br>
   <code>weco</code> directly modifies the file specified by <code>--source</code> during the optimization process. It is <strong>strongly recommended</strong> to use version control (like Git) to track changes and revert if needed. Alternatively, ensure you have a backup of your original file before running the command. Upon completion, the file will contain the best-performing version of the code found during the run.
 </div>
 
----
+### Manual Setup
 
-**Example: Optimizing Simple PyTorch Operations**
-
-This basic example shows how to optimize a simple PyTorch function for speedup.
+**Configure optimization parameters yourself** - If you need precise control over the optimization parameters, you can use the direct `weco run` command:
 
-For more advanced examples, including [Triton](/examples/triton/README.md), [CUDA kernel optimization](/examples/cuda/README.md), [ML model optimization](/examples/spaceship-titanic/README.md), and [prompt engineering for math problems](https://github.com/WecoAI/weco-cli/tree/main/examples/prompt), please see the `README.md` files within the corresponding subdirectories under the [`examples/`](./examples/) folder.
+**Example: Optimizing Simple PyTorch Operations**
 
 ```bash
 # Navigate to the example directory
@@ -94,7 +121,7 @@ cd examples/hello-kernel-world
 # Install dependencies
 pip install torch
 
-# Run Weco
+# Run Weco with manual configuration
 weco run --source optimize.py \
      --eval-command "python evaluate.py --solution-path optimize.py --device cpu" \
      --metric speedup \
@@ -105,36 +132,87 @@ weco run --source optimize.py \
 
 **Note:** If you have an NVIDIA GPU, change the device in the `--eval-command` to `cuda`. If you are running this on Apple Silicon, set it to `mps`.
 
+For more advanced examples, including [Triton](/examples/triton/README.md), [CUDA kernel optimization](/examples/cuda/README.md), [ML model optimization](/examples/spaceship-titanic/README.md), and [prompt engineering for math problems](examples/prompt/README.md), please see the `README.md` files within the corresponding subdirectories under the [`examples/`](examples/) folder.
+
 ---
 
 ### Arguments for `weco run`
 
 **Required:**
 
-| Argument            | Description                                                                                                                                                                                  |
-| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `-s, --source`      | Path to the source code file that will be optimized (e.g., `optimize.py`).                                                                                                                   |
-| `-c, --eval-command`| Command to run for evaluating the code in `--source`. This command should print the target `--metric` and its value to the terminal (stdout/stderr). See note below.                        |
-| `-m, --metric`      | The name of the metric you want to optimize (e.g., 'accuracy', 'speedup', 'loss'). This metric name should match what's printed by your `--eval-command`.                                    |
-| `-g, --goal`   | `maximize`/`max` to maximize the `--metric` or `minimize`/`min` to minimize it. |
+| Argument            | Description                                                                                                                                                                                  | Example               |
+| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------- |
+| `-s, --source`      | Path to the source code file that will be optimized.                                                                                                                   | `-s model.py`      |
+| `-c, --eval-command`| Command to run for evaluating the code in `--source`. This command should print the target `--metric` and its value to the terminal (stdout/stderr). See note below.                        | `-c "python eval.py"` |
+| `-m, --metric`      | The name of the metric you want to optimize (e.g., 'accuracy', 'speedup', 'loss'). This metric name does not need to match what's printed by your `--eval-command` exactly (e.g., its okay to use "speedup" instead of "Speedup:").                                    | `-m speedup`          |
+| `-g, --goal`        | `maximize`/`max` to maximize the `--metric` or `minimize`/`min` to minimize it.                                                                                                              | `-g maximize`         |
 
 <br>
 
 **Optional:**
 
-| Argument                       | Description                                                                                                                                                                                                                | Default |
-| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
-| `-n, --steps`                  | Number of optimization steps (LLM iterations) to run.                                                                                                                                                                      | 100 |
-| `-M, --model`                  | Model identifier for the LLM to use (e.g., `gpt-4o`, `claude-3.5-sonnet`).                                                                                                                                                 | `o4-mini` when `OPENAI_API_KEY` is set; `claude-3-7-sonnet-20250219` when `ANTHROPIC_API_KEY` is set; `gemini-2.5-pro-exp-03-25` when `GEMINI_API_KEY` is set (priority: `OPENAI_API_KEY` > `ANTHROPIC_API_KEY` > `GEMINI_API_KEY`). |
-| `-i, --additional-instructions`| Natural language description of specific instructions **or** path to a file containing detailed instructions to guide the LLM.                                                                                             | `None` |
-| `-l, --log-dir`                | Path to the directory to log intermediate steps and final optimization result.                                                                                                                                             | `.runs/` |
+| Argument                       | Description                                                                                                                                                                                                                | Default                                                                                                                                                | Example             |
+| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------ |
+| `-n, --steps`                  | Number of optimization steps (LLM iterations) to run.                                                                                                                                                                      | 100                                                                                                                                                     | `-n 50`             |
+| `-M, --model`                  | Model identifier for the LLM to use (e.g., `o4-mini`, `claude-sonnet-4-0`).                                                                                                        | `o4-mini` when `OPENAI_API_KEY` is set; `claude-sonnet-4-0` when `ANTHROPIC_API_KEY` is set; `gemini-2.5-pro` when `GEMINI_API_KEY` is set. | `-M o4-mini`         |
+| `-i, --additional-instructions`| Natural language description of specific instructions **or** path to a file containing detailed instructions to guide the LLM.                                                                                             | `None`                                                                                                                                                  | `-i instructions.md` or `-i "Optimize the model for faster inference"`|
+| `-l, --log-dir`                | Path to the directory to log intermediate steps and final optimization result.                                                                                                                                             | `.runs/`                                                                                                                                               | `-l ./logs/`        |
 
 ---
 
-### Weco Dashboard
-To associate your optimization runs with your Weco account and view them on the Weco dashboard, you can log in. `weco` uses a device authentication flow
+### Authentication & Dashboard
+
+Weco offers both **anonymous** and **authenticated** usage:
+
+#### Anonymous Usage
+You can use Weco without creating an account by providing LLM API keys via environment variables. This is perfect for trying out Weco or for users who prefer not to create accounts.
+
+#### Authenticated Usage (Recommended)
+To save your optimization runs and view them on the Weco dashboard, you can log in using Weco's secure device authentication flow:
+
+1. **During onboarding**: When you run `weco` for the first time, you'll be prompted to log in or skip
+2. **Manual login**: Use `weco logout` to clear credentials, then run `weco` again to re-authenticate
+3. **Device flow**: Weco will open your browser automatically and guide you through a secure OAuth-style authentication
+
 ![image (16)](https://github.com/user-attachments/assets/8a0a285b-4894-46fa-b6a2-4990017ca0c6)
 
+**Benefits of authenticated usage:**
+- **Run history**: View all your optimization runs on the Weco dashboard
+- **Progress tracking**: Monitor long-running optimizations remotely
+- **Enhanced support**: Get better assistance with your optimization challenges
+
+---
+
+## Command Reference
+
+### Basic Usage Patterns
+
+| Command | Description | When to Use |
+|---------|-------------|-------------|
+| `weco` | Launch interactive onboarding | **Recommended for beginners** - Analyzes your codebase and guides you through setup |
+| `weco /path/to/project` | Launch onboarding for specific project | When working with a project in a different directory |
+| `weco run [options]` | Direct optimization execution | **For advanced users** - When you know exactly what to optimize and how |
+| `weco logout` | Clear authentication credentials | To switch accounts or troubleshoot authentication issues |
+
+### Model Selection
+
+You can specify which LLM model to use with the `-M` or `--model` flag:
+
+```bash
+# Use with onboarding
+weco --model gpt-4o
+
+# Use with direct execution
+weco run --model claude-3.5-sonnet --source optimize.py [other options...]
+```
+
+**Available models:**
+- `gpt-4o`, `o4-mini` (requires `OPENAI_API_KEY`)
+- `claude-3.5-sonnet`, `claude-sonnet-4-20250514` (requires `ANTHROPIC_API_KEY`)
+- `gemini-2.5-pro` (requires `GEMINI_API_KEY`)
+
+If no model is specified, Weco automatically selects the best available model based on your API keys.
+
 ---
 
 ### Performance & Expectations
@@ -171,16 +249,16 @@ Weco will parse this output to extract the numerical value (1.5 in this case) as
 
 ## Contributing
 
-We welcome contributions! To get started:
+We welcome your contributions! To get started:
 
-1.  **Fork and Clone the Repository:**
+1.  **Fork & Clone the Repository:**
 
     ```bash
     git clone https://github.com/WecoAI/weco-cli.git
     cd weco-cli
     ```
 
-2.  **Install Development Dependencies:**
+2.  **Install Dependencies:**
 
     ```bash
     pip install -e ".[dev]"
@@ -192,8 +270,8 @@ We welcome contributions! To get started:
     git checkout -b feature/your-feature-name
     ```
 
-4.  **Make Your Changes:** Ensure your code adheres to our style guidelines and includes relevant tests.
+4.  **Make Changes:** Ensure your code adheres to our style guidelines and includes relevant tests.
 
-5.  **Commit and Push** your changes, then open a pull request with a clear description of your enhancements.
+5.  **Commit, Push & Open a PR**: Commit your changes, and open a pull request with a clear description of your enhancements.
 
 ---

weco-0.2.22.dist-info/RECORD

@@ -0,0 +1,14 @@
+weco/__init__.py,sha256=ClO0uT6GKOA0iSptvP0xbtdycf0VpoPTq37jHtvlhtw,303
+weco/api.py,sha256=X2b9iKhpXkEqmQWjecHcQruj0bRIiTpMOGGJMLpkCug,13827
+weco/auth.py,sha256=6bDQv07sx7uxA9CrN3HqUdCHV6nqXO41PGCicquvB00,9919
+weco/chatbot.py,sha256=H6d5yK9MB3pqpE7XVh_HAi1YAmxKy0v_xdozVSlKPCc,36959
+weco/cli.py,sha256=Jy7kQEsNKdV7Wds9Z0DIWBeLpEVyssIiOBiQ4zCl3Lw,7862
+weco/optimizer.py,sha256=z86-js_rvLMv3J8zCqvtc1xJC0EA0WqrN9_BlmX2RK4,23259
+weco/panels.py,sha256=Cnro4Q65n7GGh0FBXuB_OGSxRVobd4k5lOuBViTQaaM,15591
+weco/utils.py,sha256=5Pbhv_5wbTRv93Ws7aJfIOtcxeeqNrDRT3bV6YFOdgM,6032
+weco-0.2.22.dist-info/licenses/LICENSE,sha256=p_GQqJBvuZgkLNboYKyH-5dhpTDlKs2wq2TVM55WrWE,1065
+weco-0.2.22.dist-info/METADATA,sha256=EQ6vcDHjDyU5MbyNucVQU9LccJtz2i6wzghjMB25M6U,15251
+weco-0.2.22.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+weco-0.2.22.dist-info/entry_points.txt,sha256=ixJ2uClALbCpBvnIR6BXMNck8SHAab8eVkM9pIUowcs,39
+weco-0.2.22.dist-info/top_level.txt,sha256=F0N7v6e2zBSlsorFv-arAq2yDxQbzX3KVO8GxYhPUeE,5
+weco-0.2.22.dist-info/RECORD,,

{weco-0.2.19.dist-info → weco-0.2.22.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.7.1)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

weco-0.2.19.dist-info/RECORD

@@ -1,12 +0,0 @@
-weco/__init__.py,sha256=npWmRgLxfVK69GdyxIujnI87xqmPCBrZWxxAxL_QQOc,478
-weco/api.py,sha256=lJJ0j0-bABiQXDlRb43fCo7ky0N_HwfZgFdMktRKQ90,6635
-weco/auth.py,sha256=IPfiLthcNRkPyM8pWHTyDLvikw83sigacpY1PmeA03Y,2343
-weco/cli.py,sha256=eI468fxpMTfGPL-aX6EMYxh0NuaRxpaLVF_Jj2DiFhU,36383
-weco/panels.py,sha256=pM_YGnmcXM_1CBcxo_EAzOV3g_4NFdLS4MqDqx7THbA,13563
-weco/utils.py,sha256=LVTBo3dduJmhlbotcYoUW2nLx6IRtKs4eDFR52Qltcg,5244
-weco-0.2.19.dist-info/licenses/LICENSE,sha256=p_GQqJBvuZgkLNboYKyH-5dhpTDlKs2wq2TVM55WrWE,1065
-weco-0.2.19.dist-info/METADATA,sha256=3VBVsCqr7p332A10KsLr168GvOIKcCOWWfGDv8ViF7I,10729
-weco-0.2.19.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
-weco-0.2.19.dist-info/entry_points.txt,sha256=ixJ2uClALbCpBvnIR6BXMNck8SHAab8eVkM9pIUowcs,39
-weco-0.2.19.dist-info/top_level.txt,sha256=F0N7v6e2zBSlsorFv-arAq2yDxQbzX3KVO8GxYhPUeE,5
-weco-0.2.19.dist-info/RECORD,,