refactor(sdk): rewrite SDK for ServerlessWorkflow 1.0 specification

Complete rewrite of the Python SDK to conform to the Serverless Workflow
specification v1.0, replacing the previous v0.8 implementation.

- Replace WorkflowValidator with automatic parsing validation
- `base.py`: New base types (Duration, Error, Timeout, Input/Output, etc.)
- `authentication.py`: OAuth2, OIDC, Bearer, Basic, Digest auth policies
- `call_tasks.py`: HTTP, gRPC, OpenAPI, AsyncAPI, MCP function calls
- `tasks.py`: Core task types (Do, Fork, For, Listen, Emit, Set, Switch, Try, Wait, Run, Raise)
- `events.py`: Event consumption strategies and correlation
- `retry.py`: Retry policies with backoff strategies
- `endpoint.py`: Endpoint and catalog definitions
- `draw.py`: Workflow visualization using Graphviz (930 lines)
- `workflow.py`: Rewritten Workflow class with Document, Schedule, Use components
- Replace Pipfile/pipenv with pyproject.toml/uv
- Add pre-commit hooks configuration
- Add specification submodule for validation testing
- Update to Python 3.10+
- Configure ruff for linting/formatting, mypy for type checking
- Modernize GitHub Actions workflow
- Split into separate lint, test, build jobs
- Add ruff linting and formatting checks
- Add mypy type checking
- Test matrix: Python 3.10, 3.11, 3.12
- Use uv for faster dependency management
- Remove old v0.8 test examples (13 JSON files)
- Add comprehensive v1.0 spec validation tests (1,748 lines)
- Add visualization tests with 74 DOT fixtures
- Test against official specification examples via submodule
- Update README for v1.0 API with modern examples
- Replace state-based examples with task-based patterns
- Update installation instructions for uv
- Document workflow visualization capabilities
- Reference new test locations

## Breaking Changes
- Complete API rewrite - no backwards compatibility with v0.8
- All state classes removed
- WorkflowValidator removed (validation now automatic)
- StateMachineHelper replaced with workflow.render_graph()

Author: arminhammer

.github/workflows/python-ci.yml

@@ -7,28 +7,66 @@ on:
     branches: ["main"]
 
 jobs:
-  tests:
-    name: "Python 3.9"
+  lint:
+    name: "Lint (ruff, mypy)"
     runs-on: "ubuntu-latest"
+    steps:
+      - uses: "actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683" # v4.2.2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version-file: "pyproject.toml"
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Run ruff (linting)
+        run: uv run ruff check .
+      - name: Run ruff (formatting)
+        run: uv run ruff format --check .
+      - name: Run mypy
+        run: uv run mypy serverlessworkflow
 
+  test:
+    name: "Test (Python ${{ matrix.python-version }})"
+    runs-on: "ubuntu-latest"
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
     steps:
       - uses: "actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683" # v4.2.2
-      - uses: "actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065" # v5.6.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: '3.9'
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
       - name: Install graphviz
         run: |
           sudo apt-get update
           sudo apt-get install graphviz graphviz-dev
       - name: Install dependencies
-        run: |
-          pip install pipenv
-          pip install build
-          pipenv install --dev --system
-          pip install setuptools==70.3.0
-      - name: Test
-        run: |
-          pipenv run pytest
-      - name: Build
-        run: |
-          python -m build
+        run: uv sync --all-extras
+      - name: Run pytest
+        run: uv run pytest
+
+  build:
+    name: "Build package"
+    runs-on: "ubuntu-latest"
+    needs: [lint, test]
+    steps:
+      - uses: "actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683" # v4.2.2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version-file: "pyproject.toml"
+      - name: Build package
+        run: uv build

.gitignore

@@ -132,3 +132,6 @@ dmypy.json
 .idea
 .vscode
 *.iml
+
+tests/visualization/outputs/*
+tests/visualization/fixtures/*.png

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "submodules/specification"]
+	path = submodules/specification
+	url = https://github.com/serverlessworkflow/specification.git

.pre-commit-config.yaml

@@ -0,0 +1,157 @@
+# Pre-commit hooks for Python projects
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+
+default_language_version:
+  python: python3.10
+
+repos:
+  # General file checks
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.5.0
+  hooks:
+      # Prevent giant files from being committed
+  - id: check-added-large-files
+    args: [--maxkb=1000]
+      # Check for files that would conflict in case-insensitive filesystems
+  - id: check-case-conflict
+      # Check for merge conflicts
+  - id: check-merge-conflict
+      # Check for debugger imports and py37+ breakpoint()
+  - id: debug-statements
+      # Check JSON files are valid
+  - id: check-json
+      # Check TOML files are valid
+  - id: check-toml
+      # Check YAML files are valid
+  - id: check-yaml
+    args: [--unsafe]        # Allow custom YAML tags
+      # Ensure files end with a newline
+  - id: end-of-file-fixer
+      # Remove trailing whitespace
+  - id: trailing-whitespace
+    args: [--markdown-linebreak-ext=md]
+      # Fix mixed line endings
+  - id: mixed-line-ending
+    args: [--fix=lf]
+      # Check docstrings are valid Python
+  - id: check-docstring-first
+      # Check for symlinks that point to nothing
+  - id: check-symlinks
+      # Detect private keys
+  - id: detect-private-key
+
+  # Ruff - Fast Python linter and formatter (replaces Black, isort, flake8, pylint)
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.2.1
+  hooks:
+      # Run the linter
+  - id: ruff
+    args: [--fix, --exit-non-zero-on-fix]
+      # Run the formatter
+  - id: ruff-format
+
+  # Type checking with mypy
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v1.8.0
+  hooks:
+  - id: mypy
+    additional_dependencies:
+    - types-PyYAML
+    - types-requests
+    args: [--ignore-missing-imports, --warn-unused-configs]
+        # Only run on serverlessworkflow package, not tests
+    files: ^serverlessworkflow/
+
+  # Security checks
+- repo: https://github.com/PyCQA/bandit
+  rev: 1.7.6
+  hooks:
+  - id: bandit
+    args: [-c, pyproject.toml]
+    additional_dependencies: ['bandit[toml]']
+        # Skip tests directory
+    exclude: ^tests/
+
+  # # Check for common security issues
+  # - repo: https://github.com/Lucas-C/pre-commit-hooks-safety
+  #   rev: v1.3.3
+  #   hooks:
+  #     - id: python-safety-dependencies-check
+  #       files: pyproject.toml
+
+  # Markdown formatting
+- repo: https://github.com/executablebooks/mdformat
+  rev: 0.7.17
+  hooks:
+  - id: mdformat
+    additional_dependencies:
+    - mdformat-gfm        # GitHub Flavored Markdown
+    - mdformat-black        # Format code blocks with black style
+    args: [--wrap, '100']
+
+  # Check for spelling errors
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.2.6
+  hooks:
+  - id: codespell
+    args: [--ignore-words-list=crate]
+    exclude: ^(poetry.lock|package-lock.json|\.git/|\.pytest_cache/|\.mypy_cache/)
+
+  # Validate GitHub Actions workflows
+- repo: https://github.com/python-jsonschema/check-jsonschema
+  rev: 0.27.4
+  hooks:
+  - id: check-github-workflows
+  - id: check-dependabot
+
+  # YAML formatting
+- repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
+  rev: v2.12.0
+  hooks:
+  - id: pretty-format-yaml
+    args: [--autofix, --indent, '2']
+    exclude: ^(\.github/|examples/)      # Exclude workflow files and examples
+
+  # pyproject.toml formatting
+- repo: https://github.com/tox-dev/pyproject-fmt
+  rev: 1.7.0
+  hooks:
+  - id: pyproject-fmt
+
+  # Check for outdated Python syntax
+- repo: https://github.com/asottile/pyupgrade
+  rev: v3.15.0
+  hooks:
+  - id: pyupgrade
+    args: [--py310-plus]
+
+  # Check requirements files
+- repo: https://github.com/Lucas-C/pre-commit-hooks
+  rev: v1.5.4
+  hooks:
+  - id: forbid-crlf
+  - id: remove-crlf
+  - id: forbid-tabs
+  - id: remove-tabs
+
+  # Conventional commits
+- repo: https://github.com/compilerla/conventional-pre-commit
+  rev: v3.0.0
+  hooks:
+  - id: conventional-pre-commit
+    stages: [commit-msg]
+    args: [--force-scope]
+
+# CI configuration
+ci:
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from pre-commit.com hooks
+
+    for more information, see https://pre-commit.ci
+  autofix_prs: true
+  autoupdate_branch: ''
+  autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate'
+  autoupdate_schedule: weekly
+  skip: []
+  submodules: false