Otaku

Discover, search, and learn about anime from inside Discord — powered by AniList.

A plugin for YourBot (the platform formerly known as MMO Maid) — runs sandboxed in the platform and reacts to slash-command interactions on installed servers.

What it does

Otaku gives your server a small set of slash commands for finding anime: look one up by name, browse a genre, see what's trending this season, or pull recommendations similar to a show you've already looked at. Every command answers with a rich Discord embed (cover art, score, episode count, genre tags, a short description, and a link to the AniList page). The plugin caches each user's most recent /anime lookup for 7 days so /similar works with no arguments — handy when you've already found the show you care about and just want "more like this." Primary data comes from AniList's public GraphQL API, with MAL (Jikan) and Kitsu as fallback search sources — the plugin reaches exactly the three declared proxy domains. Stored data: each user's tracking rows (watch status, rating, episodes, favorites, reviews, subscriptions — see the SQL schema below) plus the small KV keys in the table below.

Capabilities

This plugin requests the following capabilities. Each is listed in manifest.json with a one-line rationale so server admins know why it's needed before they install:

The plugin uses one Discord-side write capability — discord:send_message — exclusively for posting airing notifications to a server-designated channel. A manifest-backed @plugin.cron("5 * * * *") runs the airing and seasonal-digest checks hourly at :05 UTC for each installed server. All other Discord interactions are slash command replies.

Dashboard

A two-page manifest-mode dashboard ships with the plugin. Server admins can view it from the YourBot dev portal:

• Overview — four stat cards (tracked rows, active users 30d, episodes watched, airing subscriptions), a watch-status bar chart, and a top-5-tracked-anime table.
• Settings — pick the airing-announcement channel without leaving the portal (mirrors /otaku-admin set-channel).

All widgets read from the existing SQL tables — no new capability required.

If/when new capabilities are added, update this table and CHANGELOG.md.

Slash commands

Politeness throttle

Every command that reaches AniList (or SQL) checks an ephemeral per-user cooldown (otaku:user:<id>, 2 s) first — the lone exception is /help, which only reads the manifest. The cooldown is sandbox-side only — AniList itself permits ~90 req/min globally, and the platform proxy enforces 30/min per (server, plugin). The 2 s per-user throttle stops a single chatty user from monopolising either budget.

Reliability & observability

The HTTP transport is best-effort by design — any upstream failure logs and returns "no results" rather than crashing a handler:

• Multi-source fallback — /anime and /manga fall through AniList → MAL (Jikan) → Kitsu, so one source being down doesn't kill search.
• Compression-proof bodies — requests send Accept-Encoding: identity and recover gzip bytes client-side (v10.0.14), after a live incident where the platform proxy passed compressed bodies through lossily.
• Thread-safe throttling — the per-source rate buckets and the response cache are lock-guarded (v10.0.16), since the platform runs several dispatcher threads per worker; the limiter can't overshoot an upstream budget or raise into a handler.
• Metrics & tracing — every real transport call emits one http.request metric tagged {source, outcome} (v10.0.15; a spike in outcome=non_2xx / timeout / bad_body is the tell for an upstream/proxy incident), and every transport error/anomaly log carries the interaction's request_id (v10.0.16) so a burst correlates to its cause. ctx.metrics and ctx.log need no capability.

KV key convention

Durable KV keys (ctx.kv):

last_anime:user:<discord_user_id>   →   <anilist_media_id>   (TTL: 7 days, per-user)
last_manga:user:<discord_user_id>   →   <anilist_media_id>   (TTL: 7 days, per-user)
pref:lang:user:<discord_user_id>    →   "en" | "ja" | ...    (no TTL, per-user)
pref:spoilers:user:<discord_user_id>→   "hide" | "show"      (no TTL, per-user)
genres:global                       →   ["Action", ...]      (TTL: 24h, server-wide)
notify_channel:guild                →   "<channel_id>"       (no TTL, server-wide)
premieres_digest_last:guild         →   "<SEASON>_<YEAR>"    (no TTL, server-wide)
otaku:schema_version                →   "<version>"          (bootstrap-complete marker)
otaku:schema_v8_migrated            →   "1"                  (v7→v8 migration marker)
otaku:schema_ddl_idx                →   "<n>"                (v10.0.11 bootstrap resume cursor)
otaku:schema_pk_verified            →   "1"                  (v10.0.12 one-time wide-PK check marker)

Ephemeral keys (ctx.ephemeral, Redis-backed, evictable): otaku:user:<id> (2 s command cooldown) and otaku:airing:<media_id>:<episode> (24 h announce-once dedup).

KV is per-server and per-plugin, so the same user is tracked independently on each server. The 7-day TTL means an inactive user's cache expires on its own — no explicit cleanup needed. KV is wiped automatically on uninstall.

SQL schema

Rows are auto-scoped to ctx.server_id by the runner, so no table has an explicit server_id column. The core tracking table (created otaku_user_anime in v2.0.0, renamed and widened in v8.0.0 for manga support):

CREATE TABLE IF NOT EXISTS otaku_user_media (
  user_id      TEXT NOT NULL,
  media_id     INTEGER NOT NULL,
  media_type   TEXT NOT NULL DEFAULT 'anime',  -- v8.0.0: anime | manga
  status       TEXT NOT NULL,                  -- watching | completed | on_hold | dropped | plan
  is_favorite  BOOLEAN NOT NULL DEFAULT FALSE,
  rating       SMALLINT,                       -- v2.1.0: score × 2 (2..20)
  episodes_watched SMALLINT DEFAULT 0,         -- v2.2.0 (carries chapters for manga rows)
  added_at     TIMESTAMP NOT NULL DEFAULT NOW(),
  PRIMARY KEY (user_id, media_id, media_type)
);
CREATE INDEX IF NOT EXISTS otaku_user_media_user_status_added_idx
  ON otaku_user_media (user_id, status, added_at DESC);

-- v3.0.0:
CREATE TABLE IF NOT EXISTS otaku_server_watchlist (
  media_id   INTEGER NOT NULL,
  added_by   TEXT NOT NULL,
  added_at   TIMESTAMP NOT NULL DEFAULT NOW(),
  note       TEXT,
  PRIMARY KEY (media_id)
);

-- v3.2.0:
CREATE TABLE IF NOT EXISTS otaku_watch_parties (
  party_id   SERIAL PRIMARY KEY,
  media_id   INTEGER NOT NULL,
  created_by TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  status     TEXT NOT NULL DEFAULT 'active'  -- active | completed | abandoned
);
CREATE TABLE IF NOT EXISTS otaku_watch_party_members (
  party_id          INTEGER NOT NULL,
  user_id           TEXT NOT NULL,
  episodes_watched  SMALLINT NOT NULL DEFAULT 0,
  joined_at         TIMESTAMP NOT NULL DEFAULT NOW(),
  PRIMARY KEY (party_id, user_id)
);

-- v4.0.0:
CREATE TABLE IF NOT EXISTS otaku_notifications (
  user_id    TEXT NOT NULL,
  media_id   INTEGER NOT NULL,
  channel_id TEXT,
  added_at   TIMESTAMP NOT NULL DEFAULT NOW(),
  PRIMARY KEY (user_id, media_id)
);

Later versions add: otaku_reviews (v7.0), otaku_aotw_polls / otaku_aotw_candidates / otaku_aotw_votes (v7.1), otaku_polls / otaku_poll_options / otaku_poll_votes (v7.2), and otaku_achievements (v10.0) — 13 tables across a 16-statement bootstrap. The canonical, ordered list lives in _SCHEMA_DDL_SEQUENCE in __main__.py.

The DDL is idempotent (IF NOT EXISTS) and runs from both @plugin.on_install and @plugin.on_ready. The on_ready path covers pool-mode workers picking up a tenant that upgraded from v1.x (where on_install does not re-fire). The host rate-limits DDL (~5 statements/hour per tenant), so bootstrap resumes across worker boots via the otaku:schema_ddl_idx KV cursor (v10.0.11) instead of replaying from the top.

Custom_id namespace

All component custom_ids are prefixed with otaku::

Quick start (development)

# 1. Clone & install
git clone https://github.com/CubCadetXT1/mmo-maid-plugin-otaku.git
cd mmo-maid-plugin-otaku
# The venv must live OUTSIDE the repo — the validator rejects a top-level .venv/
python -m venv ../mmo-maid-plugin-otaku-venv && source ../mmo-maid-plugin-otaku-venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

# 2. Local dev loop (hot-reload + mock host)
yourbot dev --watch

# 3. Tests
python -m pytest -q

# 4. Lint (ruff — also runs in CI)
make lint

# 5. Pre-flight validation (also runs in CI). Use make — it cleans first:
#    test runs leave __pycache__/.pytest_cache at the repo top level, which
#    the validator's layout check rejects.
make validate

yourbot dev fires events from events.yaml against a MockContext, prints every action the plugin takes, and reloads on file change. See SDK docs for the full developer workflow.

Release process

Releases are tagged on main with semver tags (v1.2.3), which triggers .github/workflows/release.yml to validate, test, build the upload zip, and attach it to the GitHub release.

# 1. Bump manifest.json "version" and update CHANGELOG.md
# 2. Verify locally
make release          # validates, tests, builds dist/otaku-<version>.zip

# 3. Commit, tag, push
git commit -am "Release v1.2.3"
git tag v1.2.3
git push && git push --tags

The tag's version (v1.2.3 → 1.2.3) must match manifest.json's version field; CI rejects the release otherwise.

Submitting for review

The YourBot dev portal links to this repo and pulls a specific tag for review. Review turnaround is typically 1–3 business days. The reviewer checks the manifest, scans for disallowed imports and unparameterised SQL, and re-prompts users on any tier shift.

License

MIT — see LICENSE.