Metadata-Version: 2.4
Name: outerproduct-sdk
Version: 0.1.9
Requires-Dist: adbc-driver-flightsql>=1.8,<2
Requires-Dist: cloudpickle==3.1.2
Requires-Dist: obstore>=0.11,<1
Requires-Dist: pydantic>=2.13.4,<3
Summary: High-level OuterProduct SDK for workflows, data, environments, and Unity Catalog.
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# OuterProduct SDK

`outerproduct-sdk` is the sole public Python package for OuterProduct. It owns
the natural workspace API, the recovered workflow API, runtime serialization,
Files, Unity Catalog adaptation, Flight SQL, and UC-governed object storage.
Generated clients are private transport details inside one aggregate native
extension and are not re-exported from the package root.

## Natural workspace API

An API token selects one workspace, so `workspace()` takes no arguments.

```python
from outerproduct_sdk import OuterProductClient, WorkspaceClient

client = OuterProductClient("token")
workspace = client.workspace()
created = await workspace.environments.create(
    "containerImages/00000000-0000-0000-0000-000000000001",
    cpu=1,
)

environment = workspace.get_runtime_handle(created.name)


async def add(
    runtime: WorkspaceClient,
    left: int,
    right: int,
) -> int:
    return left + right


run = await environment.submit(add, 20, 22)
result = await environment.compute(add, 20, 22)

await workspace.files.write("results/answer.txt", str(result).encode())
answer = await workspace.files.read("results/answer.txt")
```

Environments are immutable snapshots. Their collection implements the full
server lifecycle: `create()`, `get()`, and `list()`. `submit()` returns after
the scheduler acknowledges a durable computation. `compute()` submits and
polls to a terminal state, yielding to asyncio between polls. Natural computed
functions are async and receive their runtime workspace as the first positional
parameter.

## Recovered workflow API

The prior attached-function workflow remains available. It shares the same
private transport and value codec as the natural API.

```python
import outerproduct_sdk as op


async def main() -> None:
    async with op.init() as client:
        environment = client.execution.environment(
            "environments/00000000-0000-0000-0000-000000000000"
        ).get()

        @environment.fn
        def child(value: int, *, client):
            return value * 2

        @environment.fn
        async def parent(value: int, *, client):
            return await client.run(child, value)

        result = await client.run(parent, 21)
```

`Client` also exposes Unity Catalog CRUD as `client.uc` and through direct
delegation, temporary table/volume/path/model credentials, lazy `client.sql`,
and the newer `client.workspace()` API. JSON literals, objects implementing the
SDK serialization contract, and Pydantic models can cross workflow boundaries.

## Storage boundaries

`workspace.files` is the workspace-scoped durable Files service. Environment
`volumes` map Unity Catalog volumes to container paths and are materialized for
each managed invocation; they are not a provider-native POSIX mount or a
write-back filesystem.

Use `store_from_url`, `store_from_volume`, `store_from_table`, or
`store_from_path` for refresh-aware UC-governed object stores.
`download_s3_prefix(client, prefix, target)` securely streams such a prefix
into a local directory with bounded concurrency.

## Packaging

The published distribution is one wheel with one native extension. Internal
serialization and UC object-store Python sources are vendored under
`outerproduct_sdk._vendor`; the wheel has no dependency on separately
published OuterProduct client packages. Third-party runtime dependencies remain
ordinary wheel dependencies.

