# Delta-Behavior API Reference
Comprehensive API documentation for the Delta-behavior library.
## Table of Contents
- [Quick Start](#quick-start)
- [Core Concepts](#core-concepts)
- [Coherence](#coherence)
- [Attractors](#attractors)
- [Transitions](#transitions)
- [API Reference](#api-reference)
- [Core Types](#core-types)
- [Configuration](#configuration)
- [Enforcement](#enforcement)
- [Applications](#applications)
- [Integration Examples](#integration-examples)
---
## Quick Start
### Installation
Add to your `Cargo.toml`:
```toml
[dependencies]
delta-behavior = "0.1"
# Or with specific applications
delta-behavior = { version = "0.1", features = ["containment", "swarm-intelligence"] }
```
### Minimal Example
```rust
use delta_behavior::{DeltaSystem, Coherence, DeltaConfig};
// Implement DeltaSystem for your type
struct MySystem {
state: Vec<f64>,
coherence: Coherence,
}
impl DeltaSystem for MySystem {
type State = Vec<f64>;
type Transition = Vec<f64>;
type Error = String;
fn coherence(&self) -> Coherence {
self.coherence
}
fn step(&mut self, delta: &Self::Transition) -> Result<(), Self::Error> {
// Validate coherence before applying
let predicted = self.predict_coherence(delta);
if predicted.value() < 0.3 {
return Err("Would violate coherence bound".into());
}
// Apply the transition
for (s, d) in self.state.iter_mut().zip(delta) {
*s += d;
}
self.coherence = predicted;
Ok(())
}
fn predict_coherence(&self, delta: &Self::Transition) -> Coherence {
let magnitude: f64 = delta.iter().map(|x| x.abs()).sum();
let impact = magnitude * 0.01;
Coherence::clamped(self.coherence.value() - impact)
}
fn state(&self) -> &Self::State {
&self.state
}
fn in_attractor(&self) -> bool {
// Check if state is near a stable configuration
self.state.iter().all(|x| x.abs() < 1.0)
}
}
```
### With Enforcement
```rust
use delta_behavior::{DeltaConfig, enforcement::DeltaEnforcer};
fn main() {
let config = DeltaConfig::default();
let mut enforcer = DeltaEnforcer::new(config);
let current = Coherence::new(0.8).unwrap();
let predicted = Coherence::new(0.75).unwrap();
match enforcer.check(current, predicted) {
EnforcementResult::Allowed => {
// Apply the transition
}
EnforcementResult::Throttled(duration) => {
// Wait before retrying
std::thread::sleep(duration);
}
EnforcementResult::Blocked(reason) => {
// Transition rejected
eprintln!("Blocked: {}", reason);
}
}
}
```
---
## Core Concepts
### Coherence
Coherence is the central metric in Delta-behavior systems. It measures how "organized" or "stable" a system currently is.
#### Properties
| 1.0 | Maximum coherence - perfectly organized |
| 0.8+ | High coherence - system is stable |
| 0.5-0.8 | Moderate coherence - may be throttled |
| 0.3-0.5 | Low coherence - transitions restricted |
| <0.3 | Critical - writes blocked |
| 0.0 | Collapsed - system failure |
#### Computing Coherence
Coherence computation depends on your domain:
##### For Vector Spaces (HNSW neighborhoods)
```rust
pub fn vector_coherence(center: &[f64], neighbors: &[&[f64]]) -> f64 {
let distances: Vec<f64> = neighbors
.iter()
.map(|n| cosine_distance(center, n))
.collect();
let mean = distances.iter().sum::<f64>() / distances.len() as f64;
let variance = distances.iter()
.map(|d| (d - mean).powi(2))
.sum::<f64>() / distances.len() as f64;
// Low variance = high coherence (tight neighborhood)
1.0 / (1.0 + variance)
}
```
##### For Graphs
```rust
pub fn graph_coherence(graph: &Graph) -> f64 {
let clustering = compute_clustering_coefficient(graph);
let modularity = compute_modularity(graph);
let connectivity = compute_algebraic_connectivity(graph);
0.4 * clustering + 0.3 * modularity + 0.3 * connectivity.min(1.0)
}
```
##### For Agent State
```rust
pub fn agent_coherence(state: &AgentState) -> f64 {
let attention_entropy = compute_attention_entropy(&state.attention);
let memory_consistency = compute_memory_consistency(&state.memory);
let goal_alignment = compute_goal_alignment(&state.goals, &state.actions);
// Low entropy + high consistency + high alignment = coherent
((1.0 - attention_entropy) * memory_consistency * goal_alignment).clamp(0.0, 1.0)
}
```
### Attractors
Attractors are stable states the system naturally evolves toward.
#### Types of Attractors
| Fixed Point | Single stable state | Thermostat at target temperature |
| Limit Cycle | Repeating sequence | Day/night cycle |
| Strange Attractor | Bounded chaos | Weather patterns |
#### Using Attractors
```rust
use delta_behavior::attractor::{Attractor, GuidanceForce};
// Define an attractor
let stable_state = Attractor {
state: vec![0.0, 0.0, 0.0], // Origin is stable
strength: 0.8,
radius: 1.0,
};
// Compute guidance force
let current_position = vec![0.5, 0.3, 0.2];
let force = GuidanceForce::toward(
¤t_position,
&stable_state.state,
stable_state.strength,
);
// Apply to transition
let biased_delta: Vec<f64> = original_delta
.iter()
.zip(&force.direction)
.map(|(d, f)| d + f * force.magnitude * 0.1)
.collect();
```
### Transitions
Transitions are state changes that must preserve coherence.
#### The Delta-Behavior Invariant
Every transition must satisfy:
```
coherence(S') >= coherence(S) - epsilon_max
coherence(S') >= coherence_min
```
#### Transition Results
| `Applied` | Transition succeeded | Continue |
| `Blocked` | Transition rejected | Find alternative |
| `Throttled` | Transition delayed | Wait and retry |
| `Modified` | Transition adjusted | Use modified version |
---
## API Reference
### Core Types
#### `Coherence`
```rust
pub struct Coherence(f64);
impl Coherence {
/// Create new coherence value (must be 0.0-1.0)
pub fn new(value: f64) -> Result<Self, &'static str>;
/// Create coherence, clamping to valid range
pub fn clamped(value: f64) -> Self;
/// Maximum coherence (1.0)
pub fn maximum() -> Self;
/// Minimum coherence (0.0)
pub fn minimum() -> Self;
/// Get the underlying value
pub fn value(&self) -> f64;
/// Check if above threshold
pub fn is_above(&self, threshold: f64) -> bool;
/// Check if below threshold
pub fn is_below(&self, threshold: f64) -> bool;
/// Calculate drop from another value
pub fn drop_from(&self, other: &Coherence) -> f64;
}
```
#### `CoherenceBounds`
```rust
pub struct CoherenceBounds {
/// Minimum acceptable coherence (writes blocked below this)
pub min_coherence: Coherence,
/// Throttle threshold (rate limited below this)
pub throttle_threshold: Coherence,
/// Target coherence for recovery
pub target_coherence: Coherence,
/// Maximum drop allowed per transition
pub max_delta_drop: f64,
}
impl Default for CoherenceBounds {
fn default() -> Self {
Self {
min_coherence: Coherence(0.3),
throttle_threshold: Coherence(0.5),
target_coherence: Coherence(0.8),
max_delta_drop: 0.1,
}
}
}
```
#### `DeltaSystem` Trait
```rust
pub trait DeltaSystem {
/// The state type
type State: Clone;
/// The transition type
type Transition;
/// Error type for failed transitions
type Error;
/// Measure current coherence
fn coherence(&self) -> Coherence;
/// Apply a transition
fn step(&mut self, transition: &Self::Transition) -> Result<(), Self::Error>;
/// Predict coherence after transition (without applying)
fn predict_coherence(&self, transition: &Self::Transition) -> Coherence;
/// Get current state
fn state(&self) -> &Self::State;
/// Check if in an attractor basin
fn in_attractor(&self) -> bool;
}
```
### Configuration
#### `DeltaConfig`
```rust
pub struct DeltaConfig {
pub bounds: CoherenceBounds,
pub energy: EnergyConfig,
pub scheduling: SchedulingConfig,
pub gating: GatingConfig,
pub guidance_strength: f64, // 0.0-1.0
}
impl DeltaConfig {
/// Default configuration
pub fn default() -> Self;
/// Strict configuration for safety-critical systems
pub fn strict() -> Self;
/// Relaxed configuration for exploratory systems
pub fn relaxed() -> Self;
}
```
#### `EnergyConfig`
Controls the soft enforcement layer where unstable transitions become expensive.
```rust
pub struct EnergyConfig {
/// Base cost for any transition
pub base_cost: f64, // default: 1.0
/// Exponent for instability scaling
pub instability_exponent: f64, // default: 2.0
/// Maximum cost cap
pub max_cost: f64, // default: 100.0
/// Budget regeneration per tick
pub budget_per_tick: f64, // default: 10.0
}
```
Energy cost formula:
```
cost = base_cost * (1 + instability)^instability_exponent
```
#### `SchedulingConfig`
Controls the medium enforcement layer for prioritization.
```rust
pub struct SchedulingConfig {
/// Coherence thresholds for 5 priority levels
pub priority_thresholds: [f64; 5], // default: [0.0, 0.3, 0.5, 0.7, 0.9]
/// Rate limits per priority level
pub rate_limits: [usize; 5], // default: [100, 50, 20, 10, 5]
}
```
#### `GatingConfig`
Controls the hard enforcement layer that blocks writes.
```rust
pub struct GatingConfig {
/// Minimum coherence to allow any writes
pub min_write_coherence: f64, // default: 0.3
/// Minimum coherence after write
pub min_post_write_coherence: f64, // default: 0.25
/// Recovery margin before writes resume
pub recovery_margin: f64, // default: 0.2
}
```
### Enforcement
#### `DeltaEnforcer`
```rust
pub struct DeltaEnforcer {
config: DeltaConfig,
energy_budget: f64,
in_recovery: bool,
}
impl DeltaEnforcer {
/// Create new enforcer
pub fn new(config: DeltaConfig) -> Self;
/// Check if transition should be allowed
pub fn check(
&mut self,
current: Coherence,
predicted: Coherence,
) -> EnforcementResult;
/// Regenerate energy budget (call once per tick)
pub fn tick(&mut self);
}
```
#### `EnforcementResult`
```rust
pub enum EnforcementResult {
/// Transition allowed
Allowed,
/// Transition blocked with reason
Blocked(String),
/// Transition throttled (delayed)
Throttled(Duration),
}
impl EnforcementResult {
/// Check if allowed
pub fn is_allowed(&self) -> bool;
}
```
---
## Applications
Enable via feature flags:
| `self-limiting` | Self-Limiting Reasoning | AI that does less when uncertain |
| `event-horizon` | Computational Event Horizons | Bounded recursion without hard limits |
| `homeostasis` | Artificial Homeostasis | Synthetic life with coherence-based survival |
| `world-model` | Self-Stabilizing World Models | Models that refuse to hallucinate |
| `creativity` | Coherence-Bounded Creativity | Novelty without chaos |
| `financial` | Anti-Cascade Financial | Markets that cannot collapse |
| `aging` | Graceful Aging | Systems that simplify over time |
| `swarm` | Swarm Intelligence | Collective behavior without pathology |
| `shutdown` | Graceful Shutdown | Systems that seek safe termination |
| `containment` | Pre-AGI Containment | Bounded intelligence growth |
| `all-applications` | All of the above | Full feature set |
### Application 1: Self-Limiting Reasoning
AI systems that automatically reduce activity when uncertain.
```rust
use delta_behavior::applications::self_limiting::{SelfLimitingReasoner, ReasoningStep};
let mut reasoner = SelfLimitingReasoner::new(0.6); // Min coherence
// Reasoning naturally slows as confidence drops
let result = reasoner.reason(query, context);
match result {
ReasoningResult::Complete(answer) => println!("Answer: {}", answer),
ReasoningResult::Halted { reason, partial } => {
println!("Stopped: {} (partial: {:?})", reason, partial);
}
ReasoningResult::Shallow { depth_reached } => {
println!("Limited to depth {}", depth_reached);
}
}
```
### Application 5: Coherence-Bounded Creativity
Generate novel outputs while maintaining coherence.
```rust
use delta_behavior::applications::creativity::{CreativeEngine, NoveltyMetrics};
let mut engine = CreativeEngine::new(0.5, 0.8); // coherence, novelty bounds
// Generate creative output that stays coherent
let output = engine.generate(seed, context);
println!("Novelty: {:.2}", output.novelty_score);
println!("Coherence: {:.2}", output.coherence);
println!("Result: {}", output.content);
```
### Application 8: Swarm Intelligence
Collective behavior with coherence-enforced coordination.
```rust
use delta_behavior::applications::swarm::{CoherentSwarm, SwarmAction};
let mut swarm = CoherentSwarm::new(0.6); // Min coherence
// Add agents
for i in 0..10 {
swarm.add_agent(&format!("agent_{}", i), (i as f64, 0.0));
}
// Agent actions are validated against swarm coherence
let result = swarm.execute_action("agent_5", SwarmAction::Move { dx: 10.0, dy: 5.0 });
match result {
ActionResult::Executed => println!("Action completed"),
ActionResult::Modified { original, modified, reason } => {
println!("Modified: {} -> {} ({})", original, modified, reason);
}
ActionResult::Rejected { reason } => {
println!("Rejected: {}", reason);
}
}
```
### Application 10: Pre-AGI Containment
Intelligence growth bounded by coherence.
```rust
use delta_behavior::applications::containment::{
ContainmentSubstrate, CapabilityDomain, GrowthResult
};
let mut substrate = ContainmentSubstrate::new();
// Attempt capability growth
let result = substrate.attempt_growth(CapabilityDomain::Reasoning, 0.5);
match result {
GrowthResult::Approved { increase, new_level, coherence_cost, .. } => {
println!("Grew by {:.2} to {:.2} (cost: {:.3})", increase, new_level, coherence_cost);
}
GrowthResult::Dampened { requested, actual, reason, .. } => {
println!("Dampened: {:.2} -> {:.2} ({})", requested, actual, reason);
}
GrowthResult::Blocked { reason, .. } => {
println!("Blocked: {}", reason);
}
GrowthResult::Lockdown { reason } => {
println!("LOCKDOWN: {}", reason);
}
}
```
---
## Integration Examples
### With Async Runtimes
```rust
use delta_behavior::{DeltaConfig, enforcement::DeltaEnforcer, Coherence};
use tokio::sync::Mutex;
use std::sync::Arc;
struct AsyncDeltaSystem {
enforcer: Arc<Mutex<DeltaEnforcer>>,
state: Arc<Mutex<SystemState>>,
}
impl AsyncDeltaSystem {
pub async fn transition(&self, delta: Delta) -> Result<(), Error> {
let mut enforcer = self.enforcer.lock().await;
let state = self.state.lock().await;
let current = state.coherence();
let predicted = state.predict_coherence(&delta);
match enforcer.check(current, predicted) {
EnforcementResult::Allowed => {
drop(state); // Release read lock
let mut state = self.state.lock().await;
state.apply(delta);
Ok(())
}
EnforcementResult::Throttled(duration) => {
drop(enforcer);
drop(state);
tokio::time::sleep(duration).await;
self.transition(delta).await // Retry
}
EnforcementResult::Blocked(reason) => {
Err(Error::Blocked(reason))
}
}
}
}
```
### With WASM
```rust
use wasm_bindgen::prelude::*;
use delta_behavior::{Coherence, CoherenceBounds};
#[wasm_bindgen]
pub struct WasmCoherenceMeter {
current: f64,
bounds: CoherenceBounds,
}
#[wasm_bindgen]
impl WasmCoherenceMeter {
#[wasm_bindgen(constructor)]
pub fn new() -> Self {
Self {
current: 1.0,
bounds: CoherenceBounds::default(),
}
}
#[wasm_bindgen]
pub fn check(&self, predicted: f64) -> bool {
predicted >= self.bounds.min_coherence.value()
}
#[wasm_bindgen]
pub fn update(&mut self, new_coherence: f64) {
self.current = new_coherence.clamp(0.0, 1.0);
}
#[wasm_bindgen]
pub fn current(&self) -> f64 {
self.current
}
}
```
### With Machine Learning Frameworks
```rust
use delta_behavior::{DeltaSystem, Coherence, DeltaConfig};
struct CoherentNeuralNetwork {
weights: Vec<Vec<f64>>,
coherence: Coherence,
config: DeltaConfig,
}
impl CoherentNeuralNetwork {
/// Training step with coherence constraints
pub fn train_step(&mut self, gradients: &[Vec<f64>], learning_rate: f64) -> Result<(), String> {
// Compute coherence impact of update
let update_magnitude: f64 = gradients.iter()
.flat_map(|g| g.iter())
.map(|x| (x * learning_rate).abs())
.sum();
let predicted_coherence = Coherence::clamped(
self.coherence.value() - update_magnitude * 0.01
);
// Check bounds
if predicted_coherence.value() < self.config.bounds.min_coherence.value() {
// Reduce learning rate to maintain coherence
let safe_lr = learning_rate * 0.5;
return self.train_step(gradients, safe_lr);
}
// Apply update
for (w, g) in self.weights.iter_mut().zip(gradients) {
for (wi, gi) in w.iter_mut().zip(g) {
*wi -= gi * learning_rate;
}
}
self.coherence = predicted_coherence;
Ok(())
}
}
```
---
## Best Practices
### 1. Choose Appropriate Coherence Metrics
Match your coherence computation to your domain:
- **Vector spaces**: Distance variance, neighborhood consistency
- **Graphs**: Clustering coefficient, modularity, connectivity
- **Agent systems**: Entropy, goal alignment, memory consistency
### 2. Start Conservative, Relax Gradually
Begin with `DeltaConfig::strict()` and relax constraints as you understand your system's behavior.
### 3. Implement Graceful Degradation
Always handle `Throttled` and `Blocked` results:
```rust
fn robust_transition(system: &mut MySystem, delta: Delta) -> Result<(), Error> {
for attempt in 0..3 {
match system.try_transition(&delta) {
Ok(()) => return Ok(()),
Err(TransitionError::Throttled(delay)) => {
std::thread::sleep(delay);
}
Err(TransitionError::Blocked(_)) if attempt < 2 => {
delta = delta.dampen(0.5); // Try smaller delta
}
Err(e) => return Err(e.into()),
}
}
Err(Error::MaxRetriesExceeded)
}
```
### 4. Monitor Coherence Trends
Track coherence over time to detect gradual degradation:
```rust
let mut state = CoherenceState::new(Coherence::maximum());
// In your main loop
state.update(system.coherence());
if state.is_declining() && state.current.value() < 0.6 {
// Trigger recovery actions
system.enter_recovery_mode();
}
```
### 5. Use Attractors for Stability
Pre-compute and register stable states:
```rust
let attractors = discover_attractors(&system, 1000);
for attractor in attractors {
system.register_attractor(attractor);
}
// Now transitions will be biased toward these stable states
```
---
## Troubleshooting
### High Rejection Rate
If too many transitions are being blocked:
1. Check if `max_delta_drop` is too restrictive
2. Consider using `DeltaConfig::relaxed()`
3. Ensure coherence computation is correctly calibrated
### Energy Exhaustion
If running out of energy budget:
1. Increase `budget_per_tick`
2. Lower `instability_exponent` for gentler cost curves
3. Call `enforcer.tick()` more frequently
### Stuck in Recovery Mode
If the system stays in recovery mode:
1. Reduce `recovery_margin`
2. Implement active coherence restoration
3. Lower `min_write_coherence` temporarily
---
## Version History
See [CHANGELOG.md](../CHANGELOG.md) for version history.
## License
MIT OR Apache-2.0