Files
ANSLibs/chilkat/include/CkAi.h

752 lines
28 KiB
C++
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// CkAi.h: interface for the CkAi class.
//
//////////////////////////////////////////////////////////////////////
// This header is generated for Chilkat 11.3.0
#define _CkVersion 11.3.0
#ifndef _CkAi_H
#define _CkAi_H
#include "chilkatDefs.h"
#include "CkString.h"
#include "CkClassWithCallbacks.h"
class CkTask;
class CkJsonObject;
class CkStringTable;
class CkStringBuilder;
class CkBinData;
class CkSocket;
class CkBaseProgress;
#if !defined(__sun__) && !defined(__sun)
#pragma pack (push, 8)
#endif
#undef Copy
// CLASS: CkAi
class CK_VISIBLE_PUBLIC CkAi : public CkClassWithCallbacks
{
private:
// Don't allow assignment or copying these objects.
CkAi(const CkAi &);
CkAi &operator=(const CkAi &);
public:
CkAi(void);
virtual ~CkAi(void);
static CkAi *createNew(void);
static CkAi *createNew2(int progLang);
void CK_VISIBLE_PRIVATE inject(void *impl);
// May be called when finished with the object to free/dispose of any
// internal resources held by the object.
void dispose(void);
CkBaseProgress *get_EventCallbackObject(void) const;
void put_EventCallbackObject(CkBaseProgress *progress);
// BEGIN PUBLIC INTERFACE
// ----------------------
// Properties
// ----------------------
// This is the API key used for authentication. Use your API key that matches your
// Provider .
//
// Suggestion: Use Chilkat's Secrets class to store and retrieve API keys in any of
// the following locations.
// * Windows Credentials Manager
// * Apple Keychain
// * AWS Secrets Manager
// * Azure Key Vault
// * IBM Cloud Secrets Manager
// * Oracle Cloud Secrets
// * Doppler Secrets
//
//
// References:
// 1: #Provider
void get_ApiKey(CkString &str);
// This is the API key used for authentication. Use your API key that matches your
// Provider .
//
// Suggestion: Use Chilkat's Secrets class to store and retrieve API keys in any of
// the following locations.
// * Windows Credentials Manager
// * Apple Keychain
// * AWS Secrets Manager
// * Azure Key Vault
// * IBM Cloud Secrets Manager
// * Oracle Cloud Secrets
// * Doppler Secrets
//
//
// References:
// 1: #Provider
const char *apiKey(void);
// This is the API key used for authentication. Use your API key that matches your
// Provider .
//
// Suggestion: Use Chilkat's Secrets class to store and retrieve API keys in any of
// the following locations.
// * Windows Credentials Manager
// * Apple Keychain
// * AWS Secrets Manager
// * Azure Key Vault
// * IBM Cloud Secrets Manager
// * Oracle Cloud Secrets
// * Doppler Secrets
//
//
// References:
// 1: #Provider
void put_ApiKey(const char *newVal);
// For custom Provider 's, use this field name for the API key in the HTTP header,
// but only if the API key is to be placed in a custom header field. If the API key
// is to be provided in an "Authorization: Bearer" header, then leave this property
// empty.
//
// The default value of this property is the empty string.
//
//
// References:
// 1: #Provider
void get_ApiKeyHeader(CkString &str);
// For custom Provider 's, use this field name for the API key in the HTTP header,
// but only if the API key is to be placed in a custom header field. If the API key
// is to be provided in an "Authorization: Bearer" header, then leave this property
// empty.
//
// The default value of this property is the empty string.
//
//
// References:
// 1: #Provider
const char *apiKeyHeader(void);
// For custom Provider 's, use this field name for the API key in the HTTP header,
// but only if the API key is to be placed in a custom header field. If the API key
// is to be provided in an "Authorization: Bearer" header, then leave this property
// empty.
//
// The default value of this property is the empty string.
//
//
// References:
// 1: #Provider
void put_ApiKeyHeader(const char *newVal);
// Specifies the API specification to be used. Possible choices are ChatCompletions
// , Responses , Gemini , Anthropic . The default value is Responses because the
// default value of the Provider property is openai . Setting the Provider property
// to a value other than custom will also automatically set this property to the
// correct and needed value.
//
// References:
// 1: #Provider
void get_ApiSpec(CkString &str);
// Specifies the API specification to be used. Possible choices are ChatCompletions
// , Responses , Gemini , Anthropic . The default value is Responses because the
// default value of the Provider property is openai . Setting the Provider property
// to a value other than custom will also automatically set this property to the
// correct and needed value.
//
// References:
// 1: #Provider
const char *apiSpec(void);
// Specifies the API specification to be used. Possible choices are ChatCompletions
// , Responses , Gemini , Anthropic . The default value is Responses because the
// default value of the Provider property is openai . Setting the Provider property
// to a value other than custom will also automatically set this property to the
// correct and needed value.
//
// References:
// 1: #Provider
void put_ApiSpec(const char *newVal);
// Specifies the provider's base URL. For example, http://localhost:11434/v1 or
// https://api.together.xyz/v1 . The default value is https://api.openai.com/v1
// because the default value of the Provider property is openai . Setting the
// Provider property to a value other than custom will also automatically set this
// property to the correct and needed value.
//
// References:
// 1: #Provider
void get_BaseUrl(CkString &str);
// Specifies the provider's base URL. For example, http://localhost:11434/v1 or
// https://api.together.xyz/v1 . The default value is https://api.openai.com/v1
// because the default value of the Provider property is openai . Setting the
// Provider property to a value other than custom will also automatically set this
// property to the correct and needed value.
//
// References:
// 1: #Provider
const char *baseUrl(void);
// Specifies the provider's base URL. For example, http://localhost:11434/v1 or
// https://api.together.xyz/v1 . The default value is https://api.openai.com/v1
// because the default value of the Provider property is openai . Setting the
// Provider property to a value other than custom will also automatically set this
// property to the correct and needed value.
//
// References:
// 1: #Provider
void put_BaseUrl(const char *newVal);
// For multimodal inputs like image data, image URLs, file data, and file URLs, the
// full data or URL is sent initially. If the property is set to true, the full
// data/URL is re-sent in subsequent interactions. If set to false, only the
// image or file summary is sent thereafter.
//
// By default, this property is false.
//
// Full transcript style: always send the entire conversation (including
// files/images). This guarantees the model has all context, but can get expensive.
//
// Summarized transcript style: for previously sent multimodal items, sends the
// summary message (e.g. “Earlier, I uploaded a PDF with account statements”)
// instead of the raw file or url itself.
//
bool get_FullTranscript(void);
// For multimodal inputs like image data, image URLs, file data, and file URLs, the
// full data or URL is sent initially. If the property is set to true, the full
// data/URL is re-sent in subsequent interactions. If set to false, only the
// image or file summary is sent thereafter.
//
// By default, this property is false.
//
// Full transcript style: always send the entire conversation (including
// files/images). This guarantees the model has all context, but can get expensive.
//
// Summarized transcript style: for previously sent multimodal items, sends the
// summary message (e.g. “Earlier, I uploaded a PDF with account statements”)
// instead of the raw file or url itself.
//
void put_FullTranscript(bool newVal);
// The interval in milliseconds between each AbortCheck event callback, which
// enables an application to abort certain method calls before they complete. By
// default, HeartbeatMs is set to 0 , meaning no AbortCheck event callbacks will
// trigger.
//
// References:
// 1: #AbortCheck
int get_HeartbeatMs(void);
// The interval in milliseconds between each AbortCheck event callback, which
// enables an application to abort certain method calls before they complete. By
// default, HeartbeatMs is set to 0 , meaning no AbortCheck event callbacks will
// trigger.
//
// References:
// 1: #AbortCheck
void put_HeartbeatMs(int newVal);
// This applies to providers like OpenAI that can maintain conversation state on
// the server. If set to true, only the conversation ID is sent with each query.
// If set to false, the entire conversation transcript is sent with each query,
// making each query stateless.
//
// This only applies if a conversation is selected.
//
// The default value of this property is false.
//
bool get_HostedConvo(void);
// This applies to providers like OpenAI that can maintain conversation state on
// the server. If set to true, only the conversation ID is sent with each query.
// If set to false, the entire conversation transcript is sent with each query,
// making each query stateless.
//
// This only applies if a conversation is selected.
//
// The default value of this property is false.
//
void put_HostedConvo(bool newVal);
// The maximum amount of time to wait for additional incoming data when receiving a
// response. The default value is 90000 (90 seconds). This is not a total timeout,
// but the maximum time allowed when data transmission has paused.
int get_IdleTimeoutMs(void);
// The maximum amount of time to wait for additional incoming data when receiving a
// response. The default value is 90000 (90 seconds). This is not a total timeout,
// but the maximum time allowed when data transmission has paused.
void put_IdleTimeoutMs(int newVal);
// The model to be used for AI conversations. For example, GPT-4o or GPT-5 . The
// list of available models can be obtained by calling GetModels .
//
// The default value is the empty string. A model must always be specified. Chilkat
// won't try to guess or default to a model.
//
//
// References:
// 1: #GetModels
void get_Model(CkString &str);
// The model to be used for AI conversations. For example, GPT-4o or GPT-5 . The
// list of available models can be obtained by calling GetModels .
//
// The default value is the empty string. A model must always be specified. Chilkat
// won't try to guess or default to a model.
//
//
// References:
// 1: #GetModels
const char *model(void);
// The model to be used for AI conversations. For example, GPT-4o or GPT-5 . The
// list of available models can be obtained by calling GetModels .
//
// The default value is the empty string. A model must always be specified. Chilkat
// won't try to guess or default to a model.
//
//
// References:
// 1: #GetModels
void put_Model(const char *newVal);
// This is the AI provider. Possible values are: openai , google , claude ,
// deepseek , perplexity , and xai .
//
// Starting in Chilkat v11.3.0 , this property can be set to custom , and the
// BaseUrl and ApiSpec properties can also be set to fully specify the provider.
//
// The default value is openai .
//
//
// References:
// 1: #BaseUrl
// 2: #ApiSpec
void get_Provider(CkString &str);
// This is the AI provider. Possible values are: openai , google , claude ,
// deepseek , perplexity , and xai .
//
// Starting in Chilkat v11.3.0 , this property can be set to custom , and the
// BaseUrl and ApiSpec properties can also be set to fully specify the provider.
//
// The default value is openai .
//
//
// References:
// 1: #BaseUrl
// 2: #ApiSpec
const char *provider(void);
// This is the AI provider. Possible values are: openai , google , claude ,
// deepseek , perplexity , and xai .
//
// Starting in Chilkat v11.3.0 , this property can be set to custom , and the
// BaseUrl and ApiSpec properties can also be set to fully specify the provider.
//
// The default value is openai .
//
//
// References:
// 1: #BaseUrl
// 2: #ApiSpec
void put_Provider(const char *newVal);
// The HTTP response status code for the last Ask is as follows:
// * 0 indicates an error occurred before receiving an HTTP response.
// * 200 indicates a successful response.
// * A failed response has a status code of 400 or higher.
//
// References:
// 1: #Ask
int get_ResponseStatusCode(void);
// The currently selected conversation can be set to your desired conversation
// name. Once set, all future queries will be part of that conversation, updating
// its state with each input and output. By default, no conversation is selected,
// indicated by an empty string, leading to stateless queries. The first
// conversation created or imported will be automatically selected. If you attempt
// to select a non-existent conversation, the selection will not change. You can
// reset this property to an empty string to revert to stateless querying.
void get_SelectedConvo(CkString &str);
// The currently selected conversation can be set to your desired conversation
// name. Once set, all future queries will be part of that conversation, updating
// its state with each input and output. By default, no conversation is selected,
// indicated by an empty string, leading to stateless queries. The first
// conversation created or imported will be automatically selected. If you attempt
// to select a non-existent conversation, the selection will not change. You can
// reset this property to an empty string to revert to stateless querying.
const char *selectedConvo(void);
// The currently selected conversation can be set to your desired conversation
// name. Once set, all future queries will be part of that conversation, updating
// its state with each input and output. By default, no conversation is selected,
// indicated by an empty string, leading to stateless queries. The first
// conversation created or imported will be automatically selected. If you attempt
// to select a non-existent conversation, the selection will not change. You can
// reset this property to an empty string to revert to stateless querying.
void put_SelectedConvo(const char *newVal);
// When set to true, the Ask method operates in streaming mode, returning
// immediately after the request is sent. You can then use the PollAi and
// NextAiEvent methods to receive streaming events. By default, this property is
// false.
//
// References:
// 1: #Ask
bool get_Streaming(void);
// When set to true, the Ask method operates in streaming mode, returning
// immediately after the request is sent. You can then use the PollAi and
// NextAiEvent methods to receive streaming events. By default, this property is
// false.
//
// References:
// 1: #Ask
void put_Streaming(bool newVal);
// This is a catch-all property to be used for uncommon needs. This property
// defaults to the empty string, and should typically remain empty.
void get_UncommonOptions(CkString &str);
// This is a catch-all property to be used for uncommon needs. This property
// defaults to the empty string, and should typically remain empty.
const char *uncommonOptions(void);
// This is a catch-all property to be used for uncommon needs. This property
// defaults to the empty string, and should typically remain empty.
void put_UncommonOptions(const char *newVal);
// ----------------------
// Methods
// ----------------------
// Sends the current potentially multimodal input within the context of the
// selected conversation and receives the model's output. Currently, the desired
// outputType can only be text . Future versions of Chilkat will support image , audio ,
// or a JSON schema to tell the model to return data in the specified JSON
// structured output.
//
// Accumulated outputs are cleared on entry to this method. Accumulated inputs are
// cleared on the successful return of this method.
//
// This method cannot be called while a streaming Ask is in progress. In such a
// case the return value is false and nothing will occur.
//
bool Ask(const char *outputType);
// Sends the current potentially multimodal input within the context of the
// selected conversation and receives the model's output. Currently, the desired
// outputType can only be text . Future versions of Chilkat will support image , audio ,
// or a JSON schema to tell the model to return data in the specified JSON
// structured output.
//
// Accumulated outputs are cleared on entry to this method. Accumulated inputs are
// cleared on the successful return of this method.
//
// This method cannot be called while a streaming Ask is in progress. In such a
// case the return value is false and nothing will occur.
//
CkTask *AskAsync(const char *outputType);
// Deletes the conversation by its name. If name equals * then all conversations
// are deleted.
bool DeleteConvo(const char *name);
// Exports the conversation specified by name to json, replacing json's contents
// with the exported transcript. You can later import a conversation using
// ImportConvo . The currently selected conversation can be exported by passing *
// for the name.
//
// References:
// 1: #ImportConvo
bool ExportConvo(const char *name, CkJsonObject &json);
// Provides details about the last method called on this object instance. While
// many methods do not generate information, some allow you to retrieve details by
// accessing the last JSON data immediately after the method call returns.
//
// Methods that produce last JSON information include: GetModels .
//
//
// References:
// 1: #GetModels
void GetLastJsonData(CkJsonObject &json);
// Returns a list of models available to your account, such as GPT-4o and GPT-5 .
// The models are listed in st, sorted in ascending, case-insensitive order. To
// access the raw JSON response after calling this method, use GetLastJsonData .
//
// References:
// 1: #GetLastJsonData
bool GetModels(CkStringTable &st);
// Returns a list of models available to your account, such as GPT-4o and GPT-5 .
// The models are listed in st, sorted in ascending, case-insensitive order. To
// access the raw JSON response after calling this method, use GetLastJsonData .
//
// References:
// 1: #GetLastJsonData
CkTask *GetModelsAsync(CkStringTable &st);
// Returns the text output from the last call to Ask .
//
// References:
// 1: #Ask
bool GetOutputText(CkString &outStr);
// Returns the text output from the last call to Ask .
//
// References:
// 1: #Ask
const char *getOutputText(void);
// Returns the text output from the last call to Ask .
//
// References:
// 1: #Ask
const char *outputText(void);
// Returns the text output, appended to sb, from the last call to Ask .
//
// References:
// 1: #Ask
bool GetOutputTextSb(CkStringBuilder &sb);
// Imports the conversation from json and assigns it the name in name.
bool ImportConvo(const char *name, CkJsonObject &json);
// Adds file data, such as a PDF, to the potentially multimodal input that will be
// sent in the next call to Ask . The bd contains the file data.
//
// If FullTranscript is _CKFALSE_, summary is sent in subsequent interactions instead
// of the file data. If FullTranscript is true, summary is not sent, and the file
// data is re-sent in each interaction.
//
// This method cannot be used with DeepSeek .
//
//
// References:
// 1: #Ask
// 2: #FullTranscript
bool InputAddFileData(const char *filename, CkBinData &bd, const char *summary);
// Adds a file located at a url to the potentially multimodal input that will be
// sent in the next call to Ask .
//
// If FullTranscript is _CKFALSE_, summary is sent in subsequent interactions instead
// of the file URL. If FullTranscript is true, summary is not sent, and the file URL
// is re-sent in each interaction.
//
// This method cannot be used with DeepSeek .
//
//
// References:
// 1: #Ask
// 2: #FullTranscript
bool InputAddFileUrl(const char *url, const char *summary);
// Adds an image to the potentially multimodal input that will be sent in the next
// call to Ask . The bd contains the images data. The image data must be jpeg,
// png, or webp format.
//
// If FullTranscript is _CKFALSE_, summary is sent in subsequent interactions instead
// of the image data. If FullTranscript is true, summary is not sent, and the image
// data is re-sent in each interaction.
//
// This method cannot be used with DeepSeek . DeepSeek does not appear to expose an
// OpenAI-compatible vision model (yet). You cannot send image URLs or image data
// to DeepSeek.
//
//
// References:
// 1: #Ask
// 2: #FullTranscript
bool InputAddImageData(CkBinData &bd, const char *summary);
// Adds an image located at a url to the potentially multimodal input that will be
// sent in the next call to Ask .
//
// If FullTranscript is _CKFALSE_, summary is sent in subsequent interactions instead
// of the image URL. If FullTranscript is true, summary is not sent, and the image
// URL is re-sent in each interaction.
//
// This method cannot be used with DeepSeek . DeepSeek does not appear to expose an
// OpenAI-compatible vision model (yet). You cannot send image URLs or image data
// to DeepSeek.
//
//
// References:
// 1: #Ask
// 2: #FullTranscript
bool InputAddImageUrl(const char *url, const char *summary);
// Adds text to the potentially multimodal input that will be sent in the next call
// to Ask .
//
// References:
// 1: #Ask
bool InputAddText(const char *text);
// Adds text to the potentially multimodal input that will be sent in the next call
// to Ask .
//
// References:
// 1: #Ask
bool InputAddTextSb(CkStringBuilder &sb);
// Clears the inputs to be sent in the next call to Ask .
//
// References:
// 1: #Ask
void InputClear(void);
// Returns the full list of conversation names in st.
bool ListConvos(CkStringTable &st);
// Creates and initializes a transcript for a new conversation. The name is a
// unique name for the conversation. You can reference the conversation by this
// name, such as for the ExportConvo method.
//
// The sysMsg sets the broad behavior, tone, and role of the assistant. Example: "You
// are a polite tutor who explains concepts clearly and simply." Think of it as the
// high-level persona or instructions the model follows throughout the
// conversation. The devMsg provides more technical or policy-level guidance.
// Example: "Always respond in Markdown. Do not reveal internal reasoning. Keep
// answers under 200 words." Its like hidden scaffolding to enforce app rules,
// formatting, or safety constraints.
//
// Note: The first conversation created is automatically set as the SelectedConvo .
// You can use any unique name for a conversation except * .
//
//
// References:
// 1: #ExportConvo
// 2: #SelectedConvo
bool NewConvo(const char *name, const char *sysMsg, const char *devMsg);
// Retrieves the next available AI streaming mode response update. Use the PollAi
// method to check if a response update is immediately accessible. The event name
// is returned in sbName. If the event name is delta , the text is returned in sbDelta.
//
// For the complete raw event JSON, use the GetLastJsonData function. Note that the
// raw JSON format varies by AI provider.
//
// Each AI provider (e.g., OpenAI, Claude, xAI) sends a unique set of events. Some
// of these events mark the start and end of sections and content parts, while
// others do not. Chilkat standardizes these events and returns the following event
// types.
// * response_created — The server acknowledges the request and has created a
// response object. Nothing has been streamed yet — its just the signal that the
// response pipeline is open.
// * empty — Some AI providers send empty heartbeat / keep-alive updates to
// ensure the stream stays open and proxies don't time out.
// * output_item_added — A new output item has been added to the response. An
// “output item” is a top-level container — could be text, tool call, or other
// structured content.
// * content_part_added — Within the output item, the model starts a new
// content part. A content part is typically a segment of a specific type (e.g.,
// text, JSON snippet, or image reference).
// * delta — These are the incremental text tokens being streamed. Each delta
// contains the next piece of text (like characters or words). Youll see many of
// these in sequence while the model is generating.
// * output_text_done — Marks the end of the text streaming for that content
// part. No more deltas will arrive for this part.
// * content_part_done — Closes the current content part. Tells you the model
// is finished with that segment (e.g., done streaming a paragraph).
// * output_item_done — Closes the current output item entirely. Means that
// item is fully complete (all its parts are done).
// * response_completed — The entire response object is finished. No more items
// will be added, and the stream will soon close.
// * null_terminator — The stream is closed. All streaming responses end with a
// single null_terminator.
//
// maxWaitMs defines the maximum wait time to receive the complete event. For instance,
// if PollAi signals an available streaming update but only part of the event JSON
// has been received, the rest is probably on its way. In such cases, this method
// must wait to receive the entire JSON.
//
//
// References:
// 1: #PollAi
// 2: #GetLastJsonData
bool NextAiEvent(int maxWaitMs, CkStringBuilder &sbName, CkStringBuilder &sbDelta);
// Returns immediately with one of the following values:
//
// -1 - Error
// 0 - No streaming event updates are available.
// 1 - A streaming event updates is ready for retrieval via NextAiEvent
// 2 - The streaming AI response has already completed, or no streaming response is
// ongoing.
//
// If abort is true, then the streaming response is aborted and this method
// returns the value 2 . Applications should pass in false for abort to continue
// streaming.
//
//
// References:
// 1: #NextAiEvent
int PollAi(bool abort);
// Sets additional Ask params such as temperature , effort , and max_output_tokens
// .
//
// References:
// 1: #Ask
bool SetAskParams(CkJsonObject &json);
// This method copies connection settings, including HTTP proxy, SOCKS proxy,
// network interface IP address, and other related settings from sock. It's
// optional; if not used, default settings apply. Call this method before sending
// REST API requests to an AI provider.
bool SetConnectionSettings(CkSocket &sock);
// Sets additional provider params needed for some pre-defined providers. As of
// this current version, the possible params are:
// 1. azure.clientId , a GUID/UUID such as 17280f2d-f709-4a7b-af1d-9928190e13cf
// 2. azure.clientSecret , such as UZc8Q~YBrRIgfe_zbAOwWV.8ikuHa3JJF7LvCdt.
// 3. azure.tenantId , a GUID/UUID such as aa4b5625-a31f-44dd-94ec-e2f6c0c64d2c
// 4. azure.location , such as eastus
// 5. azure.subscription , a GUID/UUID such as
// 4abd4bf6-5260-4795-90f6-1e91ce4f582c
bool SetProviderParams(CkJsonObject &json);
// This method is provided for convenience. It causes the calling thread to sleep
// for a number of milliseconds.
void SleepMs(int millisec);
// END PUBLIC INTERFACE
};
#if !defined(__sun__) && !defined(__sun)
#pragma pack (pop)
#endif
#endif