Skip to main content

Orca Framework

Preview: not yet released

Orca Framework has not been released yet. These docs are a preview of what it does. There is no public download; access is by request for evaluation only. Get in touch if you'd like preview access or want to follow its progress.

Orca Framework is the runtime that operates a lab. You wire your instruments into a topology once, define your workflows in plain Python, and submit them to a long-running service that schedules them, moves labware between devices, recovers from failures, and reports every event back out for monitoring and external integrations.

For network-accessible AI agent control via MCP, see Swarm, which wraps Orca Framework's runtime with authenticated REST + MCP + WebSocket surfaces.

It runs the same way in simulation and on real hardware, so you can develop and debug without a single instrument plugged in.

What it does for you​

If you are a...Orca Framework gives you...
Lab managerA single system that runs your existing instruments, validated workflows you can trust, and visibility into every run. No need to replace what you already own.
Lab automation engineerA persistent runtime, four Python decorators (@orca.action, @orca.method, @orca.thread, @orca.workflow), and clean integration points for stores, events, and drivers.
IntegratorThree control surfaces in the box — Python API, localhost daemon REST + SSE, and the orca CLI. Build your own service layer on top, or pair with Swarm for authenticated network + MCP access.

What's different from Legacy Orca​

The high-level shape is the same — workflows compose threads, threads compose methods, methods compose actions — but the framework underneath is substantially more capable:

  • Persistent runtime. Long-lived SystemRuntime accepting workflow submissions on the fly. Legacy ran one workflow then exited.
  • Decorated Python authoring. @orca.method, @orca.thread, @orca.workflow. The JSON workflow path is retired. Real IDE, real diffs, real refactors.
  • Reservation-based scheduling with deadlock detection. A wait-for graph catches cycles. Most competitors use static pre-scheduling and brittle conflict resolution.
  • Multi-thread, multi-lineage convergence. Plates converge from independent thread lineages onto shared devices. Co-labware coordination is a first-class concept.
  • Sim-first with three run modes. PURE_SIM, DEVICE_SIM, LIVE. Develop and validate assays with zero hardware. Lazy device init resolved at dispatch.
  • Multi-group submissions. One submission can fan N samples into one shared final plate via GroupSharing.SHARED_ACROSS_GROUPS.
  • Cross-submission batching. Later submissions can join an in-flight BATCHABLE execution. Operators can drip-feed samples over hours into one batched run.
  • Event-driven (EventBus). Every status change fires; external systems subscribe. No polling, no log scraping.
  • Pause / resume / abort. Workflow control at runtime, not just job queueing.
  • Pluggable persistence. ILabwareStore, IIncidentStore, and the teachpoint / deck-layout / profile stores. In-memory or embedded SQLite for dev, DB-backed in prod. Swap without code changes.
  • Fully serializable. System topology, workflows, methods, labware, teachpoints all round-trip through JSON. Git-style diff and version control on the lab itself.
  • Typed ActionContext accessors. Method authors get IDE autocomplete and type checking instead of dict spelunking.
  • Manual-place entry threads. Operator-loaded plates enter the workflow at submission time with typed error envelopes for misuse.

The legacy docs are still available — pick Orca Legacy from the Orca menu in the navbar.

At a glance​

Defining a workflow in Orca Framework looks like this:

import orca.orca as orca
from orca.workflow_models.action_context import ActionContext
from orca.workflow_models.method_context import MethodContext
from orca.workflow_models.thread_context import ThreadContext

@orca.action(device=shaker, inputs=[plate])
async def shake(ctx: ActionContext):
    await ctx.device().shake(duration=30, speed=500)

@orca.method
async def shake_step(ctx: MethodContext):
    yield shake

@orca.thread(start="plate_pad", end="plate_pad", labware=plate)
async def sample_journey(ctx: ThreadContext):
    yield shake_step

@orca.workflow(name="sample_assay")
def sample_assay(wf):
    wf.start(sample_journey)

That's a complete workflow. The runtime takes it from there.

Where to go next​

If you're evaluating, start with Architecture — a one-page tour of how Orca Framework thinks about your lab.

If you're building, jump to Installation then Quick Start.

Need help​