API Reference

This section provides the auto-generated, detailed technical documentation for all public classes and functions in the CogniCoreAI library. It is generated directly from the docstrings in the source code.

Agent

This is the central orchestrator of the framework.

The core agent module of the CogniCore framework.

This module has been refactored to be LLM-agnostic. The Agent class now operates on the BaseLLM abstraction, allowing any compatible LLM backend to be plugged in without changing the agent’s reasoning logic.

class cognicoreai.agents.Agent(llm, memory, tools, system_prompt='You are a helpful assistant.', mode='v1', v2_config=None, policy=None)

Bases: object

The central conversational agent, now decoupled from any specific LLM.

chat(user_input)

The main method for interacting with the agent. The logic now uses the standardized LLMResponse object.

Return type:

str

property events

Returns V2 runtime events when running in V2 mode.

class cognicoreai.agents.ToolHandler(tools)

Bases: object

A helper class to manage the tools available to an agent. (This class remains unchanged as its logic is independent of the LLM)

execute_tool(tool_name, tool_input)

Return type:

str

get_tool_definitions()

Return type:

List[dict]

LLMs

This module contains the abstraction layer for Large Language Models, allowing for modular, swappable backends.

LLM Abstraction Module for CogniCore.

This module provides a generic interface for interacting with various Large Language Models (LLMs). The core component is the BaseLLM abstract class, which defines a standard “contract” that all LLM provider implementations must follow.

This abstraction decouples the Agent from any specific LLM provider (like OpenAI), making the framework highly modular and extensible. To add support for a new model, one simply needs to create a new class that inherits from BaseLLM and implements the get_completion method.

class cognicoreai.llms.BaseLLM

Bases: ABC

Abstract Base Class for all LLM clients.

This class defines the “contract” for how the CogniCore Agent interacts with an LLM. Any class that provides access to an LLM must inherit from this class and implement the get_completion method.

abstractmethod get_completion(messages, tools)

Sends a request to the LLM and returns a standardized response.

Return type:

LLMResponse

Args:

messages (List[Message]): The sequence of messages forming the

conversation history.

tools (List[Dict[str, Any]]): The definitions of tools available

for the LLM to use.

Returns:

LLMResponse: A standardized response object containing the model’s

reply and any requested tool calls.

class cognicoreai.llms.LLMResponse(content, tool_calls, raw_response_message)

Bases: object

A standardized data structure for the response from any LLM.

This class abstracts away the provider-specific response object, giving the Agent a clean and predictable object to work with.

Attributes:

content (Optional[str]): The direct text response from the model. This is

None if the model decides to call a tool instead of responding.

tool_calls (Optional[List[ToolCall]]): A list of tool calls requested

by the model. This is None if the model provides a direct text response.

raw_response_message (Any): The original, unaltered message object from

the LLM provider’s response. This is useful for logging the exact model output back into memory.

content: str | None

raw_response_message: Any

tool_calls: List[ToolCall] | None

class cognicoreai.llms.OpenAI_LLM(model='gpt-4-turbo', api_key=None)

Bases: BaseLLM

A concrete implementation of BaseLLM for OpenAI’s chat models.

This class handles all the specifics of communicating with the OpenAI API.

get_completion(messages, tools)

Implements the LLM call specifically for the OpenAI API.

It translates the OpenAI-specific response object into the framework’s standard LLMResponse format.

Return type:

LLMResponse

class cognicoreai.llms.ToolCall(id, function_name, arguments)

Bases: object

A standardized data structure representing a tool call requested by an LLM.

This class ensures that the Agent receives tool call information in a consistent format, regardless of the underlying LLM provider.

Attributes:

id (str): A unique identifier for this specific tool call. function_name (str): The name of the function/tool to be called. arguments (str): A JSON string representing the arguments for the function.

arguments: str

function_name: str

id: str

Memory

This module provides the components for managing an agent’s conversational memory.

Memory module for CogniCore agents.

This module provides the foundational components for managing an agent’s memory. The core design principle is to use an abstract base class (BaseMemory) to define a consistent interface for all memory backends. This allows for flexibility, enabling developers to use simple in-memory storage for testing or to implement complex, persistent memory solutions (e.g., using databases or file systems) for production use cases.

The standard message format used throughout the library is also defined here as the Message type.

class cognicoreai.memory.BaseMemory

Bases: ABC

Abstract Base Class for all memory modules in CogniCore.

This class defines the essential interface that any memory implementation must adhere to. By programming against this abstraction, the Agent class can seamlessly switch between different memory backends without changing its internal logic.

abstractmethod add_message(message)

Adds a single message to the memory store.

This method is responsible for appending a new message to the conversation history.

Return type:

None

Args:

message (Message): The message object to add to the history.

abstractmethod clear()

Clears the entire conversation history from memory.

Return type:

None

abstractmethod get_history()

Retrieves the complete conversation history.

Return type:

List[Message]

Returns:

List[Message]: A list of all message objects stored in memory,

in the order they were added.

class cognicoreai.memory.Message

Bases: TypedDict

Represents a single message in the conversation history.

Attributes:

role (Literal[“system”, “user”, “assistant”, “tool”]): The role of the entity

that produced the message. “system” messages set the agent’s behavior, “user” messages are from the end-user, and “assistant” messages are from the AI.

content (str): The text content of the message.

content: str

event: Dict[str, Any]

name: str

role: Literal['system', 'user', 'assistant', 'tool']

tool_call_id: str

tool_calls: List[Dict[str, Any]]

class cognicoreai.memory.VolatileMemory

Bases: BaseMemory

A simple, in-memory implementation of the BaseMemory.

This memory backend stores the conversation history in a Python list. It is “volatile” because the history is lost as soon as the object is destroyed or the application exits.

This class is ideal for development, testing, and simple applications where conversation persistence is not required.

add_message(message)

Adds a single message to the in-memory history list.

Return type:

None

Args:

message (Message): The message object to add.

clear()

Clears the history list, effectively resetting the agent’s memory.

Return type:

None

get_history()

Retrieves the complete conversation history.

Return type:

List[Message]

Returns:

List[Message]: A copy of the internal history list to prevent

external modification of the memory state.

Tools

This module provides the components for equipping an agent with tools to interact with the outside world.

Tool integration module for CogniCore agents.

This module allows agents to be equipped with tools that they can use to interact with the outside world, such as performing calculations, searching the web, or calling external APIs.

The design is centered around the Tool abstract base class, which mandates that every tool must have a name and a description. This metadata is critical, as it is provided to the Large Language Model (LLM) to enable it to make informed decisions about which tool to use and what input to provide.

class cognicoreai.tools.CalculatorTool

Bases: Tool

A tool that allows the agent to perform basic arithmetic calculations.

property description: str

Returns the description, which explains how the LLM should use the tool.

property name: str

Returns the unique name of the tool.

run(tool_input)

Parses and executes the mathematical expression.

Return type:

str

Args:

tool_input (str): The mathematical expression to evaluate.

Returns:

str: The result of the calculation or an error message if the

input is invalid.

class cognicoreai.tools.Tool

Bases: ABC

Abstract Base Class for all tools that an agent can use.

This class defines the standard interface for all tools. The name and description properties are essential for the agent’s reasoning process, while the run method contains the actual executable logic of the tool.

abstract property description: str

A detailed, natural-language description of what the tool does.

This description is provided to the LLM in the prompt, so it must be clear and descriptive enough for the model to understand the tool’s purpose, its capabilities, and the expected format of its input.

abstract property name: str

A unique, machine-readable name for the tool.

This name is used by the LLM to specify which tool it wants to call. It should consist of letters, numbers, and underscores only. Example: “web_search”, “calculator”.

abstractmethod run(tool_input)

Executes the tool with the given input.

Return type:

str

Args:

tool_input (str): The input for the tool, typically generated by

the LLM. The tool’s implementation is responsible for parsing this input.

Returns:

str: The output of the tool’s execution, which will be returned

to the agent to continue its reasoning process.

Simulation

This module contains the powerful framework for running behavioral tests and simulations on an agent.

Behavioral Simulation and Evaluation Module for CogniCore.

This module provides the tools to test an agent’s behavior against predefined scenarios. It allows developers to verify not just that individual components work, but that the agent as a whole reasons and acts as expected in a given conversational context.

The workflow is: 1. Define one or more Assertion`s (conditions for success). 2. Create a `Scenario that includes conversational steps and assertions. 3. Run the Scenario using the Simulator.

class cognicoreai.simulation.Assertion

Bases: ABC

Abstract Base Class for all assertions.

An assertion is a rule that evaluates to True or False based on the agent’s conversation history after a scenario is run.

abstractmethod evaluate(history)

Evaluates the assertion against the conversation history.

Return type:

bool

Args:

history (List[Message]): The complete conversation history from the

agent’s memory.

Returns:

bool: True if the assertion passes, False otherwise.

class cognicoreai.simulation.ResponseContainsAssertion(expected_text, case_sensitive=False)

Bases: Assertion

Asserts that the agent’s final response contains specific text.

evaluate(history)

Evaluates the assertion against the conversation history.

Return type:

bool

Args:

history (List[Message]): The complete conversation history from the

agent’s memory.

Returns:

bool: True if the assertion passes, False otherwise.

class cognicoreai.simulation.Scenario(name, steps, assertions)

Bases: object

Defines a complete, runnable test case for an agent.

class cognicoreai.simulation.SimulationResult(scenario_name: str, passed: bool, assertion_results: Dict[str, bool], final_history: List[Message])

Bases: NamedTuple

A data structure to hold the results of a single scenario simulation.

assertion_results: Dict[str, bool]

Alias for field number 2

final_history: List[Message]

Alias for field number 3

passed: bool

Alias for field number 1

scenario_name: str

Alias for field number 0

class cognicoreai.simulation.Simulator

Bases: object

The engine that runs scenarios against an agent and reports results.

run(agent, scenarios)

Executes a list of scenarios against a given agent.

Return type:

List[SimulationResult]

Args:

agent (Agent): The agent instance to test. scenarios (List[Scenario]): A list of scenarios to run.

Returns:

List[SimulationResult]: A list of result objects, one for each scenario.

class cognicoreai.simulation.ToolUsedAssertion(tool_name)

Bases: Assertion

Asserts that a specific tool was called at least once.

evaluate(history)

Evaluates the assertion against the conversation history.

Return type:

bool

Args:

history (List[Message]): The complete conversation history from the

agent’s memory.

Returns:

bool: True if the assertion passes, False otherwise.

V2 Protocol

This module defines runtime envelopes and lifecycle primitives for V2 execution.

Protocol and lifecycle primitives for V2 runtime execution.

class cognicoreai.protocol.ErrorEnvelope(error_type, severity, retriable, remediation_hint)

Bases: object

Standardized failure payload used by V2 runtime events.

error_type: Literal['validation', 'dependency', 'timeout', 'policy', 'internal']

remediation_hint: str

retriable: bool

severity: Literal['S1', 'S2', 'S3']

class cognicoreai.protocol.EventEnvelope(message_type, source, destination, correlation_id, protocol_version='2.0.0-alpha', causation_id=None, message_id=<factory>, timestamp_utc=<factory>)

Bases: object

Event wrapper carrying causality metadata across runtime operations.

causation_id: str | None = None

correlation_id: str

destination: str

message_id: str

message_type: Literal['task.created', 'task.assigned', 'task.started', 'task.progress', 'task.completed', 'task.failed', 'task.cancelled', 'tool.call.requested', 'tool.call.completed', 'tool.call.failed', 'policy.blocked']

protocol_version: str = '2.0.0-alpha'

source: str

timestamp_utc: str

class cognicoreai.protocol.RuntimeEvent(envelope, payload, error=None)

Bases: object

A full runtime event consisting of envelope + payload + optional error.

envelope: EventEnvelope

error: ErrorEnvelope | None = None

payload: Dict[str, Any]

cognicoreai.protocol.new_correlation_id()

Create a correlation id for a runtime execution thread.

Return type:

str

cognicoreai.protocol.validate_transition(current, nxt)

Validate whether a lifecycle transition is allowed by the V2 state model.

Return type:

bool

V2 Policy

This module provides policy hooks used by V2 runtime and tool execution.

Policy hooks for V2 runtime safety and capability control.

class cognicoreai.policy.AllowAllPolicy

Bases: BasePolicy

Default policy that allows all actions.

evaluate(action, context=None)

Return type:

PolicyDecision

class cognicoreai.policy.BasePolicy

Bases: ABC

Abstract policy interface for runtime action validation.

abstractmethod evaluate(action, context=None)

Return type:

PolicyDecision

class cognicoreai.policy.DenyByCapabilityPolicy(blocked_capabilities)

Bases: BasePolicy

Policy that blocks specific capability/tool names.

evaluate(action, context=None)

Return type:

PolicyDecision

class cognicoreai.policy.PolicyDecision(allowed, reason='allowed', severity='S3')

Bases: object

Result of a policy check over an action request.

allowed: bool

reason: str = 'allowed'

severity: str = 'S3'

V2 Tool Runtime

This module defines policy-aware tool execution in V2 flows.

Tool execution runtime for V2, including policy checks and typed outcomes.

class cognicoreai.tool_runtime.ToolExecutionResult(status, content, tool_name, error_type=None)

Bases: object

Normalized outcome of a tool execution attempt.

content: str

error_type: str | None = None

status: Literal['completed', 'failed', 'blocked']

tool_name: str

class cognicoreai.tool_runtime.ToolRuntime(tools, policy)

Bases: object

Policy-aware and retry-capable tool execution adapter.

execute(tool_name, tool_input, retry_budget=0)

Return type:

ToolExecutionResult

V2 Orchestration

This module provides multi-agent runtime orchestration modes for V2 alpha.

V2 orchestration runtime with multi-agent execution modes.

class cognicoreai.orchestrator.V2Config(mode='supervisor', max_rounds=1, emit_events=True, tool_retry_budget=0)

Bases: object

Config knobs for the V2 multi-agent runtime.

emit_events: bool = True

max_rounds: int = 1

mode: Literal['supervisor', 'planner', 'blackboard'] = 'supervisor'

tool_retry_budget: int = 0

class cognicoreai.orchestrator.V2MultiAgentRuntime(llm, memory, tools, system_prompt, config, policy=None)

Bases: object

An additive V2 runtime that keeps V1 compatibility via opt-in usage.

chat(user_input)

Return type:

str

property events: List[RuntimeEvent]