Describe

azure_openai_describe_rows

azure_openai_describe_rows(document_version, invoice_description=None, batch_size=50, max_characters=200000, system_prompt=None, api_key=None, azure_endpoint=None, api_version=None, model=None, temperature=None, max_retries=5, provider=None, base_url=None, openai_client=None)

Describe every line item across all sheets of a document for classification.

Generates a plain-English description for each row, batching rows into single LLM calls (default 50 per call) so the model sees related line items together — their shared context improves each description — while keeping any one prompt bounded. Descriptions are matched back to rows by an echoed integer key rather than list position, and each batch is validated and retried, so a dropped or reordered item does not silently mis-label subsequent rows.

The returned map is keyed by SheetItem.id (the stable per-row id), ready to look up per row in a downstream classification loop, e.g. a template step {{ row_descriptions[current_row.id] }}.

Parameters:

Name	Type	Description	Default
`document_version`	`DocumentVersion`	The document whose sheet rows will be described.	required
`invoice_description`	`str \| None`	Document-level context for the rows. If not provided, the persisted `document_summary` result is used.	`None`
`batch_size`	`int`	Maximum number of rows per LLM call. Defaults to 50.	`50`
`max_characters`	`int`	Character cap on each batch's user prompt.	`200000`
`system_prompt`	`str \| None`	Override the default row-description prompt. A custom prompt must still instruct the model to return the documented `{"descriptions": [{"key", "description"}]}` shape.	`None`
`api_key`	`str \| None`	API key for the Azure OpenAI resource.	`None`
`azure_endpoint`	`str \| None`	Endpoint URL for the Azure OpenAI resource.	`None`
`api_version`	`str \| None`	API version for the Azure OpenAI resource.	`None`
`model`	`str \| None`	Model deployment name within the Azure resource.	`None`
`temperature`	`float \| None`	Sampling temperature.	`None`
`max_retries`	`int`	Maximum attempts per batch (covers both transient API errors and response-validation failures).	`5`
`openai_client`	`LanguageModelClient \| None`	Optional AzureOpenAIClient to reuse. Should be configured for JSON mode (`response_format={"type": "json_object"}`). If not provided, a JSON-mode client is created.	`None`

Returns:

Type	Description
`dict[str, str]`	A mapping of `row_id -> description`. Rows the model failed to
`dict[str, str]`	describe (after retries) map to an empty string rather than being
`dict[str, str]`	omitted, so callers can rely on every row id being present.

azure_openai_description

azure_openai_description(content=None, metadata=None, image_url=None, image_detail='high', max_characters=200000, max_metadata_characters=50000, system_prompt=None, api_key=None, azure_endpoint=None, api_version=None, model=None, temperature=None, max_retries=5, provider=None, base_url=None, openai_client=None)

Generates a description from the provided container content, metadata and image. Uses the Azure OpenAI service.

Parameters:

Name	Type	Description	Default
`content`	`str \| None`	The main-body of the prompt	`None`
`metadata`	`dict \| None`	Any additional information describing the content	`None`
`image_url`	`str \| None`	A signed or public URL where an image can be found	`None`
`image_detail`	`str`	Vision fidelity for the image — "high" (default; full tiling, best for reading text), "low" (downscaled to 512x512, cheap) or "auto".	`'high'`
`max_characters`	`int`	Maximum number of text characters (excluding images) from `content` to be included in the prompt. Any additional characters are trimmed from `content`.	`200000`
`max_metadata_characters`	`int`	Maximum number of characters of the JSON-serialised metadata to include in the prompt. Defaults to 50000 (~12.5k tokens). Per-extractor metadata payloads can balloon to hundreds of KB (e.g. APS Model Derivative emits a per-view object property tree with thousands of objects), which can overshoot the model's context window. Anything past this cap is truncated with a marker.	`50000`
`system_prompt`	`str \| None`	Overrides the default prompt	`None`
`api_key`	`str \| None`	Access key for the Azure OpenAI resource	`None`
`azure_endpoint`	`str \| None`	Your Azure endpoint, including the resource, e.g. https://example-resource.azure.openai.com/. if not provided will default to environment variable `AZURE_OPENAI_ENDPOINT`.	`None`
`api_version`	`str \| None`	API version for Azure resource.	`None`
`model`	`str \| None`	Model deployment name within the Azure resource. If not provided will default to environment variable `AZURE_OPENAI_DEPLOYMENT`.	`None`
`max_retries`	`int`	Maximum number of unsuccessful call attempts to the OpenAI service before returning an error.	`5`

Returns:

Type	Description
`str`	A plain-text description of the input content.

azure_openai_description_row

azure_openai_description_row(content=None, max_characters=200000, system_prompt=None, api_key=None, azure_endpoint=None, api_version=None, model=None, temperature=None, max_retries=5, provider=None, base_url=None, openai_client=None)

Generates a short (3-7 word) description from the provided string or dictionary. Expects the input to be a construction material, activity or other built environment related concept. Uses the Azure OpenAI service.

Parameters:

Name	Type	Description	Default
`content`	`str \| dict \| None`	The main-body of the prompt	`None`
`max_characters`	`int`	Maximum number of text characters from `content` to be included in the prompt. Any additional characters are trimmed from `content`.	`200000`
`system_prompt`	`str \| None`	Overrides the default prompt	`None`
`api_key`	`str \| None`	Access key for the Azure OpenAI resource	`None`
`azure_endpoint`	`str \| None`	Your Azure endpoint, including the resource, e.g. https://example-resource.azure.openai.com/. if not provided will default to environment variable `AZURE_OPENAI_ENDPOINT`.	`None`
`api_version`	`str \| None`	API version for Azure resource.	`None`
`model`	`str \| None`	Model deployment name within the Azure resource. If not provided will default to environment variable `AZURE_OPENAI_DEPLOYMENT`.	`None`
`max_retries`	`int`	Maximum number of unsuccessful call attempts to the OpenAI service before returning an error.	`5`
`openai_client`	`LanguageModelClient \| None`	Optional AzureOpenAIClient instance to reuse. If not provided, a new client will be created. Providing a shared client instance improves performance in concurrent scenarios.	`None`

Returns:

Type	Description
`str`	A plain-text description of the input content.

content_list_generator

content_list_generator(text, metadata=None, image_url=None, n=10, api_key=None, azure_endpoint=None, api_version=None, model=None, temperature=None, max_retries=5, provider=None, base_url=None)

Generates a list of up to 10 key document 'atomic' themes, for the purpose of creating a spread of Uniclass (or other) classifications that describe a document.

Parameters:

Name	Type	Description	Default
`text`	`str`	Content of the document	required
`metadata`	`dict \| None`	Dictionary of metadata for the document	`None`
`image_url`	`str \| None`	Image of the document (if applicable)	`None`
`n`	`int`	Number of themes to provide	`10`

Returns:

Type	Description
`list[str]`	A markdown formatted list of themes