ractogateway.prompts.engine

RACTO Prompt Engine — structured, anti-hallucination prompt compilation.

The RactoPrompt model enforces the RACTO principle:

R ole — Who the model is. A im — What it must accomplish. C onstraints — Hard boundaries it must never violate. T one — Communication style. O utput — The exact shape of the expected response.

class ractogateway.prompts.engine.RactoFile(data, mime_type, name='')

Bases: object

A file attachment that can be passed to RactoPrompt.to_messages().

Create from a file path (MIME type is auto-detected) or directly from raw bytes with an explicit MIME type.

Parameters:

• data (bytes) – Raw bytes of the file.

• mime_type (str) – MIME type string, e.g. "image/jpeg" or "application/pdf".

• name (str) – Optional filename hint used for display / debugging.

Examples

>>> # From a file path
>>> img = RactoFile.from_path("/tmp/photo.jpg")

>>> # From bytes
>>> img = RactoFile.from_bytes(open("photo.jpg", "rb").read(), "image/jpeg")

classmethod from_path(path)

Load a file from path and auto-detect its MIME type.

Parameters:

path (str | Path) – Absolute or relative path to the file on disk.

Raises:

FileNotFoundError – If path does not exist.

Return type:

RactoFile

classmethod from_bytes(data, mime_type, name='')

Create a RactoFile directly from data bytes.

Parameters:

• data (bytes) – Raw file bytes.

• mime_type (str) – MIME type of the data, e.g. "image/png".

• name (str) – Optional filename string (no file I/O is performed).

Return type:

RactoFile

property base64_data: str

Return file bytes encoded as a base-64 ASCII string.

property is_image: bool

True when the MIME type is a supported image type.

property is_pdf: bool

property is_text: bool

class ractogateway.prompts.engine.RactoPrompt(**data)

Bases: BaseModel

A strictly validated RACTO prompt definition.

Parameters:

• role (str) – A sentence (or short paragraph) describing who the LLM is.

• aim (str) – A clear statement of the task objective.

• constraints (list[str]) – Hard rules the model must obey. At least one is required.

• tone (str) – The desired communication style (e.g. “Professional and concise”).

• output_format (str | type[BaseModel]) – Either a format keyword ("json", "text", "markdown"), a free-form format description, or a Pydantic model class whose JSON Schema will be embedded in the prompt.

• context (str | None) – Optional extra context paragraph injected between AIM and CONSTRAINTS. Useful for passing domain-specific background knowledge that the model needs to reason about.

• examples (list[dict[str, str]] | None) – Optional list of example input/output pairs that are included in the prompt to steer the model via few-shot learning.

• anti_hallucination (bool) – When True (the default), the compiler appends explicit anti-hallucination directives at the end of the prompt.

Notes

Legacy compatibility:

Older RactoGateway versions accepted instructions without the full RACTO field set. That shape is still accepted and mapped to aim with sensible defaults for missing RACTO fields.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

role: str

aim: str

constraints: list[str]

tone: str

output_format: str | type[BaseModel]

context: str | None

examples: list[dict[str, str]] | None

anti_hallucination: bool

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

compile()

Compile the RACTO fields into an optimized system prompt string.

The resulting prompt is structured into clearly delimited sections so that the LLM can parse each instruction block unambiguously.

Return type:

str

Returns:

str – A ready-to-use system prompt.

to_messages(user_message, *, attachments=None, provider='generic')

Return a ready-to-send message list for a given LLM provider.

Parameters:

• user_message (str) – The end-user’s query or input.

• attachments (list[RactoFile] | None) –

  Optional list of RactoFile objects to send alongside the text message. Accepted inputs per file:

  • File path — use RactoFile.from_path():

    RactoFile.from_path("/tmp/diagram.png")
    

  • Raw bytes — use RactoFile.from_bytes():

    RactoFile.from_bytes(img_bytes, "image/png")
    

  Each file is re-encoded into the content-block schema expected by the target provider (image_url for OpenAI, image / document for Anthropic, inline_data for Google, images list for Ollama).

• provider (str) – One of "openai", "anthropic", "google", "ollama", or "generic". Controls the system-role key name and the content-block format used for attachments.

Return type:

list[dict[str, Any]]

Returns:

list[dict[str, Any]] – A list of message dicts suitable for the provider’s API.