Skip to main content

CEREBRUM - API Specification

Version: v1.3.0 | Last Updated: March 2026

Overview​

This document provides a complete API reference for the CEREBRUM module, including all classes, methods, and data structures.

Core Classes​

CerebrumEngine​

Main orchestrator for case-based reasoning and Bayesian inference.

Methods​

__init__(config: Optional[CerebrumConfig] = None) -> None​

Initialize CEREBRUM engine.

Parameters:

  • config (Optional[CerebrumConfig]): Configuration object

Returns: None

create_model(name: str, model_type: str, config: Optional[dict[str, Any]] = None) -> Model​

Create a new cognitive model.

Parameters:

  • name (str): Model name (must be unique)
  • model_type (str): Type of model (e.g., "case_based", "bayesian")
  • config (Optional[dict[str, Any]]): Model configuration parameters

Returns: Model - Created model

Raises:

  • ModelError: If model already exists
add_case(case: Case) -> None​

Add a case to the case base.

Parameters:

  • case (Case): Case to add

Returns: None

Raises:

  • InvalidCaseError: If case is invalid
reason(case: Case, context: Optional[dict[str, Any]] = None) -> ReasoningResult​

Perform reasoning on a case.

Parameters:

  • case (Case): Query case
  • context (Optional[dict[str, Any]]): Additional context

Returns: ReasoningResult - Reasoning result with prediction and confidence

learn_from_case(case: Case, outcome: Any) -> None​

Learn from a case by updating the case base.

Parameters:

  • case (Case): Case to learn from
  • outcome (Any): Observed outcome

Returns: None

transform_model(model: Model, transformation: str, **kwargs) -> Model​

Transform a model through adaptation or learning.

Parameters:

  • model (Model): Model to transform
  • transformation (str): Transformation type ("adapt_to_case", "learn_from_feedback", etc.)
  • **kwargs: Transformation-specific parameters

Returns: Model - Transformed model

Raises:

  • TransformationError: If transformation fails
set_bayesian_network(network: BayesianNetwork) -> None​

Set Bayesian network for probabilistic inference.

Parameters:

  • network (BayesianNetwork): Bayesian network

Returns: None

set_active_inference_agent(agent: ActiveInferenceAgent) -> None​

Set active inference agent.

Parameters:

  • agent (ActiveInferenceAgent): Active inference agent

Returns: None

Case Management​

Case​

Represents a case in case-based reasoning.

Attributes​

  • case_id (str): Unique case identifier
  • features (dict[str, Any]): Feature dictionary
  • context (dict[str, Any]): Additional context
  • outcome (Optional[Any]): Outcome or solution
  • metadata (dict[str, Any]): Additional metadata

Methods​

to_dict() -> dict[str, Any]​

Convert case to dictionary.

Returns: dict[str, Any] - Case as dictionary

from_dict(data: dict[str, Any]) -> Case​

Create case from dictionary.

Parameters:

  • data (dict[str, Any]): Case data

Returns: Case - Case object

CaseBase​

Collection of cases with similarity search.

Methods​

add_case(case: Case) -> None​

Add a case to the case base.

Parameters:

  • case (Case): Case to add

Returns: None

retrieve_similar(query: Case, k: int = 10, threshold: float = 0.0) -> list[tuple[Case, float]]​

Retrieve k most similar cases.

Parameters:

  • query (Case): Query case
  • k (int): Number of cases to retrieve
  • threshold (float): Minimum similarity threshold

Returns: list[tuple[Case, float]] - List of (case, similarity) tuples

compute_similarity(case1: Case, case2: Case) -> float​

Compute similarity between two cases.

Parameters:

  • case1 (Case): First case
  • case2 (Case): Second case

Returns: float - Similarity score in [0, 1]

CaseRetriever​

Retrieves similar cases using various strategies.

Methods​

retrieve(query: Case, k: int = 10, threshold: float = 0.0) -> list[tuple[Case, float]]​

Retrieve similar cases.

Parameters:

  • query (Case): Query case
  • k (int): Number of cases to retrieve
  • threshold (float): Minimum similarity threshold

Returns: list[tuple[Case, float]] - List of (case, weight) tuples

Bayesian Inference​

BayesianNetwork​

Represents a Bayesian network (probabilistic graphical model).

Methods​

add_node(node: str, values: list[Any], prior: Optional[list[float]] = None) -> None​

Add a node to the network.

Parameters:

  • node (str): Node name
  • values (list[Any]): Possible values
  • prior (Optional[list[float]]): Prior probabilities

Returns: None

Raises:

  • NetworkStructureError: If node already exists
add_edge(parent: str, child: str) -> None​

Add a directed edge.

Parameters:

  • parent (str): Parent node name
  • child (str): Child node name

Returns: None

Raises:

  • NetworkStructureError: If nodes don't exist
set_cpt(node: str, cpt: dict[tuple, dict[Any, float]]) -> None​

Set conditional probability table.

Parameters:

  • node (str): Node name
  • cpt (dict[tuple, dict[Any, float]]): Conditional probability table

Returns: None

InferenceEngine​

Performs probabilistic inference.

Methods​

infer(query: dict[str, Any], evidence: Optional[dict[str, Any]] = None) -> dict[str, Distribution]​

Perform inference.

Parameters:

  • query (dict[str, Any]): Variables to query
  • evidence (Optional[dict[str, Any]]): Observed evidence

Returns: dict[str, Distribution] - Posterior distributions

Raises:

  • InferenceError: If inference fails
compute_marginal(variable: str, evidence: Optional[dict[str, Any]] = None) -> Distribution​

Compute marginal distribution.

Parameters:

  • variable (str): Variable name
  • evidence (Optional[dict[str, Any]]): Optional evidence

Returns: Distribution - Marginal distribution

Distribution​

Represents a probability distribution.

Attributes​

  • values (list[Any]): Possible values
  • probabilities (list[float]): Probabilities (normalized)

Methods​

sample(n: int = 1) -> list[Any]​

Sample from the distribution.

Parameters:

  • n (int): Number of samples

Returns: list[Any] - Samples

expectation() -> float​

Compute expectation (for numeric values).

Returns: float - Expected value

Raises:

  • ValueError: If values are not numeric
mode() -> Any​

Get the most probable value.

Returns: Any - Mode value

Active Inference​

ActiveInferenceAgent​

Implements active inference agent.

Methods​

predict(observation: Optional[dict[str, Any]] = None) -> dict[str, float]​

Predict state distribution.

Parameters:

  • observation (Optional[dict[str, Any]]): Optional observation

Returns: dict[str, float] - Predicted state distribution

select_action(state: Optional[dict[str, Any]] = None) -> str​

Select action based on expected free energy.

Parameters:

  • state (Optional[dict[str, Any]]): Optional current state

Returns: str - Selected action

update_beliefs(observation: dict[str, Any]) -> None​

Update beliefs based on observation.

Parameters:

  • observation (dict[str, Any]): New observation

Returns: None

compute_free_energy(beliefs: Optional[BeliefState] = None, observations: Optional[dict[str, Any]] = None) -> float​

Compute variational free energy.

Parameters:

  • beliefs (Optional[BeliefState]): Belief state
  • observations (Optional[dict[str, Any]]): Observations

Returns: float - Free energy value

Model Transformation​

TransformationManager​

Manages model transformations.

Methods​

transform(model: Model, transformation_type: str, transformer_name: Optional[str] = None, **kwargs) -> Model​

Transform a model.

Parameters:

  • model (Model): Model to transform
  • transformation_type (str): Type of transformation
  • transformer_name (Optional[str]): Specific transformer
  • **kwargs: Transformation parameters

Returns: Model - Transformed model

Visualization​

ModelVisualizer​

Visualizes Bayesian networks.

Methods​

visualize_network(network: BayesianNetwork) -> Figure​

Visualize Bayesian network structure.

Parameters:

  • network (BayesianNetwork): Network to visualize

Returns: Figure - Matplotlib figure

CaseVisualizer​

Visualizes case similarity.

Methods​

plot_case_similarity(cases: list[tuple[Case, float]], query_case: Optional[Case] = None) -> Figure​

Plot case similarity scores.

Parameters:

  • cases (list[tuple[Case, float]]): Cases with similarities
  • query_case (Optional[Case]): Optional query case

Returns: Figure - Matplotlib figure

Configuration​

CerebrumConfig​

Configuration for CEREBRUM engine.

Attributes​

  • case_similarity_threshold (float): Minimum similarity threshold
  • max_retrieved_cases (int): Maximum cases to retrieve
  • case_weighting_strategy (str): Weighting strategy
  • inference_method (str): Inference method
  • adaptation_rate (float): Model adaptation rate
  • learning_rate (float): Learning rate

Exceptions​

  • CerebrumError: Base exception
  • CaseError: Case-related errors
  • CaseNotFoundError: Case not found
  • InvalidCaseError: Invalid case
  • BayesianInferenceError: Bayesian inference errors
  • InferenceError: Inference failures
  • NetworkStructureError: Network structure errors
  • ActiveInferenceError: Active inference errors
  • ModelError: Model-related errors
  • TransformationError: Transformation errors
  • VisualizationError: Visualization errors

Free-Energy Loop (v1.3.0)​

FreeEnergyLoop​

Closed-loop free-energy minimization runner for active inference agents.

Constructor​

__init__(agent: ActiveInferenceAgent, max_steps: int = 50, fe_threshold: float = 0.1, convergence_window: int = 3) -> None​

Parameters:

  • agent (ActiveInferenceAgent): Active inference agent to run
  • max_steps (int): Maximum perception-action cycles
  • fe_threshold (float): Free energy convergence threshold
  • convergence_window (int): Consecutive steps below threshold needed for convergence

Methods​

run(observation: dict[str, Any]) -> LoopResult​

Run the free-energy minimization loop.

Parameters:

  • observation (dict[str, Any]): Initial observation

Returns: LoopResult - Result of the loop execution

StepResult​

Result of a single perception-action cycle.

Attributes​

  • step (int): Step number
  • free_energy (float): Free energy at this step
  • action (str): Action selected
  • beliefs (dict[str, float]): Belief state after update

LoopResult​

Result of the full free-energy loop execution.

Attributes​

  • converged (bool): Whether the loop converged
  • steps (int): Total steps taken
  • final_free_energy (float): Final free energy value
  • action_history (list[str]): Sequence of actions taken
  • step_results (list[StepResult]): Per-step detail