kodeagent.kutils#

A minimal set of utilities used by KodeAgent. This module will be copied along with code for CodeAgent, so keep it minimum.

build_tool_schema

Auto-generate an OpenAI-style tool schema from a Python function.

call_llm

Call the LLM with the given parameters and response format.

clean_json_string

Clean and repair common JSON formatting issues from LLM responses.

combine_user_messages

Combines consecutive user messages into a single message with a list of content items.

detect_file_type

Identify the content/MIME type of file pointed by a URL.

get_logger

Get a logger for KodeAgent.

is_image_file

Identify whether a given MIME type is an image.

is_it_url

Check whether a given path is a URL.

make_user_message

Create a single user message to be sent to LiteLLM.

parse_param_descriptions

Extract per-parameter descriptions from a docstring.

read_prompt

Reads a prompt from the prompts directory.

validate_chat_history

Validate that a provided chat history is OpenAI-compliant.

A minimal set of utilities used by KodeAgent. This module will be copied along with code for CodeAgent, so keep it minimum.

kodeagent.kutils.build_tool_schema(fn: Callable, just_first_line: bool = False, as_text: bool = True) → dict[str, Any] | str[source]#

Auto-generate an OpenAI-style tool schema from a Python function.

Parameters:

  • fn – The function to build a tool schema for.

  • just_first_line – Whether to use only the first line of the docstring for the description.

  • as_text – Whether to return the schema as a formatted text instead of a dictionary.

Returns:

A dictionary representing the tool schema. Or a formatted text if as_text is True.

async kodeagent.kutils.call_llm(model_name: str, litellm_params: dict, messages: list[dict], response_format: type[BaseModel] | None = None, trace_id: str | None = None, max_retries: int = 3, usage_tracker: Any | None = None, component_name: str = 'unknown') → str | None[source]#

Call the LLM with the given parameters and response format.

Parameters:

  • model_name – The name of the LLM model to use.

  • litellm_params – Dictionary of parameters to pass to litellm.

  • messages – List of message dictionaries.

  • response_format – Optional pydantic model for structured output.

  • trace_id – Optional trace ID for observability.

  • max_retries – Maximum number of retries for the LLM call.

  • usage_tracker – Optional UsageTracker instance to record usage.

  • component_name – Name of the component making the call (for tracking).

Returns:

The LLM response as string.

Raises:

  • RetryError – If the LLM call fails after maximum retries.

  • ValueError – If the LLM returns an empty or invalid response body.

kodeagent.kutils.clean_json_string(json_str: str) → str[source]#

Clean and repair common JSON formatting issues from LLM responses.

Parameters:

json_str – Potentially malformed JSON string

Returns:

Cleaned JSON string

kodeagent.kutils.combine_user_messages(messages: list) → list[source]#

Combines consecutive user messages into a single message with a list of content items.

Returns:

A new list of messages with combined user messages.

kodeagent.kutils.detect_file_type(url: str) → str[source]#

Identify the content/MIME type of file pointed by a URL.

Parameters:

url – The URL to the file.

Returns:

The detected MIME type or Unknown file type.

kodeagent.kutils.get_logger(name: str | None = 'KodeAgent') → Logger[source]#

Get a logger for KodeAgent.

Returns:

A logger instance.

kodeagent.kutils.is_image_file(file_type) → bool[source]#

Identify whether a given MIME type is an image.

Parameters:

file_type – The file/content type.

Returns:

True if an image file; False otherwise.

kodeagent.kutils.is_it_url(path: str) → bool[source]#

Check whether a given path is a URL.

Parameters:

path – The path.

Returns:

True if it’s a URL; False otherwise.

kodeagent.kutils.make_user_message(text_content: str, files: list[str] | None = None) → list[dict[str, Any]][source]#

Create a single user message to be sent to LiteLLM.

Parameters:

  • text_content – The text content of the message.

  • files – An optional list of file paths or URLs, which can include images or other file types.

Returns:

A list of dict items representing the messages.

kodeagent.kutils.parse_param_descriptions(doc: str) → dict[str, str][source]#

Extract per-parameter descriptions from a docstring.

Supports Google-style (Args:) and Sphinx-style (:param name:) formats.

Parameters:

doc – The docstring to parse.

Returns:

A dictionary mapping parameter names to their descriptions.

kodeagent.kutils.read_prompt(filename: str) → str[source]#

Reads a prompt from the prompts directory.

Parameters:

filename – Name of the prompt file to read.

Returns:

The content of the prompt file as a string.

Raises:

  • FileNotFoundError – If the prompt file does not exist.

  • RuntimeError – If there is an error reading the file.

kodeagent.kutils.validate_chat_history(history: list[dict], tool_names: set[str] | None = None) → None[source]#

Validate that a provided chat history is OpenAI-compliant.

Performs stringent structural and semantic checks on each message. Raises ValueError with a precise description on the first problem found.

Parameters:

  • history – The chat history to validate. Must be a non-empty list[dict].

  • tool_names – Optional set of tool names registered on the agent. When provided, tool call names not in this set emit a logger.warning.

Raises:

ValueError – If the history fails any structural or compliance check.