OpenAI Class

Properties   Methods   Events   Config Settings   Errors  

Provides an easy way to chat with, embed text with, and list models from OpenAI and any OpenAI-compatible Chat Completions endpoint.

Syntax

class ipworksllm.OpenAI

Remarks

The OpenAI class provides a simple way to communicate with the OpenAI Chat Completions API, as well as any service that implements an OpenAI-compatible protocol, such as DeepSeek, Ollama, vLLM, Groq, or Azure OpenAI.

Selecting an Endpoint

The server_url property specifies the base URL used to build every request. Operation paths, such as /chat/completions, /models, and /embeddings, are appended to this value verbatim; no part of server_url is rewritten or normalized, and no /v1 segment is added or removed automatically.

By default, the class uses the official OpenAI endpoint, https://api.openai.com/v1. In most cases, the default endpoint is the correct choice. The server_url property should only be changed when connecting to a different OpenAI-compatible service.

// Official OpenAI. openai.ServerURL = "https://api.openai.com/v1"; openai.APIKey = "sk-..."; // DeepSeek. openai.ServerURL = "https://api.deepseek.com/v1"; openai.APIKey = "sk-..."; // A locally hosted Ollama server. No API key is required. openai.ServerURL = "http://localhost:11434/v1"; // A locally hosted vLLM server. openai.ServerURL = "http://localhost:8000/v1"; // Azure OpenAI, or any provider whose full request path must be given verbatim. openai.ServerURL = "https://my-resource.openai.azure.com/openai/deployments/my-deployment";

The api_key property is optional. When it is left empty, no Authorization header is sent at all, which is required by servers such as Ollama or vLLM that do not expect one. When api_key is set, it is sent as an Authorization: Bearer <key> header.

Sending a Chat

A conversation is built up in the messages properties, which holds a list of OpenAIMessage items. The add_message method is a convenient way to append a message with a given Role (such as system, developer, user, or assistant) and text Content.

Once the conversation contains at least one message, calling chat sends the entire messages properties, together with every non-default request property, to {ServerURL}/chat/completions. On success, the assistant's reply is appended to messages as a new item.

openai.ServerURL = "https://api.openai.com/v1"; openai.APIKey = "sk-..."; openai.Model = "gpt-4o"; openai.AddMessage("system", "You are a concise assistant."); openai.AddMessage("user", "What is the capital of France?"); openai.Chat(); // The assistant's reply is now the last item in Messages. string reply = openai.Messages[openai.Messages.Count - 1].Content; Console.WriteLine(reply);

Streaming

Setting the stream property to True before calling chat causes the request to be streamed. As each incremental piece of the assistant's reply arrives, the on_message_delta event fires with the text fragment. Once the stream completes, the fully assembled reply is still appended to messages, exactly as in the non-streaming case.

openai.Stream = true; openai.OnMessageDelta += (s, e) => { Console.Write(e.Delta); }; openai.AddMessage("user", "Write a short poem about the sea."); openai.Chat();

Tool Calling

Tools give the model an opportunity to request that the calling application execute a function on its behalf. A tool is declared by first queuing its parameters with one or more calls to add_tool_param, then calling add_tool to consume the queued parameters and append a new OpenAITool item to the tools properties.

When the model's reply requests one or more tool invocations, the on_tool_call event fires once per requested call, providing the provider-assigned Id, the tool Name, and the ArgumentsJson produced by the model. To continue the conversation, append a message with role tool whose ToolCallId field is set to Id and whose Content holds the tool's result, then call chat again so the model can incorporate that result.

openai.AddToolParam("location", "cstr", "The city and state, e.g. San Francisco, CA", true); openai.AddTool("get_weather", "Gets the current weather for a location."); openai.OnToolCall += (s, e) => { // Execute the requested tool and append its result as a 'tool' message. string result = GetWeather(e.ArgumentsJson); var message = new OpenAIMessage(); message.Role = "tool"; message.ToolCallId = e.Id; message.Content = result; openai.Messages.Add(message); }; openai.AddMessage("user", "What is the weather like in Boston?"); openai.Chat(); // If a tool was called, ToolCall fired and a 'tool' message was appended above. // Calling Chat again lets the model produce a final answer using the tool result. if (openai.Messages[openai.Messages.Count - 1].Role == "tool") openai.Chat();

Embeddings and Models

The create_embedding method creates an embedding vector for every item of the embeddings properties. All of the texts are sent to {ServerURL}/embeddings in a single request, and the OutputVector property of each item is set to the vector created for that item's InputText, as JSON text containing an array of floating point numbers. The EmbeddingModel configuration setting selects a model dedicated to embeddings without disturbing the model property used for chats.

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

The list_models method sends a request to {ServerURL}/models and fires the on_model_list event once for each model reported by the server.

openai.OnModelList += (s, e) => { Console.WriteLine(e.Id + " (" + e.OwnedBy + ")"); }; openai.ListModels();

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.

api_key property

The API key used to authenticate with the endpoint.

Syntax

def get_api_key() -> str: ...

def set_api_key(value: str) -> None: ...


api_key = property(get_api_key, set_api_key)

Default Value

""

Remarks

This property specifies the API key used to authenticate requests. When set, it is sent as an Authorization: Bearer <key> header.

When this property is left empty, no Authorization header is sent at all. This is required by some OpenAI-compatible servers, such as a locally hosted Ollama or vLLM instance, that do not expect an Authorization header to be present.

embedding_count property

The number of records in the Embedding arrays.

Syntax

def get_embedding_count() -> int: ...

def set_embedding_count(value: int) -> None: ...


embedding_count = property(get_embedding_count, set_embedding_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• embedding_input_text
• embedding_output_vector

The array indices start at 0 and end at embedding_count - 1.

embedding_input_text property

The text to create an embedding for.

Syntax

def get_embedding_input_text(embedding_index: int) -> str: ...

def set_embedding_input_text(embedding_index: int, value: str) -> None: ...

Default Value

""

Remarks

The text to create an embedding for.

This property holds the text that create_embedding sends to the server for this item. It must not be empty; otherwise create_embedding fails with error 802 before anything is sent.

The embedding_index parameter specifies the index of the item in the array. The size of the array is controlled by the embedding_count property.

embedding_output_vector property

The embedding vector created for the text, as a JSON array.

Syntax

def get_embedding_output_vector(embedding_index: int) -> str: ...

Default Value

""

Remarks

The embedding vector created for the text, as a JSON array.

This property holds the embedding vector the server created for embedding_input_text, as JSON text containing an array of floating point numbers, for example [0.0023064255,-0.009327292,0.015797347]. Each number is reported exactly as the server wrote it; only the whitespace between the numbers is removed. The number of elements depends on the model, and on the EmbeddingDimensions configuration setting when that setting is set.

This property is empty until create_embedding succeeds. create_embedding clears it in every item before its request is sent, so a failed call never leaves a vector from an earlier call next to new text.

The embedding_index parameter specifies the index of the item in the array. The size of the array is controlled by the embedding_count property.

This property is read-only.

firewall_auto_detect property

Whether to automatically detect and use firewall system settings, if available.

Syntax

def get_firewall_auto_detect() -> bool: ...

def set_firewall_auto_detect(value: bool) -> None: ...


firewall_auto_detect = property(get_firewall_auto_detect, set_firewall_auto_detect)

Default Value

False

Remarks

Whether to automatically detect and use firewall system settings, if available.

firewall_host property

The name or IP address of the firewall (optional).

Syntax

def get_firewall_host() -> str: ...

def set_firewall_host(value: str) -> None: ...


firewall_host = property(get_firewall_host, set_firewall_host)

Default Value

""

Remarks

The name or IP address of the firewall (optional). If a firewall_host is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the class fails with an error.

firewall_password property

A password if authentication is to be used when connecting through the firewall.

Syntax

def get_firewall_password() -> str: ...

def set_firewall_password(value: str) -> None: ...


firewall_password = property(get_firewall_password, set_firewall_password)

Default Value

""

Remarks

A password if authentication is to be used when connecting through the firewall. If firewall_host is specified, the firewall_user and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

firewall_port property

The Transmission Control Protocol (TCP) port for the firewall Host .

Syntax

def get_firewall_port() -> int: ...

def set_firewall_port(value: int) -> None: ...


firewall_port = property(get_firewall_port, set_firewall_port)

Default Value

0

Remarks

The Transmission Control Protocol (TCP) port for the firewall firewall_host. See the description of the firewall_host property for details.

NOTE: This property is set automatically when firewall_type is set to a valid value. See the description of the firewall_type property for details.

firewall_type property

The type of firewall to connect through.

Syntax

def get_firewall_type() -> int: ...

def set_firewall_type(value: int) -> None: ...


firewall_type = property(get_firewall_type, set_firewall_type)

Possible Values

0 # None
1 # Tunnel
2 # SOCKS4
3 # SOCKS5
10 # SOCKS4A

Default Value

0

Remarks

The type of firewall to connect through. The applicable values are as follows:

firewall_user property

A username if authentication is to be used when connecting through a firewall.

Syntax

def get_firewall_user() -> str: ...

def set_firewall_user(value: str) -> None: ...


firewall_user = property(get_firewall_user, set_firewall_user)

Default Value

""

Remarks

A username if authentication is to be used when connecting through a firewall. If firewall_host is specified, this property and the firewall_password property are used to connect and authenticate to the given Firewall. If the authentication fails, the class fails with an error.

frequency_penalty property

The frequency penalty to apply to the completion.

Syntax

def get_frequency_penalty() -> str: ...

def set_frequency_penalty(value: str) -> None: ...


frequency_penalty = property(get_frequency_penalty, set_frequency_penalty)

Default Value

""

Remarks

This property specifies a value, typically ranging from -2.0 to 2.0. Positive values penalize new tokens based on how frequently they have already appeared in the text so far, decreasing the likelihood of the model repeating the same phrasing.

When this property is left empty (the default), the frequency_penalty field is omitted from the request and the server's own default is used.

max_completion_tokens property

The maximum number of tokens to generate in the completion.

Syntax

def get_max_completion_tokens() -> int: ...

def set_max_completion_tokens(value: int) -> None: ...


max_completion_tokens = property(get_max_completion_tokens, set_max_completion_tokens)

Default Value

0

Remarks

This property specifies an upper bound on the number of tokens the model may generate in its reply, including visible output tokens and any internal reasoning tokens used by the model.

When this property is left at 0 (the default), the max_completion_tokens field is omitted from the request and the server's own default is used.

message_count property

The number of records in the Message arrays.

Syntax

def get_message_count() -> int: ...

def set_message_count(value: int) -> None: ...


message_count = property(get_message_count, set_message_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• message_content
• message_name
• message_role
• message_tool_call_id
• message_tool_calls

The array indices start at 0 and end at message_count - 1.

message_content property

The text content of the message.

Syntax

def get_message_content(message_index: int) -> str: ...

def set_message_content(message_index: int, value: str) -> None: ...

Default Value

""

Remarks

The text content of the message.

This property holds the text content of the message. When role is set to tool, this property holds the tool's result text.

The message_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_count property.

message_name property

An optional name identifying a distinct participant with the same role.

Syntax

def get_message_name(message_index: int) -> str: ...

def set_message_name(message_index: int, value: str) -> None: ...

Default Value

""

Remarks

An optional name identifying a distinct participant with the same role.

This property optionally identifies a distinct participant sharing the same role, such as distinguishing between multiple users in a conversation.

The message_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_count property.

message_role property

The role of the message's author.

Syntax

def get_message_role(message_index: int) -> str: ...

def set_message_role(message_index: int, value: str) -> None: ...

Default Value

""

Remarks

The role of the message's author.

This property identifies the role of the message's author, such as system, developer, user, assistant, or tool.

The message_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_count property.

message_tool_call_id property

The id of the tool call this message is a result for.

Syntax

def get_message_tool_call_id(message_index: int) -> str: ...

def set_message_tool_call_id(message_index: int, value: str) -> None: ...

Default Value

""

Remarks

The id of the tool call this message is a result for.

This property is used when role is set to tool, and must be set to the Id value received via the on_tool_call event for the call this message provides the result of.

The message_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_count property.

message_tool_calls property

The raw tool_calls JSON array for an assistant message.

Syntax

def get_message_tool_calls(message_index: int) -> str: ...

def set_message_tool_calls(message_index: int, value: str) -> None: ...

Default Value

""

Remarks

The raw tool_calls JSON array for an assistant message.

This property holds the raw tool_calls JSON array as received from, or to be sent to, the server. It is set automatically on assistant messages that request tool invocations, and is serialized back verbatim when non-empty.

The message_index parameter specifies the index of the item in the array. The size of the array is controlled by the message_count property.

model property

The model used when sending a chat or creating an embedding.

Syntax

def get_model() -> str: ...

def set_model(value: str) -> None: ...


model = property(get_model, set_model)

Default Value

""

Remarks

This property specifies the identifier of the model that will process the request, for example gpt-4o or gpt-4o-mini. This property must be set before calling chat.

When create_embedding is called, this model is used unless the EmbeddingModel configuration setting has been set to a different value.

Refer to the documentation of the endpoint specified by server_url for the list of valid model identifiers.

organization property

The organization associated with the request.

Syntax

def get_organization() -> str: ...

def set_organization(value: str) -> None: ...


organization = property(get_organization, set_organization)

Default Value

""

Remarks

This property specifies the value sent in the OpenAI-Organization header. It is only sent when this property is non-empty.

This is used by accounts that belong to multiple organizations to indicate which organization should be billed for the request. Refer to the provider's documentation to determine whether this header is supported.

presence_penalty property

The presence penalty to apply to the completion.

Syntax

def get_presence_penalty() -> str: ...

def set_presence_penalty(value: str) -> None: ...


presence_penalty = property(get_presence_penalty, set_presence_penalty)

Default Value

""

Remarks

This property specifies a value, typically ranging from -2.0 to 2.0. Positive values penalize new tokens based on whether they have appeared in the text so far at all, increasing the likelihood of the model introducing new topics.

When this property is left empty (the default), the presence_penalty field is omitted from the request and the server's own default is used.

project property

The project associated with the request.

Syntax

def get_project() -> str: ...

def set_project(value: str) -> None: ...


project = property(get_project, set_project)

Default Value

""

Remarks

This property specifies the value sent in the OpenAI-Project header. It is only sent when this property is non-empty.

This is used by accounts with API keys scoped to the organization level to indicate which project should be billed for the request. Refer to the provider's documentation to determine whether this header is supported.

proxy_auth_scheme property

The type of authorization to perform when connecting to the proxy.

Syntax

def get_proxy_auth_scheme() -> int: ...

def set_proxy_auth_scheme(value: int) -> None: ...


proxy_auth_scheme = property(get_proxy_auth_scheme, set_proxy_auth_scheme)

Possible Values

0 # Basic
1 # Digest
2 # Proprietary
3 # None
4 # Ntlm
5 # Negotiate

Default Value

0

Remarks

The type of authorization to perform when connecting to the proxy. This is used only when the proxy_user and proxy_password properties are set.

proxy_auth_scheme should be set to authNone (3) when no authentication is expected.

By default, proxy_auth_scheme is authBasic (0), and if the proxy_user and proxy_password properties are set, the class will attempt basic authentication.

If proxy_auth_scheme is set to authDigest (1), digest authentication will be attempted instead.

If proxy_auth_scheme is set to authProprietary (2), then the authorization token will not be generated by the class. Look at the configuration file for the class being used to find more information about manually setting this token.

If proxy_auth_scheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of proxy_user and proxy_password.

proxy_auto_detect property

Whether to automatically detect and use proxy system settings, if available.

Syntax

def get_proxy_auto_detect() -> bool: ...

def set_proxy_auto_detect(value: bool) -> None: ...


proxy_auto_detect = property(get_proxy_auto_detect, set_proxy_auto_detect)

Default Value

False

Remarks

Whether to automatically detect and use proxy system settings, if available. The default value is False.

proxy_password property

A password if authentication is to be used for the proxy.

Syntax

def get_proxy_password() -> str: ...

def set_proxy_password(value: str) -> None: ...


proxy_password = property(get_proxy_password, set_proxy_password)

Default Value

""

Remarks

A password if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

proxy_port property

The Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Syntax

def get_proxy_port() -> int: ...

def set_proxy_port(value: int) -> None: ...


proxy_port = property(get_proxy_port, set_proxy_port)

Default Value

80

Remarks

The Transmission Control Protocol (TCP) port for the proxy proxy_server (default 80). See the description of the proxy_server property for details.

proxy_server property

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Syntax

def get_proxy_server() -> str: ...

def set_proxy_server(value: str) -> None: ...


proxy_server = property(get_proxy_server, set_proxy_server)

Default Value

""

Remarks

If a proxy proxy_server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the proxy_server property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the proxy_server property is set to the corresponding address. If the search is not successful, an error is returned.

proxy_ssl property

When to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Syntax

def get_proxy_ssl() -> int: ...

def set_proxy_ssl(value: int) -> None: ...


proxy_ssl = property(get_proxy_ssl, set_proxy_ssl)

Possible Values

0 # Automatic
1 # Always
2 # Never
3 # Tunnel

Default Value

0

Remarks

When to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

proxy_user property

A username if authentication is to be used for the proxy.

Syntax

def get_proxy_user() -> str: ...

def set_proxy_user(value: str) -> None: ...


proxy_user = property(get_proxy_user, set_proxy_user)

Default Value

""

Remarks

A username if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

response_format property

The format that the model's reply must be output in.

Syntax

def get_response_format() -> str: ...

def set_response_format(value: str) -> None: ...


response_format = property(get_response_format, set_response_format)

Default Value

""

Remarks

This property controls the response_format field of the request. The value text or json_object is translated into {"type": "text"} or {"type": "json_object"} respectively. Alternatively, this property may be set to a complete raw JSON object (a value beginning with {), which is passed through to the response_format field verbatim, allowing a full JSON Schema response format to be specified.

When this property is left empty (the default), the response_format field is omitted from the request and the model replies with unstructured text.

server_url property

The base URL of the OpenAI or OpenAI-compatible API endpoint.

Syntax

def get_server_url() -> str: ...

def set_server_url(value: str) -> None: ...


server_url = property(get_server_url, set_server_url)

Default Value

"https://api.openai.com/v1"

Remarks

This property specifies the base URL used to build request URLs. Operation paths such as /chat/completions 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.

By default, the class uses the official OpenAI endpoint, https://api.openai.com/v1. In most cases, the default endpoint is the correct choice. This property should only be changed when connecting to a different OpenAI-compatible service, such as a locally hosted server or an alternative cloud provider.

The following example targets a locally hosted Ollama server, which expects no api_key at all.

openai.ServerURL = "http://localhost:11434/v1"; openai.Model = "llama3.2"; openai.AddMessage("user", "What is the capital of France?"); openai.Chat();

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

openai.ServerURL = "http://localhost:11434/v1"; openai.Model = "llama3.2"; await openai.AddMessage("user", "What is the capital of France?"); await openai.Chat();

ssl_accept_server_cert_effective_date property

The date on which this certificate becomes valid.

Syntax

def get_ssl_accept_server_cert_effective_date() -> str: ...


ssl_accept_server_cert_effective_date = property(get_ssl_accept_server_cert_effective_date, None)

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

ssl_accept_server_cert_encoded property

The certificate (PEM/Base64 encoded).

Syntax

def get_ssl_accept_server_cert_encoded() -> bytes: ...

def set_ssl_accept_server_cert_encoded(value: bytes) -> None: ...


ssl_accept_server_cert_encoded = property(get_ssl_accept_server_cert_encoded, set_ssl_accept_server_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_accept_server_cert_store and ssl_accept_server_cert_subject properties also may be used to specify a certificate.

When ssl_accept_server_cert_encoded is set, a search is initiated in the current ssl_accept_server_cert_store for the private key of the certificate. If the key is found, ssl_accept_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_accept_server_cert_subject is set to an empty string.

ssl_accept_server_cert_expiration_date property

The date on which the certificate expires.

Syntax

def get_ssl_accept_server_cert_expiration_date() -> str: ...


ssl_accept_server_cert_expiration_date = property(get_ssl_accept_server_cert_expiration_date, None)

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

ssl_accept_server_cert_extended_key_usage property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_accept_server_cert_extended_key_usage() -> str: ...


ssl_accept_server_cert_extended_key_usage = property(get_ssl_accept_server_cert_extended_key_usage, None)

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

ssl_accept_server_cert_fingerprint property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_ssl_accept_server_cert_fingerprint() -> str: ...


ssl_accept_server_cert_fingerprint = property(get_ssl_accept_server_cert_fingerprint, None)

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

ssl_accept_server_cert_fingerprint_sha1 property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_ssl_accept_server_cert_fingerprint_sha1() -> str: ...


ssl_accept_server_cert_fingerprint_sha1 = property(get_ssl_accept_server_cert_fingerprint_sha1, None)

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

ssl_accept_server_cert_fingerprint_sha256 property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_ssl_accept_server_cert_fingerprint_sha256() -> str: ...


ssl_accept_server_cert_fingerprint_sha256 = property(get_ssl_accept_server_cert_fingerprint_sha256, None)

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

ssl_accept_server_cert_issuer property

The issuer of the certificate.

Syntax

def get_ssl_accept_server_cert_issuer() -> str: ...


ssl_accept_server_cert_issuer = property(get_ssl_accept_server_cert_issuer, None)

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

ssl_accept_server_cert_private_key property

The private key of the certificate (if available).

Syntax

def get_ssl_accept_server_cert_private_key() -> str: ...


ssl_accept_server_cert_private_key = property(get_ssl_accept_server_cert_private_key, None)

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_accept_server_cert_private_key may be available but not exportable. In this case, ssl_accept_server_cert_private_key returns an empty string.

This property is read-only.

ssl_accept_server_cert_private_key_available property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_accept_server_cert_private_key_available() -> bool: ...


ssl_accept_server_cert_private_key_available = property(get_ssl_accept_server_cert_private_key_available, None)

Default Value

False

Remarks

Whether a ssl_accept_server_cert_private_key is available for the selected certificate. If ssl_accept_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

ssl_accept_server_cert_private_key_container property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_ssl_accept_server_cert_private_key_container() -> str: ...


ssl_accept_server_cert_private_key_container = property(get_ssl_accept_server_cert_private_key_container, None)

Default Value

""

Remarks

The name of the ssl_accept_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

ssl_accept_server_cert_public_key property

The public key of the certificate.

Syntax

def get_ssl_accept_server_cert_public_key() -> str: ...


ssl_accept_server_cert_public_key = property(get_ssl_accept_server_cert_public_key, None)

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

ssl_accept_server_cert_public_key_algorithm property

The textual description of the certificate's public key algorithm.

Syntax

def get_ssl_accept_server_cert_public_key_algorithm() -> str: ...


ssl_accept_server_cert_public_key_algorithm = property(get_ssl_accept_server_cert_public_key_algorithm, None)

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_accept_server_cert_public_key_length property

The length of the certificate's public key (in bits).

Syntax

def get_ssl_accept_server_cert_public_key_length() -> int: ...


ssl_accept_server_cert_public_key_length = property(get_ssl_accept_server_cert_public_key_length, None)

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

ssl_accept_server_cert_serial_number property

The serial number of the certificate encoded as a string.

Syntax

def get_ssl_accept_server_cert_serial_number() -> str: ...


ssl_accept_server_cert_serial_number = property(get_ssl_accept_server_cert_serial_number, None)

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

ssl_accept_server_cert_signature_algorithm property

The text description of the certificate's signature algorithm.

Syntax

def get_ssl_accept_server_cert_signature_algorithm() -> str: ...


ssl_accept_server_cert_signature_algorithm = property(get_ssl_accept_server_cert_signature_algorithm, None)

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_accept_server_cert_store property

The name of the certificate store for the client certificate.

Syntax

def get_ssl_accept_server_cert_store() -> bytes: ...

def set_ssl_accept_server_cert_store(value: bytes) -> None: ...


ssl_accept_server_cert_store = property(get_ssl_accept_server_cert_store, set_ssl_accept_server_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_accept_server_cert_store_type property denotes the type of the certificate store specified by ssl_accept_server_cert_store. If the store is password-protected, specify the password in ssl_accept_server_cert_store_password.

ssl_accept_server_cert_store is used in conjunction with the ssl_accept_server_cert_subject property to specify client certificates. If ssl_accept_server_cert_store has a value, and ssl_accept_server_cert_subject or ssl_accept_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_accept_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

ssl_accept_server_cert_store_password property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_ssl_accept_server_cert_store_password() -> str: ...

def set_ssl_accept_server_cert_store_password(value: str) -> None: ...


ssl_accept_server_cert_store_password = property(get_ssl_accept_server_cert_store_password, set_ssl_accept_server_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

ssl_accept_server_cert_store_type property

The type of certificate store for this certificate.

Syntax

def get_ssl_accept_server_cert_store_type() -> int: ...

def set_ssl_accept_server_cert_store_type(value: int) -> None: ...


ssl_accept_server_cert_store_type = property(get_ssl_accept_server_cert_store_type, set_ssl_accept_server_cert_store_type)

Possible Values

0 # User
1 # Machine
2 # PFXFile
3 # PFXBlob
4 # JKSFile
5 # JKSBlob
6 # PEMKeyFile
7 # PEMKeyBlob
8 # PublicKeyFile
9 # PublicKeyBlob
10 # SSHPublicKeyBlob
11 # P7BFile
12 # P7BBlob
13 # SSHPublicKeyFile
14 # PPKFile
15 # PPKBlob
16 # XMLFile
17 # XMLBlob
18 # JWKFile
19 # JWKBlob
20 # SecurityKey
21 # BCFKSFile
22 # BCFKSBlob
23 # PKCS11
99 # Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

ssl_accept_server_cert_subject property

The subject of the certificate used for client authentication.

Syntax

def get_ssl_accept_server_cert_subject() -> str: ...

def set_ssl_accept_server_cert_subject(value: str) -> None: ...


ssl_accept_server_cert_subject = property(get_ssl_accept_server_cert_subject, set_ssl_accept_server_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

ssl_accept_server_cert_subject_alt_names property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_ssl_accept_server_cert_subject_alt_names() -> str: ...


ssl_accept_server_cert_subject_alt_names = property(get_ssl_accept_server_cert_subject_alt_names, None)

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

ssl_accept_server_cert_thumbprint_md5 property

The MD5 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_md5() -> str: ...


ssl_accept_server_cert_thumbprint_md5 = property(get_ssl_accept_server_cert_thumbprint_md5, None)

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_accept_server_cert_thumbprint_sha1 property

The SHA-1 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_sha1() -> str: ...


ssl_accept_server_cert_thumbprint_sha1 = property(get_ssl_accept_server_cert_thumbprint_sha1, None)

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_accept_server_cert_thumbprint_sha256 property

The SHA-256 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_sha256() -> str: ...


ssl_accept_server_cert_thumbprint_sha256 = property(get_ssl_accept_server_cert_thumbprint_sha256, None)

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_accept_server_cert_usage property

The text description of UsageFlags .

Syntax

def get_ssl_accept_server_cert_usage() -> str: ...


ssl_accept_server_cert_usage = property(get_ssl_accept_server_cert_usage, None)

Default Value

""

Remarks

The text description of ssl_accept_server_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

ssl_accept_server_cert_usage_flags property

The flags that show intended use for the certificate.

Syntax

def get_ssl_accept_server_cert_usage_flags() -> int: ...


ssl_accept_server_cert_usage_flags = property(get_ssl_accept_server_cert_usage_flags, None)

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_accept_server_cert_usage_flags is a combination of the following flags:

Please see the ssl_accept_server_cert_usage property for a text representation of ssl_accept_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

ssl_accept_server_cert_version property

The certificate's version number.

Syntax

def get_ssl_accept_server_cert_version() -> str: ...


ssl_accept_server_cert_version = property(get_ssl_accept_server_cert_version, None)

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

ssl_cert_effective_date property

The date on which this certificate becomes valid.

Syntax

def get_ssl_cert_effective_date() -> str: ...


ssl_cert_effective_date = property(get_ssl_cert_effective_date, None)

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

ssl_cert_encoded property

The certificate (PEM/Base64 encoded).

Syntax

def get_ssl_cert_encoded() -> bytes: ...

def set_ssl_cert_encoded(value: bytes) -> None: ...


ssl_cert_encoded = property(get_ssl_cert_encoded, set_ssl_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_cert_store and ssl_cert_subject properties also may be used to specify a certificate.

When ssl_cert_encoded is set, a search is initiated in the current ssl_cert_store for the private key of the certificate. If the key is found, ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_cert_subject is set to an empty string.

ssl_cert_expiration_date property

The date on which the certificate expires.

Syntax

def get_ssl_cert_expiration_date() -> str: ...


ssl_cert_expiration_date = property(get_ssl_cert_expiration_date, None)

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

ssl_cert_extended_key_usage property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_cert_extended_key_usage() -> str: ...


ssl_cert_extended_key_usage = property(get_ssl_cert_extended_key_usage, None)

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

ssl_cert_fingerprint property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_ssl_cert_fingerprint() -> str: ...


ssl_cert_fingerprint = property(get_ssl_cert_fingerprint, None)

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

ssl_cert_fingerprint_sha1 property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_ssl_cert_fingerprint_sha1() -> str: ...


ssl_cert_fingerprint_sha1 = property(get_ssl_cert_fingerprint_sha1, None)

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

ssl_cert_fingerprint_sha256 property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_ssl_cert_fingerprint_sha256() -> str: ...


ssl_cert_fingerprint_sha256 = property(get_ssl_cert_fingerprint_sha256, None)

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

ssl_cert_issuer property

The issuer of the certificate.

Syntax

def get_ssl_cert_issuer() -> str: ...


ssl_cert_issuer = property(get_ssl_cert_issuer, None)

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

ssl_cert_private_key property

The private key of the certificate (if available).

Syntax

def get_ssl_cert_private_key() -> str: ...


ssl_cert_private_key = property(get_ssl_cert_private_key, None)

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_cert_private_key may be available but not exportable. In this case, ssl_cert_private_key returns an empty string.

This property is read-only.

ssl_cert_private_key_available property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_cert_private_key_available() -> bool: ...


ssl_cert_private_key_available = property(get_ssl_cert_private_key_available, None)

Default Value

False

Remarks

Whether a ssl_cert_private_key is available for the selected certificate. If ssl_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

ssl_cert_private_key_container property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_ssl_cert_private_key_container() -> str: ...


ssl_cert_private_key_container = property(get_ssl_cert_private_key_container, None)

Default Value

""

Remarks

The name of the ssl_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

ssl_cert_public_key property

The public key of the certificate.

Syntax

def get_ssl_cert_public_key() -> str: ...


ssl_cert_public_key = property(get_ssl_cert_public_key, None)

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

ssl_cert_public_key_algorithm property

The textual description of the certificate's public key algorithm.

Syntax

def get_ssl_cert_public_key_algorithm() -> str: ...


ssl_cert_public_key_algorithm = property(get_ssl_cert_public_key_algorithm, None)

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_cert_public_key_length property

The length of the certificate's public key (in bits).

Syntax

def get_ssl_cert_public_key_length() -> int: ...


ssl_cert_public_key_length = property(get_ssl_cert_public_key_length, None)

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

ssl_cert_serial_number property

The serial number of the certificate encoded as a string.

Syntax

def get_ssl_cert_serial_number() -> str: ...


ssl_cert_serial_number = property(get_ssl_cert_serial_number, None)

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

ssl_cert_signature_algorithm property

The text description of the certificate's signature algorithm.

Syntax

def get_ssl_cert_signature_algorithm() -> str: ...


ssl_cert_signature_algorithm = property(get_ssl_cert_signature_algorithm, None)

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_cert_store property

The name of the certificate store for the client certificate.

Syntax

def get_ssl_cert_store() -> bytes: ...

def set_ssl_cert_store(value: bytes) -> None: ...


ssl_cert_store = property(get_ssl_cert_store, set_ssl_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password-protected, specify the password in ssl_cert_store_password.

ssl_cert_store is used in conjunction with the ssl_cert_subject property to specify client certificates. If ssl_cert_store has a value, and ssl_cert_subject or ssl_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

ssl_cert_store_password property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_ssl_cert_store_password() -> str: ...

def set_ssl_cert_store_password(value: str) -> None: ...


ssl_cert_store_password = property(get_ssl_cert_store_password, set_ssl_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

ssl_cert_store_type property

The type of certificate store for this certificate.

Syntax

def get_ssl_cert_store_type() -> int: ...

def set_ssl_cert_store_type(value: int) -> None: ...


ssl_cert_store_type = property(get_ssl_cert_store_type, set_ssl_cert_store_type)

Possible Values

0 # User
1 # Machine
2 # PFXFile
3 # PFXBlob
4 # JKSFile
5 # JKSBlob
6 # PEMKeyFile
7 # PEMKeyBlob
8 # PublicKeyFile
9 # PublicKeyBlob
10 # SSHPublicKeyBlob
11 # P7BFile
12 # P7BBlob
13 # SSHPublicKeyFile
14 # PPKFile
15 # PPKBlob
16 # XMLFile
17 # XMLBlob
18 # JWKFile
19 # JWKBlob
20 # SecurityKey
21 # BCFKSFile
22 # BCFKSBlob
23 # PKCS11
99 # Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

ssl_cert_subject property

The subject of the certificate used for client authentication.

Syntax

def get_ssl_cert_subject() -> str: ...

def set_ssl_cert_subject(value: str) -> None: ...


ssl_cert_subject = property(get_ssl_cert_subject, set_ssl_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

ssl_cert_subject_alt_names property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_ssl_cert_subject_alt_names() -> str: ...


ssl_cert_subject_alt_names = property(get_ssl_cert_subject_alt_names, None)

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

ssl_cert_thumbprint_md5 property

The MD5 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_md5() -> str: ...


ssl_cert_thumbprint_md5 = property(get_ssl_cert_thumbprint_md5, None)

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_cert_thumbprint_sha1 property

The SHA-1 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_sha1() -> str: ...


ssl_cert_thumbprint_sha1 = property(get_ssl_cert_thumbprint_sha1, None)

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_cert_thumbprint_sha256 property

The SHA-256 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_sha256() -> str: ...


ssl_cert_thumbprint_sha256 = property(get_ssl_cert_thumbprint_sha256, None)

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_cert_usage property

The text description of UsageFlags .

Syntax

def get_ssl_cert_usage() -> str: ...


ssl_cert_usage = property(get_ssl_cert_usage, None)

Default Value

""

Remarks

The text description of ssl_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

ssl_cert_usage_flags property

The flags that show intended use for the certificate.

Syntax

def get_ssl_cert_usage_flags() -> int: ...


ssl_cert_usage_flags = property(get_ssl_cert_usage_flags, None)

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_cert_usage_flags is a combination of the following flags:

Please see the ssl_cert_usage property for a text representation of ssl_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

ssl_cert_version property

The certificate's version number.

Syntax

def get_ssl_cert_version() -> str: ...


ssl_cert_version = property(get_ssl_cert_version, None)

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

ssl_provider property

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

Syntax

def get_ssl_provider() -> int: ...

def set_ssl_provider(value: int) -> None: ...


ssl_provider = property(get_ssl_provider, set_ssl_provider)

Possible Values

0 # Automatic
1 # Platform
2 # Internal

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, on Windows, the class will use the platform implementation. On Linux/macOS, the class will use the internal implementation. 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.

ssl_server_cert_effective_date property

The date on which this certificate becomes valid.

Syntax

def get_ssl_server_cert_effective_date() -> str: ...


ssl_server_cert_effective_date = property(get_ssl_server_cert_effective_date, None)

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

ssl_server_cert_encoded property

The certificate (PEM/Base64 encoded).

Syntax

def get_ssl_server_cert_encoded() -> bytes: ...


ssl_server_cert_encoded = property(get_ssl_server_cert_encoded, None)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_server_cert_store and ssl_server_cert_subject properties also may be used to specify a certificate.

When ssl_server_cert_encoded is set, a search is initiated in the current ssl_server_cert_store for the private key of the certificate. If the key is found, ssl_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_server_cert_subject is set to an empty string.

This property is read-only.

ssl_server_cert_expiration_date property

The date on which the certificate expires.

Syntax

def get_ssl_server_cert_expiration_date() -> str: ...


ssl_server_cert_expiration_date = property(get_ssl_server_cert_expiration_date, None)

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

ssl_server_cert_extended_key_usage property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_server_cert_extended_key_usage() -> str: ...


ssl_server_cert_extended_key_usage = property(get_ssl_server_cert_extended_key_usage, None)

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

ssl_server_cert_fingerprint property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_ssl_server_cert_fingerprint() -> str: ...


ssl_server_cert_fingerprint = property(get_ssl_server_cert_fingerprint, None)

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

ssl_server_cert_fingerprint_sha1 property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_ssl_server_cert_fingerprint_sha1() -> str: ...


ssl_server_cert_fingerprint_sha1 = property(get_ssl_server_cert_fingerprint_sha1, None)

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

ssl_server_cert_fingerprint_sha256 property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_ssl_server_cert_fingerprint_sha256() -> str: ...


ssl_server_cert_fingerprint_sha256 = property(get_ssl_server_cert_fingerprint_sha256, None)

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

ssl_server_cert_issuer property

The issuer of the certificate.

Syntax

def get_ssl_server_cert_issuer() -> str: ...


ssl_server_cert_issuer = property(get_ssl_server_cert_issuer, None)

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

ssl_server_cert_private_key property

The private key of the certificate (if available).

Syntax

def get_ssl_server_cert_private_key() -> str: ...


ssl_server_cert_private_key = property(get_ssl_server_cert_private_key, None)

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_server_cert_private_key may be available but not exportable. In this case, ssl_server_cert_private_key returns an empty string.

This property is read-only.

ssl_server_cert_private_key_available property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_server_cert_private_key_available() -> bool: ...


ssl_server_cert_private_key_available = property(get_ssl_server_cert_private_key_available, None)

Default Value

False

Remarks

Whether a ssl_server_cert_private_key is available for the selected certificate. If ssl_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

ssl_server_cert_private_key_container property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_ssl_server_cert_private_key_container() -> str: ...


ssl_server_cert_private_key_container = property(get_ssl_server_cert_private_key_container, None)

Default Value

""

Remarks

The name of the ssl_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

ssl_server_cert_public_key property

The public key of the certificate.

Syntax

def get_ssl_server_cert_public_key() -> str: ...


ssl_server_cert_public_key = property(get_ssl_server_cert_public_key, None)

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

ssl_server_cert_public_key_algorithm property

The textual description of the certificate's public key algorithm.

Syntax

def get_ssl_server_cert_public_key_algorithm() -> str: ...


ssl_server_cert_public_key_algorithm = property(get_ssl_server_cert_public_key_algorithm, None)

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_server_cert_public_key_length property

The length of the certificate's public key (in bits).

Syntax

def get_ssl_server_cert_public_key_length() -> int: ...


ssl_server_cert_public_key_length = property(get_ssl_server_cert_public_key_length, None)

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

ssl_server_cert_serial_number property

The serial number of the certificate encoded as a string.

Syntax

def get_ssl_server_cert_serial_number() -> str: ...


ssl_server_cert_serial_number = property(get_ssl_server_cert_serial_number, None)

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

ssl_server_cert_signature_algorithm property

The text description of the certificate's signature algorithm.

Syntax

def get_ssl_server_cert_signature_algorithm() -> str: ...


ssl_server_cert_signature_algorithm = property(get_ssl_server_cert_signature_algorithm, None)

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_server_cert_store property

The name of the certificate store for the client certificate.

Syntax

def get_ssl_server_cert_store() -> bytes: ...


ssl_server_cert_store = property(get_ssl_server_cert_store, None)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_server_cert_store_type property denotes the type of the certificate store specified by ssl_server_cert_store. If the store is password-protected, specify the password in ssl_server_cert_store_password.

ssl_server_cert_store is used in conjunction with the ssl_server_cert_subject property to specify client certificates. If ssl_server_cert_store has a value, and ssl_server_cert_subject or ssl_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

This property is read-only.

ssl_server_cert_store_password property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_ssl_server_cert_store_password() -> str: ...


ssl_server_cert_store_password = property(get_ssl_server_cert_store_password, None)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

This property is read-only.

ssl_server_cert_store_type property

The type of certificate store for this certificate.

Syntax

def get_ssl_server_cert_store_type() -> int: ...


ssl_server_cert_store_type = property(get_ssl_server_cert_store_type, None)

Possible Values

0 # User
1 # Machine
2 # PFXFile
3 # PFXBlob
4 # JKSFile
5 # JKSBlob
6 # PEMKeyFile
7 # PEMKeyBlob
8 # PublicKeyFile
9 # PublicKeyBlob
10 # SSHPublicKeyBlob
11 # P7BFile
12 # P7BBlob
13 # SSHPublicKeyFile
14 # PPKFile
15 # PPKBlob
16 # XMLFile
17 # XMLBlob
18 # JWKFile
19 # JWKBlob
20 # SecurityKey
21 # BCFKSFile
22 # BCFKSBlob
23 # PKCS11
99 # Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

This property is read-only.

ssl_server_cert_subject property

The subject of the certificate used for client authentication.

Syntax

def get_ssl_server_cert_subject() -> str: ...


ssl_server_cert_subject = property(get_ssl_server_cert_subject, None)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

This property is read-only.

ssl_server_cert_subject_alt_names property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_ssl_server_cert_subject_alt_names() -> str: ...


ssl_server_cert_subject_alt_names = property(get_ssl_server_cert_subject_alt_names, None)

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

ssl_server_cert_thumbprint_md5 property

The MD5 hash of the certificate.

Syntax

def get_ssl_server_cert_thumbprint_md5() -> str: ...


ssl_server_cert_thumbprint_md5 = property(get_ssl_server_cert_thumbprint_md5, None)

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_server_cert_thumbprint_sha1 property

The SHA-1 hash of the certificate.

Syntax

def get_ssl_server_cert_thumbprint_sha1() -> str: ...


ssl_server_cert_thumbprint_sha1 = property(get_ssl_server_cert_thumbprint_sha1, None)

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_server_cert_thumbprint_sha256 property

The SHA-256 hash of the certificate.

Syntax

def get_ssl_server_cert_thumbprint_sha256() -> str: ...


ssl_server_cert_thumbprint_sha256 = property(get_ssl_server_cert_thumbprint_sha256, None)

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_server_cert_usage property

The text description of UsageFlags .

Syntax

def get_ssl_server_cert_usage() -> str: ...


ssl_server_cert_usage = property(get_ssl_server_cert_usage, None)

Default Value

""

Remarks

The text description of ssl_server_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

ssl_server_cert_usage_flags property

The flags that show intended use for the certificate.

Syntax

def get_ssl_server_cert_usage_flags() -> int: ...


ssl_server_cert_usage_flags = property(get_ssl_server_cert_usage_flags, None)

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_server_cert_usage_flags is a combination of the following flags:

Please see the ssl_server_cert_usage property for a text representation of ssl_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

ssl_server_cert_version property

The certificate's version number.

Syntax

def get_ssl_server_cert_version() -> str: ...


ssl_server_cert_version = property(get_ssl_server_cert_version, None)

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

stop_sequences property

A comma-separated list of sequences where the model should stop generating.

Syntax

def get_stop_sequences() -> str: ...

def set_stop_sequences(value: str) -> None: ...


stop_sequences = property(get_stop_sequences, set_stop_sequences)

Default Value

""

Remarks

This property specifies up to a handful of sequences, separated by commas, at which the model will stop generating further tokens. For example, setting this to END,STOP causes generation to stop as soon as either END or STOP is produced.

When this property is left empty (the default), the stop field is omitted from the request.

stream property

Whether the chat response should be streamed.

Syntax

def get_stream() -> bool: ...

def set_stream(value: bool) -> None: ...


stream = property(get_stream, set_stream)

Default Value

False

Remarks

When this property is set to True, chat sends the request with streaming enabled and the on_message_delta event fires once for each incremental fragment of the assistant's reply as it is received.

In both cases, once the reply has been fully received it is appended to messages as a new item.

The default value is False.

The following example prints the assistant's reply as it arrives.

openai.Stream = true; openai.OnMessageDelta += (s, e) => { Console.Write(e.Delta); }; openai.AddMessage("user", "Write a short poem about the sea."); openai.Chat();

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

openai.Stream = true; openai.OnMessageDelta += async (s, e) => { Console.Write(e.Delta); }; await openai.AddMessage("user", "Write a short poem about the sea."); await openai.Chat();

temperature property

The sampling temperature to use for the completion.

Syntax

def get_temperature() -> str: ...

def set_temperature(value: str) -> None: ...


temperature = property(get_temperature, set_temperature)

Default Value

""

Remarks

This property specifies the sampling temperature, typically ranging from 0.0 to 2.0. Higher values make the output more random, while lower values make it more focused and deterministic.

When this property is left empty (the default), the temperature field is omitted from the request and the server's own default is used.

timeout property

The timeout for operations in seconds.

Syntax

def get_timeout() -> int: ...

def set_timeout(value: int) -> None: ...


timeout = property(get_timeout, set_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.

tool_count property

The number of records in the Tool arrays.

Syntax

def get_tool_count() -> int: ...

def set_tool_count(value: int) -> None: ...


tool_count = property(get_tool_count, set_tool_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• tool_description
• tool_name
• tool_parameters_schema

The array indices start at 0 and end at tool_count - 1.

tool_description property

The brief, human-readable description of what the tool does.

Syntax

def get_tool_description(tool_index: int) -> str: ...

def set_tool_description(tool_index: int, value: str) -> None: ...

Default Value

""

Remarks

The brief, human-readable description of what the tool does.

This property holds a brief, human-readable description of what the tool does, which is critical in helping the model understand when the tool should be called.

The tool_index parameter specifies the index of the item in the array. The size of the array is controlled by the tool_count property.

tool_name property

The unique name associated with the tool.

Syntax

def get_tool_name(tool_index: int) -> str: ...

def set_tool_name(tool_index: int, value: str) -> None: ...

Default Value

""

Remarks

The unique name associated with the tool.

This property identifies the unique name associated with the tool.

The tool_index parameter specifies the index of the item in the array. The size of the array is controlled by the tool_count property.

tool_parameters_schema property

The raw JSON Schema describing the tool's parameters.

Syntax

def get_tool_parameters_schema(tool_index: int) -> str: ...

def set_tool_parameters_schema(tool_index: int, value: str) -> None: ...

Default Value

""

Remarks

The raw JSON Schema describing the tool's parameters.

This property holds the raw JSON Schema object describing the tool's parameters, as built from calls to add_tool_param or as set directly. When left empty, a schema equivalent to {"type": "object"} (no parameters) is used.

The tool_index parameter specifies the index of the item in the array. The size of the array is controlled by the tool_count property.

tool_choice property

Controls whether and how the model is permitted to call tools.

Syntax

def get_tool_choice() -> str: ...

def set_tool_choice(value: str) -> None: ...


tool_choice = property(get_tool_choice, set_tool_choice)

Default Value

""

Remarks

This property controls the tool_choice field of the request. The value auto, none, or required is sent as the corresponding JSON string, respectively allowing the model to decide, preventing any tool call, or forcing at least one tool call. Alternatively, this property may be set to a complete raw JSON object (a value beginning with {), which is passed through to the tool_choice field verbatim, allowing a specific tool to be forced by name.

When this property is left empty (the default), the tool_choice field is omitted from the request and the server's own default behavior is used. This property has no effect unless at least one tool has been added to the tools properties.

top_p property

The nucleus sampling value to use for the completion.

Syntax

def get_top_p() -> str: ...

def set_top_p(value: str) -> None: ...


top_p = property(get_top_p, set_top_p)

Default Value

""

Remarks

This property specifies an alternative to sampling with temperature, called nucleus sampling. The model considers only the tokens comprising the top TopP probability mass, expressed as a value between 0.0 and 1.0.

When this property is left empty (the default), the top_p field is omitted from the request and the server's own default is used.

It is generally recommended to alter either temperature or this property, but not both.

add_message method

Appends a message to the Messages collection.

Syntax

def add_message(role: str, content: str) -> None: ...

Remarks

This method appends a new message with the given role (such as system, developer, user, or assistant) and text content to the messages properties. It is a convenience equivalent to adding an item to the collection directly.

add_tool method

Appends a tool to the Tools collection.

Syntax

def add_tool(name: str, description: str) -> None: ...

Remarks

This method appends a new OpenAITool item, with the given name and description, to the tools properties.

Any parameters queued by prior calls to add_tool_param are consumed and used to build the new tool's parameter schema; the parameter queue is then cleared.

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

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

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

add_tool_param method

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

Syntax

def add_tool_param(name: str, param_type: str, description: str, required: bool) -> None: ...

Remarks

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

name specifies the parameter's name.

param_type 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 add_tool is called.

chat method

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

Syntax

def chat() -> None: ...

Remarks

This method sends the entire messages properties, together with every request property that has been set away from its default value, to {ServerURL}/chat/completions. Properties left at their default values are omitted from the request JSON, which allows the class to work with services that reject unrecognized fields.

On success, the assistant's reply is appended to messages as a new item.

When the model's reply requests one or more tool invocations, the on_tool_call event fires once for each requested call. To continue the conversation, append a message with role tool containing the tool's result and call this method again.

The model property must be set before calling this method.

The following example sends a short conversation and reads the reply back out of messages.

openai.APIKey = "sk-..."; openai.Model = "gpt-4o"; openai.AddMessage("system", "You are a concise assistant."); openai.AddMessage("user", "What is the capital of France?"); openai.Chat(); string reply = openai.Messages[openai.Messages.Count - 1].Content;

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

openai.APIKey = "sk-..."; openai.Model = "gpt-4o"; await openai.AddMessage("system", "You are a concise assistant."); await openai.AddMessage("user", "What is the capital of France?"); await openai.Chat(); string reply = openai.Messages[openai.Messages.Count - 1].Content;

config method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

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.

create_embedding method

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

Syntax

def create_embedding() -> None: ...

Remarks

This method sends the InputText of every item in the embeddings properties to {ServerURL}/embeddings in a single request, and sets the OutputVector of each item to the embedding vector the server created for its text, as JSON text containing an array of floating point numbers.

The model specified by the EmbeddingModel configuration setting is used, or, when that setting is empty, the model specified by model. When the EmbeddingDimensions configuration setting is set, the server is asked to shorten every vector to that number of elements.

The following example selects a model dedicated to embeddings and embeds two sentences with it in one request.

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

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

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

All items are sent in one request; this method never splits them over several requests. The server limits the size of that request: the OpenAI API 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 server's own explanation; spread a large set of texts over several calls in that case. Other services that implement the OpenAI API may set different limits.

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, the PromptTokens and TotalTokens configuration settings report the tokens the server counted.

This method fails with error 802 when embeddings is empty, when an item's InputText is empty, or when neither the EmbeddingModel configuration setting nor model is set. Nothing is appended to messages by this method.

do_events method

This method processes events from the internal message queue.

Syntax

def do_events() -> None: ...

Remarks

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

interrupt method

This method interrupts the current method.

Syntax

def interrupt() -> None: ...

Remarks

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

list_models method

Retrieves the list of models available from the endpoint.

Syntax

def list_models() -> None: ...

Remarks

This method sends a request to {ServerURL}/models. The on_model_list event fires once for each model reported by the server.

This method is typically used to discover which model identifiers are valid for the model property when communicating with a given endpoint.

reset method

This method will reset the class.

Syntax

def reset() -> None: ...

Remarks

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

on_connected event

Fired immediately after a connection completes (or fails).

Syntax

class OpenAIConnectedEventParams(object):
  @property
  def status_code() -> int: ...
  @property
  def description() -> str: ...
# In class OpenAI:
@property
def on_connected() -> Callable[[OpenAIConnectedEventParams], None]: ...
@on_connected.setter
def on_connected(event_hook: Callable[[OpenAIConnectedEventParams], None]) -> None: ...

Remarks

If the connection is made normally, status_code is 0 and description is "OK".

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

Please refer to the Error Codes section for more information.

on_connection_status event

Fired to indicate changes in the connection state.

Syntax

class OpenAIConnectionStatusEventParams(object):
  @property
  def connection_event() -> str: ...
  @property
  def status_code() -> int: ...
  @property
  def description() -> str: ...
# In class OpenAI:
@property
def on_connection_status() -> Callable[[OpenAIConnectionStatusEventParams], None]: ...
@on_connection_status.setter
def on_connection_status(event_hook: Callable[[OpenAIConnectionStatusEventParams], None]) -> None: ...

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 connection_event parameter indicates the type of connection event. Values may include the following:

on_disconnected event

Fired when a connection is closed.

Syntax

class OpenAIDisconnectedEventParams(object):
  @property
  def status_code() -> int: ...
  @property
  def description() -> str: ...
# In class OpenAI:
@property
def on_disconnected() -> Callable[[OpenAIDisconnectedEventParams], None]: ...
@on_disconnected.setter
def on_disconnected(event_hook: Callable[[OpenAIDisconnectedEventParams], None]) -> None: ...

Remarks

If the connection is broken normally, status_code is 0 and description is "OK".

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

Please refer to the Error Codes section for more information.

on_end_transfer event

Fired when a document finishes transferring.

Syntax

class OpenAIEndTransferEventParams(object):
  @property
  def direction() -> int: ...
# In class OpenAI:
@property
def on_end_transfer() -> Callable[[OpenAIEndTransferEventParams], None]: ...
@on_end_transfer.setter
def on_end_transfer(event_hook: Callable[[OpenAIEndTransferEventParams], None]) -> None: ...

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.

on_error event

Fired when information is available about errors during data delivery.

Syntax

class OpenAIErrorEventParams(object):
  @property
  def error_code() -> int: ...
  @property
  def description() -> str: ...
# In class OpenAI:
@property
def on_error() -> Callable[[OpenAIErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[OpenAIErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The error_code 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.

on_header event

Fired every time a header line comes in.

Syntax

class OpenAIHeaderEventParams(object):
  @property
  def field() -> str: ...
  @property
  def value() -> str: ...
# In class OpenAI:
@property
def on_header() -> Callable[[OpenAIHeaderEventParams], None]: ...
@on_header.setter
def on_header(event_hook: Callable[[OpenAIHeaderEventParams], None]) -> None: ...

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).

on_log event

Fired once for each log message.

Syntax

class OpenAILogEventParams(object):
  @property
  def log_level() -> int: ...
  @property
  def message() -> str: ...
  @property
  def log_type() -> str: ...
# In class OpenAI:
@property
def on_log() -> Callable[[OpenAILogEventParams], None]: ...
@on_log.setter
def on_log(event_hook: Callable[[OpenAILogEventParams], None]) -> None: ...

Remarks

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

log_level 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.

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

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

on_message_delta event

Fires once for each incremental fragment of a streamed reply.

Syntax

class OpenAIMessageDeltaEventParams(object):
  @property
  def delta() -> str: ...
# In class OpenAI:
@property
def on_message_delta() -> Callable[[OpenAIMessageDeltaEventParams], None]: ...
@on_message_delta.setter
def on_message_delta(event_hook: Callable[[OpenAIMessageDeltaEventParams], None]) -> None: ...

Remarks

This event fires when stream is set to True and chat is called. It fires once for each incremental text fragment of the assistant's reply as it is received from the server.

delta holds the text fragment. Concatenating the value of delta across every occurrence of this event reconstructs the full reply, which is also appended to messages once streaming completes.

The following example accumulates the fragments as they arrive.

StringBuilder assembled = new StringBuilder(); openai.Stream = true; openai.OnMessageDelta += (s, e) => { assembled.Append(e.Delta); }; openai.AddMessage("user", "Write a short poem about the sea."); openai.Chat();

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

StringBuilder assembled = new StringBuilder(); openai.Stream = true; openai.OnMessageDelta += async (s, e) => { assembled.Append(e.Delta); }; await openai.AddMessage("user", "Write a short poem about the sea."); await openai.Chat();

on_model_list event

Fires once for each model reported by the server.

Syntax

class OpenAIModelListEventParams(object):
  @property
  def id() -> str: ...
  @property
  def owned_by() -> str: ...
# In class OpenAI:
@property
def on_model_list() -> Callable[[OpenAIModelListEventParams], None]: ...
@on_model_list.setter
def on_model_list(event_hook: Callable[[OpenAIModelListEventParams], None]) -> None: ...

Remarks

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

id holds the model's identifier, as would be supplied to model. owned_by holds the identifier of the organization that owns the model.

on_redirect event

Fired when a redirection is received from the server.

Syntax

class OpenAIRedirectEventParams(object):
  @property
  def location() -> str: ...
  @property
  def accept() -> bool: ...
  @accept.setter
  def accept(value) -> None: ...
# In class OpenAI:
@property
def on_redirect() -> Callable[[OpenAIRedirectEventParams], None]: ...
@on_redirect.setter
def on_redirect(event_hook: Callable[[OpenAIRedirectEventParams], None]) -> None: ...

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 fails with an error. location is the location to which the client is being redirected. Further control over redirection is provided in the follow_redirects property.

on_set_cookie event

Fired for every cookie set by the server.

Syntax

class OpenAISetCookieEventParams(object):
  @property
  def name() -> str: ...
  @property
  def value() -> str: ...
  @property
  def expires() -> str: ...
  @property
  def domain() -> str: ...
  @property
  def path() -> str: ...
  @property
  def secure() -> bool: ...
# In class OpenAI:
@property
def on_set_cookie() -> Callable[[OpenAISetCookieEventParams], None]: ...
@on_set_cookie.setter
def on_set_cookie(event_hook: Callable[[OpenAISetCookieEventParams], None]) -> None: ...

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 (url_server) 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 (url_path) 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.

on_ssl_server_authentication event

Fired after the server presents its certificate to the client.

Syntax

class OpenAISSLServerAuthenticationEventParams(object):
  @property
  def cert_encoded() -> bytes: ...
  @property
  def cert_subject() -> str: ...
  @property
  def cert_issuer() -> str: ...
  @property
  def status() -> str: ...
  @property
  def accept() -> bool: ...
  @accept.setter
  def accept(value) -> None: ...
# In class OpenAI:
@property
def on_ssl_server_authentication() -> Callable[[OpenAISSLServerAuthenticationEventParams], None]: ...
@on_ssl_server_authentication.setter
def on_ssl_server_authentication(event_hook: Callable[[OpenAISSLServerAuthenticationEventParams], None]) -> None: ...

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.

on_ssl_status event

Fired when secure connection progress messages are available.

Syntax

class OpenAISSLStatusEventParams(object):
  @property
  def message() -> str: ...
# In class OpenAI:
@property
def on_ssl_status() -> Callable[[OpenAISSLStatusEventParams], None]: ...
@on_ssl_status.setter
def on_ssl_status(event_hook: Callable[[OpenAISSLStatusEventParams], None]) -> None: ...

Remarks

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

on_start_transfer event

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

Syntax

class OpenAIStartTransferEventParams(object):
  @property
  def direction() -> int: ...
# In class OpenAI:
@property
def on_start_transfer() -> Callable[[OpenAIStartTransferEventParams], None]: ...
@on_start_transfer.setter
def on_start_transfer(event_hook: Callable[[OpenAIStartTransferEventParams], None]) -> None: ...

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.

on_status event

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

Syntax

class OpenAIStatusEventParams(object):
  @property
  def http_version() -> str: ...
  @property
  def status_code() -> int: ...
  @property
  def description() -> str: ...
# In class OpenAI:
@property
def on_status() -> Callable[[OpenAIStatusEventParams], None]: ...
@on_status.setter
def on_status(event_hook: Callable[[OpenAIStatusEventParams], None]) -> None: ...

Remarks

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

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

on_tool_call event

Fires once for each tool call requested by the model.

Syntax

class OpenAIToolCallEventParams(object):
  @property
  def id() -> str: ...
  @property
  def name() -> str: ...
  @property
  def arguments_json() -> str: ...
# In class OpenAI:
@property
def on_tool_call() -> Callable[[OpenAIToolCallEventParams], None]: ...
@on_tool_call.setter
def on_tool_call(event_hook: Callable[[OpenAIToolCallEventParams], None]) -> None: ...

Remarks

This event fires when the model reply requests one or more tool invocations. id is the provider-assigned tool call id, name is the tool name, and arguments_json holds the argument JSON produced by the model.

To continue the conversation, append a message with role tool whose ToolCallId field is set to id and whose Content holds the tool result, then call chat again.

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

openai.OnToolCall += (s, e) => { OpenAIMessage message = new OpenAIMessage(); message.Role = "tool"; message.ToolCallId = e.Id; message.Content = GetWeather(e.ArgumentsJson); openai.Messages.Add(message); }; openai.AddMessage("user", "What is the weather like in Boston?"); openai.Chat(); // A tool result was appended above, so call Chat again for the final answer. if (openai.Messages[openai.Messages.Count - 1].Role == "tool") openai.Chat();

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

openai.OnToolCall += async (s, e) => { OpenAIMessage message = new OpenAIMessage(); message.Role = "tool"; message.ToolCallId = e.Id; message.Content = GetWeather(e.ArgumentsJson); openai.Messages.Add(message); }; await openai.AddMessage("user", "What is the weather like in Boston?"); await openai.Chat(); if (openai.Messages[openai.Messages.Count - 1].Role == "tool") await openai.Chat();

on_transfer event

Fired while a document transfers (delivers document).

Syntax

class OpenAITransferEventParams(object):
  @property
  def direction() -> int: ...
  @property
  def bytes_transferred() -> int: ...
  @property
  def percent_done() -> int: ...
  @property
  def text() -> bytes: ...
# In class OpenAI:
@property
def on_transfer() -> Callable[[OpenAITransferEventParams], None]: ...
@on_transfer.setter
def on_transfer(event_hook: Callable[[OpenAITransferEventParams], None]) -> None: ...

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 bytes_transferred 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 percent_done parameter shows the progress of the transfer in the corresponding direction. If percent_done 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.

OpenAI Config Settings

OpenAI 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

OpenAI Errors

OpenAI Errors

HTTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

SSL Errors

TCP/IP Errors