Metadata-Version: 2.4
Name: outerproduct-sdk
Version: 0.1.11
Requires-Dist: adbc-driver-flightsql[dbapi]>=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 Workspace API, runtime serialization, Files, Unity Catalog adaptation,
Flight SQL, and UC-governed object storage. Its client hierarchy has two
levels: `OuterProductClient` manages Workspaces, and `WorkspaceClient` owns all
UC and non-UC resource operations for one selected Workspace.

## Natural workspace API

The client is an authenticated session, not a workspace. `workspace(name)`
resolves or provisions a Workspace resource within the authenticated
organization and uses its separate UUID for workspace-owned APIs. Omitting the
name ensures and selects `workspaces/default`.

```python
from outerproduct_sdk import OuterProductClient, WorkspaceClient

client = OuterProductClient("token")
workspace = client.workspace()
catalogs = workspace.list_catalogs()
created = await workspace.create_environment(
    f"workspace/{workspace.id}/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.write_file("results/answer.txt", str(result).encode())
answer = await workspace.read_file("results/answer.txt")
```

Environments are immutable snapshots. Their `create_environment()`,
`get_environment()`, and `list_environments()` lifecycle methods live directly
on the Workspace client. `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.

Unity Catalog CRUD, temporary table/volume/path/model credentials, Files,
Flight SQL, environments, and workflows are all flat Workspace methods. JSON
literals, objects implementing the SDK serialization contract, and Pydantic
models can cross workflow boundaries.

## Storage boundaries

File operations are flat methods on the workspace-scoped client. 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.

