Add trainable Model primitive examples (IMDB NB + HF)

.beads/.gitignore

@@ -0,0 +1,46 @@
+# SQLite databases
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+sync-state.json
+last-touched
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Legacy database files
+db.sqlite
+bd.db
+
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+.jsonl.lock
+sync_base.jsonl
+export-state/
+
+# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
+# They would override fork protection in .git/info/exclude, allowing
+# contributors to accidentally commit upstream issue databases.
+# The JSONL files (issues.jsonl, interactions.jsonl) and config files
+# are tracked by git by default since no pattern above ignores them.

.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --status done
+
+# Sync with git remote
+bd sync
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

.beads/config.yaml

@@ -0,0 +1,67 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, no SQLite, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of SQLite database
+# no-db: false
+
+# Disable daemon for RPC communication (forces direct database access)
+# no-daemon: false
+
+# Disable auto-flush of database to JSONL after mutations
+# no-auto-flush: false
+
+# Disable auto-import from JSONL when it's newer than database
+# no-auto-import: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Path to database (overridden by BEADS_DB or --db)
+# db: ""
+
+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
+# auto-start-daemon: true
+
+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
+# flush-debounce: "5s"
+
+# Export events (audit trail) to .beads/events.jsonl on each flush/sync
+# When enabled, new events are appended incrementally using a high-water mark.
+# Use 'bd export --events' to trigger manually regardless of this setting.
+# events-export: false
+
+# Git branch for beads commits (bd sync will commit to this branch)
+# IMPORTANT: Set this for team projects so all clones use the same sync branch.
+# This setting persists across clones (unlike database config which is gitignored).
+# Can also use BEADS_SYNC_BRANCH env var for local override.
+# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
+# sync-branch: "beads-sync"
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo

.beads/issues.jsonl

@@ -0,0 +1,20 @@
+{"id":"Tactus-examples-1dv","title":"Useful Agent Patterns: Multi-agent Teams","description":"Example of orchestrating a team of agents with different roles.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:51:03.87167-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:51:03.87167-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-1n4","title":"Useful Agent Patterns: Human-in-the-Loop Approval","description":"Example of an approval workflow where the agent requests human permission for sensitive actions.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:51:14.475249-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:51:14.475249-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-1s8","title":"Useful Agent Patterns: System Integration (Beads/JIRA)","description":"Example of giving the agent access to a project management system.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:51:14.302281-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:51:14.302281-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-1x2","title":"Useful Agent Patterns: Sub-agents","description":"Example of a main agent delegating tasks to sub-agents.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:51:03.725235-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:51:03.725235-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-1ze","title":"Useful Agent Patterns: Structure \u0026 Policy","description":"Establish directory structure and editorial policies for the Useful Agent Patterns series. Includes creating EDITORIAL.md, updating AGENTS.md, and creating the series folder with its own AGENTS.md.","notes":"CRITICAL GUIDELINES:\\n1. Code MUST run and pass tests (Mocked for CI, Real for usage).\\n2. Prose must be accessible magazine-style.\\n3. Define acronyms (RLHF, RL, CI/CD) but allow common ones (LLM, ML).\\n4. Start with relatable real-world scenarios.","status":"open","priority":2,"issue_type":"epic","owner":"rap@endymion.com","created_at":"2026-02-10T08:50:35.028022-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:56:13.287825-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-2xe","title":"Add Nano Banana Integration","description":"Integrate Nano Banana (Gemini CLI wrapper) for image generation.","status":"open","priority":2,"issue_type":"feature","owner":"rap@endymion.com","created_at":"2026-02-10T14:18:42.817726-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T14:18:42.817726-05:00","dependencies":[{"issue_id":"Tactus-examples-2xe","depends_on_id":"Tactus-examples-69s","type":"blocks","created_at":"2026-02-10T14:18:42.818492-05:00","created_by":"Ryan Alyn Porter"}]}
+{"id":"Tactus-examples-37v","title":"Useful Agent Patterns: Blind RAG","description":"Example of retrieval augmented generation where the agent doesn't see the full corpus directly.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:51:03.574094-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:51:03.574094-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-69s","title":"Add Image Generation Support","description":"Add capability to generate images within Tactus procedures (e.g. OpenAI DALL-E, Google Imagen).","status":"open","priority":2,"issue_type":"feature","owner":"rap@endymion.com","created_at":"2026-02-10T14:18:37.273993-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T14:18:37.273993-05:00"}
+{"id":"Tactus-examples-80t","title":"Useful Agent Patterns: Filtering Long Text","description":"Example showing how to filter down long texts before passing them to an LLM.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:50:52.210364-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:50:52.210364-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-8in","title":"Useful Agent Patterns: Basic Tool Use","description":"Example showing how to give an agent a basic tool and have it use it.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:50:51.730214-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:50:51.730214-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-9ua","title":"Useful Agent Patterns: Classifier with LLM","description":"Example of how to build a classifier using an LLM.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:50:52.366449-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:50:52.366449-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-b4j","title":"Useful Agent Patterns: RaR RL Rubrics","description":"Example of Retrospective and Refinement (RaR) / RL for deriving rubrics from feedback.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:51:14.632244-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:51:14.632244-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-c6o","title":"Add model primitive example","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-13T08:46:53.732502-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-13T08:46:53.732502-05:00"}
+{"id":"Tactus-examples-d7m","title":"Useful Agent Patterns: Guardrails with Tests","description":"Example of giving an agent a programming environment and tests/specs as guardrails.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:50:52.038439-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:50:52.038439-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-jzk","title":"Useful Agent Patterns: Nano Banana Aware","description":"Implement patterns from nano-banana-aware (Style Guides, Chromakey, Image Types) as Tactus procedures.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T14:18:50.203467-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T14:18:50.203467-05:00","labels":["useful-agent-patterns"],"dependencies":[{"issue_id":"Tactus-examples-jzk","depends_on_id":"Tactus-examples-2xe","type":"blocks","created_at":"2026-02-10T14:18:50.204141-05:00","created_by":"Ryan Alyn Porter"}]}
+{"id":"Tactus-examples-t89","title":"Useful Agent Patterns: Feedback Loops","description":"Example of AI feedback loops (e.g., Gemini reviewing Nano Banana's work).","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:51:04.019191-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:51:04.019191-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-v7d","title":"Useful Agent Patterns: Progressive Disclosure","description":"Example of progressive disclosure UX patterns, similar to Claude Code skills.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:51:04.15148-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:51:04.15148-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-vkw","title":"Useful Agent Patterns: Advanced RAG","description":"Example demonstrating advanced RAG techniques like HyDE, Reranking, or Graph RAG.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:51:14.791821-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:51:14.791821-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-x6j","title":"Useful Agent Patterns: Context \u0026 Virtual Files","description":"Example showing text utilities built on a shared 'virtual file' paradigm for agent I/O.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:50:51.883703-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:50:51.883703-05:00","labels":["useful-agent-patterns"]}
+{"id":"Tactus-examples-yei","title":"Useful Agent Patterns: Real-time Video","description":"Example of generating video in realtime.","status":"open","priority":2,"issue_type":"task","owner":"rap@endymion.com","created_at":"2026-02-10T08:51:14.149812-05:00","created_by":"Ryan Alyn Porter","updated_at":"2026-02-10T08:51:14.149812-05:00","labels":["useful-agent-patterns"]}

.beads/metadata.json

@@ -0,0 +1,4 @@
+{
+  "database": "beads.db",
+  "jsonl_export": "issues.jsonl"
+}

.gitattributes

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
           python-version: '3.11'
 
       - name: Install Tactus
-        run: pip install tactus
+        run: pip install "git+https://github.com/AnthusAI/Tactus.git@main"
 
       - name: Run Tests
         run: |

02-classification/01-support-inbox-triage.tac

@@ -0,0 +1,59 @@
+-- Support Inbox Triage (LLM Classification)
+--
+-- Route an incoming support message into an explicit label set.
+-- Demonstrates stdlib retry logic when the model returns an invalid label.
+
+-- SNIPPET START
+Procedure {
+  input = {
+    message = field.string{required = true, description = "Incoming support message"}
+  },
+  output = {
+    label = field.string{required = true, description = "One of: billing, account, bug, other"},
+    retries = field.number{required = true, description = "How many retries were needed"}
+  },
+  function(input)
+    local triage = Classify {
+      name = "support_triage_llm",
+      method = "llm",
+      classes = {"billing", "account", "bug", "other"},
+      prompt = [[
+You are a support triage assistant.
+Return only one label from: billing, account, bug, other.
+If the request is unclear, choose "other".
+]],
+      model = "openai/gpt-4o-mini",
+      temperature = 0,
+      max_retries = 3
+    }
+
+    local result = triage(input.message)
+    return {label = result.value, retries = result.retry_count}
+  end
+}
+-- SNIPPET END
+
+-- Deterministic model responses for CI-safe specs.
+--
+-- The LLM classifier retries if the predicted value isn't in the allowed class set.
+-- With temporal mocks, we can simulate an invalid first attempt followed by a valid one.
+Mocks {
+  support_triage_llm = {
+    temporal = {
+      {value = "Maybe", confidence = 0.2},
+      {value = "billing", confidence = 0.91}
+    }
+  }
+}
+
+Specification([[
+Feature: Support inbox triage
+
+  Scenario: Invalid output triggers retry and still returns a valid label
+    Given the procedure has started
+    And the input message is "I was double charged this month. Please refund me."
+    When the procedure runs
+    Then the procedure should complete successfully
+    And the output label should be "billing"
+    And the output retries should be 1
+]])

02-classification/02-composite-fuzzy-then-llm.tac

@@ -0,0 +1,77 @@
+-- Composite Classification: Fuzzy Match First, LLM Fallback
+--
+-- Pattern:
+--   1) Try fast fuzzy matching for obvious cases (no API calls).
+--   2) If nothing matches, fall back to LLM classification for nuance.
+
+-- SNIPPET START
+Procedure {
+  input = {
+    message = field.string{required = true, description = "Incoming support message"}
+  },
+  output = {
+    label = field.string{required = true, description = "One of: billing, account, bug, other"},
+    path = field.string{required = true, description = "Which classifier decided: fuzzy or llm"}
+  },
+  function(input)
+    local fuzzy = Classify {
+      method = "fuzzy",
+      classes = {"double charged", "refund", "invoice", "login", "password reset", "crash", "error"},
+      threshold = 0.90,
+      algorithm = "token_set_ratio"
+    }
+
+    local llm = Classify {
+      name = "support_triage_llm_fallback",
+      method = "llm",
+      classes = {"billing", "account", "bug", "other"},
+      prompt = "Classify this support message into one label: billing, account, bug, other.",
+      model = "openai/gpt-4o-mini",
+      temperature = 0,
+      max_retries = 3
+    }
+
+    local fuzzy_result = fuzzy(input.message)
+    if fuzzy_result.value ~= "NO_MATCH" then
+      local v = fuzzy_result.value
+      if v == "double charged" or v == "refund" or v == "invoice" then
+        return {label = "billing", path = "fuzzy"}
+      end
+      if v == "login" or v == "password reset" then
+        return {label = "account", path = "fuzzy"}
+      end
+      if v == "crash" or v == "error" then
+        return {label = "bug", path = "fuzzy"}
+      end
+    end
+
+    local llm_result = llm(input.message)
+    return {label = llm_result.value, path = "llm"}
+  end
+}
+-- SNIPPET END
+
+-- Deterministic model response for CI-safe specs.
+Mocks {
+  support_triage_llm_fallback = {
+    returns = {value = "bug", confidence = 0.93}
+  }
+}
+
+Specification([[
+Feature: Composite classification
+
+  Scenario: Fuzzy path handles an obvious billing message
+    Given the procedure has started
+    And the input message is "double charged"
+    When the procedure runs
+    Then the output label should be "billing"
+    And the output path should be "fuzzy"
+
+  Scenario: LLM fallback handles the long tail
+    Given the procedure has started
+    And the input message is "After the last update, the app crashes whenever I click Save."
+    When the procedure runs
+    Then the output label should be "bug"
+    And the output path should be "llm"
+]])