Metadata-Version: 2.4
Name: mini-oss-osdk
Version: 0.1.0a4
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 canonical Object Query, Engine-backed SQL diagnostics, Operation polling and bounded Result Gateway access. `0.1.0a4` adds `explain()` while retaining the unified `OSDKClient` facade and low-level `ObjectEngineClient`/`ResultGatewayClient` APIs.

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

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

## Explain a query without executing it

```python
from mini_oss_osdk import Field, ObjectSet, OSDKClient

query = (
    ObjectSet.base("Restaurant")
    .where(Field("city").eq("Los Angeles"))
    .fetch_page(select=("name", "city"), page_size=25)
)

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(
        namespace_id="01jabcdefgh2",
        query=query,
    )
    print(explanation.athena_sql)
```

`explain()` delegates binding, planning and SQL rendering to Object Engine. It returns `ExplainResult` with Catalog 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:
    restaurant = await client.ontology.objects.object(
        "01jabcdefgh2", "Restaurant"
    ).get(
        "restaurant-001",
        select=("name", "city"),
    )

    if restaurant is not None:
        print(restaurant.rid, restaurant.primary_key, restaurant["name"])
```

`get()` only orchestrates canonical lookup → execute → wait → bounded Result page. It never reads Dataset/Redash/Athena metadata or creates SQL. 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. A local wait timeout does not cancel the server Operation.

Generated ontology-specific classes are not implemented.

## Distribution verification

```bash
python -m unittest discover -s tests
python -m ruff check src tests scripts
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.

## 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.
