Model Radar 📡🤖

A lightweight, crash-resilient Discord bot built in Rust with poise and serenity. Model Radar monitors OpenRouter's live model catalog for free LLMs (:free and exact $0 pricing) and dispatches configurable release alerts and role pings directly to your Discord server.

✨ Features

Automated OpenRouter Monitoring: Periodically polls the public OpenRouter models API (/api/v1/models) with configurable intervals.
Accurate Zero-Price Detection: String-based decimal parsing identifies genuine free-tier models (including scientific notation like 0e-9999) while rejecting precision artifacts, non-zero pricing, and tiered overrides.
Flexible Subscription Filters:
- free_only: Target free models or watch all new catalog entries.
- search: Filter releases by model identifier or name (e.g., qwen, llama, coder).
- min_context: Ignore models with context windows below a given token threshold (e.g. 32768).
- compact: Dense notification rows for high-volume channels.
Controlled Opt-In Role Pings: Role pings configured per server (supports custom roles as well as @everyone).
Crash-Resilient State: Subscriptions and catalog states are stored atomically (.tmp write followed by atomic filesystem rename) to guarantee state integrity across crashes and container reboots.
Queue Bounds: Unreachable alert channels (e.g., deleted channel or revoked bot permissions) are capped at 50 queued events, preventing unbounded state growth.
Discord API Safety: Strict UTF-16 character limit enforcement and markdown character escaping prevent broken embeds or Discord 400 Bad Request rejections.
Interactive Discord Buttons: Multi-page /free-models and /status views include interactive [◀ Prev] and [Next ▶] buttons with automatic timeout disabling.
Model ID Autocomplete: Live slash command autocomplete for /model <id> to instantly find any model in the catalog as you type.
Direct OpenRouter Web Links: Embed titles link directly to the model's page on OpenRouter for quick inspection in the browser.
Dry-Run Diagnostic Mode: Test public catalog availability and parsing without needing a Discord token (--check).

📋 Slash Commands

All interactions use Discord Slash Commands:

Command	Scope	Description
`/free-models [search] [page]`	Public / Ephemeral	Browse all currently available free models in OpenRouter's catalog with interactive `[◀ Prev]` / `[Next ▶]` buttons and search filter.
`/status [free_only] [search] [min_context] [page] [page_size] [compact] [public]`	Configurable	View a catalog freshness snapshot with model counts, interactive pagination, and token constraints.
`/model <id> [compact] [show_pricing] [public]`	Configurable	Inspect detailed specifications with live model ID autocomplete and direct clickable links to OpenRouter.
`/watch [ping_role] [free_only] [search] [min_context] [ping_enabled] [compact] [clear_role]`	Manage Server	Set up or update automatic catalog release alerts in the current channel. Supports any role or `@everyone`. Omitted options retain existing settings.
`/unwatch`	Manage Server	Remove the server's subscription and delete all queued pending alerts.
`/stats`	Ephemeral	View catalog freshness, last successful fetch timestamp, polling interval, and complete server subscription settings.
`/testping`	Manage Server	Dispatch a labeled test notification to verify channel permissions and role mentionability without modifying catalog state.
`/about`	Ephemeral	Display bot information, command guide, poll interval, and optional operator support link.

🚀 Getting Started

1. Create a Discord Bot Application

Go to the Discord Developer Portal and create a New Application.
Navigate to the Bot tab:
- Click Reset Token to generate a bot token. Copy this token for your DISCORD_TOKEN environment variable.
- Note: No Privileged Gateway Intents are required (Model Radar does not require Message Content, Server Members, or Presence intents).
Navigate to OAuth2 → URL Generator:
- Scopes: Select bot and applications.commands.
- Bot Permissions: Select:
  - View Channels
  - Send Messages
  - Embed Links
Open the generated invite URL in your browser to invite the bot to your server.

2. Configuration & Environment Variables

Variable	Required	Default	Description
`DISCORD_TOKEN`	Yes	—	Discord Bot Token from the Developer Portal.
`POLL_SECONDS`	No	`600`	Catalog polling interval in seconds (allowed: `60` to `86400`).
`STATE_PATH`	No	`state.json`	Path where subscription settings and catalog state are stored.
`SUPPORT_URL`	No	—	Optional HTTPS URL (e.g. Ko-fi, GitHub Sponsors) shown in `/about`.
`DISCORD_GUILD_ID`	No	—	Guild ID for instant slash command registration during testing (global registration takes up to an hour).

3. Deployment Options

Option A: Docker Compose (Recommended)

Clone the repository:

git clone https://github.com/oiupoyt/model-radar.git
cd model-radar

Create a .env file from the example:
```
cp .env.example .env
```
Edit .env and fill in your DISCORD_TOKEN.
Launch the container:
```
docker compose up -d
```
State will be persisted in the ./data directory.

Option B: Native Cargo Run

Prerequisites: Rust 1.85+ (Edition 2024)

# Verify catalog connection and parsing (no token required)
cargo run --locked -- --check

# Run the bot
export DISCORD_TOKEN="your_bot_token"
export POLL_SECONDS=600
cargo run --release --locked

🛠️ Setting Up Alerts in Discord

In your Discord server, pick a role for notifications (e.g. @ModelAlerts, @everyone, or any custom role).
In the channel where alerts should be posted, run:
```
/watch ping_role:@ModelAlerts ping_enabled:true
```
(Or /watch ping_role:@everyone ping_enabled:true to notify everyone).
Verify the setup by running:
```
/testping
```
Check your active server configuration at any time with /stats.

🧪 Development & Testing

Model Radar includes a comprehensive test suite covering catalog parsing, pricing edge cases, store migrations, and Discord embed safety:

# Run unit and integration tests
cargo test --locked

# Run linter
cargo clippy --all-targets -- -D warnings

# Check code formatting
cargo fmt --check

📄 License

This project is licensed under the MIT License.

7 KiB Raw Blame History