Metadata-Version: 2.4
Name: stepflow-py
Version: 0.4.0
Summary: Python SDK for Stepflow components and workflows.
Project-URL: Homepage, https://stepflow-ai.github.io/stepflow/
Project-URL: Documentation, https://stepflow-ai.github.io/stepflow/
Project-URL: Repository, https://github.com/stepflow-ai/stepflow
Project-URL: Bug Tracker, https://github.com/stepflow-ai/stepflow/issues
Project-URL: Changelog, https://github.com/stepflow-ai/stepflow/blob/main/sdks/python/CHANGELOG.md
Project-URL: Source Code, https://github.com/stepflow-ai/stepflow/tree/main/sdks/python
Author: DataStax Inc.
Maintainer: DataStax Inc.
License: Apache-2.0
Keywords: ai,automation,components,orchestration,pipeline,stepflow,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.17.0
Requires-Dist: msgspec>=0.19.0
Requires-Dist: types-jsonschema>=4.17.0
Provides-Extra: http
Requires-Dist: fastapi>=0.104.1; extra == 'http'
Requires-Dist: sse-starlette>=1.6.5; extra == 'http'
Requires-Dist: uvicorn>=0.24.0; extra == 'http'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Description-Content-Type: text/markdown

# Stepflow Python SDK

Python SDK for building Stepflow components and workflows.

## Installation

```bash
# Install from source
uv add stepflow-py
```

## Usage

### Creating a Component Server

```python
from stepflow_py import StepflowStdioServer, StepflowContext
import msgspec

# Define input/output types
class MyInput(msgspec.Struct):
    message: str
    count: int

class MyOutput(msgspec.Struct):
    result: str

# Create server
server = StepflowStdioServer()

# Register a component
@server.component
def my_component(input: MyInput) -> MyOutput:
    return MyOutput(result=f"Processed: {input.message} x{input.count}")

# Component with context (for blob operations)
@server.component
async def component_with_context(input: MyInput, context: StepflowContext) -> MyOutput:
    # Store data as a blob
    blob_id = await context.put_blob({"processed": input.message})
    return MyOutput(result=f"Stored blob: {blob_id}")

# Run the server
if __name__ == "__main__":
    server.run()
```

### Using the Context API

The `StepflowContext` provides bidirectional communication with the Stepflow runtime:

```python
# Store JSON data as a blob
blob_id = await context.put_blob({"key": "value"})

# Retrieve blob data
data = await context.get_blob(blob_id)

# Logging
context.log("Debug message")
```

## Development

### Running Tests

```bash
uv run pytest
```

### Type Checking

```bash
uv run mypy src/
```

### Protocol Generation

This SDK uses auto-generated protocol types from the JSON schema. To regenerate the protocol types when the schema changes:

```bash
uv run python generate.py
```

The generation script automatically handles the generation and applies necessary fixes for msgspec compatibility.

### Project Structure

- `src/stepflow_py/` - Main SDK code
  - `generated_protocol.py` - Auto-generated protocol types from JSON schema
  - `protocol.py` - Hybrid protocol layer with envelope patterns for efficient deserialization
  - `server.py` - Component server implementation
  - `context.py` - Runtime context API
  - `exceptions.py` - SDK-specific exceptions
- `tests/` - Test suite

### Architecture

The SDK uses a hybrid approach for protocol handling:

1. **Generated Types** (`generated_protocol.py`) - Auto-generated from the Stepflow JSON schema using `datamodel-code-generator`
2. **Protocol Layer** (`protocol.py`) - Combines generated types with manual envelope patterns for two-stage deserialization using `msgspec.Raw`
3. **Server Implementation** - Uses the protocol layer for efficient JSON-RPC message handling

This design provides:
- **Type Safety** - All protocol messages use properly typed structs
- **Schema Consistency** - Generated types match the Rust protocol exactly
- **Performance** - Two-stage deserialization with `msgspec.Raw` for optimal speed
- **Maintainability** - Protocol changes can be regenerated automatically

## License

Licensed under the Apache License, Version 2.0.