Metadata-Version: 2.4
Name: compello
Version: 0.2.0
Summary: A constraint-driven autotraining framework that steers models toward declared correctness properties.
Author: averoe
Maintainer: averoe
License: Apache-2.0
Keywords: machine-learning,constrained-optimization,training,pytorch,tensorflow,jax,keras,autotraining,linter,static-analysis,cooper
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: numpy
Requires-Dist: numpy>=1.21; extra == "numpy"
Provides-Extra: config
Requires-Dist: pyyaml>=5.4; extra == "config"
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: tensorflow
Requires-Dist: tensorflow>=2.12; extra == "tensorflow"
Provides-Extra: jax
Requires-Dist: jax>=0.4; extra == "jax"
Requires-Dist: optax>=0.1; extra == "jax"
Provides-Extra: cooper
Requires-Dist: cooper>=0.1.0; extra == "cooper"
Provides-Extra: tuning
Requires-Dist: optuna>=3.0; extra == "tuning"
Provides-Extra: datalint
Requires-Dist: polars>=0.18; extra == "datalint"
Provides-Extra: tui
Requires-Dist: textual>=0.30; extra == "tui"
Provides-Extra: telemetry
Requires-Dist: prometheus-client>=0.14; extra == "telemetry"
Provides-Extra: dev
Requires-Dist: numpy>=1.21; extra == "dev"
Requires-Dist: pyyaml>=5.4; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: optuna>=3.0; extra == "dev"
Requires-Dist: polars>=0.18; extra == "dev"
Requires-Dist: textual>=0.30; extra == "dev"
Requires-Dist: prometheus-client>=0.14; extra == "dev"
Provides-Extra: all
Requires-Dist: numpy>=1.21; extra == "all"
Requires-Dist: pyyaml>=5.4; extra == "all"
Requires-Dist: torch>=2.0; extra == "all"
Requires-Dist: tensorflow>=2.12; extra == "all"
Requires-Dist: jax>=0.4; extra == "all"
Requires-Dist: optax>=0.1; extra == "all"
Requires-Dist: cooper>=0.1.0; extra == "all"
Requires-Dist: optuna>=3.0; extra == "all"
Requires-Dist: polars>=0.18; extra == "all"
Requires-Dist: textual>=0.30; extra == "all"
Requires-Dist: prometheus-client>=0.14; extra == "all"
Dynamic: license-file

# 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**.

```bash
pip install compello
```

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

---

## Table of Contents

- [Why Compello?](#why-compello)
  - [Open-Loop vs. Closed-Loop Training](#open-loop-vs-closed-loop-training)
  - [Mathematical Formulation](#mathematical-formulation)
  - [System Architecture & Control Flow](#system-architecture--control-flow)
- [Features](#features)
  - [1. Assertion DSL & Sandboxed AST Evaluator](#1-assertion-dsl--sandboxed-ast-evaluator)
  - [2. Differentiable Penalty Library & Modality Relaxations](#2-differentiable-penalty-library--modality-relaxations)
  - [3. Adaptive & Passive Controllers](#3-adaptive--passive-controllers)
  - [4. Pre-Flight Data Feasibility (`compello.datalint`)](#4-pre-flight-data-feasibility-compellodatalint)
  - [5. Anti-Forgetting Data Equilibrium Macro-Loop (`compello.monitor`)](#5-anti-forgetting-data-equilibrium-macro-loop-compellomonitor)
  - [6. Dynamic Hyperparameter Tuning (`compello.tuning`)](#6-dynamic-hyperparameter-tuning-compellotuning)
  - [7. Tabular Feature Analysis (`compello.features`)](#7-tabular-feature-analysis-compellofeatures)
  - [8. Gradient Surgery & Layer Scoping](#8-gradient-surgery--layer-scoping)
  - [9. Observability, Telemetry & Live TUI](#9-observability-telemetry--live-tui)
  - [10. Static AST Linter (`trainlint`) & Solution Blueprints](#10-static-ast-linter-trainlint--solution-blueprints)
- [Installation & Optional Extras](#installation--optional-extras)
- [Developer Tutorial](#developer-tutorial)
  - [Step 1: Basic Closed-Loop Steering](#step-1-basic-closed-loop-steering)
  - [Step 2: PyTorch & TensorFlow Training Loop Integration](#step-2-pytorch--tensorflow-training-loop-integration)
  - [Step 3: Framework Callbacks (HuggingFace & PyTorch Lightning)](#step-3-framework-callbacks-huggingface--pytorch-lightning)
  - [Step 4: Pre-Flight Static Doctor & Conflict Detection](#step-4-pre-flight-static-doctor--conflict-detection)
  - [Step 5: Pre-Flight Dataset Feasibility Validation](#step-5-pre-flight-dataset-feasibility-validation)
  - [Step 6: Fine-Tuning Anti-Forgetting Macro-Loop](#step-6-fine-tuning-anti-forgetting-macro-loop)
  - [Step 7: Constraint-Aware Hyperparameter Tuning](#step-7-constraint-aware-hyperparameter-tuning)
  - [Step 8: Tabular Feature Analyzer](#step-8-tabular-feature-analyzer)
  - [Step 9: Declarative Config-Driven Workflow](#step-9-declarative-config-driven-workflow)
  - [Step 10: Observation-Only Passive Auditing](#step-10-observation-only-passive-auditing)
- [Declarative Configuration Schema](#declarative-configuration-schema)
- [Command-Line Interface (CLI) Reference](#command-line-interface-cli-reference)
- [Public API Reference](#public-api-reference)
- [Verification & Testing](#verification--testing)
- [Governance & Security](#governance--security)
- [License](#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.**

```python
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

```bash
# 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

```python
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
```python
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
```python
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)

```python
# 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()
```

```python
# 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

```python
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

```python
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

```python
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

```python
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

```python
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

```yaml
# 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"
```

```python
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

```python
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`:

```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:

```bash
pip install "compello[dev]"
pytest -v
```

---

## Governance & Security

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

---

## License

Compello is released under the **[Apache License 2.0](LICENSE)**.
