LLMClient Class

Properties   Methods   Events   Config Settings   Errors  

Provides a single, provider-neutral way to generate replies with, call tools through, create embeddings with, count tokens for, and list models of the OpenAI, Anthropic, and Google Gemini APIs, and of the many services that implement one of them.

Syntax

ipworksllm.LLMClient

Remarks

The LLMClient class provides one API for the OpenAI Chat Completions API, the Anthropic Messages API, and the Google Gemini API. The conversation, the tools, and the reply are held in a normalized form; the class translates them into the request of the selected provider and translates the provider's reply back, so the same application code works with every provider.

Selecting a Provider

The ServiceProvider property selects the provider: spOpenAI (0) (the default), spAnthropic (1), or spGemini (2); one of the services that implement the OpenAI Chat Completions API, spOllama (3), spLMStudio (4), spGroq (5), spOpenRouter (6), spTogetherAI (7), or spFireworksAI (8); or a custom endpoint of one of the three APIs, spCustomGemini (97), spCustomAnthropic (98), or spCustomOpenAI (99). The APIKey property holds the API key issued by that provider, and Model names the model that processes each request.

LLMClient llmclient = new LLMClient(); llmclient.ServiceProvider = LLMClientServiceProviders.spAnthropic; llmclient.APIKey = "sk-ant-..."; llmclient.Model = "claude-sonnet-5"; llmclient.MaxOutputTokens = 1024; // Required by the Anthropic API.

Selecting an Endpoint

When ServerURL is empty (the default), the class uses the default endpoint of the selected provider, such as https://api.openai.com/v1 for spOpenAI or http://localhost:11434/v1 for spOllama; ServerURL lists them all. In most cases, the default endpoint is the correct choice. The ServerURL property should only be set when connecting to a custom endpoint, to an Ollama or LM Studio server on another host or port, or through a gateway or proxy that implements the selected provider's API. When ServerURL is set, operation paths such as /chat/completions or /messages are appended to its value verbatim; no part of the value is rewritten, and no version segment is added or removed.

Any other service that implements one of the three APIs, such as vLLM or DeepSeek, is used by selecting the matching custom value and setting ServerURL to the base URL of that service; the custom values have no default endpoint. When APIKey is left empty, no authentication header is sent at all, as a locally hosted server expects.

// A locally hosted Ollama server, at its default address. No API key is required. llmclient.ServiceProvider = LLMClientServiceProviders.spOllama; llmclient.Model = "llama3.2"; // A vLLM server on another machine. llmclient.ServiceProvider = LLMClientServiceProviders.spCustomOpenAI; llmclient.ServerURL = "http://192.168.1.20:8000/v1"; llmclient.Model = "meta-llama/Llama-3.1-8B-Instruct";

Building a Conversation

A conversation is held in two collections. Each message is one LLMMessage item in the Messages collection, carrying the message's Id and Role (user, assistant, or tool). The content of the messages is held in the MessageParts collection, in which each LLMMessagePart item is one piece of content, such as text, an image, a file, or a tool call. The MessageId field of a part holds the Id of the message it belongs to.

The AddMessage method appends a message, adds a text part to it when Content is not empty, and returns the new message's Id. The AddMessagePart method adds further parts to that message, such as an image or a file given by URL. To send the bytes of an image or file inline, add the part with an empty Content and set the part's Data field. Instructions that apply to the whole conversation are supplied through SystemPrompt rather than as a message.

llmclient.SystemPrompt = "You are a concise assistant."; string id = llmclient.AddMessage("user", "What is in these pictures?"); // An image given by URL. llmclient.AddMessagePart(id, (int)PartTypes.ptImage, "https://www.example.com/photo.jpg", "image/jpeg"); // An image sent inline. llmclient.AddMessagePart(id, (int)PartTypes.ptImage, "", "image/png"); llmclient.MessageParts[llmclient.MessageParts.Count - 1].DataB = File.ReadAllBytes("chart.png");

Calling Reset clears the conversation, the tools, and the reply, while configuration such as ServiceProvider, APIKey, and Model is kept.

Generating a Reply

The Generate method sends the conversation to the selected provider. On success, the reply is appended to Messages as a message with role assistant, and its parts are appended to MessageParts. ResponseText holds the text of the reply, FinishReason reports why the model stopped, and InputTokens, OutputTokens, and TotalTokens report the token usage the provider counted.

llmclient.AddMessage("user", "What is the capital of France?"); llmclient.Generate(); Console.WriteLine(llmclient.ResponseText); Console.WriteLine("Tokens used: " + llmclient.TotalTokens);

Streaming

Setting Stream to True before calling Generate causes the reply to be streamed. The ContentDelta event fires once for each fragment as it arrives; its PartType parameter is 0 (ptText) for visible text and 5 (ptReasoning) for the model's reasoning. Once the stream completes, the assembled reply is appended exactly as in the non-streaming case.

llmclient.Stream = true; llmclient.OnContentDelta += (s, e) => { if (e.PartType == (int)PartTypes.ptText) Console.Write(e.Delta); }; llmclient.AddMessage("user", "Write a short poem about the sea."); llmclient.Generate();

Tool Calling

A tool is declared by queuing its parameters with AddToolParam and then calling AddTool, or by passing a complete JSON Schema to AddTool. When the reply calls one or more tools, the reply is appended first, and then the ToolCall event fires once for each call. Answer each call with AddToolResult, passing the call's Id, and then call Generate again so the model can use the results. While the model is calling tools, FinishReason reports frToolCalls.

llmclient.AddToolParam("location", "string", "The city and state, e.g. San Francisco, CA", true); llmclient.AddTool("get_weather", "Gets the current weather for a location.", ""); llmclient.OnToolCall += (s, e) => { llmclient.AddToolResult(e.Id, GetWeather(e.ArgumentsJson), false); }; llmclient.AddMessage("user", "What is the weather like in Boston?"); llmclient.Generate(); // Send the tool results back until the model gives its final answer. while (llmclient.FinishReason == LLMClientFinishReasons.frToolCalls) llmclient.Generate(); Console.WriteLine(llmclient.ResponseText);

Provider Differences

The class hides the differences between the providers wherever the provider APIs allow it. Where this documentation describes spOpenAI, spAnthropic, or spGemini, the same applies to every other provider that uses the same API, unless stated otherwise. The differences that remain are:

• The Anthropic API requires a limit on the length of the reply, so MaxOutputTokens must be set to a positive value when ServiceProvider is spAnthropic or spCustomAnthropic; otherwise Generate fails with error 802.
• The OpenAI Chat Completions API has no token counting endpoint, so CountTokens fails with error 804 when ServiceProvider is spOpenAI or any other provider that uses that API.
• Services that implement the OpenAI Chat Completions API name the limit on the length of the reply differently; MaxOutputTokens lists the field each provider receives.
• Ollama does not support choosing tools, so the ToolChoice configuration setting must be empty or auto when ServiceProvider is spOllama.
• The Anthropic API cannot request JSON output without a schema, so setting the ResponseFormat configuration setting to json without also setting ResponseSchema causes Generate to fail with error 804 when ServiceProvider is spAnthropic.
• Changing ServiceProvider keeps the conversation and the tools, so a conversation may be continued with another provider. The ProviderData field of every part is cleared, however, because provider specific data, such as the signature of an Anthropic thinking block, cannot be sent to a different provider.
• Message roles other than user, assistant, and tool, such as developer, are passed through with spOpenAI only; with spAnthropic or spGemini, Generate fails with error 804.
• The Anthropic API offers no embeddings, so CreateEmbedding fails with error 804 when ServiceProvider is spAnthropic or spCustomAnthropic.
• A few configuration settings apply to one API only: AnthropicVersion, GeminiSafetySettings, OpenAIOrganization, OpenAIProject, and EmbeddingTaskType, which is supported only with the Gemini API.

A reply that the provider blocks for safety reasons is not an error: Generate returns normally and FinishReason reports frContentFilter. The provider's own finish reason is always available through the ProviderFinishReason configuration setting.

Creating Embeddings

An embedding is a vector of floating point numbers that represents the meaning of a piece of text: texts with similar meanings have vectors that point in similar directions, which makes embeddings the basis of semantic search, clustering, and classification. The CreateEmbedding method creates an embedding for every item of the Embeddings collection in a single request, and sets the OutputVector field of each item to the vector created for its InputText, as JSON text containing an array of floating point numbers.

Embeddings are created with a model dedicated to them, which the EmbeddingModel configuration setting selects without disturbing Model. Providers that use the OpenAI or the Gemini API are supported when the service offers embeddings; the Anthropic API offers none.

llmclient.Config("EmbeddingModel=text-embedding-3-small"); llmclient.Embeddings.Add(new LLMEmbedding("The quick brown fox jumps over the lazy dog.")); llmclient.Embeddings.Add(new LLMEmbedding("A fast auburn fox leaps over a sleepy hound.")); llmclient.CreateEmbedding(); foreach (LLMEmbedding embedding in llmclient.Embeddings) { Console.WriteLine(embedding.OutputVector); }

To compare two texts, parse both vectors and compute their cosine similarity: the dot product of the vectors divided by the product of their lengths. Values near 1 mean the texts are close in meaning. Vectors are only comparable when the same model, with the same EmbeddingDimensions, created them.

Counting Tokens and Listing Models

With spAnthropic and spGemini, the CountTokens method returns the number of input tokens the current conversation would consume, without generating a reply.

int inputTokens = llmclient.CountTokens();

The ListModels method fires the ModelList event once for each model the provider reports. The Anthropic and Gemini APIs return the list in pages: when more pages remain, ModelMarker is set, and calling ListModels again returns the next page. The OpenAI list is not paged, so ModelMarker stays empty with spOpenAI.

llmclient.OnModelList += (s, e) => { Console.WriteLine(e.Id + " (" + e.Name + ")"); }; do { llmclient.ListModels(); } while (llmclient.ModelMarker != "");

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

APIKey Property (LLMClient Class)

The API key used to authenticate with the selected provider.

Syntax

public String getAPIKey();
public void setAPIKey(String APIKey);

Default Value

""

Remarks

This property specifies the API key used to authenticate requests to the provider selected by ServiceProvider. The header that carries it depends on the API the provider uses:

When this property is left empty, no authentication header is sent at all. This is required by some servers, such as a locally hosted Ollama, LM Studio, or vLLM instance, and supports gateways placed in front of a provider that supply credentials of their own.

An API key is issued for one provider only. When ServiceProvider is changed, this property should be set to a key issued by the newly selected provider.

This property is not available at design time.

Embeddings Property (LLMClient Class)

The texts to create embeddings for, and the vectors created for them.

Syntax

public LLMEmbeddingList getEmbeddings();

Remarks

This collection holds the LLMEmbedding items that CreateEmbedding sends to the provider. Add one item for each piece of text and set its InputText; CreateEmbedding then sends all of the texts in a single request and sets the OutputVector of each item to the embedding vector created for its text.

CreateEmbedding never adds, removes, or reorders items, so the vector created for a text is always found in the same item as the text.

llmclient.Embeddings.Add(new LLMEmbedding("The quick brown fox jumps over the lazy dog.")); llmclient.Embeddings.Add(new LLMEmbedding("A fast auburn fox leaps over a sleepy hound.")); llmclient.CreateEmbedding(); foreach (LLMEmbedding embedding in llmclient.Embeddings) { Console.WriteLine(embedding.OutputVector); }

This collection is independent of the conversation: its items are never sent by Generate or CountTokens, and CreateEmbedding leaves Messages and MessageParts unchanged. Calling Reset clears this collection.

This property is not available at design time.

FinishReason Property (LLMClient Class)

The reason the model stopped generating the last reply.

Syntax

public int getFinishReason();

Enumerated values:
  public final static int frNone = 0;
  public final static int frStop = 1;
  public final static int frLength = 2;
  public final static int frToolCalls = 3;
  public final static int frContentFilter = 4;
  public final static int frOther = 5;

Default Value

0

Remarks

This property reports why the model stopped generating the reply received by the last call to Generate. The value is normalized across providers; the provider's own value is always available, unchanged, through the ProviderFinishReason configuration setting. This property is cleared when Generate, CountTokens, CreateEmbedding, or ListModels is called.

Possible values are:

The values reported by each provider are mapped as follows:

A blocked request or reply is never reported as an error: Generate returns normally and this property reports frContentFilter. A reply that carries no content at all appends nothing to Messages. This happens, for example, when the Gemini API blocks the prompt itself; ProviderFinishReason then holds the block reason the server reported.

This property is read-only and not available at design time.

Firewall Property (LLMClient Class)

A set of properties related to firewall access.

Syntax

public Firewall getFirewall();
public void setFirewall(Firewall firewall);

Remarks

This is a Firewall-type property, which contains fields describing the firewall through which the class will attempt to connect.

InputTokens Property (LLMClient Class)

The number of input tokens the provider counted for the last request.

Syntax

public int getInputTokens();

Default Value

0

Remarks

This property reports the number of input (prompt) tokens the provider counted for the request sent by the last call to Generate or CreateEmbedding. It counts every input token of the request, which the providers report as follows:

A value of 0 means the provider did not report usage for the last request. This property is cleared when Generate, CountTokens, CreateEmbedding, or ListModels is called.

To learn how many input tokens a conversation would consume before sending it, use CountTokens, which returns the count instead of setting this property.

This property is read-only and not available at design time.

MaxOutputTokens Property (LLMClient Class)

The maximum number of tokens the model may generate in a reply.

Syntax

public int getMaxOutputTokens();
public void setMaxOutputTokens(int maxOutputTokens);

Default Value

0

Remarks

This property specifies an upper bound on the number of tokens the model may generate for a single reply. A reply that reaches the limit is cut short, and FinishReason reports frLength.

The field that carries the value depends on ServiceProvider:

When this property is left at 0 (the default), the field is omitted from the request and the provider's own default is used. The Anthropic API, however, requires this field and defines no default for it: when ServiceProvider is spAnthropic or spCustomAnthropic, this property must be set to a positive value before calling Generate, which otherwise fails with error 802.

Different models accept different upper bounds for this value. Refer to the provider's documentation for the limit that applies to the model named by Model.

This property is not available at design time.

MessageParts Property (LLMClient Class)

The content of every message in the conversation.

Syntax

public LLMMessagePartList getMessageParts();

Remarks

This collection holds the LLMMessagePart items that make up the content of the messages in Messages. Each part is one piece of content, such as text, an image, a file, a tool call, a tool result, or the model's reasoning, as given by its PartType field.

Every part belongs to exactly one message: its MessageId field holds the Id of that message. When the conversation is sent, the parts of each message are sent in the order in which they appear in this collection.

Parts are added to this collection in several ways:

• AddMessage adds a text part when its Content parameter is not empty.
• AddMessagePart adds a part of any type to an existing message, for example an image or a file.
• AddToolResult adds the result of a tool call.
• Generate adds the parts of the reply, such as its text, its reasoning, and the tool calls the model made.

To send the bytes of an image or file inline, set the part's Data field, together with MediaType. The following example adds an image read from disk to a message.

string id = llmclient.AddMessage("user", "What does this chart show?"); llmclient.AddMessagePart(id, (int)PartTypes.ptImage, "", "image/png"); llmclient.MessageParts[llmclient.MessageParts.Count - 1].DataB = File.ReadAllBytes("chart.png"); llmclient.Generate();

In the Async Edition (nsoftware.async.IPWorksLLM), the method calls are awaited:

string id = await llmclient.AddMessage("user", "What does this chart show?"); await llmclient.AddMessagePart(id, (int)PartTypes.ptImage, "", "image/png"); llmclient.MessageParts[llmclient.MessageParts.Count - 1].DataB = File.ReadAllBytes("chart.png"); await llmclient.Generate();

This property is not available at design time.

Messages Property (LLMClient Class)

The messages of the conversation sent to and returned from the model.

Syntax

public LLMMessageList getMessages();

Remarks

This collection holds the list of LLMMessage items making up the conversation. Each item holds only the message's Id and Role; the content of the message is held in the MessageParts collection, in the parts whose MessageId field matches Id.

The roles user, assistant, and tool are translated into the form each provider expects. Instructions that apply to the whole conversation are supplied through the SystemPrompt property instead of a message.

Calling Generate sends the entire conversation and appends the reply to this collection as a message with role assistant, whichever provider is selected. A reply that carries no content at all, such as one for a prompt the provider blocked, appends nothing.

The AddMessage method is a convenient way to append a new message to this collection, and a text part to MessageParts, without constructing the items directly. It returns the Id of the new message.

This property is not available at design time.

Model Property (LLMClient Class)

The model used to generate replies and count tokens.

Syntax

public String getModel();
public void setModel(String model);

Default Value

""

Remarks

This property specifies the identifier of the model that will process the request, for example gpt-4o with spOpenAI, claude-sonnet-5 with spAnthropic, or gemini-2.0-flash with spGemini. Model identifiers are specific to a provider, so this property normally changes together with ServiceProvider.

This property must be set before calling Generate or CountTokens, which otherwise fail with error 802, and before calling CreateEmbedding unless the EmbeddingModel configuration setting supplies a model of its own. The OpenAI and Anthropic APIs name the model in the request body; the Gemini API names it in the request path, as {ServerURL}/models/{Model}:{operation}. With spGemini, a value that already carries the models/ resource name prefix is accepted as well; the prefix is not duplicated in the request path.

The ListModels method may be used to discover the model identifiers the provider accepts.

This property is not available at design time.

ModelMarker Property (LLMClient Class)

A marker indicating what page of models to return next.

Syntax

public String getModelMarker();
public void setModelMarker(String modelMarker);

Default Value

""

Remarks

This property will be populated when ListModels is called if the results are paged and there are more pages. To list all models, continue to call ListModels until this property returns an empty string.

The Anthropic and Gemini APIs return the list of models in pages; the marker is sent back to them as the after_id and pageToken query parameters respectively. The OpenAI API returns every model at once, so this property is always empty when ServiceProvider is spOpenAI.

A marker is only meaningful to the provider that returned it, so changing ServiceProvider to a different value clears this property.

Refer to ListModels for more information.

This property is not available at design time.

OutputTokens Property (LLMClient Class)

The number of output tokens the provider counted for the last reply.

Syntax

public int getOutputTokens();

Default Value

0

Remarks

This property reports the number of output tokens the provider counted for the reply received by the last call to Generate. It counts every generated token, including the tokens of any reasoning the model performed, which the providers report as follows:

A value of 0 means the provider did not report usage for the last reply. After CreateEmbedding, this property is always 0, because creating embeddings generates no output tokens. This property is cleared when Generate, CountTokens, CreateEmbedding, or ListModels is called.

This property is read-only and not available at design time.

Proxy Property (LLMClient Class)

A set of properties related to proxy access.

Syntax

public Proxy getProxy();
public void setProxy(Proxy proxy);

Remarks

This property contains fields describing the proxy through which the class will attempt to connect.

ResponseText Property (LLMClient Class)

The text of the last reply.

Syntax

public String getResponseText();

Default Value

""

Remarks

This property holds the text of the reply received by the last call to Generate: the Text of every text part of the reply, concatenated in order. It is a convenient way to read the reply in the common case, without searching MessageParts for the parts of the appended message.

The model's reasoning is not included. When the reply holds only tool calls, this property is empty; the calls are reported through the ToolCall event.

This property is cleared when Generate, CountTokens, CreateEmbedding, or ListModels is called.

This property is read-only and not available at design time.

ServerURL Property (LLMClient Class)

The base URL of the provider's API endpoint.

Syntax

public String getServerURL();
public void setServerURL(String serverURL);

Default Value

""

Remarks

This property specifies the base URL used to build request URLs. When this property is empty (the default), the default base URL of the provider selected by ServiceProvider is used:

The custom values of ServiceProvider (spCustomGemini (97), spCustomAnthropic (98), and spCustomOpenAI (99)) have no default base URL: this property must be set before calling Generate, CountTokens, or ListModels, which otherwise fail with error 802.

Operation paths, such as /chat/completions, /messages, or /models/{Model}:generateContent, are appended to this value verbatim; no part of the value is rewritten, so endpoints that include or omit a version segment (such as /v1) are both supported.

In most cases, the default endpoint is the correct choice. This property should only be set when connecting to a custom endpoint, to an Ollama or LM Studio server on another host or port, or through a gateway or proxy that implements the selected provider's API.

Changing ServiceProvider does not change this property. Set it back to an empty string to use the default base URL of the newly selected provider.

The following example targets a vLLM server on another machine, which expects no APIKey at all.

llmclient.ServiceProvider = LLMClientServiceProviders.spCustomOpenAI; llmclient.ServerURL = "http://192.168.1.20:8000/v1"; llmclient.Model = "meta-llama/Llama-3.1-8B-Instruct"; llmclient.AddMessage("user", "What is the capital of France?"); llmclient.Generate();

In the Async Edition (nsoftware.async.IPWorksLLM), the same operation is awaited:

llmclient.ServiceProvider = LLMClientServiceProviders.spCustomOpenAI; llmclient.ServerURL = "http://192.168.1.20:8000/v1"; llmclient.Model = "meta-llama/Llama-3.1-8B-Instruct"; await llmclient.AddMessage("user", "What is the capital of France?"); await llmclient.Generate();

This property is not available at design time.

ServiceProvider Property (LLMClient Class)

The provider the class communicates with.

Syntax

public int getServiceProvider();
public void setServiceProvider(int serviceProvider);

Enumerated values:
  public final static int spOpenAI = 0;
  public final static int spAnthropic = 1;
  public final static int spGemini = 2;
  public final static int spOllama = 3;
  public final static int spLMStudio = 4;
  public final static int spGroq = 5;
  public final static int spOpenRouter = 6;
  public final static int spTogetherAI = 7;
  public final static int spFireworksAI = 8;
  public final static int spCustomGemini = 97;
  public final static int spCustomAnthropic = 98;
  public final static int spCustomOpenAI = 99;

Default Value

0

Remarks

This property specifies the provider whose API is used by Generate, CountTokens, CreateEmbedding, and ListModels. Every provider implements one of three APIs: the OpenAI Chat Completions API, the Anthropic Messages API, or the Google Gemini API. Possible values are:

The selected provider determines the default request URL, the header that carries APIKey, and the shape of every request and reply. The conversation itself is held in a provider-neutral form in Messages and MessageParts, and is translated for the selected provider each time a request is sent.

Where this documentation describes the behavior of spOpenAI, spAnthropic, or spGemini, the same behavior applies to every other value that uses the same API, unless stated otherwise. The differences between providers that share an API are:

• The default base URL, listed under ServerURL. The custom values (97 to 99) have no default, so ServerURL must be set before any request is made; otherwise the request fails with error 802.
• The field that carries MaxOutputTokens, as described there.
• The ToolChoice configuration setting, which must be empty or auto with spOllama, because Ollama does not support choosing tools.

A service that expects requests exactly as one of the official APIs does, such as a gateway or proxy in front of that API, is best used by selecting the official value (for example spOpenAI) and setting ServerURL, rather than by selecting a custom value.

Changing this property to a different value keeps Messages, MessageParts, and Tools, so a conversation may be continued with another provider. The ProviderData field of every item in MessageParts is cleared, however, because data that one provider returned, such as the signature of an Anthropic thinking block, cannot be sent to another, and ModelMarker is cleared for the same reason. Properties such as APIKey, Model, and ServerURL keep their values, and normally need to be changed along with this property.

The following example asks a question of one provider and continues the same conversation with another.

llmclient.ServiceProvider = LLMClientServiceProviders.spOpenAI; llmclient.APIKey = "sk-..."; llmclient.Model = "gpt-4o"; llmclient.AddMessage("user", "What is the capital of France?"); llmclient.Generate(); llmclient.ServiceProvider = LLMClientServiceProviders.spAnthropic; llmclient.APIKey = "sk-ant-..."; llmclient.Model = "claude-sonnet-5"; llmclient.MaxOutputTokens = 1024; llmclient.AddMessage("user", "And what is the capital of Germany?"); llmclient.Generate();

In the Async Edition (nsoftware.async.IPWorksLLM), the method calls are awaited:

llmclient.ServiceProvider = LLMClientServiceProviders.spOpenAI; llmclient.APIKey = "sk-..."; llmclient.Model = "gpt-4o"; await llmclient.AddMessage("user", "What is the capital of France?"); await llmclient.Generate(); llmclient.ServiceProvider = LLMClientServiceProviders.spAnthropic; llmclient.APIKey = "sk-ant-..."; llmclient.Model = "claude-sonnet-5"; llmclient.MaxOutputTokens = 1024; await llmclient.AddMessage("user", "And what is the capital of Germany?"); await llmclient.Generate();

This property is not available at design time.

SSLAcceptServerCert Property (LLMClient Class)

Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

public Certificate getSSLAcceptServerCert();
public void setSSLAcceptServerCert(Certificate SSLAcceptServerCert);

Remarks

If it finds any issues with the certificate presented by the server, the class will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

NOTE: This functionality is provided only for cases in which you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

SSLCert Property (LLMClient Class)

The certificate to be used during Secure Sockets Layer (SSL) negotiation.

Syntax

public Certificate getSSLCert();
public void setSSLCert(Certificate SSLCert);

Remarks

This property includes the digital certificate that the class will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

SSLProvider Property (LLMClient Class)

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

public int getSSLProvider();
public void setSSLProvider(int SSLProvider);

Enumerated values:
  public final static int sslpAutomatic = 0;
  public final static int sslpPlatform = 1;
  public final static int sslpInternal = 2;

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic), the class will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are as follows:

In most cases using the default value (Automatic) is recommended. The class will select a provider depending on the current platform.

When Automatic is selected, the platform implementation is used by default. When TLS 1.3 is enabled via SSLEnabledProtocols, the class will always try and use the platform implementation. If the platform TLS 1.3 implementation is not available, the internal implementation will be used.

SSLServerCert Property (LLMClient Class)

The server certificate for the last established connection.

Syntax

public Certificate getSSLServerCert();

Remarks

This property contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Stream Property (LLMClient Class)

Whether the reply should be streamed.

Syntax

public boolean isStream();
public void setStream(boolean stream);

Default Value

False

Remarks

When this property is set to True, Generate requests a streamed reply and the ContentDelta event fires once for each fragment of the reply as it is received. The event's PartType parameter is 0 (ptText) for a fragment of visible text and 5 (ptReasoning) for a fragment of the model's reasoning.

A streamed reply is requested with the stream field of the request when ServiceProvider is spOpenAI or spAnthropic, and through the streamGenerateContent operation, with the alt=sse query parameter, when it is spGemini.

In both cases, once the reply has been fully received it is appended to Messages and MessageParts, and the ToolCall event fires for each tool the model called.

The default value is False.

The following example prints the text of the reply as it arrives.

llmclient.Stream = true; llmclient.OnContentDelta += (s, e) => { if (e.PartType == (int)PartTypes.ptText) Console.Write(e.Delta); }; llmclient.AddMessage("user", "Write a short poem about the sea."); llmclient.Generate();

In the Async Edition (nsoftware.async.IPWorksLLM), the handler returns a task and the request is awaited:

llmclient.Stream = true; llmclient.OnContentDelta += async (s, e) => { if (e.PartType == (int)PartTypes.ptText) Console.Write(e.Delta); }; await llmclient.AddMessage("user", "Write a short poem about the sea."); await llmclient.Generate();

This property is not available at design time.

SystemPrompt Property (LLMClient Class)

The system prompt sent alongside the conversation.

Syntax

public String getSystemPrompt();
public void setSystemPrompt(String systemPrompt);

Default Value

""

Remarks

This property specifies the system prompt, which gives the model context and instructions that apply to the whole conversation, such as a role to adopt or a goal to pursue.

Each provider receives the system prompt in the form its API expects:

When this property is left empty (the default), no system prompt is sent.

The following example gives the model a role that applies to the whole conversation.

llmclient.SystemPrompt = "You are a concise assistant. Answer in one sentence."; llmclient.AddMessage("user", "What is the capital of France?"); llmclient.Generate();

In the Async Edition (nsoftware.async.IPWorksLLM), the property is set the same way and the request is awaited:

llmclient.SystemPrompt = "You are a concise assistant. Answer in one sentence."; await llmclient.AddMessage("user", "What is the capital of France?"); await llmclient.Generate();

This property is not available at design time.

Timeout Property (LLMClient Class)

The timeout for operations in seconds.

Syntax

public int getTimeout();
public void setTimeout(int timeout);

Default Value

60

Remarks

This property specifies the timeout period in seconds for operations performed by the class.

If this is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If this is set to a positive value, the class will wait for the operation to complete before returning control. If the timeout expires before the operation completes, the class throws an exception.

Note that all timeouts are inactivity timeouts, meaning the timeout period is extended by value specified in this property when any amount of data is successfully sent or received.

This property is not available at design time.

Tools Property (LLMClient Class)

The list of tools the model may call.

Syntax

public LLMToolList getTools();

Remarks

This collection holds the list of LLMTool items that are made available to the model when Generate is called. Each item's Name, Description, and InputSchema are sent as one function tool in the form the selected provider expects: an entry of tools with spOpenAI and spAnthropic, and a function declaration of tools with spGemini. When this collection is empty, no tools are sent.

The ToolChoice configuration setting controls whether the model may, must, or must not call a tool.

The AddToolParam and AddTool methods are a convenient way to append a new tool to this collection without constructing an LLMTool item directly.

This property is not available at design time.

TotalTokens Property (LLMClient Class)

The total number of tokens the provider counted for the last request.

Syntax

public int getTotalTokens();

Default Value

0

Remarks

This property reports the total number of tokens used by the last call to Generate or CreateEmbedding. When the provider reports a total, that value is used:

When the provider reports usage but no total, this property holds the sum of InputTokens and OutputTokens. A value of 0 means the provider did not report usage for the last request. This property is cleared when Generate, CountTokens, CreateEmbedding, or ListModels is called.

This property is read-only and not available at design time.

AddMessage Method (LLMClient Class)

Adds a message to the conversation and returns its Id.

Syntax

public String addMessage(String role, String content);

Remarks

This method appends a new LLMMessage item with the given Role to the Messages collection, and returns the Id generated for it. A generated Id has the form msg followed by a number, and never repeats an Id already present in Messages.

When Content is not empty, a text part holding Content is also appended to the MessageParts collection for the new message. To add further content to the message, such as an image or a file, pass the returned Id to AddMessagePart.

Role must not be empty, and is normally user or assistant. The results of tool calls are added with AddToolResult, which maintains the messages with role tool. Other roles, such as developer, are sent unchanged when ServiceProvider is spOpenAI; the Anthropic and Gemini APIs do not accept them, so with spAnthropic or spGemini Generate and CountTokens fail with error 804. A system prompt is supplied through the SystemPrompt property instead of a message.

The following example adds a question together with an image.

string id = llmclient.AddMessage("user", "What is in this picture?"); llmclient.AddMessagePart(id, (int)PartTypes.ptImage, "https://www.example.com/photo.jpg", "image/jpeg"); llmclient.Generate();

In the Async Edition (nsoftware.async.IPWorksLLM), the method calls are awaited:

string id = await llmclient.AddMessage("user", "What is in this picture?"); await llmclient.AddMessagePart(id, (int)PartTypes.ptImage, "https://www.example.com/photo.jpg", "image/jpeg"); await llmclient.Generate();

AddMessagePart Method (LLMClient Class)

Adds a content part to a message.

Syntax

public void addMessagePart(String messageId, int partType, String content, String mediaType);

Remarks

This method appends a new LLMMessagePart item of the given PartType to the MessageParts collection. MessageId must be the Id of a message in Messages, such as the value returned by AddMessage; otherwise this method fails with error 802.

PartType specifies the kind of part, and determines the meaning of Content. A value outside the range below causes this method to fail with error 802.

MediaType specifies the media type of an image or a file, such as image/png or application/pdf, and is stored in the part's MediaType field. It must be set when the bytes are supplied through Data; for a data: URL, the media type the URL names is used when MediaType is empty. It may be left empty for the other part types.

The following example adds a PDF document read from disk to a question.

string id = llmclient.AddMessage("user", "Summarize this report."); llmclient.AddMessagePart(id, (int)PartTypes.ptFile, "", "application/pdf"); LLMMessagePart part = llmclient.MessageParts[llmclient.MessageParts.Count - 1]; part.DataB = File.ReadAllBytes("report.pdf"); part.FileName = "report.pdf"; llmclient.Generate();

In the Async Edition (nsoftware.async.IPWorksLLM), the method calls are awaited:

string id = await llmclient.AddMessage("user", "Summarize this report."); await llmclient.AddMessagePart(id, (int)PartTypes.ptFile, "", "application/pdf"); LLMMessagePart part = llmclient.MessageParts[llmclient.MessageParts.Count - 1]; part.DataB = File.ReadAllBytes("report.pdf"); part.FileName = "report.pdf"; await llmclient.Generate();

AddTool Method (LLMClient Class)

Appends a tool to the Tools collection.

Syntax

public void addTool(String name, String description, String inputSchema);

Remarks

This method appends a new LLMTool item, with the given Name, Description, and InputSchema, to the Tools collection. Name must not be empty.

InputSchema is the JSON Schema object that describes the input the tool expects. When InputSchema is empty, the schema is built from the parameters queued by prior calls to AddToolParam. When no parameters were queued either, the tool's InputSchema is left empty, and a schema equivalent to {"type":"object"} (no input) is sent. The parameter queue is cleared each time this method is called.

Example: llmclient.AddToolParam("location", "string", "The city and state, e.g. San Francisco, CA", true); llmclient.AddTool("get_weather", "Gets the current weather for a location.", ""); // Alternatively, declare the same tool with a complete JSON Schema. llmclient.AddTool("get_weather", "Gets the current weather for a location.", "{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\"," + "\"description\":\"The city and state, e.g. San Francisco, CA\"}}," + "\"required\":[\"location\"]}");

In the Async Edition (nsoftware.async.IPWorksLLM), the calls are awaited:

await llmclient.AddToolParam("location", "string", "The city and state, e.g. San Francisco, CA", true); await llmclient.AddTool("get_weather", "Gets the current weather for a location.", "");

AddToolParam Method (LLMClient Class)

Queues a parameter to be included in the next tool added via AddTool.

Syntax

public void addToolParam(String name, String paramType, String description, boolean required);

Remarks

This method queues a parameter to be included in the JSON Schema of the next tool appended via AddTool.

Name specifies the parameter's name.

ParamType specifies the parameter's JSON Schema type, such as string, number, boolean, or object.

Description specifies a natural language description of the parameter, which helps the model determine appropriate values for it.

Required specifies whether the model must supply a value for this parameter whenever it calls the tool.

Queued parameters are consumed, and the queue is cleared, the next time AddTool is called. They are used only when that call passes an empty InputSchema; a non-empty InputSchema is used as given.

AddToolResult Method (LLMClient Class)

Adds the result of a tool call to the conversation.

Syntax

public void addToolResult(String toolCallId, String content, boolean isError);

Remarks

This method answers a tool call the model made, as reported by the ToolCall event. It appends a tool result part to the message with role tool at the end of Messages; when the last message is not a tool message, a new one is appended first. Calling this method once for each call of a reply therefore collects all of the results in one message.

ToolCallId is the Id reported by ToolCall. It must match the ToolCallId of a tool call part in MessageParts; otherwise this method fails with error 802. The ToolName of that call is copied to the new part, because the Gemini API identifies a result by the name of the function it answers.

Content is the result of the tool, typically text or a JSON value, and is stored in the new part's Text field. The Gemini API accepts only a JSON object as the response of a function. With spGemini, when IsError is False, a Content that is a JSON object is sent as is and any other value is sent as {"result": Content}; when IsError is True, the result is sent as {"error": Content}.

IsError specifies whether the tool failed, in which case Content describes the error. It is sent as the is_error field of the tool result when ServiceProvider is spAnthropic. The OpenAI API has no equivalent field, so with spOpenAI this parameter has no effect and Content alone should describe the error.

Each provider receives the results in the form its API expects: one message with role tool per result with spOpenAI, tool_result blocks at the start of a user message with spAnthropic, and functionResponse parts of a user message with spGemini.

Once every call of the reply has been answered, call Generate again so the model can use the results.

The following example answers each call as it is reported.

llmclient.OnToolCall += (s, e) => { string result; bool failed = false; try { result = GetWeather(e.ArgumentsJson); } catch (Exception ex) { result = "The weather service failed: " + ex.Message; failed = true; } llmclient.AddToolResult(e.Id, result, failed); }; llmclient.AddMessage("user", "What is the weather like in Boston?"); llmclient.Generate(); while (llmclient.FinishReason == LLMClientFinishReasons.frToolCalls) llmclient.Generate();

In the Async Edition (nsoftware.async.IPWorksLLM), the handler returns a task and each call is awaited:

llmclient.OnToolCall += async (s, e) => { string result; bool failed = false; try { result = GetWeather(e.ArgumentsJson); } catch (Exception ex) { result = "The weather service failed: " + ex.Message; failed = true; } await llmclient.AddToolResult(e.Id, result, failed); }; await llmclient.AddMessage("user", "What is the weather like in Boston?"); await llmclient.Generate(); while (llmclient.FinishReason == LLMClientFinishReasons.frToolCalls) await llmclient.Generate();

Config Method (LLMClient Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CountTokens Method (LLMClient Class)

Counts the input tokens the current conversation would consume.

Syntax

public int countTokens();

Remarks

This method sends the conversation in Messages and MessageParts, together with SystemPrompt and Tools, to the token counting endpoint of the selected provider, and returns the number of input tokens the model would consume. No reply is generated and nothing is appended to the conversation.

The endpoint depends on ServiceProvider:

This is useful for checking a conversation against a model's context window, or for estimating cost, before sending it.

The Model property must be set before calling this method, which otherwise fails with error 802. MaxOutputTokens is not required, because no output is generated.

The following example measures a conversation before paying to send it.

llmclient.ServiceProvider = LLMClientServiceProviders.spGemini; llmclient.Model = "gemini-2.0-flash"; llmclient.AddMessage("user", "What is the capital of France?"); int inputTokens = llmclient.CountTokens();

In the Async Edition (nsoftware.async.IPWorksLLM), the same operation is awaited:

llmclient.ServiceProvider = LLMClientServiceProviders.spGemini; llmclient.Model = "gemini-2.0-flash"; await llmclient.AddMessage("user", "What is the capital of France?"); int inputTokens = await llmclient.CountTokens();

CreateEmbedding Method (LLMClient Class)

Creates an embedding vector for each item of the Embeddings collection.

Syntax

public void createEmbedding();

Remarks

This method sends the InputText of every item in the Embeddings collection to the provider selected by ServiceProvider in a single request, and sets the OutputVector of each item to the embedding vector the provider created for its text, as JSON text containing an array of floating point numbers. The request is sent to:

The model specified by the EmbeddingModel configuration setting is used, or, when that setting is empty, the model specified by Model. Most providers publish models dedicated to embeddings, such as text-embedding-3-small with spOpenAI or gemini-embedding-001 with spGemini, so EmbeddingModel lets one model generate replies while another creates embeddings. The EmbeddingDimensions and EmbeddingTaskType configuration settings refine the request.

llmclient.ServiceProvider = LLMClientServiceProviders.spOpenAI; llmclient.APIKey = "sk-..."; llmclient.Config("EmbeddingModel=text-embedding-3-small"); llmclient.Embeddings.Add(new LLMEmbedding("The quick brown fox jumps over the lazy dog.")); llmclient.Embeddings.Add(new LLMEmbedding("A fast auburn fox leaps over a sleepy hound.")); llmclient.CreateEmbedding(); string firstVector = llmclient.Embeddings[0].OutputVector;

In the Async Edition (nsoftware.async.IPWorksLLM), the same operation is awaited:

await llmclient.Config("EmbeddingModel=text-embedding-3-small"); llmclient.Embeddings.Add(new LLMEmbedding("The quick brown fox jumps over the lazy dog.")); llmclient.Embeddings.Add(new LLMEmbedding("A fast auburn fox leaps over a sleepy hound.")); await llmclient.CreateEmbedding(); string firstVector = llmclient.Embeddings[0].OutputVector;

Every provider that uses the OpenAI API is sent the same request as spOpenAI, and every provider that uses the Gemini API the same request as spGemini. Not every such service offers embeddings; a service that does not answers with an error, which this method reports as error 801.

All items are sent in one request; this method never splits them over several requests. The provider limits the size of that request: the OpenAI API, for example, accepts at most 2048 inputs, at most 8192 tokens in any one input, and at most 300,000 tokens across all inputs of a request. A request beyond a limit fails with error 801, which carries the provider's own explanation; spread a large set of texts over several calls in that case.

The OutputVector of every item is cleared before the request is sent, so after an error no item holds a vector. When the reply does not hold exactly one embedding for each item, this method fails with error 803. On success, InputTokens and TotalTokens report the tokens the provider counted, or 0 when the reply carries no token count, which not every provider includes; OutputTokens is always 0, because creating embeddings generates no output tokens. ResponseText and FinishReason are cleared, as by every other request, while Messages and MessageParts are left unchanged.

This method fails with error 802 when Embeddings is empty, when an item's InputText is empty, when neither the EmbeddingModel configuration setting nor Model is set, or when ServiceProvider is a custom value (97 to 99) and ServerURL is empty. It fails with error 804 when ServiceProvider uses the Anthropic API, and when the EmbeddingTaskType configuration setting is set while ServiceProvider uses the OpenAI API, which has no such field.

DoEvents Method (LLMClient Class)

This method processes events from the internal message queue.

Syntax

public void doEvents();

Remarks

When DoEvents is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

Generate Method (LLMClient Class)

Sends the current conversation to the model and appends the reply.

Syntax

public void generate();

Remarks

This method sends the conversation in Messages and MessageParts, together with SystemPrompt, Tools, MaxOutputTokens, and the request configuration settings, such as Temperature and ToolChoice, to the provider selected by ServiceProvider:

Request properties and configuration settings left at their default values are omitted from the provider request.

On success, the reply is appended to Messages as a new message with role assistant, and its parts, such as text, reasoning, and tool calls, are appended to MessageParts. ResponseText then holds the text of the reply, FinishReason reports why the model stopped, and InputTokens, OutputTokens, and TotalTokens report the token usage the provider counted.

When Stream is set to True, the request is streamed (with spGemini, it is sent to {ServerURL}/models/{Model}:streamGenerateContent?alt=sse instead) and the ContentDelta event fires once for each incremental fragment of the reply as it is received; the fully assembled reply is still appended to Messages and MessageParts once streaming completes.

When the model's reply requests one or more tool invocations, the ToolCall event fires once for each requested call, after the reply has been appended. To continue the conversation, answer each call with AddToolResult and call this method again.

A reply that the provider blocks for safety reasons is not an error: this method returns normally and FinishReason reports frContentFilter. A reply that carries no content at all, such as one for a prompt the provider blocked, appends nothing to Messages.

The Model property must be set before calling this method; when ServiceProvider is spAnthropic or spCustomAnthropic, MaxOutputTokens must be set to a positive value; and when ServiceProvider is a custom value (97 to 99), ServerURL must be set. Otherwise this method fails with error 802.

The following example sends a short conversation and reads the reply.

llmclient.ServiceProvider = LLMClientServiceProviders.spOpenAI; llmclient.APIKey = "sk-..."; llmclient.Model = "gpt-4o"; llmclient.SystemPrompt = "You are a concise assistant."; llmclient.AddMessage("user", "What is the capital of France?"); llmclient.Generate(); string reply = llmclient.ResponseText;

In the Async Edition (nsoftware.async.IPWorksLLM), the same operation is awaited:

llmclient.ServiceProvider = LLMClientServiceProviders.spOpenAI; llmclient.APIKey = "sk-..."; llmclient.Model = "gpt-4o"; llmclient.SystemPrompt = "You are a concise assistant."; await llmclient.AddMessage("user", "What is the capital of France?"); await llmclient.Generate(); string reply = llmclient.ResponseText;

Interrupt Method (LLMClient Class)

This method interrupts the current method.

Syntax

public void interrupt();

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

ListModels Method (LLMClient Class)

Retrieves the list of models available from the provider.

Syntax

public void listModels();

Remarks

This method sends a request to {ServerURL}/models of the provider selected by ServiceProvider. The ModelList event fires once for each model reported by the server.

The Anthropic and Gemini APIs return the list in pages. If there are still more models to list when this method returns, the ModelMarker property will be populated; continue to call this method until ModelMarker is empty to list every page. The OpenAI API returns every model at once, so with spOpenAI a single call lists all models and ModelMarker stays empty.

This method is typically used to discover which model identifiers are valid for the Model property.

The following example prints every model the provider reports.

llmclient.OnModelList += (s, e) => { Console.WriteLine(e.Id + " (" + e.Name + ")"); }; do { llmclient.ListModels(); } while (llmclient.ModelMarker != "");

In the Async Edition (nsoftware.async.IPWorksLLM), the handler returns a task and each request is awaited:

llmclient.OnModelList += async (s, e) => { Console.WriteLine(e.Id + " (" + e.Name + ")"); }; do { await llmclient.ListModels(); } while (llmclient.ModelMarker != "");

Reset Method (LLMClient Class)

This method will reset the class.

Syntax

public void reset();

Remarks

This method will reset the class's properties to their default values.

Connected Event (LLMClient Class)

Fired immediately after a connection completes (or fails).

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void connected(LLMClientConnectedEvent e) {}
  ...
}

public class LLMClientConnectedEvent {
  public int statusCode;
  public String description;
}

Remarks

If the connection is made normally, StatusCode is 0 and Description is "OK".

If the connection fails, StatusCode has the error code returned by the Transmission Control Protocol (TCP)/IP stack. Description contains a description of this code. The value of StatusCode is equal to the value of the error.

Please refer to the Error Codes section for more information.

ConnectionStatus Event (LLMClient Class)

Fired to indicate changes in the connection state.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void connectionStatus(LLMClientConnectionStatusEvent e) {}
  ...
}

public class LLMClientConnectionStatusEvent {
  public String connectionEvent;
  public int statusCode;
  public String description;
}

Remarks

This event is fired when the connection state changes: for example, completion of a firewall or proxy connection or completion of a security handshake.

The ConnectionEvent parameter indicates the type of connection event. Values may include the following:

ContentDelta Event (LLMClient Class)

Fires once for each incremental fragment of a streamed reply.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void contentDelta(LLMClientContentDeltaEvent e) {}
  ...
}

public class LLMClientContentDeltaEvent {
  public int partType;
  public String delta;
}

Remarks

This event fires when Stream is set to True and Generate is called. It fires once for each incremental fragment of the reply as it is received from the server.

PartType identifies the kind of content the fragment belongs to: 0 (ptText) for the visible text of the reply, or 5 (ptReasoning) for the model's reasoning, when the provider streams it.

Delta holds the fragment itself. Concatenating Delta across every occurrence of this event with the same PartType reconstructs that content; the assembled reply is also appended to Messages and MessageParts once streaming completes.

Tool calls are not reported through this event. The class assembles each tool call as it is streamed, and the ToolCall event fires for each completed call once the reply has been appended.

The following example prints the visible text of the reply as it arrives, ignoring the model's reasoning.

llmclient.Stream = true; llmclient.OnContentDelta += (s, e) => { if (e.PartType == (int)PartTypes.ptText) Console.Write(e.Delta); }; llmclient.AddMessage("user", "Write a short poem about the sea."); llmclient.Generate();

In the Async Edition (nsoftware.async.IPWorksLLM), the handler returns a task and the request is awaited:

llmclient.Stream = true; llmclient.OnContentDelta += async (s, e) => { if (e.PartType == (int)PartTypes.ptText) Console.Write(e.Delta); }; await llmclient.AddMessage("user", "Write a short poem about the sea."); await llmclient.Generate();

Disconnected Event (LLMClient Class)

Fired when a connection is closed.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void disconnected(LLMClientDisconnectedEvent e) {}
  ...
}

public class LLMClientDisconnectedEvent {
  public int statusCode;
  public String description;
}

Remarks

If the connection is broken normally, StatusCode is 0 and Description is "OK".

If the connection is broken for any other reason, StatusCode has the error code returned by the Transmission Control Protocol (TCP/IP) subsystem. Description contains a description of this code. The value of StatusCode is equal to the value of the TCP/IP error.

Please refer to the Error Codes section for more information.

EndTransfer Event (LLMClient Class)

Fired when a document finishes transferring.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void endTransfer(LLMClientEndTransferEvent e) {}
  ...
}

public class LLMClientEndTransferEvent {
  public int direction;
}

Remarks

This event is fired first when the client finishes sending data to the server (in a POST or PUT request) and then when the document text finishes transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

Error Event (LLMClient Class)

Fired when information is available about errors during data delivery.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void error(LLMClientErrorEvent e) {}
  ...
}

public class LLMClientErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Header Event (LLMClient Class)

Fired every time a header line comes in.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void header(LLMClientHeaderEvent e) {}
  ...
}

public class LLMClientHeaderEvent {
  public String field;
  public String value;
}

Remarks

The Field parameter contains the name of the HTTP header (which is the same as it is delivered). The Value parameter contains the header contents.

If the header line being retrieved is a continuation header line, then the Field parameter contains "" (empty string).

Log Event (LLMClient Class)

Fired once for each log message.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void log(LLMClientLogEvent e) {}
  ...
}

public class LLMClientLogEvent {
  public int logLevel;
  public String message;
  public String logType;
}

Remarks

This event is fired once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of message. Possible values are as follows:

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

Message is the log entry.

LogType identifies the type of log entry. Possible values are as follows:

• "Info"
• "RequestHeaders"
• "ResponseHeaders"
• "RequestBody"
• "ResponseBody"
• "ProxyRequest"
• "ProxyResponse"
• "FirewallRequest"
• "FirewallResponse"

ModelList Event (LLMClient Class)

Fires once for each model reported by the server.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void modelList(LLMClientModelListEvent e) {}
  ...
}

public class LLMClientModelListEvent {
  public String id;
  public String name;
  public String description;
}

Remarks

This event fires once for each model returned in response to a call to ListModels.

Id holds the model's identifier, as would be supplied to Model. Name holds a human readable name for the model, and Description holds a description of the model. The providers report them as follows:

Redirect Event (LLMClient Class)

Fired when a redirection is received from the server.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void redirect(LLMClientRedirectEvent e) {}
  ...
}

public class LLMClientRedirectEvent {
  public String location;
  public boolean accept; //read-write
}

Remarks

This event is fired in cases in which the client can decide whether or not to continue with the redirection process. The Accept parameter is always True by default, but if you do not want to follow the redirection, Accept may be set to False, in which case the class throws an exception. Location is the location to which the client is being redirected. Further control over redirection is provided in the FollowRedirects property.

SetCookie Event (LLMClient Class)

Fired for every cookie set by the server.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void setCookie(LLMClientSetCookieEvent e) {}
  ...
}

public class LLMClientSetCookieEvent {
  public String name;
  public String value;
  public String expires;
  public String domain;
  public String path;
  public boolean secure;
}

Remarks

This event is fired for every Set-Cookie: header received from the HTTP server.

The Name parameter contains the name of the cookie, with the corresponding value supplied in the Value parameter.

The Expires parameter contains an expiration time for the cookie (if provided by the server). The time format used is "Weekday, DD-Mon-YY HH:MM:SS GMT". If the server does not provide an expiration time, the Expires parameter will be an empty string. In this case, the convention is to drop the cookie at the end of the session.

The Domain parameter contains a domain name to limit the cookie to (if provided by the server). If the server does not provide a domain name, the Domain parameter will be an empty string. The convention in this case is to use the server specified in the URL (URLServer) as the cookie domain.

The Path parameter contains a path name to limit the cookie to (if provided by the server). If the server does not provide a cookie path, the Path parameter will be an empty string. The convention in this case is to use the path specified in the URL (URLPath) as the cookie path.

The Secure parameter specifies whether the cookie is secure. If the value of this parameter is True, the cookie value must be submitted only through a secure (HTTPS) connection.

SSLServerAuthentication Event (LLMClient Class)

Fired after the server presents its certificate to the client.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void SSLServerAuthentication(LLMClientSSLServerAuthenticationEvent e) {}
  ...
}

public class LLMClientSSLServerAuthenticationEvent {
  public byte[] certEncoded;
  public String certSubject;
  public String certIssuer;
  public String status;
  public boolean accept; //read-write
}

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (LLMClient Class)

Fired when secure connection progress messages are available.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void SSLStatus(LLMClientSSLStatusEvent e) {}
  ...
}

public class LLMClientSSLStatusEvent {
  public String message;
}

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

StartTransfer Event (LLMClient Class)

Fired when a document starts transferring (after the headers).

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void startTransfer(LLMClientStartTransferEvent e) {}
  ...
}

public class LLMClientStartTransferEvent {
  public int direction;
}

Remarks

This event is fired first when the client starts sending data to the server (in a POST or PUT request) and then when the document text starts transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

Status Event (LLMClient Class)

Fired when the HTTP status line is received from the server.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void status(LLMClientStatusEvent e) {}
  ...
}

public class LLMClientStatusEvent {
  public String HTTPVersion;
  public int statusCode;
  public String description;
}

Remarks

HTTPVersion is a string containing the HTTP version string as returned from the server (e.g., "1.1").

StatusCode contains the HTTP status code (e.g., 200), and Description the associated message returned by the server (e.g., "OK").

ToolCall Event (LLMClient Class)

Fires once for each tool call requested by the model.

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void toolCall(LLMClientToolCallEvent e) {}
  ...
}

public class LLMClientToolCallEvent {
  public String id;
  public String name;
  public String argumentsJson;
}

Remarks

This event fires when the model's reply requests one or more tool invocations, once for each call. It fires for both streamed and non-streamed replies, after the reply, including one tool call part for each call, has been appended to Messages and MessageParts.

Id is the identifier of the call. It is assigned by the provider; when the Gemini API does not assign one, the class generates an identifier of the form llm_call_ followed by a number. Name is the name of the tool, and ArgumentsJson holds the JSON arguments object the model produced for the call.

To continue the conversation, pass Id and the tool's result to AddToolResult, then call Generate again once every call has been answered.

The following example answers the call and lets the model produce a final reply.

llmclient.OnToolCall += (s, e) => { llmclient.AddToolResult(e.Id, GetWeather(e.ArgumentsJson), false); }; llmclient.AddMessage("user", "What is the weather like in Boston?"); llmclient.Generate(); // The tool results were added above, so call Generate again for the final answer. while (llmclient.FinishReason == LLMClientFinishReasons.frToolCalls) llmclient.Generate(); Console.WriteLine(llmclient.ResponseText);

In the Async Edition (nsoftware.async.IPWorksLLM), the handler returns a task and each request is awaited:

llmclient.OnToolCall += async (s, e) => { await llmclient.AddToolResult(e.Id, GetWeather(e.ArgumentsJson), false); }; await llmclient.AddMessage("user", "What is the weather like in Boston?"); await llmclient.Generate(); while (llmclient.FinishReason == LLMClientFinishReasons.frToolCalls) await llmclient.Generate(); Console.WriteLine(llmclient.ResponseText);

Transfer Event (LLMClient Class)

Fired while a document transfers (delivers document).

Syntax

public class DefaultLLMClientEventListener implements LLMClientEventListener {
  ...
  public void transfer(LLMClientTransferEvent e) {}
  ...
}

public class LLMClientTransferEvent {
  public int direction;
  public long bytesTransferred;
  public int percentDone;
  public byte[] text;
}

Remarks

The Text parameter contains the portion of the document text being received. It is empty if data are being posted to the server.

The BytesTransferred parameter contains the number of bytes transferred in this Direction since the beginning of the document text (excluding HTTP response headers).

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

NOTE: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

• EffectiveDate
• ExpirationDate
• ExtendedKeyUsage
• Fingerprint
• FingerprintSHA1
• FingerprintSHA256
• Issuer
• KeyPassword
• PrivateKey
• PrivateKeyAvailable
• PrivateKeyContainer
• PublicKey
• PublicKeyAlgorithm
• PublicKeyLength
• SerialNumber
• SignatureAlgorithm
• Store
• StorePassword
• StoreType
• SubjectAltNames
• ThumbprintMD5
• ThumbprintSHA1
• ThumbprintSHA256
• Usage
• UsageFlags
• Version
• Subject
• Encoded

Fields

Constructors

public Certificate();

public Certificate(String certificateFile);

public Certificate(byte[] encoded);

public Certificate(int storeType, String store, String storePassword, String subject);

public Certificate(int storeType, String store, String storePassword, String subject, String configurationString);

public Certificate(int storeType, String store, String storePassword, byte[] encoded);

public Certificate(int storeType, byte[] store, String storePassword, String subject);

public Certificate(int storeType, byte[] store, String storePassword, String subject, String configurationString);

public Certificate(int storeType, byte[] store, String storePassword, byte[] encoded);

Firewall Type

The firewall the class will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall, such as the firewall Host and the FirewallType.

• AutoDetect
• FirewallType
• Host
• Password
• Port
• User

Fields

Constructors

public Firewall();

LLMEmbedding Type

A piece of text and the embedding vector created for it.

Remarks

This type represents one item of the Embeddings collection. Set InputText to the text to embed before calling CreateEmbedding. When that method returns, OutputVector holds the embedding vector the server created for the text.

• InputText
• OutputVector

Fields

Constructors

public LLMEmbedding();

public LLMEmbedding(String inputText);

LLMMessage Type

A single message in a conversation.

Remarks

This type represents a single message making up part of the conversation held in the Messages collection. A message holds only its Id and its Role. Its content, such as text, images, files, tool calls, and tool results, is held in the MessageParts collection, in the LLMMessagePart items whose MessageId matches Id.

• Id
• Role

Fields

Constructors

public LLMMessage();

LLMMessagePart Type

A single piece of the content of a message.

Remarks

This type represents one piece of the content of a message, held in the MessageParts collection. The MessageId field links the part to its message in Messages, and PartType identifies the kind of content the part holds. Only the fields that apply to that kind of content are used:

On the parts of a reply, the ProviderData field additionally holds the part exactly as the provider returned it, which the class uses when the conversation is sent back to the same provider.

• ArgumentsJson
• Data
• FileName
• IsError
• MediaType
• MessageId
• PartType
• ProviderData
• Text
• ToolCallId
• ToolName
• URL

Fields

Constructors

public LLMMessagePart();

LLMTool Type

A tool the model may call.

Remarks

This type represents a single tool made available to the model via the Tools collection. Each item is sent to the selected provider as one function tool, described by its Name, Description, and InputSchema.

• Description
• InputSchema
• Name

Fields

Constructors

public LLMTool();

Proxy Type

The proxy the class will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the Server and the AuthScheme.

• AuthScheme
• AutoDetect
• Password
• Port
• Server
• SSL
• User

Fields

Constructors

public Proxy();

public Proxy(String server, int port);

public Proxy(String server, int port, String user, String password);

Config Settings (LLMClient Class)

LLMClient Config Settings

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Socket Config Settings

Base Config Settings

Trappable Errors (LLMClient Class)

LLMClient Errors

HTTP Errors

TCPClient Errors

SSL Errors

TCP/IP Errors