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

First Ever 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"
+  }

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+## Contributing
+
+Thanks for helping improve fastapi-cloudflow! This guide explains how to develop locally, run tests, and the project structure expectations so contributions stay consistent.
+
+### Prerequisites
+- Python 3.13
+- [uv](https://github.com/astral-sh/uv) for env/install
+
+### Setup
+```
+uv sync
+```
+
+### Commands (local)
+- Lint: `uv run ruff check --fix .`
+- Types: `uv run ty check`
+- Unit tests: `uv run pytest -q tests/unit`
+- Codegen tests (snapshots): `uv run pytest -q tests/codegen`
+  - First run creates snapshots under `tests/codegen/fixtures/yaml` if missing; commit them
+- Full test suite: `uv run pytest -q`
+
+### Smoke tests
+Run end-to-end against deployed Workflows (requires Google Cloud project and a deployed example app):
+```
+export GOOGLE_CLOUD_PROJECT=<your-project>
+uv run -q python tests/smoke/run_smoke.py --region us-central1
+```
+
+### Project structure
+- `src/fastapi_cloudflow/`
+  - The reusable library (FastAPI-first) and CLI. Includes a FastAPI runtime (`attach_to_fastapi`) plus codegen/CLI. Keep it typed and well-tested
+
+- `examples/app/`
+  - A realistic FastAPI app showcasing multi-step, playful workflows
+  - Naming: files should reflect the workflow domain (e.g., `echo_name.py`, `post_story.py`, `jokes.py`)
+  - Every workflow is multi-step and demonstrates transformations; avoid duplicates covering the exact same feature
+
+- `tests/`
+  - `unit/`: FastAPI TestClient calls each step endpoint (`/steps/<name>`). Scope: step contracts (Pydantic I/O), route registration, and runtime error paths (422s for malformed/missing body, wrapper support)
+  - `codegen/`: Runs the CLI to generate YAML and compares full-file snapshots under `tests/codegen/fixtures/yaml`. Scope: codegen stability and header/auth/timeout/ArgExpr emission
+  - `smoke/`: Python runner that deploys Workflows and invokes them via gcloud, asserting final outputs. Scope: end-to-end validation of the example app + generated Workflows

README.md

@@ -1,2 +1,124 @@
-# fastapi-google-workflows
-Framework to create Google Cloud Workflows using FastAPI server
+[![Code Coverage](https://qlty.sh/gh/flamingo-run/projects/fastapi-google-workflows/coverage.svg)](https://qlty.sh/gh/flamingo-run/projects/fastapi-google-workflows)
+[![Maintainability](https://qlty.sh/gh/flamingo-run/projects/fastapi-google-workflows/maintainability.svg)](https://qlty.sh/gh/flamingo-run/projects/fastapi-google-workflows)
+[![CI](https://github.com/flamingo-run/fastapi-cloud-workflows/actions/workflows/ci.yml/badge.svg)](https://github.com/flamingo-run/fastapi-cloud-workflows/actions/workflows/ci.yml)
+
+
+# FastAPI Cloudflow
+
+Typed, ergonomic Google Cloud Workflows backed by FastAPI apps.
+
+Write typed steps as normal async functions, compose them with `>>`, and generate/deploy Cloud Workflows while the framework exposes first-class FastAPI step endpoints for you.
+
+## Why it’s useful
+- Define workflows in pure, typed Python (Pydantic IO models)
+- Reuse your FastAPI app: framework attaches `/steps/<name>` endpoints automatically
+- Generate stable Cloud Workflows YAML from your Python composition
+- Works great with CI (codegen snapshots) and smoke tests against real GCP
+
+## Tiny example
+```python
+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
+    status: str
+
+class OrderPlaced(BaseModel):
+    order_id: str
+    status: str
+
+@step(name="price-order")
+async def price_order(ctx: Context, data: CreateOrder) -> OrderDraft:
+    return OrderDraft(order_id="o-123", status="priced")
+
+@step(name="confirm-order")
+async def confirm_order(ctx: Context, data: OrderDraft) -> OrderPlaced:
+    return OrderPlaced(order_id=data.order_id, status="approved")
+
+ORDER_FLOW = (workflow("order-flow") >> price_order >> confirm_order).build()
+```
+- Run `fastapi-cloudflow build` and you’ll get `order-flow.yaml`
+- Attach to your FastAPI app and the framework exposes `POST /steps/price-order` with typed IO
+
+## How it works (high-level)
+```mermaid
+graph TD
+  %% GCP runtime
+  subgraph GCP
+    subgraph CloudRun
+      subgraph "FastAPI Server"
+        subgraph "steps endpoints"
+          StepCode["steps code"]
+        end
+        Other["other endpoints"]
+      end
+    end
+    subgraph CloudWorkflows
+      subgraph Workflow
+        WFStep["Step"]
+      end
+    end
+  end
+
+  %% CD pipeline
+  subgraph "Continuous Delivery"
+    subgraph Codegen
+      YAML["YAML"]
+    end
+    Deploy["Deployment"]
+  end
+
+  Codebase["Codebase"] --> Codegen
+  Codebase --> Deploy
+  Codegen --> YAML
+  YAML --> Workflow
+  WFStep -->|http.post| StepCode
+  StepCode -->|JSON| WFStep
+  Deploy --> CloudRun
+```
+
+- You write typed steps and compose with `workflow(...) >> step_a >> step_b`
+- The CLI emits Cloud Workflows YAML that uses `http.post` to call the attached FastAPI step endpoints
+- The framework injects a workflow context into each request (headers include name/run-id), and returns typed JSON bodies
+
+## Try the examples
+- See `examples/app/flows`: playful multi-step workflows
+  - `echo_name.py` → echo-name-flow: echo → extract → shout
+  - `post_story.py` → post-story-flow: build story → POST external → summarize
+  - `jokes.py` → joke-flow: fetch → split → rate
+
+## Codegen & tests
+- Codegen snapshots: `uv run -q pytest -q tests/codegen` (full-file YAML equality)
+- Unit tests: `uv run -q pytest -q tests/unit` (hits `/steps/<name>` endpoints with TestClient)
+- Smoke tests: `uv run -q python tests/smoke/run_smoke.py --region us-central1` (requires GCP & deployed example)
+
+## Supported features (Cloud Workflows)
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| HTTP calls (http.get/post/…) | ✅ | `HttpStep`; custom headers, method |
+| Auth to Cloud Run (OIDC audience) | ✅ | Python steps bake OIDC with `audience=BASE_URL` |
+| Step timeouts | ✅ | `HttpStep(timeout=…)` emits seconds |
+| Variables / assignment | ✅ | payload propagation + adapters/typed steps |
+| Expressions (concat/env/params) | ✅ | `Arg.env/param/ctx`, string concat and path join |
+| Sequential composition | ✅ | `workflow(...) >> step_a >> step_b` |
+| Workflow input/output | ✅ | single `payload` param; final `return: ${payload}` |
+| Error surfacing | ✅ | HTTP errors propagate; FastAPI returns typed 4xx/5xx |
+| Retries | ⏳ | planned `RetryPolicy` emission |
+| Try/catch | ❌ | not yet |
+| Conditionals / switch | ❌ | not yet |
+| Loops | ❌ | not yet |
+| Parallel branches / join | ❌ | not yet |
+| Subworkflows / call other workflows | ❌ | not yet |
+| GCP connectors / direct service calls | ❌ | not yet |
+
+## Next steps
+- Open CONTRIBUTING.md for local setup, structure, and contribution checklist
+- Use descriptive names for workflows/steps and prefer multi-step workflows that show transformations
+

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 --token $(PYPI_API_TOKEN)
+
+  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