compitum API

.. py:module:: compitum.router

.. py:class:: CompitumRouter(models: ~typing.List[~compitum.models.Model], predictors: ~typing.Dict[str, ~typing.Dict[str, ~compitum.predictors.CalibratedPredictor]], solver: ~compitum.constraints.ReflectiveConstraintSolver, coherence: ~compitum.coherence.CoherenceFunctional, boundary: ~compitum.boundary.BoundaryAnalyzer, srmf: ~compitum.control.LyapunovController, pgd_extractor: ~compitum.pgd.RegexPromptExtractor, metric_map: ~typing.Dict[str, ~compitum.metric.SymbolicManifoldMetric], energy: ~compitum.energy.SymbolicFreeEnergy, update_stride: int = 8, enable_metric_update: bool = True, enable_controller: bool = True) :module: compitum.router

Routes prompts/embeddings across models and emits a certificate.

Orchestration order:

  • feature extraction (PGD)

  • per-model utility + diagnostics (energy, uncertainty)

  • constraint-feasible selection

  • boundary analysis

  • optional metric update (two-timescale) with bounded step size

  • controller update (Lyapunov-based trust region)

.. py:class:: SwitchCertificate(model: ‘str’, utility: ‘float’, utility_components: ‘Dict[str, float]’, constraints: ‘InfoDict’, boundary_analysis: ‘Dict[str, Any]’, drift_status: ‘Dict[str, float]’, pgd_signature: ‘str’, timestamp: ‘float’, router_version: ‘str’ = ‘0.1.1’) :module: compitum.router

.. py:module:: compitum.metric

.. py:module:: compitum.constraints

.. py:class:: InfoDict :module: compitum.constraints

.. py:module:: compitum.coherence

.. py:module:: compitum.boundary

.. py:module:: compitum.control

.. py:class:: LyapunovController(kappa: float = 0.1, r0: float = 1.0, integral_gain: float = 0.005) :module: compitum.control

Lyapunov-based trust-region controller.

This class supersedes the prior “SRMFController”. In our framework, the SRMF functional acts as a Lyapunov candidate under bounded-observer assumptions; this controller implements a concrete, numerically stable update that decreases a positive-definite Lyapunov function and clips the trust region to maintain boundedness.

.. py:method:: LyapunovController.lyapunov_function() -> float :module: compitum.control

  Positive-definite Lyapunov candidate (squared integral error).

.. py:method:: LyapunovController.update(d_star: float, grad_norm: float) -> ~typing.Tuple[float, ~typing.Dict[str, float]] :module: compitum.control

  Updates the controller state based on the observed error `d_star` and gradient norm.

  This controller is inspired by Lyapunov stability theory. The `drift_integral` term
  acts as a simple Lyapunov function candidate. By driving this term towards zero, we
  ensure that the system remains in a stable state.

.. py:class:: SRMFController(kappa: float = 0.1, r0: float = 1.0, integral_gain: float = 0.005) :module: compitum.control

Deprecated alias for backward compatibility.

The Self-Regulating Mapping Function (SRMF) serves as a Lyapunov functional in our setting; this alias preserves older imports while the canonical implementation is provided by LyapunovController.

.. py:module:: compitum.energy

.. py:module:: compitum.models

.. py:class:: Model(name: str, center: numpy.ndarray, capabilities: compitum.capabilities.Capabilities, cost: float) :module: compitum.models

.. py:module:: compitum.predictors

.. py:class:: CalibratedPredictor() :module: compitum.predictors

Calibrated regressor with quantile bounds (p5,p95). For latency/cost: consider enabling monotonic constraints via LightGBM when available.

.. py:module:: compitum.cli