txt: ## dist_zef-bduggan-AI-Gator.md
  [![Actions Status](https://github.com/bduggan/raku-ai-gator/actions/workflows/linux.yml/badge.svg)](https://github.com/bduggan/raku-ai-gator/actions/workflows/linux.yml)
  [![Actions Status](https://github.com/bduggan/raku-ai-gator/actions/workflows/macos.yml/badge.svg)](https://github.com/bduggan/raku-ai-gator/actions/workflows/macos.yml)
  
  # NAME
  
  AI::Gator - Ailigator -- your AI Generic Assistant with a Tool-Oriented REPL
  
  ![ailigator](https://github.com/user-attachments/assets/0e71fb98-e149-483a-8654-300316e413e8)
  
  # SYNOPSIS
  
  Put this into $HOME/ai-gator/tools/weather.raku:
  
  ```
  #| Get real time weather for a given city
  our sub get_weather(
     Str :$city! #= The city to get the weather for
  ) {
     "The weather in $city is sunny.";
  }
  
  ```
  
  Then start the AI Gator REPL:
  
  ```
  $ ai-gator
  
  You: Is it raining in Toledo?
  [tool] get_weather city Toledo
  [tool] get_weather done
  Gator: No, it is not raining in Toledo. The weather is sunny.
  You: What about Philadelphia or San Francisco?
  [tool] get_weather city Philadelphia
  [tool] get_weather done
  [tool] get_weather city San Francisco
  [tool] get_weather done
  Gator: It is sunny in both Philadelphia and San Francisco.
  
  ```
  
  For other options, run:
  
  ```
  $ ai-gator -h
  
  ```
  
  This module can also be used programmatically:
  
  ```
  use AI::Gator;
  
  my AI::Gator $gator = AI::Gator::Gemini.new: model => 'gemini-2.0-flash';
  my AI::Gator::Session $session = AI::Gator::Session::Gemini.new;
  
  $session.add-message: "Hello, Gator!";
  
  react whenever $gator.chat($session) -> $chunk {
    print $chunk;
  }
  
  # Hello! How can I help you today?
  
  ```
  
  To use tools programmatically, here is an example:
  
  ```
  use AI::Gator;
  
  #| Get real time weather for a given city
  sub get_weather(
     Str :$city! #= The city to get the weather for
  ) {
     "The weather in $city is sunny.";
  }
  
  my AI::Gator $gator = AI::Gator::Gemini.new:
    model => 'gemini-2.0-flash',
    :quiet,
    tools => @( &get_weather, );
  
  my AI::Gator::Session $session = AI::Gator::Session::Gemini.new;
  
  $session.add-message: "Hello ailigator!";
  react whenever $gator.chat($session) { .print }
  # Hello! How can I help you today? 🐊
  
  my $tool-promise = start $gator.tool-builder($session);
  $session.add-message: "What is the weather in Paris?";
  react whenever $gator.chat($session) { .print }
  await $tool-promise;
  
  $gator.do-tool-calls: $session;
  
  react whenever $gator.chat($session) { .print }
  # The weather in Paris is sunny.
  
  ```
  
  # DESCRIPTION
  
  AI::Gator is an AI assistant oriented towards using tools and a REPL interface.
  
  Features:
  
  * streaming responses
  * tool definitions in Raku
  * tool calls
  * session storage
  * Gemini and OpenAI support
  * REPL interface with history
  
  Tools are defined as Raku functions and converted into an OpenAI or Gemini specification using declarator pod and other native Raku features.
  
  All sessions are stored in the sessions/ directory, and the REPL stores the history in a .history file, readline-style.
  
  # COMMAND LINE OPTIONS
  
  `ai-gator resume-last` will resume the last session, if it exists.
  
  `ai-gator resume session-id` will resume the specified session.
  
  `ai-gator sessions` will list all sessions.
  
  Also in the REPL:
  
  ```
  `\history` will show user + assistant commands
  
  `\history all` will show all commands, including tool calls
  
  `\history mine` will show just the user commands
  
  ```
  
  # CONFIGURATION
  
  Set AI\_GATOR\_HOME to ai-gator's home (by default $HOME/ai-gator).
  
  In this directory, the following files and directories are used:
  
  * config.toml: configuration file
  * tools/: directory with files containing tools
  * sessions/: directory with session files (created by the REPL)
  * .history: file with readline history (also created by the REPL)
  
  # CONFIGURATION FILE
  
  Sample configuration to use Gemini:
  
  ```
  model = "gemini-2.0-flash"
  adapter = 'Gemini'
  
  ```
  
  Sample configuration to use OpenAI:
  
  ```
  model = "gpt-4o"
  base-uri = "https://api.openai.com/v1"
  
  ```
  
  # ENVIRONMENT
  
  * AI\_GATOR\_HOME: home directory for AI::Gator (default: $HOME/ai-gator)
  * GEMINI\_API\_KEY: API key for Gemini (if using Gemini)
  * OPENAI\_API\_KEY: API key for OpenAI (if using OpenAI)
  
  # NOTES
  
  This is all pretty rough and experimental. Expect the api to change. Patches welcome!
  
  # AUTHOR
  
  Brian Duggan
  