Metadata-Version: 2.4
Name: velocity-workflow
Version: 1.0.0
Summary: Python SDK for V.E.L.O.C.I.T.Y.-WorkFlow - a hardware-native zero-allocation durable execution engine
Author: V.E.L.O.C.I.T.Y.-WorkFlow Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/UnitBuilds-CC/V.E.L.O.C.I.T.Y.-WorkFlow
Project-URL: Repository, https://github.com/UnitBuilds-CC/V.E.L.O.C.I.T.Y.-WorkFlow
Project-URL: Documentation, https://github.com/UnitBuilds-CC/V.E.L.O.C.I.T.Y.-WorkFlow/tree/main/docs
Keywords: workflow,temporal,durable-execution,orchestration,velocity
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: grpcio>=1.50.0
Requires-Dist: grpcio-tools>=1.50.0
Requires-Dist: protobuf>=4.21.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"

# V.E.L.O.C.I.T.Y.-WorkFlow Python SDK

Python SDK for V.E.L.O.C.I.T.Y.-WorkFlow - a hardware-native zero-allocation durable execution engine and Temporal alternative.

## Installation

```bash
pip install velocity-workflow
```

## Quick Start

### Define a Workflow

```python
from velocity import WorkflowContext

def greeting_workflow(context: WorkflowContext, input: dict) -> str:
    name = input["name"]
    print(f"Workflow started: {context.workflow_id}")
    
    # Execute an activity
    greeting = f"Hello, {name}! Welcome to V.E.L.O.C.I.T.Y.-WorkFlow."
    
    print(f"Workflow completed: {context.workflow_id}")
    return greeting
```

### Define an Activity

```python
from velocity import ActivityContext

def greet_activity(context: ActivityContext, name: str) -> str:
    print(f"Activity executing: greeting {name}")
    return f"Hello, {name}! Welcome to V.E.L.O.C.I.T.Y.-WorkFlow."
```

### Start a Worker

```python
from velocity import Worker, WorkerOptions

worker = Worker(WorkerOptions(
    namespace="default",
    task_queue="greeting-queue",
    workflows={
        "greeting-workflow": greeting_workflow,
    },
    activities={
        "greet-activity": greet_activity,
    },
))

worker.run()
```

### Start a Workflow

```python
from velocity import Client, ClientOptions, WorkflowOptions

client = Client(ClientOptions(
    host_port="localhost:7233",
    namespace="default",
))

# Start workflow
execution = client.start_workflow(WorkflowOptions(
    workflow_id="greeting-1",
    workflow_type="greeting-workflow",
    task_queue="greeting-queue",
    input={"name": "World"},
))

print(f"Started workflow: {execution.workflow_id}")

# Wait for result
handle = client.get_workflow(execution.workflow_id)
result = handle.result()
print(f"Workflow result: {result}")

client.close()
```

## Features

- **Durable Execution**: Workflows survive process crashes and server restarts
- **Activity Support**: Execute unreliable code in activities with automatic retries
- **Timers**: Sleep and schedule future work
- **Signals**: Send external events to running workflows
- **Queries**: Query workflow state without affecting execution
- **Child Workflows**: Compose workflows hierarchically
- **Search Attributes**: Index workflows for visibility
- **Memo**: Store arbitrary data with workflows

## API Reference

### Client

- `Client(options)` - Create a new client
- `start_workflow(options)` - Start a new workflow execution
- `execute_workflow(options, timeout)` - Start workflow and wait for result
- `signal_workflow(workflow_id, signal_name, input)` - Signal a running workflow
- `query_workflow(workflow_id, query_type, input)` - Query a workflow
- `terminate_workflow(workflow_id, reason)` - Terminate a workflow
- `cancel_workflow(workflow_id)` - Cancel a workflow
- `describe_workflow(workflow_id)` - Get workflow details
- `get_workflow_history(workflow_id)` - Get workflow history
- `get_workflow(workflow_id)` - Get a workflow handle

### Worker

- `Worker(options)` - Create a new worker
- `run()` - Start the worker (blocks)
- `stop()` - Stop the worker
- `is_running()` - Check if worker is running

### Workflow Registration

- `register_workflow(name, func)` - Register a workflow function
- `get_workflow(name)` - Get a registered workflow
- `has_workflow(name)` - Check if workflow is registered

### Activity Registration

- `register_activity(name, func)` - Register an activity function
- `get_activity(name)` - Get a registered activity
- `has_activity(name)` - Check if activity is registered

## Examples

See the `examples/` directory for complete examples:

- `hello_world.py` - Simple greeting workflow
- `timer.py` - Timer and sleep example
- `signal.py` - Signal handling example
- `child_workflow.py` - Child workflow composition

## Development

```bash
# Install dependencies
pip install -e ".[dev]"

# Format
black src/

# Type check
mypy src/

# Test
pytest
```

## License

MIT
