Metadata-Version: 2.5
Name: kova-client
Version: 0.1.0rc9
Summary: Official Python client for the Kova Service API
Project-URL: Documentation, https://github.com/cofy-x/kova/blob/main/docs/service.md#python-sdk
Project-URL: Issues, https://github.com/cofy-x/kova/issues
Project-URL: Repository, https://github.com/cofy-x/kova
Author: Kova Authors
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Description-Content-Type: text/markdown

# kova-client

`kova-client` is the official, thin Python client for the Kova Service HTTP API v1.
It submits immutable sources for bounded image builds and returns server-verified manifest digests and immutable image references.
It does not own workflow recovery, artifact retention, datasets, episodes, or Axern/Axrun domain objects.

```bash
python -m pip install kova-client
```

```python
from kova_client import ClientConfig, CreateBuildRequest, KovaClient, Platform, TargetSpec

config = ClientConfig.from_env()
with KovaClient(config) as kova:
    job = kova.create_build(
        CreateBuildRequest(
            source_uri="oci://registry.example.com/team/sources@sha256:<manifest-digest>",
            source_digest="sha256:<source-content-digest>",
            targets=(
                TargetSpec(
                    target="registry.example.com/team/seed:build-123",
                    platform=Platform.LINUX_AMD64,
                ),
            ),
            concurrency=1,
            idempotency_key="build-123",
        )
    )
    terminal = kova.wait_build(job.id, timeout=600)
    if terminal.status == "succeeded":
        for output in kova.get_results(job.id).outputs:
            print(output.platform, output.immutable_ref, output.manifest_digest)
```

`ClientConfig.from_env()` explicitly reads `KOVA_SERVICE_URL`, `KOVA_SERVICE_TOKEN`, `KOVA_SERVICE_CA_FILE`, and `KOVA_SERVICE_INSECURE`.
Constructing `ClientConfig` or either client never reads a user directory or process environment implicitly.
Use a stable idempotency key if the caller may retry submission; `create_build` itself is never retried.
