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 OpenAPI snapshot contains 16 paths, 21 public operations and 41 referenced schemas. It declares standard ApiFailureResponse responses for HTTP 401, 403 and 500 on all 21 public operations, plus HTTP 422 on all 17 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 currently approved input is contracts commit 5d6ba3b08ff0e6c072a9d93599316154973d229b, bundle 0.6.0, bundle SHA adf87bc23ea2b25421e8edad054f1ba42884b1abd098718bdf6bb1383b5d6b33:

uv run python scripts/import_contract_bundle.py \
  /path/to/pointcosm-sdk-contracts \
  --revision 5d6ba3b08ff0e6c072a9d93599316154973d229b \
  --bundle-release 0.6.0 \
  --bundle-sha256 adf87bc23ea2b25421e8edad054f1ba42884b1abd098718bdf6bb1383b5d6b33 \
  --customer-sha256 11d6e486681d43b8eb825fb5ff91440d3cce2151ba3b6aa09585ffa6f238f363 \
  --auth-sha256 ff17917c6ccab2fcf1cb6c2ee0392c2efea6dfca567d084a6434836c36c489cf
uv run python scripts/validate_auth_openapi.py openapi/auth-public.openapi.json
uv run python scripts/generate.py --check

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.

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.