assistant.modules.assistant

Classes

Assistant

Provides LLM-powered utilities within a ViUR module context.

Module Contents

class assistant.modules.assistant.Assistant

Bases: viur.core.prototypes.Singleton

Provides LLM-powered utilities within a ViUR module context.

This class includes various AI-assisted features such as script generation, image description, and language-aware prompting. It is designed to be used in the context of a ViUR admin and integrates with services like OpenAI and Anthropic.

Responsibilities:

  • Generating backend scripts from user instructions and data models.

  • Producing accessible image descriptions (e.g., for alt attributes).

  • Translate text.

  • Managing prompt and API settings.

Integrated Services:

  • OpenAI (e.g., GPT) for image description generation and translations.

  • Anthropic Claude for structured script generation with reasoning capabilities.

Configuration can be made in

  • this singleton skel itself.

  • The backend configuration CONFIG.

Note

The methods in this module assumes a properly configured environment with API keys and AI model settings. However, you only need to configure what is actually used. Error handling is included for common failure modes such as misconfiguration or service unavailability.

kindName: Final[str] = 'viur-assistant'
generate_script(*, prompt, modules_to_include=None, enable_caching=False, max_thinking_tokens=0)

Generates a script based on a user prompt and optional module structures using a language model.

This method builds a structured prompt for the LLM Anthropic Claude and optionally includes application-specific module metadata to enrich the generation context. Additional configuration such as caching behavior and token budgeting for “thinking steps” can be provided.

Parameters:

  • prompt (str) – The main user instruction or query that guides the script generation.

  • modules_to_include (list[str]) – Optional list of module names whose structures should be included as part of the model context. These are injected into the LLM prompt as JSON.

  • enable_caching (bool) – If set to True, instructs the system to use ephemeral caching for the scriptor documentation prompt section.

  • max_thinking_tokens (int) – If greater than 0, enables the model’s “thinking” feature with a token budget for intermediate reasoning or planning steps.

Returns:

A JSON-encoded string of the model’s response, typically containing the generated script.

Raises:

InternalServerError –

  • If configuration (skel) is missing.

  • If the LLM request fails due to connection or model errors.

Note

  • Requires a valid anthropic_model configuration in the current context.

  • The actual parsing of the generated code (e.g., extracting specific script content) is currently marked as a TODO and has to be discussed.

get_viur_structures(modules_to_include)

Collect and return ViUR module structures for a given list of module names.

For each named module, its structure is extracted if it is of type List or Tree. Tree structures will return separate entries for node and leaf skeletons.

Parameters:

modules_to_include (Iterable[str]) – List of ViUR module names to retrieve structures for.

Returns:

A dictionary mapping module names to their respective structure definitions. For Tree modules, nested keys "node" and "leaf" are returned.

Raises:

ValueError – If a module exists but is not a supported type (i.e., not List or Tree).

Return type:

dict[str, dict]

Note

Modules that are missing or not found are silently skipped.

translate(*, text, language, characteristic=None)

Translate a given text into a target language, optionally using a specific style.

This method sends the input text to OpenAI with instructions to translate it into the requested language, optionally applying predefined translation characteristics such as simplification.

Parameters:

  • text (str) – The source text to translate.

  • language (str) – The target language code (e.g. "de", "en", "de-x-simple").

  • characteristic (Optional[str]) – Optional translation style (e.g. "simplified", "formal", etc.) as defined in CONFIG.translate_language_characteristics.

Returns:

Translated text as a plain string. HTML tags from the original text are preserved.

Raises:

InternalServerError – If configuration is missing.

Note

  • The translation style is determined by merging base rules (*) and the selected characteristic.

  • The returned translation contains only the translated text, with no explanation or additional formatting.

describe_image(filekey, prompt='', context='', language=None)

Generate an HTML alt attribute description for a given image using OpenAi.

This method reads an image via its filekey, resizes it to a configured pixel target, and sends it along with optional prompt and context data to an OpenAI model. The model returns a plain-text alternative description for accessibility purposes, formatted as an HTML alt text in the specified language.

Parameters:

  • filekey (viur.core.db.Key | str) – Key identifying the image file in the ViUR file module. (Key of the file skeleton).

  • prompt (str) – Optional user-defined hint or instruction for how the image should be interpreted.

  • context (str) – Optional additional background information to support a better description.

  • language (str | None) – Target language code for the generated description (e.g., "en", "de-x-simple"). Falls back to the current session language if not specified.

Returns:

A plain-text string suitable for use in an HTML alt attribute (no quotes or labels).

Raises:

  • InternalServerError – If required configuration is missing.

  • NotFound – If the referenced image file could not be loaded.

Note

  • The image is resized and converted to JPEG before being sent to the model.

  • This function uses a preconfigured OpenAI model, pixel count, and JPEG quality settings.

_get_resized_image_bytes(image, target_pixel_count, jpeg_quality=50)

Resize an image to approximately match a target total pixel count and return it as a JPEG byte stream.

The image is scaled proportionally to meet the target pixel count (width × height), while preserving the original aspect ratio. If the resized dimensions would exceed the original image size, no upscaling is performed. The result is encoded as a JPEG.

Parameters:

  • image (IO[bytes] | str | bytes | os.PathLike[str] | os.PathLike[bytes]) – Input image, provided as a file-like object, byte string, file path, or raw bytes.

  • target_pixel_count (int) – Desired total number of pixels for the resized image. Used to compute the new dimensions.

  • jpeg_quality (int) – JPEG compression quality (0 to 100). Higher values yield better image quality at the cost of file size. Default is 50.

Returns:

The resized and JPEG-compressed image as a byte stream.

Raises:

ValueError – If jpeg_quality is not in the 0–100 range or the image input is invalid.

Note

  • Images in PNG, SVG, or WEBP format are automatically converted to RGB JPEG.

  • This function is intended for preprocessing images before passing them to AI models, balancing detail and data size.

openai_create_completion(*, model, messages, **kwargs)

Creates a model response in a new chat conversation.

Uses OpenAI API and structured JSON format, see https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses#json-mode .

Parameters:

  • model (str | openai.types.ChatModel) – Model ID used to generate the response, like gpt-4o or o3.

  • messages (Iterable[openai.types.chat.ChatCompletionMessageParam]) – A list of messages comprising the conversation.

  • kwargs – Additional arguments passing to the client.

Returns:

The response in plain text on success.

Raises:

errors.HTTPException – If an API error occurs.

render_text(text)

Render the give text as usual for the current renderer.

If the current renderer is the JSON renderer, JSON string is returned and the content-type header is also set to JSON.

Parameters:

text (str) – The text to render.

Return type:

Any