Python SDK

Overview

The SDK is a thin HTTP client that talks to the Semphony control server. You use it to start or resume experiments (runs), open sessions, attach devices by slug or ID, and invoke capabilities such as imaging acquire, stage move, or vacuum control. It is aimed at experimental scientists and engineers who want to automate in-situ workflows from Python without building their own REST calls.

Installation

Install the package with pip. The core SDK only requires requests.

pip install semphony

Optional extras:

• pip install semphony[find-roi] — for imaging.find_roi() (adds opencv-python and numpy).
• pip install semphony[autofocus] — for imaging.autofocus() (adds torch and torchvision).
• pip install semphony[examples] — for running the example notebooks (adds Jupyter and python-dotenv).

Quick start

Create a client with your control server URL and API key (from the Semphony dashboard), then create or resume a run, start a session, attach an imaging device, and acquire an image.

from semphony import SemphonyClient
from semphony.systems import ImagingDevice
from semphony.models import AcquisitionConfig

client = SemphonyClient(
    base_url="https://semphony-control-server.example.com",
    api_key="your-api-key",
)
tescan = ImagingDevice(client, device_slug="tescan-001")

run = client.run("my_experiment", resume=True)
with run.session() as s:
    tescan.attach(s)
    result = tescan.acquire(AcquisitionConfig(fov_um=100), download=True)

Core concepts

Client — SemphonyClient(base_url, api_key) holds the server URL and authenticates with a Bearer token. Use it to create runs and (via devices) invoke capabilities.

Run — An experiment instance. Create or resume with client.run(name, resume=True). Optionally pass system=... to target a system.

Session — A session belongs to a run and is when devices are attached and commands are executed. Use with run.session() as s: (session starts on enter, closes on exit) or session = run.session().start() and session.close() for notebooks.

Attach — Before using a device in a session, call device.attach(session). The device then routes capability calls through the client for that run/session.

flowchart LR
    C[SemphonyClient] -->|"run()"| R[Run]
    R -->|"session()"| S[Session]
    S -->|attach| D1[ImagingDevice]
    S -->|attach| D2[DeformationDevice]
    D1 -->|capabilities| API[Control server API]
                    

Explore the SDK