Merge pull request #1 from flamingo-run/feature/first-version

First Version

Author: joaodaher

.github/actions/setup-env/action.yml

@@ -0,0 +1,22 @@
+name: Setup FastAPI Cloudflow Environment
+description: Common environment setup for all FastAPI Cloudflow jobs
+
+inputs:
+  github-token:
+    description: 'GitHub token for authentication'
+    required: false
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/checkout@v4
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+    - name: Install Task
+      uses: arduino/setup-task@v2
+      with:
+        version: 3.x
+        repo-token: ${{ inputs.github-token }}
+    - name: Install dependencies
+      run: task install-dev
+      shell: bash

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-env
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Lint with Ruff and Ty
+        run: task lint
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-env
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Run tests
+        run: task test
+      - name: Report Coverage
+        run: uv run coverage lcov
+      - uses: qltysh/qlty-action/coverage@v1
+        with:
+          token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
+          files: coverage.lcov
+  
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-env
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build package
+        run: task build

.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Tag & Release Package
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-env
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Detect version upgrade
+        id: versioning
+        run: |
+          package_version=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          echo "package_version=$package_version" >> $GITHUB_OUTPUT
+          upgraded=$(git tag --list | grep -q "${package_version}$" && echo "false" || echo "true")
+          echo "upgraded=$upgraded" >> $GITHUB_OUTPUT
+          pre_release=$([[ $package_version =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] && echo "false" || echo "true")
+          echo "pre_release=$pre_release" >> $GITHUB_OUTPUT
+          main_branch_release=$([[ $pre_release == "false" && $GITHUB_REF_NAME == "main" ]] && echo "true" || echo "false")
+          alternative_branch_release=$([[ $pre_release == "true" && $GITHUB_REF_NAME != "main" ]] && echo "true" || echo "false")
+          should_release=$([[ $upgraded == "true" && ($main_branch_release == "true" || $alternative_branch_release == "true") ]] && echo "true" || echo "false")
+          echo "should_release=$should_release" >> $GITHUB_OUTPUT
+          echo "upgraded=$upgraded"
+          echo "pre_release=$pre_release"
+          echo "git_ref=$GITHUB_REF_NAME"
+          echo "main_branch_release=$main_branch_release"
+          echo "alternative_branch_release=$alternative_branch_release"
+          echo "should_release=$should_release"
+      - name: Create Release
+        if: ${{ steps.versioning.outputs.should_release == 'true' }}
+        run: gh release create ${{ steps.versioning.outputs.package_version }} --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build & Publish package
+        if: ${{ steps.versioning.outputs.should_release == 'true' }}
+        run: |
+          task build
+          uv publish

.python-version

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

.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+    "[python]": {
+      "editor.formatOnSave": true,
+      "editor.codeActionsOnSave": {
+        "source.fixAll.ruff": "always",
+        "source.organizeImports.ruff": "always"
+      },
+      "editor.detectIndentation": false,
+      "editor.tabSize": 4,
+      "editor.defaultFormatter": "charliermarsh.ruff",
+      "editor.rulers": [
+        120
+      ],
+    },
+    "python.analysis.autoImportCompletions": true,
+    "python.formatting.provider": "none",
+    "python.languageServer": "None",
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "python.defaultInterpreterPath": "${workspaceRoot}/.venv/bin/python",
+    "debug.allowBreakpointsEverywhere": true,
+    "ruff.nativeServer": "on"
+  }

README.md

@@ -1,2 +1,35 @@
-# fastapi-google-workflows
-Framework to create Google Cloud Workflows using FastAPI server
+# fastapi-cloudflow
+Typed Python-to-Google Cloud Workflows for FastAPI apps. Define steps as typed functions, compose with `>>`, generate Workflows YAML and attach endpoints to your FastAPI app automatically.
+
+## Quickstart (uv + Python 3.13)
+
+```bash
+uv run fastapi-cloudflow serve --module app.flows.order
+```
+
+Call your workflow locally:
+
+```bash
+curl -s localhost:8000/wf/order-flow/run \
+  -H 'Content-Type: application/json' \
+  -d '{"account_id":1,"sku":"abc","qty":2}'
+```
+
+Emit YAML:
+
+```bash
+uv run fastapi-cloudflow build --module app.flows.order
+```
+
+Attach to an existing FastAPI app:
+
+```python
+from fastapi import FastAPI
+from fastapi_cloudflow import attach_to_fastapi
+from app.flows.order import WORKFLOWS
+
+app = FastAPI()
+attach_to_fastapi(app, WORKFLOWS)
+```
+
+See `docs/` for architecture, decisions, and roadmap.

Taskfile.yml

@@ -0,0 +1,81 @@
+version: '3'
+
+tasks:
+  install:
+    desc: Install production dependencies
+    cmds:
+      - uv sync --no-dev
+
+  install-dev:
+    desc: Install development dependencies
+    cmds:
+      - uv sync --group docs --group dev
+      - uv pip install -e .
+
+  install-docs:
+    desc: Install documentation dependencies
+    cmds:
+      - uv sync --group docs
+
+  update:
+    desc: Update dependencies
+    cmds:
+      - uv lock --upgrade
+
+  test:
+    desc: Run tests
+    deps: [install-dev]
+    cmds:
+      - uv run pytest
+
+  lint:
+    desc: Run linting
+    cmds:
+      - uv run ruff check .
+      - uv run ruff format --check .
+      - uv run ty check
+
+  format:
+    desc: Format code
+    cmds:
+      - uv run ruff format .
+      - uv run ruff check --fix --unsafe-fixes .
+
+  clean:
+    desc: Clean build artifacts
+    cmds:
+      - rm -rf build/
+      - rm -rf dist/
+      - rm -rf src/*.egg-info/
+      - rm -rf .coverage
+      - rm -rf htmlcov/
+
+  build:
+    desc: Build package
+    deps: [clean]
+    cmds:
+      - uv build
+
+  publish:
+    desc: Publish to PyPI
+    deps: [build]
+    cmds:
+      - uv publish
+
+  docs-build:
+    desc: Build the documentation
+    deps: [install-docs]
+    cmds:
+      - uv run mkdocs build --config-file ./mkdocs.yml
+
+  docs-serve:
+    desc: Serve the documentation locally
+    deps: [install-docs]
+    cmds:
+      - uv run mkdocs serve --config-file ./mkdocs.yml
+
+  docs-deploy:
+    desc: Deploy documentation to GitHub Pages
+    deps: [install-docs]
+    cmds:
+      - uv run mkdocs gh-deploy --config-file ./mkdocs.yml

app/flows/order.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from decimal import Decimal
+from uuid import uuid4
+
+from pydantic import BaseModel
+
+from fastapi_cloudflow import Context, step, workflow
+
+
+class CreateOrder(BaseModel):
+    account_id: int
+    sku: str
+    qty: int
+
+
+class OrderDraft(BaseModel):
+    order_id: str
+    price: Decimal
+
+
+class PaymentAuth(BaseModel):
+    order_id: str
+    status: str
+
+
+@step(name="price-order")
+async def price_order(ctx: Context, data: CreateOrder) -> OrderDraft:
+    return OrderDraft(order_id=f"o-{uuid4().hex}", price=Decimal("12.34"))
+
+
+@step(name="auth-payment")
+async def auth_payment(ctx: Context, data: OrderDraft) -> PaymentAuth:
+    return PaymentAuth(order_id=data.order_id, status="approved")
+
+
+# Building the workflow auto-registers it in the registry
+ORDER_FLOW = (workflow("order-flow") >> price_order >> auth_payment).build()

app/flows/payments.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from fastapi_cloudflow import Arg, AssignStep, Context, HttpStep, step, workflow
+
+
+class Cart(BaseModel):
+    total: float
+    currency: str
+
+
+class PSPReq(BaseModel):
+    amount: float
+    currency: str
+
+
+class PSPRes(BaseModel):
+    status: str
+    psp_id: str
+
+
+@step(name="validate-cart")
+async def validate_cart(ctx: Context, data: Cart) -> Cart:
+    assert data.total >= 0
+    return data
+
+
+to_psp = AssignStep("cart->psp", Cart, PSPReq, expr={"amount": "${payload.total}", "currency": "${payload.currency}"})
+
+psp = HttpStep("psp-charge", PSPReq, PSPRes, method="POST", url=Arg.env("PSP_URL") / "charge")
+
+
+class ChargeResult(BaseModel):
+    ok: bool
+    txn_id: str | None
+
+
+@step(name="summarize-charge")
+async def summarize_charge(ctx: Context, data: PSPRes) -> ChargeResult:
+    return ChargeResult(ok=(data.status == "approved"), txn_id=data.psp_id)
+
+
+PAYMENT_FLOW = (workflow("payment-flow") >> validate_cart >> to_psp >> psp >> summarize_charge).build()