stepflow-py 0.2.1__tar.gz

stepflow_py-0.2.1/.gitignore

@@ -0,0 +1,2 @@
+*.pyc
+__pycache__

stepflow_py-0.2.1/.python-version

@@ -0,0 +1 @@
+3.13

stepflow_py-0.2.1/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## <a id="0.2.1"></a> [StepFlow Python SDK 0.2.1](https://github.com/riptano/stepflow/releases/tag/stepflow-py-0.2.1) - 2025-07-29
+### Bug Fixes
+
+- Input search path and remove unneeded flow_dir variable ([#74](https://github.com/riptano/stepflow/pull/74))
+- Relax requires-python ([#180](https://github.com/riptano/stepflow/pull/180))
+
+### Documentation
+
+- Update contributing with link to conventional commits ([#121](https://github.com/riptano/stepflow/pull/121))
+- Use generated schemas in documentation ([#127](https://github.com/riptano/stepflow/pull/127))
+- Added details on error handling with examples to claude and contrib docs ([#146](https://github.com/riptano/stepflow/pull/146))
+- Updates to paths, routes, and invocations to ensure all examples are working ([#161](https://github.com/riptano/stepflow/pull/161))
+
+### Features
+
+- Generate protocol schema from Rust code ([#120](https://github.com/riptano/stepflow/pull/120))
+- Generate and use protocol types ([#122](https://github.com/riptano/stepflow/pull/122))
+- Add FlowBuilder and Value API ([#135](https://github.com/riptano/stepflow/pull/135))
+- Support `.` and `[...]` in paths ([#138](https://github.com/riptano/stepflow/pull/138))
+- Change component names URLs to paths ([#144](https://github.com/riptano/stepflow/pull/144))
+- Switch to path-based routing for components ([#145](https://github.com/riptano/stepflow/pull/145))
+- Implement protocol over HTTP+SSE ([#147](https://github.com/riptano/stepflow/pull/147))
+- Allow substitutions in environment variables ([#148](https://github.com/riptano/stepflow/pull/148))
+- Add eval method and demonstrate loop/map ([#153](https://github.com/riptano/stepflow/pull/153))
+- Change to trie-based routing ([#157](https://github.com/riptano/stepflow/pull/157))
+- Replace HTTP+SSE with Streamable HTTP ([#168](https://github.com/riptano/stepflow/pull/168))
+- Added validate to CLI args. Supports both flow and config ([#175](https://github.com/riptano/stepflow/pull/175))
+
+### Miscellaneous Tasks
+
+- Setup release scripts and documentation ([#95](https://github.com/riptano/stepflow/pull/95))
+- Update names of release workflows ([#97](https://github.com/riptano/stepflow/pull/97))
+- Configure license headers ([#115](https://github.com/riptano/stepflow/pull/115))
+- Setup CI for python ([#139](https://github.com/riptano/stepflow/pull/139))
+- Fix python lints & mypy ([#140](https://github.com/riptano/stepflow/pull/140))
+- Add scripts for the CI checks ([#156](https://github.com/riptano/stepflow/pull/156))
+- Update release process for python ([#173](https://github.com/riptano/stepflow/pull/173))
+- Change action label to stepflow-py
+- Use gh token for checkout
+- Set GITHUB_TOUKEN
+- Fix cliff.toml
+- Release stepflow-py v0.2.0 ([#179](https://github.com/riptano/stepflow/pull/179))
+
+### Refactoring
+
+- Standardize on `input` naming ([#77](https://github.com/riptano/stepflow/pull/77))
+- Remove unused components and update examples ([#111](https://github.com/riptano/stepflow/pull/111))
+- Use custom exceptions in python SDK ([#114](https://github.com/riptano/stepflow/pull/114))
+- Some doc fixes, load test scripts ([#169](https://github.com/riptano/stepflow/pull/169))
+- Update config to camel case consistently ([#170](https://github.com/riptano/stepflow/pull/170))
+- Rename stepflow-sdk to stepflow-py ([#172](https://github.com/riptano/stepflow/pull/172))
+
+## <a id="0.2.0"></a> [StepFlow Python SDK 0.2.0](https://github.com/riptano/stepflow/releases/tag/stepflow-py-0.2.0) - 2025-07-29
+### Bug Fixes
+
+- Input search path and remove unneeded flow_dir variable ([#74](https://github.com/riptano/stepflow/pull/74))
+
+### Documentation
+
+- Update contributing with link to conventional commits ([#121](https://github.com/riptano/stepflow/pull/121))
+- Use generated schemas in documentation ([#127](https://github.com/riptano/stepflow/pull/127))
+- Added details on error handling with examples to claude and contrib docs ([#146](https://github.com/riptano/stepflow/pull/146))
+- Updates to paths, routes, and invocations to ensure all examples are working ([#161](https://github.com/riptano/stepflow/pull/161))
+
+### Features
+
+- Generate protocol schema from Rust code ([#120](https://github.com/riptano/stepflow/pull/120))
+- Generate and use protocol types ([#122](https://github.com/riptano/stepflow/pull/122))
+- Add FlowBuilder and Value API ([#135](https://github.com/riptano/stepflow/pull/135))
+- Support `.` and `[...]` in paths ([#138](https://github.com/riptano/stepflow/pull/138))
+- Change component names URLs to paths ([#144](https://github.com/riptano/stepflow/pull/144))
+- Switch to path-based routing for components ([#145](https://github.com/riptano/stepflow/pull/145))
+- Implement protocol over HTTP+SSE ([#147](https://github.com/riptano/stepflow/pull/147))
+- Allow substitutions in environment variables ([#148](https://github.com/riptano/stepflow/pull/148))
+- Add eval method and demonstrate loop/map ([#153](https://github.com/riptano/stepflow/pull/153))
+- Change to trie-based routing ([#157](https://github.com/riptano/stepflow/pull/157))
+- Replace HTTP+SSE with Streamable HTTP ([#168](https://github.com/riptano/stepflow/pull/168))
+- Added validate to CLI args. Supports both flow and config ([#175](https://github.com/riptano/stepflow/pull/175))
+
+### Miscellaneous Tasks
+
+- Setup release scripts and documentation ([#95](https://github.com/riptano/stepflow/pull/95))
+- Update names of release workflows ([#97](https://github.com/riptano/stepflow/pull/97))
+- Configure license headers ([#115](https://github.com/riptano/stepflow/pull/115))
+- Setup CI for python ([#139](https://github.com/riptano/stepflow/pull/139))
+- Fix python lints & mypy ([#140](https://github.com/riptano/stepflow/pull/140))
+- Add scripts for the CI checks ([#156](https://github.com/riptano/stepflow/pull/156))
+- Update release process for python ([#173](https://github.com/riptano/stepflow/pull/173))
+- Change action label to stepflow-py
+- Use gh token for checkout
+- Set GITHUB_TOUKEN
+- Fix cliff.toml
+
+### Refactoring
+
+- Standardize on `input` naming ([#77](https://github.com/riptano/stepflow/pull/77))
+- Remove unused components and update examples ([#111](https://github.com/riptano/stepflow/pull/111))
+- Use custom exceptions in python SDK ([#114](https://github.com/riptano/stepflow/pull/114))
+- Some doc fixes, load test scripts ([#169](https://github.com/riptano/stepflow/pull/169))
+- Update config to camel case consistently ([#170](https://github.com/riptano/stepflow/pull/170))
+- Rename stepflow-sdk to stepflow-py ([#172](https://github.com/riptano/stepflow/pull/172))
+
+## [Unreleased]
+

stepflow_py-0.2.1/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: stepflow-py
+Version: 0.2.1
+Summary: Python SDK for Stepflow components and workflows.
+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'
+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.

stepflow_py-0.2.1/README.md

@@ -0,0 +1,113 @@
+# 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.

stepflow_py-0.2.1/cliff.toml

@@ -0,0 +1,86 @@
+# Configuration file for git-cliff for Python SDK package
+# See: https://git-cliff.org/docs/configuration
+
+[changelog]
+# Changelog header
+header = """
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+"""
+# Template for the changelog body
+body = """
+{%- if version -%}
+    {%- set clean_version = version | trim_start_matches(pat="stepflow-py-") -%}
+    ## <a id="{{ clean_version }}"></a> [StepFlow Python SDK {{ clean_version }}](https://github.com/riptano/stepflow/releases/tag/stepflow-py-{{ clean_version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+{%- else -%}
+    ## unreleased
+{%- endif -%}
+{%- if message %}
+    {{ message }}
+{% endif -%}
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | striptags | trim | upper_first }}
+    {% for commit in commits %}
+        - {{ commit.message | upper_first }}\
+    {%- endfor %}
+{% endfor %}\n
+"""
+# Remove the trailing whitespace in the template
+trim = true
+# Changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+# Parse the commits based on https://www.conventionalcommits.org
+conventional_commits = true
+# Filter out commits that are not conventional
+filter_unconventional = true
+# Process each line of a commit as an individual commit
+split_commits = false
+# Only include commits that affect the Python SDK directory or root files that affect Python SDK
+filter_commits = true
+# Include commits that modify files in these paths
+include_paths = [
+    "sdks/python/**",
+    "CLAUDE.md",
+    "CONTRIBUTING.md",
+    "README.md",
+    ".github/workflows/release_python.yml",
+    ".github/workflows/release_prepare.yml",
+    ".github/workflows/release_dispatch.yml",
+    ".github/workflows/ci.yml"
+]
+# Regex for preprocessing the commit messages
+commit_preprocessors = [
+  { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/riptano/stepflow/pull/${2}))"},
+]
+# Regex for parsing and grouping commits
+commit_parsers = [
+  { message = "^feat", group = "Features"},
+  { message = "^fix", group = "Bug Fixes"},
+  { message = "^doc", group = "Documentation"},
+  { message = "^perf", group = "Performance"},
+  { message = "^refactor", group = "Refactoring"},
+  { message = "^style", group = "Style"},
+  { message = "^test", group = "Testing"},
+  { message = "^chore\\(release\\):", skip = true},
+  { message = "^chore\\(deps\\)", skip = true},
+  { message = "^chore|^ci", group = "Miscellaneous Tasks"},
+  { body = ".*security", group = "Security"},
+  { message = "^revert", group = "Revert"},
+]
+# Protect breaking changes from being skipped due to matching a skipping commit_parser
+protect_breaking_commits = false
+# Glob pattern for matching git tags
+tag_pattern = "stepflow-py-[0-9.]*"
+# Regex for skipping tags
+# Regex for ignoring tags
+ignore_tags = ""
+# Sort the tags topologically
+topo_order = false
+# Sort the commits inside sections by oldest/newest order
+sort_commits = "oldest"

stepflow_py-0.2.1/examples/session_example.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  The ASF licenses this
+# file to you under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License.  You may obtain a copy of
+# the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+"""
+Example demonstrating session_id access in components.
+This shows how HTTP mode components can access their session ID.
+"""
+
+import msgspec
+
+from stepflow_py import StepflowContext, StepflowServer
+
+# Create server instance
+server = StepflowServer()
+
+
+class SessionInput(msgspec.Struct):
+    message: str
+
+
+class SessionOutput(msgspec.Struct):
+    processed_message: str
+    session_id: str | None
+    transport_mode: str
+
+
+@server.component
+def session_aware_component(
+    input: SessionInput, context: StepflowContext
+) -> SessionOutput:
+    """Component that demonstrates session_id access."""
+
+    # Access the session ID from the context
+    session_id = context.session_id
+
+    # Determine transport mode based on session_id presence
+    transport_mode = "HTTP" if session_id is not None else "STDIO"
+
+    return SessionOutput(
+        processed_message=f"Processed: {input.message}",
+        session_id=session_id,
+        transport_mode=transport_mode,
+    )
+
+
+if __name__ == "__main__":
+    # This example can be run in both STDIO and HTTP modes
+    print("Session-aware component server started")
+    print("In STDIO mode: session_id will be None")
+    print("In HTTP mode: session_id will be the actual session ID")
+    server.run()