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,199 @@
1
+ """Core observability sink: what happened during one tool call, classified once.
2
+
3
+ This is the lightweight, dependency-free half of observability that the core
4
+ genuinely needs: a per-call ``CallOutcome`` kept on a ContextVar, the ``note_*``
5
+ recorders the client/tools/polling call as they go, and the ``classify``
6
+ functions that turn an outcome into a single label.
7
+
8
+ It carries NO Prometheus/Redis dependency. A deployment that wants real metrics
9
+ injects its recorders through the sinks below; with nothing injected every sink
10
+ is a no-op, so the core records nothing and depends on nothing.
11
+ """
12
+
13
+ from contextlib import contextmanager
14
+ from contextvars import ContextVar, Token
15
+ from dataclasses import dataclass, fields
16
+ from typing import Any, Callable, Iterator, Optional
17
+
18
+ from fastmcp.exceptions import NotFoundError
19
+ from fastmcp.exceptions import ValidationError as FastMCPValidationError
20
+ from pydantic import ValidationError as PydanticValidationError
21
+
22
+ _NO_BALANCE_CODES = ("insufficient_balance", "key_limit_exceeded")
23
+ _REJECTED_REASONS = (
24
+ "SOURCE_PRIVATE",
25
+ "SOURCE_RESTRICTED",
26
+ "SOURCE_UNPROCESSABLE",
27
+ "INPUT_TOO_LARGE",
28
+ )
29
+
30
+
31
+ @dataclass
32
+ class CallOutcome:
33
+ api_status: Optional[int] = None
34
+ api_code: Optional[str] = None
35
+ network_error: bool = False
36
+ job_error_reason: Optional[str] = None
37
+ job_failed: bool = False
38
+ input_error: bool = False
39
+ # When each kind of note was last made, in the order of this call's notes (0 =
40
+ # never). A call can carry on past an early error, so the note that ended it is
41
+ # the most recent one, not the first kind in a fixed list.
42
+ api_seq: int = 0
43
+ network_seq: int = 0
44
+ job_seq: int = 0
45
+ input_seq: int = 0
46
+ last_seq: int = 0
47
+
48
+ def next_seq(self) -> int:
49
+ self.last_seq += 1
50
+ return self.last_seq
51
+
52
+
53
+ _current: ContextVar[Optional[CallOutcome]] = ContextVar("deapi_mcp_call_outcome", default=None)
54
+
55
+
56
+ def begin_call() -> tuple[CallOutcome, Token[Optional[CallOutcome]]]:
57
+ outcome = CallOutcome()
58
+ return outcome, _current.set(outcome)
59
+
60
+
61
+ def end_call(token: Token[Optional[CallOutcome]]) -> None:
62
+ _current.reset(token)
63
+
64
+
65
+ def note_api_error(status: Optional[int], body: Optional[dict[str, Any]]) -> None:
66
+ outcome = _current.get()
67
+ if outcome is None:
68
+ return
69
+ outcome.api_status = status
70
+ code = body.get("code") if isinstance(body, dict) else None
71
+ outcome.api_code = code if isinstance(code, str) else None
72
+ outcome.api_seq = outcome.next_seq()
73
+
74
+
75
+ def note_network_error() -> None:
76
+ outcome = _current.get()
77
+ if outcome is not None:
78
+ outcome.network_error = True
79
+ outcome.network_seq = outcome.next_seq()
80
+
81
+
82
+ def note_job_failure(error_reason: Optional[str]) -> None:
83
+ outcome = _current.get()
84
+ if outcome is not None:
85
+ outcome.job_failed = True
86
+ outcome.job_error_reason = error_reason
87
+ outcome.job_seq = outcome.next_seq()
88
+
89
+
90
+ def note_input_error() -> None:
91
+ outcome = _current.get()
92
+ if outcome is not None:
93
+ outcome.input_error = True
94
+ outcome.input_seq = outcome.next_seq()
95
+
96
+
97
+ def forget_api_error() -> None:
98
+ """Drop the API error noted so far: the caller recovered from it (e.g. by retrying)."""
99
+ outcome = _current.get()
100
+ if outcome is not None:
101
+ outcome.api_status = None
102
+ outcome.api_code = None
103
+ outcome.api_seq = 0
104
+
105
+
106
+ @contextmanager
107
+ def errors_tolerated() -> Iterator[None]:
108
+ """Discard whatever is noted inside the block.
109
+
110
+ For work whose failure the call deliberately survives, such as an optional
111
+ lookup: an error there did not end the call, so it must not label it. The
112
+ sequence keeps counting, so notes made after the block still order correctly.
113
+ """
114
+ outcome = _current.get()
115
+ saved = {f.name: getattr(outcome, f.name) for f in fields(CallOutcome)} if outcome else {}
116
+ try:
117
+ yield
118
+ finally:
119
+ if outcome is not None:
120
+ for name, value in saved.items():
121
+ if name != "last_seq":
122
+ setattr(outcome, name, value)
123
+
124
+
125
+ def classify_api(status: Optional[int], code: Optional[str]) -> str:
126
+ if status == 401:
127
+ return "bad_key"
128
+ if code in _NO_BALANCE_CODES:
129
+ return "no_balance"
130
+ if status == 429:
131
+ return "rate_limited"
132
+ if status is not None and 400 <= status < 500:
133
+ return "invalid_input"
134
+ return "deapi_error"
135
+
136
+
137
+ def classify_job(error_reason: Optional[str]) -> str:
138
+ return "job_rejected" if error_reason in _REJECTED_REASONS else "job_failed"
139
+
140
+
141
+ def classify(
142
+ result: Optional[dict[str, Any]], outcome: CallOutcome, exc: Optional[BaseException]
143
+ ) -> str:
144
+ if exc is not None:
145
+ if isinstance(exc, (FastMCPValidationError, PydanticValidationError, NotFoundError)):
146
+ return "invalid_input"
147
+ return "internal_error"
148
+ if isinstance(result, dict) and result.get("success") is True:
149
+ return "pending" if result.get("done") is False else "ok"
150
+ # Every kind of note made during the call, in precedence order. The most recent
151
+ # one decides, since it is what ended the call; an outcome built by hand (no
152
+ # sequence numbers) falls back to the precedence order alone.
153
+ candidates: list[tuple[int, str]] = []
154
+ if outcome.job_failed:
155
+ candidates.append((outcome.job_seq, classify_job(outcome.job_error_reason)))
156
+ if outcome.api_status is not None or outcome.api_code is not None:
157
+ candidates.append((outcome.api_seq, classify_api(outcome.api_status, outcome.api_code)))
158
+ if outcome.network_error:
159
+ candidates.append((outcome.network_seq, "deapi_error"))
160
+ if outcome.input_error:
161
+ candidates.append((outcome.input_seq, "invalid_input"))
162
+ if not candidates:
163
+ return "internal_error"
164
+ # max() keeps the first of equal keys, so ties go to the earlier (higher-precedence) kind.
165
+ return max(candidates, key=lambda candidate: candidate[0])[1]
166
+
167
+
168
+ # ---------------------------------------------------------------------------
169
+ # Injectable sinks (dependency inversion for the optional metrics overlay)
170
+ #
171
+ # The core calls these; by default they do nothing. A metrics overlay registers
172
+ # its real recorder once at startup (alongside the overlay it passes to
173
+ # ``create_app``), and from then on the core's calls reach it. This keeps the core
174
+ # free of any Prometheus/Redis dependency.
175
+ # ---------------------------------------------------------------------------
176
+
177
+ AuthRejectedSink = Callable[[str], None]
178
+
179
+
180
+ def _noop_auth_rejected(reason: str) -> None:
181
+ """Default auth-rejected sink: record nothing."""
182
+
183
+
184
+ _auth_rejected_sink: AuthRejectedSink = _noop_auth_rejected
185
+
186
+
187
+ def set_auth_rejected_sink(sink: Optional[AuthRejectedSink]) -> None:
188
+ """Install the auth-rejected recorder (or reset to the no-op with ``None``)."""
189
+ global _auth_rejected_sink
190
+ _auth_rejected_sink = sink if sink is not None else _noop_auth_rejected
191
+
192
+
193
+ def record_auth_rejected(reason: str) -> None:
194
+ """Report a rejected authentication to whatever sink is installed.
195
+
196
+ A no-op unless a metrics overlay installs a recorder via
197
+ :func:`set_auth_rejected_sink`.
198
+ """
199
+ _auth_rejected_sink(reason)
@@ -0,0 +1,319 @@
1
+ """Smart adaptive polling manager for async job completion."""
2
+
3
+ import asyncio
4
+ import logging
5
+ import time
6
+ from typing import Optional
7
+
8
+ from fastmcp import Context
9
+
10
+ from .config import PollingConfig, settings
11
+ from .deapi_client import DeapiAPIError, DeapiClient
12
+ from .observability import forget_api_error, note_job_failure
13
+ from .schemas import JobStatus, JobStatusResponse, ToolResult
14
+ from .webhooks import get_job_registry
15
+
16
+ logger = logging.getLogger(__name__)
17
+
18
+
19
+ def _current_context() -> Optional[Context]:
20
+ """The MCP context of the tool call being served, when there is one.
21
+
22
+ Taken from FastMCP rather than threaded through every tool's signature, so
23
+ each wait reports progress to the client (and to clients that reset their
24
+ call timeout on progress, keeps the call alive). Outside a request — tests,
25
+ scripts — there is none and the poller runs silently, as before.
26
+
27
+ The context is used for progress notifications only. Status lines go to the
28
+ server's own logger, not to the client: the MCP logging capability
29
+ (``ctx.info`` and friends, ``notifications/message``) is deprecated as of
30
+ the 2026-07-28 protocol revision.
31
+ """
32
+ try:
33
+ from fastmcp.server.dependencies import get_context
34
+
35
+ return get_context()
36
+ except Exception:
37
+ return None
38
+
39
+
40
+ class PollingManager:
41
+ """Manages adaptive polling for async job completion."""
42
+
43
+ def __init__(self, client: DeapiClient, job_type: str, max_wait: Optional[float] = None):
44
+ """Initialize polling manager.
45
+
46
+ Args:
47
+ client: Initialized DeapiClient instance
48
+ job_type: Type of job for adaptive polling config (audio, image, video, etc.)
49
+ max_wait: Longest this call waits, in seconds. Defaults to
50
+ settings.tool_max_wait; the job type's own `timeout` caps it too.
51
+ Reaching it is not a failure: the job keeps running and the
52
+ result says so (`in_progress`), with the job_id to resume from.
53
+ """
54
+ self.client = client
55
+ self.job_type = job_type
56
+ self.config: PollingConfig = settings.get_polling_config(job_type)
57
+ self.max_wait = min(
58
+ max_wait if max_wait is not None else settings.tool_max_wait, self.config.timeout
59
+ )
60
+
61
+ async def _wait_before_next_poll(self, job_id: str, delay: float, remaining: float) -> None:
62
+ """Pause between status checks.
63
+
64
+ For a job the API will call us back about, block on that callback with
65
+ the fallback interval as a cap, so a completed job is noticed at once
66
+ and a lost callback still gets polled. Otherwise sleep the adaptive
67
+ delay as before.
68
+ """
69
+ # Never sleep past the end of this call's wait: the last status check
70
+ # should land just before it, not one long backoff after.
71
+ remaining = max(remaining, 0.0)
72
+ job_registry = get_job_registry()
73
+ if not job_registry.is_tracked(job_id):
74
+ await asyncio.sleep(min(delay, remaining))
75
+ return
76
+
77
+ event = job_registry.track(job_id)
78
+ try:
79
+ await asyncio.wait_for(
80
+ event.wait(), timeout=min(settings.webhook_fallback_poll_interval, remaining)
81
+ )
82
+ except asyncio.TimeoutError:
83
+ return # safety-net poll
84
+ # Woken by the callback. Clear so a non-terminal wake (should not happen,
85
+ # but a replayed delivery could cause one) does not spin the loop.
86
+ event.clear()
87
+
88
+ @staticmethod
89
+ async def _report(
90
+ ctx: Optional[Context],
91
+ progress: float,
92
+ last_reported: Optional[float],
93
+ message: str,
94
+ ) -> Optional[float]:
95
+ """Send a progress notification, carrying ``message`` as the status line.
96
+
97
+ Progress must rise from one notification to the next, so a value that
98
+ is not above the last one sent is skipped. Returns the last value sent.
99
+ Best effort: a notification that cannot be delivered must not turn a
100
+ job's outcome into an error.
101
+ """
102
+ if ctx is None or (last_reported is not None and progress <= last_reported):
103
+ return last_reported
104
+ try:
105
+ await ctx.report_progress(progress=progress, total=100.0, message=message)
106
+ except Exception:
107
+ logger.debug("Could not send a progress notification", exc_info=True)
108
+ return last_reported
109
+ return progress
110
+
111
+ def _calculate_next_delay(self, current_delay: float, attempt: int) -> float:
112
+ """Calculate next polling delay with exponential backoff.
113
+
114
+ Args:
115
+ current_delay: Current delay in seconds
116
+ attempt: Current attempt number
117
+
118
+ Returns:
119
+ Next delay in seconds, capped at max_delay
120
+ """
121
+ next_delay = current_delay * self.config.backoff_factor
122
+ return min(next_delay, self.config.max_delay)
123
+
124
+ async def poll_until_complete(
125
+ self,
126
+ job_id: str,
127
+ ctx: Optional[Context] = None,
128
+ ) -> ToolResult:
129
+ """Poll job status until completion or timeout.
130
+
131
+ Args:
132
+ job_id: Job request ID to poll
133
+ ctx: Optional MCP context for progress reporting
134
+
135
+ Returns:
136
+ ToolResult with final job status and result. Never raises for a job
137
+ that was submitted: a timeout, a 404, repeated API errors or a status
138
+ response this client cannot read all come back as a failed ToolResult
139
+ that still carries ``job_id``. The job may well finish anyway (and has
140
+ been paid for), and ``check_job_status`` can still reach it — but only
141
+ if the caller was told the id.
142
+ """
143
+ ctx = ctx or _current_context()
144
+ result: Optional[ToolResult] = None
145
+ try:
146
+ result = await self._poll_until_complete(job_id, ctx)
147
+ return result
148
+ finally:
149
+ # Once the job is over nobody will listen for it again. A job still
150
+ # running stays tracked, so a later check_job_status(wait_seconds)
151
+ # wakes on its callback too; the registry's TTL sweep bounds it.
152
+ if result is None or not result.in_progress:
153
+ get_job_registry().forget(job_id)
154
+
155
+ async def _poll_until_complete(
156
+ self,
157
+ job_id: str,
158
+ ctx: Optional[Context],
159
+ ) -> ToolResult:
160
+ start_time = time.time()
161
+ current_delay = self.config.initial_delay
162
+ attempt = 0
163
+ last_progress = None
164
+ reported: Optional[float] = None # last progress value sent to the client
165
+
166
+ logger.debug("Polling %s job %s", self.job_type, job_id)
167
+ reported = await self._report(
168
+ ctx, 0.0, reported, f"Job {job_id} submitted, waiting for the {self.job_type} job"
169
+ )
170
+
171
+ while True:
172
+ attempt += 1
173
+ elapsed = time.time() - start_time
174
+
175
+ # Poll job status
176
+ try:
177
+ status_response: JobStatusResponse = await self.client.get_job_status(job_id)
178
+ status_data = status_response.data
179
+ current_status = status_data.status
180
+
181
+ # Report progress, with the status as its message, when it rose
182
+ if status_data.progress is not None:
183
+ reported = await self._report(
184
+ ctx,
185
+ status_data.progress,
186
+ reported,
187
+ f"Job {job_id} {current_status.value}: "
188
+ f"{status_data.progress:.0f}% after {elapsed:.0f}s",
189
+ )
190
+ last_progress = status_data.progress
191
+
192
+ if attempt % 5 == 0: # every 5th attempt, to avoid spam
193
+ logger.debug(
194
+ "Job %s status: %s (elapsed: %.1fs, attempt: %d)",
195
+ job_id,
196
+ current_status.value,
197
+ elapsed,
198
+ attempt,
199
+ )
200
+
201
+ # Check if job is complete
202
+ if current_status == JobStatus.DONE:
203
+ logger.debug("Job %s completed after %.1fs", job_id, elapsed)
204
+ await self._report(
205
+ ctx, 100.0, reported, f"Job {job_id} completed after {elapsed:.0f}s"
206
+ )
207
+
208
+ return ToolResult(
209
+ success=True,
210
+ job_id=job_id,
211
+ status=current_status,
212
+ result=status_data.result,
213
+ result_url=status_data.result_url,
214
+ price=status_data.price,
215
+ results_alt_formats=status_data.results_alt_formats,
216
+ prompt_boost=status_data.prompt_boost,
217
+ # The API's own metadata (title, channel, views) when the job
218
+ # asked for it with include_metadata; ours goes in `metadata`.
219
+ source_metadata=status_data.metadata,
220
+ metadata={
221
+ "elapsed_time": elapsed,
222
+ "attempts": attempt,
223
+ },
224
+ )
225
+
226
+ elif current_status.is_failure:
227
+ note_job_failure(status_data.error_reason)
228
+ # Prefer the API's own reason. Falling back to a generic message
229
+ # would discard the only information the caller can act on.
230
+ error_msg = status_data.error_reason or f"Job {job_id} failed"
231
+ if status_data.error_code:
232
+ error_msg = f"{error_msg} ({status_data.error_code})"
233
+ # The tool result carries the error to the client.
234
+ logger.info("Job %s failed: %s", job_id, error_msg)
235
+
236
+ return ToolResult(
237
+ success=False,
238
+ job_id=job_id,
239
+ status=current_status,
240
+ error=error_msg,
241
+ error_code=status_data.error_code,
242
+ retryable=status_data.retryable,
243
+ refunded=status_data.refunded,
244
+ metadata={
245
+ "elapsed_time": elapsed,
246
+ "attempts": attempt,
247
+ },
248
+ )
249
+
250
+ # Job still in progress, wait before next poll
251
+ if status_data.progress is not None:
252
+ last_progress = status_data.progress
253
+ remaining = self.max_wait - (time.time() - start_time)
254
+ # This call has waited long enough. The job has not failed — it is
255
+ # still running, paid for, and reachable by its id — so say exactly
256
+ # that instead of reporting an error. Checked right after a status
257
+ # read, never after a wait: a wait that runs to the end of the budget
258
+ # (a callback that never came) is always followed by one more read,
259
+ # so a job that finished meanwhile is returned, not reported as running.
260
+ if remaining <= 0:
261
+ elapsed = time.time() - start_time
262
+ logger.debug("Job %s still running after %.0fs", job_id, elapsed)
263
+ return ToolResult(
264
+ success=True,
265
+ in_progress=True,
266
+ job_id=job_id,
267
+ status=current_status,
268
+ progress=last_progress,
269
+ metadata={"elapsed_time": elapsed, "attempts": attempt},
270
+ )
271
+ await self._wait_before_next_poll(job_id, current_delay, remaining)
272
+ current_delay = self._calculate_next_delay(current_delay, attempt)
273
+
274
+ except DeapiAPIError as e:
275
+ # API error during status check
276
+ logger.warning("Error checking job %s status: %s", job_id, e)
277
+
278
+ # If it's a 404, the job might not exist
279
+ if e.status_code == 404:
280
+ return ToolResult(
281
+ success=False,
282
+ job_id=job_id,
283
+ error="Job not found",
284
+ metadata={"elapsed_time": elapsed, "attempts": attempt},
285
+ )
286
+
287
+ # For other errors, retry with delay
288
+ if attempt < 3: # Retry a few times for transient errors
289
+ # Retried, so this error does not end the call; a later attempt
290
+ # that also fails notes its own.
291
+ forget_api_error()
292
+ logger.info("Retrying job %s status (attempt %d/3)", job_id, attempt + 1)
293
+ await asyncio.sleep(current_delay)
294
+ current_delay = self._calculate_next_delay(current_delay, attempt)
295
+ else:
296
+ # Too many errors, give up
297
+ return ToolResult(
298
+ success=False,
299
+ job_id=job_id,
300
+ error=str(e),
301
+ metadata={"elapsed_time": elapsed, "attempts": attempt},
302
+ )
303
+
304
+ except Exception as e:
305
+ # Anything else is a defect on this side of the wire — typically a
306
+ # status payload the schema does not model yet. Retrying cannot
307
+ # help, and letting it propagate would turn a paid, possibly
308
+ # finished job into an anonymous "Unexpected error".
309
+ error_msg = (
310
+ f"Could not read the status of job {job_id}: {e}. "
311
+ "The job may still complete; query it with check_job_status."
312
+ )
313
+ logger.warning("Could not read the status of job %s", job_id, exc_info=True)
314
+ return ToolResult(
315
+ success=False,
316
+ job_id=job_id,
317
+ error=error_msg,
318
+ metadata={"elapsed_time": elapsed, "attempts": attempt},
319
+ )
deapi_mcp/py.typed ADDED
File without changes