Procaaso SEAMS SDK
Version 1.1.1
A Python SDK for building distributed process control systems using the Procaaso Seam Interface Specification v1.0. Enables event-based communication between containerized services through standardized seam contracts.
Features
- 5 Standard Contracts: Actuator, Sensor, Unit, Driver, and APP contracts per ISA-88
- Idempotent Commands: Built-in command deduplication and replay protection
- State Management: Automatic seam state synchronization via sidecar
- Type Safety: Pydantic models for all seam attributes
- Async/Await: Full asyncio support for non-blocking operations
- ISA-88 Compliant: Recipe orchestration with APP → Unit → Equipment hierarchy
- Polling & Streaming: Flexible command routing patterns
Installation
pip install procaaso-seams-sdk
Or with Poetry:
poetry add procaaso-seams-sdk
Quick Start
Creating an Actuator Service (Pump)
import asyncio
from procaaso_seams_sdk import ActuatorService
from procaaso_seams_sdk.bus.envelopes import CommandRequest
class PumpService(ActuatorService):
async def handle_command(self, request: CommandRequest) -> None:
cmd = request.command
if cmd == "Start":
await self.update_state(lifecycle_state="Running")
await self.update_feedback(pv=50.0, sp=50.0)
elif cmd == "Stop":
await self.update_state(lifecycle_state="Idle")
await self.update_feedback(pv=0.0, sp=0.0)
# Initialize and run
async def main():
pump = PumpService(
component_id="P01",
bus=bus_adapter,
store=seam_store,
router=bus_router,
log=logger
)
await pump.start()
asyncio.run(main())
Creating a Sensor Service
from procaaso_seams_sdk import SensorService
class TemperatureSensor(SensorService):
async def handle_command(self, request: CommandRequest) -> None:
if request.command == "ResetFault":
await self.update_state(lifecycle_state="Online", faulted=False)
async def read_sensor(self):
# Simulate reading
temperature = 25.5
await self.update_value(pv=temperature, quality="GOOD")
asyncio.run(main())
ISA-88 Recipe Controller (APP Service)
from procaaso_seams_sdk import APPService
class RecipeController(APPService):
async def handle_command(self, request: CommandRequest) -> None:
if request.command == "LoadRecipe":
recipe_id = request.args[0]["recipe_id"]
await self.update_state(
lifecycle_state="RecipeLoaded",
loaded_recipe_id=recipe_id
)
elif request.command == "StartRecipe":
await self.update_state(lifecycle_state="Running")
await self.execute_recipe()
Architecture
┌─────────────────────────────────────────────────────────────┐
│ MES / HMI / SCADA │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ APP (Recipe Controller) │
│ Uses: APPService, UnitClient │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Unit (Batch Controller) │
│ Uses: UnitService, ActuatorClient, SensorClient │
└──────────────────────────┬──────────────────────────────────┘
│
┌────────────┴────────────┐
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ Actuators (P/V/M) │ │ Sensors (T/P/F) │
│ ActuatorService │ │ SensorService │
└──────────────────────┘ └──────────────────────┘
Contract Overview
| Contract | Purpose | Key Attributes |
|---|---|---|
| Actuator | Controllable devices (pumps, valves, motors) | meta, state, capabilities, feedback, intent, cmd |
| Sensor | Measurement devices | meta, state, value, scaling, capabilities, cmd |
| Unit | Process control logic (ISA-88 Unit Procedure) | meta, state, intent, waiting_on, cmd, outcome |
| Driver | I/O hardware with multiple channels | meta, state, capabilities, inventory, cmd |
| APP | Recipe orchestration (ISA-88 Master Recipe) | meta, state, cmd |
Examples
The SDK includes 15+ working examples demonstrating:
- Simple Examples: Basic pump, sensor, and valve services
- TFF System: Complete tangential flow filtration demo with ISA-88 coordination
- Advanced Patterns: Polling routers, control loops, multi-phase recipes
See the examples/ directory and examples/README.md for details.
Documentation
- Seam Interface Spec v1.0 - Contract definitions
- Seam Models - YAML schema for all attributes
- SDK Behavior Spec - Implementation requirements
- Examples Guide - Usage patterns and demos
Key Concepts
Seams
A seam is the integration surface between services. Each seam has:
component.instrument.attributepath (e.g.,P01.actuator.state)stateSchemaIdURI defining structure- Typed fields (bool, float, int, string, list)
Idempotency
All commands use command_id for replay protection:
- Duplicate commands return cached reply
- Permanent tracking (requires UUID-based IDs)
- Prevents double-execution on network retries
State Machine
Services follow ISA-88 state machines:
- Actuator:
Idle → Starting → Running → Stopping → Stopped - Unit:
Idle → Running → Complete/Stopped/Aborted - APP:
Idle → RecipeLoaded → Running → Complete
Development
Running Tests
poetry install
poetry run pytest
Building Package
poetry build
Requirements
- Python 3.10+
- procaaso-client ^0.1.19
- pydantic ^1.10.0
- aiohttp ^3.9.0
License
Copyright © 2025 Alphinity Bespoke Systems
Contributing
This SDK implements the Procaaso Seam Interface Specification v1.0. Changes must maintain backward compatibility or increment the major version per semantic versioning.
Developer Notes
For AI/Copilot development, see internal build contract:
Source of truth:
- specs/Procaaso_Seam_Interface_Spec_v1.0.md
- specs/seams_models_v1.yaml
- specs/SDK_Behavior_Spec.md
Hard rules:
- Do not invent seam shapes not in seams_models_v1.yaml
- Bus envelopes must follow interface spec
- All services: Announce → CommandRequest/Reply → StateEvent
- Use async/await everywhere
- Use procaaso-client for bus read/write
Metadata
Release files for procaaso-seams-sdk 1.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| procaaso_seams_sdk-1.1.1.tar.gz | 45.0 kB | Without provenance | Details for procaaso_seams_sdk-1.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| procaaso_seams_sdk-1.1.1-py3-none-any.whl | Python 3 | none | any | Details for procaaso_seams_sdk-1.1.1-py3-none-any.whl |
Total release size: 106.9 kB
Release files / procaaso_seams_sdk-1.1.1.tar.gz
| Download URL | procaaso_seams_sdk-1.1.1.tar.gz |
|---|---|
| Size | 45.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8b2acabd6aa649549d3a83c8f059fdc602f32d72b94d3aa4fcae2b157593adbd
|
|
BLAKE2b-256 checksum How to use checksums |
f0ef7db8d2b2933455e4b3594a3e7a2c4da54900cf0606b2e29946a5b5fc071b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.7.1 CPython/3.10.11 Windows/10
|
Release files / procaaso_seams_sdk-1.1.1-py3-none-any.whl
| Download URL | procaaso_seams_sdk-1.1.1-py3-none-any.whl |
|---|---|
| Size | 62.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
766932ecdea4b5da417d3b12ff32d4b29f80fa4a8ff5cead10da7a60245fa5f2
|
|
BLAKE2b-256 checksum How to use checksums |
6a0d2aaa0d55c116768f8117497414f138e3d9f9f0c433bfd3dea2c75f071ec8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.7.1 CPython/3.10.11 Windows/10
|
Security for procaaso-seams-sdk 1.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.