Skip to main content

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

Key Concepts

Seams

A seam is the integration surface between services. Each seam has:

  • component.instrument.attribute path (e.g., P01.actuator.state)
  • stateSchemaId URI 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)

Source distribution for procaaso-seams-sdk 1.1.1
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)

Table of built distributions (wheels) for procaaso-seams-sdk 1.1.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page