animedex.models.trace

Trace.moe screenshot-search models.

TraceHit is the typed shape returned by animedex trace search: each hit carries the AniList id (so the result can be chained into the AniList backend for richer metadata), the episode and timecode where the frame appears, a similarity score, and optional preview media URLs.

TraceQuota is the typed shape of animedex trace quota (GET /me). The upstream returns the caller’s IP in the id field; the mapper unconditionally drops it before constructing the record (of #4 covered the same vector for fixtures).

TraceHit

class animedex.models.trace.TraceHit(*, anilist_id: int, anilist_title: AnimeTitle | None = None, similarity: Annotated[float, Ge(ge=0.0), Le(le=1.0)], episode: str | None = None, start_at_seconds: float, frame_at_seconds: float, end_at_seconds: float, episode_filename: str | None = None, episode_duration_seconds: float | None = None, preview_video_url: str | None = None, preview_image_url: str | None = None, source: SourceTag)[source]

Bases: AnimedexModel

A single Trace.moe match.

Variables:

  • anilist_id (int) – AniList identifier of the matched series. Use this to chain into the AniList backend for full metadata.

  • anilist_title (AnimeTitle or None) – AniList title block, populated when the /search call was made with anilistInfo=true. Saves a follow-up AniList round-trip.

  • similarity (float) – Match confidence in the closed interval [0, 1]. Trace.moe documentation considers values below ~0.87 unreliable.

  • episode (str or None) – Episode identifier (string-typed because some matches return non-integer values like "1.5" for OVAs).

  • start_at_seconds (float) – Scene start timestamp inside the episode, in seconds.

  • frame_at_seconds (float) – Exact matched-frame timestamp, in seconds. Lies between start_at_seconds and end_at_seconds.

  • end_at_seconds (float) – Scene end timestamp, in seconds.

  • episode_filename (str or None) – Source video filename. Useful for human verification of the match (e.g. "[Group][Show][05][1080p].mkv").

  • episode_duration_seconds (float or None) – Total length of the matched episode, in seconds.

  • preview_video_url (str or None) – Short MP4 preview of the matched scene.

  • preview_image_url (str or None) – Single-frame JPEG preview.

  • source (SourceTag) – Provenance tag.

anilist_id: int
anilist_title: AnimeTitle | None
similarity: float
episode: str | None
start_at_seconds: float
frame_at_seconds: float
end_at_seconds: float
episode_filename: str | None
episode_duration_seconds: float | None
preview_video_url: str | None
preview_image_url: str | None
source: SourceTag

TraceQuota

class animedex.models.trace.TraceQuota(*, priority: int, concurrency: int, quota: int, quota_used: int, source: SourceTag)[source]

Bases: AnimedexModel

Trace.moe quota state for the calling client.

Returned by GET /me. The upstream payload also carries an id field that holds the caller’s egress IP — the mapper drops it unconditionally so the value never appears in cache rows or rendered output.

Variables:

  • priority (int) – API priority class (0 for anonymous, higher for sponsor / patron tiers).

  • concurrency (int) – Max simultaneous searches the tier allows. Anonymous tier: 1.

  • quota (int) – Monthly search budget.

  • quota_used (int) – Searches consumed this month. Upstream returns this as a JSON string; the mapper coerces to int.

  • source (SourceTag) – Provenance tag.

priority: int
concurrency: int
quota: int
quota_used: int
source: SourceTag

selftest

animedex.models.trace.selftest() → bool[source]

Smoke-test the trace models.

Returns:

True on success; raises on schema errors.

Return type:

bool