Skip to main content

Choice

A Choice represents a single response alternative within a chat completion response. You get one by calling response.create_choice() or response.create_single_choice().

Choice implements the context manager protocol. Using it as a context manager automatically calls open() on entry and close() on exit.

from aidial_sdk.chat_completion import Response

# Preferred: use as a context manager
with response.create_single_choice() as choice:
    choice.append_content("Hello!")

# Manual control (equivalent)
choice = response.create_single_choice()
choice.open()
choice.append_content("Hello!")
choice.close()

Streaming content​

append_content​

def append_content(self, content: str) -> None

Appends text to the choice's content. In streaming mode, each call sends a chunk to the client immediately. Call multiple times to stream content incrementally.

Raises RuntimeServerError if the choice is not open or already closed.

with response.create_single_choice() as choice:
    choice.append_content("The answer is ")
    choice.append_content("42.")

content_stream​

@property
def content_stream(self) -> ContentStream

Returns a ContentStream object that implements the write(str) method. This allows you to redirect output from standard library functions that accept file-like objects:

with response.create_single_choice() as choice:
    # Redirect print output
    print("Hello, world!", file=choice.content_stream)

    # Use with tqdm progress bars
    import tqdm
    for item in tqdm.tqdm(items, file=choice.content_stream):
        process(item)

    # Write CSV data
    import csv
    csv.writer(choice.content_stream).writerows(data)

    # Redirect logging
    import logging
    handler = logging.StreamHandler(stream=choice.content_stream)

Attachments​

add_attachment​

# From an Attachment object
def add_attachment(self, attachment: Attachment) -> None

# From individual fields
def add_attachment(
    self,
    type: str | None = None,
    title: str | None = None,
    data: str | None = None,
    url: str | None = None,
    reference_url: str | None = None,
    reference_type: str | None = None,
) -> None

Adds a file attachment to the choice. DIAL Chat renders attachments below the response content. You can call this multiple times to add multiple attachments.

Raises RuntimeServerError if the choice is not open or already closed.

with response.create_single_choice() as choice:
    choice.append_content("Here is the analysis:")
    choice.add_attachment(
        type="text/csv",
        title="results.csv",
        data="name,score\nAlice,95\nBob,87",
    )

Stages​

create_stage​

def create_stage(self, name: str | None = None) -> Stage

Creates a Stage for reporting intermediate progress. Stages appear as expandable sections in DIAL Chat, showing the user what your application is doing internally (for example, retrieving documents, calling APIs, or processing data).

You can create multiple stages within a choice. Each stage has its own content stream and attachments.

Raises RuntimeServerError if the choice is not open or already closed.

with response.create_single_choice() as choice:
    with choice.create_stage("Retrieving documents") as stage:
        stage.append_content("Found 3 relevant documents.")
        stage.add_attachment(type="text/plain", title="doc1.txt", data="...")

    choice.append_content("Based on the retrieved documents...")

Tool calls​

create_function_tool_call​

def create_function_tool_call(
    self,
    id: str,
    name: str,
    arguments: str | None = None,
) -> FunctionToolCall

Creates a function tool call. Use this when your application acts as a model that supports the tool use protocol. The returned FunctionToolCall object has an append_arguments(str) method for streaming the arguments incrementally.

Sets the choice's finish reason to FinishReason.TOOL_CALLS.

with response.create_single_choice() as choice:
    tool_call = choice.create_function_tool_call(
        id="call_abc123",
        name="get_weather",
        arguments='{"location": "London"}',
    )

Streaming arguments:

with response.create_single_choice() as choice:
    tool_call = choice.create_function_tool_call(
        id="call_abc123",
        name="get_weather",
    )
    tool_call.append_arguments('{"location":')
    tool_call.append_arguments(' "London"}')

create_function_call​

def create_function_call(
    self,
    name: str,
    arguments: str | None = None,
) -> FunctionCall

Creates a legacy function call. The returned FunctionCall object has an append_arguments(str) method for streaming.

Sets the choice's finish reason to FinishReason.FUNCTION_CALL. Only one function call per choice is allowed.

State and forms​

set_state​

def set_state(self, state: Any) -> None

Sets opaque application state that is round-tripped through DIAL Chat. The state is included in the custom_content.state field of the assistant message in subsequent requests. Use this to maintain conversation context without relying on the message content.

Raises RuntimeServerError if called twice or if the choice is not open.

set_form_schema​

def set_form_schema(self, form_schema: Any) -> None

Sets a JSON Schema that DIAL Chat renders as an interactive form. When the user submits the form, the values arrive in custom_content.form_value of the next user message.

Raises RuntimeServerError if called twice or if the choice is not open.

with response.create_single_choice() as choice:
    choice.append_content("Please configure the report:")
    choice.set_form_schema({
        "type": "object",
        "properties": {
            "format": {"type": "string", "enum": ["pdf", "csv", "xlsx"]},
            "include_charts": {"type": "boolean", "default": True},
        },
        "required": ["format"],
    })

For forms with buttons, use the Button dataclass and form decorator from aidial_sdk.chat_completion.form.

Lifecycle​

open​

def open(self) -> None

Opens the choice for content generation. Called automatically when used as a context manager.

close​

def close(self, finish_reason: FinishReason | None = None) -> None

Closes the choice. If finish_reason is not provided, it is inferred from the last operation:

  • FinishReason.STOP if append_content was called.
  • FinishReason.TOOL_CALLS if create_function_tool_call was called.
  • FinishReason.FUNCTION_CALL if create_function_call was called.
  • FinishReason.STOP as the fallback.

Called automatically when the context manager exits.

Properties​

PropertyTypeDescription
indexintZero-based index of this choice in the response.
openedboolWhether open() has been called.
closedboolWhether close() has been called.

Further reading​