iomate-base 0.1.0a0__tar.gz

iomate_base-0.1.0a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iomate_base-0.1.0a0/PKG-INFO

@@ -0,0 +1,620 @@
+Metadata-Version: 2.4
+Name: iomate-base
+Version: 0.1.0a0
+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
+```