Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
6c53ac3
feat(models): server-side filters + rich metadata for models.list (A1)
Nov 17, 2026
5321508
feat(fine-tunes): add model compression (quantization) sub-resource (D1)
Nov 17, 2026
3386de5
feat(batches): add client.batches.files compatible-mode File resource…
Nov 17, 2026
9f414fa
feat(batches): add client.batches job plane create/get/list/cancel/wa…
Nov 17, 2026
f2378e5
feat(responses): add client.responses create/get/delete/input_items.l…
Nov 17, 2026
5636908
feat(models): auto-pagination, availability check, region/workspace c…
Nov 18, 2026
0c41657
feat(models): add read-only models.limits and models.permissions sub-…
Nov 18, 2026
47288e1
feat(batches): add download_output/download_error result helpers + in…
Nov 18, 2026
f2fdf67
feat(models): region safe passthrough + region-aware catalog cache (A4)
Nov 18, 2026
83b6f3c
feat(models): explicit cross-region RegionRouter with opt-in + cross-…
Nov 18, 2026
3d219fb
feat(batch): client.batch_chat.completions queued synchronous Batch C…
Nov 18, 2026
0c2ddcf
feat(conversations): client.conversations CRUD + items lifecycle (C2)
Nov 18, 2026
213ff8b
feat(messages): native Anthropic Messages resource (C3)
Nov 18, 2026
7a07fa7
feat(deployments): PTU throughput reservation + capacity instances/op…
Nov 18, 2026
a0fa141
style(deployments): apply pre-commit formatting + reduce create-body …
Nov 18, 2026
9053697
docs(anthropic): clarify web-search billing marker packaging is SDK-side
Nov 18, 2026
cb3e2f8
style: make pre-commit pass across control-plane modules
Nov 18, 2026
a870781
fix: address branch review findings across v2 resources
Nov 18, 2026
328cec8
fix(resources): enforce non-empty and percent-encode IDs in paths
Nov 20, 2026
573da41
fix(api): percent-encode conversation, item, and response IDs in paths
Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions dashscope/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -297,10 +303,14 @@ def __dir__():
"VideoSynthesis",
# dashscope 2.0
"AsyncClient",
"AsyncRegionRouter",
"Client",
"Config",
"DashScopeError",
"ErrorCode",
"ModelAvailability",
"RegionModelInfo",
"RegionRouter",
"Settings",
"WsConnection",
"WsTask",
Expand Down
93 changes: 89 additions & 4 deletions dashscope/_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
from __future__ import annotations

import os
import re
import threading
import warnings
from dataclasses import dataclass
Expand Down Expand Up @@ -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

Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion dashscope/cli/commands/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
Expand Down
13 changes: 11 additions & 2 deletions dashscope/cli/config_store.py
Original file line number Diff line number Diff line change
Expand Up @@ -173,15 +173,13 @@ 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,
)

return {
"protocol": ("protocol", tuple(VALID_PROTOCOLS)),
"region": ("region", tuple(VALID_REGIONS)),
"output": ("output format", tuple(OUTPUT_FORMATS)),
}

Expand Down Expand Up @@ -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:
Expand Down
15 changes: 15 additions & 0 deletions dashscope/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
69 changes: 69 additions & 0 deletions dashscope/protocols/anthropic.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
Callable,
Dict,
List,
Mapping,
Optional,
Tuple,
Union,
Expand All @@ -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``
Expand Down Expand Up @@ -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,
Expand Down
Loading
Loading