aia 1.1.1 → 2.0.0.0.pre.alpha

data/examples/25_spawn.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# examples/25_spawn.sh
+#
+# Demonstrates /spawn mode: SpawnHandler.
+#
+# Dynamically creates a specialist robot on demand. You can name
+# the specialist type (/spawn ruby-expert) or let AIA auto-detect
+# from the content of your next prompt (/spawn with no args).
+# Spawned specialists are cached and reused within the session.
+#
+# How it works in chat:
+#   1. Type /spawn [optional type]  →  AIA sets spawn mode
+#   2. Type your question  →  specialist robot answers
+#
+# Prerequisites: Run 00_setup_aia.sh first
+# Usage: cd examples && bash 25_spawn.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+if ! command -v expect &>/dev/null; then
+    echo "ERROR: expect is not installed."
+    echo "       Install with: brew install expect"
+    exit 1
+fi
+
+echo "=== Demo 25: Spawn Mode (SpawnHandler) ==="
+echo
+echo "The /spawn directive creates a specialist robot to answer"
+echo "a domain-specific question. Specialists are cached for the"
+echo "session so repeated questions in the same domain reuse the"
+echo "same specialist robot."
+echo
+echo "Directive mechanics: /spawn [type] sets the mode for the NEXT"
+echo "prompt. Named type: /spawn security-expert. Auto-detect: /spawn"
+echo
+
+# --- Part 1: Explicit specialist type ---
+
+echo "--- Part 1: Explicit specialist (/spawn security-expert) ---"
+echo
+echo "We'll explicitly request a security expert to review a"
+echo "common code vulnerability pattern."
+echo
+echo "Running: aia -c ${CONFIG} --chat"
+echo
+
+expect <<'EXPECT_SCRIPT'
+set timeout 300
+log_user 1
+
+spawn aia -c aia_config.yml --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "/spawn security-expert\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for directive confirmation ***"; exit 1 }
+}
+
+send "What are the top 3 SQL injection prevention techniques and how does parameterized query binding work?\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for specialist response ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Part 2: Auto-detect specialist ---
+
+echo "--- Part 2: Auto-detect specialist (/spawn with no args) ---"
+echo
+echo "Without a type, AIA asks the primary robot to determine what"
+echo "kind of specialist would best answer the next question."
+echo "The primary robot chooses the role and writes the specialist's"
+echo "system prompt automatically."
+echo
+echo "Running: aia -c ${CONFIG} --chat"
+echo
+
+expect <<'EXPECT_SCRIPT'
+set timeout 300
+log_user 1
+
+spawn aia -c aia_config.yml --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "/spawn\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for directive confirmation ***"; exit 1 }
+}
+
+send "What database indexing strategies should I consider for a write-heavy time-series workload in PostgreSQL?\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for specialist response ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Part 3: Your turn ---
+
+echo "--- Part 3: Your turn ---"
+echo
+echo "Try /spawn ruby-expert, /spawn data-scientist, /spawn devops,"
+echo "or just /spawn and let AIA decide. Ask domain-specific questions"
+echo "that benefit from a focused specialist perspective."
+echo
+
+if [[ "${BATCH_MODE:-}" == "true" ]]; then
+  echo "(Skipping interactive session in batch mode)"
+else
+  aia -c "${CONFIG}" --chat
+fi

data/examples/26_debate.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# examples/26_debate_fixed.sh
+#
+# Fixed version of the debate demonstration script
+#
+# Demonstrates /debate mode: DebateHandler.
+#
+# Two robots debate a topic across multiple rounds. Each round,
+# every robot responds to the previous arguments. Stops when any
+# robot says CONVERGED or after 5 rounds. Uses SimilarityScorer
+# to also detect convergence when responses become too similar.
+#
+# Requires a 2-model network (-m MODEL_A,MODEL_B).
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+if ! command -v expect &>/dev/null; then
+    echo "ERROR: expect is not installed."
+    echo "       Install with: brew install expect"
+    exit 1
+fi
+
+MODEL_A="gpt-4.1"
+MODEL_B="gpt-4.1-mini"
+
+echo "=== Demo 26: Debate Mode (DebateHandler) ==="
+echo
+echo "The /debate directive pits two robots against each other in"
+echo "a structured multi-round debate. Each robot sees what the"
+echo "other said in the previous round and responds. The debate"
+echo "ends when a robot says CONVERGED or after 5 rounds."
+echo
+echo "Using models: ${MODEL_A} vs ${MODEL_B}"
+echo "Robot names:  Tobor (gpt-4.1) and Vanguard (gpt-4.1-mini)"
+echo
+
+# --- Part 1: A technical debate ---
+
+echo "--- Part 1: Technical debate ---"
+echo
+echo "Both models will debate the best approach to API design."
+echo "Watch how their positions evolve across rounds."
+echo
+echo "Running: aia -c ${CONFIG} -m ${MODEL_A},${MODEL_B} --chat"
+echo
+
+# Create the expect script with proper variable substitution
+expect -c "
+set timeout 600
+log_user 1
+
+spawn aia -c ${CONFIG} -m ${MODEL_A},${MODEL_B} --chat
+
+expect {
+  \"#=> \" {}
+  timeout { puts \"\n*** Timed out waiting for chat prompt ***\"; exit 1 }
+}
+
+send \"/debate\r\"
+
+expect {
+  \"#=> \" {}
+  timeout { puts \"\n*** Timed out waiting for directive confirmation ***\"; exit 1 }
+}
+
+send \"REST vs GraphQL: which is the better default choice for a new web API in 2025, and why?\r\"
+
+expect {
+  \"#=> \" {}
+  timeout { puts \"\n*** Timed out waiting for debate results ***\"; exit 1 }
+}
+
+send \"exit\r\"
+expect eof
+"
+
+drain_terminal
+echo
+echo
+
+# --- Part 2: Your turn ---
+
+echo "--- Part 2: Your turn ---"
+echo
+echo "Try /debate on any topic where two perspectives are valuable:"
+echo "architecture decisions, tradeoffs, design choices, or even"
+echo "open-ended questions where you want multiple viewpoints stress-tested."
+echo
+echo "Running: aia -c ${CONFIG} -m ${MODEL_A},${MODEL_B} --chat"
+echo
+
+if [[ "${BATCH_MODE:-}" == "true" ]]; then
+  echo "(Skipping interactive session in batch mode)"
+else
+  aia -c "${CONFIG}" -m "${MODEL_A},${MODEL_B}" --chat
+fi

data/examples/27_mention_routing.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# examples/27_mention_routing.sh
+#
+# Demonstrates @mention routing in a multi-model network.
+#
+# In a 2-model chat session, prefix any message with @RobotName
+# to direct it to a specific robot. Only that robot responds.
+# Robot names are assigned by AIA based on the model:
+#   gpt-4.1      → Tobor    (first robot always gets the name "Tobor")
+#   gpt-4.1-mini → Vanguard
+#
+# If the @name is not recognized, AIA lists available robot names.
+#
+# Requires a 2-model network (-m MODEL_A,MODEL_B).
+#
+# Prerequisites: Run 00_setup_aia.sh first (OPENAI_API_KEY must be set).
+# Usage: cd examples && bash 27_mention_routing.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+if ! command -v expect &>/dev/null; then
+    echo "ERROR: expect is not installed."
+    echo "       Install with: brew install expect"
+    exit 1
+fi
+
+MODEL_A="gpt-4.1"
+MODEL_B="gpt-4.1-mini"
+
+echo "=== Demo 27: @mention Routing ==="
+echo
+echo "In a multi-model network, prefix your message with @RobotName"
+echo "to direct it to a specific robot. Only that robot responds."
+echo
+echo "Using models: ${MODEL_A} vs ${MODEL_B}"
+echo "Robot names:  Tobor (gpt-4.1) and Vanguard (gpt-4.1-mini)"
+echo
+
+# --- Part 1: Route to Tobor (gpt-4.1) ---
+
+echo "--- Part 1: Direct a question to @Tobor ---"
+echo
+echo "Running: aia -c ${CONFIG} -m ${MODEL_A},${MODEL_B} --chat"
+echo
+
+expect <<'EXPECT_SCRIPT'
+set timeout 180
+log_user 1
+
+spawn aia -c aia_config.yml -m gpt-4.1,gpt-4.1-mini --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "@Tobor What is your favorite metaphor for explaining recursion?\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for response ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Part 2: Route to Vanguard (gpt-4.1-mini) ---
+
+echo "--- Part 2: Direct a question to @Vanguard ---"
+echo
+echo "Running: aia -c ${CONFIG} -m ${MODEL_A},${MODEL_B} --chat"
+echo
+
+expect <<'EXPECT_SCRIPT'
+set timeout 180
+log_user 1
+
+spawn aia -c aia_config.yml -m gpt-4.1,gpt-4.1-mini --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "@Vanguard Describe the CAP theorem in one sentence.\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for response ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Part 3: Unknown @mention lists available robots ---
+
+echo "--- Part 3: Unknown @mention shows available robots ---"
+echo
+echo "If you @mention a name that doesn't match any robot,"
+echo "AIA lists the available robot names so you can correct it."
+echo
+echo "Running: aia -c ${CONFIG} -m ${MODEL_A},${MODEL_B} --chat"
+echo
+
+expect <<'EXPECT_SCRIPT'
+set timeout 60
+log_user 1
+
+spawn aia -c aia_config.yml -m gpt-4.1,gpt-4.1-mini --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "@nonexistent What is 2 + 2?\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for response ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Part 4: Mix @mention and normal turns ---
+
+echo "--- Part 4: Mix directed and undirected turns ---"
+echo
+echo "In a session you can freely mix @mention turns (one robot)"
+echo "with normal turns (all robots). This shows how to hold a"
+echo "selective conversation across a network."
+echo
+echo "Running: aia -c ${CONFIG} -m ${MODEL_A},${MODEL_B} --chat"
+echo
+
+if [[ "${BATCH_MODE:-}" == "true" ]]; then
+  echo "(Skipping interactive session in batch mode)"
+else
+  aia -c "${CONFIG}" -m "${MODEL_A},${MODEL_B}" --chat
+fi

data/examples/28_model_switching.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# examples/28_model_switching.sh
+#
+# Demonstrates /model directive: switching models mid-conversation.
+#
+# The /model directive rebuilds the active robot with a new model
+# while preserving the full conversation history. Context is
+# transferred so the new model can see everything discussed so far.
+#
+# Note: Natural language model switching ("use gpt-4.1-mini instead")
+# is detected by ModelSwitchHandler but currently stubbed. Use
+# /model directly for reliable in-session model changes.
+#
+# Prerequisites:
+#   - Run 00_setup_aia.sh first (OPENAI_API_KEY must be set)
+# Usage: cd examples && bash 28_model_switching.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+if ! command -v expect &>/dev/null; then
+    echo "ERROR: expect is not installed."
+    echo "       Install with: brew install expect"
+    exit 1
+fi
+
+MODEL_A="gpt-4.1"
+MODEL_B="gpt-4.1-mini"
+
+echo "=== Demo 28: Model Switching (/model directive) ==="
+echo
+echo "The /model directive switches the active model mid-conversation."
+echo "Conversation history is transferred so the new model has"
+echo "full context of everything discussed before the switch."
+echo
+echo "Starting model: ${MODEL_A}"
+echo "Switch target:  ${MODEL_B}"
+echo
+
+# --- Part 1: Ask a question, switch models, ask a follow-up ---
+
+echo "--- Part 1: Ask a question, switch models, ask a follow-up ---"
+echo
+echo "We'll ask a question with ${MODEL_A}, switch to ${MODEL_B},"
+echo "then ask a follow-up. The second model should reference the"
+echo "first exchange because history is preserved across the switch."
+echo
+echo "Running: aia -c ${CONFIG} --chat"
+echo
+
+expect <<'EXPECT_SCRIPT'
+set timeout 180
+log_user 1
+
+spawn aia -c aia_config.yml --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "Name three key differences between a process and a thread.\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for first response ***"; exit 1 }
+}
+
+send "/model gpt-4.1-mini\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for model switch ***"; exit 1 }
+}
+
+send "Based on what you just said, which is more appropriate for a CPU-bound image processing pipeline?\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for follow-up response ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Part 2: Your turn ---
+
+echo "--- Part 2: Your turn ---"
+echo
+echo "Use /model <name> any time during a chat to switch models."
+echo "The new model picks up the full conversation history."
+echo "You can switch back and forth as many times as you like."
+echo
+echo "Running: aia -c ${CONFIG} --chat"
+echo
+
+if [[ "${BATCH_MODE:-}" == "true" ]]; then
+  echo "(Skipping interactive session in batch mode)"
+else
+  aia -c "${CONFIG}" --chat
+fi

data/examples/29_agent_harness.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# examples/29_agent_harness.sh
+#
+# Demonstrates AIA as a full agent harness using 3-tier layered orchestration.
+#
+# A complete application requirements document is fed to the /orchestrate
+# directive. AIA runs a three-tier execution:
+#
+#   Tier 1 — Tobor (orchestrator)
+#     Reads the full requirements and decomposes them into independent
+#     architectural layers (e.g. Infrastructure, Data Models, Auth, Routes, Views).
+#
+#   Tier 2 — Lead agents (one per layer)
+#     Each lead agent receives its layer's requirements and further decomposes
+#     them into specific implementation tasks, assigning a specialist type to
+#     each task (e.g. sequel-migration-writer, sinatra-route-builder).
+#
+#   Tier 3 — Specialist robots (one per task)
+#     Each specialist receives a focused, concrete task and produces an actual
+#     implementation artifact: a code file, migration, route handler, or spec.
+#
+#   Synthesis
+#     Each lead agent synthesizes its layer's artifacts into a summary.
+#     Tobor then synthesizes all layer summaries into a final integration report.
+#
+# The application being built: TaskFlow — a multi-user project and task
+# management web app using Ruby, Sinatra, Sequel (SQLite), and ERB templates.
+# Full requirements: examples/requirements/sinatra_taskflow_app.md
+#
+# Prerequisites: Run 00_setup_aia.sh first (OPENAI_API_KEY must be set)
+# Requires: expect (brew install expect)
+# Usage: cd examples && bash 29_agent_harness.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+if ! command -v expect &>/dev/null; then
+    echo "ERROR: expect is not installed."
+    echo "       Install with: brew install expect"
+    exit 1
+fi
+
+MODEL_A="gpt-4.1"
+MODEL_B="gpt-4.1-mini"
+ORCH_CONFIG="aia_config_orchestrator.yml"
+REQUIREMENTS="requirements/sinatra_taskflow_app.md"
+
+echo "=== Demo 29: AIA Agent Harness — 3-Tier Layered Orchestration ==="
+echo
+echo "Application being built:"
+echo "  TaskFlow — a multi-user project and task management web app"
+echo "  Stack: Ruby + Sinatra + Sequel (SQLite) + ERB + Bootstrap 5"
+echo
+echo "Execution model:"
+echo "  Tier 1  Tobor (orchestrator) decomposes requirements into layers"
+echo "  Tier 2  One lead agent per layer decomposes into specialist tasks"
+echo "  Tier 3  One specialist per task produces the implementation artifact"
+echo
+
+if [[ ! -f "${REQUIREMENTS}" ]]; then
+    echo "ERROR: Requirements file not found: ${REQUIREMENTS}"
+    echo "       Expected at: examples/requirements/sinatra_taskflow_app.md"
+    exit 1
+fi
+
+# --- Orchestration run ---
+
+echo "--- Orchestrated build: /orchestrate ---"
+echo
+echo "The directive /orchestrate enables 3-tier mode for the next prompt."
+echo "The next message is the full application requirements document."
+echo "AIA will:"
+echo "  1. Decompose requirements into architectural layers"
+echo "  2. Spawn a lead agent for each layer"
+echo "  3. Have each lead spawn specialists for its tasks"
+echo "  4. Collect artifacts and synthesize across all layers"
+echo
+echo "Requirements document: ${REQUIREMENTS}"
+echo "Running: aia -c ${ORCH_CONFIG} -m ${MODEL_A},${MODEL_B} --chat"
+echo
+echo "Note: This demonstration runs 3+ tiers of agents in sequence."
+echo "      Each layer spawns 2-4 specialists. Allow 10-20 minutes"
+echo "      depending on OpenAI API response times."
+echo
+
+REQUIREMENTS_CONTENT=$(cat "${REQUIREMENTS}")
+
+expect <<EXPECT_SCRIPT
+set timeout 1800
+log_user 1
+
+spawn aia -c aia_config_orchestrator.yml -m gpt-4.1,gpt-4.1-mini --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "/orchestrate\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for directive confirmation ***"; exit 1 }
+}
+
+send {${REQUIREMENTS_CONTENT}}
+send "\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for orchestration to complete ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Show what was built ---
+
+echo "--- Generated application files ---"
+echo
+
+BUILD_DIR=$(ls -dt orchestrated_build_* 2>/dev/null | head -1)
+
+if [[ -z "${BUILD_DIR}" ]]; then
+    echo "No build directory found. The orchestration may not have completed."
+else
+    echo "Build directory: ${BUILD_DIR}"
+    echo
+    echo "Files produced by the agent team:"
+    find "${BUILD_DIR}" -type f | sort | grep -v INTEGRATION_REPORT.md | while read -r f; do
+        rel="${f#${BUILD_DIR}/}"
+        lines=$(wc -l < "${f}" 2>/dev/null | tr -d ' ' || echo "?")
+        printf "  %-50s  (%s lines)\n" "${rel}" "${lines}"
+    done
+    echo
+    REPORT="${BUILD_DIR}/INTEGRATION_REPORT.md"
+    if [[ -f "${REPORT}" ]]; then
+        echo "--- INTEGRATION_REPORT.md ---"
+        echo
+        cat "${REPORT}"
+        echo
+    fi
+
+    # Show a sample generated file (first non-report Ruby file found)
+    SAMPLE=$(find "${BUILD_DIR}" -type f -name "*.rb" | sort | head -1)
+    if [[ -n "${SAMPLE}" ]]; then
+        echo "--- Sample artifact: ${SAMPLE#${BUILD_DIR}/} ---"
+        echo
+        cat "${SAMPLE}"
+        echo
+    fi
+fi
+
+# --- Interactive session ---
+
+echo "--- Interactive orchestration session ---"
+echo
+echo "The same session is now open for you to:"
+echo "  /orchestrate   run 3-tier orchestration on any requirements prompt"
+echo "  /spawn <type>  create a specialist lead agent for a focused task"
+echo "  /decompose     parallel workstreams for multi-part questions"
+echo "  @Tobor         address the orchestrator directly"
+echo "  @Quark         address the specialist network robot directly"
+echo
+echo "Running: aia -c ${ORCH_CONFIG} -m ${MODEL_A},${MODEL_B} --chat"
+echo
+
+if [[ "${BATCH_MODE:-}" == "true" ]]; then
+  echo "(Skipping interactive session in batch mode)"
+else
+  aia -c "${ORCH_CONFIG}" -m "${MODEL_A},${MODEL_B}" --chat
+fi