Merge remote-tracking branch 'origin/main'

Author: ovvesley

.github/workflows/checks.yml

@@ -11,63 +11,31 @@ permissions:
   packages: write
 
 jobs:
-  experiment-tools:
-    name: Test experiment tools
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-      - name: Run Python tests
-        run: python -m unittest discover -s experiments -p 'test_*.py'
+  checks:
+    name: Central AkôFlow example CI
+    uses: UFFeScience/akoflow/.github/workflows/examples-ci.yml@main
+    with:
+      examples_ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      publish: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    permissions:
+      contents: read
+      packages: write
 
-  showcase:
-    name: Validate ${{ matrix.showcase }}
+  notify-documentation:
+    name: Notify AkôFlow documentation
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - {category: machine-learning, showcase: training-with-mlflow}
-          - {category: machine-learning, showcase: hyperparameter-search}
-          - {category: machine-learning, showcase: batch-inference}
-          - {category: machine-learning, showcase: model-comparison}
-          - {category: machine-learning, showcase: anomaly-detection}
-          - {category: machine-learning, showcase: computer-vision}
-          - {category: machine-learning, showcase: model-ensemble}
-          - {category: machine-learning, showcase: model-distillation}
-          - {category: machine-learning, showcase: inference-benchmark}
-          - {category: machine-learning, showcase: lora-fine-tuning}
-          - {category: machine-learning, showcase: model-conversion}
-          - {category: machine-learning, showcase: infrastructure-selection}
-          - {category: generative-ai, showcase: rag-indexing}
-          - {category: generative-ai, showcase: synthetic-dataset}
-          - {category: generative-ai, showcase: audio-transcription}
-          - {category: generative-ai, showcase: document-extraction}
-          - {category: agentic-workflows, showcase: bounded-agent}
-          - {category: agentic-workflows, showcase: supervised-tool-loop}
-          - {category: agentic-workflows, showcase: multi-agent-review}
-          - {category: scientific-ai, showcase: ai-assisted-analysis}
-          - {category: scientific-ai, showcase: surrogate-model}
-          - {category: scientific-ai, showcase: experiment-feedback-loop}
     steps:
-      - uses: actions/checkout@v4
-      - name: Execute regression fixture
-        working-directory: ${{ matrix.category }}/${{ matrix.showcase }}
-        run: ./run.sh
-      - uses: docker/login-action@v3
-        if: github.event_name == 'push'
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - uses: docker/build-push-action@v6
-        with:
-          context: ${{ matrix.category }}/${{ matrix.showcase }}
-          file: ${{ matrix.category }}/${{ matrix.showcase }}/docker/Dockerfile
-          push: ${{ github.event_name == 'push' }}
-          tags: |
-            ghcr.io/uffescience/akoflow-showcase-${{ matrix.showcase }}:latest
-            ghcr.io/uffescience/akoflow-showcase-${{ matrix.showcase }}:v1
-            ghcr.io/uffescience/akoflow-showcase-${{ matrix.showcase }}:v1.0.0
+      - name: Dispatch documentation rebuild
+        env:
+          GH_TOKEN: ${{ secrets.AKOFLOW_DOCS_DISPATCH_TOKEN }}
+          SOURCE_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "AKOFLOW_DOCS_DISPATCH_TOKEN is not configured; the daily reconciliation will pick up this change."
+            exit 0
+          fi
+          gh api repos/UFFeScience/akoflow/dispatches \
+            --method POST \
+            --field event_type=examples-updated \
+            --field "client_payload[source_sha]=$SOURCE_SHA"

AGENTS.md

@@ -0,0 +1,12 @@
+# Repository working conventions
+
+## Branch names
+
+- Every change associated with a GitHub issue must use the exact branch name
+  `AKO-<N>`, where `<N>` is that issue's numeric identifier.
+- Examples: issue `#5` uses `AKO-5`; issue `#142` uses `AKO-142`.
+- Do not add personal, tool, or category prefixes such as `codex/`, `feat/`, or
+  `docs/` to issue branches.
+- Create the issue before creating its implementation branch so the identifier
+  is authoritative.
+

README.md

@@ -11,8 +11,8 @@ assets, and validation workflows can evolve independently from the engine.
 
 - `simulation/`, `local/`, `kind/`, `slurm/`, and `real/`: execution and
   infrastructure examples.
-- `machine-learning/`, `generative-ai/`, `agentic-workflows/`, and
-  `scientific-ai/`: complete showcase workflows.
+- `machine-learning/`, `generative-ai/`, `document-ai/`, `media/`, `rendering/`,
+  `agentic-workflows/`, and `scientific-ai/`: complete showcase workflows.
 - `connections/`, `onboarding/`, and `server-instance/`: reusable connection
   and installation templates.
 - `experiments/`: Python and Node.js tools used to launch, collect, analyze,
@@ -23,4 +23,30 @@ own directory with `./run.sh`. Most API-driven examples expect an AkôFlow
 daemon at `http://localhost:8080` and accept the usual AkôFlow environment
 variables for endpoint and token overrides.
 
+Showcase workflow documents declare an OCI image and a structured command for
+each activity. They never invoke `docker run`: AkôFlow owns image delivery and
+container startup for the selected runtime. The local `run.sh` fixture executes
+the deterministic workload directly, while CI builds and validates the image as
+a separate concern.
+
 Product documentation is published at [akoflow.com](https://akoflow.com).
+
+New runnable examples follow the [showcase standard](SHOWCASE_STANDARD.md):
+offline smoke execution, real computation, observable stages, stable artifact
+contracts, and optional larger profiles.
+
+## Continuous integration
+
+The example files live in this repository, while the reusable CI implementation
+is maintained in `UFFeScience/akoflow/.github/workflows/examples-ci.yml`. The
+small workflow in this repository passes the exact pull-request or `main`
+commit to that central workflow. Runnable showcases are discovered from their
+`docker/Dockerfile` and executable `run.sh`; adding a showcase does not require
+editing a duplicated matrix.
+
+After a push to `main`, CI publishes validated showcase images to GHCR and
+notifies the AkôFlow documentation workflow. Configure the repository secret
+`AKOFLOW_DOCS_DISPATCH_TOKEN` with access to dispatch workflows in
+`UFFeScience/akoflow`. If the secret is temporarily unavailable, the daily
+documentation reconciliation still checks out this repository and validates
+all referenced example files.

SHOWCASE_STANDARD.md

@@ -0,0 +1,33 @@
+# Runnable showcase standard
+
+New end-to-end showcases must be reproducible workloads, not timing simulations.
+They follow this contract:
+
+1. **Correct domain ownership.** Store the example under its technical domain
+   (`generative-ai`, `document-ai`, `media`, `rendering`, and so on), never a
+   marketing category.
+2. **Offline execution.** `run.sh` must complete without network access. Small
+   fixtures belong in `data/`; large public datasets may have an explicit
+   preparation script, checksum, license note, and deterministic local fallback.
+3. **Observable stages.** Each meaningful computation is a separate AkôFlow
+   activity. Parallel work is expressed with `dependsOn`, and activities exchange
+   artifacts only through the execution workspace.
+4. **Real computation.** Stages process data with the declared toolchain. Do not
+   use `sleep` or precomputed outputs to imitate work.
+5. **Portable smoke profile.** The default run is CPU-compatible and small enough
+   for CI. `AKOFLOW_PROFILE=demo`, `standard`, or `stress` may increase dataset
+   size, frame count, model size, or repetitions without changing the DAG.
+6. **Stable result contract.** A successful run writes `outputs/manifest.json`
+   with `showcase`, `status`, and `artifacts`. `validate.sh` checks semantics and
+   non-empty artifacts, not only process exit status.
+7. **Container parity.** `docker/Dockerfile` contains every runtime dependency and
+   invokes the same stage runner used by `run.sh`.
+8. **Complete AkôFlow inputs.** Every showcase includes `workflow.yaml`,
+   `environment.yaml`, `scope.yaml`, and `topology.yaml` plus a concise README.
+9. **Safe optional integrations.** Hosted APIs, Ollama, GPU acceleration, and
+   external storage are opt-in adapters. Secrets never appear in fixtures,
+   commands, logs, or committed output.
+
+The five reference implementations are AI Video Studio, Document Intelligence,
+Local RAG Factory, Video Intelligence, and Blender Render Farm.
+

agentic-workflows/bounded-agent/run.sh

@@ -1,11 +1,8 @@
 #!/bin/sh
 set -eu
 root=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-image="akoflow-showcase-bounded-agent:dev"
 rm -rf "$root/outputs" "$root/screenshots"
 mkdir -p "$root/outputs" "$root/screenshots"
-docker build --tag "$image" --file "$root/docker/Dockerfile" "$root"
-docker run --rm --mount "type=bind,src=$root/outputs,dst=/outputs" "$image"
+python3 "$root/scripts/run_showcase.py" --output "$root/outputs"
 node "$root/scripts/capture_screenshots.mjs"
 "$root/validate.sh"
-

agentic-workflows/bounded-agent/scripts/run_showcase.py

@@ -1,16 +1,30 @@
 #!/usr/bin/env python3
 """Deterministic, dependency-free executable for an AkôFlow showcase image."""
 from __future__ import annotations
-import csv, hashlib, json, pickle, sys
+import argparse, csv, hashlib, json, pickle
 from pathlib import Path
 
-root = Path("/app")
-config = json.loads((root / "scenario.json").read_text())
-out = Path(sys.argv[1] if len(sys.argv) > 1 else "/outputs")
+source_root = Path(__file__).resolve().parents[1]
+container_config = Path("/app/scenario.json")
+config_path = container_config if container_config.exists() else source_root / "data/input.json"
+config = json.loads(config_path.read_text())
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--stage", choices=config["stages"])
+parser.add_argument("--output", default="/outputs" if container_config.exists() else str(source_root / "outputs"))
+args = parser.parse_args()
+
+stage = args.stage
+if stage is not None and stage not in config["stages"]:
+    raise SystemExit(f"unknown stage: {stage}")
+out = Path(args.output)
 out.mkdir(parents=True, exist_ok=True)
 digest = hashlib.sha256(json.dumps(config, sort_keys=True).encode()).hexdigest()
-record = {"showcase": config["slug"], "digest": digest, "stages": config["stages"], "status": "success"}
-for name in config["artifacts"]:
+selected_stages = [stage] if stage is not None else config["stages"]
+record = {"showcase": config["slug"], "digest": digest, "stages": selected_stages, "status": "success"}
+if stage is not None:
+    (out / f"stage-{stage}.json").write_text(json.dumps({**record, "stage": stage}, indent=2) + "\n")
+for name in config["artifacts"] if stage is None or stage == config["stages"][-1] else []:
     path = out / name
     if name.endswith(".json"):
         path.write_text(json.dumps({**record, "artifact": name}, indent=2) + "\n")
@@ -27,5 +41,7 @@
         path.write_text("# " + config["title"] + "\n\n" + json.dumps(record, indent=2) + "\n")
     else:
         path.write_text(json.dumps({**record, "artifact": name}) + "\n")
-(out / "manifest.json").write_text(json.dumps({**record, "artifacts": config["artifacts"]}, indent=2) + "\n")
-
+if stage is None or stage == config["stages"][-1]:
+    (out / "manifest.json").write_text(
+        json.dumps({**record, "artifacts": config["artifacts"]}, indent=2) + "\n"
+    )

agentic-workflows/bounded-agent/workflow.yaml

@@ -1,27 +1,33 @@
 name: showcase-bounded-agent
 spec:
   namespace: showcase
-  # Published by .github/workflows/build-showcase.yml.
-  image: ghcr.io/uffescience/akoflow-showcase-bounded-agent:v1
+  # AkôFlow starts this OCI image; activities only declare commands inside it.
+  image: ghcr.io/uffescience/akoflow-examples/showcase-bounded-agent:v1
   activities:
     - name: goal
       runtime: local
-      # The local executor launches this OCI image through Docker in run.sh.
-      run: docker run --rm ghcr.io/uffescience/akoflow-showcase-bounded-agent:v1 goal
+      command:
+        entrypoint: python
+        arguments: ["/app/run_showcase.py", "--stage", "goal", "--output", "."]
+        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
     - name: agent
       runtime: local
-      # The local executor launches this OCI image through Docker in run.sh.
-      run: docker run --rm ghcr.io/uffescience/akoflow-showcase-bounded-agent:v1 agent
+      command:
+        entrypoint: python
+        arguments: ["/app/run_showcase.py", "--stage", "agent", "--output", "."]
+        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
       dependsOn:
         - goal
     - name: validator
       runtime: local
-      # The local executor launches this OCI image through Docker in run.sh.
-      run: docker run --rm ghcr.io/uffescience/akoflow-showcase-bounded-agent:v1 validator
+      command:
+        entrypoint: python
+        arguments: ["/app/run_showcase.py", "--stage", "validator", "--output", "."]
+        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
       dependsOn:

agentic-workflows/multi-agent-review/run.sh

@@ -1,11 +1,8 @@
 #!/bin/sh
 set -eu
 root=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-image="akoflow-showcase-multi-agent-review:dev"
 rm -rf "$root/outputs" "$root/screenshots"
 mkdir -p "$root/outputs" "$root/screenshots"
-docker build --tag "$image" --file "$root/docker/Dockerfile" "$root"
-docker run --rm --mount "type=bind,src=$root/outputs,dst=/outputs" "$image"
+python3 "$root/scripts/run_showcase.py" --output "$root/outputs"
 node "$root/scripts/capture_screenshots.mjs"
 "$root/validate.sh"
-

agentic-workflows/multi-agent-review/scripts/run_showcase.py

@@ -1,16 +1,30 @@
 #!/usr/bin/env python3
 """Deterministic, dependency-free executable for an AkôFlow showcase image."""
 from __future__ import annotations
-import csv, hashlib, json, pickle, sys
+import argparse, csv, hashlib, json, pickle
 from pathlib import Path
 
-root = Path("/app")
-config = json.loads((root / "scenario.json").read_text())
-out = Path(sys.argv[1] if len(sys.argv) > 1 else "/outputs")
+source_root = Path(__file__).resolve().parents[1]
+container_config = Path("/app/scenario.json")
+config_path = container_config if container_config.exists() else source_root / "data/input.json"
+config = json.loads(config_path.read_text())
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--stage", choices=config["stages"])
+parser.add_argument("--output", default="/outputs" if container_config.exists() else str(source_root / "outputs"))
+args = parser.parse_args()
+
+stage = args.stage
+if stage is not None and stage not in config["stages"]:
+    raise SystemExit(f"unknown stage: {stage}")
+out = Path(args.output)
 out.mkdir(parents=True, exist_ok=True)
 digest = hashlib.sha256(json.dumps(config, sort_keys=True).encode()).hexdigest()
-record = {"showcase": config["slug"], "digest": digest, "stages": config["stages"], "status": "success"}
-for name in config["artifacts"]:
+selected_stages = [stage] if stage is not None else config["stages"]
+record = {"showcase": config["slug"], "digest": digest, "stages": selected_stages, "status": "success"}
+if stage is not None:
+    (out / f"stage-{stage}.json").write_text(json.dumps({**record, "stage": stage}, indent=2) + "\n")
+for name in config["artifacts"] if stage is None or stage == config["stages"][-1] else []:
     path = out / name
     if name.endswith(".json"):
         path.write_text(json.dumps({**record, "artifact": name}, indent=2) + "\n")
@@ -27,5 +41,7 @@
         path.write_text("# " + config["title"] + "\n\n" + json.dumps(record, indent=2) + "\n")
     else:
         path.write_text(json.dumps({**record, "artifact": name}) + "\n")
-(out / "manifest.json").write_text(json.dumps({**record, "artifacts": config["artifacts"]}, indent=2) + "\n")
-
+if stage is None or stage == config["stages"][-1]:
+    (out / "manifest.json").write_text(
+        json.dumps({**record, "artifacts": config["artifacts"]}, indent=2) + "\n"
+    )

agentic-workflows/multi-agent-review/workflow.yaml

@@ -1,35 +1,43 @@
 name: showcase-multi-agent-review
 spec:
   namespace: showcase
-  # Published by .github/workflows/build-showcase.yml.
-  image: ghcr.io/uffescience/akoflow-showcase-multi-agent-review:v1
+  # AkôFlow starts this OCI image; activities only declare commands inside it.
+  image: ghcr.io/uffescience/akoflow-examples/showcase-multi-agent-review:v1
   activities:
     - name: researcher
       runtime: local
-      # The local executor launches this OCI image through Docker in run.sh.
-      run: docker run --rm ghcr.io/uffescience/akoflow-showcase-multi-agent-review:v1 researcher
+      command:
+        entrypoint: python
+        arguments: ["/app/run_showcase.py", "--stage", "researcher", "--output", "."]
+        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
     - name: reviewer
       runtime: local
-      # The local executor launches this OCI image through Docker in run.sh.
-      run: docker run --rm ghcr.io/uffescience/akoflow-showcase-multi-agent-review:v1 reviewer
+      command:
+        entrypoint: python
+        arguments: ["/app/run_showcase.py", "--stage", "reviewer", "--output", "."]
+        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
       dependsOn:
         - researcher
     - name: critic
       runtime: local
-      # The local executor launches this OCI image through Docker in run.sh.
-      run: docker run --rm ghcr.io/uffescience/akoflow-showcase-multi-agent-review:v1 critic
+      command:
+        entrypoint: python
+        arguments: ["/app/run_showcase.py", "--stage", "critic", "--output", "."]
+        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
       dependsOn:
         - reviewer
     - name: synthesis
       runtime: local
-      # The local executor launches this OCI image through Docker in run.sh.
-      run: docker run --rm ghcr.io/uffescience/akoflow-showcase-multi-agent-review:v1 synthesis
+      command:
+        entrypoint: python
+        arguments: ["/app/run_showcase.py", "--stage", "synthesis", "--output", "."]
+        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
       dependsOn: