README

MakerAI ChatTools

Companion package for MakerAI — 29 ready-to-use implementations of the ChatTools bridge interfaces for Delphi applications.

Each unit wraps a specific third-party AI API and plugs directly into TAiChatConnection via MakerAI's gap-analysis bridge: set SessionCaps to declare what capability you need, assign the corresponding tool, and MakerAI routes the call automatically — no changes to your chat code.

Conn.Params.Values['ModelCaps']   := '[]';
Conn.Params.Values['SessionCaps'] := '[cap_WebSearch]';
Conn.WebSearchTool := TAiTavilyWebSearchTool.Create(nil);
// RunNew detects the gap → calls Tavily → injects results → completions

Requirements

• Delphi 11 Alexandria or later (10.4 Sydney minimum)
• MakerAI installed and compiled → github.com/gustavoeenriquez/MakerAi

Installation

Option A — Package (recommended)

1. Open Source/Packages/uMakerAi.ChatTools.dproj in Delphi
2. Build → generates uMakerAi.ChatTools.bpl
3. Install via Component > Install Packages

Option B — Source only

Add the specific Source/<category>/ folder to Delphi's Library Path. Each demo .dproj already includes the correct relative paths.

Available Tools

Web Search

These tools implement IAiWebSearchTool — used when SessionCaps includes cap_WebSearch.
Assign to TAiChatConnection.WebSearchTool.

Key properties (all tools): ApiKey, MaxResults/NumResults/Count.
Env var convention: TAVILY_API_KEY, BRAVE_API_KEY, SERPAPI_API_KEY, EXA_API_KEY, PERPLEXITY_API_KEY

Speech — Text-to-Speech & Speech-to-Text

These tools implement IAiSpeechTool — used when SessionCaps includes cap_Speech.
Assign to TAiChatConnection.SpeechTool.

Key properties: ApiKey, TTSModel, STTModel, VoiceName/VoiceId, Language.

Vision — Image Description

These tools implement IAiVisionTool — used when SessionCaps includes cap_Vision.
Assign to TAiChatConnection.VisionTool.

Key properties: ApiKey, Model, MaxTokens, DescriptionPrompt.

Image Generation

These tools implement IAiImageTool — used when SessionCaps includes cap_GenImage.
Assign to TAiChatConnection.ImageTool.

Key properties: ApiKey, ModelPath/Model/ModelVersion, ImageSize/AspectRatio, OutputFormat, NegativePrompt.

Video Generation

These tools implement IAiVideoTool — used when SessionCaps includes cap_GenVideo.
Assign to TAiChatConnection.VideoTool.

Special auth notes:

• KlingAI: env vars KLINGAI_API_KEY + KLINGAI_API_SECRET — JWT is generated and signed automatically.
• Runway ML: header X-Runway-Version: 2024-11-06 is added automatically.
• D-ID: Basic Auth format key: (empty password) is handled automatically.

Key properties: ApiKey, Model, DurationSeconds/Duration/Seconds, AspectRatio, Ratio, NegativePrompt.

PDF Parsing

These tools implement IAiPdfTool — used when SessionCaps includes cap_Pdf.
Assign to TAiChatConnection.PdfTool.

Key properties: ApiKey (N/A for Native), ResultType/OutputFormat, Language, PremiumMode/ParseMode.

• Native Delphi: VisionChat (optional TAiChat for image pages), Prompt, DPI, MinTextLength
• Env var convention: LLAMA_CLOUD_API_KEY, MISTRAL_API_KEY, REDUCTO_API_KEY, UNSTRUCTURED_API_KEY

Usage Examples

Web Search with gap-analysis bridge

uses uMakerAi.Chat.AiConnection, uMakerAi.Chat.Initializations,
     uMakerAi.ChatTools.Tavily;

var
  Conn  : TAiChatConnection;
  Tavily: TAiTavilyWebSearchTool;
begin
  Tavily := TAiTavilyWebSearchTool.Create(nil);
  Conn   := TAiChatConnection.Create(nil);
  try
    Tavily.ApiKey      := '@TAVILY_API_KEY';
    Tavily.MaxResults  := 5;
    Tavily.IncludeAnswer := True;

    Conn.DriverName := 'Claude';
    Conn.Model      := 'claude-haiku-4-5-20251001';
    Conn.Params.Values['ApiKey']       := '@CLAUDE_API_KEY';
    Conn.Params.Values['Asynchronous'] := 'False';
    Conn.Params.Values['ModelCaps']    := '[]';
    Conn.Params.Values['SessionCaps']  := '[cap_WebSearch]';
    Conn.WebSearchTool := Tavily;

    Writeln(Conn.AddMessageAndRun('What are the top AI models of 2025?', 'user', []));
  finally
    Conn.WebSearchTool := nil;
    Conn.Free;
    Tavily.Free;
  end;
end;

Direct call (without chat)

uses uMakerAi.Core, uMakerAi.Chat.Messages, uMakerAi.Chat.Tools,
     uMakerAi.ChatTools.ElevenLabs;

var
  Tool  : TAiElevenLabsTool;
  AskMsg: TAiChatMessage;
  ResMsg: TAiChatMessage;
begin
  Tool   := TAiElevenLabsTool.Create(nil);
  AskMsg := TAiChatMessage.Create(nil);
  ResMsg := TAiChatMessage.Create(nil);
  try
    Tool.ApiKey          := '@ELEVENLABS_API_KEY';
    Tool.VoiceId         := 'JBFqnCBsd6RMkjVDRZzb'; // George
    Tool.TTSModel        := 'eleven_multilingual_v2';

    Tool.ExecuteSpeechGeneration('Hello, I am an AI assistant.', ResMsg, AskMsg);

    if ResMsg.MediaFiles.Count > 0 then
      ResMsg.MediaFiles[0].Stream.SaveToFile('output.mp3');
  finally
    ResMsg.Free; AskMsg.Free; Tool.Free;
  end;
end;

PDF parsing with native Delphi (no external API)

uses uMakerAi.Chat.AiConnection, uMakerAi.Chat.Initializations,
     uMakerAi.ChatTools.NativePdf;

var
  Conn     : TAiChatConnection;
  PdfTool  : TAiNativePdfTool;
  Media    : TAiMediaFile;
begin
  PdfTool := TAiNativePdfTool.Create(nil);
  Media   := TAiMediaFile.Create(nil);
  Conn    := TAiChatConnection.Create(nil);
  try
    // Configure vision chat for analyzing scanned pages (optional)
    Conn.DriverName := 'Claude';
    Conn.Model      := 'claude-3-5-sonnet-20241022';
    Conn.Params.Values['ApiKey']       := '@CLAUDE_API_KEY';
    Conn.Params.Values['Asynchronous'] := 'False';

    // Configure PDF tool
    PdfTool.VisionChat := Conn;  // for scanned/image pages
    PdfTool.DPI        := 150;
    PdfTool.Prompt     := 'Extract all text and information from this page.';

    Media.LoadFromFile('document.pdf');

    Conn.Params.Values['ModelCaps']   := '[]';
    Conn.Params.Values['SessionCaps'] := '[cap_Pdf]';
    Conn.PdfTool := PdfTool;

    // MakerAI detects gap → extracts text (local 1ms) or renders + vision (50-200ms) → completions
    Writeln(Conn.AddMessageAndRun('Summarize this document', 'user', [Media]));
  finally
    Conn.PdfTool := nil;
    Conn.Free; Media.Free; PdfTool.Free;
  end;
end;

PDF parsing with cloud service (LlamaParse)

uses uMakerAi.Chat.AiConnection, uMakerAi.Chat.Initializations,
     uMakerAi.ChatTools.LlamaParse;

var
  Conn      : TAiChatConnection;
  LlamaParse: TAiLlamaParseToolPdf;
  Media     : TAiMediaFile;
begin
  LlamaParse := TAiLlamaParseToolPdf.Create(nil);
  Media      := TAiMediaFile.Create(nil);
  Conn       := TAiChatConnection.Create(nil);
  try
    LlamaParse.ApiKey     := '@LLAMA_CLOUD_API_KEY';
    LlamaParse.ResultType := 'markdown';

    Media.LoadFromFile('document.pdf');

    Conn.DriverName := 'Claude';
    Conn.Model      := 'claude-haiku-4-5-20251001';
    Conn.Params.Values['ApiKey']       := '@CLAUDE_API_KEY';
    Conn.Params.Values['Asynchronous'] := 'False';
    Conn.Params.Values['ModelCaps']    := '[]';
    Conn.Params.Values['SessionCaps']  := '[cap_Pdf]';
    Conn.PdfTool := LlamaParse;

    // MakerAI detects gap → parses PDF with LlamaParse (async poll) → injects markdown → completions
    Writeln(Conn.AddMessageAndRun('Summarize this document', 'user', [Media]));
  finally
    Conn.PdfTool := nil;
    Conn.Free; Media.Free; LlamaParse.Free;
  end;
end;

Demos

Open Demos/ChatToolsDemos.groupproj in Delphi IDE to access all 58 demo projects.

Each service has two demos:

• 01-DirectCall — standalone usage without TAiChatConnection
• 02-ChatTools — full bridge integration with TAiChatConnection + gap analysis

Adding a New Tool

1. Create Source/<category>/uMakerAi.ChatTools.<Service>.pas

2. Inherit from the correct base class:

   	Interface	Base Class

   | IAiWebSearchTool | TAiWebSearchToolBase | ExecuteSearch | | IAiSpeechTool | TAiSpeechToolBase | ExecuteTranscription, ExecuteSpeechGeneration | | IAiVisionTool | TAiVisionToolBase | ExecuteImageDescription | | IAiImageTool | TAiImageToolBase | ExecuteImageGeneration | | IAiVideoTool | TAiVideoToolBase | ExecuteVideoGeneration | | IAiPdfTool | TAiPdfToolBase | ExecutePdfAnalysis |

3. Use ReportState, ReportDataEnd, ReportError for lifecycle callbacks.

4. Add the unit to Source/Packages/uMakerAi.ChatTools.dpk.

5. Create Demos/<Service>/01-DirectCall/ and 02-ChatTools/ demo projects.

Environment Variables Summary

All tools support the @VAR_NAME convention: set ApiKey := '@TAVILY_API_KEY' and the value is resolved via GetEnvironmentVariable at runtime.

Note: TAiNativePdfTool does not require an API key for text extraction (100% local via Delphi PDF library). It optionally uses a VisionChat (with its own API key) only for scanned/image pages. Set @CLAUDE_API_KEY, @OPENAI_API_KEY etc. only if you assign a VisionChat for page vision analysis.

License

MIT License — Copyright (c) 2026 Gustavo Enríquez - CimaMaker

Links

• MakerAI (core framework): https://github.com/gustavoeenriquez/MakerAi
• Official website: https://makerai.cimamaker.com