Metadata-Version: 2.4
Name: pointcosm
Version: 0.5.0
Summary: Official Python SDK for the PointCosm customer API
Keywords: pointcosm,sdk,api-client,openapi
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: attrs>=26.1,<27
Requires-Dist: httpx>=0.28.1,<0.29
Maintainer: PointCosm
Requires-Python: >=3.11, <3.15
Project-URL: Repository, https://github.com/pointcosm-studio/pointcosm-python
Project-URL: Issues, https://github.com/pointcosm-studio/pointcosm-python/issues
Description-Content-Type: text/markdown

# Pointcosm Python SDK

[简体中文](README.zh-CN.md) | 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.

```bash
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:

```bash
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/`](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:

```bash
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`:

```bash
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:

```bash
python -m pip install pointcosm
```

For local development:

```bash
uv sync --all-groups
```

## Static Bearer

```python
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.

```python
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](docs/006-python-sdk-guide.zh-CN.md) and the
[public API reference](docs/004-public-api-reference.md).

```python
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.

```python
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](LICENSE). The license does not grant permission to use
PointCosm trade names, trademarks, service marks or product names except as described by the
license.
