Orca Framework by Cheshire Labs

Orca Framework is an open-source lab automation scheduler and workflow orchestrator developed by Cheshire Labs. It is designed for biotech and clinical laboratories that want to run parallel, multi-instrument workflows without replacing existing equipment. Workflows are written in plain Python and submitted to a long-lived runtime service that manages scheduling, labware movement, error recovery, and operator intervention across the instruments a lab already owns.

Version 2.3.0 is the current release, available via GitHub. The framework supports three run modes — PURE_SIM, DEVICE_SIM, and LIVE — so assays can be fully built and debugged in simulation before any hardware is connected. The same code runs in simulation and on hardware without modification.

Core Workflow Model

• Workflows are structured using four Python decorators: @orca.action, @orca.method, @orca.thread, and @orca.workflow.
• A workflow is composed of labware threads; each thread represents one piece of labware's path through the lab. Threads are composed of methods, and methods are composed of actions at individual devices.
• Multiple labware threads can run in parallel within a single workflow submission, and multiple submissions can be active simultaneously.
• One submission can fan multiple samples into a shared final plate, and later submissions can join an in-flight batchable execution, allowing operators to drip-feed samples over hours into a single run.
• Standalone methods can be executed independently without running a full workflow.

Scheduling and Runtime Behavior

• The runtime is a long-lived SystemRuntime that accepts workflow submissions at any time; it does not exit after a single run.
• Scheduling is reservation-based: devices and labware positions are reserved as threads progress, not scheduled up front.
• Resource pools allow an action to target a pool of equivalent devices, with the runtime selecting a free device at dispatch time.
• Deadlock detection identifies knots in the wait-for structure and instructs one thread to yield and move its labware out of the way. Situations that cannot be resolved automatically are caught by a stall detector, which pauses the run and presents the operator with actionable items.
• Co-labware coordination is a first-class concept, supporting scenarios where labware from independent threads converges at a shared device.
• Individual labware threads can be paused, resumed, or stopped without affecting other threads in the same run.

Operator and Error Management

• A single consolidated list surfaces everything stopping a run — device faults, error-paused threads, paused executions, and labware awaiting human action — each entry accompanied by the remedies that clear it.
• Operators can take over a device mid-run; the runtime holds the device so the scheduler cannot intervene, and every manual command is recorded against the run.
• Commands that would overwrite the driver's record of labware position are refused, with the refusal identifying the correct verb that writes both the driver and the record together.
• Operators can place labware types that were never declared in the workflow by naming the catalog type.
• The instrument gets a vote: if a liquid handler reports a deck state that disagrees with the runtime record, the discrepancy is raised as an incident rather than silently overwritten.
• An event bus fires on every status change, allowing external systems to subscribe without polling or log scraping.

State, Storage, and Calibration

• Labware positions, well volumes, incidents, and calibration data live in swappable stores. The default stores are in-memory; plugging in a database-backed store enables state persistence across process restarts.
• State restored after a restart is flagged for operator confirmation.
• Calibration data — teachpoints, deck layouts, access configs, grip profiles, move defaults, and labware catalog entries — lives outside source files and is read and edited through the API or CLI, keeping it separate from version-controlled workflow code.
• Workflows, methods, and topology remain in Python files that are diffed and reviewed through standard source control.

Interfaces and Integration

• Orca Framework exposes three interfaces: a Python API, a localhost daemon over REST and SSE, and the orca CLI.
• The daemon listens on localhost by default. A companion product, Orca AI, wraps the same runtime with authenticated REST, MCP, and WebSocket surfaces for AI agents, dashboards, or other networked machines.
• The event bus supports custom integrations by allowing external systems to subscribe to status change events.

Supported Instruments and Data Types

• The framework coordinates common laboratory devices including liquid handlers, shakers, centrifuges, sealers, and plate readers.
• It manages labware movement between instruments and tracks labware state, well volumes, and deck positions across the run.

Orca Framework is available as open-source software. Legacy documentation for prior versions remains accessible, and the architecture is designed so that existing instrument investments are preserved rather than replaced.