Core SDK and framework for building IOMate Packages.

iomate-base provides the foundational abstractions, contracts, type system, and runtime definitions used throughout the IOMate Package ecosystem.

It is designed to be independent of specific IOMate Packages.

iomate-base
     ↑
     │
IOMate Packages
     │
     └── Actions

Features

iomate-base provides:

• Action definitions
• Action Groups
• Action Contracts
• Action registration and discovery
• Variables
• Variable flags
• Type definitions
• Python type resolution
• Runtime references
• Package metadata
• Package definitions
• Runtime execution contracts
• Version compatibility definitions

The core architecture is based on:

Types
  ↓
Variables
  ↓
Actions
  ↓
Contracts
  ↓
Packages

---

Requirements

• Python 3.12+
• Poetry

The supported Python version range is defined in pyproject.toml.

---

Installation

Install from PyPI:

pip install iomate-base

Or add it to a Poetry project:

poetry add iomate-base

---

Development Setup

Clone the repository and install the development dependencies:

poetry install

Activate the Poetry environment if required:

poetry shell

Or execute commands directly through Poetry:

poetry run <command>

---

Project Structure

iomate-base/
├── pyproject.toml
├── poetry.lock
│
├── src/
│   └── iomate_base/
│       ├── actions/
│       ├── contracts/
│       ├── packages/
│       ├── registry/
│       ├── runtime/
│       ├── types/
│       └── variables/
│
├── tests/
│   ├── actions/
│   ├── contracts/
│   ├── packages/
│   ├── registry/
│   ├── runtime/
│   ├── types/
│   └── variables/
│
└── README.md

---

Core Concepts

Actions

Actions are the primary executable abstraction in IOMate.

An Action defines:

• Stable key
• Version
• Name
• Description
• Inputs
• Outputs
• Metadata
• Handler

Examples:

workflow.if
browser.open
browser.click
http.request

iomate-base defines the Action abstraction but does not implement Package-specific Actions.

---

Action Groups

Actions can be organized into Action Groups.

The hierarchy is:

Package
    ↓
Action Group
    ↓
Action

Example:

iomate-workflow
├── Workflow
│   ├── workflow.if
│   ├── workflow.else_if
│   └── workflow.else
│
└── Error Handling
    ├── error_handling.try
    ├── error_handling.except
    └── error_handling.finally

---

Variables

Variables represent values flowing between Actions.

A Variable contains, conceptually:

name
type
value
flags

Variables are the interoperability layer between IOMate Packages.

For example:

iomate-selenium
       │
       │ creates
       ▼
SeleniumDriver Variable
       │
       │ consumed by
       ▼
iomate-claude

This allows Packages to communicate without directly depending on each other.

---

Variable Flags

Variables can expose behavioral and runtime flags such as:

required
nullable
mutable
readonly
runtime_reference
scope

These flags define how a Variable can be created, consumed, modified, and managed during execution.

---

Type System

iomate-base provides a normalized type system based on Python type annotations.

Initial supported types include:

str
int
float
bool
bytes
None
list
tuple
set
dict
Any

Parameterized types are also supported:

list[str]
list[int]
dict[str, int]
tuple[str, int]
set[str]

For example:

def process(items: list[str]) -> int:
    ...

can be represented as:

{
  "type": "list",
  "items": {
    "type": "string"
  }
}

---

Any

Any represents an unrestricted input type.

For example:

def analyze(value: Any, prompt: str) -> Any:
    ...

means that the Action does not impose an input type restriction.

It does not mean that the runtime Variable has no type.

A runtime Variable may still contain:

type: SeleniumDriver
value: <runtime object>

while being accepted by an Action with an Any input.

---

Runtime References

Some values represent objects that must remain inside the Robot process.

Examples include:

SeleniumDriver
BrowserSession
DatabaseConnection
FileHandle

These values can be represented as runtime references.

A runtime reference should not automatically be serialized.

The actual object remains managed by the execution environment.

---

Action Contracts

An Action Contract defines the interface of an Action.

A contract includes:

Action key
Contract version
Inputs
Outputs
Type constraints
Variable flags

Example:

{
  "key": "workflow.if",
  "version": "2.0.0",
  "inputs": [
    {
      "name": "condition",
      "type": "boolean",
      "required": true
    }
  ],
  "outputs": []
}

Action Contracts are independently versioned from Package versions.

This allows the runtime to determine whether an Action is compatible with an Automation.

---

Package Architecture

iomate-base is the foundation for IOMate Packages.

Examples of Packages include:

iomate-workflow
iomate-selenium
iomate-browser
iomate-http
iomate-excel
iomate-database
iomate-claude

Packages depend on iomate-base.

iomate-base must remain independent of those Packages.

The dependency direction is:

iomate-base
     ↑
     │
IOMate Packages

Package-to-Package communication should happen through shared Variables and runtime references rather than direct Package dependencies.

---

Example Package

A Package built using iomate-base may expose:

iomate-example
└── Example
    ├── example.create
    └── example.process

Its dependency can be declared through Poetry:

[tool.poetry.dependencies]
python = ">=3.12,<3.13"
iomate-base = ">=0.1.0,<1.0.0"

The Package then uses the abstractions provided by iomate-base to define its Actions, Inputs, Outputs, Variables, and Contracts.

---

Testing

Run the complete test suite:

poetry run pytest

Run tests with coverage:

poetry run pytest --cov=src/iomate_base --cov-report=term

The project requires a minimum coverage of:

90%

---

Code Quality

Run Ruff:

poetry run ruff check .

Check formatting:

poetry run ruff format --check .

Format the project:

poetry run ruff format .

Run MyPy:

poetry run mypy src

---

Pre-commit

Install the project's pre-commit hooks:

poetry run pre-commit install

Run all hooks:

poetry run pre-commit run --all-files

---

Documentation

Documentation should be updated when changes affect:

• Public APIs
• Actions
• Action Contracts
• Variables
• Types
• Runtime References
• Package interfaces
• Compatibility behavior
• Versioning

Public abstractions should include clear documentation and type annotations.

---

Versioning

iomate-base follows Semantic Versioning:

MAJOR.MINOR.PATCH

MAJOR

Breaking changes to public APIs or contracts.

MINOR

Backward-compatible functionality.

PATCH

Backward-compatible fixes.

Because iomate-base is consumed by multiple Packages, backward compatibility is a critical requirement.

---

Contributing

See CONTRIBUTING.md for:

• Branching strategy
• Development workflow
• Pull Request requirements
• Testing requirements
• Commit conventions
• Release process

See CODE_OF_CONDUCT.md for the project's community standards.

---

License

See LICENSE for licensing information.

---

Ecosystem

iomate-base is the foundation of the IOMate Package ecosystem.

                    IOMate
                       │
             ┌─────────┴─────────┐
             │                   │
        Control Plane       Execution Plane
             │                   │
             └─────────┬─────────┘
                       │
                  iomate-base
                       │
        ┌──────────────┼──────────────┐
        │              │              │
   workflow       selenium        claude
        │              │              │
        └──────────────┼──────────────┘
                       │
                    Actions

The core principles are:

Packages → Capabilities
Variables → Interoperability
Contracts → Compatibility
iomate-base → Foundation