Compello

Compello is a constraint-driven autotraining framework for Python. It allows machine learning models to be trained against declared behavioral properties—such as non-negativity, feature monotonicity, group fairness parity, probability floors, and transformation invariance—by incorporating constraint enforcement directly into the optimization loop.

Instead of evaluating model assertions post-training, Compello compiles declarative expectations into differentiable penalty signals. An adaptive controller monitors constraint violations at each training step, dynamically tuning Lagrangian multipliers across PyTorch, TensorFlow / Keras 3, JAX, and NumPy.

pip install compello

Requires Python 3.9+. Zero required external dependencies for the core framework.

---

Table of Contents

• Why Compello?
  • Open-Loop vs. Closed-Loop Training
  • Mathematical Formulation
  • System Architecture & Control Flow
• Features
  • 1. Assertion DSL & Sandboxed AST Evaluator
  • 2. Differentiable Penalty Library & Modality Relaxations
  • 3. Adaptive & Passive Controllers
  • 4. Pre-Flight Data Feasibility (compello.datalint)
  • 5. Anti-Forgetting Data Equilibrium Macro-Loop (compello.monitor)
  • 6. Dynamic Hyperparameter Tuning (compello.tuning)
  • 7. Tabular Feature Analysis (compello.features)
  • 8. Gradient Surgery & Layer Scoping
  • 9. Observability, Telemetry & Live TUI
  • 10. Static AST Linter (trainlint) & Solution Blueprints
• Installation & Optional Extras
• Developer Tutorial
  • Step 1: Basic Closed-Loop Steering
  • Step 2: PyTorch & TensorFlow Training Loop Integration
  • Step 3: Framework Callbacks (HuggingFace & PyTorch Lightning)
  • Step 4: Pre-Flight Static Doctor & Conflict Detection
  • Step 5: Pre-Flight Dataset Feasibility Validation
  • Step 6: Fine-Tuning Anti-Forgetting Macro-Loop
  • Step 7: Constraint-Aware Hyperparameter Tuning
  • Step 8: Tabular Feature Analyzer
  • Step 9: Declarative Config-Driven Workflow
  • Step 10: Observation-Only Passive Auditing
• Declarative Configuration Schema
• Command-Line Interface (CLI) Reference
• Public API Reference
• Verification & Testing
• Governance & Security
• License

---

Why Compello?

Open-Loop vs. Closed-Loop Training

Standard machine learning training is open-loop:

1. Select a primary task loss $\mathcal{L}_{\text{task}}$ (e.g., Cross-Entropy, MSE).
2. Configure optimizer hyperparameters (learning rate, momentum, weight decay).
3. Execute optimization for $N$ steps.
4. Run evaluation scripts post-training to verify whether model outputs satisfy constraints or domain requirements.

When post-hoc evaluation reveals failures, practitioners often manually add static penalty terms with fixed coefficients ($\mathcal{L}{\text{total}} = \mathcal{L}{\text{task}} + \lambda \cdot \mathcal{L}_{\text{penalty}}$).

Fixed penalty coefficients $\lambda$ have operational limitations:

• If $\lambda$ is too small, penalty gradients are insufficient and violations persist.
• If $\lambda$ is too large, penalty gradients dominate the loss landscape and prevent convergence on the primary task.

Compello applies closed-loop control to training loops.

from compello import wrap, expect

# Wrap your model to create a transparent proxy
model = wrap(raw_model)

# Declare target properties
expect(model.output, "> 0", name="non_negative_dose")
expect(model.output, monotonic_in="age", increasing=True, name="monotonic_risk")
expect(model.output, parity_across="demographic_group", name="fairness_parity")

At each optimization step, Compello evaluates constraint violations, calculates differentiable penalty metrics, and updates Lagrangian multipliers via adaptive PID or dual-ascent controllers. Multipliers increase when violations occur and decay when constraints are satisfied.

---

Mathematical Formulation

Compello formulates constrained optimization as a dynamic min-max problem over model parameters $\theta$ and multiplier vector $\boldsymbol{\lambda} = [\lambda_1, \dots, \lambda_K]^T$:

$$\min_{\theta} \max_{\boldsymbol{\lambda} \ge \mathbf{0}} \mathcal{L}{\text{steered}}(\theta, \boldsymbol{\lambda}) = \mathcal{L}{\text{task}}(f_\theta(X), Y) + \sum_{i=1}^{K} \lambda_i \cdot \phi_i(f_\theta(X))$$

Where:

• $\theta$ represents trainable weights.
• $\phi_i(f_\theta(X)) \ge 0$ is the differentiable violation metric for constraint $i$, where $\phi_i = 0$ indicates zero violation.
• $\lambda_i \ge 0$ is the dynamically updated multiplier for constraint $i$.

Adaptive PID Multiplier Controller

Under the ADAPTIVE_PID strategy, multiplier adjustments use Proportional, Integral, and Derivative signals over filtered violation trajectories $v_{i,t}$:

$$\Delta \log \lambda_{i,t} = K_p \cdot v_{i,t} + K_i \cdot \text{EMA}{\text{slow}}(v{i,t}) + K_d \cdot (v_{i,t} - v_{i,t-1})$$

$$\lambda_{i,t+1} = \min\left(\lambda_{\text{max}}, \exp\left(\log \lambda_{i,t} + \Delta \log \lambda_{i,t}\right)\right)$$

Mechanism characteristics:

1. Log-Space Scaling: Log-space operations maintain $\lambda_{i,t} > 0$ without hard threshold clipping.
2. Dual-Rate EMA Filtering: Fast EMA reduces batch-level variance while slow EMA tracks systemic trend.
3. Hysteresis Dead-Band: When $v_{i,t} \le \text{tolerance}$, the controller enters a dead-band zone and decays multipliers toward zero.
4. Ceiling Lock Detection: If a multiplier remains at $\lambda_{\text{max}}$ for patience consecutive steps, Compello flags the constraint as infeasible.

---

System Architecture & Control Flow

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                                 COMPELLED STEP EXECUTION                                    │
│                                                                                             │
│  1. FORWARD PASS ──────────► 2. ASSERTION EVALUATION ───────► 3. DIFFERENTIABLE PENALTY     │
│     `model(x)`               Target Extraction (`expect`)       COMPUTATION                 │
│     Model Proxy              Sandboxed AST Evaluator            Hinge / Sigmoid Relaxations │
│                                                                              │              │
│  6. OPTIMIZER STEP ◄──────── 5. GRADIENT SURGERY (PCGrad) ◄─── 4. ADAPTIVE CONTROLLER       │
│     `optimizer.step()`       Vector Projection                  PID Multiplier Update ($\lambda_i$)│
│                              Layer-Scoped ($N$ layers)          Dual-Rate EMA Smoothing     │
└─────────────────────────────────────────────────────────────────────────────────────────────┘

1. Proxy Wrapping (wrap): compello.wrap() wraps models or tensors in a ModelProxy / TensorProxy without altering parameters or signature.
2. Target Extraction & Parsing (expect): Target tensors (OutputTarget, LogitTarget, ModelTarget) are monitored during the forward pass. Condition strings are evaluated via SandboxedEvaluator.
3. Penalty Computation: Violations are converted into differentiable penalty values using hinge functions, soft sigmoids, or cross-view consistency relaxations.
4. Multiplier Update: The Controller updates constraint weights $\lambda_i$ using PID control, dual-rate EMA smoothing, and dead-bands.
5. Gradient Surgery (PCGrad): When penalty gradients oppose primary task gradients ($\cos \theta < 0$), PCGrad projects constraint gradients onto the normal plane of task gradients: $$g_{\text{steered}} = g_{\text{task}} - \frac{g_{\text{task}} \cdot g_{\text{penalty}}}{|g_{\text{penalty}}|^2} g_{\text{penalty}}$$
6. Optimizer Update: The combined loss $\mathcal{L}{\text{steered}} = \mathcal{L}{\text{task}} + \sum \lambda_i \phi_i$ is passed to the optimizer.

---

Features

1. Assertion DSL & Sandboxed AST Evaluator

The expect() assertion DSL supports explicit target typing and condition expressions:

• Target Types: OutputTarget (model outputs), LogitTarget (logits), and ModelTarget (parameters).
• String Predicates: Arithmetic and comparison expressions such as "> 0.0", "< 100.0", or "> 0.6 and < 10.0".
• AST Security (SandboxedEvaluator): String expressions pass through an AST evaluator (safe_parse, safe_evaluate) enforcing:
  • Maximum AST nesting depth of 32 levels.
  • Prohibition of attribute access (obj.attr) to prevent class traversal.
  • Restriction of allowed function calls to abs, min, max, len, and round.
• Python Lambdas: Native callables (e.g., lambda y: y > 0) for first-party logic.
• Custom Types: Register assertion types via register_assertion_type("name", AssertionClass).

2. Differentiable Penalty Library & Modality Relaxations

• Range / Hinge Penalties: Hinge functions for upper and lower bounds: $$\phi(y) = \max(0, \text{lower} - y) + \max(0, y - \text{upper})$$
• Monotonicity: Penalizes out-of-order predictions relative to an ordered feature: $$\phi(y, x) = \sum_{i < j \text{ s.t. } x_i < x_j} \max(0, y_i - y_j)$$
• Invariance: Measures L2 distance under transformations: $$\phi(y) = |f_\theta(x) - f_\theta(T(x))|_2^2$$
• Probability Floor: Mask-aware penalty enforcing minimum token/logit probability: $$\phi(p) = \text{mask} \odot \max(0, p_{\text{min}} - p)$$
• Cross-Group Parity: Penalizes output variance across demographic groups $g \in G$: $$\phi(y) = \text{Var}_{g \in G}\left(\mathbb{E}[y \mid g]\right)$$
• Lipschitz Smoothness: Bounds output sensitivity relative to input shifts: $$\phi(x, x') = \max\left(0, \frac{|f(x) - f(x')|}{|x - x'|} - L_{\text{max}}\right)$$
• Modality Relaxations: Sigmoid-based relaxations for non-differentiable objectives:
  • soft_iou_penalty — Soft Intersection-over-Union for segmentation masks.
  • soft_f1_penalty — Soft F1-score relaxation for classification.
  • spectral_gate_penalty — Frequency domain spectral mask penalty.
  • soft_rank_penalty — Differentiable top-k ranking relaxation.

3. Adaptive & Passive Controllers

The Controller module provides control strategies for managing multipliers $\lambda_i$:

• ADAPTIVE_PID: PID control with dual-rate EMA smoothing, cold-start monitoring, and dead-bands.
• DUAL_ASCENT: Lagrangian dual ascent with log-space buffers.
• LINEAR_RAMP: Linear scaling from weight_min to weight_max over a set step budget.
• FIXED: Static multiplier values.
• Safety Mechanisms: ControllerConfig.validate() checks hyperparameter bounds at initialization.
• PassiveController: Observation-only mode that logs violations while keeping $\lambda_i \equiv 0.0$.

4. Pre-Flight Data Feasibility (compello.datalint)

The compello.datalint module inspects datasets before training:

• check_data(dataset, assertions, config): Evaluates datasets for range errors, monotonicity breaks, Lipschitz instability, and subgroup parity gaps.
• DatalintReport: Summary of dataset feasibility and specific violation locations.
• Performance: Polars acceleration for tabular data with pure-Python fallback.

5. Anti-Forgetting Data Equilibrium Macro-Loop (compello.monitor)

For fine-tuning and domain adaptation:

• SamplingController & EquilibriumSampler: Adjusts data mixture ratios ($\theta$) between domain data and anchor baseline data based on gradient alignment, KL divergence, and Wasserstein distance.
• Equilibrium-Lock: Locks the mixture ratio when domain and anchor objectives conflict ($\cos(\theta) < \text{lock_threshold}$).
• Anchor Hash Checks: check_anchor_cache_integrity() verifies tokenizer/vocabulary hashes at startup.
• Provenance Logging: Writes mixture transitions to compello_monitor_provenance.jsonl.

6. Dynamic Hyperparameter Tuning (compello.tuning)

Controller hyperparameter search via tune_controller():

• Optuna Backend: Bayesian hyperparameter search when Optuna is installed.
• Random Search Fallback: Fallback implementation when Optuna is absent.
• Early Pruning: Prunes trials that hit weight ceiling locks (ceiling_lock_prune).
• Results: Returns TuningResult and per-trial TrialSnapshot history.

7. Tabular Feature Analysis (compello.features)

Pre-training statistical checks on tabular inputs via FeatureAnalyzer:

• Variance Thresholding: Identifies low-variance features.
• Correlation Redundancy: Identifies collinear feature pairs ($r > 0.95$).
• Cardinality Checks: Identifies high-cardinality categorical columns.
• Constraint Protection: Prevents features referenced by active constraints from being flagged for removal.

8. Gradient Surgery & Layer Scoping

When task loss and constraint penalty gradients oppose each other ($\cos \theta < 0$):

• PCGrad Projection: apply_gradient_surgery() projects constraint gradients onto the normal plane of task gradients.
• Layer Scoping: scoped_gradient_surgery(..., last_n_layers=N) restricts projection to the top $N$ layers to limit compute overhead.

9. Observability, Telemetry & Live TUI

• Prometheus: get_prometheus_metrics(controller) exports metrics in Prometheus text format.
• OpenTelemetry: emit_otel_step_metrics() pushes per-step constraint metrics.
• Alerting: recommend_alert_thresholds() generates metric alert rules based on violation distributions.
• Multi-Run Aggregator: MultiRunAggregator compares constraint metrics across runs.
• Terminal UI: Interactive monitor launched via compello tui checkpoint.json or run_tui().

10. Static AST Linter (trainlint) & Solution Blueprints

• trainlint: Static AST analyzer for PyTorch, TensorFlow, and JAX training scripts. Includes CLI and Flake8 plugin.
• Blueprints (compello.blueprints): Diagnostic blueprints generated by doctor():
  • InfeasibleConstraintBlueprint
  • GradientConflictBlueprint
  • CoverageGapBlueprint
  • DegeneracyBlueprint

---

Installation & Optional Extras

# Core framework
pip install compello

# Framework Adapters
pip install "compello[numpy]"          # NumPy reference backend
pip install "compello[torch]"          # PyTorch backend & callbacks
pip install "compello[tensorflow]"     # TensorFlow / Keras 3 backend & callbacks
pip install "compello[jax]"            # JAX & Optax backend

# Utilities
pip install "compello[tuning]"         # Optuna integration
pip install "compello[datalint]"       # Polars acceleration for datalint
pip install "compello[tui]"            # Textual terminal dashboard
pip install "compello[telemetry]"      # Prometheus exporter
pip install "compello[config]"         # PyYAML config parser

# Extras Bundles
pip install "compello[all]"            # All optional dependencies
pip install "compello[dev]"            # Development & testing dependencies

---

Developer Tutorial

Step 1: Basic Closed-Loop Steering

import numpy as np
import compello
from compello import expect
from compello.controller import Controller, ControllerConfig

# 1. Wrap model function
raw_fn = lambda x: x * 2.0 - 1.0
model = compello.wrap(raw_fn)

# 2. Declare constraint property
positivity_constraint = expect(model.output, "> 0", name="positivity")

# 3. Configure PID controller
config = ControllerConfig(strategy="adaptive_pid", tolerance=1e-3, weight_ceiling=20.0)
controller = Controller(config)
controller.register_assertions([positivity_constraint])

# 4. Training step evaluation
input_data = np.array([0.5, -0.2, 1.2])
output = model(input_data)

violation = positivity_constraint.violation_scalar()
step_result = controller.step({"positivity": violation})

weight = controller.states["positivity"].weight
print(f"Violation: {violation:.4f} | Weight: {weight:.4f} | Total Penalty: {step_result.total_penalty:.4f}")

---

Step 2: PyTorch & TensorFlow Training Loop Integration

PyTorch Integration

import torch
import torch.nn as nn
import compello
from compello import expect
from compello.controller import Controller, ControllerConfig

class Regressor(nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = nn.Linear(10, 1)
    def forward(self, x):
        return self.fc(x)

model = Regressor()
wrapped_model = compello.wrap(model)
positivity = expect(wrapped_model.output, "> 0", name="positive_output")

controller = Controller(ControllerConfig(strategy="adaptive_pid"))
controller.register_assertions([positivity])

optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)

for x_batch, y_batch in dataloader:
    optimizer.zero_grad()
    predictions = wrapped_model(x_batch)
    
    task_loss = nn.functional.mse_loss(predictions, y_batch)
    violation = positivity.violation_scalar()
    res = controller.step({"positive_output": violation})
    
    total_loss = task_loss + res.total_penalty
    total_loss.backward()
    optimizer.step()

TensorFlow / Keras 3 Integration

import tensorflow as tf
import compello
from compello import expect
from compello.controller import Controller, ControllerConfig

model = tf.keras.Sequential([tf.keras.layers.Dense(1, input_shape=(10,))])
wrapped_model = compello.wrap(model)
upper_bound = expect(wrapped_model.output, "< 10.0", name="upper_bound")

controller = Controller(ControllerConfig(strategy="adaptive_pid"))
controller.register_assertions([upper_bound])
optimizer = tf.keras.optimizers.Adam(1e-3)

@tf.function
def train_step(x_batch, y_batch):
    with tf.GradientTape() as tape:
        predictions = wrapped_model(x_batch)
        task_loss = tf.reduce_mean(tf.square(predictions - y_batch))
        
        violation = upper_bound.violation_scalar()
        res = controller.step({"upper_bound": violation})
        total_loss = task_loss + res.total_penalty
        
    grads = tape.gradient(total_loss, model.trainable_variables)
    optimizer.apply_gradients(zip(grads, model.trainable_variables))

---

Step 3: Framework Callbacks (HuggingFace & PyTorch Lightning)

# HuggingFace Trainer
from compello.callbacks import CompelloTrainerCallback
from compello.controller import Controller, ControllerConfig
from transformers import Trainer, TrainingArguments

controller = Controller(ControllerConfig(strategy="adaptive_pid"))
callback = CompelloTrainerCallback(controller=controller)

trainer = Trainer(
    model=model,
    args=TrainingArguments(output_dir="./results"),
    train_dataset=dataset,
    callbacks=[callback],
)
trainer.train()

# PyTorch Lightning
import pytorch_lightning as pl
from compello.callbacks import CompelloLightningCallback
from compello.controller import Controller, ControllerConfig

controller = Controller(ControllerConfig(strategy="adaptive_pid"))
callback = CompelloLightningCallback(controller=controller)

trainer = pl.Trainer(max_epochs=10, callbacks=[callback])
trainer.fit(model, train_dataloader)

---

Step 4: Pre-Flight Static Doctor & Conflict Detection

import numpy as np
import compello
from compello import expect, doctor, detect_conflicts

tensor = compello.wrap(np.array([1.0]))
c1 = expect(tensor, "> 0.8", name="high_floor")
c2 = expect(tensor, "< 0.3", name="low_ceiling")

conflicts = detect_conflicts([c1, c2])
for conflict in conflicts:
    print(f"Conflict: {conflict.kind} between {conflict.target_names} -> {conflict.rationale}")

report = doctor(assertions=[c1, c2], config={"backend": "raw_pytorch"})
print(report.render())

---

Step 5: Pre-Flight Dataset Feasibility Validation

import compello
from compello import expect, check_data, DatalintConfig

dataset = {
    "age": [18, 25, 35, 45, 55],
    "risk_score": [0.1, 0.3, 0.25, 0.6, 0.8],
}

assertion = expect(dataset["risk_score"], monotonic_in="age", increasing=True, name="risk_monotone")
report = check_data(dataset, [assertion], config=DatalintConfig(tau=0.01))

print("Is Dataset Feasible?", report.feasible)
print(report.render())

---

Step 6: Fine-Tuning Anti-Forgetting Macro-Loop

from compello.monitor import SamplingController, MonitorConfig

config = MonitorConfig(
    target_alignment=0.0,
    window_size=5,
    lock_threshold=-0.2,
    provenance_log_path="compello_monitor_provenance.jsonl",
)

macro_controller = SamplingController(config, initial_theta=0.2)

for macro_step in range(1, 6):
    simulated_alignment = 0.1 if macro_step < 3 else -0.3
    new_theta = macro_controller.step_macro(
        gradient_alignment=simulated_alignment,
        macro_step=macro_step,
    )
    print(f"Macro Step {macro_step} | Theta: {new_theta:.4f} | Locked: {macro_controller.locked}")

---

Step 7: Constraint-Aware Hyperparameter Tuning

import compello
from compello import Controller, ControllerConfig, tune_controller

controller = Controller(ControllerConfig())
controller.register_assertions([expect(compello.wrap(1.0), "> 0.5", name="acc_floor")])

search_space = {
    "weight_lr": {"type": "float", "low": 0.001, "high": 0.1},
    "patience": {"type": "int", "low": 3, "high": 20},
    "strategy": {"type": "categorical", "choices": ["adaptive_pid", "dual_ascent"]},
}

def objective_fn(ctrl):
    ctrl.step({"acc_floor": 0.1})
    return ctrl.states["acc_floor"].last_raw_violation

tuning_result = tune_controller(controller, search_space, objective_fn, n_trials=5, smoke_test=True)
print("Best Parameters:", tuning_result.best_params)
print("Pruned Trials Count:", tuning_result.pruned_trials)

---

Step 8: Tabular Feature Analyzer

import numpy as np
import compello
from compello import expect
from compello.features import FeatureAnalyzer

X_data = np.array([
    [1.0, 5.0, 100.0],
    [1.0, 5.0, 101.0],
    [1.0, 5.0, 102.0],
])

analyzer = FeatureAnalyzer(variance_threshold=0.01)
protected_assertion = expect(X_data[:, 0], "> 0", name="feature_0_must_exist")

report = analyzer.analyze(X_data, feature_names=["f0", "f1", "f2"], assertions=[protected_assertion])
print(report.render())

---

Step 9: Declarative Config-Driven Workflow

# compello_config.yaml
backend: raw_pytorch
seed: 42
controller:
  strategy: adaptive_pid
  tolerance: 0.001
  weight_ceiling: 25.0
  patience: 10
constraints:
  - name: positivity
    assertion_type: range
    condition: "> 0.0"
  - name: upper_bound
    assertion_type: range
    condition: "< 100.0"

from compello.config import load_config

config = load_config("compello_config.yaml")
print(f"Backend: {config.backend}")
print(f"Constraints: {[c.name for c in config.constraints]}")

---

Step 10: Observation-Only Passive Auditing

from compello import PassiveController, ControllerConfig

passive_ctrl = PassiveController(ControllerConfig(tolerance=0.01))
passive_ctrl.register("latency_bound")

step_res = passive_ctrl.step({"latency_bound": 0.05})
print(f"Weight: {step_res.per_constraint['latency_bound'].weight}")
print(f"Violation: {step_res.per_constraint['latency_bound'].raw_violation}")

---

Declarative Configuration Schema

Configuration options for compello_config.yaml:

backend: raw_pytorch
seed: 42

controller:
  strategy: adaptive_pid
  tolerance: 0.001
  weight_ceiling: 25.0
  patience: 15
  kp: 0.1
  ki: 0.01
  kd: 0.05
  ema_fast_decay: 0.9
  ema_slow_decay: 0.999

constraints:
  - name: dose_positivity
    assertion_type: range
    condition: "> 0.0"
    tolerance: 0.0001
    weight_ceiling: 50.0

  - name: risk_monotonicity
    assertion_type: monotonicity
    feature_index: 0
    increasing: true

  - name: subgroup_fairness
    assertion_type: cross_group_parity
    group_attribute: "demographic_group"
    max_variance: 0.05

surgery:
  enabled: true
  layer_scope: last_n_layers
  last_n_layers: 4

monitor:
  target_alignment: 0.0
  window_size: 10
  lock_threshold: -0.25
  provenance_log_path: "compello_monitor_provenance.jsonl"

---

Command-Line Interface (CLI) Reference

Command overview for compello:

Subcommand	Description	Flags	Usage
doctor	Static pre-flight diagnostics.	--config FILE, --data DATA.csv, --anchor ANCHOR.csv	compello doctor --config compello_config.yaml
check	Validates YAML/JSON configuration files.	--strict, --json	compello check compello_config.yaml
lint	Runs trainlint static linter on Python scripts.	--shield, --ascii	compello lint train.py --shield
bench	Runs controller performance benchmarks.	--json, --iters N	compello bench --json
tui	Launches interactive terminal dashboard.	CHECKPOINT.json	compello tui checkpoint.json
init	Scaffolds project configuration template.	--dir DIR	compello init --dir ./my_project
report	Regenerates reports from training logs.	--log LOG.json	compello report checkpoint.json --log run.log
library	Searches or installs community constraints.	search QUERY, install NAME	compello library search monotonicity
version	Displays version and backend status.	--json	compello version

---

Public API Reference

Overview of primary public exports:

Subsystem	Symbols	Description
Proxy & Targets	wrap, unwrap, ModelProxy, TensorProxy, OutputTarget, LogitTarget, ModelTarget	Model and tensor proxy wrapping.
Assertions	expect, register_assertion_type, registered_assertion_types	Constraint declaration DSL and registry.
Controller	Controller, ControllerConfig, PassiveController, FIXED, LINEAR_RAMP, ADAPTIVE_PID, DUAL_ASCENT	Multiplier controllers and configuration.
Data & Monitor	check_data, DatalintConfig, DatalintReport, EquilibriumSampler, SamplingController, MacroKernelEngine, MonitorConfig	Data feasibility checking and mixture monitoring.
Diagnostics & Surgery	apply_gradient_surgery, scoped_gradient_surgery, detect_conflicts, InsightEngine, ColdStartMonitor	Gradient surgery and diagnostic monitoring.
Validation & Doctor	validate, preflight, doctor, dry_run, render_preflight_shield	Static pre-flight analysis.
Tuning & Features	tune_controller, TuningResult, TrialSnapshot, FeatureAnalyzer, SuggestionReport	Controller tuning and tabular feature screening.
Observability & Callbacks	get_prometheus_metrics, emit_otel_step_metrics, CompelloTrainerCallback, CompelloLightningCallback	Observability exporters and framework callbacks.
Sandboxing & Config	SandboxedEvaluator, safe_parse, safe_evaluate, load_config, save_controller, load_controller	AST sandboxed evaluation and serialization.
Maturity Decorators	@stable, @experimental, @deprecated	API stability status annotations.

---

Verification & Testing

Compello includes an automated test suite:

• 308 Passing Tests: Unit, integration, and property tests.
• 56-Fixture Golden Anomaly Suite (tests/test_golden_anomaly_suite.py): Adversarial regression suite for edge cases, sandbox security, datalint feasibility, and equilibrium locks.
• Cross-Backend Suite (tests/test_cross_backend_consistency.py): Ensures mathematical consistency across backends.
• NumPy Reference Execution: The test suite executes on the NumPy backend without requiring GPU hardware or framework dependencies.

To run tests:

pip install "compello[dev]"
pytest -v

---

Governance & Security

• CONTRIBUTING.md: Coding standards, maturity annotations, test expectations, and PR workflow.
• SECURITY.md: Security policy and disclosure procedures.
• THREAT_MODEL.md: Technical threat model covering sandboxed evaluation, dataset privacy, and anchor cache integrity.
• CHANGELOG.md: Version history log.

---

License

Compello is released under the Apache License 2.0.