Metadata-Version: 2.4
Name: outerproduct-sdk
Version: 0.1.13
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. `OuterProductClient` is the only
public client and owns all UC and non-UC operations for one automatically
selected Workspace.

## Natural workspace API

`op.init()` reads `OUTERPRODUCT_API_KEY` and `OUTERPRODUCT_BASE_URL`, ensures
`workspaces/default`, and returns an already-scoped client. Pass `workspace=`
to select another Workspace; callers never create or unwrap a second client.

```python
import outerproduct_sdk as op

client = op.init()
catalogs = client.list_catalogs()

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

sandbox = client.get_runtime_handle(created.name)


async def add(
    runtime: op.OuterProductClient,
    left: int,
    right: int,
) -> int:
    return left + right


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

await client.write_file("results/answer.txt", str(result).encode())
answer = await client.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 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.

