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.
- deapi_mcp/__init__.py +24 -0
- deapi_mcp/auth.py +33 -0
- deapi_mcp/auth_code_store.py +226 -0
- deapi_mcp/config.py +297 -0
- deapi_mcp/consent.py +549 -0
- deapi_mcp/deapi_client.py +466 -0
- deapi_mcp/fastmcp_auth.py +227 -0
- deapi_mcp/key_verifier.py +225 -0
- deapi_mcp/landing.py +431 -0
- deapi_mcp/middleware.py +756 -0
- deapi_mcp/oauth_clients.py +443 -0
- deapi_mcp/oauth_endpoints.py +973 -0
- deapi_mcp/observability.py +199 -0
- deapi_mcp/polling_manager.py +319 -0
- deapi_mcp/py.typed +0 -0
- deapi_mcp/schemas.py +397 -0
- deapi_mcp/server_remote.py +416 -0
- deapi_mcp/tools/__init__.py +0 -0
- deapi_mcp/tools/_price_helpers.py +167 -0
- deapi_mcp/tools/_responses.py +157 -0
- deapi_mcp/tools/audio.py +1195 -0
- deapi_mcp/tools/embedding.py +102 -0
- deapi_mcp/tools/image.py +884 -0
- deapi_mcp/tools/prompt.py +155 -0
- deapi_mcp/tools/utility.py +230 -0
- deapi_mcp/tools/video.py +1117 -0
- deapi_mcp/utils.py +666 -0
- deapi_mcp/webhooks.py +349 -0
- deapi_mcp-0.7.0.dist-info/METADATA +642 -0
- deapi_mcp-0.7.0.dist-info/RECORD +33 -0
- deapi_mcp-0.7.0.dist-info/WHEEL +4 -0
- deapi_mcp-0.7.0.dist-info/entry_points.txt +2 -0
- deapi_mcp-0.7.0.dist-info/licenses/LICENSE +21 -0
deapi_mcp/middleware.py
ADDED
|
@@ -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
|