loom-core 0.1.0__py3-none-any.whl

loom_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,342 @@
+Metadata-Version: 2.4
+Name: loom-core
+Version: 0.1.0
+Summary: Durable workflow orchestration engine for Python
+Home-page: https://github.com/satadeep3927/loom
+Author: Satadeep Dasgupta
+Author-email: Satadeep Dasgupta <satadeep.dasgupta@brainiuminfotech.com>
+License: MIT
+Project-URL: Homepage, https://github.com/satadeep3927/loom
+Project-URL: Documentation, https://github.com/satadeep3927/loom/blob/main/README.md
+Project-URL: Repository, https://github.com/satadeep3927/loom
+Project-URL: Issues, https://github.com/satadeep3927/loom/issues
+Keywords: workflow,orchestration,durable,event-sourcing,temporal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Loom - Durable Workflow Orchestration
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI](https://img.shields.io/badge/pypi-loom--core-blue)](https://pypi.org/project/loom-core/)
+
+A Python-based durable workflow orchestration engine inspired by [Temporal](https://temporal.io/) and [Durable Task Framework](https://github.com/Azure/durabletask). Loom provides event-sourced, deterministic workflow execution with automatic recovery and replay capabilities.
+
+## Features
+
+- **Event Sourcing**: All workflow state changes persisted as immutable events
+- **Deterministic Replay**: Workflows reconstruct from event history for recovery
+- **Type Safe**: Full generic typing support with `Workflow[InputT, StateT]`
+- **Async First**: Built on asyncio for high-performance concurrent execution
+- **Durable Execution**: Workflows survive process crashes and auto-recover
+- **Beautiful CLI**: Rich console interface with progress tracking
+- **Well Tested**: Comprehensive test suite with pytest
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install loom-core
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/yourusername/loom.git
+cd loom
+pip install -e .
+```
+
+### Define a Workflow
+
+```python
+import asyncio
+from typing import TypedDict
+import loom
+
+
+# Define your data types
+class OrderInput(TypedDict):
+    order_id: str
+    customer_email: str
+
+
+class OrderState(TypedDict):
+    payment_confirmed: bool
+    email_sent: bool
+
+
+# Define activities (side effects)
+@loom.activity(name="process_payment", retry_count=3, timeout_seconds=30)
+async def process_payment(order_id: str) -> bool:
+    # Call payment API
+    return True
+
+
+@loom.activity(name="send_email", retry_count=2)
+async def send_confirmation_email(email: str, order_id: str) -> None:
+    # Send email via service
+    pass
+
+
+# Define workflow
+@loom.workflow(name="OrderProcessing", version="1.0.0")
+class OrderWorkflow(loom.Workflow[OrderInput, OrderState]):
+    
+    @loom.step(name="process_payment")
+    async def payment_step(self, ctx: loom.WorkflowContext[OrderInput, OrderState]):
+        success = await ctx.activity(process_payment, ctx.input["order_id"])
+        await ctx.state.set("payment_confirmed", success)
+        ctx.logger.info(f"Payment processed: {success}")
+    
+    @loom.step(name="send_confirmation")
+    async def notification_step(self, ctx: loom.WorkflowContext[OrderInput, OrderState]):
+        if ctx.state["payment_confirmed"]:
+            await ctx.activity(
+                send_confirmation_email,
+                ctx.input["customer_email"],
+                ctx.input["order_id"]
+            )
+            await ctx.state.set("email_sent", True)
+            ctx.logger.info("Confirmation email sent")
+```
+
+**Note**: For state updates, use:
+- `await ctx.state.set("key", value)` for single values
+- `await ctx.state.update(key=lambda _: asyncio.sleep(0, value))` for batch updates (requires awaitable)
+
+See [STATE_MANAGEMENT.md](STATE_MANAGEMENT.md) for detailed examples.
+
+### Start a Workflow
+
+```python
+async def main():
+    db = loom.Database()
+    async with db:
+        # Initialize database
+        await db.migrate_up()
+        
+        # Start workflow
+        handle = await db.start_workflow(
+            OrderWorkflow,
+            workflow_input=OrderInput(
+                order_id="ORD-12345",
+                customer_email="customer@example.com"
+            ),
+            initial_state=OrderState(
+                payment_confirmed=False,
+                email_sent=False
+            ),
+        )
+        
+        print(f"Workflow started: {handle.workflow_id}")
+        
+        # Execute workflow tasks
+        while True:
+            task_executed = await loom.run_once()
+            if not task_executed:
+                break
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Run the Worker
+
+```bash
+# Initialize database
+loom init
+
+# Start worker with 4 concurrent task processors
+loom worker
+
+# Custom configuration
+loom worker --workers 8 --poll-interval 1.0
+```
+
+## CLI Commands
+
+```bash
+# Initialize database
+loom init
+
+# Start distributed worker
+loom worker [--workers 4] [--poll-interval 0.5]
+
+# List workflows
+loom list [--limit 50] [--status RUNNING]
+
+# Inspect workflow details
+loom inspect <workflow-id> [--events]
+
+# Show database statistics
+loom stats
+```
+
+## 🏗️ Architecture
+
+### Core Components
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      Workflow                           │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
+│  │  Step 1  │→ │  Step 2  │→ │  Step 3  │             │
+│  └──────────┘  └──────────┘  └──────────┘             │
+└─────────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────┐
+│                  WorkflowContext                        │
+│  • State Management (StateProxy)                        │
+│  • Activity Execution                                   │
+│  • Event Replay & Cursor                                │
+│  • Logger (replay-safe)                                 │
+└─────────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────┐
+│                      Engine                             │
+│  • replay_until_block() - Step execution                │
+│  • replay_activity() - Activity retry                   │
+│  • Event matching & determinism                         │
+└─────────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────┐
+│                    Database (SQLite)                    │
+│  • workflows   • events   • tasks   • logs              │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Event Types
+
+- `WORKFLOW_STARTED` - Workflow initialization
+- `WORKFLOW_COMPLETED` - Successful completion
+- `WORKFLOW_FAILED` - Fatal error occurred
+- `STATE_SET` - Single state key updated
+- `STATE_UPDATE` - Batch state update
+- `ACTIVITY_SCHEDULED` - Activity queued for execution
+- `ACTIVITY_COMPLETED` - Activity finished successfully
+- `ACTIVITY_FAILED` - Activity permanently failed
+- `TIMER_FIRED` - Sleep/delay completed
+- `SIGNAL_RECEIVED` - External signal received
+
+## 📚 Documentation
+
+See [`.copilot-instructions.md`](.copilot-instructions.md) for comprehensive development guidelines including:
+
+- Event sourcing patterns
+- Deterministic execution rules
+- Activity best practices
+- Testing strategies
+- Common pitfalls to avoid
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=src --cov-report=html
+
+# Run specific test file
+pytest tests/test_workflow.py
+
+# Verbose output
+pytest -v
+```
+
+## Project Structure
+
+```
+loom/
+├── src/
+│   ├── common/         # Shared utilities
+│   ├── core/           # Core engine (context, engine, runner, worker)
+│   ├── database/       # Database layer
+│   ├── decorators/     # @workflow, @step, @activity
+│   ├── lib/            # Utilities and progress tracking
+│   ├── migrations/     # Database migrations
+│   └── schemas/        # Type definitions
+├── tests/              # Test suite
+├── examples/           # Example workflows
+├── loom.py             # Main package interface
+└── pyproject.toml      # Package configuration
+```
+
+## Configuration
+
+Loom uses SQLite by default for simplicity. For production:
+
+- Consider PostgreSQL/MySQL for scalability
+- Implement connection pooling
+- Add monitoring and alerting
+- Deploy multiple workers for high availability
+
+## Contributing
+
+Contributions welcome! Please ensure:
+
+1. Tests pass: `pytest`
+2. Code formatted: `black .`
+3. Type checking: `mypy .`
+4. Linting: `ruff check .`
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Acknowledgments
+
+Inspired by:
+- [Temporal](https://temporal.io/) - The workflow orchestration platform
+- [Durable Task Framework](https://github.com/Azure/durabletask) - Microsoft's durable task library
+- [Cadence](https://cadenceworkflow.io/) - Uber's workflow platform
+
+---
+
+**Built withpy src`
+4. Linting: `ruff check src`
+
+## 📝 License
+
+MIT License - see LICENSE file for details
+
+## 🙏 Acknowledgments
+
+Inspired by:
+- [Temporal](https://temporal.io/) - The workflow orchestration platform
+- [Durable Task Framework](https://github.com/Azure/durabletask) - Microsoft's durable task library
+- [Cadence](https://cadenceworkflow.io/) - Uber's workflow platform
+
+## 📧 Contact
+
+For questions and support, please open an issue on GitHub.
+
+---
+
+**Built with ❤️ using Python 3.12+**

loom_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,50 @@
+loom_core-0.1.0.dist-info/licenses/LICENSE,sha256=8EpC-clAYRUfJQ92T3iQEIIWYjx2A3Kfk28zOd8lh7I,1095
+src/__init__.py,sha256=BESUSbebsjCFRkELNqdCJ3USyVbnoomCl6IRmsdOfLI,1294
+src/cli/__init__.py,sha256=BI8VfSIB5MF4_D9GxHFJwynNEvosDHReVGvsliS99ho,73
+src/cli/cli.py,sha256=cykYs_CKkJWck4auqDxxns9bgPkVznuN9HWsVgfHAmM,7673
+src/common/activity.py,sha256=DXAKEJw5IgvUNJj8yr3Vu0UfxnBZW_KkKcBt70TnpyU,1078
+src/common/config.py,sha256=NZHW07CzpWCaLv77nhULycmD7_QMHdF-3AsrxDFid4A,273
+src/common/errors.py,sha256=jc7_XS8dUPS8fg5pb7kJaTuIR1e6eKBZyZtbsHW3lgM,1712
+src/common/workflow.py,sha256=YfiS0FBhzEBp71t6YKsqM7aNvklvFatb_h3RbgAormQ,1945
+src/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/core/compiled.py,sha256=Y2NQDMZVLee65ILgJoK2Ny_OcR1T4LJnOQWQcyg0Z7U,1178
+src/core/context.py,sha256=rVWWSOaAmdVOzKKFh9TwpJVX-4Rm0h7bC76ipEcqVBw,9219
+src/core/engine.py,sha256=rZHl15Qa36zvv0r7XDi2f0NGzXoO6X3uHrKaA-jlax4,4202
+src/core/handle.py,sha256=beOVmJit-gSrk7II4c2KuSubmr5OIPls82_vJ-pI04U,5532
+src/core/logger.py,sha256=4ej95IdHOdBh-y7PQoRFz_H22PJYDXvAioBoId8mOhg,1729
+src/core/runner.py,sha256=pYITY35Q88ItZA4EuSWmNE5sgxL0tExXrm9j5vSaz6o,1718
+src/core/state.py,sha256=jdFzSPanATeiWAkQewwcSDjjVseOyMRUdDfsc-a34mQ,2996
+src/core/worker.py,sha256=jpTtvM1rIToVkG4SwJu1W9Q-eL3bw8b3N8KsxxrRovA,5322
+src/core/workflow.py,sha256=E_A2rI6iaW3liZmVy3X98oxSeBDXMGiQnRZRq3Cp3BA,5755
+src/database/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/database/db.py,sha256=BtZTNtZ6cXpfvrtdmW8Xb47zoC2NXvVoWVmUILow2eA,23535
+src/decorators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/decorators/activity.py,sha256=xt7oeYOKJxhKIEcwWsSVA26c_jk4yQB1PHtbcg3tCFI,4824
+src/decorators/workflow.py,sha256=rBpbnpLfDTTAWdgiERpUPIgNUJpnYJKvBZPmzx-ECcc,1516
+src/lib/progress.py,sha256=Es-BKYVI5xOsC-K6wBi5kUbloYIlh5X_V8sLkU7W9IU,3354
+src/lib/utils.py,sha256=aL4VR-_JXbNLYsJYyFL__JQRAq6NQzBYetvHqMGIgYY,809
+src/migrations/down/001_setup_pragma.sql,sha256=NGUGhNmJaroGe_APkLmp6p4q6-zVEYGKHJE4wJixfgs,280
+src/migrations/down/002_create_workflows.sql,sha256=rQcF30tXrBJbbGkOIlJlVMBJ7SZNQHtJpMjgNmo_-hE,58
+src/migrations/down/003.create_events.sql,sha256=5fpnS9yA6gp5z-dOeg7f-klblJPugrwZ6jgwNrQAGLw,52
+src/migrations/down/004.create_tasks.sql,sha256=vFSGPYQLyWdk7sNTk5jrrq3fHZsw1trcPZAd_eL9kVc,50
+src/migrations/down/005.create_indexes.sql,sha256=aDFXwWWwkyjpGqG9zZHTsQ4XyAhrNxDwjivYpVRf458,148
+src/migrations/down/006_auto_update_triggers.sql,sha256=1lEFZsuYANADENOM6baHSA4ljqiovOSstQXIzw80hUc,108
+src/migrations/down/007_create_logs.sql,sha256=LziyAbGM5OFDa2skhk5XhSeC3yzSOaP3Kh_a2gSAEQQ,26
+src/migrations/up/001_setup_pragma.sql,sha256=MAm4ghbC1CXs9OcAryvL-LnwMy00Igb_Ax5Ik2w0YGE,317
+src/migrations/up/002_create_workflows.sql,sha256=2gSUk4EF7dk3mTz6MHHQ-MA6-A8tvbpI30YzgQ9zLCA,530
+src/migrations/up/003_create_events.sql,sha256=3b5uDBjuNkPom4NWUDlV0Xml4tj7BkHBoksJooC1pFk,388
+src/migrations/up/004_create_tasks.sql,sha256=xLGGDFgb0DrrBkiYUOdQ80z019v5MZE7HoA_6MLpCJg,794
+src/migrations/up/005_create_indexes.sql,sha256=1nZVwoyHJdV7YgwXCOZdWFyV0UCZI_jpjsxHyNO9u90,323
+src/migrations/up/006_auto_update_triggers.sql,sha256=hnsbGu6n5XMFKgVha2A_rw9IVRw9zB3Zw73PGOc2R3Y,447
+src/migrations/up/007_create_logs.sql,sha256=IV7vy9U1mGnN4nAZqLwTCyII9Qeeqzx-b1_sSsk1PO4,345
+src/schemas/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/schemas/activity.py,sha256=0sYvmmsVhDFFPyOHkVm0tajVaAAzoq5wY6-K03nPSos,266
+src/schemas/database.py,sha256=v9JXHWx4G_r1-SJcrCJkcnaI7Zbic-ZxtHnd7ezXrF8,282
+src/schemas/events.py,sha256=Gz-R836nVXNSsp4Y54idhKs_WTvzFPmx5KlA8PunP28,2216
+src/schemas/tasks.py,sha256=DJbLInggIGxI-CfP1kSyK79Bz83e3sZyEKh6C2HE8q4,1341
+src/schemas/workflow.py,sha256=F1cNEJRuEWLjPhGinEZE2T6vwchDC8RuTHmxEIaH6Ls,671
+loom_core-0.1.0.dist-info/METADATA,sha256=xMFFZyf9gfKbwMCCyhKKOq3uxZePKTCJweptoqgpiao,11944
+loom_core-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+loom_core-0.1.0.dist-info/entry_points.txt,sha256=CgWbuziOoZ90zDBfSlj8mpMOu3scxAzYN10vnYWn9Gk,41
+loom_core-0.1.0.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+loom_core-0.1.0.dist-info/RECORD,,

loom_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

loom_core-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+loom = src.cli.cli:cli

loom_core-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loom Contributors
+
+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.

loom_core-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+src

src/__init__.py

@@ -0,0 +1,45 @@
+"""Loom - Durable workflow orchestration engine for Python.
+
+This module provides the main API for creating and managing durable workflows.
+
+Example:
+    >>> import loom
+    >>>
+    >>> @loom.activity(name="greet", retry_count=3)
+    >>> async def greet(name: str) -> str:
+    ...     return f"Hello, {name}!"
+    >>>
+    >>> @loom.workflow(name="GreetingWorkflow", version="1.0.0")
+    >>> class GreetingWorkflow(loom.Workflow[dict, dict]):
+    ...     @loom.step(name="greet_step")
+    ...     async def greet_step(self, ctx):
+    ...         result = await ctx.activity(greet, ctx.input["name"])
+    ...         await ctx.state.set("result", result)
+"""
+
+from src.core.context import WorkflowContext
+from src.core.runner import run_once
+from src.core.worker import WorkflowWorker, start_worker
+from src.core.workflow import Workflow
+from src.database.db import Database
+from src.decorators.activity import activity
+from src.decorators.workflow import step, workflow
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Decorators
+    "activity",
+    "workflow",
+    "step",
+    # Core classes
+    "Workflow",
+    "WorkflowContext",
+    "Database",
+    "WorkflowWorker",
+    # Functions
+    "start_worker",
+    "run_once",
+    # Version
+    "__version__",
+]

src/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI module for Loom."""
+
+from .cli import cli
+
+__all__ = ["cli"]