kodeagent.models#

Data models for tasks, agent plans, chat messages, and agent responses. Uses Pydantic for data validation and serialization. This module defines various models (task, plan, observation, chat response) to structure the interactions and behaviors of agents.

`AgentPlan`	A structured plan for an agent to follow.
`AgentResponse`	Streaming response sent by an agent in the course of solving a task.
`ChatMessage`	Generic chat message.
`CodeActChatMessage`	Messages for the CodeActAgent with built-in validation.
`CodeReview`	Code review decision for CodeActAgent.
`ComponentUsage`	Aggregated usage for a specific component.
`ObserverResponse`	The response from the observer after analyzing the agent's behavior.
`PlanStep`	A single step in an agent's plan.
`ReActChatMessage`	Messages for the ReAct agent with built-in validation.
`Task`	Task to be solved by an agent.
`UsageMetrics`	Individual usage metrics for a single LLM call.

kodeagent.models.AGENT_RESPONSE_TYPES#

Defined types for agent responses.

alias of Literal[‘step’, ‘final’, ‘log’]

class kodeagent.models.AgentPlan(*, steps: list[PlanStep])[source]#

Bases: BaseModel

A structured plan for an agent to follow.

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.

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

steps: list[PlanStep]#: List of steps to accomplish the task.

class kodeagent.models.AgentResponse[source]#

Bases: TypedDict

Streaming response sent by an agent in the course of solving a task.

channel: str | None#: Optional channel name for the response.

metadata: dict[str, Any] | None#: Optional metadata associated with the response.

type: Literal['step', 'final', 'log']#

‘step’, ‘final’, or ‘log’.

Type:: Type of the response

value: Any#: Value of the response, varies by type.

class kodeagent.models.ChatMessage(*, role: Literal['user', 'assistant', 'system', 'tool'], content: Any, files: list[str] | None = None)[source]#

Bases: BaseModel

Generic chat message.

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.

content: Any#: Content of the message.

files: list[str] | None#: Optional list of file paths or URLs associated with the message.

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

role: Literal['user', 'assistant', 'system', 'tool']#: Role of the message sender.

class kodeagent.models.CodeActChatMessage(*, role: Literal['user', 'assistant', 'system', 'tool'] = 'assistant', content: str | None = None, files: list[str] | None = None, thought: str, code: str | None = None, final_answer: str | None = None, task_successful: bool = False)[source]#

Bases: ChatMessage

Messages for the CodeActAgent with built-in validation. Combines functionality of CodeActAgentResponse and CodeActChatMessage.

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.

code: str | None#: Python code with tool use to run; None when providing final answer.

content: str | None#: Content of the message. Always None for CodeAct messages.

final_answer: str | None#: Final answer for the task; set only in the final step.

property is_final: bool#: Check if this is a final answer.

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

role: Literal['user', 'assistant', 'system', 'tool']#: Role of the message sender. Defaults to ‘assistant’.

classmethod sanitize_code_xor_final_answer(data: Any) → Any[source]#: Sanitize code and final_answer to ensure mutual exclusivity.

task_successful: bool#: Task completed or failed? False when code is set.

thought: str#: Thoughts behind the code.

validate_mutual_exclusivity() → CodeActChatMessage[source]#

Ensure code execution and final answer are mutually exclusive.

Raises:: ValueError – If both code and final_answer are provided, or if neither is valid.

class kodeagent.models.CodeReview(*, is_secure: bool, reason: str)[source]#

Bases: BaseModel

Code review decision for CodeActAgent.

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.

is_secure: bool#: Is the code safe & secure for execution?

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reason: str#: A brief explanation of the decision.

class kodeagent.models.ComponentUsage(*, component_name: str, call_count: int = 0, total_prompt_tokens: int = 0, total_completion_tokens: int = 0, total_tokens: int = 0, total_cost: float = 0.0)[source]#

Bases: BaseModel

Aggregated usage for a specific component.

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.

call_count: int#: Number of LLM calls made by the component.

component_name: str#: Name of the component (e.g., Planner, Observer, Agent).

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total_completion_tokens: int#: Total completion tokens used by the component.

total_cost: float#: Total cost in USD for the component.

total_prompt_tokens: int#: Total prompt tokens used by the component.

total_tokens: int#: Total tokens used by the component.

kodeagent.models.MESSAGE_ROLES#

Defined roles for chat messages.

alias of Literal[‘user’, ‘assistant’, ‘system’, ‘tool’]

class kodeagent.models.ObserverResponse(*, is_progressing: bool, is_in_loop: bool, reasoning: str, correction_message: str | None)[source]#

Bases: BaseModel

The response from the observer after analyzing the agent’s behavior.

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.

correction_message: str | None#: A specific, actionable feedback to help the agent self-correct.

is_in_loop: bool#: True if the agent is stuck in a repetitive loop.

is_progressing: bool#: True if the agent is making meaningful progress on the plan.

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reasoning: str#: A short reason for the assessment (max 15–20 words).

class kodeagent.models.PlanStep(*, description: str, is_done: bool = False)[source]#

Bases: BaseModel

A single step in an agent’s plan.

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.

description: str#: A brief description of the step.

is_done: bool#: Whether the step has been completed.

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class kodeagent.models.ReActChatMessage(*, role: Literal['user', 'assistant', 'system', 'tool'] = 'assistant', content: str | None = None, files: list[str] | None = None, thought: str, action: str, args: str | None = None, final_answer: str | None = None, task_successful: bool = False)[source]#

Bases: ChatMessage

Messages for the ReAct agent with built-in validation. Combines functionality of ReActAgentResponse and ReActChatMessage.

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.

action: str#: Name of the tool to use from available tools, or ‘FINISH’ to provide final answer.

args: str | None#: Tool arguments as JSON string; None when final_answer is available.

content: str | None#: Content of the message. Always None for ReAct messages.

final_answer: str | None#: Final answer for the task; set only in the final step.

property is_final: bool#: Check if this is a final answer.

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

role: Literal['user', 'assistant', 'system', 'tool']#: Role of the message sender. Defaults to ‘assistant’.

classmethod sanitize_action_xor_final_answer(data: Any) → Any[source]#: Sanitize action and final_answer to ensure mutual exclusivity.

task_successful: bool#: Task completed or failed? False when args is set.

thought: str#: Thoughts behind the tool use.

classmethod validate_args_json(v: str | None) → str | None[source]#

Validate that args is valid JSON and normalize it.

Parameters:: v – The args string to validate.
Returns:: The normalized JSON string if valid, else None.

validate_mutual_exclusivity() → ReActChatMessage[source]#

Ensure tool call and final answer are mutually exclusive.

Raises:: ValueError – If both action and final_answer are provided, or if neither is valid.

class kodeagent.models.Task(*, id: str = <factory>, description: str, files: list[str] | None = None, result: ~typing.Any | None = None, is_finished: bool = False, is_error: bool = False, output_files: list[str] = <factory>, steps_taken: int = 0, total_llm_calls: int = 0, total_prompt_tokens: int = 0, total_completion_tokens: int = 0, total_tokens: int = 0, total_cost: float = 0.0, usage_by_component: dict[str, dict] | None = None)[source]#

Bases: BaseModel

Task to be solved by an agent.

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.

description: str#: Task description.

files: list[str] | None#: A list of file paths or URLs.

id: str#: Auto-generated task ID.

is_error: bool#: Whether the task execution resulted in any error.

is_finished: bool#: Whether the task has finished running.

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_files: list[str]#: List of file paths generated during task execution.

result: Any | None#: Task result.

steps_taken: int#: Number of steps/iterations taken by the agent for this task.

total_completion_tokens: int#: Total completion tokens used.

total_cost: float#: Total cost in USD for all LLM calls.

total_llm_calls: int#: Total number of LLM calls made during task execution.

total_prompt_tokens: int#: Total prompt tokens used.

total_tokens: int#: Total tokens used (prompt + completion).

usage_by_component: dict[str, dict] | None#: Breakdown of usage by component (Planner, Observer, Agent).

class kodeagent.models.UsageMetrics(*, prompt_tokens: int = 0, completion_tokens: int = 0, total_tokens: int = 0, cost: float = 0.0)[source]#

Bases: BaseModel

Individual usage metrics for a single LLM call.

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.

completion_tokens: int#: Number of completion tokens used.

cost: float#: Cost in USD for the LLM call.

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

prompt_tokens: int#: Number of prompt tokens used.

total_tokens: int#: Total tokens used (prompt + completion).

kodeagent.models#

This Page