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,416 @@
1
+ """Remote FastMCP server for deAPI with streamable-http transport.
2
+
3
+ This is the server seam of the ``deapi-mcp`` core. No metrics exposition lives
4
+ in the core: ``create_app`` takes one only as an optional injected overlay, and
5
+ the stock ``build_app`` passes nothing.
6
+ """
7
+
8
+ import asyncio
9
+ import logging
10
+ import os
11
+ from contextlib import asynccontextmanager
12
+ from typing import Any, AsyncIterator
13
+
14
+ import uvicorn
15
+ from fastmcp import FastMCP
16
+ from starlette.applications import Starlette
17
+
18
+ # Import FastMCP-compatible auth provider
19
+ from . import __version__, auth_code_store
20
+ from .fastmcp_auth import (
21
+ ApiKeyHeaderMiddleware,
22
+ DeapiAuthProvider,
23
+ InvalidTokenDescriptionMiddleware,
24
+ )
25
+
26
+ # Import tool functions
27
+ from .tools.audio import (
28
+ audio_transcription,
29
+ audio_transcription_price,
30
+ audio_url_transcription,
31
+ audio_url_transcription_price,
32
+ text_to_audio,
33
+ text_to_audio_price,
34
+ text_to_music,
35
+ text_to_music_price,
36
+ video_file_transcription,
37
+ video_file_transcription_price,
38
+ video_url_transcription,
39
+ video_url_transcription_price,
40
+ )
41
+ from .tools.embedding import text_to_embedding, text_to_embedding_price
42
+ from .tools.image import (
43
+ image_remove_background,
44
+ image_remove_background_price,
45
+ image_to_image,
46
+ image_to_image_price,
47
+ image_to_text,
48
+ image_to_text_price,
49
+ image_upscale,
50
+ image_upscale_price,
51
+ text_to_image,
52
+ text_to_image_price,
53
+ )
54
+ from .tools.prompt import prompt_booster, prompt_booster_price
55
+ from .tools.utility import check_job_status, get_available_models, get_balance
56
+ from .tools.video import (
57
+ audio_to_video,
58
+ audio_to_video_price,
59
+ image_to_video,
60
+ image_to_video_price,
61
+ text_to_video,
62
+ text_to_video_price,
63
+ video_description,
64
+ video_description_price,
65
+ video_upscale,
66
+ video_upscale_price,
67
+ )
68
+ from .webhooks import JobRegistry, get_job_registry, set_job_registry
69
+
70
+ # Initialize FastMCP server WITHOUT auth (will be added later)
71
+ # Auth requires knowing the base URL which we don't have until runtime
72
+ mcp = FastMCP(name="deAPI AI API", version=__version__, auth=None)
73
+
74
+
75
+ def register_core_tools(server: FastMCP) -> None:
76
+ """Register every deAPI core tool on the given FastMCP instance.
77
+
78
+ Exposed so any consumer -- such as a thin deployment wrapper -- can assemble
79
+ a server from the same tool set. The module registers them on its own ``mcp``
80
+ just below, which preserves the current import-time behaviour.
81
+ """
82
+ # Audio & video transcription
83
+ server.tool()(audio_transcription)
84
+ server.tool()(text_to_audio)
85
+ server.tool()(text_to_music)
86
+ server.tool()(audio_transcription_price)
87
+ server.tool()(text_to_audio_price)
88
+ server.tool()(text_to_music_price)
89
+ server.tool()(audio_url_transcription)
90
+ server.tool()(audio_url_transcription_price)
91
+ server.tool()(video_file_transcription)
92
+ server.tool()(video_url_transcription)
93
+ server.tool()(video_file_transcription_price)
94
+ server.tool()(video_url_transcription_price)
95
+ # Image
96
+ server.tool()(text_to_image)
97
+ server.tool()(image_to_image)
98
+ server.tool()(image_to_text)
99
+ server.tool()(image_remove_background)
100
+ server.tool()(image_upscale)
101
+ server.tool()(text_to_image_price)
102
+ server.tool()(image_to_image_price)
103
+ server.tool()(image_to_text_price)
104
+ server.tool()(image_remove_background_price)
105
+ server.tool()(image_upscale_price)
106
+ # Video
107
+ server.tool()(text_to_video)
108
+ server.tool()(image_to_video)
109
+ server.tool()(audio_to_video)
110
+ server.tool()(image_to_video_price)
111
+ server.tool()(text_to_video_price)
112
+ server.tool()(audio_to_video_price)
113
+ server.tool()(video_description)
114
+ server.tool()(video_description_price)
115
+ server.tool()(video_upscale)
116
+ server.tool()(video_upscale_price)
117
+ # Embedding
118
+ server.tool()(text_to_embedding)
119
+ server.tool()(text_to_embedding_price)
120
+ # Prompt booster
121
+ server.tool()(prompt_booster)
122
+ server.tool()(prompt_booster_price)
123
+ # Utility
124
+ server.tool()(get_balance)
125
+ server.tool()(get_available_models)
126
+ server.tool()(check_job_status)
127
+
128
+
129
+ # Register the core tools on this module's server instance (import-time behaviour).
130
+ register_core_tools(mcp)
131
+
132
+
133
+ # ============================================================================
134
+ # SERVER ENTRY POINT FOR REMOTE HOSTING
135
+ # ============================================================================
136
+
137
+
138
+ def env_int(name: str, default: int) -> int:
139
+ """Read an integer environment variable; unset or blank means the default.
140
+
141
+ A secrets env may carry `NAME=` with no value, which reaches the process as an empty
142
+ string -- a bare int() on it would crash-loop the rollout.
143
+ """
144
+ raw = os.getenv(name, "").strip()
145
+ if not raw:
146
+ return default
147
+ try:
148
+ return int(raw)
149
+ except ValueError:
150
+ raise ValueError(f"{name} must be an integer, got {raw!r}") from None
151
+
152
+
153
+ LOOPBACK_HOSTS = {"127.0.0.1", "localhost", "::1"}
154
+
155
+
156
+ def require_jwt_secret_key(host: str) -> None:
157
+ """Exit non-zero when replicas could each sign with a different ephemeral JWT key.
158
+
159
+ Without DEAPI_JWT_SECRET_KEY every process generates its own key, so a token issued by
160
+ one pod is rejected by another. That is fatal for a multi-replica deploy (bound beyond
161
+ loopback, or Redis configured); a local dev run keeps the warning and the ephemeral key.
162
+ """
163
+ from .config import settings as deapi_settings
164
+
165
+ if os.getenv("DEAPI_JWT_SECRET_KEY"):
166
+ return
167
+ if host in LOOPBACK_HOSTS and not deapi_settings.redis_host:
168
+ return
169
+ logging.getLogger(__name__).error(
170
+ "DEAPI_JWT_SECRET_KEY is not set (host=%s, redis=%s). Each replica would sign tokens "
171
+ "with its own ephemeral key and reject the others'. Set the same key on every replica.",
172
+ host,
173
+ "configured" if deapi_settings.redis_host else "unset",
174
+ )
175
+ raise SystemExit(1)
176
+
177
+
178
+ def _run_job_registry_with_lifespan(app: Starlette) -> None:
179
+ """Start the job registry before the app serves and stop it after the app's own shutdown."""
180
+ inner = app.router.lifespan_context
181
+
182
+ @asynccontextmanager
183
+ async def lifespan(app: Starlette) -> AsyncIterator[Any]:
184
+ job_registry = get_job_registry()
185
+ await job_registry.start()
186
+ try:
187
+ async with inner(app) as state:
188
+ yield state
189
+ finally:
190
+ await job_registry.stop()
191
+
192
+ app.router.lifespan_context = lifespan
193
+
194
+
195
+ def create_app(
196
+ server: "FastMCP | None" = None,
197
+ *,
198
+ metrics: Any = None,
199
+ job_registry: JobRegistry | None = None,
200
+ ) -> Starlette:
201
+ """Build the Starlette app from the core server, plus optional overlays.
202
+
203
+ ``server`` defaults to this module's ``mcp``. ``metrics`` is an optional overlay
204
+ that instruments tools and OAuth, adds the missing-token counter and mounts
205
+ /metrics; the core carries no metrics dependency of its own, and the stock
206
+ server passes nothing. ``job_registry`` replaces the in-process registry that
207
+ completion webhooks wake waiting tools through; pass a shared one when several
208
+ replicas serve the same receiver URL. Its ``start``/``stop`` run with the app's
209
+ lifespan while webhooks are on. Mutates ``server`` (auth, middleware) and the
210
+ process-wide registry, so call it once per process per server.
211
+ """
212
+ server = server if server is not None else mcp
213
+ logger = logging.getLogger(__name__)
214
+
215
+ # Get configuration from environment
216
+ host = os.getenv("MCP_HOST", "0.0.0.0")
217
+ port = env_int("MCP_PORT", 8000)
218
+
219
+ require_jwt_secret_key(host)
220
+
221
+ logger.info("Starting deAPI MCP Server with HTTP transport")
222
+ logger.info(f"Server will run on {host}:{port}")
223
+
224
+ # Log which OAuth code store backs this process at startup (no I/O)
225
+ auth_code_store.get_auth_code_store()
226
+
227
+ # Create FastMCP auth provider
228
+ #
229
+ # FastMCP builds `resource_metadata` in every 401 challenge from this URL. The bind
230
+ # address (0.0.0.0:8000) means nothing to a client behind the gateway, so the public
231
+ # URL wins whenever it is set -- the same one oauth_endpoints.py advertises in discovery.
232
+ base_url = os.getenv("PUBLIC_BASE_URL") or f"http://{host}:{port}"
233
+ auth_provider = DeapiAuthProvider(base_url=base_url)
234
+
235
+ # Set auth on the server instance BEFORE calling http_app
236
+ server.auth = auth_provider
237
+
238
+ # Conditionally enable model description enrichment middleware
239
+ from .config import settings as deapi_settings
240
+
241
+ if deapi_settings.enrich_tool_descriptions:
242
+ from .middleware import ModelEnrichmentMiddleware
243
+
244
+ server.add_middleware(ModelEnrichmentMiddleware(ttl=deapi_settings.model_cache_ttl))
245
+ logger.info(
246
+ "Model description enrichment enabled (TTL: %ss)",
247
+ deapi_settings.model_cache_ttl,
248
+ )
249
+
250
+ if metrics is not None:
251
+ metrics.install(server)
252
+
253
+ # Get the Starlette app from FastMCP with streamable-http transport
254
+ # stateless_http: no Mcp-Session-Id, so any replica can serve any request
255
+ starlette_app = server.http_app(transport="streamable-http", stateless_http=True)
256
+
257
+ # Every tool call answers as an sse-starlette stream, and sse-starlette ends all of them
258
+ # on SIGTERM by default, so uvicorn's graceful shutdown would find nothing to wait for and
259
+ # a rollout would cut every in-flight call. Stateless mode has no standalone GET stream
260
+ # (405), so each stream ends with its call; timeout_graceful_shutdown caps the wait.
261
+ from sse_starlette.sse import AppStatus
262
+
263
+ # sse-starlette ships py.typed but leaves this staticmethod unannotated.
264
+ AppStatus.disable_automatic_graceful_drain() # type: ignore[no-untyped-call]
265
+
266
+ # Add health check endpoint for Docker/monitoring
267
+ from starlette.requests import Request
268
+ from starlette.responses import JSONResponse, Response
269
+ from starlette.routing import Route
270
+
271
+ from .oauth_endpoints import (
272
+ authorize_endpoint,
273
+ oauth_authorization_server_metadata,
274
+ token_endpoint,
275
+ )
276
+ from .webhooks import WEBHOOK_ROUTE, internal_webhooks_enabled, webhook_receiver
277
+
278
+ async def health_check(request: Request) -> JSONResponse:
279
+ """Health check endpoint for Docker and monitoring."""
280
+ return JSONResponse({"status": "healthy", "service": "deapi-mcp"})
281
+
282
+ # Add the health route to the app
283
+ starlette_app.routes.append(Route("/health", health_check))
284
+
285
+ # Setup instructions at "/". The registry is fixed once the app is built, so the
286
+ # tool list is read on the first visit and kept.
287
+ from .landing import landing_response, public_base_url
288
+
289
+ landing_tools: list[Any] = []
290
+
291
+ async def landing_page(request: Request) -> Response:
292
+ if not landing_tools:
293
+ landing_tools.extend(await server.list_tools(run_middleware=False))
294
+ return landing_response(public_base_url(request), landing_tools)
295
+
296
+ starlette_app.routes.append(Route("/", landing_page, methods=["GET"]))
297
+
298
+ if metrics is not None:
299
+ metrics.wrap_app(starlette_app, server)
300
+
301
+ # Add OAuth endpoints for MCP clients (Claude Desktop, etc.)
302
+ # These enable OAuth Authorization Code flow for authentication
303
+ starlette_app.routes.append(
304
+ Route("/.well-known/oauth-authorization-server", oauth_authorization_server_metadata)
305
+ )
306
+ # Claude Desktop also tries path-based discovery on auth server
307
+ starlette_app.routes.append(
308
+ Route("/.well-known/oauth-authorization-server/mcp", oauth_authorization_server_metadata)
309
+ )
310
+ # OAuth Authorization Code flow endpoints
311
+ authorize_handler = (
312
+ metrics.instrument(authorize_endpoint, "authorize")
313
+ if metrics is not None
314
+ else authorize_endpoint
315
+ )
316
+ token_handler = (
317
+ metrics.instrument(token_endpoint, metrics.token_step)
318
+ if metrics is not None
319
+ else token_endpoint
320
+ )
321
+ starlette_app.routes.append(Route("/authorize", authorize_handler, methods=["GET", "POST"]))
322
+ # Dynamic client registration (RFC 7591) for public clients; a 404 when switched off
323
+ if (
324
+ deapi_settings.oauth_public_clients
325
+ and host not in LOOPBACK_HOSTS
326
+ and not deapi_settings.client_ip_header
327
+ ):
328
+ logger.warning(
329
+ "DEAPI_CLIENT_IP_HEADER is not set: the sign-in screen counts wrong keys by the "
330
+ "connection address, which behind a proxy is the proxy's (one shared limit) or "
331
+ "whatever X-Forwarded-For says. Set it to a header your edge sets, e.g. "
332
+ "CF-Connecting-IP behind Cloudflare."
333
+ )
334
+ if deapi_settings.oauth_public_clients:
335
+ from .oauth_clients import register_endpoint
336
+
337
+ starlette_app.routes.append(Route("/register", register_endpoint, methods=["POST"]))
338
+ starlette_app.routes.append(Route("/token", token_handler, methods=["POST"]))
339
+
340
+ if job_registry is not None:
341
+ set_job_registry(job_registry)
342
+
343
+ # Completion webhooks: only mounted when configured, so a server
344
+ # that isn't using them exposes no receiver at all.
345
+ if internal_webhooks_enabled():
346
+ starlette_app.routes.append(Route(WEBHOOK_ROUTE, webhook_receiver, methods=["POST"]))
347
+ _run_job_registry_with_lifespan(starlette_app)
348
+ logger.info(
349
+ f"Completion webhooks: ON -- jobs will call back {deapi_settings.webhook_receiver_url} "
350
+ f"(safety-net poll every {deapi_settings.webhook_fallback_poll_interval:.0f}s)"
351
+ )
352
+ else:
353
+ logger.info("Completion webhooks: off -- jobs are polled to completion")
354
+
355
+ # Added last, so it is the outermost layer: authentication and any overlay
356
+ # middleware (a missing-token counter) see the key as a Bearer token.
357
+ starlette_app.add_middleware(InvalidTokenDescriptionMiddleware)
358
+ starlette_app.add_middleware(ApiKeyHeaderMiddleware)
359
+
360
+ logger.info(f"MCP endpoint: http://{host}:{port}/mcp")
361
+ logger.info(f"OAuth server: http://{host}:{port}/.well-known/oauth-authorization-server")
362
+ logger.info(
363
+ "Authentication: OAuth 2.0 (Authorization Code + PKCE), Bearer tokens and X-API-Key"
364
+ )
365
+
366
+ return starlette_app
367
+
368
+
369
+ def build_app() -> Starlette:
370
+ """The stock server app: the core with no overlay.
371
+
372
+ A deployment with its own metrics builds its app with
373
+ ``create_app(mcp, metrics=<overlay>)`` instead.
374
+ """
375
+ return create_app(mcp)
376
+
377
+
378
+ def main() -> None:
379
+ """Entry point for the MCP server (used by console_scripts and __main__)."""
380
+ # Configure logging
381
+ logging.basicConfig(
382
+ level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
383
+ )
384
+
385
+ host = os.getenv("MCP_HOST", "0.0.0.0")
386
+ port = env_int("MCP_PORT", 8000)
387
+ starlette_app = build_app()
388
+
389
+ # Configure and run uvicorn
390
+ # proxy_headers=True: Trust X-Forwarded-Proto, X-Forwarded-Host from ingress/proxy
391
+ # forwarded_allow_ips="*": Accept forwarded headers from any IP.
392
+ # IMPORTANT: Only safe when the server is behind a reverse proxy (nginx, ingress, etc.)
393
+ # that is the sole entry point. If the server is directly exposed to the internet,
394
+ # an attacker can forge X-Forwarded-For headers to spoof their IP.
395
+ # For direct exposure, set FORWARDED_ALLOW_IPS to your proxy's IP(s) instead.
396
+ forwarded_ips = os.getenv("FORWARDED_ALLOW_IPS", "*")
397
+ config = uvicorn.Config(
398
+ starlette_app,
399
+ host=host,
400
+ port=port,
401
+ log_level="info",
402
+ proxy_headers=True,
403
+ forwarded_allow_ips=forwarded_ips,
404
+ # Keep uvicorn's graceful drain inside the platform's pod termination grace period
405
+ # so long polling calls can finish before the process is killed. Tune via the env var
406
+ # to match your deployment's grace/preStop settings.
407
+ timeout_graceful_shutdown=env_int("MCP_GRACEFUL_SHUTDOWN_SECONDS", 930),
408
+ )
409
+ server = uvicorn.Server(config)
410
+
411
+ # Run the server
412
+ asyncio.run(server.serve())
413
+
414
+
415
+ if __name__ == "__main__":
416
+ main()
File without changes
@@ -0,0 +1,167 @@
1
+ """Helpers for resolving request parameters from the model cache.
2
+
3
+ Uses the global model cache (populated by ModelEnrichmentMiddleware, or on
4
+ demand via ``ensure_model_cache``) to resolve model defaults and features, so
5
+ neither the price tools nor the generation tools need hardcoded parameter
6
+ values. No single number suits every model: a ``steps`` of 20 is over the
7
+ limit on Flux1schnell (max 10) and Flux_2_Klein (fixed at 4), and the video
8
+ models each fix ``fps`` at a different value.
9
+ """
10
+
11
+ from typing import Any, Dict, Optional, Tuple
12
+
13
+ from ..middleware import get_cached_model
14
+ from ..schemas import ModelInfo
15
+
16
+
17
+ def _get_model_info_section(model: Optional[ModelInfo], section: str) -> Dict[str, Any]:
18
+ """Safely extract a section (defaults, features, limits) from model info."""
19
+ if model is None or not isinstance(model.info, dict):
20
+ return {}
21
+ value = model.info.get(section)
22
+ return value if isinstance(value, dict) else {}
23
+
24
+
25
+ def get_model_defaults(model_slug: str) -> Dict[str, Any]:
26
+ """Get defaults dict from cached model info."""
27
+ return _get_model_info_section(get_cached_model(model_slug), "defaults")
28
+
29
+
30
+ def get_model_features(model_slug: str) -> Dict[str, Any]:
31
+ """Get features dict from cached model info."""
32
+ return _get_model_info_section(get_cached_model(model_slug), "features")
33
+
34
+
35
+ def get_model_limits(model_slug: str) -> Dict[str, Any]:
36
+ """Get limits dict from cached model info."""
37
+ return _get_model_info_section(get_cached_model(model_slug), "limits")
38
+
39
+
40
+ def feature_enabled(model_slug: str, feature: str) -> bool:
41
+ """True only when the card turns the flag on (true/1).
42
+
43
+ Unknown or absent counts as off: a knob is sent only to a model known
44
+ to take it, never guessed at a model whose card is not loaded.
45
+ """
46
+ value = get_model_features(model_slug).get(feature)
47
+ return value is not None and str(value).lower() in ("1", "true")
48
+
49
+
50
+ def resolve_upscale_factor(
51
+ model_slug: str, scale: Optional[int]
52
+ ) -> Tuple[Optional[int], Optional[str]]:
53
+ """The `scale` to send for a video upscale, or an error to return instead.
54
+
55
+ A model that publishes `min_scale`/`max_scale` requires the field and one
56
+ that publishes neither rejects it (VideoUpscaleRequest). Unset on a ranged
57
+ model, the smallest factor is used. With no card at all the caller's value
58
+ is passed through for the API to judge.
59
+ """
60
+ card = get_cached_model(model_slug)
61
+ if card is None:
62
+ return scale, None
63
+ limits = get_model_limits(model_slug)
64
+ lo, hi = limits.get("min_scale"), limits.get("max_scale")
65
+ if lo is None and hi is None:
66
+ if scale is not None:
67
+ return None, (
68
+ f"{model_slug} has a fixed upscale factor and does not take 'scale'; leave it unset."
69
+ )
70
+ return None, None
71
+ if scale is None:
72
+ scale = _to_number(lo if lo is not None else hi)
73
+ return scale, None
74
+
75
+
76
+ def resolve_from_card(model_slug: str, user_params: Dict[str, Any]) -> Dict[str, Any]:
77
+ """Fill each unset parameter from the model card's defaults.
78
+
79
+ A user value always wins. A key the caller left unset and the card does
80
+ not default is omitted, so the API — which knows whether that model needs
81
+ it — can say so, rather than this client inventing a number that might be
82
+ out of range. Unlike ``resolve_generation_params`` nothing is guessed:
83
+ this is for the payload that actually runs the job.
84
+ """
85
+ defaults = get_model_defaults(model_slug)
86
+ resolved: Dict[str, Any] = {}
87
+ for key, value in user_params.items():
88
+ if value is None:
89
+ value = _to_number(defaults.get(key))
90
+ if value is not None:
91
+ resolved[key] = value
92
+ return resolved
93
+
94
+
95
+ def resolve_generation_params(
96
+ model_slug: str,
97
+ user_params: Dict[str, Any],
98
+ ) -> Dict[str, Any]:
99
+ """Build generation price params from model defaults + user overrides.
100
+
101
+ For each standard generation parameter (width, height, steps, guidance,
102
+ seed, fps, frames), uses the user-provided value if present, otherwise
103
+ falls back to the model's defaults from the cache.
104
+
105
+ Guidance is handled specially:
106
+ - If features.supports_guidance is "0" (or false), uses the model's
107
+ fixed default (usually 0).
108
+ - Otherwise uses user value or model default.
109
+
110
+ Seed defaults to -1 if not provided by user or model.
111
+
112
+ Returns a dict of resolved params (does NOT include 'model' or 'prompt' —
113
+ those are always added by the caller).
114
+ """
115
+ defaults = get_model_defaults(model_slug)
116
+ features = get_model_features(model_slug)
117
+
118
+ # Fallback defaults when cache is empty (e.g., first request before
119
+ # tools/list triggers the middleware cache population).
120
+ _fallbacks = {
121
+ "width": 512,
122
+ "height": 512,
123
+ "steps": 4,
124
+ }
125
+
126
+ params: Dict[str, Any] = {}
127
+
128
+ # Standard numeric params: use user value → model default → fallback
129
+ for key in ("width", "height", "steps", "fps", "frames"):
130
+ user_val = user_params.get(key)
131
+ if user_val is not None:
132
+ params[key] = user_val
133
+ elif key in defaults:
134
+ params[key] = _to_number(defaults[key])
135
+ elif key in _fallbacks:
136
+ params[key] = _fallbacks[key]
137
+
138
+ # Guidance: respect supports_guidance feature flag
139
+ supports_guidance = str(features.get("supports_guidance", "1"))
140
+ if supports_guidance in ("0", "false", "False"):
141
+ # Model doesn't support custom guidance — use fixed default
142
+ params["guidance"] = _to_number(defaults.get("guidance", 0))
143
+ else:
144
+ user_guidance = user_params.get("guidance")
145
+ if user_guidance is not None:
146
+ params["guidance"] = user_guidance
147
+ elif "guidance" in defaults:
148
+ params["guidance"] = _to_number(defaults["guidance"])
149
+ else:
150
+ params["guidance"] = 0 # safe fallback
151
+
152
+ # Seed: always include, default -1
153
+ params["seed"] = user_params.get("seed", -1)
154
+
155
+ return params
156
+
157
+
158
+ def _to_number(value: Any) -> Any:
159
+ """Convert string numbers from API defaults to int/float."""
160
+ if isinstance(value, str):
161
+ try:
162
+ if "." in value:
163
+ return float(value)
164
+ return int(value)
165
+ except (ValueError, TypeError):
166
+ return value
167
+ return value