GenAI

Private preview

This feature is currently available to a limited group of customers as part of a private preview program. Please note that the API may change during this phase. If you’re interested in participating, please contact our support team.

class GenAIMixin

This class defines all functions related to GenAI.

get_chat_completion(messages, instructions=None, model_id=None, config=None, tools=None, tool_choice=None)

Gets the chat completion for the given messages.

Parameters:

messages (Sequence[Message]) – The chat messages.
instructions (str, optional) – The system prompt to provide instructions or context to the model.
model_id (ChatModel, optional) – The chat model. If omitted, the default model is used ChatModel.ANTHROPIC_CLAUDE_SONNET.
config (ChatInferenceConfig, optional) – The config with the inference parameters.
tools (Sequence[Tool], optional) – The tools that the model can use.
tool_choice (ToolChoice, optional) – Specify how the model should choose a tool.

Returns:

The chat completion.

Return type:

ChatCompletion

Examples:

Basic usage:

>>> import blueconic
>>> from blueconic.domain.genai import Message
>>> bc = blueconic.Client()
>>> response = bc.get_chat_completion([
>>>   Message(Message.Role.USER, "What is Lorem Ipsum?")
>>> ])
>>> print(response.content[0].text)
"Lorem Ipsum is essentially dummy text used as a placeholder in design and publishing. It allows designers to focus on the layout without being distracted by the content."

With a document:

>>> import requests
>>> import blueconic
>>> from blueconic.domain.genai import Message, TextBlock, DocumentBlock
>>> bc = blueconic.Client()
>>> doc = requests.get("https://example.com/lorem_ipsum.pdf")
>>> response = bc.get_chat_completion([
>>>   Message(Message.Role.USER, [
>>>     TextBlock("Summarize this document"),
>>>     DocumentBlock(doc.content, DocumentBlock.Format.PDF, "Lorem Ipsum")
>>>   ])
>>> ])
>>> print(response.content[0].text)
"The document contains Lorem Ipsum dummy text that is commonly used in the publishing industry as a placeholder text."

With an image:

>>> import requests
>>> import blueconic
>>> from blueconic.domain.genai import Message, TextBlock, ImageBlock
>>> bc = blueconic.Client()
>>> img = requests.get("https://example.com/earth.png")
>>> response = bc.get_chat_completion([
>>>   Message(Message.Role.USER, [
>>>     TextBlock("Describe this image"),
>>>     ImageBlock(img.content, ImageBlock.Format.PNG)
>>>   ])
>>> ])
>>> print(response.content[0].text)
"The image shows a view of the Earth from space."

With a tool:

>>> import blueconic
>>> from blueconic.domain.genai import Message, Tool, ChatCompletion
>>> bc = blueconic.Client()
>>> # Implement a tool
>>> def calculator_add(a, b):
>>>   return int(a) + int(b)
>>> # Define the tool schema
>>> calculator_add_json_schema = {
>>>   "type": "object",
>>>   "properties": {
>>>     "a": {"type": "number"},
>>>     "b": {"type": "number"}
>>>   },
>>>   "required": ["a", "b"]
>>> }
>>> # Create the tool specification
>>> calculator_add_tool = Tool(
>>>   name="calculator_add",
>>>   description="Calculates the addition of two numbers",
>>>   parameters=calculator_add_json_schema
>>> )
>>> # Send the chat completion request with the tool
>>> response = bc.get_chat_completion([
>>>   Message(Message.Role.USER, "What is 2 + 2?")
>>> ], tools=[calculator_add_tool])
>>> # Extract the tool use request and execute the tool
>>> if response.stop_reason == ChatCompletion.StopReason.TOOL_USE:
>>>   tool_use_request = response.content[-1]
>>>   print(tool_use_request.name)
>>>   print(tool_use_request.tool_input)
>>>   if tool_use_request.name == "calculator_add":
>>>     result = calculator_add(**tool_use_request.tool_input)
>>>     print(result)
calculator_add
{"a": 2, "b": 2}
4

get_text_embeddings(text, model_id=None, config=None)

Gets the embeddings for the given texts. The embeddings are returned in the same order as the original texts.

Parameters:

text (Sequence[str]) – The texts to embed.
model_id (EmbeddingModel, optional) – The embedding model. If omitted, the default model is used EmbeddingModel.AMAZON_TITAN_TEXT.
config (dict[str, str], optional) – The config with the inference parameters.

Returns:

the text embeddings

Return type:

Sequence[Embedding]

Chat

class ChatCompletion(content, stop_reason)

Bases: object

class StopReason(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Stop reasons for stopping the chat completion.

END_TURN: The chat completion ended because it reached the end of a turn and successfully generated a response.
MAX_TOKENS: The chat completion ended because it reached the maximum number of tokens it may generate.
STOP_SEQUENCE: The chat completion ended because it encountered a stop sequence specified in the request.
TOOL_USE: The chat completion ended because it requests the use of a tool.

END_TURN = 'END_TURN'

MAX_TOKENS = 'MAX_TOKENS'

STOP_SEQUENCE = 'STOP_SEQUENCE'

TOOL_USE = 'TOOL_USE'

get_message()

Gets a Message from the chat completion. The role is always Message.Role.ASSISTANT.

Returns:: The chat message.
Return type:: Message

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with the keys ‘content’ and ‘stopReason’.
Return type:: dict

property content

Returns:: A sequence of content blocks.
Return type:: Sequence[ContentBlock]

property stop_reason

Returns:: The reason for stopping the chat completion.
Return type:: ChatCompletion.StopReason

class ChatInferenceConfig(max_token_count=None, stop_sequences=None, temperature=None, top_p=None, extra_inference_params=None)

Bases: object

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with the inference configuration parameters.
Return type:: dict

property extra_inference_params

Returns:: The additional model-specific inference parameters.
Return type:: dict[str, str]

property max_token_count

Returns:: The maximum number of tokens to be generated.
Return type:: int

property stop_sequences

Returns:: The stop sequences that determine when the output generation should terminate.
Return type:: Sequence[str]

property temperature

Returns:: The temperature of the model to control the randomness (‘creativity’) of the output.
Return type:: float

property top_p

Returns:: The top cumulative probability limit of token candidates to consider.
Return type:: float

class ContentBlock(blockType)

Bases: object

class Type(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

The content block types.

DOCUMENT = 'DOCUMENT'

IMAGE = 'IMAGE'

JSON = 'JSON'

TEXT = 'TEXT'

TOOL_RESULT = 'TOOL_RESULT'

TOOL_USE = 'TOOL_USE'

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with the key ‘type’.
Return type:: dict

property type

Returns:: The content block type.
Return type:: ContentBlock.Type

class DocumentBlock(source, docFormat, name)

Bases: ContentBlock

class Format(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

The supported document formats.

CSV = 'CSV'

DOC = 'DOC'

DOCX = 'DOCX'

HTML = 'HTML'

MD = 'MD'

PDF = 'PDF'

TXT = 'TXT'

XLS = 'XLS'

XLSX = 'XLSX'

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with the keys ‘type’, ‘format’, ‘name’, and ‘source’.
Return type:: dict

property format

Returns:: The document format.
Return type:: DocumentBlock.Format

property name

Returns:: The document name.
Return type:: str

property source

Returns:: The document as a base64-encoded string.
Return type:: str

class ImageBlock(source, imgFormat)

Bases: ContentBlock

class Format(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

The supported image formats.

GIF = 'GIF'

JPEG = 'JPEG'

PNG = 'PNG'

WEBP = 'WEBP'

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with the keys ‘type’, ‘format’, and ‘source’.
Return type:: dict

property format

Returns:: The image format.
Return type:: ImageBlock.Format

property source

Returns:: The image as a base64-encoded string.
Return type:: str

class JsonBlock(json)

Bases: ContentBlock

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary that represents the JSON content.
Return type:: dict

property json

Returns:: The JSON content.
Return type:: Mapping

class Message(role, content)

Bases: object

class Role(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

The message roles in a chat.

ASSISTANT = 'ASSISTANT'

USER = 'USER'

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with keys ‘role’ and ‘content’.
Return type:: dict

property content

Returns:: The message content.
Return type:: str | Sequence[ContentBlock]

property role

Returns:: The message role.
Return type:: Message.Role

class TextBlock(text)

Bases: ContentBlock

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with the keys ‘type’ and ‘text’.
Return type:: dict

property text

Returns:: The text content.
Return type:: str

class Tool(name, description, parameters)

Bases: object

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with the keys ‘name’, ‘description’, and ‘parameters’.
Return type:: dict

property description

Returns:: The description of the tool.
Return type:: str

property name

Returns:: The name of the tool.
Return type:: str

property parameters

Returns:: The tool input described as a JSON schema object.
Return type:: dict

class ToolChoice(tool_choice_type, name=None)

Bases: object

class Type(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Tool choice type determines how a model should choose a tool.

AUTO: Lets the model decide whether to use a tool or not.
ANY: Makes the model choose at least one tool to use.
SPECIFIC: Makes the model use a specific tool.

ANY = 'ANY'

AUTO = 'AUTO'

SPECIFIC = 'SPECIFIC'

classmethod any()

Factory method to create a tool choice with type ToolChoice.Type.ANY.

Returns:: Tool choice with type ToolChoice.Type.ANY.
Return type:: ToolChoice

classmethod auto()

Factory method to create a tool choice with type ToolChoice.Type.AUTO.

Returns:: Tool choice with type ToolChoice.Type.AUTO.
Return type:: ToolChoice

classmethod specific(name)

Factory method to create a tool choice with type ToolChoice.Type.SPECIFIC.

Parameters:: name (str) – The name of the tool to use.
Returns:: Tool choice with type ToolChoice.Type.SPECIFIC.
Return type:: ToolChoice

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with the keys ‘type’ and optionally ‘name’ if the type is ToolChoice.Type.SPECIFIC.
Return type:: dict

property name

Returns:: The name of the tool to use.
Return type:: str

property type

Returns:: The tool choice type.
Return type:: ToolChoice.Type

class ToolResultBlock(tool_use_id, result)

Bases: ContentBlock

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with the keys ‘type’, ‘tool_use_id’, and ‘result’.
Return type:: dict

property result

Returns:: The results of the tool use.
Return type:: str | Sequence[TextBlock | DocumentBlock | ImageBlock | JsonBlock]

property tool_use_id

Returns:: The tool use request ID related to the tool result.
Return type:: str

class ToolUseBlock(tool_use_id, name, tool_input)

Bases: ContentBlock

to_dict()

Converts the instance to a dictionary representation.

Returns:: A dictionary with the keys ‘type’, ‘toolUseId’, ‘name’, and ‘input’.
Return type:: dict

property name

Returns:: The tool name.
Return type:: str

property tool_input

Returns:: The tool input.
Return type:: dict

property tool_use_id

Returns:: The tool use request ID.
Return type:: str

Models

class ChatModel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The supported models for chat requests.

static get_default()

Returns the default chat model.

Returns:: The default chat model.
Return type:: ChatModel

AMAZON_NOVA_PRO = 'AMAZON_NOVA_PRO'

ANTHROPIC_CLAUDE_SONNET = 'ANTHROPIC_CLAUDE_SONNET'

class EmbeddingModel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The supported models for embedding requests.

AMAZON_TITAN_TEXT = 'AMAZON_TITAN_TEXT'

Embeddings

class Embedding(embedding)

to_dict(): Converts the instance to a dictionary representation. :return: A dictionary with the key ‘embedding’. :rtype: dict

property embedding

Returns:: Returns the embedding.
Return type:: Sequence[float]