API Reference

Complete reference for all public classes and methods in the ARC library.

Arc

The primary controller class for monitoring and protecting training loops.

arc.api.callback

class Arc(
    config: Optional[Config] = None,
    model_path: Optional[str] = None,
    auto_intervene: bool = False,
    verbose: bool = True,
)

Methods

Method	Returns	Description
`attach(model, optimizer)`	`Arc`	Attach ARC to a model and optimizer
`detach()`	`None`	Remove all hooks and detach
`on_batch_end(loss, step)`	`None`	Call after each batch to record loss
`on_epoch_end(epoch, val_loss, train_loss)`	`FailurePrediction`	Call at epoch end, returns failure prediction
`get_report()`	`str`	Generate text report of training health
`save_state(path)`	`None`	Save internal state to disk
`load_state(path)`	`None`	Load previously saved state
`reset()`	`None`	Reset all internal state

Properties

Property	Type	Description
`overhead_percentage`	`float`	Current ARC overhead as % of training time

Context Manager

Arc supports the context manager protocol. Use with Arc(...) as arc: for automatic cleanup.

ArcV2

The high-level wrapper that automatically configures ARC based on model size and task type.

arc.api.v2

arc = ArcV2.auto(
    model, 
    optimizer,
    task_type="classification",
    safety_level="standard"
)

Method	Returns	Description
`auto(model, optimizer, **kwargs)`	`ArcV2`	Class method to auto-initialize
`step(loss)`	`dict`	Records loss and performs online interventions
`begin_task(task_id)`	`None`	Starts a new continual learning task (EWC)
`consolidate_task(dataloader)`	`None`	Computes Fisher information for EWC
`get_ewc_loss()`	`Tensor`	Returns the EWC penalty for the current batch

ArcCallback

PyTorch Lightning callback for zero-code integration.

usage

from arc import ArcCallback

trainer = pl.Trainer(callbacks=[ArcCallback(
    auto_intervene=True,
    verbose=True,
)])

Config

Field	Type	Default
`signal`	`SignalConfig`	Default signal settings
`feature`	`FeatureConfig`	Window size 10, min history 3
`prediction`	`PredictionConfig`	GRU hidden 64, 2 layers
`thresholds`	`FailureThresholds`	Standard thresholds
`overhead`	`OverheadConfig`	5% max overhead
`device`	`str`	`"auto"`

Class Methods

Method	Description
`Config.low_overhead()`	Production preset: 5% sampling, no curvature, 2% max overhead
`Config.high_accuracy()`	Research preset: 30% sampling, curvature proxy, spectral features
`Config.from_json(str)`	Deserialize from JSON string
`Config.from_dict(dict)`	Create from dictionary

SignalConfig

Field	Type	Default	Description
`collect_every_n_steps`	`int`	1	Collection frequency
`activation_sample_ratio`	`float`	0.1	Fraction of activations to sample
`compute_gradient_entropy`	`bool`	True	Compute gradient entropy metric
`compute_curvature_proxy`	`bool`	False	Enable Hessian-vector product estimation
`track_effective_rank`	`bool`	True	Track effective rank of weight matrices

PredictionConfig

Field	Type	Default
`temporal_hidden_size`	`int`	64
`num_gru_layers`	`int`	2
`mc_dropout_samples`	`int`	20
`high_risk_threshold`	`float`	0.7
`medium_risk_threshold`	`float`	0.4

FailureThresholds

Field	Type	Default
`loss_explosion_factor`	`float`	10.0
`loss_nan_detection`	`bool`	True
`vanishing_grad_threshold`	`float`	1e-7
`exploding_grad_threshold`	`float`	1e4
`activation_similarity_threshold`	`float`	0.95
`effective_rank_collapse_ratio`	`float`	0.3
`overfit_gap_threshold`	`float`	0.5

Signal Collectors

Collector	Signals
`GradientCollector`	Gradient norms, entropy, histogram
`ActivationCollector`	Activation stats, similarity, effective rank
`WeightCollector`	Weight norms, NaN/Inf check, variance
`OptimizerCollector`	Optimizer state integrity, momentum norms
`LossCollector`	Loss trajectory, EMA, acceleration
`CurvatureCollector`	Hessian-vector products (optional)

PINNStabilizer

Method	Description
`__init__(model, n_loss_terms)`	Initialize with model and number of loss components
`get_stabilized_loss(losses)`	Compute adaptively weighted combined loss
`stabilize_step()`	Apply gradient clipping and stabilization
`update(epoch, loss)`	Update internal state for curriculum scheduling

ConformalPredictor

Method	Description
`__init__(model, alpha)`	Initialize with model and significance level
`calibrate(loader)`	Calibrate on held-out data
`predict(input)`	Return prediction set with coverage guarantee

AdversarialDetector

Method	Description
`__init__(model)`	Initialize with model to protect
`fit(clean_loader)`	Fit detector on clean data distribution
`detect(input)`	Check if input is adversarial

ElasticWeightConsolidation

Method	Description
`__init__(model, lambda_)`	Initialize with model and EWC strength
`consolidate(dataloader)`	Compute Fisher Information and store parameters
`penalty()`	Compute EWC penalty loss

BulletproofTrainer

bulletproof.py

from arc import BulletproofTrainer, BulletproofConfig

config = BulletproofConfig(max_epochs=100)
trainer = BulletproofTrainer(model, optimizer, config)
trainer.fit(train_loader, val_loader)