Getting started¶

Install¶

pip install ascribe-link

For AI agent generation (see AI agent generation), install the optional extra:

pip install "ascribe-link[agent]"

From a source checkout:

git clone https://github.com/lbl-camera/ascribe-link.git
cd ascribe-link
pip install -e ".[test]"

Run the server¶

Installing puts an ascribe-link console script on your PATH:

ascribe-link

The server binds 0.0.0.0:8000 by default. Check that it came up:

curl http://localhost:8000/api/specimens/
curl http://localhost:8000/api/processing/functions

Command-line options¶

See Federation for relay and worker modes.

Embed it in your own application¶

create_app() returns a configured Litestar app, so you can register your own functions and serve them with any ASGI server:

import uvicorn

from ascribe_link import create_app
from ascribe_link.models import MeshResult


def my_function(param1: float = 1.0, param2: int = 32) -> MeshResult:
    ...  # generate a mesh
    return MeshResult(vertices=..., indices=...)


app = create_app(
    specimens_dir="/data/specimens",
    mesh_functions={"my_function": my_function},
)

uvicorn.run(app, host="0.0.0.0", port=8000)

create_app() accepts:

specimens_dir

Directory of specimen bundles to scan. Defaults to ./specimens.

mesh_functions

Mapping of name → callable, registered as processing functions.

relay_mode

Accept worker connections and aggregate their catalogs.

enable_agent, agent_model, agent_timeout

AI agent generation — see AI agent generation.

Specimen directory layout¶

Each specimen is a subdirectory holding a specimen.json metadata file, a thumbnail, and (for static specimens) a data file:

specimens/
├── brain/
│   ├── specimen.json   # metadata
│   ├── brain.stl       # data file
│   └── thumbnail.png   # preview image
└── parametric_sphere/
    ├── specimen.json   # metadata with schema + function_name
    └── thumbnail.png

The directory is scanned at startup. GET /api/specimens/reload re-scans it without a restart.

Run the tests¶

pip install -e ".[test]"
pytest