The BaseAdapter class in tck/adapters/base_adapter.py defines the contract all TCK-testable implementations must satisfy. This document provides the complete reference for all methods, data models, and enums.

Data Models

All models are Pydantic BaseModel subclasses. Implementations must return instances of these exact types.

TCKMessage

Field Type Required Description

id

UUID

Yes

Unique message identifier

role

str

Yes

One of: user, assistant, system

content

str

Yes

Message text content

timestamp

datetime

Yes

Creation timestamp

embedding

list[float] | None

No

Vector embedding

metadata

dict[str, Any]

Yes

Arbitrary metadata (default: {})

TCKConversation

Field Type Required Description

id

UUID

Yes

Unique conversation identifier

session_id

str

Yes

Session identifier

messages

list[TCKMessage]

Yes

Messages in insertion order

title

str | None

No

Human-readable title

created_at

datetime

Yes

Creation timestamp

updated_at

datetime | None

No

Last update timestamp

TCKSessionInfo

Field Type Required Description

session_id

str

Yes

Session identifier

message_count

int

Yes

Number of messages in session

created_at

datetime

Yes

Session creation time

updated_at

datetime | None

No

Last update time

TCKEntity

Field Type Required Description

id

UUID

Yes

Unique entity identifier

name

str

Yes

Entity name

type

str

Yes

One of: PERSON, ORGANIZATION, LOCATION, EVENT, OBJECT

subtype

str | None

No

Entity subtype

description

str | None

No

Entity description

embedding

list[float] | None

No

Vector embedding

canonical_name

str | None

No

Canonical form of the name

created_at

datetime

Yes

Creation timestamp

TCKPreference

Field Type Required Description

id

UUID

Yes

Unique preference identifier

category

str

Yes

Preference category

preference

str

Yes

Preference statement

context

str | None

No

Contextual information

embedding

list[float] | None

No

Vector embedding

TCKFact

Field Type Required Description

id

UUID

Yes

Unique fact identifier

subject

str

Yes

Subject of the fact

predicate

str

Yes

Relationship or action

object

str

Yes

Object of the fact

embedding

list[float] | None

No

Vector embedding

TCKRelationship

Field Type Required Description

id

UUID

Yes

Unique relationship identifier

source_id

UUID

Yes

Source entity ID

target_id

UUID

Yes

Target entity ID

relationship_type

str

Yes

Relationship type label

properties

dict[str, Any]

Yes

Relationship properties (default: {})

TCKReasoningTrace

Field Type Required Description

id

UUID

Yes

Unique trace identifier

session_id

str

Yes

Associated session

task

str

Yes

Task description

steps

list[TCKReasoningStep]

Yes

Steps in the trace

outcome

str | None

No

Final outcome description

success

bool | None

No

Whether the task succeeded

started_at

datetime

Yes

Trace start time

completed_at

datetime | None

No

Trace completion time

TCKReasoningStep

Field Type Required Description

id

UUID

Yes

Unique step identifier

trace_id

UUID

Yes

Parent trace ID

step_number

int

Yes

Sequential step number (monotonically increasing)

thought

str | None

No

Agent’s reasoning

action

str | None

No

Action taken

observation

str | None

No

Observation from action

tool_calls

list[TCKToolCall]

Yes

Tool calls within this step

TCKToolCall

Field Type Required Description

id

UUID

Yes

Unique call identifier

tool_name

str

Yes

Name of the tool

arguments

dict[str, Any]

Yes

Tool arguments

result

Any

No

Tool result

status

ToolCallStatus

Yes

Status (default: pending)

duration_ms

int | None

No

Duration in milliseconds

error

str | None

No

Error message

TCKToolStats

Field Type Required Description

name

str

Yes

Tool name

total_calls

int

Yes

Total invocations

successful_calls

int

Yes

Successful invocations

failed_calls

int

Yes

Failed invocations

success_rate

float

Yes

Success ratio (0.0 to 1.0)

avg_duration_ms

float | None

No

Average duration

Enums

MessageRole

class MessageRole(str, Enum):
    USER = "user"
    ASSISTANT = "assistant"
    SYSTEM = "system"

ToolCallStatus

class ToolCallStatus(str, Enum):
    PENDING = "pending"
    SUCCESS = "success"
    FAILURE = "failure"
    ERROR = "error"
    TIMEOUT = "timeout"
    CANCELLED = "cancelled"

Methods by Tier

Bronze: Lifecycle

async def setup(self) -> None
async def teardown(self) -> None
async def clear_all_data(self) -> None

Bronze: Short-Term Memory

async def add_message(self, session_id: str, role: str, content: str, *, metadata: dict[str, Any] | None = None) -> TCKMessage
async def get_conversation(self, session_id: str, *, limit: int | None = None) -> TCKConversation
async def search_messages(self, query: str, *, session_id: str | None = None, limit: int = 10, threshold: float = 0.7) -> list[TCKMessage]
async def list_sessions(self, *, limit: int = 100) -> list[TCKSessionInfo]
async def delete_message(self, message_id: UUID) -> bool
async def clear_session(self, session_id: str) -> None

Silver: Long-Term Memory

async def add_entity(self, name: str, entity_type: str, *, description: str | None = None) -> TCKEntity
async def add_preference(self, category: str, preference: str, *, context: str | None = None) -> TCKPreference
async def add_fact(self, subject: str, predicate: str, obj: str) -> TCKFact
async def search_entities(self, query: str, *, limit: int = 10) -> list[TCKEntity]
async def search_preferences(self, query: str, *, category: str | None = None, limit: int = 10) -> list[TCKPreference]
async def get_entity_by_name(self, name: str) -> TCKEntity | None
async def get_related_entities(self, entity_id: UUID, *, relationship_type: str | None = None, depth: int = 1) -> list[TCKEntity]

Silver: Reasoning Memory

async def start_trace(self, session_id: str, task: str) -> TCKReasoningTrace
async def add_step(self, trace_id: UUID, *, thought: str | None = None, action: str | None = None, observation: str | None = None) -> TCKReasoningStep
async def record_tool_call(self, step_id: UUID, tool_name: str, arguments: dict[str, Any], *, result: Any = None, status: ToolCallStatus = ToolCallStatus.SUCCESS, duration_ms: int | None = None, error: str | None = None) -> TCKToolCall
async def complete_trace(self, trace_id: UUID, *, outcome: str | None = None, success: bool | None = None) -> TCKReasoningTrace
async def get_trace_with_steps(self, trace_id: UUID) -> TCKReasoningTrace | None
async def list_traces(self, *, session_id: str | None = None, limit: int = 100) -> list[TCKReasoningTrace]
async def get_tool_stats(self, tool_name: str | None = None) -> list[TCKToolStats]

Gold: Cross-Memory (optional defaults)

async def add_relationship(self, source_id: UUID, target_id: UUID, relationship_type: str, *, properties: dict[str, Any] | None = None) -> TCKRelationship
async def merge_duplicate_entities(self, source_id: UUID, target_id: UUID, *, canonical_name: str | None = None) -> TCKEntity
async def get_similar_traces(self, task: str, *, limit: int = 5, success_only: bool = True) -> list[TCKReasoningTrace]

Gold methods have default implementations that raise NotImplementedError. Implementations targeting Gold must override them.