Skip to content

feat: fill Bailian control-plane API gaps (modules A–D) - #239

Open
lzsweb wants to merge 20 commits into
mainfrom
dev/v2.2
Open

lzsweb wants to merge 20 commits into
mainfrom
dev/v2.2

Conversation

@lzsweb

@lzsweb lzsweb commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

Summary

Fills the Bailian (Model Studio) control-plane API gaps in the 2.0 SDK across modules A–D (15 commits). All resources are hand-written, sync/async symmetric, follow the C1 error contract (dual-layer HTTP/business check, raise_on_error=False envelope, raw=True escape hatch, sdk_module header), and are verified against the authoritative Bailian docs before implementation.

  • A · Models (A1–A5): server-side filters + rich metadata for models.list; auto-pagination, is_available, region/workspace context; read-only models.limits / models.permissions; region safe passthrough (format-safe DNS label invariant, unknown-region warn vs reject) + region-aware catalog cache (TTL, refresh=True, credential-fingerprinted key); explicit opt-in cross-region RegionRouter (off by default, cross-border compliance is the user's responsibility).
  • B · Batches (B1–B4): batches.files compatible-mode File resource; batches job plane (create/get/list/cancel/wait); download_output/download_error helpers; batch_chat.completions queued synchronous Batch Chat.
  • C · Responses / Conversations / Messages (C1–C3): client.responses (create/get/delete/input_items.list + stream); client.conversations CRUD + items lifecycle; native Anthropic client.messages resource (workspace路由, anthropic-version, web_search billing-header injection, streaming accumulation).
  • D · Model production (D1, D3): fine_tunes.compress (quantization) sub-resource; PTU throughput reservation — deployments.create(plan="ptu") fields, capacity_instances (create/list/get/scale/renew/delete) + capacity_operations (get/wait) sub-resources, renew / update_overflow_strategy, with billing safeguards (purchase/renew default max_retries=0, x-acs-req-uuid idempotency key, HTTP-200 operation_status=FAILED check).

Out of scope (verified): D2 (fine_tune metrics/retry) and D4 (deployments start/stop/rollout) are not open in the official docs. Module E is mostly server-blocked; F (AgentStudio) deferred pending evaluation; G (ManagementClient, repositioned as the ToB self-service backend SDK integration layer) is planned after A–F and not started here.

Test plan

  • Full suite green: pytest -q → 6216 passed, 47 skipped, 0 failures.
  • New mock tests per milestone (public/arbitrary model names only); D3 adds tests/test_deployments_ptu.py (39 cases) and keeps tests/test_finetune_deployments.py (132) green.
  • pre-commit clean on changed files (black 79-col, add-trailing-comma, flake8, mypy, pylint source+tests).
  • Line width ≤88 audited on new/changed files.
  • Online e2e not run (requires external public models + Beijing/Singapore workspace; high-risk billing writes not auto-tested).

zhansheng.lzs and others added 20 commits November 17, 2026 16:37
Route the singular `provider` into the server-side `providers` filter and
pass through the full 12-filter contract (name/model/language/providers/
inference_providers/capabilities/features/context_window/service_site/
supports/deployment_methods/deployment_ptu_service_tiers), with array
filters sent as repeated query params. This fixes the client-side per-page
slice that left total_count pre-filter and hid matches on other pages;
filters are threaded through bind_pagination so traversal preserves them.

Type the rich catalog metadata (ModelPrice/ModelPriceRange/InferenceMetadata/
ModelInfo and the extended Model fields). Update CLI --provider help and the
example to the server-side semantics; rewrite the provider tests and add
coverage for repeated keys, scalar passthrough, metadata parsing, and
filter-preserving pagination (sync/async).
Wire client.fine_tunes.compress against /api/v1/fine-tunes/compress:
templates catalog (base_models + custom_models[].templates[]) and the
jobs lifecycle (create/get/list/logs/cancel/delete/wait), sync + async.
Matches the official Model Studio compression contract: quantization-only,
integer GPU-seconds usage, server-side job filters, terminal-state waiter.
… (B1)

Mount the OpenAI-compatible File plane for the Batch workflow under
client.batches.files: upload (purpose=batch, JSONL-validated), content
download, cursor-paginated list (purpose/after/limit), get and delete.
Every call routes through compatible_mode_base_url (/compatible-mode/v1/files)
independent of the chat protocol, and carries sdk_module="batches" on the
x-dashscope-sdk-client header.

This is a distinct wire from the native client.files (fine-tune): multipart
"file" singular, flat OpenAI objects, after/has_more cursor pagination (new
BatchFileList, since BasePage is offset-only). Native client.files is left
untouched; B2 adds the batch job plane to the same Batches class.

Sync/async symmetric with raw overloads; 34 mock tests cover wire shape,
cursor traversal, content bytes/write_to_file, error mapping and routing.
…it (B2)

Extend the Batches resource with the OpenAI-compatible batch job plane:
create, get, cursor-paginated list, cancel, a polling wait, and a pre-upload
validate_input row-level JSONL check. Same compatible-mode wire as B1's File
plane (/compatible-mode/v1/batches, protocol-independent, sdk_module="batches"
on x-dashscope-sdk-client).

create has no server-side idempotency key, so it defaults to max_retries=0
(no auto-retry) to avoid spawning duplicate batches; get/list/cancel/wait keep
the default retry budget. No fake idempotency header is injected -- a caller
passing max_retries explicitly owns the duplicate risk. completion_window is
validated client-side (integer + h/d, 24h..336h).

New models Batch/RequestCounts/BatchErrors/BatchErrorItem/BatchList. BatchList
and B1's BatchFileList now share a _CursorPage base (cursor traversal with
polymorphic-self typing); the Batch list limit is [1,100] (vs File [1,2000])
and advances by last_id. wait mirrors fine_tunes.wait with lowercase terminal
statuses {completed,failed,expired,cancelled}.

Sync/async symmetric with raw overloads; 64 mock tests cover wire shape, the
no-retry default, cursor traversal, waiter terminal/timeout/error paths,
validate_input row checks, error mapping and routing.
…ist + stream (C1)

First-class OpenAI-compatible Responses resource on the core inference
Client (API-Key Bearer), independent of chat protocol normalization.

- types/responses.py: flat OpenAI response object; single permissive
  ResponseOutputItem covering all 10 heterogeneous output item types;
  two-generation usage union + tool_usage; 8 typed tool classes;
  ResponseDeleted {id, deleted} (no object); InputItem; stream events.
- resources/responses.py: create/get/delete + input_items.list; sync/async
  symmetric; ResponseStream/AsyncResponseStream over transport SSE with
  text_stream/reasoning_stream/get_final_response; InputItemList reuses
  the shared _CursorPage (cursor prefers last_id, created_at in ms).
- Bailian extensions as first-class params: reasoning.effort/summary,
  prompt_cache_options, ocr_options, session_cache -> x-dashscope-session-cache
  header (create-level); enable_thinking DeprecationWarning (once-guard).
- Pre-flight validation: model/input required, previous_response_id XOR
  conversation, function_call_output must immediately follow its
  function_call with matching call_id.
- Routing via compatible_mode_base_url; sdk_module="responses" on every
  request_api/open_stream; local _checked mirrors batches/decision
  dual-layer error handling with non-raising envelope backfill.
- create three overloads (stream/raw); get/delete/list support raw=True.
- tests/test_responses.py: 33 mock tests (httpx.MockTransport).
…ontext (A2)

Build on A1's server-side filters + rich metadata to make the model
catalog fully traversable and region-aware.

- iter()/list_all() (sync+async): walk every page of the filtered catalog
  from page 1 to total, reusing BasePage.iter_pages/iter_pages_async and
  forwarding all filters per page. iter is lazy (Iterator/AsyncIterator),
  list_all eager (List[Model]); page_size defaults to 100 to cut
  round-trips. Current Client Region only.
- is_available(model) (sync+async) -> bool: answers only for this Client's
  Region/endpoint, never queries other Regions implicitly. Mirrors get's
  wire call; transport/HTTP errors propagate rather than reading as
  "unavailable"; empty/blank model id raises ValueError so an empty filter
  cannot masquerade as the whole catalog matching.
- Model gains SDK-injected served_region (=config.region) and workspace
  (=effective workspace, per-call override wins), stamped on every model
  in list/get (incl. the not-found envelope branch). These describe the
  endpoint the catalog was read from, so the SDK values are authoritative.
- service_site kept distinct from served_region: verified against the
  official list-models doc that the wire per-model object returns neither
  service_site nor region/workspace. service_site is a deployment-site
  query filter, so Model.service_site echoes the query's filter (None when
  unfiltered) and preserves a wire-provided value when present.
- tests: 17 new cases in test_files_models.py (injection/default region/
  workspace override/service_site echo + wire precedence/get + not-found/
  iter all-pages + filter preservation + laziness/list_all/is_available
  true/false/empty-model/HTTP-error/sdk header/async symmetry);
  test_pagination dump expectation updated for the three new fields.
…resources (A3)

Wire-verified against Bailian docs: GET /models/limits -> output.quotas[]
and GET /models/permissions -> output.permissions[] (API-Key bearer,
inference plane). Corrections: versions has no public endpoint (dropped);
authorizations renamed to permissions per wire authority. Read-only list/get
with BasePage pagination; writes deferred to management plane (G3).
…put reuse e2e (B3)

Batch-level convenience over the existing files.content download: resolve a
batch's output_file_id/error_file_id (fetching the batch first when given an
id) and return Optional[FileContent], None when the file is absent. Input
file reuse is already supported by create/files.list and now covered by
tests. Adds a gated live e2e using the public zero-cost batch-test-model.
Part 1: downgrade the static region whitelist to safe DNS-label
passthrough. Any region/workspace interpolated into the gateway host
must match an RFC1123 label (host-injection guard); with a workspace an
unknown-but-safe region warns instead of raising, without a workspace a
known shared-gateway mapping is still required, and an explicit base_url
bypasses the policy. CLI region validation mirrors the new acceptance.

Part 2: per-instance short-TTL (60s) catalog cache for list/get/
is_available, keyed by region/workspace/credential-fingerprint/query so
entries never cross tenants or Regions. refresh=True forces a fetch,
raw=True and errors are never cached, and only genuine successes are
stored. Adds refresh to list/get/iter/list_all/is_available (sync+async).
…border compliance notice (A5)

Discovery-only cross-region model availability (no inference routing,
no auto fallback). Disabled by default: construction requires explicit
allow_cross_region=True; enabling warns that cross-border data
compliance is the user's sole responsibility. Validates per-region
Clients as one config unit (region/workspace/key), reuses A4 catalog
cache so each region costs one network read, and records per-region
errors without aborting or silently switching regions.
…hat (B4)

OpenAI-compatible single non-streaming request on the dedicated batch
gateway (batch.dashscope.aliyuncs.com/compatible-mode/v1), independent of
the client's chat protocol. Reuses OpenAIProtocol + ChatCompletion +
normalize_messages; derives its own batch base_url (explicit base_url
override as escape hatch). timeout 60..3600s (default 3600), max_retries
passthrough for unscheduled-timeout retries. sdk_module=batch_chat
(/batch_chat2). 27 mock tests; full suite 6080 passed.
OpenAI-compatible Conversations API on the compatible-mode wire, reusing
C1 conventions: compatible_mode_base_url routing (chat protocol cannot
move it), per-resource _checked dual-layer error envelope, _CursorPage
cursor pagination, sdk_module=conversations (/conversations2), sync/async
symmetry, local pre-validation (items<=20, metadata<=16 pairs, limit
1-100). Full documented surface: conversation create/get/update/delete +
items.create/list/get/delete. Types exported via dashscope.types (the
top-level dashscope.Conversation remains the 1.x class). Links to
Responses via conversation= (mutually exclusive with previous_response_id).
40 mock tests; full suite 6120 passed.
Add client.messages (sync/async) as a first-class Anthropic Messages
resource, distinct from the chat protocol=anthropic adapter.

- types/anthropic_messages.py: AnthropicMessage/ContentBlock/Usage/
  StreamEvent + server-tool/cache/thinking/output configs, exported via
  dashscope.types (avoids collision with canonical chat Message).
- resources/messages.py: create + stream overloads, _checked dual-layer
  error envelope, temperature [0,2) validation, max_tokens required,
  budget_tokens deprecation warning, sdk_module=messages (/messages2),
  anthropic-version header.
- _config.anthropic_base_url: POST {base}/apps/anthropic/v1/messages
  (base not ending /v1); explicit base_url stays service root.
- Stream accumulation via _MessageBuilder (Anthropic has no terminal
  full-message event); server_tool_use/web_search_tool_result carry
  complete input/content at content_block_start (non-incremental).
- Shared web_search billing-header injection helpers in
  protocols/anthropic.py so native resource and chat adapter behave
  identically; output_config/cache_control/server tools first-class.

count_tokens, /v1/models, metadata first-class intentionally not done
(not provided / not documented by Bailian).

51 mock tests + 6 adapter consistency tests; full suite 6177 passed.
…erations (D3)

Extend client.deployments with plan="ptu" create/scale fields, renew and
update_overflow_strategy, and mount capacity_instances (create/list/get/
scale/renew/delete) + capacity_operations (get/wait) subresources.

Billing safeguards per the authoritative throughput-reservation contract:
purchase/renew/scale/delete default to max_retries=0, instance writes carry
an x-acs-req-uuid idempotency key mirrored to X-DashScope-RequestId (the
first ModelCode create deliberately does not), and HTTP-200
operation_status=FAILED is surfaced as a catalog error. CapacityOperation
preserves the original write request_id separately from the poll envelope;
instance pagination normalizes the camelCase wire shape.

D2 (fine_tune metrics/retry) and D4 (deployments start/stop/rollout) verified
not open in the official docs and left out of scope.
…branches (D3)

Run pre-commit (black 79-col, add-trailing-comma, flake8, mypy, pylint) on
the D3 changed files. Refactor _build_create_body to collapse optional-field
branches into a dict update and extract _validate_ptu_create, clearing
pylint R0912 (too-many-branches). No behavior change; 171 tests still green.
The identifier value is a Bailian doc convention; riding it as a standalone
system text block is a valid system form, not a doc-mandated packaging.
The A–D milestone files were committed without a full pre-commit run, so
CI failed. Apply black formatting and resolve the genuine lint errors:

- flake8/pylint: drop unused httpx / NotFoundError imports and unused r2.
- pylint R1735: dict(...) -> dict literals (models, fine_tunes_compress).
- pylint R0912: extract helpers for branchy functions — models
  _build_list_params filter collapse, batches _validate_batch_row,
  messages _MessageBuilder per-event handlers + shared finalizer.
- mypy: annotate filter_kwargs Dict[str, Any] (stops **unpack overload
  explosion); guard Optional[int] content-block indexes.
- pylint W0622: scope redefined-builtin disable to Responses.create
  overloads (canonical `input` API param, matching the impl precedent).
- pylint E1133: materialize Optional[Any] content via list() so astroid
  sees an iterable in anthropic_messages.search_results.

Behavior preserved: full suite 6216 passed, 47 skipped.
- messages: preserve message_start usage counters when a spec-conformant
  delta omits them (exclude_unset over exclude_none), and honor the
  client's strict_validation when building the final streamed message
- models: bypass the catalog cache for requests carrying extra_query /
  extra_headers so overrides neither read nor pollute cached entries;
  when the gateway omits total, mark the page's total unknown and keep
  walking full pages instead of truncating after the first page
- deployments/PTU: reuse a caller-supplied idempotency key regardless of
  header case, emitting one x-acs-req-uuid / X-DashScope-RequestId pair;
  accept snake_case pagination aliases on capacity instance lists
- batch_chat: honor client protocol_options (strict mode) when building
  request bodies instead of a shared default protocol
- batches/files: skip blank lines in JSONL pre-validation to match the
  batches row scanner, and reject all-blank batch uploads like
  validate_input does

Behavior note: models.list's singular provider filter now folds into the
server-side providers filter; it no longer matches source client-side,
and total_count reflects the filtered set (documented in list()).
- Add _path_id utility to validate non-empty string IDs and percent-encode
- Apply _path_id to deployed_model, instance_id, operation_id in deployments module
- Add similar ID guards and encoding for file_id and batch_id in batches module
- Add job_id validation and encoding in fine_tunes_compress module
- Enforce model ID non-empty validation in models module for list, get, limits, permissions
- Modify batch_chat create to default max_retries to 0 to avoid duplicate billing
- Add tests for ID validation errors before sending requests
- Add tests verifying correct percent-encoding of IDs in request URLs
- Adjust max_retries default for batch_chat and fine_tunes_compress create operations to 0
- Ensure that unsafe characters do not retarget URL segments by encoding them
- Import urllib.parse.quote to encode IDs in URLs
- Encode conversation_id, item_id, and response_id to prevent path retargeting by '/', '?', or '#'
- Reject empty or whitespace-only IDs before making requests
- Add synchronous and asynchronous tests to verify percent-encoding of IDs in request paths
- Ensure requests with invalid IDs do not reach the network layer and raise ValueError early
- Verify correct encoding is applied consistently across conversation, item, and response API calls

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant