deapi-mcp 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,756 @@
1
+ """Model-aware tool description enrichment middleware for FastMCP.
2
+
3
+ Intercepts tools/list responses and appends available model information
4
+ (slugs, parameter limits, guidance requirements) to each tool's description.
5
+ This helps LLMs choose correct models and parameters without needing to call
6
+ get_available_models first.
7
+
8
+ Opt-in via DEAPI_ENRICH_TOOL_DESCRIPTIONS=true env var.
9
+ """
10
+
11
+ import asyncio
12
+ import hashlib
13
+ import hmac
14
+ import logging
15
+ import secrets
16
+ import time
17
+ from collections import OrderedDict
18
+ from dataclasses import dataclass, field
19
+ from typing import Any, Dict, List, Optional, Sequence, cast
20
+
21
+ import mcp.types as mt
22
+ from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
23
+ from fastmcp.tools import Tool
24
+
25
+ from .auth import current_deapi_token
26
+ from .observability import errors_tolerated
27
+ from .schemas import ModelInfo
28
+
29
+ logger = logging.getLogger(__name__)
30
+
31
+
32
+ # ---------------------------------------------------------------------------
33
+ # Inference type → MCP tool name mapping
34
+ # ---------------------------------------------------------------------------
35
+
36
+ TEST_MODEL_STATUS = "test_model"
37
+ TEST_MODEL_NOTE = (
38
+ " Models marked (test model) are experimental: they may change or disappear. "
39
+ "Prefer an unmarked model unless the caller asks for one of them."
40
+ )
41
+
42
+ INFERENCE_TYPE_TO_TOOLS: Dict[str, List[str]] = {
43
+ "txt2img": ["text_to_image", "text_to_image_price"],
44
+ "img2img": ["image_to_image", "image_to_image_price"],
45
+ "txt2video": ["text_to_video", "text_to_video_price"],
46
+ "img2video": ["image_to_video", "image_to_video_price"],
47
+ "audio2video": ["audio_to_video", "audio_to_video_price"],
48
+ "txt2audio": ["text_to_audio", "text_to_audio_price"],
49
+ "txt2music": ["text_to_music", "text_to_music_price"],
50
+ "txt2embedding": ["text_to_embedding", "text_to_embedding_price"],
51
+ "audio_file2text": ["audio_transcription", "audio_transcription_price"],
52
+ "audio2text": ["audio_url_transcription", "audio_url_transcription_price"],
53
+ "video2text": ["video_url_transcription", "video_url_transcription_price"],
54
+ "video_file2text": ["video_file_transcription", "video_file_transcription_price"],
55
+ "img2txt": ["image_to_text", "image_to_text_price"],
56
+ "img-rmbg": ["image_remove_background", "image_remove_background_price"],
57
+ "img-upscale": ["image_upscale", "image_upscale_price"],
58
+ # One tool, two types: the API picks video2desc for a URL and video_file2desc for an upload.
59
+ "video2desc": ["video_description", "video_description_price"],
60
+ "video_file2desc": ["video_description", "video_description_price"],
61
+ "vid-upscale": ["video_upscale", "video_upscale_price"],
62
+ }
63
+
64
+
65
+ # ---------------------------------------------------------------------------
66
+ # Model cache
67
+ # ---------------------------------------------------------------------------
68
+
69
+
70
+ @dataclass
71
+ class _ModelCache:
72
+ """One account's model catalogue, indexed by tool name and by slug."""
73
+
74
+ lock: asyncio.Lock = field(default_factory=asyncio.Lock)
75
+ tool_models: Dict[str, List[ModelInfo]] = field(default_factory=dict)
76
+ models_by_slug: Dict[str, ModelInfo] = field(default_factory=dict)
77
+ enrichments: Dict[str, str] = field(default_factory=dict)
78
+ # None = never. Not 0.0: monotonic() counts from boot, so on a host up for less
79
+ # than the TTL a 0.0 stamp would read as a fresh fetch.
80
+ last_fetched: Optional[float] = None
81
+ last_miss_refresh: Optional[float] = None
82
+ key: str = ""
83
+
84
+ def is_stale(self, ttl: float) -> bool:
85
+ return self.last_fetched is None or (time.monotonic() - self.last_fetched) > ttl
86
+
87
+
88
+ DEFAULT_CACHE_TTL = 300.0
89
+ # A model missing from a fresh catalogue (e.g. just granted to the account)
90
+ # triggers a refetch at most this often, so unknown slugs cannot flood the API.
91
+ MISS_REFRESH_INTERVAL = 30.0
92
+ MAX_CACHED_USERS = 1000
93
+ # Tokens whose catalogue has not been fetched successfully yet. Any string is
94
+ # accepted as a bearer token, so these are kept apart: random tokens can only
95
+ # churn this small pool, never evict users whose catalogue loaded.
96
+ MAX_UNCONFIRMED_USERS = 256
97
+
98
+
99
+ def _set_bounded(
100
+ entries: "OrderedDict[str, _ModelCache]", key: str, cache: _ModelCache, limit: int
101
+ ) -> None:
102
+ entries[key] = cache
103
+ while len(entries) > limit:
104
+ entries.popitem(last=False)
105
+
106
+
107
+ class _PerUserCaches:
108
+ """One catalogue per deAPI token, least recently used evicted first.
109
+
110
+ Accounts do not all see the same models, so a catalogue fetched with one
111
+ user's token must never describe or default another user's calls. Entries
112
+ are keyed by an HMAC of the token under a per-process random key, so the
113
+ raw token is never held as a key and the key means nothing outside this
114
+ process. An entry joins the main pool only once a fetch with its token
115
+ succeeds (``confirm``).
116
+ """
117
+
118
+ def __init__(
119
+ self,
120
+ max_entries: int = MAX_CACHED_USERS,
121
+ max_unconfirmed: int = MAX_UNCONFIRMED_USERS,
122
+ ) -> None:
123
+ self.max_entries = max_entries
124
+ self.max_unconfirmed = max_unconfirmed
125
+ self._entries: "OrderedDict[str, _ModelCache]" = OrderedDict()
126
+ self._unconfirmed: "OrderedDict[str, _ModelCache]" = OrderedDict()
127
+ self._hmac_key = secrets.token_bytes(32)
128
+
129
+ def _user_key(self, token: Optional[str]) -> str:
130
+ if not token:
131
+ return ""
132
+ return hmac.new(self._hmac_key, token.encode(), hashlib.sha256).hexdigest()
133
+
134
+ def current(self) -> _ModelCache:
135
+ """The cache of the user whose token is on the current request."""
136
+ key = self._user_key(current_deapi_token.get())
137
+ cache = self._entries.get(key)
138
+ if cache is not None:
139
+ self._entries.move_to_end(key)
140
+ return cache
141
+ cache = self._unconfirmed.get(key)
142
+ if cache is not None:
143
+ self._unconfirmed.move_to_end(key)
144
+ return cache
145
+ cache = _ModelCache(key=key)
146
+ _set_bounded(self._unconfirmed, key, cache, self.max_unconfirmed)
147
+ return cache
148
+
149
+ def confirm(self, cache: _ModelCache) -> None:
150
+ """Move a cache whose fetch succeeded into the main pool."""
151
+ if self._unconfirmed.get(cache.key) is cache:
152
+ del self._unconfirmed[cache.key]
153
+ _set_bounded(self._entries, cache.key, cache, self.max_entries)
154
+
155
+ def __len__(self) -> int:
156
+ return len(self._entries)
157
+
158
+ def clear(self) -> None:
159
+ self._entries.clear()
160
+ self._unconfirmed.clear()
161
+
162
+
163
+ _caches = _PerUserCaches()
164
+
165
+
166
+ class _CurrentUserCache:
167
+ """``_cache.x`` reads and writes the calling user's ``_ModelCache``."""
168
+
169
+ def __getattr__(self, name: str) -> Any:
170
+ return getattr(_caches.current(), name)
171
+
172
+ def __setattr__(self, name: str, value: Any) -> None:
173
+ setattr(_caches.current(), name, value)
174
+
175
+
176
+ _cache = _CurrentUserCache()
177
+
178
+
179
+ def _needs_miss_refresh(cache: _ModelCache, model: Optional[str]) -> bool:
180
+ return (
181
+ bool(model)
182
+ and cache.last_fetched is not None
183
+ and model not in cache.models_by_slug
184
+ and (
185
+ cache.last_miss_refresh is None
186
+ or (time.monotonic() - cache.last_miss_refresh) > MISS_REFRESH_INTERVAL
187
+ )
188
+ )
189
+
190
+
191
+ async def ensure_model_cache(ttl: float = DEFAULT_CACHE_TTL, model: Optional[str] = None) -> None:
192
+ """Populate or refresh the caller's model cache when it is older than ``ttl``.
193
+
194
+ Tools call this before reading a card, so a call that arrives before any
195
+ tools/list — or right after a restart — still resolves the model's own
196
+ defaults instead of guessing. Passing ``model`` also refetches a fresh
197
+ catalogue that lacks that slug (at most once per MISS_REFRESH_INTERVAL),
198
+ so a model the account gained since the last fetch is found. A failed
199
+ fetch is logged and stamped like a refresh, so an unreachable catalogue
200
+ is retried once per TTL rather than on every call.
201
+ """
202
+ cache = _caches.current()
203
+ if not cache.is_stale(ttl) and not _needs_miss_refresh(cache, model):
204
+ return
205
+ async with cache.lock:
206
+ stale = cache.is_stale(ttl)
207
+ if not stale and not _needs_miss_refresh(cache, model):
208
+ return
209
+ if not stale:
210
+ cache.last_miss_refresh = time.monotonic()
211
+ try:
212
+ # The catalogue is optional here: a failed fetch is survived, so an error
213
+ # it notes must not become the label of the tool call that triggered it.
214
+ with errors_tolerated():
215
+ await _fetch_and_index_models(cache)
216
+ except Exception:
217
+ logger.warning("Failed to fetch the model catalogue", exc_info=True)
218
+ cache.last_fetched = time.monotonic()
219
+
220
+
221
+ # ---------------------------------------------------------------------------
222
+ # Public cache accessors
223
+ # ---------------------------------------------------------------------------
224
+
225
+
226
+ def get_cached_model(slug: str) -> Optional[ModelInfo]:
227
+ """Look up a model by slug from the cache.
228
+
229
+ Returns None if the model is not in the cache (e.g., cache not yet
230
+ populated or model slug unknown).
231
+ """
232
+ return cast(Optional[ModelInfo], _cache.models_by_slug.get(slug))
233
+
234
+
235
+ def get_cached_models_for_tool(tool_name: str) -> List[ModelInfo]:
236
+ """Get all cached models available for a given tool name."""
237
+ return cast(List[ModelInfo], _cache.tool_models.get(tool_name, []))
238
+
239
+
240
+ # ---------------------------------------------------------------------------
241
+ # Formatting helpers
242
+ # ---------------------------------------------------------------------------
243
+
244
+
245
+ def _format_model_info(model: ModelInfo) -> str:
246
+ """Format a single model into a concise one-line description.
247
+
248
+ Shows slug and key parameters: steps, size, guidance, fps, frames, LoRAs.
249
+ """
250
+ head = f" - `{model.slug}`"
251
+ if is_test_model(model):
252
+ head += " (test model)"
253
+
254
+ info = model.info
255
+ if not isinstance(info, dict):
256
+ return head
257
+
258
+ limits = info.get("limits") or {}
259
+ defaults = info.get("defaults") or {}
260
+ features = info.get("features") or {}
261
+
262
+ parts: List[str] = []
263
+
264
+ # Steps
265
+ min_steps = limits.get("min_steps")
266
+ max_steps = limits.get("max_steps")
267
+ default_steps = defaults.get("steps")
268
+ if min_steps is not None and max_steps is not None:
269
+ if str(min_steps) == str(max_steps):
270
+ parts.append(f"steps={min_steps} (fixed)")
271
+ else:
272
+ step_str = f"steps={min_steps}-{max_steps}"
273
+ if default_steps is not None:
274
+ step_str += f" (default {default_steps})"
275
+ parts.append(step_str)
276
+
277
+ # Size (width x height)
278
+ min_w = limits.get("min_width")
279
+ max_w = limits.get("max_width")
280
+ min_h = limits.get("min_height")
281
+ max_h = limits.get("max_height")
282
+ if all(v is not None for v in [min_w, max_w, min_h, max_h]):
283
+ types = model.inference_types if isinstance(model.inference_types, list) else []
284
+ label: Optional[str] = (
285
+ "input size" if types and set(types) <= _INPUT_SIZED_TYPES else "size"
286
+ )
287
+ parts.append(f"{label}={min_w}-{max_w}x{min_h}-{max_h}")
288
+ edits = isinstance(model.inference_types, list) and "img2img" in model.inference_types
289
+ if edits and _flag(features, "supports_custom_output_size") is False:
290
+ # Image edits: width/height are dropped and the output keeps the input's size.
291
+ parts.append("output size = input size")
292
+
293
+ # Guidance
294
+ supports_guidance = str(features.get("supports_guidance", "1"))
295
+ if supports_guidance == "0":
296
+ g_val = defaults.get("guidance", "0")
297
+ parts.append(f"guidance={g_val} (FIXED, must use this value)")
298
+ else:
299
+ min_g = limits.get("min_guidance")
300
+ max_g = limits.get("max_guidance")
301
+ default_g = defaults.get("guidance")
302
+ if min_g is not None and max_g is not None:
303
+ if str(min_g) == str(max_g):
304
+ parts.append(f"guidance={min_g} (fixed)")
305
+ else:
306
+ g_str = f"guidance={min_g}-{max_g}"
307
+ if default_g is not None:
308
+ g_str += f" (default {default_g})"
309
+ parts.append(g_str)
310
+
311
+ # FPS (video models)
312
+ min_fps = limits.get("min_fps")
313
+ max_fps = limits.get("max_fps")
314
+ if min_fps is not None and max_fps is not None:
315
+ if str(min_fps) == str(max_fps):
316
+ parts.append(f"fps={min_fps} (fixed)")
317
+ else:
318
+ parts.append(f"fps={min_fps}-{max_fps}")
319
+
320
+ # Frames (video models)
321
+ min_frames = limits.get("min_frames")
322
+ max_frames = limits.get("max_frames")
323
+ if min_frames is not None and max_frames is not None:
324
+ parts.append(f"frames={min_frames}-{max_frames}")
325
+
326
+ # Duration (music models)
327
+ min_dur = limits.get("min_duration")
328
+ max_dur = limits.get("max_duration")
329
+ if min_dur is not None and max_dur is not None:
330
+ parts.append(f"duration={min_dur}-{max_dur}s")
331
+
332
+ # BPM (music models)
333
+ min_bpm = limits.get("min_bpm")
334
+ max_bpm = limits.get("max_bpm")
335
+ if min_bpm is not None and max_bpm is not None:
336
+ parts.append(f"bpm={min_bpm}-{max_bpm}")
337
+
338
+ # Bounds the API enforces with a 422 that the LLM has no other way to know.
339
+ # Each is shown only when the card publishes it (many are null), and each
340
+ # maps to an error already observed against the live API.
341
+ # Input images only exist on edits; a txt2img-only card still carries the count.
342
+ bounds_limits = (
343
+ limits if edits else {k: v for k, v in limits.items() if k != "max_input_images"}
344
+ )
345
+ parts.extend(_format_request_bounds(bounds_limits, defaults))
346
+ parts.extend(_format_transcription(features, limits))
347
+
348
+ # A reference/driving audio window on a model that is neither TTS (shown on
349
+ # its languages line) nor a multi-reference video model (shown under refs).
350
+ max_ref_audios = limits.get("max_ref_audios")
351
+ if not model.languages and not (
352
+ isinstance(max_ref_audios, (int, float)) and max_ref_audios > 0
353
+ ):
354
+ types = model.inference_types if isinstance(model.inference_types, list) else []
355
+ label = (
356
+ "ref_audio"
357
+ if "txt2music" in types
358
+ else "audio2video audio" if "audio2video" in types else None
359
+ )
360
+ window = (
361
+ _range(limits, "min_ref_audio_duration", "max_ref_audio_duration", label, "s")
362
+ if label
363
+ else None
364
+ )
365
+ if window:
366
+ parts.append(window)
367
+
368
+ # The API silently drops negative_prompt on these; say so where it would be sent.
369
+ types = model.inference_types if isinstance(model.inference_types, list) else []
370
+ if _flag(features, "supports_negative_prompt") is False and set(types) & _GENERATION_TYPES:
371
+ parts.append("no negative_prompt")
372
+
373
+ # LoRAs: the API validates `name`, not the display name, so list the names.
374
+ if model.loras:
375
+ names: List[Any] = [
376
+ getattr(lora, "name", None) or (lora.get("name") if isinstance(lora, dict) else None)
377
+ for lora in model.loras
378
+ ]
379
+ names = [n for n in names if n]
380
+ parts.append(
381
+ f"loras: {', '.join(names)}" if names else f"{len(model.loras)} LoRAs available"
382
+ )
383
+
384
+ # TTS: mode, output format, then languages and voices on their own line
385
+ tts_line = _format_tts_languages(model, features, limits)
386
+ if tts_line:
387
+ mode = next(
388
+ (m for f, m in _TTS_MODE_FEATURES if str(features.get(f)).lower() in ("1", "true")),
389
+ None,
390
+ )
391
+ if mode:
392
+ parts.append(f"mode={mode}")
393
+ fmts = limits.get("output_formats")
394
+ if isinstance(fmts, list) and fmts:
395
+ parts.append(f"format={'/'.join(map(str, fmts))}")
396
+
397
+ line = f"{head}: {', '.join(parts)}" if parts else head
398
+ return f"{line}\n{tts_line}" if tts_line else line
399
+
400
+
401
+ def is_test_model(model: ModelInfo) -> bool:
402
+ """Whether the catalogue flags this model as a test model."""
403
+ return model.status == TEST_MODEL_STATUS
404
+
405
+
406
+ def _range(
407
+ limits: Dict[str, Any], lo_key: str, hi_key: str, label: str, unit: str = ""
408
+ ) -> Optional[str]:
409
+ """'label=lo-hi' when the card publishes both ends, else None."""
410
+ lo, hi = limits.get(lo_key), limits.get(hi_key)
411
+ if lo is None and hi is None:
412
+ return None
413
+ if lo is not None and hi is not None:
414
+ if str(lo) == str(hi):
415
+ return f"{label}={lo}{unit} (fixed)"
416
+ return f"{label}={lo}-{hi}{unit}"
417
+ return f"{label}≤{hi}{unit}" if hi is not None else f"{label}≥{lo}{unit}"
418
+
419
+
420
+ def _format_request_bounds(
421
+ limits: Dict[str, Any], defaults: Optional[Dict[str, Any]] = None
422
+ ) -> List[str]:
423
+ """Per-request limits the API validates, grouped by the tool they affect.
424
+
425
+ Kept to the ones that produce a 422 the LLM could not have predicted:
426
+ - images: dimension multiples, pixel/side/ratio caps, input-image count,
427
+ accepted quality tiers (1024x1024 on a 1,032,192-px model was a live 422)
428
+ - TTS: text length, speed, sample rate (our Field said speed 0.1-3.0;
429
+ Kokoro accepts 0.5-2)
430
+ - transcription: which ts_level values the model implements
431
+ (WhisperLargeV3 is segment-only; word needs WhisperLargeV3Ct2)
432
+ - video / upscale / music / embedding: their own caps
433
+ """
434
+ out: List[str] = []
435
+
436
+ # --- images
437
+ # `dimension_multiple` is the real grid, and the API snaps to it rather than
438
+ # rejecting. `resolution_step` is the web UI's slider step and is never
439
+ # enforced (ValidatesDimensionLimits), so it is not shown.
440
+ step = limits.get("dimension_multiple")
441
+ if step and str(step) not in ("0", "1"):
442
+ out.append(f"w/h rounded down to a multiple of {step}")
443
+ if limits.get("max_pixels"):
444
+ out.append(f"≤{limits['max_pixels'] / 1e6:.2f}Mpx")
445
+ if limits.get("max_side"):
446
+ out.append(f"side≤{limits['max_side']}")
447
+ if limits.get("max_ratio"):
448
+ out.append(f"aspect≤{limits['max_ratio']}")
449
+ if limits.get("max_input_images"):
450
+ out.append(f"up to {limits['max_input_images']} input image(s)")
451
+ if limits.get("quality_options"):
452
+ quality = f"quality: {'|'.join(map(str, limits['quality_options']))}"
453
+ default_quality = (defaults or {}).get("quality")
454
+ if default_quality:
455
+ quality += f" (default {default_quality})"
456
+ out.append(quality)
457
+
458
+ # --- TTS
459
+ for item in (
460
+ _range(limits, "min_text", "max_text", "text", " chars"),
461
+ _range(limits, "min_speed", "max_speed", "speed"),
462
+ ):
463
+ if item:
464
+ out.append(item)
465
+ # The card calls this `available_ratios`; on every TTS model it holds sample rates.
466
+ if limits.get("available_ratios"):
467
+ out.append(f"sample_rate: {'|'.join(map(str, limits['available_ratios']))}")
468
+
469
+ # --- transcription
470
+ if limits.get("timestamp_levels"):
471
+ out.append(f"ts_level: {'|'.join(map(str, limits['timestamp_levels']))}")
472
+
473
+ # --- img2video reference mode (MiniMax-H3 and alike)
474
+ refs = _format_reference_limits(limits)
475
+ if refs:
476
+ out.append(refs)
477
+
478
+ # --- video description
479
+ if limits.get("available_presets"):
480
+ out.append(f"presets: {'|'.join(map(str, limits['available_presets']))}")
481
+
482
+ # --- video / upscale / music / embedding / description
483
+ if limits.get("max_video_duration_seconds"):
484
+ out.append(f"video≤{limits['max_video_duration_seconds']}s")
485
+ for item in (
486
+ _range(limits, "min_scale", "max_scale", "scale", "x"),
487
+ _range(limits, "min_caption", "max_caption", "caption", " chars"),
488
+ ):
489
+ if item:
490
+ out.append(item)
491
+ if limits.get("max_input_tokens"):
492
+ out.append(f"≤{limits['max_input_tokens']} tokens/input")
493
+ return out
494
+
495
+
496
+ def _format_reference_limits(limits: Dict[str, Any]) -> Optional[str]:
497
+ """'refs: ≤3 images, ≤1 video (2-5s), ≤3 audio (1-10s), ≤3 files total', or None.
498
+
499
+ The API publishes the effective counts only on a model that supports at least
500
+ one reference type, and an unsupported type as 0, so a positive count is the
501
+ signal. Without this line an agent cannot tell which video model takes
502
+ ref_images at all, let alone how many.
503
+ """
504
+ parts: List[str] = []
505
+ for key, noun, lo_key, hi_key in (
506
+ ("max_ref_images", "images", None, None),
507
+ ("max_ref_videos", "video", "min_ref_video_duration", "max_ref_video_duration"),
508
+ ("max_ref_audios", "audio", "min_ref_audio_duration", "max_ref_audio_duration"),
509
+ ):
510
+ count = limits.get(key)
511
+ if not isinstance(count, (int, float)) or count <= 0:
512
+ continue
513
+ item = f"≤{count} {noun}"
514
+ lo, hi = (limits.get(lo_key), limits.get(cast(str, hi_key))) if lo_key else (None, None)
515
+ if lo is not None and hi is not None:
516
+ item += f" ({lo}-{hi}s)"
517
+ parts.append(item)
518
+ if not parts:
519
+ return None
520
+ total = limits.get("max_ref_files")
521
+ if isinstance(total, (int, float)) and total > 0:
522
+ parts.append(f"≤{total} files total")
523
+ return "refs: " + ", ".join(parts)
524
+
525
+
526
+ # Types whose card size bounds describe the uploaded input, not an output.
527
+ _INPUT_SIZED_TYPES = {"img-upscale", "img-rmbg", "img2txt", "vid-upscale", "vid-rmbg"}
528
+ # Types whose request carries a negative_prompt.
529
+ _GENERATION_TYPES = {"txt2img", "img2img", "txt2video", "img2video", "audio2video"}
530
+
531
+
532
+ def _flag(features: Dict[str, Any], name: str) -> Optional[bool]:
533
+ """A feature flag as a bool, or None when the card does not set it.
534
+
535
+ Cards carry booleans on newer models and "0"/"1" strings on older ones.
536
+ """
537
+ value = features.get(name)
538
+ if value is None:
539
+ return None
540
+ return str(value).lower() in ("1", "true")
541
+
542
+
543
+ def _format_transcription(features: Dict[str, Any], limits: Dict[str, Any]) -> List[str]:
544
+ """What a speech-to-text model can do, beyond its ts_level list.
545
+
546
+ WhisperLargeV3 and WhisperLargeV3Ct2 differ in exactly these: only Ct2
547
+ diarizes, and only Ct2 returns a JSON document (text + segments) instead
548
+ of plain text. Diarizing on WhisperLargeV3 is a 422.
549
+ """
550
+ out: List[str] = []
551
+ if _flag(features, "supports_timestamps") is False:
552
+ out.append("no timestamps")
553
+ if _flag(features, "supports_diarization"):
554
+ out.append("diarize")
555
+ fmt = limits.get("output_format")
556
+ if fmt == "json":
557
+ out.append("output=json (text + segments)")
558
+ elif fmt:
559
+ out.append(f"output={fmt}")
560
+ langs = limits.get("languages")
561
+ if isinstance(langs, list) and langs:
562
+ out.append(f"lang: {'|'.join(map(str, langs))}")
563
+ return out
564
+
565
+
566
+ # Which feature flag names which TTS mode. Each model advertises exactly one.
567
+ _TTS_MODE_FEATURES = (
568
+ ("supports_voice_clone", "voice_clone"),
569
+ ("supports_voice_design", "voice_design"),
570
+ ("supports_custom_voice", "custom_voice"),
571
+ )
572
+
573
+ _VOICES_SHOWN_PER_LANGUAGE = 25
574
+
575
+
576
+ def _format_tts_languages(
577
+ model: ModelInfo, features: Dict[str, Any], limits: Dict[str, Any]
578
+ ) -> Optional[str]:
579
+ """One indented line listing a TTS model's languages and voice slugs.
580
+
581
+ The `lang` and `voice` values are per-model and not guessable — Kokoro
582
+ takes 'en-us' + 'af_alloy', the Qwen3 models take 'English' — so without
583
+ this an LLM has no way to form a valid request. Kept compact: voices are
584
+ capped per language, and a model whose every language offers the same
585
+ single voice (Chatterbox: 23 languages, all 'Default') is collapsed.
586
+ """
587
+ if not model.languages:
588
+ return None
589
+
590
+ langs = model.languages
591
+ voice_sets = [tuple(v.slug for v in lang.voices) for lang in langs]
592
+
593
+ # Voice-cloning / voice-design: languages only, the voice comes from elsewhere
594
+ if all(not vs for vs in voice_sets):
595
+ is_clone = str(features.get("supports_voice_clone")).lower() in ("1", "true")
596
+ src = "ref_audio" if is_clone else "instruct"
597
+ # The API rejects a reference clip outside this window; stating it here
598
+ # saves a failed call (a 4.8s sample against a 5s minimum is a real case).
599
+ lo, hi = limits.get("min_ref_audio_duration"), limits.get("max_ref_audio_duration")
600
+ bound = f", {lo}-{hi}s" if is_clone and lo is not None and hi is not None else ""
601
+ return f" langs: {', '.join(lang.slug for lang in langs)} (voice from {src}{bound})"
602
+
603
+ # Same voice list in every language that has one: list it once. Covers
604
+ # Chatterbox (23 languages, all 'default') and the Qwen3 CustomVoice model
605
+ # (the same named voices in every language).
606
+ distinct = {vs for vs in voice_sets if vs}
607
+ # One list, or one list that every other merely lacks a few of (the Qwen3
608
+ # CustomVoice model has no 'Ryan' in Chinese): print it once, plus the gaps.
609
+ widest = max(distinct, key=len) if distinct else ()
610
+ if distinct and all(set(vs) <= set(widest) for vs in distinct):
611
+ voices = list(widest)
612
+ shown = ", ".join(voices[:_VOICES_SHOWN_PER_LANGUAGE])
613
+ more = len(voices) - _VOICES_SHOWN_PER_LANGUAGE
614
+ suffix = f", +{more}" if more > 0 else ""
615
+ notes = []
616
+ voiceless = [lang.slug for lang, vs in zip(langs, voice_sets) if not vs]
617
+ if voiceless:
618
+ notes.append(f"no voice listed for: {', '.join(voiceless)}")
619
+ for lang, vs in zip(langs, voice_sets):
620
+ missing = [v for v in voices if vs and v not in vs]
621
+ if missing:
622
+ notes.append(f"{lang.slug} lacks {', '.join(missing)}")
623
+ note = f" ({'; '.join(notes)})" if notes else ""
624
+ same = "same in every language" if len(distinct) == 1 else "shared"
625
+ return (
626
+ f" langs: {', '.join(lang.slug for lang in langs)} ({len(langs)}); "
627
+ f"voices ({len(voices)}, {same}): {shown}{suffix}{note}"
628
+ )
629
+
630
+ chunks = []
631
+ for lang in langs:
632
+ slugs = [v.slug for v in lang.voices]
633
+ if not slugs:
634
+ chunks.append(lang.slug)
635
+ continue
636
+ shown = ", ".join(slugs[:_VOICES_SHOWN_PER_LANGUAGE])
637
+ more = len(slugs) - _VOICES_SHOWN_PER_LANGUAGE
638
+ suffix = f", +{more}" if more > 0 else ""
639
+ chunks.append(f"{lang.slug} [{len(slugs)}: {shown}{suffix}]")
640
+ return " langs: " + "; ".join(chunks)
641
+
642
+
643
+ def _build_enrichment_block(models: List[ModelInfo]) -> str:
644
+ """Build the enrichment text block for a list of models.
645
+
646
+ Standard models are listed first, in catalogue order; test models go last
647
+ and are marked. The catalogue itself interleaves them, and an agent that
648
+ finds no anchor in the description takes the first familiar name — which
649
+ was a partner test model on text_to_image and image_to_image.
650
+ """
651
+ if not models:
652
+ return ""
653
+ ordered = sorted(models, key=is_test_model) # stable: catalogue order within each group
654
+ lines = ["---", "Available models:"]
655
+ for model in ordered:
656
+ lines.append(_format_model_info(model))
657
+ if any(is_test_model(m) for m in ordered):
658
+ lines.append(TEST_MODEL_NOTE)
659
+ return "\n".join(lines)
660
+
661
+
662
+ # ---------------------------------------------------------------------------
663
+ # Model fetching & indexing
664
+ # ---------------------------------------------------------------------------
665
+
666
+
667
+ async def _fetch_and_index_models(cache: Optional[_ModelCache] = None) -> None:
668
+ """Fetch the caller's models from deAPI and index them by tool name."""
669
+ from .deapi_client import get_client
670
+
671
+ if cache is None:
672
+ cache = _caches.current()
673
+
674
+ async with get_client() as client:
675
+ response = await client.get_models()
676
+
677
+ tool_models: Dict[str, List[ModelInfo]] = {}
678
+ for model in response.data:
679
+ inference_types = model.inference_types
680
+ if isinstance(inference_types, list):
681
+ for itype in inference_types:
682
+ tool_names = INFERENCE_TYPE_TO_TOOLS.get(itype, [])
683
+ for tool_name in tool_names:
684
+ listed = tool_models.setdefault(tool_name, [])
685
+ # Two types can route to one tool (video2desc, video_file2desc);
686
+ # list the model once.
687
+ if model not in listed:
688
+ listed.append(model)
689
+
690
+ enrichments: Dict[str, str] = {}
691
+ for tool_name, models in tool_models.items():
692
+ block = _build_enrichment_block(models)
693
+ if block:
694
+ enrichments[tool_name] = block
695
+
696
+ cache.tool_models = tool_models
697
+ cache.models_by_slug = {m.slug: m for m in response.data}
698
+ cache.enrichments = enrichments
699
+ cache.last_fetched = time.monotonic()
700
+ _caches.confirm(cache)
701
+
702
+ logger.info(
703
+ "Model cache refreshed: %d models indexed across %d tools",
704
+ sum(len(m) for m in tool_models.values()),
705
+ len(enrichments),
706
+ )
707
+
708
+
709
+ # ---------------------------------------------------------------------------
710
+ # Middleware
711
+ # ---------------------------------------------------------------------------
712
+
713
+
714
+ class ModelEnrichmentMiddleware(Middleware):
715
+ """Middleware that enriches tool descriptions with available model info.
716
+
717
+ Intercepts tools/list responses and appends model specs (slugs, parameter
718
+ limits, guidance requirements) to each tool's description. Uses a TTL-based
719
+ cache to avoid fetching models on every request.
720
+ """
721
+
722
+ def __init__(self, ttl: float = DEFAULT_CACHE_TTL):
723
+ super().__init__()
724
+ self._ttl = ttl
725
+
726
+ async def _ensure_cache_fresh(self) -> None:
727
+ """Refresh model cache if stale."""
728
+ await ensure_model_cache(self._ttl)
729
+
730
+ async def on_list_tools(
731
+ self,
732
+ context: MiddlewareContext[mt.ListToolsRequest],
733
+ call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]],
734
+ ) -> Sequence[Tool]:
735
+ """Enrich tool descriptions with available model information."""
736
+ tools = await call_next(context)
737
+
738
+ await self._ensure_cache_fresh()
739
+
740
+ enrichments = _caches.current().enrichments
741
+ if not enrichments:
742
+ return tools
743
+
744
+ enriched: List[Tool] = []
745
+ for tool in tools:
746
+ enrichment = enrichments.get(tool.name)
747
+ if enrichment:
748
+ try:
749
+ new_desc = (tool.description or "") + "\n\n" + enrichment
750
+ enriched.append(tool.model_copy(update={"description": new_desc}))
751
+ except Exception:
752
+ logger.warning("Failed to enrich tool %s", tool.name, exc_info=True)
753
+ enriched.append(tool)
754
+ else:
755
+ enriched.append(tool)
756
+ return enriched