omium 0.1.0__tar.gz

omium-0.1.0/LICENSE.md

@@ -0,0 +1,8 @@
+# Proprietary License
+
+Copyright (c) 2025 Omium.
+
+All rights reserved. The Omium Python SDK is proprietary software. You may not copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies of the SDK
+except as explicitly permitted in writing by Omium.
+

omium-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE.md
+recursive-include omium/proto *.py
+recursive-include omium *.typed
+

omium-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: omium
+Version: 0.1.0
+Summary: Omium SDK for Python - Fault-tolerant agent operating system
+Author-email: Omium Team <anurag@omium.ai>
+License: # Proprietary License
+        
+        Copyright (c) 2025 Omium.
+        
+        All rights reserved. The Omium Python SDK is proprietary software. You may not copy,
+        modify, merge, publish, distribute, sublicense, and/or sell copies of the SDK
+        except as explicitly permitted in writing by Omium.
+        
+        
+Keywords: agents,checkpointing,fault-tolerant,omium
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: grpcio-tools>=1.60.0
+Requires-Dist: protobuf>=4.25.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: click>=8.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.2; extra == "dev"
+Dynamic: license-file
+
+# Omium Python SDK
+
+Python SDK for integrating Omium checkpoint and recovery capabilities into your agent workflows.
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install omium
+```
+
+The package is signed and published via PyPI’s Trusted Publisher workflow so that no API
+tokens are stored in the repository. Enable pip’s hash-checking mode or use `pipx` if you
+need additional supply-chain guarantees.
+
+### From source (development)
+
+```bash
+cd omium-platform/sdk/python
+python -m pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Setup Client
+
+```python
+from omium import OmiumClient
+
+client = OmiumClient(checkpoint_manager_url="localhost:7001")
+await client.connect()
+client.set_execution_context(execution_id="exec_123", agent_id="agent_1")
+```
+
+### 2. Using @checkpoint Decorator
+
+```python
+from omium import checkpoint
+
+@checkpoint("validate_data", preconditions=["data is not None"])
+async def validate_data(data: dict) -> dict:
+    assert data is not None
+    assert "value" in data
+    return {"validated": True, "data": data}
+
+# Use the function
+result = await validate_data({"value": 42})
+```
+
+### 3. Using Checkpoint Context Manager
+
+```python
+from omium import Checkpoint
+
+async with Checkpoint("important_state", client=client) as cp:
+    # Critical code here
+    result = await do_critical_thing()
+    cp.update_state(step="complete")
+    # Checkpoint saved automatically on exit
+```
+
+### 4. Manual Checkpoint Creation
+
+```python
+checkpoint_id = await client.create_checkpoint(
+    checkpoint_name="manual_checkpoint",
+    state={"data": "important"},
+    preconditions=["data exists"],
+    postconditions=["data is valid"],
+)
+```
+
+### 5. Rollback to Checkpoint
+
+```python
+rollback_result = await client.rollback_to_checkpoint(
+    checkpoint_id="cp_123",
+    trigger_reason="manual rollback",
+)
+```
+
+## Features
+
+- **@checkpoint Decorator** - Automatic checkpoint creation before/after function execution
+- **Checkpoint Context Manager** - Manual checkpoint control with context manager
+- **Async gRPC Client** - High-performance async communication with checkpoint-manager
+- **State Serialization** - Automatic serialization of function arguments and results
+- **Pre/Post Conditions** - Validation support for checkpoint creation
+- **Rollback Support** - Rollback execution to any checkpoint
+
+## Examples
+
+See `examples/basic_checkpoint.py` for complete examples.
+
+## Testing
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=omium --cov-report=html
+```
+
+## API Reference
+
+### OmiumClient
+
+Main client for checkpoint operations.
+
+#### Methods
+
+- `connect()` - Connect to checkpoint-manager service
+- `close()` - Close connection
+- `set_execution_context(execution_id, agent_id)` - Set execution context
+- `create_checkpoint(...)` - Create a checkpoint
+- `get_checkpoint(checkpoint_id)` - Get checkpoint details
+- `list_checkpoints(execution_id)` - List checkpoints for execution
+- `rollback_to_checkpoint(checkpoint_id)` - Rollback to checkpoint
+- `verify_checkpoint(checkpoint_id)` - Verify checkpoint integrity
+
+### @checkpoint Decorator
+
+```python
+@checkpoint(
+    name: str,
+    preconditions: Optional[List[str]] = None,
+    postconditions: Optional[List[str]] = None,
+    client: Optional[OmiumClient] = None,
+    execution_id: Optional[str] = None,
+    agent_id: Optional[str] = None,
+)
+```
+
+### Checkpoint Context Manager
+
+```python
+Checkpoint(
+    name: str,
+    client: Optional[OmiumClient] = None,
+    execution_id: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    preconditions: Optional[List[str]] = None,
+    postconditions: Optional[List[str]] = None,
+)
+```
+
+## Requirements
+
+- Python >= 3.11
+- grpcio >= 1.60.0
+- protobuf >= 4.25.0
+
+## Development
+
+### Generating Proto Code
+
+```bash
+# From sdk/python directory
+python -m grpc_tools.protoc \
+    --python_out=omium/proto \
+    --grpc_python_out=omium/proto \
+    --proto_path=../../shared/proto \
+    ../../shared/proto/checkpoint/checkpoint.proto
+```
+
+Or use the script:
+
+```bash
+.\scripts\generate-proto.ps1  # Windows
+./scripts/generate-proto.sh   # Linux/Mac
+```
+
+## License
+
+Proprietary - Omium Platform

omium-0.1.0/README.md

@@ -0,0 +1,181 @@
+# Omium Python SDK
+
+Python SDK for integrating Omium checkpoint and recovery capabilities into your agent workflows.
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install omium
+```
+
+The package is signed and published via PyPI’s Trusted Publisher workflow so that no API
+tokens are stored in the repository. Enable pip’s hash-checking mode or use `pipx` if you
+need additional supply-chain guarantees.
+
+### From source (development)
+
+```bash
+cd omium-platform/sdk/python
+python -m pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Setup Client
+
+```python
+from omium import OmiumClient
+
+client = OmiumClient(checkpoint_manager_url="localhost:7001")
+await client.connect()
+client.set_execution_context(execution_id="exec_123", agent_id="agent_1")
+```
+
+### 2. Using @checkpoint Decorator
+
+```python
+from omium import checkpoint
+
+@checkpoint("validate_data", preconditions=["data is not None"])
+async def validate_data(data: dict) -> dict:
+    assert data is not None
+    assert "value" in data
+    return {"validated": True, "data": data}
+
+# Use the function
+result = await validate_data({"value": 42})
+```
+
+### 3. Using Checkpoint Context Manager
+
+```python
+from omium import Checkpoint
+
+async with Checkpoint("important_state", client=client) as cp:
+    # Critical code here
+    result = await do_critical_thing()
+    cp.update_state(step="complete")
+    # Checkpoint saved automatically on exit
+```
+
+### 4. Manual Checkpoint Creation
+
+```python
+checkpoint_id = await client.create_checkpoint(
+    checkpoint_name="manual_checkpoint",
+    state={"data": "important"},
+    preconditions=["data exists"],
+    postconditions=["data is valid"],
+)
+```
+
+### 5. Rollback to Checkpoint
+
+```python
+rollback_result = await client.rollback_to_checkpoint(
+    checkpoint_id="cp_123",
+    trigger_reason="manual rollback",
+)
+```
+
+## Features
+
+- **@checkpoint Decorator** - Automatic checkpoint creation before/after function execution
+- **Checkpoint Context Manager** - Manual checkpoint control with context manager
+- **Async gRPC Client** - High-performance async communication with checkpoint-manager
+- **State Serialization** - Automatic serialization of function arguments and results
+- **Pre/Post Conditions** - Validation support for checkpoint creation
+- **Rollback Support** - Rollback execution to any checkpoint
+
+## Examples
+
+See `examples/basic_checkpoint.py` for complete examples.
+
+## Testing
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=omium --cov-report=html
+```
+
+## API Reference
+
+### OmiumClient
+
+Main client for checkpoint operations.
+
+#### Methods
+
+- `connect()` - Connect to checkpoint-manager service
+- `close()` - Close connection
+- `set_execution_context(execution_id, agent_id)` - Set execution context
+- `create_checkpoint(...)` - Create a checkpoint
+- `get_checkpoint(checkpoint_id)` - Get checkpoint details
+- `list_checkpoints(execution_id)` - List checkpoints for execution
+- `rollback_to_checkpoint(checkpoint_id)` - Rollback to checkpoint
+- `verify_checkpoint(checkpoint_id)` - Verify checkpoint integrity
+
+### @checkpoint Decorator
+
+```python
+@checkpoint(
+    name: str,
+    preconditions: Optional[List[str]] = None,
+    postconditions: Optional[List[str]] = None,
+    client: Optional[OmiumClient] = None,
+    execution_id: Optional[str] = None,
+    agent_id: Optional[str] = None,
+)
+```
+
+### Checkpoint Context Manager
+
+```python
+Checkpoint(
+    name: str,
+    client: Optional[OmiumClient] = None,
+    execution_id: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    preconditions: Optional[List[str]] = None,
+    postconditions: Optional[List[str]] = None,
+)
+```
+
+## Requirements
+
+- Python >= 3.11
+- grpcio >= 1.60.0
+- protobuf >= 4.25.0
+
+## Development
+
+### Generating Proto Code
+
+```bash
+# From sdk/python directory
+python -m grpc_tools.protoc \
+    --python_out=omium/proto \
+    --grpc_python_out=omium/proto \
+    --proto_path=../../shared/proto \
+    ../../shared/proto/checkpoint/checkpoint.proto
+```
+
+Or use the script:
+
+```bash
+.\scripts\generate-proto.ps1  # Windows
+./scripts/generate-proto.sh   # Linux/Mac
+```
+
+## License
+
+Proprietary - Omium Platform

omium-0.1.0/checkpoint/checkpoint_pb2.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: checkpoint/checkpoint.proto
+# Protobuf Python Version: 5.29.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    5,
+    29,
+    0,
+    '',
+    'checkpoint/checkpoint.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2
+from google.protobuf import struct_pb2 as google_dot_protobuf_dot_struct__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1b\x63heckpoint/checkpoint.proto\x12\x13omium.checkpoint.v1\x1a\x1fgoogle/protobuf/timestamp.proto\x1a\x1cgoogle/protobuf/struct.proto\"\xa6\x03\n\nCheckpoint\x12\n\n\x02id\x18\x01 \x01(\t\x12\x14\n\x0c\x65xecution_id\x18\x02 \x01(\t\x12\x10\n\x08\x61gent_id\x18\x03 \x01(\t\x12\x17\n\x0f\x63heckpoint_name\x18\x04 \x01(\t\x12\x18\n\x10\x63heckpoint_index\x18\x05 \x01(\x05\x12\x18\n\x10state_size_bytes\x18\x06 \x01(\x03\x12\x16\n\x0estate_blob_uri\x18\x07 \x01(\t\x12\x10\n\x08\x63hecksum\x18\x08 \x01(\t\x12\x15\n\rpreconditions\x18\t \x03(\t\x12\x16\n\x0epostconditions\x18\n \x03(\t\x12\x19\n\x11validation_passed\x18\x0b \x01(\x08\x12)\n\x08metadata\x18\x0c \x01(\x0b\x32\x17.google.protobuf.Struct\x12\x18\n\x10\x63ompression_type\x18\r \x01(\t\x12.\n\ncreated_at\x18\x0e \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12.\n\nexpires_at\x18\x0f \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\x8b\x02\n\x17\x43reateCheckpointRequest\x12\x14\n\x0c\x65xecution_id\x18\x01 \x01(\t\x12\x10\n\x08\x61gent_id\x18\x02 \x01(\t\x12\x17\n\x0f\x63heckpoint_name\x18\x03 \x01(\t\x12&\n\x05state\x18\x04 \x01(\x0b\x32\x17.google.protobuf.Struct\x12\x15\n\rpreconditions\x18\x05 \x03(\t\x12\x16\n\x0epostconditions\x18\x06 \x03(\t\x12)\n\x08metadata\x18\x07 \x01(\x0b\x32\x17.google.protobuf.Struct\x12\x18\n\x10\x63ompression_type\x18\x08 \x01(\t\x12\x13\n\x0bttl_seconds\x18\t \x01(\x03\"w\n\x18\x43reateCheckpointResponse\x12\x33\n\ncheckpoint\x18\x01 \x01(\x0b\x32\x1f.omium.checkpoint.v1.Checkpoint\x12\x0f\n\x07success\x18\x02 \x01(\x08\x12\x15\n\rerror_message\x18\x03 \x01(\t\"D\n\x14GetCheckpointRequest\x12\x15\n\rcheckpoint_id\x18\x01 \x01(\t\x12\x15\n\rinclude_state\x18\x02 \x01(\x08\"\x9c\x01\n\x15GetCheckpointResponse\x12\x33\n\ncheckpoint\x18\x01 \x01(\x0b\x32\x1f.omium.checkpoint.v1.Checkpoint\x12&\n\x05state\x18\x02 \x01(\x0b\x32\x17.google.protobuf.Struct\x12\x0f\n\x07success\x18\x03 \x01(\x08\x12\x15\n\rerror_message\x18\x04 \x01(\t\"\x84\x01\n\x16ListCheckpointsRequest\x12\x14\n\x0c\x65xecution_id\x18\x01 \x01(\t\x12\x10\n\x08\x61gent_id\x18\x02 \x01(\t\x12\r\n\x05limit\x18\x03 \x01(\x05\x12\x0e\n\x06offset\x18\x04 \x01(\x05\x12\x10\n\x08order_by\x18\x05 \x01(\t\x12\x11\n\tascending\x18\x06 \x01(\x08\"\x8c\x01\n\x17ListCheckpointsResponse\x12\x34\n\x0b\x63heckpoints\x18\x01 \x03(\x0b\x32\x1f.omium.checkpoint.v1.Checkpoint\x12\x13\n\x0btotal_count\x18\x02 \x01(\x05\x12\x0f\n\x07success\x18\x03 \x01(\x08\x12\x15\n\rerror_message\x18\x04 \x01(\t\"\xb8\x01\n\x1bRollbackToCheckpointRequest\x12\x14\n\x0c\x65xecution_id\x18\x01 \x01(\t\x12\x15\n\rcheckpoint_id\x18\x02 \x01(\t\x12\x14\n\x0ctriggered_by\x18\x03 \x01(\t\x12\x16\n\x0etrigger_reason\x18\x04 \x01(\t\x12\x14\n\x0ctrigger_type\x18\x05 \x01(\t\x12(\n\x07options\x18\x06 \x01(\x0b\x32\x17.google.protobuf.Struct\"\xd1\x01\n\x1cRollbackToCheckpointResponse\x12\x13\n\x0brollback_id\x18\x01 \x01(\t\x12:\n\x11target_checkpoint\x18\x02 \x01(\x0b\x32\x1f.omium.checkpoint.v1.Checkpoint\x12\x0f\n\x07success\x18\x03 \x01(\x08\x12\x15\n\rerror_message\x18\x04 \x01(\t\x12\x38\n\x14\x65stimated_completion\x18\x05 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"?\n\x17\x44\x65leteCheckpointRequest\x12\x15\n\rcheckpoint_id\x18\x01 \x01(\t\x12\r\n\x05\x66orce\x18\x02 \x01(\x08\"B\n\x18\x44\x65leteCheckpointResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\x12\x15\n\rerror_message\x18\x02 \x01(\t\"0\n\x17VerifyCheckpointRequest\x12\x15\n\rcheckpoint_id\x18\x01 \x01(\t\"m\n\x18VerifyCheckpointResponse\x12\r\n\x05valid\x18\x01 \x01(\x08\x12\x16\n\x0e\x63hecksum_match\x18\x02 \x01(\t\x12\x13\n\x0b\x62lob_exists\x18\x03 \x01(\x08\x12\x15\n\rerror_message\x18\x04 \x01(\t2\xb9\x05\n\x11\x43heckpointService\x12o\n\x10\x43reateCheckpoint\x12,.omium.checkpoint.v1.CreateCheckpointRequest\x1a-.omium.checkpoint.v1.CreateCheckpointResponse\x12\x66\n\rGetCheckpoint\x12).omium.checkpoint.v1.GetCheckpointRequest\x1a*.omium.checkpoint.v1.GetCheckpointResponse\x12l\n\x0fListCheckpoints\x12+.omium.checkpoint.v1.ListCheckpointsRequest\x1a,.omium.checkpoint.v1.ListCheckpointsResponse\x12{\n\x14RollbackToCheckpoint\x12\x30.omium.checkpoint.v1.RollbackToCheckpointRequest\x1a\x31.omium.checkpoint.v1.RollbackToCheckpointResponse\x12o\n\x10\x44\x65leteCheckpoint\x12,.omium.checkpoint.v1.DeleteCheckpointRequest\x1a-.omium.checkpoint.v1.DeleteCheckpointResponse\x12o\n\x10VerifyCheckpoint\x12,.omium.checkpoint.v1.VerifyCheckpointRequest\x1a-.omium.checkpoint.v1.VerifyCheckpointResponseB7Z5github.com/omium/shared/proto/checkpoint;checkpointpbb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'checkpoint.checkpoint_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'Z5github.com/omium/shared/proto/checkpoint;checkpointpb'
+  _globals['_CHECKPOINT']._serialized_start=116
+  _globals['_CHECKPOINT']._serialized_end=538
+  _globals['_CREATECHECKPOINTREQUEST']._serialized_start=541
+  _globals['_CREATECHECKPOINTREQUEST']._serialized_end=808
+  _globals['_CREATECHECKPOINTRESPONSE']._serialized_start=810
+  _globals['_CREATECHECKPOINTRESPONSE']._serialized_end=929
+  _globals['_GETCHECKPOINTREQUEST']._serialized_start=931
+  _globals['_GETCHECKPOINTREQUEST']._serialized_end=999
+  _globals['_GETCHECKPOINTRESPONSE']._serialized_start=1002
+  _globals['_GETCHECKPOINTRESPONSE']._serialized_end=1158
+  _globals['_LISTCHECKPOINTSREQUEST']._serialized_start=1161
+  _globals['_LISTCHECKPOINTSREQUEST']._serialized_end=1293
+  _globals['_LISTCHECKPOINTSRESPONSE']._serialized_start=1296
+  _globals['_LISTCHECKPOINTSRESPONSE']._serialized_end=1436
+  _globals['_ROLLBACKTOCHECKPOINTREQUEST']._serialized_start=1439
+  _globals['_ROLLBACKTOCHECKPOINTREQUEST']._serialized_end=1623
+  _globals['_ROLLBACKTOCHECKPOINTRESPONSE']._serialized_start=1626
+  _globals['_ROLLBACKTOCHECKPOINTRESPONSE']._serialized_end=1835
+  _globals['_DELETECHECKPOINTREQUEST']._serialized_start=1837
+  _globals['_DELETECHECKPOINTREQUEST']._serialized_end=1900
+  _globals['_DELETECHECKPOINTRESPONSE']._serialized_start=1902
+  _globals['_DELETECHECKPOINTRESPONSE']._serialized_end=1968
+  _globals['_VERIFYCHECKPOINTREQUEST']._serialized_start=1970
+  _globals['_VERIFYCHECKPOINTREQUEST']._serialized_end=2018
+  _globals['_VERIFYCHECKPOINTRESPONSE']._serialized_start=2020
+  _globals['_VERIFYCHECKPOINTRESPONSE']._serialized_end=2129
+  _globals['_CHECKPOINTSERVICE']._serialized_start=2132
+  _globals['_CHECKPOINTSERVICE']._serialized_end=2829
+# @@protoc_insertion_point(module_scope)