150 lines
7 KiB
Markdown
150 lines
7 KiB
Markdown
# Model Radar 📡🤖
|
|
|
|
[](https://github.com/oiupoyt/model-radar/actions)
|
|
[](LICENSE)
|
|
|
|
A lightweight, crash-resilient Discord bot built in Rust with [poise](https://github.com/serenity-rs/poise) and [serenity](https://github.com/serenity-rs/serenity). Model Radar monitors [OpenRouter](https://openrouter.ai)'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:** Mentionable role pings configured per server. Explicitly disallows `@everyone` and `@here` mentions to protect against ping abuse.
|
|
- **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 `/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 |
|
|
| :--- | :--- | :--- |
|
|
| `/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 [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. 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
|
|
|
|
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and create a **New Application**.
|
|
2. 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).
|
|
3. Navigate to **OAuth2 → URL Generator**:
|
|
- **Scopes:** Select `bot` and `applications.commands`.
|
|
- **Bot Permissions:** Select:
|
|
- `View Channels`
|
|
- `Send Messages`
|
|
- `Embed Links`
|
|
4. 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)
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://github.com/oiupoyt/model-radar.git
|
|
cd model-radar
|
|
```
|
|
|
|
2. Create a `.env` file from the example:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
Edit `.env` and fill in your `DISCORD_TOKEN`.
|
|
|
|
3. Launch the container:
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
State will be persisted in the `./data` directory.
|
|
|
|
#### Option B: Native Cargo Run
|
|
|
|
Prerequisites: [Rust 1.85+ (Edition 2024)](https://rustup.rs/)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. In your Discord server, create an opt-in role for notifications (e.g. `@ModelAlerts`).
|
|
2. Ensure the role is **mentionable** in Server Settings → Roles.
|
|
3. In the channel where alerts should be posted, run:
|
|
```
|
|
/watch role:@ModelAlerts ping_enabled:true
|
|
```
|
|
4. Verify the setup by running:
|
|
```
|
|
/testping
|
|
```
|
|
5. 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:
|
|
|
|
```bash
|
|
# 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](LICENSE).
|