Reorganize the truss-examples folder

.claude/CLAUDE.md

@@ -0,0 +1,127 @@
+# Truss Examples — Project Rules
+
+This repo contains production-ready inference examples for Truss. Follow these rules when creating, editing, or reviewing examples.
+
+## Repository structure
+
+Top-level directories:
+
+- `tutorials/` — Getting-started guides (BERT, LLMs, streaming, image generation, caching, batching)
+- `llm/` — Text generation models, organized by family (`llm/llama/`, `llm/qwen/`, `llm/mistral/`, etc.)
+- `embeddings/` — Embedding and reranker models (`bei/`, `tei/`, `clip/`)
+- `image/` — Image generation, editing, segmentation (`stable-diffusion/`, `flux/`, `segment-anything/`)
+- `audio/` — Speech-to-text, TTS, music generation (`whisper/`, `kokoro/`, `musicgen-large/`)
+- `optimized/` — Autogenerated TRT-LLM configs (`briton/`, `bisv2/`)
+- `infrastructure/` — Patterns and techniques (custom servers, gRPC, model caching, chains)
+- `_internal/` — Build tooling, templates, test scripts (not customer-facing)
+- `_archive/` — Deprecated examples
+
+## Placement rules
+
+| Model type | Directory | Example |
+|---|---|---|
+| Text generation / chat / LLM | `llm/<family>/` | `llm/llama/tinyllama-1.1B-chat-v1.0` |
+| Embedding or reranker | `embeddings/bei/`, `embeddings/tei/`, or `embeddings/clip/` | `embeddings/bei/baai-bge-large-en-v1.5-embedding` |
+| Image generation or processing | `image/` or `image/<family>/` | `image/stable-diffusion/stable-diffusion-xl-1.0` |
+| Audio (STT, TTS, music) | `audio/` | `audio/whisper/faster-whisper-v3` |
+| Infrastructure pattern | `infrastructure/` | `infrastructure/model-cache` |
+| Getting-started tutorial | `tutorials/` | `tutorials/getting-started-bert` |
+
+## Naming conventions
+
+- Use hyphens, not underscores: `falcon-7b` not `falcon_7b`
+- Do not include "truss" in folder names: `falcon-7b` not `falcon-7b-truss`
+- Include parameter count when multiple variants exist: `Falcon 7B` not `Falcon`
+- All directory names should be lowercase
+
+## config.yaml requirements
+
+Always include:
+- `model_name`
+- `description` (one-sentence summary)
+- `model_metadata.example_model_input`
+
+Recommended:
+- `model_metadata.repo_id` (Hugging Face model ID)
+- `model_metadata.avatar_url` (128x128 PNG)
+- `model_metadata.cover_image_url` (452x423 PNG)
+- `model_metadata.tags`
+
+### Requirements pinning
+
+Pin versions for ALL Python requirements:
+
+```yaml
+requirements:
+- accelerate==0.20.3
+- torch==2.0.1
+- transformers==4.30.2
+```
+
+Never leave a requirement unpinned. For git+ dependencies, pin to a specific commit hash, not `@master` or `@main`.
+
+### Secrets
+
+If the model requires a HuggingFace token, always name the secret `hf_access_token`:
+
+```yaml
+secrets:
+  hf_access_token: "ENTER HF ACCESS TOKEN HERE"
+```
+
+### Hardware
+
+Configure with the least expensive hardware that runs at reasonable speed and quality. Note tradeoffs in the README when applicable.
+
+## README template
+
+Every example must include a `README.md` following this structure:
+
+```markdown
+# <Model Name>
+
+<One or two sentence description.>
+
+## Deploying <Model Name>
+
+<Deploy instructions with `truss push <path>`.>
+
+## Invoking <Model Name>
+
+<Curl or Python snippet with example input and expected output.>
+```
+
+- Deploy path must match the actual directory path relative to repo root
+- OpenAI-compatible models must show `/v1/chat/completions` endpoint
+- Never use `--trusted` or `--publish` flags
+- If the config requires `hf_access_token`, the README must mention setting up the secret
+
+Reference example: `image/stable-diffusion/stable-diffusion-xl-1.0`
+
+## Model I/O conventions
+
+- Models that support streaming should accept a `stream` kwarg defaulting to false
+- Models that take text input should call the parameter `prompt`
+
+## CI
+
+CI auto-discovers examples by finding directories with `config.yaml`, skipping `_archive/` and `_internal/`. To exclude a specific example from CI, add its path to `ci_excludes.yaml` at the repo root. The test suite (`_internal/bin/test_all.py`) validates all configs, READMEs, naming, links, and pinning.
+
+Run tests locally:
+```bash
+python _internal/bin/test_all.py           # default
+python _internal/bin/test_all.py --verbose  # show every check
+python _internal/bin/test_all.py --category llm  # filter by category
+```
+
+## Automatic documentation
+
+To include an example in auto-generated docs on https://truss.baseten.co/, add a `doc.yaml`:
+
+```yaml
+title: "Text-to-image"
+description: "Building a text-to-image model with SDXL"
+files:
+  - model/model.py
+  - config.yaml
+```

.github/workflows/pr.yml

@@ -12,6 +12,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup-python/
-      - run: poetry install
-      - run: poetry run pre-commit run --all-files
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11.4'
+      - run: pip install truss pre-commit
+      - run: pre-commit run --all-files

.github/workflows/test-examples.yml

@@ -6,54 +6,81 @@ on:
     - cron: '0 6 * * *'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - name: Set up Python environment
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.11.4'
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install git+https://github.com/basetenlabs/truss.git pyyaml --upgrade
+      - name: Run local validation (test_all.py)
+        run: |
+          python _internal/bin/test_all.py
+
   generate_tests:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     outputs:
       tests: ${{ steps.generate-matrix.outputs.tests }}
 
     steps:
-      - uses: actions/checkout@v4
-      - name: yq - portable yaml processor
-        uses: mikefarah/yq@v4.35.2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.11.4'
+      - run: pip install pyyaml
       - name: Generate all tests that need to be run
         id: generate-matrix
         run: |
-          TESTS=$(cat ci.yaml | yq e ".tests" | yq eval -o=json | jq -c .)
+          TESTS=$(python _internal/bin/discover_examples.py)
           echo "tests=$TESTS" >> $GITHUB_OUTPUT
 
   ci:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     needs:
+      - validate
       - generate_tests
     strategy:
       fail-fast: false
       max-parallel: 3
       matrix:
         test: ${{ fromJSON(needs.generate_tests.outputs.tests) }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - name: Set up Python environment
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: '3.11.4'
-      - name: Install dependencies (if any)
+          cache: 'pip'
+      - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install git+https://github.com/basetenlabs/truss.git requests tenacity --upgrade
-      - name: Test => (${{ matrix.test }}
+      - name: Test ${{ matrix.test }}
         run: |
-          python ./bin/test_example.py ${{secrets.BASETEN_API_KEY}} ${{matrix.test}}
+          python _internal/bin/test_example.py ${{ secrets.BASETEN_API_KEY }} ${{ matrix.test }}
+
   report_to_slack:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     if: always() && github.ref == 'refs/heads/main'
     needs:
       - ci
     steps:
-      - name: get-branch
-        run: echo ${{ github.ref }}
-      - name: show-slack-status
-        uses: 8398a7/action-slack@v3
+      - name: Report CI result
+        uses: 8398a7/action-slack@77eaa4f1c608a7d68b38af4e3f739dcd8cba273e # v3.19.0
         with:
           status: custom
           fields: author, job, commit, repo

.github/workflows/truss_deploy.yml

@@ -31,4 +31,4 @@ jobs:
             - name: Run tests
               env:
                 BASETEN_API_KEY: ${{ secrets.BASETEN_API_KEY }}
-              run: python bin/test_truss_deploy.py
+              run: python _internal/bin/test_truss_deploy.py

.github/workflows/warm-chains.yml

@@ -12,7 +12,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python environment
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: '3.11.4'
       - name: Install dependencies (if any)
@@ -29,5 +29,5 @@ jobs:
           EOF
       - name: Warm up chains
         run: |
-          truss chains deploy chains-examples/docs/poems/poems.py
-          truss chains deploy chains-examples/docs/audio-transcription/whisper_chainlet.py
+          truss chains deploy infrastructure/chains-examples/docs/poems/poems.py
+          truss chains deploy infrastructure/chains-examples/docs/audio-transcription/whisper_chainlet.py