Lattica Studio

Build, deploy, and serve fully homomorphic encryption (FHE) models on the Lattica platform, from a PyTorch-style pipeline definition to an encrypted inference endpoint.

Your data is encrypted before it leaves the client and stays encrypted throughout inference. The server computes on ciphertext and never sees the plaintext input, the plaintext output, or your secret key.

Inference runs on cloud-hosted GPU accelerators, which can significantly reduce latency versus many CPU-only FHE setups. You also avoid managing custom CUDA kernel compilation yourself.

This repository contains three Python packages:

Package	Role
lattica-build	Define a homomorphic computation graph, bind weights, plan FHE parameters, and emit a deployable artifact. Runs entirely locally.
lattica-studio	Deploy and compile that artifact on the platform, then manage models, workers, and query tokens.
lattica-query	Generate keys, encrypt inputs, execute encrypted queries, and decrypt results locally.

Both require Python 3.11+.

How it fits together

       ┌─────────────────────────┐
       │      lattica-build      │   define pipeline + FHE params
       │        (local)          │   →  artifact.zip
       └────────────┬────────────┘
                    │
                    ▼
       ┌─────────────────────────┐
       │     lattica-studio      │   deploy → compile → start GPU worker
       │   (control plane API)   │   →  model_id, query token
       └────────────┬────────────┘
                    │
                    ▼
       ┌─────────────────────────┐
       │      lattica-query      │   keygen, encrypt, query, decrypt
       │  (client, holds the SK) │   →  plaintext result
       └─────────────────────────┘

The secret key never leaves the client. Only the evaluation key and ciphertexts are sent to the server.

Installation

pip install lattica-studio

This pulls in lattica-build (pipeline construction) and lattica-query (client-side encryption and querying) as dependencies.

To work from a checkout of this repository:

pip install -e ./lattica_build_src
pip install -e ./lattica_query_src
pip install -e ./lattica_studio_src

Quickstart

1. Build an artifact locally

No account needed for this step. Build the packaged MNIST example:

lattica-build --pipeline-module lattica_build.examples.advanced.mnist_fc --out mnist.zip

On success the command writes mnist.zip and prints a JSON summary listing hom_pipeline.json and hom_pipeline.safetensors.

Add --print_graph to inspect the computation graph, or point at your own file:

lattica-build my_pipeline.py --out my_pipeline.zip

Any pipeline module or file just needs to expose two callables:

def build_pipeline() -> HomomorphicPipeline: ...
def build_params() -> HomParams: ...

2. Deploy, serve, and query

The remaining steps need a Lattica account license key. Set it once:

export LATTICA_LICENSE_KEY="..."

import os

import torch

from lattica_build import build
from lattica_build.examples.advanced import mnist_fc
from lattica_query import QueryClient
from lattica_studio import LatticaStudio

x = torch.zeros(mnist_fc.INPUT_SHAPE)

# Build locally, then deploy and compile on the platform.
mnist = mnist_fc.Pipeline()
artifact = build(
    mnist.build_pipeline(),
    mnist.build_params(),
    "mnist.zip",
)
with LatticaStudio(os.environ["LATTICA_LICENSE_KEY"]) as studio:
    model_id = studio.deploy(artifact, "my-mnist-model")

    # A GPU worker must be running to serve encrypted queries.
    with studio.workers.running(model_id, stop_on_exit=True):
        token = studio.tokens.create(model_id, name="my-mnist-model", save=True)

        with QueryClient(token) as client:
            # Generates FHE keys and uploads the evaluation key.
            # The secret key never leaves this machine.
            sk = client.keys.ensure()

            # x is a plain torch tensor shaped like the pipeline's input.
            result = client.query.encrypted(x, key=sk)
            print(result.argmax(dim=-1))

studio.deploy_pipeline(...) combines the build and deploy steps if you don't need the artifact on disk:

model_id = studio.deploy_pipeline(
    mnist.build_pipeline(),
    mnist.build_params(),
    "my-mnist-model",
)

Deploying under a name that already exists redeploys into that model rather than creating a duplicate. Active workers are stopped and the model is recompiled.

A complete, runnable version of the flow above lives in lattica_studio_src/lattica_studio/example.py.

Display tables quickly

If you just want to inspect resources in a printable table, use the helper script:

cd lattica_studio_src
python -m lattica_studio.list_and_display models
python -m lattica_studio.list_and_display workers
python -m lattica_studio.list_and_display tokens
python -m lattica_studio.list_and_display all

It uses LATTICA_LICENSE_KEY by default (or pass --license-key ...).

Working efficiently

Worker runtime is billed while a worker is up, so keep workers running only as long as you are actually serving queries. The studio.workers.running(model_id, stop_on_exit=True) context manager stops the worker on exit, including when the block raises.

Two things to keep in mind while iterating:

• Changing the pipeline architecture invalidates the key context. Redeploy, then create a fresh token and regenerate keys before querying again.
• Reuse a compiled model across sessions. Deployment and key setup only need to happen when the pipeline changes. To query an existing model, look it up by name with studio.models.get_id_by_name(...) and reuse a saved token with studio.tokens.load(...).

API overview

LatticaStudio exposes deployment directly and groups everything else by resource.

Deployment

studio.deploy(artifact, model_name, instance_type=..., num_devices=1)
studio.deploy_pipeline(
    pipeline,
    params,
    model_name,
    instance_type=...,
    num_devices=1,
    display_graph=False,
)

Both register (or reuse) the model, upload the artifact, and block until compilation finishes, raising CompilationError or CompilationTimeoutError if it doesn't.

studio.models

studio.models.list()                       # → list[Model]
studio.models.get_by_id(model_id)          # → Model
studio.models.find_by_name(name)           # → Model | None
studio.models.get_by_name(name)            # → Model
studio.models.update(model_id, ...)        # name, description, visibility, instance_type, ...
studio.models.activate(model_id)
studio.models.deactivate(model_id)
studio.models.set_visibility(model_id, visibility)
studio.models.display(studio.models.list())    # printable table

studio.workers

studio.workers.running(model_id, stop_on_exit=True)   # context manager (preferred)
studio.workers.get_or_start(model_id)                 # reuse a ready worker, else start one
studio.workers.start(model_id)                        # blocks until ready
studio.workers.active(model_id)
studio.workers.stop(model_id=..., session_id=...)
studio.workers.list_sessions(model_id=..., from_date=..., to_date=...)

studio.tokens

studio.tokens.create(model_id, name=None, save=False)     # save=True caches it locally
studio.tokens.load()                                      # newest cached token
studio.tokens.load(name)                                  # newest cached token with this name
studio.tokens.get(token)                                  # → TokenInfo
studio.tokens.list(status=..., model_id=...)
studio.tokens.assign(token_id, model_id)
studio.tokens.unassign(token_id, model_id)
studio.tokens.update(token_id, name=..., note=..., status=...)
studio.tokens.delete(token_id)

studio.account / studio.finance

studio.account.get()
studio.account.update(company_name=..., contact_name=..., email=..., phone_number=...)
studio.finance.get_credits()
studio.finance.list_transactions()

Instance types

Pass an InstanceType to deploy, deploy_pipeline, or models.update:

from lattica_studio import InstanceType

studio.deploy(artifact, "my-model", instance_type=InstanceType.G7E_2XLARGE)

Instance type	Compute class
G4DN_XLARGE	GPU
G7E_2XLARGE	GPU (default)

num_devices defaults to 1 and is fixed when a model is created. Redeploying an existing model name with a different value raises ValueError; use a new model name to change the device count.

Errors

Studio-specific failures derive from LatticaStudioError. Shared credential, HTTP, protocol, and storage failures derive from LatticaClientError:

from lattica_query import LatticaClientError
from lattica_studio import LatticaStudioError

Individual subclasses such as CompilationError and WorkerStartupTimeoutError are exported by lattica_studio when you want to handle a specific failure.

Repository layout

lattica_build_src/          # lattica-build package
  lattica_build/
    base_classes/           # HomomorphicPipeline, HomOp, tracing, graph printing
    operators/              # FHE, polynomial, shape, comparison, composite ops
    params/                 # FHE parameter planning, level/scale budgeting
    examples/               # runnable pipeline definitions
    build.py                # build() API and lattica-build CLI

lattica_studio_src/         # lattica-studio package
  lattica_studio/
    studio.py               # LatticaStudio entry point
    deployment.py           # deploy / compile orchestration
    resources/              # models, workers, tokens, account, finance
    types.py                # Model, Worker, TokenInfo, InstanceType
    exceptions.py
    example.py              # end-to-end reference script

Deeper documentation lives alongside the code:

Topic	Doc
Runnable pipeline examples	examples/README.md
Pipeline API and data binding	base_classes/README.md
Operator composition model	operators/README.md
FHE level and scale planning	params/README.md

Troubleshooting

CompilationError right after deploy. The pipeline built locally but the backend rejected it. The exception message includes the backend's compilation error. Check FHE parameter budgets first, see params/README.md.

WorkerStartupTimeoutError. A worker on a running box is ready in roughly 20 seconds; a new box can take up to 30 minutes, which is how long start waits by default. On timeout the worker is stopped and its credits come back; retry, or set studio.workers.start(model_id, timeout=...).

Queries fail after a redeploy. Changing the pipeline invalidates the key context. Create a fresh token and regenerate keys.

ResourceNotFoundError from get_by_name. The model name doesn't exist on this account. List what's there with studio.models.display(studio.models.list()).

License

Each package is distributed under the license in its own directory:

• lattica_build_src/LICENSE.md
• lattica_studio_src/LICENSE.md

Please read the applicable license before use.

Copyright © LatticaAI Inc. All rights reserved.