oats.session

Session management, message handling, compaction, and budgeting.

oats.session.models

oats.session.session

Session management for AI conversations.

class oats.session.session.SessionTime(**data)[source]

Bases: BaseModel

Timestamps for session lifecycle.

created

When the session was created.

updated

When the session was last updated.

archived

When the session was archived, if applicable.

created: datetime
updated: datetime
archived: datetime | None
model_config: ClassVar[ConfigDict] = {}

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

class oats.session.session.SessionInfo(**data)[source]

Bases: BaseModel

Metadata about a session.

id

Unique session identifier.

title

Human-readable session title.

project_dir

Path to the project root directory.

working_dir

Path to the current working directory.

time

Session lifecycle timestamps.

model_id

The model ID used for this session.

provider_id

The provider ID used for this session.

root_session_id

ID of the root session if this is a sub-session.

message_count

Total number of messages in the session.

total_tokens

Total tokens consumed across all completions.

parent_session_id

ID of the parent session if this is a child session.

model_config: ClassVar[ConfigDict] = {'protected_namespaces': ()}

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

id: str
title: str
project_dir: str
working_dir: str
time: SessionTime
model_id: str | None
provider_id: str | None
root_session_id: str | None
message_count: int
total_tokens: int
parent_session_id: str | None
class oats.session.session.Session(**data)[source]

Bases: BaseModel

A conversation session with messages.

Wraps SessionInfo metadata and a list of Message objects. Provides convenience methods for creating different message types and formatting messages for LLM APIs.

info

Session metadata (title, project dir, model, etc.).

messages

Ordered list of messages in the conversation.

info: SessionInfo
messages: list[Message]
property id: str

Return the session ID.

property title: str

Return the session title.

add_message(message)[source]

Add a message to the session.

Return type:

Message

Parameters:

message – The message to add.

Returns:

The added message.

create_user_message(content, images=None)[source]

Create and add a user message.

Return type:

Message

images is an optional list of dicts with keys:

media_type – e.g. “image/png” data – base64-encoded bytes (mutually exclusive with url) url – image URL (mutually exclusive with data)

create_assistant_message()[source]

Create and add an assistant message.

Return type:

Message

Returns:

The newly created assistant Message.

create_system_message(content)[source]

Create and add a system message.

Return type:

Message

Parameters:

content – The system message text.

Returns:

The newly created system Message.

get_messages_for_llm()[source]

Get messages formatted for LLM API.

Return type:

list[dict[str, Any]]

Returns:

A list of dicts in the format expected by provider APIs.

update_title(title)[source]

Update the session title.

Return type:

None

Parameters:

title – The new title for the session.

add_usage(usage)[source]

Add token usage from a completion.

Return type:

None

Parameters:

usage – Dict with token counts (total_tokens, etc.).

model_config: ClassVar[ConfigDict] = {}

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

class oats.session.session.SessionStorage[source]

Bases: object

Storage manager for sessions.

Handles CRUD operations for Session objects using the core Storage layer. Publishes lifecycle events (created, updated, deleted) to the event bus.

__init__()[source]

Initialize the session storage.

async create(session)[source]

Create a new session.

Return type:

Session

Parameters:

session – The session to create.

Returns:

The created session.

async get(session_id)[source]

Get a session by ID.

Return type:

Session | None

Parameters:

session_id – The session identifier.

Returns:

The Session if found, or None.

async update(session)[source]

Update a session.

Return type:

Session

Parameters:

session – The session to update.

Returns:

The updated session.

async delete(session_id)[source]

Delete a session.

Return type:

bool

Parameters:

session_id – The session identifier.

Returns:

True if the session was deleted.

async list()[source]

List all sessions.

Return type:

list[Session]

Returns:

A list of all Session objects.

async list_infos()[source]

List session infos only (lighter weight).

Return type:

list[SessionInfo]

Returns:

A list of SessionInfo objects without full message history.

oats.session.session.get_session_storage()[source]

Get the global session storage.

Lazily initializes a singleton SessionStorage on first call.

Return type:

SessionStorage

Returns:

The global SessionStorage instance.

async oats.session.session.create_session(project_dir, working_dir=None, title='New Session', model_id=None, provider_id=None, root_session_id=None)[source]

Create a new session.

Return type:

Session

Parameters:

  • project_dir – Path to the project root.

  • working_dir – Path to the working directory (defaults to project_dir).

  • title – Session title.

  • model_id – Model ID to use for this session.

  • provider_id – Provider ID to use for this session.

  • root_session_id – Root session ID for sub-sessions.

Returns:

The newly created Session.

async oats.session.session.get_session(session_id)[source]

Get a session by ID.

Return type:

Session | None

Parameters:

session_id – The session identifier.

Returns:

The Session if found, or None.

async oats.session.session.list_sessions()[source]

List all session infos.

Return type:

list[SessionInfo]

Returns:

A list of SessionInfo objects for all sessions.

oats.session.message

Message models for session conversations.

class oats.session.message.TextPart(**data)[source]

Bases: BaseModel

A text content part within a message.

type

Always “text”.

id

Unique identifier for this part.

content

The text content.

type: Literal['text']
id: str
content: str
model_config: ClassVar[ConfigDict] = {}

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

class oats.session.message.ImagePart(**data)[source]

Bases: BaseModel

An image content part (base64-encoded or URL).

type

Always “image”.

id

Unique identifier for this part.

media_type

MIME type of the image (e.g. “image/png”).

data

Base64-encoded image bytes (mutually exclusive with url).

url

URL pointing to the image (mutually exclusive with data).

detail

Resolution hint for the provider (“auto”, “low”, “high”).

type: Literal['image']
id: str
media_type: str
data: str | None
url: str | None
detail: str
model_config: ClassVar[ConfigDict] = {}

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

class oats.session.message.ToolCallPart(**data)[source]

Bases: BaseModel

A tool call from the assistant.

type

Always “tool_call”.

id

Unique identifier for this part.

tool_call_id

The ID used to correlate with the tool result.

tool_name

Name of the tool being called.

arguments

Dict of arguments passed to the tool.

type: Literal['tool_call']
id: str
tool_call_id: str
tool_name: str
arguments: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

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

class oats.session.message.ToolResultPart(**data)[source]

Bases: BaseModel

Result from a tool execution.

type

Always “tool_result”.

id

Unique identifier for this part.

tool_call_id

The ID of the tool call this result corresponds to.

tool_name

Name of the tool that was executed.

title

Short title describing the tool result.

output

The tool’s output text.

error

Error message if the tool failed.

metadata

Additional metadata about the tool execution.

type: Literal['tool_result']
id: str
tool_call_id: str
tool_name: str
title: str
output: str
error: str | None
metadata: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

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

class oats.session.message.Message(**data)[source]

Bases: BaseModel

A message in a session conversation.

Messages can contain text, images, tool calls, and tool results. Supports conversion to the format expected by LLM provider APIs.

id

Unique message identifier.

session_id

The session this message belongs to.

role

The sender role (“user”, “assistant”, “system”).

parts

Ordered list of content parts (text, images, tool calls, results).

created_at

When the message was created.

model

The model that generated this message (for assistant messages).

provider

The provider that generated this message.

usage

Token usage stats for this message.

id: str
session_id: str
role: Literal['user', 'assistant', 'system']
parts: list[TextPart | ImagePart | ToolCallPart | ToolResultPart]
created_at: datetime
model: str | None
provider: str | None
usage: dict[str, int] | None
add_text(content)[source]

Add a text part to the message.

Return type:

TextPart

Parameters:

content – The text content to add.

Returns:

The created TextPart.

add_image(media_type, *, data=None, url=None, detail='auto')[source]

Add an image part (base64 data or URL) to the message.

Return type:

ImagePart

Parameters:

  • media_type – MIME type of the image.

  • data – Base64-encoded image bytes.

  • url – URL pointing to the image.

  • detail – Resolution hint for the provider.

Returns:

The created ImagePart.

get_images()[source]

Get all image parts.

Return type:

list[ImagePart]

Returns:

List of ImagePart objects in this message.

has_images()[source]

Check whether the message contains any image parts.

Return type:

bool

Returns:

True if the message has at least one image part.

add_tool_call(tool_call_id, tool_name, arguments)[source]

Add a tool call part to the message.

Return type:

ToolCallPart

Parameters:

  • tool_call_id – Unique ID for correlating with the result.

  • tool_name – Name of the tool being called.

  • arguments – Arguments to pass to the tool.

Returns:

The created ToolCallPart.

add_tool_result(tool_call_id, tool_name, title, output, error=None, metadata=None)[source]

Add a tool result part to the message.

Return type:

ToolResultPart

Parameters:

  • tool_call_id – ID of the tool call this result corresponds to.

  • tool_name – Name of the tool that was executed.

  • title – Short title for the result.

  • output – The tool’s output text.

  • error – Error message if the tool failed.

  • metadata – Additional metadata about the execution.

Returns:

The created ToolResultPart.

get_text_content()[source]

Get concatenated text content from all text parts.

Return type:

str

Returns:

All text parts joined with newlines.

get_tool_calls()[source]

Get all tool call parts.

Return type:

list[ToolCallPart]

Returns:

List of ToolCallPart objects in this message.

get_tool_results()[source]

Get all tool result parts.

Return type:

list[ToolResultPart]

Returns:

List of ToolResultPart objects in this message.

to_llm_format()[source]

Convert to format for LLM API.

Handles user (with optional multimodal), system, and assistant roles. For assistant messages with tool calls, formats them in the OpenAI-compatible tool_calls structure.

Return type:

dict[str, Any]

Returns:

A dict ready to be passed to a provider API.

model_config: ClassVar[ConfigDict] = {}

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

oats.session.processor

oats.session.compaction

oats.session.modes

oats.session.token_budget

oats.session.task_budget

oats.session.metrics

oats.session.usage

oats.session.build_system_prompt

oats.session.caveman

oats.session.debug_trace

oats.session.file_cache

oats.session.screenshot_store

oats.session.skill_selector

oats.session.tool_retention