diff --git a/dashscope/__init__.py b/dashscope/__init__.py index 5fd3ef90..f8c17389 100644 --- a/dashscope/__init__.py +++ b/dashscope/__init__.py @@ -87,6 +87,12 @@ from dashscope._quickstart import chat from dashscope.client import AsyncClient, Client from dashscope.errors import DashScopeError, ErrorCode +from dashscope.region_router import ( + AsyncRegionRouter, + ModelAvailability, + RegionModelInfo, + RegionRouter, +) from dashscope.transport.ws_connection import WsConnection, WsTask # cn-beijing defaults to the legacy dashscope.aliyuncs.com endpoints; @@ -297,10 +303,14 @@ def __dir__(): "VideoSynthesis", # dashscope 2.0 "AsyncClient", + "AsyncRegionRouter", "Client", "Config", "DashScopeError", "ErrorCode", + "ModelAvailability", + "RegionModelInfo", + "RegionRouter", "Settings", "WsConnection", "WsTask", diff --git a/dashscope/_config.py b/dashscope/_config.py index 145d6d04..e39cacb9 100644 --- a/dashscope/_config.py +++ b/dashscope/_config.py @@ -31,6 +31,7 @@ from __future__ import annotations import os +import re import threading import warnings from dataclasses import dataclass @@ -234,10 +235,66 @@ def _legacy_fallback(host: str) -> str: return host +# RFC1123 DNS label: lowercase letters/digits/hyphen, 1-63 chars, no +# leading/trailing hyphen. ``region`` and ``workspace`` are interpolated +# into the gateway host (``{workspace}.{region}.maas.aliyuncs.com``), so +# any character outside this set (dot, slash, ``@``, uppercase, ...) could +# rewrite the host and must be rejected before it reaches a URL. +_SAFE_LABEL_RE = re.compile(r"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$") + + +def _is_safe_region_label(region: str) -> bool: + return isinstance(region, str) and bool(_SAFE_LABEL_RE.match(region)) + + def _validate_region(region: str) -> str: - if region not in VALID_REGIONS: + """Format-check a region that may be interpolated into a gateway host. + + The static whitelist is no longer a hard gate -- it would block newly + launched regions before an SDK upgrade. Membership is decided by + :func:`_gateway_region` from the workspace/base_url context; here we + only reject labels that could rewrite the host. + """ + if not _is_safe_region_label(region): + raise ValueError( + f"invalid region {region!r}: expected a lowercase DNS label " + f"(letters, digits, hyphens), e.g. 'cn-beijing'", + ) + return region + + +def _gateway_region(region: str, workspace: Optional[str]) -> str: + """Apply the region allowance policy for a default gateway host. + + - workspace configured: any safe label passes; an unknown region + (not in ``VALID_REGIONS``) warns instead of rejecting, so a newly + launched region works without an SDK upgrade. + - no workspace (legacy shared gateway): the region must have a known + gateway mapping, otherwise the shared endpoint cannot be built. + + The workspace is host-interpolated too, so it must also be a safe + label. An explicit ``base_url`` bypasses this entirely (the caller + never builds a default host). + """ + region = _validate_region(region) + if workspace: + if not _is_safe_region_label(workspace): + raise ValueError( + f"invalid workspace {workspace!r}: expected a lowercase " + f"DNS label (letters, digits, hyphens)", + ) + if region not in VALID_REGIONS: + warnings.warn( + f"region {region!r} is not a known DashScope region; " + f"passing it through to the workspace gateway. Ensure " + f"the workspace and API key belong to this region.", + UserWarning, + stacklevel=2, + ) + elif region not in LEGACY_GATEWAY_HOSTS: raise ValueError( - f"invalid region {region!r}, expected one of {VALID_REGIONS}", + f"invalid region {region!r}: no shared gateway mapping; " + f"configure a workspace or an explicit base_url", ) return region @@ -261,7 +318,7 @@ def _protocol_default_base_url( workspace: Optional[str], region: Optional[str] = None, ) -> str: - region = _validate_region(region or DEFAULT_REGION) + region = _gateway_region(region or DEFAULT_REGION, workspace) if workspace: host = WORKSPACE_GATEWAY_TEMPLATE.format( workspace=workspace, @@ -294,6 +351,26 @@ def compatible_mode_base_url( return _protocol_default_base_url("openai", workspace, region) +def anthropic_base_url( + workspace: Optional[str], + region: Optional[str] = None, + configured_base_url: Optional[str] = None, +) -> str: + """Endpoint root for the Anthropic-compatible Messages API. + + Messages lives under ``/apps/anthropic`` (the wire path is + ``/v1/messages`` beneath it), independent of the chat ``protocol`` + setting -- the same rule ``compatible_mode_base_url`` applies. An + explicit base_url stays the service root (callers point it at + ``.../apps/anthropic``); otherwise the default gateway host carries + the fixed anthropic path. The root deliberately does not end in + ``/v1`` so clients appending ``/v1/messages`` do not double it. + """ + if configured_base_url is not None: + return configured_base_url + return _protocol_default_base_url("anthropic", workspace, region) + + def workspace_ws_url( workspace: Optional[str], path: str, @@ -307,7 +384,7 @@ def workspace_ws_url( gateway (``wss://dashscope.aliyuncs.com`` for cn-beijing) with a warning. """ - region = _validate_region(region or DEFAULT_REGION) + region = _gateway_region(region or DEFAULT_REGION, workspace) if workspace: host = WORKSPACE_WS_GATEWAY_TEMPLATE.format( workspace=workspace, @@ -443,6 +520,14 @@ def region(self) -> str: @region.setter def region(self, value: str) -> None: _validate_region(value) + if value not in VALID_REGIONS: + warnings.warn( + f"region {value!r} is not a known DashScope region; it " + f"will pass through to the workspace gateway (or require " + f"an explicit base_url / known shared-gateway mapping).", + UserWarning, + stacklevel=2, + ) with self._lock: self._explicit["region"] = value diff --git a/dashscope/cli/commands/models.py b/dashscope/cli/commands/models.py index 226fd9a8..d1bf747a 100644 --- a/dashscope/cli/commands/models.py +++ b/dashscope/cli/commands/models.py @@ -40,7 +40,7 @@ def list_models( provider: Optional[str] = typer.Option( None, "--provider", - help="Filter by provider or source (client-side, per page).", + help="Filter by provider (server-side; folds into providers).", ), ) -> None: """List available models.""" diff --git a/dashscope/cli/config_store.py b/dashscope/cli/config_store.py index 12990623..9a0475d5 100644 --- a/dashscope/cli/config_store.py +++ b/dashscope/cli/config_store.py @@ -173,7 +173,6 @@ def _enum_choices() -> Dict[str, Tuple[str, Tuple[str, ...]]]: """ from dashscope._config import ( # pylint: disable=import-outside-toplevel VALID_PROTOCOLS, - VALID_REGIONS, ) from dashscope.cli.output import ( # pylint: disable=import-outside-toplevel OUTPUT_FORMATS, @@ -181,7 +180,6 @@ def _enum_choices() -> Dict[str, Tuple[str, Tuple[str, ...]]]: return { "protocol": ("protocol", tuple(VALID_PROTOCOLS)), - "region": ("region", tuple(VALID_REGIONS)), "output": ("output format", tuple(OUTPUT_FORMATS)), } @@ -230,6 +228,17 @@ def _validate(key: str, value: Any) -> Any: f"{', '.join(allowed)}", ) return value + if key == "region": + from dashscope._config import ( # pylint: disable=import-outside-toplevel + _is_safe_region_label, + ) + + if not _is_safe_region_label(value): + raise usage_error( + f"invalid region {value!r}, expected a lowercase DNS " + f"label (letters, digits, hyphens), e.g. 'cn-beijing'", + ) + return value if key in _POSITIVE_SECONDS: return _validate_number(key, value, integer=False, positive=True) if key in _NON_NEGATIVE_INTS: diff --git a/dashscope/client.py b/dashscope/client.py index 5f6d342f..64454ad2 100644 --- a/dashscope/client.py +++ b/dashscope/client.py @@ -17,17 +17,22 @@ from dashscope.protocols import ChatProtocol, get_protocol from dashscope.resources.apps import Apps, AsyncApps from dashscope.resources.audio import AsyncAudio, Audio +from dashscope.resources.batch_chat import AsyncBatchChat, BatchChat +from dashscope.resources.batches import AsyncBatches, Batches from dashscope.resources.chat import AsyncChat, Chat +from dashscope.resources.conversations import AsyncConversations, Conversations from dashscope.resources.decision import AsyncDecision, Decision from dashscope.resources.deployments import AsyncDeployments, Deployments from dashscope.resources.embeddings import AsyncEmbeddings, Embeddings from dashscope.resources.files import AsyncFiles, Files from dashscope.resources.fine_tunes import AsyncFineTunes, FineTunes from dashscope.resources.images import AsyncImages, Images +from dashscope.resources.messages import AsyncMessages, Messages from dashscope.resources.models import AsyncModels, Models from dashscope.resources.multimodal import AsyncMultimodal, Multimodal from dashscope.resources.rerank import AsyncRerank, Rerank from dashscope.resources.reinforcement_learning import AsyncRl, Rl +from dashscope.resources.responses import AsyncResponses, Responses from dashscope.resources.tingwu import AsyncTingWu, TingWu from dashscope.resources.tokenization import AsyncTokenization, Tokenization from dashscope.resources.videos import AsyncVideos, Videos @@ -135,6 +140,11 @@ def __init__( self.decision = Decision(self) self.tokenization = Tokenization(self) self.files = Files(self) + self.batches = Batches(self) + self.batch_chat = BatchChat(self) + self.responses = Responses(self) + self.conversations = Conversations(self) + self.messages = Messages(self) self.models = Models(self) self.images = Images(self) self.videos = Videos(self) @@ -397,6 +407,11 @@ def __init__( self.decision = AsyncDecision(self) self.tokenization = AsyncTokenization(self) self.files = AsyncFiles(self) + self.batches = AsyncBatches(self) + self.batch_chat = AsyncBatchChat(self) + self.responses = AsyncResponses(self) + self.conversations = AsyncConversations(self) + self.messages = AsyncMessages(self) self.models = AsyncModels(self) self.images = AsyncImages(self) self.videos = AsyncVideos(self) diff --git a/dashscope/protocols/anthropic.py b/dashscope/protocols/anthropic.py index ae92c5a0..27292489 100644 --- a/dashscope/protocols/anthropic.py +++ b/dashscope/protocols/anthropic.py @@ -35,6 +35,7 @@ Callable, Dict, List, + Mapping, Optional, Tuple, Union, @@ -53,11 +54,71 @@ __all__ = [ "AnthropicProtocol", + "WEB_SEARCH_BILLING_HEADER", + "detect_web_search_tool", + "ensure_billing_header", + "system_has_billing_header", ] # Anthropic requires max_tokens; used when the caller omits it. DEFAULT_MAX_TOKENS = 4096 +# Server-side web search only fires when the system prompt carries this +# client identifier. The SDK injects it when a web_search server tool is +# declared (a caller-provided marker wins). Shared with the native +# ``client.messages`` resource so both Anthropic paths behave identically. +WEB_SEARCH_BILLING_HEADER = "x-anthropic-billing-header: cc_entrypoint=cli;" +_BILLING_MARKER = "x-anthropic-billing-header" + + +def detect_web_search_tool(tools: Any) -> bool: + """True when a server-side web_search tool is declared in ``tools``. + + Identified by ``name == "web_search"`` plus a date-suffixed + ``web_search_*`` type, so a custom function merely named web_search + (no such type) does not trigger the billing-header injection. + """ + if not isinstance(tools, (list, tuple)): + return False + return any( + isinstance(t, Mapping) + and t.get("name") == "web_search" + and str(t.get("type") or "").startswith("web_search") + for t in tools + ) + + +def system_has_billing_header(system: Any) -> bool: + if isinstance(system, str): + return _BILLING_MARKER in system + if isinstance(system, (list, tuple)): + return any( + isinstance(b, Mapping) and _BILLING_MARKER in (b.get("text") or "") + for b in system + ) + return False + + +def ensure_billing_header(system: Any, tools: Any) -> Any: + """Inject the web-search billing identifier into ``system`` when needed. + + Returns ``system`` unchanged when no web_search server tool is declared + or the caller already supplied the marker. A string system becomes a + block list so the marker rides as its own text block (a valid system + block form; the docs mandate the identifier, not this packaging). + """ + if not detect_web_search_tool(tools) or system_has_billing_header(system): + return system + marker_block = {"type": "text", "text": WEB_SEARCH_BILLING_HEADER} + if system is None: + return [marker_block] + if isinstance(system, str): + return [{"type": "text", "text": system}, marker_block] + if isinstance(system, (list, tuple)): + return list(system) + [marker_block] + return system + + # Canonical parameters this adapter does not map onto the Anthropic # Messages wire (``tool_choice`` does map — see _translate_tool_choice; # ``enable_thinking``/``thinking_budget`` reach the wire's ``thinking`` @@ -761,6 +822,14 @@ def build_chat_request( ), ) _apply_extra_parameters(body, self._strict, extra_parameters) + # Server tools (web_search) reach the wire via extra_parameters; + # inject the billing identifier the same way the native messages + # resource does, so both Anthropic paths enable search identically. + if detect_web_search_tool(body.get("tools")): + body["system"] = ensure_billing_header( + body.get("system"), + body.get("tools"), + ) return ChatRequest( path=path or self.PATH, body=body, diff --git a/dashscope/region_router.py b/dashscope/region_router.py new file mode 100644 index 00000000..206aa47c --- /dev/null +++ b/dashscope/region_router.py @@ -0,0 +1,277 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Explicit cross-Region model discovery (A5, scope-review §22.7). + +A :class:`RegionRouter` aggregates several per-Region Clients that the +caller supplies explicitly -- the SDK never guesses another Region's +credential or workspace (§22.4). It answers "which Regions serve this +model" by probing each Client's own catalog; it does **not** route or +replay inference requests, and there is **no automatic cross-Region +fallback** (§22.8): a Region that errors is reported as an error entry, +never silently skipped or retried elsewhere. + +**Disabled by default.** Cross-Region discovery may move data across +borders, so constructing a router requires an explicit +``allow_cross_region=True`` opt-in, and enabling it warns that +**cross-border data compliance is the user's sole responsibility**. +""" + +from __future__ import annotations + +import warnings +from typing import Dict, List, Mapping, Optional + +from pydantic import BaseModel, Field + +from dashscope._config import _is_safe_region_label +from dashscope.client import AsyncClient, Client +from dashscope.errors import DashScopeError +from dashscope.resources.models import Model + +__all__ = [ + "AsyncRegionRouter", + "ModelAvailability", + "RegionModelInfo", + "RegionRouter", +] + +_CROSS_BORDER_NOTICE = ( + "RegionRouter performs cross-region model discovery, which may involve " + "cross-border data transfer. Cross-border data compliance is the user's " + "sole responsibility: you must ensure compliance with all applicable " + "data-export, residency and privacy laws before enabling it." +) + +_OPT_IN_REQUIRED = ( + "cross-region discovery is disabled by default. Pass " + "allow_cross_region=True to opt in. " + _CROSS_BORDER_NOTICE +) + + +def _gate_cross_region(allow_cross_region: bool) -> None: + if not allow_cross_region: + raise ValueError(_OPT_IN_REQUIRED) + warnings.warn(_CROSS_BORDER_NOTICE, UserWarning, stacklevel=3) + + +class RegionModelInfo(BaseModel): + """One Region's answer for a model. + + ``available`` is True only when that Region's catalog lists the model. + ``model`` carries the catalog entry when available. ``error`` is set + when the Region query itself failed (auth/transport/HTTP), which is + distinct from "the model is not in this Region's catalog"; the Region + label is always present so a failure is attributable (§22.8). + """ + + region: str + available: bool = False + model: Optional[Model] = None + error: Optional[str] = None + + +class ModelAvailability(BaseModel): + """Aggregated cross-Region availability for one model.""" + + model: str + regions: Dict[str, RegionModelInfo] = Field(default_factory=dict) + + @property + def available_in(self) -> List[str]: + """The Region labels whose catalog serves the model.""" + return [ + region for region, info in self.regions.items() if info.available + ] + + +def _validate_clients(clients, expected_type): + if not clients: + raise ValueError( + "RegionRouter requires at least one per-region Client", + ) + validated = {} + for region, client in clients.items(): + if not _is_safe_region_label(region): + raise ValueError( + f"invalid region label {region!r}: expected a lowercase DNS " + f"label (letters, digits, hyphens), e.g. 'cn-beijing'", + ) + if not isinstance(client, expected_type): + raise TypeError( + f"clients[{region!r}] must be a {expected_type.__name__}", + ) + if client.config.region != region: + raise ValueError( + f"clients[{region!r}] is configured for region " + f"{client.config.region!r}; the key must match the client's " + f"own region (region/workspace/key are one config unit)", + ) + validated[region] = client + return validated + + +def _error_text(exc: DashScopeError) -> str: + return f"{exc.code}: {exc.message}" + + +class _RouterModels: + def __init__(self, clients: Mapping[str, Client]) -> None: + self._clients = clients + + def available_regions( + self, + model: str, + *, + timeout: Optional[float] = None, + refresh: bool = False, + ) -> ModelAvailability: + """Probe every supplied Region's catalog for ``model``. + + Each Region is queried through its own Client (its own credential, + workspace and endpoint); ``timeout`` / ``refresh`` forward to the + catalog read. A Region that fails is recorded with its error rather + than aborting the discovery or falling back to another Region. + """ + if not model or not model.strip(): + raise ValueError("model must be a non-empty model id") + regions = {} + for region, client in self._clients.items(): + regions[region] = _probe_region( + client, + model, + region, + timeout=timeout, + refresh=refresh, + ) + return ModelAvailability(model=model, regions=regions) + + +def _probe_region(client, model, region, *, timeout, refresh): + try: + available = client.models.is_available( + model, + timeout=timeout, + refresh=refresh, + ) + except DashScopeError as exc: + return RegionModelInfo( + region=region, + available=False, + error=_error_text(exc), + ) + if not available: + return RegionModelInfo(region=region, available=False) + try: + # is_available already made (or refreshed) the shared catalog read, + # so get reuses it from the cache rather than fetching again. + entry = client.models.get(model, timeout=timeout) + except DashScopeError as exc: + return RegionModelInfo( + region=region, + available=True, + error=_error_text(exc), + ) + return RegionModelInfo(region=region, available=True, model=entry) + + +class RegionRouter: + """Aggregate explicit per-Region Clients for cross-Region discovery. + + >>> router = RegionRouter( + ... clients={"cn-beijing": bj, "ap-southeast-1": sg}, + ... allow_cross_region=True, + ... ) + >>> router.models.available_regions("qwen-plus").available_in + ['cn-beijing', 'ap-southeast-1'] + + Keys must be safe DNS region labels matching each Client's own + ``config.region``; values must be :class:`~dashscope.Client` instances. + Discovery only -- no inference routing, no automatic fallback. + + Disabled by default: ``allow_cross_region`` must be explicitly True, + which warns that cross-border data compliance is the user's sole + responsibility. + """ + + def __init__( + self, + clients: Mapping[str, Client], + *, + allow_cross_region: bool = False, + ) -> None: + _gate_cross_region(allow_cross_region) + self._clients = _validate_clients(clients, Client) + self.models = _RouterModels(self._clients) + + +class _AsyncRouterModels: + def __init__(self, clients: Mapping[str, AsyncClient]) -> None: + self._clients = clients + + async def available_regions( + self, + model: str, + *, + timeout: Optional[float] = None, + refresh: bool = False, + ) -> ModelAvailability: + """Async :meth:`_RouterModels.available_regions`.""" + if not model or not model.strip(): + raise ValueError("model must be a non-empty model id") + regions = {} + for region, client in self._clients.items(): + regions[region] = await _probe_region_async( + client, + model, + region, + timeout=timeout, + refresh=refresh, + ) + return ModelAvailability(model=model, regions=regions) + + +async def _probe_region_async(client, model, region, *, timeout, refresh): + try: + available = await client.models.is_available( + model, + timeout=timeout, + refresh=refresh, + ) + except DashScopeError as exc: + return RegionModelInfo( + region=region, + available=False, + error=_error_text(exc), + ) + if not available: + return RegionModelInfo(region=region, available=False) + try: + # is_available already made (or refreshed) the shared catalog read, + # so get reuses it from the cache rather than fetching again. + entry = await client.models.get(model, timeout=timeout) + except DashScopeError as exc: + return RegionModelInfo( + region=region, + available=True, + error=_error_text(exc), + ) + return RegionModelInfo(region=region, available=True, model=entry) + + +class AsyncRegionRouter: + """Async :class:`RegionRouter`; per-Region ``AsyncClient`` instances. + + Disabled by default: ``allow_cross_region`` must be explicitly True, + which warns that cross-border data compliance is the user's sole + responsibility. + """ + + def __init__( + self, + clients: Mapping[str, AsyncClient], + *, + allow_cross_region: bool = False, + ) -> None: + _gate_cross_region(allow_cross_region) + self._clients = _validate_clients(clients, AsyncClient) + self.models = _AsyncRouterModels(self._clients) diff --git a/dashscope/resources/_model_cache.py b/dashscope/resources/_model_cache.py new file mode 100644 index 00000000..6ccd5c66 --- /dev/null +++ b/dashscope/resources/_model_cache.py @@ -0,0 +1,112 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Short-TTL in-memory cache for the read-only model catalog (A4). + +The catalog (``models.list`` / ``get`` / ``is_available``) is slow-changing +reference data, so repeated identical reads within a short window can be +served from memory instead of the gateway. The cache is per-Models-instance +and keyed by Region, workspace, credential identity and the exact query, so +an entry never crosses tenants or Regions. Only successful responses are +stored; errors and ``raw=True`` reads bypass it, and ``refresh=True`` forces +a fresh fetch. Nothing is persisted to disk and no plaintext key is stored. +""" + +from __future__ import annotations + +import hashlib +import threading +import time +from typing import TYPE_CHECKING, Any, Dict, Mapping, Optional, Tuple + +if TYPE_CHECKING: + from dashscope.transport._response import APIResponse + +MODEL_CATALOG_CACHE_TTL = 60.0 + +_MAX_ENTRIES = 256 + +__all__ = [ + "MODEL_CATALOG_CACHE_TTL", + "catalog_key", + "credential_fingerprint", + "normalize_params", +] + + +def credential_fingerprint(api_key: Optional[str]) -> str: + """A short, non-reversible identity for the effective credential. + + Two calls with the same key share a cache entry; different keys (different + tenants) do not. The plaintext key is never stored -- only this digest. + """ + return hashlib.sha256((api_key or "").encode("utf-8")).hexdigest()[:16] + + +def normalize_params(params: Mapping[str, Any]) -> Tuple[Tuple[str, Any], ...]: + """A hashable, order-independent form of the catalog query params. + + Keys are sorted and list values become tuples so the same filter set + hashes identically regardless of dict ordering or list identity. + """ + items = [] + for key in sorted(params): + value = params[key] + if isinstance(value, (list, tuple)): + value = tuple(value) + items.append((key, value)) + return tuple(items) + + +def catalog_key( + config: Any, + params: Mapping[str, Any], + *, + api_key: Optional[str], + workspace: Optional[str], +) -> Tuple[Any, ...]: + """Build the isolation key for one catalog read. + + ``api_key`` / ``workspace`` are the per-call overrides; ``None`` falls + back to the client config, mirroring what the transport actually sends. + """ + eff_workspace = workspace if workspace is not None else config.workspace + eff_api_key = api_key if api_key is not None else config.api_key + return ( + config.region, + eff_workspace, + credential_fingerprint(eff_api_key), + normalize_params(params), + ) + + +class _CatalogCache: + """Per-instance TTL cache of successful catalog responses. + + Bounded to ``_MAX_ENTRIES``; the oldest entry is evicted when full. + Thread-safe for the sync client. The async client shares one instance on + a single event loop and never awaits inside the lock, so the same short + critical section is safe there too. + """ + + def __init__(self, ttl: float = MODEL_CATALOG_CACHE_TTL) -> None: + self._ttl = ttl + self._lock = threading.Lock() + self._entries: Dict[Any, Tuple[float, "APIResponse"]] = {} + + def get(self, key: Any) -> Optional["APIResponse"]: + with self._lock: + entry = self._entries.get(key) + if entry is None: + return None + stored_at, resp = entry + if time.monotonic() - stored_at >= self._ttl: + del self._entries[key] + return None + return resp + + def set(self, key: Any, resp: "APIResponse") -> None: + with self._lock: + if key not in self._entries and len(self._entries) >= _MAX_ENTRIES: + oldest = min(self._entries, key=lambda k: self._entries[k][0]) + del self._entries[oldest] + self._entries[key] = (time.monotonic(), resp) diff --git a/dashscope/resources/_ptu.py b/dashscope/resources/_ptu.py new file mode 100644 index 00000000..684825c9 --- /dev/null +++ b/dashscope/resources/_ptu.py @@ -0,0 +1,1876 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""PTU throughput-reservation capacity subresources (milestone D3). + +The native gateway exposes reserved throughput (``plan="ptu"``) under the +same ``/deployments`` base path as MU/lora deployments, plus two +subresources scoped to one ``deployed_model`` (ModelCode): + +* ``capacity-instances`` -- the billable capacity instances behind a + ModelCode. Write operations (create/scale/renew/delete) are asynchronous + and answer with a :class:`CapacityOperation`, not the instance itself. +* ``capacity-operations`` -- poll one write operation until it reaches a + terminal status (``SUCCEEDED`` / ``FAILED``). + +Billing safeguards (authoritative throughput-reservation contract): + +* Purchase/renew/scale/delete default to ``max_retries=0``: the wire has no + automatic dedup for a retried write, so a blind retry could spawn a + duplicate billable instance. Callers opt back in explicitly. +* Instance writes carry an idempotency key (``x-acs-req-uuid`` mirrored to + ``X-DashScope-RequestId``). Reusing the key with identical params reuses + the operation; a new business operation must use a new key. +* HTTP 200 is not operation success: ``output.operation_status`` may be + ``FAILED`` with ``error_code`` / ``error_message``. ``_check_operation`` + surfaces that as a catalog error when ``raise_on_error`` is set. + +The first ModelCode creation (``deployments.create(plan="ptu")``) is NOT +given an idempotency key -- the contract reserves the key for instance +operations and warns against deduping the initial ModelCode purchase. +""" + +from __future__ import annotations + +import asyncio +import time +import uuid +from typing import ( + TYPE_CHECKING, + Any, + Callable, + Dict, + List, + Literal, + Mapping, + Optional, + Union, + overload, +) +from urllib.parse import quote + +from pydantic import AliasChoices, BaseModel, ConfigDict, Field + +from dashscope.errors import DashScopeError, error_from_business_code +from dashscope.resources._jobs import ( + DEFAULT_MAX_INTERVAL, + DEFAULT_POLL_INTERVAL, + DEFAULT_WAIT_TIMEOUT, + FAILED, + SUCCEEDED, +) +from dashscope.transport._options import request_options +from dashscope.types._parse import parse_model +from dashscope.types.common import ( + ResponseBase, + flatten_envelope, + response_envelope, + with_headers, +) + +if TYPE_CHECKING: + import httpx + + from dashscope.transport._response import APIResponse + +_BASE_PATH = "/deployments" + +# 1.x tags this API "finetune" (Deployments lives in dashscope.finetune). +MODULE = "finetune" + +PROCESSING = "PROCESSING" +_OP_TERMINAL = frozenset({SUCCEEDED, FAILED}) + +__all__ = [ + "AsyncCapacityInstances", + "AsyncCapacityOperations", + "CapacityInstance", + "CapacityInstanceList", + "CapacityInstances", + "CapacityOperation", + "CapacityOperations", + "PrePaidInfo", + "PtuCapacity", +] + + +class PtuCapacity(BaseModel): + """Reserved throughput in kTPM (thousands of tokens per minute). + + ``input_tpm`` / ``output_tpm`` are required on a write; the optional + ``thinking_output_tpm`` reserves reasoning-output throughput separately. + Extra wire counters pass through untouched. + """ + + model_config = ConfigDict(extra="allow") + + input_tpm: Optional[int] = None + output_tpm: Optional[int] = None + thinking_output_tpm: Optional[int] = None + + +class PrePaidInfo(BaseModel): + """Pre-paid (subscription) billing terms for a PTU instance. + + ``pricing_cycle`` is case-sensitive: ``Day`` (default) or ``Hour`` + (8-hour trial, ``ptu_default`` only). ``duration`` is in cycles and must + be positive; an ``Hour`` purchase is fixed at 8 and cannot auto-renew. + """ + + model_config = ConfigDict(extra="allow") + + pricing_cycle: Optional[str] = None + duration: Optional[int] = None + auto_renewal: Optional[bool] = None + auto_renewal_duration: Optional[int] = None + auto_renewal_cycle: Optional[int] = None + + +class CapacityInstance(ResponseBase): + """One billable capacity instance behind a ModelCode. + + ``model_service_id`` is the ModelCode (the ``deployed_model`` the + instance belongs to); ``instance_id`` identifies this instance. The + ``can_*`` flags report which operations the platform currently allows + (an 8-hour trial instance, for example, cannot scale/renew/delete). + A released instance is ``deleted=True`` -- ``STOPPED`` alone is not a + release. + """ + + model_service_id: Optional[str] = None + instance_id: Optional[str] = None + charge_type: Optional[str] = None + status: Optional[str] = None + deleted: bool = False + effective_capacity: Optional[PtuCapacity] = None + configured_capacity: Optional[PtuCapacity] = None + target_capacity: Optional[PtuCapacity] = None + pre_paid_info: Optional[PrePaidInfo] = None + gmt_effective: Optional[str] = None + gmt_expired: Optional[str] = None + can_scale: Optional[bool] = None + can_renew: Optional[bool] = None + can_enable_auto_renew: Optional[bool] = None + can_disable_auto_renew: Optional[bool] = None + can_delete: Optional[bool] = None + fail_reason: Optional[str] = None + gmt_created: Optional[str] = None + gmt_modified: Optional[str] = None + gmt_deleted: Optional[str] = None + + +class CapacityInstanceList(ResponseBase): + """A page of capacity instances. + + This subresource paginates in camelCase, unlike the ModelCode-level + ``DeploymentList``: the wire sends ``records`` / ``items`` (total) / + ``page`` / ``itemsPerPage`` / ``pageCount``. The fields normalize to + snake_case while keeping the wire aliases readable. + """ + + records: List[CapacityInstance] = [] + total_count: int = Field( + 0, + validation_alias=AliasChoices("total_count", "items"), + ) + page: int = Field(1, validation_alias=AliasChoices("page", "page_no")) + items_per_page: int = Field( + 20, + validation_alias=AliasChoices( + "items_per_page", + "itemsPerPage", + "page_size", + ), + ) + page_count: int = Field( + 0, + validation_alias=AliasChoices("page_count", "pageCount"), + ) + + +class CapacityOperation(ResponseBase): + """The asynchronous result of one capacity write operation. + + ``operation_request_id`` is the request id of the ORIGINAL write call + that spawned this operation, preserved separately from the envelope + ``request_id`` (which is the id of this poll response). The two differ; + ``flatten_envelope`` would otherwise let the poll id overwrite the + write id, so ``_parse_operation`` captures it before flattening. + + ``operation_type`` is CREATE / SCALE / RENEW / DELETE for public writes + (STOP / REFUND are platform lifecycle events with no public write API). + """ + + operation_id: Optional[str] = None + operation_request_id: Optional[str] = None + operation_type: Optional[str] = None + operation_status: Optional[str] = None + model_service_id: Optional[str] = None + instance_id: Optional[str] = None + from_status: Optional[str] = None + current_status: Optional[str] = None + error_code: Optional[str] = None + error_message: Optional[str] = None + gmt_created: Optional[str] = None + gmt_finished: Optional[str] = None + + @property + def finished(self) -> bool: + return self.operation_status in _OP_TERMINAL + + @property + def succeeded(self) -> bool: + return self.operation_status == SUCCEEDED + + @property + def failed(self) -> bool: + return self.operation_status == FAILED + + +def _idempotency_headers( + extra_headers: Optional[Mapping[str, str]], +) -> Dict[str, str]: + """Mirror one idempotency key across both header spellings. + + Read priority is ``x-acs-req-uuid`` > ``X-DashScope-RequestId``, matched + case-insensitively (header names are case-insensitive on the wire); when + neither is supplied a fresh UUID is generated. Both headers are set to + the SAME value so the gateway dedups a network retry of this write. + A caller-supplied key is preserved, letting them reuse an operation + deliberately or rotate to a new business operation. Variant casings of + either name are normalized to the canonical pair so two conflicting + spellings never reach the wire together. + """ + headers = dict(extra_headers or {}) + lowered = {name.lower(): value for name, value in headers.items()} + key = lowered.get("x-acs-req-uuid") or lowered.get("x-dashscope-requestid") + if not key: + key = uuid.uuid4().hex + for name in list(headers): + if name.lower() in ("x-acs-req-uuid", "x-dashscope-requestid"): + del headers[name] + headers["x-acs-req-uuid"] = key + headers["X-DashScope-RequestId"] = key + return headers + + +def _purchase_retries(max_retries: Optional[int]) -> int: + """Default a billable write to no automatic retry. + + The wire has no dedup for a blindly retried purchase/renew/scale, so a + transport retry could create a duplicate billable instance. ``None`` + (the caller said nothing) becomes 0; an explicit value is honored. + """ + return 0 if max_retries is None else max_retries + + +def _path_id(value: str, name: str) -> str: + """Validate one URL path id and percent-encode it. + + An empty id would degenerate the URL to a collection path (including + on mutating endpoints); a ``/``, ``?`` or ``#`` inside an id would + silently retarget the request. Encoding keeps the id one segment. + """ + if not isinstance(value, str) or not value.strip(): + raise ValueError(f"{name} must be a non-empty string") + return quote(value, safe="") + + +def _ptu_capacity_body(capacity: Any) -> Dict[str, Any]: + """Normalize and validate a ``ptu_capacity`` write payload.""" + if isinstance(capacity, PtuCapacity): + capacity = capacity.model_dump(exclude_none=True) + if not isinstance(capacity, Mapping): + raise ValueError("ptu_capacity must be a mapping of TPM counters") + body = dict(capacity) + for key in ("input_tpm", "output_tpm"): + if key not in body: + raise ValueError(f"ptu_capacity requires '{key}'") + value = body[key] + if not isinstance(value, int) or isinstance(value, bool) or value < 0: + raise ValueError( + f"ptu_capacity '{key}' must be a non-negative int", + ) + return body + + +def _pre_paid_info_body(info: Any) -> Dict[str, Any]: + """Normalize and validate a ``pre_paid_info`` write payload.""" + if isinstance(info, PrePaidInfo): + info = info.model_dump(exclude_none=True) + if not isinstance(info, Mapping): + raise ValueError("pre_paid_info must be a mapping of billing terms") + body = dict(info) + duration = body.get("duration") + if duration is not None: + if not isinstance(duration, int) or isinstance(duration, bool): + raise ValueError("pre_paid_info 'duration' must be an int") + if duration <= 0: + raise ValueError("pre_paid_info 'duration' must be positive") + cycle = body.get("pricing_cycle") + if cycle is not None and cycle not in ("Day", "Hour"): + raise ValueError( + "pre_paid_info 'pricing_cycle' must be 'Day' or 'Hour'", + ) + return body + + +def _validate_order_type(order_type: Optional[str]) -> None: + if order_type is not None and order_type not in ("UPGRADE", "DOWNGRADE"): + raise ValueError("order_type must be 'UPGRADE' or 'DOWNGRADE'") + + +def _instance_create_body( + billing_method: str, + ptu_capacity: Any, + pre_paid_info: Any, +) -> Dict[str, Any]: + if billing_method not in ("PRE_PAY", "POST_PAY"): + raise ValueError("billing_method must be 'PRE_PAY' or 'POST_PAY'") + body: Dict[str, Any] = { + "billing_method": billing_method, + "ptu_capacity": _ptu_capacity_body(ptu_capacity), + } + if pre_paid_info is not None: + body["pre_paid_info"] = _pre_paid_info_body(pre_paid_info) + elif billing_method == "PRE_PAY": + raise ValueError("pre_paid_info is required for PRE_PAY billing") + return body + + +def _instance_scale_body( + ptu_capacity: Any, + order_type: Optional[str], +) -> Dict[str, Any]: + _validate_order_type(order_type) + body: Dict[str, Any] = {"ptu_capacity": _ptu_capacity_body(ptu_capacity)} + if order_type is not None: + body["order_type"] = order_type + return body + + +def _renew_body( + pre_paid_info: Any, + is_change: Optional[bool], + ptu_capacity: Any, + instance_id: Optional[str] = None, +) -> Dict[str, Any]: + body: Dict[str, Any] = { + "pre_paid_info": _pre_paid_info_body(pre_paid_info), + } + if instance_id is not None: + body["instance_id"] = instance_id + if is_change is not None: + body["is_change"] = is_change + if ptu_capacity is not None: + if not is_change: + raise ValueError( + "changing ptu_capacity on renew requires is_change=True", + ) + body["ptu_capacity"] = _ptu_capacity_body(ptu_capacity) + return body + + +def _parse_operation( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> CapacityOperation: + output = body.get("output") + output = output if isinstance(output, dict) else {} + flat = flatten_envelope(body) + # The inner request_id is the original write's id; capture it before + # the envelope's poll id wins the flattened ``request_id`` field. + original = output.get("request_id") + if original is not None: + flat["operation_request_id"] = original + return parse_model( + CapacityOperation, + flat, + strict=strict, + response=response, + ) + + +def _parse_instance( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> CapacityInstance: + return parse_model( + CapacityInstance, + flatten_envelope(body), + strict=strict, + response=response, + ) + + +def _parse_instance_list( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> CapacityInstanceList: + data = flatten_envelope(body) + records = data.get("records") + if not isinstance(records, list): + records = [] + # Honor every alias the model declares: a snake_case answer must not + # fall back to len(records)/20 and truncate pagination early. + return parse_model( + CapacityInstanceList, + { + "records": records, + "total_count": data.get( + "items", + data.get("total_count", len(records)), + ), + "page": data.get("page", data.get("page_no", 1)), + "items_per_page": data.get( + "itemsPerPage", + data.get("items_per_page", data.get("page_size", 20)), + ), + "page_count": data.get( + "pageCount", + data.get("page_count", 0), + ), + **response_envelope(data), + }, + strict=strict, + response=response, + ) + + +def _check_operation( + client: Any, + operation: CapacityOperation, +) -> CapacityOperation: + """Surface an HTTP-200 operation failure as a catalog error. + + A capacity write can return HTTP 200 with ``operation_status=FAILED``; + the dual-layer HTTP/business check in ``raise_for_status`` does not see + it because the failure lives inside ``output``. In raising mode this + converts it to the matching catalog error; in compat mode the operation + is returned untouched for the caller to inspect. + """ + if operation.operation_status == FAILED and client.raise_on_error: + raise error_from_business_code( + message=( + operation.error_message + or f"capacity operation {operation.operation_id} failed" + ), + code=operation.error_code, + body=operation.model_dump(exclude={"headers"}), + headers=operation.headers, + ) + return operation + + +class CapacityInstances: + """Capacity-instance subresource for one ModelCode (sync). + + Mounted as ``client.deployments.capacity_instances``. Every method takes + the ``deployed_model`` (ModelCode) first; instance writes are scoped to + it and return a :class:`CapacityOperation` to poll. + """ + + def __init__(self, client) -> None: + self._client = client + + def _path(self, deployed_model: str) -> str: + model = _path_id(deployed_model, "deployed_model") + return f"{_BASE_PATH}/{model}/capacity-instances" + + @overload + def create( + self, + deployed_model: str, + *, + billing_method: str, + ptu_capacity: Any, + pre_paid_info: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityOperation: + ... + + @overload + def create( + self, + deployed_model: str, + *, + billing_method: str, + ptu_capacity: Any, + pre_paid_info: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def create( + self, + deployed_model: str, + *, + billing_method: str, + ptu_capacity: Any, + pre_paid_info: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityOperation, "APIResponse"]: + """Buy an additional capacity instance (stacked purchase). + + ``billing_method`` is case-sensitive ``PRE_PAY`` / ``POST_PAY``; a + ModelCode may hold only one undeleted post-paid instance. Defaults + to ``max_retries=0`` and carries an idempotency key. Returns the + :class:`CapacityOperation` to poll (HTTP 200 is not success). + """ + body = _instance_create_body( + billing_method, + ptu_capacity, + pre_paid_info, + ) + resp = self._client.transport.request_api( + "POST", + self._path(deployed_model), + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + _idempotency_headers(extra_headers), + extra_query, + extra_body, + max_retries=_purchase_retries(max_retries), + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + operation = with_headers( + _parse_operation( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return _check_operation(self._client, operation) + + @overload + def list( + self, + deployed_model: str, + *, + page_no: int = 1, + page_size: int = 20, + include_deleted: bool = True, + statuses: Optional[str] = None, + charge_types: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityInstanceList: + ... + + @overload + def list( + self, + deployed_model: str, + *, + page_no: int = 1, + page_size: int = 20, + include_deleted: bool = True, + statuses: Optional[str] = None, + charge_types: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + deployed_model: str, + *, + page_no: int = 1, + page_size: int = 20, + include_deleted: bool = True, + statuses: Optional[str] = None, + charge_types: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityInstanceList, "APIResponse"]: + """List capacity instances of a ModelCode, one page at a time. + + ``statuses`` / ``charge_types`` are comma-separated filters (e.g. + ``"RUNNING,STOPPED"``, ``"pre_paid,post_paid"``). ``include_deleted`` + defaults to True so released instances stay visible. Pagination is + camelCase on the wire; see :class:`CapacityInstanceList`. + """ + params: Dict[str, Any] = { + "page_no": page_no, + "page_size": page_size, + "include_deleted": include_deleted, + } + if statuses is not None: + params["statuses"] = statuses + if charge_types is not None: + params["charge_types"] = charge_types + resp = self._client.transport.request_api( + "GET", + self._path(deployed_model), + params=params, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_instance_list( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + def get( + self, + deployed_model: str, + instance_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityInstance: + ... + + @overload + def get( + self, + deployed_model: str, + instance_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def get( + self, + deployed_model: str, + instance_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityInstance, "APIResponse"]: + """Fetch one capacity instance (deleted instances stay queryable). + + The ModelCode and instance id must match; a post-paid repurchase + reuses the same instance id. + """ + instance_id = _path_id(instance_id, "instance_id") + resp = self._client.transport.request_api( + "GET", + f"{self._path(deployed_model)}/{instance_id}", + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_instance( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + def scale( + self, + deployed_model: str, + instance_id: str, + *, + ptu_capacity: Any, + order_type: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityOperation: + ... + + @overload + def scale( + self, + deployed_model: str, + instance_id: str, + *, + ptu_capacity: Any, + order_type: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def scale( + self, + deployed_model: str, + instance_id: str, + *, + ptu_capacity: Any, + order_type: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityOperation, "APIResponse"]: + """Resize one instance to an ABSOLUTE ``ptu_capacity``. + + The instance id comes from the path (no body id). Check + ``can_scale`` first; an 8-hour trial instance cannot scale. + Defaults to ``max_retries=0`` with an idempotency key. + """ + instance_id = _path_id(instance_id, "instance_id") + body = _instance_scale_body(ptu_capacity, order_type) + resp = self._client.transport.request_api( + "PUT", + f"{self._path(deployed_model)}/{instance_id}/scale", + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + _idempotency_headers(extra_headers), + extra_query, + extra_body, + max_retries=_purchase_retries(max_retries), + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + operation = with_headers( + _parse_operation( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return _check_operation(self._client, operation) + + @overload + def renew( + self, + deployed_model: str, + instance_id: str, + *, + pre_paid_info: Any, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityOperation: + ... + + @overload + def renew( + self, + deployed_model: str, + instance_id: str, + *, + pre_paid_info: Any, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def renew( + self, + deployed_model: str, + instance_id: str, + *, + pre_paid_info: Any, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityOperation, "APIResponse"]: + """Renew one pre-paid instance (no ``order_type`` on renew). + + Changing ``ptu_capacity`` requires ``is_change=True``. Check + ``can_renew`` first; an 8-hour trial instance cannot renew. + Defaults to ``max_retries=0`` with an idempotency key. + """ + instance_id = _path_id(instance_id, "instance_id") + body = _renew_body(pre_paid_info, is_change, ptu_capacity) + resp = self._client.transport.request_api( + "PUT", + f"{self._path(deployed_model)}/{instance_id}/renew", + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + _idempotency_headers(extra_headers), + extra_query, + extra_body, + max_retries=_purchase_retries(max_retries), + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + operation = with_headers( + _parse_operation( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return _check_operation(self._client, operation) + + @overload + def delete( + self, + deployed_model: str, + instance_id: str, + *, + reason: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityOperation: + ... + + @overload + def delete( + self, + deployed_model: str, + instance_id: str, + *, + reason: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def delete( + self, + deployed_model: str, + instance_id: str, + *, + reason: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityOperation, "APIResponse"]: + """Release one instance (queued asynchronously, no JSON body). + + A post-paid release marks the instance ``deleted=True`` / STOPPED; + an effective pre-paid instance must be unsubscribed first + (PREPAID_UNSUBSCRIBE_REQUIRED). Defaults to ``max_retries=0`` with + an idempotency key. ``reason`` is sent as a query parameter. + """ + instance_id = _path_id(instance_id, "instance_id") + params: Dict[str, Any] = {} + if reason is not None: + params["reason"] = reason + resp = self._client.transport.request_api( + "DELETE", + f"{self._path(deployed_model)}/{instance_id}", + params=params or None, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + _idempotency_headers(extra_headers), + extra_query, + extra_body, + max_retries=_purchase_retries(max_retries), + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + operation = with_headers( + _parse_operation( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return _check_operation(self._client, operation) + + +class CapacityOperations: + """Capacity-operation polling subresource for one ModelCode (sync). + + Mounted as ``client.deployments.capacity_operations``. ``get`` reads one + operation; ``wait`` polls with exponential backoff until terminal. + """ + + def __init__(self, client) -> None: + self._client = client + + def _path(self, deployed_model: str, operation_id: str) -> str: + model = _path_id(deployed_model, "deployed_model") + operation = _path_id(operation_id, "operation_id") + return f"{_BASE_PATH}/{model}/capacity-operations/{operation}" + + @overload + def get( + self, + deployed_model: str, + operation_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityOperation: + ... + + @overload + def get( + self, + deployed_model: str, + operation_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def get( + self, + deployed_model: str, + operation_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityOperation, "APIResponse"]: + """Read one capacity operation by the id a write returned. + + Use the ``operation_id`` from the write response, not a guessed + number: a nonexistent numeric id answers 404 + CAPACITY_OPERATION_NOT_FOUND. A terminal FAILED operation raises in + raising mode (compat mode returns it for inspection). + """ + resp = self._client.transport.request_api( + "GET", + self._path(deployed_model, operation_id), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + operation = with_headers( + _parse_operation( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return _check_operation(self._client, operation) + + def wait( + self, + deployed_model: str, + operation_id: str, + *, + poll_interval: float = DEFAULT_POLL_INTERVAL, + max_interval: float = DEFAULT_MAX_INTERVAL, + timeout: float = DEFAULT_WAIT_TIMEOUT, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + _sleep: Optional[Callable[[float], Any]] = None, + ) -> CapacityOperation: + """Poll with exponential backoff until the operation is terminal. + + Mirrors ``jobs.wait``: a terminal FAILED operation raises in raising + mode (via ``get``); with ``raise_on_error=False`` it comes back as + the :class:`CapacityOperation` envelope -- check ``operation_status`` + / ``failed``. ``_sleep`` is a test seam replacing the pause between + polls. After a terminal result, refresh the instance/deployment to + read the new effective state. + """ + sleep_fn = _sleep or time.sleep + deadline = time.monotonic() + timeout + current = self.get( + deployed_model, + operation_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + interval = poll_interval + while not current.finished: + if current.is_error: + return current + remaining = deadline - time.monotonic() + if remaining <= 0: + raise DashScopeError( + f"timed out after {timeout}s waiting for capacity " + f"operation {operation_id}", + ) + sleep_fn(min(interval, remaining)) + interval = min(interval * 2, max_interval) + current = self.get( + deployed_model, + operation_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + return current + + +class AsyncCapacityInstances: + """Async twin of :class:`CapacityInstances`.""" + + def __init__(self, client) -> None: + self._client = client + + def _path(self, deployed_model: str) -> str: + model = _path_id(deployed_model, "deployed_model") + return f"{_BASE_PATH}/{model}/capacity-instances" + + @overload + async def create( + self, + deployed_model: str, + *, + billing_method: str, + ptu_capacity: Any, + pre_paid_info: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityOperation: + ... + + @overload + async def create( + self, + deployed_model: str, + *, + billing_method: str, + ptu_capacity: Any, + pre_paid_info: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def create( + self, + deployed_model: str, + *, + billing_method: str, + ptu_capacity: Any, + pre_paid_info: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityOperation, "APIResponse"]: + """Buy an additional capacity instance (stacked purchase).""" + body = _instance_create_body( + billing_method, + ptu_capacity, + pre_paid_info, + ) + resp = await self._client.transport.request_api( + "POST", + self._path(deployed_model), + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + _idempotency_headers(extra_headers), + extra_query, + extra_body, + max_retries=_purchase_retries(max_retries), + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + operation = with_headers( + _parse_operation( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return _check_operation(self._client, operation) + + @overload + async def list( + self, + deployed_model: str, + *, + page_no: int = 1, + page_size: int = 20, + include_deleted: bool = True, + statuses: Optional[str] = None, + charge_types: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityInstanceList: + ... + + @overload + async def list( + self, + deployed_model: str, + *, + page_no: int = 1, + page_size: int = 20, + include_deleted: bool = True, + statuses: Optional[str] = None, + charge_types: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + deployed_model: str, + *, + page_no: int = 1, + page_size: int = 20, + include_deleted: bool = True, + statuses: Optional[str] = None, + charge_types: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityInstanceList, "APIResponse"]: + """List capacity instances of a ModelCode, one page at a time.""" + params: Dict[str, Any] = { + "page_no": page_no, + "page_size": page_size, + "include_deleted": include_deleted, + } + if statuses is not None: + params["statuses"] = statuses + if charge_types is not None: + params["charge_types"] = charge_types + resp = await self._client.transport.request_api( + "GET", + self._path(deployed_model), + params=params, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_instance_list( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + async def get( + self, + deployed_model: str, + instance_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityInstance: + ... + + @overload + async def get( + self, + deployed_model: str, + instance_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def get( + self, + deployed_model: str, + instance_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityInstance, "APIResponse"]: + """Fetch one capacity instance (deleted instances stay queryable).""" + instance_id = _path_id(instance_id, "instance_id") + resp = await self._client.transport.request_api( + "GET", + f"{self._path(deployed_model)}/{instance_id}", + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_instance( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + async def scale( + self, + deployed_model: str, + instance_id: str, + *, + ptu_capacity: Any, + order_type: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityOperation: + ... + + @overload + async def scale( + self, + deployed_model: str, + instance_id: str, + *, + ptu_capacity: Any, + order_type: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def scale( + self, + deployed_model: str, + instance_id: str, + *, + ptu_capacity: Any, + order_type: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityOperation, "APIResponse"]: + """Resize one instance to an ABSOLUTE ``ptu_capacity``.""" + instance_id = _path_id(instance_id, "instance_id") + body = _instance_scale_body(ptu_capacity, order_type) + resp = await self._client.transport.request_api( + "PUT", + f"{self._path(deployed_model)}/{instance_id}/scale", + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + _idempotency_headers(extra_headers), + extra_query, + extra_body, + max_retries=_purchase_retries(max_retries), + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + operation = with_headers( + _parse_operation( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return _check_operation(self._client, operation) + + @overload + async def renew( + self, + deployed_model: str, + instance_id: str, + *, + pre_paid_info: Any, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityOperation: + ... + + @overload + async def renew( + self, + deployed_model: str, + instance_id: str, + *, + pre_paid_info: Any, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def renew( + self, + deployed_model: str, + instance_id: str, + *, + pre_paid_info: Any, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityOperation, "APIResponse"]: + """Renew one pre-paid instance (no ``order_type`` on renew).""" + instance_id = _path_id(instance_id, "instance_id") + body = _renew_body(pre_paid_info, is_change, ptu_capacity) + resp = await self._client.transport.request_api( + "PUT", + f"{self._path(deployed_model)}/{instance_id}/renew", + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + _idempotency_headers(extra_headers), + extra_query, + extra_body, + max_retries=_purchase_retries(max_retries), + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + operation = with_headers( + _parse_operation( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return _check_operation(self._client, operation) + + @overload + async def delete( + self, + deployed_model: str, + instance_id: str, + *, + reason: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityOperation: + ... + + @overload + async def delete( + self, + deployed_model: str, + instance_id: str, + *, + reason: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def delete( + self, + deployed_model: str, + instance_id: str, + *, + reason: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityOperation, "APIResponse"]: + """Release one instance (queued asynchronously, no JSON body).""" + instance_id = _path_id(instance_id, "instance_id") + params: Dict[str, Any] = {} + if reason is not None: + params["reason"] = reason + resp = await self._client.transport.request_api( + "DELETE", + f"{self._path(deployed_model)}/{instance_id}", + params=params or None, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + _idempotency_headers(extra_headers), + extra_query, + extra_body, + max_retries=_purchase_retries(max_retries), + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + operation = with_headers( + _parse_operation( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return _check_operation(self._client, operation) + + +class AsyncCapacityOperations: + """Async twin of :class:`CapacityOperations`.""" + + def __init__(self, client) -> None: + self._client = client + + def _path(self, deployed_model: str, operation_id: str) -> str: + model = _path_id(deployed_model, "deployed_model") + operation = _path_id(operation_id, "operation_id") + return f"{_BASE_PATH}/{model}/capacity-operations/{operation}" + + @overload + async def get( + self, + deployed_model: str, + operation_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CapacityOperation: + ... + + @overload + async def get( + self, + deployed_model: str, + operation_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def get( + self, + deployed_model: str, + operation_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CapacityOperation, "APIResponse"]: + """Read one capacity operation by the id a write returned.""" + resp = await self._client.transport.request_api( + "GET", + self._path(deployed_model, operation_id), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + operation = with_headers( + _parse_operation( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return _check_operation(self._client, operation) + + async def wait( + self, + deployed_model: str, + operation_id: str, + *, + poll_interval: float = DEFAULT_POLL_INTERVAL, + max_interval: float = DEFAULT_MAX_INTERVAL, + timeout: float = DEFAULT_WAIT_TIMEOUT, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + _sleep: Optional[Callable[[float], Any]] = None, + ) -> CapacityOperation: + """Poll with exponential backoff until the operation is terminal.""" + sleep_fn = _sleep or asyncio.sleep + deadline = time.monotonic() + timeout + current = await self.get( + deployed_model, + operation_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + interval = poll_interval + while not current.finished: + if current.is_error: + return current + remaining = deadline - time.monotonic() + if remaining <= 0: + raise DashScopeError( + f"timed out after {timeout}s waiting for capacity " + f"operation {operation_id}", + ) + await sleep_fn(min(interval, remaining)) + interval = min(interval * 2, max_interval) + current = await self.get( + deployed_model, + operation_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + return current diff --git a/dashscope/resources/batch_chat.py b/dashscope/resources/batch_chat.py new file mode 100644 index 00000000..a3ea1915 --- /dev/null +++ b/dashscope/resources/batch_chat.py @@ -0,0 +1,578 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""client.batch_chat -- Batch Chat (queued, synchronous, discounted). + +Batch Chat keeps the real-time Chat API's synchronous call shape but +routes to a dedicated batch gateway: the request queues, the connection +is held, and the complete result returns at once. It is OpenAI-compatible +(``POST {batch}/compatible-mode/v1/chat/completions``) regardless of the +client's chat ``protocol`` setting, so this resource always builds and +parses through the OpenAI adapter and derives its own batch base URL -- +like ``client.decision``, the chat ``protocol`` cannot move it. + +Single request only; for many requests in one file use ``client.batches`` +(the asynchronous file-input Batch Job). Non-streaming: the server returns +the full completion once the request is scheduled, so there is no +``stream`` option here (use ``client.chat`` for streaming). + +Billing/timeout semantics differ from real-time Chat: only successfully +executed requests are billed (a request that times out unscheduled is not +billed); the catalog price matches real-time but Batch Chat carries a +limited-time 50% discount; it is an independent billing item that does not +support prepaid plans, new-user free quota or context cache. The server +holds the connection up to 3600s; a custom ``timeout`` must be within +60..3600s and defaults to 3600s. The transport cannot tell whether a +dropped/timed-out request was already scheduled (and billed), so +``create`` defaults to ``max_retries=0`` rather than the client's +real-time Chat retry default. + +Contract: +https://help.aliyun.com/zh/model-studio/openai-compatible-batch-chat +""" + +from __future__ import annotations + +from typing import ( + TYPE_CHECKING, + Any, + Dict, + List, + Mapping, + Optional, + Union, + overload, +) + +from typing_extensions import Literal + +from dashscope._config import Config +from dashscope.errors import response_error +from dashscope.protocols import get_protocol +from dashscope.protocols.openai import OpenAIProtocol +from dashscope.transport._options import request_options +from dashscope.types._parse import parse_model +from dashscope.types.common import with_headers +from dashscope.types.completions import ChatCompletion +from dashscope.types.messages import MessageInput, normalize_messages + +if TYPE_CHECKING: + from dashscope.transport._response import APIResponse + +_PATH = "/chat/completions" +# Functional-area tag for x-dashscope-sdk-client (emitted as "batch_chat2"). +MODULE = "batch_chat" + +# The documented Batch Chat gateway. Batch Chat is served on this shared +# batch host (currently Beijing); the official contract documents no +# workspace/international batch host, so anything else must be supplied as +# an explicit base_url rather than invented here. +BATCH_GATEWAY_BASE = "https://batch.dashscope.aliyuncs.com/compatible-mode/v1" + +# Server holds the connection up to 3600s; custom timeout range 60..3600s. +BATCH_DEFAULT_TIMEOUT = 3600.0 +BATCH_MIN_TIMEOUT = 60.0 +BATCH_MAX_TIMEOUT = 3600.0 + +# Batch Chat is always OpenAI-compatible, independent of the client's chat +# protocol. Response parsing is stateless, so one shared instance is safe +# there (strictness is passed per call). Request building is resolved per +# client instead, so protocol_options such as ``strict`` are honored. +_PROTOCOL = OpenAIProtocol() + +__all__ = [ + "AsyncBatchChat", + "AsyncBatchChatCompletions", + "BatchChat", + "BatchChatCompletions", +] + + +def _batch_base_url(config: Config) -> str: + # An explicit base_url stays the service root (escape hatch for a + # custom/workspace batch endpoint); otherwise the documented batch + # gateway. The chat protocol setting must not move it. + if config.configured_base_url is not None: + return config.configured_base_url + return BATCH_GATEWAY_BASE + + +def _resolve_timeout(timeout: Optional[float]) -> float: + if timeout is None: + return BATCH_DEFAULT_TIMEOUT + if not BATCH_MIN_TIMEOUT <= timeout <= BATCH_MAX_TIMEOUT: + raise ValueError( + f"batch_chat timeout must be between {BATCH_MIN_TIMEOUT:.0f} " + f"and {BATCH_MAX_TIMEOUT:.0f} seconds (got {timeout!r}); the " + f"server holds the connection up to " + f"{BATCH_MAX_TIMEOUT:.0f}s", + ) + return float(timeout) + + +def _messages( + messages: Union[str, List[MessageInput]], +) -> List[Dict[str, Any]]: + normalized = normalize_messages(messages) + if not normalized: + raise ValueError("messages must not be empty") + return [m.model_dump(exclude_none=True) for m in normalized] + + +def _build_body( + *, + protocol: OpenAIProtocol, + model: str, + messages: Union[str, List[MessageInput]], + tools: Optional[List[Dict[str, Any]]], + temperature: Optional[float], + top_p: Optional[float], + max_tokens: Optional[int], + stop: Union[str, List[str], None], + seed: Optional[int], + repetition_penalty: Optional[float], + presence_penalty: Optional[float], + enable_thinking: Optional[bool], + response_format: Optional[Dict[str, Any]], + top_k: Optional[int], + tool_choice: Union[str, Dict[str, Any], None], + n: Optional[int], + logprobs: Optional[bool], + top_logprobs: Optional[int], + thinking_budget: Optional[int], + enable_search: Optional[bool], + search_options: Optional[Dict[str, Any]], + parallel_tool_calls: Optional[bool], + parameters: Optional[Dict[str, Any]], +) -> Dict[str, Any]: + if not model or not model.strip(): + raise ValueError("model must be a non-empty string") + request = protocol.build_chat_request( + model=model, + messages=_messages(messages), + stream=False, + tools=tools, + temperature=temperature, + top_p=top_p, + max_tokens=max_tokens, + stop=stop, + seed=seed, + repetition_penalty=repetition_penalty, + presence_penalty=presence_penalty, + enable_thinking=enable_thinking, + response_format=response_format, + top_k=top_k, + tool_choice=tool_choice, + n=n, + logprobs=logprobs, + top_logprobs=top_logprobs, + thinking_budget=thinking_budget, + enable_search=enable_search, + search_options=search_options, + parallel_tool_calls=parallel_tool_calls, + extra_parameters=parameters, + ) + return request.body + + +def _checked(client, resp) -> ChatCompletion: + """Raise on failure, or fill the error envelope when not raising. + + Batch Chat is OpenAI-compatible, so a failure nests ``code`` / + ``message`` under ``error``; routing through ``response_error`` keeps + ``raise_on_error=False`` reporting it via ``is_error`` / ``code`` / + ``message`` instead of an empty success. + """ + http_resp = resp.http_response + error = response_error(http_resp) + if error is None: + return with_headers( + _PROTOCOL.parse_completion( + resp.json(), + strict_validation=client.config.strict_validation, + response=http_resp, + ), + http_resp, + ) + if client.raise_on_error: + raise error + return with_headers( + parse_model( + ChatCompletion, + { + "request_id": error.request_id, + "status_code": error.status_code, + "code": error.code, + "message": error.message, + "is_error": True, + "headers": dict(http_resp.headers), + }, + strict=client.config.strict_validation, + response=http_resp, + ), + http_resp, + ) + + +class BatchChatCompletions: + """Synchronous Batch Chat calls (``client.batch_chat.completions``).""" + + def __init__(self, client) -> None: + self._client = client + self._protocol = get_protocol( + "openai", + protocol_options=client._protocol_options, + ) + + @overload + def create( + self, + *, + model: str, + messages: Union[str, List[MessageInput]], + tools: Optional[List[Dict[str, Any]]] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_tokens: Optional[int] = None, + stop: Union[str, List[str], None] = None, + seed: Optional[int] = None, + repetition_penalty: Optional[float] = None, + presence_penalty: Optional[float] = None, + enable_thinking: Optional[bool] = None, + response_format: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + tool_choice: Union[str, Dict[str, Any], None] = None, + n: Optional[int] = None, + logprobs: Optional[bool] = None, + top_logprobs: Optional[int] = None, + thinking_budget: Optional[int] = None, + enable_search: Optional[bool] = None, + search_options: Optional[Dict[str, Any]] = None, + parallel_tool_calls: Optional[bool] = None, + parameters: Optional[Dict[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> ChatCompletion: + ... + + @overload + def create( + self, + *, + model: str, + messages: Union[str, List[MessageInput]], + tools: Optional[List[Dict[str, Any]]] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_tokens: Optional[int] = None, + stop: Union[str, List[str], None] = None, + seed: Optional[int] = None, + repetition_penalty: Optional[float] = None, + presence_penalty: Optional[float] = None, + enable_thinking: Optional[bool] = None, + response_format: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + tool_choice: Union[str, Dict[str, Any], None] = None, + n: Optional[int] = None, + logprobs: Optional[bool] = None, + top_logprobs: Optional[int] = None, + thinking_budget: Optional[int] = None, + enable_search: Optional[bool] = None, + search_options: Optional[Dict[str, Any]] = None, + parallel_tool_calls: Optional[bool] = None, + parameters: Optional[Dict[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def create( + self, + *, + model: str, + messages: Union[str, List[MessageInput]], + tools: Optional[List[Dict[str, Any]]] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_tokens: Optional[int] = None, + stop: Union[str, List[str], None] = None, + seed: Optional[int] = None, + repetition_penalty: Optional[float] = None, + presence_penalty: Optional[float] = None, + enable_thinking: Optional[bool] = None, + response_format: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + tool_choice: Union[str, Dict[str, Any], None] = None, + n: Optional[int] = None, + logprobs: Optional[bool] = None, + top_logprobs: Optional[int] = None, + thinking_budget: Optional[int] = None, + enable_search: Optional[bool] = None, + search_options: Optional[Dict[str, Any]] = None, + parallel_tool_calls: Optional[bool] = None, + parameters: Optional[Dict[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ChatCompletion, "APIResponse"]: + """Run one Batch Chat completion (queued, synchronous, discounted). + + Same parameters as ``client.chat.completions.create`` minus + streaming: the request queues on the batch gateway and the full + :class:`~dashscope.types.completions.ChatCompletion` returns once + scheduled. ``timeout`` defaults to 3600s and must be within + 60..3600s (the server's max connection hold). + + Only successful requests are billed; a request that times out + unscheduled is not billed. The transport cannot tell whether a + dropped request was already scheduled, so this defaults to + ``max_retries=0`` (no automatic retry) -- unlike real-time Chat. + Passing ``max_retries`` explicitly re-enables retry and the + caller owns the duplicate-billing risk. Batch Chat is an + independent billing item at a limited-time 50% discount, with no + prepaid plans, new-user free quota or context cache. + + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + body = _build_body( + protocol=self._protocol, + model=model, + messages=messages, + tools=tools, + temperature=temperature, + top_p=top_p, + max_tokens=max_tokens, + stop=stop, + seed=seed, + repetition_penalty=repetition_penalty, + presence_penalty=presence_penalty, + enable_thinking=enable_thinking, + response_format=response_format, + top_k=top_k, + tool_choice=tool_choice, + n=n, + logprobs=logprobs, + top_logprobs=top_logprobs, + thinking_budget=thinking_budget, + enable_search=enable_search, + search_options=search_options, + parallel_tool_calls=parallel_tool_calls, + parameters=parameters, + ) + resp = self._client.transport.request_api( + "POST", + _PATH, + json=body, + base_url=_batch_base_url(self._client.config), + sdk_module=MODULE, + timeout=_resolve_timeout(timeout), + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=0 if max_retries is None else max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp) + + +class AsyncBatchChatCompletions: + """Asynchronous Batch Chat calls (``client.batch_chat.completions``).""" + + def __init__(self, client) -> None: + self._client = client + self._protocol = get_protocol( + "openai", + protocol_options=client._protocol_options, + ) + + @overload + async def create( + self, + *, + model: str, + messages: Union[str, List[MessageInput]], + tools: Optional[List[Dict[str, Any]]] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_tokens: Optional[int] = None, + stop: Union[str, List[str], None] = None, + seed: Optional[int] = None, + repetition_penalty: Optional[float] = None, + presence_penalty: Optional[float] = None, + enable_thinking: Optional[bool] = None, + response_format: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + tool_choice: Union[str, Dict[str, Any], None] = None, + n: Optional[int] = None, + logprobs: Optional[bool] = None, + top_logprobs: Optional[int] = None, + thinking_budget: Optional[int] = None, + enable_search: Optional[bool] = None, + search_options: Optional[Dict[str, Any]] = None, + parallel_tool_calls: Optional[bool] = None, + parameters: Optional[Dict[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> ChatCompletion: + ... + + @overload + async def create( + self, + *, + model: str, + messages: Union[str, List[MessageInput]], + tools: Optional[List[Dict[str, Any]]] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_tokens: Optional[int] = None, + stop: Union[str, List[str], None] = None, + seed: Optional[int] = None, + repetition_penalty: Optional[float] = None, + presence_penalty: Optional[float] = None, + enable_thinking: Optional[bool] = None, + response_format: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + tool_choice: Union[str, Dict[str, Any], None] = None, + n: Optional[int] = None, + logprobs: Optional[bool] = None, + top_logprobs: Optional[int] = None, + thinking_budget: Optional[int] = None, + enable_search: Optional[bool] = None, + search_options: Optional[Dict[str, Any]] = None, + parallel_tool_calls: Optional[bool] = None, + parameters: Optional[Dict[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def create( + self, + *, + model: str, + messages: Union[str, List[MessageInput]], + tools: Optional[List[Dict[str, Any]]] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_tokens: Optional[int] = None, + stop: Union[str, List[str], None] = None, + seed: Optional[int] = None, + repetition_penalty: Optional[float] = None, + presence_penalty: Optional[float] = None, + enable_thinking: Optional[bool] = None, + response_format: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + tool_choice: Union[str, Dict[str, Any], None] = None, + n: Optional[int] = None, + logprobs: Optional[bool] = None, + top_logprobs: Optional[int] = None, + thinking_budget: Optional[int] = None, + enable_search: Optional[bool] = None, + search_options: Optional[Dict[str, Any]] = None, + parallel_tool_calls: Optional[bool] = None, + parameters: Optional[Dict[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ChatCompletion, "APIResponse"]: + """Async twin of :meth:`BatchChatCompletions.create`.""" + body = _build_body( + protocol=self._protocol, + model=model, + messages=messages, + tools=tools, + temperature=temperature, + top_p=top_p, + max_tokens=max_tokens, + stop=stop, + seed=seed, + repetition_penalty=repetition_penalty, + presence_penalty=presence_penalty, + enable_thinking=enable_thinking, + response_format=response_format, + top_k=top_k, + tool_choice=tool_choice, + n=n, + logprobs=logprobs, + top_logprobs=top_logprobs, + thinking_budget=thinking_budget, + enable_search=enable_search, + search_options=search_options, + parallel_tool_calls=parallel_tool_calls, + parameters=parameters, + ) + resp = await self._client.transport.request_api( + "POST", + _PATH, + json=body, + base_url=_batch_base_url(self._client.config), + sdk_module=MODULE, + timeout=_resolve_timeout(timeout), + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=0 if max_retries is None else max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp) + + +class BatchChat: + """Batch Chat resource (``client.batch_chat``).""" + + def __init__(self, client) -> None: + self.completions = BatchChatCompletions(client) + + +class AsyncBatchChat: + """Async Batch Chat resource (``client.batch_chat``).""" + + def __init__(self, client) -> None: + self.completions = AsyncBatchChatCompletions(client) diff --git a/dashscope/resources/batches.py b/dashscope/resources/batches.py new file mode 100644 index 00000000..7f44db81 --- /dev/null +++ b/dashscope/resources/batches.py @@ -0,0 +1,2761 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""client.batches -- OpenAI-compatible Batch workflow. + +Two planes share the ``Batches`` resource: + +* ``client.batches.files`` (B1) -- the compatible-mode File sub-resource: + ``upload`` (purpose=batch), ``content`` download, cursor-paginated + ``list``, ``get`` and ``delete``. +* ``client.batches`` (B2) -- the batch job plane: ``create`` / ``get`` / + ``list`` / ``cancel`` / ``wait`` plus a pre-upload ``validate_input`` + row-level JSONL check. +* ``client.batches.download_output`` / ``download_error`` (B3) -- resolve a + batch's ``output_file_id`` / ``error_file_id`` and download the results + JSONL through ``files.content`` (``None`` when the file is absent). An + uploaded input file id is reusable across creates (no re-upload needed); + discover existing batch files with ``files.list(purpose="batch")``. + +Wire: every call sits under ``{gateway}/compatible-mode/v1`` -- the +OpenAI-compatible File/Batch API, NOT the native ``/api/v1/files`` that +``client.files`` uses for fine-tune. The two differ in multipart field name +(``file`` vs ``files``), response shape (a flat OpenAI object vs +``data.uploaded_files``) and pagination (an ``after``/``has_more`` cursor vs +``page_no``/``total``). Like ``client.decision``, this resource derives its +own base URL via ``compatible_mode_base_url`` so the chat ``protocol`` +setting cannot move it. + +``create`` has no server-side idempotency key on the wire, so it defaults +to ``max_retries=0`` (no automatic retry) to avoid creating duplicate +batches; a caller who passes ``max_retries`` explicitly owns that risk. + +Contract: +https://help.aliyun.com/zh/model-studio/openai-file-interface and +https://help.aliyun.com/zh/model-studio/batch-interfaces-compatible-with-openai +""" + +from __future__ import annotations + +import asyncio +import inspect +import json +import os +import re +import time +from pathlib import Path +from typing import ( + TYPE_CHECKING, + Any, + AsyncIterator, + Awaitable, + Callable, + Dict, + Iterator, + List, + Literal, + Mapping, + Optional, + Sequence, + Set, + Tuple, + TypeVar, + Union, + overload, +) +from urllib.parse import quote + +from pydantic import AliasChoices, BaseModel, ConfigDict, Field, PrivateAttr + +from dashscope._config import Config, compatible_mode_base_url +from dashscope.errors import ( + DashScopeError, + error_from_business_code, + response_error, +) +from dashscope.resources._jobs import ( + DEFAULT_MAX_INTERVAL, + DEFAULT_POLL_INTERVAL, + DEFAULT_WAIT_TIMEOUT, +) +from dashscope.resources.files import _io_error, _is_valid_jsonl +from dashscope.transport._options import request_options +from dashscope.types._parse import parse_model +from dashscope.types.common import ( + ResponseBase, + response_envelope, + with_headers, +) + +if TYPE_CHECKING: + import httpx + + from dashscope.transport._response import APIResponse + +_BASE_PATH = "/files" +_BATCH_PATH = "/batches" + +MODULE = "batches" + +# The File list endpoint caps ``limit`` at 2000; the Batch list endpoint +# caps it at 100 (default 20). Different wires -- do not share the bound. +_MAX_LIMIT = 2000 +_BATCH_MAX_LIMIT = 100 +_MAX_INPUT_FILE_IDS = 20 +_MAX_BATCH_ROWS = 50000 + +# completion_window: integer + h/d, 24h..336h (official Batch contract). +_WINDOW_RE = re.compile(r"^(\d+)([hd])$") +_MIN_WINDOW_HOURS = 24 +_MAX_WINDOW_HOURS = 336 + +# Batch lifecycle statuses (lowercase on the wire, unlike the uppercase +# native Job statuses in ``_jobs``). +VALIDATING = "validating" +IN_PROGRESS = "in_progress" +FINALIZING = "finalizing" +COMPLETED = "completed" +FAILED = "failed" +EXPIRED = "expired" +CANCELLING = "cancelling" +CANCELLED = "cancelled" + +_BATCH_TERMINAL = frozenset({COMPLETED, FAILED, EXPIRED, CANCELLED}) + +__all__ = [ + "AsyncBatchFiles", + "AsyncBatches", + "Batch", + "BatchErrorItem", + "BatchErrors", + "BatchFile", + "BatchFileList", + "BatchFiles", + "BatchList", + "Batches", + "CANCELLED", + "CANCELLING", + "COMPLETED", + "EXPIRED", + "FAILED", + "FINALIZING", + "FileContent", + "FileDeletion", + "IN_PROGRESS", + "RequestCounts", + "VALIDATING", +] + + +class BatchFile(ResponseBase): + """One file in the OpenAI-compatible store. + + The flat OpenAI shape comes back from ``upload`` / ``get`` and nested in + ``BatchFileList.data``. ``id`` is the wire name (``file-batch-xxx`` / + ``file-fe-xxx``); :attr:`file_id` is a convenience alias so callers can + pass the same value to ``content`` / ``get`` / ``delete``. + """ + + id: Optional[str] = Field( + None, + validation_alias=AliasChoices("id", "file_id"), + ) + object: Optional[str] = None + bytes: Optional[int] = None + # Unix seconds (Integer on the wire), not a formatted string. + created_at: Optional[int] = None + filename: Optional[str] = None + purpose: Optional[str] = None + status: Optional[str] = None + status_details: Optional[Any] = None + + @property + def file_id(self) -> Optional[str]: + return self.id + + +class RequestCounts(BaseModel): + """Per-status request tallies on a batch (``request_counts``).""" + + model_config = ConfigDict(extra="allow") + + total: int = 0 + completed: int = 0 + failed: int = 0 + + +class BatchErrorItem(BaseModel): + """One row-level error in a batch's ``errors.data`` (OpenAI shape).""" + + model_config = ConfigDict(extra="allow") + + code: Optional[str] = None + message: Optional[str] = None + param: Optional[str] = None + line: Optional[int] = None + + +class BatchErrors(BaseModel): + """The ``errors`` object on a failed batch (``{object, data}``).""" + + model_config = ConfigDict(extra="allow") + + object: Optional[str] = None + data: List[BatchErrorItem] = [] + + +class Batch(ResponseBase): + """One batch job (``client.batches`` create/get/list/cancel/wait). + + The flat OpenAI Batch object: ``status`` drives the lifecycle + (validating -> in_progress -> finalizing -> completed, or + failed/expired/cancelling/cancelled). Timestamps are Unix seconds + (``null`` until the stage is reached). :attr:`finished` is true at any + terminal status; :attr:`succeeded` only at ``completed``. + """ + + id: Optional[str] = None + object: Optional[str] = None + endpoint: Optional[str] = None + errors: Optional[BatchErrors] = None + input_file_id: Optional[str] = None + completion_window: Optional[str] = None + status: Optional[str] = None + output_file_id: Optional[str] = None + error_file_id: Optional[str] = None + created_at: Optional[int] = None + in_progress_at: Optional[int] = None + expires_at: Optional[int] = None + finalizing_at: Optional[int] = None + completed_at: Optional[int] = None + failed_at: Optional[int] = None + expired_at: Optional[int] = None + cancelling_at: Optional[int] = None + cancelled_at: Optional[int] = None + request_counts: Optional[RequestCounts] = None + metadata: Optional[Dict[str, Any]] = None + + @property + def batch_id(self) -> Optional[str]: + return self.id + + @property + def finished(self) -> bool: + return self.status in _BATCH_TERMINAL + + @property + def succeeded(self) -> bool: + return self.status == COMPLETED + + +_PageT = TypeVar("_PageT", bound="_CursorPage") + + +class _CursorPage(ResponseBase): + """Shared cursor-page traversal for compatible-mode list endpoints. + + The compatible-mode wire paginates by cursor (``has_more`` + ``after`` + = the last id), not by ``page_no``/``total`` like + :class:`~dashscope.types.pagination.BasePage`. This base holds the + traversal ergonomics (``iter_pages`` / ``next_page`` / async twins); + subclasses supply the typed ``data`` list, ``items`` and ``_next_cursor``. + The ``self: _PageT`` annotations keep ``next_page`` returning the + concrete subclass type. + """ + + data: List[Any] = [] + has_more: bool = False + + # Fetches the next page as ``(after_cursor) -> page`` (a page or an + # awaitable of one). A PrivateAttr so it stays out of ``model_dump()``. + _fetch_next: Optional[Callable[[str], Any]] = PrivateAttr(default=None) + + @property + def items(self) -> List[Any]: + return self.data + + def bind_pagination( + self: _PageT, + callback: Optional[Callable[[str], Any]], + ) -> _PageT: + self._fetch_next = callback + return self + + @property + def _next_cursor(self) -> Optional[str]: + return self.data[-1].id if self.data else None + + def has_next_page(self) -> bool: + return ( + self.has_more + and self._fetch_next is not None + and self._next_cursor is not None + ) + + def next_page(self: _PageT) -> Optional[_PageT]: + if not self.has_next_page(): + return None + assert self._fetch_next is not None and self._next_cursor is not None + result = self._fetch_next(self._next_cursor) + if inspect.isawaitable(result): + close = getattr(result, "close", None) + if callable(close): + close() + raise TypeError( + "this page was fetched through AsyncClient, so advancing it " + "is a coroutine; use next_page_async() or iter_pages_async() " + "instead of the synchronous traversal", + ) + return result + + async def next_page_async(self: _PageT) -> Optional[_PageT]: + if not self.has_next_page(): + return None + assert self._fetch_next is not None and self._next_cursor is not None + result = self._fetch_next(self._next_cursor) + if inspect.isawaitable(result): + result = await result + return result + + def __iter__(self) -> Iterator[Any]: + return iter(self.data) + + def __aiter__(self) -> AsyncIterator[Any]: + async def _gen() -> AsyncIterator[Any]: + for item in self.data: + yield item + + return _gen() + + def iter_pages(self: _PageT) -> Iterator[_PageT]: + page: Optional[_PageT] = self + while page is not None: + yield page + page = page.next_page() + + async def iter_pages_async(self: _PageT) -> AsyncIterator[_PageT]: + page: Optional[_PageT] = self + while page is not None: + yield page + page = await page.next_page_async() + + +class BatchFileList(_CursorPage): + """One cursor page of files, from ``files.list``. + + ``has_more`` says whether another page exists and ``after`` (the last + ``id`` on this page) fetches it; see :class:`_CursorPage` for traversal. + """ + + data: List[BatchFile] = [] + object: Optional[str] = None + + @property + def items(self) -> List[BatchFile]: + return self.data + + def __iter__(self) -> Iterator[BatchFile]: + return iter(self.data) + + def __aiter__(self) -> AsyncIterator[BatchFile]: + async def _gen() -> AsyncIterator[BatchFile]: + for item in self.data: + yield item + + return _gen() + + +class BatchList(_CursorPage): + """One cursor page of batch jobs, from ``batches.list``. + + Like :class:`BatchFileList` but the wire also carries ``first_id`` / + ``last_id``; the next-page cursor prefers ``last_id`` (the doc's + ``after`` = "last task id of the previous page"). + """ + + data: List[Batch] = [] + object: Optional[str] = None + first_id: Optional[str] = None + last_id: Optional[str] = None + + @property + def items(self) -> List[Batch]: + return self.data + + @property + def _next_cursor(self) -> Optional[str]: + if self.last_id: + return self.last_id + return self.data[-1].id if self.data else None + + def __iter__(self) -> Iterator[Batch]: + return iter(self.data) + + def __aiter__(self) -> AsyncIterator[Batch]: + async def _gen() -> AsyncIterator[Batch]: + for item in self.data: + yield item + + return _gen() + + +class FileDeletion(ResponseBase): + """Result of ``files.delete`` (``{object, deleted, id}``).""" + + id: Optional[str] = None + object: Optional[str] = None + deleted: bool = False + + +class FileContent(bytes): + """Binary content of a downloaded file (``files.content``). + + A ``bytes`` subclass so it drops into any code expecting raw bytes, with + a :attr:`text` view (UTF-8) for the JSONL batch results and a + :meth:`write_to_file` helper. ``status_code`` / :attr:`is_error` let a + ``raise_on_error=False`` caller inspect a failed download, whose body is + the gateway's error bytes rather than a parsed envelope. + """ + + request_id: Optional[str] + headers: Dict[str, str] + status_code: Optional[int] + + def __new__( + cls, + content: bytes = b"", + *, + request_id: Optional[str] = None, + headers: Optional[Mapping[str, str]] = None, + status_code: Optional[int] = None, + ) -> "FileContent": + obj = super().__new__(cls, content) + obj.request_id = request_id + obj.headers = dict(headers or {}) + obj.status_code = status_code + return obj + + @property + def text(self) -> str: + return self.decode("utf-8") + + @property + def is_error(self) -> bool: + return self.status_code is not None and self.status_code >= 400 + + def write_to_file(self, path: Union[str, "os.PathLike[str]"]) -> Path: + dest = Path(os.fspath(path)) + dest.parent.mkdir(parents=True, exist_ok=True) + dest.write_bytes(self) + return dest + + +def _endpoint_base(config: Config) -> str: + # The compatible-mode File API sits under /compatible-mode/v1 on every + # gateway; the chat protocol setting must not move it. + return compatible_mode_base_url( + config.workspace, + config.region, + config.configured_base_url, + ) + + +def _require_file_id(file_id: str) -> str: + if not file_id or not file_id.strip(): + raise ValueError("file_id must be a non-empty string") + # Percent-encode so a '/', '?' or '#' inside the id cannot retarget + # the request to another path or query. + return quote(file_id, safe="") + + +def _validate_upload(file_path: str, purpose: str) -> None: + if not os.path.isfile(file_path): + raise _io_error(FileNotFoundError(f"file not found: {file_path}")) + # Batch input must be JSONL; file-extract accepts binary documents. + if purpose == "batch": + if not _is_valid_jsonl(file_path): + raise ValueError(f"file {file_path} is not in valid jsonl format") + # Same rule as validate_input: blank lines are tolerated, but an + # all-blank file carries no rows and must not pass the pre-check. + try: + with open(file_path, encoding="utf-8") as f: + if not any(line.strip() for line in f): + raise ValueError( + f"file {file_path} has no batch input rows", + ) + except OSError as exc: + raise _io_error(exc) from exc + + +def _upload_form(file_path: str, purpose: str): + try: + with open(file_path, "rb") as f: + # Bytes, not a live handle: transport retries must re-send the + # full body. + content = f.read() + except OSError as exc: + raise _io_error(exc) from exc + return {"purpose": purpose}, { + "file": (os.path.basename(file_path), content), + } + + +def _list_params( + *, + purpose: Optional[str], + after: Optional[str], + limit: Optional[int], + create_before: Optional[str], + create_after: Optional[str], +) -> Dict[str, Any]: + params: Dict[str, Any] = {} + if purpose is not None: + params["purpose"] = purpose + if after is not None: + params["after"] = after + if limit is not None: + if not 1 <= limit <= _MAX_LIMIT: + raise ValueError(f"limit must be between 1 and {_MAX_LIMIT}") + params["limit"] = limit + if create_before is not None: + params["create_before"] = create_before + if create_after is not None: + params["create_after"] = create_after + return params + + +def _parse_file( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> BatchFile: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + BatchFile, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) + + +def _parse_list( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> BatchFileList: + payload = dict(body) if isinstance(body, dict) else {} + data = payload.get("data") + if not isinstance(data, list): + data = [] + return parse_model( + BatchFileList, + { + "data": data, + "object": payload.get("object"), + "has_more": bool(payload.get("has_more", False)), + **response_envelope(payload), + }, + strict=strict, + response=response, + ) + + +def _parse_delete( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> FileDeletion: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + FileDeletion, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) + + +def _checked(client, resp, model_cls, parser): + """Raise on failure, or fill the error envelope when not raising. + + Compatible-mode failures nest ``code`` / ``message`` under ``error`` + (OpenAI shape), which the flat success parser cannot see. Routing the + reply through ``response_error`` keeps ``raise_on_error=False`` + reporting the failure via ``is_error`` / ``code`` / ``message`` instead + of surfacing it as an empty success. + """ + http_resp = resp.http_response + error = response_error(http_resp) + if error is None: + return with_headers( + parser( + resp.json(), + strict=client.config.strict_validation, + response=http_resp, + ), + http_resp, + ) + if client.raise_on_error: + raise error + return with_headers( + model_cls( + request_id=error.request_id, + status_code=error.status_code, + code=error.code, + message=error.message, + is_error=True, + ), + http_resp, + ) + + +def _content_result(client, resp) -> FileContent: + http_resp = resp.http_response + # Status-first: a successful download is raw bytes (JSONL), not a JSON + # envelope, so the business-code layer must not parse it as one. + if http_resp.status_code >= 400: + error = response_error(http_resp) + if error is not None and client.raise_on_error: + raise error + return FileContent( + http_resp.content, + request_id=resp.request_id, + headers=dict(http_resp.headers), + status_code=http_resp.status_code, + ) + + +def _parse_batch( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> Batch: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + Batch, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) + + +def _parse_batch_list( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> BatchList: + payload = dict(body) if isinstance(body, dict) else {} + data = payload.get("data") + if not isinstance(data, list): + data = [] + return parse_model( + BatchList, + { + "data": data, + "object": payload.get("object"), + "first_id": payload.get("first_id"), + "last_id": payload.get("last_id"), + "has_more": bool(payload.get("has_more", False)), + **response_envelope(payload), + }, + strict=strict, + response=response, + ) + + +def _require_batch_id(batch_id: str) -> str: + if not batch_id or not batch_id.strip(): + raise ValueError("batch_id must be a non-empty string") + # Percent-encode so a '/', '?' or '#' inside the id cannot retarget + # the request to another path or query. + return quote(batch_id, safe="") + + +def _batch_id(batch: Union[Batch, str]) -> str: + batch_id = batch.batch_id if isinstance(batch, Batch) else batch + if not batch_id: + raise DashScopeError("batch id required") + return batch_id + + +def _result_file_id(batch: Batch, attr: str) -> Optional[str]: + # output_file_id / error_file_id stay null until the batch produces + # results (error_file_id only when some row failed); treat blank as + # absent so the download helpers return None instead of GETting "". + value = getattr(batch, attr, None) + if isinstance(value, str) and value.strip(): + return value + return None + + +def _validate_completion_window(window: str) -> None: + match = _WINDOW_RE.match(window or "") + if match is None: + raise ValueError( + "completion_window must be an integer followed by 'h' or 'd' " + "(e.g. '24h', '7d')", + ) + amount, unit = int(match.group(1)), match.group(2) + hours = amount * 24 if unit == "d" else amount + if not _MIN_WINDOW_HOURS <= hours <= _MAX_WINDOW_HOURS: + raise ValueError( + f"completion_window must be between {_MIN_WINDOW_HOURS}h and " + f"{_MAX_WINDOW_HOURS}h (got {window!r})", + ) + + +def _build_batch_create_body( + *, + input_file_id: str, + endpoint: str, + completion_window: str, + metadata: Optional[Mapping[str, Any]], +) -> Dict[str, Any]: + if not input_file_id or not input_file_id.strip(): + raise ValueError("input_file_id must be a non-empty string") + if not endpoint or not endpoint.strip(): + raise ValueError("endpoint must be a non-empty string") + _validate_completion_window(completion_window) + body: Dict[str, Any] = { + "input_file_id": input_file_id, + "endpoint": endpoint, + "completion_window": completion_window, + } + if metadata is not None: + body["metadata"] = dict(metadata) + return body + + +def _csv_param(value: Union[str, Sequence[str]]) -> str: + if isinstance(value, str): + return value + return ",".join(value) + + +def _batch_list_params( + *, + after: Optional[str], + limit: Optional[int], + ds_name: Optional[str], + input_file_ids: Union[str, Sequence[str], None], + status: Union[str, Sequence[str], None], + create_after: Optional[str], + create_before: Optional[str], +) -> Dict[str, Any]: + params: Dict[str, Any] = {} + if after is not None: + params["after"] = after + if limit is not None: + if not 1 <= limit <= _BATCH_MAX_LIMIT: + raise ValueError( + f"limit must be between 1 and {_BATCH_MAX_LIMIT}", + ) + params["limit"] = limit + if ds_name is not None: + params["ds_name"] = ds_name + if input_file_ids is not None: + ids = ( + input_file_ids.split(",") + if isinstance(input_file_ids, str) + else list(input_file_ids) + ) + if len(ids) > _MAX_INPUT_FILE_IDS: + raise ValueError( + f"input_file_ids accepts at most {_MAX_INPUT_FILE_IDS} ids", + ) + params["input_file_ids"] = ",".join(ids) + if status is not None: + params["status"] = _csv_param(status) + if create_after is not None: + params["create_after"] = create_after + if create_before is not None: + params["create_before"] = create_before + return params + + +def _validate_batch_row( + row: Any, + lineno: int, + *, + endpoint: Optional[str], +) -> Tuple[str, str]: + """Validate one batch JSONL row's fields; return ``(custom_id, model)``. + + Uniqueness and cross-row model consistency are checked by the caller, + which owns the ``seen`` set and the running ``model``. + """ + if not isinstance(row, dict): + raise ValueError(f"line {lineno}: each row must be a JSON object") + custom_id = row.get("custom_id") + if not isinstance(custom_id, str) or not custom_id.strip(): + raise ValueError( + f"line {lineno}: custom_id must be a non-empty string", + ) + if row.get("method") != "POST": + raise ValueError(f"line {lineno}: method must be 'POST'") + url = row.get("url") + if not isinstance(url, str) or not url.strip(): + raise ValueError(f"line {lineno}: url must be a non-empty string") + if endpoint is not None and url != endpoint: + raise ValueError( + f"line {lineno}: url {url!r} does not match " + f"endpoint {endpoint!r}", + ) + body = row.get("body") + if not isinstance(body, dict): + raise ValueError(f"line {lineno}: body must be a JSON object") + row_model = body.get("model") + if not isinstance(row_model, str) or not row_model.strip(): + raise ValueError( + f"line {lineno}: body.model must be a non-empty string", + ) + return custom_id, row_model + + +def _validate_input_rows( + file_path: str, + *, + endpoint: Optional[str] = None, +) -> int: + """Row-level validation of a batch input JSONL file (pre-upload). + + Each non-blank line must be a JSON object with a unique non-empty + ``custom_id``, ``method="POST"``, a non-empty ``url`` (equal to + ``endpoint`` when given) and a ``body`` object carrying a non-empty + ``model``; all rows must use the same model. Returns the row count. + Local file I/O only -- no network call. + """ + if not os.path.isfile(file_path): + raise _io_error(FileNotFoundError(f"file not found: {file_path}")) + seen: Set[str] = set() + model: Optional[str] = None + count = 0 + try: + with open(file_path, "r", encoding="utf-8") as f: + for lineno, raw in enumerate(f, start=1): + line = raw.strip() + if not line: + continue + count += 1 + if count > _MAX_BATCH_ROWS: + raise ValueError( + f"batch input exceeds {_MAX_BATCH_ROWS} rows", + ) + try: + row = json.loads(line) + except ValueError as exc: + raise ValueError( + f"line {lineno}: not valid JSON ({exc})", + ) from exc + custom_id, row_model = _validate_batch_row( + row, + lineno, + endpoint=endpoint, + ) + if custom_id in seen: + raise ValueError( + f"line {lineno}: duplicate custom_id {custom_id!r}", + ) + seen.add(custom_id) + if model is None: + model = row_model + elif row_model != model: + raise ValueError( + f"line {lineno}: all rows must use the same model " + f"(expected {model!r}, got {row_model!r})", + ) + except OSError as exc: + raise _io_error(exc) from exc + if count == 0: + raise ValueError(f"file {file_path} has no batch input rows") + return count + + +class BatchFiles: + """Synchronous compatible-mode File calls (``client.batches.files``).""" + + def __init__(self, client) -> None: + self._client = client + + @overload + def upload( + self, + *, + file_path: str, + purpose: str = "batch", + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BatchFile: + ... + + @overload + def upload( + self, + *, + file_path: str, + purpose: str = "batch", + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def upload( + self, + *, + file_path: str, + purpose: str = "batch", + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BatchFile, "APIResponse"]: + """Upload a file to the compatible-mode store. + + ``purpose="batch"`` (the default) requires a JSONL input file; + ``file-extract`` accepts document/binary files. The multipart field + is ``file`` (singular), unlike the native ``client.files`` upload. + """ + _validate_upload(file_path, purpose) + data, files = _upload_form(file_path, purpose) + resp = self._client.transport.request_api( + "POST", + _BASE_PATH, + data=data, + files=files, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, BatchFile, _parse_file) + + @overload + def content( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> FileContent: + ... + + @overload + def content( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def content( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[FileContent, "APIResponse"]: + """Download a file's raw content (``GET /files/{id}/content``). + + Used for a batch's ``output_file_id`` / ``error_file_id`` JSONL + results. Returns :class:`FileContent` (bytes) with a ``text`` view + and ``write_to_file``. + """ + file_id = _require_file_id(file_id) + resp = self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/{file_id}/content", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _content_result(self._client, resp) + + @overload + def list( # pylint: disable=redefined-builtin + self, + *, + purpose: Optional[str] = None, + after: Optional[str] = None, + limit: Optional[int] = None, + create_before: Optional[str] = None, + create_after: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BatchFileList: + ... + + @overload + def list( # pylint: disable=redefined-builtin + self, + *, + purpose: Optional[str] = None, + after: Optional[str] = None, + limit: Optional[int] = None, + create_before: Optional[str] = None, + create_after: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( # pylint: disable=redefined-builtin + self, + *, + purpose: Optional[str] = None, + after: Optional[str] = None, + limit: Optional[int] = None, + create_before: Optional[str] = None, + create_after: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BatchFileList, "APIResponse"]: + """List files, one cursor page at a time. + + ``purpose="batch"`` narrows to batch files. ``after`` is the last + ``id`` of the previous page; ``limit`` is in [1, 2000]. Cross pages + with ``iter_pages()`` / ``next_page()`` on the parsed result. + """ + params = _list_params( + purpose=purpose, + after=after, + limit=limit, + create_before=create_before, + create_after=create_after, + ) + resp = self._client.transport.request_api( + "GET", + _BASE_PATH, + params=params, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + result = _checked(self._client, resp, BatchFileList, _parse_list) + if not result.is_error: + result.bind_pagination( + lambda cursor: self.list( + purpose=purpose, + after=cursor, + limit=limit, + create_before=create_before, + create_after=create_after, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + ) + return result + + @overload + def get( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BatchFile: + ... + + @overload + def get( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def get( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BatchFile, "APIResponse"]: + """Fetch one file's metadata (``GET /files/{id}``).""" + file_id = _require_file_id(file_id) + resp = self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/{file_id}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, BatchFile, _parse_file) + + @overload + def delete( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> FileDeletion: + ... + + @overload + def delete( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def delete( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[FileDeletion, "APIResponse"]: + """Delete one file (``DELETE /files/{id}``).""" + file_id = _require_file_id(file_id) + resp = self._client.transport.request_api( + "DELETE", + f"{_BASE_PATH}/{file_id}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, FileDeletion, _parse_delete) + + +class AsyncBatchFiles: + """Asynchronous compatible-mode File calls (``client.batches.files``).""" + + def __init__(self, client) -> None: + self._client = client + + @overload + async def upload( + self, + *, + file_path: str, + purpose: str = "batch", + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BatchFile: + ... + + @overload + async def upload( + self, + *, + file_path: str, + purpose: str = "batch", + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def upload( + self, + *, + file_path: str, + purpose: str = "batch", + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BatchFile, "APIResponse"]: + """Async twin of :meth:`BatchFiles.upload`.""" + _validate_upload(file_path, purpose) + data, files = _upload_form(file_path, purpose) + resp = await self._client.transport.request_api( + "POST", + _BASE_PATH, + data=data, + files=files, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, BatchFile, _parse_file) + + @overload + async def content( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> FileContent: + ... + + @overload + async def content( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def content( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[FileContent, "APIResponse"]: + """Async twin of :meth:`BatchFiles.content`.""" + file_id = _require_file_id(file_id) + resp = await self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/{file_id}/content", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _content_result(self._client, resp) + + @overload + async def list( # pylint: disable=redefined-builtin + self, + *, + purpose: Optional[str] = None, + after: Optional[str] = None, + limit: Optional[int] = None, + create_before: Optional[str] = None, + create_after: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BatchFileList: + ... + + @overload + async def list( # pylint: disable=redefined-builtin + self, + *, + purpose: Optional[str] = None, + after: Optional[str] = None, + limit: Optional[int] = None, + create_before: Optional[str] = None, + create_after: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( # pylint: disable=redefined-builtin + self, + *, + purpose: Optional[str] = None, + after: Optional[str] = None, + limit: Optional[int] = None, + create_before: Optional[str] = None, + create_after: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BatchFileList, "APIResponse"]: + """Async twin of :meth:`BatchFiles.list`.""" + params = _list_params( + purpose=purpose, + after=after, + limit=limit, + create_before=create_before, + create_after=create_after, + ) + resp = await self._client.transport.request_api( + "GET", + _BASE_PATH, + params=params, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + result = _checked(self._client, resp, BatchFileList, _parse_list) + if not result.is_error: + result.bind_pagination( + lambda cursor: self.list( + purpose=purpose, + after=cursor, + limit=limit, + create_before=create_before, + create_after=create_after, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + ) + return result + + @overload + async def get( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BatchFile: + ... + + @overload + async def get( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def get( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BatchFile, "APIResponse"]: + """Async twin of :meth:`BatchFiles.get`.""" + file_id = _require_file_id(file_id) + resp = await self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/{file_id}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, BatchFile, _parse_file) + + @overload + async def delete( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> FileDeletion: + ... + + @overload + async def delete( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def delete( + self, + file_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[FileDeletion, "APIResponse"]: + """Async twin of :meth:`BatchFiles.delete`.""" + file_id = _require_file_id(file_id) + resp = await self._client.transport.request_api( + "DELETE", + f"{_BASE_PATH}/{file_id}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, FileDeletion, _parse_delete) + + +class Batches: + """OpenAI-compatible Batch workflow (``client.batches``). + + ``files`` is the compatible-mode File sub-resource (B1); the methods + here are the batch job plane (B2): create/get/list/cancel/wait plus a + pre-upload ``validate_input`` row-level JSONL check. + """ + + def __init__(self, client) -> None: + self._client = client + self.files = BatchFiles(client) + + @overload + def create( + self, + *, + input_file_id: str, + endpoint: str, + completion_window: str = "24h", + metadata: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Batch: + ... + + @overload + def create( + self, + *, + input_file_id: str, + endpoint: str, + completion_window: str = "24h", + metadata: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def create( + self, + *, + input_file_id: str, + endpoint: str, + completion_window: str = "24h", + metadata: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Batch, "APIResponse"]: + """Create a batch job (``POST /batches``). + + ``input_file_id`` is an uploaded batch file id (or OSS URL); + ``endpoint`` must match every row's ``url`` in that file + (``/v1/chat/completions``, ``/v1/embeddings`` or + ``/v1/chat/ds-test``); ``completion_window`` is 24h..336h. + + The wire has **no idempotency key**, so this defaults to + ``max_retries=0`` (no automatic retry) -- a retried create could + otherwise spawn a duplicate batch. Passing ``max_retries`` + explicitly re-enables retry and the caller owns that duplicate + risk. Validate the input first with :meth:`validate_input`. + + ``input_file_id`` is reusable: an already-uploaded batch file id + (``file-batch-xxx``) can drive many creates without re-uploading; + find existing ones with ``files.list(purpose="batch")``. + """ + body = _build_batch_create_body( + input_file_id=input_file_id, + endpoint=endpoint, + completion_window=completion_window, + metadata=metadata, + ) + resp = self._client.transport.request_api( + "POST", + _BATCH_PATH, + json=body, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=0 if max_retries is None else max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Batch, _parse_batch) + + @overload + def get( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Batch: + ... + + @overload + def get( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def get( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Batch, "APIResponse"]: + """Fetch one batch job (``GET /batches/{id}``). + + Only tasks created within the last 30 days are retrievable. + """ + batch_id = _require_batch_id(batch_id) + resp = self._client.transport.request_api( + "GET", + f"{_BATCH_PATH}/{batch_id}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Batch, _parse_batch) + + @overload + def list( # pylint: disable=redefined-builtin + self, + *, + after: Optional[str] = None, + limit: Optional[int] = None, + ds_name: Optional[str] = None, + input_file_ids: Union[str, Sequence[str], None] = None, + status: Union[str, Sequence[str], None] = None, + create_after: Optional[str] = None, + create_before: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BatchList: + ... + + @overload + def list( # pylint: disable=redefined-builtin + self, + *, + after: Optional[str] = None, + limit: Optional[int] = None, + ds_name: Optional[str] = None, + input_file_ids: Union[str, Sequence[str], None] = None, + status: Union[str, Sequence[str], None] = None, + create_after: Optional[str] = None, + create_before: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( # pylint: disable=redefined-builtin + self, + *, + after: Optional[str] = None, + limit: Optional[int] = None, + ds_name: Optional[str] = None, + input_file_ids: Union[str, Sequence[str], None] = None, + status: Union[str, Sequence[str], None] = None, + create_after: Optional[str] = None, + create_before: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BatchList, "APIResponse"]: + """List batch jobs, one cursor page at a time (``GET /batches``). + + ``after`` is the last id of the previous page; ``limit`` is in + [1, 100] (default 20). ``input_file_ids`` / ``status`` accept a + comma-separated string or a sequence (joined for the wire); + ``input_file_ids`` is capped at 20. ``create_after`` / + ``create_before`` are ``yyyyMMddHHmmss``. Cross pages with + ``iter_pages()`` / ``next_page()`` on the parsed result. + """ + params = _batch_list_params( + after=after, + limit=limit, + ds_name=ds_name, + input_file_ids=input_file_ids, + status=status, + create_after=create_after, + create_before=create_before, + ) + resp = self._client.transport.request_api( + "GET", + _BATCH_PATH, + params=params, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + result = _checked(self._client, resp, BatchList, _parse_batch_list) + if not result.is_error: + result.bind_pagination( + lambda cursor: self.list( + after=cursor, + limit=limit, + ds_name=ds_name, + input_file_ids=input_file_ids, + status=status, + create_after=create_after, + create_before=create_before, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + ) + return result + + @overload + def cancel( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Batch: + ... + + @overload + def cancel( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def cancel( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Batch, "APIResponse"]: + """Cancel a batch job (``POST /batches/{id}/cancel``). + + Moves the job to ``cancelling`` then ``cancelled``; work already + done is still billed. Returns the updated :class:`Batch`. + """ + batch_id = _require_batch_id(batch_id) + resp = self._client.transport.request_api( + "POST", + f"{_BATCH_PATH}/{batch_id}/cancel", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Batch, _parse_batch) + + def wait( + self, + batch: Union[Batch, str], + *, + poll_interval: float = DEFAULT_POLL_INTERVAL, + max_interval: float = DEFAULT_MAX_INTERVAL, + timeout: float = DEFAULT_WAIT_TIMEOUT, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + _sleep: Optional[Callable[[float], Any]] = None, + ) -> Batch: + """Poll until the batch reaches a terminal status. + + Terminal: completed/failed/expired/cancelled. With + ``raise_on_error=True`` a ``failed`` batch raises (carrying its + ``errors`` detail) and ``cancelled``/``expired`` raise a + :class:`DashScopeError`; ``completed`` returns the batch. With + ``raise_on_error=False`` a transport-level failure comes back as + the :class:`Batch` envelope instead of raising. ``_sleep`` is a + test seam -- it replaces the pause between polls. + """ + batch_id = _batch_id(batch) + sleep_fn = _sleep or time.sleep + deadline = time.monotonic() + timeout + current = ( + batch + if isinstance(batch, Batch) + else self.get( + batch_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + ) + interval = poll_interval + while not current.finished: + if current.is_error: + return current + remaining = deadline - time.monotonic() + if remaining <= 0: + raise DashScopeError( + f"timed out after {timeout}s waiting for batch {batch_id}", + ) + sleep_fn(min(interval, remaining)) + interval = min(interval * 2, max_interval) + current = self.get( + batch_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + return self._check_terminal(current, batch_id) + + def _check_terminal(self, batch: Batch, batch_id: str) -> Batch: + if batch.status == FAILED and self._client.raise_on_error: + detail = None + if batch.errors and batch.errors.data: + detail = batch.errors.data[0].message + raise error_from_business_code( + message=batch.message or detail or f"batch {batch_id} failed", + code=batch.code, + # ``headers`` is transport metadata, not wire body. + body=batch.model_dump(exclude={"headers"}), + headers=batch.headers, + ) + if ( + batch.status in (CANCELLED, EXPIRED) + and self._client.raise_on_error + ): + raise DashScopeError( + f"batch {batch_id} was {batch.status} while waiting", + request_id=batch.request_id, + ) + return batch + + def validate_input( + self, + file_path: str, + *, + endpoint: Optional[str] = None, + ) -> int: + """Validate a batch input JSONL file row by row (pre-upload). + + Local file I/O only -- no network call, so this is a plain method + on both the sync and async clients. Checks each row's + ``custom_id`` (unique, non-empty), ``method="POST"``, ``url`` + (matching ``endpoint`` when given) and ``body.model`` (non-empty, + same across all rows). Returns the row count; raises + ``ValueError`` with the offending line number on the first + violation. Run this before ``files.upload`` + ``create``. + """ + return _validate_input_rows(file_path, endpoint=endpoint) + + def download_output( + self, + batch: Union[Batch, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + ) -> Optional[FileContent]: + """Download a batch's successful-results JSONL (``output_file_id``). + + Accepts a :class:`Batch` (used as-is) or a batch id (fetched via + :meth:`get`). Resolves ``output_file_id`` and downloads it through + ``files.content`` (``GET /files/{id}/content``), returning + :class:`FileContent` (bytes with ``text`` / ``write_to_file``). + Returns ``None`` when the batch has no output file yet (not + ``completed``, or an error envelope under ``raise_on_error=False``). + Each output row is ``{id, custom_id, response:{status_code, + request_id, body}, error}``. Call :meth:`wait` first for a terminal + batch. High-level helper -- no ``raw`` overload; use + ``files.content(file_id, raw=True)`` for the raw response. + """ + return self._download_result( + batch, + "output_file_id", + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + + def download_error( + self, + batch: Union[Batch, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + ) -> Optional[FileContent]: + """Download a batch's failed-requests JSONL (``error_file_id``). + + Like :meth:`download_output` but for ``error_file_id``; returns + ``None`` when no row failed (the common case for a clean batch). + """ + return self._download_result( + batch, + "error_file_id", + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + + def _download_result( + self, + batch: Union[Batch, str], + attr: str, + *, + timeout: Optional[float], + api_key: Optional[str], + workspace: Optional[str], + extra_headers: Optional[Mapping[str, str]], + extra_query: Optional[Mapping[str, Any]], + extra_body: Optional[Mapping[str, Any]], + max_retries: Optional[int], + ) -> Optional[FileContent]: + batch_id = _batch_id(batch) + current = ( + batch + if isinstance(batch, Batch) + else self.get( + batch_id, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + ) + file_id = _result_file_id(current, attr) + if file_id is None: + return None + return self.files.content( + file_id, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + + +class AsyncBatches: + """Async twin of :class:`Batches`.""" + + def __init__(self, client) -> None: + self._client = client + self.files = AsyncBatchFiles(client) + + @overload + async def create( + self, + *, + input_file_id: str, + endpoint: str, + completion_window: str = "24h", + metadata: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Batch: + ... + + @overload + async def create( + self, + *, + input_file_id: str, + endpoint: str, + completion_window: str = "24h", + metadata: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def create( + self, + *, + input_file_id: str, + endpoint: str, + completion_window: str = "24h", + metadata: Optional[Mapping[str, Any]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Batch, "APIResponse"]: + """Async twin of :meth:`Batches.create` (defaults ``max_retries=0``).""" + body = _build_batch_create_body( + input_file_id=input_file_id, + endpoint=endpoint, + completion_window=completion_window, + metadata=metadata, + ) + resp = await self._client.transport.request_api( + "POST", + _BATCH_PATH, + json=body, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=0 if max_retries is None else max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Batch, _parse_batch) + + @overload + async def get( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Batch: + ... + + @overload + async def get( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def get( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Batch, "APIResponse"]: + """Async twin of :meth:`Batches.get`.""" + batch_id = _require_batch_id(batch_id) + resp = await self._client.transport.request_api( + "GET", + f"{_BATCH_PATH}/{batch_id}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Batch, _parse_batch) + + @overload + async def list( # pylint: disable=redefined-builtin + self, + *, + after: Optional[str] = None, + limit: Optional[int] = None, + ds_name: Optional[str] = None, + input_file_ids: Union[str, Sequence[str], None] = None, + status: Union[str, Sequence[str], None] = None, + create_after: Optional[str] = None, + create_before: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> BatchList: + ... + + @overload + async def list( # pylint: disable=redefined-builtin + self, + *, + after: Optional[str] = None, + limit: Optional[int] = None, + ds_name: Optional[str] = None, + input_file_ids: Union[str, Sequence[str], None] = None, + status: Union[str, Sequence[str], None] = None, + create_after: Optional[str] = None, + create_before: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( # pylint: disable=redefined-builtin + self, + *, + after: Optional[str] = None, + limit: Optional[int] = None, + ds_name: Optional[str] = None, + input_file_ids: Union[str, Sequence[str], None] = None, + status: Union[str, Sequence[str], None] = None, + create_after: Optional[str] = None, + create_before: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[BatchList, "APIResponse"]: + """Async twin of :meth:`Batches.list`.""" + params = _batch_list_params( + after=after, + limit=limit, + ds_name=ds_name, + input_file_ids=input_file_ids, + status=status, + create_after=create_after, + create_before=create_before, + ) + resp = await self._client.transport.request_api( + "GET", + _BATCH_PATH, + params=params, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + result = _checked(self._client, resp, BatchList, _parse_batch_list) + if not result.is_error: + result.bind_pagination( + lambda cursor: self.list( + after=cursor, + limit=limit, + ds_name=ds_name, + input_file_ids=input_file_ids, + status=status, + create_after=create_after, + create_before=create_before, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + ) + return result + + @overload + async def cancel( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Batch: + ... + + @overload + async def cancel( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def cancel( + self, + batch_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Batch, "APIResponse"]: + """Async twin of :meth:`Batches.cancel`.""" + batch_id = _require_batch_id(batch_id) + resp = await self._client.transport.request_api( + "POST", + f"{_BATCH_PATH}/{batch_id}/cancel", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Batch, _parse_batch) + + async def wait( + self, + batch: Union[Batch, str], + *, + poll_interval: float = DEFAULT_POLL_INTERVAL, + max_interval: float = DEFAULT_MAX_INTERVAL, + timeout: float = DEFAULT_WAIT_TIMEOUT, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + _sleep: Optional[Callable[[float], Awaitable[None]]] = None, + ) -> Batch: + """Async twin of :meth:`Batches.wait`.""" + batch_id = _batch_id(batch) + sleep_fn = _sleep or asyncio.sleep + deadline = time.monotonic() + timeout + current = ( + batch + if isinstance(batch, Batch) + else await self.get( + batch_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + ) + interval = poll_interval + while not current.finished: + if current.is_error: + return current + remaining = deadline - time.monotonic() + if remaining <= 0: + raise DashScopeError( + f"timed out after {timeout}s waiting for batch {batch_id}", + ) + await sleep_fn(min(interval, remaining)) + interval = min(interval * 2, max_interval) + current = await self.get( + batch_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + return self._check_terminal(current, batch_id) + + def _check_terminal(self, batch: Batch, batch_id: str) -> Batch: + if batch.status == FAILED and self._client.raise_on_error: + detail = None + if batch.errors and batch.errors.data: + detail = batch.errors.data[0].message + raise error_from_business_code( + message=batch.message or detail or f"batch {batch_id} failed", + code=batch.code, + body=batch.model_dump(exclude={"headers"}), + headers=batch.headers, + ) + if ( + batch.status in (CANCELLED, EXPIRED) + and self._client.raise_on_error + ): + raise DashScopeError( + f"batch {batch_id} was {batch.status} while waiting", + request_id=batch.request_id, + ) + return batch + + def validate_input( + self, + file_path: str, + *, + endpoint: Optional[str] = None, + ) -> int: + """Local row-level JSONL validation; see :meth:`Batches.validate_input`. + + A plain (non-async) method: it does local file I/O, no network. + """ + return _validate_input_rows(file_path, endpoint=endpoint) + + async def download_output( + self, + batch: Union[Batch, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + ) -> Optional[FileContent]: + """Async twin of :meth:`Batches.download_output`.""" + return await self._download_result( + batch, + "output_file_id", + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + + async def download_error( + self, + batch: Union[Batch, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + ) -> Optional[FileContent]: + """Async twin of :meth:`Batches.download_error`.""" + return await self._download_result( + batch, + "error_file_id", + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + + async def _download_result( + self, + batch: Union[Batch, str], + attr: str, + *, + timeout: Optional[float], + api_key: Optional[str], + workspace: Optional[str], + extra_headers: Optional[Mapping[str, str]], + extra_query: Optional[Mapping[str, Any]], + extra_body: Optional[Mapping[str, Any]], + max_retries: Optional[int], + ) -> Optional[FileContent]: + batch_id = _batch_id(batch) + current = ( + batch + if isinstance(batch, Batch) + else await self.get( + batch_id, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + ) + file_id = _result_file_id(current, attr) + if file_id is None: + return None + return await self.files.content( + file_id, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) diff --git a/dashscope/resources/conversations.py b/dashscope/resources/conversations.py new file mode 100644 index 00000000..ffe5a2c4 --- /dev/null +++ b/dashscope/resources/conversations.py @@ -0,0 +1,1028 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""client.conversations -- OpenAI-compatible Conversations API (C2). + +Server-side conversation context for the Responses API: a conversation's +items are injected as history automatically, and each response's input +and output are appended back to it. Pass ``conversation=conv.id`` to +``client.responses.create`` (mutually exclusive with +``previous_response_id``); the SDK stays a stateless wrapper -- no +client-side history or memory. + +The resource covers the full documented surface: conversation +``create`` / ``get`` / ``update`` / ``delete`` and ``items.create`` / +``items.list`` / ``items.get`` / ``items.delete``. + +Like ``client.responses`` / ``client.batches``, every call derives its own +base URL via ``compatible_mode_base_url`` (``{gateway}/compatible-mode/v1``) +so the chat ``protocol`` setting cannot move it, and tags ``sdk_module`` +``conversations`` for the ``x-dashscope-sdk-client`` header. + +Limits (mirrored as local pre-validation): at most 20 items per +create/add; metadata at most 16 string pairs (key <= 64, value <= 512 +chars); the service keeps the latest 100 items within 7 days. + +Contract: +https://help.aliyun.com/zh/model-studio/openai-compatible-conversations +""" + +from __future__ import annotations + +from typing import ( + TYPE_CHECKING, + Any, + Dict, + List, + Mapping, + Optional, + Sequence, + Union, +) +from urllib.parse import quote + +from pydantic import BaseModel + +from dashscope._config import Config, compatible_mode_base_url +from dashscope.errors import response_error +from dashscope.resources.batches import _CursorPage +from dashscope.transport._options import request_options +from dashscope.types._parse import parse_model +from dashscope.types.common import response_envelope, with_headers +from dashscope.types.conversations import ( + Conversation, + ConversationDeleted, + ConversationItem, + ConversationItemDeleted, + parse_conversation, + parse_conversation_deleted, + parse_conversation_item, + parse_conversation_item_deleted, +) + +if TYPE_CHECKING: + import httpx + + from dashscope.transport._response import APIResponse + +_CONVERSATIONS_PATH = "/conversations" + +MODULE = "conversations" + +# items.list caps limit at 100 (default 20); order defaults to desc. +_MAX_LIMIT = 100 +# create conversation / create items accept at most 20 items per call. +_MAX_ITEMS = 20 +_MAX_METADATA_PAIRS = 16 +_MAX_METADATA_KEY_LEN = 64 +_MAX_METADATA_VALUE_LEN = 512 + +ItemsInput = Sequence[Union[Mapping[str, Any], BaseModel]] +MetadataInput = Mapping[str, str] + + +def _endpoint_base(config: Config) -> str: + # The compatible-mode Conversations API sits under /compatible-mode/v1 + # on every gateway; the chat protocol setting must not move it. + return compatible_mode_base_url( + config.workspace, + config.region, + config.configured_base_url, + ) + + +def _conversation_id(value: Union[Conversation, str]) -> str: + cid = value.id if isinstance(value, Conversation) else value + if not cid or not str(cid).strip(): + raise ValueError("conversation_id must be a non-empty string") + # Percent-encode so a '/', '?' or '#' inside the id cannot retarget + # the request to another path or query. + return quote(str(cid), safe="") + + +def _item_id(value: Union[ConversationItem, str]) -> str: + iid = value.id if isinstance(value, ConversationItem) else value + if not iid or not str(iid).strip(): + raise ValueError("item_id must be a non-empty string") + # Percent-encode so a '/', '?' or '#' inside the id cannot retarget + # the request to another path or query. + return quote(str(iid), safe="") + + +def _validate_metadata( + metadata: Optional[MetadataInput], +) -> Optional[Dict[str, str]]: + if metadata is None: + return None + if not isinstance(metadata, Mapping): + raise ValueError("metadata must be a mapping of string keys/values") + if len(metadata) > _MAX_METADATA_PAIRS: + raise ValueError( + f"metadata supports at most {_MAX_METADATA_PAIRS} key/value " + f"pairs (got {len(metadata)})", + ) + result: Dict[str, str] = {} + for key, value in metadata.items(): + if not isinstance(key, str) or len(key) > _MAX_METADATA_KEY_LEN: + raise ValueError( + f"metadata keys must be strings of at most " + f"{_MAX_METADATA_KEY_LEN} characters", + ) + if not isinstance(value, str) or len(value) > _MAX_METADATA_VALUE_LEN: + raise ValueError( + f"metadata values must be strings of at most " + f"{_MAX_METADATA_VALUE_LEN} characters", + ) + result[key] = value + return result + + +def _normalize_items(value: ItemsInput) -> List[Dict[str, Any]]: + items: List[Dict[str, Any]] = [] + for item in value: + if isinstance(item, BaseModel): + items.append(item.model_dump(exclude_none=True)) + elif isinstance(item, Mapping): + items.append(dict(item)) + else: + raise ValueError("each item must be a mapping or a pydantic model") + if len(items) > _MAX_ITEMS: + raise ValueError( + f"items supports at most {_MAX_ITEMS} entries per call " + f"(got {len(items)})", + ) + return items + + +def _build_create_body( + *, + metadata: Optional[MetadataInput], + items: Optional[ItemsInput], +) -> Dict[str, Any]: + body: Dict[str, Any] = {} + normalized_metadata = _validate_metadata(metadata) + if normalized_metadata is not None: + body["metadata"] = normalized_metadata + if items is not None: + normalized = _normalize_items(items) + if normalized: + body["items"] = normalized + return body + + +def _build_items_body(items: ItemsInput) -> Dict[str, Any]: + if items is None: + raise ValueError("items is required") + normalized = _normalize_items(items) + if not normalized: + raise ValueError("items must not be empty") + return {"items": normalized} + + +def _items_params( + *, + after: Optional[str], + limit: Optional[int], + order: Optional[str], +) -> Dict[str, Any]: + params: Dict[str, Any] = {} + if after is not None: + params["after"] = after + if limit is not None: + if not 1 <= limit <= _MAX_LIMIT: + raise ValueError(f"limit must be between 1 and {_MAX_LIMIT}") + params["limit"] = limit + if order is not None: + if order not in ("asc", "desc"): + raise ValueError("order must be 'asc' or 'desc'") + params["order"] = order + return params + + +def _checked(client, resp, model_cls, parser): + """Raise on failure, or fill the error envelope when not raising. + + Compatible-mode failures nest ``code`` / ``message`` under ``error`` + (OpenAI shape), which the flat success parser cannot see; routing the + reply through ``response_error`` keeps ``raise_on_error=False`` + reporting the failure via ``is_error`` / ``code`` / ``message``. + """ + http_resp = resp.http_response + error = response_error(http_resp) + if error is None: + return with_headers( + parser( + resp.json(), + strict=client.config.strict_validation, + response=http_resp, + ), + http_resp, + ) + if client.raise_on_error: + raise error + return with_headers( + model_cls( + request_id=error.request_id, + status_code=error.status_code, + code=error.code, + message=error.message, + is_error=True, + ), + http_resp, + ) + + +class ConversationItemList(_CursorPage): + """One cursor page of conversation items (``items.list`` / + ``items.create``). + + The wire carries ``first_id`` / ``last_id`` (item ids, ``msg_xxx``); + the next-page cursor prefers ``last_id``. ``object`` is ``list`` on + ``items.list`` (absent on ``items.create``, defaulted here). + """ + + data: List[ConversationItem] = [] + first_id: Optional[str] = None + last_id: Optional[str] = None + object: Optional[str] = "list" + + @property + def _next_cursor(self) -> Optional[str]: + if self.last_id: + return self.last_id + return self.data[-1].id if self.data else None + + +def _parse_conversation_item_list( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> ConversationItemList: + payload = dict(body) if isinstance(body, dict) else {} + data = payload.get("data") + if not isinstance(data, list): + data = [] + return parse_model( + ConversationItemList, + { + "data": data, + "first_id": payload.get("first_id"), + "last_id": payload.get("last_id"), + "object": payload.get("object", "list"), + "has_more": bool(payload.get("has_more", False)), + **response_envelope(payload), + }, + strict=strict, + response=response, + ) + + +class ConversationItems: + """``client.conversations.items`` -- a conversation's message items.""" + + def __init__(self, client) -> None: + self._client = client + + def create( + self, + conversation_id: Union[Conversation, str], + *, + items: ItemsInput, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ConversationItemList, "APIResponse"]: + """Add message items (``POST /conversations/{id}/items``). + + ``items`` is required, at most 20 per call; each is a ``message`` + with ``role`` (user/assistant/system/developer) and ``content`` + (string or content-block list). Returns the created items as a + cursor page (``data`` / ``first_id`` / ``last_id`` / ``has_more``). + """ + cid = _conversation_id(conversation_id) + body = _build_items_body(items) + resp = self._client.transport.request_api( + "POST", + f"{_CONVERSATIONS_PATH}/{cid}/items", + json=body, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked( + self._client, + resp, + ConversationItemList, + _parse_conversation_item_list, + ) + + def list( # pylint: disable=redefined-builtin + self, + conversation_id: Union[Conversation, str], + *, + after: Optional[str] = None, + limit: Optional[int] = None, + order: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ConversationItemList, "APIResponse"]: + """List items, one cursor page (``GET /conversations/{id}/items``). + + ``after`` is an item id (``msg_xxx``) -- the previous page's + ``last_id``; ``limit`` is in [1, 100] (default 20); ``order`` is + ``asc`` / ``desc`` (default ``desc``). Cross pages with + ``iter_pages()`` / ``next_page()`` on the parsed result. + """ + cid = _conversation_id(conversation_id) + params = _items_params(after=after, limit=limit, order=order) + resp = self._client.transport.request_api( + "GET", + f"{_CONVERSATIONS_PATH}/{cid}/items", + params=params, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + result = _checked( + self._client, + resp, + ConversationItemList, + _parse_conversation_item_list, + ) + if not result.is_error: + result.bind_pagination( + lambda cursor: self.list( + cid, + after=cursor, + limit=limit, + order=order, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + ) + return result + + def get( + self, + conversation_id: Union[Conversation, str], + item_id: Union[ConversationItem, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ConversationItem, "APIResponse"]: + """Retrieve one item (``GET /conversations/{id}/items/{item_id}``).""" + cid = _conversation_id(conversation_id) + iid = _item_id(item_id) + resp = self._client.transport.request_api( + "GET", + f"{_CONVERSATIONS_PATH}/{cid}/items/{iid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked( + self._client, + resp, + ConversationItem, + parse_conversation_item, + ) + + def delete( + self, + conversation_id: Union[Conversation, str], + item_id: Union[ConversationItem, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ConversationItemDeleted, "APIResponse"]: + """Delete one item (``DELETE /conversations/{id}/items/{item_id}``). + + The wire returns ``{id, deleted, object: conversation.item.deleted}``. + """ + cid = _conversation_id(conversation_id) + iid = _item_id(item_id) + resp = self._client.transport.request_api( + "DELETE", + f"{_CONVERSATIONS_PATH}/{cid}/items/{iid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked( + self._client, + resp, + ConversationItemDeleted, + parse_conversation_item_deleted, + ) + + +class AsyncConversationItems: + """Async twin of :class:`ConversationItems`.""" + + def __init__(self, client) -> None: + self._client = client + + async def create( + self, + conversation_id: Union[Conversation, str], + *, + items: ItemsInput, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ConversationItemList, "APIResponse"]: + """Async twin of :meth:`ConversationItems.create`.""" + cid = _conversation_id(conversation_id) + body = _build_items_body(items) + resp = await self._client.transport.request_api( + "POST", + f"{_CONVERSATIONS_PATH}/{cid}/items", + json=body, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked( + self._client, + resp, + ConversationItemList, + _parse_conversation_item_list, + ) + + async def list( # pylint: disable=redefined-builtin + self, + conversation_id: Union[Conversation, str], + *, + after: Optional[str] = None, + limit: Optional[int] = None, + order: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ConversationItemList, "APIResponse"]: + """Async twin of :meth:`ConversationItems.list`.""" + cid = _conversation_id(conversation_id) + params = _items_params(after=after, limit=limit, order=order) + resp = await self._client.transport.request_api( + "GET", + f"{_CONVERSATIONS_PATH}/{cid}/items", + params=params, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + result = _checked( + self._client, + resp, + ConversationItemList, + _parse_conversation_item_list, + ) + if not result.is_error: + result.bind_pagination( + lambda cursor: self.list( + cid, + after=cursor, + limit=limit, + order=order, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + ) + return result + + async def get( + self, + conversation_id: Union[Conversation, str], + item_id: Union[ConversationItem, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ConversationItem, "APIResponse"]: + """Async twin of :meth:`ConversationItems.get`.""" + cid = _conversation_id(conversation_id) + iid = _item_id(item_id) + resp = await self._client.transport.request_api( + "GET", + f"{_CONVERSATIONS_PATH}/{cid}/items/{iid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked( + self._client, + resp, + ConversationItem, + parse_conversation_item, + ) + + async def delete( + self, + conversation_id: Union[Conversation, str], + item_id: Union[ConversationItem, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ConversationItemDeleted, "APIResponse"]: + """Async twin of :meth:`ConversationItems.delete`.""" + cid = _conversation_id(conversation_id) + iid = _item_id(item_id) + resp = await self._client.transport.request_api( + "DELETE", + f"{_CONVERSATIONS_PATH}/{cid}/items/{iid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked( + self._client, + resp, + ConversationItemDeleted, + parse_conversation_item_deleted, + ) + + +class Conversations: + """``client.conversations`` -- the OpenAI-compatible Conversations + lifecycle, with ``items`` as a sub-resource.""" + + def __init__(self, client) -> None: + self._client = client + self.items = ConversationItems(client) + + def create( + self, + *, + metadata: Optional[MetadataInput] = None, + items: Optional[ItemsInput] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Conversation, "APIResponse"]: + """Create a conversation (``POST /conversations``). + + ``metadata`` (<= 16 string pairs) and initial ``items`` (<= 20 + ``message`` entries) are both optional. The returned ``id`` seeds + ``client.responses.create(conversation=...)`` for multi-turn + context; ``created_at`` is Unix milliseconds. + """ + body = _build_create_body(metadata=metadata, items=items) + resp = self._client.transport.request_api( + "POST", + _CONVERSATIONS_PATH, + json=body, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Conversation, parse_conversation) + + def get( + self, + conversation_id: Union[Conversation, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Conversation, "APIResponse"]: + """Retrieve a conversation (``GET /conversations/{id}``).""" + cid = _conversation_id(conversation_id) + resp = self._client.transport.request_api( + "GET", + f"{_CONVERSATIONS_PATH}/{cid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Conversation, parse_conversation) + + def update( + self, + conversation_id: Union[Conversation, str], + *, + metadata: MetadataInput, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Conversation, "APIResponse"]: + """Update a conversation's metadata (``POST /conversations/{id}``). + + ``metadata`` is required and **fully replaces** the existing + metadata (<= 16 string pairs, key <= 64, value <= 512 chars). + """ + cid = _conversation_id(conversation_id) + normalized = _validate_metadata(metadata) + if normalized is None: + raise ValueError("metadata is required for update") + resp = self._client.transport.request_api( + "POST", + f"{_CONVERSATIONS_PATH}/{cid}", + json={"metadata": normalized}, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Conversation, parse_conversation) + + def delete( + self, + conversation_id: Union[Conversation, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ConversationDeleted, "APIResponse"]: + """Delete a conversation (``DELETE /conversations/{id}``). + + The conversation's items are **not** deleted. The wire returns + ``{id, deleted, object: conversation.deleted}``. + """ + cid = _conversation_id(conversation_id) + resp = self._client.transport.request_api( + "DELETE", + f"{_CONVERSATIONS_PATH}/{cid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked( + self._client, + resp, + ConversationDeleted, + parse_conversation_deleted, + ) + + +class AsyncConversations: + """Async twin of :class:`Conversations`.""" + + def __init__(self, client) -> None: + self._client = client + self.items = AsyncConversationItems(client) + + async def create( + self, + *, + metadata: Optional[MetadataInput] = None, + items: Optional[ItemsInput] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Conversation, "APIResponse"]: + """Async twin of :meth:`Conversations.create`.""" + body = _build_create_body(metadata=metadata, items=items) + resp = await self._client.transport.request_api( + "POST", + _CONVERSATIONS_PATH, + json=body, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Conversation, parse_conversation) + + async def get( + self, + conversation_id: Union[Conversation, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Conversation, "APIResponse"]: + """Async twin of :meth:`Conversations.get`.""" + cid = _conversation_id(conversation_id) + resp = await self._client.transport.request_api( + "GET", + f"{_CONVERSATIONS_PATH}/{cid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Conversation, parse_conversation) + + async def update( + self, + conversation_id: Union[Conversation, str], + *, + metadata: MetadataInput, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Conversation, "APIResponse"]: + """Async twin of :meth:`Conversations.update`.""" + cid = _conversation_id(conversation_id) + normalized = _validate_metadata(metadata) + if normalized is None: + raise ValueError("metadata is required for update") + resp = await self._client.transport.request_api( + "POST", + f"{_CONVERSATIONS_PATH}/{cid}", + json={"metadata": normalized}, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Conversation, parse_conversation) + + async def delete( + self, + conversation_id: Union[Conversation, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ConversationDeleted, "APIResponse"]: + """Async twin of :meth:`Conversations.delete`.""" + cid = _conversation_id(conversation_id) + resp = await self._client.transport.request_api( + "DELETE", + f"{_CONVERSATIONS_PATH}/{cid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked( + self._client, + resp, + ConversationDeleted, + parse_conversation_deleted, + ) + + +__all__ = [ + "AsyncConversationItems", + "AsyncConversations", + "ConversationItemList", + "ConversationItems", + "Conversations", +] diff --git a/dashscope/resources/deployments.py b/dashscope/resources/deployments.py index de332837..847299cf 100644 --- a/dashscope/resources/deployments.py +++ b/dashscope/resources/deployments.py @@ -26,6 +26,24 @@ from pydantic import AliasChoices, BaseModel, ConfigDict, Field +from dashscope.resources._ptu import ( + AsyncCapacityInstances, + AsyncCapacityOperations, + CapacityInstance, + CapacityInstanceList, + CapacityInstances, + CapacityOperation, + CapacityOperations, + PrePaidInfo, + PtuCapacity, + _idempotency_headers, + _path_id, + _pre_paid_info_body, + _ptu_capacity_body, + _purchase_retries, + _renew_body, + _validate_order_type, +) from dashscope.resources._sse import ( _aiter_sse, _iter_sse, @@ -54,11 +72,20 @@ MODULE = "finetune" __all__ = [ + "AsyncCapacityInstances", + "AsyncCapacityOperations", "AsyncDeployments", + "CapacityInstance", + "CapacityInstanceList", + "CapacityInstances", + "CapacityOperation", + "CapacityOperations", "Deployment", "DeploymentEvent", "DeploymentList", "Deployments", + "PrePaidInfo", + "PtuCapacity", ] @@ -93,6 +120,18 @@ class Deployment(ResponseBase): ) modifier: Optional[str] = None creator: Optional[str] = None + # PTU throughput-reservation fields (plan="ptu"); empty for MU/lora. + name: Optional[str] = None + plan: Optional[str] = None + ptu_service_tier: Optional[str] = None + ptu_capacity: Optional[PtuCapacity] = None + pre_paid_info: Optional[PrePaidInfo] = None + pre_paid_instance_id: Optional[str] = None + pre_paid_gmt_expired: Optional[str] = None + overflow_strategy: Optional[str] = None + fail_reason: Optional[str] = None + operation_id: Optional[str] = None + instance_id: Optional[str] = None class DeploymentList(ResponseBase): @@ -188,51 +227,114 @@ def _parse_event( ) +def _validate_ptu_create( + plan: Optional[str], + charge_type: Optional[str], + ptu_capacity: Any, + pre_paid_info: Any, +) -> None: + # PTU expresses capacity as ptu_capacity (kTPM), not instance count. + # charge_type and ptu_capacity are required; pre_paid billing + # additionally requires pre_paid_info. + if plan != "ptu": + return + if charge_type is None: + raise ValueError("plan='ptu' requires charge_type") + if ptu_capacity is None: + raise ValueError("plan='ptu' requires ptu_capacity") + if charge_type == "pre_paid" and pre_paid_info is None: + raise ValueError("pre_paid charge_type requires pre_paid_info") + + def _build_create_body( model: str, - capacity: int, + capacity: Optional[int], model_version: Optional[str], suffix: Optional[str], plan: Optional[str], template_id: Optional[str], deploy_spec: Optional[Dict[str, Any]], billing_method: Optional[str], + service_tier: Optional[str] = None, + charge_type: Optional[str] = None, + ptu_capacity: Any = None, + pre_paid_info: Any = None, + name: Optional[str] = None, ) -> Dict[str, Any]: # Wire spellings; the public names are ``model`` / ``model_version``. - body: Dict[str, Any] = {"model_name": model, "capacity": capacity} - if model_version is not None: - body["model_version"] = model_version - if suffix is not None: - body["suffix"] = suffix - if plan is not None: - body["plan"] = plan - if template_id is not None: - body["template_id"] = template_id - - # MU deployments reject the create call unless both are present. - if deploy_spec is not None: - body["deploy_spec"] = deploy_spec - if billing_method is not None: - body["billing_method"] = billing_method + body: Dict[str, Any] = {"model_name": model} + if capacity is not None: + body["capacity"] = capacity + optional = { + "model_version": model_version, + "suffix": suffix, + "plan": plan, + "template_id": template_id, + # MU deployments reject the create call unless both are present. + "deploy_spec": deploy_spec, + "billing_method": billing_method, + "name": name, + "service_tier": service_tier, + "charge_type": charge_type, + } + body.update({k: v for k, v in optional.items() if v is not None}) + if ptu_capacity is not None: + body["ptu_capacity"] = _ptu_capacity_body(ptu_capacity) + if pre_paid_info is not None: + body["pre_paid_info"] = _pre_paid_info_body(pre_paid_info) + _validate_ptu_create(plan, charge_type, ptu_capacity, pre_paid_info) + return body + + +def _build_scale_body( + deployed_model: str, + capacity: Optional[int], + ptu_capacity: Any, + instance_id: Optional[str], + pre_paid_info: Any, + order_type: Optional[str], +) -> Dict[str, Any]: + if capacity is None and ptu_capacity is None: + raise ValueError("scale requires capacity or ptu_capacity") + _validate_order_type(order_type) + body: Dict[str, Any] = {"deployed_model": deployed_model} + if capacity is not None: + body["capacity"] = capacity + if ptu_capacity is not None: + # PTU scale is an ABSOLUTE target, not an increment. + body["ptu_capacity"] = _ptu_capacity_body(ptu_capacity) + if instance_id is not None: + body["instance_id"] = instance_id + if pre_paid_info is not None: + body["pre_paid_info"] = _pre_paid_info_body(pre_paid_info) + if order_type is not None: + body["order_type"] = order_type return body class Deployments: def __init__(self, client) -> None: self._client = client + self.capacity_instances = CapacityInstances(client) + self.capacity_operations = CapacityOperations(client) @overload def create( self, *, model: str, - capacity: int, + capacity: Optional[int] = None, model_version: Optional[str] = None, suffix: Optional[str] = None, plan: Optional[str] = None, template_id: Optional[str] = None, deploy_spec: Optional[Dict[str, Any]] = None, billing_method: Optional[str] = None, + service_tier: Optional[str] = None, + charge_type: Optional[str] = None, + ptu_capacity: Any = None, + pre_paid_info: Any = None, + name: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -249,13 +351,18 @@ def create( self, *, model: str, - capacity: int, + capacity: Optional[int] = None, model_version: Optional[str] = None, suffix: Optional[str] = None, plan: Optional[str] = None, template_id: Optional[str] = None, deploy_spec: Optional[Dict[str, Any]] = None, billing_method: Optional[str] = None, + service_tier: Optional[str] = None, + charge_type: Optional[str] = None, + ptu_capacity: Any = None, + pre_paid_info: Any = None, + name: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -271,13 +378,18 @@ def create( self, *, model: str, - capacity: int, + capacity: Optional[int] = None, model_version: Optional[str] = None, suffix: Optional[str] = None, plan: Optional[str] = None, template_id: Optional[str] = None, deploy_spec: Optional[Dict[str, Any]] = None, billing_method: Optional[str] = None, + service_tier: Optional[str] = None, + charge_type: Optional[str] = None, + ptu_capacity: Any = None, + pre_paid_info: Any = None, + name: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -287,7 +399,20 @@ def create( max_retries: Optional[int] = None, raw: bool = False, ) -> Union[Deployment, "APIResponse"]: - """Create a deployment of ``model`` with ``capacity`` instances. + """Create a deployment of ``model``. + + For MU/lora plans pass ``capacity`` (instance count). For PTU + throughput reservation pass ``plan="ptu"`` with ``charge_type`` + (``pre_paid`` / ``post_paid``) and ``ptu_capacity`` (kTPM mapping); + ``pre_paid`` additionally requires ``pre_paid_info``. Optional PTU + fields: ``service_tier`` (``ptu_fast`` default / ``ptu_default``), + ``name``, ``suffix``. + + A PTU create is a billable purchase, so it defaults to + ``max_retries=0`` (a blind retry could spawn a duplicate ModelCode). + The first ModelCode creation is deliberately NOT given an + idempotency key -- the contract reserves that for instance writes; + on a create timeout, confirm the existing ModelCode before retrying. ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` before any error check, so a caller can read the status, headers and @@ -302,7 +427,14 @@ def create( template_id, deploy_spec, billing_method, + service_tier, + charge_type, + ptu_capacity, + pre_paid_info, + name, ) + if plan == "ptu": + max_retries = _purchase_retries(max_retries) resp = self._client.transport.request_api( "POST", _BASE_PATH, @@ -382,6 +514,7 @@ def get( before any error check, so a caller can read the status, headers and ``elapsed`` of the response or re-parse it itself. """ + deployed_model = _path_id(deployed_model, "deployed_model") resp = self._client.transport.request_api( "GET", f"{_BASE_PATH}/{deployed_model}", @@ -496,7 +629,11 @@ def scale( self, deployed_model: str, *, - capacity: int, + capacity: Optional[int] = None, + ptu_capacity: Any = None, + instance_id: Optional[str] = None, + pre_paid_info: Any = None, + order_type: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -513,7 +650,11 @@ def scale( self, deployed_model: str, *, - capacity: int, + capacity: Optional[int] = None, + ptu_capacity: Any = None, + instance_id: Optional[str] = None, + pre_paid_info: Any = None, + order_type: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -529,7 +670,11 @@ def scale( self, deployed_model: str, *, - capacity: int, + capacity: Optional[int] = None, + ptu_capacity: Any = None, + instance_id: Optional[str] = None, + pre_paid_info: Any = None, + order_type: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -539,16 +684,222 @@ def scale( max_retries: Optional[int] = None, raw: bool = False, ) -> Union[Deployment, "APIResponse"]: - """Resize a deployment to ``capacity`` instances. + """Resize a deployment. + + MU/lora: pass ``capacity`` (instance count). PTU: pass + ``ptu_capacity`` as an ABSOLUTE kTPM target (not an increment), + optionally ``instance_id`` (required when the ModelCode holds more + than one instance, else CAPACITY_INSTANCE_REQUIRED), + ``pre_paid_info`` and ``order_type`` (UPGRADE / DOWNGRADE). A PTU + scale is billable, so it defaults to ``max_retries=0`` and carries + an idempotency key. Scaling to all-zero is not a delete. ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` before any error check, so a caller can read the status, headers and ``elapsed`` of the response or re-parse it itself. """ + body = _build_scale_body( + deployed_model, + capacity, + ptu_capacity, + instance_id, + pre_paid_info, + order_type, + ) + headers = extra_headers + if ptu_capacity is not None: + max_retries = _purchase_retries(max_retries) + headers = _idempotency_headers(extra_headers) + deployed_model = _path_id(deployed_model, "deployed_model") resp = self._client.transport.request_api( "PUT", f"{_BASE_PATH}/{deployed_model}/scale", - json={"deployed_model": deployed_model, "capacity": capacity}, + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + def renew( + self, + deployed_model: str, + *, + pre_paid_info: Any, + instance_id: Optional[str] = None, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Deployment: + ... + + @overload + def renew( + self, + deployed_model: str, + *, + pre_paid_info: Any, + instance_id: Optional[str] = None, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def renew( + self, + deployed_model: str, + *, + pre_paid_info: Any, + instance_id: Optional[str] = None, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Deployment, "APIResponse"]: + """Renew a pre-paid PTU ModelCode (no ``order_type`` on renew). + + ``pre_paid_info`` is required; ``instance_id`` selects one instance + when the ModelCode holds several. Changing ``ptu_capacity`` requires + ``is_change=True``. Billable, so defaults to ``max_retries=0`` with + an idempotency key. Returns the refreshed :class:`Deployment`. + + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + deployed_model = _path_id(deployed_model, "deployed_model") + body = _renew_body(pre_paid_info, is_change, ptu_capacity, instance_id) + resp = self._client.transport.request_api( + "PUT", + f"{_BASE_PATH}/{deployed_model}/renew", + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + _idempotency_headers(extra_headers), + extra_query, + extra_body, + max_retries=_purchase_retries(max_retries), + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + def update_overflow_strategy( + self, + deployed_model: str, + *, + overflow_strategy: str, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Deployment: + ... + + @overload + def update_overflow_strategy( + self, + deployed_model: str, + *, + overflow_strategy: str, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def update_overflow_strategy( + self, + deployed_model: str, + *, + overflow_strategy: str, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Deployment, "APIResponse"]: + """Set the whole-ModelCode overflow strategy (lowercase). + + ``enable`` lets traffic beyond the reserved capacity overflow to + pay-as-you-go (extra cost); ``disable`` throttles it. This is a + config toggle, not a purchase, so normal retries apply. + + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + if overflow_strategy not in ("enable", "disable"): + raise ValueError("overflow_strategy must be 'enable' or 'disable'") + deployed_model = _path_id(deployed_model, "deployed_model") + resp = self._client.transport.request_api( + "PUT", + f"{_BASE_PATH}/{deployed_model}/update-overflowstrategy", + json={"overflow_strategy": overflow_strategy}, sdk_module=MODULE, timeout=timeout, api_key=api_key, @@ -624,6 +975,7 @@ def delete( before any error check, so a caller can read the status, headers and ``elapsed`` of the response or re-parse it itself. """ + deployed_model = _path_id(deployed_model, "deployed_model") resp = self._client.transport.request_api( "DELETE", f"{_BASE_PATH}/{deployed_model}", @@ -663,6 +1015,7 @@ def stream_events( extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, ) -> Iterator[DeploymentEvent]: + deployed_model_id = _path_id(deployed_model_id, "deployed_model_id") response = self._client.transport.open_stream( "GET", f"{_BASE_PATH}/{deployed_model_id}/stream", @@ -706,19 +1059,26 @@ def stream_events( class AsyncDeployments: def __init__(self, client) -> None: self._client = client + self.capacity_instances = AsyncCapacityInstances(client) + self.capacity_operations = AsyncCapacityOperations(client) @overload async def create( self, *, model: str, - capacity: int, + capacity: Optional[int] = None, model_version: Optional[str] = None, suffix: Optional[str] = None, plan: Optional[str] = None, template_id: Optional[str] = None, deploy_spec: Optional[Dict[str, Any]] = None, billing_method: Optional[str] = None, + service_tier: Optional[str] = None, + charge_type: Optional[str] = None, + ptu_capacity: Any = None, + pre_paid_info: Any = None, + name: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -735,13 +1095,18 @@ async def create( self, *, model: str, - capacity: int, + capacity: Optional[int] = None, model_version: Optional[str] = None, suffix: Optional[str] = None, plan: Optional[str] = None, template_id: Optional[str] = None, deploy_spec: Optional[Dict[str, Any]] = None, billing_method: Optional[str] = None, + service_tier: Optional[str] = None, + charge_type: Optional[str] = None, + ptu_capacity: Any = None, + pre_paid_info: Any = None, + name: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -757,13 +1122,18 @@ async def create( self, *, model: str, - capacity: int, + capacity: Optional[int] = None, model_version: Optional[str] = None, suffix: Optional[str] = None, plan: Optional[str] = None, template_id: Optional[str] = None, deploy_spec: Optional[Dict[str, Any]] = None, billing_method: Optional[str] = None, + service_tier: Optional[str] = None, + charge_type: Optional[str] = None, + ptu_capacity: Any = None, + pre_paid_info: Any = None, + name: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -773,11 +1143,14 @@ async def create( max_retries: Optional[int] = None, raw: bool = False, ) -> Union[Deployment, "APIResponse"]: - """Create a deployment of ``model`` with ``capacity`` instances. + """Create a deployment of ``model`` (async twin of ``Deployments.create``). + + PTU throughput reservation (``plan="ptu"``) is a billable purchase + and defaults to ``max_retries=0``; see the sync method for the full + contract and safeguards. ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` - before any error check, so a caller can read the status, headers and - ``elapsed`` of the response or re-parse it itself. + before any error check. """ body = _build_create_body( model, @@ -788,7 +1161,14 @@ async def create( template_id, deploy_spec, billing_method, + service_tier, + charge_type, + ptu_capacity, + pre_paid_info, + name, ) + if plan == "ptu": + max_retries = _purchase_retries(max_retries) resp = await self._client.transport.request_api( "POST", _BASE_PATH, @@ -868,6 +1248,7 @@ async def get( before any error check, so a caller can read the status, headers and ``elapsed`` of the response or re-parse it itself. """ + deployed_model = _path_id(deployed_model, "deployed_model") resp = await self._client.transport.request_api( "GET", f"{_BASE_PATH}/{deployed_model}", @@ -982,7 +1363,11 @@ async def scale( self, deployed_model: str, *, - capacity: int, + capacity: Optional[int] = None, + ptu_capacity: Any = None, + instance_id: Optional[str] = None, + pre_paid_info: Any = None, + order_type: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -999,7 +1384,11 @@ async def scale( self, deployed_model: str, *, - capacity: int, + capacity: Optional[int] = None, + ptu_capacity: Any = None, + instance_id: Optional[str] = None, + pre_paid_info: Any = None, + order_type: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -1015,7 +1404,11 @@ async def scale( self, deployed_model: str, *, - capacity: int, + capacity: Optional[int] = None, + ptu_capacity: Any = None, + instance_id: Optional[str] = None, + pre_paid_info: Any = None, + order_type: Optional[str] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -1025,16 +1418,212 @@ async def scale( max_retries: Optional[int] = None, raw: bool = False, ) -> Union[Deployment, "APIResponse"]: - """Resize a deployment to ``capacity`` instances. + """Resize a deployment (async twin of ``Deployments.scale``). + + PTU ``ptu_capacity`` is an absolute target and billable, so it + defaults to ``max_retries=0`` with an idempotency key. ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` - before any error check, so a caller can read the status, headers and - ``elapsed`` of the response or re-parse it itself. + before any error check. """ + body = _build_scale_body( + deployed_model, + capacity, + ptu_capacity, + instance_id, + pre_paid_info, + order_type, + ) + headers = extra_headers + if ptu_capacity is not None: + max_retries = _purchase_retries(max_retries) + headers = _idempotency_headers(extra_headers) + deployed_model = _path_id(deployed_model, "deployed_model") resp = await self._client.transport.request_api( "PUT", f"{_BASE_PATH}/{deployed_model}/scale", - json={"deployed_model": deployed_model, "capacity": capacity}, + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + async def renew( + self, + deployed_model: str, + *, + pre_paid_info: Any, + instance_id: Optional[str] = None, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Deployment: + ... + + @overload + async def renew( + self, + deployed_model: str, + *, + pre_paid_info: Any, + instance_id: Optional[str] = None, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def renew( + self, + deployed_model: str, + *, + pre_paid_info: Any, + instance_id: Optional[str] = None, + is_change: Optional[bool] = None, + ptu_capacity: Any = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Deployment, "APIResponse"]: + """Renew a pre-paid PTU ModelCode (async twin of ``Deployments.renew``). + + Billable, so defaults to ``max_retries=0`` with an idempotency key. + + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + deployed_model = _path_id(deployed_model, "deployed_model") + body = _renew_body(pre_paid_info, is_change, ptu_capacity, instance_id) + resp = await self._client.transport.request_api( + "PUT", + f"{_BASE_PATH}/{deployed_model}/renew", + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + _idempotency_headers(extra_headers), + extra_query, + extra_body, + max_retries=_purchase_retries(max_retries), + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + async def update_overflow_strategy( + self, + deployed_model: str, + *, + overflow_strategy: str, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Deployment: + ... + + @overload + async def update_overflow_strategy( + self, + deployed_model: str, + *, + overflow_strategy: str, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def update_overflow_strategy( + self, + deployed_model: str, + *, + overflow_strategy: str, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Deployment, "APIResponse"]: + """Set the whole-ModelCode overflow strategy (async twin). + + ``enable`` overflows to pay-as-you-go (extra cost); ``disable`` + throttles. Config toggle, so normal retries apply. + + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + if overflow_strategy not in ("enable", "disable"): + raise ValueError("overflow_strategy must be 'enable' or 'disable'") + deployed_model = _path_id(deployed_model, "deployed_model") + resp = await self._client.transport.request_api( + "PUT", + f"{_BASE_PATH}/{deployed_model}/update-overflowstrategy", + json={"overflow_strategy": overflow_strategy}, sdk_module=MODULE, timeout=timeout, api_key=api_key, @@ -1110,6 +1699,7 @@ async def delete( before any error check, so a caller can read the status, headers and ``elapsed`` of the response or re-parse it itself. """ + deployed_model = _path_id(deployed_model, "deployed_model") resp = await self._client.transport.request_api( "DELETE", f"{_BASE_PATH}/{deployed_model}", @@ -1149,6 +1739,7 @@ async def stream_events( extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, ) -> AsyncIterator[DeploymentEvent]: + deployed_model_id = _path_id(deployed_model_id, "deployed_model_id") response = await self._client.transport.open_stream( "GET", f"{_BASE_PATH}/{deployed_model_id}/stream", diff --git a/dashscope/resources/files.py b/dashscope/resources/files.py index 38f40b5d..fc7e1472 100644 --- a/dashscope/resources/files.py +++ b/dashscope/resources/files.py @@ -213,6 +213,11 @@ def _is_valid_jsonl(file_path: str) -> bool: try: with open(file_path, encoding="utf-8") as f: for line in f: + # Blank lines are skipped, matching the batch row scanner + # (batches._validate_input_rows) so validate_input and the + # upload gate agree on the same file. + if not line.strip(): + continue try: json.loads(line) except json.decoder.JSONDecodeError: diff --git a/dashscope/resources/fine_tunes.py b/dashscope/resources/fine_tunes.py index c1d39c62..6741bea6 100644 --- a/dashscope/resources/fine_tunes.py +++ b/dashscope/resources/fine_tunes.py @@ -318,6 +318,11 @@ def _build_create_body( class FineTunes: def __init__(self, client) -> None: self._client = client + # Lazy import: fine_tunes_compress imports JobLogs from this module, + # so a top-level import here would be circular. + from dashscope.resources.fine_tunes_compress import Compress + + self.compress = Compress(client) @overload def create( @@ -958,6 +963,9 @@ def _check_terminal(self, job: FineTune, job_id: str) -> FineTune: class AsyncFineTunes: def __init__(self, client) -> None: self._client = client + from dashscope.resources.fine_tunes_compress import AsyncCompress + + self.compress = AsyncCompress(client) @overload async def create( diff --git a/dashscope/resources/fine_tunes_compress.py b/dashscope/resources/fine_tunes_compress.py new file mode 100644 index 00000000..8a3b5c17 --- /dev/null +++ b/dashscope/resources/fine_tunes_compress.py @@ -0,0 +1,1913 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""client.fine_tunes.compress -- model compression (quantization) jobs. + +A REST job plane nested under fine-tunes, mirroring the parent's +create/get/list/logs/cancel/delete/wait surface rather than the +``/services`` + ``/tasks`` async pattern: the wire contract is +``/api/v1/fine-tunes/compress`` with ``templates`` and ``jobs`` beneath it. + +Compression is quantization-only and currently Beijing-region only; the +base model must be a full-parameter fine-tune (LoRA / already-quantized +models are not supported). The produced ``quantized_output`` model name +feeds ``deployments``. Auth is the same API-Key Bearer as the rest of the +core Client, so this lives here rather than in a RAM ManagementClient. +""" + +from __future__ import annotations + +import asyncio +import re +import time +from typing import ( + TYPE_CHECKING, + Any, + Awaitable, + Callable, + Dict, + List, + Literal, + Mapping, + Optional, + Union, + overload, +) + +from pydantic import BaseModel, ConfigDict + +from dashscope.errors import ( + DashScopeError, + error_from_business_code, +) +from dashscope.resources._jobs import ( + CANCELED, + DEFAULT_MAX_INTERVAL, + DEFAULT_POLL_INTERVAL, + DEFAULT_WAIT_TIMEOUT, + FAILED, + SUCCEEDED, +) +from dashscope.resources.fine_tunes import JobLogs +from dashscope.transport._options import request_options +from dashscope.types._parse import parse_model +from dashscope.types.common import ( + JobStatus, + ResponseBase, + flatten_envelope, + response_envelope, + with_headers, +) +from dashscope.types.pagination import BasePage + +if TYPE_CHECKING: + import httpx + + from dashscope.transport._response import APIResponse + +_BASE_PATH = "/fine-tunes/compress" + +MODULE = "finetune" + +__all__ = [ + "AsyncCompress", + "AsyncCompressJobs", + "AsyncCompressTemplates", + "Compress", + "CompressCustomModel", + "CompressError", + "CompressHyperParameter", + "CompressJob", + "CompressJobList", + "CompressJobs", + "CompressTemplate", + "CompressTemplateList", + "CompressTemplates", +] + +_TERMINAL = frozenset({SUCCEEDED, FAILED, CANCELED}) + +_SUFFIX_RE = re.compile(r"[a-z0-9]{1,8}") + + +class CompressError(BaseModel): + """The ``error`` object a failed compress job carries.""" + + model_config = ConfigDict(extra="allow") + + code: Optional[str] = None + message: Optional[str] = None + + +class CompressJob(ResponseBase): + """One compression job. + + The same type comes back from ``create`` / ``get`` and is nested in + ``CompressJobList.jobs``. A failed job reports its own ``error`` object + alongside the response envelope, so both stay readable. + """ + + job_id: Optional[str] = None + job_name: Optional[str] = None + job_description: Optional[str] = None + status: Optional[str] = None + model: Optional[str] = None + base_model: Optional[str] = None + template_id: Optional[str] = None + template_name: Optional[str] = None + template_description: Optional[str] = None + training_type: Optional[str] = None + compress_type: Optional[str] = None + hyper_parameters: Dict[str, Any] = {} + custom_calibration_file_ids: List[str] = [] + quantized_output: Optional[str] = None + create_time: Optional[str] = None + start_time: Optional[str] = None + end_time: Optional[str] = None + error: Optional[CompressError] = None + group: Optional[str] = None + # GPU seconds (Integer on the wire), present on SUCCEEDED / CANCELED. + usage: Optional[int] = None + + @property + def task_id(self) -> Optional[str]: + """``Job`` spells the same identifier ``task_id``.""" + return self.job_id + + @property + def succeeded(self) -> bool: + return self.status == SUCCEEDED + + @property + def finished(self) -> bool: + return self.status in _TERMINAL + + +class CompressJobList(BasePage[CompressJob]): + """One page of compression jobs, from ``compress.jobs.list``. + + ``page_no`` / ``page_size`` / ``total_count`` come from + :class:`~dashscope.types.pagination.BasePage`; iterate the page directly + or cross pages with ``iter_pages()`` / ``next_page()``. + """ + + jobs: List[CompressJob] = [] + + @property + def items(self) -> List[CompressJob]: + return self.jobs + + @property + def total(self) -> int: + """Alias of ``total_count``, keeping the wire field name readable.""" + return self.total_count + + +class CompressHyperParameter(BaseModel): + """One tunable hyper-parameter descriptor a template advertises. + + ``type=string`` carries ``support_values`` (an enum); ``type=number`` + carries ``data_range`` + ``step``. The ``name`` is the key to use when + overriding ``hyper_parameters`` on ``jobs.create``. + """ + + model_config = ConfigDict(extra="allow") + + name: Optional[str] = None + type: Optional[str] = None + display_name: Optional[str] = None + description: Optional[str] = None + defaultValue: Optional[str] = None + recommend_value: Optional[str] = None + required: Optional[bool] = None + support_values: List[str] = [] + data_range: List[str] = [] + step: Optional[int] = None + + +class CompressTemplate(BaseModel): + """One compression template bound to a custom model. + + Nested under ``CompressCustomModel.templates``; the wire field is + ``description`` (not ``template_description``) and ``hyper_parameters`` + is an array of descriptors, empty when nothing is tunable. + """ + + model_config = ConfigDict(extra="allow") + + template_id: Optional[str] = None + template_name: Optional[str] = None + description: Optional[str] = None + compress_type: Optional[str] = None + hyper_parameters: List[CompressHyperParameter] = [] + + +class CompressCustomModel(BaseModel): + """One quantizable custom fine-tune and the templates it supports.""" + + model_config = ConfigDict(extra="allow") + + model: Optional[str] = None + model_name: Optional[str] = None + base_model: Optional[str] = None + templates: List[CompressTemplate] = [] + + +class CompressTemplateList(ResponseBase): + """The quantization catalog from ``compress.templates.list``. + + Not paginated: the server returns every quantizable custom model and + its templates in one shot, alongside the supported ``base_models``. + """ + + base_models: List[str] = [] + custom_models: List[CompressCustomModel] = [] + + @property + def templates(self) -> List[CompressTemplate]: + """Every template across all custom models, flattened for convenience.""" + return [t for m in self.custom_models for t in m.templates] + + +def _parse_job( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> CompressJob: + return parse_model( + CompressJob, + flatten_envelope(body), + strict=strict, + response=response, + ) + + +def _parse_list( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> CompressJobList: + data = flatten_envelope(body) + jobs = data.get("jobs") + if not isinstance(jobs, list): + # A retyped ``jobs`` would poison the ``len()`` below; empty is the + # honest reading of "not a list", matching ``fine_tunes._parse_list``. + jobs = [] + return parse_model( + CompressJobList, + { + "page_no": data.get("page_no", 1), + "page_size": data.get("page_size", 10), + "total_count": data.get("total", len(jobs)), + "jobs": jobs, + **response_envelope(data), + }, + strict=strict, + response=response, + ) + + +def _parse_templates( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> CompressTemplateList: + data = flatten_envelope(body) + base_models = data.get("base_models") + custom_models = data.get("custom_models") + return parse_model( + CompressTemplateList, + { + "base_models": base_models + if isinstance(base_models, list) + else [], + "custom_models": ( + custom_models if isinstance(custom_models, list) else [] + ), + **response_envelope(data), + }, + strict=strict, + response=response, + ) + + +def _parse_status( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> JobStatus: + return parse_model( + JobStatus, + flatten_envelope(body), + strict=strict, + response=response, + ) + + +def _parse_logs( + job_id: str, + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> JobLogs: + data = flatten_envelope(body) + return parse_model( + JobLogs, + { + "job_id": job_id, + "content": data.get("logs") or "", + **response_envelope(data), + }, + strict=strict, + response=response, + ) + + +def _job_id(job: Union[CompressJob, str]) -> str: + job_id = job.job_id if isinstance(job, CompressJob) else job + if not job_id: + raise DashScopeError("compress job id required") + return job_id + + +def _build_create_body( + model: str, + template_id: str, + *, + job_name: Optional[str], + job_description: Optional[str], + hyper_parameters: Optional[Dict[str, Any]], + custom_calibration_file_ids: Union[List[str], str, None], + output_model_suffix: Optional[str], +) -> Dict[str, Any]: + body: Dict[str, Any] = {"model": model, "template_id": template_id} + if job_name is not None: + if len(job_name) > 50: + raise DashScopeError("job_name must be at most 50 characters") + body["job_name"] = job_name + if job_description is not None: + if len(job_description) > 200: + raise DashScopeError( + "job_description must be at most 200 characters", + ) + body["job_description"] = job_description + if hyper_parameters is not None: + body["hyper_parameters"] = hyper_parameters + if custom_calibration_file_ids is not None: + if isinstance(custom_calibration_file_ids, str): + custom_calibration_file_ids = [custom_calibration_file_ids] + body["custom_calibration_file_ids"] = custom_calibration_file_ids + if output_model_suffix is not None: + # The server names the quantized model ``{base}-{suffix}-{job_id}`` + # and rejects anything outside lowercase letters + digits, max 8. + if not _SUFFIX_RE.fullmatch(output_model_suffix): + raise DashScopeError( + "output_model_suffix must be 1-8 lowercase letters/digits", + ) + body["output_model_suffix"] = output_model_suffix + return body + + +def _build_job_list_params( + page_no: int, + page_size: int, + *, + status: Optional[str], + model: Optional[str], + template_id: Optional[str], + quant_spec: Optional[str], + quant_method: Optional[str], + start_time: Optional[str], + end_time: Optional[str], + job_name: Optional[str], + job_id: Optional[str], + search_key: Optional[str], + select_key: Optional[str], + sort_by: Optional[str], + sort_order: Optional[str], +) -> Dict[str, Any]: + params: Dict[str, Any] = {"page_no": page_no, "page_size": page_size} + for key, value in ( + ("status", status), + ("model", model), + ("template_id", template_id), + ("quant_spec", quant_spec), + ("quant_method", quant_method), + ("start_time", start_time), + ("end_time", end_time), + ("job_name", job_name), + ("job_id", job_id), + ("search_key", search_key), + ("select_key", select_key), + ("sort_by", sort_by), + ("sort_order", sort_order), + ): + if value is not None: + params[key] = value + return params + + +class CompressTemplates: + """``client.fine_tunes.compress.templates`` -- list quantization templates.""" + + def __init__(self, client) -> None: + self._client = client + + @overload + def list( + self, + *, + model: Optional[str] = None, + lang: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CompressTemplateList: + ... + + @overload + def list( + self, + *, + model: Optional[str] = None, + lang: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + model: Optional[str] = None, + lang: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CompressTemplateList, "APIResponse"]: + """List the quantization catalog (not paginated). + + Returns every quantizable custom model and its templates, plus the + supported ``base_models``. ``model`` filters by model ID (a base + model name returns all custom models derived from it); ``lang`` + selects ``zh-CN`` / ``en-US`` for the localized template text. + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + params: Dict[str, Any] = {} + if model is not None: + params["model"] = model + if lang is not None: + params["lang"] = lang + resp = self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/templates", + params=params, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + result = _parse_templates( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ) + return with_headers(result, resp.http_response) + + +class CompressJobs: + """``client.fine_tunes.compress.jobs`` -- compression job lifecycle.""" + + def __init__(self, client) -> None: + self._client = client + + @overload + def create( + self, + *, + model: str, + template_id: str, + job_name: Optional[str] = None, + job_description: Optional[str] = None, + hyper_parameters: Optional[Dict[str, Any]] = None, + custom_calibration_file_ids: Union[List[str], str, None] = None, + output_model_suffix: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CompressJob: + ... + + @overload + def create( + self, + *, + model: str, + template_id: str, + job_name: Optional[str] = None, + job_description: Optional[str] = None, + hyper_parameters: Optional[Dict[str, Any]] = None, + custom_calibration_file_ids: Union[List[str], str, None] = None, + output_model_suffix: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def create( + self, + *, + model: str, + template_id: str, + job_name: Optional[str] = None, + job_description: Optional[str] = None, + hyper_parameters: Optional[Dict[str, Any]] = None, + custom_calibration_file_ids: Union[List[str], str, None] = None, + output_model_suffix: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CompressJob, "APIResponse"]: + """Create a compression (quantization) job. + + ``model`` must be a full-parameter fine-tune supported by the + template; ``template_id`` is required. The wire has no + idempotency key, so this defaults to ``max_retries=0`` (no + automatic retry) -- a retried create could otherwise spawn a + duplicate billed job. Passing ``max_retries`` explicitly + re-enables retry and the caller owns that risk. ``raw=True`` + returns the :class:`~dashscope.transport.APIResponse` before any + error check. + """ + body = _build_create_body( + model, + template_id, + job_name=job_name, + job_description=job_description, + hyper_parameters=hyper_parameters, + custom_calibration_file_ids=custom_calibration_file_ids, + output_model_suffix=output_model_suffix, + ) + resp = self._client.transport.request_api( + "POST", + f"{_BASE_PATH}/jobs", + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=0 if max_retries is None else max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_job( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + def get( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CompressJob: + ... + + @overload + def get( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def get( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CompressJob, "APIResponse"]: + """Fetch one compression job. + + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + job_id = _job_id(job_id) + resp = self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/jobs/{job_id}", + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_job( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + def list( + self, + *, + status: Optional[str] = None, + model: Optional[str] = None, + template_id: Optional[str] = None, + quant_spec: Optional[str] = None, + quant_method: Optional[str] = None, + start_time: Optional[str] = None, + end_time: Optional[str] = None, + job_name: Optional[str] = None, + job_id: Optional[str] = None, + search_key: Optional[str] = None, + select_key: Optional[str] = None, + sort_by: Optional[str] = None, + sort_order: Optional[str] = None, + page_no: int = 1, + page_size: int = 10, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CompressJobList: + ... + + @overload + def list( + self, + *, + status: Optional[str] = None, + model: Optional[str] = None, + template_id: Optional[str] = None, + quant_spec: Optional[str] = None, + quant_method: Optional[str] = None, + start_time: Optional[str] = None, + end_time: Optional[str] = None, + job_name: Optional[str] = None, + job_id: Optional[str] = None, + search_key: Optional[str] = None, + select_key: Optional[str] = None, + sort_by: Optional[str] = None, + sort_order: Optional[str] = None, + page_no: int = 1, + page_size: int = 10, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + status: Optional[str] = None, + model: Optional[str] = None, + template_id: Optional[str] = None, + quant_spec: Optional[str] = None, + quant_method: Optional[str] = None, + start_time: Optional[str] = None, + end_time: Optional[str] = None, + job_name: Optional[str] = None, + job_id: Optional[str] = None, + search_key: Optional[str] = None, + select_key: Optional[str] = None, + sort_by: Optional[str] = None, + sort_order: Optional[str] = None, + page_no: int = 1, + page_size: int = 10, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CompressJobList, "APIResponse"]: + """List compression jobs, one page at a time, with server-side filters. + + Filters are preserved across ``iter_pages()`` / ``next_page()``. + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + filter_kwargs: Dict[str, Any] = { + "status": status, + "model": model, + "template_id": template_id, + "quant_spec": quant_spec, + "quant_method": quant_method, + "start_time": start_time, + "end_time": end_time, + "job_name": job_name, + "job_id": job_id, + "search_key": search_key, + "select_key": select_key, + "sort_by": sort_by, + "sort_order": sort_order, + } + resp = self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/jobs", + params=_build_job_list_params(page_no, page_size, **filter_kwargs), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + result = _parse_list( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ) + result.bind_pagination( + lambda next_no, next_size: self.list( + page_no=next_no, + page_size=next_size, + **filter_kwargs, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + requested_page_no=page_no, + requested_page_size=page_size, + ) + return with_headers(result, resp.http_response) + + @overload + def cancel( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> JobStatus: + ... + + @overload + def cancel( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def cancel( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[JobStatus, "APIResponse"]: + """Cancel a PENDING/QUEUING/RUNNING compression job. + + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + job_id = _job_id(job_id) + resp = self._client.transport.request_api( + "POST", + f"{_BASE_PATH}/jobs/{job_id}/cancel", + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_status( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + def delete( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> JobStatus: + ... + + @overload + def delete( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def delete( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[JobStatus, "APIResponse"]: + """Delete a terminal compression job; the quantized model is kept. + + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + job_id = _job_id(job_id) + resp = self._client.transport.request_api( + "DELETE", + f"{_BASE_PATH}/jobs/{job_id}", + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_status( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + def logs( + self, + job_id: str, + *, + offset: int = 0, + lines: int = 100, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> JobLogs: + ... + + @overload + def logs( + self, + job_id: str, + *, + offset: int = 0, + lines: int = 100, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def logs( + self, + job_id: str, + *, + offset: int = 0, + lines: int = 100, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[JobLogs, "APIResponse"]: + """Fetch logs of one compression job. + + ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` + before any error check. + """ + job_id = _job_id(job_id) + resp = self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/jobs/{job_id}/logs", + # The wire parameter is singular "line". + params={"offset": offset, "line": lines}, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_logs( + job_id, + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + def wait( + self, + job: Union[CompressJob, str], + *, + poll_interval: float = DEFAULT_POLL_INTERVAL, + max_interval: float = DEFAULT_MAX_INTERVAL, + timeout: float = DEFAULT_WAIT_TIMEOUT, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + _sleep: Optional[Callable[[float], Any]] = None, + ) -> CompressJob: + """Poll until the job reaches a terminal status. + + With ``raise_on_error=False`` a transport-level failure comes back + as the :class:`CompressJob` envelope instead of raising. ``_sleep`` + is a test seam — it replaces the pause between polls. + """ + job_id = _job_id(job) + sleep_fn = _sleep or time.sleep + deadline = time.monotonic() + timeout + current = ( + job + if isinstance(job, CompressJob) + else self.get( + job_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + ) + interval = poll_interval + while not current.finished: + if current.is_error: + return current + remaining = deadline - time.monotonic() + if remaining <= 0: + raise DashScopeError( + f"timed out after {timeout}s waiting for" + f" compress job {job_id}", + ) + sleep_fn(min(interval, remaining)) + interval = min(interval * 2, max_interval) + current = self.get( + job_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + return self._check_terminal(current, job_id) + + def _check_terminal(self, job: CompressJob, job_id: str) -> CompressJob: + if job.status == FAILED and self._client.raise_on_error: + err = job.error + raise error_from_business_code( + message=( + job.message + or (err.message if err else None) + or f"compress job {job_id} failed" + ), + code=job.code or (err.code if err else None), + body=job.model_dump(exclude={"headers"}), + headers=job.headers, + ) + if job.status == CANCELED and self._client.raise_on_error: + raise DashScopeError( + f"compress job {job_id} was canceled while waiting", + request_id=job.request_id, + ) + return job + + +class Compress: + """``client.fine_tunes.compress`` -- templates + jobs sub-resources.""" + + def __init__(self, client) -> None: + self._client = client + self.templates = CompressTemplates(client) + self.jobs = CompressJobs(client) + + +class AsyncCompressTemplates: + """Async counterpart of :class:`CompressTemplates`.""" + + def __init__(self, client) -> None: + self._client = client + + @overload + async def list( + self, + *, + model: Optional[str] = None, + lang: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CompressTemplateList: + ... + + @overload + async def list( + self, + *, + model: Optional[str] = None, + lang: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + model: Optional[str] = None, + lang: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CompressTemplateList, "APIResponse"]: + """Async twin of :meth:`CompressTemplates.list`.""" + params: Dict[str, Any] = {} + if model is not None: + params["model"] = model + if lang is not None: + params["lang"] = lang + resp = await self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/templates", + params=params, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + result = _parse_templates( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ) + return with_headers(result, resp.http_response) + + +class AsyncCompressJobs: + """Async counterpart of :class:`CompressJobs`.""" + + def __init__(self, client) -> None: + self._client = client + + @overload + async def create( + self, + *, + model: str, + template_id: str, + job_name: Optional[str] = None, + job_description: Optional[str] = None, + hyper_parameters: Optional[Dict[str, Any]] = None, + custom_calibration_file_ids: Union[List[str], str, None] = None, + output_model_suffix: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CompressJob: + ... + + @overload + async def create( + self, + *, + model: str, + template_id: str, + job_name: Optional[str] = None, + job_description: Optional[str] = None, + hyper_parameters: Optional[Dict[str, Any]] = None, + custom_calibration_file_ids: Union[List[str], str, None] = None, + output_model_suffix: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def create( + self, + *, + model: str, + template_id: str, + job_name: Optional[str] = None, + job_description: Optional[str] = None, + hyper_parameters: Optional[Dict[str, Any]] = None, + custom_calibration_file_ids: Union[List[str], str, None] = None, + output_model_suffix: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CompressJob, "APIResponse"]: + """Async twin of :meth:`CompressJobs.create`.""" + body = _build_create_body( + model, + template_id, + job_name=job_name, + job_description=job_description, + hyper_parameters=hyper_parameters, + custom_calibration_file_ids=custom_calibration_file_ids, + output_model_suffix=output_model_suffix, + ) + resp = await self._client.transport.request_api( + "POST", + f"{_BASE_PATH}/jobs", + json=body, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=0 if max_retries is None else max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_job( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + async def get( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CompressJob: + ... + + @overload + async def get( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def get( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CompressJob, "APIResponse"]: + """Async twin of :meth:`CompressJobs.get`.""" + job_id = _job_id(job_id) + resp = await self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/jobs/{job_id}", + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_job( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + async def list( + self, + *, + status: Optional[str] = None, + model: Optional[str] = None, + template_id: Optional[str] = None, + quant_spec: Optional[str] = None, + quant_method: Optional[str] = None, + start_time: Optional[str] = None, + end_time: Optional[str] = None, + job_name: Optional[str] = None, + job_id: Optional[str] = None, + search_key: Optional[str] = None, + select_key: Optional[str] = None, + sort_by: Optional[str] = None, + sort_order: Optional[str] = None, + page_no: int = 1, + page_size: int = 10, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> CompressJobList: + ... + + @overload + async def list( + self, + *, + status: Optional[str] = None, + model: Optional[str] = None, + template_id: Optional[str] = None, + quant_spec: Optional[str] = None, + quant_method: Optional[str] = None, + start_time: Optional[str] = None, + end_time: Optional[str] = None, + job_name: Optional[str] = None, + job_id: Optional[str] = None, + search_key: Optional[str] = None, + select_key: Optional[str] = None, + sort_by: Optional[str] = None, + sort_order: Optional[str] = None, + page_no: int = 1, + page_size: int = 10, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + status: Optional[str] = None, + model: Optional[str] = None, + template_id: Optional[str] = None, + quant_spec: Optional[str] = None, + quant_method: Optional[str] = None, + start_time: Optional[str] = None, + end_time: Optional[str] = None, + job_name: Optional[str] = None, + job_id: Optional[str] = None, + search_key: Optional[str] = None, + select_key: Optional[str] = None, + sort_by: Optional[str] = None, + sort_order: Optional[str] = None, + page_no: int = 1, + page_size: int = 10, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[CompressJobList, "APIResponse"]: + """Async twin of :meth:`CompressJobs.list`.""" + filter_kwargs: Dict[str, Any] = { + "status": status, + "model": model, + "template_id": template_id, + "quant_spec": quant_spec, + "quant_method": quant_method, + "start_time": start_time, + "end_time": end_time, + "job_name": job_name, + "job_id": job_id, + "search_key": search_key, + "select_key": select_key, + "sort_by": sort_by, + "sort_order": sort_order, + } + resp = await self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/jobs", + params=_build_job_list_params(page_no, page_size, **filter_kwargs), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + result = _parse_list( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ) + result.bind_pagination( + lambda next_no, next_size: self.list( + page_no=next_no, + page_size=next_size, + **filter_kwargs, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + requested_page_no=page_no, + requested_page_size=page_size, + ) + return with_headers(result, resp.http_response) + + @overload + async def cancel( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> JobStatus: + ... + + @overload + async def cancel( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def cancel( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[JobStatus, "APIResponse"]: + """Async twin of :meth:`CompressJobs.cancel`.""" + job_id = _job_id(job_id) + resp = await self._client.transport.request_api( + "POST", + f"{_BASE_PATH}/jobs/{job_id}/cancel", + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_status( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + async def delete( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> JobStatus: + ... + + @overload + async def delete( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def delete( + self, + job_id: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[JobStatus, "APIResponse"]: + """Async twin of :meth:`CompressJobs.delete`.""" + job_id = _job_id(job_id) + resp = await self._client.transport.request_api( + "DELETE", + f"{_BASE_PATH}/jobs/{job_id}", + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_status( + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + @overload + async def logs( + self, + job_id: str, + *, + offset: int = 0, + lines: int = 100, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> JobLogs: + ... + + @overload + async def logs( + self, + job_id: str, + *, + offset: int = 0, + lines: int = 100, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def logs( + self, + job_id: str, + *, + offset: int = 0, + lines: int = 100, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[JobLogs, "APIResponse"]: + """Async twin of :meth:`CompressJobs.logs`.""" + job_id = _job_id(job_id) + resp = await self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/jobs/{job_id}/logs", + # The wire parameter is singular "line". + params={"offset": offset, "line": lines}, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + return with_headers( + _parse_logs( + job_id, + resp.json(), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + async def wait( + self, + job: Union[CompressJob, str], + *, + poll_interval: float = DEFAULT_POLL_INTERVAL, + max_interval: float = DEFAULT_MAX_INTERVAL, + timeout: float = DEFAULT_WAIT_TIMEOUT, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + _sleep: Optional[Callable[[float], Awaitable[None]]] = None, + ) -> CompressJob: + """Async twin of :meth:`CompressJobs.wait`, same compat-mode contract.""" + job_id = _job_id(job) + sleep_fn = _sleep or asyncio.sleep + deadline = time.monotonic() + timeout + current = ( + job + if isinstance(job, CompressJob) + else await self.get( + job_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + ) + interval = poll_interval + while not current.finished: + if current.is_error: + return current + remaining = deadline - time.monotonic() + if remaining <= 0: + raise DashScopeError( + f"timed out after {timeout}s waiting for" + f" compress job {job_id}", + ) + await sleep_fn(min(interval, remaining)) + interval = min(interval * 2, max_interval) + current = await self.get( + job_id, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ) + return self._check_terminal(current, job_id) + + def _check_terminal(self, job: CompressJob, job_id: str) -> CompressJob: + if job.status == FAILED and self._client.raise_on_error: + err = job.error + raise error_from_business_code( + message=( + job.message + or (err.message if err else None) + or f"compress job {job_id} failed" + ), + code=job.code or (err.code if err else None), + body=job.model_dump(exclude={"headers"}), + headers=job.headers, + ) + if job.status == CANCELED and self._client.raise_on_error: + raise DashScopeError( + f"compress job {job_id} was canceled while waiting", + request_id=job.request_id, + ) + return job + + +class AsyncCompress: + """Async counterpart of :class:`Compress`.""" + + def __init__(self, client) -> None: + self._client = client + self.templates = AsyncCompressTemplates(client) + self.jobs = AsyncCompressJobs(client) diff --git a/dashscope/resources/messages.py b/dashscope/resources/messages.py new file mode 100644 index 00000000..d7a4a03e --- /dev/null +++ b/dashscope/resources/messages.py @@ -0,0 +1,937 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""client.messages -- Anthropic-compatible Messages API (C3). + +A *native* Anthropic Messages resource: ``create`` returns an +:class:`~dashscope.types.AnthropicMessage` whose ``content`` array carries +typed blocks (text / thinking / tool_use / server-tool results), and +``stream=True`` returns a :class:`MessageStream` of native SSE events. +This is distinct from ``Client(protocol="anthropic").chat``, which +normalizes the same wire onto canonical chat types; both paths share the +web-search billing-header injection so they behave identically. + +Routing differs from the compatible-mode resources: Messages lives at +``{base}/apps/anthropic/v1/messages`` (base does not end in ``/v1``), via +``anthropic_base_url`` -- the chat ``protocol`` setting cannot move it. +Every call tags ``sdk_module`` ``messages`` for the +``x-dashscope-sdk-client`` header. + +Bailian specifics honoured here: ``temperature`` range is [0, 2) (not the +official [0, 1]); ``output_config`` (effort + structured-output format), +block-level and top-level ``cache_control``, ``document`` / ``video`` +blocks and ``thinking.display`` are first-class; ``thinking.budget_tokens`` +is deprecated in favour of ``output_config.effort``. There is no +``count_tokens`` and no ``/v1/models`` on this endpoint (use +``client.models`` for discovery). + +Contract: +https://help.aliyun.com/zh/model-studio/anthropic-api-messages +""" + +from __future__ import annotations + +import functools +import json +import warnings +from typing import ( + TYPE_CHECKING, + Any, + Dict, + Iterator, + List, + Literal, + Mapping, + Optional, + Sequence, + Union, + overload, +) + +from pydantic import BaseModel + +from dashscope._config import Config, anthropic_base_url +from dashscope.errors import DashScopeError, response_error +from dashscope.protocols.anthropic import ( + AnthropicProtocol, + ensure_billing_header, +) +from dashscope.transport._options import request_options +from dashscope.transport.sse import AsyncStream, Stream +from dashscope.types.anthropic_messages import ( + AnthropicMessage, + AnthropicStreamEvent, + parse_message, + parse_message_stream_event, +) +from dashscope.types.common import with_headers + +if TYPE_CHECKING: + import httpx + + from dashscope.transport._response import APIResponse + +_MESSAGES_PATH = "/v1/messages" + +MODULE = "messages" + +# Bailian widens the official Anthropic [0, 1] range to [0, 2). +_MIN_TEMPERATURE = 0.0 +_MAX_TEMPERATURE = 2.0 + +_BUDGET_TOKENS_WARNED = False + +MessagesInput = Sequence[Union[Mapping[str, Any], BaseModel]] +SystemInput = Union[str, Sequence[Union[Mapping[str, Any], BaseModel]]] +Tools = Sequence[Union[Mapping[str, Any], BaseModel]] +ConfigInput = Union[Mapping[str, Any], BaseModel] +ToolChoiceInput = Union[str, Mapping[str, Any], BaseModel] + + +def _endpoint_base(config: Config) -> str: + # Messages sits under /apps/anthropic on every gateway; the chat + # protocol setting must not move it. + return anthropic_base_url( + config.workspace, + config.region, + config.configured_base_url, + ) + + +def _normalize_items( + value: Sequence[Union[Mapping[str, Any], BaseModel]], +) -> List[Dict[str, Any]]: + items: List[Dict[str, Any]] = [] + for item in value: + if isinstance(item, BaseModel): + items.append(item.model_dump(exclude_none=True)) + elif isinstance(item, Mapping): + items.append(dict(item)) + else: + raise ValueError( + "each item must be a mapping or a pydantic model", + ) + return items + + +def _normalize_config( + value: Optional[ConfigInput], +) -> Optional[Dict[str, Any]]: + if value is None: + return None + if isinstance(value, BaseModel): + return value.model_dump(exclude_none=True) + return dict(value) + + +def _normalize_system(value: Optional[SystemInput]) -> Optional[Any]: + if value is None: + return None + if isinstance(value, str): + return value + return _normalize_items(value) + + +def _normalize_tool_choice(value: ToolChoiceInput) -> Dict[str, Any]: + if isinstance(value, str): + return {"type": value} + if isinstance(value, BaseModel): + return value.model_dump(exclude_none=True) + if isinstance(value, Mapping): + return dict(value) + raise ValueError( + "tool_choice must be a string, mapping or pydantic model", + ) + + +def _validate_temperature(temperature: Optional[float]) -> None: + if temperature is None: + return + if not _MIN_TEMPERATURE <= temperature < _MAX_TEMPERATURE: + raise ValueError( + "temperature must be in [0, 2) on the Bailian Messages API " + "(the official Anthropic [0, 1] range does not apply)", + ) + + +def _warn_budget_tokens() -> None: + global _BUDGET_TOKENS_WARNED # pylint: disable=global-statement + if _BUDGET_TOKENS_WARNED: + return + _BUDGET_TOKENS_WARNED = True + warnings.warn( + "thinking.budget_tokens is deprecated on the Messages API; use " + "output_config={'effort': ...} instead", + category=DeprecationWarning, + stacklevel=3, + ) + + +def _build_create_body( + model: str, + max_tokens: int, + messages: MessagesInput, + *, + system: Optional[SystemInput], + tools: Optional[Tools], + tool_choice: Optional[ToolChoiceInput], + temperature: Optional[float], + top_p: Optional[float], + top_k: Optional[int], + stop_sequences: Optional[Sequence[str]], + thinking: Optional[ConfigInput], + output_config: Optional[ConfigInput], + cache_control: Optional[ConfigInput], + stream: bool, +) -> Dict[str, Any]: + if not model or not model.strip(): + raise ValueError("model must be a non-empty string") + if max_tokens is None or max_tokens <= 0: + raise ValueError("max_tokens must be a positive integer") + normalized_messages = _normalize_items(messages) + if not normalized_messages: + raise ValueError("messages must be a non-empty sequence") + _validate_temperature(temperature) + body: Dict[str, Any] = { + "model": model, + "max_tokens": max_tokens, + "messages": normalized_messages, + "stream": stream, + } + normalized_tools = _normalize_items(tools) if tools is not None else None + if normalized_tools is not None: + body["tools"] = normalized_tools + # Inject the web-search billing identifier when a server web_search + # tool is declared (a caller-provided marker wins); shared with the + # chat protocol="anthropic" adapter so both paths enable search alike. + injected_system = ensure_billing_header( + _normalize_system(system), + normalized_tools, + ) + if injected_system is not None: + body["system"] = injected_system + optional = { + "temperature": temperature, + "top_p": top_p, + "top_k": top_k, + } + body.update({k: v for k, v in optional.items() if v is not None}) + if stop_sequences is not None: + body["stop_sequences"] = list(stop_sequences) + if tool_choice is not None: + body["tool_choice"] = _normalize_tool_choice(tool_choice) + thinking_dict = _normalize_config(thinking) + if thinking_dict is not None: + if thinking_dict.get("budget_tokens") is not None: + _warn_budget_tokens() + body["thinking"] = thinking_dict + for key, value in ( + ("output_config", output_config), + ("cache_control", cache_control), + ): + normalized = _normalize_config(value) + if normalized is not None: + body[key] = normalized + return body + + +def _checked(client, resp, model_cls, parser): + """Raise on failure, or fill the error envelope when not raising. + + Mirrors the per-resource pattern of responses/conversations: route the + reply through ``response_error`` (HTTP >= 400, then HTTP-200 business + code) so ``raise_on_error=False`` reports the failure via ``is_error`` + / ``code`` / ``message``. Anthropic failures nest ``message`` under + ``error``, which ``error_from_status`` understands. + """ + http_resp = resp.http_response + error = response_error(http_resp) + if error is None: + return with_headers( + parser( + resp.json(), + strict=client.config.strict_validation, + response=http_resp, + ), + http_resp, + ) + if client.raise_on_error: + raise error + return with_headers( + model_cls( + request_id=error.request_id, + status_code=error.status_code, + code=error.code, + message=error.message, + is_error=True, + ), + http_resp, + ) + + +def _parse_tool_json(raw: str) -> Dict[str, Any]: + if not raw or not raw.strip(): + return {} + try: + parsed = json.loads(raw) + except ValueError: + return {} + return parsed if isinstance(parsed, dict) else {} + + +class _MessageBuilder: + """Reassemble native SSE events into a final :class:`AnthropicMessage`. + + Anthropic streams carry no terminal full-message event (unlike + Responses), so the message is accumulated: ``message_start`` seeds the + skeleton, ``content_block_start`` opens a block, ``content_block_delta`` + appends text/thinking/signature or tool-input JSON, ``message_delta`` + supplies stop_reason + full usage, ``message_stop`` ends the stream. + """ + + def __init__(self) -> None: + self._skeleton: Dict[str, Any] = {} + self._blocks: Dict[int, Dict[str, Any]] = {} + self._json: Dict[int, str] = {} + self._usage: Dict[str, Any] = {} + self._stop_reason: Optional[str] = None + self._stop_sequence: Optional[str] = None + self._saw_stop = False + + def feed(self, event: AnthropicStreamEvent) -> None: + kind = event.type + if kind == "message_start": + self._on_message_start(event) + elif kind == "content_block_start": + self._on_content_block_start(event) + elif kind == "content_block_delta": + self._on_content_block_delta(event) + elif kind == "content_block_stop": + self._on_content_block_stop(event) + elif kind == "message_delta": + self._on_message_delta(event) + elif kind == "message_stop": + self._saw_stop = True + + def _on_message_start(self, event: AnthropicStreamEvent) -> None: + message = event.message + if message is not None: + self._skeleton = { + "id": message.id, + "type": message.type, + "role": message.role, + "model": message.model, + } + if message.usage is not None: + # exclude_unset, not exclude_none: int fields default to 0, + # so a wire frame omitting them must not dump those zeros. + self._usage = message.usage.model_dump(exclude_unset=True) + + def _on_content_block_start(self, event: AnthropicStreamEvent) -> None: + index = event.index + if index is None: + return + block = ( + event.content_block.model_dump(exclude_none=True) + if event.content_block is not None + else {} + ) + self._blocks[index] = block + if block.get("type") == "tool_use": + # tool_use input arrives incrementally via input_json_delta; + # server_tool_use / web_search_tool_result carry complete + # input/content in this start event (no deltas to buffer). + self._json[index] = "" + block.setdefault("input", {}) + + def _on_content_block_delta(self, event: AnthropicStreamEvent) -> None: + index = event.index + if index is None: + return + delta = event.delta or {} + block = self._blocks.setdefault(index, {}) + delta_type = delta.get("type") + if delta_type == "text_delta": + block["text"] = (block.get("text") or "") + ( + delta.get("text") or "" + ) + elif delta_type == "thinking_delta": + block["thinking"] = (block.get("thinking") or "") + ( + delta.get("thinking") or "" + ) + elif delta_type == "signature_delta": + block["signature"] = delta.get("signature") or "" + elif delta_type == "input_json_delta": + self._json[index] = self._json.get(index, "") + ( + delta.get("partial_json") or "" + ) + + def _finalize_json_block(self, index: int, raw: str) -> None: + block = self._blocks.setdefault(index, {}) + if raw.strip(): + block["input"] = _parse_tool_json(raw) + elif not block.get("input"): + block["input"] = {} + + def _on_content_block_stop(self, event: AnthropicStreamEvent) -> None: + index = event.index + if index is None: + return + if index in self._json: + self._finalize_json_block(index, self._json.pop(index)) + + def _on_message_delta(self, event: AnthropicStreamEvent) -> None: + delta = event.delta or {} + if "stop_reason" in delta: + self._stop_reason = delta.get("stop_reason") + if "stop_sequence" in delta: + self._stop_sequence = delta.get("stop_sequence") + if event.usage is not None: + # Spec-conformant message_delta usage carries only output_tokens; + # exclude_unset keeps the message_start input/cache counters. + self._usage.update(event.usage.model_dump(exclude_unset=True)) + + def build( + self, + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, + ) -> AnthropicMessage: + if not self._saw_stop: + raise DashScopeError( + "message stream ended without a message_stop event", + ) + for index, raw in self._json.items(): + self._finalize_json_block(index, raw) + content = [self._blocks[i] for i in sorted(self._blocks)] + return parse_message( + { + **self._skeleton, + "content": content, + "stop_reason": self._stop_reason, + "stop_sequence": self._stop_sequence, + "usage": self._usage or None, + }, + strict=strict, + response=response, + ) + + +class MessageStream: + """Typed iterator over Messages SSE events. + + Consume it one way: iterate the events, read ``text_stream`` / + ``thinking_stream``, or call ``get_final_message()`` -- each reads the + live socket once. ``get_final_message`` reassembles the full + :class:`AnthropicMessage` from the event sequence. + """ + + def __init__( + self, + inner: Stream[AnthropicStreamEvent], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, + ) -> None: + self._inner = inner + self._strict = strict + self._response = response + + def __iter__(self) -> Iterator[AnthropicStreamEvent]: + return iter(self._inner) + + @property + def text_stream(self) -> Iterator[str]: + for event in self: + if event.type == "content_block_delta": + delta = event.delta or {} + if delta.get("type") == "text_delta" and delta.get("text"): + yield delta["text"] + + @property + def thinking_stream(self) -> Iterator[str]: + for event in self: + if event.type == "content_block_delta": + delta = event.delta or {} + if delta.get("type") == "thinking_delta" and delta.get( + "thinking", + ): + yield delta["thinking"] + + def get_final_message(self) -> AnthropicMessage: + builder = _MessageBuilder() + for event in self: + builder.feed(event) + final = builder.build(strict=self._strict, response=self._response) + final.headers = self.headers + return final + + @property + def headers(self) -> Dict[str, str]: + """Raw HTTP response headers of the stream's envelope.""" + return self._inner.headers + + def close(self) -> None: + self._inner.close() + + +class AsyncMessageStream: + """Async twin of :class:`MessageStream`.""" + + def __init__( + self, + inner: AsyncStream[AnthropicStreamEvent], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, + ) -> None: + self._inner = inner + self._strict = strict + self._response = response + + def __aiter__(self): + return self._inner.__aiter__() + + @property + def text_stream(self): + return self._text_stream() + + async def _text_stream(self): + async for event in self: + if event.type == "content_block_delta": + delta = event.delta or {} + if delta.get("type") == "text_delta" and delta.get("text"): + yield delta["text"] + + @property + def thinking_stream(self): + return self._thinking_stream() + + async def _thinking_stream(self): + async for event in self: + if event.type == "content_block_delta": + delta = event.delta or {} + if delta.get("type") == "thinking_delta" and delta.get( + "thinking", + ): + yield delta["thinking"] + + async def get_final_message(self) -> AnthropicMessage: + builder = _MessageBuilder() + async for event in self: + builder.feed(event) + final = builder.build(strict=self._strict, response=self._response) + final.headers = self.headers + return final + + @property + def headers(self) -> Dict[str, str]: + """Raw HTTP response headers of the stream's envelope.""" + return self._inner.headers + + async def aclose(self) -> None: + await self._inner.aclose() + + +class Messages: + """``client.messages`` -- the native Anthropic Messages resource.""" + + def __init__(self, client) -> None: + self._client = client + + @overload + def create( + self, + *, + model: str, + max_tokens: int, + messages: MessagesInput, + stream: Literal[True], + system: Optional[SystemInput] = None, + tools: Optional[Tools] = None, + tool_choice: Optional[ToolChoiceInput] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + top_k: Optional[int] = None, + stop_sequences: Optional[Sequence[str]] = None, + thinking: Optional[ConfigInput] = None, + output_config: Optional[ConfigInput] = None, + cache_control: Optional[ConfigInput] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> MessageStream: + ... + + @overload + def create( + self, + *, + model: str, + max_tokens: int, + messages: MessagesInput, + stream: Literal[False] = False, + system: Optional[SystemInput] = None, + tools: Optional[Tools] = None, + tool_choice: Optional[ToolChoiceInput] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + top_k: Optional[int] = None, + stop_sequences: Optional[Sequence[str]] = None, + thinking: Optional[ConfigInput] = None, + output_config: Optional[ConfigInput] = None, + cache_control: Optional[ConfigInput] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> AnthropicMessage: + ... + + @overload + def create( + self, + *, + model: str, + max_tokens: int, + messages: MessagesInput, + stream: Literal[False] = False, + system: Optional[SystemInput] = None, + tools: Optional[Tools] = None, + tool_choice: Optional[ToolChoiceInput] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + top_k: Optional[int] = None, + stop_sequences: Optional[Sequence[str]] = None, + thinking: Optional[ConfigInput] = None, + output_config: Optional[ConfigInput] = None, + cache_control: Optional[ConfigInput] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def create( + self, + *, + model: str, + max_tokens: int, + messages: MessagesInput, + stream: bool = False, + system: Optional[SystemInput] = None, + tools: Optional[Tools] = None, + tool_choice: Optional[ToolChoiceInput] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + top_k: Optional[int] = None, + stop_sequences: Optional[Sequence[str]] = None, + thinking: Optional[ConfigInput] = None, + output_config: Optional[ConfigInput] = None, + cache_control: Optional[ConfigInput] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[AnthropicMessage, MessageStream, "APIResponse"]: + """Create a message (``POST /apps/anthropic/v1/messages``). + + ``messages`` are native Anthropic turns (role + content string or + blocks); ``system`` is a string or block array. Bailian extensions + are first-class: ``output_config`` (effort / structured-output + format), ``cache_control`` (top-level auto cache; block-level + markers ride inside system/messages blocks), ``thinking`` + (type / display). ``temperature`` must be in [0, 2). Declaring a + server ``web_search`` tool auto-injects the billing identifier into + system (a caller-provided marker wins). ``thinking.budget_tokens`` + is deprecated in favour of ``output_config.effort`` and emits a + ``DeprecationWarning``. + + ``stream=True`` returns a :class:`MessageStream`; ``raw=True`` + returns the :class:`~dashscope.transport.APIResponse` before any + error check (only with ``stream=False``; combining raises + ``ValueError``). + """ + body = _build_create_body( + model, + max_tokens, + messages, + system=system, + tools=tools, + tool_choice=tool_choice, + temperature=temperature, + top_p=top_p, + top_k=top_k, + stop_sequences=stop_sequences, + thinking=thinking, + output_config=output_config, + cache_control=cache_control, + stream=stream, + ) + headers = {"anthropic-version": AnthropicProtocol.API_VERSION} + options = request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ) + transport = self._client.transport + base_url = _endpoint_base(self._client.config) + if stream: + if raw: + raise ValueError("raw=True is not supported with stream=True") + response = transport.open_stream( + "POST", + _MESSAGES_PATH, + json=body, + headers=headers, + base_url=base_url, + api_key=api_key, + workspace=workspace, + sdk_module=MODULE, + timeout=timeout, + options=options, + ) + return MessageStream( + Stream( + response, + functools.partial( + parse_message_stream_event, + strict=self._client.config.strict_validation, + response=response, + ), + ), + strict=self._client.config.strict_validation, + response=response, + ) + resp = transport.request_api( + "POST", + _MESSAGES_PATH, + json=body, + headers=headers, + base_url=base_url, + api_key=api_key, + workspace=workspace, + sdk_module=MODULE, + timeout=timeout, + options=options, + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, AnthropicMessage, parse_message) + + +class AsyncMessages: + """Async twin of :class:`Messages`.""" + + def __init__(self, client) -> None: + self._client = client + + @overload + async def create( + self, + *, + model: str, + max_tokens: int, + messages: MessagesInput, + stream: Literal[True], + system: Optional[SystemInput] = None, + tools: Optional[Tools] = None, + tool_choice: Optional[ToolChoiceInput] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + top_k: Optional[int] = None, + stop_sequences: Optional[Sequence[str]] = None, + thinking: Optional[ConfigInput] = None, + output_config: Optional[ConfigInput] = None, + cache_control: Optional[ConfigInput] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> AsyncMessageStream: + ... + + @overload + async def create( + self, + *, + model: str, + max_tokens: int, + messages: MessagesInput, + stream: Literal[False] = False, + system: Optional[SystemInput] = None, + tools: Optional[Tools] = None, + tool_choice: Optional[ToolChoiceInput] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + top_k: Optional[int] = None, + stop_sequences: Optional[Sequence[str]] = None, + thinking: Optional[ConfigInput] = None, + output_config: Optional[ConfigInput] = None, + cache_control: Optional[ConfigInput] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> AnthropicMessage: + ... + + @overload + async def create( + self, + *, + model: str, + max_tokens: int, + messages: MessagesInput, + stream: Literal[False] = False, + system: Optional[SystemInput] = None, + tools: Optional[Tools] = None, + tool_choice: Optional[ToolChoiceInput] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + top_k: Optional[int] = None, + stop_sequences: Optional[Sequence[str]] = None, + thinking: Optional[ConfigInput] = None, + output_config: Optional[ConfigInput] = None, + cache_control: Optional[ConfigInput] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def create( + self, + *, + model: str, + max_tokens: int, + messages: MessagesInput, + stream: bool = False, + system: Optional[SystemInput] = None, + tools: Optional[Tools] = None, + tool_choice: Optional[ToolChoiceInput] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + top_k: Optional[int] = None, + stop_sequences: Optional[Sequence[str]] = None, + thinking: Optional[ConfigInput] = None, + output_config: Optional[ConfigInput] = None, + cache_control: Optional[ConfigInput] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[AnthropicMessage, AsyncMessageStream, "APIResponse"]: + """Async twin of :meth:`Messages.create`.""" + body = _build_create_body( + model, + max_tokens, + messages, + system=system, + tools=tools, + tool_choice=tool_choice, + temperature=temperature, + top_p=top_p, + top_k=top_k, + stop_sequences=stop_sequences, + thinking=thinking, + output_config=output_config, + cache_control=cache_control, + stream=stream, + ) + headers = {"anthropic-version": AnthropicProtocol.API_VERSION} + options = request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ) + transport = self._client.transport + base_url = _endpoint_base(self._client.config) + if stream: + if raw: + raise ValueError("raw=True is not supported with stream=True") + response = await transport.open_stream( + "POST", + _MESSAGES_PATH, + json=body, + headers=headers, + base_url=base_url, + api_key=api_key, + workspace=workspace, + sdk_module=MODULE, + timeout=timeout, + options=options, + ) + return AsyncMessageStream( + AsyncStream( + response, + functools.partial( + parse_message_stream_event, + strict=self._client.config.strict_validation, + response=response, + ), + ), + strict=self._client.config.strict_validation, + response=response, + ) + resp = await transport.request_api( + "POST", + _MESSAGES_PATH, + json=body, + headers=headers, + base_url=base_url, + api_key=api_key, + workspace=workspace, + sdk_module=MODULE, + timeout=timeout, + options=options, + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, AnthropicMessage, parse_message) + + +__all__ = [ + "AsyncMessageStream", + "AsyncMessages", + "MessageStream", + "Messages", +] diff --git a/dashscope/resources/models.py b/dashscope/resources/models.py index 80f557a3..dc383948 100644 --- a/dashscope/resources/models.py +++ b/dashscope/resources/models.py @@ -7,7 +7,9 @@ from typing import ( TYPE_CHECKING, Any, + AsyncIterator, Dict, + Iterator, List, Literal, Mapping, @@ -16,11 +18,16 @@ overload, ) -from pydantic import AliasChoices, Field +from pydantic import AliasChoices, BaseModel, ConfigDict, Field from dashscope.errors import ( ErrorCode, error_from_business_code, + response_error, +) +from dashscope.resources._model_cache import ( + _CatalogCache, + catalog_key, ) from dashscope.transport._options import request_options from dashscope.types._parse import parse_model @@ -40,7 +47,70 @@ MODULE = "models" -__all__ = ["AsyncModels", "Model", "ModelList", "Models"] +__all__ = [ + "AsyncModelLimits", + "AsyncModelPermissions", + "AsyncModels", + "InferenceMetadata", + "Model", + "ModelInfo", + "ModelLimits", + "ModelList", + "ModelPermission", + "ModelPermissions", + "ModelPrice", + "ModelPriceRange", + "ModelQuota", + "Models", + "PermissionDetail", + "PermissionList", + "QuotaList", + "RateLimit", +] + + +class ModelPrice(BaseModel): + """One billing item inside a price range (``type``/``price``/unit/name).""" + + model_config = ConfigDict(extra="allow") + + type: Optional[str] = None + # The wire sends price as a string ("2", "0.0008"); kept verbatim so no + # precision is lost coercing it to a float. + price: Optional[str] = None + price_unit: Optional[str] = None + price_name: Optional[str] = None + + +class ModelPriceRange(BaseModel): + """One tiered billing range; ``range_name`` is ``Default`` when untiered.""" + + model_config = ConfigDict(extra="allow") + + prices: List[ModelPrice] = [] + range_name: Optional[str] = None + + +class InferenceMetadata(BaseModel): + """Input/output modalities (``Text``/``Image``/``Audio``/``Video``).""" + + model_config = ConfigDict(extra="allow") + + request_modality: List[str] = [] + response_modality: List[str] = [] + + +class ModelInfo(BaseModel): + """Context-length limits; ``None`` means unlimited or not applicable.""" + + model_config = ConfigDict(extra="allow") + + context_window: Optional[int] = None + max_input_tokens: Optional[int] = None + max_output_tokens: Optional[int] = None + max_reasoning_tokens: Optional[int] = None + reasoning_max_input_tokens: Optional[int] = None + reasoning_max_output_tokens: Optional[int] = None class Model(ResponseBase): @@ -60,6 +130,25 @@ class Model(ResponseBase): None, validation_alias=AliasChoices("open_source", "opensource"), ) + name: Optional[str] = None + description: Optional[str] = None + capabilities: List[str] = [] + inference_provider: Optional[str] = None + features: List[str] = [] + prices: List[ModelPriceRange] = [] + published_time: Optional[str] = None + inference_metadata: Optional[InferenceMetadata] = None + model_info: Optional[ModelInfo] = None + equivalent_snapshot: Optional[str] = None + # SDK-injected query context, not per-model wire fields: the catalog + # endpoint's region and the effective workspace. ``service_site`` echoes + # the query's deployment-site filter (None when unfiltered, i.e. the page + # may span sites); it is a different dimension from ``served_region`` and + # the two are never conflated. A gateway that does return ``service_site`` + # per model keeps its own value. + served_region: Optional[str] = None + workspace: Optional[str] = None + service_site: Optional[str] = None class ModelList(BasePage[Model]): @@ -78,11 +167,123 @@ def items(self) -> List[Model]: return self.models +class RateLimit(BaseModel): + """One rate-limit tier (account- or workspace-level). + + ``request_limit_period`` is in seconds: 60 means RPM, 1 means QPS. + ``usage_limit`` of ``None`` means no usage cap. Every field is optional + because the gateway omits the dimensions a model does not constrain. + """ + + model_config = ConfigDict(extra="allow") + + request_limit: Optional[int] = None + request_limit_period: Optional[int] = None + usage_limit: Optional[int] = None + usage_limit_field: Optional[str] = None + usage_limit_period: Optional[int] = None + async_user_queue_limit: Optional[int] = None + async_user_concurrency_limit: Optional[int] = None + + +class ModelQuota(ResponseBase): + """One model's rate-limit quotas, from ``models.limits``. + + ``model_limit`` is the account-level ceiling (``None`` when unset); + ``workspace_limit`` is the per-workspace cap (``None`` when the workspace + inherits the account limit). The envelope is filled on the standalone + ``get`` result and stays empty on the nested list copies. + """ + + model: Optional[str] = None + workspace_id: Optional[str] = None + model_limit: Optional[RateLimit] = None + workspace_limit: Optional[RateLimit] = None + + +class QuotaList(BasePage[ModelQuota]): + """One page of model quotas, from ``models.limits.list``. + + ``page_no`` / ``page_size`` / ``total_count`` come from + :class:`~dashscope.types.pagination.BasePage`; iterate the page directly + or cross pages with ``iter_pages()`` / ``next_page()``. + """ + + quotas: List[ModelQuota] = [] + + @property + def items(self) -> List[ModelQuota]: + return self.quotas + + +class PermissionDetail(BaseModel): + """Per-action authorization flags for one model in a workspace.""" + + model_config = ConfigDict(extra="allow") + + inference: Optional[bool] = None + fine_tune: Optional[bool] = None + deploy: Optional[bool] = None + + +class ModelPermission(ResponseBase): + """One model's authorization state, from ``models.permissions``. + + ``permissions`` carries the per-action flags (inference / fine_tune / + deploy). Whether a model appears at all depends on the query's + ``authorization_scope`` (AUTHORIZABLE vs AUTHORIZED). + """ + + model: Optional[str] = None + name: Optional[str] = None + permissions: Optional[PermissionDetail] = None + + +class PermissionList(BasePage[ModelPermission]): + """One page of model permissions, from ``models.permissions.list``. + + ``page_no`` / ``page_size`` / ``total_count`` come from + :class:`~dashscope.types.pagination.BasePage`; iterate the page directly + or cross pages with ``iter_pages()`` / ``next_page()``. + """ + + permissions: List[ModelPermission] = [] + + @property + def items(self) -> List[ModelPermission]: + return self.permissions + + +def _with_context( + item: Dict[str, Any], + *, + region: Optional[str], + workspace: Optional[str], + service_site: Optional[str], +) -> Dict[str, Any]: + """Stamp the SDK-injected query context onto one wire model dict. + + ``served_region`` / ``workspace`` describe the endpoint the catalog was + read from, so the SDK's values are authoritative and override any a + gateway might echo. ``service_site`` is only filled from the query filter + when the wire item does not carry its own, so a real per-model value is + never erased by an unfiltered (None) query. + """ + merged = dict(item) + merged["served_region"] = region + merged["workspace"] = workspace + merged.setdefault("service_site", service_site) + return merged + + def _parse_list( body: Dict[str, Any], *, strict: bool = False, response: Optional[httpx.Response] = None, + region: Optional[str] = None, + workspace: Optional[str] = None, + service_site: Optional[str] = None, ) -> ModelList: """Build a page from the native envelope. @@ -93,11 +294,17 @@ def _parse_list( A body carrying the page as a bare list has no ``page_no`` / ``total`` to read, so the list is taken as one whole page: the generic envelope lifter only unwraps a *dict*, and letting this shape through it would - parse as an empty catalog rather than as the malformed one it is. The - ``total`` fallback to ``len(models)`` keeps ``total_count`` meaningful - for gateways that omit it, matching ``files.list``. + parse as an empty catalog rather than as the malformed one it is. When + a dict page omits ``total``, ``total_count`` falls back to + ``len(models)`` for display, but the page is marked ``_total_unknown`` + so traversal continues while pages come back full instead of stopping + after page 1. + + ``region`` / ``workspace`` / ``service_site`` are stamped onto every model + as SDK-injected query context (see :func:`_with_context`). """ data = body.get("output") or body.get("data") or {} + total_unknown = False if isinstance(data, dict): models = data.get("models") # A retyped ``models`` would both poison the ``len()`` below (a @@ -108,13 +315,29 @@ def _parse_list( models = [] page_no = data.get("page_no", 1) page_size = data.get("page_size", 10) - total = data.get("total", len(models)) + total = data.get("total") + if total is None: + # No total to do offset arithmetic against: traversal falls + # back to full-page continuation instead of stopping at page 1. + total_unknown = True + total = len(models) else: # Only a genuine list can be read as a whole page; ``len()`` on a # drifted scalar would escape as a bare TypeError from here. models = data if isinstance(data, list) else [] page_no, page_size, total = 1, 10, len(models) - return parse_model( + models = [ + _with_context( + m, + region=region, + workspace=workspace, + service_site=service_site, + ) + if isinstance(m, dict) + else m + for m in models + ] + result = parse_model( ModelList, { "page_no": page_no, @@ -126,6 +349,8 @@ def _parse_list( strict=strict, response=response, ) + result._total_unknown = total_unknown # pylint: disable=protected-access + return result def _parse_get_models(body: Dict[str, Any]) -> List[Dict[str, Any]]: @@ -135,17 +360,234 @@ def _parse_get_models(body: Dict[str, Any]) -> List[Dict[str, Any]]: return [] -def _match_provider(model: Model, provider: str) -> bool: - wanted = provider.lower() - return wanted in ( - (model.provider or "").lower(), - (model.source or "").lower(), +def _build_list_params( + page_no: int, + page_size: int, + *, + name: Optional[str], + model: Optional[str], + language: Optional[str], + provider: Optional[str], + providers: Optional[List[str]], + inference_providers: Optional[List[str]], + capabilities: Optional[List[str]], + features: Optional[List[str]], + context_window: Optional[int], + service_site: Optional[str], + supports: Optional[List[str]], + deployment_methods: Optional[List[str]], + deployment_ptu_service_tiers: Optional[List[str]], +) -> Dict[str, Any]: + """Translate the public filters into the server's query contract. + + Array filters are sent as repeated parameter names (``capabilities=TG& + capabilities=Reasoning``), which httpx produces from a list value. The + singular ``provider`` convenience folds into the server-side ``providers`` + filter so the catalog total reflects the filtered set, rather than the + old client-side per-page slice whose ``total_count`` stayed pre-filter. + """ + params: Dict[str, Any] = {"page_no": page_no, "page_size": page_size} + effective_providers = list(providers or []) + if provider and provider not in effective_providers: + effective_providers.append(provider) + if effective_providers: + params["providers"] = effective_providers + scalar_filters = { + "name": name, + "model": model, + "language": language, + "context_window": context_window, + "service_site": service_site, + } + params.update({k: v for k, v in scalar_filters.items() if v is not None}) + list_filters = { + "inference_providers": inference_providers, + "capabilities": capabilities, + "features": features, + "supports": supports, + "deployment_methods": deployment_methods, + "deployment_ptu_service_tiers": deployment_ptu_service_tiers, + } + params.update({k: v for k, v in list_filters.items() if v}) + return params + + +def _parse_meta_page( + cls: type, + body: Dict[str, Any], + *, + items_key: str, + strict: bool = False, + response: Optional[httpx.Response] = None, +) -> Any: + """Build a quota/permission page from the native ``output`` envelope. + + ``models.limits`` and ``models.permissions`` answer with the same shape as + the catalog -- ``output.total`` / ``page_no`` / ``page_size`` plus an item + array (``quotas`` / ``permissions``) -- so they share this lifter and the + :class:`~dashscope.types.pagination.BasePage` traversal. ``data`` stays + accepted for gateways that re-wrap the page OpenAI-style. A non-list item + field reads as empty rather than poisoning ``len()``; when the gateway + omits ``total``, ``total_count`` falls back to the item count for display + and the page is marked ``_total_unknown`` so traversal continues while + pages come back full. + """ + data = body.get("output") or body.get("data") or {} + total_unknown = False + if isinstance(data, dict): + items = data.get(items_key) + if not isinstance(items, list): + items = [] + page_no = data.get("page_no", 1) + page_size = data.get("page_size", 20) + total = data.get("total") + if total is None: + total_unknown = True + total = len(items) + else: + items = data if isinstance(data, list) else [] + page_no, page_size, total = 1, 20, len(items) + items = [item for item in items if isinstance(item, dict)] + result = parse_model( + cls, + { + "page_no": page_no, + "page_size": page_size, + "total_count": total, + items_key: items, + **response_envelope(body), + }, + strict=strict, + response=response, ) + result._total_unknown = total_unknown # pylint: disable=protected-access + return result + + +def _meta_items(body: Dict[str, Any], items_key: str) -> List[Dict[str, Any]]: + """Raw item dicts of a quota/permission page, for the standalone ``get``.""" + data = body.get("output") or body.get("data") or {} + if isinstance(data, dict): + items = data.get(items_key) or [] + return [item for item in items if isinstance(item, dict)] + return [] + + +def _require_model_id(model: str) -> None: + # An empty model filter matches the whole catalog, so a standalone + # ``get("")`` would silently answer with the first entry instead of + # failing. Same guard as ``is_available``. + if not model or not model.strip(): + raise ValueError("model must be a non-empty model id") + + +def _build_limits_params( + page_no: int, + page_size: int, + *, + name: Optional[str], + model: Optional[str], +) -> Dict[str, Any]: + params: Dict[str, Any] = {"page_no": page_no, "page_size": page_size} + if name is not None: + params["name"] = name + if model is not None: + params["model"] = model + return params + + +def _build_permissions_params( + page_no: int, + page_size: int, + *, + name: Optional[str], + model: Optional[str], + authorization_scope: Optional[str], + action: Optional[str], +) -> Dict[str, Any]: + params: Dict[str, Any] = {"page_no": page_no, "page_size": page_size} + if name is not None: + params["name"] = name + if model is not None: + params["model"] = model + if authorization_scope is not None: + params["authorization_scope"] = authorization_scope + if action is not None: + params["action"] = action + return params class Models: def __init__(self, client) -> None: self._client = client + self.limits = ModelLimits(client) + self.permissions = ModelPermissions(client) + self._catalog_cache = _CatalogCache() + + def _models_get( + self, + params: Mapping[str, Any], + *, + refresh: bool, + raw: bool, + timeout: Optional[float], + api_key: Optional[str], + workspace: Optional[str], + options: Any, + ) -> "APIResponse": + """Single cached read seam for the catalog (list/get/is_available). + + ``raw=True`` bypasses the cache and the error check, returning the + live response. Otherwise a fresh, unexpired entry is reused; on a + miss the response is fetched, error-checked, and cached only when it + is genuinely successful, so errors are never cached even in + non-raising mode. ``refresh=True`` skips the lookup but still updates + the entry. Options carrying ``extra_query`` / ``extra_headers`` + bypass the cache entirely: they change the effective query or can + override the auth/workspace headers, neither of which the key + captures. The cached response is re-parsed by each caller, so every + call hands back fresh model objects rather than a shared instance. + """ + if raw: + return self._client.transport.request_api( + "GET", + _BASE_PATH, + params=params, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=options, + client=self._client, + ) + cacheable = options is None or not ( + options.extra_query or options.extra_headers + ) + key = catalog_key( + self._client.config, + params, + api_key=api_key, + workspace=workspace, + ) + if cacheable and not refresh: + cached = self._catalog_cache.get(key) + if cached is not None: + return cached + resp = self._client.transport.request_api( + "GET", + _BASE_PATH, + params=params, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=options, + client=self._client, + ) + resp.raise_for_status() + if cacheable and response_error(resp.http_response) is None: + self._catalog_cache.set(key, resp) + return resp @overload def list( @@ -154,6 +596,18 @@ def list( page_no: int = 1, page_size: int = 10, provider: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + language: Optional[str] = None, + providers: Optional[List[str]] = None, + inference_providers: Optional[List[str]] = None, + capabilities: Optional[List[str]] = None, + features: Optional[List[str]] = None, + context_window: Optional[int] = None, + service_site: Optional[str] = None, + supports: Optional[List[str]] = None, + deployment_methods: Optional[List[str]] = None, + deployment_ptu_service_tiers: Optional[List[str]] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -161,6 +615,7 @@ def list( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: Literal[False] = False, ) -> ModelList: ... @@ -172,6 +627,18 @@ def list( page_no: int = 1, page_size: int = 10, provider: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + language: Optional[str] = None, + providers: Optional[List[str]] = None, + inference_providers: Optional[List[str]] = None, + capabilities: Optional[List[str]] = None, + features: Optional[List[str]] = None, + context_window: Optional[int] = None, + service_site: Optional[str] = None, + supports: Optional[List[str]] = None, + deployment_methods: Optional[List[str]] = None, + deployment_ptu_service_tiers: Optional[List[str]] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -179,6 +646,7 @@ def list( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: Literal[True], ) -> "APIResponse": ... @@ -189,6 +657,18 @@ def list( page_no: int = 1, page_size: int = 10, provider: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + language: Optional[str] = None, + providers: Optional[List[str]] = None, + inference_providers: Optional[List[str]] = None, + capabilities: Optional[List[str]] = None, + features: Optional[List[str]] = None, + context_window: Optional[int] = None, + service_site: Optional[str] = None, + supports: Optional[List[str]] = None, + deployment_methods: Optional[List[str]] = None, + deployment_ptu_service_tiers: Optional[List[str]] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -196,15 +676,24 @@ def list( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: bool = False, ) -> Union[ModelList, "APIResponse"]: - """List models; ``provider`` filters client-side per page. + """List models with the server's full filter contract. - The server has no provider filter, so ``total_count`` is always - the pre-filter total of the whole catalog, not of the filtered - ``models`` slice. Pagination therefore walks the unfiltered catalog: - ``has_next_page()`` / ``iter_pages()`` follow ``total_count``, and the - ``provider`` filter is applied to each fetched page independently. + All filters are applied server-side, so ``total_count`` is the total + of the *filtered* catalog and pagination walks that filtered set. + Array filters (``providers``/``capabilities``/``features``/...) are + sent as repeated query parameters. The singular ``provider`` is a + convenience that folds into ``providers``; it no longer filters the + current page client-side (which left ``total_count`` pre-filter and + hid matches on other pages). + + Reads are served from a short-TTL (60s) per-client cache keyed by + Region, workspace, credential and the exact query, so repeated + identical reads avoid the gateway. ``refresh=True`` forces a fresh + fetch (and updates the cache); errors and ``raw=True`` are never + cached. The cache never crosses tenants or Regions. ``raw=True`` returns the :class:`~dashscope.transport.APIResponse` instead of a ``ModelList``, before any error check, so callers can @@ -215,11 +704,25 @@ def list( through it as an empty catalog. Use ``resp.json()`` and ``_parse_list`` when the raw path has to agree with this one. """ - resp = self._client.transport.request_api( - "GET", - _BASE_PATH, - params={"page_no": page_no, "page_size": page_size}, - sdk_module=MODULE, + filter_kwargs: Dict[str, Any] = { + "name": name, + "model": model, + "language": language, + "provider": provider, + "providers": providers, + "inference_providers": inference_providers, + "capabilities": capabilities, + "features": features, + "context_window": context_window, + "service_site": service_site, + "supports": supports, + "deployment_methods": deployment_methods, + "deployment_ptu_service_tiers": deployment_ptu_service_tiers, + } + resp = self._models_get( + _build_list_params(page_no, page_size, **filter_kwargs), + refresh=refresh, + raw=raw, timeout=timeout, api_key=api_key, workspace=workspace, @@ -229,25 +732,26 @@ def list( extra_body, max_retries=max_retries, ), - client=self._client, ) if raw: return resp - resp.raise_for_status() result = _parse_list( resp.json(), strict=self._client.config.strict_validation, response=resp.http_response, + region=self._client.config.region, + workspace=( + workspace + if workspace is not None + else self._client.config.workspace + ), + service_site=service_site, ) - if provider: - result.models = [ - m for m in result.models if _match_provider(m, provider) - ] result.bind_pagination( lambda next_no, next_size: self.list( page_no=next_no, page_size=next_size, - provider=provider, + **filter_kwargs, timeout=timeout, api_key=api_key, workspace=workspace, @@ -255,6 +759,7 @@ def list( extra_query=extra_query, extra_body=extra_body, max_retries=max_retries, + refresh=refresh, ), requested_page_no=page_no, requested_page_size=page_size, @@ -273,6 +778,7 @@ def get( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: Literal[False] = False, ) -> Model: ... @@ -289,6 +795,7 @@ def get( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: Literal[True], ) -> "APIResponse": ... @@ -304,14 +811,18 @@ def get( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: bool = False, ) -> Union[Model, "APIResponse"]: - # Server filters by model name via query params. - resp = self._client.transport.request_api( - "GET", - _BASE_PATH, - params={"model": model, "page_no": 1, "page_size": 1}, - sdk_module=MODULE, + # Server filters by model name via query params. Shares the catalog + # cache with list/is_available: the same (region, workspace, + # credential, query) reads one response. ``refresh=True`` forces a + # fresh fetch; errors and ``raw=True`` are never cached. + _require_model_id(model) + resp = self._models_get( + {"model": model, "page_no": 1, "page_size": 1}, + refresh=refresh, + raw=raw, timeout=timeout, api_key=api_key, workspace=workspace, @@ -321,13 +832,17 @@ def get( extra_body, max_retries=max_retries, ), - client=self._client, ) if raw: return resp - resp.raise_for_status() body = resp.json() models = _parse_get_models(body) + region = self._client.config.region + effective_workspace = ( + workspace + if workspace is not None + else self._client.config.workspace + ) if not models: if self._client.raise_on_error: raise error_from_business_code( @@ -339,7 +854,11 @@ def get( return with_headers( parse_model( Model, - response_envelope(body), + { + **response_envelope(body), + "served_region": region, + "workspace": effective_workspace, + }, strict=self._client.config.strict_validation, response=resp.http_response, ), @@ -351,17 +870,253 @@ def get( # Dict merge, not ``**`` twice: a wire entry carrying an # envelope key of its own would otherwise raise a # duplicate-keyword TypeError instead of being parsed. - {**models[0], **response_envelope(body)}, + { + **_with_context( + models[0], + region=region, + workspace=effective_workspace, + service_site=None, + ), + **response_envelope(body), + }, strict=self._client.config.strict_validation, response=resp.http_response, ), resp.http_response, ) + def iter( + self, + *, + page_size: int = 100, + provider: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + language: Optional[str] = None, + providers: Optional[List[str]] = None, + inference_providers: Optional[List[str]] = None, + capabilities: Optional[List[str]] = None, + features: Optional[List[str]] = None, + context_window: Optional[int] = None, + service_site: Optional[str] = None, + supports: Optional[List[str]] = None, + deployment_methods: Optional[List[str]] = None, + deployment_ptu_service_tiers: Optional[List[str]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + refresh: bool = False, + ) -> Iterator[Model]: + """Iterate every model across all pages, lazily. + + Takes the same server-side filters as :meth:`list` (minus ``page_no`` + / ``raw``) and walks the filtered catalog from page 1 to the end, so + callers never maintain ``page_no`` / ``total_count`` by hand. + ``page_size`` defaults to 100 to cut round-trips. Each yielded + :class:`Model` carries the injected ``served_region`` / ``workspace`` + / ``service_site`` context. Only the current Client Region is read. + Pages share the catalog cache; ``refresh=True`` forces every page to + be fetched fresh. + """ + page = self.list( + page_no=1, + page_size=page_size, + provider=provider, + name=name, + model=model, + language=language, + providers=providers, + inference_providers=inference_providers, + capabilities=capabilities, + features=features, + context_window=context_window, + service_site=service_site, + supports=supports, + deployment_methods=deployment_methods, + deployment_ptu_service_tiers=deployment_ptu_service_tiers, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + refresh=refresh, + ) + for following in page.iter_pages(): + yield from following + + def list_all( + self, + *, + page_size: int = 100, + provider: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + language: Optional[str] = None, + providers: Optional[List[str]] = None, + inference_providers: Optional[List[str]] = None, + capabilities: Optional[List[str]] = None, + features: Optional[List[str]] = None, + context_window: Optional[int] = None, + service_site: Optional[str] = None, + supports: Optional[List[str]] = None, + deployment_methods: Optional[List[str]] = None, + deployment_ptu_service_tiers: Optional[List[str]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + refresh: bool = False, + ) -> List[Model]: + """Collect every model across all pages into one list. + + Eager counterpart of :meth:`iter` with the same filters; walks the + whole filtered catalog of the current Client Region. Prefer + :meth:`iter` when the catalog is large or only a prefix is needed. + """ + return list( + self.iter( + page_size=page_size, + provider=provider, + name=name, + model=model, + language=language, + providers=providers, + inference_providers=inference_providers, + capabilities=capabilities, + features=features, + context_window=context_window, + service_site=service_site, + supports=supports, + deployment_methods=deployment_methods, + deployment_ptu_service_tiers=deployment_ptu_service_tiers, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + refresh=refresh, + ), + ) + + def is_available( + self, + model: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + refresh: bool = False, + ) -> bool: + """Whether ``model`` is in the current Client Region's catalog. + + Answers only for this Client's Region/endpoint and never queries + other Regions implicitly (use a per-Region Client for that). Returns + ``True`` when the catalog query returns a matching entry, ``False`` + when it returns none. Transport/HTTP errors propagate rather than + being read as "unavailable". ``model`` must be a non-empty id, so an + empty filter cannot masquerade as the whole catalog being a match. + Shares the catalog cache with ``get``; ``refresh=True`` forces a + fresh fetch. + """ + if not model or not model.strip(): + raise ValueError("model must be a non-empty model id") + resp = self._models_get( + {"model": model, "page_no": 1, "page_size": 1}, + refresh=refresh, + raw=False, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + ) + return bool(_parse_get_models(resp.json())) + class AsyncModels: def __init__(self, client) -> None: self._client = client + self.limits = AsyncModelLimits(client) + self.permissions = AsyncModelPermissions(client) + self._catalog_cache = _CatalogCache() + + async def _models_get( + self, + params: Mapping[str, Any], + *, + refresh: bool, + raw: bool, + timeout: Optional[float], + api_key: Optional[str], + workspace: Optional[str], + options: Any, + ) -> "APIResponse": + """Async :meth:`Models._models_get`; same cache, awaited fetch. + + The cache lookup/store are synchronous and never await inside the + lock, so sharing one ``_CatalogCache`` on a single event loop is + safe. Like the sync seam, options carrying ``extra_query`` / + ``extra_headers`` bypass the cache. + """ + if raw: + return await self._client.transport.request_api( + "GET", + _BASE_PATH, + params=params, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=options, + client=self._client, + ) + cacheable = options is None or not ( + options.extra_query or options.extra_headers + ) + key = catalog_key( + self._client.config, + params, + api_key=api_key, + workspace=workspace, + ) + if cacheable and not refresh: + cached = self._catalog_cache.get(key) + if cached is not None: + return cached + resp = await self._client.transport.request_api( + "GET", + _BASE_PATH, + params=params, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=options, + client=self._client, + ) + resp.raise_for_status() + if cacheable and response_error(resp.http_response) is None: + self._catalog_cache.set(key, resp) + return resp @overload async def list( @@ -370,6 +1125,18 @@ async def list( page_no: int = 1, page_size: int = 10, provider: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + language: Optional[str] = None, + providers: Optional[List[str]] = None, + inference_providers: Optional[List[str]] = None, + capabilities: Optional[List[str]] = None, + features: Optional[List[str]] = None, + context_window: Optional[int] = None, + service_site: Optional[str] = None, + supports: Optional[List[str]] = None, + deployment_methods: Optional[List[str]] = None, + deployment_ptu_service_tiers: Optional[List[str]] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -377,6 +1144,7 @@ async def list( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: Literal[False] = False, ) -> ModelList: ... @@ -388,6 +1156,18 @@ async def list( page_no: int = 1, page_size: int = 10, provider: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + language: Optional[str] = None, + providers: Optional[List[str]] = None, + inference_providers: Optional[List[str]] = None, + capabilities: Optional[List[str]] = None, + features: Optional[List[str]] = None, + context_window: Optional[int] = None, + service_site: Optional[str] = None, + supports: Optional[List[str]] = None, + deployment_methods: Optional[List[str]] = None, + deployment_ptu_service_tiers: Optional[List[str]] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -395,6 +1175,7 @@ async def list( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: Literal[True], ) -> "APIResponse": ... @@ -405,6 +1186,18 @@ async def list( page_no: int = 1, page_size: int = 10, provider: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + language: Optional[str] = None, + providers: Optional[List[str]] = None, + inference_providers: Optional[List[str]] = None, + capabilities: Optional[List[str]] = None, + features: Optional[List[str]] = None, + context_window: Optional[int] = None, + service_site: Optional[str] = None, + supports: Optional[List[str]] = None, + deployment_methods: Optional[List[str]] = None, + deployment_ptu_service_tiers: Optional[List[str]] = None, timeout: Optional[float] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, @@ -412,13 +1205,28 @@ async def list( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: bool = False, ) -> Union[ModelList, "APIResponse"]: - resp = await self._client.transport.request_api( - "GET", - _BASE_PATH, - params={"page_no": page_no, "page_size": page_size}, - sdk_module=MODULE, + filter_kwargs: Dict[str, Any] = { + "name": name, + "model": model, + "language": language, + "provider": provider, + "providers": providers, + "inference_providers": inference_providers, + "capabilities": capabilities, + "features": features, + "context_window": context_window, + "service_site": service_site, + "supports": supports, + "deployment_methods": deployment_methods, + "deployment_ptu_service_tiers": deployment_ptu_service_tiers, + } + resp = await self._models_get( + _build_list_params(page_no, page_size, **filter_kwargs), + refresh=refresh, + raw=raw, timeout=timeout, api_key=api_key, workspace=workspace, @@ -428,25 +1236,26 @@ async def list( extra_body, max_retries=max_retries, ), - client=self._client, ) if raw: return resp - resp.raise_for_status() result = _parse_list( resp.json(), strict=self._client.config.strict_validation, response=resp.http_response, + region=self._client.config.region, + workspace=( + workspace + if workspace is not None + else self._client.config.workspace + ), + service_site=service_site, ) - if provider: - result.models = [ - m for m in result.models if _match_provider(m, provider) - ] result.bind_pagination( lambda next_no, next_size: self.list( page_no=next_no, page_size=next_size, - provider=provider, + **filter_kwargs, timeout=timeout, api_key=api_key, workspace=workspace, @@ -454,6 +1263,7 @@ async def list( extra_query=extra_query, extra_body=extra_body, max_retries=max_retries, + refresh=refresh, ), requested_page_no=page_no, requested_page_size=page_size, @@ -472,6 +1282,7 @@ async def get( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: Literal[False] = False, ) -> Model: ... @@ -488,6 +1299,7 @@ async def get( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: Literal[True], ) -> "APIResponse": ... @@ -503,14 +1315,17 @@ async def get( extra_query: Optional[Mapping[str, Any]] = None, extra_body: Optional[Mapping[str, Any]] = None, max_retries: Optional[int] = None, + refresh: bool = False, raw: bool = False, ) -> Union[Model, "APIResponse"]: - # Server filters by model name via query params. - resp = await self._client.transport.request_api( - "GET", - _BASE_PATH, - params={"model": model, "page_no": 1, "page_size": 1}, - sdk_module=MODULE, + # Server filters by model name via query params. Shares the catalog + # cache with list/is_available; ``refresh=True`` forces a fresh + # fetch, errors and ``raw=True`` are never cached. + _require_model_id(model) + resp = await self._models_get( + {"model": model, "page_no": 1, "page_size": 1}, + refresh=refresh, + raw=raw, timeout=timeout, api_key=api_key, workspace=workspace, @@ -520,13 +1335,17 @@ async def get( extra_body, max_retries=max_retries, ), - client=self._client, ) if raw: return resp - resp.raise_for_status() body = resp.json() models = _parse_get_models(body) + region = self._client.config.region + effective_workspace = ( + workspace + if workspace is not None + else self._client.config.workspace + ) if not models: if self._client.raise_on_error: raise error_from_business_code( @@ -538,7 +1357,11 @@ async def get( return with_headers( parse_model( Model, - response_envelope(body), + { + **response_envelope(body), + "served_region": region, + "workspace": effective_workspace, + }, strict=self._client.config.strict_validation, response=resp.http_response, ), @@ -550,7 +1373,1080 @@ async def get( # Dict merge, not ``**`` twice: a wire entry carrying an # envelope key of its own would otherwise raise a # duplicate-keyword TypeError instead of being parsed. - {**models[0], **response_envelope(body)}, + { + **_with_context( + models[0], + region=region, + workspace=effective_workspace, + service_site=None, + ), + **response_envelope(body), + }, + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + async def iter( + self, + *, + page_size: int = 100, + provider: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + language: Optional[str] = None, + providers: Optional[List[str]] = None, + inference_providers: Optional[List[str]] = None, + capabilities: Optional[List[str]] = None, + features: Optional[List[str]] = None, + context_window: Optional[int] = None, + service_site: Optional[str] = None, + supports: Optional[List[str]] = None, + deployment_methods: Optional[List[str]] = None, + deployment_ptu_service_tiers: Optional[List[str]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + refresh: bool = False, + ) -> AsyncIterator[Model]: + """Async :meth:`Models.iter`: ``async for m in client.models.iter(...)``. + + Walks every page of the current Client Region's filtered catalog, + fetching the next page lazily only as iteration advances. Each model + carries the injected ``served_region`` / ``workspace`` / + ``service_site`` context. Pages share the catalog cache; + ``refresh=True`` forces every page to be fetched fresh. + """ + page = await self.list( + page_no=1, + page_size=page_size, + provider=provider, + name=name, + model=model, + language=language, + providers=providers, + inference_providers=inference_providers, + capabilities=capabilities, + features=features, + context_window=context_window, + service_site=service_site, + supports=supports, + deployment_methods=deployment_methods, + deployment_ptu_service_tiers=deployment_ptu_service_tiers, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + refresh=refresh, + ) + async for following in page.iter_pages_async(): + for item in following.items: + yield item + + async def list_all( + self, + *, + page_size: int = 100, + provider: Optional[str] = None, + name: Optional[str] = None, + model: Optional[str] = None, + language: Optional[str] = None, + providers: Optional[List[str]] = None, + inference_providers: Optional[List[str]] = None, + capabilities: Optional[List[str]] = None, + features: Optional[List[str]] = None, + context_window: Optional[int] = None, + service_site: Optional[str] = None, + supports: Optional[List[str]] = None, + deployment_methods: Optional[List[str]] = None, + deployment_ptu_service_tiers: Optional[List[str]] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + refresh: bool = False, + ) -> List[Model]: + """Async :meth:`Models.list_all`; collects the whole filtered catalog.""" + return [ + m + async for m in self.iter( + page_size=page_size, + provider=provider, + name=name, + model=model, + language=language, + providers=providers, + inference_providers=inference_providers, + capabilities=capabilities, + features=features, + context_window=context_window, + service_site=service_site, + supports=supports, + deployment_methods=deployment_methods, + deployment_ptu_service_tiers=deployment_ptu_service_tiers, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + refresh=refresh, + ) + ] + + async def is_available( + self, + model: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + refresh: bool = False, + ) -> bool: + """Async :meth:`Models.is_available`; current Client Region only. + + Shares the catalog cache with ``get``; ``refresh=True`` forces a + fresh fetch. + """ + if not model or not model.strip(): + raise ValueError("model must be a non-empty model id") + resp = await self._models_get( + {"model": model, "page_no": 1, "page_size": 1}, + refresh=refresh, + raw=False, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + ) + return bool(_parse_get_models(resp.json())) + + +class ModelLimits: + """Read-only model rate-limit quotas (``GET /models/limits``). + + Reports the account-level (``model_limit``) and workspace-level + (``workspace_limit``) RPM/QPS, token-usage and async-task caps for the + current Client Region/workspace, so callers can plan concurrency and + choose between realtime and Batch without waiting for a 429. Updating + limits is a management-plane write and is not exposed here. + """ + + def __init__(self, client) -> None: + self._client = client + + @overload + def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> QuotaList: + ... + + @overload + def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[QuotaList, "APIResponse"]: + """List model quotas; ``name`` fuzzy-matches, ``model`` is exact. + + Filters are server-side, so ``total_count`` is the filtered total and + ``iter_pages()`` walks the filtered set. ``raw=True`` returns the + :class:`~dashscope.transport.APIResponse` before any error check. + """ + resp = self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/limits", + params=_build_limits_params( + page_no, + page_size, + name=name, + model=model, + ), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + result = _parse_meta_page( + QuotaList, + resp.json(), + items_key="quotas", + strict=self._client.config.strict_validation, + response=resp.http_response, + ) + result.bind_pagination( + lambda next_no, next_size: self.list( + name=name, + model=model, + page_no=next_no, + page_size=next_size, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + requested_page_no=page_no, + requested_page_size=page_size, + ) + return with_headers(result, resp.http_response) + + @overload + def get( + self, + model: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> ModelQuota: + ... + + @overload + def get( + self, + model: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def get( + self, + model: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ModelQuota, "APIResponse"]: + """Fetch one model's quotas by exact id. + + Raises ``Model.NotExist`` (``NotFoundError``) when the gateway returns + no quota for ``model`` and ``raise_on_error`` is set; otherwise returns + an empty :class:`ModelQuota` envelope. ``raw=True`` skips the check. + """ + _require_model_id(model) + resp = self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/limits", + params={"model": model, "page_no": 1, "page_size": 1}, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + body = resp.json() + items = _meta_items(body, "quotas") + if not items: + if self._client.raise_on_error: + raise error_from_business_code( + message=f"Model '{model}' not found", + code=ErrorCode.MODEL_NOT_EXIST.value, + body=body, + headers=resp.http_response.headers, + ) + return with_headers( + parse_model( + ModelQuota, + response_envelope(body), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return with_headers( + parse_model( + ModelQuota, + {**items[0], **response_envelope(body)}, + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + +class AsyncModelLimits: + """Async :class:`ModelLimits` (``GET /models/limits``).""" + + def __init__(self, client) -> None: + self._client = client + + @overload + async def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> QuotaList: + ... + + @overload + async def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[QuotaList, "APIResponse"]: + """Async :meth:`ModelLimits.list`.""" + resp = await self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/limits", + params=_build_limits_params( + page_no, + page_size, + name=name, + model=model, + ), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + result = _parse_meta_page( + QuotaList, + resp.json(), + items_key="quotas", + strict=self._client.config.strict_validation, + response=resp.http_response, + ) + result.bind_pagination( + lambda next_no, next_size: self.list( + name=name, + model=model, + page_no=next_no, + page_size=next_size, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + requested_page_no=page_no, + requested_page_size=page_size, + ) + return with_headers(result, resp.http_response) + + @overload + async def get( + self, + model: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> ModelQuota: + ... + + @overload + async def get( + self, + model: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def get( + self, + model: str, + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ModelQuota, "APIResponse"]: + """Async :meth:`ModelLimits.get`.""" + _require_model_id(model) + resp = await self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/limits", + params={"model": model, "page_no": 1, "page_size": 1}, + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + body = resp.json() + items = _meta_items(body, "quotas") + if not items: + if self._client.raise_on_error: + raise error_from_business_code( + message=f"Model '{model}' not found", + code=ErrorCode.MODEL_NOT_EXIST.value, + body=body, + headers=resp.http_response.headers, + ) + return with_headers( + parse_model( + ModelQuota, + response_envelope(body), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return with_headers( + parse_model( + ModelQuota, + {**items[0], **response_envelope(body)}, + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + +class ModelPermissions: + """Read-only model authorization state (``GET /models/permissions``). + + Reports which models are authorizable or already authorized in the current + workspace and their per-action flags (inference / fine_tune / deploy), so + callers can diagnose authorization before an inference permission error. + ``authorization_scope`` selects AUTHORIZABLE (default) or AUTHORIZED; + ``action`` (currently only INFERENCE) drives the filter when AUTHORIZED. + Granting/revoking authorization is a write and is not exposed here. + """ + + def __init__(self, client) -> None: + self._client = client + + @overload + def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> PermissionList: + ... + + @overload + def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[PermissionList, "APIResponse"]: + """List model permissions; ``name`` fuzzy-matches, ``model`` is exact. + + Omitting ``authorization_scope`` lets the gateway default to + AUTHORIZABLE. Filters are server-side, so ``total_count`` is the + filtered total and ``iter_pages()`` walks the filtered set. + ``raw=True`` returns the APIResponse before any error check. + """ + resp = self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/permissions", + params=_build_permissions_params( + page_no, + page_size, + name=name, + model=model, + authorization_scope=authorization_scope, + action=action, + ), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + result = _parse_meta_page( + PermissionList, + resp.json(), + items_key="permissions", + strict=self._client.config.strict_validation, + response=resp.http_response, + ) + result.bind_pagination( + lambda next_no, next_size: self.list( + name=name, + model=model, + authorization_scope=authorization_scope, + action=action, + page_no=next_no, + page_size=next_size, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + requested_page_no=page_no, + requested_page_size=page_size, + ) + return with_headers(result, resp.http_response) + + @overload + def get( + self, + model: str, + *, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> ModelPermission: + ... + + @overload + def get( + self, + model: str, + *, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def get( + self, + model: str, + *, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ModelPermission, "APIResponse"]: + """Fetch one model's authorization by exact id. + + Pass ``authorization_scope="AUTHORIZED"`` to read the granted flags; + the default AUTHORIZABLE lists models that *can* be authorized. Raises + ``Model.NotExist`` when no entry matches and ``raise_on_error`` is set; + otherwise returns an empty :class:`ModelPermission` envelope. + """ + _require_model_id(model) + resp = self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/permissions", + params=_build_permissions_params( + 1, + 1, + name=None, + model=model, + authorization_scope=authorization_scope, + action=action, + ), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + body = resp.json() + items = _meta_items(body, "permissions") + if not items: + if self._client.raise_on_error: + raise error_from_business_code( + message=f"Model '{model}' not found", + code=ErrorCode.MODEL_NOT_EXIST.value, + body=body, + headers=resp.http_response.headers, + ) + return with_headers( + parse_model( + ModelPermission, + response_envelope(body), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return with_headers( + parse_model( + ModelPermission, + {**items[0], **response_envelope(body)}, + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + + +class AsyncModelPermissions: + """Async :class:`ModelPermissions` (``GET /models/permissions``).""" + + def __init__(self, client) -> None: + self._client = client + + @overload + async def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> PermissionList: + ... + + @overload + async def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def list( + self, + *, + name: Optional[str] = None, + model: Optional[str] = None, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + page_no: int = 1, + page_size: int = 20, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[PermissionList, "APIResponse"]: + """Async :meth:`ModelPermissions.list`.""" + resp = await self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/permissions", + params=_build_permissions_params( + page_no, + page_size, + name=name, + model=model, + authorization_scope=authorization_scope, + action=action, + ), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + result = _parse_meta_page( + PermissionList, + resp.json(), + items_key="permissions", + strict=self._client.config.strict_validation, + response=resp.http_response, + ) + result.bind_pagination( + lambda next_no, next_size: self.list( + name=name, + model=model, + authorization_scope=authorization_scope, + action=action, + page_no=next_no, + page_size=next_size, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + requested_page_no=page_no, + requested_page_size=page_size, + ) + return with_headers(result, resp.http_response) + + @overload + async def get( + self, + model: str, + *, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> ModelPermission: + ... + + @overload + async def get( + self, + model: str, + *, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def get( + self, + model: str, + *, + authorization_scope: Optional[str] = None, + action: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ModelPermission, "APIResponse"]: + """Async :meth:`ModelPermissions.get`.""" + _require_model_id(model) + resp = await self._client.transport.request_api( + "GET", + f"{_BASE_PATH}/permissions", + params=_build_permissions_params( + 1, + 1, + name=None, + model=model, + authorization_scope=authorization_scope, + action=action, + ), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + resp.raise_for_status() + body = resp.json() + items = _meta_items(body, "permissions") + if not items: + if self._client.raise_on_error: + raise error_from_business_code( + message=f"Model '{model}' not found", + code=ErrorCode.MODEL_NOT_EXIST.value, + body=body, + headers=resp.http_response.headers, + ) + return with_headers( + parse_model( + ModelPermission, + response_envelope(body), + strict=self._client.config.strict_validation, + response=resp.http_response, + ), + resp.http_response, + ) + return with_headers( + parse_model( + ModelPermission, + {**items[0], **response_envelope(body)}, strict=self._client.config.strict_validation, response=resp.http_response, ), diff --git a/dashscope/resources/responses.py b/dashscope/resources/responses.py new file mode 100644 index 00000000..083d335f --- /dev/null +++ b/dashscope/resources/responses.py @@ -0,0 +1,1208 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""client.responses -- OpenAI-compatible Responses API (C1). + +A stored-response lifecycle independent of chat: ``create`` / ``get`` / +``delete`` plus ``input_items.list``, and SSE streaming. The wire is a flat +OpenAI ``response`` object whose ``output`` array carries ten item types +(message, reasoning, function_call and the built-in tool calls), so it is +modelled in :mod:`dashscope.types.responses` rather than reusing chat's +choice/message shape. + +Like ``client.batches`` / ``client.decision``, every call derives its own +base URL via ``compatible_mode_base_url`` (``{gateway}/compatible-mode/v1``) +so the chat ``protocol`` setting cannot move it, and tags ``sdk_module`` +``responses`` for the ``x-dashscope-sdk-client`` header. + +State lives on the server (a stored response id is valid for 7 days and can +seed ``previous_response_id``); the SDK stays a stateless wrapper -- no +client-side history or memory. + +Contract: +https://help.aliyun.com/zh/model-studio/qwen-api-via-openai-responses +""" + +from __future__ import annotations + +import functools +import warnings +from typing import ( + TYPE_CHECKING, + Any, + AsyncIterator, + Dict, + Iterator, + List, + Literal, + Mapping, + Optional, + Sequence, + Union, + overload, +) +from urllib.parse import quote + +from pydantic import BaseModel + +from dashscope._config import Config, compatible_mode_base_url +from dashscope.errors import DashScopeError, response_error +from dashscope.resources.batches import _CursorPage +from dashscope.transport._options import request_options +from dashscope.transport.sse import AsyncStream, Stream +from dashscope.types._parse import parse_model +from dashscope.types.common import response_envelope, with_headers +from dashscope.types.responses import ( + InputItem, + Response, + ResponseDeleted, + ResponseStreamEvent, + parse_response, + parse_response_deleted, + parse_stream_event, +) + +if TYPE_CHECKING: + import httpx + + from dashscope.transport._response import APIResponse + +_RESPONSES_PATH = "/responses" + +MODULE = "responses" + +# input_items caps limit at 100 (default 20); order defaults to desc. +_MAX_LIMIT = 100 + +_SESSION_CACHE_HEADER = "x-dashscope-session-cache" + +# Terminal stream events carry the full response object. +_TERMINAL_EVENTS = frozenset( + {"response.completed", "response.failed", "response.incomplete"}, +) + +_ENABLE_THINKING_WARNED = False + +Input = Union[str, Sequence[Union[Mapping[str, Any], BaseModel]]] +Tools = Sequence[Union[Mapping[str, Any], BaseModel]] +ConfigInput = Union[Mapping[str, Any], BaseModel] + + +def _endpoint_base(config: Config) -> str: + # The compatible-mode Responses API sits under /compatible-mode/v1 on + # every gateway; the chat protocol setting must not move it. + return compatible_mode_base_url( + config.workspace, + config.region, + config.configured_base_url, + ) + + +def _response_id(value: Union[Response, str]) -> str: + rid = value.id if isinstance(value, Response) else value + if not rid or not str(rid).strip(): + raise ValueError("response_id must be a non-empty string") + # Percent-encode so a '/', '?' or '#' inside the id cannot retarget + # the request to another path or query. + return quote(str(rid), safe="") + + +def _normalize_config( + value: Optional[ConfigInput], +) -> Optional[Dict[str, Any]]: + if value is None: + return None + if isinstance(value, BaseModel): + return value.model_dump(exclude_none=True) + return dict(value) + + +def _normalize_items( + value: Sequence[Union[Mapping[str, Any], BaseModel]], +) -> List[Dict[str, Any]]: + items: List[Dict[str, Any]] = [] + for item in value: + if isinstance(item, BaseModel): + items.append(item.model_dump(exclude_none=True)) + elif isinstance(item, Mapping): + items.append(dict(item)) + else: + raise ValueError( + "each item must be a mapping or a pydantic model", + ) + return items + + +def _normalize_input(value: Input) -> Union[str, List[Dict[str, Any]]]: + if isinstance(value, str): + return value + return _normalize_items(value) + + +def _validate_function_call_sequence(items: List[Dict[str, Any]]) -> None: + # The server rejects a function_call_output that does not immediately + # follow its matching function_call (same call_id); mirror that here so + # the error surfaces before the round-trip. + prev: Optional[Dict[str, Any]] = None + for item in items: + if item.get("type") == "function_call_output": + if ( + prev is None + or prev.get("type") != "function_call" + or prev.get("call_id") != item.get("call_id") + ): + raise ValueError( + "each function_call_output must immediately follow its " + "matching function_call (same call_id) in the input array", + ) + prev = item + + +def _warn_enable_thinking() -> None: + global _ENABLE_THINKING_WARNED # pylint: disable=global-statement + if _ENABLE_THINKING_WARNED: + return + _ENABLE_THINKING_WARNED = True + warnings.warn( + "enable_thinking is deprecated on the Responses API; use " + "reasoning={'effort': ...} instead", + category=DeprecationWarning, + stacklevel=3, + ) + + +def _session_headers(session_cache: Optional[bool]) -> Dict[str, str]: + if session_cache is None: + return {} + return {_SESSION_CACHE_HEADER: "enable" if session_cache else "disable"} + + +def _build_create_body( + model: str, + input: Input, # pylint: disable=redefined-builtin + *, + instructions: Optional[str], + previous_response_id: Optional[str], + conversation: Optional[str], + store: Optional[bool], + tools: Optional[Tools], + tool_choice: Union[str, Mapping[str, Any], None], + parallel_tool_calls: Optional[bool], + temperature: Optional[float], + top_p: Optional[float], + max_output_tokens: Optional[int], + reasoning: Optional[ConfigInput], + prompt_cache_options: Optional[ConfigInput], + ocr_options: Optional[ConfigInput], + enable_thinking: Optional[bool], + text: Optional[ConfigInput], + stream: bool, +) -> Dict[str, Any]: + if not model or not model.strip(): + raise ValueError("model must be a non-empty string") + if input is None: + raise ValueError("input is required") + if previous_response_id is not None and conversation is not None: + raise ValueError( + "previous_response_id and conversation are mutually exclusive", + ) + normalized_input = _normalize_input(input) + if isinstance(normalized_input, list): + _validate_function_call_sequence(normalized_input) + if enable_thinking is not None: + _warn_enable_thinking() + body: Dict[str, Any] = { + "model": model, + "input": normalized_input, + "stream": stream, + } + optional = { + "instructions": instructions, + "previous_response_id": previous_response_id, + "conversation": conversation, + "store": store, + "tool_choice": tool_choice, + "parallel_tool_calls": parallel_tool_calls, + "temperature": temperature, + "top_p": top_p, + "max_output_tokens": max_output_tokens, + "enable_thinking": enable_thinking, + } + body.update({k: v for k, v in optional.items() if v is not None}) + if tools is not None: + body["tools"] = _normalize_items(tools) + for key, value in ( + ("reasoning", reasoning), + ("prompt_cache_options", prompt_cache_options), + ("ocr_options", ocr_options), + ("text", text), + ): + normalized = _normalize_config(value) + if normalized is not None: + body[key] = normalized + return body + + +def _input_items_params( + *, + after: Optional[str], + limit: Optional[int], + order: Optional[str], +) -> Dict[str, Any]: + params: Dict[str, Any] = {} + if after is not None: + params["after"] = after + if limit is not None: + if not 1 <= limit <= _MAX_LIMIT: + raise ValueError(f"limit must be between 1 and {_MAX_LIMIT}") + params["limit"] = limit + if order is not None: + if order not in ("asc", "desc"): + raise ValueError("order must be 'asc' or 'desc'") + params["order"] = order + return params + + +def _checked(client, resp, model_cls, parser): + """Raise on failure, or fill the error envelope when not raising. + + Compatible-mode failures nest ``code`` / ``message`` under ``error`` + (OpenAI shape), which the flat success parser cannot see; routing the + reply through ``response_error`` keeps ``raise_on_error=False`` + reporting the failure via ``is_error`` / ``code`` / ``message``. + """ + http_resp = resp.http_response + error = response_error(http_resp) + if error is None: + return with_headers( + parser( + resp.json(), + strict=client.config.strict_validation, + response=http_resp, + ), + http_resp, + ) + if client.raise_on_error: + raise error + return with_headers( + model_cls( + request_id=error.request_id, + status_code=error.status_code, + code=error.code, + message=error.message, + is_error=True, + ), + http_resp, + ) + + +class InputItemList(_CursorPage): + """One cursor page of ``input_items``. + + The wire carries ``first_id`` / ``last_id`` (item ids, ``msg_xxx``); the + next-page cursor prefers ``last_id``. ``id`` is the parent response id, + ``model`` the model that produced it, and ``created_at`` is Unix + **milliseconds** (unlike the response object's seconds). + """ + + data: List[InputItem] = [] + first_id: Optional[str] = None + last_id: Optional[str] = None + id: Optional[str] = None + model: Optional[str] = None + created_at: Optional[int] = None + + @property + def items(self) -> List[InputItem]: + return self.data + + @property + def _next_cursor(self) -> Optional[str]: + if self.last_id: + return self.last_id + return self.data[-1].id if self.data else None + + def __iter__(self) -> Iterator[InputItem]: + return iter(self.data) + + def __aiter__(self) -> AsyncIterator[InputItem]: + async def _gen() -> AsyncIterator[InputItem]: + for item in self.data: + yield item + + return _gen() + + +def _parse_input_item_list( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> InputItemList: + payload = dict(body) if isinstance(body, dict) else {} + data = payload.get("data") + if not isinstance(data, list): + data = [] + return parse_model( + InputItemList, + { + "data": data, + "first_id": payload.get("first_id"), + "last_id": payload.get("last_id"), + "id": payload.get("id"), + "model": payload.get("model"), + "created_at": payload.get("created_at"), + "has_more": bool(payload.get("has_more", False)), + **response_envelope(payload), + }, + strict=strict, + response=response, + ) + + +class ResponseStream: + """Typed iterator over Responses SSE events. + + Consume it one way: iterate the events, read ``text_stream`` / + ``reasoning_stream``, or call ``get_final_response()`` -- each reads the + live socket once. The terminal event (``response.completed`` / + ``failed`` / ``incomplete``) carries the full :class:`Response`. + """ + + def __init__(self, inner: Stream[ResponseStreamEvent]) -> None: + self._inner = inner + + def __iter__(self) -> Iterator[ResponseStreamEvent]: + return iter(self._inner) + + @property + def text_stream(self) -> Iterator[str]: + for event in self: + if event.type == "response.output_text.delta" and event.delta: + yield event.delta + + @property + def reasoning_stream(self) -> Iterator[str]: + for event in self: + if ( + event.type + in ( + "response.reasoning_text.delta", + "response.reasoning_summary_text.delta", + ) + and event.delta + ): + yield event.delta + + def get_final_response(self) -> Response: + final: Optional[Response] = None + for event in self: + if event.type in _TERMINAL_EVENTS and event.response is not None: + final = event.response + if final is None: + raise DashScopeError( + "response stream ended without a terminal response event", + ) + final.headers = self.headers + return final + + @property + def headers(self) -> Dict[str, str]: + """Raw HTTP response headers of the stream's envelope.""" + return self._inner.headers + + def close(self) -> None: + self._inner.close() + + +class AsyncResponseStream: + """Async twin of :class:`ResponseStream`.""" + + def __init__(self, inner: AsyncStream[ResponseStreamEvent]) -> None: + self._inner = inner + + def __aiter__(self): + return self._inner.__aiter__() + + @property + def text_stream(self): + return self._text_stream() + + async def _text_stream(self): + async for event in self: + if event.type == "response.output_text.delta" and event.delta: + yield event.delta + + @property + def reasoning_stream(self): + return self._reasoning_stream() + + async def _reasoning_stream(self): + async for event in self: + if ( + event.type + in ( + "response.reasoning_text.delta", + "response.reasoning_summary_text.delta", + ) + and event.delta + ): + yield event.delta + + async def get_final_response(self) -> Response: + final: Optional[Response] = None + async for event in self: + if event.type in _TERMINAL_EVENTS and event.response is not None: + final = event.response + if final is None: + raise DashScopeError( + "response stream ended without a terminal response event", + ) + final.headers = self.headers + return final + + @property + def headers(self) -> Dict[str, str]: + """Raw HTTP response headers of the stream's envelope.""" + return self._inner.headers + + async def aclose(self) -> None: + await self._inner.aclose() + + +class InputItems: + """``client.responses.input_items`` -- list a response's input items.""" + + def __init__(self, client) -> None: + self._client = client + + def list( # pylint: disable=redefined-builtin + self, + response_id: Union[Response, str], + *, + after: Optional[str] = None, + limit: Optional[int] = None, + order: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[InputItemList, "APIResponse"]: + """List input items, one cursor page (``GET /responses/{id}/input_items``). + + ``after`` is an item id (``msg_xxx``) -- the previous page's + ``last_id``; ``limit`` is in [1, 100] (default 20); ``order`` is + ``asc`` / ``desc`` (default ``desc``). Cross pages with + ``iter_pages()`` / ``next_page()`` on the parsed result. + """ + rid = _response_id(response_id) + params = _input_items_params(after=after, limit=limit, order=order) + resp = self._client.transport.request_api( + "GET", + f"{_RESPONSES_PATH}/{rid}/input_items", + params=params, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + result = _checked( + self._client, + resp, + InputItemList, + _parse_input_item_list, + ) + if not result.is_error: + result.bind_pagination( + lambda cursor: self.list( + rid, + after=cursor, + limit=limit, + order=order, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + ) + return result + + +class AsyncInputItems: + """Async twin of :class:`InputItems`.""" + + def __init__(self, client) -> None: + self._client = client + + async def list( # pylint: disable=redefined-builtin + self, + response_id: Union[Response, str], + *, + after: Optional[str] = None, + limit: Optional[int] = None, + order: Optional[str] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[InputItemList, "APIResponse"]: + """Async twin of :meth:`InputItems.list`.""" + rid = _response_id(response_id) + params = _input_items_params(after=after, limit=limit, order=order) + resp = await self._client.transport.request_api( + "GET", + f"{_RESPONSES_PATH}/{rid}/input_items", + params=params, + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + result = _checked( + self._client, + resp, + InputItemList, + _parse_input_item_list, + ) + if not result.is_error: + result.bind_pagination( + lambda cursor: self.list( + rid, + after=cursor, + limit=limit, + order=order, + timeout=timeout, + api_key=api_key, + workspace=workspace, + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + max_retries=max_retries, + ), + ) + return result + + +class Responses: + """``client.responses`` -- the OpenAI-compatible Responses lifecycle.""" + + def __init__(self, client) -> None: + self._client = client + self.input_items = InputItems(client) + + @overload + def create( # pylint: disable=redefined-builtin + self, + *, + model: str, + input: Input, + stream: Literal[True], + instructions: Optional[str] = None, + previous_response_id: Optional[str] = None, + conversation: Optional[str] = None, + store: Optional[bool] = None, + tools: Optional[Tools] = None, + tool_choice: Union[str, Mapping[str, Any], None] = None, + parallel_tool_calls: Optional[bool] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_output_tokens: Optional[int] = None, + reasoning: Optional[ConfigInput] = None, + prompt_cache_options: Optional[ConfigInput] = None, + ocr_options: Optional[ConfigInput] = None, + enable_thinking: Optional[bool] = None, + text: Optional[ConfigInput] = None, + session_cache: Optional[bool] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> ResponseStream: + ... + + @overload + def create( # pylint: disable=redefined-builtin + self, + *, + model: str, + input: Input, + stream: Literal[False] = False, + instructions: Optional[str] = None, + previous_response_id: Optional[str] = None, + conversation: Optional[str] = None, + store: Optional[bool] = None, + tools: Optional[Tools] = None, + tool_choice: Union[str, Mapping[str, Any], None] = None, + parallel_tool_calls: Optional[bool] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_output_tokens: Optional[int] = None, + reasoning: Optional[ConfigInput] = None, + prompt_cache_options: Optional[ConfigInput] = None, + ocr_options: Optional[ConfigInput] = None, + enable_thinking: Optional[bool] = None, + text: Optional[ConfigInput] = None, + session_cache: Optional[bool] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Response: + ... + + @overload + def create( # pylint: disable=redefined-builtin + self, + *, + model: str, + input: Input, + stream: Literal[False] = False, + instructions: Optional[str] = None, + previous_response_id: Optional[str] = None, + conversation: Optional[str] = None, + store: Optional[bool] = None, + tools: Optional[Tools] = None, + tool_choice: Union[str, Mapping[str, Any], None] = None, + parallel_tool_calls: Optional[bool] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_output_tokens: Optional[int] = None, + reasoning: Optional[ConfigInput] = None, + prompt_cache_options: Optional[ConfigInput] = None, + ocr_options: Optional[ConfigInput] = None, + enable_thinking: Optional[bool] = None, + text: Optional[ConfigInput] = None, + session_cache: Optional[bool] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + def create( # pylint: disable=redefined-builtin + self, + *, + model: str, + input: Input, + stream: bool = False, + instructions: Optional[str] = None, + previous_response_id: Optional[str] = None, + conversation: Optional[str] = None, + store: Optional[bool] = None, + tools: Optional[Tools] = None, + tool_choice: Union[str, Mapping[str, Any], None] = None, + parallel_tool_calls: Optional[bool] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_output_tokens: Optional[int] = None, + reasoning: Optional[ConfigInput] = None, + prompt_cache_options: Optional[ConfigInput] = None, + ocr_options: Optional[ConfigInput] = None, + enable_thinking: Optional[bool] = None, + text: Optional[ConfigInput] = None, + session_cache: Optional[bool] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Response, ResponseStream, "APIResponse"]: + """Create a stored response (``POST /responses``). + + ``input`` is a string or a sequence of typed input items. + ``previous_response_id`` and ``conversation`` are mutually exclusive + (server-side context); a ``function_call_output`` item must + immediately follow its matching ``function_call``. Bailian + extensions are first-class: ``reasoning`` (effort/summary), + ``prompt_cache_options``, ``ocr_options``, ``text`` (structured + output) and ``session_cache`` (-> ``x-dashscope-session-cache`` + header). ``enable_thinking`` is deprecated in favour of + ``reasoning.effort`` and emits a ``DeprecationWarning``. + + ``stream=True`` returns a :class:`ResponseStream`; ``raw=True`` + returns the :class:`~dashscope.transport.APIResponse` before any + error check (only with ``stream=False``; combining raises + ``ValueError``). + """ + body = _build_create_body( + model, + input, + instructions=instructions, + previous_response_id=previous_response_id, + conversation=conversation, + store=store, + tools=tools, + tool_choice=tool_choice, + parallel_tool_calls=parallel_tool_calls, + temperature=temperature, + top_p=top_p, + max_output_tokens=max_output_tokens, + reasoning=reasoning, + prompt_cache_options=prompt_cache_options, + ocr_options=ocr_options, + enable_thinking=enable_thinking, + text=text, + stream=stream, + ) + headers = _session_headers(session_cache) + options = request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ) + transport = self._client.transport + base_url = _endpoint_base(self._client.config) + if stream: + if raw: + raise ValueError("raw=True is not supported with stream=True") + response = transport.open_stream( + "POST", + _RESPONSES_PATH, + json=body, + headers=headers or None, + base_url=base_url, + api_key=api_key, + workspace=workspace, + sdk_module=MODULE, + timeout=timeout, + options=options, + ) + return ResponseStream( + Stream( + response, + functools.partial( + parse_stream_event, + strict=self._client.config.strict_validation, + response=response, + ), + ), + ) + resp = transport.request_api( + "POST", + _RESPONSES_PATH, + json=body, + headers=headers or None, + base_url=base_url, + api_key=api_key, + workspace=workspace, + sdk_module=MODULE, + timeout=timeout, + options=options, + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Response, parse_response) + + def get( + self, + response_id: Union[Response, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Response, "APIResponse"]: + """Retrieve a stored response (``GET /responses/{id}``).""" + rid = _response_id(response_id) + resp = self._client.transport.request_api( + "GET", + f"{_RESPONSES_PATH}/{rid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Response, parse_response) + + def delete( + self, + response_id: Union[Response, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ResponseDeleted, "APIResponse"]: + """Delete a stored response (``DELETE /responses/{id}``). + + The wire returns ``{id, deleted}`` (no ``object`` field). + """ + rid = _response_id(response_id) + resp = self._client.transport.request_api( + "DELETE", + f"{_RESPONSES_PATH}/{rid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked( + self._client, + resp, + ResponseDeleted, + parse_response_deleted, + ) + + +class AsyncResponses: + """Async twin of :class:`Responses`.""" + + def __init__(self, client) -> None: + self._client = client + self.input_items = AsyncInputItems(client) + + @overload + async def create( # pylint: disable=redefined-builtin + self, + *, + model: str, + input: Input, + stream: Literal[True], + instructions: Optional[str] = None, + previous_response_id: Optional[str] = None, + conversation: Optional[str] = None, + store: Optional[bool] = None, + tools: Optional[Tools] = None, + tool_choice: Union[str, Mapping[str, Any], None] = None, + parallel_tool_calls: Optional[bool] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_output_tokens: Optional[int] = None, + reasoning: Optional[ConfigInput] = None, + prompt_cache_options: Optional[ConfigInput] = None, + ocr_options: Optional[ConfigInput] = None, + enable_thinking: Optional[bool] = None, + text: Optional[ConfigInput] = None, + session_cache: Optional[bool] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> AsyncResponseStream: + ... + + @overload + async def create( # pylint: disable=redefined-builtin + self, + *, + model: str, + input: Input, + stream: Literal[False] = False, + instructions: Optional[str] = None, + previous_response_id: Optional[str] = None, + conversation: Optional[str] = None, + store: Optional[bool] = None, + tools: Optional[Tools] = None, + tool_choice: Union[str, Mapping[str, Any], None] = None, + parallel_tool_calls: Optional[bool] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_output_tokens: Optional[int] = None, + reasoning: Optional[ConfigInput] = None, + prompt_cache_options: Optional[ConfigInput] = None, + ocr_options: Optional[ConfigInput] = None, + enable_thinking: Optional[bool] = None, + text: Optional[ConfigInput] = None, + session_cache: Optional[bool] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[False] = False, + ) -> Response: + ... + + @overload + async def create( # pylint: disable=redefined-builtin + self, + *, + model: str, + input: Input, + stream: Literal[False] = False, + instructions: Optional[str] = None, + previous_response_id: Optional[str] = None, + conversation: Optional[str] = None, + store: Optional[bool] = None, + tools: Optional[Tools] = None, + tool_choice: Union[str, Mapping[str, Any], None] = None, + parallel_tool_calls: Optional[bool] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_output_tokens: Optional[int] = None, + reasoning: Optional[ConfigInput] = None, + prompt_cache_options: Optional[ConfigInput] = None, + ocr_options: Optional[ConfigInput] = None, + enable_thinking: Optional[bool] = None, + text: Optional[ConfigInput] = None, + session_cache: Optional[bool] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: Literal[True], + ) -> "APIResponse": + ... + + async def create( # pylint: disable=redefined-builtin + self, + *, + model: str, + input: Input, + stream: bool = False, + instructions: Optional[str] = None, + previous_response_id: Optional[str] = None, + conversation: Optional[str] = None, + store: Optional[bool] = None, + tools: Optional[Tools] = None, + tool_choice: Union[str, Mapping[str, Any], None] = None, + parallel_tool_calls: Optional[bool] = None, + temperature: Optional[float] = None, + top_p: Optional[float] = None, + max_output_tokens: Optional[int] = None, + reasoning: Optional[ConfigInput] = None, + prompt_cache_options: Optional[ConfigInput] = None, + ocr_options: Optional[ConfigInput] = None, + enable_thinking: Optional[bool] = None, + text: Optional[ConfigInput] = None, + session_cache: Optional[bool] = None, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Response, AsyncResponseStream, "APIResponse"]: + """Async twin of :meth:`Responses.create`.""" + body = _build_create_body( + model, + input, + instructions=instructions, + previous_response_id=previous_response_id, + conversation=conversation, + store=store, + tools=tools, + tool_choice=tool_choice, + parallel_tool_calls=parallel_tool_calls, + temperature=temperature, + top_p=top_p, + max_output_tokens=max_output_tokens, + reasoning=reasoning, + prompt_cache_options=prompt_cache_options, + ocr_options=ocr_options, + enable_thinking=enable_thinking, + text=text, + stream=stream, + ) + headers = _session_headers(session_cache) + options = request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ) + transport = self._client.transport + base_url = _endpoint_base(self._client.config) + if stream: + if raw: + raise ValueError("raw=True is not supported with stream=True") + response = await transport.open_stream( + "POST", + _RESPONSES_PATH, + json=body, + headers=headers or None, + base_url=base_url, + api_key=api_key, + workspace=workspace, + sdk_module=MODULE, + timeout=timeout, + options=options, + ) + return AsyncResponseStream( + AsyncStream( + response, + functools.partial( + parse_stream_event, + strict=self._client.config.strict_validation, + response=response, + ), + ), + ) + resp = await transport.request_api( + "POST", + _RESPONSES_PATH, + json=body, + headers=headers or None, + base_url=base_url, + api_key=api_key, + workspace=workspace, + sdk_module=MODULE, + timeout=timeout, + options=options, + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Response, parse_response) + + async def get( + self, + response_id: Union[Response, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[Response, "APIResponse"]: + """Async twin of :meth:`Responses.get`.""" + rid = _response_id(response_id) + resp = await self._client.transport.request_api( + "GET", + f"{_RESPONSES_PATH}/{rid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked(self._client, resp, Response, parse_response) + + async def delete( + self, + response_id: Union[Response, str], + *, + timeout: Optional[float] = None, + api_key: Optional[str] = None, + workspace: Optional[str] = None, + extra_headers: Optional[Mapping[str, str]] = None, + extra_query: Optional[Mapping[str, Any]] = None, + extra_body: Optional[Mapping[str, Any]] = None, + max_retries: Optional[int] = None, + raw: bool = False, + ) -> Union[ResponseDeleted, "APIResponse"]: + """Async twin of :meth:`Responses.delete`.""" + rid = _response_id(response_id) + resp = await self._client.transport.request_api( + "DELETE", + f"{_RESPONSES_PATH}/{rid}", + base_url=_endpoint_base(self._client.config), + sdk_module=MODULE, + timeout=timeout, + api_key=api_key, + workspace=workspace, + options=request_options( + extra_headers, + extra_query, + extra_body, + max_retries=max_retries, + ), + client=self._client, + ) + if raw: + return resp + return _checked( + self._client, + resp, + ResponseDeleted, + parse_response_deleted, + ) diff --git a/dashscope/types/__init__.py b/dashscope/types/__init__.py index c6f0b31d..d9b647fe 100644 --- a/dashscope/types/__init__.py +++ b/dashscope/types/__init__.py @@ -3,6 +3,20 @@ """Shared typed models for the dashscope 2.0 SDK.""" from dashscope.types.common import JobStatus, ResponseBase, Usage +from dashscope.types.anthropic_messages import ( + AnthropicCacheCreation, + AnthropicContentBlock, + AnthropicMessage, + AnthropicServerToolUsage, + AnthropicStreamEvent, + AnthropicUsage, + CacheControl, + OutputConfig, + ThinkingConfig, + WebSearchResult, + parse_message, + parse_message_stream_event, +) from dashscope.types.completions import ( ChatCompletion, ChatCompletionChunk, @@ -13,6 +27,17 @@ parse_chunk, parse_completion, ) +from dashscope.types.conversations import ( + Conversation, + ConversationContentPart, + ConversationDeleted, + ConversationItem, + ConversationItemDeleted, + parse_conversation, + parse_conversation_deleted, + parse_conversation_item, + parse_conversation_item_deleted, +) from dashscope.types.messages import ( AudioPart, ImagePart, @@ -25,27 +50,98 @@ normalize_messages, ) from dashscope.types.pagination import BasePage +from dashscope.types.responses import ( + CodeInterpreterTool, + FileSearchTool, + FunctionTool, + ImageSearchTool, + InputItem, + McpTool, + OcrOptions, + PromptCacheBreakpoint, + PromptCacheOptions, + Reasoning, + Response, + ResponseContentPart, + ResponseDeleted, + ResponseOutputItem, + ResponseStreamEvent, + ResponseUsage, + SummaryText, + ToolUsage, + WebExtractorTool, + WebSearchImageTool, + WebSearchTool, + parse_response, + parse_response_deleted, + parse_stream_event, +) __all__ = [ + "AnthropicCacheCreation", + "AnthropicContentBlock", + "AnthropicMessage", + "AnthropicServerToolUsage", + "AnthropicStreamEvent", + "AnthropicUsage", "AudioPart", "BasePage", + "CacheControl", "ChatCompletion", "ChatCompletionChunk", "ChatCompletionMessage", "Choice", + "CodeInterpreterTool", + "Conversation", + "ConversationContentPart", + "ConversationDeleted", + "ConversationItem", + "ConversationItemDeleted", "Delta", + "FileSearchTool", + "FunctionTool", "ImagePart", + "ImageSearchTool", + "InputItem", "JobStatus", + "McpTool", "Message", + "OcrOptions", + "OutputConfig", + "PromptCacheBreakpoint", + "PromptCacheOptions", + "Reasoning", + "Response", "ResponseBase", + "ResponseContentPart", + "ResponseDeleted", + "ResponseOutputItem", + "ResponseStreamEvent", + "ResponseUsage", "StreamChoice", + "SummaryText", "TextPart", + "ThinkingConfig", "ToolCall", "ToolCallFunction", + "ToolUsage", "Usage", "VideoPart", + "WebExtractorTool", + "WebSearchImageTool", + "WebSearchResult", + "WebSearchTool", "extract_text", "normalize_messages", "parse_chunk", "parse_completion", + "parse_conversation", + "parse_conversation_deleted", + "parse_conversation_item", + "parse_conversation_item_deleted", + "parse_message", + "parse_message_stream_event", + "parse_response", + "parse_response_deleted", + "parse_stream_event", ] diff --git a/dashscope/types/anthropic_messages.py b/dashscope/types/anthropic_messages.py new file mode 100644 index 00000000..4ff76844 --- /dev/null +++ b/dashscope/types/anthropic_messages.py @@ -0,0 +1,251 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Typed models for the Anthropic-compatible Messages API (C3). + +These are *native* Anthropic types (a ``message`` object whose ``content`` +array carries text / thinking / tool_use / server-tool blocks), distinct +from the canonical chat :class:`dashscope.types.Message` used by +``client.chat``. The ``client.messages`` resource returns these directly; +the ``protocol="anthropic"`` chat adapter keeps normalizing to chat types. + +Every model is permissive (``extra="allow"``, optional defaulted fields): +Bailian adds extensions (``output_config`` echo, two-generation cache +``usage``, ``server_tool_use`` counters, ``x_tools``) and the content-block +shape varies by ``type``. A single permissive block model keeps every type +readable without a discriminated union the tolerant parser would have to +guess -- the same approach :mod:`dashscope.types.responses` takes. + +Contract: +https://help.aliyun.com/zh/model-studio/anthropic-api-messages +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any, Dict, List, Optional + +from pydantic import BaseModel, ConfigDict + +from dashscope.types._parse import parse_model +from dashscope.types.common import ResponseBase, response_envelope + +if TYPE_CHECKING: + import httpx + +__all__ = [ + "AnthropicCacheCreation", + "AnthropicContentBlock", + "AnthropicMessage", + "AnthropicServerToolUsage", + "AnthropicStreamEvent", + "AnthropicUsage", + "CacheControl", + "OutputConfig", + "ThinkingConfig", + "WebSearchResult", + "parse_message", + "parse_message_stream_event", +] + + +# -------------------------------------------------------------------------- +# Content blocks (one permissive model covers every wire type) +# -------------------------------------------------------------------------- +class WebSearchResult(BaseModel): + """One ``web_search_tool_result.content[]`` element.""" + + model_config = ConfigDict(extra="allow") + + type: str = "web_search_result" + title: Optional[str] = None + url: Optional[str] = None + encrypted_content: Optional[str] = None + page_age: Optional[str] = None + + +class AnthropicContentBlock(BaseModel): + """One ``content[]`` block, covering every wire type. + + Fields are conditional on ``type`` (the service omits the rest): + ``text`` -> text; ``thinking`` -> thinking/signature; ``redacted_thinking`` + -> data; ``tool_use`` / ``server_tool_use`` -> id/name/input (+caller); + ``web_search_tool_result`` -> tool_use_id/content (a list of + :class:`WebSearchResult`); ``web_fetch_tool_result`` -> tool_use_id/content + (a document object); ``tool_result`` -> tool_use_id/content (string or + blocks). ``cache_control`` may ride on input blocks (explicit cache). + """ + + model_config = ConfigDict(extra="allow") + + type: Optional[str] = None + text: Optional[str] = None + thinking: Optional[str] = None + signature: Optional[str] = None + data: Optional[str] = None + id: Optional[str] = None + name: Optional[str] = None + input: Optional[Dict[str, Any]] = None + tool_use_id: Optional[str] = None + content: Optional[Any] = None + caller: Optional[Dict[str, Any]] = None + cache_control: Optional[Dict[str, Any]] = None + + @property + def search_results(self) -> List[WebSearchResult]: + """Typed view of a ``web_search_tool_result`` block's content.""" + content = self.content + if not isinstance(content, list): + return [] + # list() materializes the Optional[Any] so type checkers see an + # iterable (astroid cannot narrow it through the isinstance guard). + return [ + parse_model(WebSearchResult, item) + for item in list(content) + if isinstance(item, dict) + ] + + +# -------------------------------------------------------------------------- +# Usage (cache + server-tool counters; optional-field union) +# -------------------------------------------------------------------------- +class AnthropicServerToolUsage(BaseModel): + """Server-side tool call counts, returned only when such a tool ran.""" + + model_config = ConfigDict(extra="allow") + + web_search_requests: int = 0 + web_fetch_requests: int = 0 + + +class AnthropicCacheCreation(BaseModel): + """Cache-creation tokens split by TTL (qwen4-max explicit cache).""" + + model_config = ConfigDict(extra="allow") + + ephemeral_5m_input_tokens: int = 0 + ephemeral_1h_input_tokens: int = 0 + + +class AnthropicUsage(BaseModel): + """Token usage. ``prompt_tokens_details.cached_tokens`` equals + ``cache_read_input_tokens`` -- do not double-count. ``input_tokens`` + excludes cached/created tokens on qwen4-max.""" + + model_config = ConfigDict(extra="allow") + + input_tokens: int = 0 + output_tokens: int = 0 + cache_creation_input_tokens: int = 0 + cache_read_input_tokens: int = 0 + server_tool_use: Optional[AnthropicServerToolUsage] = None + cache_creation: Optional[AnthropicCacheCreation] = None + prompt_tokens_details: Optional[Dict[str, Any]] = None + + +# -------------------------------------------------------------------------- +# Request-side configuration (Bailian extensions; also accepted as dicts) +# -------------------------------------------------------------------------- +class ThinkingConfig(BaseModel): + """Deep-thinking control. ``type``: enabled / disabled. + ``budget_tokens`` is deprecated in favour of ``output_config.effort``. + ``display="summarized"`` (qwen4-max) returns a summary + signature.""" + + model_config = ConfigDict(extra="allow") + + type: Optional[str] = None + budget_tokens: Optional[int] = None + display: Optional[str] = None + + +class OutputConfig(BaseModel): + """Bailian extension. ``effort`` controls reasoning strength (per-model + tiers differ); ``format`` (``{type: json_schema, schema}``) enables + structured output.""" + + model_config = ConfigDict(extra="allow") + + effort: Optional[str] = None + format: Optional[Dict[str, Any]] = None + + +class CacheControl(BaseModel): + """Explicit-cache breakpoint (qwen4-max). ``type`` is ``ephemeral``; + ``ttl`` is 5m (default) / 1h. Rides on a block or the request top level.""" + + model_config = ConfigDict(extra="allow") + + type: str = "ephemeral" + ttl: Optional[str] = None + + +# -------------------------------------------------------------------------- +# Top-level message +# -------------------------------------------------------------------------- +class AnthropicMessage(ResponseBase): + """A Messages reply (create). ``stop_reason``: end_turn / max_tokens / + tool_use / stop_sequence. ``content`` carries the typed blocks.""" + + id: Optional[str] = None + type: Optional[str] = "message" + role: Optional[str] = "assistant" + model: Optional[str] = None + content: List[AnthropicContentBlock] = [] + stop_reason: Optional[str] = None + stop_sequence: Optional[str] = None + usage: Optional[AnthropicUsage] = None + + @property + def text(self) -> str: + """Concatenated text of every ``text`` block (skips thinking/tools).""" + return "".join( + block.text + for block in self.content + if block.type == "text" and block.text + ) + + +class AnthropicStreamEvent(ResponseBase): + """One streaming event. ``type`` identifies it: ``message_start`` + (carries ``message``), ``content_block_start`` (``index`` + + ``content_block``), ``content_block_delta`` (``index`` + ``delta``), + ``content_block_stop``, ``message_delta`` (``delta`` stop_reason + + full ``usage``), ``message_stop``, ``ping``. All fields optional.""" + + type: Optional[str] = None + message: Optional[AnthropicMessage] = None + index: Optional[int] = None + content_block: Optional[AnthropicContentBlock] = None + delta: Optional[Dict[str, Any]] = None + usage: Optional[AnthropicUsage] = None + + +# -------------------------------------------------------------------------- +# Parsers +# -------------------------------------------------------------------------- +def parse_message( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional[httpx.Response] = None, +) -> AnthropicMessage: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + AnthropicMessage, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) + + +def parse_message_stream_event( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional[httpx.Response] = None, +) -> AnthropicStreamEvent: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + AnthropicStreamEvent, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) diff --git a/dashscope/types/conversations.py b/dashscope/types/conversations.py new file mode 100644 index 00000000..be472dc0 --- /dev/null +++ b/dashscope/types/conversations.py @@ -0,0 +1,162 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Typed models for the OpenAI-compatible Conversations API (C2). + +A conversation is server-side context for the Responses API: its items +are injected as history automatically, and each response's input/output +is appended back to it. The wire is a flat OpenAI ``conversation`` object +plus ``message`` items, modelled here independently of chat. + +Every model is permissive (``extra="allow"``, optional defaulted fields) +and parses through :func:`~dashscope.types._parse.parse_model`, so a +drifted field degrades rather than sinks an otherwise healthy reply. +``created_at`` is Unix **milliseconds** (unlike the response object's +seconds). The service keeps the latest 100 items within 7 days. + +These types are exported under ``dashscope.types`` (not the top-level +``dashscope`` namespace, which already carries the 1.x ``Conversation``). + +Contract: +https://help.aliyun.com/zh/model-studio/openai-compatible-conversations +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union + +from pydantic import BaseModel, ConfigDict + +from dashscope.types._parse import parse_model +from dashscope.types.common import ResponseBase, response_envelope + +if TYPE_CHECKING: + import httpx + +__all__ = [ + "Conversation", + "ConversationContentPart", + "ConversationDeleted", + "ConversationItem", + "ConversationItemDeleted", + "parse_conversation", + "parse_conversation_deleted", + "parse_conversation_item", + "parse_conversation_item_deleted", +] + + +class ConversationContentPart(BaseModel): + """A content block: ``input_text`` (user) or ``output_text`` (model).""" + + model_config = ConfigDict(extra="allow") + + type: Optional[str] = None + text: Optional[str] = None + + +class Conversation(ResponseBase): + """A conversation (create / get / update). ``object`` is + ``conversation``; ``metadata`` is at most 16 string key/value pairs.""" + + id: Optional[str] = None + object: Optional[str] = "conversation" + created_at: Optional[int] = None + metadata: Optional[Dict[str, Any]] = None + + +class ConversationDeleted(ResponseBase): + """Result of ``conversations.delete``. Deleting a conversation does + not delete its items. ``object`` is ``conversation.deleted``.""" + + id: Optional[str] = None + deleted: bool = False + object: Optional[str] = "conversation.deleted" + + +class ConversationItem(ResponseBase): + """One ``message`` item. ``content`` is a plain string or a list of + content blocks; ``status`` is ``in_progress`` / ``completed`` / + ``incomplete``. Returned top-level by ``items.get`` and nested in + ``items.list`` / ``items.create``.""" + + id: Optional[str] = None + type: Optional[str] = "message" + role: Optional[str] = None + status: Optional[str] = None + content: Union[str, List[ConversationContentPart]] = [] + + @property + def text(self) -> str: + """Concatenated text of the content (string or block list).""" + if isinstance(self.content, str): + return self.content + return "".join(part.text for part in self.content if part.text) + + +class ConversationItemDeleted(ResponseBase): + """Result of ``items.delete``. ``object`` is + ``conversation.item.deleted``.""" + + id: Optional[str] = None + deleted: bool = False + object: Optional[str] = "conversation.item.deleted" + + +def parse_conversation( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> Conversation: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + Conversation, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) + + +def parse_conversation_deleted( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> ConversationDeleted: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + ConversationDeleted, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) + + +def parse_conversation_item( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> ConversationItem: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + ConversationItem, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) + + +def parse_conversation_item_deleted( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional["httpx.Response"] = None, +) -> ConversationItemDeleted: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + ConversationItemDeleted, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) diff --git a/dashscope/types/pagination.py b/dashscope/types/pagination.py index 5da7975d..01dec100 100644 --- a/dashscope/types/pagination.py +++ b/dashscope/types/pagination.py @@ -98,6 +98,10 @@ class BasePage(ResponseBase, Generic[T]): # ``page_size``; see :meth:`bind_pagination`. _requested_no: Optional[int] = PrivateAttr(default=None) _requested_size: Optional[int] = PrivateAttr(default=None) + # Set by the parser when the gateway omitted ``total``: offset arithmetic + # against a len(items) fallback would stop after the first full page, so + # traversal continues while pages come back full instead. + _total_unknown: bool = PrivateAttr(default=False) page_no: int = 1 page_size: int = 10 @@ -160,8 +164,13 @@ def has_next_page(self) -> bool: Offset arithmetic only: it trusts the server's ``total_count`` and does not consult ``_fetch_next``, so it stays meaningful on a page - built without a callback (e.g. parsed straight from a body). + built without a callback (e.g. parsed straight from a body). When + the gateway omitted ``total`` (``_total_unknown``), a full page + implies more data and a short/empty page ends the walk -- equating + the missing total with the first page's length would truncate. """ + if self._total_unknown: + return len(self.items) >= self._cursor_size return self._cursor_no * self._cursor_size < self.total_count def next_page(self) -> Optional["BasePage[T]"]: diff --git a/dashscope/types/responses.py b/dashscope/types/responses.py new file mode 100644 index 00000000..b0167076 --- /dev/null +++ b/dashscope/types/responses.py @@ -0,0 +1,473 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Typed models for the OpenAI-compatible Responses API (C1). + +The Responses wire is a flat OpenAI ``response`` object whose ``output`` +array carries ten heterogeneous item types (message, reasoning, +function_call and the seven built-in tool calls). Chat's choice/message +model cannot express those, so they are modelled independently here. + +Every model is permissive (``extra="allow"``, optional defaulted fields): +the service echoes OpenAI-protocol fields it does not support as ``null`` +and adds Bailian extensions (``tool_usage``, ``ocr_result``, two-generation +``usage``). Parsing degrades rather than raises so a drifted field never +sinks an otherwise healthy response. + +Contract: +https://help.aliyun.com/zh/model-studio/qwen-api-via-openai-responses +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Union + +from pydantic import BaseModel, ConfigDict + +from dashscope.types._parse import parse_model +from dashscope.types.common import ResponseBase, response_envelope + +if TYPE_CHECKING: + import httpx + +__all__ = [ + "CodeInterpreterTool", + "FileSearchTool", + "FunctionTool", + "ImageSearchTool", + "InputItem", + "InputTokensDetails", + "McpTool", + "OutputTokensDetails", + "PromptCacheOptions", + "Reasoning", + "Response", + "ResponseContentPart", + "ResponseDeleted", + "ResponseError", + "ResponseOutputItem", + "ResponseStreamEvent", + "ResponseUsage", + "SummaryText", + "ToolUsage", + "ToolUsageCount", + "WebExtractorTool", + "WebSearchImageTool", + "WebSearchTool", + "parse_response", + "parse_response_deleted", + "parse_stream_event", +] + + +# -------------------------------------------------------------------------- +# Content blocks +# -------------------------------------------------------------------------- +class ResponseContentPart(BaseModel): + """A content block. Output uses ``output_text``; input items reuse the + same shape with ``input_text``. ``logprobs`` is currently always null.""" + + model_config = ConfigDict(extra="allow") + + type: Optional[str] = None + text: Optional[str] = None + annotations: List[Dict[str, Any]] = [] + logprobs: Optional[Any] = None + + +class SummaryText(BaseModel): + """One reasoning-summary element (``reasoning.summary[]``).""" + + model_config = ConfigDict(extra="allow") + + type: str = "summary_text" + text: Optional[str] = None + + +class ResponseOutputItem(BaseModel): + """One ``output[]`` item, covering all ten wire types. + + Fields are conditional on ``type`` (the service omits the rest): + ``message`` -> role/content; ``reasoning`` -> summary/encrypted_content; + ``function_call`` -> name/arguments/call_id; ``web_search_call`` -> + action; ``code_interpreter_call`` -> code/outputs/container_id; + ``web_extractor_call`` -> goal/output/urls; ``web_search_image_call`` / + ``image_search_call`` -> name/arguments/output; ``mcp_call`` -> + server_label/name/arguments/output; ``file_search_call`` -> + queries/results. A single permissive model keeps every type readable + without a discriminated union the tolerant parser would have to guess. + """ + + model_config = ConfigDict(extra="allow") + + type: Optional[str] = None + id: Optional[str] = None + role: Optional[str] = None + status: Optional[str] = None + name: Optional[str] = None + arguments: Optional[str] = None + call_id: Optional[str] = None + content: List[ResponseContentPart] = [] + summary: List[SummaryText] = [] + encrypted_content: Optional[str] = None + action: Optional[Dict[str, Any]] = None + code: Optional[str] = None + outputs: List[Dict[str, Any]] = [] + container_id: Optional[str] = None + goal: Optional[str] = None + output: Optional[str] = None + urls: List[str] = [] + server_label: Optional[str] = None + queries: List[str] = [] + results: List[Dict[str, Any]] = [] + + +# -------------------------------------------------------------------------- +# Usage (two generations share one optional-field union) +# -------------------------------------------------------------------------- +class CacheWriteTokensDetails(BaseModel): + model_config = ConfigDict(extra="allow") + + ttl_1h_tokens: int = 0 + ttl_5m_tokens: int = 0 + + +class CacheCreation(BaseModel): + model_config = ConfigDict(extra="allow") + + ephemeral_5m_input_tokens: int = 0 + ephemeral_1h_input_tokens: int = 0 + cache_type: Optional[str] = None + + +class InputTokensDetails(BaseModel): + """Old gen: ``cached_tokens`` (+ multimodal text/image/audio). New gen + (Qwen4 / Kimi-K3.1+): ``cache_write_tokens`` + ``cache_write_tokens_details``. + Session cache adds ``cache_creation_input_tokens`` / ``cache_creation``.""" + + model_config = ConfigDict(extra="allow") + + cached_tokens: int = 0 + cache_write_tokens: int = 0 + cache_write_tokens_details: Optional[CacheWriteTokensDetails] = None + cache_creation_input_tokens: int = 0 + cache_creation: Optional[CacheCreation] = None + text_tokens: Optional[int] = None + image_tokens: Optional[int] = None + audio_tokens: Optional[int] = None + + +class OutputTokensDetails(BaseModel): + model_config = ConfigDict(extra="allow") + + reasoning_tokens: int = 0 + text_tokens: Optional[int] = None + + +class ResponseUsage(BaseModel): + """Token usage. ``x_details`` / ``x_tools`` / ``plugins`` are old-gen + only; the new structure omits them. No model hardcoding -- whichever + fields the service returns are surfaced.""" + + model_config = ConfigDict(extra="allow") + + input_tokens: int = 0 + output_tokens: int = 0 + total_tokens: int = 0 + input_tokens_details: Optional[InputTokensDetails] = None + output_tokens_details: Optional[OutputTokensDetails] = None + x_details: List[Dict[str, Any]] = [] + x_tools: Optional[Dict[str, Any]] = None + plugins: Optional[Dict[str, Any]] = None + prompt_tokens_details: Optional[Dict[str, Any]] = None + + +class ToolUsageCount(BaseModel): + model_config = ConfigDict(extra="allow") + + num_requests: int = 0 + count: Optional[int] = None + + +class ToolUsage(BaseModel): + """Built-in tool call counts, billed separately from token ``usage``. + Empty object ``{}`` when no tool ran.""" + + model_config = ConfigDict(extra="allow") + + web_search: Optional[ToolUsageCount] = None + code_interpreter: Optional[ToolUsageCount] = None + web_extractor: Optional[ToolUsageCount] = None + image_search: Optional[ToolUsageCount] = None + web_search_image: Optional[ToolUsageCount] = None + pdf_page_parser: Optional[ToolUsageCount] = None + + +class ResponseError(BaseModel): + """Failure object (``error``); null on success. Create uses + ``{code, message}``, retrieve/delete use ``{message, type}``.""" + + model_config = ConfigDict(extra="allow") + + code: Optional[str] = None + message: Optional[str] = None + type: Optional[str] = None + + +# -------------------------------------------------------------------------- +# Request-side configuration (also echoed on the response) +# -------------------------------------------------------------------------- +class Reasoning(BaseModel): + """Thinking control. ``effort``: none/minimal/low/medium/high/xhigh/max + (per-model mapping differs; not hard-validated so new tiers pass through). + ``summary="auto"`` (qwen4-max) returns a summary + encrypted_content.""" + + model_config = ConfigDict(extra="allow") + + effort: Optional[str] = None + summary: Optional[str] = None + + +class PromptCacheOptions(BaseModel): + """Explicit cache (qwen4-max). ``mode``: implicit (default) / explicit; + ``ttl``: 5m (default) / 1h.""" + + model_config = ConfigDict(extra="allow") + + mode: Optional[str] = None + ttl: Optional[str] = None + + +class OcrOptions(BaseModel): + """OCR task config (qwen3.5-ocr). ``task=document_parsing`` raises the + PDF page cap from 10 to 50.""" + + model_config = ConfigDict(extra="allow") + + task: Optional[str] = None + + +class PromptCacheBreakpoint(BaseModel): + """Manual cache breakpoint on an input block (qwen4-max).""" + + model_config = ConfigDict(extra="allow") + + mode: str = "explicit" + + +# -------------------------------------------------------------------------- +# Tools (eight built-in/custom types; plain dicts are accepted too) +# -------------------------------------------------------------------------- +class WebSearchTool(BaseModel): + model_config = ConfigDict(extra="allow") + + type: Literal["web_search"] = "web_search" + + +class WebExtractorTool(BaseModel): + """Must be declared together with ``web_search``.""" + + model_config = ConfigDict(extra="allow") + + type: Literal["web_extractor"] = "web_extractor" + + +class CodeInterpreterTool(BaseModel): + model_config = ConfigDict(extra="allow") + + type: Literal["code_interpreter"] = "code_interpreter" + + +class WebSearchImageTool(BaseModel): + model_config = ConfigDict(extra="allow") + + type: Literal["web_search_image"] = "web_search_image" + + +class ImageSearchTool(BaseModel): + model_config = ConfigDict(extra="allow") + + type: Literal["image_search"] = "image_search" + + +class FileSearchTool(BaseModel): + """Knowledge-base search. ``vector_store_ids`` currently accepts one id.""" + + model_config = ConfigDict(extra="allow") + + type: Literal["file_search"] = "file_search" + vector_store_ids: List[str] = [] + max_num_results: Optional[int] = None + + +class McpTool(BaseModel): + model_config = ConfigDict(extra="allow") + + type: Literal["mcp"] = "mcp" + server_protocol: Optional[str] = None + server_label: Optional[str] = None + server_url: Optional[str] = None + server_description: Optional[str] = None + headers: Optional[Dict[str, str]] = None + + +class FunctionTool(BaseModel): + model_config = ConfigDict(extra="allow") + + type: Literal["function"] = "function" + name: Optional[str] = None + description: Optional[str] = None + parameters: Optional[Dict[str, Any]] = None + strict: Optional[bool] = None + + +Tool = Union[ + WebSearchTool, + WebExtractorTool, + CodeInterpreterTool, + WebSearchImageTool, + ImageSearchTool, + FileSearchTool, + McpTool, + FunctionTool, + Dict[str, Any], +] + + +# -------------------------------------------------------------------------- +# Top-level responses +# -------------------------------------------------------------------------- +class Response(ResponseBase): + """A stored response (create / get). ``id`` is valid for 7 days and can + seed ``previous_response_id``. ``created_at`` is Unix seconds.""" + + id: Optional[str] = None + object: Optional[str] = "response" + created_at: Optional[int] = None + completed_at: Optional[int] = None + status: Optional[str] = None + model: Optional[str] = None + output: List[ResponseOutputItem] = [] + usage: Optional[ResponseUsage] = None + tool_usage: Optional[ToolUsage] = None + error: Optional[ResponseError] = None + incomplete_details: Optional[Dict[str, Any]] = None + previous_response_id: Optional[str] = None + conversation: Optional[Any] = None + store: Optional[bool] = None + metadata: Optional[Dict[str, Any]] = None + instructions: Optional[str] = None + tools: List[Dict[str, Any]] = [] + tool_choice: Optional[Any] = None + parallel_tool_calls: Optional[bool] = None + temperature: Optional[float] = None + top_p: Optional[float] = None + max_output_tokens: Optional[int] = None + frequency_penalty: Optional[float] = None + presence_penalty: Optional[float] = None + top_logprobs: Optional[int] = None + service_tier: Optional[str] = None + background: Optional[bool] = None + reasoning: Optional[Reasoning] = None + prompt_cache_options: Optional[PromptCacheOptions] = None + text: Optional[Dict[str, Any]] = None + ocr_result: Optional[Any] = None + + @property + def output_text(self) -> str: + """Concatenated text of every ``message`` item's output_text blocks.""" + parts: List[str] = [] + for item in self.output: + if item.type != "message": + continue + for part in item.content: + if part.type == "output_text" and part.text: + parts.append(part.text) + return "".join(parts) + + +class ResponseDeleted(ResponseBase): + """Result of ``delete``. The wire returns only ``{id, deleted}`` (no + ``object`` field, unlike the OpenAI SDK's ``response.deleted``).""" + + id: Optional[str] = None + deleted: bool = False + + +class InputItem(BaseModel): + """One ``input_items`` entry: a user/assistant message whose content + blocks are ``input_text`` (user) or ``output_text`` (assistant).""" + + model_config = ConfigDict(extra="allow") + + id: Optional[str] = None + type: Optional[str] = "message" + role: Optional[str] = None + status: Optional[str] = None + content: List[ResponseContentPart] = [] + + +class ResponseStreamEvent(ResponseBase): + """One streaming event. ``type`` + ``sequence_number`` identify it; + ``response.completed`` carries the full :class:`Response` and ends the + stream. Which of response/item/part/delta/text is populated depends on + ``type`` (all optional, permissive).""" + + type: Optional[str] = None + sequence_number: Optional[int] = None + response: Optional[Response] = None + item: Optional[ResponseOutputItem] = None + part: Optional[ResponseContentPart] = None + delta: Optional[str] = None + text: Optional[str] = None + item_id: Optional[str] = None + output_index: Optional[int] = None + content_index: Optional[int] = None + logprobs: Optional[Any] = None + + +# -------------------------------------------------------------------------- +# Parsers +# -------------------------------------------------------------------------- +def parse_response( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional[httpx.Response] = None, +) -> Response: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + Response, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) + + +def parse_response_deleted( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional[httpx.Response] = None, +) -> ResponseDeleted: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + ResponseDeleted, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) + + +def parse_stream_event( + body: Dict[str, Any], + *, + strict: bool = False, + response: Optional[httpx.Response] = None, +) -> ResponseStreamEvent: + payload = dict(body) if isinstance(body, dict) else {} + return parse_model( + ResponseStreamEvent, + {**payload, **response_envelope(payload)}, + strict=strict, + response=response, + ) diff --git a/examples/01_atomic_capabilities/models/models.py b/examples/01_atomic_capabilities/models/models.py index 45018a07..33fe9183 100644 --- a/examples/01_atomic_capabilities/models/models.py +++ b/examples/01_atomic_capabilities/models/models.py @@ -22,9 +22,10 @@ for model in page.models: print(f"model: {model.model}") - # List only Model Studio (Bailian) models - print("----- list models (provider=Bailian) -----") - page = client.models.list(provider="Bailian") + # Filter server-side by provider (repeated ``providers`` query param); + # total_count then reflects the filtered catalog and pagination walks it. + print("----- list models (providers=[qwen]) -----") + page = client.models.list(providers=["qwen"]) for model in page.models[:5]: print(f"model: {model.model}") diff --git a/tests/cli/test_config_store.py b/tests/cli/test_config_store.py index de9c77fe..7a0ec34b 100644 --- a/tests/cli/test_config_store.py +++ b/tests/cli/test_config_store.py @@ -103,7 +103,7 @@ class TestValidation: "key,value", [ ("protocol", "bogus"), - ("region", "mars-1"), + ("region", "mars.1"), ("output", "csv"), ("timeout", "0"), ("timeout", "-1"), @@ -142,6 +142,16 @@ def test_valid_protocol_and_region(self, config): set_value("region", "cn-beijing", path=config) assert load_raw(config)["protocol"] == "openai" + def test_unknown_but_safe_region_passes_through(self, config): + # A4: the SDK no longer hard-rejects a safe DNS region label, so + # the CLI (which mirrors resolve-time acceptance) must accept it + # too; a newly launched region works without an SDK upgrade. + assert set_value("region", "mars-1", path=config) == ( + "region", + "mars-1", + ) + assert load_raw(config)["region"] == "mars-1" + class TestPreservation: def test_comments_and_unknown_keys_survive(self, config): diff --git a/tests/protocols/test_anthropic_conformance.py b/tests/protocols/test_anthropic_conformance.py index d35a4dc6..bf3fc4ca 100644 --- a/tests/protocols/test_anthropic_conformance.py +++ b/tests/protocols/test_anthropic_conformance.py @@ -10,7 +10,10 @@ from dashscope import AsyncClient, Client from dashscope.protocols import AnthropicProtocol -from dashscope.protocols.anthropic import DEFAULT_MAX_TOKENS +from dashscope.protocols.anthropic import ( + DEFAULT_MAX_TOKENS, + WEB_SEARCH_BILLING_HEADER, +) MODEL = "qwen3-max" @@ -297,3 +300,100 @@ def handler(request): else: client.close() http_client.close() + + +# --- Adapter backfill: server web_search billing injection --------------- +# The native ``client.messages`` resource and the chat ``protocol=anthropic`` +# adapter share the same injection helpers, so declaring a server web_search +# tool through ``extra_parameters`` must enable search identically (C3). + +_WEB_SEARCH_TOOL = { + "type": "web_search_20250305", + "name": "web_search", + "max_uses": 8, +} + + +def test_adapter_web_search_injects_billing_into_string_system(): + request = _v2_request( + [ + {"role": "system", "content": "You are helpful."}, + {"role": "user", "content": "Search the news"}, + ], + extra_parameters={"tools": [_WEB_SEARCH_TOOL]}, + ) + assert request.body["system"] == [ + {"type": "text", "text": "You are helpful."}, + {"type": "text", "text": WEB_SEARCH_BILLING_HEADER}, + ] + assert request.body["tools"] == [_WEB_SEARCH_TOOL] + + +def test_adapter_web_search_injects_billing_without_system(): + request = _v2_request( + [{"role": "user", "content": "Search the news"}], + extra_parameters={"tools": [_WEB_SEARCH_TOOL]}, + ) + assert request.body["system"] == [ + {"type": "text", "text": WEB_SEARCH_BILLING_HEADER}, + ] + + +def test_adapter_web_search_caller_marker_wins(): + marker_system = f"Custom rules. {WEB_SEARCH_BILLING_HEADER}" + request = _v2_request( + [ + {"role": "system", "content": marker_system}, + {"role": "user", "content": "Search the news"}, + ], + extra_parameters={"tools": [_WEB_SEARCH_TOOL]}, + ) + assert request.body["system"] == marker_system + + +def test_adapter_custom_function_named_web_search_not_injected(): + request = _v2_request( + [ + {"role": "system", "content": "You are helpful."}, + {"role": "user", "content": "hi"}, + ], + extra_parameters={ + "tools": [ + { + "type": "function", + "name": "web_search", + "input_schema": {"type": "object", "properties": {}}, + }, + ], + }, + ) + assert request.body["system"] == "You are helpful." + + +def test_adapter_web_fetch_alone_not_injected(): + request = _v2_request( + [ + {"role": "system", "content": "You are helpful."}, + {"role": "user", "content": "Fetch a page"}, + ], + extra_parameters={ + "tools": [ + { + "type": "web_fetch_20250910", + "name": "web_fetch", + "max_uses": 3, + }, + ], + }, + ) + assert request.body["system"] == "You are helpful." + + +def test_adapter_no_server_tools_leaves_system_untouched(): + request = _v2_request( + [ + {"role": "system", "content": "You are helpful."}, + {"role": "user", "content": "hi"}, + ], + ) + assert request.body["system"] == "You are helpful." diff --git a/tests/protocols/test_batch_e2e.py b/tests/protocols/test_batch_e2e.py new file mode 100644 index 00000000..8b201a51 --- /dev/null +++ b/tests/protocols/test_batch_e2e.py @@ -0,0 +1,131 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Live gated e2e for the Batch workflow (B3 full closed loop). + +Uses the public, zero-inference-cost test model ``batch-test-model`` with +endpoint ``/v1/chat/ds-test`` (documented in the Bailian OpenAI-compatible +Batch guide): it skips inference and returns a fixed +``{"content": "This is a test result."}``, so the whole upload -> create -> +wait -> download_output loop can be exercised cheaply with a public model. + +Skipped unless explicitly opted in. Creating batch jobs is a write side +effect, so beyond the usual key/workspace gate this requires +``DASHSCOPE_E2E_BATCH=1``:: + + DASHSCOPE_API_KEY=... DASHSCOPE_WORKSPACE=... DASHSCOPE_E2E_BATCH=1 \\ + pytest tests/protocols/test_batch_e2e.py + +The test model caps input at 1 MB / 100 rows and 2 parallel jobs; this case +uploads 2 rows and cleans up its files afterwards. +""" + +from __future__ import annotations + +import json +import os + +import pytest + +from dashscope import Client + +_ENDPOINT = "/v1/chat/ds-test" +_MODEL = "batch-test-model" + + +def _opted_in() -> bool: + return os.environ.get("DASHSCOPE_E2E_BATCH", "").strip().lower() in ( + "1", + "true", + "yes", + ) + + +def _make_client(): + api_key = os.environ.get("DASHSCOPE_API_KEY") + workspace = os.environ.get("DASHSCOPE_WORKSPACE") + if not api_key: + pytest.skip("DASHSCOPE_API_KEY not set") + if not workspace: + pytest.skip("DASHSCOPE_WORKSPACE not set") + if not _opted_in(): + pytest.skip("set DASHSCOPE_E2E_BATCH=1 to create live batch jobs") + return Client(api_key=api_key, workspace=workspace, max_retries=1) + + +def _rows(): + return [ + { + "custom_id": "1", + "method": "POST", + "url": _ENDPOINT, + "body": { + "model": _MODEL, + "messages": [{"role": "user", "content": "你好!"}], + }, + }, + { + "custom_id": "2", + "method": "POST", + "url": _ENDPOINT, + "body": { + "model": _MODEL, + "messages": [{"role": "user", "content": "What is 2+2?"}], + }, + }, + ] + + +def test_batch_full_loop_with_test_model(tmp_path): + client = _make_client() + input_path = tmp_path / "test_model.jsonl" + input_path.write_text( + "".join(json.dumps(r) + "\n" for r in _rows()), + encoding="utf-8", + ) + uploaded = [] + with client: + assert ( + client.batches.validate_input( + str(input_path), + endpoint=_ENDPOINT, + ) + == 2 + ) + file_obj = client.batches.files.upload( + file_path=str(input_path), + purpose="batch", + ) + uploaded.append(file_obj.id) + batch = client.batches.create( + input_file_id=file_obj.id, + endpoint=_ENDPOINT, + completion_window="24h", + ) + batch = client.batches.wait( + batch, + poll_interval=5, + max_interval=30, + timeout=300, + ) + assert batch.status == "completed", batch.model_dump() + try: + content = client.batches.download_output(batch) + assert content is not None + assert "This is a test result." in content.text + rows = [json.loads(line) for line in content.text.splitlines()] + assert {r["custom_id"] for r in rows} == {"1", "2"} + for row in rows: + assert row["response"]["status_code"] == 200 + if batch.output_file_id: + uploaded.append(batch.output_file_id) + error_content = client.batches.download_error(batch) + # A clean test-model batch has no failed rows. + assert error_content is None or isinstance(error_content, bytes) + if batch.error_file_id: + uploaded.append(batch.error_file_id) + finally: + for file_id in uploaded: + try: + client.batches.files.delete(file_id) + except Exception: # noqa: BLE001 - best-effort cleanup + pass diff --git a/tests/test_audio_omni_session.py b/tests/test_audio_omni_session.py index 5979be0f..d19ca007 100644 --- a/tests/test_audio_omni_session.py +++ b/tests/test_audio_omni_session.py @@ -1560,6 +1560,67 @@ def test_live38_raw_send_event_bypasses_helper_validation( assert ws.close_calls == ws.recv_calls == 0 +@pytest.mark.parametrize("model", _LIVE38_MODELS) +@pytest.mark.parametrize( + "message", + [ + "Parse RealtimeEvent error: Common error!", + "Invalid value for field 'session.output_modalities'.", + ], + ids=["legacy-generic", "field-specific"], +) +def test_live38_invalid_output_modalities_surfaces_server_message( + model_opened, + message, +): + # Regression: the server replaced the generic parse error with a + # field-specific rejection for invalid output_modalities; the SDK + # must pass the server message through and keep the session usable. + session, ws = model_opened + session.update_session(output_modalities=["video"]) + request_id = json.loads(ws.sent[-1])["event_id"] + assert _payloads(ws) == [ + { + "type": "session.update", + "session": {"output_modalities": ["video"]}, + }, + ] + rejected = { + "type": "error", + "event_id": "server-error", + "error": { + "type": "invalid_request_error", + "code": "InvalidParameter", + "message": message, + "event_id": request_id, + }, + } + ws.inbox.append(rejected) + with pytest.raises(BadRequestError, match=re.escape(message)) as caught: + session.recv_event() + assert caught.value.code == "InvalidParameter" + assert caught.value.body == rejected + assert session.last_message == rejected + assert ws.close_calls == 0 + + session.update_session(output_modalities=["text", "audio"]) + assert _payloads(ws)[-1] == { + "type": "session.update", + "session": {"output_modalities": ["text", "audio"]}, + } + updated = { + "type": "session.updated", + "session": { + "id": "live-session", + "output_modalities": ["text", "audio"], + }, + } + ws.inbox.append(updated) + assert session.recv_event() == updated + assert session.session_id == "live-session" + assert ws.close_calls == 0 + + @pytest.mark.parametrize("model", _QWEN_AUDIO_MODELS) @pytest.mark.parametrize( "options, expected", diff --git a/tests/test_batch_chat.py b/tests/test_batch_chat.py new file mode 100644 index 00000000..311558b3 --- /dev/null +++ b/tests/test_batch_chat.py @@ -0,0 +1,524 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Tests for client.batch_chat.completions (B4). + +Batch Chat is the OpenAI-compatible chat wire on a dedicated batch gateway +(``batch.dashscope.aliyuncs.com/compatible-mode/v1``), synchronous and +non-streaming, with a 60..3600s timeout (default 3600s). These cover the +batch host routing + explicit base_url override, the OpenAI body shape, +ChatCompletion parsing, the batch_chat2 SDK header, timeout validation, +raw/error envelopes and async symmetry. + +Mock conventions match test_batches.py / test_responses.py. +""" + +# Mock handlers intentionally ignore the request argument; pytest fixture +# injection looks like unused/redefined names to pylint. +# pylint: disable=unused-argument,redefined-outer-name + +from __future__ import annotations + +import json + +import httpx +import pytest + +from dashscope import AsyncClient, Client +from dashscope.errors import BadRequestError, DashScopeError +from dashscope.resources.batch_chat import ( + BATCH_DEFAULT_TIMEOUT, + BATCH_GATEWAY_BASE, + _resolve_timeout, +) +from dashscope.transport._response import APIResponse +from dashscope.types.completions import ChatCompletion + +BASE_URL = "https://api.test.local/api/v1" + +_COMPLETION = { + "id": "chatcmpl-abc", + "object": "chat.completion", + "created": 1763618557, + "model": "qwen-plus", + "choices": [ + { + "index": 0, + "finish_reason": "stop", + "message": {"role": "assistant", "content": "你好"}, + }, + ], + "usage": { + "prompt_tokens": 10, + "completion_tokens": 5, + "total_tokens": 15, + }, +} + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +@pytest.fixture +def clean_env(monkeypatch): + from dashscope._config import settings + + for name in ( + "DASHSCOPE_API_KEY", + "DASHSCOPE_BASE_URL", + "DASHSCOPE_HTTP_BASE_URL", + "DASHSCOPE_WORKSPACE", + "DASHSCOPE_REGION", + "DASHSCOPE_PROTOCOL", + "DASHSCOPE_CONFIG", + ): + monkeypatch.delenv(name, raising=False) + settings.clear() + yield monkeypatch + settings.clear() + + +def _ok_handler(captured=None): + def handler(request): + if captured is not None: + captured["method"] = request.method + captured["url"] = str(request.url) + captured["host"] = request.url.host + captured["path"] = request.url.path + captured["body"] = json.loads(request.content) + captured["headers"] = dict(request.headers) + return httpx.Response(200, json=_COMPLETION) + + return handler + + +# -------------------------------------------------------------------------- +# routing +# -------------------------------------------------------------------------- + + +def test_default_batch_host_and_path(clean_env): + captured = {} + # No explicit base_url -> the documented batch gateway, regardless of + # the client's native chat protocol default. + client = _make_client(_ok_handler(captured), base_url=None) + client.batch_chat.completions.create(model="qwen-plus", messages="hi") + assert captured["method"] == "POST" + assert captured["host"] == "batch.dashscope.aliyuncs.com" + assert captured["path"] == "/compatible-mode/v1/chat/completions" + assert captured["url"] == BATCH_GATEWAY_BASE + "/chat/completions" + client.close() + + +def test_explicit_base_url_override(clean_env): + captured = {} + client = _make_client(_ok_handler(captured)) + client.batch_chat.completions.create(model="qwen-plus", messages="hi") + assert captured["host"] == "api.test.local" + assert captured["path"] == "/api/v1/chat/completions" + client.close() + + +def test_sdk_header_batch_chat2(clean_env): + captured = {} + client = _make_client(_ok_handler(captured)) + client.batch_chat.completions.create(model="qwen-plus", messages="hi") + assert captured["headers"]["x-dashscope-sdk-client"].endswith( + "/batch_chat2", + ) + client.close() + + +# -------------------------------------------------------------------------- +# wire body + parsing +# -------------------------------------------------------------------------- + + +def test_wire_body_openai_shape(clean_env): + captured = {} + client = _make_client(_ok_handler(captured)) + client.batch_chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "hi"}], + temperature=0.5, + max_tokens=128, + enable_thinking=False, + parameters={"foo": "bar"}, + ) + body = captured["body"] + assert body["model"] == "qwen-plus" + assert body["messages"] == [{"role": "user", "content": "hi"}] + assert body["temperature"] == 0.5 + assert body["max_tokens"] == 128 + # enable_thinking is a top-level body param (not nested), per contract. + assert body["enable_thinking"] is False + assert body["foo"] == "bar" + # Non-streaming: no stream flag on the batch wire. + assert "stream" not in body + client.close() + + +def test_strict_protocol_options_reject_unknown_params(clean_env): + client = _make_client( + _ok_handler(), + protocol_options={"strict": True}, + ) + with pytest.raises(DashScopeError, match="strict mode"): + client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + repetition_penalty=1.1, + ) + client.close() + + +async def test_async_strict_protocol_options_reject_unknown_params(clean_env): + client = _make_async_client( + _ok_handler(), + protocol_options={"strict": True}, + ) + with pytest.raises(DashScopeError, match="strict mode"): + await client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + repetition_penalty=1.1, + ) + await client.aclose() + + +def test_string_messages_normalized(clean_env): + captured = {} + client = _make_client(_ok_handler(captured)) + client.batch_chat.completions.create(model="qwen-plus", messages="hi") + assert captured["body"]["messages"] == [{"role": "user", "content": "hi"}] + client.close() + + +def test_parse_completion(clean_env): + client = _make_client(_ok_handler()) + resp = client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + ) + assert isinstance(resp, ChatCompletion) + assert resp.is_error is False + assert resp.request_id == "chatcmpl-abc" + assert resp.model == "qwen-plus" + assert resp.choices[0].message.content == "你好" + assert resp.usage.total_tokens == 15 + client.close() + + +def test_raw_returns_apiresponse(clean_env): + client = _make_client(_ok_handler()) + raw = client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + raw=True, + ) + assert isinstance(raw, APIResponse) + assert raw.http_response.status_code == 200 + assert raw.json()["id"] == "chatcmpl-abc" + client.close() + + +# -------------------------------------------------------------------------- +# timeout contract +# -------------------------------------------------------------------------- + + +def test_resolve_timeout_default_and_bounds(): + assert _resolve_timeout(None) == BATCH_DEFAULT_TIMEOUT == 3600.0 + assert _resolve_timeout(60) == 60.0 + assert _resolve_timeout(1800) == 1800.0 + assert _resolve_timeout(3600) == 3600.0 + + +@pytest.mark.parametrize("bad", [0, 30, 59, 3601, 7200, -1]) +def test_resolve_timeout_out_of_range(bad): + with pytest.raises(ValueError, match="between 60 and 3600"): + _resolve_timeout(bad) + + +def test_create_rejects_short_timeout_before_network(clean_env): + def handler(request): + raise AssertionError("network must not be reached on bad timeout") + + client = _make_client(handler) + with pytest.raises(ValueError, match="between 60 and 3600"): + client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + timeout=30, + ) + client.close() + + +def test_timeout_forwarded_to_transport(clean_env, monkeypatch): + captured = {} + client = _make_client(_ok_handler()) + orig = client.transport.request_api + + def spy(*args, **kwargs): + captured["timeout"] = kwargs.get("timeout") + return orig(*args, **kwargs) + + monkeypatch.setattr(client.transport, "request_api", spy) + client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + timeout=1800, + ) + assert captured["timeout"] == 1800.0 + client.close() + + +def test_default_timeout_forwarded(clean_env, monkeypatch): + captured = {} + client = _make_client(_ok_handler()) + orig = client.transport.request_api + + def spy(*args, **kwargs): + captured["timeout"] = kwargs.get("timeout") + return orig(*args, **kwargs) + + monkeypatch.setattr(client.transport, "request_api", spy) + client.batch_chat.completions.create(model="qwen-plus", messages="hi") + assert captured["timeout"] == 3600.0 + client.close() + + +# -------------------------------------------------------------------------- +# validation +# -------------------------------------------------------------------------- + + +def test_empty_messages_raises(clean_env): + client = _make_client(_ok_handler()) + with pytest.raises(ValueError, match="messages must not be empty"): + client.batch_chat.completions.create(model="qwen-plus", messages=[]) + client.close() + + +def test_empty_model_raises(clean_env): + client = _make_client(_ok_handler()) + with pytest.raises(ValueError, match="model must be a non-empty string"): + client.batch_chat.completions.create(model=" ", messages="hi") + client.close() + + +# -------------------------------------------------------------------------- +# errors +# -------------------------------------------------------------------------- + + +def test_http_error_raises(clean_env): + def handler(request): + return httpx.Response( + 400, + json={"error": {"code": "InvalidParameter", "message": "bad"}}, + headers={"x-request-id": "rid-err"}, + ) + + client = _make_client(handler) + with pytest.raises(BadRequestError) as ei: + client.batch_chat.completions.create(model="qwen-plus", messages="hi") + assert ei.value.code == "InvalidParameter" + assert ei.value.request_id == "rid-err" + client.close() + + +def test_error_envelope_when_not_raising(clean_env): + def handler(request): + return httpx.Response( + 404, + json={"error": {"code": "NotFound", "message": "gone"}}, + headers={"x-request-id": "rid-404"}, + ) + + client = _make_client(handler, raise_on_error=False) + resp = client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + ) + assert resp.is_error is True + assert resp.status_code == 404 + assert resp.code == "NotFound" + assert resp.message == "gone" + assert resp.request_id == "rid-404" + client.close() + + +def test_business_error_layer(clean_env): + body = { + "code": "InvalidParameter", + "message": "unsupported", + "request_id": "rid-biz", + } + + def handler(request): + return httpx.Response(200, json=body) + + client = _make_client(handler) + with pytest.raises(BadRequestError): + client.batch_chat.completions.create(model="qwen-plus", messages="hi") + client.close() + + client = _make_client(handler, raise_on_error=False) + resp = client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + ) + assert resp.is_error is True + assert resp.code == "InvalidParameter" + client.close() + + +def test_raw_bypasses_error_check(clean_env): + def handler(request): + return httpx.Response(400, json={"error": {"message": "bad"}}) + + client = _make_client(handler) + raw = client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + raw=True, + ) + assert raw.http_response.status_code == 400 + assert raw.json()["error"]["message"] == "bad" + client.close() + + +# -------------------------------------------------------------------------- +# async symmetry +# -------------------------------------------------------------------------- + + +@pytest.mark.asyncio +async def test_async_default_host_and_parse(clean_env): + captured = {} + client = _make_async_client(_ok_handler(captured), base_url=None) + resp = await client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + ) + assert captured["host"] == "batch.dashscope.aliyuncs.com" + assert captured["path"] == "/compatible-mode/v1/chat/completions" + assert resp.choices[0].message.content == "你好" + assert resp.request_id == "chatcmpl-abc" + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_error_envelope_when_not_raising(clean_env): + def handler(request): + return httpx.Response( + 404, + json={"error": {"code": "NotFound", "message": "gone"}}, + ) + + client = _make_async_client(handler, raise_on_error=False) + resp = await client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + ) + assert resp.is_error is True + assert resp.code == "NotFound" + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_raw(clean_env): + client = _make_async_client(_ok_handler()) + raw = await client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + raw=True, + ) + assert isinstance(raw, APIResponse) + assert raw.json()["id"] == "chatcmpl-abc" + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_timeout_validation(clean_env): + client = _make_async_client(_ok_handler()) + with pytest.raises(ValueError, match="between 60 and 3600"): + await client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + timeout=3601, + ) + await client.aclose() + + +# -------------------------------------------------------------------------- +# retry policy (billed POST: scheduled-or-not is unknowable after a drop) +# -------------------------------------------------------------------------- + + +def test_create_default_no_retry(clean_env): + attempts = [] + + def handler(request): + attempts.append(1) + return httpx.Response(503, json={"message": "busy"}) + + client = _make_client(handler) + with pytest.raises(DashScopeError): + client.batch_chat.completions.create(model="qwen-plus", messages="hi") + # The transport cannot tell whether the request was already scheduled + # (and billed) -> create must not auto-retry on the client default. + assert len(attempts) == 1 + client.close() + + +def test_create_explicit_max_retries_retries(clean_env, monkeypatch): + attempts = [] + + def handler(request): + attempts.append(1) + if len(attempts) < 3: + return httpx.Response(503, json={"message": "busy"}) + return httpx.Response(200, json=_COMPLETION) + + from dashscope.transport import http as transport_http + + monkeypatch.setattr(transport_http, "_sleep", lambda seconds: None) + client = _make_client(handler) + resp = client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + max_retries=2, + ) + assert isinstance(resp, ChatCompletion) + assert len(attempts) == 3 + client.close() + + +@pytest.mark.asyncio +async def test_async_create_default_no_retry(clean_env): + attempts = [] + + def handler(request): + attempts.append(1) + return httpx.Response(503, json={"message": "busy"}) + + client = _make_async_client(handler) + with pytest.raises(DashScopeError): + await client.batch_chat.completions.create( + model="qwen-plus", + messages="hi", + ) + assert len(attempts) == 1 + await client.aclose() diff --git a/tests/test_batch_files.py b/tests/test_batch_files.py new file mode 100644 index 00000000..0ef8ab52 --- /dev/null +++ b/tests/test_batch_files.py @@ -0,0 +1,836 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Tests for client.batches.files (B1: compatible-mode File sub-resource). + +The batch File plane sits under /compatible-mode/v1/files on every gateway, +independent of the client's chat ``protocol`` -- the routing tests pin that +for native / openai / anthropic alike, mirroring test_decision.py. It is a +different wire from the native client.files (multipart ``file`` singular, +flat OpenAI object, ``after``/``has_more`` cursor), so these tests assert +that shape rather than the native ``data.uploaded_files`` / page_no one. +""" + +# Mock handlers intentionally ignore the request argument; pytest fixture +# injection looks like unused/redefined names to pylint. +# pylint: disable=unused-argument,redefined-outer-name + +from __future__ import annotations + +import json + +import httpx +import pytest + +from dashscope import AsyncClient, Client +from dashscope.errors import ( + BadRequestError, + NotFoundError, + RateLimitError, + SdkError, +) +from dashscope.resources.batches import ( + BatchFile, + BatchFileList, + FileContent, +) +from dashscope.transport._ident import sdk_client_value + +BASE_URL = "https://api.test.local/api/v1" +_WS_HOST = "https://ws-123.cn-beijing.maas.aliyuncs.com" +_COMPAT_FILES = "/compatible-mode/v1/files" + +# A flat OpenAI-compatible file object (upload / get response). +_FILE_BODY = { + "id": "file-batch-abc123", + "object": "file", + "bytes": 2048, + "created_at": 1730000000, + "filename": "batch_input.jsonl", + "purpose": "batch", + "status": "processed", +} + +_JSONL = b'{"custom_id": "1"}\n{"custom_id": "2"}\n' + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +@pytest.fixture +def clean_env(monkeypatch): + from dashscope._config import settings + + for name in ( + "DASHSCOPE_API_KEY", + "DASHSCOPE_BASE_URL", + "DASHSCOPE_HTTP_BASE_URL", + "DASHSCOPE_WORKSPACE", + "DASHSCOPE_REGION", + "DASHSCOPE_PROTOCOL", + "DASHSCOPE_CONFIG", + ): + monkeypatch.delenv(name, raising=False) + settings.clear() + yield monkeypatch + settings.clear() + + +def _jsonl_file(tmp_path, name="batch_input.jsonl"): + path = tmp_path / name + path.write_bytes(_JSONL) + return str(path) + + +# -------------------------------------------------------------------------- +# upload +# -------------------------------------------------------------------------- + + +def test_upload_builds_multipart_and_parses_flat_object(tmp_path): + captured = {} + + def handler(request): + captured["path"] = request.url.path + captured["method"] = request.method + captured["content_type"] = request.headers.get("content-type", "") + captured["body"] = request.content.decode("utf-8", "replace") + return httpx.Response(200, json=_FILE_BODY) + + client = _make_client(handler) + resp = client.batches.files.upload(file_path=_jsonl_file(tmp_path)) + # Explicit base_url stays the service root (same rule as chat/decision). + assert captured["path"] == "/api/v1/files" + assert captured["method"] == "POST" + assert captured["content_type"].startswith("multipart/form-data") + # Compat-mode uses ``file`` (singular) and DOES send purpose, unlike the + # native client.files upload (``files`` plural, purpose omitted). + assert 'name="file"' in captured["body"] + assert 'name="files"' not in captured["body"] + assert 'name="purpose"' in captured["body"] + assert "batch" in captured["body"] + assert "batch_input.jsonl" in captured["body"] + assert resp.id == "file-batch-abc123" + assert resp.file_id == "file-batch-abc123" + assert resp.object == "file" + assert resp.bytes == 2048 + assert resp.created_at == 1730000000 + assert resp.filename == "batch_input.jsonl" + assert resp.purpose == "batch" + assert resp.is_error is False + client.close() + + +def test_upload_missing_file_is_catalog_io_error(tmp_path): + client = _make_client(lambda r: httpx.Response(200, json=_FILE_BODY)) + with pytest.raises(SdkError) as ei: + client.batches.files.upload(file_path=str(tmp_path / "nope.jsonl")) + assert ei.value.code == "sdk.IoError" + assert "nope.jsonl" in ei.value.message + assert ei.value.allow_retry is False + client.close() + + +def test_upload_batch_purpose_requires_jsonl(tmp_path): + client = _make_client(lambda r: httpx.Response(200, json=_FILE_BODY)) + bad = tmp_path / "bad.jsonl" + bad.write_text("not json\n", encoding="utf-8") + with pytest.raises(ValueError, match="jsonl"): + client.batches.files.upload(file_path=str(bad), purpose="batch") + # file-extract accepts non-JSONL documents: no JSONL gate for it. + resp = client.batches.files.upload( + file_path=str(bad), + purpose="file-extract", + ) + assert resp.id == "file-batch-abc123" + client.close() + + +def test_upload_blank_lines_match_validate_input(tmp_path): + row = ( + '{"custom_id": "r1", "method": "POST", ' + '"url": "/v1/chat/completions", ' + '"body": {"model": "qwen-plus", "messages": []}}' + ) + path = tmp_path / "blank.jsonl" + path.write_text(f"{row}\n\n{row.replace('r1', 'r2')}\n", encoding="utf-8") + client = _make_client(lambda r: httpx.Response(200, json=_FILE_BODY)) + # validate_input tolerates blank lines; the upload gate must agree. + assert client.batches.validate_input(str(path)) == 2 + resp = client.batches.files.upload(file_path=str(path), purpose="batch") + assert resp.id == "file-batch-abc123" + client.close() + + +def test_upload_empty_file_rejected_like_validate_input(tmp_path): + path = tmp_path / "empty.jsonl" + path.write_text("\n \n", encoding="utf-8") + client = _make_client(lambda r: httpx.Response(200, json=_FILE_BODY)) + with pytest.raises(ValueError, match="no batch input rows"): + client.batches.validate_input(str(path)) + with pytest.raises(ValueError, match="no batch input rows"): + client.batches.files.upload(file_path=str(path), purpose="batch") + client.close() + + +def test_upload_retry_resends_full_body(tmp_path, monkeypatch): + bodies = [] + + def handler(request): + bodies.append(request.content) + if len(bodies) == 1: + return httpx.Response(503, json={"message": "busy"}) + return httpx.Response(200, json=_FILE_BODY) + + from dashscope.transport import http as transport_http + + monkeypatch.setattr(transport_http, "_sleep", lambda seconds: None) + client = _make_client(handler) + resp = client.batches.files.upload(file_path=_jsonl_file(tmp_path)) + assert resp.id == "file-batch-abc123" + assert len(bodies) == 2 + for body in bodies: + assert b'{"custom_id": "1"}' in body + assert b"batch_input.jsonl" in body + client.close() + + +# -------------------------------------------------------------------------- +# content download +# -------------------------------------------------------------------------- + + +def test_content_download_returns_raw_bytes(tmp_path): + captured = {} + + def handler(request): + captured["path"] = request.url.path + captured["method"] = request.method + # JSONL is many JSON docs, not one: a JSON parse would fail. The + # download must hand back the raw bytes untouched. + return httpx.Response( + 200, + content=_JSONL, + headers={ + "content-type": "application/jsonl", + "x-request-id": "rid-dl", + }, + ) + + client = _make_client(handler) + content = client.batches.files.content("file-batch-out") + assert captured["path"] == "/api/v1/files/file-batch-out/content" + assert captured["method"] == "GET" + assert isinstance(content, FileContent) + assert isinstance(content, bytes) + assert bytes(content) == _JSONL + assert content.text == _JSONL.decode("utf-8") + assert content.request_id == "rid-dl" + assert content.status_code == 200 + assert content.is_error is False + dest = content.write_to_file(tmp_path / "nested" / "result.jsonl") + assert dest.read_bytes() == _JSONL + client.close() + + +def test_content_error_raises(): + def handler(request): + return httpx.Response( + 404, + json={"error": {"message": "file does not exist"}}, + headers={"x-request-id": "rid-404"}, + ) + + client = _make_client(handler) + with pytest.raises(NotFoundError) as ei: + client.batches.files.content("missing") + assert ei.value.status_code == 404 + assert ei.value.request_id == "rid-404" + client.close() + + +def test_content_error_no_raise_reports_status(): + def handler(request): + return httpx.Response( + 404, + json={"error": {"message": "file does not exist"}}, + headers={"x-request-id": "rid-404"}, + ) + + client = _make_client(handler, raise_on_error=False) + content = client.batches.files.content("missing") + assert content.is_error is True + assert content.status_code == 404 + assert content.request_id == "rid-404" + # The body is the gateway's error bytes, not a parsed envelope. + assert b"file does not exist" in bytes(content) + client.close() + + +# -------------------------------------------------------------------------- +# list (cursor pagination) +# -------------------------------------------------------------------------- + + +def test_list_cursor_pagination_preserves_filters(): + seen = [] + + def handler(request): + after = request.url.params.get("after") + seen.append( + { + "path": request.url.path, + "purpose": request.url.params.get("purpose"), + "after": after, + "limit": request.url.params.get("limit"), + }, + ) + if after is None: + return httpx.Response( + 200, + json={ + "object": "list", + "data": [{"id": "f1"}, {"id": "f2"}], + "has_more": True, + }, + ) + return httpx.Response( + 200, + json={ + "object": "list", + "data": [{"id": "f3"}], + "has_more": False, + }, + ) + + client = _make_client(handler) + page = client.batches.files.list(purpose="batch", limit=2) + assert page.object == "list" + assert [f.id for f in page.items] == ["f1", "f2"] + assert page.has_more is True + assert page.has_next_page() is True + pages = list(page.iter_pages()) + assert [[f.id for f in p] for p in pages] == [["f1", "f2"], ["f3"]] + assert pages[-1].has_next_page() is False + assert pages[-1].next_page() is None + # The cursor callback re-sends purpose/limit and advances ``after``. + assert seen[0] == { + "path": "/api/v1/files", + "purpose": "batch", + "after": None, + "limit": "2", + } + assert seen[1]["after"] == "f2" + assert seen[1]["purpose"] == "batch" + assert seen[1]["limit"] == "2" + client.close() + + +def test_list_empty_page_has_no_next(): + def handler(request): + return httpx.Response( + 200, + json={"object": "list", "data": [], "has_more": False}, + ) + + client = _make_client(handler) + page = client.batches.files.list() + assert page.items == [] + assert page.has_next_page() is False + assert list(page.iter_pages()) == [page] + client.close() + + +def test_list_params_validation_and_omission(): + captured = {} + + def handler(request): + captured["params"] = dict(request.url.params) + return httpx.Response( + 200, + json={"object": "list", "data": [], "has_more": False}, + ) + + client = _make_client(handler) + for bad_limit in (0, 2001): + with pytest.raises(ValueError, match="limit"): + client.batches.files.list(limit=bad_limit) + # Unset optionals stay off the wire. + client.batches.files.list() + assert captured["params"] == {} + client.batches.files.list( + purpose="batch", + after="f9", + limit=2000, + create_before="fb", + create_after="fa", + ) + assert captured["params"] == { + "purpose": "batch", + "after": "f9", + "limit": "2000", + "create_before": "fb", + "create_after": "fa", + } + client.close() + + +def test_sync_next_page_rejects_async_callback(): + page = BatchFileList(data=[BatchFile(id="f1")], has_more=True) + + async def fetch(cursor): + return BatchFileList(data=[BatchFile(id="f2")], has_more=False) + + page.bind_pagination(fetch) + with pytest.raises(TypeError, match="next_page_async"): + page.next_page() + + +# -------------------------------------------------------------------------- +# get / delete +# -------------------------------------------------------------------------- + + +def test_get_and_delete(): + seen = [] + + def handler(request): + seen.append((request.method, request.url.path)) + if request.method == "DELETE": + return httpx.Response( + 200, + json={ + "id": "file-batch-abc123", + "object": "file", + "deleted": True, + }, + ) + return httpx.Response(200, json=_FILE_BODY) + + client = _make_client(handler) + got = client.batches.files.get("file-batch-abc123") + assert got.id == "file-batch-abc123" + assert got.purpose == "batch" + deleted = client.batches.files.delete("file-batch-abc123") + assert deleted.deleted is True + assert deleted.id == "file-batch-abc123" + assert seen == [ + ("GET", "/api/v1/files/file-batch-abc123"), + ("DELETE", "/api/v1/files/file-batch-abc123"), + ] + client.close() + + +@pytest.mark.parametrize("file_id", ["", " "]) +def test_empty_file_id_rejected_locally(file_id): + client = _make_client(lambda r: httpx.Response(200, json=_FILE_BODY)) + for call in ( + client.batches.files.get, + client.batches.files.delete, + client.batches.files.content, + ): + with pytest.raises(ValueError, match="file_id"): + call(file_id) + client.close() + + +def test_file_id_percent_encoded_in_path(): + seen = [] + + def handler(request): + seen.append(request.url.raw_path) + if request.url.path.endswith("/content"): + return httpx.Response(200, content=_JSONL) + if request.method == "DELETE": + return httpx.Response( + 200, + json={"id": "f1", "object": "file", "deleted": True}, + ) + return httpx.Response(200, json=_FILE_BODY) + + client = _make_client(handler) + tricky = "file/batch?x#y" + client.batches.files.get(tricky) + client.batches.files.content(tricky) + client.batches.files.delete(tricky) + # '/', '?' and '#' stay inside one path segment instead of retargeting + # the request to another path or query. + encoded = b"/api/v1/files/file%2Fbatch%3Fx%23y" + assert seen == [encoded, encoded + b"/content", encoded] + client.close() + + +async def test_async_file_id_percent_encoded_in_path(): + seen = [] + + def handler(request): + seen.append(request.url.raw_path) + return httpx.Response(200, json=_FILE_BODY) + + client = _make_async_client(handler) + await client.batches.files.get("file/batch?x#y") + assert seen == [b"/api/v1/files/file%2Fbatch%3Fx%23y"] + await client.aclose() + + +# -------------------------------------------------------------------------- +# error mapping +# -------------------------------------------------------------------------- + + +def test_http_error_maps_openai_nested_body(): + def handler(request): + return httpx.Response( + 400, + json={ + "error": { + "code": "InvalidParameter", + "message": "purpose is invalid", + }, + }, + headers={"x-request-id": "rid-err"}, + ) + + client = _make_client(handler) + with pytest.raises(BadRequestError) as ei: + client.batches.files.get("file-batch-abc123") + assert ei.value.code == "InvalidParameter" + assert ei.value.status_code == 400 + assert ei.value.request_id == "rid-err" + client.close() + + +def test_http_429_maps_rate_limit(): + def handler(request): + return httpx.Response(429, json={"error": {"message": "slow down"}}) + + client = _make_client(handler) + with pytest.raises(RateLimitError): + client.batches.files.list() + client.close() + + +def test_error_envelope_when_not_raising(): + def handler(request): + return httpx.Response( + 404, + json={ + "error": { + "code": "File.NotFound", + "message": "file file-batch-typo does not exist", + }, + }, + headers={"x-request-id": "rid-404"}, + ) + + client = _make_client(handler, raise_on_error=False) + resp = client.batches.files.get("file-batch-typo") + assert resp.is_error is True + assert resp.status_code == 404 + assert resp.code == "File.NotFound" + assert resp.message == "file file-batch-typo does not exist" + assert resp.request_id == "rid-404" + assert resp.id is None + assert resp.headers["x-request-id"] == "rid-404" + client.close() + + +def test_business_error_layer_raise_and_report(): + body = { + "code": "InvalidParameter", + "message": "purpose unsupported", + "request_id": "rid-biz", + } + + def handler(request): + return httpx.Response(200, json=body) + + client = _make_client(handler) + with pytest.raises(BadRequestError) as ei: + client.batches.files.get("f1") + assert ei.value.status_code == 200 + client.close() + + client = _make_client(handler, raise_on_error=False) + resp = client.batches.files.get("f1") + assert resp.is_error is True + assert resp.code == "InvalidParameter" + assert resp.status_code == 200 + client.close() + + +def test_list_error_page_does_not_bind_pagination(): + def handler(request): + return httpx.Response( + 400, + json={"error": {"code": "InvalidParameter", "message": "bad"}}, + ) + + client = _make_client(handler, raise_on_error=False) + page = client.batches.files.list() + assert page.is_error is True + assert page.has_next_page() is False + assert page.next_page() is None + client.close() + + +# -------------------------------------------------------------------------- +# SDK identification header +# -------------------------------------------------------------------------- + + +def test_sdk_module_header(): + seen = {} + + def handler(request): + seen["client"] = request.headers.get("x-dashscope-sdk-client") + return httpx.Response(200, json=_FILE_BODY) + + client = _make_client(handler) + client.batches.files.get("f1") + assert seen["client"] == sdk_client_value("batches") + assert seen["client"].endswith("/batches2") + client.close() + + +# -------------------------------------------------------------------------- +# routing (compatible-mode path, protocol-independent) +# -------------------------------------------------------------------------- + + +@pytest.mark.parametrize("protocol", ["native", "openai", "anthropic"]) +def test_routing_default_gateway_ignores_chat_protocol(clean_env, protocol): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_FILE_BODY) + + http_client = httpx.Client( + transport=httpx.MockTransport(handler), + base_url=_WS_HOST + "/api/v1", + ) + client = Client( + api_key="sk-test", + workspace="ws-123", + protocol=protocol, + http_client=http_client, + ) + client.batches.files.get("f1") + assert urls == [_WS_HOST + _COMPAT_FILES + "/f1"], protocol + client.close() + + +@pytest.mark.parametrize("region", ["cn-beijing", "ap-southeast-1"]) +def test_routing_documented_region_gateways(clean_env, region): + urls = [] + ws_host = f"https://ws-123.{region}.maas.aliyuncs.com" + + def handler(request): + urls.append(str(request.url)) + return httpx.Response( + 200, + json={"object": "list", "data": [], "has_more": False}, + ) + + http_client = httpx.Client( + transport=httpx.MockTransport(handler), + base_url=ws_host + "/api/v1", + ) + client = Client( + api_key="sk-test", + workspace="ws-123", + region=region, + http_client=http_client, + ) + client.batches.files.list(purpose="batch") + assert urls[0].startswith(ws_host + _COMPAT_FILES) + client.close() + + +def test_routing_explicit_base_url(): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_FILE_BODY) + + client = _make_client(handler) + client.batches.files.get("f1") + assert urls == [BASE_URL + "/files/f1"] + client.close() + + +# -------------------------------------------------------------------------- +# async symmetry +# -------------------------------------------------------------------------- + + +async def test_async_upload_and_get(tmp_path): + captured = {} + + def handler(request): + captured["path"] = request.url.path + captured["body"] = request.content.decode("utf-8", "replace") + return httpx.Response(200, json=_FILE_BODY) + + client = _make_async_client(handler) + resp = await client.batches.files.upload(file_path=_jsonl_file(tmp_path)) + assert captured["path"] == "/api/v1/files" + assert 'name="file"' in captured["body"] + assert resp.file_id == "file-batch-abc123" + got = await client.batches.files.get("file-batch-abc123") + assert got.id == "file-batch-abc123" + await client.aclose() + + +async def test_async_content_download(tmp_path): + def handler(request): + return httpx.Response( + 200, + content=_JSONL, + headers={"x-request-id": "rid-dl"}, + ) + + client = _make_async_client(handler) + content = await client.batches.files.content("file-batch-out") + assert bytes(content) == _JSONL + assert content.text == _JSONL.decode("utf-8") + assert content.request_id == "rid-dl" + dest = content.write_to_file(tmp_path / "out.jsonl") + assert dest.read_bytes() == _JSONL + await client.aclose() + + +async def test_async_list_cursor_pagination(): + seen = [] + + def handler(request): + after = request.url.params.get("after") + seen.append(after) + if after is None: + return httpx.Response( + 200, + json={ + "object": "list", + "data": [{"id": "f1"}], + "has_more": True, + }, + ) + return httpx.Response( + 200, + json={ + "object": "list", + "data": [{"id": "f2"}], + "has_more": False, + }, + ) + + client = _make_async_client(handler) + page = await client.batches.files.list(purpose="batch") + pages = [p async for p in page.iter_pages_async()] + assert [[f.id for f in p] for p in pages] == [["f1"], ["f2"]] + assert seen == [None, "f1"] + # __aiter__ walks the current page's items. + assert [f.id async for f in page] == ["f1"] + await client.aclose() + + +async def test_async_delete_and_error_envelope(): + def handler(request): + if request.method == "DELETE": + return httpx.Response( + 200, + json={"id": "f1", "object": "file", "deleted": True}, + ) + return httpx.Response( + 404, + json={"error": {"code": "File.NotFound", "message": "gone"}}, + headers={"x-request-id": "rid-404"}, + ) + + client = _make_async_client(handler) + deleted = await client.batches.files.delete("f1") + assert deleted.deleted is True + await client.aclose() + + client = _make_async_client(handler, raise_on_error=False) + resp = await client.batches.files.get("missing") + assert resp.is_error is True + assert resp.status_code == 404 + assert resp.code == "File.NotFound" + assert resp.request_id == "rid-404" + await client.aclose() + + +async def test_async_routing_default_gateway(clean_env): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_FILE_BODY) + + http_client = httpx.AsyncClient( + transport=httpx.MockTransport(handler), + base_url=_WS_HOST + "/api/v1", + ) + client = AsyncClient( + api_key="sk-test", + workspace="ws-123", + http_client=http_client, + ) + await client.batches.files.get("f1") + assert urls == [_WS_HOST + _COMPAT_FILES + "/f1"] + await client.aclose() + + +async def test_async_empty_file_id_rejected_locally(): + client = _make_async_client(lambda r: httpx.Response(200, json=_FILE_BODY)) + with pytest.raises(ValueError, match="file_id"): + await client.batches.files.get("") + await client.aclose() + + +def test_raw_returns_apiresponse_before_error_check(): + def handler(request): + return httpx.Response( + 400, + json={"error": {"message": "bad"}}, + ) + + client = _make_client(handler) + raw = client.batches.files.get("f1", raw=True) + # raw=True bypasses the error check: no raise, status readable. + assert raw.status_code == 400 + assert raw.json()["error"]["message"] == "bad" + client.close() + + +def test_upload_wire_body_is_jsonl_lines(tmp_path): + captured = {} + + def handler(request): + captured["body"] = request.content + return httpx.Response(200, json=_FILE_BODY) + + path = tmp_path / "rows.jsonl" + rows = [{"custom_id": str(i), "method": "POST"} for i in range(3)] + path.write_text( + "".join(json.dumps(r) + "\n" for r in rows), + encoding="utf-8", + ) + client = _make_client(handler) + client.batches.files.upload(file_path=str(path)) + for row in rows: + assert json.dumps(row).encode() in captured["body"] + client.close() diff --git a/tests/test_batch_results.py b/tests/test_batch_results.py new file mode 100644 index 00000000..42fc5d34 --- /dev/null +++ b/tests/test_batch_results.py @@ -0,0 +1,414 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Tests for client.batches result download + input reuse (B3). + +B3 layers ``download_output`` / ``download_error`` on the B2 job plane: +resolve a batch's ``output_file_id`` / ``error_file_id`` (fetching the batch +first when given an id) and download the results JSONL through B1's +``files.content`` (``GET /files/{id}/content``). Returns ``None`` when the +file id is absent. Also covers input-file reuse (the same uploaded id drives +many creates; ``files.list(purpose="batch")`` discovers existing ids). + +Same compatible-mode wire and mock conventions as test_batches.py / +test_batch_files.py: with an explicit ``base_url`` the resource appends its +path to that root, so paths read ``/api/v1/batches/...`` and +``/api/v1/files/.../content``. +""" + +# Mock handlers intentionally ignore the request argument; pytest fixture +# injection looks like unused/redefined names to pylint. +# pylint: disable=unused-argument,redefined-outer-name + +from __future__ import annotations + +import json + +import httpx +import pytest + +from dashscope import AsyncClient, Client +from dashscope.errors import NotFoundError +from dashscope.resources.batches import Batch, BatchFileList, FileContent + +BASE_URL = "https://api.test.local/api/v1" +_ENDPOINT = "/v1/chat/ds-test" +_INPUT_FILE_ID = "file-batch-abc123" +_OUTPUT_FILE_ID = "file-batch-out" +_ERROR_FILE_ID = "file-batch-err" +_BATCH_ID = "batch_abc123" + +_OUTPUT_JSONL = ( + json.dumps( + { + "id": "r1", + "custom_id": "1", + "response": { + "status_code": 200, + "request_id": "r1", + "body": { + "model": "batch-test-model", + "choices": [ + {"message": {"content": "This is a test result."}}, + ], + }, + }, + "error": None, + }, + ) + + "\n" + + json.dumps( + { + "id": "r2", + "custom_id": "2", + "response": { + "status_code": 200, + "request_id": "r2", + "body": { + "model": "batch-test-model", + "choices": [ + {"message": {"content": "This is a test result."}}, + ], + }, + }, + "error": None, + }, + ) + + "\n" +).encode("utf-8") + +_ERROR_JSONL = ( + json.dumps( + { + "id": "r3", + "custom_id": "3", + "response": None, + "error": {"code": "InvalidParameter", "message": "bad row"}, + }, + ) + + "\n" +).encode("utf-8") + + +def _batch_body(**overrides): + body = { + "id": _BATCH_ID, + "object": "batch", + "endpoint": _ENDPOINT, + "input_file_id": _INPUT_FILE_ID, + "completion_window": "24h", + "status": "completed", + "created_at": 1730000000, + "request_counts": {"total": 2, "completed": 2, "failed": 0}, + "errors": None, + "output_file_id": _OUTPUT_FILE_ID, + "error_file_id": None, + } + body.update(overrides) + return body + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +def _content_handler(captured, *, content=_OUTPUT_JSONL, status=200): + def handler(request): + captured["method"] = request.method + captured["path"] = request.url.path + captured["sdk"] = request.headers.get("x-dashscope-sdk-client") + if status >= 400: + return httpx.Response( + status, + json={"error": {"message": "file does not exist"}}, + headers={"x-request-id": "rid-404"}, + ) + return httpx.Response( + status, + content=content, + headers={ + "content-type": "application/jsonl", + "x-request-id": "rid-dl", + }, + ) + + return handler + + +# -------------------------------------------------------------------------- +# download_output / download_error (sync) +# -------------------------------------------------------------------------- + + +def test_download_output_from_batch_object(tmp_path): + captured = {} + client = _make_client(_content_handler(captured)) + batch = Batch(**_batch_body()) + content = client.batches.download_output(batch) + # A Batch object is used as-is: no GET /batches round-trip. + assert captured["method"] == "GET" + assert captured["path"] == f"/api/v1/files/{_OUTPUT_FILE_ID}/content" + assert captured["sdk"].endswith("/batches2") + assert isinstance(content, FileContent) + assert bytes(content) == _OUTPUT_JSONL + assert "This is a test result." in content.text + assert content.request_id == "rid-dl" + assert content.status_code == 200 + assert content.is_error is False + dest = content.write_to_file(tmp_path / "nested" / "result.jsonl") + assert dest.read_bytes() == _OUTPUT_JSONL + rows = [json.loads(line) for line in content.text.splitlines()] + assert [r["custom_id"] for r in rows] == ["1", "2"] + client.close() + + +def test_download_output_from_batch_id_fetches_first(): + calls = [] + + def handler(request): + calls.append((request.method, request.url.path)) + if request.url.path == f"/api/v1/batches/{_BATCH_ID}": + return httpx.Response(200, json=_batch_body()) + if request.url.path == f"/api/v1/files/{_OUTPUT_FILE_ID}/content": + return httpx.Response(200, content=_OUTPUT_JSONL) + raise AssertionError(f"unexpected path {request.url.path}") + + client = _make_client(handler) + content = client.batches.download_output(_BATCH_ID) + assert calls == [ + ("GET", f"/api/v1/batches/{_BATCH_ID}"), + ("GET", f"/api/v1/files/{_OUTPUT_FILE_ID}/content"), + ] + assert bytes(content) == _OUTPUT_JSONL + client.close() + + +def test_download_output_none_when_no_output_file(): + def handler(request): + raise AssertionError("no network call expected when file id absent") + + client = _make_client(handler) + batch = Batch(**_batch_body(status="in_progress", output_file_id=None)) + assert client.batches.download_output(batch) is None + client.close() + + +def test_download_output_none_when_blank_output_file(): + def handler(request): + raise AssertionError("no network call expected for blank file id") + + client = _make_client(handler) + batch = Batch(**_batch_body(output_file_id=" ")) + assert client.batches.download_output(batch) is None + client.close() + + +def test_download_error_from_batch_object(): + captured = {} + client = _make_client( + _content_handler(captured, content=_ERROR_JSONL), + ) + batch = Batch(**_batch_body(error_file_id=_ERROR_FILE_ID)) + content = client.batches.download_error(batch) + assert captured["path"] == f"/api/v1/files/{_ERROR_FILE_ID}/content" + assert bytes(content) == _ERROR_JSONL + assert "bad row" in content.text + client.close() + + +def test_download_error_none_when_no_errors(): + def handler(request): + raise AssertionError("no network call expected when no error file") + + client = _make_client(handler) + batch = Batch(**_batch_body(error_file_id=None)) + assert client.batches.download_error(batch) is None + client.close() + + +def test_download_output_content_error_raises(): + captured = {} + client = _make_client(_content_handler(captured, status=404)) + batch = Batch(**_batch_body()) + with pytest.raises(NotFoundError) as ei: + client.batches.download_output(batch) + assert ei.value.status_code == 404 + assert ei.value.request_id == "rid-404" + client.close() + + +def test_download_output_content_error_no_raise_reports_status(): + captured = {} + client = _make_client( + _content_handler(captured, status=404), + raise_on_error=False, + ) + batch = Batch(**_batch_body()) + content = client.batches.download_output(batch) + assert content.is_error is True + assert content.status_code == 404 + assert b"file does not exist" in bytes(content) + client.close() + + +def test_download_output_from_id_get_error_raises(): + def handler(request): + return httpx.Response( + 404, + json={"error": {"message": "batch does not exist"}}, + headers={"x-request-id": "rid-b404"}, + ) + + client = _make_client(handler) + with pytest.raises(NotFoundError) as ei: + client.batches.download_output("missing-batch") + assert ei.value.status_code == 404 + client.close() + + +def test_download_output_from_id_get_error_no_raise_returns_none(): + def handler(request): + return httpx.Response( + 404, + json={"error": {"message": "batch does not exist"}}, + headers={"x-request-id": "rid-b404"}, + ) + + client = _make_client(handler, raise_on_error=False) + # The error envelope carries no output_file_id -> None (caller inspects + # the failure via batches.get under raise_on_error=False). + assert client.batches.download_output("missing-batch") is None + client.close() + + +# -------------------------------------------------------------------------- +# input file reuse +# -------------------------------------------------------------------------- + + +def test_input_file_id_reused_across_creates(): + bodies = [] + + def handler(request): + assert request.method == "POST" + assert request.url.path == "/api/v1/batches" + bodies.append(json.loads(request.content)) + return httpx.Response(200, json=_batch_body(status="validating")) + + client = _make_client(handler) + first = client.batches.create( + input_file_id=_INPUT_FILE_ID, + endpoint=_ENDPOINT, + ) + second = client.batches.create( + input_file_id=_INPUT_FILE_ID, + endpoint=_ENDPOINT, + ) + # Same uploaded id drives both creates -- no re-upload between them. + assert bodies[0]["input_file_id"] == _INPUT_FILE_ID + assert bodies[1]["input_file_id"] == _INPUT_FILE_ID + assert first.input_file_id == second.input_file_id == _INPUT_FILE_ID + client.close() + + +def test_input_reuse_discover_via_files_list(): + captured = {} + + def handler(request): + captured["path"] = request.url.path + captured["purpose"] = request.url.params.get("purpose") + return httpx.Response( + 200, + json={ + "object": "list", + "data": [ + { + "id": _INPUT_FILE_ID, + "object": "file", + "bytes": 120, + "created_at": 1730000000, + "filename": "input.jsonl", + "purpose": "batch", + }, + ], + "has_more": False, + }, + ) + + client = _make_client(handler) + page = client.batches.files.list(purpose="batch") + assert captured["path"] == "/api/v1/files" + assert captured["purpose"] == "batch" + assert isinstance(page, BatchFileList) + assert [f.id for f in page.items] == [_INPUT_FILE_ID] + client.close() + + +# -------------------------------------------------------------------------- +# async twins +# -------------------------------------------------------------------------- + + +@pytest.mark.asyncio +async def test_async_download_output_from_batch_object(): + captured = {} + client = _make_async_client(_content_handler(captured)) + batch = Batch(**_batch_body()) + content = await client.batches.download_output(batch) + assert captured["path"] == f"/api/v1/files/{_OUTPUT_FILE_ID}/content" + assert captured["sdk"].endswith("/batches2") + assert bytes(content) == _OUTPUT_JSONL + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_download_output_from_batch_id_fetches_first(): + calls = [] + + def handler(request): + calls.append((request.method, request.url.path)) + if request.url.path == f"/api/v1/batches/{_BATCH_ID}": + return httpx.Response(200, json=_batch_body()) + if request.url.path == f"/api/v1/files/{_OUTPUT_FILE_ID}/content": + return httpx.Response(200, content=_OUTPUT_JSONL) + raise AssertionError(f"unexpected path {request.url.path}") + + client = _make_async_client(handler) + content = await client.batches.download_output(_BATCH_ID) + assert calls == [ + ("GET", f"/api/v1/batches/{_BATCH_ID}"), + ("GET", f"/api/v1/files/{_OUTPUT_FILE_ID}/content"), + ] + assert bytes(content) == _OUTPUT_JSONL + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_download_error_none_when_no_errors(): + def handler(request): + raise AssertionError("no network call expected when no error file") + + client = _make_async_client(handler) + batch = Batch(**_batch_body(error_file_id=None)) + assert await client.batches.download_error(batch) is None + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_download_output_content_error_raises(): + captured = {} + client = _make_async_client(_content_handler(captured, status=404)) + batch = Batch(**_batch_body()) + with pytest.raises(NotFoundError) as ei: + await client.batches.download_output(batch) + assert ei.value.status_code == 404 + await client.aclose() diff --git a/tests/test_batches.py b/tests/test_batches.py new file mode 100644 index 00000000..1b13a814 --- /dev/null +++ b/tests/test_batches.py @@ -0,0 +1,1038 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Tests for client.batches job plane (B2: create/get/list/cancel/wait). + +Same compatible-mode wire as B1's File plane (/compatible-mode/v1/batches, +protocol-independent, flat OpenAI Batch object, after/has_more cursor), so +these mirror test_batch_files.py conventions. B2-specific coverage: create +defaults to max_retries=0 (no server idempotency key), completion_window +validation, the Batch-list cursor (limit [1,100], first_id/last_id), the +polling waiter (terminal completed/failed/expired/cancelled) and the +pre-upload validate_input row-level JSONL check. +""" + +# Mock handlers intentionally ignore the request argument; pytest fixture +# injection looks like unused/redefined names to pylint. +# pylint: disable=unused-argument,redefined-outer-name + +from __future__ import annotations + +import json + +import httpx +import pytest + +from dashscope import AsyncClient, Client +from dashscope.errors import ( + BadRequestError, + DashScopeError, + RateLimitError, + SdkError, +) +from dashscope.resources.batches import Batch, BatchList +from dashscope.transport._ident import sdk_client_value + +BASE_URL = "https://api.test.local/api/v1" +_WS_HOST = "https://ws-123.cn-beijing.maas.aliyuncs.com" +_COMPAT_BATCHES = "/compatible-mode/v1/batches" +_ENDPOINT = "/v1/chat/completions" + +# A flat OpenAI-compatible Batch object (create / get / cancel response). +_BATCH_BODY = { + "id": "batch_abc123", + "object": "batch", + "endpoint": _ENDPOINT, + "input_file_id": "file-batch-abc123", + "completion_window": "24h", + "status": "validating", + "created_at": 1730000000, + "request_counts": {"total": 0, "completed": 0, "failed": 0}, + "metadata": {"ds_name": "my-batch"}, + "errors": None, + "output_file_id": None, + "error_file_id": None, +} + +_GOOD_ROWS = [ + { + "custom_id": "1", + "method": "POST", + "url": _ENDPOINT, + "body": {"model": "qwen-plus", "messages": []}, + }, + { + "custom_id": "2", + "method": "POST", + "url": _ENDPOINT, + "body": {"model": "qwen-plus", "messages": []}, + }, +] + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +@pytest.fixture +def clean_env(monkeypatch): + from dashscope._config import settings + + for name in ( + "DASHSCOPE_API_KEY", + "DASHSCOPE_BASE_URL", + "DASHSCOPE_HTTP_BASE_URL", + "DASHSCOPE_WORKSPACE", + "DASHSCOPE_REGION", + "DASHSCOPE_PROTOCOL", + "DASHSCOPE_CONFIG", + ): + monkeypatch.delenv(name, raising=False) + settings.clear() + yield monkeypatch + settings.clear() + + +def _rows_file(tmp_path, rows, name="input.jsonl"): + path = tmp_path / name + path.write_text( + "".join(json.dumps(r) + "\n" for r in rows), + encoding="utf-8", + ) + return str(path) + + +# -------------------------------------------------------------------------- +# create +# -------------------------------------------------------------------------- + + +def test_create_wire_body_and_parse(): + captured = {} + + def handler(request): + captured["method"] = request.method + captured["path"] = request.url.path + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_BATCH_BODY) + + client = _make_client(handler) + resp = client.batches.create( + input_file_id="file-batch-abc123", + endpoint=_ENDPOINT, + completion_window="48h", + metadata={"ds_name": "n", "ds_description": "d"}, + ) + assert captured["method"] == "POST" + assert captured["path"] == "/api/v1/batches" + assert captured["body"] == { + "input_file_id": "file-batch-abc123", + "endpoint": _ENDPOINT, + "completion_window": "48h", + "metadata": {"ds_name": "n", "ds_description": "d"}, + } + assert resp.id == "batch_abc123" + assert resp.batch_id == "batch_abc123" + assert resp.object == "batch" + assert resp.status == "validating" + assert resp.finished is False + assert resp.succeeded is False + assert resp.request_counts.total == 0 + assert resp.metadata == {"ds_name": "my-batch"} + assert resp.errors is None + assert resp.is_error is False + client.close() + + +def test_create_omits_metadata_when_unset(): + captured = {} + + def handler(request): + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_BATCH_BODY) + + client = _make_client(handler) + client.batches.create(input_file_id="f", endpoint=_ENDPOINT) + assert "metadata" not in captured["body"] + assert captured["body"]["completion_window"] == "24h" + client.close() + + +def test_create_defaults_to_no_retry(): + attempts = [] + + def handler(request): + attempts.append(request.url.path) + return httpx.Response(503, json={"message": "busy"}) + + client = _make_client(handler) + with pytest.raises(DashScopeError): + client.batches.create(input_file_id="f", endpoint=_ENDPOINT) + # No idempotency key on the wire -> create must not auto-retry. + assert len(attempts) == 1 + client.close() + + +def test_create_explicit_max_retries_retries(monkeypatch): + attempts = [] + + def handler(request): + attempts.append(1) + if len(attempts) < 3: + return httpx.Response(503, json={"message": "busy"}) + return httpx.Response(200, json=_BATCH_BODY) + + from dashscope.transport import http as transport_http + + monkeypatch.setattr(transport_http, "_sleep", lambda seconds: None) + client = _make_client(handler) + resp = client.batches.create( + input_file_id="f", + endpoint=_ENDPOINT, + max_retries=2, + ) + assert resp.id == "batch_abc123" + assert len(attempts) == 3 + client.close() + + +@pytest.mark.parametrize( + "window", + ["", "24", "h", "12h", "337h", "0d", "15d", "abc", "24x"], +) +def test_create_rejects_bad_completion_window(window): + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + with pytest.raises(ValueError, match="completion_window"): + client.batches.create( + input_file_id="f", + endpoint=_ENDPOINT, + completion_window=window, + ) + client.close() + + +@pytest.mark.parametrize("window", ["24h", "336h", "1d", "14d", "7d"]) +def test_create_accepts_valid_windows(window): + captured = {} + + def handler(request): + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_BATCH_BODY) + + client = _make_client(handler) + client.batches.create( + input_file_id="f", + endpoint=_ENDPOINT, + completion_window=window, + ) + assert captured["body"]["completion_window"] == window + client.close() + + +def test_create_requires_input_file_id_and_endpoint(): + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + with pytest.raises(ValueError, match="input_file_id"): + client.batches.create(input_file_id="", endpoint=_ENDPOINT) + with pytest.raises(ValueError, match="endpoint"): + client.batches.create(input_file_id="f", endpoint=" ") + client.close() + + +# -------------------------------------------------------------------------- +# get / cancel +# -------------------------------------------------------------------------- + + +def test_get_wire_and_parse(): + captured = {} + + def handler(request): + captured["method"] = request.method + captured["path"] = request.url.path + return httpx.Response( + 200, + json={ + **_BATCH_BODY, + "status": "completed", + "output_file_id": "file-out", + "request_counts": {"total": 10, "completed": 10, "failed": 0}, + }, + ) + + client = _make_client(handler) + resp = client.batches.get("batch_abc123") + assert captured == { + "method": "GET", + "path": "/api/v1/batches/batch_abc123", + } + assert resp.status == "completed" + assert resp.finished is True + assert resp.succeeded is True + assert resp.output_file_id == "file-out" + assert resp.request_counts.completed == 10 + client.close() + + +def test_get_parses_errors_and_counts(): + body = { + **_BATCH_BODY, + "status": "failed", + "errors": { + "object": "list", + "data": [ + {"code": "c", "message": "m", "param": "p", "line": 5}, + ], + }, + "request_counts": {"total": 5, "completed": 3, "failed": 2}, + } + + client = _make_client(lambda r: httpx.Response(200, json=body)) + resp = client.batches.get("b1") + assert resp.errors.data[0].line == 5 + assert resp.errors.data[0].code == "c" + assert resp.request_counts.failed == 2 + assert resp.finished is True + assert resp.succeeded is False + client.close() + + +def test_cancel_wire_and_parse(): + captured = {} + + def handler(request): + captured["method"] = request.method + captured["path"] = request.url.path + return httpx.Response( + 200, + json={**_BATCH_BODY, "status": "cancelling"}, + ) + + client = _make_client(handler) + resp = client.batches.cancel("batch_abc123") + assert captured == { + "method": "POST", + "path": "/api/v1/batches/batch_abc123/cancel", + } + assert resp.status == "cancelling" + assert resp.finished is False + client.close() + + +@pytest.mark.parametrize("batch_id", ["", " "]) +def test_empty_batch_id_rejected_locally(batch_id): + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + for call in (client.batches.get, client.batches.cancel): + with pytest.raises(ValueError, match="batch_id"): + call(batch_id) + client.close() + + +def test_batch_id_percent_encoded_in_path(): + seen = [] + + def handler(request): + seen.append(request.url.raw_path) + return httpx.Response(200, json=_BATCH_BODY) + + client = _make_client(handler) + tricky = "batch/a?b#c" + client.batches.get(tricky) + client.batches.cancel(tricky) + # '/', '?' and '#' stay inside one path segment instead of retargeting + # the request to another path or query. + encoded = b"/api/v1/batches/batch%2Fa%3Fb%23c" + assert seen == [encoded, encoded + b"/cancel"] + client.close() + + +async def test_async_batch_id_percent_encoded_in_path(): + seen = [] + + def handler(request): + seen.append(request.url.raw_path) + return httpx.Response(200, json=_BATCH_BODY) + + client = _make_async_client(handler) + await client.batches.get("batch/a?b#c") + assert seen == [b"/api/v1/batches/batch%2Fa%3Fb%23c"] + await client.aclose() + + +# -------------------------------------------------------------------------- +# list (cursor pagination) +# -------------------------------------------------------------------------- + + +def test_list_cursor_pagination_uses_last_id(): + seen = [] + + def handler(request): + after = request.url.params.get("after") + seen.append(after) + if after is None: + return httpx.Response( + 200, + json={ + "object": "list", + "data": [{"id": "b1"}, {"id": "b2"}], + "first_id": "b1", + "last_id": "b2", + "has_more": True, + }, + ) + return httpx.Response( + 200, + json={ + "object": "list", + "data": [{"id": "b3"}], + "first_id": "b3", + "last_id": "b3", + "has_more": False, + }, + ) + + client = _make_client(handler) + page = client.batches.list(limit=2, status="completed") + assert page.object == "list" + assert page.first_id == "b1" + assert page.last_id == "b2" + assert [b.id for b in page.items] == ["b1", "b2"] + assert page.has_next_page() is True + pages = list(page.iter_pages()) + assert [[b.id for b in p] for p in pages] == [["b1", "b2"], ["b3"]] + assert pages[-1].has_next_page() is False + assert pages[-1].next_page() is None + # The cursor advances by last_id and re-sends the status filter. + assert seen == [None, "b2"] + client.close() + + +def test_list_empty_page_has_no_next(): + def handler(request): + return httpx.Response( + 200, + json={"object": "list", "data": [], "has_more": False}, + ) + + client = _make_client(handler) + page = client.batches.list() + assert page.items == [] + assert page.has_next_page() is False + assert list(page.iter_pages()) == [page] + client.close() + + +def test_list_params_validation_and_csv(): + captured = {} + + def handler(request): + captured["params"] = dict(request.url.params) + return httpx.Response( + 200, + json={"object": "list", "data": [], "has_more": False}, + ) + + client = _make_client(handler) + for bad_limit in (0, 101): + with pytest.raises(ValueError, match="limit"): + client.batches.list(limit=bad_limit) + with pytest.raises(ValueError, match="input_file_ids"): + client.batches.list(input_file_ids=[f"f{i}" for i in range(21)]) + # Unset optionals stay off the wire. + client.batches.list() + assert captured["params"] == {} + client.batches.list( + after="b9", + limit=100, + ds_name="foo", + input_file_ids=["f1", "f2"], + status=["completed", "failed"], + create_after="20260101000000", + create_before="20260201000000", + ) + assert captured["params"] == { + "after": "b9", + "limit": "100", + "ds_name": "foo", + "input_file_ids": "f1,f2", + "status": "completed,failed", + "create_after": "20260101000000", + "create_before": "20260201000000", + } + # Comma-separated string forms pass through unchanged. + client.batches.list(input_file_ids="f1,f2", status="completed") + assert captured["params"]["input_file_ids"] == "f1,f2" + assert captured["params"]["status"] == "completed" + client.close() + + +def test_list_error_page_does_not_bind_pagination(): + def handler(request): + return httpx.Response( + 400, + json={"error": {"code": "InvalidParameter", "message": "bad"}}, + ) + + client = _make_client(handler, raise_on_error=False) + page = client.batches.list() + assert page.is_error is True + assert page.has_next_page() is False + assert page.next_page() is None + client.close() + + +def test_sync_next_page_rejects_async_callback(): + page = BatchList(data=[Batch(id="b1")], has_more=True, last_id="b1") + + async def fetch(cursor): + return BatchList(data=[Batch(id="b2")], has_more=False) + + page.bind_pagination(fetch) + with pytest.raises(TypeError, match="next_page_async"): + page.next_page() + + +# -------------------------------------------------------------------------- +# error mapping +# -------------------------------------------------------------------------- + + +def test_http_error_maps_openai_nested_body(): + def handler(request): + return httpx.Response( + 400, + json={ + "error": { + "code": "InvalidParameter", + "message": "endpoint is invalid", + }, + }, + headers={"x-request-id": "rid-err"}, + ) + + client = _make_client(handler) + with pytest.raises(BadRequestError) as ei: + client.batches.get("batch_x") + assert ei.value.code == "InvalidParameter" + assert ei.value.status_code == 400 + assert ei.value.request_id == "rid-err" + client.close() + + +def test_http_429_maps_rate_limit(): + def handler(request): + return httpx.Response(429, json={"error": {"message": "slow down"}}) + + client = _make_client(handler) + with pytest.raises(RateLimitError): + client.batches.list() + client.close() + + +def test_error_envelope_when_not_raising(): + def handler(request): + return httpx.Response( + 404, + json={ + "error": { + "code": "Batch.NotFound", + "message": "batch batch_typo does not exist", + }, + }, + headers={"x-request-id": "rid-404"}, + ) + + client = _make_client(handler, raise_on_error=False) + resp = client.batches.get("batch_typo") + assert resp.is_error is True + assert resp.status_code == 404 + assert resp.code == "Batch.NotFound" + assert resp.message == "batch batch_typo does not exist" + assert resp.request_id == "rid-404" + assert resp.id is None + assert resp.headers["x-request-id"] == "rid-404" + client.close() + + +def test_business_error_layer_raise_and_report(): + body = { + "code": "InvalidParameter", + "message": "endpoint unsupported", + "request_id": "rid-biz", + } + + def handler(request): + return httpx.Response(200, json=body) + + client = _make_client(handler) + with pytest.raises(BadRequestError) as ei: + client.batches.get("b1") + assert ei.value.status_code == 200 + client.close() + + client = _make_client(handler, raise_on_error=False) + resp = client.batches.get("b1") + assert resp.is_error is True + assert resp.code == "InvalidParameter" + assert resp.status_code == 200 + client.close() + + +# -------------------------------------------------------------------------- +# waiter +# -------------------------------------------------------------------------- + + +def test_wait_polls_until_completed(): + statuses = iter(["validating", "in_progress", "completed"]) + calls = [] + + def handler(request): + calls.append(request.url.path) + return httpx.Response( + 200, + json={**_BATCH_BODY, "status": next(statuses)}, + ) + + client = _make_client(handler) + sleeps = [] + result = client.batches.wait( + "batch_abc123", + _sleep=lambda s: sleeps.append(s), + ) + assert result.status == "completed" + assert result.succeeded is True + assert len(calls) == 3 + # Slept between polls, never after the terminal status. + assert len(sleeps) == 2 + client.close() + + +def test_wait_accepts_batch_object_skipping_initial_get(): + calls = [] + + def handler(request): + calls.append(1) + return httpx.Response( + 200, + json={**_BATCH_BODY, "status": "completed"}, + ) + + client = _make_client(handler) + seed = Batch(id="batch_abc123", status="in_progress") + result = client.batches.wait(seed, _sleep=lambda s: None) + assert result.status == "completed" + assert len(calls) == 1 + client.close() + + +def test_wait_failed_raises_with_errors_detail(): + def handler(request): + return httpx.Response( + 200, + json={ + **_BATCH_BODY, + "status": "failed", + "errors": { + "object": "list", + "data": [ + { + "code": "invalid_row", + "message": "row 3 bad", + "line": 3, + }, + ], + }, + }, + ) + + client = _make_client(handler) + with pytest.raises(DashScopeError) as ei: + client.batches.wait("batch_abc123", _sleep=lambda s: None) + assert "row 3 bad" in ei.value.message + client.close() + + +def test_wait_failed_no_raise_returns_batch(): + def handler(request): + return httpx.Response(200, json={**_BATCH_BODY, "status": "failed"}) + + client = _make_client(handler, raise_on_error=False) + result = client.batches.wait("batch_abc123", _sleep=lambda s: None) + assert result.status == "failed" + assert result.finished is True + assert result.succeeded is False + # HTTP 200 with no business code: the call succeeded, the job failed. + assert result.is_error is False + client.close() + + +@pytest.mark.parametrize("status", ["cancelled", "expired"]) +def test_wait_cancelled_expired_raise(status): + def handler(request): + return httpx.Response(200, json={**_BATCH_BODY, "status": status}) + + client = _make_client(handler) + with pytest.raises(DashScopeError, match=status): + client.batches.wait("batch_abc123", _sleep=lambda s: None) + client.close() + + +def test_wait_timeout(): + def handler(request): + return httpx.Response( + 200, + json={**_BATCH_BODY, "status": "in_progress"}, + ) + + client = _make_client(handler) + with pytest.raises(DashScopeError, match="timed out"): + client.batches.wait( + "batch_abc123", + timeout=0, + _sleep=lambda s: None, + ) + client.close() + + +def test_wait_transport_error_no_raise_returns_envelope(): + def handler(request): + return httpx.Response(503, json={"message": "busy"}) + + client = _make_client(handler, raise_on_error=False, max_retries=0) + result = client.batches.wait("batch_abc123", _sleep=lambda s: None) + assert result.is_error is True + assert result.status is None + client.close() + + +# -------------------------------------------------------------------------- +# validate_input (pre-upload row-level JSONL check) +# -------------------------------------------------------------------------- + + +def test_validate_input_accepts_good_rows(tmp_path): + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + n = client.batches.validate_input( + _rows_file(tmp_path, _GOOD_ROWS), + endpoint=_ENDPOINT, + ) + assert n == 2 + client.close() + + +def test_validate_input_duplicate_custom_id(tmp_path): + rows = [dict(_GOOD_ROWS[0]), dict(_GOOD_ROWS[0])] + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + with pytest.raises(ValueError, match="duplicate custom_id"): + client.batches.validate_input(_rows_file(tmp_path, rows)) + client.close() + + +def test_validate_input_model_mismatch(tmp_path): + rows = [ + dict(_GOOD_ROWS[0]), + {**_GOOD_ROWS[1], "body": {"model": "qwen-max"}}, + ] + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + with pytest.raises(ValueError, match="same model"): + client.batches.validate_input(_rows_file(tmp_path, rows)) + client.close() + + +def test_validate_input_endpoint_mismatch(tmp_path): + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + with pytest.raises(ValueError, match="does not match"): + client.batches.validate_input( + _rows_file(tmp_path, _GOOD_ROWS), + endpoint="/v1/embeddings", + ) + client.close() + + +def test_validate_input_bad_method(tmp_path): + rows = [{**_GOOD_ROWS[0], "method": "GET"}] + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + with pytest.raises(ValueError, match="method"): + client.batches.validate_input(_rows_file(tmp_path, rows)) + client.close() + + +def test_validate_input_missing_body_model(tmp_path): + rows = [ + {"custom_id": "1", "method": "POST", "url": _ENDPOINT, "body": {}}, + ] + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + with pytest.raises(ValueError, match="body.model"): + client.batches.validate_input(_rows_file(tmp_path, rows)) + client.close() + + +def test_validate_input_not_json(tmp_path): + path = tmp_path / "bad.jsonl" + path.write_text("{not json}\n", encoding="utf-8") + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + with pytest.raises(ValueError, match="not valid JSON"): + client.batches.validate_input(str(path)) + client.close() + + +def test_validate_input_missing_file_is_io_error(tmp_path): + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + with pytest.raises(SdkError) as ei: + client.batches.validate_input(str(tmp_path / "nope.jsonl")) + assert ei.value.code == "sdk.IoError" + client.close() + + +def test_validate_input_empty_file(tmp_path): + path = tmp_path / "empty.jsonl" + path.write_text("", encoding="utf-8") + client = _make_client(lambda r: httpx.Response(200, json=_BATCH_BODY)) + with pytest.raises(ValueError, match="no batch input rows"): + client.batches.validate_input(str(path)) + client.close() + + +# -------------------------------------------------------------------------- +# SDK identification header +# -------------------------------------------------------------------------- + + +def test_sdk_module_header(): + seen = {} + + def handler(request): + seen["client"] = request.headers.get("x-dashscope-sdk-client") + return httpx.Response(200, json=_BATCH_BODY) + + client = _make_client(handler) + client.batches.get("b1") + assert seen["client"] == sdk_client_value("batches") + assert seen["client"].endswith("/batches2") + client.close() + + +# -------------------------------------------------------------------------- +# routing (compatible-mode path, protocol-independent) +# -------------------------------------------------------------------------- + + +@pytest.mark.parametrize("protocol", ["native", "openai", "anthropic"]) +def test_routing_default_gateway_ignores_chat_protocol(clean_env, protocol): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_BATCH_BODY) + + http_client = httpx.Client( + transport=httpx.MockTransport(handler), + base_url=_WS_HOST + "/api/v1", + ) + client = Client( + api_key="sk-test", + workspace="ws-123", + protocol=protocol, + http_client=http_client, + ) + client.batches.get("b1") + assert urls == [_WS_HOST + _COMPAT_BATCHES + "/b1"], protocol + client.close() + + +def test_routing_explicit_base_url(): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_BATCH_BODY) + + client = _make_client(handler) + client.batches.create(input_file_id="f", endpoint=_ENDPOINT) + assert urls == [BASE_URL + "/batches"] + client.close() + + +def test_raw_returns_apiresponse_before_error_check(): + def handler(request): + return httpx.Response(400, json={"error": {"message": "bad"}}) + + client = _make_client(handler) + raw = client.batches.get("b1", raw=True) + assert raw.status_code == 400 + assert raw.json()["error"]["message"] == "bad" + client.close() + + +# -------------------------------------------------------------------------- +# async symmetry +# -------------------------------------------------------------------------- + + +async def test_async_create_get_cancel(): + captured = [] + + def handler(request): + captured.append((request.method, request.url.path)) + if request.url.path.endswith("/cancel"): + return httpx.Response( + 200, + json={**_BATCH_BODY, "status": "cancelling"}, + ) + return httpx.Response(200, json=_BATCH_BODY) + + client = _make_async_client(handler) + created = await client.batches.create( + input_file_id="f", + endpoint=_ENDPOINT, + ) + assert created.id == "batch_abc123" + got = await client.batches.get("batch_abc123") + assert got.status == "validating" + cancelled = await client.batches.cancel("batch_abc123") + assert cancelled.status == "cancelling" + assert captured == [ + ("POST", "/api/v1/batches"), + ("GET", "/api/v1/batches/batch_abc123"), + ("POST", "/api/v1/batches/batch_abc123/cancel"), + ] + await client.aclose() + + +async def test_async_create_defaults_to_no_retry(): + attempts = [] + + def handler(request): + attempts.append(1) + return httpx.Response(503, json={"message": "busy"}) + + client = _make_async_client(handler) + with pytest.raises(DashScopeError): + await client.batches.create(input_file_id="f", endpoint=_ENDPOINT) + assert len(attempts) == 1 + await client.aclose() + + +async def test_async_list_cursor_pagination(): + seen = [] + + def handler(request): + after = request.url.params.get("after") + seen.append(after) + if after is None: + return httpx.Response( + 200, + json={ + "object": "list", + "data": [{"id": "b1"}], + "first_id": "b1", + "last_id": "b1", + "has_more": True, + }, + ) + return httpx.Response( + 200, + json={ + "object": "list", + "data": [{"id": "b2"}], + "first_id": "b2", + "last_id": "b2", + "has_more": False, + }, + ) + + client = _make_async_client(handler) + page = await client.batches.list() + pages = [p async for p in page.iter_pages_async()] + assert [[b.id for b in p] for p in pages] == [["b1"], ["b2"]] + assert seen == [None, "b1"] + assert [b.id async for b in page] == ["b1"] + await client.aclose() + + +async def test_async_wait_until_completed(): + statuses = iter(["in_progress", "completed"]) + + def handler(request): + return httpx.Response( + 200, + json={**_BATCH_BODY, "status": next(statuses)}, + ) + + async def nosleep(seconds): + return None + + client = _make_async_client(handler) + result = await client.batches.wait("batch_abc123", _sleep=nosleep) + assert result.status == "completed" + await client.aclose() + + +async def test_async_wait_failed_raises(): + def handler(request): + return httpx.Response( + 200, + json={ + **_BATCH_BODY, + "status": "failed", + "errors": {"object": "list", "data": [{"message": "boom"}]}, + }, + ) + + async def nosleep(seconds): + return None + + client = _make_async_client(handler) + with pytest.raises(DashScopeError, match="boom"): + await client.batches.wait("batch_abc123", _sleep=nosleep) + await client.aclose() + + +async def test_async_routing_default_gateway(clean_env): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_BATCH_BODY) + + http_client = httpx.AsyncClient( + transport=httpx.MockTransport(handler), + base_url=_WS_HOST + "/api/v1", + ) + client = AsyncClient( + api_key="sk-test", + workspace="ws-123", + http_client=http_client, + ) + await client.batches.get("b1") + assert urls == [_WS_HOST + _COMPAT_BATCHES + "/b1"] + await client.aclose() + + +async def test_async_validate_input_is_local(tmp_path): + client = _make_async_client( + lambda r: httpx.Response(200, json=_BATCH_BODY), + ) + # Plain (non-async) method: local file I/O, no network. + n = client.batches.validate_input(_rows_file(tmp_path, _GOOD_ROWS)) + assert n == 2 + await client.aclose() + + +async def test_async_empty_batch_id_rejected_locally(): + client = _make_async_client( + lambda r: httpx.Response(200, json=_BATCH_BODY), + ) + with pytest.raises(ValueError, match="batch_id"): + await client.batches.get("") + await client.aclose() diff --git a/tests/test_config.py b/tests/test_config.py index ed408bca..0b935d55 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -338,6 +338,85 @@ def test_region_catalogs_stay_in_sync(): assert DEFAULT_REGION in VALID_REGIONS +def test_unsafe_region_labels_rejected(clean_env): + # A4: region is interpolated into the gateway host, so any label that + # could rewrite the host (dot/slash/uppercase/underscore/empty/ + # overlong/leading-trailing hyphen) is rejected even with a workspace. + for bad in ( + "cn-beijing.evil.com", + "a/b", + "CN-BEIJING", + "cn_beijing", + "", + "-cn-beijing", + "cn-beijing-", + "a" * 64, + "cn-beijing@x", + ): + with pytest.raises(ValueError, match="invalid region"): + resolve_config( + region=bad, + workspace="ws-123", + config_path="/nonexistent/config.toml", + ) + + +def test_unknown_region_with_workspace_passes_through(clean_env, tmp_path): + # A4: a safe but unknown region is allowed with a workspace, warning + # instead of rejecting, so a newly launched region works pre-upgrade. + with pytest.warns(UserWarning, match="not a known DashScope region"): + cfg = resolve_config( + region="mars-1", + workspace="ws-123", + config_path=tmp_path / "absent.toml", + ) + assert cfg.region == "mars-1" + assert cfg.base_url == "https://ws-123.mars-1.maas.aliyuncs.com/api/v1" + + +def test_unknown_region_without_workspace_rejected(clean_env): + # No workspace -> the legacy shared gateway needs a known mapping. + with pytest.raises(ValueError, match="invalid region"): + resolve_config( + region="mars-1", + config_path="/nonexistent/config.toml", + ) + + +def test_explicit_base_url_bypasses_region_whitelist(clean_env, tmp_path): + # Escape hatch: an unknown region is recorded but never gates the + # request, and no warning is emitted. + import warnings as _warnings + + with _warnings.catch_warnings(): + _warnings.simplefilter("error") + cfg = resolve_config( + region="mars-1", + base_url="https://explicit.example.com", + config_path=tmp_path / "absent.toml", + ) + assert cfg.region == "mars-1" + assert cfg.base_url == "https://explicit.example.com" + + +def test_unsafe_workspace_rejected(clean_env): + # The workspace is host-interpolated too; a dot could rewrite the host. + with pytest.raises(ValueError, match="invalid workspace"): + resolve_config( + region="cn-beijing", + workspace="ws.123", + config_path="/nonexistent/config.toml", + ) + + +def test_settings_region_setter_warns_on_unknown(clean_env): + from dashscope._config import settings + + with pytest.warns(UserWarning, match="not a known DashScope region"): + settings.region = "mars-1" + assert settings.region == "mars-1" + + def test_configured_base_url_beats_region(clean_env, tmp_path): # An explicit base_url stays the escape hatch: region is still # recorded but does not rewrite the configured URL. diff --git a/tests/test_conversations.py b/tests/test_conversations.py new file mode 100644 index 00000000..809990ed --- /dev/null +++ b/tests/test_conversations.py @@ -0,0 +1,850 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Tests for client.conversations (C2). + +The OpenAI-compatible Conversations API: conversation create/get/update/ +delete plus items.create/list/get/delete, on the same compatible-mode wire +as Responses (/compatible-mode/v1/conversations). Covers routing (chat +protocol cannot move it), the conversation/item wire shapes, cursor +pagination, metadata/items/limit pre-validation, error envelopes, the +conversations2 SDK header, Responses linkage and async symmetry. + +Mock conventions match test_responses.py / test_batches.py. +""" + +# Mock handlers intentionally ignore the request argument; pytest fixture +# injection looks like unused/redefined names to pylint. +# pylint: disable=unused-argument,redefined-outer-name + +from __future__ import annotations + +import json + +import httpx +import pytest + +from dashscope import AsyncClient, Client +from dashscope.errors import BadRequestError +from dashscope.resources.conversations import ConversationItemList +from dashscope.transport._ident import sdk_client_value +from dashscope.transport._response import APIResponse +from dashscope.types import ( + Conversation, + ConversationDeleted, + ConversationItem, + ConversationItemDeleted, +) + +BASE_URL = "https://api.test.local/api/v1" +_WS_HOST = "https://ws-123.cn-beijing.maas.aliyuncs.com" +_COMPAT_CONVERSATIONS = "/compatible-mode/v1/conversations" +_CONV_ID = "conv_abc123" +_ITEM_ID = "msg_abc123" + +_CONVERSATION_BODY = { + "id": _CONV_ID, + "object": "conversation", + "created_at": 1771316949128, + "metadata": {"topic": "demo"}, +} +_CONV_DELETED_BODY = { + "id": _CONV_ID, + "deleted": True, + "object": "conversation.deleted", +} +_ITEM_BODY = { + "id": _ITEM_ID, + "type": "message", + "role": "user", + "status": "completed", + "content": [{"type": "input_text", "text": "hi"}], +} +_ITEM_DELETED_BODY = { + "id": _ITEM_ID, + "deleted": True, + "object": "conversation.item.deleted", +} +_ITEMS_LIST_BODY = { + "data": [_ITEM_BODY], + "first_id": _ITEM_ID, + "last_id": _ITEM_ID, + "has_more": False, + "object": "list", +} +# items.create answers with the same list shape but no ``object`` field. +_ITEMS_CREATE_BODY = { + "data": [_ITEM_BODY], + "first_id": _ITEM_ID, + "last_id": _ITEM_ID, + "has_more": False, +} + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +@pytest.fixture +def clean_env(monkeypatch): + from dashscope._config import settings + + for name in ( + "DASHSCOPE_API_KEY", + "DASHSCOPE_BASE_URL", + "DASHSCOPE_HTTP_BASE_URL", + "DASHSCOPE_WORKSPACE", + "DASHSCOPE_REGION", + "DASHSCOPE_PROTOCOL", + "DASHSCOPE_CONFIG", + ): + monkeypatch.delenv(name, raising=False) + settings.clear() + yield monkeypatch + settings.clear() + + +def _capture_handler(captured, body): + def handler(request): + captured["method"] = request.method + captured["path"] = request.url.path + captured["params"] = dict(request.url.params) + captured["sdk"] = request.headers.get("x-dashscope-sdk-client") + if request.content: + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=body) + + return handler + + +# -------------------------------------------------------------------------- +# conversation CRUD +# -------------------------------------------------------------------------- + + +def test_create_conversation_wire_and_parse(): + captured = {} + client = _make_client(_capture_handler(captured, _CONVERSATION_BODY)) + conv = client.conversations.create( + metadata={"topic": "demo"}, + items=[{"type": "message", "role": "system", "content": "hello"}], + ) + assert captured["method"] == "POST" + assert captured["path"] == "/api/v1/conversations" + assert captured["body"]["metadata"] == {"topic": "demo"} + assert captured["body"]["items"] == [ + {"type": "message", "role": "system", "content": "hello"}, + ] + assert captured["sdk"] == sdk_client_value("conversations") + assert captured["sdk"].endswith("/conversations2") + assert isinstance(conv, Conversation) + assert conv.id == _CONV_ID + assert conv.object == "conversation" + # created_at is Unix milliseconds. + assert conv.created_at == 1771316949128 + assert conv.metadata == {"topic": "demo"} + assert conv.is_error is False + client.close() + + +def test_create_conversation_empty_body(): + captured = {} + client = _make_client(_capture_handler(captured, _CONVERSATION_BODY)) + client.conversations.create() + assert captured["body"] == {} + client.close() + + +def test_get_conversation_accepts_object_or_id(): + captured = {} + client = _make_client(_capture_handler(captured, _CONVERSATION_BODY)) + conv = client.conversations.get(_CONV_ID) + assert captured["method"] == "GET" + assert captured["path"] == f"/api/v1/conversations/{_CONV_ID}" + assert conv.id == _CONV_ID + # A Conversation object is accepted in place of its id. + client.conversations.get(conv) + assert captured["path"] == f"/api/v1/conversations/{_CONV_ID}" + client.close() + + +def test_update_conversation_replaces_metadata(): + captured = {} + client = _make_client(_capture_handler(captured, _CONVERSATION_BODY)) + client.conversations.update(_CONV_ID, metadata={"topic": "update"}) + assert captured["method"] == "POST" + assert captured["path"] == f"/api/v1/conversations/{_CONV_ID}" + assert captured["body"] == {"metadata": {"topic": "update"}} + client.close() + + +def test_update_conversation_metadata_required(): + client = _make_client(_capture_handler({}, _CONVERSATION_BODY)) + with pytest.raises(ValueError, match="metadata is required"): + client.conversations.update(_CONV_ID, metadata=None) + client.close() + + +def test_delete_conversation(): + captured = {} + client = _make_client(_capture_handler(captured, _CONV_DELETED_BODY)) + result = client.conversations.delete(_CONV_ID) + assert captured["method"] == "DELETE" + assert captured["path"] == f"/api/v1/conversations/{_CONV_ID}" + assert isinstance(result, ConversationDeleted) + assert result.deleted is True + assert result.id == _CONV_ID + assert result.object == "conversation.deleted" + client.close() + + +# -------------------------------------------------------------------------- +# items +# -------------------------------------------------------------------------- + + +def test_items_create(): + captured = {} + client = _make_client(_capture_handler(captured, _ITEMS_CREATE_BODY)) + page = client.conversations.items.create( + _CONV_ID, + items=[ + { + "type": "message", + "role": "user", + "content": [{"type": "input_text", "text": "hi"}], + }, + ], + ) + assert captured["method"] == "POST" + assert captured["path"] == f"/api/v1/conversations/{_CONV_ID}/items" + assert captured["body"]["items"][0]["role"] == "user" + assert isinstance(page, ConversationItemList) + assert [i.id for i in page.items] == [_ITEM_ID] + assert page.first_id == _ITEM_ID + assert page.last_id == _ITEM_ID + assert page.has_more is False + client.close() + + +def test_items_create_requires_non_empty_items(): + client = _make_client(_capture_handler({}, _ITEMS_CREATE_BODY)) + with pytest.raises(ValueError, match="items must not be empty"): + client.conversations.items.create(_CONV_ID, items=[]) + with pytest.raises(ValueError, match="items is required"): + client.conversations.items.create(_CONV_ID, items=None) + client.close() + + +def test_items_list_params_and_parse(): + captured = {} + client = _make_client(_capture_handler(captured, _ITEMS_LIST_BODY)) + page = client.conversations.items.list( + _CONV_ID, + after="msg_prev", + limit=10, + order="asc", + ) + assert captured["method"] == "GET" + assert captured["path"] == f"/api/v1/conversations/{_CONV_ID}/items" + assert captured["params"] == { + "after": "msg_prev", + "limit": "10", + "order": "asc", + } + assert isinstance(page, ConversationItemList) + assert page.object == "list" + assert page.items[0].text == "hi" + client.close() + + +def test_items_list_cursor_traversal(): + pages = { + None: { + "data": [{**_ITEM_BODY, "id": "msg_1"}], + "first_id": "msg_1", + "last_id": "msg_1", + "has_more": True, + "object": "list", + }, + "msg_1": { + "data": [{**_ITEM_BODY, "id": "msg_2"}], + "first_id": "msg_2", + "last_id": "msg_2", + "has_more": False, + "object": "list", + }, + } + + def handler(request): + after = request.url.params.get("after") + return httpx.Response(200, json=pages[after]) + + client = _make_client(handler) + first = client.conversations.items.list(_CONV_ID) + assert first.has_next_page() is True + ids = [item.id for page in first.iter_pages() for item in page] + assert ids == ["msg_1", "msg_2"] + client.close() + + +def test_items_get_and_text(): + captured = {} + client = _make_client(_capture_handler(captured, _ITEM_BODY)) + item = client.conversations.items.get(_CONV_ID, _ITEM_ID) + assert captured["method"] == "GET" + assert captured["path"] == ( + f"/api/v1/conversations/{_CONV_ID}/items/{_ITEM_ID}" + ) + assert isinstance(item, ConversationItem) + assert item.role == "user" + assert item.status == "completed" + assert item.text == "hi" + client.close() + + +def test_item_text_from_string_content(): + body = {**_ITEM_BODY, "content": "plain string"} + client = _make_client(_capture_handler({}, body)) + item = client.conversations.items.get(_CONV_ID, _ITEM_ID) + assert item.content == "plain string" + assert item.text == "plain string" + client.close() + + +def test_items_delete(): + captured = {} + client = _make_client(_capture_handler(captured, _ITEM_DELETED_BODY)) + result = client.conversations.items.delete(_CONV_ID, _ITEM_ID) + assert captured["method"] == "DELETE" + assert captured["path"] == ( + f"/api/v1/conversations/{_CONV_ID}/items/{_ITEM_ID}" + ) + assert isinstance(result, ConversationItemDeleted) + assert result.deleted is True + assert result.object == "conversation.item.deleted" + client.close() + + +# -------------------------------------------------------------------------- +# routing +# -------------------------------------------------------------------------- + + +@pytest.mark.parametrize("protocol", ["native", "openai", "anthropic"]) +def test_routing_default_gateway_ignores_chat_protocol(clean_env, protocol): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_CONVERSATION_BODY) + + http_client = httpx.Client( + transport=httpx.MockTransport(handler), + base_url=_WS_HOST + "/api/v1", + ) + client = Client( + api_key="sk-test", + workspace="ws-123", + protocol=protocol, + http_client=http_client, + ) + client.conversations.get(_CONV_ID) + assert urls == [ + _WS_HOST + _COMPAT_CONVERSATIONS + f"/{_CONV_ID}", + ], protocol + client.close() + + +def test_routing_explicit_base_url(): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_CONVERSATION_BODY) + + client = _make_client(handler) + client.conversations.create() + assert urls == [BASE_URL + "/conversations"] + client.close() + + +# -------------------------------------------------------------------------- +# pre-validation +# -------------------------------------------------------------------------- + + +def test_conversation_id_empty_raises(): + client = _make_client(_capture_handler({}, _CONVERSATION_BODY)) + with pytest.raises(ValueError, match="conversation_id must be"): + client.conversations.get(" ") + client.close() + + +def test_item_id_empty_raises(): + client = _make_client(_capture_handler({}, _ITEM_BODY)) + with pytest.raises(ValueError, match="item_id must be"): + client.conversations.items.get(_CONV_ID, "") + client.close() + + +@pytest.mark.parametrize("limit", [0, 101, -1]) +def test_items_limit_validation(limit): + client = _make_client(_capture_handler({}, _ITEMS_LIST_BODY)) + with pytest.raises(ValueError, match="limit must be between 1 and 100"): + client.conversations.items.list(_CONV_ID, limit=limit) + client.close() + + +def test_items_order_validation(): + client = _make_client(_capture_handler({}, _ITEMS_LIST_BODY)) + with pytest.raises(ValueError, match="order must be"): + client.conversations.items.list(_CONV_ID, order="sideways") + client.close() + + +def test_metadata_pair_limit(): + client = _make_client(_capture_handler({}, _CONVERSATION_BODY)) + too_many = {f"k{i}": "v" for i in range(17)} + with pytest.raises(ValueError, match="at most 16"): + client.conversations.create(metadata=too_many) + client.close() + + +def test_metadata_key_value_length_limits(): + client = _make_client(_capture_handler({}, _CONVERSATION_BODY)) + with pytest.raises(ValueError, match="keys must be strings"): + client.conversations.create(metadata={"k" * 65: "v"}) + with pytest.raises(ValueError, match="values must be strings"): + client.conversations.create(metadata={"k": "v" * 513}) + client.close() + + +def test_items_max_20(): + client = _make_client(_capture_handler({}, _ITEMS_CREATE_BODY)) + items = [ + {"type": "message", "role": "user", "content": "x"} for _ in range(21) + ] + with pytest.raises(ValueError, match="at most 20"): + client.conversations.items.create(_CONV_ID, items=items) + client.close() + + +# -------------------------------------------------------------------------- +# errors / raw +# -------------------------------------------------------------------------- + + +def test_http_error_raises(): + def handler(request): + return httpx.Response( + 400, + json={"error": {"code": "InvalidParameter", "message": "bad"}}, + headers={"x-request-id": "rid-err"}, + ) + + client = _make_client(handler) + with pytest.raises(BadRequestError) as ei: + client.conversations.get(_CONV_ID) + assert ei.value.code == "InvalidParameter" + assert ei.value.request_id == "rid-err" + client.close() + + +def test_error_envelope_when_not_raising(): + def handler(request): + return httpx.Response( + 404, + json={"error": {"code": "NotFound", "message": "gone"}}, + headers={"x-request-id": "rid-404"}, + ) + + client = _make_client(handler, raise_on_error=False) + conv = client.conversations.get(_CONV_ID) + assert conv.is_error is True + assert conv.status_code == 404 + assert conv.code == "NotFound" + assert conv.message == "gone" + assert conv.request_id == "rid-404" + client.close() + + +def test_business_error_layer(): + body = { + "code": "InvalidParameter", + "message": "unsupported", + "request_id": "rid-biz", + } + + def handler(request): + return httpx.Response(200, json=body) + + client = _make_client(handler) + with pytest.raises(BadRequestError): + client.conversations.create() + client.close() + + client = _make_client(handler, raise_on_error=False) + conv = client.conversations.create() + assert conv.is_error is True + assert conv.code == "InvalidParameter" + client.close() + + +def test_raw_returns_apiresponse_before_error_check(): + def handler(request): + return httpx.Response(400, json={"error": {"message": "bad"}}) + + client = _make_client(handler) + raw = client.conversations.get(_CONV_ID, raw=True) + assert isinstance(raw, APIResponse) + assert raw.http_response.status_code == 400 + assert raw.json()["error"]["message"] == "bad" + client.close() + + +def test_items_list_error_not_paginated(): + def handler(request): + return httpx.Response( + 404, + json={"error": {"code": "NotFound", "message": "gone"}}, + ) + + client = _make_client(handler, raise_on_error=False) + page = client.conversations.items.list(_CONV_ID) + assert page.is_error is True + assert page.has_next_page() is False + client.close() + + +# -------------------------------------------------------------------------- +# Responses linkage (C1 + C2) +# -------------------------------------------------------------------------- + + +def test_responses_create_with_conversation(): + bodies = {} + + def handler(request): + if request.url.path == "/api/v1/conversations": + return httpx.Response(200, json=_CONVERSATION_BODY) + if request.url.path == "/api/v1/responses": + bodies["responses"] = json.loads(request.content) + return httpx.Response( + 200, + json={"id": "resp_1", "object": "response", "output": []}, + ) + raise AssertionError(f"unexpected path {request.url.path}") + + client = _make_client(handler) + conv = client.conversations.create() + client.responses.create( + model="qwen-plus", + input="hi", + conversation=conv.id, + ) + assert bodies["responses"]["conversation"] == _CONV_ID + client.close() + + +def test_responses_conversation_mutex_previous_response_id(): + client = _make_client(_capture_handler({}, _CONVERSATION_BODY)) + with pytest.raises(ValueError, match="mutually exclusive"): + client.responses.create( + model="qwen-plus", + input="hi", + conversation=_CONV_ID, + previous_response_id="resp_1", + ) + client.close() + + +# -------------------------------------------------------------------------- +# async symmetry +# -------------------------------------------------------------------------- + + +@pytest.mark.asyncio +async def test_async_conversation_crud(): + captured = {} + client = _make_async_client( + _capture_handler(captured, _CONVERSATION_BODY), + ) + conv = await client.conversations.create(metadata={"topic": "demo"}) + assert captured["sdk"].endswith("/conversations2") + assert conv.id == _CONV_ID + await client.conversations.get(conv) + assert captured["path"] == f"/api/v1/conversations/{_CONV_ID}" + await client.conversations.update(_CONV_ID, metadata={"topic": "x"}) + assert captured["body"] == {"metadata": {"topic": "x"}} + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_delete_conversation(): + captured = {} + client = _make_async_client( + _capture_handler(captured, _CONV_DELETED_BODY), + ) + result = await client.conversations.delete(_CONV_ID) + assert captured["method"] == "DELETE" + assert result.deleted is True + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_items_create_list_get_delete(): + captured = {} + client = _make_async_client( + _capture_handler(captured, _ITEMS_CREATE_BODY), + ) + page = await client.conversations.items.create( + _CONV_ID, + items=[{"type": "message", "role": "user", "content": "hi"}], + ) + assert captured["path"] == f"/api/v1/conversations/{_CONV_ID}/items" + assert page.items[0].id == _ITEM_ID + await client.aclose() + + client = _make_async_client(_capture_handler(captured, _ITEMS_LIST_BODY)) + listed = await client.conversations.items.list(_CONV_ID, limit=5) + assert captured["params"]["limit"] == "5" + assert listed.items[0].text == "hi" + await client.aclose() + + client = _make_async_client(_capture_handler(captured, _ITEM_BODY)) + item = await client.conversations.items.get(_CONV_ID, _ITEM_ID) + assert item.text == "hi" + await client.aclose() + + client = _make_async_client( + _capture_handler(captured, _ITEM_DELETED_BODY), + ) + deleted = await client.conversations.items.delete(_CONV_ID, _ITEM_ID) + assert deleted.deleted is True + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_items_cursor_traversal(): + pages = { + None: { + "data": [{**_ITEM_BODY, "id": "msg_1"}], + "first_id": "msg_1", + "last_id": "msg_1", + "has_more": True, + "object": "list", + }, + "msg_1": { + "data": [{**_ITEM_BODY, "id": "msg_2"}], + "first_id": "msg_2", + "last_id": "msg_2", + "has_more": False, + "object": "list", + }, + } + + def handler(request): + return httpx.Response(200, json=pages[request.url.params.get("after")]) + + client = _make_async_client(handler) + first = await client.conversations.items.list(_CONV_ID) + ids = [item.id async for page in first.iter_pages_async() for item in page] + assert ids == ["msg_1", "msg_2"] + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_routing_default_gateway(clean_env): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_CONVERSATION_BODY) + + http_client = httpx.AsyncClient( + transport=httpx.MockTransport(handler), + base_url=_WS_HOST + "/api/v1", + ) + client = AsyncClient( + api_key="sk-test", + workspace="ws-123", + http_client=http_client, + ) + await client.conversations.get(_CONV_ID) + assert urls == [_WS_HOST + _COMPAT_CONVERSATIONS + f"/{_CONV_ID}"] + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_error_envelope_when_not_raising(): + def handler(request): + return httpx.Response( + 404, + json={"error": {"code": "NotFound", "message": "gone"}}, + ) + + client = _make_async_client(handler, raise_on_error=False) + conv = await client.conversations.get(_CONV_ID) + assert conv.is_error is True + assert conv.code == "NotFound" + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_raw(): + client = _make_async_client( + _capture_handler({}, _CONVERSATION_BODY), + ) + raw = await client.conversations.create(raw=True) + assert isinstance(raw, APIResponse) + assert raw.json()["id"] == _CONV_ID + await client.aclose() + + +# -------------------------------------------------------------------------- +# path-id guards (percent-encoding, rejection before the wire) +# -------------------------------------------------------------------------- + +_TRICKY_CONV = "conv/a?b#c" +_TRICKY_ITEM = "msg/x?y#z" +_ENCODED_CONV = b"/api/v1/conversations/conv%2Fa%3Fb%23c" +_ENCODED_ITEM = b"/items/msg%2Fx%3Fy%23z" +_VALID_ITEMS = [ + { + "type": "message", + "role": "user", + "content": [{"type": "input_text", "text": "hi"}], + }, +] + + +def _id_guard_handler(seen): + def handler(request): + seen.append(request.url.raw_path) + path = request.url.path + if path.endswith("/items"): + body = ( + _ITEMS_CREATE_BODY + if request.method == "POST" + else _ITEMS_LIST_BODY + ) + elif "/items/" in path: + body = ( + _ITEM_DELETED_BODY + if request.method == "DELETE" + else _ITEM_BODY + ) + elif request.method == "DELETE": + body = _CONV_DELETED_BODY + else: + body = _CONVERSATION_BODY + return httpx.Response(200, json=body) + + return handler + + +def test_conversation_and_item_ids_percent_encoded_in_path(): + seen = [] + client = _make_client(_id_guard_handler(seen)) + client.conversations.get(_TRICKY_CONV) + client.conversations.update(_TRICKY_CONV, metadata={"topic": "x"}) + client.conversations.delete(_TRICKY_CONV) + client.conversations.items.create(_TRICKY_CONV, items=_VALID_ITEMS) + client.conversations.items.list(_TRICKY_CONV) + client.conversations.items.get(_TRICKY_CONV, _TRICKY_ITEM) + client.conversations.items.delete(_TRICKY_CONV, _TRICKY_ITEM) + # '/', '?' and '#' stay inside one path segment instead of retargeting + # the request to another path or query. + assert seen == [ + _ENCODED_CONV, + _ENCODED_CONV, + _ENCODED_CONV, + _ENCODED_CONV + b"/items", + _ENCODED_CONV + b"/items", + _ENCODED_CONV + _ENCODED_ITEM, + _ENCODED_CONV + _ENCODED_ITEM, + ] + client.close() + + +@pytest.mark.parametrize("bad", ["", " "]) +def test_empty_conversation_id_rejected_before_wire(bad): + def handler(request): + raise AssertionError("request must not reach the wire") + + client = _make_client(handler) + with pytest.raises(ValueError, match="conversation_id"): + client.conversations.get(bad) + with pytest.raises(ValueError, match="conversation_id"): + client.conversations.update(bad, metadata={"k": "v"}) + with pytest.raises(ValueError, match="conversation_id"): + client.conversations.delete(bad) + with pytest.raises(ValueError, match="conversation_id"): + client.conversations.items.create(bad, items=_VALID_ITEMS) + with pytest.raises(ValueError, match="conversation_id"): + client.conversations.items.list(bad) + with pytest.raises(ValueError, match="conversation_id"): + client.conversations.items.get(bad, _ITEM_ID) + with pytest.raises(ValueError, match="conversation_id"): + client.conversations.items.delete(bad, _ITEM_ID) + client.close() + + +@pytest.mark.parametrize("bad", ["", " "]) +def test_empty_item_id_rejected_before_wire(bad): + def handler(request): + raise AssertionError("request must not reach the wire") + + client = _make_client(handler) + with pytest.raises(ValueError, match="item_id"): + client.conversations.items.get(_CONV_ID, bad) + with pytest.raises(ValueError, match="item_id"): + client.conversations.items.delete(_CONV_ID, bad) + client.close() + + +@pytest.mark.asyncio +async def test_async_ids_percent_encoded_in_path(): + seen = [] + client = _make_async_client(_id_guard_handler(seen)) + await client.conversations.get(_TRICKY_CONV) + await client.conversations.items.get(_TRICKY_CONV, _TRICKY_ITEM) + await client.conversations.items.delete(_TRICKY_CONV, _TRICKY_ITEM) + assert seen == [ + _ENCODED_CONV, + _ENCODED_CONV + _ENCODED_ITEM, + _ENCODED_CONV + _ENCODED_ITEM, + ] + await client.aclose() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("bad", ["", " "]) +async def test_async_empty_ids_rejected_before_wire(bad): + def handler(request): + raise AssertionError("request must not reach the wire") + + client = _make_async_client(handler) + with pytest.raises(ValueError, match="conversation_id"): + await client.conversations.get(bad) + with pytest.raises(ValueError, match="conversation_id"): + await client.conversations.update(bad, metadata={"k": "v"}) + with pytest.raises(ValueError, match="conversation_id"): + await client.conversations.delete(bad) + with pytest.raises(ValueError, match="conversation_id"): + await client.conversations.items.list(bad) + with pytest.raises(ValueError, match="item_id"): + await client.conversations.items.get(_CONV_ID, bad) + with pytest.raises(ValueError, match="item_id"): + await client.conversations.items.delete(_CONV_ID, bad) + await client.aclose() diff --git a/tests/test_deployments_ptu.py b/tests/test_deployments_ptu.py new file mode 100644 index 00000000..807654b9 --- /dev/null +++ b/tests/test_deployments_ptu.py @@ -0,0 +1,1102 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Tests for PTU throughput reservation (milestone D3). + +Covers ``client.deployments`` PTU create/scale/renew/overflow plus the +``capacity_instances`` and ``capacity_operations`` subresources: wire +bodies, billing safeguards (max_retries=0 default, x-acs-req-uuid +idempotency), the HTTP-200 operation_status=FAILED check, the +operation_request_id collision, camelCase instance pagination, and +sync/async symmetry. Model names are public/arbitrary, never internal. +""" + +# Mock handlers intentionally ignore the request argument. +# pylint: disable=unused-argument + +from __future__ import annotations + +import json + +import httpx +import pytest + +from dashscope import AsyncClient, Client +from dashscope.errors import DashScopeError +from dashscope.resources.deployments import ( + CapacityInstance, + CapacityInstanceList, + CapacityOperation, + Deployment, + PrePaidInfo, + PtuCapacity, +) + +BASE_URL = "https://api.test.local/api/v1" + +_PTU_CAPACITY = {"input_tpm": 100, "output_tpm": 50} +_PRE_PAID = {"pricing_cycle": "Day", "duration": 1, "auto_renewal": False} + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +def _deployment_output(**extra): + output = { + "deployed_model": "pm-abc123", + "model_name": "qwen-plus", + "plan": "ptu", + "status": "RUNNING", + "ptu_service_tier": "ptu_fast", + "ptu_capacity": _PTU_CAPACITY, + "charge_type": "pre_paid", + "overflow_strategy": "disable", + "operation_id": "op-1", + "instance_id": "ci-1", + } + output.update(extra) + return {"request_id": "req-dep", "output": output} + + +def _operation_output(status="PROCESSING", **extra): + output = { + "operation_id": "op-1", + "request_id": "req-original-write", + "operation_type": "CREATE", + "operation_status": status, + "model_service_id": "pm-abc123", + "instance_id": "ci-1", + } + output.update(extra) + return {"request_id": "req-poll", "output": output} + + +def _instance_output(**extra): + output = { + "model_service_id": "pm-abc123", + "instance_id": "ci-1", + "charge_type": "pre_paid", + "status": "RUNNING", + "deleted": False, + "effective_capacity": _PTU_CAPACITY, + "can_scale": True, + "can_renew": True, + "can_delete": False, + } + output.update(extra) + return {"request_id": "req-inst", "output": output} + + +# --- PTU create ---------------------------------------------------------- + + +def test_ptu_create_wire_body_and_no_idempotency(): + captured = {} + + def handler(request): + captured["body"] = json.loads(request.content) + captured["headers"] = request.headers + return httpx.Response(200, json=_deployment_output()) + + client = _make_client(handler) + created = client.deployments.create( + model="qwen-plus", + plan="ptu", + charge_type="pre_paid", + ptu_capacity=_PTU_CAPACITY, + pre_paid_info=_PRE_PAID, + service_tier="ptu_fast", + name="my-ptu", + suffix="alpha", + ) + body = captured["body"] + assert body["model_name"] == "qwen-plus" + assert body["plan"] == "ptu" + assert body["charge_type"] == "pre_paid" + assert body["ptu_capacity"] == _PTU_CAPACITY + assert body["pre_paid_info"] == _PRE_PAID + assert body["service_tier"] == "ptu_fast" + assert body["name"] == "my-ptu" + assert body["suffix"] == "alpha" + assert "capacity" not in body + # First ModelCode creation must NOT carry an instance idempotency key. + assert "x-acs-req-uuid" not in captured["headers"] + assert "x-dashscope-requestid" not in captured["headers"] + assert isinstance(created, Deployment) + assert created.plan == "ptu" + assert created.ptu_capacity.input_tpm == 100 + assert created.ptu_capacity.output_tpm == 50 + assert created.overflow_strategy == "disable" + assert created.operation_id == "op-1" + assert created.instance_id == "ci-1" + client.close() + + +def test_ptu_create_accepts_typed_models(): + captured = {} + + def handler(request): + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_deployment_output()) + + client = _make_client(handler) + client.deployments.create( + model="qwen-plus", + plan="ptu", + charge_type="post_paid", + ptu_capacity=PtuCapacity(input_tpm=100, output_tpm=50), + pre_paid_info=PrePaidInfo(pricing_cycle="Day", duration=1), + ) + assert captured["body"]["ptu_capacity"] == _PTU_CAPACITY + assert captured["body"]["pre_paid_info"]["duration"] == 1 + client.close() + + +def test_ptu_create_defaults_to_no_retry(): + attempts = [] + + def handler(request): + attempts.append(1) + return httpx.Response(503, json={"message": "busy"}) + + client = _make_client(handler) + with pytest.raises(DashScopeError): + client.deployments.create( + model="qwen-plus", + plan="ptu", + charge_type="post_paid", + ptu_capacity=_PTU_CAPACITY, + ) + assert len(attempts) == 1 + client.close() + + +def test_ptu_create_explicit_max_retries_retries(monkeypatch): + attempts = [] + + def handler(request): + attempts.append(1) + if len(attempts) < 3: + return httpx.Response(503, json={"message": "busy"}) + return httpx.Response(200, json=_deployment_output()) + + from dashscope.transport import http as transport_http + + monkeypatch.setattr(transport_http, "_sleep", lambda seconds: None) + client = _make_client(handler) + created = client.deployments.create( + model="qwen-plus", + plan="ptu", + charge_type="post_paid", + ptu_capacity=_PTU_CAPACITY, + max_retries=2, + ) + assert created.deployed_model == "pm-abc123" + assert len(attempts) == 3 + client.close() + + +def test_mu_create_keeps_default_retry(monkeypatch): + attempts = [] + + def handler(request): + attempts.append(1) + return httpx.Response(503, json={"message": "busy"}) + + from dashscope.transport import http as transport_http + + monkeypatch.setattr(transport_http, "_sleep", lambda seconds: None) + client = _make_client(handler) + with pytest.raises(DashScopeError): + client.deployments.create(model="qwen-plus", capacity=2, plan="mu") + # The purchase safeguard is PTU-specific; MU create still retries. + assert len(attempts) > 1 + client.close() + + +@pytest.mark.parametrize( + "kwargs,match", + [ + ({"plan": "ptu", "ptu_capacity": _PTU_CAPACITY}, "charge_type"), + ({"plan": "ptu", "charge_type": "post_paid"}, "ptu_capacity"), + ( + { + "plan": "ptu", + "charge_type": "pre_paid", + "ptu_capacity": _PTU_CAPACITY, + }, + "pre_paid_info", + ), + ( + { + "plan": "ptu", + "charge_type": "post_paid", + "ptu_capacity": {"input_tpm": 100}, + }, + "output_tpm", + ), + ( + { + "plan": "ptu", + "charge_type": "post_paid", + "ptu_capacity": {"input_tpm": -1, "output_tpm": 5}, + }, + "non-negative", + ), + ], +) +def test_ptu_create_validation(kwargs, match): + client = _make_client( + lambda r: httpx.Response(200, json=_deployment_output()), + ) + with pytest.raises(ValueError, match=match): + client.deployments.create(model="qwen-plus", **kwargs) + client.close() + + +# --- PTU scale ----------------------------------------------------------- + + +def test_ptu_scale_body_idempotency_and_no_retry(): + captured = {} + attempts = [] + + def handler(request): + attempts.append(1) + captured["body"] = json.loads(request.content) + captured["headers"] = request.headers + captured["path"] = request.url.path + return httpx.Response(200, json=_deployment_output()) + + client = _make_client(handler) + client.deployments.scale( + "pm-abc123", + ptu_capacity={"input_tpm": 200, "output_tpm": 100}, + instance_id="ci-1", + order_type="UPGRADE", + ) + assert captured["path"] == "/api/v1/deployments/pm-abc123/scale" + assert captured["body"] == { + "deployed_model": "pm-abc123", + "ptu_capacity": {"input_tpm": 200, "output_tpm": 100}, + "instance_id": "ci-1", + "order_type": "UPGRADE", + } + key = captured["headers"]["x-acs-req-uuid"] + assert key + assert captured["headers"]["x-dashscope-requestid"] == key + assert len(attempts) == 1 + client.close() + + +def test_mu_scale_has_no_idempotency_key(): + captured = {} + + def handler(request): + captured["headers"] = request.headers + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_deployment_output()) + + client = _make_client(handler) + client.deployments.scale("pm-abc123", capacity=4) + assert captured["body"] == {"deployed_model": "pm-abc123", "capacity": 4} + assert "x-acs-req-uuid" not in captured["headers"] + client.close() + + +def test_scale_requires_capacity_or_ptu(): + client = _make_client( + lambda r: httpx.Response(200, json=_deployment_output()), + ) + with pytest.raises(ValueError, match="capacity or ptu_capacity"): + client.deployments.scale("pm-abc123") + with pytest.raises(ValueError, match="order_type"): + client.deployments.scale( + "pm-abc123", + capacity=2, + order_type="SIDEWAYS", + ) + client.close() + + +def test_scale_reuses_caller_idempotency_key(): + captured = {} + + def handler(request): + captured["headers"] = request.headers + return httpx.Response(200, json=_deployment_output()) + + client = _make_client(handler) + client.deployments.scale( + "pm-abc123", + ptu_capacity=_PTU_CAPACITY, + extra_headers={"x-acs-req-uuid": "my-key"}, + ) + assert captured["headers"]["x-acs-req-uuid"] == "my-key" + assert captured["headers"]["x-dashscope-requestid"] == "my-key" + client.close() + + +def _assert_scale_reuses_variant_key(variant): + captured = {} + + def handler(request): + captured["headers"] = request.headers + captured["raw"] = request.headers.raw + return httpx.Response(200, json=_deployment_output()) + + client = _make_client(handler) + client.deployments.scale( + "pm-abc123", + ptu_capacity=_PTU_CAPACITY, + extra_headers={variant: "my-key"}, + ) + # One key on the wire, not a caller/SDK pair with conflicting values + # (httpx joins duplicate header lines with ", "). + assert captured["headers"]["x-acs-req-uuid"] == "my-key" + assert captured["headers"]["x-dashscope-requestid"] == "my-key" + names = [name.lower() for name, _ in captured["raw"]] + assert names.count(b"x-acs-req-uuid") == 1 + assert names.count(b"x-dashscope-requestid") == 1 + client.close() + + +def test_scale_reuses_case_variant_idempotency_key(): + for variant in ("X-Acs-Req-Uuid", "x-dashscope-requestid"): + _assert_scale_reuses_variant_key(variant) + + +# --- renew / overflow ---------------------------------------------------- + + +def test_renew_body_and_safeguards(): + captured = {} + attempts = [] + + def handler(request): + attempts.append(1) + captured["body"] = json.loads(request.content) + captured["headers"] = request.headers + captured["path"] = request.url.path + return httpx.Response(200, json=_deployment_output()) + + client = _make_client(handler) + client.deployments.renew( + "pm-abc123", + pre_paid_info=_PRE_PAID, + instance_id="ci-1", + is_change=True, + ptu_capacity=_PTU_CAPACITY, + ) + assert captured["path"] == "/api/v1/deployments/pm-abc123/renew" + assert captured["body"] == { + "pre_paid_info": _PRE_PAID, + "instance_id": "ci-1", + "is_change": True, + "ptu_capacity": _PTU_CAPACITY, + } + assert captured["headers"]["x-acs-req-uuid"] + assert len(attempts) == 1 + client.close() + + +def test_renew_capacity_change_requires_is_change(): + client = _make_client( + lambda r: httpx.Response(200, json=_deployment_output()), + ) + with pytest.raises(ValueError, match="is_change"): + client.deployments.renew( + "pm-abc123", + pre_paid_info=_PRE_PAID, + ptu_capacity=_PTU_CAPACITY, + ) + client.close() + + +def test_update_overflow_strategy(): + captured = {} + + def handler(request): + captured["body"] = json.loads(request.content) + captured["path"] = request.url.path + captured["headers"] = request.headers + return httpx.Response( + 200, + json=_deployment_output(overflow_strategy="enable"), + ) + + client = _make_client(handler) + updated = client.deployments.update_overflow_strategy( + "pm-abc123", + overflow_strategy="enable", + ) + assert captured["path"] == ( + "/api/v1/deployments/pm-abc123/update-overflowstrategy" + ) + assert captured["body"] == {"overflow_strategy": "enable"} + # Config toggle, not a purchase: no idempotency key forced. + assert "x-acs-req-uuid" not in captured["headers"] + assert updated.overflow_strategy == "enable" + with pytest.raises(ValueError, match="overflow_strategy"): + client.deployments.update_overflow_strategy( + "pm-abc123", + overflow_strategy="ENABLE", + ) + client.close() + + +# --- capacity instances -------------------------------------------------- + + +def test_instance_create_body_idempotency_and_operation(): + captured = {} + attempts = [] + + def handler(request): + attempts.append(1) + captured["body"] = json.loads(request.content) + captured["headers"] = request.headers + captured["path"] = request.url.path + return httpx.Response(200, json=_operation_output("SUCCEEDED")) + + client = _make_client(handler) + op = client.deployments.capacity_instances.create( + "pm-abc123", + billing_method="PRE_PAY", + ptu_capacity=_PTU_CAPACITY, + pre_paid_info=_PRE_PAID, + ) + assert captured["path"] == ( + "/api/v1/deployments/pm-abc123/capacity-instances" + ) + assert captured["body"] == { + "billing_method": "PRE_PAY", + "ptu_capacity": _PTU_CAPACITY, + "pre_paid_info": _PRE_PAID, + } + assert captured["headers"]["x-acs-req-uuid"] + assert len(attempts) == 1 + assert isinstance(op, CapacityOperation) + assert op.succeeded + assert op.operation_id == "op-1" + # Inner write request id preserved separately from the poll envelope. + assert op.request_id == "req-poll" + assert op.operation_request_id == "req-original-write" + client.close() + + +def test_instance_create_postpaid_no_prepaid_ok(): + captured = {} + + def handler(request): + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_operation_output("SUCCEEDED")) + + client = _make_client(handler) + client.deployments.capacity_instances.create( + "pm-abc123", + billing_method="POST_PAY", + ptu_capacity=_PTU_CAPACITY, + ) + assert "pre_paid_info" not in captured["body"] + client.close() + + +@pytest.mark.parametrize( + "kwargs,match", + [ + ( + {"billing_method": "pre_pay", "ptu_capacity": _PTU_CAPACITY}, + "billing_method", + ), + ( + {"billing_method": "PRE_PAY", "ptu_capacity": _PTU_CAPACITY}, + "pre_paid_info", + ), + ( + {"billing_method": "POST_PAY", "ptu_capacity": {"input_tpm": 1}}, + "output_tpm", + ), + ], +) +def test_instance_create_validation(kwargs, match): + client = _make_client( + lambda r: httpx.Response(200, json=_operation_output()), + ) + with pytest.raises(ValueError, match=match): + client.deployments.capacity_instances.create("pm-abc123", **kwargs) + client.close() + + +def test_instance_list_camelcase_pagination(): + captured = {} + + def handler(request): + captured["params"] = dict(request.url.params) + captured["path"] = request.url.path + return httpx.Response( + 200, + json={ + "request_id": "req-list", + "output": { + "records": [_instance_output()["output"]], + "items": 7, + "page": 2, + "itemsPerPage": 20, + "pageCount": 1, + }, + }, + ) + + client = _make_client(handler) + page = client.deployments.capacity_instances.list( + "pm-abc123", + page_no=2, + page_size=20, + statuses="RUNNING,STOPPED", + charge_types="pre_paid,post_paid", + ) + assert captured["path"] == ( + "/api/v1/deployments/pm-abc123/capacity-instances" + ) + assert captured["params"] == { + "page_no": "2", + "page_size": "20", + "include_deleted": "true", + "statuses": "RUNNING,STOPPED", + "charge_types": "pre_paid,post_paid", + } + assert isinstance(page, CapacityInstanceList) + assert page.total_count == 7 + assert page.page == 2 + assert page.items_per_page == 20 + assert page.page_count == 1 + assert isinstance(page.records[0], CapacityInstance) + assert page.records[0].instance_id == "ci-1" + assert page.records[0].can_scale is True + client.close() + + +def test_instance_list_snake_case_pagination(): + def handler(request): + return httpx.Response( + 200, + json={ + "request_id": "req-list", + "output": { + "records": [_instance_output()["output"]], + "total_count": 7, + "page_no": 1, + "page_size": 1, + "page_count": 7, + }, + }, + ) + + client = _make_client(handler) + page = client.deployments.capacity_instances.list( + "pm-abc123", + page_no=1, + page_size=1, + ) + # The snake_case totals must survive: falling back to len(records)/20 + # would report one full page and stop pagination early. + assert page.total_count == 7 + assert page.page == 1 + assert page.items_per_page == 1 + assert page.page_count == 7 + client.close() + + +def test_instance_get(): + captured = {} + + def handler(request): + captured["path"] = request.url.path + return httpx.Response(200, json=_instance_output(can_delete=True)) + + client = _make_client(handler) + inst = client.deployments.capacity_instances.get("pm-abc123", "ci-1") + assert captured["path"] == ( + "/api/v1/deployments/pm-abc123/capacity-instances/ci-1" + ) + assert inst.model_service_id == "pm-abc123" + assert inst.effective_capacity.input_tpm == 100 + assert inst.can_delete is True + client.close() + + +def test_instance_scale_renew_delete_paths(): + seen = [] + + def handler(request): + body = json.loads(request.content) if request.content else None + seen.append((request.method, request.url.path, body, request.headers)) + return httpx.Response(200, json=_operation_output("SUCCEEDED")) + + client = _make_client(handler) + ci = client.deployments.capacity_instances + ci.scale( + "pm-abc123", + "ci-1", + ptu_capacity=_PTU_CAPACITY, + order_type="DOWNGRADE", + ) + ci.renew("pm-abc123", "ci-1", pre_paid_info=_PRE_PAID) + ci.delete("pm-abc123", "ci-1", reason="scaling down") + assert seen[0][0] == "PUT" + assert seen[0][1] == ( + "/api/v1/deployments/pm-abc123/capacity-instances/ci-1/scale" + ) + assert seen[0][2] == { + "ptu_capacity": _PTU_CAPACITY, + "order_type": "DOWNGRADE", + } + assert seen[1][1] == ( + "/api/v1/deployments/pm-abc123/capacity-instances/ci-1/renew" + ) + assert seen[1][2] == {"pre_paid_info": _PRE_PAID} + assert seen[2][0] == "DELETE" + assert seen[2][1] == ( + "/api/v1/deployments/pm-abc123/capacity-instances/ci-1" + ) + # Delete carries no JSON body; reason rides as a query parameter. + assert seen[2][2] is None + for _, _, _, headers in seen: + assert headers["x-acs-req-uuid"] + client.close() + + +def test_instance_delete_reason_query(): + captured = {} + + def handler(request): + captured["params"] = dict(request.url.params) + return httpx.Response(200, json=_operation_output("SUCCEEDED")) + + client = _make_client(handler) + client.deployments.capacity_instances.delete( + "pm-abc123", + "ci-1", + reason="bye", + ) + assert captured["params"] == {"reason": "bye"} + client.close() + + +# --- operation failure / polling ----------------------------------------- + + +def test_operation_failed_raises_catalog_error(): + def handler(request): + return httpx.Response( + 200, + json=_operation_output( + "FAILED", + error_code="CAPACITY_INSTANCE_REQUIRED", + error_message="instance id required", + ), + ) + + client = _make_client(handler) + with pytest.raises(DashScopeError) as exc: + client.deployments.capacity_instances.create( + "pm-abc123", + billing_method="POST_PAY", + ptu_capacity=_PTU_CAPACITY, + ) + assert exc.value.code == "CAPACITY_INSTANCE_REQUIRED" + client.close() + + +def test_operation_failed_compat_returns_envelope(): + def handler(request): + return httpx.Response( + 200, + json=_operation_output( + "FAILED", + error_code="PREPAID_UNSUBSCRIBE_REQUIRED", + error_message="unsubscribe first", + ), + ) + + client = _make_client(handler, raise_on_error=False) + op = client.deployments.capacity_instances.delete("pm-abc123", "ci-1") + assert op.failed + assert op.operation_status == "FAILED" + assert op.error_code == "PREPAID_UNSUBSCRIBE_REQUIRED" + client.close() + + +def test_operations_get_path_and_request_id_collision(): + captured = {} + + def handler(request): + captured["path"] = request.url.path + return httpx.Response(200, json=_operation_output("SUCCEEDED")) + + client = _make_client(handler) + op = client.deployments.capacity_operations.get("pm-abc123", "op-1") + assert captured["path"] == ( + "/api/v1/deployments/pm-abc123/capacity-operations/op-1" + ) + assert op.request_id == "req-poll" + assert op.operation_request_id == "req-original-write" + assert op.finished + client.close() + + +def test_operations_get_404_maps_error(): + def handler(request): + return httpx.Response( + 404, + json={"code": "CAPACITY_OPERATION_NOT_FOUND", "message": "no op"}, + ) + + client = _make_client(handler) + with pytest.raises(DashScopeError) as exc: + client.deployments.capacity_operations.get("pm-abc123", "999") + assert exc.value.status_code == 404 + client.close() + + +def test_wait_polls_until_terminal(): + states = iter(["PROCESSING", "PROCESSING", "SUCCEEDED"]) + polls = [] + + def handler(request): + polls.append(1) + return httpx.Response(200, json=_operation_output(next(states))) + + client = _make_client(handler) + op = client.deployments.capacity_operations.wait( + "pm-abc123", + "op-1", + _sleep=lambda seconds: None, + ) + assert op.succeeded + assert len(polls) == 3 + client.close() + + +def test_wait_failed_raises(): + states = iter(["PROCESSING", "FAILED"]) + + def handler(request): + return httpx.Response( + 200, + json=_operation_output( + next(states), + error_code="InternalError", + error_message="boom", + ), + ) + + client = _make_client(handler) + with pytest.raises(DashScopeError) as exc: + client.deployments.capacity_operations.wait( + "pm-abc123", + "op-1", + _sleep=lambda seconds: None, + ) + assert exc.value.code == "InternalError" + client.close() + + +def test_wait_timeout(): + def handler(request): + return httpx.Response(200, json=_operation_output("PROCESSING")) + + client = _make_client(handler) + with pytest.raises(DashScopeError, match="timed out"): + client.deployments.capacity_operations.wait( + "pm-abc123", + "op-1", + timeout=0, + _sleep=lambda seconds: None, + ) + client.close() + + +def test_wait_compat_returns_failed(): + def handler(request): + return httpx.Response( + 200, + json=_operation_output("FAILED", error_code="InternalError"), + ) + + client = _make_client(handler, raise_on_error=False) + op = client.deployments.capacity_operations.wait( + "pm-abc123", + "op-1", + _sleep=lambda seconds: None, + ) + assert op.failed + client.close() + + +# --- async symmetry ------------------------------------------------------ + + +async def test_async_ptu_create_and_safeguard(): + captured = {} + attempts = [] + + def handler(request): + attempts.append(1) + captured["body"] = json.loads(request.content) + captured["headers"] = request.headers + return httpx.Response(200, json=_deployment_output()) + + client = _make_async_client(handler) + created = await client.deployments.create( + model="qwen-plus", + plan="ptu", + charge_type="post_paid", + ptu_capacity=_PTU_CAPACITY, + ) + assert created.plan == "ptu" + assert captured["body"]["ptu_capacity"] == _PTU_CAPACITY + assert "x-acs-req-uuid" not in captured["headers"] + assert len(attempts) == 1 + await client.aclose() + + +async def test_async_instance_create_operation_and_failure(): + def handler(request): + return httpx.Response( + 200, + json=_operation_output( + "FAILED", + error_code="POSTPAID_INSTANCE_ALREADY_EXISTS", + error_message="exists", + ), + ) + + client = _make_async_client(handler) + with pytest.raises(DashScopeError) as exc: + await client.deployments.capacity_instances.create( + "pm-abc123", + billing_method="POST_PAY", + ptu_capacity=_PTU_CAPACITY, + ) + assert exc.value.code == "POSTPAID_INSTANCE_ALREADY_EXISTS" + await client.aclose() + + +async def test_async_instance_list_camelcase(): + def handler(request): + return httpx.Response( + 200, + json={ + "request_id": "req-list", + "output": { + "records": [_instance_output()["output"]], + "items": 3, + "page": 1, + "itemsPerPage": 20, + "pageCount": 1, + }, + }, + ) + + client = _make_async_client(handler) + page = await client.deployments.capacity_instances.list("pm-abc123") + assert page.total_count == 3 + assert page.records[0].instance_id == "ci-1" + await client.aclose() + + +async def test_async_renew_and_overflow(): + seen = [] + + def handler(request): + seen.append((request.method, request.url.path)) + return httpx.Response(200, json=_deployment_output()) + + client = _make_async_client(handler) + await client.deployments.renew("pm-abc123", pre_paid_info=_PRE_PAID) + await client.deployments.update_overflow_strategy( + "pm-abc123", + overflow_strategy="disable", + ) + assert seen == [ + ("PUT", "/api/v1/deployments/pm-abc123/renew"), + ("PUT", "/api/v1/deployments/pm-abc123/update-overflowstrategy"), + ] + await client.aclose() + + +async def test_async_wait_polls_until_terminal(): + states = iter(["PROCESSING", "SUCCEEDED"]) + polls = [] + + def handler(request): + polls.append(1) + return httpx.Response(200, json=_operation_output(next(states))) + + async def nosleep(seconds): + return None + + client = _make_async_client(handler) + op = await client.deployments.capacity_operations.wait( + "pm-abc123", + "op-1", + _sleep=nosleep, + ) + assert op.succeeded + assert len(polls) == 2 + await client.aclose() + + +# --- ID guards and percent-encoding ---------------------------------------- + + +def _no_wire(request): + raise AssertionError("invalid id must not reach the wire") + + +@pytest.mark.parametrize("bad", ["", " "]) +@pytest.mark.parametrize( + ("name", "call"), + [ + ("get", lambda c, m: c.deployments.get(m)), + ("scale", lambda c, m: c.deployments.scale(m, capacity=1)), + ( + "renew", + lambda c, m: c.deployments.renew(m, pre_paid_info=_PRE_PAID), + ), + ( + "overflow", + lambda c, m: c.deployments.update_overflow_strategy( + m, + overflow_strategy="enable", + ), + ), + ("delete", lambda c, m: c.deployments.delete(m)), + ("stream", lambda c, m: list(c.deployments.stream_events(m))), + ( + "instances.list", + lambda c, m: c.deployments.capacity_instances.list(m), + ), + ( + "instances.get", + lambda c, m: c.deployments.capacity_instances.get(m, "ci-1"), + ), + ( + "operations.get", + lambda c, m: c.deployments.capacity_operations.get(m, "op-1"), + ), + ], +) +def test_empty_deployed_model_rejected_before_wire(name, call, bad): + # An empty id would degenerate the URL to a collection path, including + # on mutating endpoints (DELETE, scale, renew). + client = _make_client(_no_wire) + with pytest.raises(ValueError, match="deployed_model"): + call(client, bad) + client.close() + + +@pytest.mark.parametrize("bad", ["", " "]) +@pytest.mark.parametrize( + ("name", "call"), + [ + ( + "instances.get", + lambda c, i: c.deployments.capacity_instances.get("pm-1", i), + ), + ( + "instances.scale", + lambda c, i: c.deployments.capacity_instances.scale( + "pm-1", + i, + ptu_capacity=_PTU_CAPACITY, + ), + ), + ( + "instances.renew", + lambda c, i: c.deployments.capacity_instances.renew( + "pm-1", + i, + pre_paid_info=_PRE_PAID, + ), + ), + ( + "instances.delete", + lambda c, i: c.deployments.capacity_instances.delete("pm-1", i), + ), + ( + "operations.get", + lambda c, i: c.deployments.capacity_operations.get("pm-1", i), + ), + ( + "operations.wait", + lambda c, i: c.deployments.capacity_operations.wait("pm-1", i), + ), + ], +) +def test_empty_instance_or_operation_id_rejected_before_wire(name, call, bad): + client = _make_client(_no_wire) + with pytest.raises(ValueError, match="non-empty string"): + call(client, bad) + client.close() + + +async def test_async_empty_ids_rejected_before_wire(): + client = _make_async_client(_no_wire) + with pytest.raises(ValueError, match="deployed_model"): + await client.deployments.get("") + with pytest.raises(ValueError, match="deployed_model"): + await client.deployments.delete(" ") + with pytest.raises(ValueError, match="deployed_model"): + _ = [event async for event in client.deployments.stream_events("")] + with pytest.raises(ValueError, match="instance_id"): + await client.deployments.capacity_instances.get("pm-1", "") + with pytest.raises(ValueError, match="operation_id"): + await client.deployments.capacity_operations.get("pm-1", "") + await client.aclose() + + +def test_deployed_model_percent_encoded_in_path(): + seen = [] + + def handler(request): + seen.append(request.url.raw_path) + return httpx.Response(200, json=_deployment_output()) + + client = _make_client(handler) + client.deployments.get("pm/a?b#c") + # '/', '?' and '#' stay inside one path segment instead of retargeting + # the request to another path or query. + assert seen == [b"/api/v1/deployments/pm%2Fa%3Fb%23c"] + client.close() + + +def test_capacity_ids_percent_encoded_in_path(): + seen = [] + + def handler(request): + seen.append(request.url.raw_path) + if "capacity-operations" in request.url.path: + return httpx.Response(200, json=_operation_output("SUCCEEDED")) + return httpx.Response(200, json=_instance_output()) + + client = _make_client(handler) + client.deployments.capacity_instances.get("pm/a", "ci/b") + client.deployments.capacity_operations.get("pm/a", "op/b") + assert seen == [ + b"/api/v1/deployments/pm%2Fa/capacity-instances/ci%2Fb", + b"/api/v1/deployments/pm%2Fa/capacity-operations/op%2Fb", + ] + client.close() diff --git a/tests/test_files_models.py b/tests/test_files_models.py index a5941333..eafd8466 100644 --- a/tests/test_files_models.py +++ b/tests/test_files_models.py @@ -327,12 +327,25 @@ async def test_async_files_delete_missing_file_raises_not_found(): def test_models_list_with_provider_filter(): - # ``data``-wrapped pages stay supported for gateways that re-wrap - # the native ``output`` envelope OpenAI-style. + # ``data``-wrapped pages stay supported for gateways that re-wrap the + # native ``output`` envelope OpenAI-style. ``provider`` / ``providers`` + # are sent server-side as a repeated ``providers`` param, and the + # gateway's filtered total drives pagination. + catalog = [ + {"model": "qwen-plus", "provider": "qwen"}, + {"model": "qwen3-max", "provider": "qwen"}, + {"model": "llama-3", "provider": "community"}, + ] captured = {} def handler(request): - captured["params"] = dict(request.url.params) + captured["params"] = request.url.params + providers = request.url.params.get_list("providers") + models = ( + [m for m in catalog if m["provider"] in providers] + if providers + else catalog + ) return httpx.Response( 200, json={ @@ -340,26 +353,231 @@ def handler(request): "data": { "page_no": 1, "page_size": 10, - "total": 3, - "models": [ - {"model": "qwen-plus", "source": "dashscope"}, - {"model": "qwen3-max", "source": "bailian"}, - {"model": "qwen-turbo", "provider": "Community"}, - ], + "total": len(models), + "models": models, }, }, ) client = _make_client(handler) all_models = client.models.list() - assert captured["params"] == {"page_no": "1", "page_size": "10"} + assert dict(captured["params"]) == {"page_no": "1", "page_size": "10"} assert len(all_models.models) == 3 + assert all_models.total_count == 3 + + qwen = client.models.list(provider="qwen") + assert captured["params"].get_list("providers") == ["qwen"] + assert [m.model for m in qwen.models] == ["qwen-plus", "qwen3-max"] + assert qwen.total_count == 2 + + community = client.models.list(providers=["community"]) + assert captured["params"].get_list("providers") == ["community"] + assert [m.model for m in community.models] == ["llama-3"] + + +def test_models_list_array_filters_use_repeated_keys(): + # Array filters serialize as repeated parameter names, not a joined + # string or a bracketed key: capabilities=TG&capabilities=Reasoning. + captured = {} + + def handler(request): + captured["params"] = request.url.params + return httpx.Response( + 200, + json={"request_id": "r", "output": {"models": [], "total": 0}}, + ) + + client = _make_client(handler) + client.models.list( + providers=["qwen", "deepseek"], + inference_providers=["aliyun-bailian"], + capabilities=["TG", "Reasoning"], + features=["function-calling"], + supports=["fine-tune"], + deployment_methods=["ptu"], + deployment_ptu_service_tiers=["standard"], + ) + params = captured["params"] + assert params.get_list("providers") == ["qwen", "deepseek"] + assert params.get_list("inference_providers") == ["aliyun-bailian"] + assert params.get_list("capabilities") == ["TG", "Reasoning"] + assert params.get_list("features") == ["function-calling"] + assert params.get_list("supports") == ["fine-tune"] + assert params.get_list("deployment_methods") == ["ptu"] + assert params.get_list("deployment_ptu_service_tiers") == ["standard"] + + +def test_models_list_scalar_filters_pass_through(): + captured = {} + + def handler(request): + captured["params"] = dict(request.url.params) + return httpx.Response( + 200, + json={"request_id": "r", "output": {"models": [], "total": 0}}, + ) + + client = _make_client(handler) + client.models.list( + name="qwen", + model="qwen-plus", + language="zh", + context_window=131072, + service_site="international", + ) + assert captured["params"] == { + "page_no": "1", + "page_size": "10", + "name": "qwen", + "model": "qwen-plus", + "language": "zh", + "context_window": "131072", + "service_site": "international", + } + + +def test_models_list_provider_merges_into_providers_without_dupes(): + captured = {} + + def handler(request): + captured["params"] = request.url.params + return httpx.Response( + 200, + json={"request_id": "r", "output": {"models": [], "total": 0}}, + ) + + client = _make_client(handler) + client.models.list(provider="qwen", providers=["qwen", "deepseek"]) + assert captured["params"].get_list("providers") == ["qwen", "deepseek"] + + +def test_models_list_parses_rich_metadata(): + body = { + "request_id": "r", + "output": { + "page_no": 1, + "page_size": 10, + "total": 1, + "models": [ + { + "model": "qwen3-max", + "name": "Qwen3-Max", + "description": "flagship", + "capabilities": ["TG", "Reasoning"], + "inference_provider": "aliyun-bailian", + "features": ["function-calling"], + "published_time": "2025-09-01", + "equivalent_snapshot": "qwen3-max-2025-09-01", + "prices": [ + { + "range_name": "Default", + "prices": [ + { + "type": "input", + "price": "0.0008", + "price_unit": "per 1k tokens", + "price_name": "Input", + }, + ], + }, + ], + "inference_metadata": { + "request_modality": ["Text"], + "response_modality": ["Text"], + }, + "model_info": { + "context_window": 262144, + "max_input_tokens": 258048, + "max_output_tokens": 32768, + }, + }, + ], + }, + } + client = _make_client(lambda r: httpx.Response(200, json=body)) + model = client.models.list().models[0] + assert model.name == "Qwen3-Max" + assert model.capabilities == ["TG", "Reasoning"] + assert model.inference_provider == "aliyun-bailian" + assert model.equivalent_snapshot == "qwen3-max-2025-09-01" + assert model.prices[0].range_name == "Default" + assert model.prices[0].prices[0].price == "0.0008" # verbatim string + assert model.inference_metadata.request_modality == ["Text"] + assert model.model_info.context_window == 262144 + assert model.model_info.max_output_tokens == 32768 + + +def test_models_list_pagination_preserves_filters(): + catalog = [{"model": f"m{i}", "provider": "qwen"} for i in range(5)] + seen = [] + + def handler(request): + params = request.url.params + seen.append( + (int(params.get("page_no", 1)), params.get_list("capabilities")), + ) + page_no = int(params.get("page_no", 1)) + page_size = int(params.get("page_size", 10)) + start = (page_no - 1) * page_size + return httpx.Response( + 200, + json={ + "request_id": "r", + "output": { + "models": catalog[start : start + page_size], + "page_no": page_no, + "page_size": page_size, + "total": len(catalog), + }, + }, + ) + + client = _make_client(handler) + page = client.models.list( + page_no=1, + page_size=2, + capabilities=["TG"], + provider="qwen", + ) + collected = [m.model for p in page.iter_pages() for m in p] + assert collected == ["m0", "m1", "m2", "m3", "m4"] + # Every advanced page re-sends the same filters. + assert seen == [(1, ["TG"]), (2, ["TG"]), (3, ["TG"])] + - bailian = client.models.list(provider="Bailian") - assert [m.model for m in bailian.models] == ["qwen3-max"] +@pytest.mark.asyncio +async def test_models_async_list_filters_and_pagination(): + catalog = [{"model": f"m{i}"} for i in range(5)] + seen = [] + + def handler(request): + params = request.url.params + seen.append( + (int(params.get("page_no", 1)), params.get_list("providers")), + ) + page_no = int(params.get("page_no", 1)) + page_size = int(params.get("page_size", 10)) + start = (page_no - 1) * page_size + return httpx.Response( + 200, + json={ + "request_id": "r", + "output": { + "models": catalog[start : start + page_size], + "page_no": page_no, + "page_size": page_size, + "total": len(catalog), + }, + }, + ) - community = client.models.list(provider="community") - assert [m.model for m in community.models] == ["qwen-turbo"] + client = _make_async_client(handler) + page = await client.models.list(page_no=1, page_size=2, provider="qwen") + assert seen[0] == (1, ["qwen"]) + collected = [m.model async for p in page.iter_pages_async() for m in p] + assert collected == ["m0", "m1", "m2", "m3", "m4"] + assert seen == [(1, ["qwen"]), (2, ["qwen"]), (3, ["qwen"])] + await client.aclose() def test_models_list_parses_native_output_envelope(): @@ -422,6 +640,78 @@ def handler(request): assert page.total_count == 2 +def _no_total_handler(catalog, seen=None): + def handler(request): + params = request.url.params + page_no = int(params.get("page_no", 1)) + page_size = int(params.get("page_size", 10)) + if seen is not None: + seen.append(page_no) + start = (page_no - 1) * page_size + return httpx.Response( + 200, + json={ + "request_id": "r", + "output": { + "models": catalog[start : start + page_size], + "page_no": page_no, + "page_size": page_size, + # No ``total``: traversal must continue on full pages. + }, + }, + ) + + return handler + + +def test_models_list_all_without_total_walks_full_pages(): + catalog = [{"model": f"m{i}"} for i in range(5)] + seen = [] + client = _make_client(_no_total_handler(catalog, seen)) + assert [m.model for m in client.models.list_all(page_size=2)] == [ + "m0", + "m1", + "m2", + "m3", + "m4", + ] + # The short third page ends the walk; no fourth request. + assert seen == [1, 2, 3] + client.close() + + +def test_models_list_all_without_total_exact_multiple(): + catalog = [{"model": f"m{i}"} for i in range(4)] + seen = [] + client = _make_client(_no_total_handler(catalog, seen)) + assert [m.model for m in client.models.list_all(page_size=2)] == [ + "m0", + "m1", + "m2", + "m3", + ] + # A full last page cannot be told from a middle one: one extra fetch + # returns the empty page that ends the walk. + assert seen == [1, 2, 3] + client.close() + + +@pytest.mark.asyncio +async def test_models_async_list_all_without_total_walks_full_pages(): + catalog = [{"model": f"m{i}"} for i in range(5)] + seen = [] + client = _make_async_client(_no_total_handler(catalog, seen)) + assert [m.model for m in await client.models.list_all(page_size=2)] == [ + "m0", + "m1", + "m2", + "m3", + "m4", + ] + assert seen == [1, 2, 3] + await client.aclose() + + def test_models_list_parses_a_bare_list_page(): # A page delivered as a bare list carries no ``page_no`` / ``total`` to # read, so it is taken as one whole page. The generic envelope lifter @@ -637,3 +927,307 @@ def handler(request): # The envelope belongs to the response, not to each item inside it. assert page.files[0].request_id is None assert not page.files[0].is_error + + +# --- A2: auto-pagination, availability, region/workspace context --- + + +def _catalog_handler(catalog, seen=None): + def handler(request): + params = request.url.params + page_no = int(params.get("page_no", 1)) + page_size = int(params.get("page_size", 10)) + if seen is not None: + seen.append((page_no, page_size)) + start = (page_no - 1) * page_size + return httpx.Response( + 200, + json={ + "request_id": "r", + "output": { + "models": catalog[start : start + page_size], + "page_no": page_no, + "page_size": page_size, + "total": len(catalog), + }, + }, + ) + + return handler + + +def _one_model_body(extra=None): + item = {"model": "qwen-plus"} + if extra: + item.update(extra) + return { + "request_id": "r", + "output": {"models": [item], "total": 1}, + } + + +def test_models_list_injects_served_region_and_workspace(): + client = _make_client( + lambda r: httpx.Response(200, json=_one_model_body()), + region="ap-southeast-1", + workspace="ws-sg", + ) + m = client.models.list().models[0] + assert m.served_region == "ap-southeast-1" + assert m.workspace == "ws-sg" + assert m.service_site is None + + +def test_models_list_injects_default_region_when_unset(): + client = _make_client( + lambda r: httpx.Response(200, json=_one_model_body()), + ) + m = client.models.list().models[0] + assert m.served_region == "cn-beijing" + assert m.workspace is None + + +def test_models_list_workspace_override_wins_over_config(): + client = _make_client( + lambda r: httpx.Response(200, json=_one_model_body()), + workspace="ws-config", + ) + m = client.models.list(workspace="ws-call").models[0] + assert m.workspace == "ws-call" + + +def test_models_list_service_site_echoes_filter(): + client = _make_client( + lambda r: httpx.Response(200, json=_one_model_body()), + ) + m = client.models.list(service_site="international").models[0] + assert m.service_site == "international" + # served_region is a different dimension, never conflated with the site. + assert m.served_region == "cn-beijing" + + +def test_models_list_wire_service_site_is_not_erased(): + body = _one_model_body({"service_site": "global"}) + client = _make_client(lambda r: httpx.Response(200, json=body)) + # An unfiltered query (None) must not erase a real per-model wire value. + assert client.models.list().models[0].service_site == "global" + # Even a conflicting filter does not override the wire's own value. + assert ( + client.models.list(service_site="international").models[0].service_site + == "global" + ) + + +def test_models_get_injects_context(): + client = _make_client( + lambda r: httpx.Response(200, json=_one_model_body()), + region="eu-central-1", + workspace="ws-eu", + ) + m = client.models.get("qwen-plus") + assert m.served_region == "eu-central-1" + assert m.workspace == "ws-eu" + assert m.service_site is None + + +def test_models_get_not_found_still_injects_context(): + client = _make_client( + lambda r: httpx.Response(200, json={"output": {"models": []}}), + region="cn-beijing", + workspace="ws-bj", + raise_on_error=False, + ) + m = client.models.get("nope") + assert m.model is None + assert m.served_region == "cn-beijing" + assert m.workspace == "ws-bj" + + +def test_models_iter_walks_all_pages_and_preserves_filters(): + catalog = [{"model": f"m{i}"} for i in range(5)] + seen = [] + + def handler(request): + params = request.url.params + seen.append( + ( + int(params.get("page_no", 1)), + params.get_list("capabilities"), + params.get("service_site"), + ), + ) + page_no = int(params.get("page_no", 1)) + page_size = int(params.get("page_size", 10)) + start = (page_no - 1) * page_size + return httpx.Response( + 200, + json={ + "request_id": "r", + "output": { + "models": catalog[start : start + page_size], + "page_no": page_no, + "page_size": page_size, + "total": len(catalog), + }, + }, + ) + + client = _make_client(handler, region="cn-beijing", workspace="ws") + got = list( + client.models.iter( + page_size=2, + capabilities=["TG"], + service_site="international", + ), + ) + assert [m.model for m in got] == ["m0", "m1", "m2", "m3", "m4"] + assert seen == [ + (1, ["TG"], "international"), + (2, ["TG"], "international"), + (3, ["TG"], "international"), + ] + assert all( + m.served_region == "cn-beijing" + and m.workspace == "ws" + and m.service_site == "international" + for m in got + ) + + +def test_models_iter_is_lazy(): + catalog = [{"model": f"m{i}"} for i in range(6)] + seen = [] + client = _make_client(_catalog_handler(catalog, seen)) + it = client.models.iter(page_size=2) + assert next(it).model == "m0" + # Only page 1 is fetched until iteration advances past it. + assert seen == [(1, 2)] + assert next(it).model == "m1" + assert seen == [(1, 2)] + assert next(it).model == "m2" + assert seen == [(1, 2), (2, 2)] + + +def test_models_list_all_collects_every_page(): + catalog = [{"model": f"m{i}"} for i in range(5)] + client = _make_client(_catalog_handler(catalog)) + got = client.models.list_all(page_size=2) + assert isinstance(got, list) + assert [m.model for m in got] == ["m0", "m1", "m2", "m3", "m4"] + + +def test_models_is_available_true_and_queries_current_region(): + seen = {} + + def handler(request): + seen["path"] = request.url.path + seen["model"] = request.url.params.get("model") + seen["page_size"] = request.url.params.get("page_size") + seen["sdk"] = request.headers.get("x-dashscope-sdk-client") + return httpx.Response(200, json=_one_model_body()) + + client = _make_client(handler) + assert client.models.is_available("qwen-plus") is True + assert seen["path"] == "/api/v1/models" + assert seen["model"] == "qwen-plus" + assert seen["page_size"] == "1" + assert seen["sdk"].endswith("/models2") + + +def test_models_is_available_false_when_absent(): + client = _make_client( + lambda r: httpx.Response(200, json={"output": {"models": []}}), + ) + assert client.models.is_available("nope") is False + + +def test_models_is_available_rejects_empty_model(): + client = _make_client( + lambda r: httpx.Response(200, json=_one_model_body()), + ) + with pytest.raises(ValueError): + client.models.is_available("") + with pytest.raises(ValueError): + client.models.is_available(" ") + + +def test_models_is_available_propagates_http_error(): + client = _make_client( + lambda r: httpx.Response( + 400, + json={"code": "InvalidParameter", "message": "bad"}, + ), + ) + with pytest.raises(BadRequestError): + client.models.is_available("qwen-plus") + + +@pytest.mark.asyncio +async def test_async_models_iter_and_list_all(): + catalog = [{"model": f"m{i}"} for i in range(5)] + seen = [] + client = _make_async_client( + _catalog_handler(catalog, seen), + region="ap-southeast-1", + workspace="ws-sg", + ) + got = [m async for m in client.models.iter(page_size=2)] + assert [m.model for m in got] == ["m0", "m1", "m2", "m3", "m4"] + assert all( + m.served_region == "ap-southeast-1" and m.workspace == "ws-sg" + for m in got + ) + collected = await client.models.list_all(page_size=2) + assert [m.model for m in collected] == ["m0", "m1", "m2", "m3", "m4"] + + +@pytest.mark.asyncio +async def test_async_models_is_available(): + present = _make_async_client( + lambda r: httpx.Response(200, json=_one_model_body()), + ) + assert await present.models.is_available("qwen-plus") is True + absent = _make_async_client( + lambda r: httpx.Response(200, json={"output": {"models": []}}), + ) + assert await absent.models.is_available("nope") is False + with pytest.raises(ValueError): + await absent.models.is_available("") + + +@pytest.mark.asyncio +async def test_async_models_list_injects_context(): + client = _make_async_client( + lambda r: httpx.Response(200, json=_one_model_body()), + region="eu-central-1", + workspace="ws-eu", + ) + page = await client.models.list(service_site="international") + m = page.models[0] + assert m.served_region == "eu-central-1" + assert m.workspace == "ws-eu" + assert m.service_site == "international" + + +@pytest.mark.parametrize("model", ["", " "]) +def test_models_get_empty_id_rejected_before_wire(model): + # An empty model filter matches the whole catalog, so get("") would + # silently answer with the first entry instead of failing. + def handler(request): + raise AssertionError("empty model id must not reach the wire") + + client = _make_client(handler) + with pytest.raises(ValueError, match="non-empty model id"): + client.models.get(model) + client.close() + + +@pytest.mark.asyncio +async def test_async_models_get_empty_id_rejected_before_wire(): + def handler(request): + raise AssertionError("empty model id must not reach the wire") + + client = _make_async_client(handler) + with pytest.raises(ValueError, match="non-empty model id"): + await client.models.get("") + await client.aclose() diff --git a/tests/test_finetune_compress.py b/tests/test_finetune_compress.py new file mode 100644 index 00000000..d8e3ba49 --- /dev/null +++ b/tests/test_finetune_compress.py @@ -0,0 +1,659 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Tests for client.fine_tunes.compress (D1: model compression).""" + +# Mock handlers intentionally ignore the request argument. +# pylint: disable=unused-argument + +from __future__ import annotations + +import json + +import httpx +import pytest + +from dashscope import AsyncClient, Client +from dashscope.errors import DashScopeError +from dashscope.resources.fine_tunes_compress import ( + CompressJob, + CompressJobList, + CompressTemplateList, +) + +BASE_URL = "https://api.test.local/api/v1" +JOBS = "/api/v1/fine-tunes/compress/jobs" +TEMPLATES = "/api/v1/fine-tunes/compress/templates" + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +def _job_payload(status, job_id="cj-1"): + return { + "request_id": "req-1", + "output": { + "job_id": job_id, + "job_name": "quant-run", + "status": status, + "model": "qwen3.5-flash-ft", + "base_model": "qwen3.5-flash", + "template_id": "tpl-1", + "template_name": "int4", + "training_type": "quantization", + "compress_type": "quantization", + "hyper_parameters": {"bits": 4}, + "custom_calibration_file_ids": ["file-abc"], + "quantized_output": "qwen3.5-flash-ft-q4-cj-1", + "group": "quantization", + "create_time": "2026-11-17 10:00:00", + }, + } + + +# --- templates.list ------------------------------------------------------- + + +def _templates_payload(): + return { + "request_id": "req-t", + "output": { + "base_models": ["qwen3.5-flash-2026-02-23"], + "custom_models": [ + { + "model": "qwen3.5-flash-2026-02-23-ft-abc", + "model_name": "我的SFT调优模型", + "base_model": "qwen3.5-flash-2026-02-23", + "templates": [ + { + "template_id": "quant-flash-nvfp4-mlp-nomtp", + "template_name": "W4A4 NVFP4高性能压缩", + "description": "更低比特压缩兼顾高精度与高性能。", + "compress_type": "quantization", + "hyper_parameters": [ + { + "name": "calib_input", + "type": "string", + "display_name": "校准输入", + "support_values": ["true"], + "defaultValue": "true", + "required": False, + }, + ], + }, + ], + }, + ], + }, + } + + +def test_templates_list_path_params_and_parse(): + captured = {} + + def handler(request): + captured["method"] = request.method + captured["path"] = request.url.path + captured["params"] = dict(request.url.params) + return httpx.Response(200, json=_templates_payload()) + + client = _make_client(handler) + catalog = client.fine_tunes.compress.templates.list( + model="qwen3.5-flash-2026-02-23", + lang="zh-CN", + ) + assert captured["method"] == "GET" + assert captured["path"] == TEMPLATES + # The catalog endpoint takes only model/lang, no pagination. + assert captured["params"] == { + "model": "qwen3.5-flash-2026-02-23", + "lang": "zh-CN", + } + assert isinstance(catalog, CompressTemplateList) + assert catalog.request_id == "req-t" + assert catalog.base_models == ["qwen3.5-flash-2026-02-23"] + custom = catalog.custom_models[0] + assert custom.model == "qwen3.5-flash-2026-02-23-ft-abc" + assert custom.model_name == "我的SFT调优模型" + assert custom.base_model == "qwen3.5-flash-2026-02-23" + tpl = custom.templates[0] + assert tpl.template_id == "quant-flash-nvfp4-mlp-nomtp" + assert tpl.description == "更低比特压缩兼顾高精度与高性能。" + assert tpl.compress_type == "quantization" + hp = tpl.hyper_parameters[0] + assert hp.name == "calib_input" + assert hp.type == "string" + assert hp.support_values == ["true"] + assert hp.required is False + + +def test_templates_list_omits_unset_params_and_flattens(): + captured = {} + + def handler(request): + captured["params"] = dict(request.url.params) + payload = _templates_payload() + # A second custom model with two templates exercises flattening. + payload["output"]["custom_models"].append( + { + "model": "m2", + "base_model": "qwen3.5-flash-2026-02-23", + "templates": [ + {"template_id": "t2"}, + {"template_id": "t3"}, + ], + }, + ) + return httpx.Response(200, json=payload) + + client = _make_client(handler) + catalog = client.fine_tunes.compress.templates.list() + assert captured["params"] == {} + assert [t.template_id for t in catalog.templates] == [ + "quant-flash-nvfp4-mlp-nomtp", + "t2", + "t3", + ] + + +# --- jobs.create ---------------------------------------------------------- + + +def test_create_builds_wire_body(): + captured = {} + + def handler(request): + captured["method"] = request.method + captured["path"] = request.url.path + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_job_payload("PENDING")) + + client = _make_client(handler) + job = client.fine_tunes.compress.jobs.create( + model="qwen3.5-flash-ft", + template_id="tpl-1", + job_name="quant-run", + job_description="int4 quantization", + hyper_parameters={"bits": 4}, + custom_calibration_file_ids="file-abc", + output_model_suffix="q4", + ) + assert captured["method"] == "POST" + assert captured["path"] == JOBS + body = captured["body"] + assert body["model"] == "qwen3.5-flash-ft" + assert body["template_id"] == "tpl-1" + assert body["job_name"] == "quant-run" + assert body["job_description"] == "int4 quantization" + assert body["hyper_parameters"] == {"bits": 4} + # A bare string is normalized to a one-element list. + assert body["custom_calibration_file_ids"] == ["file-abc"] + assert body["output_model_suffix"] == "q4" + assert job.job_id == "cj-1" + assert job.status == "PENDING" + assert job.request_id == "req-1" + assert job.quantized_output == "qwen3.5-flash-ft-q4-cj-1" + assert job.compress_type == "quantization" + + +def test_create_minimal_body_omits_unset_optionals(): + captured = {} + + def handler(request): + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_job_payload("PENDING")) + + client = _make_client(handler) + client.fine_tunes.compress.jobs.create( + model="qwen3.5-flash-ft", + template_id="tpl-1", + ) + assert captured["body"] == { + "model": "qwen3.5-flash-ft", + "template_id": "tpl-1", + } + + +@pytest.mark.parametrize( + "kwargs", + [ + {"output_model_suffix": "BAD!"}, + {"output_model_suffix": "toolongsuffix"}, + {"output_model_suffix": "Upper"}, + {"job_name": "x" * 51}, + {"job_description": "x" * 201}, + ], +) +def test_create_rejects_invalid_inputs(kwargs): + called = [] + + def handler(request): + called.append(request) + return httpx.Response(200, json=_job_payload("PENDING")) + + client = _make_client(handler) + with pytest.raises(DashScopeError): + client.fine_tunes.compress.jobs.create( + model="qwen3.5-flash-ft", + template_id="tpl-1", + **kwargs, + ) + # Validation happens before any request is sent. + assert called == [] + + +def test_create_accepts_valid_suffix_boundary(): + captured = {} + + def handler(request): + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_job_payload("PENDING")) + + client = _make_client(handler) + client.fine_tunes.compress.jobs.create( + model="m", + template_id="tpl-1", + output_model_suffix="abcd1234", # exactly 8, lowercase + digits + ) + assert captured["body"]["output_model_suffix"] == "abcd1234" + + +# --- jobs.get / list / cancel / delete / logs paths ----------------------- + + +def test_job_lifecycle_paths(): + seen = [] + + def handler(request): + seen.append((request.method, request.url.path)) + if request.method == "GET" and request.url.path.endswith("/logs"): + assert dict(request.url.params) == {"offset": "2", "line": "50"} + return httpx.Response( + 200, + json={"request_id": "req-l", "output": {"logs": ["a", "b"]}}, + ) + if request.method == "GET" and request.url.path.endswith("cj-1"): + return httpx.Response(200, json=_job_payload("RUNNING")) + if request.method == "GET": + return httpx.Response( + 200, + json={ + "request_id": "req-2", + "output": { + "page_no": 1, + "page_size": 10, + "total": 1, + "jobs": [_job_payload("SUCCEEDED")["output"]], + }, + }, + ) + return httpx.Response( + 200, + json={"request_id": "req-3", "output": {"status": "done"}}, + ) + + client = _make_client(handler) + assert client.fine_tunes.compress.jobs.get("cj-1").status == "RUNNING" + listed = client.fine_tunes.compress.jobs.list() + assert isinstance(listed, CompressJobList) + assert listed.total_count == 1 + assert listed.jobs[0].job_id == "cj-1" + logs = client.fine_tunes.compress.jobs.logs("cj-1", offset=2, lines=50) + assert logs.content == "a\nb" + assert logs.job_id == "cj-1" + assert client.fine_tunes.compress.jobs.cancel("cj-1").status == "done" + assert client.fine_tunes.compress.jobs.delete("cj-1").status == "done" + assert seen == [ + ("GET", f"{JOBS}/cj-1"), + ("GET", JOBS), + ("GET", f"{JOBS}/cj-1/logs"), + ("POST", f"{JOBS}/cj-1/cancel"), + ("DELETE", f"{JOBS}/cj-1"), + ] + + +def test_jobs_list_filters_pass_through(): + captured = {} + + def handler(request): + captured["params"] = dict(request.url.params) + return httpx.Response( + 200, + json={"request_id": "r", "output": {"jobs": [], "total": 0}}, + ) + + client = _make_client(handler) + client.fine_tunes.compress.jobs.list( + status="SUCCEEDED", + model="qwen3.5-flash-ft", + template_id="tpl-1", + quant_spec="int4", + quant_method="gptq", + start_time="2026-11-01", + end_time="2026-11-17", + job_name="quant-run", + job_id="cj-1", + search_key="kw", + select_key="sel", + sort_by="create_time", + sort_order="desc", + page_no=2, + page_size=50, + ) + assert captured["params"] == { + "page_no": "2", + "page_size": "50", + "status": "SUCCEEDED", + "model": "qwen3.5-flash-ft", + "template_id": "tpl-1", + "quant_spec": "int4", + "quant_method": "gptq", + "start_time": "2026-11-01", + "end_time": "2026-11-17", + "job_name": "quant-run", + "job_id": "cj-1", + "search_key": "kw", + "select_key": "sel", + "sort_by": "create_time", + "sort_order": "desc", + } + + +def test_jobs_list_pagination_preserves_filters(): + catalog = [{"job_id": f"cj{i}"} for i in range(5)] + seen = [] + + def handler(request): + params = request.url.params + seen.append((int(params.get("page_no", 1)), params.get("status"))) + page_no = int(params.get("page_no", 1)) + page_size = int(params.get("page_size", 10)) + start = (page_no - 1) * page_size + return httpx.Response( + 200, + json={ + "request_id": "r", + "output": { + "jobs": catalog[start : start + page_size], + "page_no": page_no, + "page_size": page_size, + "total": len(catalog), + }, + }, + ) + + client = _make_client(handler) + page = client.fine_tunes.compress.jobs.list( + page_no=1, + page_size=2, + status="SUCCEEDED", + ) + collected = [j.job_id for p in page.iter_pages() for j in p] + assert collected == ["cj0", "cj1", "cj2", "cj3", "cj4"] + assert seen == [(1, "SUCCEEDED"), (2, "SUCCEEDED"), (3, "SUCCEEDED")] + + +def test_job_parses_nested_error_and_usage(): + payload = _job_payload("FAILED") + payload["output"]["error"] = {"code": "InternalError", "message": "boom"} + payload["output"]["usage"] = 120 + client = _make_client(lambda r: httpx.Response(200, json=payload)) + job = client.fine_tunes.compress.jobs.get("cj-1") + assert job.error.code == "InternalError" + assert job.error.message == "boom" + assert job.usage == 120 + assert job.finished is True + assert job.succeeded is False + + +# --- jobs.wait ------------------------------------------------------------ + + +def test_wait_polls_until_terminal(): + statuses = iter(["QUEUING", "RUNNING", "SUCCEEDED"]) + delays = [] + + def handler(request): + return httpx.Response(200, json=_job_payload(next(statuses))) + + client = _make_client(handler) + job = client.fine_tunes.compress.jobs.wait("cj-1", _sleep=delays.append) + assert job.status == "SUCCEEDED" + assert delays == [1.0, 2.0] + + +def test_wait_failed_job_raises_with_nested_error(): + payload = _job_payload("FAILED") + payload["output"]["error"] = { + "code": "InternalError", + "message": "quant crashed", + } + + def handler(request): + return httpx.Response( + 200, + json=payload, + headers={"x-request-id": "req-h"}, + ) + + client = _make_client(handler) + with pytest.raises(DashScopeError) as exc: + client.fine_tunes.compress.jobs.wait("cj-1", _sleep=lambda s: None) + error = exc.value + assert error.code == "InternalError" + assert error.message == "quant crashed" + assert error.headers["x-request-id"] == "req-h" + assert "headers" not in error.body + assert error.body["status"] == "FAILED" + + +def test_wait_canceled_job_raises(): + client = _make_client( + lambda r: httpx.Response(200, json=_job_payload("CANCELED")), + ) + with pytest.raises(DashScopeError, match="canceled"): + client.fine_tunes.compress.jobs.wait("cj-1", _sleep=lambda s: None) + + +def test_wait_returns_error_envelope_in_compat_mode(): + def handler(request): + return httpx.Response( + 401, + json={ + "request_id": "req-x", + "code": "InvalidApiKey", + "message": "bad key", + }, + ) + + client = _make_client(handler, raise_on_error=False) + job = client.fine_tunes.compress.jobs.wait("cj-1", _sleep=lambda s: None) + assert job.is_error is True + assert job.code == "InvalidApiKey" + assert job.request_id == "req-x" + + +def test_wait_accepts_job_object(): + client = _make_client( + lambda r: httpx.Response(200, json=_job_payload("SUCCEEDED")), + ) + job = CompressJob(job_id="cj-1", status="RUNNING") + done = client.fine_tunes.compress.jobs.wait(job, _sleep=lambda s: None) + assert done.status == "SUCCEEDED" + + +# --- raw escape hatch ----------------------------------------------------- + + +def test_raw_returns_api_response(): + client = _make_client( + lambda r: httpx.Response(200, json=_job_payload("RUNNING")), + ) + resp = client.fine_tunes.compress.jobs.get("cj-1", raw=True) + assert resp.http_response.status_code == 200 + assert resp.json()["output"]["job_id"] == "cj-1" + + +# --- async symmetry ------------------------------------------------------- + + +@pytest.mark.asyncio +async def test_async_create_get_and_templates(): + seen = [] + + def handler(request): + seen.append((request.method, request.url.path)) + if request.url.path == TEMPLATES: + return httpx.Response(200, json=_templates_payload()) + if request.method == "POST": + return httpx.Response(200, json=_job_payload("PENDING")) + return httpx.Response(200, json=_job_payload("SUCCEEDED")) + + client = _make_async_client(handler) + job = await client.fine_tunes.compress.jobs.create( + model="qwen3.5-flash-ft", + template_id="tpl-1", + output_model_suffix="q4", + ) + assert job.job_id == "cj-1" + fetched = await client.fine_tunes.compress.jobs.get("cj-1") + assert fetched.status == "SUCCEEDED" + catalog = await client.fine_tunes.compress.templates.list() + assert catalog.custom_models[0].templates[0].template_id == ( + "quant-flash-nvfp4-mlp-nomtp" + ) + assert seen == [ + ("POST", JOBS), + ("GET", f"{JOBS}/cj-1"), + ("GET", TEMPLATES), + ] + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_list_pagination_preserves_filters(): + catalog = [{"job_id": f"cj{i}"} for i in range(5)] + seen = [] + + def handler(request): + params = request.url.params + seen.append((int(params.get("page_no", 1)), params.get("status"))) + page_no = int(params.get("page_no", 1)) + page_size = int(params.get("page_size", 10)) + start = (page_no - 1) * page_size + return httpx.Response( + 200, + json={ + "request_id": "r", + "output": { + "jobs": catalog[start : start + page_size], + "page_no": page_no, + "page_size": page_size, + "total": len(catalog), + }, + }, + ) + + client = _make_async_client(handler) + page = await client.fine_tunes.compress.jobs.list( + page_no=1, + page_size=2, + status="SUCCEEDED", + ) + collected = [j.job_id async for p in page.iter_pages_async() for j in p] + assert collected == ["cj0", "cj1", "cj2", "cj3", "cj4"] + assert seen == [(1, "SUCCEEDED"), (2, "SUCCEEDED"), (3, "SUCCEEDED")] + await client.aclose() + + +@pytest.mark.asyncio +async def test_async_wait_polls_until_terminal(): + statuses = iter(["RUNNING", "SUCCEEDED"]) + delays = [] + + async def fake_sleep(seconds): + delays.append(seconds) + + def handler(request): + return httpx.Response(200, json=_job_payload(next(statuses))) + + client = _make_async_client(handler) + job = await client.fine_tunes.compress.jobs.wait( + "cj-1", + _sleep=fake_sleep, + ) + assert job.status == "SUCCEEDED" + assert delays == [1.0] + await client.aclose() + + +# --- retry policy + job id guards ------------------------------------------ + + +def test_create_default_no_retry(): + attempts = [] + + def handler(request): + attempts.append(1) + return httpx.Response(503, json={"message": "busy"}) + + client = _make_client(handler) + with pytest.raises(DashScopeError): + client.fine_tunes.compress.jobs.create( + model="qwen3.5-flash-ft", + template_id="tpl-1", + ) + # No idempotency key on the wire -> create must not auto-retry. + assert len(attempts) == 1 + client.close() + + +@pytest.mark.asyncio +async def test_async_create_default_no_retry(): + attempts = [] + + def handler(request): + attempts.append(1) + return httpx.Response(503, json={"message": "busy"}) + + client = _make_async_client(handler) + with pytest.raises(DashScopeError): + await client.fine_tunes.compress.jobs.create( + model="qwen3.5-flash-ft", + template_id="tpl-1", + ) + assert len(attempts) == 1 + await client.aclose() + + +@pytest.mark.parametrize("op", ["get", "cancel", "delete", "logs"]) +def test_empty_job_id_rejected_before_wire(op): + def handler(request): + raise AssertionError("empty job id must not reach the wire") + + client = _make_client(handler) + with pytest.raises(DashScopeError, match="job id required"): + getattr(client.fine_tunes.compress.jobs, op)("") + client.close() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("op", ["get", "cancel", "delete", "logs"]) +async def test_async_empty_job_id_rejected_before_wire(op): + def handler(request): + raise AssertionError("empty job id must not reach the wire") + + client = _make_async_client(handler) + with pytest.raises(DashScopeError, match="job id required"): + await getattr(client.fine_tunes.compress.jobs, op)("") + await client.aclose() diff --git a/tests/test_messages.py b/tests/test_messages.py new file mode 100644 index 00000000..38c5a50a --- /dev/null +++ b/tests/test_messages.py @@ -0,0 +1,1334 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Tests for client.messages (C3: native Anthropic Messages + stream). + +Native Anthropic wire at {base}/apps/anthropic/v1/messages (base does not +end in /v1, protocol-independent), returning AnthropicMessage with typed +content blocks -- distinct from the protocol="anthropic" chat adapter. +C3-specific coverage: temperature [0,2), output_config / cache_control / +thinking first-class, thinking.budget_tokens deprecation, server-tool +billing-header auto-injection (and override), document/video/thinking +input blocks, the native content-block union (thinking/server_tool_use/ +web_search_tool_result/web_fetch_tool_result), cache + server-tool usage, +SSE accumulation (text/thinking/tool-input JSON/server-tool results) and +raw/stream overloads. Mirrors test_responses.py conventions. +""" + +# Mock handlers intentionally ignore the request argument; pytest fixture +# injection looks like unused/redefined names to pylint. +# pylint: disable=unused-argument,redefined-outer-name + +from __future__ import annotations + +import json + +import httpx +import pytest + +from dashscope import AsyncClient, Client +from dashscope.errors import ( + APIResponseValidationError, + BadRequestError, + DashScopeError, +) +from dashscope.protocols.anthropic import WEB_SEARCH_BILLING_HEADER +from dashscope.transport._ident import sdk_client_value +from dashscope.types import AnthropicMessage + +BASE_URL = "https://api.test.local/apps/anthropic" +_WS_HOST = "https://ws-123.cn-beijing.maas.aliyuncs.com" +_MESSAGES_PATH = "/apps/anthropic/v1/messages" + +_MESSAGE_BODY = { + "id": "msg_1", + "type": "message", + "role": "assistant", + "model": "qwen4-max", + "content": [{"type": "text", "text": "Hello"}], + "stop_reason": "end_turn", + "stop_sequence": None, + "usage": { + "input_tokens": 10, + "output_tokens": 5, + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 0, + }, +} + +_USER_MESSAGES = [{"role": "user", "content": "hi"}] + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +def _sse(frames): + return "".join( + f"id: {i}\ndata: {json.dumps(f)}\n\n" for i, f in enumerate(frames, 1) + ) + + +@pytest.fixture +def clean_env(monkeypatch): + from dashscope._config import settings + + for name in ( + "DASHSCOPE_API_KEY", + "DASHSCOPE_BASE_URL", + "DASHSCOPE_HTTP_BASE_URL", + "DASHSCOPE_WORKSPACE", + "DASHSCOPE_REGION", + "DASHSCOPE_PROTOCOL", + "DASHSCOPE_CONFIG", + ): + monkeypatch.delenv(name, raising=False) + settings.clear() + yield monkeypatch + settings.clear() + + +def _ok_handler(captured=None): + def handler(request): + if captured is not None: + captured["method"] = request.method + captured["path"] = request.url.path + captured["headers"] = dict(request.headers) + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_MESSAGE_BODY) + + return handler + + +# -------------------------------------------------------------------------- +# create: wire body, headers, parse +# -------------------------------------------------------------------------- + + +def test_create_wire_body_and_parse(): + captured = {} + client = _make_client(_ok_handler(captured)) + msg = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert captured["method"] == "POST" + assert captured["path"] == _MESSAGES_PATH + assert captured["body"] == { + "model": "qwen4-max", + "max_tokens": 1024, + "messages": _USER_MESSAGES, + "stream": False, + } + assert captured["headers"]["anthropic-version"] == "2023-06-01" + assert isinstance(msg, AnthropicMessage) + assert msg.id == "msg_1" + assert msg.text == "Hello" + assert msg.stop_reason == "end_turn" + assert msg.usage.input_tokens == 10 + client.close() + + +def test_sdk_module_header(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert captured["headers"]["x-dashscope-sdk-client"] == sdk_client_value( + "messages", + ) + assert captured["headers"]["x-dashscope-sdk-client"].endswith("/messages2") + client.close() + + +def test_system_string_passthrough(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + system="You are helpful", + ) + assert captured["body"]["system"] == "You are helpful" + client.close() + + +def test_system_blocks_with_cache_control(): + captured = {} + client = _make_client(_ok_handler(captured)) + system = [ + { + "type": "text", + "text": "repo", + "cache_control": {"type": "ephemeral"}, + }, + ] + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + system=system, + ) + assert captured["body"]["system"] == system + client.close() + + +def test_top_level_cache_control_first_class(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + cache_control={"type": "ephemeral", "ttl": "1h"}, + ) + assert captured["body"]["cache_control"] == { + "type": "ephemeral", + "ttl": "1h", + } + client.close() + + +def test_output_config_effort_and_format(): + captured = {} + client = _make_client(_ok_handler(captured)) + fmt = { + "type": "json_schema", + "schema": { + "type": "object", + "properties": {"name": {"type": "string"}}, + "required": ["name"], + "additionalProperties": False, + }, + } + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + output_config={"effort": "high", "format": fmt}, + ) + assert captured["body"]["output_config"] == { + "effort": "high", + "format": fmt, + } + client.close() + + +def test_thinking_type_and_display(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + thinking={"type": "enabled", "display": "summarized"}, + ) + assert captured["body"]["thinking"] == { + "type": "enabled", + "display": "summarized", + } + client.close() + + +def test_thinking_budget_tokens_deprecation(): + client = _make_client(_ok_handler()) + with pytest.warns(DeprecationWarning, match="budget_tokens"): + client.messages.create( + model="qwen4-max", + max_tokens=2048, + messages=_USER_MESSAGES, + thinking={"type": "enabled", "budget_tokens": 1024}, + ) + client.close() + + +def test_sampling_params_and_stop_sequences(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + temperature=1.5, + top_p=0.8, + top_k=20, + stop_sequences=["STOP"], + ) + body = captured["body"] + assert body["temperature"] == 1.5 + assert body["top_p"] == 0.8 + assert body["top_k"] == 20 + assert body["stop_sequences"] == ["STOP"] + client.close() + + +@pytest.mark.parametrize("temperature", [-0.1, 2, 2.5, 3, 100]) +def test_temperature_out_of_range_rejected(temperature): + client = _make_client(_ok_handler()) + with pytest.raises(ValueError, match=r"\[0, 2\)"): + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + temperature=temperature, + ) + client.close() + + +def test_temperature_upper_bound_exclusive(): + # 1.999... is valid; the official Anthropic [0,1] clamp must not apply. + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + temperature=1.99, + ) + assert captured["body"]["temperature"] == 1.99 + client.close() + + +def test_function_tools_and_tool_choice(): + captured = {} + client = _make_client(_ok_handler(captured)) + tools = [ + { + "name": "get_weather", + "description": "weather", + "input_schema": { + "type": "object", + "properties": {"city": {"type": "string"}}, + "required": ["city"], + }, + }, + ] + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + tools=tools, + tool_choice={"type": "tool", "name": "get_weather"}, + ) + assert captured["body"]["tools"] == tools + assert captured["body"]["tool_choice"] == { + "type": "tool", + "name": "get_weather", + } + client.close() + + +def test_tool_choice_string_normalized(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + tool_choice="any", + ) + assert captured["body"]["tool_choice"] == {"type": "any"} + client.close() + + +# -------------------------------------------------------------------------- +# server tools + billing-header injection +# -------------------------------------------------------------------------- + + +def test_web_search_injects_billing_header_into_string_system(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + system="You are helpful", + tools=[ + { + "type": "web_search_20250305", + "name": "web_search", + "max_uses": 8, + }, + ], + ) + system = captured["body"]["system"] + assert isinstance(system, list) + assert system[0] == {"type": "text", "text": "You are helpful"} + assert system[-1] == {"type": "text", "text": WEB_SEARCH_BILLING_HEADER} + client.close() + + +def test_web_search_injects_billing_header_when_no_system(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + tools=[{"type": "web_search_20250305", "name": "web_search"}], + ) + assert captured["body"]["system"] == [ + {"type": "text", "text": WEB_SEARCH_BILLING_HEADER}, + ] + client.close() + + +def test_web_search_caller_marker_wins(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + system=[{"type": "text", "text": WEB_SEARCH_BILLING_HEADER}], + tools=[{"type": "web_search_20250305", "name": "web_search"}], + ) + assert len(captured["body"]["system"]) == 1 + client.close() + + +def test_web_fetch_with_web_search_injects_once(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + tools=[ + {"type": "web_search_20250305", "name": "web_search"}, + {"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 3}, + ], + ) + system = captured["body"]["system"] + assert sum(WEB_SEARCH_BILLING_HEADER in b["text"] for b in system) == 1 + client.close() + + +def test_custom_function_named_web_search_not_injected(): + captured = {} + client = _make_client(_ok_handler(captured)) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + system="plain", + tools=[ + { + "name": "web_search", + "input_schema": {"type": "object", "properties": {}}, + }, + ], + ) + # No web_search_* server type -> no injection, system stays a string. + assert captured["body"]["system"] == "plain" + client.close() + + +# -------------------------------------------------------------------------- +# multimodal / thinking / tool input blocks passthrough +# -------------------------------------------------------------------------- + + +def test_multimodal_input_blocks_passthrough(): + captured = {} + client = _make_client(_ok_handler(captured)) + messages = [ + { + "role": "user", + "content": [ + { + "type": "image", + "source": {"type": "url", "url": "https://x/a.jpg"}, + }, + { + "type": "video", + "source": {"type": "url", "url": "https://x/a.mp4"}, + }, + { + "type": "document", + "source": { + "type": "base64", + "media_type": "application/pdf", + "data": "BASE64", + }, + }, + {"type": "text", "text": "describe"}, + ], + }, + ] + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=messages, + ) + assert captured["body"]["messages"] == messages + client.close() + + +def test_thinking_and_tool_blocks_passthrough(): + captured = {} + client = _make_client(_ok_handler(captured)) + messages = [ + { + "role": "assistant", + "content": [ + { + "type": "thinking", + "thinking": "summary", + "signature": "cipher", + }, + { + "type": "tool_use", + "id": "toolu_1", + "name": "get_weather", + "input": {"city": "Hangzhou"}, + }, + ], + }, + { + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_use_id": "toolu_1", + "content": "sunny", + }, + ], + }, + ] + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=messages, + ) + assert captured["body"]["messages"] == messages + client.close() + + +# -------------------------------------------------------------------------- +# validation +# -------------------------------------------------------------------------- + + +def test_empty_model_rejected(): + client = _make_client(_ok_handler()) + with pytest.raises(ValueError, match="model"): + client.messages.create( + model=" ", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + client.close() + + +@pytest.mark.parametrize("max_tokens", [0, -1, None]) +def test_invalid_max_tokens_rejected(max_tokens): + client = _make_client(_ok_handler()) + with pytest.raises(ValueError, match="max_tokens"): + client.messages.create( + model="qwen4-max", + max_tokens=max_tokens, + messages=_USER_MESSAGES, + ) + client.close() + + +def test_empty_messages_rejected(): + client = _make_client(_ok_handler()) + with pytest.raises(ValueError, match="messages"): + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=[], + ) + client.close() + + +# -------------------------------------------------------------------------- +# response parsing: native block union + usage +# -------------------------------------------------------------------------- + + +def test_parse_thinking_and_server_tool_blocks(): + body = { + "id": "msg_2", + "type": "message", + "role": "assistant", + "model": "qwen4-max", + "content": [ + {"type": "thinking", "thinking": "reason", "signature": "sig"}, + { + "type": "server_tool_use", + "id": "srvtoolu_1", + "name": "web_search", + "input": {"queries": ["杭州天气"]}, + "caller": {"type": "direct"}, + }, + { + "type": "web_search_tool_result", + "tool_use_id": "srvtoolu_1", + "content": [ + { + "type": "web_search_result", + "title": "T", + "url": "https://x", + "encrypted_content": "enc", + "page_age": None, + }, + ], + }, + { + "type": "web_fetch_tool_result", + "tool_use_id": "srvtoolu_2", + "content": { + "type": "web_fetch_result", + "url": "https://y", + "retrieved_at": "2026-11-18", + "content": { + "type": "document", + "title": "Doc", + "source": { + "type": "text", + "media_type": "text/plain", + "data": "body", + }, + }, + }, + }, + {"type": "text", "text": "answer"}, + ], + "stop_reason": "end_turn", + "stop_sequence": None, + "usage": { + "input_tokens": 100, + "output_tokens": 20, + "cache_creation_input_tokens": 5, + "cache_read_input_tokens": 7, + "server_tool_use": { + "web_search_requests": 1, + "web_fetch_requests": 1, + }, + "cache_creation": { + "ephemeral_5m_input_tokens": 5, + "ephemeral_1h_input_tokens": 0, + }, + "prompt_tokens_details": {"cached_tokens": 7}, + }, + } + + def handler(request): + return httpx.Response(200, json=body) + + client = _make_client(handler) + msg = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert msg.text == "answer" + assert msg.content[0].thinking == "reason" + assert msg.content[0].signature == "sig" + assert msg.content[1].input == {"queries": ["杭州天气"]} + results = msg.content[2].search_results + assert results[0].title == "T" + assert results[0].url == "https://x" + assert msg.content[3].content["type"] == "web_fetch_result" + assert msg.usage.server_tool_use.web_search_requests == 1 + assert msg.usage.cache_read_input_tokens == 7 + assert msg.usage.cache_creation.ephemeral_5m_input_tokens == 5 + assert msg.usage.prompt_tokens_details["cached_tokens"] == 7 + client.close() + + +# -------------------------------------------------------------------------- +# errors +# -------------------------------------------------------------------------- + + +def test_http_error_anthropic_nested_raises(): + def handler(request): + return httpx.Response( + 400, + json={ + "type": "error", + "error": { + "type": "invalid_request_error", + "message": "max_tokens too large", + }, + }, + ) + + client = _make_client(handler) + with pytest.raises(BadRequestError) as ei: + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert ei.value.code == "invalid_request_error" + assert "max_tokens too large" in ei.value.message + client.close() + + +def test_http_error_non_raising_envelope(): + def handler(request): + return httpx.Response( + 404, + json={ + "type": "error", + "error": {"type": "not_found_error", "message": "no model"}, + }, + ) + + client = _make_client(handler, raise_on_error=False) + msg = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert msg.is_error is True + assert msg.code == "not_found_error" + assert msg.status_code == 404 + client.close() + + +def test_business_code_on_http_200(): + def handler(request): + return httpx.Response( + 200, + json={"code": "InvalidParameter", "message": "boom"}, + ) + + client = _make_client(handler, raise_on_error=False) + msg = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert msg.is_error is True + assert msg.code == "InvalidParameter" + client.close() + + +def test_raw_returns_apiresponse_before_error_check(): + def handler(request): + return httpx.Response(400, json={"error": {"message": "bad"}}) + + client = _make_client(handler) + raw = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + raw=True, + ) + assert raw.status_code == 400 + assert raw.json()["error"]["message"] == "bad" + client.close() + + +def test_raw_with_stream_raises(): + client = _make_client(_ok_handler()) + with pytest.raises(ValueError, match="raw=True"): + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + raw=True, + ) + client.close() + + +# -------------------------------------------------------------------------- +# routing +# -------------------------------------------------------------------------- + + +@pytest.mark.parametrize("protocol", ["native", "openai", "anthropic"]) +def test_routing_default_gateway_ignores_chat_protocol(clean_env, protocol): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_MESSAGE_BODY) + + http_client = httpx.Client( + transport=httpx.MockTransport(handler), + base_url=_WS_HOST + "/api/v1", + ) + client = Client( + api_key="sk-test", + workspace="ws-123", + protocol=protocol, + http_client=http_client, + ) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert urls == [_WS_HOST + _MESSAGES_PATH], protocol + client.close() + + +def test_routing_explicit_base_url(): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_MESSAGE_BODY) + + client = _make_client(handler) + client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert urls == [BASE_URL + "/v1/messages"] + client.close() + + +# -------------------------------------------------------------------------- +# streaming +# -------------------------------------------------------------------------- + +_STREAM_FRAMES = [ + { + "type": "message_start", + "message": { + "id": "msg_s", + "type": "message", + "role": "assistant", + "model": "qwen4-max", + "content": [], + "usage": {"input_tokens": 15, "output_tokens": 0}, + }, + }, + { + "type": "content_block_start", + "index": 0, + "content_block": {"type": "thinking", "thinking": "", "signature": ""}, + }, + { + "type": "content_block_delta", + "index": 0, + "delta": {"type": "thinking_delta", "thinking": "Let me think"}, + }, + { + "type": "content_block_delta", + "index": 0, + "delta": {"type": "signature_delta", "signature": "sig-abc"}, + }, + {"type": "content_block_stop", "index": 0}, + { + "type": "content_block_start", + "index": 1, + "content_block": {"type": "text", "text": ""}, + }, + { + "type": "content_block_delta", + "index": 1, + "delta": {"type": "text_delta", "text": "Hel"}, + }, + { + "type": "content_block_delta", + "index": 1, + "delta": {"type": "text_delta", "text": "lo"}, + }, + {"type": "content_block_stop", "index": 1}, + { + "type": "message_delta", + "delta": {"stop_reason": "end_turn", "stop_sequence": None}, + "usage": { + "input_tokens": 15, + "output_tokens": 1078, + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 0, + }, + }, + {"type": "message_stop"}, +] + + +def _stream_handler(frames=None): + def handler(request): + return httpx.Response( + 200, + content=_sse(frames if frames is not None else _STREAM_FRAMES), + headers={ + "content-type": "text/event-stream", + "x-request-id": "rid-stream", + }, + ) + + return handler + + +def test_stream_iterates_events_and_text_stream(): + client = _make_client(_stream_handler()) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + events = list(stream) + assert events[0].type == "message_start" + assert events[-1].type == "message_stop" + assert stream.headers["x-request-id"] == "rid-stream" + client.close() + + client = _make_client(_stream_handler()) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + assert "".join(stream.text_stream) == "Hello" + client.close() + + +def test_stream_thinking_stream(): + client = _make_client(_stream_handler()) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + assert "".join(stream.thinking_stream) == "Let me think" + client.close() + + +def test_stream_get_final_message_accumulates(): + client = _make_client(_stream_handler()) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + final = stream.get_final_message() + assert isinstance(final, AnthropicMessage) + assert final.id == "msg_s" + assert final.text == "Hello" + assert final.content[0].thinking == "Let me think" + assert final.content[0].signature == "sig-abc" + assert final.stop_reason == "end_turn" + assert final.usage.output_tokens == 1078 + assert final.headers["x-request-id"] == "rid-stream" + client.close() + + +_PARTIAL_USAGE_FRAMES = [ + { + "type": "message_start", + "message": { + "id": "msg_p", + "type": "message", + "role": "assistant", + "model": "qwen4-max", + "content": [], + "usage": { + "input_tokens": 15, + "output_tokens": 0, + "cache_read_input_tokens": 7, + }, + }, + }, + { + "type": "content_block_start", + "index": 0, + "content_block": {"type": "text", "text": ""}, + }, + { + "type": "content_block_delta", + "index": 0, + "delta": {"type": "text_delta", "text": "Hi"}, + }, + {"type": "content_block_stop", "index": 0}, + { + "type": "message_delta", + "delta": {"stop_reason": "end_turn", "stop_sequence": None}, + # Spec-conformant delta usage carries only output_tokens. + "usage": {"output_tokens": 42}, + }, + {"type": "message_stop"}, +] + + +def test_stream_partial_delta_usage_keeps_start_counters(): + client = _make_client(_stream_handler(_PARTIAL_USAGE_FRAMES)) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + final = stream.get_final_message() + assert final.usage.input_tokens == 15 + assert final.usage.cache_read_input_tokens == 7 + assert final.usage.output_tokens == 42 + client.close() + + +_DRIFT_STOP_FRAMES = [ + { + "type": "message_start", + "message": { + "id": "msg_d", + "type": "message", + "role": "assistant", + "model": "qwen4-max", + "content": [], + "usage": {"input_tokens": 1, "output_tokens": 0}, + }, + }, + { + "type": "message_delta", + # stop_reason drifts to an int: event parsing stays tolerant, the + # final aggregation must honor the client's strict_validation. + "delta": {"stop_reason": 123, "stop_sequence": None}, + "usage": {"output_tokens": 2}, + }, + {"type": "message_stop"}, +] + + +def test_stream_final_message_honors_strict_validation(): + client = _make_client( + _stream_handler(_DRIFT_STOP_FRAMES), + strict_validation=True, + ) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + with pytest.raises(APIResponseValidationError): + stream.get_final_message() + client.close() + + # Tolerant default: the drifted field degrades instead of raising. + client = _make_client(_stream_handler(_DRIFT_STOP_FRAMES)) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + final = stream.get_final_message() + assert final.id == "msg_d" + client.close() + + +async def test_async_stream_final_message_honors_strict_validation(): + client = _make_async_client( + _stream_handler(_DRIFT_STOP_FRAMES), + strict_validation=True, + ) + stream = await client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + with pytest.raises(APIResponseValidationError): + await stream.get_final_message() + await client.aclose() + + +def test_stream_get_final_message_tool_input_json(): + frames = [ + { + "type": "message_start", + "message": { + "id": "msg_t", + "type": "message", + "role": "assistant", + "model": "qwen4-max", + "content": [], + "usage": {"input_tokens": 5, "output_tokens": 0}, + }, + }, + { + "type": "content_block_start", + "index": 0, + "content_block": { + "type": "tool_use", + "id": "toolu_1", + "name": "get_weather", + "input": {}, + }, + }, + { + "type": "content_block_delta", + "index": 0, + "delta": {"type": "input_json_delta", "partial_json": '{"city":'}, + }, + { + "type": "content_block_delta", + "index": 0, + "delta": { + "type": "input_json_delta", + "partial_json": '"Hangzhou"}', + }, + }, + {"type": "content_block_stop", "index": 0}, + { + "type": "message_delta", + "delta": {"stop_reason": "tool_use", "stop_sequence": None}, + "usage": {"input_tokens": 5, "output_tokens": 20}, + }, + {"type": "message_stop"}, + ] + client = _make_client(_stream_handler(frames)) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + final = stream.get_final_message() + assert final.content[0].type == "tool_use" + assert final.content[0].name == "get_weather" + assert final.content[0].input == {"city": "Hangzhou"} + assert final.stop_reason == "tool_use" + client.close() + + +def test_stream_get_final_message_server_tool_result(): + frames = [ + { + "type": "message_start", + "message": { + "id": "msg_w", + "type": "message", + "role": "assistant", + "model": "qwen4-max", + "content": [], + "usage": {"input_tokens": 5, "output_tokens": 0}, + }, + }, + { + "type": "content_block_start", + "index": 0, + "content_block": { + "type": "server_tool_use", + "id": "srvtoolu_1", + "name": "web_search", + "input": {"queries": ["杭州天气"]}, + "caller": {"type": "direct"}, + }, + }, + {"type": "content_block_stop", "index": 0}, + { + "type": "content_block_start", + "index": 1, + "content_block": { + "type": "web_search_tool_result", + "tool_use_id": "srvtoolu_1", + "content": [ + { + "type": "web_search_result", + "title": "T", + "url": "https://x", + "encrypted_content": "enc", + "page_age": None, + }, + ], + }, + }, + {"type": "content_block_stop", "index": 1}, + { + "type": "message_delta", + "delta": {"stop_reason": "end_turn", "stop_sequence": None}, + "usage": { + "input_tokens": 5, + "output_tokens": 10, + "server_tool_use": {"web_search_requests": 1}, + }, + }, + {"type": "message_stop"}, + ] + client = _make_client(_stream_handler(frames)) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + final = stream.get_final_message() + # server_tool_use input must survive (complete in start, not wiped). + assert final.content[0].input == {"queries": ["杭州天气"]} + assert final.content[1].search_results[0].title == "T" + assert final.usage.server_tool_use.web_search_requests == 1 + client.close() + + +def test_stream_without_message_stop_raises(): + client = _make_client(_stream_handler(_STREAM_FRAMES[:-1])) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + with pytest.raises(DashScopeError, match="message_stop"): + stream.get_final_message() + client.close() + + +def test_stream_in_stream_error_raises(): + frames = [ + _STREAM_FRAMES[0], + {"error": {"code": "InvalidParameter", "message": "boom"}}, + ] + client = _make_client(_stream_handler(frames)) + stream = client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + with pytest.raises(BadRequestError) as ei: + list(stream) + assert ei.value.code == "InvalidParameter" + client.close() + + +# -------------------------------------------------------------------------- +# async symmetry +# -------------------------------------------------------------------------- + + +async def test_async_create_wire_and_parse(): + captured = {} + client = _make_async_client(_ok_handler(captured)) + msg = await client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert captured["path"] == _MESSAGES_PATH + assert msg.text == "Hello" + await client.aclose() + + +async def test_async_billing_header_injection(): + captured = {} + client = _make_async_client(_ok_handler(captured)) + await client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + tools=[{"type": "web_search_20250305", "name": "web_search"}], + ) + assert captured["body"]["system"] == [ + {"type": "text", "text": WEB_SEARCH_BILLING_HEADER}, + ] + await client.aclose() + + +async def test_async_error_non_raising_envelope(): + def handler(request): + return httpx.Response( + 400, + json={ + "type": "error", + "error": {"type": "invalid_request_error", "message": "bad"}, + }, + ) + + client = _make_async_client(handler, raise_on_error=False) + msg = await client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert msg.is_error is True + assert msg.code == "invalid_request_error" + await client.aclose() + + +async def test_async_stream_text_and_final_message(): + client = _make_async_client(_stream_handler()) + stream = await client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + chunks = [chunk async for chunk in stream.text_stream] + assert "".join(chunks) == "Hello" + await client.aclose() + + client = _make_async_client(_stream_handler()) + stream = await client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + final = await stream.get_final_message() + assert final.text == "Hello" + assert final.usage.output_tokens == 1078 + await client.aclose() + + +async def test_async_stream_partial_delta_usage_keeps_start_counters(): + client = _make_async_client(_stream_handler(_PARTIAL_USAGE_FRAMES)) + stream = await client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + stream=True, + ) + final = await stream.get_final_message() + assert final.usage.input_tokens == 15 + assert final.usage.cache_read_input_tokens == 7 + assert final.usage.output_tokens == 42 + await client.aclose() + + +async def test_async_routing_ignores_chat_protocol(clean_env): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_MESSAGE_BODY) + + http_client = httpx.AsyncClient( + transport=httpx.MockTransport(handler), + base_url=_WS_HOST + "/api/v1", + ) + client = AsyncClient( + api_key="sk-test", + workspace="ws-123", + protocol="openai", + http_client=http_client, + ) + await client.messages.create( + model="qwen4-max", + max_tokens=1024, + messages=_USER_MESSAGES, + ) + assert urls == [_WS_HOST + _MESSAGES_PATH] + await client.aclose() diff --git a/tests/test_model_cache.py b/tests/test_model_cache.py new file mode 100644 index 00000000..811826c5 --- /dev/null +++ b/tests/test_model_cache.py @@ -0,0 +1,557 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Region-aware model catalog cache (A4 Part 2). + +Covers the key helpers and ``_CatalogCache`` directly, then the wiring +through ``Models`` / ``AsyncModels``: hits, ``refresh``, key isolation, +``raw``/error bypass, the shared get/is_available read, pagination refresh, +non-aliasing and a thread-safety smoke. +""" + +from __future__ import annotations + +import threading + +import httpx +import pytest + +from dashscope import AsyncClient, Client +from dashscope.errors import DashScopeError +from dashscope.resources import _model_cache as mc +from dashscope.resources._model_cache import ( + _CatalogCache, + catalog_key, + credential_fingerprint, + normalize_params, +) + +BASE_URL = "https://api.test.local/api/v1" + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +def _page(models, total=None, page_no=1, page_size=10): + return httpx.Response( + 200, + json={ + "request_id": "r", + "output": { + "models": models, + "total": len(models) if total is None else total, + "page_no": page_no, + "page_size": page_size, + }, + }, + ) + + +class _Cfg: + """Stand-in for the frozen client Config in key-helper unit tests.""" + + def __init__(self, region="cn-beijing", workspace="ws-1", api_key="sk-1"): + self.region = region + self.workspace = workspace + self.api_key = api_key + + +class TestKeyHelpers: + def test_normalize_params_is_order_independent_and_hashable(self): + a = normalize_params({"b": 2, "a": ["x", "y"]}) + b = normalize_params({"a": ("x", "y"), "b": 2}) + assert a == b == (("a", ("x", "y")), ("b", 2)) + assert hash(a) == hash(b) + + def test_credential_fingerprint_hides_the_key(self): + fp = credential_fingerprint("sk-secret") + assert "sk-secret" not in fp + assert len(fp) == 16 + assert fp == credential_fingerprint("sk-secret") + assert fp != credential_fingerprint("sk-other") + assert credential_fingerprint(None) == credential_fingerprint("") + + def test_catalog_key_isolates_every_dimension(self): + cfg = _Cfg() + params = {"model": "qwen-plus", "page_no": 1, "page_size": 1} + base = catalog_key(cfg, params, api_key=None, workspace=None) + assert ( + catalog_key( + _Cfg(region="ap-southeast-1"), + params, + api_key=None, + workspace=None, + ) + != base + ) + assert catalog_key(cfg, params, api_key=None, workspace="ws-2") != base + assert catalog_key(cfg, params, api_key="sk-2", workspace=None) != base + assert ( + catalog_key( + cfg, + {**params, "page_no": 2}, + api_key=None, + workspace=None, + ) + != base + ) + + def test_catalog_key_resolves_overrides_against_config(self): + cfg = _Cfg() + params = {"page_no": 1, "page_size": 10} + # Per-call values equal to the config resolve to the same key. + assert catalog_key( + cfg, + params, + api_key="sk-1", + workspace="ws-1", + ) == catalog_key(cfg, params, api_key=None, workspace=None) + + +class TestCatalogCache: + def test_hit_then_ttl_expiry(self, monkeypatch): + now = [1000.0] + monkeypatch.setattr(mc.time, "monotonic", lambda: now[0]) + cache = _CatalogCache(ttl=60.0) + sentinel = object() + cache.set("k", sentinel) + assert cache.get("k") is sentinel + now[0] += 59.0 + assert cache.get("k") is sentinel + now[0] += 2.0 + assert cache.get("k") is None + assert "k" not in cache._entries + + def test_miss_on_unknown_key(self): + assert _CatalogCache().get("absent") is None + + def test_eviction_drops_the_oldest_at_the_cap(self, monkeypatch): + now = [0.0] + monkeypatch.setattr(mc.time, "monotonic", lambda: now[0]) + cache = _CatalogCache(ttl=1000.0) + for i in range(mc._MAX_ENTRIES + 1): + now[0] = float(i) + cache.set(("k", i), object()) + assert len(cache._entries) == mc._MAX_ENTRIES + assert cache.get(("k", 0)) is None + assert cache.get(("k", mc._MAX_ENTRIES)) is not None + + def test_resetting_a_key_does_not_evict(self, monkeypatch): + now = [0.0] + monkeypatch.setattr(mc.time, "monotonic", lambda: now[0]) + cache = _CatalogCache(ttl=1000.0) + for i in range(mc._MAX_ENTRIES): + now[0] = float(i) + cache.set(("k", i), object()) + now[0] = 9999.0 + cache.set(("k", 0), object()) # refresh existing, not a new entry + assert len(cache._entries) == mc._MAX_ENTRIES + assert cache.get(("k", 0)) is not None + + +class TestSyncCache: + def test_same_params_hits_cache(self): + calls = [] + + def handler(request): + calls.append(dict(request.url.params)) + return _page([{"model": "qwen-plus"}]) + + client = _make_client(handler) + a = client.models.list() + b = client.models.list() + assert len(calls) == 1 + assert [m.model for m in a.models] == ["qwen-plus"] + assert [m.model for m in b.models] == ["qwen-plus"] + assert a is not b + + def test_refresh_bypasses_and_updates_cache(self): + calls = [] + + def handler(request): + calls.append(1) + return _page([{"model": f"m{len(calls)}"}]) + + client = _make_client(handler) + assert client.models.list().models[0].model == "m1" + assert client.models.list().models[0].model == "m1" # hit + assert len(calls) == 1 + assert client.models.list(refresh=True).models[0].model == "m2" + assert len(calls) == 2 + assert client.models.list().models[0].model == "m2" # updated hit + assert len(calls) == 2 + + def test_key_isolation_per_call_overrides(self): + calls = [] + + def handler(request): + calls.append(dict(request.url.params)) + return _page([{"model": "qwen-plus"}]) + + client = _make_client(handler) + client.models.list() # 1: base + client.models.list() # hit + client.models.list(workspace="ws-2") # 2 + client.models.list(api_key="sk-other") # 3 + client.models.list(provider="qwen") # 4 + client.models.list(page_no=2) # 5 + client.models.list(service_site="intl") # 6 + assert len(calls) == 6 + + def test_extra_query_bypasses_cache(self): + calls = [] + + def handler(request): + calls.append(dict(request.url.params)) + return _page([{"model": f"m{len(calls)}"}]) + + client = _make_client(handler) + client.models.list() # 1: cached + client.models.list() # hit + assert len(calls) == 1 + # extra_query changes the effective query: no stale page-1 hit. + result = client.models.list(extra_query={"page_no": 2}) + assert len(calls) == 2 + assert calls[-1]["page_no"] == "2" + assert result.models[0].model == "m2" + # ...and the bypassed read must not pollute the plain entry. + assert client.models.list().models[0].model == "m1" + assert len(calls) == 2 + + def test_extra_headers_bypasses_cache(self): + calls = [] + + def handler(request): + calls.append(request.headers.get("x-dashscope-workspace")) + return _page([{"model": f"m{len(calls)}"}]) + + client = _make_client(handler, workspace="ws-a") + client.models.list() # 1: cached under ws-a + client.models.list() # hit + assert len(calls) == 1 + # A workspace header override must not read ws-a's entry. + result = client.models.list( + extra_headers={"X-DashScope-WorkSpace": "ws-b"}, + ) + assert len(calls) == 2 + assert calls[-1] == "ws-b" + assert result.models[0].model == "m2" + assert client.models.list().models[0].model == "m1" + assert len(calls) == 2 + + def test_raw_bypasses_cache(self): + calls = [] + + def handler(request): + calls.append(1) + return _page([{"model": "qwen-plus"}]) + + client = _make_client(handler) + r1 = client.models.list(raw=True) + client.models.list(raw=True) + assert r1.status_code == 200 + assert len(calls) == 2 # raw never caches + client.models.list() # non-raw still has to fetch + assert len(calls) == 3 + client.models.list() # now cached + assert len(calls) == 3 + + def test_error_is_not_cached(self): + calls = [] + + def handler(request): + calls.append(1) + if len(calls) == 1: + return httpx.Response(500, json={"message": "boom"}) + return _page([{"model": "qwen-plus"}]) + + client = _make_client(handler) + with pytest.raises(DashScopeError): + client.models.list(max_retries=0) + assert len(calls) == 1 + # The failure was not cached: the retry reaches the network again. + assert client.models.list(max_retries=0).models[0].model == "qwen-plus" + assert len(calls) == 2 + client.models.list(max_retries=0) # success now cached + assert len(calls) == 2 + + def test_business_error_in_non_raising_mode_is_not_cached(self): + calls = [] + + def handler(request): + calls.append(1) + if len(calls) == 1: + return httpx.Response( + 200, + json={"code": "InternalError", "message": "boom"}, + ) + return _page([{"model": "qwen-plus"}]) + + client = _make_client(handler, raise_on_error=False) + first = client.models.list(max_retries=0) + assert first.code == "InternalError" + second = client.models.list(max_retries=0) + assert [m.model for m in second.models] == ["qwen-plus"] + assert len(calls) == 2 + + def test_get_and_is_available_share_the_read(self): + calls = [] + + def handler(request): + calls.append(dict(request.url.params)) + return _page([{"model": "qwen-plus"}], total=1) + + client = _make_client(handler) + model = client.models.get("qwen-plus") + assert model.model == "qwen-plus" + assert client.models.is_available("qwen-plus") is True + assert len(calls) == 1 # same query, one fetch + client.models.get("qwen-plus") + assert len(calls) == 1 + # A different model is a different key. + assert client.models.is_available("qwen-max") is True + assert len(calls) == 2 + + def test_cache_hit_returns_fresh_objects(self): + def handler(request): + return _page([{"model": "qwen-plus"}]) + + client = _make_client(handler) + a = client.models.list() + b = client.models.list() + assert a is not b + assert a.models is not b.models + assert a.models[0] is not b.models[0] + assert b.models[0].model == "qwen-plus" + + def test_iter_refresh_refetches_every_page(self): + catalog = [{"model": "m1"}, {"model": "m2"}] + calls = [] + + def handler(request): + page_no = int(request.url.params.get("page_no", 1)) + page_size = int(request.url.params.get("page_size", 10)) + calls.append(page_no) + start = (page_no - 1) * page_size + return _page( + catalog[start : start + page_size], + total=len(catalog), + page_no=page_no, + page_size=page_size, + ) + + client = _make_client(handler) + assert [m.model for m in client.models.list_all(page_size=1)] == [ + "m1", + "m2", + ] + assert calls == [1, 2] + client.models.list_all(page_size=1) # both pages cached + assert calls == [1, 2] + client.models.list_all(page_size=1, refresh=True) + assert calls == [1, 2, 1, 2] + + def test_disabled_ttl_never_hits(self): + calls = [] + + def handler(request): + calls.append(1) + return _page([{"model": "qwen-plus"}]) + + client = _make_client(handler) + client.models._catalog_cache = _CatalogCache(ttl=0.0) + client.models.list() + client.models.list() + assert len(calls) == 2 + + def test_concurrent_reads_of_a_warm_key_do_not_refetch(self): + calls = [] + + def handler(request): + calls.append(1) + return _page([{"model": "qwen-plus"}]) + + client = _make_client(handler) + client.models.list() # warm the cache + assert len(calls) == 1 + errors = [] + + def worker(): + try: + for _ in range(20): + result = client.models.list() + assert result.models[0].model == "qwen-plus" + except Exception as exc: # pylint: disable=broad-except + errors.append(exc) + + threads = [threading.Thread(target=worker) for _ in range(8)] + for t in threads: + t.start() + for t in threads: + t.join() + assert not errors + assert len(calls) == 1 # every concurrent read was a hit + + +class TestAsyncCache: + @pytest.mark.asyncio + async def test_same_params_hits_cache(self): + calls = [] + + async def handler(request): + calls.append(1) + return _page([{"model": "qwen-plus"}]) + + client = _make_async_client(handler) + a = await client.models.list() + b = await client.models.list() + assert len(calls) == 1 + assert a is not b + assert [m.model for m in b.models] == ["qwen-plus"] + await client.aclose() + + @pytest.mark.asyncio + async def test_refresh_bypasses_and_updates_cache(self): + calls = [] + + async def handler(request): + calls.append(1) + return _page([{"model": f"m{len(calls)}"}]) + + client = _make_async_client(handler) + assert (await client.models.list()).models[0].model == "m1" + assert (await client.models.list()).models[0].model == "m1" + assert len(calls) == 1 + fresh = await client.models.list(refresh=True) + assert fresh.models[0].model == "m2" + assert len(calls) == 2 + assert (await client.models.list()).models[0].model == "m2" + assert len(calls) == 2 + await client.aclose() + + @pytest.mark.asyncio + async def test_extra_query_bypasses_cache(self): + calls = [] + + async def handler(request): + calls.append(dict(request.url.params)) + return _page([{"model": f"m{len(calls)}"}]) + + client = _make_async_client(handler) + await client.models.list() + await client.models.list() + assert len(calls) == 1 + result = await client.models.list(extra_query={"page_no": 2}) + assert len(calls) == 2 + assert calls[-1]["page_no"] == "2" + assert result.models[0].model == "m2" + assert (await client.models.list()).models[0].model == "m1" + assert len(calls) == 2 + await client.aclose() + + @pytest.mark.asyncio + async def test_extra_headers_bypasses_cache(self): + calls = [] + + async def handler(request): + calls.append(request.headers.get("x-dashscope-workspace")) + return _page([{"model": f"m{len(calls)}"}]) + + client = _make_async_client(handler, workspace="ws-a") + await client.models.list() + await client.models.list() + assert len(calls) == 1 + result = await client.models.list( + extra_headers={"X-DashScope-WorkSpace": "ws-b"}, + ) + assert len(calls) == 2 + assert calls[-1] == "ws-b" + assert result.models[0].model == "m2" + assert (await client.models.list()).models[0].model == "m1" + assert len(calls) == 2 + await client.aclose() + + @pytest.mark.asyncio + async def test_raw_bypasses_cache(self): + calls = [] + + async def handler(request): + calls.append(1) + return _page([{"model": "qwen-plus"}]) + + client = _make_async_client(handler) + await client.models.list(raw=True) + await client.models.list(raw=True) + assert len(calls) == 2 + await client.models.list() + assert len(calls) == 3 + await client.aclose() + + @pytest.mark.asyncio + async def test_error_is_not_cached(self): + calls = [] + + async def handler(request): + calls.append(1) + if len(calls) == 1: + return httpx.Response(500, json={"message": "boom"}) + return _page([{"model": "qwen-plus"}]) + + client = _make_async_client(handler) + with pytest.raises(DashScopeError): + await client.models.list(max_retries=0) + result = await client.models.list(max_retries=0) + assert result.models[0].model == "qwen-plus" + assert len(calls) == 2 + await client.aclose() + + @pytest.mark.asyncio + async def test_get_and_is_available_share_the_read(self): + calls = [] + + async def handler(request): + calls.append(1) + return _page([{"model": "qwen-plus"}], total=1) + + client = _make_async_client(handler) + assert (await client.models.get("qwen-plus")).model == "qwen-plus" + assert await client.models.is_available("qwen-plus") is True + assert len(calls) == 1 + await client.aclose() + + @pytest.mark.asyncio + async def test_iter_refresh_refetches_every_page(self): + catalog = [{"model": "m1"}, {"model": "m2"}] + calls = [] + + async def handler(request): + page_no = int(request.url.params.get("page_no", 1)) + page_size = int(request.url.params.get("page_size", 10)) + calls.append(page_no) + start = (page_no - 1) * page_size + return _page( + catalog[start : start + page_size], + total=len(catalog), + page_no=page_no, + page_size=page_size, + ) + + client = _make_async_client(handler) + first = await client.models.list_all(page_size=1) + assert [m.model for m in first] == ["m1", "m2"] + assert calls == [1, 2] + await client.models.list_all(page_size=1) + assert calls == [1, 2] + await client.models.list_all(page_size=1, refresh=True) + assert calls == [1, 2, 1, 2] + await client.aclose() diff --git a/tests/test_model_limits_permissions.py b/tests/test_model_limits_permissions.py new file mode 100644 index 00000000..b2fdf629 --- /dev/null +++ b/tests/test_model_limits_permissions.py @@ -0,0 +1,443 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Tests for the read-only models.limits / models.permissions sub-resources (A3). + +Wire contract verified against the official Bailian docs: +- 查询模型限额 GET /api/v1/models/limits -> output.quotas[] +- 查询模型授权 GET /api/v1/models/permissions -> output.permissions[] +Both are API-Key Bearer endpoints under the models path, paginated with the +same output.total/page_no/page_size envelope as the catalog. There is no public +model-versions endpoint, so A3 exposes only limits and permissions. +""" + +from __future__ import annotations + +from typing import Any, Dict, List + +import httpx +import pytest + +from dashscope import AsyncClient, Client +from dashscope.errors import NotFoundError +from dashscope.resources.models import ( + ModelPermission, + ModelQuota, + PermissionList, + QuotaList, +) +from dashscope.types.pagination import BasePage + +BASE_URL = "https://api.test.local/api/v1" + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +def _slice_page( + catalog: List[Dict[str, Any]], + key: str, + params: Dict[str, str], +) -> Dict[str, Any]: + page_no = int(params.get("page_no", 1)) + page_size = int(params.get("page_size", 20)) + start = (page_no - 1) * page_size + return { + "code": None, + "message": None, + "success": True, + "request_id": "req-meta", + "output": { + key: catalog[start : start + page_size], + "page_no": page_no, + "page_size": page_size, + "total": len(catalog), + }, + } + + +def _quota(model: str, **limits: Any) -> Dict[str, Any]: + return { + "model": model, + "workspace_id": "llm-ws1", + "model_limit": limits or None, + "workspace_limit": None, + } + + +# --- models.limits (sync) ------------------------------------------------- + + +def _limits_handler(catalog, seen): + def handler(request): + assert request.url.path == "/api/v1/models/limits" + seen.append(dict(request.url.params)) + seen[-1]["sdk"] = request.headers.get("x-dashscope-sdk-client") + return httpx.Response( + 200, + json=_slice_page(catalog, "quotas", dict(request.url.params)), + ) + + return handler + + +def test_limits_list_parses_quota_fields(): + catalog = [ + _quota( + "qwen-plus", + request_limit=500, + request_limit_period=1, + usage_limit=500000, + usage_limit_field="total_tokens", + usage_limit_period=6, + ), + ] + seen: List[Any] = [] + client = _make_client(_limits_handler(catalog, seen)) + + page = client.models.limits.list(page_no=1, page_size=20) + assert isinstance(page, QuotaList) + assert page.total_count == 1 + assert page.request_id == "req-meta" + quota = page.quotas[0] + assert isinstance(quota, ModelQuota) + assert quota.model == "qwen-plus" + assert quota.workspace_id == "llm-ws1" + assert quota.model_limit.request_limit == 500 + assert quota.model_limit.request_limit_period == 1 + assert quota.model_limit.usage_limit == 500000 + assert quota.model_limit.usage_limit_field == "total_tokens" + assert quota.workspace_limit is None + # Functional-area ident is the models module, path is the limits sub-path. + assert seen[0]["sdk"].endswith("/models2") + + +def test_limits_list_sends_name_and_model_filters(): + seen: List[Any] = [] + client = _make_client(_limits_handler([_quota("qwen-plus")], seen)) + client.models.limits.list(name="qwen", model="qwen-plus") + assert seen[0]["name"] == "qwen" + assert seen[0]["model"] == "qwen-plus" + + +def test_limits_iter_pages_crosses_all_pages_and_keeps_filters(): + catalog = [_quota(f"m{i}") for i in range(5)] + seen: List[Any] = [] + client = _make_client(_limits_handler(catalog, seen)) + + page = client.models.limits.list(page_no=1, page_size=2, model="m") + collected = [q.model for p in page.iter_pages() for q in p] + assert collected == ["m0", "m1", "m2", "m3", "m4"] + assert [int(s["page_no"]) for s in seen] == [1, 2, 3] + # The filter survives traversal: every fetched page carries model. + assert all(s["model"] == "m" for s in seen) + + +def test_limits_iter_pages_without_total_walks_full_pages(): + catalog = [_quota(f"m{i}") for i in range(5)] + seen: List[Any] = [] + + def handler(request): + seen.append(dict(request.url.params)) + body = _slice_page(catalog, "quotas", dict(request.url.params)) + del body["output"]["total"] + return httpx.Response(200, json=body) + + client = _make_client(handler) + page = client.models.limits.list(page_no=1, page_size=2) + collected = [q.model for p in page.iter_pages() for q in p] + assert collected == ["m0", "m1", "m2", "m3", "m4"] + assert [int(s["page_no"]) for s in seen] == [1, 2, 3] + + +def test_limits_null_model_limit_is_preserved(): + catalog = [ + { + "model": "wan-i2v", + "workspace_id": "llm-ws1", + "model_limit": None, + "workspace_limit": { + "request_limit": 5, + "request_limit_period": 1, + "async_user_queue_limit": 500, + "async_user_concurrency_limit": 5, + }, + }, + ] + client = _make_client(_limits_handler(catalog, [])) + quota = client.models.limits.list().quotas[0] + assert quota.model_limit is None + assert quota.workspace_limit.async_user_queue_limit == 500 + assert quota.workspace_limit.async_user_concurrency_limit == 5 + + +def test_limits_get_returns_single_quota_with_envelope(): + catalog = [_quota("qwen-plus", request_limit=2, request_limit_period=60)] + + def handler(request): + params = dict(request.url.params) + assert params["model"] == "qwen-plus" + assert params["page_size"] == "1" + return httpx.Response( + 200, + json=_slice_page(catalog, "quotas", params), + ) + + client = _make_client(handler) + quota = client.models.limits.get("qwen-plus") + assert isinstance(quota, ModelQuota) + assert quota.model == "qwen-plus" + assert quota.request_id == "req-meta" + assert quota.model_limit.request_limit == 2 + + +def test_limits_get_not_found_raises(): + client = _make_client(_limits_handler([], [])) + with pytest.raises(NotFoundError, match="not found"): + client.models.limits.get("absent-model") + + +def test_limits_get_not_found_compat_returns_empty_envelope(): + client = _make_client(_limits_handler([], []), raise_on_error=False) + quota = client.models.limits.get("absent-model") + assert quota.model is None + assert quota.request_id == "req-meta" + assert quota.is_error is False + + +def test_limits_raw_returns_response(): + client = _make_client(_limits_handler([_quota("m0")], [])) + resp = client.models.limits.list(raw=True) + assert resp.http_response.status_code == 200 + assert "quotas" in resp.json()["output"] + + +def test_limits_model_dump_excludes_callback(): + client = _make_client(_limits_handler([_quota("m0")], [])) + page = client.models.limits.list() + dumped = page.model_dump() + assert "_fetch_next" not in dumped + assert not any(k.startswith("_") for k in dumped) + assert "quotas" in dumped and "total_count" in dumped + + +# --- models.permissions (sync) -------------------------------------------- + + +def _permission(model: str, name: str, **flags: Any) -> Dict[str, Any]: + return { + "model": model, + "name": name, + "permissions": { + "inference": flags.get("inference", True), + "fine_tune": flags.get("fine_tune", False), + "deploy": flags.get("deploy", False), + }, + } + + +def _permissions_handler(catalog, seen): + def handler(request): + assert request.url.path == "/api/v1/models/permissions" + params = dict(request.url.params) + params["sdk"] = request.headers.get("x-dashscope-sdk-client") + seen.append(params) + scope = params.get("authorization_scope", "AUTHORIZABLE") + # AUTHORIZED narrows to models whose inference flag is granted. + filtered = ( + [p for p in catalog if p["permissions"]["inference"]] + if scope == "AUTHORIZED" + else catalog + ) + return httpx.Response( + 200, + json=_slice_page(filtered, "permissions", params), + ) + + return handler + + +def test_permissions_list_parses_flags(): + catalog = [_permission("qwen-plus", "通义千问-Plus", inference=True)] + seen: List[Any] = [] + client = _make_client(_permissions_handler(catalog, seen)) + + page = client.models.permissions.list() + assert isinstance(page, PermissionList) + assert page.total_count == 1 + perm = page.permissions[0] + assert isinstance(perm, ModelPermission) + assert perm.model == "qwen-plus" + assert perm.name == "通义千问-Plus" + assert perm.permissions.inference is True + assert perm.permissions.fine_tune is False + assert perm.permissions.deploy is False + assert seen[0]["sdk"].endswith("/models2") + + +def test_permissions_scope_and_action_are_sent_and_preserved(): + catalog = [ + _permission("a", "A", inference=True), + _permission("b", "B", inference=False), + ] + seen: List[Any] = [] + client = _make_client(_permissions_handler(catalog, seen)) + + page = client.models.permissions.list( + page_no=1, + page_size=1, + authorization_scope="AUTHORIZED", + action="INFERENCE", + ) + # Server-side filter: only the authorized model counts toward the total. + assert page.total_count == 1 + collected = [p.model for pg in page.iter_pages() for p in pg] + assert collected == ["a"] + assert all(s["authorization_scope"] == "AUTHORIZED" for s in seen) + assert all(s["action"] == "INFERENCE" for s in seen) + + +def test_permissions_get_authorized_scope(): + catalog = [_permission("qwen-plus", "Plus", inference=True)] + + def handler(request): + params = dict(request.url.params) + assert params["model"] == "qwen-plus" + assert params["authorization_scope"] == "AUTHORIZED" + return httpx.Response( + 200, + json=_slice_page(catalog, "permissions", params), + ) + + client = _make_client(handler) + perm = client.models.permissions.get( + "qwen-plus", + authorization_scope="AUTHORIZED", + ) + assert perm.model == "qwen-plus" + assert perm.permissions.inference is True + assert perm.request_id == "req-meta" + + +def test_permissions_get_not_found_raises(): + client = _make_client(_permissions_handler([], [])) + with pytest.raises(NotFoundError, match="not found"): + client.models.permissions.get("absent-model") + + +def test_permissions_get_not_found_compat_returns_empty_envelope(): + client = _make_client( + _permissions_handler([], []), + raise_on_error=False, + ) + perm = client.models.permissions.get("absent-model") + assert perm.model is None + assert perm.permissions is None + assert perm.request_id == "req-meta" + + +def test_permissions_raw_returns_response(): + client = _make_client(_permissions_handler([_permission("a", "A")], [])) + resp = client.models.permissions.list(raw=True) + assert resp.http_response.status_code == 200 + assert "permissions" in resp.json()["output"] + + +# --- shared BasePage integration ------------------------------------------ + + +def test_meta_lists_share_base_page_and_total_alias(): + for cls in (QuotaList, PermissionList): + assert issubclass(cls, BasePage) + assert cls.model_validate({"total": 7}).total_count == 7 + assert BasePage().items == [] + + +def test_meta_page_without_callback_cannot_advance(): + page = QuotaList(page_no=1, page_size=2, total_count=5) + assert page.has_next_page() is True + assert page.next_page() is None + + +# --- async ---------------------------------------------------------------- + + +@pytest.mark.asyncio +async def test_limits_async_list_and_iter_pages(): + catalog = [_quota(f"m{i}") for i in range(5)] + seen: List[Any] = [] + client = _make_async_client(_limits_handler(catalog, seen)) + + page = await client.models.limits.list(page_no=1, page_size=2) + collected = [q.model async for p in page.iter_pages_async() for q in p] + assert collected == ["m0", "m1", "m2", "m3", "m4"] + assert [int(s["page_no"]) for s in seen] == [1, 2, 3] + + +@pytest.mark.asyncio +async def test_limits_async_get(): + catalog = [_quota("qwen-plus", request_limit=2)] + client = _make_async_client(_limits_handler(catalog, [])) + quota = await client.models.limits.get("qwen-plus") + assert quota.model == "qwen-plus" + assert quota.request_id == "req-meta" + + +@pytest.mark.asyncio +async def test_permissions_async_list_and_get(): + catalog = [_permission("a", "A", inference=True)] + seen: List[Any] = [] + client = _make_async_client(_permissions_handler(catalog, seen)) + + page = await client.models.permissions.list( + authorization_scope="AUTHORIZED", + ) + assert [p.model async for p in page] == ["a"] + perm = await client.models.permissions.get("a") + assert perm.permissions.inference is True + + +@pytest.mark.asyncio +async def test_async_meta_page_rejects_sync_traversal(): + catalog = [_quota(f"m{i}") for i in range(5)] + client = _make_async_client(_limits_handler(catalog, [])) + page = await client.models.limits.list(page_no=1, page_size=2) + with pytest.raises(TypeError, match="iter_pages_async"): + list(page.iter_pages()) + + +# --- empty-id guards ------------------------------------------------------- + + +@pytest.mark.parametrize("model", ["", " "]) +@pytest.mark.parametrize("sub", ["limits", "permissions"]) +def test_meta_get_empty_id_rejected_before_wire(sub, model): + # An empty model filter matches the whole catalog, so get("") would + # silently answer with the first entry instead of failing. + def handler(request): + raise AssertionError("empty model id must not reach the wire") + + client = _make_client(handler) + with pytest.raises(ValueError, match="non-empty model id"): + getattr(client.models, sub).get(model) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("sub", ["limits", "permissions"]) +async def test_async_meta_get_empty_id_rejected_before_wire(sub): + def handler(request): + raise AssertionError("empty model id must not reach the wire") + + client = _make_async_client(handler) + with pytest.raises(ValueError, match="non-empty model id"): + await getattr(client.models, sub).get("") diff --git a/tests/test_pagination.py b/tests/test_pagination.py index 40aca409..9c177a59 100644 --- a/tests/test_pagination.py +++ b/tests/test_pagination.py @@ -139,23 +139,42 @@ def test_models_boundary_empty_catalog(): assert seen == [1] -def test_models_provider_filter_applies_per_page_only(): - # total_count stays the pre-filter catalog total; the filter narrows only - # the items on each fetched page. +def test_models_provider_filter_is_server_side(): + # ``provider`` folds into the server-side ``providers`` filter: the gateway + # returns only matching models and a total_count of the *filtered* set, so + # pagination walks the filtered catalog instead of slicing each page + # client-side (which left total_count pre-filter and hid other-page matches). catalog = [ {"model": "a", "provider": "dashscope"}, {"model": "b", "provider": "other"}, {"model": "c", "provider": "dashscope"}, {"model": "d", "provider": "other"}, ] - client = _make_client(_models_handler(catalog, [])) + seen_providers: List[Any] = [] - page = client.models.list(page_no=1, page_size=2, provider="dashscope") - assert page.total_count == 4 # unfiltered + def handler(request): + providers = request.url.params.get_list("providers") + seen_providers.append(providers) + filtered = ( + [m for m in catalog if m["provider"] in providers] + if providers + else catalog + ) + params = dict(request.url.params) + return httpx.Response( + 200, + json=_slice_page(filtered, "models", params, envelope="output"), + ) + + client = _make_client(handler) + page = client.models.list(page_no=1, page_size=1, provider="dashscope") + assert page.total_count == 2 # filtered total, not the catalog's 4 assert [m.model for m in page] == ["a"] all_filtered = [m.model for p in page.iter_pages() for m in p] assert all_filtered == ["a", "c"] + # The filter survives traversal: every fetched page carries providers. + assert seen_providers == [["dashscope"], ["dashscope"]] def test_model_dump_excludes_callback(): @@ -178,6 +197,21 @@ def test_model_dump_excludes_callback(): "source": None, "provider": None, "open_source": None, + "name": None, + "description": None, + "capabilities": [], + "inference_provider": None, + "features": [], + "prices": [], + "published_time": None, + "inference_metadata": None, + "model_info": None, + "equivalent_snapshot": None, + # SDK-injected query context (A2): default region, no workspace, + # unfiltered service_site. + "served_region": "cn-beijing", + "workspace": None, + "service_site": None, }, ] diff --git a/tests/test_region_router.py b/tests/test_region_router.py new file mode 100644 index 00000000..25a614a1 --- /dev/null +++ b/tests/test_region_router.py @@ -0,0 +1,312 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Explicit cross-Region model discovery router (A5). + +The router is disabled by default and requires an explicit +``allow_cross_region=True`` opt-in that warns cross-border data compliance +is the user's sole responsibility. +""" + +from __future__ import annotations + +import httpx +import pytest + +from dashscope import ( + AsyncClient, + AsyncRegionRouter, + Client, + ModelAvailability, + RegionModelInfo, + RegionRouter, +) + +BASE_URL = "https://api.test.local/api/v1" + + +def _router(clients): + with pytest.warns(UserWarning, match="sole responsibility"): + return RegionRouter(clients=clients, allow_cross_region=True) + + +def _async_router(clients): + with pytest.warns(UserWarning, match="sole responsibility"): + return AsyncRegionRouter(clients=clients, allow_cross_region=True) + + +def _catalog_handler(catalog, calls): + def handler(request): + model = request.url.params.get("model") + calls.append(model) + models = ( + [m for m in catalog if m["model"] == model] if model else catalog + ) + return httpx.Response( + 200, + json={ + "request_id": "r", + "output": { + "models": models, + "total": len(models), + "page_no": 1, + "page_size": 1, + }, + }, + ) + + return handler + + +def _region_client(region, catalog, calls, **kwargs): + handler = _catalog_handler(catalog, calls) + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + return Client( + api_key="sk-test", + region=region, + workspace=f"ws-{region}", + base_url=BASE_URL, + http_client=http_client, + **kwargs, + ) + + +def _async_region_client(region, catalog, calls, **kwargs): + handler = _catalog_handler(catalog, calls) + + async def async_handler(request): + return handler(request) + + mock = httpx.MockTransport(async_handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + return AsyncClient( + api_key="sk-test", + region=region, + workspace=f"ws-{region}", + base_url=BASE_URL, + http_client=http_client, + **kwargs, + ) + + +BJ = [{"model": "qwen-plus"}, {"model": "qwen-max"}] +SG = [{"model": "qwen-max"}] + + +class TestOptIn: + def test_disabled_by_default(self): + client = _region_client("cn-beijing", BJ, []) + with pytest.raises(ValueError, match="disabled by default"): + RegionRouter(clients={"cn-beijing": client}) + + def test_async_disabled_by_default(self): + client = _async_region_client("cn-beijing", BJ, []) + with pytest.raises(ValueError, match="disabled by default"): + AsyncRegionRouter(clients={"cn-beijing": client}) + + def test_default_off_message_states_compliance(self): + with pytest.raises(ValueError, match="sole responsibility"): + RegionRouter(clients={}) + + def test_enabling_warns_compliance(self): + client = _region_client("cn-beijing", BJ, []) + with pytest.warns(UserWarning, match="sole responsibility"): + RegionRouter( + clients={"cn-beijing": client}, + allow_cross_region=True, + ) + + def test_async_enabling_warns_compliance(self): + client = _async_region_client("cn-beijing", BJ, []) + with pytest.warns(UserWarning, match="sole responsibility"): + AsyncRegionRouter( + clients={"cn-beijing": client}, + allow_cross_region=True, + ) + + +class TestValidation: + def test_empty_clients_rejected(self): + with pytest.raises(ValueError, match="at least one"): + _router({}) + + def test_unsafe_region_label_rejected(self): + client = _region_client("cn-beijing", BJ, []) + with pytest.raises(ValueError, match="invalid region label"): + _router({"cn-beijing.evil": client}) + + def test_wrong_client_type_rejected(self): + with pytest.raises(TypeError, match="must be a Client"): + _router({"cn-beijing": object()}) + + def test_key_must_match_client_region(self): + client = _region_client("cn-beijing", BJ, []) + with pytest.raises(ValueError, match="must match the client's"): + _router({"ap-southeast-1": client}) + + def test_async_router_requires_async_clients(self): + sync = _region_client("cn-beijing", BJ, []) + with pytest.raises(TypeError, match="must be a AsyncClient"): + _async_router({"cn-beijing": sync}) + + def test_valid_construction(self): + router = _router( + { + "cn-beijing": _region_client("cn-beijing", BJ, []), + "ap-southeast-1": _region_client("ap-southeast-1", SG, []), + }, + ) + assert callable(router.models.available_regions) + + +class TestSyncDiscovery: + def test_available_in_only_matching_regions(self): + bj_calls, sg_calls = [], [] + router = _router( + { + "cn-beijing": _region_client("cn-beijing", BJ, bj_calls), + "ap-southeast-1": _region_client( + "ap-southeast-1", + SG, + sg_calls, + ), + }, + ) + result = router.models.available_regions("qwen-plus") + assert isinstance(result, ModelAvailability) + assert result.model == "qwen-plus" + assert result.available_in == ["cn-beijing"] + bj = result.regions["cn-beijing"] + assert isinstance(bj, RegionModelInfo) + assert bj.available is True + assert bj.model.model == "qwen-plus" + assert bj.error is None + sg = result.regions["ap-southeast-1"] + assert sg.available is False + assert sg.model is None + assert sg.error is None + # is_available + get share one cached read per available region. + assert bj_calls == ["qwen-plus"] + assert sg_calls == ["qwen-plus"] + + def test_model_in_every_region(self): + router = _router( + { + "cn-beijing": _region_client("cn-beijing", BJ, []), + "ap-southeast-1": _region_client("ap-southeast-1", SG, []), + }, + ) + result = router.models.available_regions("qwen-max") + assert result.available_in == ["cn-beijing", "ap-southeast-1"] + + def test_model_in_no_region(self): + router = _router( + { + "cn-beijing": _region_client("cn-beijing", BJ, []), + "ap-southeast-1": _region_client("ap-southeast-1", SG, []), + }, + ) + result = router.models.available_regions("absent-model") + assert result.available_in == [] + assert all(info.error is None for info in result.regions.values()) + + def test_blank_model_rejected(self): + router = _router( + {"cn-beijing": _region_client("cn-beijing", BJ, [])}, + ) + with pytest.raises(ValueError, match="non-empty model id"): + router.models.available_regions(" ") + + def test_region_error_is_reported_not_fallback(self): + def failing(request): + return httpx.Response(500, json={"message": "boom"}) + + mock = httpx.MockTransport(failing) + bad = Client( + api_key="sk-test", + region="cn-beijing", + workspace="ws-bj", + base_url=BASE_URL, + http_client=httpx.Client(transport=mock, base_url=BASE_URL), + max_retries=0, + ) + sg_calls = [] + router = _router( + { + "cn-beijing": bad, + "ap-southeast-1": _region_client( + "ap-southeast-1", + SG, + sg_calls, + ), + }, + ) + result = router.models.available_regions("qwen-max") + # The failing region is an error entry, the other is still probed. + assert result.regions["cn-beijing"].available is False + assert result.regions["cn-beijing"].error is not None + assert result.regions["ap-southeast-1"].available is True + assert result.available_in == ["ap-southeast-1"] + assert sg_calls == ["qwen-max"] + + def test_refresh_refetches(self): + calls = [] + router = _router( + {"cn-beijing": _region_client("cn-beijing", BJ, calls)}, + ) + router.models.available_regions("qwen-plus") + assert calls == ["qwen-plus"] + router.models.available_regions("qwen-plus") # cached + assert calls == ["qwen-plus"] + router.models.available_regions("qwen-plus", refresh=True) + assert calls == ["qwen-plus", "qwen-plus"] + + +class TestAsyncDiscovery: + @pytest.mark.asyncio + async def test_available_in_only_matching_regions(self): + bj_calls, sg_calls = [], [] + bj = _async_region_client("cn-beijing", BJ, bj_calls) + sg = _async_region_client("ap-southeast-1", SG, sg_calls) + router = _async_router({"cn-beijing": bj, "ap-southeast-1": sg}) + result = await router.models.available_regions("qwen-plus") + assert result.available_in == ["cn-beijing"] + assert result.regions["cn-beijing"].model.model == "qwen-plus" + assert result.regions["ap-southeast-1"].available is False + assert bj_calls == ["qwen-plus"] + await bj.aclose() + await sg.aclose() + + @pytest.mark.asyncio + async def test_blank_model_rejected(self): + bj = _async_region_client("cn-beijing", BJ, []) + router = _async_router({"cn-beijing": bj}) + with pytest.raises(ValueError, match="non-empty model id"): + await router.models.available_regions("") + await bj.aclose() + + @pytest.mark.asyncio + async def test_region_error_is_reported_not_fallback(self): + async def failing(request): + return httpx.Response(500, json={"message": "boom"}) + + mock = httpx.MockTransport(failing) + bad = AsyncClient( + api_key="sk-test", + region="cn-beijing", + workspace="ws-bj", + base_url=BASE_URL, + http_client=httpx.AsyncClient( + transport=mock, + base_url=BASE_URL, + ), + max_retries=0, + ) + sg = _async_region_client("ap-southeast-1", SG, []) + router = _async_router({"cn-beijing": bad, "ap-southeast-1": sg}) + result = await router.models.available_regions("qwen-max") + assert result.regions["cn-beijing"].error is not None + assert result.regions["ap-southeast-1"].available is True + assert result.available_in == ["ap-southeast-1"] + await bad.aclose() + await sg.aclose() diff --git a/tests/test_response_drift.py b/tests/test_response_drift.py index f3522e00..1cc916d7 100644 --- a/tests/test_response_drift.py +++ b/tests/test_response_drift.py @@ -382,7 +382,9 @@ def handler(request): client = _make_client(handler) with caplog.at_level(logging.DEBUG, logger="dashscope._logging"): page = client.models.list() - assert page.total_count == 0 + # A null total falls back to the item count and marks the page's total + # unknown, so traversal keeps walking full pages instead of stopping. + assert page.total_count == 1 assert page.models[0].model == "qwen-plus" assert _drift_records(caplog) diff --git a/tests/test_responses.py b/tests/test_responses.py new file mode 100644 index 00000000..9bbdb349 --- /dev/null +++ b/tests/test_responses.py @@ -0,0 +1,937 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Alibaba, Inc. and its affiliates. +"""Tests for client.responses (C1: create/get/delete/input_items + stream). + +Same compatible-mode wire as batches (/compatible-mode/v1/responses, +protocol-independent, flat OpenAI response object), so these mirror +test_batches.py conventions. C1-specific coverage: the ten-type output +array and output_text convenience, two-generation usage + tool_usage, +Bailian extension normalization (reasoning/prompt_cache_options/ocr_options/ +text/tools), session_cache header, the previous_response_id ⊕ conversation +and function_call_output adjacency pre-validations, enable_thinking +deprecation, the input_items cursor (created_at milliseconds, last_id), +SSE streaming (text_stream / get_final_response) and raw/stream overloads. +""" + +# Mock handlers intentionally ignore the request argument; pytest fixture +# injection looks like unused/redefined names to pylint. +# pylint: disable=unused-argument,redefined-outer-name + +from __future__ import annotations + +import json + +import httpx +import pytest + +import dashscope.resources.responses as responses_mod +from dashscope import AsyncClient, Client +from dashscope.errors import BadRequestError, DashScopeError +from dashscope.resources.responses import InputItemList +from dashscope.transport._ident import sdk_client_value +from dashscope.types.responses import ( + FunctionTool, + OcrOptions, + Reasoning, + Response, + ResponseDeleted, + WebSearchTool, +) + +BASE_URL = "https://api.test.local/api/v1" +_WS_HOST = "https://ws-123.cn-beijing.maas.aliyuncs.com" +_COMPAT_RESPONSES = "/compatible-mode/v1/responses" + +_RESPONSE_BODY = { + "id": "resp_abc123", + "object": "response", + "created_at": 1771165900, + "status": "completed", + "model": "qwen-plus", + "output": [ + { + "type": "message", + "id": "msg_1", + "role": "assistant", + "status": "completed", + "content": [ + {"type": "output_text", "text": "Hello", "annotations": []}, + ], + }, + ], + "usage": { + "input_tokens": 10, + "output_tokens": 5, + "total_tokens": 15, + "input_tokens_details": {"cached_tokens": 0}, + "output_tokens_details": {"reasoning_tokens": 0}, + }, + "tool_usage": {}, + "error": None, + "parallel_tool_calls": False, + "tool_choice": "auto", + "tools": [], + "store": True, +} + +_INPUT_ITEMS_BODY = { + "created_at": 1778674066000, + "data": [ + { + "id": "msg_1", + "type": "message", + "role": "user", + "status": "completed", + "content": [{"type": "input_text", "text": "hi"}], + }, + ], + "first_id": "msg_1", + "last_id": "msg_1", + "has_more": False, + "id": "resp_abc123", + "model": "qwen-plus", +} + + +def _make_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.Client(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return Client(api_key="sk-test", http_client=http_client, **kwargs) + + +def _make_async_client(handler, **kwargs): + mock = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=mock, base_url=BASE_URL) + kwargs.setdefault("base_url", BASE_URL) + return AsyncClient(api_key="sk-test", http_client=http_client, **kwargs) + + +def _sse(frames): + return "".join( + f"id: {i}\ndata: {json.dumps(f)}\n\n" for i, f in enumerate(frames, 1) + ) + + +@pytest.fixture +def clean_env(monkeypatch): + from dashscope._config import settings + + for name in ( + "DASHSCOPE_API_KEY", + "DASHSCOPE_BASE_URL", + "DASHSCOPE_HTTP_BASE_URL", + "DASHSCOPE_WORKSPACE", + "DASHSCOPE_REGION", + "DASHSCOPE_PROTOCOL", + "DASHSCOPE_CONFIG", + ): + monkeypatch.delenv(name, raising=False) + settings.clear() + yield monkeypatch + settings.clear() + + +# -------------------------------------------------------------------------- +# create +# -------------------------------------------------------------------------- + + +def test_create_wire_body_and_parse(): + captured = {} + + def handler(request): + captured["method"] = request.method + captured["path"] = request.url.path + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + resp = client.responses.create(model="qwen-plus", input="hi") + assert captured["method"] == "POST" + assert captured["path"] == "/api/v1/responses" + # Unset optionals stay off the wire; stream defaults to False. + assert captured["body"] == { + "model": "qwen-plus", + "input": "hi", + "stream": False, + } + assert isinstance(resp, Response) + assert resp.id == "resp_abc123" + assert resp.object == "response" + assert resp.status == "completed" + assert resp.output_text == "Hello" + assert resp.output[0].type == "message" + assert resp.usage.total_tokens == 15 + assert resp.usage.input_tokens_details.cached_tokens == 0 + assert resp.tool_usage is not None + assert resp.is_error is False + client.close() + + +def test_create_normalizes_extensions_and_tools(): + captured = {} + + def handler(request): + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + client.responses.create( + model="qwen-plus", + input=[{"role": "user", "content": "hi"}], + instructions="be brief", + store=False, + tools=[ + WebSearchTool(), + FunctionTool(name="get_weather", parameters={"type": "object"}), + {"type": "code_interpreter"}, + ], + tool_choice="auto", + parallel_tool_calls=True, + temperature=0.7, + top_p=0.9, + max_output_tokens=1024, + reasoning=Reasoning(effort="high", summary="auto"), + prompt_cache_options={"mode": "explicit", "ttl": "1h"}, + ocr_options=OcrOptions(task="document_parsing"), + text={"format": {"type": "json_schema", "name": "out"}}, + ) + body = captured["body"] + assert body["input"] == [{"role": "user", "content": "hi"}] + assert body["instructions"] == "be brief" + assert body["store"] is False + assert body["tools"] == [ + {"type": "web_search"}, + { + "type": "function", + "name": "get_weather", + "parameters": {"type": "object"}, + }, + {"type": "code_interpreter"}, + ] + assert body["reasoning"] == {"effort": "high", "summary": "auto"} + assert body["prompt_cache_options"] == {"mode": "explicit", "ttl": "1h"} + assert body["ocr_options"] == {"task": "document_parsing"} + assert body["text"] == {"format": {"type": "json_schema", "name": "out"}} + assert body["temperature"] == 0.7 + assert body["max_output_tokens"] == 1024 + client.close() + + +def test_create_session_cache_header(): + seen = [] + + def handler(request): + seen.append(request.headers.get("x-dashscope-session-cache")) + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + client.responses.create(model="qwen-plus", input="hi", session_cache=True) + client.responses.create(model="qwen-plus", input="hi", session_cache=False) + client.responses.create(model="qwen-plus", input="hi") + assert seen == ["enable", "disable", None] + client.close() + + +def test_create_previous_response_id_and_conversation_exclusive(): + def handler(request): + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + with pytest.raises(ValueError, match="mutually exclusive"): + client.responses.create( + model="qwen-plus", + input="hi", + previous_response_id="resp_1", + conversation="conv_1", + ) + # Either alone is fine. + client.responses.create( + model="qwen-plus", + input="hi", + previous_response_id="resp_1", + ) + client.responses.create( + model="qwen-plus", + input="hi", + conversation="conv_1", + ) + client.close() + + +def test_create_function_call_output_adjacency(): + captured = {} + + def handler(request): + captured["body"] = json.loads(request.content) + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + good = [ + { + "type": "function_call", + "call_id": "call_1", + "name": "get_weather", + "arguments": "{}", + }, + {"type": "function_call_output", "call_id": "call_1", "output": "sun"}, + ] + client.responses.create(model="qwen-plus", input=good) + assert captured["body"]["input"] == good + + orphan = [ + {"type": "function_call_output", "call_id": "call_1", "output": "sun"}, + ] + with pytest.raises(ValueError, match="function_call_output"): + client.responses.create(model="qwen-plus", input=orphan) + + mismatch = [ + {"type": "function_call", "call_id": "call_1", "name": "f"}, + {"type": "function_call_output", "call_id": "call_2", "output": "x"}, + ] + with pytest.raises(ValueError, match="function_call_output"): + client.responses.create(model="qwen-plus", input=mismatch) + client.close() + + +def test_create_enable_thinking_deprecation(): + def handler(request): + return httpx.Response(200, json=_RESPONSE_BODY) + + responses_mod._ENABLE_THINKING_WARNED = False + client = _make_client(handler) + with pytest.warns(DeprecationWarning, match="enable_thinking"): + client.responses.create( + model="qwen-plus", + input="hi", + enable_thinking=True, + ) + client.close() + + +def test_create_requires_model_and_input(): + def handler(request): + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + with pytest.raises(ValueError, match="model"): + client.responses.create(model="", input="hi") + with pytest.raises(ValueError, match="input"): + client.responses.create(model="qwen-plus", input=None) + client.close() + + +# -------------------------------------------------------------------------- +# get / delete +# -------------------------------------------------------------------------- + + +def test_get_parses_response(): + def handler(request): + assert request.method == "GET" + assert request.url.path == "/api/v1/responses/resp_abc123" + return httpx.Response( + 200, + json=_RESPONSE_BODY, + headers={"x-request-id": "rid-1"}, + ) + + client = _make_client(handler) + resp = client.responses.get("resp_abc123") + assert resp.id == "resp_abc123" + assert resp.request_id == "rid-1" + assert resp.headers["x-request-id"] == "rid-1" + # A Response object is accepted as the id too. + again = client.responses.get(resp) + assert again.id == "resp_abc123" + client.close() + + +def test_get_requires_non_empty_id(): + def handler(request): + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + with pytest.raises(ValueError, match="response_id"): + client.responses.get(" ") + client.close() + + +@pytest.mark.parametrize("bad", ["", " "]) +def test_empty_response_id_rejected_before_wire(bad): + def handler(request): + raise AssertionError("request must not reach the wire") + + client = _make_client(handler) + for call in ( + client.responses.get, + client.responses.delete, + client.responses.input_items.list, + ): + with pytest.raises(ValueError, match="response_id"): + call(bad) + client.close() + + +def test_response_id_percent_encoded_in_path(): + seen = [] + + def handler(request): + seen.append(request.url.raw_path) + if request.method == "DELETE": + return httpx.Response( + 200, + json={"id": "resp/a?b#c", "deleted": True}, + ) + if request.url.path.endswith("/input_items"): + return httpx.Response(200, json=_INPUT_ITEMS_BODY) + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + tricky = "resp/a?b#c" + client.responses.get(tricky) + client.responses.delete(tricky) + client.responses.input_items.list(tricky) + # '/', '?' and '#' stay inside one path segment instead of retargeting + # the request to another path or query. + encoded = b"/api/v1/responses/resp%2Fa%3Fb%23c" + assert seen == [encoded, encoded, encoded + b"/input_items"] + client.close() + + +def test_delete_returns_id_and_deleted_no_object(): + def handler(request): + assert request.method == "DELETE" + assert request.url.path == "/api/v1/responses/resp_abc123" + return httpx.Response( + 200, + json={"id": "resp_abc123", "deleted": True}, + ) + + client = _make_client(handler) + resp = client.responses.delete("resp_abc123") + assert isinstance(resp, ResponseDeleted) + assert resp.id == "resp_abc123" + assert resp.deleted is True + client.close() + + +def test_http_error_maps_openai_nested_body(): + def handler(request): + return httpx.Response( + 400, + json={"error": {"code": "InvalidParameter", "message": "bad"}}, + headers={"x-request-id": "rid-err"}, + ) + + client = _make_client(handler) + with pytest.raises(BadRequestError) as ei: + client.responses.get("resp_x") + assert ei.value.code == "InvalidParameter" + assert ei.value.status_code == 400 + assert ei.value.request_id == "rid-err" + client.close() + + +def test_error_envelope_when_not_raising(): + def handler(request): + return httpx.Response( + 404, + json={"error": {"code": "NotFound", "message": "gone"}}, + headers={"x-request-id": "rid-404"}, + ) + + client = _make_client(handler, raise_on_error=False) + resp = client.responses.get("resp_typo") + assert resp.is_error is True + assert resp.status_code == 404 + assert resp.code == "NotFound" + assert resp.message == "gone" + assert resp.request_id == "rid-404" + assert resp.id is None + client.close() + + +def test_business_error_layer_raise_and_report(): + body = { + "code": "InvalidParameter", + "message": "unsupported", + "request_id": "rid-biz", + } + + def handler(request): + return httpx.Response(200, json=body) + + client = _make_client(handler) + with pytest.raises(BadRequestError) as ei: + client.responses.get("resp_1") + assert ei.value.status_code == 200 + client.close() + + client = _make_client(handler, raise_on_error=False) + resp = client.responses.get("resp_1") + assert resp.is_error is True + assert resp.code == "InvalidParameter" + client.close() + + +# -------------------------------------------------------------------------- +# input_items.list +# -------------------------------------------------------------------------- + + +def test_input_items_parse_and_created_at_milliseconds(): + def handler(request): + assert request.url.path == "/api/v1/responses/resp_abc123/input_items" + return httpx.Response(200, json=_INPUT_ITEMS_BODY) + + client = _make_client(handler) + page = client.responses.input_items.list("resp_abc123") + assert isinstance(page, InputItemList) + assert page.id == "resp_abc123" + assert page.model == "qwen-plus" + # Milliseconds, not seconds (13 digits). + assert page.created_at == 1778674066000 + assert page.first_id == "msg_1" + assert page.last_id == "msg_1" + assert [i.id for i in page.items] == ["msg_1"] + assert page.items[0].content[0].type == "input_text" + assert page.has_next_page() is False + client.close() + + +def test_input_items_cursor_pagination_uses_last_id(): + seen = [] + + def handler(request): + after = request.url.params.get("after") + seen.append(after) + if after is None: + return httpx.Response( + 200, + json={ + "data": [{"id": "msg_1"}, {"id": "msg_2"}], + "first_id": "msg_1", + "last_id": "msg_2", + "has_more": True, + }, + ) + return httpx.Response( + 200, + json={ + "data": [{"id": "msg_3"}], + "first_id": "msg_3", + "last_id": "msg_3", + "has_more": False, + }, + ) + + client = _make_client(handler) + page = client.responses.input_items.list("resp_1", limit=2, order="asc") + pages = list(page.iter_pages()) + assert [[i.id for i in p] for p in pages] == [ + ["msg_1", "msg_2"], + ["msg_3"], + ] + assert seen == [None, "msg_2"] + client.close() + + +def test_input_items_params_validation(): + captured = {} + + def handler(request): + captured["params"] = dict(request.url.params) + return httpx.Response(200, json={"data": [], "has_more": False}) + + client = _make_client(handler) + for bad_limit in (0, 101): + with pytest.raises(ValueError, match="limit"): + client.responses.input_items.list("resp_1", limit=bad_limit) + with pytest.raises(ValueError, match="order"): + client.responses.input_items.list("resp_1", order="sideways") + client.responses.input_items.list("resp_1") + assert captured["params"] == {} + client.responses.input_items.list( + "resp_1", + after="msg_9", + limit=100, + order="desc", + ) + assert captured["params"] == { + "after": "msg_9", + "limit": "100", + "order": "desc", + } + client.close() + + +def test_input_items_error_page_does_not_bind_pagination(): + def handler(request): + return httpx.Response( + 400, + json={"error": {"code": "InvalidParameter", "message": "bad"}}, + ) + + client = _make_client(handler, raise_on_error=False) + page = client.responses.input_items.list("resp_1") + assert page.is_error is True + assert page.has_next_page() is False + assert page.next_page() is None + client.close() + + +# -------------------------------------------------------------------------- +# header / routing / raw +# -------------------------------------------------------------------------- + + +def test_sdk_module_header(): + seen = {} + + def handler(request): + seen["client"] = request.headers.get("x-dashscope-sdk-client") + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + client.responses.get("resp_1") + assert seen["client"] == sdk_client_value("responses") + assert seen["client"].endswith("/responses2") + client.close() + + +@pytest.mark.parametrize("protocol", ["native", "openai", "anthropic"]) +def test_routing_default_gateway_ignores_chat_protocol(clean_env, protocol): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_RESPONSE_BODY) + + http_client = httpx.Client( + transport=httpx.MockTransport(handler), + base_url=_WS_HOST + "/api/v1", + ) + client = Client( + api_key="sk-test", + workspace="ws-123", + protocol=protocol, + http_client=http_client, + ) + client.responses.get("resp_1") + assert urls == [_WS_HOST + _COMPAT_RESPONSES + "/resp_1"], protocol + client.close() + + +def test_routing_explicit_base_url(): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + client.responses.create(model="qwen-plus", input="hi") + assert urls == [BASE_URL + "/responses"] + client.close() + + +def test_raw_returns_apiresponse_before_error_check(): + def handler(request): + return httpx.Response(400, json={"error": {"message": "bad"}}) + + client = _make_client(handler) + raw = client.responses.get("resp_1", raw=True) + assert raw.status_code == 400 + assert raw.json()["error"]["message"] == "bad" + client.close() + + +def test_raw_with_stream_raises(): + def handler(request): + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_client(handler) + with pytest.raises(ValueError, match="raw=True"): + client.responses.create( + model="qwen-plus", + input="hi", + stream=True, + raw=True, + ) + client.close() + + +# -------------------------------------------------------------------------- +# streaming +# -------------------------------------------------------------------------- + +_STREAM_FRAMES = [ + { + "type": "response.created", + "sequence_number": 0, + "response": {"id": "resp_s", "object": "response", "status": "queued"}, + }, + { + "type": "response.output_text.delta", + "sequence_number": 1, + "delta": "He", + "item_id": "msg_1", + "output_index": 0, + "content_index": 0, + }, + { + "type": "response.output_text.delta", + "sequence_number": 2, + "delta": "llo", + }, + { + "type": "response.completed", + "sequence_number": 3, + "response": {**_RESPONSE_BODY, "id": "resp_s"}, + }, +] + + +def _stream_handler(request): + return httpx.Response( + 200, + content=_sse(_STREAM_FRAMES), + headers={ + "content-type": "text/event-stream", + "x-request-id": "rid-stream", + }, + ) + + +def test_stream_iterates_events_and_text_stream(): + client = _make_client(_stream_handler) + stream = client.responses.create( + model="qwen-plus", + input="hi", + stream=True, + ) + events = list(stream) + assert [e.type for e in events] == [ + "response.created", + "response.output_text.delta", + "response.output_text.delta", + "response.completed", + ] + assert events[0].response.status == "queued" + assert stream.headers["x-request-id"] == "rid-stream" + client.close() + + client = _make_client(_stream_handler) + stream = client.responses.create( + model="qwen-plus", + input="hi", + stream=True, + ) + assert "".join(stream.text_stream) == "Hello" + client.close() + + +def test_stream_get_final_response(): + client = _make_client(_stream_handler) + stream = client.responses.create( + model="qwen-plus", + input="hi", + stream=True, + ) + final = stream.get_final_response() + assert isinstance(final, Response) + assert final.id == "resp_s" + assert final.status == "completed" + assert final.output_text == "Hello" + assert final.usage.total_tokens == 15 + assert final.headers["x-request-id"] == "rid-stream" + client.close() + + +def test_stream_in_stream_error_raises(): + def handler(request): + frames = [ + _STREAM_FRAMES[0], + {"error": {"code": "InvalidParameter", "message": "boom"}}, + ] + return httpx.Response( + 200, + content=_sse(frames), + headers={"content-type": "text/event-stream"}, + ) + + client = _make_client(handler) + stream = client.responses.create( + model="qwen-plus", + input="hi", + stream=True, + ) + with pytest.raises(BadRequestError) as ei: + list(stream) + assert ei.value.code == "InvalidParameter" + client.close() + + +def test_stream_without_terminal_raises(): + def handler(request): + return httpx.Response( + 200, + content=_sse(_STREAM_FRAMES[:3]), + headers={"content-type": "text/event-stream"}, + ) + + client = _make_client(handler) + stream = client.responses.create( + model="qwen-plus", + input="hi", + stream=True, + ) + with pytest.raises(DashScopeError, match="terminal"): + stream.get_final_response() + client.close() + + +# -------------------------------------------------------------------------- +# async symmetry +# -------------------------------------------------------------------------- + + +async def test_async_create_get_delete(): + captured = [] + + def handler(request): + captured.append((request.method, request.url.path)) + if request.method == "DELETE": + return httpx.Response( + 200, + json={"id": "resp_abc123", "deleted": True}, + ) + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_async_client(handler) + created = await client.responses.create(model="qwen-plus", input="hi") + assert created.output_text == "Hello" + got = await client.responses.get("resp_abc123") + assert got.status == "completed" + deleted = await client.responses.delete("resp_abc123") + assert deleted.deleted is True + assert captured == [ + ("POST", "/api/v1/responses"), + ("GET", "/api/v1/responses/resp_abc123"), + ("DELETE", "/api/v1/responses/resp_abc123"), + ] + await client.aclose() + + +async def test_async_input_items_pagination(): + seen = [] + + def handler(request): + after = request.url.params.get("after") + seen.append(after) + if after is None: + return httpx.Response( + 200, + json={ + "data": [{"id": "msg_1"}], + "last_id": "msg_1", + "has_more": True, + }, + ) + return httpx.Response( + 200, + json={ + "data": [{"id": "msg_2"}], + "last_id": "msg_2", + "has_more": False, + }, + ) + + client = _make_async_client(handler) + page = await client.responses.input_items.list("resp_1") + pages = [p async for p in page.iter_pages_async()] + assert [[i.id for i in p] for p in pages] == [["msg_1"], ["msg_2"]] + assert seen == [None, "msg_1"] + await client.aclose() + + +async def test_async_stream_get_final_response(): + client = _make_async_client(_stream_handler) + stream = await client.responses.create( + model="qwen-plus", + input="hi", + stream=True, + ) + final = await stream.get_final_response() + assert final.id == "resp_s" + assert final.output_text == "Hello" + await client.aclose() + + +async def test_async_error_envelope_when_not_raising(): + def handler(request): + return httpx.Response( + 404, + json={"error": {"code": "NotFound", "message": "gone"}}, + ) + + client = _make_async_client(handler, raise_on_error=False) + resp = await client.responses.get("resp_typo") + assert resp.is_error is True + assert resp.code == "NotFound" + await client.aclose() + + +async def test_async_routing_default_gateway(clean_env): + urls = [] + + def handler(request): + urls.append(str(request.url)) + return httpx.Response(200, json=_RESPONSE_BODY) + + http_client = httpx.AsyncClient( + transport=httpx.MockTransport(handler), + base_url=_WS_HOST + "/api/v1", + ) + client = AsyncClient( + api_key="sk-test", + workspace="ws-123", + http_client=http_client, + ) + await client.responses.get("resp_1") + assert urls == [_WS_HOST + _COMPAT_RESPONSES + "/resp_1"] + await client.aclose() + + +async def test_async_response_id_percent_encoded_in_path(): + seen = [] + + def handler(request): + seen.append(request.url.raw_path) + if request.url.path.endswith("/input_items"): + return httpx.Response(200, json=_INPUT_ITEMS_BODY) + return httpx.Response(200, json=_RESPONSE_BODY) + + client = _make_async_client(handler) + await client.responses.get("resp/a?b#c") + await client.responses.input_items.list("resp/a?b#c") + encoded = b"/api/v1/responses/resp%2Fa%3Fb%23c" + assert seen == [encoded, encoded + b"/input_items"] + await client.aclose() + + +@pytest.mark.parametrize("bad", ["", " "]) +async def test_async_empty_response_id_rejected_before_wire(bad): + def handler(request): + raise AssertionError("request must not reach the wire") + + client = _make_async_client(handler) + with pytest.raises(ValueError, match="response_id"): + await client.responses.get(bad) + with pytest.raises(ValueError, match="response_id"): + await client.responses.delete(bad) + with pytest.raises(ValueError, match="response_id"): + await client.responses.input_items.list(bad) + await client.aclose() diff --git a/tests/test_settings.py b/tests/test_settings.py index df401195..3b0c446f 100644 --- a/tests/test_settings.py +++ b/tests/test_settings.py @@ -139,8 +139,14 @@ def test_region_lazy_env_and_setter(clean): def test_region_setter_validation(clean): + # A4: an unsafe label is still rejected; a safe but unknown region + # warns instead of raising (passthrough), so new regions work + # without an SDK upgrade. with pytest.raises(ValueError, match="invalid region"): + settings.region = "moon.1" + with pytest.warns(UserWarning, match="not a known DashScope region"): settings.region = "moon-1" + assert settings.region == "moon-1" def test_base_url_uses_settings_region(clean):