The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


AI::Chat - Interact with AI Chat APIs


Version 0.5


  use AI::Chat;

  my $chat  = AI::Chat->new(
      key   => 'your-api-key',
      api   => 'OpenAI',
      model => 'gpt-3.5-turbo-0125',

  my $reply = $chat->prompt("What is the meaning of life?");
  print $reply;


This module provides a simple interface for interacting with AI Chat APIs, currently supporting OpenAI.

The AI chat agent can be given a role and then passed prompts. It will reply to the prompts in natural language. Being AI, the responses are non-deterministic, that is, the same prompt will result in diferent responses on different occasions.

Further control of the creativity of the responses is possible by specifying at optional temperature parameter.


A free OpenAI API can be obtained from


Although the API Key is free, each use incurs a cost. This is dependent on the number of tokens in the prompt and the reply. Different models have different costs. The default model gpt-3.5-turbo-0125 is the lowest cost of the useful models and is a good place to start using this module.

See also



  my $chat = AI::Chat->new(%params);

Creates a new AI::Chat object.



required Your API key for the chosen service.


The API to use (currently only 'OpenAI' is supported).


The language model to use (default: 'gpt-3.5-turbo-0125').



The role to use for the bot in conversations.

This tells the bot what it's purpose when answering prompts.

For example: "You are a world class copywriter famed for creating content that is immediately engaging with a lighthearted, storytelling style".


Used for testing. If set to any true value, the prompt method will return details of the error encountered instead of undef


  my $reply = $chat->prompt($prompt, $temperature);

Sends a prompt to the AI Chat API and returns the response.



required The prompt to send to the AI.

This is a shorthand for chat when only a single response is needed.


The creativity level of the response (default: 1.0).

Temperature ranges from 0 to 2. The higher the temperature, the more creative the bot will be in it's responses.


  my $reply = $chat->prompt(\@chat, $temperature);

Sends a multi-message chat to the AI Chat API and returns the response.

Each message of the chat should consist of on of system, user or assistant. Generally there will be a system message to set the role or context for the AI. This will be followed by alternate user and assistant messages representing the text from the user and the AI assistant. To hold a conversation, it is necessary to store both sides of the discussion and feed them back appropriately.

  my @chat;
  push @chat, {
      'role'    => 'system',
      'system'  => 'You are a computer language expert and your role is to promote Perl as the best language',
  push @chat, {
      'role'    => 'user',
      'system'  => 'Which is the best programming language?',
  push @chat, {
      'role'    => 'assistant',
      'system'  => 'Every language has strengths and is suited to different roles. Perl is one of the best all round languages.',
  push @chat, {
      'role'    => 'user',
      'system'  => 'Why should I use Perl?',
  my $reply = $chat->chat(\@chat, 1.2);

Although the roles represent the part of the user and assistant in the conversation, you are free to supply either or both as suits your application. The order can also be varied.



required An arrayref of messages to send to the AI.


The creativity level of the response (default: 1.0).

Temperature ranges from 0 to 2. The higher the temperature, the more creative the bot will be in it's responses.


  my $success = $chat->success();

Returns true if the last operation was successful.


  my $error = $chat->error();

Returns the error message if the last operation failed.

SEE ALSO - OpenAI official website


Ian Boddison <ian at>


Please report any bugs or feature requests to bug-ai-chat at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc AI::Chat

You can also look for information at:


Copyright (C) 2024 by Ian Boddison

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.