weco 0.3.2__tar.gz → 0.3.4__tar.gz

{weco-0.3.2 → weco-0.3.4}/.gitignore

@@ -89,3 +89,6 @@ repomix-output.*
 examples/extract-line-plot/predictions/
 examples/extract-line-plot/subset_line_*/
 examples/extract-line-plot/subset_line_*.zip
+
+# Example: prompt
+examples/prompt/.cache

{weco-0.3.2 → weco-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weco
-Version: 0.3.2
+Version: 0.3.4
 Summary: Documentation for `weco`, a CLI for using Weco AI's code optimizer.
 Author-email: Weco AI Team <contact@weco.ai>
 License: 
@@ -230,7 +230,7 @@ Dynamic: license-file
 
 <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>
+  <h1>Weco: The Code Optimization Agent</h1>
 </div>
 
 [![Python](https://img.shields.io/badge/Python-3.8.0+-blue)](https://www.python.org)
@@ -238,7 +238,7 @@ Dynamic: license-file
 [![docs](https://img.shields.io/website?url=https://docs.weco.ai/&label=docs)](https://docs.weco.ai/)
 [![PyPI Downloads](https://static.pepy.tech/badge/weco?color=4c1)](https://pepy.tech/projects/weco)
 [![arXiv on AIDE](https://img.shields.io/badge/arXiv-AIDE-b31b1b?logo=arxiv&logoColor=white)](https://arxiv.org/abs/2502.13138)
-[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg?labelColor=ffffff&color=F17E01)](https://colab.research.google.com/github/WecoAI/weco-cli/blob/main/examples/hello-kernel-world/colab_notebook_walkthrough.ipynb)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg?labelColor=ffffff&color=F17E01)](https://colab.research.google.com/github/WecoAI/weco-cli/blob/main/examples/hello-world/colab_notebook_walkthrough.ipynb)
 
 `pip install weco`
 
@@ -262,77 +262,32 @@ Example applications include:
 
 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)
 
----
-
-## Setup
-
-1.  **Install the Package:**
-
-    ```bash
-    pip install weco
-    ```
-
-2.  **Authenticate (Required):**
-
-    `weco` now uses a **credit-based billing system** with centralized LLM access. You need to authenticate to use the service:
-
-    - **Run the CLI**: `weco` will prompt you to authenticate via your web browser
-    - **Free Credits**: New users receive **free credits** upon signup
-    - **Centralized Keys**: All LLM provider API keys are managed by Weco (no BYOK required)
-    - **Credit Top-ups**: Purchase additional credits through the dashboard at [dashboard.weco.ai](https://dashboard.weco.ai)
-
----
-
-## 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:
+## Install the Package
 
 ```bash
-weco /path/to/your/project
+pip install weco
 ```
 
-This launches Weco's interactive copilot that will:
+## Getting Started
 
-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
+### Quickstart with an example project
 
 **Configure optimization parameters yourself** - If you need precise control over the optimization parameters, you can use the direct `weco run` command:
 
 **Example: Optimizing Simple PyTorch Operations**
 
 ```bash
-# Navigate to the example directory
-cd examples/hello-kernel-world
-
-# Install dependencies
-pip install torch
+git clone https://github.com/WecoAI/weco-cli.git
+cd weco-cli/examples/hello-world/
+pip install -r requirements.txt
 
-# Run Weco with manual configuration
-weco run --source optimize.py \
-     --eval-command "python evaluate.py --solution-path optimize.py --device cpu" \
+# Run Weco with configuration
+weco run --source module.py \
+     --eval-command "python evaluate.py --path module.py" \
      --metric speedup \
      --goal maximize \
-     --steps 15 \
+     --steps 10 \
      --additional-instructions "Fuse operations in the forward method while ensuring the max float deviation remains small. Maintain the same format of the code."
 ```
 
@@ -362,34 +317,12 @@ For more advanced examples, including [Triton](/examples/triton/README.md), [CUD
 | 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` | `-M o4-mini`         |
+| `-M, --model`                  | Model identifier for the LLM to use (e.g., `o4-mini`, `claude-sonnet-4-5`, `gpt-5`).                                                                                                        | `o4-mini` | `-M o4-mini`         |
 | `-i, --additional-instructions`| Natural language description of specific instructions **or** path to a file containing detailed instructions to guide the LLM. Supported file formats include - `.txt`, `.md`, and `.rst`.                                                                                             | `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/`        |
 | `--eval-timeout`       | Timeout in seconds for each step in evaluation.                                                                                                                                                                             | No timeout (unlimited)                                                                                                                                                  | `--eval-timeout 3600`             |
 | `--save-logs`          | Save execution output from each optimization step to disk. Creates timestamped directories with raw output files and a JSONL index for tracking execution history.                                                        | `False`                                                                                                                                                 | `--save-logs`       |
-
----
-
-### Authentication & Dashboard
-
-The CLI requires a Weco account for authentication and billing.
-
-#### Credit-Based Authentication (Required)
-Weco now requires authentication for all operations. This enables our credit-based billing system and provides access to powerful optimizations:
-
-1. **During onboarding**: When you run `weco` for the first time, you'll be prompted to log in
-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:**
-- **No API Key Management**: All LLM provider keys are managed centrally
-- **Cost Transparency**: See exactly how many credits each optimization consumes
-- **Free Trial**: Free credits to get started with optimization projects
-- **Run History**: View all your optimization runs on the Weco dashboard
-- **Progress Tracking**: Monitor long-running optimizations remotely
-- **Budget Control**: Set spending limits and auto top-up preferences
+| `--apply-change`       | Automatically apply the best solution to the source file without prompting.                                                                                                                                                | `False`                                                                                                                                                 | `--apply-change`       |
 
 ---
 
@@ -399,8 +332,6 @@ Weco now requires authentication for all operations. This enables our credit-bas
 
 | 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 resume <run-id>` | Resume an interrupted run | Continue from the last completed step |
 | `weco logout` | Clear authentication credentials | To switch accounts or troubleshoot authentication issues |
@@ -410,19 +341,23 @@ Weco now requires authentication for all operations. This enables our credit-bas
 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...]
+weco run --model gpt-5 --source optimize.py [other options...]
 ```
 
-**Available models:**
-- `o4-mini`, `o3-mini`, `gpt-4o` (OpenAI models)
-- `claude-sonnet-4-0`, `claude-opus-4-0` (Anthropic models)  
-- `gemini-2.5-pro`, `gemini-2.5-flash` (Google models)
+**Available models (30 total):**
+
+**OpenAI Models:**
+- GPT-5 Series: `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.1-codex-mini`, `gpt-5-codex`, `gpt-5-pro`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`
+- O-Series Reasoning: `o3-pro`, `o3`, `o3-mini`, `o4-mini`, `o1-pro`, `o1`, `codex-mini-latest`
+- GPT-4 Series: `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-4o`, `gpt-4o-mini`
+
+**Anthropic Claude (via Vertex AI):**
+- `claude-opus-4-5`, `claude-opus-4-1`, `claude-opus-4`, `claude-sonnet-4-5`, `claude-sonnet-4`, `claude-haiku-4-5`
+
+**Google Gemini:**
+- `gemini-3-pro-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`
 
-All models are available through Weco's centralized system. If no model is specified, Weco automatically selects the best model for your optimization task.
+All models are available through Weco. If no model is specified, Weco automatically selects the best model for your optimization task.
 
 ---
 
@@ -441,6 +376,7 @@ Arguments for `weco resume`:
 | Argument | Description | Example |
 |----------|-------------|---------|
 | `run-id` | The UUID of the run to resume (shown at the start of each run) | `0002e071-1b67-411f-a514-36947f0c4b31` |
+| `--apply-change` | Automatically apply the best solution to the source file without prompting | `--apply-change` |
 
 Notes:
 - Works only for interrupted runs (status: `error`, `terminated`, etc.).

{weco-0.3.2 → weco-0.3.4}/README.md

@@ -2,7 +2,7 @@
 
 <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>
+  <h1>Weco: The Code Optimization Agent</h1>
 </div>
 
 [![Python](https://img.shields.io/badge/Python-3.8.0+-blue)](https://www.python.org)
@@ -10,7 +10,7 @@
 [![docs](https://img.shields.io/website?url=https://docs.weco.ai/&label=docs)](https://docs.weco.ai/)
 [![PyPI Downloads](https://static.pepy.tech/badge/weco?color=4c1)](https://pepy.tech/projects/weco)
 [![arXiv on AIDE](https://img.shields.io/badge/arXiv-AIDE-b31b1b?logo=arxiv&logoColor=white)](https://arxiv.org/abs/2502.13138)
-[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg?labelColor=ffffff&color=F17E01)](https://colab.research.google.com/github/WecoAI/weco-cli/blob/main/examples/hello-kernel-world/colab_notebook_walkthrough.ipynb)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg?labelColor=ffffff&color=F17E01)](https://colab.research.google.com/github/WecoAI/weco-cli/blob/main/examples/hello-world/colab_notebook_walkthrough.ipynb)
 
 `pip install weco`
 
@@ -34,77 +34,32 @@ Example applications include:
 
 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)
 
----
-
-## Setup
-
-1.  **Install the Package:**
-
-    ```bash
-    pip install weco
-    ```
-
-2.  **Authenticate (Required):**
-
-    `weco` now uses a **credit-based billing system** with centralized LLM access. You need to authenticate to use the service:
-
-    - **Run the CLI**: `weco` will prompt you to authenticate via your web browser
-    - **Free Credits**: New users receive **free credits** upon signup
-    - **Centralized Keys**: All LLM provider API keys are managed by Weco (no BYOK required)
-    - **Credit Top-ups**: Purchase additional credits through the dashboard at [dashboard.weco.ai](https://dashboard.weco.ai)
-
----
-
-## 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:
+## Install the Package
 
 ```bash
-weco /path/to/your/project
+pip install weco
 ```
 
-This launches Weco's interactive copilot that will:
+## Getting Started
 
-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
+### Quickstart with an example project
 
 **Configure optimization parameters yourself** - If you need precise control over the optimization parameters, you can use the direct `weco run` command:
 
 **Example: Optimizing Simple PyTorch Operations**
 
 ```bash
-# Navigate to the example directory
-cd examples/hello-kernel-world
-
-# Install dependencies
-pip install torch
+git clone https://github.com/WecoAI/weco-cli.git
+cd weco-cli/examples/hello-world/
+pip install -r requirements.txt
 
-# Run Weco with manual configuration
-weco run --source optimize.py \
-     --eval-command "python evaluate.py --solution-path optimize.py --device cpu" \
+# Run Weco with configuration
+weco run --source module.py \
+     --eval-command "python evaluate.py --path module.py" \
      --metric speedup \
      --goal maximize \
-     --steps 15 \
+     --steps 10 \
      --additional-instructions "Fuse operations in the forward method while ensuring the max float deviation remains small. Maintain the same format of the code."
 ```
 
@@ -134,34 +89,12 @@ For more advanced examples, including [Triton](/examples/triton/README.md), [CUD
 | 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` | `-M o4-mini`         |
+| `-M, --model`                  | Model identifier for the LLM to use (e.g., `o4-mini`, `claude-sonnet-4-5`, `gpt-5`).                                                                                                        | `o4-mini` | `-M o4-mini`         |
 | `-i, --additional-instructions`| Natural language description of specific instructions **or** path to a file containing detailed instructions to guide the LLM. Supported file formats include - `.txt`, `.md`, and `.rst`.                                                                                             | `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/`        |
 | `--eval-timeout`       | Timeout in seconds for each step in evaluation.                                                                                                                                                                             | No timeout (unlimited)                                                                                                                                                  | `--eval-timeout 3600`             |
 | `--save-logs`          | Save execution output from each optimization step to disk. Creates timestamped directories with raw output files and a JSONL index for tracking execution history.                                                        | `False`                                                                                                                                                 | `--save-logs`       |
-
----
-
-### Authentication & Dashboard
-
-The CLI requires a Weco account for authentication and billing.
-
-#### Credit-Based Authentication (Required)
-Weco now requires authentication for all operations. This enables our credit-based billing system and provides access to powerful optimizations:
-
-1. **During onboarding**: When you run `weco` for the first time, you'll be prompted to log in
-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:**
-- **No API Key Management**: All LLM provider keys are managed centrally
-- **Cost Transparency**: See exactly how many credits each optimization consumes
-- **Free Trial**: Free credits to get started with optimization projects
-- **Run History**: View all your optimization runs on the Weco dashboard
-- **Progress Tracking**: Monitor long-running optimizations remotely
-- **Budget Control**: Set spending limits and auto top-up preferences
+| `--apply-change`       | Automatically apply the best solution to the source file without prompting.                                                                                                                                                | `False`                                                                                                                                                 | `--apply-change`       |
 
 ---
 
@@ -171,8 +104,6 @@ Weco now requires authentication for all operations. This enables our credit-bas
 
 | 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 resume <run-id>` | Resume an interrupted run | Continue from the last completed step |
 | `weco logout` | Clear authentication credentials | To switch accounts or troubleshoot authentication issues |
@@ -182,19 +113,23 @@ Weco now requires authentication for all operations. This enables our credit-bas
 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...]
+weco run --model gpt-5 --source optimize.py [other options...]
 ```
 
-**Available models:**
-- `o4-mini`, `o3-mini`, `gpt-4o` (OpenAI models)
-- `claude-sonnet-4-0`, `claude-opus-4-0` (Anthropic models)  
-- `gemini-2.5-pro`, `gemini-2.5-flash` (Google models)
+**Available models (30 total):**
+
+**OpenAI Models:**
+- GPT-5 Series: `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.1-codex-mini`, `gpt-5-codex`, `gpt-5-pro`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`
+- O-Series Reasoning: `o3-pro`, `o3`, `o3-mini`, `o4-mini`, `o1-pro`, `o1`, `codex-mini-latest`
+- GPT-4 Series: `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-4o`, `gpt-4o-mini`
+
+**Anthropic Claude (via Vertex AI):**
+- `claude-opus-4-5`, `claude-opus-4-1`, `claude-opus-4`, `claude-sonnet-4-5`, `claude-sonnet-4`, `claude-haiku-4-5`
+
+**Google Gemini:**
+- `gemini-3-pro-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`
 
-All models are available through Weco's centralized system. If no model is specified, Weco automatically selects the best model for your optimization task.
+All models are available through Weco. If no model is specified, Weco automatically selects the best model for your optimization task.
 
 ---
 
@@ -213,6 +148,7 @@ Arguments for `weco resume`:
 | Argument | Description | Example |
 |----------|-------------|---------|
 | `run-id` | The UUID of the run to resume (shown at the start of each run) | `0002e071-1b67-411f-a514-36947f0c4b31` |
+| `--apply-change` | Automatically apply the best solution to the source file without prompting | `--apply-change` |
 
 Notes:
 - Works only for interrupted runs (status: `error`, `terminated`, etc.).

weco-0.3.4/examples/README.md

@@ -0,0 +1,148 @@
+## Weco Examples
+
+Explore runnable examples that show how to use Weco to optimize ML models, prompts, and GPU kernels. Pick an example and get going in minutes.
+
+### Table of Contents
+
+- [Weco Examples](#weco-examples)
+  - [Table of Contents](#table-of-contents)
+  - [Prerequisites](#prerequisites)
+  - [Examples at a glance](#examples-at-a-glance)
+- [Quick starts](#quick-starts)
+  - [🧭 Hello World](#-hello-world)
+  - [⚡ Triton Optimization](#-triton-optimization)
+  - [🚀 CUDA Optimization](#-cuda-optimization)
+  - [🧠 Prompt Engineering](#-prompt-engineering)
+  - [📊 Extract Line Plot — Chart to CSV](#-extract-line-plot--chart-to-csv)
+  - [🛰️ Model Development — Spaceship Titanic](#️-model-development--spaceship-titanic)
+
+### Prerequisites
+
+- **Install the CLI**
+```bash
+pip install weco
+```
+
+### Examples at a glance
+
+| Example | Focus | Dependencies | Docs |
+| :-- | :-- | :-- | :-- |
+| 🧭 Hello World | Learn the Weco workflow on a small PyTorch model | `torch` | [README](hello-world/README.md) • [Colab](hello-world/colab_notebook_walkthrough.ipynb) |
+| ⚡ Triton Optimization | Speed up attention with Triton kernels | `numpy`, `torch`, `triton`, NVIDIA GPU | [README](triton/README.md) |
+| 🚀 CUDA Optimization | Generate low-level CUDA kernels for max speed | `ninja`, `numpy`, `torch`, `triton`, NVIDIA GPU, CUDA Toolkit | [README](cuda/README.md) |
+| 🧠 Prompt Engineering | Iteratively refine LLM prompts to improve accuracy | `openai`, `datasets`, OpenAI API key | [README](prompt/README.md) |
+| 📊 Agentic Scaffolding | Optimize agentic scaffolding for chart-to-CSV extraction | `openai`, `huggingface_hub`, `uv`, OpenAI API key | [README](extract-line-plot/README.md) |
+| 🛰️ Spaceship Titanic | Improve a Kaggle model training pipeline | `pandas`, `numpy`, `scikit-learn`, `torch`, `xgboost`, `lightgbm`, `catboost` | [README](spaceship-titanic/README.md) |
+
+---
+
+## Quick starts
+
+Minimal commands to run each example. For full context and explanations, see the linked READMEs.
+
+> **Tip**: Add `--apply-change` to any command below to automatically apply the best solution to your source file without prompting.
+
+### 🧭 Hello World
+
+```bash
+cd examples/hello-world
+pip install -r requirements.txt
+weco run --source module.py \
+     --eval-command "python evaluate.py --path module.py" \
+     --metric speedup \
+     --goal maximize \
+     --steps 15 \
+     --additional-instructions "Fuse operations in the forward method while ensuring the max float deviation remains small. Maintain the same format of the code."
+```
+- **Tip**: Use `--device cuda` (NVIDIA GPU) or `--device mps` (Apple Silicon).
+
+### ⚡ Triton Optimization
+
+- **Requirements**: NVIDIA GPU
+
+```bash
+cd examples/triton
+pip install -r requirements.txt
+weco run --source module.py \
+     --eval-command "python evaluate.py --path module.py" \
+     --metric speedup \
+     --goal maximize \
+     --steps 15 \
+     --model o4-mini \
+     --additional-instructions "Use a combination of triton and pytorch to optimize the forward pass while ensuring a small max float diff. Maintain the same code interface. Do not use any fallbacks. Assume any required dependencies are installed and data is already on the gpu." \
+     --eval-timeout 120
+```
+
+### 🚀 CUDA Optimization
+
+- **Requirements**: NVIDIA GPU and CUDA Toolkit
+- **Optional**: If compatible, install [flash attention](https://github.com/Dao-AILab/flash-attention?tab=readme-ov-file#installation-and-features) (`pip install flash-attn --no-build-isolation`)
+
+```bash
+cd examples/cuda
+pip install -r requirements.txt
+weco run --source module.py \
+     --eval-command "python evaluate.py --path module.py" \
+     --metric speedup \
+     --goal maximize \
+     --steps 50 \
+     --model gpt-5 \
+     --additional-instructions "Write in-line CUDA using pytorch's load_inline() to optimize the code while ensuring a small max float diff. Maintain the same code interface. Do not use any fallbacks and never use the build_directory arg for load_inline(). Assume any required dependencies are installed and data is already on the gpu." \
+     --eval-timeout 600
+```
+
+### 🧠 Prompt Engineering
+
+- **Requirements**: OpenAI API key (create [here](https://platform.openai.com/api-keys))
+- **Install Dependencies**: `pip install openai datasets`
+- **Run**:
+```bash
+cd examples/prompt
+export OPENAI_API_KEY="your_key_here"
+weco run --source optimize.py \
+     --eval-command "python eval.py" \
+     --metric score \
+     --goal maximize \
+     --steps 20 \
+     --model o4-mini \
+     --additional-instructions "Improve the prompt to get better scores. Focus on clarity, specificity, and effective prompt engineering techniques."
+```
+
+### 📊 Extract Line Plot — Chart to CSV
+
+- **Requirements**: OpenAI API key (create [here](https://platform.openai.com/api-keys))
+- **Install Dependencies**: `pip install uv openai huggingface_hub`
+- **Run**:
+```bash
+cd examples/extract-line-plot
+export OPENAI_API_KEY="your_key_here"
+uv run --with huggingface_hub python prepare_data.py  # prepare dataset
+weco run --source optimize.py \
+         --eval-command 'uv run --with openai python eval.py --max-samples 100 --num-workers 50' \
+         --metric accuracy \
+         --goal maximize \
+         --steps 20 \
+         --model gpt-5
+```
+
+### 🛰️ Model Development — Spaceship Titanic
+
+- **Install Dependencies**: `pip install pandas numpy scikit-learn torch xgboost lightgbm catboost`
+- **Run**:
+```bash
+cd examples/spaceship-titanic
+weco run --source train.py \
+     --eval-command "python evaluate.py --data-dir ./data --seed 0" \
+     --metric accuracy \
+     --goal maximize \
+     --steps 10 \
+     --model o4-mini \
+     --additional-instructions "Improve feature engineering, model choice and hyper-parameters." \
+     --log-dir .runs/spaceship-titanic
+```
+
+---
+
+If you're new to Weco, start with **Hello World**, then explore **Triton** and **CUDA** for kernel engineering, **Prompt Engineering** for optimzing an LLM's prompt, **Extract Line Plot** for optimzing agentic scaffolds, or try **Spaceship Titanic** for model development.
+
+

{weco-0.3.2 → weco-0.3.4}/examples/cuda/README.md

@@ -7,7 +7,8 @@ This approach aims for low-level optimization beyond standard PyTorch or even Tr
 
 Install the CLI and dependencies for the example:
 ```bash
-pip install weco ninja numpy torch triton
+pip install weco
+pip install -r requirements.txt
 ```
 > **Note:**
 > 1. This example requires a compatible NVIDIA GPU and the CUDA Toolkit installed on your system for compiling and running the generated CUDA code.
@@ -17,8 +18,8 @@ pip install weco ninja numpy torch triton
 
 Now run Weco to optimize your code:
 ```bash
-weco run --source optimize.py \
-     --eval-command "python evaluate.py --solution-path optimize.py" \
+weco run --source module.py \
+     --eval-command "python evaluate.py --path module.py" \
      --metric speedup \
      --goal maximize \
      --steps 50 \
@@ -29,8 +30,8 @@ weco run --source optimize.py \
 
 ### Explanation
 
-*   `--source optimize.py`: The initial PyTorch self-attention code to be optimized with CUDA.
-*   `--eval-command "python evaluate.py --solution-path optimize.py"`: Runs the evaluation script, which compiles (if necessary) and benchmarks the CUDA-enhanced code in `optimize.py` against a baseline, printing the `speedup`.
+*   `--source module.py`: The initial PyTorch self-attention code to be optimized with CUDA.
+*   `--eval-command "python evaluate.py --path module.py"`: Runs the evaluation script, which compiles (if necessary) and benchmarks the CUDA-enhanced code in `module.py` against a baseline, printing the `speedup`.
 *   `--metric speedup`: The optimization target metric.
 *   `--goal maximize`: Weco aims to increase the speedup.
 *   `--steps 50`: The number of optimization iterations.
@@ -38,7 +39,7 @@ weco run --source optimize.py \
 *   `--additional-instructions "..."`: Provides guidance to the LLM on the optimization approach.
 *   `--eval-timeout 600`: Stop runnning the evaluation script if it does not complete in 600 seconds.
 
-Weco will iteratively modify `optimize.py`, generating and integrating CUDA C++ code, guided by the evaluation results and the additional instructions provided.
+Weco will iteratively modify `module.py`, generating and integrating CUDA C++ code, guided by the evaluation results and the additional instructions provided.
 
 ## Next Steps
 

{weco-0.3.2 → weco-0.3.4}/examples/cuda/evaluate.py

@@ -77,7 +77,7 @@ if __name__ == "__main__":
     import argparse
 
     parser = argparse.ArgumentParser()
-    parser.add_argument("--solution-path", type=str, required=True)
+    parser.add_argument("--path", type=str, required=True)
     args = parser.parse_args()
 
     # setup local cache for PyTorch extensions
@@ -107,7 +107,7 @@ if __name__ == "__main__":
     # load solution module
     try:
         torch.manual_seed(0)
-        solution_module = load_module_from_path(args.solution_path, add_to_sys_modules=False)
+        solution_module = load_module_from_path(args.path, add_to_sys_modules=False)
         solution_model = solution_module.Model(
             n_embd=n_embd, n_head=n_head, attn_pdrop=attn_pdrop, resid_pdrop=resid_pdrop, max_seqlen=max_seqlen
         ).to("cuda")

weco-0.3.4/examples/cuda/requirements.txt

@@ -0,0 +1,4 @@
+ninja
+numpy
+torch
+triton