Metadata-Version: 2.4
Name: outerproduct-sdk
Version: 0.1.12
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 runs, data, sandboxes, 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()

base_image = (await workspace.list_images())[0]
image = await workspace.build_image(
    base_image.name,
    display_name="analytics",
    description="Pinned analytics dependencies",
    pypi_dependencies=("numpy==2.3.2", "polars>=1.33"),
)
created = await workspace.create_sandbox(
    image.name,
    cpu=1,
)

sandbox = workspace.get_runtime_handle(created.name)


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


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

await workspace.write_file("results/answer.txt", str(result).encode())
answer = await workspace.read_file("results/answer.txt")
```

Images are immutable registry artifacts. `build_image()` layers canonical
PyPI requirements onto an existing workspace image and returns only after the
new digest is published. Sandboxes are immutable snapshots. Their `create_sandbox()`,
`get_sandbox()`, and `list_sandboxes()` 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, sandboxes, and runs are all flat Workspace methods. JSON
literals, objects implementing the SDK serialization contract, and Pydantic
models can cross run boundaries.

## Storage boundaries

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

