Documentation – KeGAL Internal Modules¶

This document covers the internal modules that power the KeGAL framework: the LLM abstraction layer (kegal.llm.*), the graph compiler (kegal.compiler), the prompt composer (kegal.compose), the utilities (kegal.utils), and the MCP handler (kegal.mcp_handler).

Most users never interact with these modules directly — the Compiler class is the public entry point. This reference is useful when extending the framework, writing custom LLM backends, or debugging graph execution.

Important – Any secrets, AWS keys, or personal access tokens that appear in the example files have been replaced with an empty string ("") for safety.

1. `kegal.llm.init`¶

The package’s __init__ simply re‑exports the public LLM classes so they can be imported directly from kegal.llm.

from kegal.llm import (
    LlmModel,
    LlmHandler,
    LlmAnthropic,
    LlmOpenai,
    LlmOllama,
    LlmBedrock,
    LlmGemini,
)

Provider classes are imported on demand — the corresponding SDK package (anthropic, openai, ollama, boto3, google-genai) is loaded only when the class is instantiated, not when kegal is imported. This means import kegal works even if only one provider's SDK is installed.

2. `kegal.llm.llm_model`¶

This module defines the core abstract base class (LlmModel) and the Pydantic models that represent the data structures used throughout the framework.

`LlmModel` (Abstract Base Class)¶

Public methods

Method	Purpose
`complete(...)`	Main entry point for generating a response from an LLM. Returns an `LLMResponse` with the text output, token counts, and any tool calls.
`extract_format_from_media_type(media_type: str)`	Normalises a MIME type string (e.g. `"image/jpg"` → `"jpeg"`).
`extract_images_from_pdf(pdf: LLMPdfData)`	Extracts embedded images from a PDF and returns them as `LLMImageData` objects.

Abstract methods (implemented by each concrete subclass — not called directly)

Method	Purpose
`_chat_message(...)`	Convert a plain string into the provider-specific chat message format.
`_chat_history(...)`	Convert a list of `LLMMessage` objects into the provider-specific history format.
`_images_data(...)`	Convert `LLMImageData` objects into the provider-specific image payload.
`_pdfs_data(...)`	Convert `LLMPdfData` objects into the provider-specific document payload.
`_tools_data(...)`	Convert `LLMTool` objects into the provider-specific function-call schema.
`_structured_output_data(...)`	Convert an `LLMStructuredOutput` into the provider-specific schema constraint.

Note – You never call these methods directly. complete() assembles the full provider request internally. To add a new LLM backend, subclass LlmModel and implement the abstract methods above.

Pydantic Models¶

`LLMImageData`¶

Field	Type	Optional	Description
`media_type`	`str`	No	MIME type of the image (e.g. `"image/png"`).
`image_b64`	`str`	No	Base‑64 encoded image data.

`LLMPdfData`¶

Field	Type	Optional	Description
`doc_b64`	`str`	No	Base‑64 encoded PDF file.

`LLMTool`¶

Field	Type	Optional	Description
`name`	`str`	No	Name of the tool.
`description`	`str`	No	Short description.
`parameters`	`dict[str, LLMStructuredSchema]`	No	JSON‑schema‑style definitions of expected arguments.
`required`	`list[str]`	No	Required parameter names.

`LLMStructuredSchema`¶

The most commonly used fields:

Field	Type	Optional	Description
`type`	`str`	Yes	JSON schema type (`"string"`, `"boolean"`, `"number"`, `"integer"`, `"object"`, `"array"`).
`enum`	`list[Any]`	Yes	Allowed literal values.
`description`	`str`	Yes	Human-readable description shown to the LLM.
`properties`	`dict[str, Any]`	Yes	For `"object"` types: nested field schemas.
`items`	`dict[str, Any]`	Yes	For `"array"` types: schema for each element.
`required`	`list[str]`	Yes	Required property names for objects.

The full schema supports all JSON Schema Draft 2020-12 keywords (min/max, pattern, allOf, anyOf, etc.). See graph_doc.md §11 LLMStructuredSchema for the complete field reference.

`LLMStructuredOutput`¶

Field	Type	Optional	Description
`json_output`	`LLMStructuredSchema`	No	The JSON schema the LLM must conform to in its response.

`LLMMessage`¶

Field	Type	Optional	Description
`role`	`str`	No	`"user"`, `"assistant"`, or `"system"`.
`content`	`str`	No	The text content of the message.

3. `kegal.llm.llm_handler`¶

LLMHandler is the factory that selects and instantiates the correct concrete LLM backend based on the llm field in a GraphModel entry. The Compiler calls it once per model during initialisation; users never need to call it directly.

class LLMHandler:
    def __init__(self, model_config: GraphModel) -> None
    def get_llm_instance(self) -> LlmModel

Argument	Type	Description
`model_config`	`GraphModel`	Configuration for a single LLM (model name, provider, credentials).

get_llm_instance() reads model_config.llm and returns the matching subclass:

`GraphModel.llm` value	Concrete class	Provider
`"anthropic"`	`LlmAnthropic`	Anthropic API (direct)
`"anthropic_aws"`	`LlmAnthropic`	Anthropic via AWS Bedrock inference profile
`"bedrock"`	`LlmBedrock`	Amazon Bedrock (native Bedrock models, e.g. Nova)
`"ollama"`	`LlmOllama`	Ollama local server
`"openai"`	`LlmOpenai`	OpenAI API

4. `kegal.llm.llm_anthropic`¶

Concrete implementation for Anthropic (direct API via llm: "anthropic", or Bedrock inference profile via llm: "anthropic_aws"). Instantiated automatically by LLMHandler — not created directly.