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.

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,
    provider=op.ComputeEnvironmentProvider.MODAL,
    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 control plane accepts the root Attempt of 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.

Workspace files

op.init() creates a Python FileStore automatically. On the first file operation it reads the workspace's existing JSON metadata and derives the workspace-files sibling of its managed storage root. It uses the client's UC credential-vending methods and the existing obstore credential providers. Cloud file bytes travel directly between the SDK process and object storage.

import outerproduct_sdk as op

client = op.init()
await client.upload_file("/models/weights.bin", "weights.bin")
await client.download_file("/models/weights.bin", "downloaded.bin")
entries = await client.list_directory("/models")

await client.write_file("/notes.txt", b"hello")
contents = await client.read_file("/notes.txt")

Uploads and downloads handle chunking internally. Uploads use bounded multipart concurrency and attempt to abort unfinished uploads on failure or cancellation. Downloads write to a temporary file and replace the destination only after completion. Directory listing returns a normal list and handles pagination internally; recursive, start_after, and max_results control the selection.

Writes support atomic create-only and ETag preconditions. Hash preconditions are rejected; a supplied content hash is checked against the bytes before writing. Local filesystem stores do not persist content-type or hash metadata. Empty directories use the server-compatible .outerproduct-directory marker.

Tests can inject an isolated store with op.init(_filestore=op.FileStore(MemoryStore())), importing MemoryStore from obstore.store. Normal initialization requires no storage configuration. Managed runtime clients continue to use their existing host file capability; the direct file-transfer methods are available on clients created by op.init().

Serve a Hugging Face model

Create an inference endpoint with a Hugging Face repository and revision. The endpoint downloads the model directly during initialization, loads it in vLLM, and captures its CPU/GPU snapshot for subsequent restores.

import outerproduct_sdk as op

client = op.init()
images = await client.list_images()
image = next(image for image in images if image.display_name == "inference")
endpoint = await client.create_inference_endpoint(
    "Qwen chat",
    image.name,
    "Qwen/Qwen3-0.6B",
    revision="c1899de289a04d12100db370d81485cdf75e47ca",
    gpu="L4",
)

revision defaults to main; pass a full commit hash to select the same files across separately created endpoints. Endpoint creation returns while provisioning runs. Refresh the endpoint until its status is READY, then use its openai_base_url for OpenAI-compatible requests. Download or model-loading failures leave the endpoint FAILED with an error.

For authenticated downloads, create a Unity Catalog secret in the same workspace before creating the endpoint:

import os

client.create_secret(
    name="my_huggingface",
    values={"HF_TOKEN": os.environ["HF_TOKEN"]},
)
endpoint = await client.create_inference_endpoint(
    "Qwen chat",
    image.name,
    "Qwen/Qwen3-0.6B",
    gpu="L4",
    hf_token_secret="my_huggingface",
)

hf_token_secret defaults to "hf_token". Endpoint creation reads the current HF_TOKEN value from the named secret in this workspace and injects it into the endpoint's environment. If the secret or key is absent, no token is supplied. Catalog lookup errors fail endpoint creation. The token is not stored in the endpoint resource or returned by the API. Rotating the secret applies to newly created endpoints; existing endpoints keep their deployed value.

Storage boundaries

File operations are flat methods on the workspace-scoped client. Sources and volume bindings belong to individual Calls and do not affect environment builds:

from outerproduct_sdk import WorkspaceSources

env = client.get_runtime_handle(compute_environment.name)
env = env.with_source(WorkspaceSources(paths=("/project", "/shared")))
env = env.with_source(WorkspaceSources(paths=("/helpers.py",)))  # appends
env = env.with_volumes({"/data": "main.default.training"})


async def child(runtime):
    import helpers

    return helpers.compute()


async def parent(runtime, child_environment_name):
    # Children declare their own sources and volumes, even in the same environment.
    child_env = runtime.get_runtime_handle(child_environment_name).with_source(
        WorkspaceSources(paths=("/child-project",))
    )
    return await child_env.compute(child)


result = await env.compute(parent, compute_environment.name)

WorkspaceSources accepts up to 64 absolute, normalized Workspace Files paths. Each directory's entire contents merge into a temporary working directory; a single file is placed under its basename. Hidden files, binary files, and empty directories are preserved. Shared directories merge; duplicate files and file/directory conflicts fail before user code executes. Repeated .with_source calls append in order and return new handles.

The worker downloads sources after claiming the Call and before deserializing the callable. The working directory becomes cwd and is prepended to sys.path and PYTHONPATH. Files are read at execution time using the Call's credentials; these references are live reads, not immutable snapshots or local file uploads. There is no package detection or dependency resolution. Install dependencies through the Image as usual.

.with_volumes accepts up to 16 bindings from absolute container destinations to catalog.schema.volume names. Duplicate, overlapping, or already occupied destinations fail. Volumes are downloaded using credentials for the current Call; these are temporary directories, without write-back to storage. Source files and volume destinations are removed on completion, failure, or cancellation, and the previous working directory and Python paths are restored. Children inherit neither sources nor volume bindings. Configured handles retain their client; construct child handles through the injected runtime client.

Use store_from_url, store_from_volume, store_from_table, store_from_path, or store_from_model_version 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.