Metadata-Version: 2.4
Name: iomate-base
Version: 0.1.7
Summary: Core SDK and runtime contracts for the IOMate ecosystem
License-File: LICENSE
Author: IOMate
Requires-Python: >=3.12,<=3.14.4
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Description-Content-Type: text/markdown

<div align="center">
  <h1><strong>IOMATE-BASE</strong></h1>
</div>

<p align="center">
  <a href="https://github.com/iomateapp/iomate-base/actions?query=branch%staging">
    <img src="https://github.com/iomateapp/iomate-base/actions/workflows/quality-and-tests.yaml/badge.svg?branch=staging" />
  </a>
  <a href="https://codecov.io/gh/iomateapp/iomate-base">
    <img src="https://codecov.io/gh/iomateapp/iomate-base/branch/staging/graph/badge.svg" />
  </a>
  <img src="https://img.shields.io/pypi/dm/iomate-base" />
  <img src="https://img.shields.io/github/license/iomateapp/iomate-base" />
  <img src="https://img.shields.io/github/v/release/iomateapp/iomate-base" />
  <img src="https://img.shields.io/github/stars/iomateapp/iomate-base?style=flat" />
</p>

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.

```text
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:

```text
Types
  ↓
Variables
  ↓
Actions
  ↓
Contracts
  ↓
Packages
```

---

## Requirements

- Python 3.12+
- Poetry

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

---

## Installation

Install from PyPI:

```bash
pip install iomate-base
```

Or add it to a Poetry project:

```bash
poetry add iomate-base
```

---

## Development Setup

Clone the repository and install the development dependencies:

```bash
poetry install
```

Activate the Poetry environment if required:

```bash
poetry shell
```

Or execute commands directly through Poetry:

```bash
poetry run <command>
```

---

## Project Structure

```text
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:

```text
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:

```text
Package
    ↓
Action Group
    ↓
Action
```

Example:

```text
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:

```text
name
type
value
flags
```

Variables are the interoperability layer between IOMate Packages.

For example:

```text
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:

```text
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:

```text
str
int
float
bool
bytes
None
list
tuple
set
dict
Any
```

Parameterized types are also supported:

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

For example:

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

can be represented as:

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

---

### Any

`Any` represents an unrestricted input type.

For example:

```python
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:

```text
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:

```text
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:

```text
Action key
Contract version
Inputs
Outputs
Type constraints
Variable flags
```

Example:

```json
{
  "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:

```text
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:

```text
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:

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

Its dependency can be declared through Poetry:

```toml
[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:

```bash
poetry run pytest
```

Run tests with coverage:

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

The project requires a minimum coverage of:

```text
90%
```

---

## Code Quality

Run Ruff:

```bash
poetry run ruff check .
```

Check formatting:

```bash
poetry run ruff format --check .
```

Format the project:

```bash
poetry run ruff format .
```

Run MyPy:

```bash
poetry run mypy src
```

---

## Pre-commit

Install the project's pre-commit hooks:

```bash
poetry run pre-commit install
```

Run all hooks:

```bash
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:

```text
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](CONTRIBUTING.md) for:

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

See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for the project's community standards.

---

## License

See [LICENSE](LICENSE) for licensing information.

---

## Ecosystem

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

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

The core principles are:

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