optimize dashboard

2026-09-09 20:10:19 -04:00 · 2025-12-29 22:00:59 +05:00
850 changed files with 25113 additions and 104221 deletions
@@ -0,0 +1,12 @@
+name: Type Check
+
+description: "Run type checker"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Run type checker
+      run: |
+        nix --extra-experimental-features nix-command --extra-experimental-features flakes develop -c just sync
+        nix --extra-experimental-features nix-command --extra-experimental-features flakes develop -c just check
+      shell: bash
@@ -0,0 +1,159 @@
+# EXO Benchmark Dashboard
+
+A fully self-contained, browser-based dashboard for tracking EXO benchmark performance over time.
+
+## Features
+
+- 📊 **Success Rate Tracking**: Monitor cluster reliability across commits
+- ⚡ **Response Time Analysis**: Track average request completion times  
+- 🎯 **Throughput Metrics**: Tokens per second visualization
+- 📈 **Request Distribution**: Success/failure breakdown over time
+- 🔄 **Auto-Refresh**: Updates every 60 seconds
+- 📺 **TV-Ready**: Large, clear visualizations perfect for display
+- 🔐 **Secure**: Credentials stored in browser localStorage only
+- 🌐 **No Backend**: Directly accesses S3 from the browser
+
+## Quick Start
+
+### Option 1: Direct File Access (Simplest)
+
+Just open the HTML file directly in your browser:
+
+```bash
+open .github/benchmark-dashboard/index.html
+```
+
+Then click "Configure AWS Credentials" and enter your keys.
+
+### Option 2: URL Parameters (For Quick Setup)
+
+```bash
+# Serve with credentials in URL (they'll be moved to localStorage)
+open ".github/benchmark-dashboard/index.html?accessKey=YOUR_KEY&secretKey=YOUR_SECRET&region=us-east-1"
+```
+
+The credentials will be saved to localStorage and removed from the URL immediately.
+
+### Option 3: Simple HTTP Server
+
+```bash
+# From repo root
+python3 -m http.server 8080
+
+# Then open: http://localhost:8080/.github/benchmark-dashboard/
+```
+
+## AWS Credentials
+
+The dashboard needs read-only access to the `exo-benchmark-results` S3 bucket.
+
+### Required IAM Permissions
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:GetObject",
+        "s3:ListBucket"
+      ],
+      "Resource": [
+        "arn:aws:s3:::exo-benchmark-results",
+        "arn:aws:s3:::exo-benchmark-results/*"
+      ]
+    }
+  ]
+}
+```
+
+### Security Notes
+
+- ✅ Credentials stored in browser `localStorage` only
+- ✅ Never sent to any server (except AWS)
+- ✅ All S3 access happens client-side
+- ✅ Use read-only IAM credentials
+- ⚠️ Don't commit credentials to git
+- ⚠️ Use a dedicated read-only IAM user
+
+## TV/Kiosk Mode
+
+For permanent display on a TV:
+
+### macOS
+```bash
+open -a "Google Chrome" --args --kiosk ".github/benchmark-dashboard/index.html"
+```
+
+### Linux
+```bash
+chromium-browser --kiosk --app="file://$(pwd)/.github/benchmark-dashboard/index.html"
+```
+
+### Auto-start on Boot
+
+Create a simple startup script:
+
+```bash
+#!/bin/bash
+# /usr/local/bin/start-benchmark-dashboard.sh
+
+cd /path/to/exo
+python3 -m http.server 8080 &
+sleep 2
+chromium-browser --kiosk http://localhost:8080/.github/benchmark-dashboard/
+```
+
+## Data Displayed
+
+### Summary Cards
+- **Latest Success Rate**: Most recent benchmark success percentage with trend
+- **Avg Response Time**: Latest average response time in ms with trend
+- **Total Benchmarks**: Count of all benchmarks run
+- **Active Configurations**: Number of unique benchmark configs
+
+### Charts
+1. **Success Rate Over Time**: Line chart showing reliability trends
+2. **Average Response Time**: Performance over time (lower is better)
+3. **Throughput**: Tokens/second metric (higher is better)
+4. **Request Distribution**: Stacked bar chart of successes/failures
+
+## How It Works
+
+1. **Loads AWS SDK**: Uses AWS SDK for JavaScript (browser version)
+2. **Lists S3 Objects**: Fetches all files from `s3://exo-benchmark-results/bench/`
+3. **Downloads Results**: Fetches each JSON result file
+4. **Parses & Visualizes**: Uses Chart.js to create interactive charts
+5. **Auto-Refreshes**: Polls S3 every 60 seconds for new results
+
+## Customization
+
+To modify the dashboard:
+
+1. Edit `index.html` 
+2. Adjust `REFRESH_INTERVAL` for different polling frequency
+3. Modify chart colors/styles in the Chart.js configuration
+4. Add new metrics by extending the results parsing
+
+## Troubleshooting
+
+**"AWS credentials not configured"**
+- Click "Configure AWS Credentials" and enter your keys
+
+**"Error loading benchmark data"**
+- Check AWS credentials are correct
+- Verify S3 bucket name is `exo-benchmark-results`
+- Ensure IAM user has read permissions
+- Check browser console for detailed errors
+
+**"No benchmark results found"**
+- Wait for benchmark workflows to run
+- Verify results are being uploaded to S3
+- Check S3 bucket has files in `bench/` prefix
+
+**Charts not updating**
+- Check browser console for errors
+- Verify network connectivity to S3
+- Try refreshing the page manually
+
@@ -0,0 +1,186 @@
+# EXO Benchmark Configurations
+
+This directory contains configuration files for the EXO staged benchmark system.
+
+## Overview
+
+The staged benchmark system allows you to run complex, multi-stage load tests against EXO clusters. Each stage can have different characteristics:
+
+- **Prompt Length**: Number of tokens in the input prompt
+- **Generation Length**: Maximum tokens to generate in the response
+- **Time Between Requests**: Delay (in seconds) between firing consecutive requests
+- **Iterations**: Number of requests to send in this stage
+
+Requests are **fire-and-forget** - they don't wait for the previous request to complete. This allows you to test overlapping request handling and measure success rates under load.
+
+## Configuration Files
+
+### `bench_simple.yaml`
+A minimal configuration that replicates the behavior of the original `bench.py` script:
+- Single stage with 1 iteration
+- Short prompt (~20 tokens)
+- Generates up to 100 tokens
+
+This is useful for quick smoke tests.
+
+### `bench_config.yaml`
+A comprehensive multi-stage benchmark with:
+1. **Warmup** (10 requests): Light load with short prompts
+2. **Medium Load** (20 requests): Moderate load with medium prompts
+3. **Stress Test** (30 requests): Heavy overlapping requests with long prompts
+4. **Cooldown** (5 requests): Light load to wind down
+
+This tests the cluster's behavior under varying load patterns.
+
+## Configuration Schema
+
+```yaml
+# Hardware configuration - maps runner labels to instance counts
+hardware_plan:
+  M3ULTRA_GPU80_512GB: 4
+
+# Environment variables to set on each node (optional)
+environment:
+  OVERRIDE_MEMORY_MB: 512
+
+# Timeout for instance and runner readiness (seconds)
+timeout_seconds: 600
+
+# Model instances to run concurrently
+model_ids:
+  - "mlx-community/Llama-3.2-1B-Instruct-4bit"
+
+# Benchmark stages
+stages:
+  - name: "stage_name"              # Human-readable name for this stage
+    prompt_length: 100               # Target prompt length in tokens
+    generation_length: 200           # Max tokens to generate
+    time_between_requests: 2.0       # Seconds between firing requests
+    iterations: 10                   # Number of requests in this stage
+```
+
+## Running Benchmarks
+
+### Via GitHub Actions
+
+**Automatic (every commit):**
+- The **`bench`** workflow runs automatically on every push
+- Uses `bench_simple.yaml` as the default configuration
+- All settings (hardware plan, timeout, environment variables, models, stages) are defined in the config file
+
+**Manual (on-demand):**
+1. Go to **Actions** → **bench** workflow
+2. Click **Run workflow**
+3. Configure:
+   - **Config File**: Path to your YAML config (default: `.github/configs/bench_simple.yaml`)
+     - `.github/configs/bench_simple.yaml` for quick tests
+     - `.github/configs/bench_config.yaml` for complex multi-stage tests
+   
+All other settings (hardware plan, timeout, environment variables, models, stages) are read from the specified config file.
+
+### Via Command Line
+
+```bash
+# Start EXO on localhost:8000
+uv run exo --api-port 8000
+
+# Run simple benchmark (1 stage, 1 iteration)
+python3 .github/scripts/bench.py \
+  --api-port 8000 \
+  --config .github/configs/bench_simple.yaml \
+  --expected-nodes 1 \
+  --is-primary true \
+  --timeout-seconds 600
+
+# Run complex staged benchmark (4 stages, multiple iterations)
+python3 .github/scripts/bench.py \
+  --api-port 8000 \
+  --config .github/configs/bench_config.yaml \
+  --expected-nodes 1 \
+  --is-primary true \
+  --timeout-seconds 600
+```
+
+## Output Metrics
+
+For each stage, the benchmark reports:
+
+- **Total Requests**: Number of requests fired
+- **Successful Requests**: Requests that completed successfully
+- **Failed Requests**: Requests that encountered errors
+- **Success Rate**: Percentage of successful requests
+- **Total Tokens**: Sum of all tokens generated across successful requests
+- **Avg Tokens/Request**: Average tokens per successful request
+- **Avg Time/Request**: Average completion time per successful request
+
+A JSON summary is also printed for easy parsing and storage.
+
+## Creating Custom Benchmarks
+
+To create a custom benchmark:
+
+1. Copy an existing config file (e.g., `bench_config.yaml`)
+2. Modify the stages to match your test scenario
+3. Save it in this directory with a descriptive name
+4. Run it using the workflow or command line
+
+### Example: Sustained Load Test
+
+```yaml
+hardware_plan:
+  M3ULTRA_GPU80_512GB: 2
+
+environment:
+  OVERRIDE_MEMORY_MB: 1024
+
+timeout_seconds: 600
+
+model_ids:
+  - "mlx-community/Llama-3.2-1B-Instruct-4bit"
+
+stages:
+  - name: "sustained_load"
+    prompt_length: 200
+    generation_length: 150
+    time_between_requests: 0.5     # Very fast - 2 requests/second
+    iterations: 100                 # Run for ~50 seconds
+```
+
+### Example: Varying Prompt Sizes
+
+```yaml
+hardware_plan:
+  M4PRO_GPU16_24GB: 3
+
+timeout_seconds: 900
+
+model_ids:
+  - "mlx-community/Llama-3.2-1B-Instruct-4bit"
+
+stages:
+  - name: "tiny_prompts"
+    prompt_length: 10
+    generation_length: 100
+    time_between_requests: 1.0
+    iterations: 10
+    
+  - name: "medium_prompts"
+    prompt_length: 200
+    generation_length: 100
+    time_between_requests: 1.0
+    iterations: 10
+    
+  - name: "large_prompts"
+    prompt_length: 1000
+    generation_length: 100
+    time_between_requests: 1.0
+    iterations: 10
+```
+
+## Tips
+
+- **Overlapping Requests**: Set `time_between_requests` < expected completion time to test concurrent request handling
+- **Sequential Requests**: Set `time_between_requests` > expected completion time to ensure requests don't overlap
+- **Realistic Load**: Model real usage patterns by varying prompt/generation lengths across stages
+- **Success Rate**: A 100% success rate indicates the cluster handled the load well; lower rates suggest capacity limits
+
@@ -0,0 +1,49 @@
+# EXO Staged Benchmark Configuration
+# This configuration defines a multi-stage load test for EXO clusters
+
+# Hardware configuration - maps runner labels to instance counts
+hardware_plan:
+  M3ULTRA_GPU80_512GB: 4
+
+# Environment variables to set on each node (optional)
+environment:
+  OVERRIDE_MEMORY_MB: 512
+
+# Timeout for instance and runner readiness (seconds)
+timeout_seconds: 600
+
+# Multiple instances run concurrently on the cluster
+model_ids:
+  - "mlx-community/Qwen3-0.6B-4bit"
+  - "mlx-community/Qwen3-0.6B-4bit"
+
+# Stages run sequentially, each with its own characteristics
+stages:
+  # Stage 1: Light load with short prompts
+  - name: "warmup"
+    prompt_length: 50          # Number of tokens in prompt
+    generation_length: 100     # Max tokens to generate
+    time_between_requests: 5.0 # Seconds between firing requests
+    iterations: 10             # Number of requests to send in this stage
+    
+  # Stage 2: Medium load with medium prompts
+  - name: "medium_load"
+    prompt_length: 200
+    generation_length: 150
+    time_between_requests: 3.0
+    iterations: 20
+    
+  # Stage 3: Heavy load with long prompts - requests will overlap
+  - name: "stress_test"
+    prompt_length: 500
+    generation_length: 200
+    time_between_requests: 1.0  # Fast firing - will definitely overlap
+    iterations: 30
+    
+  # Stage 4: Cool down with simple prompts
+  - name: "cooldown"
+    prompt_length: 50
+    generation_length: 50
+    time_between_requests: 10.0
+    iterations: 5
+
@@ -0,0 +1,125 @@
+# Simple single-shot benchmark
+# Tests 2 instances concurrently on 2 nodes
+
+# Hardware configuration - maps runner labels to instance counts
+hardware_plan:
+  puffin4: 1
+  puffin8: 1
+
+# Environment variables to set on each node
+environment:
+  PLACEHOLDER: "placeholder"
+  # OVERRIDE_MEMORY_MB: 50000
+  MLX_METAL_FAST_SYNCH: 1
+
+# Timeout for instance and runner readiness (seconds)
+timeout_seconds: 1800
+
+# Model instances to run concurrently
+model_ids:
+  # - "mlx-community/DeepSeek-V3.1-8bit"
+  # - "mlx-community/Kimi-K2-Instruct-4bit"
+  - "mlx-community/Kimi-K2-Thinking"
+  # - "mlx-community/Qwen3-235B-A22B-4bit"
+  # - "mlx-community/Llama-3.3-70B-Instruct-4bit"
+  # - "mlx-community/Llama-3.3-70B-Instruct-8bit"
+  # - "mlx-community/Llama-3.2-1B-Instruct-4bit"
+
+# Sharding strategy: "Pipeline" or "Tensor"
+sharding: "Tensor"
+
+# Instance type: "MlxRing" or "MlxIbv"
+instance_meta: "MlxIbv"
+
+# If true, run requests sequentially (no overlap); if false, fire-and-forget (default: false)
+no_overlap: true
+
+# Benchmark stages
+# pp: 64, 256, 1024, 2048, 4096, 8192, 16384
+# g: 64, 512
+stages:
+  # - name: "simple"
+  #   prompt_length: 512
+  #   generation_length: 10
+  #   time_between_requests: 2.0
+  #   iterations: 5
+  # - name: "pp64_g64"
+  #   prompt_length: 64
+  #   generation_length: 64
+  #   time_between_requests: 2.0
+  #   iterations: 5
+  # - name: "pp64_g64"
+  #   prompt_length: 64
+  #   generation_length: 64
+  #   time_between_requests: 2.0
+  #   iterations: 5
+  # - name: "pp64_g512"
+  #   prompt_length: 64
+  #   generation_length: 512
+  #   time_between_requests: 2.0
+  #   iterations: 10
+  # - name: "pp256_g64"
+  #   prompt_length: 256
+  #   generation_length: 64
+  #   time_between_requests: 2.0
+  #   iterations: 5
+  - name: "pp256_g64"
+    prompt_length: 256
+    generation_length: 64
+    time_between_requests: 2.0
+    iterations: 5
+  # - name: "pp256_g512"
+  #   prompt_length: 256
+  #   generation_length: 512
+  #   time_between_requests: 2.0
+  #   iterations: 10
+  # - name: "pp1024_g64"
+  #   prompt_length: 1024
+  #   generation_length: 64
+  #   time_between_requests: 2.0
+  #   iterations: 5
+  # - name: "pp1024_g512"
+  #   prompt_length: 1024
+  #   generation_length: 512
+  #   time_between_requests: 2.0
+  #   iterations: 10
+  # - name: "pp2048_g64"
+  #   prompt_length: 2048
+  #   generation_length: 64
+  #   time_between_requests: 2.0
+  #   iterations: 5
+  # - name: "pp2048_g512"
+  #   prompt_length: 2048
+  #   generation_length: 512
+  #   time_between_requests: 2.0
+  #   iterations: 10
+  # - name: "pp4096_g64"
+  #   prompt_length: 4096
+  #   generation_length: 64
+  #   time_between_requests: 2.0
+  #   iterations: 4
+  # - name: "pp4096_g512"
+  #   prompt_length: 4096
+  #   generation_length: 512
+  #   time_between_requests: 2.0
+  #   iterations: 10
+  # - name: "pp8192_g64"
+  #   prompt_length: 8192
+  #   generation_length: 64
+  #   time_between_requests: 2.0
+  #   iterations: 5
+  # - name: "pp8192_g512"
+  #   prompt_length: 8192
+  #   generation_length: 512
+  #   time_between_requests: 2.0
+  #   iterations: 5
+  # - name: "pp16384_g64"
+  #   prompt_length: 16384
+  #   generation_length: 64
+  #   time_between_requests: 2.0
+  #   iterations: 10
+  # - name: "pp16384_g512"
+  #   prompt_length: 16384
+  #   generation_length: 512
+  #   time_between_requests: 2.0
+  #   iterations: 10
@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+import json
+import os
+from typing import NotRequired, TypedDict, cast
+
+import yaml
+
+
+class MatrixEntry(TypedDict):
+    label: str
+    index: int
+
+
+class MatrixInclude(TypedDict):
+    label: str
+    index: int
+    is_primary: bool
+    expected_nodes: int
+
+
+class Config(TypedDict):
+    hardware_plan: dict[str, int]
+    timeout_seconds: NotRequired[int]
+    environment: NotRequired[dict[str, str]]
+
+
+# Read the config file
+config_file: str = os.environ["CONFIG_FILE"]
+with open(config_file, "r") as f:
+    config: Config = cast(Config, yaml.safe_load(f))
+
+# Extract hardware plan from config
+plan: dict[str, int] = config["hardware_plan"]
+if not plan:
+    raise ValueError(f"No hardware_plan found in {config_file}")
+
+# Build matrix entries
+entries: list[MatrixEntry] = []
+for label, count in plan.items():
+    for idx in range(count):
+        entries.append({"label": label, "index": idx})
+
+total_nodes: int = len(entries)
+matrix: dict[str, list[MatrixInclude]] = {
+    "include": [
+        {
+            "label": e["label"],
+            "index": e["index"],
+            "is_primary": (i == 0),
+            "expected_nodes": total_nodes,
+        }
+        for i, e in enumerate(entries)
+    ]
+}
+
+# Extract other config values
+timeout_seconds: int = config.get("timeout_seconds", 600)
+environment: dict[str, str] = config.get("environment", {})
+
+# Output to GitHub Actions
+with open(os.environ["GITHUB_OUTPUT"], "a") as f:
+    f.write(f"matrix={json.dumps(matrix)}\n")
+    f.write(f"config_file={config_file}\n")
+    f.write(f"timeout_seconds={timeout_seconds}\n")
+    f.write(f"environment={json.dumps(environment)}\n")
+
+print(f"Matrix: {json.dumps(matrix)}")
+print(f"Config file: {config_file}")
+print(f"Timeout: {timeout_seconds}")
+print(f"Environment: {json.dumps(environment)}")
@@ -0,0 +1,156 @@
+# Benchmark Workflow Usage
+
+## Overview
+
+The `bench_matrix.yml` workflow enables distributed benchmarking of models across multiple self-hosted macOS runners with different hardware configurations.
+
+## Workflow Inputs
+
+| Input | Description | Default | Required |
+|-------|-------------|---------|----------|
+| `model_id` | Model ID to benchmark | `mlx-community/Llama-3.2-1B-Instruct-4bit` | Yes |
+| `hardware_plan` | JSON mapping of runner labels to counts | `{"M4PRO_GPU16_24GB": 1}` | Yes |
+| `prompt` | Benchmark prompt text | `What is the capital of France?` | No |
+| `timeout_seconds` | Timeout for instance/runner readiness | `600` | No |
+
+## Hardware Plan Format
+
+The `hardware_plan` input is a JSON object mapping runner labels to the number of machines:
+
+```json
+{
+  "M4PRO_GPU16_24GB": 2,
+  "M3ULTRA_GPU80_512GB": 1
+}
+```
+
+This example would:
+- Start 2 runners with the `M4PRO_GPU16_24GB` label
+- Start 1 runner with the `M3ULTRA_GPU80_512GB` label
+- Total of 3 runners coordinating on a single distributed inference instance
+
+## How It Works
+
+1. **Planning Job** (`plan`)
+   - Runs on `ubuntu-latest`
+   - Parses the `hardware_plan` JSON
+   - Generates a dynamic matrix with one entry per runner
+   - Only the first runner (index 0) is marked as `is_primary`
+
+2. **Benchmark Worker Jobs** (`bench_worker`)
+   - Each job runs on a self-hosted macOS runner with the specified label
+   - All runners start EXO in parallel
+   - The primary runner creates the model instance
+   - All runners wait for their assigned runner to be ready (Loaded/Running status)
+   - The primary runner executes the benchmark and prints results
+   - The primary runner deletes the instance
+
+## Example Usage
+
+### Single Machine Benchmark
+
+```yaml
+model_id: mlx-community/Llama-3.2-1B-Instruct-4bit
+hardware_plan: '{"M4PRO_GPU16_24GB": 1}'
+prompt: What is the capital of France?
+timeout_seconds: 600
+```
+
+### Multi-Machine Distributed Benchmark
+
+```yaml
+model_id: mlx-community/Llama-3.2-3B-Instruct-4bit
+hardware_plan: '{"M4PRO_GPU16_24GB": 2, "M3ULTRA_GPU80_512GB": 1}'
+prompt: Explain quantum computing in simple terms.
+timeout_seconds: 900
+```
+
+## Benchmark Output
+
+The primary runner outputs a JSON object with benchmark results:
+
+```json
+{
+  "model_id": "mlx-community/Llama-3.2-1B-Instruct-4bit",
+  "instance_id": "abc-123-def",
+  "tokens": 42,
+  "elapsed_s": 2.451,
+  "tps": 17.136
+}
+```
+
+Where:
+- `tokens`: Number of chunks/tokens generated
+- `elapsed_s`: Total elapsed time in seconds
+- `tps`: Tokens per second (tokens / elapsed_s)
+
+## Runner Requirements
+
+Each self-hosted runner must:
+- Be labeled with appropriate hardware tags (e.g., `M4PRO_GPU16_24GB`)
+- Have the `self-hosted` and `macOS` labels
+- Have Nix installed with flakes enabled
+- Have network connectivity to other runners in the same job
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ GitHub Actions Workflow (bench_matrix.yml)                  │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌────────────────┐                                         │
+│  │  Plan Job      │                                         │
+│  │  (ubuntu)      │──┬─► Matrix: [{label, index, primary}] │
+│  └────────────────┘  │                                      │
+│                      │                                      │
+│  ┌───────────────────▼──────────────────────────────────┐  │
+│  │  Bench Worker Jobs (Matrix)                         │  │
+│  ├──────────────────────────────────────────────────────┤  │
+│  │                                                       │  │
+│  │  Runner 0 (Primary)     Runner 1         Runner 2    │  │
+│  │  ┌─────────────┐       ┌─────────────┐ ┌──────────┐ │  │
+│  │  │ Start EXO   │       │ Start EXO   │ │ Start EXO│ │  │
+│  │  │ Create Inst │       │ Wait...     │ │ Wait...  │ │  │
+│  │  │ Wait Ready  │       │ Wait Ready  │ │ Wait...  │ │  │
+│  │  │ Run Bench   │       │ (idle)      │ │ (idle)   │ │  │
+│  │  │ Print TPS   │       │             │ │          │ │  │
+│  │  │ Delete Inst │       │             │ │          │ │  │
+│  │  └─────────────┘       └─────────────┘ └──────────┘ │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Implementation Details
+
+### `scripts/bench.py`
+
+A standalone Python script that:
+- Creates instance (primary only)
+- Polls `/state` endpoint until instance and all runners are ready
+- Executes chat completion with timing (primary only)
+- Parses SSE stream and counts tokens
+- Computes TPS metrics
+- Cleans up instance (primary only)
+
+### Key Functions
+
+- `wait_for_instance()`: Polls until instance with model_id appears
+- `wait_for_runners_ready()`: Polls until expected number of runners reach Loaded/Running status
+- `run_benchmark()`: Executes chat completion, measures time, counts tokens
+
+## Troubleshooting
+
+### Instance never becomes ready
+- Check EXO logs in the workflow output
+- Verify model_id is valid and accessible
+- Increase `timeout_seconds`
+
+### Runner mismatch
+- Ensure hardware_plan counts match available labeled runners
+- Check runner labels match exactly (case-sensitive)
+
+### Network issues
+- Verify runners can communicate on the network
+- Check firewall rules between runner hosts
+
@@ -0,0 +1,305 @@
+name: bench
+
+on: [push]
+
+jobs:
+  plan:
+    if: contains(github.event.head_commit.message, '/bench')
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.build.outputs.matrix }}
+      config_file: ${{ steps.build.outputs.config_file }}
+      timeout_seconds: ${{ steps.build.outputs.timeout_seconds }}
+      environment: ${{ steps.build.outputs.environment }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Build matrix from config file
+        id: build
+        shell: bash
+        run: |
+          set -euo pipefail
+          CONFIG_FILE='.github/configs/bench_simple.yaml'
+          export CONFIG_FILE
+          echo "Config file: $CONFIG_FILE"
+          python3 .github/scripts/build_matrix.py
+
+  bench_worker:
+    needs: plan
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.plan.outputs.matrix) }}
+    name: "bench on ${{ matrix.label }} [${{ matrix.index }}]"
+    runs-on: [self-hosted, macOS, "${{ matrix.label }}"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          lfs: false
+
+      - name: Configure git user
+        run: |
+          git config --local user.email "github-actions@users.noreply.github.com"
+          git config --local user.name  "github-actions bot"
+        shell: bash
+
+      # TODO: this is mega hacky and I'd like a simpler solution.
+      - name: Setup Nix Environment
+        run: |
+          echo "Checking for nix installation..."
+          
+          # Check if nix is already available
+          if command -v nix >/dev/null 2>&1; then
+            echo "Nix already in PATH"
+          # Try sourcing profile scripts to set up environment properly
+          elif [ -f /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
+            echo "Sourcing multi-user nix-daemon profile script"
+            source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
+          elif [ -f "$HOME/.nix-profile/etc/profile.d/nix.sh" ]; then
+            echo "Sourcing single-user nix profile script"
+            source "$HOME/.nix-profile/etc/profile.d/nix.sh"
+          elif [ -f /nix/var/nix/profiles/per-user/$USER/profile/etc/profile.d/nix.sh ]; then
+            echo "Sourcing per-user nix profile script"
+            source /nix/var/nix/profiles/per-user/$USER/profile/etc/profile.d/nix.sh
+          elif [ -f /etc/profile.d/nix.sh ]; then
+            echo "Sourcing system-wide nix profile script"
+            source /etc/profile.d/nix.sh
+          # Fallback: manually add nix to PATH if binary exists
+          elif [ -f /nix/var/nix/profiles/default/bin/nix ]; then
+            echo "Found nix binary, manually adding to PATH"
+            export PATH="/nix/var/nix/profiles/default/bin:$PATH"
+          elif [ -f "$HOME/.nix-profile/bin/nix" ]; then
+            echo "Found nix binary in user profile, manually adding to PATH"
+            export PATH="$HOME/.nix-profile/bin:$PATH"
+          else
+            echo "Nix not found. Debugging info:"
+            echo "USER: $USER"
+            echo "HOME: $HOME"
+            echo "Current PATH: $PATH"
+            echo ""
+            echo "Checking common Nix locations:"
+            echo "  /nix/var/nix/profiles/default/bin/nix:"
+            ls -la /nix/var/nix/profiles/default/bin/nix 2>/dev/null || echo "    Not found"
+            echo "  /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh:"
+            ls -la /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh 2>/dev/null || echo "    Not found"
+            echo "  ~/.nix-profile/etc/profile.d/nix.sh:"
+            ls -la "$HOME/.nix-profile/etc/profile.d/nix.sh" 2>/dev/null || echo "    Not found"
+            echo "  /nix/var/nix/profiles/per-user/$USER/profile/etc/profile.d/nix.sh:"
+            ls -la "/nix/var/nix/profiles/per-user/$USER/profile/etc/profile.d/nix.sh" 2>/dev/null || echo "    Not found"
+            echo ""
+            echo "/nix directory structure:"
+            ls -la /nix 2>/dev/null || echo "    /nix directory not found"
+            echo ""
+            echo "/nix/var:"
+            ls -la /nix/var 2>/dev/null || echo "    /nix/var not found"
+            echo ""
+            echo "/nix/store:"
+            ls -la /nix/store 2>/dev/null | head -20 || echo "    /nix/store not found"
+            echo ""
+            echo "GitHub Actions runner is running as user '$USER'."
+            echo "If Nix is installed for a different user, either:"
+            echo "  1. Install Nix for user '$USER' (multi-user install recommended)"
+            echo "  2. Configure the runner service to run as the user with Nix installed"
+            echo "  3. Ensure Nix is installed system-wide with proper daemon setup"
+            exit 1
+          fi
+          
+          # Verify nix is available and persist to GITHUB_ENV
+          if command -v nix >/dev/null 2>&1; then
+            echo "✓ Nix is available"
+            nix --version
+            echo "PATH=$PATH" >> $GITHUB_ENV
+            if [ -n "$NIX_PATH" ]; then
+              echo "NIX_PATH=$NIX_PATH" >> $GITHUB_ENV
+            fi
+          else
+            echo "ERROR: Failed to set up Nix"
+            echo "PATH after setup attempt: $PATH"
+            exit 1
+          fi
+        shell: bash
+
+      - name: Setup EXO_HOME and API_PORT
+        run: |
+          EXO_HOME=$(mktemp -d -t exo-e2e-XXXXXXXX)
+          API_PORT=$((49152 + RANDOM % (65535 - 49152 + 1)))
+          EXO_MODELS_DIR="$HOME/.exo/models"
+          EXO_LIBP2P_NAMESPACE="bench-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          echo "EXO_HOME=$EXO_HOME" >> "$GITHUB_ENV"
+          echo "API_PORT=$API_PORT" >> "$GITHUB_ENV"
+          echo "EXO_MODELS_DIR=$EXO_MODELS_DIR" >> "$GITHUB_ENV"
+          echo "EXO_LIBP2P_NAMESPACE=$EXO_LIBP2P_NAMESPACE" >> "$GITHUB_ENV"
+          echo "Created EXO_HOME: $EXO_HOME"
+          echo "Generated API_PORT: $API_PORT"
+          echo "Using models from: $EXO_MODELS_DIR"
+          echo "Using libp2p namespace: $EXO_LIBP2P_NAMESPACE"
+        shell: bash
+
+      - name: Configure local MLX if available
+        run: |
+          echo "=== DEBUG: Checking for local MLX configuration ==="
+          MODIFIED=false
+          
+          echo "Checking for /Users/Shared/mlx directory..."
+          if [ -d "/Users/Shared/mlx" ]; then
+            echo "✓ Found /Users/Shared/mlx"
+            ls -la /Users/Shared/mlx | head -5
+            echo "Enabling local mlx path in pyproject.toml"
+            sed -i.bak 's|^# mlx = { path = "/Users/Shared/mlx", editable=true }$|mlx = { path = "/Users/Shared/mlx", editable=true }|' pyproject.toml
+            MODIFIED=true
+          else
+            echo "✗ /Users/Shared/mlx not found, will use PyPI version"
+          fi
+          
+          echo "Checking for /Users/Shared/mlx-lm directory..."
+          if [ -d "/Users/Shared/mlx-lm" ]; then
+            echo "✓ Found /Users/Shared/mlx-lm"
+            ls -la /Users/Shared/mlx-lm | head -5
+            echo "Enabling local mlx-lm path in pyproject.toml"
+            sed -i.bak 's|^# mlx-lm = { path = "/Users/Shared/mlx-lm", editable=true }$|mlx-lm = { path = "/Users/Shared/mlx-lm", editable=true }|' pyproject.toml
+            MODIFIED=true
+          else
+            echo "✗ /Users/Shared/mlx-lm not found, will use PyPI version"
+          fi
+          
+          if [ "$MODIFIED" = true ]; then
+            echo "=== Modified pyproject.toml [tool.uv.sources] section: ==="
+            sed -n '/\[tool\.uv\.sources\]/,/^\[/{/^\[tool\.uv\.sources\]/p; /^\[/!p;}' pyproject.toml
+            echo "=== Regenerating uv.lock with local MLX paths... ==="
+            nix --extra-experimental-features nix-command --extra-experimental-features flakes develop --command uv lock --upgrade-package mlx --upgrade-package mlx-lm
+            echo "✓ Lock file regenerated"
+          else
+            echo "⚠ No local MLX directories found, using PyPI packages"
+          fi
+          echo "=== DEBUG: Local MLX configuration complete ==="
+        shell: bash
+
+      - name: Sync dependencies
+        run: |
+          if [ -d "/Users/Shared/test" ]; then
+            pushd /Users/Shared/test
+            uv sync --reinstall
+            popd
+          fi
+          echo "Running just sync to ensure clean dependencies..."
+          nix --extra-experimental-features nix-command --extra-experimental-features flakes develop --command just sync
+        shell: bash
+
+      - name: Start EXO and run bench script
+        shell: bash
+        env:
+          IS_PRIMARY: ${{ matrix.is_primary }}
+          EXPECTED_NODES: ${{ matrix.expected_nodes }}
+          HARDWARE_LABEL: ${{ matrix.label }}
+          CONFIG_FILE: ${{ needs.plan.outputs.config_file }}
+          TIMEOUT_SECONDS: ${{ needs.plan.outputs.timeout_seconds }}
+          ENVIRONMENT_JSON: ${{ needs.plan.outputs.environment }}
+        run: |
+          set -euo pipefail
+
+          # Parse environment variables from config
+          ENV_VARS=""
+          if [ -n "$ENVIRONMENT_JSON" ] && [ "$ENVIRONMENT_JSON" != "{}" ]; then
+            ENV_VARS=$(echo "$ENVIRONMENT_JSON" | python3 -c "import sys, json; env = json.load(sys.stdin); print(' '.join([f'{k}={v}' for k, v in env.items()]))")
+          fi
+
+          echo "Starting EXO with API_PORT=${API_PORT} EXO_HOME=${EXO_HOME} EXO_LIBP2P_NAMESPACE=${EXO_LIBP2P_NAMESPACE}"
+          echo "Environment variables from config: $ENV_VARS"
+          LOG_FILE=/tmp/exo.log
+          : > "$LOG_FILE"
+
+          MASTER_FLAG=""
+          if [ "$IS_PRIMARY" = "true" ]; then
+            MASTER_FLAG="-m"
+          fi
+
+          nix --extra-experimental-features nix-command --extra-experimental-features flakes develop --command bash -c \
+            "EXO_HOME=$EXO_HOME EXO_MODELS_DIR=$EXO_MODELS_DIR EXO_LIBP2P_NAMESPACE=$EXO_LIBP2P_NAMESPACE $ENV_VARS PYTHONUNBUFFERED=1 PYTHONDEBUG=1 PYTHONPATH=. uv run exo $MASTER_FLAG --api-port $API_PORT" \
+            >> "$LOG_FILE" 2>&1 &
+
+          EXO_PID=$!
+          echo "Started EXO in background with PID: $EXO_PID"
+          echo "Log file: $LOG_FILE"
+
+          cleanup() {
+            echo '=== EXO log (tail) ==='
+            tail -n 300 "$LOG_FILE" || true
+            if ps -p "$EXO_PID" >/dev/null 2>&1; then
+              echo "Killing EXO (PID $EXO_PID)"
+              kill "$EXO_PID" || true
+            fi
+          }
+          trap cleanup EXIT
+
+          for i in $(seq 1 60); do
+            if curl -s "http://localhost:${API_PORT}/state" >/dev/null 2>&1; then
+              echo "EXO API ready"
+              break
+            fi
+            if ! ps -p "$EXO_PID" >/dev/null 2>&1; then
+              echo "EXO terminated early"; sed -n '1,200p' "$LOG_FILE" || true; exit 1
+            fi
+            sleep 1
+          done
+
+          RESULTS_FILE="/tmp/bench_results_${GITHUB_RUN_ID}_${GITHUB_RUN_ATTEMPT}_$(date +%s).json"
+          echo "Results will be saved to: $RESULTS_FILE"
+          echo "RESULTS_FILE=$RESULTS_FILE" >> "$GITHUB_ENV"
+
+          echo "Running bench script with config: $CONFIG_FILE, timeout: $TIMEOUT_SECONDS"
+          nix --extra-experimental-features nix-command --extra-experimental-features flakes develop --command bash -c \
+            "PYTHONUNBUFFERED=1 uv run --no-project --with pyyaml --with pydantic python .github/scripts/bench.py \
+              --api-port $API_PORT \
+              --config $CONFIG_FILE \
+              --expected-nodes ${EXPECTED_NODES} \
+              --is-primary ${IS_PRIMARY} \
+              --timeout-seconds ${TIMEOUT_SECONDS} \
+              --output $RESULTS_FILE \
+              --git-commit ${GITHUB_SHA} \
+              --hardware-labels ${HARDWARE_LABEL}"
+
+      - name: Install AWS CLI
+        if: always() && env.RESULTS_FILE && matrix.is_primary
+        run: |
+          if ! command -v aws &> /dev/null; then
+            echo "AWS CLI not found, installing..."
+            brew install awscli
+          else
+            echo "AWS CLI already installed"
+          fi
+        shell: bash
+
+      - name: Upload results to S3
+        if: always() && env.RESULTS_FILE && matrix.is_primary
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.S3_BENCHMARKS_AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.S3_BENCHMARKS_AWS_SECRET_ACCESS_KEY }}
+          AWS_DEFAULT_REGION: us-east-1
+        run: |
+          echo "Checking for results file: $RESULTS_FILE"
+          echo "Is primary: ${{ matrix.is_primary }}"
+
+          if [ -f "$RESULTS_FILE" ]; then
+            TIMESTAMP=$(date -u +%Y/%m/%d/%H%M%S)
+            S3_KEY="bench/${TIMESTAMP}_${GITHUB_SHA:0:8}_${GITHUB_RUN_ID}.json"
+            echo "Uploading results to s3://exo-benchmark-results/$S3_KEY"
+
+            aws s3 cp "$RESULTS_FILE" "s3://exo-benchmark-results/$S3_KEY" \
+              --content-type application/json \
+              --metadata "commit=${GITHUB_SHA},run_id=${GITHUB_RUN_ID},branch=${GITHUB_REF_NAME}"
+
+            echo "Results uploaded successfully"
+            echo "View at: https://exo-benchmark-results.s3.amazonaws.com/$S3_KEY"
+          else
+            echo "Results file not found at: $RESULTS_FILE"
+            echo "Skipping upload"
+          fi
+        shell: bash
+
+      - name: Cleanup EXO_HOME
+        run: |
+          echo "Cleaning up EXO_HOME: $EXO_HOME"
+          rm -rf "$EXO_HOME"
+        shell: bash
+        if: always()
@@ -1,18 +1,6 @@
 name: Build EXO macOS DMG

-# Release workflow:
-# 1. Create a draft GitHub Release with the tag name (e.g. v1.0.0) and write release notes in markdown
-# 2. Push the tag: git tag v1.0.0 && git push origin v1.0.0
-# 3. This workflow builds, signs, and notarizes the DMG
-# 4. Release notes are embedded in appcast.xml for Sparkle (rendered as markdown)
-# 5. DMG and appcast.xml are uploaded to S3
-# 6. The draft GitHub Release is published with the DMG attached
-#
-# For alpha releases (e.g. v1.0.0-alpha.1): draft release and notes are optional.
-# If no draft exists, a release is auto-created with generated notes.
-
 on:
-  workflow_dispatch:
  push:
    tags:
      - "v*"
@@ -22,10 +10,8 @@ on:
 jobs:
  build-macos-app:
    runs-on: "macos-26"
-    permissions:
-      contents: write
    env:
-      SPARKLE_VERSION: 2.9.0-beta.1
+      SPARKLE_VERSION: 2.8.1
      SPARKLE_DOWNLOAD_PREFIX: ${{ secrets.SPARKLE_DOWNLOAD_PREFIX }}
      SPARKLE_FEED_URL: ${{ secrets.SPARKLE_FEED_URL }}
      SPARKLE_ED25519_PUBLIC: ${{ secrets.SPARKLE_ED25519_PUBLIC }}
@@ -48,7 +34,7 @@ jobs:

      - name: Derive release version from tag
        run: |
-          if [[ "$GITHUB_REF_NAME" == "test-app" || "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+          if [[ "$GITHUB_REF_NAME" == "test-app" ]]; then
            VERSION="0.0.0-alpha.0"
            echo "IS_ALPHA=true" >> $GITHUB_ENV
          else
@@ -61,32 +47,6 @@ jobs:
          fi
          echo "RELEASE_VERSION=$VERSION" >> $GITHUB_ENV

-      - name: Compute build version from semver
-        run: |
-          VERSION="$RELEASE_VERSION"
-          # Extract major.minor.patch (strip prerelease suffix)
-          BASE_VERSION="${VERSION%%-*}"
-          MAJOR=$(echo "$BASE_VERSION" | cut -d. -f1)
-          MINOR=$(echo "$BASE_VERSION" | cut -d. -f2)
-          PATCH=$(echo "$BASE_VERSION" | cut -d. -f3)
-
-          # Extract prerelease number (e.g., "alpha.2" -> 2, or 999 for releases)
-          if [[ "$VERSION" == *-* ]]; then
-            PRERELEASE_PART="${VERSION#*-}"
-            PRERELEASE_NUM="${PRERELEASE_PART##*.}"
-            # Default to 0 if not a number
-            if ! [[ "$PRERELEASE_NUM" =~ ^[0-9]+$ ]]; then
-              PRERELEASE_NUM=0
-            fi
-          else
-            PRERELEASE_NUM=999
-          fi
-
-          # Compute: PRERELEASE + (1000 * PATCH) + (1_000_000 * MINOR) + (1_000_000_000 * MAJOR)
-          BUILD_VERSION=$((PRERELEASE_NUM + 1000 * PATCH + 1000000 * MINOR + 1000000000 * MAJOR))
-          echo "EXO_BUILD_VERSION=$BUILD_VERSION" >> $GITHUB_ENV
-          echo "Computed build version: $BUILD_VERSION from $VERSION"
-
      - name: Ensure tag commit is on main
        if: github.ref_type == 'tag'
        run: |
@@ -99,52 +59,6 @@ jobs:
            exit 1
          fi

-      - name: Fetch and validate release notes
-        if: github.ref_type == 'tag'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          # Find draft release by name using gh release list (more reliable with default token)
-          echo "Looking for draft release named '$GITHUB_REF_NAME'..."
-          DRAFT_EXISTS=$(gh release list --json name,isDraft --jq ".[] | select(.isDraft == true) | select(.name == \"$GITHUB_REF_NAME\") | .name" 2>/dev/null || echo "")
-
-          if [[ -z "$DRAFT_EXISTS" ]]; then
-            if [[ "$IS_ALPHA" == "true" ]]; then
-              echo "No draft release found for alpha tag $GITHUB_REF_NAME (optional for alphas)"
-              echo "HAS_RELEASE_NOTES=false" >> $GITHUB_ENV
-              exit 0
-            fi
-            echo "ERROR: No draft release found for tag $GITHUB_REF_NAME"
-            echo "Please create a draft release with release notes before pushing the tag."
-            exit 1
-          fi
-
-          # Fetch full release details via API to get body and ID
-          echo "Found draft release, fetching details..."
-          RELEASE_JSON=$(gh api repos/${{ github.repository }}/releases --jq ".[] | select(.draft == true) | select(.name == \"$GITHUB_REF_NAME\")" 2>/dev/null || echo "")
-
-          # Extract release notes
-          NOTES=$(echo "$RELEASE_JSON" | jq -r '.body // ""')
-          if [[ -z "$NOTES" || "$NOTES" == "null" ]]; then
-            if [[ "$IS_ALPHA" == "true" ]]; then
-              echo "Draft release has no notes (optional for alphas)"
-              echo "HAS_RELEASE_NOTES=false" >> $GITHUB_ENV
-              exit 0
-            fi
-            echo "ERROR: Draft release exists but has no release notes"
-            echo "Please add release notes to the draft release before pushing the tag."
-            exit 1
-          fi
-
-          # Save release ID for later publishing
-          RELEASE_ID=$(echo "$RELEASE_JSON" | jq -r '.id')
-          echo "DRAFT_RELEASE_ID=$RELEASE_ID" >> $GITHUB_ENV
-          echo "HAS_RELEASE_NOTES=true" >> $GITHUB_ENV
-
-          echo "Found draft release (ID: $RELEASE_ID), saving release notes..."
-          echo "$NOTES" > /tmp/release_notes.md
-          echo "RELEASE_NOTES_FILE=/tmp/release_notes.md" >> $GITHUB_ENV
-
      # ============================================================
      # Install dependencies
      # ============================================================
@@ -158,7 +72,7 @@ jobs:
          fi

      - name: Install Homebrew packages
-        run: brew install just awscli
+        run: brew install just awscli macmon

      - name: Install UV
        uses: astral-sh/setup-uv@v6
@@ -171,22 +85,11 @@ jobs:
          uv python install
          uv sync --locked

-      - name: Install Nix
-        uses: cachix/install-nix-action@v31
-        with:
-          nix_path: nixpkgs=channel:nixos-unstable
-
-      - name: Configure Cachix
-        uses: cachix/cachix-action@v14
-        with:
-          name: exo
-          authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
-
      - name: Build dashboard
        run: |
-          DASHBOARD_OUT=$(nix build .#dashboard --print-build-logs --no-link --print-out-paths)
-          mkdir -p dashboard/build
-          cp -r "$DASHBOARD_OUT"/* dashboard/build/
+          cd dashboard
+          npm ci
+          npm run build

      - name: Install Sparkle CLI
        run: |
@@ -238,92 +141,10 @@ jobs:
          # Export keychain path for other steps
          echo "BUILD_KEYCHAIN_PATH=$KEYCHAIN_PATH" >> $GITHUB_ENV

-      # ============================================================
-      # Pre-flight credential / profile validation
-      # Runs BEFORE the ~16 min build so auth/expiry failures surface in <1 min.
-      # ============================================================
-
-      - name: Validate Apple notarization credentials
-        env:
-          APPLE_NOTARIZATION_USERNAME: ${{ secrets.APPLE_NOTARIZATION_USERNAME }}
-          APPLE_NOTARIZATION_PASSWORD: ${{ secrets.APPLE_NOTARIZATION_PASSWORD }}
-          APPLE_NOTARIZATION_TEAM: ${{ secrets.APPLE_NOTARIZATION_TEAM }}
-        run: |
-          # All-or-nothing: either all three creds are set, or none are.
-          CRED_COUNT=0
-          for v in "$APPLE_NOTARIZATION_USERNAME" "$APPLE_NOTARIZATION_PASSWORD" "$APPLE_NOTARIZATION_TEAM"; do
-            [[ -n "$v" ]] && CRED_COUNT=$((CRED_COUNT + 1))
-          done
-          if [[ "$CRED_COUNT" -eq 0 ]]; then
-            echo "No notarization credentials configured — skipping notarization for this build."
-            exit 0
-          fi
-          if [[ "$CRED_COUNT" -ne 3 ]]; then
-            echo "ERROR: partial notarization credentials set ($CRED_COUNT/3). Aborting before build."
-            exit 1
-          fi
-          # Cheap, ~5s, auth-only call. Fails instantly with a clear message if
-          # the app-specific password is stale, wrong team-id, etc.
-          echo "Verifying Apple notarization credentials via notarytool history..."
-          if ! xcrun notarytool history \
-            --apple-id "$APPLE_NOTARIZATION_USERNAME" \
-            --password "$APPLE_NOTARIZATION_PASSWORD" \
-            --team-id "$APPLE_NOTARIZATION_TEAM" >/dev/null; then
-            echo "ERROR: notarytool rejected the provided credentials. Fix before rerunning."
-            echo "Common causes: app-specific password expired/revoked, wrong team-id,"
-            echo "Apple ID not on the team, or 2FA not configured for this Apple ID."
-            exit 1
-          fi
-          echo "Apple notarization credentials OK."
-
-      - name: Validate provisioning profile expiry
-        run: |
-          PROFILE="$HOME/Library/Developer/Xcode/UserData/Provisioning Profiles/EXO.provisionprofile"
-          if [[ ! -f "$PROFILE" ]]; then
-            echo "ERROR: provisioning profile not found at $PROFILE"
-            exit 1
-          fi
-          EXPIRY=$(security cms -D -i "$PROFILE" | plutil -extract ExpirationDate raw -o - - 2>/dev/null || true)
-          if [[ -z "$EXPIRY" ]]; then
-            echo "WARNING: could not read ExpirationDate from provisioning profile; skipping expiry check."
-            exit 0
-          fi
-          # Try a couple of known plutil date formats. If none parse, skip the check rather
-          # than risk a false-positive "expired" block on a format we didn't anticipate.
-          EXPIRY_EPOCH=""
-          for fmt in "%Y-%m-%dT%H:%M:%SZ" "%Y-%m-%d %H:%M:%S %z" "%Y-%m-%d %H:%M:%S +0000"; do
-            if parsed=$(date -j -f "$fmt" "$EXPIRY" +%s 2>/dev/null); then
-              EXPIRY_EPOCH="$parsed"
-              break
-            fi
-          done
-          if [[ -z "$EXPIRY_EPOCH" ]]; then
-            echo "WARNING: could not parse ExpirationDate '$EXPIRY'; skipping expiry check."
-            exit 0
-          fi
-          NOW_EPOCH=$(date +%s)
-          if [[ "$EXPIRY_EPOCH" -le "$NOW_EPOCH" ]]; then
-            echo "ERROR: provisioning profile expired on $EXPIRY. Regenerate it before rerunning."
-            exit 1
-          fi
-          DAYS_LEFT=$(( (EXPIRY_EPOCH - NOW_EPOCH) / 86400 ))
-          echo "Provisioning profile valid until $EXPIRY ($DAYS_LEFT days remaining)."
-          if [[ "$DAYS_LEFT" -lt 14 ]]; then
-            echo "WARNING: profile expires in under 14 days — regenerate soon."
-          fi
-
      # ============================================================
      # Build the bundle
      # ============================================================

-      - name: Add pinned macmon to PATH
-        run: |
-          MACMON_DIR=$(nix develop --command sh -c 'dirname $(which macmon)')
-          echo "Using macmon from: $MACMON_DIR"
-          echo "$MACMON_DIR" >> $GITHUB_PATH
-          # Remove any Homebrew macmon so PyInstaller can't accidentally pick it up
-          brew uninstall macmon 2>/dev/null || true
-
      - name: Build PyInstaller bundle
        run: uv run pyinstaller packaging/pyinstaller/exo.spec

@@ -341,7 +162,7 @@ jobs:
            -configuration Release \
            -derivedDataPath build \
            MARKETING_VERSION="$RELEASE_VERSION" \
-            CURRENT_PROJECT_VERSION="$EXO_BUILD_VERSION" \
+            CURRENT_PROJECT_VERSION="$EXO_BUILD_NUMBER" \
            EXO_BUILD_TAG="$RELEASE_VERSION" \
            EXO_BUILD_COMMIT="$GITHUB_SHA" \
            SPARKLE_FEED_URL="$SPARKLE_FEED_URL" \
@@ -378,41 +199,11 @@ jobs:
          APPLE_NOTARIZATION_PASSWORD: ${{ secrets.APPLE_NOTARIZATION_PASSWORD }}
          APPLE_NOTARIZATION_TEAM: ${{ secrets.APPLE_NOTARIZATION_TEAM }}
        run: |
-          set -o pipefail
          cd output
          security unlock-keychain -p "$MACOS_CERTIFICATE_PASSWORD" "$BUILD_KEYCHAIN_PATH"
          SIGNING_IDENTITY=$(security find-identity -v -p codesigning "$BUILD_KEYCHAIN_PATH" | awk -F '"' '{print $2}')
-
-          # Fail fast if notarization creds are partial. All-or-nothing.
-          CRED_COUNT=0
-          for v in "$APPLE_NOTARIZATION_USERNAME" "$APPLE_NOTARIZATION_PASSWORD" "$APPLE_NOTARIZATION_TEAM"; do
-            [[ -n "$v" ]] && CRED_COUNT=$((CRED_COUNT + 1))
-          done
-          if [[ "$CRED_COUNT" -ne 0 && "$CRED_COUNT" -ne 3 ]]; then
-            echo "ERROR: partial Apple notarization credentials set ($CRED_COUNT/3). Aborting."
-            exit 1
-          fi
-
          /usr/bin/codesign --deep --force --timestamp --options runtime \
            --sign "$SIGNING_IDENTITY" EXO.app
-
-          # Pre-flight: verify the signed app BEFORE building DMG and submitting to Apple.
-          # If this fails, notarization will fail too — cheap way to fail in seconds, not 15 minutes.
-          echo "===== codesign --verify EXO.app ====="
-          if ! /usr/bin/codesign --verify --deep --strict --verbose=2 EXO.app; then
-            echo "ERROR: EXO.app failed codesign verification. Dumping signing status of every executable:"
-            find EXO.app -type f \( -perm -111 -o -name "*.dylib" -o -name "*.so" -o -name "*.framework" \) -print0 |
-              while IFS= read -r -d '' f; do
-                printf -- '--- %s\n' "$f"
-                /usr/bin/codesign -dv --verbose=2 "$f" 2>&1 | sed 's/^/    /' || true
-              done
-            exit 1
-          fi
-
-          # Gatekeeper assessment. A failure here strongly predicts notarization rejection.
-          echo "===== spctl assessment (predicts notarization outcome) ====="
-          /usr/bin/spctl -a -vvv -t install EXO.app || echo "WARNING: spctl assessment failed — notarization is likely to fail too."
-
          mkdir -p dmg-root
          cp -R EXO.app dmg-root/
          ln -s /Applications dmg-root/Applications
@@ -420,22 +211,12 @@ jobs:
          hdiutil create -volname "EXO" -srcfolder dmg-root -ov -format UDZO "$DMG_NAME"
          /usr/bin/codesign --force --timestamp --options runtime \
            --sign "$SIGNING_IDENTITY" "$DMG_NAME"
-
-          echo "===== codesign --verify DMG ====="
-          if ! /usr/bin/codesign --verify --verbose=2 "$DMG_NAME"; then
-            echo "ERROR: DMG failed codesign verification."
-            exit 1
-          fi
-
          if [[ -n "$APPLE_NOTARIZATION_USERNAME" ]]; then
-            echo "===== notarytool submit ====="
-            # `|| true` so set -e doesn't abort before we can echo output / fetch the log.
-            # We rely on the parsed STATUS below to decide pass/fail.
            SUBMISSION_OUTPUT=$(xcrun notarytool submit "$DMG_NAME" \
              --apple-id "$APPLE_NOTARIZATION_USERNAME" \
              --password "$APPLE_NOTARIZATION_PASSWORD" \
              --team-id "$APPLE_NOTARIZATION_TEAM" \
-              --wait --timeout 15m 2>&1) || true
+              --wait --timeout 15m 2>&1)
            echo "$SUBMISSION_OUTPUT"

            SUBMISSION_ID=$(echo "$SUBMISSION_OUTPUT" | awk 'tolower($1)=="id:" && $2 ~ /^[0-9a-fA-F-]+$/ {print $2; exit}')
@@ -483,28 +264,6 @@ jobs:
            $CHANNEL_FLAG \
            .

-      - name: Inject release notes into appcast
-        if: github.ref_type == 'tag' && env.HAS_RELEASE_NOTES == 'true'
-        env:
-          RELEASE_VERSION: ${{ env.RELEASE_VERSION }}
-        run: |
-          # Inject markdown release notes with sparkle:format="markdown" (Sparkle 2.9+)
-          export NOTES=$(cat "$RELEASE_NOTES_FILE")
-
-          # Insert description after the enclosure tag for this version
-          awk '
-            /<enclosure[^>]*>/ && index($0, ENVIRON["RELEASE_VERSION"]) {
-              print
-              print "            <description sparkle:format=\"markdown\"><![CDATA["
-              print ENVIRON["NOTES"]
-              print "            ]]></description>"
-              next
-            }
-            { print }
-          ' output/appcast.xml > output/appcast.xml.tmp && mv output/appcast.xml.tmp output/appcast.xml
-
-          echo "Injected markdown release notes for version $RELEASE_VERSION"
-
      # ============================================================
      # Upload artifacts
      # ============================================================
@@ -516,7 +275,7 @@ jobs:
          path: output/EXO-${{ env.RELEASE_VERSION }}.dmg

      - name: Upload to S3
-        if: env.SPARKLE_S3_BUCKET != ''
+        if: env.SPARKLE_S3_BUCKET != '' && github.ref_type == 'tag'
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
@@ -532,37 +291,8 @@ jobs:
            PREFIX="${PREFIX}/"
          fi
          DMG_NAME="EXO-${RELEASE_VERSION}.dmg"
-
-          if [[ "${{ github.ref_type }}" != "tag" ]]; then
-            aws s3 cp "$DMG_NAME" "s3://${SPARKLE_S3_BUCKET}/${PREFIX}EXO-${GITHUB_SHA}.dmg"
-            exit 0
-          fi
-
          aws s3 cp "$DMG_NAME" "s3://${SPARKLE_S3_BUCKET}/${PREFIX}${DMG_NAME}"
          if [[ "$IS_ALPHA" != "true" ]]; then
            aws s3 cp "$DMG_NAME" "s3://${SPARKLE_S3_BUCKET}/${PREFIX}EXO-latest.dmg"
-            aws s3 cp appcast.xml "s3://${SPARKLE_S3_BUCKET}/${PREFIX}appcast.xml" --content-type application/xml --cache-control no-cache
-          fi
-
-      - name: Publish GitHub Release
-        if: github.ref_type == 'tag'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          DMG_PATH="output/EXO-${RELEASE_VERSION}.dmg"
-
-          if [[ "$HAS_RELEASE_NOTES" == "true" ]]; then
-            # Update the draft release with the tag and upload DMG
-            gh api --method PATCH "repos/${{ github.repository }}/releases/$DRAFT_RELEASE_ID" \
-              -f tag_name="$GITHUB_REF_NAME" \
-              -F draft=false
-            gh release upload "$GITHUB_REF_NAME" "$DMG_PATH" --clobber
-            echo "Published release $GITHUB_REF_NAME with DMG attached"
-          else
-            # Alpha without draft release - create one with auto-generated notes
-            gh release create "$GITHUB_REF_NAME" "$DMG_PATH" \
-              --title "$GITHUB_REF_NAME" \
-              --generate-notes \
-              --prerelease
-            echo "Created alpha release $GITHUB_REF_NAME with auto-generated notes"
          fi
+          aws s3 cp appcast.xml "s3://${SPARKLE_S3_BUCKET}/${PREFIX}appcast.xml" --content-type application/xml --cache-control no-cache
@@ -8,19 +8,8 @@ on:
      - main

 jobs:
-  nix:
-    name: Build and check (${{ matrix.system }})
-    runs-on: ${{ matrix.runner }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - runner: macos-26
-            system: aarch64-darwin
-          - runner: ubuntu-latest
-            system: x86_64-linux
-          - runner: ubuntu-24.04-arm
-            system: aarch64-linux
+  typecheck:
+    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
@@ -31,87 +20,164 @@ jobs:
        with:
          nix_path: nixpkgs=channel:nixos-unstable

-      - uses: cachix/cachix-action@v14
-        name: Configure Cachix
-        with:
-          name: exo
-          authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
-
-      - name: Build Metal packages (macOS only)
-        if: runner.os == 'macOS'
+      - name: Configure git user
        run: |
-          # Try to build metal-toolchain first (may succeed via cachix cache hit)
-          if nix build .#metal-toolchain 2>/dev/null; then
-            echo "metal-toolchain built successfully (likely cache hit)"
+          git config --local user.email "github-actions@users.noreply.github.com"
+          git config --local user.name  "github-actions bot"
+        shell: bash
+
+      - name: Pull LFS files
+        run: |
+          echo "Pulling Git LFS files..."
+          git lfs pull
+        shell: bash
+
+      - name: Setup Nix Environment
+        run: |
+          echo "Checking for nix installation..."
+          
+          # Check if nix binary exists directly
+          if [ -f /nix/var/nix/profiles/default/bin/nix ]; then
+            echo "Found nix binary at /nix/var/nix/profiles/default/bin/nix"
+            export PATH="/nix/var/nix/profiles/default/bin:$PATH"
+            echo "PATH=$PATH" >> $GITHUB_ENV
+            nix --version
+          elif [ -f /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
+            echo "Found nix profile script, sourcing..."
+            source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
+            nix --version
+          elif command -v nix >/dev/null 2>&1; then
+            echo "Nix already in PATH"
+            nix --version
          else
-            echo "metal-toolchain build failed, extracting from Xcode..."
-
-            NAR_HASH="sha256-ayR5mXN4sZAddwKEG2OszGRF93k9ZFc7H0yi2xbylQw="
-            NAR_NAME="metal-toolchain-17C48.nar"
-
-            # Use RUNNER_TEMP to avoid /tmp symlink issues on macOS
-            WORK_DIR="${RUNNER_TEMP}/metal-work"
-            mkdir -p "$WORK_DIR"
-
-            # Download the Metal toolchain component
-            xcodebuild -downloadComponent MetalToolchain
-
-            # Find and mount the DMG
-            DMG_PATH=$(find /System/Library/AssetsV2/com_apple_MobileAsset_MetalToolchain -name '*.dmg' 2>/dev/null | head -1)
-            if [ -z "$DMG_PATH" ]; then
-              echo "Error: Could not find Metal toolchain DMG"
-              exit 1
-            fi
-
-            echo "Found DMG at: $DMG_PATH"
-            hdiutil attach "$DMG_PATH" -mountpoint "${WORK_DIR}/metal-dmg"
-
-            # Copy the toolchain
-            cp -R "${WORK_DIR}/metal-dmg/Metal.xctoolchain" "${WORK_DIR}/metal-export"
-            hdiutil detach "${WORK_DIR}/metal-dmg"
-
-            # Create NAR and add to store
-            nix nar pack "${WORK_DIR}/metal-export" > "${WORK_DIR}/${NAR_NAME}"
-            STORE_PATH=$(nix store add --mode flat "${WORK_DIR}/${NAR_NAME}")
-            echo "Added NAR to store: $STORE_PATH"
-
-            # Verify the hash matches
-            ACTUAL_HASH=$(nix hash file "${WORK_DIR}/${NAR_NAME}")
-            if [ "$ACTUAL_HASH" != "$NAR_HASH" ]; then
-              echo "Warning: NAR hash mismatch!"
-              echo "Expected: $NAR_HASH"
-              echo "Actual:   $ACTUAL_HASH"
-              echo "The metal-toolchain.nix may need updating"
-            fi
-
-            # Clean up
-            rm -rf "$WORK_DIR"
-
-            # Retry the build now that NAR is in store
-            nix build .#metal-toolchain
+            echo "Nix not found. Debugging info:"
+            echo "Contents of /nix/var/nix/profiles/default/:"
+            ls -la /nix/var/nix/profiles/default/ 2>/dev/null || echo "Directory not found"
+            echo "Contents of /nix/var/nix/profiles/default/bin/:"
+            ls -la /nix/var/nix/profiles/default/bin/ 2>/dev/null || echo "Directory not found"
+            exit 1
          fi
+        shell: bash

-      - name: Build all Nix outputs
+      - name: Configure basedpyright include for local MLX
        run: |
-          nix flake show --json | jq -r '
-            [
-              (.packages."${{ matrix.system }}" // {} | keys[] | ".#packages.${{ matrix.system }}.\(.)"),
-              (.devShells."${{ matrix.system }}" // {} | keys[] | ".#devShells.${{ matrix.system }}.\(.)")
-            ] | .[]
-          ' | xargs nix build
+          RUNNER_LABELS='${{ toJSON(runner.labels) }}'
+          if echo "$RUNNER_LABELS" | grep -q "local_mlx"; then
+            if [ -d "/Users/Shared/mlx" ]; then
+              echo "Updating [tool.basedpyright].include to use /Users/Shared/mlx"
+              awk '
+                BEGIN { in=0 }
+                /^\[tool\.basedpyright\]/ { in=1; print; next }
+                in && /^\[/ { in=0 }  # next section
+                in && /^[ \t]*include[ \t]*=/ {
+                  print "include = [\"/Users/Shared/mlx\"]"
+                  next
+                }
+                { print }
+              ' pyproject.toml > pyproject.toml.tmp && mv pyproject.toml.tmp pyproject.toml
+
+              echo "New [tool.basedpyright] section:"
+              sed -n '/^\[tool\.basedpyright\]/,/^\[/p' pyproject.toml | sed '$d' || true
+            else
+              echo "local_mlx tag present but /Users/Shared/mlx not found; leaving pyproject unchanged."
+            fi
+          else
+            echo "Runner does not have 'local_mlx' tag; leaving pyproject unchanged."
+          fi
+        shell: bash
+
+      - uses: ./.github/actions/typecheck
+
+  nix-flake-check:
+    name: Check Nix flake
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          lfs: false
+
+      - uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable

      - name: Run nix flake check
-        run: nix flake check
-
-      - name: Run pytest (macOS only)
-        if: runner.os == 'macOS'
        run: |
-          # Build the test environment (requires relaxed sandbox for uv2nix on macOS)
-          TEST_ENV=$(nix build '.#exo-test-env' --option sandbox relaxed --print-out-paths)
+          nix flake check
+        shell: bash

-          # Run pytest outside sandbox (needs GPU access for MLX)
-          export HOME="$RUNNER_TEMP"
-          export EXO_TESTS=1
-          export EXO_DASHBOARD_DIR="$PWD/dashboard/" 
-          export EXO_RESOURCES_DIR="$PWD/resources" 
-          $TEST_ENV/bin/python -m pytest src -m "not slow" --import-mode=importlib
+#  ci:
+#    needs: typecheck
+#    runs-on: ubuntu-latest
+#    permissions:
+#      contents: read
+#    env:
+#      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+#    steps:
+#      - name: Checkout repository
+#        uses: actions/checkout@v4
+#        with:
+#          fetch-depth: 0
+#          token: ${{ secrets.GITHUB_TOKEN }}
+#          lfs: true
+#
+#      - name: Configure git user
+#        run: |
+#          git config --local user.email "github-actions@users.noreply.github.com"
+#          git config --local user.name  "github-actions bot"
+#        shell: bash
+#
+#      - name: Pull LFS files
+#        run: |
+#          echo "Pulling Git LFS files..."
+#          git lfs pull
+#        shell: bash
+#
+#      - name: Setup EXO_HOME and API_PORT
+#        run: |
+#          EXO_HOME=$(mktemp -d -t exo-ci-XXXXXXXX)
+#          # Generate random port (macOS compatible method)
+#          API_PORT=$((49152 + RANDOM % (65535 - 49152 + 1)))
+#          echo "EXO_HOME=$EXO_HOME" >> $GITHUB_ENV
+#          echo "API_PORT=$API_PORT" >> $GITHUB_ENV
+#          echo "Created EXO_HOME: $EXO_HOME"
+#          echo "Generated API_PORT: $API_PORT"
+#        shell: bash
+#
+#      - name: Setup Nix Environment
+#        run: |
+#          echo "Checking for nix installation..."
+#          
+#          # Check if nix binary exists directly
+#          if [ -f /nix/var/nix/profiles/default/bin/nix ]; then
+#            echo "Found nix binary at /nix/var/nix/profiles/default/bin/nix"
+#            export PATH="/nix/var/nix/profiles/default/bin:$PATH"
+#            echo "PATH=$PATH" >> $GITHUB_ENV
+#            nix --version
+#          elif [ -f /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
+#            echo "Found nix profile script, sourcing..."
+#            source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
+#            nix --version
+#          elif command -v nix >/dev/null 2>&1; then
+#            echo "Nix already in PATH"
+#            nix --version
+#          else
+#            echo "Nix not found. Debugging info:"
+#            echo "Contents of /nix/var/nix/profiles/default/:"
+#            ls -la /nix/var/nix/profiles/default/ 2>/dev/null || echo "Directory not found"
+#            echo "Contents of /nix/var/nix/profiles/default/bin/:"
+#            ls -la /nix/var/nix/profiles/default/bin/ 2>/dev/null || echo "Directory not found"
+#            exit 1
+#          fi
+#        shell: bash
+#
+#      - uses: ./.github/actions/lint-check
+#
+#      - uses: ./.github/actions/unit-test
+#
+#      - name: Cleanup EXO_HOME
+#        run: |
+#          echo "Cleaning up EXO_HOME: $EXO_HOME"
+#          rm -rf "$EXO_HOME"
+#        shell: bash
+#        if: always()
@@ -16,7 +16,7 @@ digest.txt
 *.xcuserdatad/
 **/.DS_Store
 app/EXO/build/
-dist/
+

 # rust
 target/
@@ -27,19 +27,3 @@ target/
 dashboard/build/
 dashboard/node_modules/
 dashboard/.svelte-kit/
-
-# host config snapshots
-hosts_*.json
-.swp
-
-# bench files
-bench/**/*.json
-
-# tmp
-tmp/models
-/build/exo
-/.agents
-/.claude/skills
-/.claude
-/.codex
-skills-lock.json
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="EMPTY_MODULE" version="4">
+  <component name="FacetManager">
+    <facet type="Python" name="Python facet">
+      <configuration sdkName="Python 3.13 virtualenv at ~/Desktop/exo/.venv" />
+    </facet>
+  </component>
+  <component name="Go" enabled="true" />
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/scripts/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/rust/exo_pyo3_bindings/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/rust/exo_pyo3_bindings/tests" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/rust/util/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/rust/networking/examples" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/rust/networking/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/rust/networking/tests" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/rust/system_custodian/src" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+      <excludeFolder url="file://$MODULE_DIR$/.direnv" />
+      <excludeFolder url="file://$MODULE_DIR$/build" />
+      <excludeFolder url="file://$MODULE_DIR$/dist" />
+      <excludeFolder url="file://$MODULE_DIR$/.go_cache" />
+      <excludeFolder url="file://$MODULE_DIR$/rust/target" />
+    </content>
+    <orderEntry type="jdk" jdkName="Python 3.13 (exo)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" name="Python 3.13 virtualenv at ~/Desktop/exo/.venv interpreter library" level="application" />
+  </component>
+</module>
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="ExternalDependencies">
-    <plugin id="al.aoli.intellijdirenv" />
+    <plugin id="systems.fehn.intellijdirenv" />
  </component>
 </project>
@@ -0,0 +1,14 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="PyCompatibilityInspection" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="ourVersions">
+        <value>
+          <list size="1">
+            <item index="0" class="java.lang.String" itemvalue="3.14" />
+          </list>
+        </value>
+      </option>
+    </inspection_tool>
+  </profile>
+</component>
@@ -4,7 +4,7 @@
    <option name="sdkName" value="Python 3.13 (exo)" />
  </component>
  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.13 (exo)" project-jdk-type="Python SDK" />
-  <component name="RuffConfiguration">
-    <option name="enabled" value="true" />
+  <component name="PythonCompatibilityInspectionAdvertiser">
+    <option name="version" value="3" />
  </component>
 </project>
@@ -215,22 +215,6 @@ class StreamContext:
        traceback: object | None = ...,
    ) -> None: ...

-def device_info() -> dict[str, str | int]:
-    """
-    Get information about the GPU device and system settings.
-
-    Currently returns:
-
-    * ``architecture``
-    * ``max_buffer_size``
-    * ``max_recommended_working_set_size``
-    * ``memory_size``
-    * ``resource_limit``
-
-    Returns:
-        dict: A dictionary with string keys and string or integer values.
-    """
-
 def abs(a: array, /, *, stream: Stream | Device | None = ...) -> array:
    """
    Element-wise absolute value.
@@ -1155,7 +1139,7 @@ class array:
    ) -> array:
        """See :func:`flatten`."""

-    def reshape(self, *shape: int, stream: Stream | Device | None = ...) -> array:
+    def reshape(self, *shape, stream: Stream | Device | None = ...) -> array:
        """
        Equivalent to :func:`reshape` but the shape can be passed either as a
        :obj:`tuple` or as separate arguments.
@@ -1238,7 +1222,7 @@ class array:
    ) -> array:
        """See :func:`swapaxes`."""

-    def transpose(self, *axes: int, stream: Stream | Device | None = ...) -> array:
+    def transpose(self, *axes, stream: Stream | Device | None = ...) -> array:
        """
        Equivalent to :func:`transpose` but the axes can be passed either as
        a tuple or as separate arguments.
@@ -1767,12 +1751,12 @@ def clip(
        array: The clipped array.
    """

-def compile[F: Callable[..., object]](
-    fun: F,
+def compile(
+    fun: Callable,
    inputs: object | None = ...,
    outputs: object | None = ...,
    shapeless: bool = ...,
-) -> F:
+) -> Callable:
    """
    Returns a compiled function which produces the same output as ``fun``.

@@ -2382,7 +2366,7 @@ class custom_function:
 def default_device() -> Device:
    """Get the default device."""

-def default_stream(device: Device | DeviceType) -> Stream:
+def default_stream(device: Device) -> Stream:
    """Get the device's default stream."""

 def degrees(a: array, /, *, stream: Stream | Device | None = ...) -> array:
@@ -2396,7 +2380,7 @@ def degrees(a: array, /, *, stream: Stream | Device | None = ...) -> array:
        array: The angles in degrees.
    """

-def depends[T](inputs: T, dependencies: array | Sequence[array]) -> T:
+def depends(inputs: array | Sequence[array], dependencies: array | Sequence[array]):
    """
    Insert dependencies between arrays in the graph. The outputs are
    identical to ``inputs`` but with dependencies on ``dependencies``.
@@ -2915,8 +2899,8 @@ def gather_mm(
    a: array,
    b: array,
    /,
-    lhs_indices: array | None = ...,
-    rhs_indices: array | None = ...,
+    lhs_indices: array,
+    rhs_indices: array,
    *,
    sorted_indices: bool = ...,
    stream: Stream | Device | None = ...,
@@ -4707,7 +4691,6 @@ def softmax(
    /,
    axis: int | Sequence[int] | None = ...,
    *,
-    precise: bool = ...,
    stream: Stream | Device | None = ...,
 ) -> array:
    """
@@ -0,0 +1,9 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from layers import *
+from utils import *
+
+from . import init as init
+from . import losses as losses
@@ -0,0 +1,20 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from activations import *
+from base import *
+from containers import *
+from convolution import *
+from convolution_transpose import *
+from distributed import *
+from dropout import *
+from embedding import *
+from linear import *
+from normalization import *
+from pooling import *
+from positional_encoding import *
+from quantized import *
+from recurrent import *
+from transformer import *
+from upsample import *
@@ -53,14 +53,10 @@ class Module(dict):
        mx.eval(model.parameters())
    """

-    def __call__(self, *args: Any, **kwargs: Any) -> mx.array: ...
+    __call__: Callable
    def __init__(self) -> None:
        """Should be called by the subclasses of ``Module``."""

-    def __getitem__(self, key: str) -> mx.array | Module: ...
-    def get(
-        self, key: str, default: mx.array | Module | None = ...
-    ) -> mx.array | Module | None: ...
    @property
    def training(self):  # -> bool:
        """Boolean indicating if the model is in training mode."""
@@ -204,7 +200,7 @@ class Module(dict):
    ) -> mx.MX_ARRAY_TREE:  # -> dict[Any, Any | dict[Any, Any | dict[Any, Any] | list[Any]] | dict[Any, Any] | list[Any]]:
        """Return the submodules that do not contain other modules."""

-    def update(self, parameters: dict[str, Any], strict: bool = ...) -> Module:
+    def update(self, parameters: dict, strict: bool = ...) -> Module:
        """Replace the parameters of this Module with the provided ones in the
        dict of dicts and lists.

@@ -30,10 +30,6 @@ class Conv1d(Module):
        bias (bool, optional): If ``True`` add a learnable bias to the output.
            Default: ``True``
    """
-
-    weight: mx.array
-    bias: mx.array | None
-    groups: int
    def __init__(
        self,
        in_channels: int,
@@ -40,10 +40,6 @@ class Linear(Module):
        bias (bool, optional): If set to ``False`` then the layer will
          not use a bias. Default is ``True``.
    """
-
-    weight: mx.array
-    bias: mx.array | None
-
    def __init__(self, input_dims: int, output_dims: int, bias: bool = ...) -> None: ...
    def __call__(self, x: mx.array) -> mx.array: ...
    def to_quantized(
@@ -88,9 +88,6 @@ class RMSNorm(Module):
        dims (int): The feature dimension of the input to normalize over
        eps (float): A small additive constant for numerical stability
    """
-
-    weight: mx.array
-
    def __init__(self, dims: int, eps: float = ...) -> None: ...
    def __call__(self, x) -> mx.array: ...

@@ -2,7 +2,7 @@
 This type stub file was generated by pyright.
 """

-from typing import Any, Callable, Optional, Union
+from typing import Callable, Optional, Union

 import mlx.core as mx
 from base import Module
@@ -13,10 +13,8 @@ def quantize(
    bits: int = ...,
    *,
    mode: str = ...,
-    class_predicate: Optional[
-        Callable[[str, Module], Union[bool, dict[str, Any]]]
-    ] = ...,
-) -> None:
+    class_predicate: Optional[Callable[[str, Module], Union[bool, dict]]] = ...,
+):  # -> None:
    """Quantize the sub-modules of a module according to a predicate.

    By default all layers that define a ``to_quantized(group_size, bits)``
@@ -7,10 +7,7 @@ from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 from mlx.core import MX_ARRAY_TREE

 def tree_map(
-    fn: Callable[..., Any],
-    tree: Any,
-    *rest: Any,
-    is_leaf: Callable[..., bool] | None = ...,
+    fn: Callable, tree: Any, *rest: Any, is_leaf: Optional[Callable] = ...
 ) -> Any:
    """Applies ``fn`` to the leaves of the Python tree ``tree`` and
    returns a new collection with the results.
@@ -47,11 +44,11 @@ def tree_map(
    """

 def tree_map_with_path(
-    fn: Callable[..., Any],
+    fn: Callable,
    tree: Any,
    *rest: Any,
-    is_leaf: Callable[..., bool] | None = ...,
-    path: str | None = ...,
+    is_leaf: Optional[Callable] = ...,
+    path: Optional[Any] = ...,
 ) -> Any:
    """Applies ``fn`` to the path and leaves of the Python tree ``tree`` and
    returns a new collection with the results.
@@ -83,9 +80,9 @@ def tree_map_with_path(
 def tree_flatten(
    tree: Any,
    prefix: str = ...,
-    is_leaf: Callable[..., bool] | None = ...,
-    destination: list[tuple[str, Any]] | dict[str, Any] | None = ...,
-) -> list[tuple[str, Any]] | dict[str, Any]:
+    is_leaf: Optional[Callable] = ...,
+    destination: Optional[Union[List[Tuple[str, Any]], Dict[str, Any]]] = ...,
+) -> Union[List[Tuple[str, Any]], Dict[str, Any]]:
    """Flattens a Python tree to a list of key, value tuples.

    The keys are using the dot notation to define trees of arbitrary depth and
@@ -121,7 +118,7 @@ def tree_flatten(
            the Python tree.
    """

-def tree_unflatten(tree: list[tuple[str, Any]] | dict[str, Any]) -> Any:
+def tree_unflatten(tree: Union[List[Tuple[str, Any]], Dict[str, Any]]) -> Any:
    """Recreate a Python tree from its flat representation.

    .. code-block:: python
@@ -3,12 +3,13 @@ This type stub file was generated by pyright.
 """

 import contextlib
+from dataclasses import dataclass
+from typing import Any, Callable, Generator, List, Optional, Tuple, Union
+
 import mlx.core as mx
 import mlx.nn as nn
-from dataclasses import dataclass
-from collections import deque
-from typing import Any, Callable, Generator, List, Optional, Sequence, Tuple, Union
 from transformers import PreTrainedTokenizer
+
 from .tokenizer_utils import TokenizerWrapper

 DEFAULT_PROMPT = ...
@@ -28,9 +29,8 @@ def str2bool(string):  # -> bool:
    ...
 def setup_arg_parser():  # -> ArgumentParser:
    """Set up and return the argument parser."""
-    ...

-generation_stream: mx.Stream
+generation_stream = ...

@contextlib.contextmanager
 def wired_limit(
@@ -43,7 +43,6 @@ def wired_limit(
    async eval could be running pass in the streams to synchronize with prior
    to exiting the context manager.
    """
-    ...
@dataclass
 class GenerationResponse:
    """
@@ -74,11 +73,9 @@ class GenerationResponse:
    finish_reason: Optional[str] = ...

 def maybe_quantize_kv_cache(
-    prompt_cache: Any,
-    quantized_kv_start: int | None,
-    kv_group_size: int | None,
-    kv_bits: int | None,
-) -> None: ...
+    prompt_cache, quantized_kv_start, kv_group_size, kv_bits
+):  # -> None:
+    ...
 def generate_step(
    prompt: mx.array,
    model: nn.Module,
@@ -92,7 +89,7 @@ def generate_step(
    kv_bits: Optional[int] = ...,
    kv_group_size: int = ...,
    quantized_kv_start: int = ...,
-    prompt_progress_callback: Optional[Callable[[int, int], None]] = ...,
+    prompt_progress_callback: Optional[Callable[[int], int]] = ...,
    input_embeddings: Optional[mx.array] = ...,
 ) -> Generator[Tuple[mx.array, mx.array], None, None]:
    """
@@ -118,7 +115,7 @@ def generate_step(
        kv_group_size (int): Group size for KV cache quantization. Default: ``64``.
        quantized_kv_start (int): Step to begin using a quantized KV cache.
           when ``kv_bits`` is non-None. Default: ``0``.
-        prompt_progress_callback (Callable[[int, int], None]): A call-back which takes the
+        prompt_progress_callback (Callable[[int], int]): A call-back which takes the
           prompt tokens processed so far and the total number of prompt tokens.
        input_embeddings (mx.array, optional): Input embeddings to use instead of or in
          conjunction with prompt tokens. Default: ``None``.
@@ -126,7 +123,6 @@ def generate_step(
    Yields:
        Tuple[mx.array, mx.array]: One token and a vector of log probabilities.
    """
-    ...

 def speculative_generate_step(
    prompt: mx.array,
@@ -172,7 +168,6 @@ def speculative_generate_step(
        Tuple[mx.array, mx.array, bool]: One token, a vector of log probabilities,
          and a bool indicating if the token was generated by the draft model
    """
-    ...

 def stream_generate(
    model: nn.Module,
@@ -180,7 +175,7 @@ def stream_generate(
    prompt: Union[str, mx.array, List[int]],
    max_tokens: int = ...,
    draft_model: Optional[nn.Module] = ...,
-    **kwargs: Any,
+    **kwargs: object,
 ) -> Generator[GenerationResponse, None, None]:
    """
    A generator producing text based on the given prompt from the model.
@@ -202,7 +197,6 @@ def stream_generate(
        GenerationResponse: An instance containing the generated text segment and
            associated metadata. See :class:`GenerationResponse` for details.
    """
-    ...

 def generate(
    model: nn.Module,
@@ -223,9 +217,6 @@ def generate(
       kwargs: The remaining options get passed to :func:`stream_generate`.
          See :func:`stream_generate` for more details.
    """
-    ...
-
-def _merge_caches(caches: List[List[Any]]) -> List[Any]: ...
@dataclass
 class BatchStats:
    """
@@ -249,263 +240,10 @@ class BatchStats:
    generation_time: float = ...
    peak_memory: float = ...

-class SequenceStateMachine:
-    """A state machine that uses one Aho-Corasick trie per state to efficiently
-    track state across a generated sequence.
-
-    The transitions are provided as state -> [(sequence, new_state)].
-
-    Example:
-
-        sm = SequenceStateMachine(
-            transitions={
-                "normal": [
-                    (think_start_tokens, "reasoning"),
-                    (tool_start_tokens, "tool"),
-                    (eos, None),
-                ],
-                "reasoning": [
-                    (think_end_tokens, "normal"),
-                    (eos, None),
-                ],
-                "tool": [
-                    (tool_end_tokens, None),
-                    (eos, None)
-                ],
-            },
-            initial="normal"
-        )
-    """
-    def __init__(self, transitions=..., initial=...) -> None: ...
-    def __deepcopy__(self, memo):  # -> SequenceStateMachine:
-        ...
-    def make_state(self):  # -> tuple[str, Any, dict[Any, Any]]:
-        ...
-    @staticmethod
-    def match(state, x):  # -> tuple[tuple[Any, Any | None, Any], Any | None, Any]:
-        ...
-
-class PromptProcessingBatch:
-    """
-    A batch processor for prompt tokens with support for incremental processing.
-
-    This class handles batched prompt processing, managing KV caches and preparing
-    tokens for generation. It supports extending, filtering, and splitting batches.
-    """
-    @dataclass
-    class Response:
-        uid: int
-        progress: tuple
-        end_of_segment: bool
-        end_of_prompt: bool
-        ...
-
-    def __init__(
-        self,
-        model: nn.Module,
-        uids: List[int],
-        caches: List[List[Any]],
-        tokens: Optional[List[List[int]]] = ...,
-        prefill_step_size: int = ...,
-        samplers: Optional[List[Callable[[mx.array], mx.array]]] = ...,
-        fallback_sampler: Optional[Callable[[mx.array], mx.array]] = ...,
-        logits_processors: Optional[
-            List[List[Callable[[mx.array, mx.array], mx.array]]]
-        ] = ...,
-        state_machines: Optional[List[SequenceStateMachine]] = ...,
-        max_tokens: Optional[List[int]] = ...,
-    ) -> None: ...
-    def __len__(self):  # -> int:
-        ...
-    def extract_cache(self, idx: int) -> List[Any]: ...
-    def extend(self, batch):  # -> None:
-        ...
-    def split(self, indices: List[int]):  # -> Self:
-        ...
-    def filter(self, keep: List[int]):  # -> None:
-        ...
-    def prompt(self, tokens: List[List[int]]):  # -> None:
-        """
-        Process prompt tokens through the model.
-
-        Args:
-            tokens: List of token sequences to process.
-        """
-        ...
-
-    def generate(self, tokens: List[List[int]]):  # -> GenerationBatch:
-        """
-        Transition from prompt processing to generation.
-
-        Args:
-            tokens: Final tokens for each sequence to start generation.
-
-        Returns:
-            A GenerationBatch ready for token generation.
-        """
-        ...
-
-    @classmethod
-    def empty(
-        cls,
-        model: nn.Module,
-        fallback_sampler: Callable[[mx.array], mx.array],
-        prefill_step_size: int = ...,
-    ):  # -> Self:
-        ...
-
-class GenerationBatch:
-    """
-    A batched token generator that manages multiple sequences in parallel.
-
-    This class handles the generation phase after prompt processing, managing
-    KV caches, sampling, and stop sequence detection for multiple sequences.
-    """
-    @dataclass
-    class Response:
-        uid: int
-        token: int
-        logprobs: mx.array
-        finish_reason: Optional[str]
-        current_state: Optional[str]
-        match_sequence: Optional[List[int]]
-        prompt_cache: Optional[List[Any]]
-        all_tokens: Optional[List[int]]
-        ...
-
-    model: nn.Module
-    uids: List[int]
-    prompt_cache: List[Any]
-    tokens: List[List[int]]
-    samplers: Optional[List[Callable[[mx.array], mx.array]]]
-    fallback_sampler: Callable[[mx.array], mx.array]
-    logits_processors: Optional[List[List[Callable[[mx.array, mx.array], mx.array]]]]
-    state_machines: List[SequenceStateMachine]
-    max_tokens: List[int]
-    _current_tokens: Optional[mx.array]
-    _current_logprobs: mx.array | List[mx.array]
-    _next_tokens: Optional[mx.array]
-    _next_logprobs: mx.array | List[mx.array]
-    _token_context: List[Any]
-    _num_tokens: List[int]
-    _matcher_states: List[Any]
-
-    def __init__(
-        self,
-        model: nn.Module,
-        uids: List[int],
-        inputs: mx.array,
-        prompt_cache: List[Any],
-        tokens: List[List[int]],
-        samplers: Optional[List[Callable[[mx.array], mx.array]]],
-        fallback_sampler: Callable[[mx.array], mx.array],
-        logits_processors: Optional[
-            List[List[Callable[[mx.array, mx.array], mx.array]]]
-        ],
-        state_machines: List[SequenceStateMachine],
-        max_tokens: List[int],
-    ) -> None: ...
-    def __len__(self) -> int: ...
-    def extend(self, batch: GenerationBatch) -> None: ...
-    def extract_cache(self, idx: int) -> List[Any]: ...
-    def filter(self, keep: List[int]) -> None: ...
-    def _step(self) -> Tuple[List[int], List[mx.array]]: ...
-    def next(self) -> List[Response]:
-        """
-        Generate the next batch of tokens.
-
-        Returns:
-            List of Response objects for each sequence in the batch.
-        """
-        ...
-
-    @classmethod
-    def empty(
-        cls, model: nn.Module, fallback_sampler: Callable[[mx.array], mx.array]
-    ):  # -> Self:
-        ...
-
-class BatchGenerator:
-    """
-    A batch generator implements continuous batching.
-
-    This class provides automatic management of prompt processing and generation
-    batches, handling the transition between the two.
-
-    It also allows for segmented prompt processing which guarantees that the
-    generator will stop at these boundaries when processing an input.
-    """
-    def __init__(
-        self,
-        model: nn.Module,
-        max_tokens: int = ...,
-        stop_tokens: Optional[Sequence[Sequence[int]]] = ...,
-        sampler: Optional[Callable[[mx.array], mx.array]] = ...,
-        logits_processors: Optional[
-            List[Callable[[mx.array, mx.array], mx.array]]
-        ] = ...,
-        completion_batch_size: int = ...,
-        prefill_batch_size: int = ...,
-        prefill_step_size: int = ...,
-    ) -> None: ...
-    def close(self) -> None: ...
-    def __del__(self):  # -> None:
-        ...
-    @contextlib.contextmanager
-    def stats(self, stats=...):  # -> Generator[Any | BatchStats, Any, None]:
-        ...
-    _unprocessed_sequences: deque[tuple[Any, ...]]
-    _prompt_batch: PromptProcessingBatch
-    _generation_batch: GenerationBatch
-    _currently_processing: list[Any]
-    _gen_tokens_counter: int
-    _steps_counter: int
-    def _next(
-        self,
-    ) -> tuple[
-        List[PromptProcessingBatch.Response], List[GenerationBatch.Response]
-    ]: ...
-    def insert(
-        self,
-        prompts: List[List[int]],
-        max_tokens: Optional[List[int]] = ...,
-        caches: Optional[List[List[Any]]] = ...,
-        all_tokens: Optional[List[List[int]]] = ...,
-        samplers: Optional[List[Callable[[mx.array], mx.array]]] = ...,
-        logits_processors: Optional[
-            List[List[Callable[[mx.array, mx.array], mx.array]]]
-        ] = ...,
-        state_machines: Optional[List[SequenceStateMachine]] = ...,
-    ) -> List[int]: ...
-    def insert_segments(
-        self,
-        segments: List[List[List[int]]],
-        max_tokens: Optional[List[int]] = ...,
-        caches: Optional[List[List[Any]]] = ...,
-        all_tokens: Optional[List[List[int]]] = ...,
-        samplers: Optional[List[Callable[[mx.array], mx.array]]] = ...,
-        logits_processors: Optional[
-            List[List[Callable[[mx.array, mx.array], mx.array]]]
-        ] = ...,
-        state_machines: Optional[List[SequenceStateMachine]] = ...,
-    ) -> List[int]: ...
-    def extract_cache(self, uids: List[int]) -> dict[int, Any]: ...
-    def remove(
-        self, uids: List[int], return_prompt_caches: bool = ...
-    ) -> dict[int, Any]: ...
-    @property
-    def prompt_cache_nbytes(self) -> int: ...
-    def next(
-        self,
-    ) -> tuple[
-        List[PromptProcessingBatch.Response], List[GenerationBatch.Response]
-    ]: ...
-    def next_generated(self) -> List[GenerationBatch.Response]: ...
-
@dataclass
 class BatchResponse:
    """
-    A data object to hold a batch generation response.
+    An data object to hold a batch generation response.

    Args:
        texts: (List[str]): The generated text for each prompt.
@@ -514,18 +252,55 @@ class BatchResponse:

    texts: List[str]
    stats: BatchStats
-    caches: Optional[List[List[Any]]]
-    ...
+
+@dataclass
+class Batch:
+    uids: List[int]
+    y: mx.array
+    logprobs: mx.array
+    max_tokens: List[int]
+    num_tokens: List[int]
+    cache: List[Any]
+    def __len__(self):  # -> int:
+        ...
+    def filter(self, keep_idx: List[int]):  # -> None:
+        ...
+    def extend(self, other):  # -> None:
+        ...
+
+class BatchGenerator:
+    @dataclass
+    class Response:
+        uid: int
+        token: int
+        logprobs: mx.array
+        finish_reason: Optional[str]
+
+    def __init__(
+        self,
+        model,
+        max_tokens: int = ...,
+        stop_tokens: Optional[set] = ...,
+        sampler: Optional[Callable[[mx.array], mx.array]] = ...,
+        completion_batch_size: int = ...,
+        prefill_batch_size: int = ...,
+        prefill_step_size: int = ...,
+    ) -> None: ...
+    def insert(
+        self, prompts, max_tokens: Union[List[int], int, None] = ...
+    ):  # -> list[Any]:
+        ...
+    def stats(self):  # -> BatchStats:
+        ...
+    def next(self):  # -> list[Any]:
+        ...

 def batch_generate(
    model,
    tokenizer,
-    prompts: List[List[int]],
-    prompt_caches: Optional[List[List[Any]]] = ...,
+    prompts: List[int],
    max_tokens: Union[int, List[int]] = ...,
    verbose: bool = ...,
-    return_prompt_caches: bool = ...,
-    logits_processors: Optional[List[Callable[[mx.array, mx.array], mx.array]]] = ...,
    **kwargs,
 ) -> BatchResponse:
    """
@@ -534,22 +309,14 @@ def batch_generate(
    Args:
       model (nn.Module): The language model.
       tokenizer (PreTrainedTokenizer): The tokenizer.
-       prompts (List[List[int]]): The input prompts.
-       prompt_caches (List[List[Any]], optional): Pre-computed prompt-caches
-          for each input prompt. Note, unlike ``generate_step``, the caches
-          won't be updated in-place.
+       prompt (List[List[int]]): The input prompts.
       verbose (bool): If ``True``, print tokens and timing information.
          Default: ``False``.
       max_tokens (Union[int, List[int]): Maximum number of output tokens. This
          can be per prompt if a list is provided.
-       return_prompt_caches (bool): Return the prompt caches in the batch
-          responses. Default: ``False``.
-       logits_processors (List[Callable[[mx.array, mx.array], mx.array]], optional):
-          A list of functions that take tokens and logits and return the processed logits. Default: ``None``.
       kwargs: The remaining options get passed to :obj:`BatchGenerator`.
          See :obj:`BatchGenerator` for more details.
    """
-    ...

 def main():  # -> None:
    ...
@@ -3,7 +3,7 @@ This type stub file was generated by pyright.
 """

 from dataclasses import dataclass
-from typing import Any, Optional
+from typing import Optional

 import mlx.core as mx

@@ -37,10 +37,10 @@ def quantized_scaled_dot_product_attention(
    bits: int = ...,
 ) -> mx.array: ...
 def scaled_dot_product_attention(
-    queries: mx.array,
-    keys: mx.array,
-    values: mx.array,
-    cache: Optional[Any],
+    queries,
+    keys,
+    values,
+    cache,
    scale: float,
    mask: Optional[mx.array],
    sinks: Optional[mx.array] = ...,
@@ -11,12 +11,9 @@ import mlx.core as mx
 class Cache(Protocol):
    keys: mx.array
    values: mx.array
-    offset: int
-    def update_and_fetch(
-        self, keys: mx.array, values: mx.array
-    ) -> tuple[mx.array, mx.array]: ...
+    def update_and_fetch(self, keys: mx.array, values: mx.array) -> None: ...
    @property
-    def state(self) -> tuple[mx.array | None, mx.array | None]: ...
+    def state(self) -> tuple[mx.array, mx.array]: ...
    @state.setter
    def state(self, v) -> None: ...

@@ -88,18 +85,16 @@ def create_attention_mask(
 ) -> array | Literal["causal"] | None: ...

 class _BaseCache(Cache):
-    keys: mx.array | None
-    values: mx.array | None
-    offset: int
+    keys: mx.array
+    values: mx.array
    @property
-    def state(self) -> tuple[mx.array | None, mx.array | None]: ...
+    def state(self) -> tuple[mx.array, mx.array]: ...
    @state.setter
    def state(self, v) -> None: ...
    @property
    def meta_state(self) -> Literal[""]: ...
    @meta_state.setter
    def meta_state(self, v) -> None: ...
-    def trim(self, n: int) -> int: ...
    def is_trimmable(self) -> Literal[False]: ...
    @classmethod
    def from_state(cls, state, meta_state) -> Self: ...
@@ -115,13 +110,15 @@ class ConcatenateKVCache(_BaseCache):
    def update_and_fetch(self, keys, values):  # -> tuple[Any | array, Any | array]:
        ...
    @property
-    def state(self) -> tuple[mx.array | None, mx.array | None]: ...
+    def state(self):  # -> tuple[Any | array | None, Any | array | None]:
+        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
    def is_trimmable(self):  # -> Literal[True]:
        ...
-    def trim(self, n: int) -> int: ...
+    def trim(self, n):  # -> int:
+        ...
    def make_mask(self, *args, **kwargs):  # -> array | Literal['causal'] | None:
        ...

@@ -131,7 +128,10 @@ class QuantizedKVCache(_BaseCache):
    def update_and_fetch(self, keys, values):  # -> Any:
        ...
    @property
-    def state(self) -> tuple[mx.array | None, mx.array | None]: ...
+    def state(
+        self,
+    ):  # -> tuple[Any | tuple[array, array, array] | None, Any | tuple[array, array, array] | None] | Any:
+        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
@@ -143,7 +143,8 @@ class QuantizedKVCache(_BaseCache):
        ...
    def is_trimmable(self):  # -> Literal[True]:
        ...
-    def trim(self, n: int) -> int: ...
+    def trim(self, n):  # -> int:
+        ...
    def make_mask(self, *args, **kwargs):  # -> array | Literal['causal'] | None:
        ...

@@ -155,30 +156,22 @@ class KVCache(_BaseCache):
    @property
    def state(
        self,
-    ) -> tuple[mx.array | None, mx.array | None]: ...
+    ) -> tuple[array, array]: ...
    @state.setter
    def state(self, v) -> None: ...
    def is_trimmable(self):  # -> Literal[True]:
        ...
-    def trim(self, n: int) -> int: ...
+    def trim(self, n):  # -> int:
+        ...
    def to_quantized(
        self, group_size: int = ..., bits: int = ...
    ) -> QuantizedKVCache: ...
-    def make_mask(
-        self, *args: Any, **kwargs: Any
-    ) -> mx.array | Literal["causal"] | None: ...
+    def make_mask(self, *args, **kwargs):  # -> array | Literal['causal'] | None:
+        ...

 class RotatingKVCache(_BaseCache):
    step = ...
-    keys: mx.array | None
-    values: mx.array | None
-    keep: int
-    max_size: int
-    _idx: int
    def __init__(self, max_size, keep=...) -> None: ...
-    def _trim(
-        self, trim_size: int, v: mx.array, append: mx.array | None = ...
-    ) -> mx.array: ...
    def update_and_fetch(
        self, keys, values
    ):  # -> tuple[array | Any, array | Any] | tuple[array | Any, array | Any | None]:
@@ -186,7 +179,8 @@ class RotatingKVCache(_BaseCache):
    @property
    def state(
        self,
-    ) -> tuple[mx.array | None, mx.array | None]: ...
+    ):  # -> tuple[Any | array, Any | array] | tuple[Any | array | None, Any | array | None]:
+        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
@@ -198,7 +192,8 @@ class RotatingKVCache(_BaseCache):
        ...
    def is_trimmable(self):  # -> bool:
        ...
-    def trim(self, n: int) -> int: ...
+    def trim(self, n):  # -> int:
+        ...
    def to_quantized(
        self, group_size: int = ..., bits: int = ...
    ) -> QuantizedKVCache: ...
@@ -213,7 +208,8 @@ class ArraysCache(_BaseCache):
        ...
    def __getitem__(self, idx): ...
    @property
-    def state(self) -> tuple[mx.array | None, mx.array | None]: ...
+    def state(self):  # -> list[Any | array] | list[array]:
+        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
@@ -227,7 +223,8 @@ class ArraysCache(_BaseCache):
        In-place extend this cache with the other cache.
        """

-    def make_mask(self, N: int) -> mx.array | None: ...
+    def make_mask(self, N: int):  # -> array | None:
+        ...

 class MambaCache(ArraysCache):
    def __init__(self, left_padding: Optional[List[int]] = ...) -> None: ...
@@ -238,7 +235,8 @@ class ChunkedKVCache(KVCache):
        ...
    def update_and_fetch(self, keys, values):  # -> tuple[array, array]:
        ...
-    def trim(self, n: int) -> int: ...
+    def trim(self, n):  # -> int:
+        ...
    @property
    def meta_state(self):  # -> tuple[str, ...]:
        ...
@@ -251,9 +249,10 @@ class CacheList(_BaseCache):
    def __getitem__(self, idx): ...
    def is_trimmable(self):  # -> bool:
        ...
-    def trim(self, n: int) -> int: ...
+    def trim(self, n): ...
    @property
-    def state(self) -> list[tuple[mx.array | None, mx.array | None]]: ...
+    def state(self):  # -> list[Any]:
+        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
@@ -268,14 +267,29 @@ class CacheList(_BaseCache):
        """

 class BatchKVCache(_BaseCache):
-    step: int
-    keys: array | None
-    values: array | None
-    offset: array
-    left_padding: array
-    _idx: int
-    def __init__(self, left_padding: List[int]) -> None: ...
-    def update_and_fetch(self, keys: array, values: array) -> tuple[array, array]: ...
+    step = ...
+    def __init__(self, left_padding: List[int]) -> None:
+        """
+        The BatchKV cache expects inputs to be left-padded.
+
+        E.g. the following prompts:
+
+            [1, 3, 5]
+            [7]
+            [2, 6, 8, 9]
+
+        Should be padded like so:
+
+            [0, 1, 3, 5]
+            [0, 0, 0, 7]
+            [2, 6, 8, 9]
+
+        And ``left_padding`` specifies the amount of padding for each.
+        In this case, ``left_padding = [1, 3, 0]``.
+        """
+
+    def update_and_fetch(self, keys, values):  # -> tuple[array | Any, array | Any]:
+        ...
    @property
    def state(
        self,
@@ -301,21 +315,12 @@ class BatchKVCache(_BaseCache):
        """

 class BatchRotatingKVCache(_BaseCache):
-    step: int
-    keys: array | None
-    values: array | None
-    offset: array
-    left_padding: array
-    max_size: int
-    _idx: int
-    _offset: int
-    rotated: bool
-    _lengths: array | None
-    def __init__(self, max_size: int, left_padding: List[int]) -> None: ...
-    def _trim(self, trim_size: int, v: array, append: array | None = ...) -> array: ...
-    def _update_in_place(self, keys: array, values: array) -> tuple[array, array]: ...
-    def _update_concat(self, keys: array, values: array) -> tuple[array, array]: ...
-    def update_and_fetch(self, keys: array, values: array) -> tuple[array, array]: ...
+    step = ...
+    def __init__(self, max_size, left_padding: List[int]) -> None: ...
+    def update_and_fetch(
+        self, keys, values
+    ):  # -> tuple[array | Any, array | Any] | tuple[array | Any, array | Any | None]:
+        ...
    @property
    def state(
        self,
@@ -57,11 +57,6 @@ class SwiGLU(nn.Module):
    def __call__(self, x, gate): ...

 class SwitchGLU(nn.Module):
-    gate_proj: SwitchLinear
-    up_proj: SwitchLinear
-    down_proj: SwitchLinear
-    activation: SwiGLU
-
    def __init__(
        self,
        input_dims: int,
@@ -73,9 +68,6 @@ class SwitchGLU(nn.Module):
    def __call__(self, x, indices) -> mx.array: ...

 class SwitchMLP(nn.Module):
-    fc1: SwitchLinear
-    fc2: SwitchLinear
-
    def __init__(
        self,
        input_dims: int,
@@ -48,11 +48,7 @@ def make_logits_processors(
    logit_bias: Optional[Dict[int, float]] = ...,
    repetition_penalty: Optional[float] = ...,
    repetition_context_size: Optional[int] = ...,
-    presence_penalty: Optional[float] = ...,
-    presence_context_size: Optional[int] = ...,
-    frequency_penalty: Optional[float] = ...,
-    frequency_context_size: Optional[int] = ...,
-) -> list[Callable[[mx.array, mx.array], mx.array]]:
+):  # -> list[Any]:
    """
    Make logits processors for use with ``generate_step``.

@@ -4,7 +4,6 @@ This type stub file was generated by pyright.

 from functools import partial
 from pathlib import Path
-from typing import Any

 from transformers import PreTrainedTokenizerFast

@@ -39,11 +38,11 @@ class StreamingDetokenizer:
    """

    __slots__ = ...
-    def reset(self) -> None: ...
-    def add_token(self, token: int) -> None: ...
-    def finalize(self) -> None: ...
+    def reset(self): ...
+    def add_token(self, token): ...
+    def finalize(self): ...
    @property
-    def last_segment(self) -> str:
+    def last_segment(self):
        """Return the last segment of readable text since last time this property was accessed."""

 class NaiveStreamingDetokenizer(StreamingDetokenizer):
@@ -104,62 +103,37 @@ class TokenizerWrapper:
    Accessing any attribute other than the ``detokenizer`` is forwarded to the
    huggingface tokenizer.
    """
+    def __init__(self, tokenizer, detokenizer_class=..., eos_token_ids=...) -> None: ...
+    def add_eos_token(self, token: str):  # -> None:
+        ...
+    @property
+    def has_thinking(self):  # -> bool:
+        ...
+    @property
+    def think_start(self):  # -> str | None:
+        ...
+    @property
+    def think_end(self):  # -> str | None:
+        ...
+    @property
+    def has_tool_calling(self):  # -> bool:
+        ...
+    @property
+    def tool_call_start(self):  # -> str | None:
+        ...
+    @property
+    def tool_call_end(self):  # -> str | None:
+        ...
+    @property
+    def detokenizer(self):  # -> NaiveStreamingDetokenizer:
+        """
+        Get a stateful streaming detokenizer.
+        """

-    _tokenizer: PreTrainedTokenizerFast
-    eos_token_id: int | None
-    eos_token: str | None
-    eos_token_ids: list[int] | set[int] | None
-    bos_token_id: int | None
-    bos_token: str | None
-    vocab_size: int
-    all_special_tokens: list[str]
-    think_start: str | None
-    think_end: str | None
-    think_start_id: int | None
-    think_end_id: int | None
-    think_start_tokens: list[int] | None
-    think_end_tokens: list[int] | None
-
-    def __init__(
-        self,
-        tokenizer: Any,
-        detokenizer_class: Any = ...,
-        eos_token_ids: list[int] | set[int] | None = ...,
-        chat_template: Any = ...,
-        tool_parser: Any = ...,
-        tool_call_start: str | None = ...,
-        tool_call_end: str | None = ...,
-    ) -> None: ...
-    def encode(self, text: str, **kwargs: Any) -> list[int]: ...
-    def decode(self, token_ids: list[int], **kwargs: Any) -> str: ...
-    def apply_chat_template(
-        self,
-        messages: list[dict[str, Any]],
-        tokenize: bool = False,
-        add_generation_prompt: bool = False,
-        tools: Any = None,
-        **kwargs: Any,
-    ) -> str: ...
-    def get_vocab(self) -> dict[str, int]: ...
-    def add_eos_token(self, token: str) -> None: ...
-    @property
-    def has_thinking(self) -> bool: ...
-    @property
-    def think_start(self) -> str | None: ...
-    @property
-    def think_end(self) -> str | None: ...
-    @property
-    def has_tool_calling(self) -> bool: ...
-    @property
-    def tool_call_start(self) -> str | None: ...
-    @property
-    def tool_call_end(self) -> str | None: ...
-    @property
-    def detokenizer(self) -> NaiveStreamingDetokenizer:
-        """Get a stateful streaming detokenizer."""
-
-    def __getattr__(self, attr: str) -> Any: ...
-    def __setattr__(self, attr: str, value: Any) -> None: ...
+    def __getattr__(self, attr):  # -> set[Any] | Any:
+        ...
+    def __setattr__(self, attr, value):  # -> None:
+        ...

 class NewlineTokenizer(PreTrainedTokenizerFast):
    """A tokenizer that replaces newlines with <n> and <n> with new line."""
@@ -172,11 +146,18 @@ class NewlineTokenizer(PreTrainedTokenizerFast):
    def batch_decode(self, *args, **kwargs):  # -> list[str]:
        ...

-def load(
+def load_tokenizer(
    model_path: Path,
-    tokenizer_config_extra: dict[str, Any] | None = None,
-    eos_token_ids: list[int] | int | None = None,
-) -> TokenizerWrapper:
+    tokenizer_config_extra=...,
+    return_tokenizer=...,
+    eos_token_ids=...,
+) -> (
+    TokenizerWrapper
+    | type[SPMStreamingDetokenizer]
+    | partial[SPMStreamingDetokenizer]
+    | type[BPEStreamingDetokenizer]
+    | type[NaiveStreamingDetokenizer]
+):
    """Load a huggingface tokenizer and try to infer the type of streaming
    detokenizer to use.

@@ -184,7 +165,4 @@ def load(
    a Hugging Face repo ID.
    """

-# Alias for backward compatibility
-load_tokenizer = load
-
-def no_bos_or_eos(sequence: list[int], bos: int, eos: int) -> list[int]: ...
+def no_bos_or_eos(sequence: list, bos: int, eos: int) -> list: ...
@@ -1,6 +0,0 @@
-{
-  "version": 1,
-  "indentation": {
-    "spaces": 4
-  }
-}
@@ -1,7 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import os
-
-if "TOKENIZERS_PARALLELISM" not in os.environ: ...
@@ -1,3 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
@@ -1,47 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-import PIL.Image
-import tqdm
-from typing import Protocol
-from mflux.models.common.config.config import Config
-
-class BeforeLoopCallback(Protocol):
-    def call_before_loop(
-        self,
-        seed: int,
-        prompt: str,
-        latents: mx.array,
-        config: Config,
-        canny_image: PIL.Image.Image | None = ...,
-        depth_image: PIL.Image.Image | None = ...,
-    ) -> None: ...
-
-class InLoopCallback(Protocol):
-    def call_in_loop(
-        self,
-        t: int,
-        seed: int,
-        prompt: str,
-        latents: mx.array,
-        config: Config,
-        time_steps: tqdm,
-    ) -> None: ...
-
-class AfterLoopCallback(Protocol):
-    def call_after_loop(
-        self, seed: int, prompt: str, latents: mx.array, config: Config
-    ) -> None: ...
-
-class InterruptCallback(Protocol):
-    def call_interrupt(
-        self,
-        t: int,
-        seed: int,
-        prompt: str,
-        latents: mx.array,
-        config: Config,
-        time_steps: tqdm,
-    ) -> None: ...
@@ -1,24 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from typing import TYPE_CHECKING
-from mflux.callbacks.callback import (
-    AfterLoopCallback,
-    BeforeLoopCallback,
-    InLoopCallback,
-    InterruptCallback,
-)
-from mflux.callbacks.generation_context import GenerationContext
-from mflux.models.common.config.config import Config
-
-if TYPE_CHECKING: ...
-
-class CallbackRegistry:
-    def __init__(self) -> None: ...
-    def register(self, callback) -> None: ...
-    def start(self, seed: int, prompt: str, config: Config) -> GenerationContext: ...
-    def before_loop_callbacks(self) -> list[BeforeLoopCallback]: ...
-    def in_loop_callbacks(self) -> list[InLoopCallback]: ...
-    def after_loop_callbacks(self) -> list[AfterLoopCallback]: ...
-    def interrupt_callbacks(self) -> list[InterruptCallback]: ...
@@ -1,29 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-import PIL.Image
-import tqdm
-from typing import TYPE_CHECKING
-from mflux.callbacks.callback_registry import CallbackRegistry
-from mflux.models.common.config.config import Config
-
-if TYPE_CHECKING: ...
-
-class GenerationContext:
-    def __init__(
-        self, registry: CallbackRegistry, seed: int, prompt: str, config: Config
-    ) -> None: ...
-    def before_loop(
-        self,
-        latents: mx.array,
-        *,
-        canny_image: PIL.Image.Image | None = ...,
-        depth_image: PIL.Image.Image | None = ...,
-    ) -> None: ...
-    def in_loop(self, t: int, latents: mx.array, time_steps: tqdm = ...) -> None: ...
-    def after_loop(self, latents: mx.array) -> None: ...
-    def interruption(
-        self, t: int, latents: mx.array, time_steps: tqdm = ...
-    ) -> None: ...
@@ -1,3 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
@@ -1,22 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import os
-
-BATTERY_PERCENTAGE_STOP_LIMIT = ...
-CONTROLNET_STRENGTH = ...
-DEFAULT_DEV_FILL_GUIDANCE = ...
-DEFAULT_DEPTH_GUIDANCE = ...
-DIMENSION_STEP_PIXELS = ...
-GUIDANCE_SCALE = ...
-GUIDANCE_SCALE_KONTEXT = ...
-IMAGE_STRENGTH = ...
-MODEL_CHOICES = ...
-MODEL_INFERENCE_STEPS = ...
-QUANTIZE_CHOICES = ...
-if os.environ.get("MFLUX_CACHE_DIR"):
-    MFLUX_CACHE_DIR = ...
-else:
-    MFLUX_CACHE_DIR = ...
-MFLUX_LORA_CACHE_DIR = ...
@@ -1,3 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
@@ -1,3 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
@@ -1,3 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
@@ -1,8 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from mflux.models.common.config.config import Config
-from mflux.models.common.config.model_config import ModelConfig
-
-__all__ = ["Config", "ModelConfig"]
@@ -1,66 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from pathlib import Path
-from typing import Any
-from tqdm import tqdm
-from mflux.models.common.config.model_config import ModelConfig
-
-logger = ...
-
-class Config:
-    def __init__(
-        self,
-        model_config: ModelConfig,
-        num_inference_steps: int = ...,
-        height: int = ...,
-        width: int = ...,
-        guidance: float = ...,
-        image_path: Path | str | None = ...,
-        image_strength: float | None = ...,
-        depth_image_path: Path | str | None = ...,
-        redux_image_paths: list[Path | str] | None = ...,
-        redux_image_strengths: list[float] | None = ...,
-        masked_image_path: Path | str | None = ...,
-        controlnet_strength: float | None = ...,
-        scheduler: str = ...,
-    ) -> None: ...
-    @property
-    def height(self) -> int: ...
-    @property
-    def width(self) -> int: ...
-    @width.setter
-    def width(self, value):  # -> None:
-        ...
-    @property
-    def image_seq_len(self) -> int: ...
-    @property
-    def guidance(self) -> float: ...
-    @property
-    def num_inference_steps(self) -> int: ...
-    @property
-    def precision(self) -> mx.Dtype: ...
-    @property
-    def num_train_steps(self) -> int: ...
-    @property
-    def image_path(self) -> Path | None: ...
-    @property
-    def image_strength(self) -> float | None: ...
-    @property
-    def depth_image_path(self) -> Path | None: ...
-    @property
-    def redux_image_paths(self) -> list[Path] | None: ...
-    @property
-    def redux_image_strengths(self) -> list[float] | None: ...
-    @property
-    def masked_image_path(self) -> Path | None: ...
-    @property
-    def init_time_step(self) -> int: ...
-    @property
-    def time_steps(self) -> tqdm: ...
-    @property
-    def controlnet_strength(self) -> float | None: ...
-    @property
-    def scheduler(self) -> Any: ...
@@ -1,86 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from functools import lru_cache
-from typing import Literal
-
-class ModelConfig:
-    precision: mx.Dtype = ...
-    def __init__(
-        self,
-        priority: int,
-        aliases: list[str],
-        model_name: str,
-        base_model: str | None,
-        controlnet_model: str | None,
-        custom_transformer_model: str | None,
-        num_train_steps: int | None,
-        max_sequence_length: int | None,
-        supports_guidance: bool | None,
-        requires_sigma_shift: bool | None,
-        transformer_overrides: dict | None = ...,
-    ) -> None: ...
-    @staticmethod
-    @lru_cache
-    def dev() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def schnell() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def dev_kontext() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def dev_fill() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def dev_redux() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def dev_depth() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def dev_controlnet_canny() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def schnell_controlnet_canny() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def dev_controlnet_upscaler() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def dev_fill_catvton() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def krea_dev() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def flux2_klein_4b() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def flux2_klein_9b() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def qwen_image() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def qwen_image_edit() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def fibo() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def z_image_turbo() -> ModelConfig: ...
-    @staticmethod
-    @lru_cache
-    def seedvr2_3b() -> ModelConfig: ...
-    def x_embedder_input_dim(self) -> int: ...
-    def is_canny(self) -> bool: ...
-    @staticmethod
-    def from_name(
-        model_name: str, base_model: Literal["dev", "schnell", "krea-dev"] | None = ...
-    ) -> ModelConfig: ...
-
-AVAILABLE_MODELS = ...
@@ -1,7 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-"""
-This type stub file was generated by pyright.
-"""
@@ -1,49 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from pathlib import Path
-from typing import TYPE_CHECKING, TypeAlias
-from mlx import nn
-from mflux.models.common.vae.tiling_config import TilingConfig
-from mflux.models.fibo.latent_creator.fibo_latent_creator import FiboLatentCreator
-from mflux.models.flux.latent_creator.flux_latent_creator import FluxLatentCreator
-from mflux.models.qwen.latent_creator.qwen_latent_creator import QwenLatentCreator
-from mflux.models.z_image.latent_creator.z_image_latent_creator import (
-    ZImageLatentCreator,
-)
-
-if TYPE_CHECKING:
-    LatentCreatorType: TypeAlias = type[
-        FiboLatentCreator | FluxLatentCreator | QwenLatentCreator | ZImageLatentCreator
-    ]
-
-class Img2Img:
-    def __init__(
-        self,
-        vae: nn.Module,
-        latent_creator: LatentCreatorType,
-        sigmas: mx.array,
-        init_time_step: int,
-        image_path: str | Path | None,
-        tiling_config: TilingConfig | None = ...,
-    ) -> None: ...
-
-class LatentCreator:
-    @staticmethod
-    def create_for_txt2img_or_img2img(
-        seed: int, height: int, width: int, img2img: Img2Img
-    ) -> mx.array: ...
-    @staticmethod
-    def encode_image(
-        vae: nn.Module,
-        image_path: str | Path,
-        height: int,
-        width: int,
-        tiling_config: TilingConfig | None = ...,
-    ) -> mx.array: ...
-    @staticmethod
-    def add_noise_by_interpolation(
-        clean: mx.array, noise: mx.array, sigma: float
-    ) -> mx.array: ...
@@ -1,3 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
@@ -1,13 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from mlx import nn
-from mflux.models.common.lora.layer.linear_lora_layer import LoRALinear
-
-class FusedLoRALinear(nn.Module):
-    def __init__(
-        self, base_linear: nn.Linear | nn.QuantizedLinear, loras: list[LoRALinear]
-    ) -> None: ...
-    def __call__(self, x):  # -> array:
-        ...
@@ -1,22 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from mlx import nn
-
-class LoRALinear(nn.Module):
-    @staticmethod
-    def from_linear(
-        linear: nn.Linear | nn.QuantizedLinear, r: int = ..., scale: float = ...
-    ):  # -> LoRALinear:
-        ...
-    def __init__(
-        self,
-        input_dims: int,
-        output_dims: int,
-        r: int = ...,
-        scale: float = ...,
-        bias: bool = ...,
-    ) -> None: ...
-    def __call__(self, x):  # -> array:
-        ...
@@ -1,26 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-import mlx.nn as nn
-from collections.abc import Callable
-from dataclasses import dataclass
-from mflux.models.common.lora.mapping.lora_mapping import LoRATarget
-
-@dataclass
-class PatternMatch:
-    source_pattern: str
-    target_path: str
-    matrix_name: str
-    transpose: bool
-    transform: Callable[[mx.array], mx.array] | None = ...
-
-class LoRALoader:
-    @staticmethod
-    def load_and_apply_lora(
-        lora_mapping: list[LoRATarget],
-        transformer: nn.Module,
-        lora_paths: list[str] | None = ...,
-        lora_scales: list[float] | None = ...,
-    ) -> tuple[list[str], list[float]]: ...
@@ -1,21 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import List, Protocol
-
-@dataclass
-class LoRATarget:
-    model_path: str
-    possible_up_patterns: List[str]
-    possible_down_patterns: List[str]
-    possible_alpha_patterns: List[str] = ...
-    up_transform: Callable[[mx.array], mx.array] | None = ...
-    down_transform: Callable[[mx.array], mx.array] | None = ...
-
-class LoRAMapping(Protocol):
-    @staticmethod
-    def get_mapping() -> List[LoRATarget]: ...
@@ -1,9 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.nn as nn
-
-class LoRASaver:
-    @staticmethod
-    def bake_and_strip_lora(module: nn.Module) -> nn.Module: ...
@@ -1,35 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-
-class LoraTransforms:
-    @staticmethod
-    def split_q_up(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_k_up(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_v_up(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_q_down(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_k_down(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_v_down(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_single_q_up(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_single_k_up(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_single_v_up(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_single_mlp_up(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_single_q_down(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_single_k_down(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_single_v_down(tensor: mx.array) -> mx.array: ...
-    @staticmethod
-    def split_single_mlp_down(tensor: mx.array) -> mx.array: ...
@@ -1,17 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from mflux.models.common.resolution.config_resolution import ConfigResolution
-from mflux.models.common.resolution.lora_resolution import LoraResolution
-from mflux.models.common.resolution.path_resolution import PathResolution
-from mflux.models.common.resolution.quantization_resolution import (
-    QuantizationResolution,
-)
-
-__all__ = [
-    "ConfigResolution",
-    "LoraResolution",
-    "PathResolution",
-    "QuantizationResolution",
-]
@@ -1,39 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from enum import Enum
-from typing import NamedTuple
-
-class QuantizationAction(Enum):
-    NONE = ...
-    STORED = ...
-    REQUESTED = ...
-
-class PathAction(Enum):
-    LOCAL = ...
-    HUGGINGFACE_CACHED = ...
-    HUGGINGFACE = ...
-    ERROR = ...
-
-class LoraAction(Enum):
-    LOCAL = ...
-    REGISTRY = ...
-    HUGGINGFACE_COLLECTION_CACHED = ...
-    HUGGINGFACE_COLLECTION = ...
-    HUGGINGFACE_REPO_CACHED = ...
-    HUGGINGFACE_REPO = ...
-    ERROR = ...
-
-class ConfigAction(Enum):
-    EXACT_MATCH = ...
-    EXPLICIT_BASE = ...
-    INFER_SUBSTRING = ...
-    ERROR = ...
-
-class Rule(NamedTuple):
-    priority: int
-    name: str
-    check: str
-    action: QuantizationAction | PathAction | LoraAction | ConfigAction
-    ...
@@ -1,14 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from typing import TYPE_CHECKING
-from mflux.models.common.config.model_config import ModelConfig
-
-if TYPE_CHECKING: ...
-logger = ...
-
-class ConfigResolution:
-    RULES = ...
-    @staticmethod
-    def resolve(model_name: str, base_model: str | None = ...) -> ModelConfig: ...
@@ -1,21 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from pathlib import Path
-
-logger = ...
-
-class LoraResolution:
-    RULES = ...
-    _registry: dict[str, Path] = ...
-    @staticmethod
-    def resolve(path: str) -> str: ...
-    @staticmethod
-    def resolve_paths(paths: list[str] | None) -> list[str]: ...
-    @staticmethod
-    def resolve_scales(scales: list[float] | None, num_paths: int) -> list[float]: ...
-    @staticmethod
-    def get_registry() -> dict[str, Path]: ...
-    @staticmethod
-    def discover_files(library_paths: list[Path]) -> dict[str, Path]: ...
@@ -1,12 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from pathlib import Path
-
-logger = ...
-
-class PathResolution:
-    RULES = ...
-    @staticmethod
-    def resolve(path: str | None, patterns: list[str] | None = ...) -> Path | None: ...
@@ -1,12 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-logger = ...
-
-class QuantizationResolution:
-    RULES = ...
-    @staticmethod
-    def resolve(
-        stored: int | None, requested: int | None
-    ) -> tuple[int | None, str | None]: ...
@@ -1,26 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from .flow_match_euler_discrete_scheduler import FlowMatchEulerDiscreteScheduler
-from .linear_scheduler import LinearScheduler
-from .seedvr2_euler_scheduler import SeedVR2EulerScheduler
-
-__all__ = [
-    "LinearScheduler",
-    "FlowMatchEulerDiscreteScheduler",
-    "SeedVR2EulerScheduler",
-]
-
-class SchedulerModuleNotFound(ValueError): ...
-class SchedulerClassNotFound(ValueError): ...
-class InvalidSchedulerType(TypeError): ...
-
-SCHEDULER_REGISTRY = ...
-
-def register_contrib(scheduler_object, scheduler_name=...):  # -> None:
-    ...
-def try_import_external_scheduler(
-    scheduler_object_path: str,
-):  # -> type[BaseScheduler]:
-    ...
@@ -1,16 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from abc import ABC, abstractmethod
-
-class BaseScheduler(ABC):
-    @property
-    @abstractmethod
-    def sigmas(self) -> mx.array: ...
-    @abstractmethod
-    def step(
-        self, noise: mx.array, timestep: int, latents: mx.array, **kwargs
-    ) -> mx.array: ...
-    def scale_model_input(self, latents: mx.array, t: int) -> mx.array: ...
@@ -1,26 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from typing import TYPE_CHECKING
-from mflux.models.common.config.config import Config
-from mflux.models.common.schedulers.base_scheduler import BaseScheduler
-
-if TYPE_CHECKING: ...
-
-class FlowMatchEulerDiscreteScheduler(BaseScheduler):
-    def __init__(self, config: Config) -> None: ...
-    @property
-    def sigmas(self) -> mx.array: ...
-    @property
-    def timesteps(self) -> mx.array: ...
-    def set_image_seq_len(self, image_seq_len: int) -> None: ...
-    @staticmethod
-    def get_timesteps_and_sigmas(
-        image_seq_len: int, num_inference_steps: int, num_train_timesteps: int = ...
-    ) -> tuple[mx.array, mx.array]: ...
-    def step(
-        self, noise: mx.array, timestep: int, latents: mx.array, **kwargs
-    ) -> mx.array: ...
-    def scale_model_input(self, latents: mx.array, t: int) -> mx.array: ...
@@ -1,20 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from typing import TYPE_CHECKING
-from mflux.models.common.config.config import Config
-from mflux.models.common.schedulers.base_scheduler import BaseScheduler
-
-if TYPE_CHECKING: ...
-
-class LinearScheduler(BaseScheduler):
-    def __init__(self, config: Config) -> None: ...
-    @property
-    def sigmas(self) -> mx.array: ...
-    @property
-    def timesteps(self) -> mx.array: ...
-    def step(
-        self, noise: mx.array, timestep: int, latents: mx.array, **kwargs
-    ) -> mx.array: ...
@@ -1,20 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from typing import TYPE_CHECKING
-from mflux.models.common.config.config import Config
-from mflux.models.common.schedulers.base_scheduler import BaseScheduler
-
-if TYPE_CHECKING: ...
-
-class SeedVR2EulerScheduler(BaseScheduler):
-    def __init__(self, config: Config) -> None: ...
-    @property
-    def timesteps(self) -> mx.array: ...
-    @property
-    def sigmas(self) -> mx.array: ...
-    def step(
-        self, noise: mx.array, timestep: int, latents: mx.array, **kwargs
-    ) -> mx.array: ...
@@ -1,24 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from mflux.models.common.tokenizer.tokenizer import (
-    BaseTokenizer,
-    LanguageTokenizer,
-    Tokenizer,
-    VisionLanguageTokenizer,
-)
-from mflux.models.common.tokenizer.tokenizer_loader import TokenizerLoader
-from mflux.models.common.tokenizer.tokenizer_output import TokenizerOutput
-
-"""
-This type stub file was generated by pyright.
-"""
-__all__ = [
-    "Tokenizer",
-    "BaseTokenizer",
-    "LanguageTokenizer",
-    "VisionLanguageTokenizer",
-    "TokenizerLoader",
-    "TokenizerOutput",
-]
@@ -1,74 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from abc import ABC, abstractmethod
-from typing import Protocol, runtime_checkable
-from PIL import Image
-from transformers import PreTrainedTokenizer
-from mflux.models.common.tokenizer.tokenizer_output import TokenizerOutput
-
-"""
-This type stub file was generated by pyright.
-"""
-
-@runtime_checkable
-class Tokenizer(Protocol):
-    tokenizer: PreTrainedTokenizer
-    def tokenize(
-        self,
-        prompt: str | list[str],
-        images: list[Image.Image] | None = ...,
-        max_length: int | None = ...,
-        **kwargs,
-    ) -> TokenizerOutput: ...
-
-class BaseTokenizer(ABC):
-    def __init__(
-        self, tokenizer: PreTrainedTokenizer, max_length: int = ...
-    ) -> None: ...
-    @abstractmethod
-    def tokenize(
-        self,
-        prompt: str | list[str],
-        images: list[Image.Image] | None = ...,
-        max_length: int | None = ...,
-        **kwargs,
-    ) -> TokenizerOutput: ...
-
-class LanguageTokenizer(BaseTokenizer):
-    def __init__(
-        self,
-        tokenizer: PreTrainedTokenizer,
-        max_length: int = ...,
-        padding: str = ...,
-        return_attention_mask: bool = ...,
-        template: str | None = ...,
-        use_chat_template: bool = ...,
-        chat_template_kwargs: dict | None = ...,
-        add_special_tokens: bool = ...,
-    ) -> None: ...
-    def tokenize(
-        self,
-        prompt: str | list[str],
-        images: list[Image.Image] | None = ...,
-        max_length: int | None = ...,
-        **kwargs,
-    ) -> TokenizerOutput: ...
-
-class VisionLanguageTokenizer(BaseTokenizer):
-    def __init__(
-        self,
-        tokenizer: PreTrainedTokenizer,
-        processor,
-        max_length: int = ...,
-        template: str | None = ...,
-        image_token: str = ...,
-    ) -> None: ...
-    def tokenize(
-        self,
-        prompt: str | list[str],
-        images: list[Image.Image] | None = ...,
-        max_length: int | None = ...,
-        **kwargs,
-    ) -> TokenizerOutput: ...
@@ -1,22 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from typing import TYPE_CHECKING
-from mflux.models.common.tokenizer.tokenizer import BaseTokenizer
-from mflux.models.common.weights.loading.weight_definition import TokenizerDefinition
-
-"""
-This type stub file was generated by pyright.
-"""
-if TYPE_CHECKING: ...
-
-class TokenizerLoader:
-    @staticmethod
-    def load(definition: TokenizerDefinition, model_path: str) -> BaseTokenizer: ...
-    @staticmethod
-    def load_all(
-        definitions: list[TokenizerDefinition],
-        model_path: str,
-        max_length_overrides: dict[str, int] | None = ...,
-    ) -> dict[str, BaseTokenizer]: ...
@@ -1,17 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from dataclasses import dataclass
-
-"""
-This type stub file was generated by pyright.
-"""
-
-@dataclass
-class TokenizerOutput:
-    input_ids: mx.array
-    attention_mask: mx.array
-    pixel_values: mx.array | None = ...
-    image_grid_thw: mx.array | None = ...
@@ -1,8 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from mflux.models.common.vae.tiling_config import TilingConfig
-from mflux.models.common.vae.vae_tiler import VAETiler
-
-__all__ = ["TilingConfig", "VAETiler"]
@@ -1,13 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from dataclasses import dataclass
-
-@dataclass(frozen=True, slots=True)
-class TilingConfig:
-    vae_decode_tiles_per_dim: int | None = ...
-    vae_decode_overlap: int = ...
-    vae_encode_tiled: bool = ...
-    vae_encode_tile_size: int = ...
-    vae_encode_tile_overlap: int = ...
@@ -1,27 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from typing import Callable
-
-class VAETiler:
-    @staticmethod
-    def encode_image_tiled(
-        *,
-        image: mx.array,
-        encode_fn: Callable[[mx.array], mx.array],
-        latent_channels: int,
-        tile_size: tuple[int, int] = ...,
-        tile_overlap: tuple[int, int] = ...,
-        spatial_scale: int = ...,
-    ) -> mx.array: ...
-    @staticmethod
-    def decode_image_tiled(
-        *,
-        latent: mx.array,
-        decode_fn: Callable[[mx.array], mx.array],
-        tile_size: tuple[int, int] = ...,
-        tile_overlap: tuple[int, int] = ...,
-        spatial_scale: int = ...,
-    ) -> mx.array: ...
@@ -1,17 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-import mlx.core as mx
-from mlx import nn
-from mflux.models.common.vae.tiling_config import TilingConfig
-
-class VAEUtil:
-    @staticmethod
-    def encode(
-        vae: nn.Module, image: mx.array, tiling_config: TilingConfig | None = ...
-    ) -> mx.array: ...
-    @staticmethod
-    def decode(
-        vae: nn.Module, latent: mx.array, tiling_config: TilingConfig | None = ...
-    ) -> mx.array: ...
@@ -1,18 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from mflux.models.common.weights.loading.loaded_weights import LoadedWeights, MetaData
-from mflux.models.common.weights.loading.weight_applier import WeightApplier
-from mflux.models.common.weights.loading.weight_definition import ComponentDefinition
-from mflux.models.common.weights.loading.weight_loader import WeightLoader
-from mflux.models.common.weights.saving.model_saver import ModelSaver
-
-__all__ = [
-    "ComponentDefinition",
-    "LoadedWeights",
-    "MetaData",
-    "ModelSaver",
-    "WeightApplier",
-    "WeightLoader",
-]
@@ -1,18 +0,0 @@
-"""
-This type stub file was generated by pyright.
-"""
-
-from dataclasses import dataclass
-
-@dataclass
-class MetaData:
-    quantization_level: int | None = ...
-    mflux_version: str | None = ...
-
-@dataclass
-class LoadedWeights:
-    components: dict[str, dict]
-    meta_data: MetaData
-    def __getattr__(self, name: str) -> dict | None: ...
-    def num_transformer_blocks(self, component_name: str = ...) -> int: ...
-    def num_single_transformer_blocks(self, component_name: str = ...) -> int: ...