Metadata-Version: 2.5
Name: orislop
Version: 0.1.0
Summary: Typed synchronous and asynchronous client for the Orislop Enterprise API
Project-URL: Homepage, https://orislop.com
Project-URL: Documentation, https://orislop.com/enterprise/docs
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
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: anyio<5,>=4.8
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: pydantic<3,>=2.12
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: mypy<3,>=1.18; extra == 'dev'
Requires-Dist: pip-audit<3,>=2.9; extra == 'dev'
Requires-Dist: pre-commit<5,>=4; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1; extra == 'dev'
Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
Requires-Dist: pytest<10,>=8.3; extra == 'dev'
Requires-Dist: pyyaml<7,>=6; extra == 'dev'
Requires-Dist: ruff<1,>=0.14; extra == 'dev'
Requires-Dist: twine<8,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# Orislop Python SDK

A typed, lightweight Python client for Orislop's enterprise media detection API.
It sends authorized media to the API; it does not include detection models.

**Release status:** 0.1.0 is prepared locally, not published. Enterprise access is
contact-only. The client follows the inspected v1 source contract; a production
inference round trip has not been verified. An unauthenticated usage check on
2026-10-22 returned HTTP 503. Local fixtures do not establish service availability.

## Install

Python 3.10–3.14 is the intended compatibility range. See the validation report
for versions actually tested locally; the CI matrix checks each supported version.

After an owner-approved release:

```sh
pip install orislop
```

Until then, install the reviewed wheel supplied with this repository or use
`python -m pip install .` from this checkout. The PyPI name has not been reserved;
a 404 from its JSON endpoint does not guarantee registration eligibility.

## Authenticate and make a first request

Ask Orislop through its existing enterprise contact process for verified access
and a key with the required scopes. See [Orislop enterprise](https://orislop.com/enterprise).
There is no verified self-service key-issuance endpoint.
Set `ORISLOP_API_KEY` securely in your runtime environment, then:

```python
from orislop import Orislop

with Orislop() as client:
    usage = client.usage()
    print(usage.month)
```

You can also use `Orislop(api_key="YOUR_API_KEY")`. Never commit a real key.
The older standalone integration's `ORISLOP_API_TOKEN` variable is not read by
this SDK; migrate it explicitly to `ORISLOP_API_KEY`.

## Submit a video and retrieve its result

Only run this example with media you are authorized to submit. Successful
analyses may incur charges under your enterprise agreement.

```python
from uuid import uuid4
from orislop import Orislop

# Persist this key and the upload ID when using the explicit workflow below.
key = str(uuid4())
with Orislop() as client:
    analysis = client.detect_and_wait(
        "video.mp4",
        content_type="video/mp4",
        idempotency_key=key,
        poll_interval=2.0,
        max_wait=300.0,
    )
    if analysis.status == "completed" and analysis.result is not None:
        print(analysis.result.model_score, analysis.result.assessment)
        print(analysis.result.limitations)
    else:
        print("Analysis did not complete successfully:", analysis.status)
```

A score is a 0–100 model signal, not a probability or proof of media provenance.
Supported types are JPEG, PNG, WebP, MP4, WebM, and MOV. Arbitrary remote video
URLs are not supported. There is no server cancellation method in this contract.

For durable integrations, persist the upload ID before submitting:

```python
from orislop import Orislop

with Orislop() as client:
    upload = client.upload_file("video.mp4", content_type="video/mp4")
    # Persist upload.upload_id and a durable idempotency key before submission.
    job = client.submit(upload.upload_id, idempotency_key="persisted-request-key-0001")
    # Persist job.id; resume later with client.retrieve(job.id) or client.wait(job.id).
    final = client.wait(job.id, max_wait=300.0)
```

A timeout during submission leaves the outcome ambiguous. Reuse the same
upload ID and idempotency key when you explicitly retry `submit`; do not rerun
the entire upload convenience workflow to recover an uncertain submission.

## Async

```python
import asyncio
from orislop import AsyncOrislop


async def main() -> None:
    async with AsyncOrislop() as client:
        usage = await client.usage()
        print(usage.month)


asyncio.run(main())
```

The async client uses asynchronous HTTP and waiting. Task cancellation stops
local work and propagates normally; it does not cancel an analysis on the server.

## Errors and retries

```python
from orislop import AuthenticationError, Orislop, RateLimitError, ServerError

with Orislop() as client:
    try:
        usage = client.usage()
    except AuthenticationError:
        print("Check key validity and scopes with your administrator.")
    except RateLimitError as error:
        print("Rate limited; request ID:", error.request_id)
    except ServerError as error:
        print("Service unavailable; request ID:", error.request_id)
```

Only safe GET requests retry transient failures automatically, with bounded
exponential backoff and jitter. POST and upload PUT requests are not replayed
automatically. `Retry-After` is honored within the configured delay bound; a
longer server delay ends automatic retrying rather than retrying too early.
Polling has its own time limit. Handle `PollingTimeout` by retrieving the same
job later. See [errors](docs/errors.md) and [configuration](docs/configuration.md).

## Documentation and support

- [Getting started](docs/getting-started.md), [authentication](docs/authentication.md)
- [API reference](docs/api-reference.md), [advanced usage](docs/advanced-usage.md)
- [Troubleshooting](docs/troubleshooting.md), [contract provenance](docs/contract.md)
- [Public enterprise API documentation](https://orislop.com/enterprise/docs)
- [Release and Trusted Publishing runbook](docs/releasing.md)
- [Contributing](CONTRIBUTING.md), [security reporting](SECURITY.md)

Use this repository's issue tracker for reproducible SDK bugs after the official
repository is created. Keep credentials, signed URLs, and customer media out of
issues. Use the existing enterprise contact channel for account and service
access. No security contact address is invented here.

Pre-1.0 minor versions may change the public interface; patch versions aim to
remain compatible. The client-only SDK is licensed under [Apache-2.0](LICENSE).
See [license scope](docs/license-decision.md) and [NOTICE](NOTICE). API access
and service usage are governed separately from the SDK's software license.
