aia 1.1.1 → 2.0.0.0.pre.alpha

data/examples/run_all.sh

@@ -9,15 +9,18 @@
 # differences (missing sections, crashes, changed command output).
 #
 # What it skips:
-#   - 00_setup_aia.sh  — run manually first (pulls models, writes config)
-#   - 15_parameters.sh — Part 2 prompts interactively for a required param
-#   - 20_mcp_servers.sh — requires Node.js/npx + MCP filesystem server
-#   - 22_chat_mode.sh  — interactive chat (Parts 1-4 use expect; Part 5
-#                         opens a live session)
+#   - 00_setup_aia.sh     — run manually first (pulls models, writes config)
+#   - 15_parameters.sh    — Part 2 prompts interactively for a required param
+#   - 20_mcp_servers.sh   — requires Node.js/npx + MCP filesystem server
+#   - 22_chat_mode.sh     — interactive chat (Parts 1-4 use expect; Part 5
+#                           opens a live session)
+#   - 29_agent_harness.sh — 3-tier orchestration (10-20 min runtime)
+#
+# Scripts 23-28 run with BATCH_MODE=true, which skips their interactive
+# "your turn" sections but still executes the automated expect-based parts.
 #
 # Prerequisites:
-#   - Run 00_setup_aia.sh first
-#   - Ollama running with qwen3 model available
+#   - Run 00_setup_aia.sh first (OPENAI_API_KEY must be set)
 #
 # Usage:
 #   cd examples
@@ -61,14 +64,17 @@ Comparing runs:
   diff output/run_PREV.log output/run_LATEST.log
 
 Skipped scripts (require manual or interactive setup):
-  00_setup_aia.sh   — run manually first (pulls models, writes config)
-  15_parameters.sh  — Part 2 prompts interactively for a required param
-  20_mcp_servers.sh — requires Node.js/npx + MCP filesystem server
-  22_chat_mode.sh   — interactive chat session
+  00_setup_aia.sh    — run manually first (pulls models, writes config)
+  15_parameters.sh   — Part 2 prompts interactively for a required param
+  20_mcp_servers.sh  — requires Node.js/npx + MCP filesystem server
+  22_chat_mode.sh    — interactive chat session
+  29_agent_harness.sh — 3-tier orchestration (10-20 min runtime)
+
+Scripts 23-28 run with BATCH_MODE=true, which skips their interactive
+"your turn" sections but still runs the automated expect-based parts.
 
 Prerequisites:
-  1. Run 00_setup_aia.sh first
-  2. Ollama running with the qwen3 model available
+  1. Run 00_setup_aia.sh first (OPENAI_API_KEY must be set)
 
 Exit codes:
   0  All scripts completed (some may have non-fatal warnings)
@@ -129,12 +135,20 @@ SCRIPTS=(
   # 20_mcp_servers.sh — skipped: requires npx + MCP server
   21_executable_prompts.sh
   # 22_chat_mode.sh — skipped: interactive chat session
+  23_verify.sh
+  24_decompose.sh
+  25_spawn.sh
+  26_debate.sh
+  27_mention_routing.sh
+  28_model_switching.sh
+  # 29_agent_harness.sh — skipped: 3-tier orchestration, 10-20 min runtime
 )
 
 SKIPPED=(
-  "15_parameters.sh (interactive parameter input)"
+  "15_parameters.sh  (interactive parameter input)"
   "20_mcp_servers.sh (requires Node.js/npx + MCP server)"
-  "22_chat_mode.sh  (interactive chat session)"
+  "22_chat_mode.sh   (interactive chat session)"
+  "29_agent_harness.sh (3-tier orchestration, 10-20 min runtime)"
 )
 
 # --- Set up output ---
@@ -200,6 +214,16 @@ run_script() {
   return ${status}
 }
 
+# Scripts that require BATCH_MODE=true to skip their interactive sessions
+BATCH_MODE_SCRIPTS=(
+  23_verify.sh
+  24_decompose.sh
+  25_spawn.sh
+  26_debate.sh
+  27_mention_routing.sh
+  28_model_switching.sh
+)
+
 # --- Main ---
 
 main() {
@@ -214,6 +238,13 @@ main() {
     local script="${SCRIPTS[$i]}"
     local index=$((i + 1))
 
+    # Enable batch mode for scripts with interactive "your turn" sessions
+    if printf '%s\n' "${BATCH_MODE_SCRIPTS[@]}" | grep -qx "${script}"; then
+      export BATCH_MODE=true
+    else
+      unset BATCH_MODE
+    fi
+
     if run_script "${script}" "${index}" "${total}"; then
       ((passed++))
     else
@@ -222,6 +253,8 @@ main() {
     fi
   done
 
+  unset BATCH_MODE
+
   echo "================================================================================"
   echo "  Summary"
   echo "================================================================================"

data/examples/tools/word_count_tool.rb

@@ -6,7 +6,7 @@ require 'ruby_llm/tool'
 class WordCountTool < RubyLLM::Tool
   def self.name = 'word_count'
 
-  description <<~'DESC'
+  description <<~DESC
     Count words, characters, lines, and sentences in a given text.
     Useful for text analysis and content length checks.
   DESC

data/lib/AGENTS.md

@@ -0,0 +1,57 @@
+### Local Agent Context: lib
+
+## Setup & Commands
+
+- To run the AIA application, use: `ruby lib/aia.rb`
+- Set up configurations by editing `lib/aia/config/defaults.yml` or using environment variables prefixed with `AIA_`.
+
+## Code Style & Patterns
+
+- Use single source of truth for configs: defined in `lib/aia/config/defaults.yml`
+- CLI flags are mapped to nested config locations using the `CLI_TO_NESTED_MAP` hash within `aia/config.rb`.
+- Initialize new components within the AIA module using `AIA` namespace, e.g., `AIA::ChatLoop`.
+
+## Implementation Details
+
+### Entry Point - `lib/aia.rb`
+- Main application entry starts by loading essential modules and patches.
+- Use `AIA.run` as the entrypoint method which initializes configuration, validates it, and starts the session.
+
+### Configuring AIA - `lib/aia/config.rb`
+- Configurations are merged from sources in priority: defaults => user config => ENV => CLI.
+- Use `Config.setup(cli_overrides)` to initialize configuration with CLI argument overrides.
+- Ensure `lib/aia/config/model_spec.rb` is loaded for model specification handling.
+- Top-level config sections include: `service`, `llm`, `prompts`, `roles`, `skills`, `output`, `audio`, `image`, `embedding`, `tools`, `flags`, `registry`, `paths`, `logger`, `rules`, `concurrency`, `tool_filter`.
+- `roles` and `skills` are proper config sections; `AIA.config.skills.dir` returns the resolved skills directory.
+
+### Directive System - `lib/aia/directive.rb` and `lib/aia/directives/`
+- `AIA::Directive` (base class) inherits from `PM::Directive` and adds AIA-specific concerns.
+- `DIRECTIVE_PREFIX = '/'` — all chat directives use a single slash, not `//`.
+- The base class provides `parse_search_terms(args)` as a private instance method available to all directive subclasses. It splits args into `[positive_terms, negative_terms]`: bare terms and `+prefix` are positive (AND); `-`, `~`, or `!` prefix marks AND NOT terms.
+- Directive subclasses live in `lib/aia/directives/`:
+  - `web_and_file_directives.rb` — `/skill`, `/skills`, `/webpage`, `/paste`
+  - `model_directives.rb` — `/llms` (and aliases), `/compare`
+  - `context_directives.rb`, `execution_directives.rb`, `navigation_directives.rb`, `special_mode_directives.rb`, `config_directives.rb`
+
+### `/skill` and `/skills` Directives - `lib/aia/directives/web_and_file_directives.rb`
+- Skills directory resolves via `aia_skills_dir`: `AIA.config.skills.dir` → `$AIA_SKILLS__DIR` → `~/.prompts/skills`.
+- A skill is a subdirectory containing a `SKILL.md` file with YAML front matter (`name`, `description`).
+- `/skill <id>` reads and returns the full `SKILL.md` content. On error, prints to stdout and returns `nil` (nothing injected into the AI prompt).
+- `/skills [terms...]` prints `skill_id: name\n  description\n\n` to stdout for each matching skill; returns `nil`. Supports AND logic for positive terms and AND NOT for `-`/`~`/`!`-prefixed terms.
+
+### `/llms` Directive - `lib/aia/directives/model_directives.rb`
+- `available_models` (aliased as `/llms`, `/models`, etc.) parses args with `parse_search_terms` into `positive_terms` and `negative_terms`.
+- Passes both to `show_rubyllm_models(positive_terms, negative_terms)`, `show_ollama_models(api_base, positive_terms, negative_terms)`, and `show_lms_models(api_base, positive_terms, negative_terms)`.
+- Negative terms apply AND NOT filtering: models whose entry string contains any negative term are excluded.
+
+### Chat Loop Operation - `lib/aia/chat_loop.rb`
+- `AIA::ChatLoop` handles the interactive chat REPL loop.
+- Initialize the chat loop with components: `robot`, `ui_presenter`, `directive_processor`.
+- Start the chat loop with `ChatLoop#start`, which sets up the session, processes context, and runs the interactive loop.
+
+### Error Handling
+- Use `AIA.debug_warn(msg, exc: nil)` to log warnings with optional debug backtrace.
+- Catch `AIA::ConfigurationError` and `AIA::Error` in the run method to handle config and general errors gracefully.
+
+### Resetting State
+- `AIA.reset!` reinitializes key components, suitable for stateful parts (e.g., `config`, `client`).