Pointcosm Python SDK

简体中文 | English

Status: official releases are distributed through PyPI. Runtime base URLs and credentials must come from approved customer configuration.

This repository contains the public Pointcosm Python SDK. Its sole contract authority is a pinned, reviewed commit of pointcosm-sdk-contracts; the SDK imports Customer/Auth OpenAPI, language-neutral manifests, sensitive-field rules and bundle metadata from that clean local checkout without network access. Train and Auth remain upstream runtime fact sources for the contracts repository, but are never direct SDK generation inputs. Mixed internal GET /openapi.json contracts are prohibited.

Development setup

The validated compatibility range is CPython 3.11 through 3.14.

uv sync --all-groups --python 3.14
uv run python -c "import pointcosm"
uv run pytest

Train Platform commands that load application settings must explicitly use:

APP_PROFILE=local

Safety boundaries

• Never commit real access tokens, client secrets, STS credentials, Webhook secrets, or signed URLs.
• Do not generate from an internal or mixed OpenAPI document.
• Do not weaken contract, deterministic-generation, error, or sensitive-sentinel gates.
• Local wheel and sdist builds are validation artifacts; official uploads use the reviewed release workflow and require explicit project-owner approval.
• Publishing uses GitHub Actions Trusted Publishing with the protected pypi environment. No long-lived PyPI token belongs in repository or organization secrets.

The reviewed implementation artifacts are under specs/001-python-sdk-v1/.

Contract status

The pinned Customer 0.8.0 snapshot contains 17 paths, 23 public operations and 52 referenced schemas. All operations declare their reviewed HTTP 401, 403 and 500 envelopes, with HTTP 422 on all 19 applicable operations. The strict contract gate is:

uv run pytest -q tests/contract/test_standard_error_responses.py

Do not skip, xfail or weaken this test during future contract refreshes.

Contract refresh review

Candidate acquisition and review belong to pointcosm-sdk-contracts. This SDK only consumes a full 40-character commit whose checkout HEAD matches, whose tracked and untracked working tree is clean, and whose bundle release, bundle SHA and every declared artifact SHA/size pass. Branches, tags used without resolution, abbreviated revisions, dirty checkouts, URLs and loose OpenAPI files are rejected.

The approved input is contracts tag v0.8.0 at commit e502eb0a65fb1feed363cb1c4d84466e26cb657c, bundle 0.8.0, bundle SHA fb79ba067a9005bd608a3be04afff0ee062859596e8972877f0bb15b5955ad07 and Customer SHA eec77b3bd3e24029698ac38b39e23fba99cd8cc64a69f621d083a07306350d5c.

Use the same command with --check after import. Review the imported neutral manifests, Python manifests, generated source and provenance diff before accepting it. Auth v1 remains exactly one marked POST /api/oauth/token operation; credential management and admin operations remain excluded.

Bundle 0.3.0 is a deliberate breaking cleanup. Public Product, Asset, Task, TaskListItem and TaskDetail no longer expose backend display/pipeline/execution fields. Unknown response fields remain forward-compatible but are never attached as public attributes. Customer-visible pricing is limited to green-point prices and frozen task charges; RMB references and compute-center costs remain forbidden.

Bundle 0.4.0 added typed seven-stage milestone timing and richer transfer lifecycle/timestamp quality to task progress. Bundle 0.5.0 makes the customer-safe TaskProgress projection required and non-null on create/rerun TaskOut, list TaskListItem and retrieve TaskDetailOut; its seven English milestone values and exactly seven milestones entries remain unchanged. SDK 0.4.0 exposes Task.progress, TaskListItem.progress and TaskDetail.progress as typed immutable public models.

Bundle 0.6.0 replaces the Asset status/count projection, adds upload-limit and upload-flow reads, supports mixed image/video products, requires product_id when creating Tasks, and exposes nullable Task charges with one or two typed charge components. Task rerun and user storage connection APIs are no longer part of the customer contract.

Bundle 0.8.0 consolidates Asset state into a required status enum, adds Task deletion and typed Task failure details, requires artifact group_id, and adds green-point purchase-order listing with promotion-code adjustments.

Installation

Install the published package from PyPI:

python -m pip install pointcosm

For local development:

uv sync --all-groups

Static Bearer

import os

from pointcosm import Pointcosm

with Pointcosm(
    base_url="http://localhost:8200",
    access_token=os.getenv("POINTCOSM_ACCESS_TOKEN", "synthetic-doc-token"),
) as client:
    if os.getenv("POINTCOSM_DOCS_DRY_RUN") != "1":
        products = client.train.list_products()

Client credentials

The Auth Service uses port 8100 locally. Production base URLs must come from approved customer configuration; the SDK repository and package do not publish deployment locators.

import os

from pointcosm import Pointcosm

client = Pointcosm.from_client_credentials(
    base_url="http://localhost:8200",
    auth_base_url="http://localhost:8100",
    client_id=os.getenv("POINTCOSM_CLIENT_ID", "synthetic-client"),
    client_secret=os.getenv("POINTCOSM_CLIENT_SECRET", "synthetic-secret"),
    resource="urn:pointcosm:train",
)
if os.getenv("POINTCOSM_DOCS_DRY_RUN") != "1":
    account = client.billing.get_green_point_account()
client.close()

Credential creation, listing, rotation and revocation remain UI/admin workflows and are not SDK APIs.

Capabilities and errors

The stable namespaces are client.train, client.storage, client.webhooks and client.billing. Methods return stable public models and may raise exceptions from pointcosm.exceptions. For a complete method catalog and end-to-end examples, see the Chinese SDK usage guide and the public API reference.

from pointcosm.exceptions import (
    PointcosmApiError,
    PointcosmContractError,
    PointcosmTransportError,
)

handled_errors = (PointcosmApiError, PointcosmContractError, PointcosmTransportError)

API errors expose bounded status_code, code, message, details, request_id and operation_id. They never retain raw bodies or headers.

Sensitive values

STS keys, Webhook secrets and signed download URLs use SensitiveStr. str and repr are redacted; revealing a value requires the explicit get_secret_value() method. Never log the revealed value.

Lifecycle, timeout and retry

SDK-created HTTP clients close on context exit. Injected httpx clients remain caller-owned and must be closed by the caller. Redirects are always disabled. Injected proxies and event hooks are also caller-owned; the SDK cannot sanitize logging performed by them.

from pointcosm import RetryPolicy, TimeoutConfig

timeout = TimeoutConfig(connect=5, read=30, write=30, pool=5)
retry = RetryPolicy(max_attempts=3, max_elapsed=10)

Retry is disabled by default. When explicitly enabled, only operations whose reviewed manifest metadata says retry=safe can retry timeout/connect failures or HTTP 429/502/503/504. Mutation, secret, authentication, business and contract failures never retry.

License

Licensed under the Apache License 2.0. The license does not grant permission to use PointCosm trade names, trademarks, service marks or product names except as described by the license.