Develop

[seanharrison]

Summary

Major release introducing the Python SDK, activity waiting/human-in-the-loop support, improved examples, expanded test coverage, and GitHub CI pipelines.

Related Issues

Changes

Python SDK (py/)

• New Python client library (kruxiaflow package) with workflow submission, status querying, and output retrieval
• Python worker SDK with polling, activity registration, custom worker support, and file-based executor
• Python standard workers (kruxiaflow.workers) for running script-based activities
• Expression evaluation engine for workflow template expressions
• Comprehensive test suite (client, models, expressions, worker, YAML serialization)
• Dockerfile for containerized Python worker deployment
• Python SDK documentation: quickstart, workflow definitions, standard workers, custom workers

Activity Waiting / Human-in-the-Loop

• Activity event subscription system with PostgreSQL-backed storage (new migration)
• Orchestrator support for waiting activities that pause until an external signal resumes them
• Rust worker client with waiting support
• API signal handlers for sending signals to waiting activities
• post-mvp-6.0-waiting.md implementation plan

Rust Core & API Enhancements

• Renamed "builtin" worker to "std" across the codebase
• Worker field made optional in workflow definitions
• Output query service and API endpoints for retrieving activity outputs
• OAuth handler scaffolding
• WebSocket handler scaffolding
• Workflow definition API handlers
• Health check and status CLI commands
• Workflow template engine (core/src/workflow/template.rs)
• Streaming support for worker activities
• File executor for file-based activity execution
• Improved dependency evaluator and workflow state management
• Orchestrator backoff and configuration modules

Examples & Documentation

• All example workflows reviewed, edited, and made runnable in the new examples environment
• docker-compose.examples.yml for running examples with init DB scripts
• Updated project README with modern structure and quickstart
• Polling logs moved from debug to trace level

Testing & CI

• Test coverage increased to 92%
• GitHub Actions CI pipelines: main-ci.yml, rust-ci.yml, py-ci.yml
• New integration tests for subscriptions, orchestrator, and worker activities

Benchmarks

• Updated benchmarks to include Python standard workers
• Server benchmarks without built-in worker
• Improved resource monitoring

Type of Change

• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement

Breaking changes:

• builtin worker renamed to std — existing workflow definitions referencing worker: builtin must be updated
• worker field is now optional in activity definitions (non-breaking for existing valid definitions, but changes parsing behavior)

Testing

Describe the tests you ran to verify your changes:

• Unit tests pass (cargo test)
• Integration tests pass (./scripts/test.sh)
• Manual testing performed
• Python tests pass (cd py && uv run pytest)

Test configuration:

• OS: macOS (Darwin 24.6.0)
• Rust version: stable
• Python version: 3.12+

Checklist

• My code follows the project's style guidelines (cargo fmt)
• I have performed a self-review of my code
• I have commented my code where necessary
• I have updated the documentation as needed
• My changes generate no new warnings (cargo clippy)
• Any dependent changes have been merged and published

Additional Notes

This is a large feature branch encompassing the Python SDK, waiting/signal infrastructure, and significant API surface expansion. The builtin → std rename is a breaking change for any existing workflow definitions using worker: builtin.