Metadata-Version: 2.4
Name: lexigram-workflow
Version: 0.1.3005
Summary: Workflow orchestration for the Lexigram Framework (pipelines, bulk ops, sagas, graph engine)
Project-URL: Homepage, https://lexigram.dev
Project-URL: Repository, https://github.com/dbtinoy-/lexigram
Project-URL: Documentation, https://docs.lexigram.dev
Project-URL: Issues, https://github.com/dbtinoy-/lexigram/issues
Project-URL: Changelog, https://github.com/dbtinoy-/lexigram/blob/main/CHANGELOG.md
Author-email: Lexigram Framework Team <team@lexigram.dev>
Maintainer-email: Lexigram Framework Team <team@lexigram.dev>
License: MIT
License-File: LICENSE
Keywords: async,framework,lexigram,orchestration,python,saga,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: lexigram-contracts>=0.1.0
Requires-Dist: lexigram>=0.1.1
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: lexigram-testing>=0.1.1; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# lexigram-workflow

Workflow orchestration for the Lexigram Framework (pipelines, bulk ops, sagas, graph engine)

---

## Overview

lexigram-workflow provides workflow orchestration, state machines, and saga pattern for modeling complex, long-running business processes. It supports durable persistence of transition history, optimistic locking, multi-level approval chains, distributed transaction coordination with automatic rollback, and a graph engine for traversing directed graphs. All services are wired via `WorkflowProvider`, which registers workflow protocols with the DI container.

---


> Full documentation: [docs.lexigram.dev](https://docs.lexigram.dev)
## Install

```bash
uv add lexigram-workflow
```

## Quick Start

```python
from lexigram import Application
from lexigram.di.module import Module, module

# Import the module from the package
from lexigram.workflow import WorkflowModule

@module(imports=[WorkflowModule.configure()])
class AppModule(Module):
    pass

app = Application(modules=[AppModule])
if __name__ == "__main__":
    app.run()
```

## Configuration

> **Zero-config usage:** Call `WorkflowModule.configure()` with no arguments to use defaults.

### Option 1 — YAML file

```yaml
# application.yaml
workflow:
  batch_size: 10
  max_concurrency: 5
  timeout: 300.0
  retry_attempts: 3
  enable_progress_tracking: true
  pipeline_timeout: 300.0
  content_checkpoint:
    enabled: true
    inline_threshold_bytes: 1048576
    default_ttl_seconds: 86400
```

### Option 2 — Profiles + Environment Variables *(recommended)*

```bash
export LEX_WORKFLOW__ENABLED=true
# Environment variables for each field
```

### Option 3 — Python

```python
from lexigram.workflow.config import BulkOperationConfig
from lexigram.workflow import WorkflowModule

config = BulkOperationConfig(batch_size=10, max_concurrency=5, retry_attempts=3)
WorkflowModule.configure(config=config)
```

### Config reference

| Field | Default | Env var | Description |
|-------|---------|---------|-------------|
| `batch_size` | `10` | `LEX_WORKFLOW__BATCH_SIZE` | Items processed per batch during bulk operations |
| `max_concurrency` | `5` | `LEX_WORKFLOW__MAX_CONCURRENCY` | Maximum parallel operations in a bulk run |
| `timeout` | `300.0` | `LEX_WORKFLOW__TIMEOUT` | Operation timeout in seconds |
| `retry_attempts` | `3` | `LEX_WORKFLOW__RETRY_ATTEMPTS` | Automatic retry count on step failure |
| `retry_delay` | `1.0` | `LEX_WORKFLOW__RETRY_DELAY` | Seconds to wait between retry attempts |
| `enable_progress_tracking` | `true` | `LEX_WORKFLOW__ENABLE_PROGRESS_TRACKING` | Track and report bulk operation progress |
| `pipeline_timeout` | `300.0` | `LEX_WORKFLOW__PIPELINE_TIMEOUT` | Default pipeline execution timeout in seconds |
| `cc_enabled` | `true` | `LEX_WORKFLOW__CC_ENABLED` | Enable content-addressed checkpointing |
| `cc_inline_threshold_bytes` | `1048576` | `LEX_WORKFLOW__CC_INLINE_THRESHOLD_BYTES` | Max bytes to store inline before blob offload |
| `cc_default_ttl_seconds` | `86400` | `LEX_WORKFLOW__CC_DEFAULT_TTL_SECONDS` | Default TTL for cache-backed checkpoint stores |

## Module Factory Methods

| Method | Description |
|--------|-------------|
| `WorkflowModule.configure(config, saga_store)` | Configure with explicit BulkOperationConfig |
| `WorkflowModule.configure(config, saga_store, content_checkpoint_store)` | Configure with content-addressed checkpoint store |
| `WorkflowModule.stub()` | Minimal config for testing |

## Key Features

- **State machine** — Declarative states and transitions with entry/exit hooks
- **Durable persistence** — Transition history persisted to DB via `StatePersistenceProtocol`
- **Optimistic locking** — Prevents concurrent transition conflicts
- **State recovery** — Rebuild machine state from persisted history on restart
- **Approval chains** — Multi-level approval flows with role and threshold rules
- **Sagas** — Distributed transaction coordination with automatic rollback
- **Content-addressed sagas** — Idempotent stage caching keyed by `sha256(stage_id, tenant_id, inputs, handler_version, config)`; skips already-completed work on resume
- **Pipeline checkpointing** — Content-addressed checkpoint stores (`InMemory`, `Cache`, `Database`) for durable saga resume
- **Pipelines** — Step-based sequential pipelines with error handling
- **Bulk operations** — Apply an operation to many entities in a supervised batch
- **Guard conditions** — Transition guards as `async def can_confirm(self) -> bool`
- **Event hooks** — `on_enter_*`, `on_exit_*`, `on_transition` lifecycle callbacks

## Testing

```python
async with Application.boot(modules=[WorkflowModule.stub()]) as app:
    # your test code
    ...
```

## Key Source Files

| File | What it contains |
|------|----------------|
| `src/lexigram/workflow/module.py` | `WorkflowModule` class with factory methods |
| `src/lexigram/workflow/di/provider.py` | `WorkflowProvider` — wires workflow protocols into DI container |
| `src/lexigram/workflow/config.py` | `BulkOperationConfig`, `ContentCheckpointConfig`, and `GraphConfig` |
| `src/lexigram/workflow/state/` | State machine implementation with transitions and hooks |
| `src/lexigram/workflow/saga/` | Saga pattern implementation with compensating transactions and content-addressed caching |
| `src/lexigram/workflow/pipeline/` | Pipeline executor for chaining steps |
| `src/lexigram/workflow/approval/` | Approval chain and levels |
| `src/lexigram/workflow/checkpoint/` | Content-addressed checkpoint stores (in-memory, cache, database) |