# FreeRide 🦞

FreeRide is a dynamic model rotation and failover system for PicoClaw that leverages OpenRouter's free model pool. It ensures your agent stays alive even if individual free models become rate-limited or go offline.

## Key Features

- **Automatic Discovery**: Scans OpenRouter for the best currently available free models.
- **Dynamic Failover**: Automatically rotates through a pool of models when errors (like 429 Rate Limiting) occur.
- **Intelligent Ranking**: Models are scored and ranked based on context length, capabilities (tools/vision), and provider trust.
- **K3s Ready**: Designed to work seamlessly in Kubernetes environments with secure API key management.
- **Visual Provenance (🦞)**: Responses generated via a fallback model are clearly marked with a "lobster" emoji and the model name, providing transparency about which model handled your request.

## Configuration

FreeRide is implemented as a native PicoClaw tool.

### 1. Enable the Tool
Ensure the `skills` tool is enabled in your `config.json` (FreeRide is bundled with the skills system):
 
```json
{
  "tools": {
    "skills": {
      "enabled": true
    }
  }
}
```

### 2. Set the API Key
FreeRide requires an OpenRouter API key. Even for free models, many providers require a key for identification and higher rate limits.

PicoClaw supports dynamic environment variable resolution using the `env://` scheme.

In **Local Mode** or **Docker**, set the environment variable:
```bash
export OPENROUTER_API_KEY="sk-or-v1-..."
```

Then in your `config.json`, use:
```json
{
  "api_keys": ["env://OPENROUTER_API_KEY"]
}
```
*(Note: `freeride auto` will automatically configure this for you.)*

In **K3s Mode**, add the secret to your cluster (see below).

## Usage

You can interact with FreeRide directly through the agent:

### `freeride auto`
**The most important command.** This command:
1. Fetches the current list of ~28+ free models.
2. Ranks them by quality.
3. Automatically populates your `config.json`'s `model_list`.
4. Adds the top 5 models to your agent's `model_fallbacks` list.
5. Reloads the agent configuration instantly.

### `freeride status`
Shows your current primary model and the active fallback rotation pool.

### `freeride list [limit]`
Displays the current top-ranked free models available on OpenRouter without modifying your configuration.

## K3s Deployment & Secrets

When running PicoClaw on K3s, follow these steps to manage your secrets safely.

### Adding the Secret
If you are creating the secrets for the first time:
```bash
kubectl create secret generic picoclaw-secrets \
  --namespace agi \
  --from-literal=openrouter-api-key="YOUR_KEY_HERE"
```

### Updating Existing Secrets (Safe Patching)
If `picoclaw-secrets` already exists and you want to add the OpenRouter key without losing your Telegram or NVIDIA keys, use **`kubectl patch`**:

```bash
kubectl patch secret picoclaw-secrets \
  --namespace agi \
  --type='json' \
  -p='[{"op": "add", "path": "/data/openrouter-api-key", "value":"'$(echo -n "YOUR_KEY_HERE" | base64 -w0)'"}]'
```

### Deployment Configuration
Ensure your `deployment.yaml` maps the secret to the environment variable:

```yaml
env:
  - name: OPENROUTER_API_KEY
    valueFrom:
      secretKeyRef:
        name: picoclaw-secrets
        key: openrouter-api-key
```

## Cooldown Persistence & Timing ❄️
 
To prevent the agent from "hanging" or retrying known-failed models, PicoClaw uses a two-pronged approach:
 
### 1. Zero-Amnesia Persistence
Model failures (e.g., 429 Rate Limits) are saved to `~/.picoclaw/cooldowns.json`. This ensures that if you restart the agent, it **remembers** which models were saturated and skips them instantly. You no longer have to wait through a series of timeouts every time you restart.
 
### 2. Aggressive 30s Timeout
The default request timeout for LLM calls is **30 seconds**. If a free model is stalled or unresponsive, the agent will move to the next fallback in your pool much faster than the standard HTTP default.
 
## Troubleshooting

- **404 Errors**: Ensure the model is still available on OpenRouter using `freeride list`. If it's gone, run `freeride auto` to refresh your fallback pool.
- **429 Rate Limiting**: This is common with free models. PicoClaw will automatically try the next model in your `model_fallbacks` list and persist the cooldown to `cooldowns.json`.

---

## Legal & Responsible Use 🛡️

FreeRide is provided for **personal assistance, educational research, and infrastructure failover** purposes only. By using this capability, you acknowledge and agree to the following:

1.  **Terms of Service**: You are responsible for complying with [OpenRouter's Terms of Service](https://openrouter.ai/terms) and the individual "Acceptable Use Policies" of each model provider (e.g., Google, Meta, Mistral).
2.  **No Guarantee of Service**: Free models are provided "as-is" by third parties. They may be withdrawn, rate-limited, or modified at any time without notice. 
3.  **No Reselling**: You should not use FreeRide to build commercial services that "resell" free model access in a way that violates provider licenses (check specific model licenses like Llama 3 Community or Qwen for commercial usage thresholds).
4.  **Rate Limit Respect**: PicoClaw handles failover automatically, but users should not use FreeRide to intentionally overwhelm or evade the fair-use rate limits of providers.

*PicoClaw is an independent tool and is not affiliated with OpenRouter or any specific LLM provider.*