Pointcosm Python SDK

简体中文 | English

Status: implementation is complete for local validation. This package has not been published and is not approved for production use.

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.
• Building local wheel or sdist artifacts is allowed for validation only.
• Uploading to TestPyPI or PyPI, creating a public tag or release, and declaring production readiness require separate 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 17 paths, 25 public operations and 45 referenced schemas. It declares standard ApiFailureResponse responses for HTTP 401, 403 and 500 on all 25 public operations, plus HTTP 422 on all 21 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 1df69d43b6ac571b31f1c6c67d7d2df38742947d, bundle 0.5.0, bundle SHA 8b948c05f25016b0da7957a3791936d85a15a945bfdc25de4befb43806f75a22:

uv run python scripts/import_contract_bundle.py \
  /path/to/pointcosm-sdk-contracts \
  --revision 1df69d43b6ac571b31f1c6c67d7d2df38742947d \
  --bundle-release 0.5.0 \
  --bundle-sha256 8b948c05f25016b0da7957a3791936d85a15a945bfdc25de4befb43806f75a22 \
  --customer-sha256 34c9aa8d5a59ef4e54a3c5960eba9326b01045db493a57332aa07df256e8c9f6 \
  --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.

Installation

The project is not published yet. 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. Production use is not approved.

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="train-platform-api",
)
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.