Skip to content

github-actions.md

Latest commit

 

History

History
247 lines (192 loc) · 10.3 KB

github-actions.md

File metadata and controls

247 lines (192 loc) · 10.3 KB

GitHub Actions — Guardrails and Fix Patterns

🧭 Quick Return to Map

You are in a sub-page of Automation Platforms.
To reorient, go back here:

Think of this page as a desk within a ward.
If you need the full triage and all prescriptions, return to the Emergency Room lobby.

Use this when your automation runs in GitHub Actions and you see race conditions, duplicate runs, stale artifacts, secret mismatch, or retrieval steps that look fine but answers drift.

Acceptance targets

  • ΔS(question, retrieved) ≤ 0.45
  • coverage ≥ 0.70 to the intended section or record
  • λ stays convergent across 3 paraphrases

Typical breakpoints → exact fixes

  • Workflow jobs start before embeddings or the index are ready
    Fix No.14: Bootstrap Ordering →
    Bootstrap Ordering

  • First run after deploy uses wrong secret or old model version
    Fix No.16: Pre-Deploy Collapse →
    Pre-Deploy Collapse

  • Circular waits between indexing and retrieval jobs or external runners
    Fix No.15: Deployment Deadlock →
    Deployment Deadlock

  • High vector similarity but wrong meaning in answers
    Fix No.5: Embedding ≠ Semantic →
    Embedding ≠ Semantic

  • Logs cannot explain “why this snippet” was chosen
    Fix No.8: Retrieval Traceability →
    Retrieval Traceability
    Standardize with Data Contracts →
    Data Contracts

  • Hybrid retrieval underperforms single retriever when mixing sources or rerankers
    Pattern: Query Parsing Split →
    Query Parsing Split
    Review Rerankers →
    Rerankers

  • Facts exist in the store but are never retrieved
    Pattern: Vectorstore Fragmentation →
    Vectorstore Fragmentation

Minimal GitHub Actions workflow with WFGY gates

name: rag-pipeline

on:
  workflow_dispatch:
  push:
    paths:
      - "rag/**"
      - ".github/workflows/rag-pipeline.yml"

env:
  VECTOR_READY_FLAG: vector_ready.txt
  INDEX_HASH_FILE: index_hash.txt
  SECRET_REV: ${{ secrets.SECRET_REV }}

jobs:
  build-index:
    runs-on: ubuntu-latest
    outputs:
      index_hash: ${{ steps.hash.outputs.index_hash }}
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install deps
        run: |
          pip install -r rag/requirements.txt

      - name: Build index
        run: |
          python rag/build_index.py --out artifacts/index.faiss --metric cosine
          echo "ok" > $VECTOR_READY_FLAG

      - name: Compute INDEX_HASH
        id: hash
        run: |
          python - << 'PY'
import hashlib, sys
with open("artifacts/index.faiss","rb") as f:
    h = hashlib.sha256(f.read()).hexdigest()
open("${{ env.INDEX_HASH_FILE }}","w").write(h)
print(f"index_hash={h}")
PY
          echo "index_hash=$(cat $INDEX_HASH_FILE)" >> $GITHUB_OUTPUT

      - name: Upload index artifacts
        uses: actions/upload-artifact@v4
        with:
          name: rag-index
          path: |
            artifacts/index.faiss
            ${{ env.VECTOR_READY_FLAG }}
            ${{ env.INDEX_HASH_FILE }}

  run-llm:
    runs-on: ubuntu-latest
    needs: build-index
    steps:
      - uses: actions/checkout@v4

      - name: Download index artifacts
        uses: actions/download-artifact@v4
        with:
          name: rag-index
          path: artifacts

      - name: Warm-up fence
        run: |
          test -f artifacts/${{ env.VECTOR_READY_FLAG }} || { echo "Vector not ready"; exit 1; }
          test -f artifacts/${{ env.INDEX_HASH_FILE }} || { echo "Missing INDEX_HASH"; exit 1; }
          echo "wf_rev=${{ github.run_id }}"
          echo "secret_rev=${{ env.SECRET_REV }}"
          echo "index_hash=$(cat artifacts/${{ env.INDEX_HASH_FILE }})"

      - name: Run guarded RAG
        env:
          WF_REV: ${{ github.run_id }}
          SECRET_REV: ${{ env.SECRET_REV }}
          INDEX_HASH: ${{ needs.build-index.outputs.index_hash }}
        run: |
          python rag/run_guarded.py \
            --wf-rev "$WF_REV" \
            --secret-rev "$SECRET_REV" \
            --index-hash "$INDEX_HASH" \
            --trace out/trace.json \
            --emit out/answer.json

      - name: ΔS and λ checks
        run: |
          python rag/check_metrics.py --trace out/trace.json --fail-threshold 0.60

      - name: Upload outputs
        uses: actions/upload-artifact@v4
        with:
          name: rag-output
          path: out/

What this enforces

  • Build and retrieval use the same metric and a single INDEX_HASH.
  • LLM job hard-fails if the vector layer is not ready.
  • A separate metrics step rejects runs with ΔS ≥ 0.60 or divergent λ.
  • Artifacts give you traceability for “why this snippet”.

Specs and recipes RAG Architecture & Recovery · Retrieval Playbook · Retrieval Traceability · Data Contracts

Common GitHub Actions gotchas

  • Workflow re-runs mutate state Compute a server-side dedupe_key = sha256(run_id + wf_rev + index_hash). Reject duplicates.

  • Matrix jobs double write to the same index or store Serialize writes or gate on a single producer job. Use needs: fan-in.

  • Secrets rotate during a long build Stamp secret_rev into artifacts and validate in the consumer job. Abort on mismatch. See Pre-Deploy Collapse

  • Artifact retention truncates traces that you need for audits Set longer retention or sync traces to durable storage with rev-stamped paths.

  • Cosine vs inner product mismatch between write and read codepaths Rebuild with explicit metric and normalization. See Embedding ≠ Semantic

When to escalate

  • ΔS stays ≥ 0.60 after chunk and retrieval fixes Work through the playbook to rebuild and verify. Retrieval Playbook

  • Same inputs flip answers between runs or branches Check version skew and session state. Pre-Deploy Collapse

🔗 Quick-Start Downloads (60 sec)

Tool Link 3-Step Setup
WFGY 1.0 PDF Engine Paper 1️⃣ Download · 2️⃣ Upload to your LLM · 3️⃣ Ask “Answer using WFGY + <your question>”
TXT OS (plain-text OS) TXTOS.txt 1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly

Explore More

Layer Page What it’s for
⭐ Proof WFGY Recognition Map External citations, integrations, and ecosystem proof
⚙️ Engine WFGY 1.0 Original PDF tension engine and early logic sketch (legacy reference)
⚙️ Engine WFGY 2.0 Production tension kernel for RAG and agent systems
⚙️ Engine WFGY 3.0 TXT based Singularity tension engine (131 S class set)
🗺️ Map Problem Map 1.0 Flagship 16 problem RAG failure taxonomy and fix map
🗺️ Map Problem Map 2.0 Global Debug Card for RAG and agent pipeline diagnosis
🗺️ Map Problem Map 3.0 Global AI troubleshooting atlas and failure pattern map
🧰 App TXT OS .txt semantic OS with fast bootstrap
🧰 App Blah Blah Blah Abstract and paradox Q&A built on TXT OS
🧰 App Blur Blur Blur Text to image generation with semantic control
🏡 Onboarding Starter Village Guided entry point for new users

If this repository helped, starring it improves discovery so more builders can find the docs and tools.
GitHub Repo stars