Metadata-Version: 2.4
Name: outerproduct-sdk
Version: 0.1.14
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, compute_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. `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_compute_environment(
    image.name,
    cpu=1,
)

compute_environment = client.get_runtime_handle(created.name)


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


async def add_twice(
    runtime: op.OuterProductClient,
    left: int,
    right: int,
) -> int:
    pending = await runtime.submit(add, left, right)
    first = await pending.refresh()
    return await runtime.compute(add, first.result(), right)


run = await compute_environment.submit(add_twice, 20, 22)
result = await compute_environment.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. ComputeEnvironments are immutable snapshots. Their `create_compute_environment()`,
`get_compute_environment()`, and `list_compute_environments()` 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. Inside a
computed function, `runtime.submit()` and `runtime.compute()` start child
computations in the same compute environment. Their result types remain
`Run[T]` and `T`, respectively.

Unity Catalog CRUD remains part of the flat Workspace API, including on the
client injected into managed computations. The flattened methods retain the
generated Unity Catalog signatures for static type checkers. Temporary
table/volume/path/model credentials, Files, Flight SQL, compute_environments,
and runs are flat Workspace methods too. 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. ComputeEnvironment
`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.

