Metadata-Version: 2.4
Name: mini-oss-osdk
Version: 0.1.0a8
Summary: Async Python client and object facade for the ITEM Mini-OSS runtime
License-Expression: LicenseRef-Proprietary
Keywords: item,ontology,osdk,object-query
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.9
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: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Dynamic: license-file

# Mini-OSS Python OSDK

Async Python builder/runtime for the canonical Object Query, Engine-backed SQL
diagnostics, Tenant-scoped Operation polling and bounded Result Gateway access.
Version `mini-oss-osdk==0.1.0a8` consumes the `1.0.0-alpha.8` contract.
It is a breaking upgrade from `0.1.0a4`: use qualified builders and Tenant routes;
old queries and Operation/Result lineage are not migrated automatically.
Python 3.9+ remains supported. Install the exact Alpha.8 version:

```bash
python -m pip install --upgrade "mini-oss-osdk==0.1.0a8"
```

This remains a pre-GA alpha package (not a `.dev` build). Explicit version pinning
is recommended; an unqualified pip upgrade may skip prereleases.

The proprietary public PyPI distribution is available as `mini-oss-osdk`; the
canonical import remains `mini_oss_osdk`.

## Build a qualified cross-Namespace query

Namespace API names are exact, case-sensitive PascalCase programming identifiers.
The first `pivot_to` argument is the Namespace that owns the Link, not the target
ObjectType Namespace. Both arguments are required; the old one-argument builder is
not supported.

```python
from mini_oss_osdk import Field, ObjectSet

query = (
    ObjectSet.base("FlightStage", "Flight")
    .where(Field("flightNumber").eq("SYN-001"))
    .pivot_to("Commerce", "orders")
    .fetch_page(select=("id", "status"), page_size=25)
)
```

The wire request uses the alpha.8 recursive AST and the side-by-side schema URL:
`namespace` and `linkNamespace` contain API names, never Namespace short IDs or
display names. A Link owner may be a third Namespace, for example
`.pivot_to("Scheduling", "assignedFlights")` from `Fleet.Aircraft`.

## Explain a query without executing it

```python
from mini_oss_osdk import OSDKClient

async with OSDKClient(
    tenant_id="01jabcdefgh1",
    object_engine_url="https://object-engine.example.com",
    result_gateway_url="https://object-results.example.com",
    api_key=tenant_api_key,
) as client:
    explanation = await client.explain(query=query)
    print(explanation.athena_sql)
    print(explanation.manifest_id, explanation.manifest_content_hash)
```

`explain()` delegates binding, planning and SQL rendering to Object Engine. It
returns `ExplainResult` with alpha.8 manifest lineage, warnings, the logical plan
and generated `athena_sql`; it does not submit Athena, create an Operation or
access Result Gateway. The low-level equivalent is
`ObjectEngineClient.explain(...)`.

Generated SQL can contain source details or business literals. Do not record it in
logs, traces or telemetry.

## High-level object lookup

```python
from mini_oss_osdk import OSDKClient

async with OSDKClient(
    tenant_id="01jabcdefgh1",
    object_engine_url="https://object-engine.example.com",
    result_gateway_url="https://object-results.example.com",
    api_key=tenant_api_key,
) as client:
    flight = await client.ontology.objects.object(
        "FlightStage", "Flight"
    ).get(
        "F001",
        select=("flightNumber",),
    )

    if flight is not None:
        print(flight.rid, flight.namespace_id, flight.namespace_api_name)
        print(flight.primary_key, flight["flightNumber"])
```

`get()` orchestrates qualified canonical lookup → Tenant-scoped Engine execute →
Operation wait → ResultRef lineage validation → bounded Result page. It never
reads Dataset/Redash/Athena metadata, creates SQL, guesses a Namespace from a RID,
or fills missing `$namespaceId`/`$namespace` fields from the lookup entry. Generic
runtime has no Catalog property list, so `select=()` requests identity only;
callers list Property API names explicitly. A future generated ontology package
may provide that static list.

Both service endpoints are required. HTTPS is mandatory except loopback HTTP used
by tests. Configure exactly one public credential: `api_key` for the Tenant API
Key lane or `bearer_token` for the delegated Cognito ID Token lane. A local wait
timeout does not cancel the server Operation. Long and Decimal result values stay
as wire strings, and Result Gateway cursors remain opaque.

## Alpha.8 migration

Alpha.8 is a deliberately breaking runtime switch. Replace Namespace short-ID
arguments with Namespace API names and qualify every base and Link traversal;
move Engine/Operation/Result calls to Tenant routes; and do not reuse alpha.7
Operation, ResultRef, cursor or query wire. See
[`docs/migration-alpha8.md`](docs/migration-alpha8.md) for the mapping and
rejection behavior.

Generated ontology-specific classes are not implemented.

## Distribution verification

```bash
python -m unittest discover -s tests
python -m ruff check src tests
python -m build
python -m twine check dist/*
python scripts/verify_distribution.py dist
```

Branch and `main` pipelines only test and build. A `v<version>` tag is the sole
public PyPI upload authority, and the tag must exactly match wheel metadata before
upload. Installing this client does not deploy services or migrate saved queries.

## License

Proprietary. Copyright (c) 2026 ITEM. All rights reserved. See [`LICENSE`](LICENSE);
public package availability does not grant permission to use, modify, or
redistribute the software.
