Metadata-Version: 2.4
Name: pointcosm
Version: 0.4.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:** 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.

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

```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 `1df69d43b6ac571b31f1c6c67d7d2df38742947d`,
bundle `0.5.0`, bundle SHA
`8b948c05f25016b0da7957a3791936d85a15a945bfdc25de4befb43806f75a22`:

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

```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. Production use is
not approved.

```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="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](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.
