aia 0.9.6 → 0.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02a36ff149a0fa6eb782735e963ca860260c10b43133b56ebe49adda5074c86d
-  data.tar.gz: 588411eb80ac91a88fc8dd456595610f9bfb71947201629ec1d5b64f5a1cf2d6
+  metadata.gz: 3411bc073c7fadee9f625917b13b06fb11aee61c234f61c57958be1000f261c6
+  data.tar.gz: 1228b68648536d5c8a4caeb2e6cf6eb91400647c96163b1ab7b6f499b1001d99
 SHA512:
-  metadata.gz: 59eb282bad1dd8e450ec98608e8f4b295ce6c9b0084d2aef7772df4834d5beecddd7fd785a46db1a47e72cf6f90c8d1b15dbd2843a8d2be737d6bf6f47911002
-  data.tar.gz: 4483f697b88266a73187b2483bae32ac6b82a4fc432bc3e494f35c5d3c63c4395949a95a8282a3a18f475bb9cbdacaf7253069817fc54c3d3927ae4a66a401bf
+  metadata.gz: cbd94570f820e5007a7a9ba94b908a0f36407ec9b9f11074283e67374b24261db18309f32c2e079521c93322ce6fe4c2223181d61f3dce99c4a0d39bc5a26e48
+  data.tar.gz: fdd5647498501805e598c5e7d319193928954e1e2e639e473440c323e49abee46c09aa665130679e790db15c49d81f0ab5bf09deb5ac0f4b6b67eba6a9da625c

data/.config/tocer/configuration.yml

@@ -1,5 +1,6 @@
 label: "## Table of Contents"
 patterns:
   - "README.md"
-  - doc/*.md
+  - docs/*.md
+  - docs/draft_articles/*.md
 root_dir: "."

data/.version

@@ -1 +1 @@
-0.9.6
+0.9.8

data/CHANGELOG.md

@@ -1,7 +1,24 @@
 # Changelog
 ## [Unreleased]
+
 ## Released
 
+### [0.9.8] 2025-06-25
+- fixing an issue with pipelined prompts
+- now showing the complete modality of the model on the processing line.
+- changed -p option from prompts_dir to pipeline
+
+### [0.9.7] 2025-06-20
+
+- **NEW FEATURE**: Added `--available_models` CLI option to list all available AI models
+- **NEW FEATURE**: Added `//tools` to show a list of available tools and their description
+- **BUG FIX**: Fixed SharedTools compatibility issue with models that don't support function calling
+- **BUG FIX**: Fixed problem with piped text through STDIN not being handled correctly.
+- **BUG FIX**: Fixed issue with output going to the default out_file evenhen --no-out_file is specified.
+- **BUG FIX**: Fixed issue with executable prompt files by adding the --exec option
+- **DOCUMENTATION**: Updated README for better clarity and structure
+- **DEPENDENCY**: Updated Gemfile.lock with latest dependency versions
+
 ### [0.9.6] 2025-06-13
 - fixed issue 84 with the //llms directive
 - changed the monkey patch to the RubyLLM::Model::Modalities class at the suggestions of the RubyLLM author in prep for a PR against that gem.

data/README.md

@@ -6,7 +6,7 @@
 
 AIA is a command-line utility that facilitates interaction with AI models through dynamic prompt management. It automates the management of pre-compositional prompts and executes generative AI commands with enhanced features including embedded directives, shell integration, embedded Ruby, history management, interactive chat, and prompt workflows.
 
-AIA leverages the [prompt_manager gem](https://github.com/madbomber/prompt_manager) to manage prompts, utilizes the [CLI tool fzf](https://github.com/junegunn/fzf) for prompt selection, and includes the [shared_tools gem](https://github.com/madbomber/shared_tools) which provides a collection of ready-to-use functions for use with LLMs that support tools.
+AIA leverages the [prompt_manager gem](https://github.com/madbomber/prompt_manager) to manage prompts, utilizes the [CLI tool fzf](https://github.com/junegunn/fzf) for prompt selection, and can use the [shared_tools gem](https://github.com/madbomber/shared_tools) which provides a collection of common ready-to-use functions for use with LLMs that support tools.
 
 **Wiki**: [Checkout the AIA Wiki](https://github.com/MadBomber/aia/wiki)
 
@@ -25,12 +25,12 @@ AIA leverages the [prompt_manager gem](https://github.com/madbomber/prompt_manag
 3. **Create your first prompt:**
    ```bash
    mkdir -p ~/.prompts
-   echo "What is [TOPIC]?" > ~/.prompts/ask.txt
+   echo "What is [TOPIC]?" > ~/.prompts/what_is.txt
    ```
 
 4. **Run your prompt:**
    ```bash
-   aia ask
+   aia what_is
    ```
    You'll be prompted to enter a value for `[TOPIC]`, then AIA will send your question to the AI model.
 
@@ -40,43 +40,76 @@ AIA leverages the [prompt_manager gem](https://github.com/madbomber/prompt_manag
    ```
 
 ```plain
-     ,      ,
-     (\____/) AI Assistant
-      (_oo_)   Fancy LLM
-        (O)     is Online
-      __||__    \)
-    [/______\]  /
-   / \__AI__/ \/
-  /    /__\
- (\   /____\
+
+       ,      ,
+       (\____/) AI Assistant (v0.9.7) is Online
+        (_oo_)   gpt-4o-mini
+         (O)       using ruby_llm (v1.3.1)
+       __||__    \) model db was last refreshed on
+     [/______\]  /    2025-06-18
+    / \__AI__/ \/      You can share my tools
+   /    /__\
+  (\   /____\
+
 ```
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
 ## Table of Contents
 
-  - [Quick Start](#quick-start)
   - [Installation & Prerequisites](#installation--prerequisites)
+    - [Requirements](#requirements)
+    - [Installation](#installation)
+    - [Setup Shell Completion](#setup-shell-completion)
   - [Basic Usage](#basic-usage)
+    - [Command Line Interface](#command-line-interface)
+    - [Key Command-Line Options](#key-command-line-options)
+    - [Directory Structure](#directory-structure)
   - [Configuration](#configuration)
     - [Essential Configuration Options](#essential-configuration-options)
     - [Configuration Precedence](#configuration-precedence)
+    - [Configuration Methods](#configuration-methods)
     - [Complete Configuration Reference](#complete-configuration-reference)
   - [Advanced Features](#advanced-features)
     - [Prompt Directives](#prompt-directives)
+      - [Configuration Directive Examples](#configuration-directive-examples)
+      - [Dynamic Content Examples](#dynamic-content-examples)
     - [Shell Integration](#shell-integration)
     - [Embedded Ruby (ERB)](#embedded-ruby-erb)
     - [Prompt Sequences](#prompt-sequences)
+      - [Using --next](#using---next)
+      - [Using --pipeline](#using---pipeline)
+      - [Example Workflow](#example-workflow)
     - [Roles and System Prompts](#roles-and-system-prompts)
     - [RubyLLM::Tool Support](#rubyllmtool-support)
   - [Examples & Tips](#examples--tips)
     - [Practical Examples](#practical-examples)
+      - [Code Review Prompt](#code-review-prompt)
+      - [Meeting Notes Processor](#meeting-notes-processor)
+      - [Documentation Generator](#documentation-generator)
     - [Executable Prompts](#executable-prompts)
     - [Tips from the Author](#tips-from-the-author)
+      - [The run Prompt](#the-run-prompt)
+      - [The Ad Hoc One-shot Prompt](#the-ad-hoc-one-shot-prompt)
+      - [Recommended Shell Setup](#recommended-shell-setup)
+      - [Prompt Directory Organization](#prompt-directory-organization)
   - [Security Considerations](#security-considerations)
+    - [Shell Command Execution](#shell-command-execution)
+    - [Safe Practices](#safe-practices)
+    - [Recommended Security Setup](#recommended-security-setup)
   - [Troubleshooting](#troubleshooting)
+    - [Common Issues](#common-issues)
+    - [Error Messages](#error-messages)
+    - [Debug Mode](#debug-mode)
+    - [Performance Issues](#performance-issues)
   - [Development](#development)
+    - [Testing](#testing)
+    - [Building](#building)
+    - [Architecture Notes](#architecture-notes)
   - [Contributing](#contributing)
+    - [Reporting Issues](#reporting-issues)
+    - [Development Setup](#development-setup)
+    - [Areas for Improvement](#areas-for-improvement)
   - [Roadmap](#roadmap)
   - [License](#license)
 
@@ -281,16 +314,21 @@ Directives are special commands in prompt files that begin with `//` and provide
 | Directive | Description | Example |
 |-----------|-------------|---------|
 | `//config` | Set configuration values | `//config model = gpt-4` |
+| `//context` | Show context for this conversation | `//context` |
 | `//include` | Insert file contents | `//include path/to/file.txt` |
 | `//shell` | Execute shell commands | `//shell ls -la` |
+| `//robot` | Show the pet robot ASCII art w/versions | `//robot` |
 | `//ruby` | Execute Ruby code | `//ruby puts "Hello World"` |
 | `//next` | Set next prompt in sequence | `//next summary` |
 | `//pipeline` | Set prompt workflow | `//pipeline analyze,summarize,report` |
 | `//clear` | Clear conversation history | `//clear` |
 | `//help` | Show available directives | `//help` |
 | `//available_models` | List available models | `//available_models` |
+| `//tools` | Show a list of available tools and their description | `//tools` |
 | `//review` | Review current context | `//review` |
 
+Directives can also be used in the interactive chat sessions.
+
 #### Configuration Directive Examples
 
 ```bash
@@ -462,22 +500,20 @@ aia --tools ~/tools/ --rejected_tools deprecated
 - Data processing utilities
 
 **Shared Tools Collection:**
-AIA includes the [shared_tools gem](https://github.com/madbomber/shared_tools) which provides a curated collection of commonly-used RubyLLM::Tool implementations:
+AIA can use the [shared_tools gem](https://github.com/madbomber/shared_tools) which provides a curated collection of commonly-used  tools (aka functions) via the --require option.
 
 ```bash
 # Access shared tools automatically (included with AIA)
-aia --tools shared --chat
+aia --require shared_tools/ruby_llm --chat
 
-# Combine with custom tools
-aia --tools shared,~/my-tools/ --chat
+# To access just one specific shared tool
+aia --require shared_tools/ruby_llm/edit_file --chat
+
+# Combine with your own local custom RubyLLM-based tools
+aia --require shared_tools/ruby_llm --tools ~/my-tools/ --chat
 ```
 
-Available shared tools include:
-- **File operations**: read, write, edit, search files
-- **Web utilities**: fetch web pages, parse HTML/JSON
-- **System tools**: execute commands, get system info
-- **Data processing**: CSV/JSON manipulation, text analysis
-- **API helpers**: HTTP requests, common API patterns
+The above examples show the shared_tools being used within an interactive chat session.  They are also available in batch prompts as well using the same --require option.  You can also use the //ruby directive to require the shared_tools as well and using a require statement within an ERB block.
 
 ## Examples & Tips
 
@@ -486,7 +522,7 @@ Available shared tools include:
 #### Code Review Prompt
 ```bash
 # ~/.prompts/code_review.txt
-//config model = gpt-4
+//config model = gpt-4o-mini
 //config temperature = 0.3
 
 Review this code for:
@@ -496,7 +532,6 @@ Review this code for:
 - Maintainability concerns
 
 Code to review:
-//include [CODE_FILE]
 ```
 
 Usage: `aia code_review mycode.rb`
@@ -516,7 +551,7 @@ Please clean up and structure these meeting notes.
 #### Documentation Generator
 ```bash
 # ~/.prompts/document.txt
-//config model = gpt-4
+//config model = gpt-4o-mini
 //shell find [PROJECT_DIR] -name "*.rb" | head -10
 
 Generate documentation for the Ruby project shown above.
@@ -525,48 +560,62 @@ Include: API references, usage examples, and setup instructions.
 
 ### Executable Prompts
 
-Create reusable executable prompts:
+The `--exec` flag is used to create executable prompts.  If it is not present on the shebang line then the prompt file will be treated like any other context file.  That means that the file will be included as context in the prompt but no dynamic content integration or directives will be processed. All other AIA options are, well, optional.  All you need is an initial prompt ID and the --exec flag.
+
+In the example below the option `--no-out_file` is used to direct the output from the LLM processing of the prompt to STDOUT.  This way the executable prompts can be good citizens on the *nix command line receiving piped in input via STDIN and send its output to STDOUT.
+
+Create executable prompts:
 
 **weather_report** (make executable with `chmod +x`):
 ```bash
-#!/usr/bin/env aia run --no-out_file
-# Get current weather for a city
+#!/usr/bin/env aia run --no-out_file --exec
+# Get current storm activity for the east and south coast of the US
+
+Summarize the tropical storm outlook fpr the Atlantic, Caribbean Sea and Gulf of America.
 
-What's the current weather in [CITY]?
-Include temperature, conditions, and 3-day forecast.
-Format as a brief, readable summary.
+//webpage https://www.nhc.noaa.gov/text/refresh/MIATWOAT+shtml/201724_MIATWOAT.shtml
 ```
 
 Usage:
 ```bash
 ./weather_report
-# Prompts for city, outputs to stdout
-
-./weather_report | glow  # Render with glow
+./weather_report | glow  # Render the markdown with glow
 ```
 
 ### Tips from the Author
 
-**Most Versatile Prompt:**
+#### The run Prompt
+```bash
+# ~/.prompts/run.txt
+# Desc: A configuration only prompt file for use with executable prompts
+#       Put whatever you want here to setup the configuration desired.
+#       You could also add a system prompt to preface your intended prompt
+```
+
+Usage: `echo "What is the meaning of life?" | aia run`
+
+#### The Ad Hoc One-shot Prompt
 ```bash
 # ~/.prompts/ad_hoc.txt
 [WHAT_NOW_HUMAN]
 ```
-Usage: `aia ad_hoc` - perfect for any quick question without cluttering shell history.
+Usage: `aia ad_hoc` - perfect for any quick one-shot question without cluttering shell history.
 
-**Recommended Shell Setup:**
+#### Recommended Shell Setup
 ```bash
 # ~/.bashrc_aia
 export AIA_PROMPTS_DIR=~/.prompts
 export AIA_OUT_FILE=./temp.md
 export AIA_MODEL=gpt-4o-mini
-export AIA_VERBOSE=true  # Shows spinner while waiting
+export AIA_VERBOSE=true  # Shows spinner while waiting for LLM response
 
 alias chat='aia --chat --terse'
-alias ask='aia ad_hoc'
+ask() { echo "$1" | aia run --no-out_file; }
 ```
 
-**Prompt Organization:**
+The `chat` alias and the `ask` function (shown above in HASH) are two powerful tools for interacting with the AI assistant. The `chat` alias allows you to engage in an interactive conversation with the AI assistant, while the `ask` function allows you to ask a question and receive a response. Later in this document the `run` prompt ID is discussed.  Besides using the run prompt ID here its also used in making executable prompt files.
+
+#### Prompt Directory Organization
 ```
 ~/.prompts/
 ├── daily/           # Daily workflow prompts
@@ -611,10 +660,6 @@ AIA executes shell commands and Ruby code embedded in prompts. This provides pow
 # Set restrictive permissions on prompts directory
 chmod 700 ~/.prompts
 chmod 600 ~/.prompts/*.txt
-
-# Use separate prompts directory for shared/untrusted prompts
-export AIA_PROMPTS_DIR_SHARED=~/shared-prompts
-chmod 755 ~/shared-prompts
 ```
 
 ## Troubleshooting

data/examples/headlines

@@ -1,21 +1,30 @@
-#!/usr/bin/env aia run --no-out_file
-# File: examples/headlines
+#!/usr/bin/env aia run --no-out_file --exec
+# NOTE: the --exec option is REQUIRED to run this executable prompt file
+#       This option signals that the contents of this file are to be appended
+#       to the contents of the given prompt ID file.  In this case it is the
+#       "run" prompt ID's text file.
+#
+#       All other AIA options are, well, optional.  The --no-out_file is
+#       used here to cause the response to this executable prompt to be
+#       sent to STDOUT like a good little *nix CLI tool.  Its not necessary.
+#       if you do not use it, the output will go to the default out_file.
+#       You could also specify a specific file to write the output to built
+#       but it is more convential to use the *nix STDOUT redirect "> output.md"
+#
 # Desc: retrieves the news.google.com website
 #       extracts and formats the headlines
-#       and prints them to the console
+#       and prints them to STDOUT
+#
+# Method:
+#   There are several ways you can accomplish this task using
+#   the shell or ERB integration.  For this example lets use
+#   a built-in directive.
 
-//config shell = true
-# //config
+Extract and summarize the headlines from the following markdown:
 
-# Puts the webpage into index.html
-# //shell wget2 https://news.google.com
+//webpage https://news.google.com
 
-$(wget2 https://news.google.com)
+__END__
 
-
-# Lets hear the headlines as well as read them.
-//config speak = true
-
-Extract and summarize the headlines from the following text:
-
-$(html2text index.html)
+The //webpage directive makes use of the website https://pure.md
+to convert any given URL to a markdown file.

data/examples/tools/pdf_page_reader.rb

@@ -0,0 +1,30 @@
+# examples/tools/pdf_page_reader.rb
+# See: https://max.engineer/giant-pdf-llm
+
+require "ruby_llm/tool"
+require 'pdf-reader'
+
+
+class PdfPageReader < RubyLLM::Tool
+  # TODO: make the path to the pdf document a parameter
+  DOC = PDF::Reader.new('docs/big-doc.pdf')
+
+  description 'Read the text of any set of pages from a PDF document.'
+  param :page_numbers,
+    desc: 'Comma-separated page numbers (first page: 1). (e.g. "12, 14, 15")'
+
+  def execute(page_numbers:)
+    puts "\n-- Reading pages: #{page_numbers}\n\n"
+    page_numbers = page_numbers.split(',').map { _1.strip.to_i }
+    pages = page_numbers.map { [_1, DOC.pages[_1.to_i - 1]] }
+    {
+      pages: pages.map { |num, p|
+        # There are lines drawn with dots in my doc.
+        # So I squeeze them to save tokens.
+        { page: num, text: p&.text&.squeeze('.') }
+      }
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/examples/tools/run_shell_command.rb

@@ -1,5 +1,6 @@
 # experiments/ai_misc/coding_agent_with_ruby_llm/tools/run_shell_command.rb
 
+require "io/console"
 require "ruby_llm/tool"
 
 module Tools
@@ -8,10 +9,21 @@ module Tools
     param :command, desc: "The command to execute"
 
     def execute(command:)
-      puts "AI wants to execute the following shell command: '#{command}'"
-      print "Do you want to execute it? (y/n) "
-      response = gets.chomp
-      return { error: "User declined to execute the command" } unless response == "y"
+      print "\n\n"
+      puts "AI wants to execute the following shell command:"
+      puts "="*command.size
+      puts command
+      puts "="*command.size
+      print "\n\n"
+
+      sleep 0.5
+      print "Execute the command? (y/N):"
+      allowed = STDIN.getch == "y"
+
+      unless allowed
+        print "Command aborted" + " "*30 if defined?(AIA)
+        return { error: "User declined to execute the command" }
+      end
 
       `#{command}`
     rescue => e

data/lib/aia/chat_processor_service.rb

@@ -60,9 +60,8 @@ module AIA
     def output_response(response)
       speak(response)
 
-      # Only output to STDOUT if we're in chat mode
-
-      if AIA.chat? || 'STDOUT' == AIA.config.out_file.upcase
+      # Output to STDOUT or file based on out_file configuration
+      if AIA.config.out_file.nil? || 'STDOUT' == AIA.config.out_file.upcase
         print "\nAI:\n  "
         puts response
       else
@@ -94,26 +93,7 @@ module AIA
 
     def determine_operation_type
       mode = AIA.config.client.model.modalities
-
-      if mode.text_to_image?
-        :text_to_image
-      elsif mode.image_to_text?
-        :image_to_text
-      elsif mode.audio_to_text?
-        :audio_to_text
-      elsif mode.text_to_audio?
-        :text_to_audio
-      elsif mode.audio_to_audio?
-        :audio_to_audio
-      elsif mode.image_to_image?
-        :image_to_image
-      elsif mode.audio_to_image?
-        :audio_to_image
-      elsif mode.image_to_audio?
-        :image_to_audio
-      else
-        :text_to_text
-      end
+      mode.input.join(',') + " TO " + mode.output.join(',')
     end
   end
 end