Quick Tour of AIA

Here is a quick high-level tour of the AIA repo:

1. Purpose

AIA (“AI Assistant”) is a Ruby-based CLI for managing and running parameterized prompts against LLMs (OpenAI, Anthropic, Mistral, etc.). It uses the prompt_manager gem for prompt storage/templating, the ai_client gem for talking to LLMs, and fzf CLI tool for interactive prompt selection.

2. Top-Level Layout

• Gem metadata: aia.gemspec, Gemfile(.lock), Rakefile, Justfile
• Executable: bin/aia → #!/usr/bin/env ruby; require_relative '../lib/aia'; AIA.run
• Documentation:
  • README.md
  • CHANGELOG.md
  • docs/architecture.md
  • knowledge.md
• Examples: examples/ → sample prompt files
• Testing: test/ → Minitest specs
• Coverage: coverage/ → test coverage report (SimpleCov)
• Vendor: vendor/ → vendored gems (via Bundler)

3. Core Library (lib/aia/)

• lib/aia.rb
  • Entrypoint: sets up Config, instantiates PromptHandler, AIClientAdapter and Session, and starts the session.
• config.rb
  • Parses CLI flags, environment variables and (TOML/YAML) config files into a single OpenStruct.
• prompt_handler.rb
  • Finds/loads your text-based prompts from AIA_PROMPTS_DIR, applies ERB, strips comments, handles parameters.
• directive_processor.rb
  • Scans prompt text for “//shell”, “//ruby”, “//include”, “//config”, “//next”/“//pipeline” directives and runs them.
• shell_command_executor.rb
  • Safely invokes shell commands embedded in prompts.
• ai_client_adapter.rb
  • Adapts your config into calls to the ai_client gem for completions, chat, embeddings, images, TTS/ASR, etc.
• history_manager.rb
  • Logs every prompt run (and its parameters) to a usage log.
• ui_presenter.rb
  • Renders results (supports markdown, pagers, TTS playback, etc.), and integrates fzf when “--fuzzy” is on.
• chat_processor_service.rb
  • Powers the interactive “--chat” mode, maintaining message history and directives across turns.
• session.rb
  • Knits it all together: given a prompt ID (or chat/fuzzy/context files), orchestrates handler → directives → LLM → UI.

4. Prompts and Workflows

• Prompts live as foo.txt in your prompts directory (default ~/.prompts).
• You can parameterize them, run ERB, include other files, shell out, chain them (//next, //pipeline), clear state, etc.
• You can also treat the prompt as an executable (#!/usr/bin/env aia run) and pass files at invocation.

5. Config & Extensibility

• Configuration via CLI, ENV (AIA_*), and a ~/.aia/config.yml (YAML or TOML)
• Supports models, temperature/max_tokens, image/TTS/ASR options, etc.
• You can drop your own Ruby libraries in “require_libs” to extend directive logic.

6. Testing & Packaging

• Testing: Minitest lives under test/aia_*.rb, test_helper.rb wires in SimpleCov.
• Rakefile defines test, lint, release tasks.
• Justfile (and main.just) are convenience shortcuts for building, testing, etc.
• Releases are built into .gem files under pkg/.

7. Getting Started

• Install dependencies:
  • brew install fzf
  • gem install aia (or bundle install + bundle exec bin/aia)
• Set AIA_PROMPTS_DIR (defaults to ~/.prompts)
• Write a prompt “example.txt” and run:

  aia example
  

• Interactive Shell:

  aia --chat