From bae3326e3569cca5475f8ff9f35b64f96f1f754f Mon Sep 17 00:00:00 2001 From: oiupoyt Date: Sun, 27 Sep 2026 18:49:01 +0530 Subject: [PATCH] docs: add live server invite and adopt minimalist style --- README.md | 69 ++++++++++++++++++++++++++----------------------------- 1 file changed, 33 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 80564ae..db47c09 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,44 @@ -# Model Radar ๐Ÿ“ก๐Ÿค– +# Model Radar [![CI](https://github.com/oiupoyt/model-radar/actions/workflows/ci.yml/badge.svg)](https://github.com/oiupoyt/model-radar/actions) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](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. +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 real-time catalog release alerts and live auto-updating dashboards directly to Discord servers. + +A live instance is running 24/7. You can see the bot in action and test commands here: +**[Join the Live Discord Server](https://discord.gg/dJ5MhVCGh)** --- -## โœจ Features +## 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. +- **Live Auto-Updating Dashboard:** Running `/watch` posts a persistent public dashboard embed in your channel that automatically refreshes every poll interval (`POLL_SECONDS`), featuring new drops at the top and active stealth/experimental models directly on the first page. +- **Interactive Component 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 ` to instantly find any model in the catalog as you type. +- **Direct OpenRouter Links:** Embed titles link directly to the model's page on OpenRouter for quick browser inspection. +- **Pricing per 1M Tokens:** Model inspection computes readable rates per 1 Million tokens (e.g. `$0.15 / 1M tokens`). - **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`). + - `min_context`: Ignore models with context windows below a given token threshold (e.g. `32,768`). - `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`). +- **Opt-In Role Pings:** Server-level ping configuration supporting 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. +- **Queue Bounds:** Unreachable alert channels (e.g., deleted channel or revoked 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. -- **Live Auto-Updating Dashboard:** Running `/watch` posts a persistent public dashboard embed in your alert channel that automatically refreshes every poll interval (`POLL_SECONDS`), featuring new drops at the top and active stealth/experimental models directly on the first page. -- **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 ` 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: +## 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 [compact] [show_pricing] [public]` | Configurable | Inspect detailed specifications with live model ID autocomplete and direct clickable links to OpenRouter. | +| `/model [compact] [show_pricing] [public]` | Configurable | Inspect detailed specifications with live model ID autocomplete, cost per 1M tokens, and direct clickable links to OpenRouter. | | `/watch [ping_role] [free_only] [search] [min_context] [ping_enabled] [compact] [clear_role]` | Manage Server | Posts a public live auto-updating dashboard in the channel and configures drop alerts. Supports any role or `@everyone`. | | `/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. | @@ -45,20 +47,17 @@ All interactions use Discord Slash Commands: --- -## ๐Ÿš€ Getting Started +## 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**. +1. Open 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). + - Click **Reset Token** to generate a bot 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` + - **Bot Permissions:** Select `View Channels`, `Send Messages`, and `Embed Links`. 4. Open the generated invite URL in your browser to invite the bot to your server. --- @@ -67,7 +66,7 @@ All interactions use Discord Slash Commands: | Variable | Required | Default | Description | | :--- | :---: | :---: | :--- | -| `DISCORD_TOKEN` | **Yes** | โ€” | Discord Bot Token from the Developer Portal. | +| `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`. | @@ -85,17 +84,17 @@ All interactions use Discord Slash Commands: cd model-radar ``` -2. Create a `.env` file from the example: +2. Create `.env` from example: ```bash cp .env.example .env ``` - Edit `.env` and fill in your `DISCORD_TOKEN`. + Edit `.env` and set `DISCORD_TOKEN`. 3. Launch the container: ```bash docker compose up -d ``` - State will be persisted in the `./data` directory. + State persists in `./data`. #### Option B: Native Cargo Run @@ -113,25 +112,23 @@ cargo run --release --locked --- -## ๐Ÿ› ๏ธ Setting Up Alerts in Discord +## Setting Up Alerts in Discord -1. In your Discord server, pick a role for notifications (e.g. `@ModelAlerts`, `@everyone`, or any custom role). +1. Pick a role for notifications (e.g. `@ModelAlerts`, `@everyone`, or any custom role). 2. In the channel where alerts should be posted, run: - ``` + ```text /watch ping_role:@ModelAlerts ping_enabled:true ``` *(Or `/watch ping_role:@everyone ping_enabled:true` to notify everyone).* 3. Verify the setup by running: - ``` + ```text /testping ``` -5. Check your active server configuration at any time with `/stats`. +4. 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: +## Development & Testing ```bash # Run unit and integration tests @@ -146,6 +143,6 @@ cargo fmt --check --- -## ๐Ÿ“„ License +## License This project is licensed under the [MIT License](LICENSE).