def-autonomy

def-autonomy is a lightweight Python-based cybernetic control library implementing the Dynamic Drive-Evaluation-Function (DEF) decision-making engine [1.3]. This framework adapts biophysiologically inspired principles of homeostatic self-regulation to design robust, self-adaptive autonomous software agents.

Unlike traditional deep reinforcement learning controllers that require substantial compute resources and are prone to unpredictable training distribution shifts, or hardcoded Finite State Machines (FSMs) that lack behavioral flexibility, def-autonomy evaluates candidate actions dynamically. It operates by continuous vector-projection of state-space deficits against environmental affordance gradients under shifting behavioral regimes.

---

🌌 Architectural Overview & Systems Mapping

The core architecture functions by mapping standard engineering telemetry to physiological state primitives:

Biological Term	Cybernetic Translation	Simulator Implementation Variables
Satiety ($x_0$, $x_c$)	Primary System Utility / Buffer Headroom	Available compute slots, battery levels, network headroom
Toxicity ($x_1$, $x_e$)	System Stress / Performance Penalties	Node request latency, HTTP error rate, hardware degradation
Metabolic Decay	System Idle Overhead	Idle host pricing, static network egress fees, passive battery loss
Threat Event ($d_{\text{threat}}$)	External System Vulnerability Risk	Unmitigated DDoS request surges, critical hardware faults
Foraging/Exploitation	Nominal Utility Execution Regime	Processing client queries, running indexing jobs
Survival	Active Hazard Mitigation Regime	Rate limiting, hot-swapping instances, shedding client loads
Conservation	System Consolidation / Optimization	Node consolidation, standby power mode, garbage collection

---

🛠️ Repository File Layout

def-autonomy/
├── .gitignore              # Ignores byte-code, virtualenvs, output figures, and raw datasets
├── requirements.txt        # Single dependency (numpy >= 1.20.0)
├── README.md               # Framework manual, setup instructions, and mathematical specifications
├── def_core.py             # Abstract Dynamic Drive-Evaluation-Function agent core
├── def_optimizer.py        # Complete (μ + λ) Evolutionary Strategy optimizer 
├── example_autoscaler.py   # Concrete cloud infrastructure resource simulation environment
└── tests/
    ├── __init__.py         # Configures testing paths and package boundaries
    └── test_core.py        # Comprehensive test suite for state boundaries and drive dynamics

---

⚡ Quick Start & Verification

1. Installation

# Clone the codebase
git clone https://github.com/your-username/def-autonomy.git
cd def-autonomy

# Initialize and launch virtual environment
python -m venv venv
source venv/bin/activate  # On Windows run: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Execution of the Cloud Cluster Autoscaler Simulator

Execute the physical simulator, which models a cluster managing variable traffic demands, resource exhaustion boundaries, and periodic security vulnerabilities:

python example_autoscaler.py

3. Hyperparameter Tuning via Evolutionary Search

Run the localized evolutionary strategy to discover optimized policy weights that minimize system error rates and maximize survival steps:

python def_optimizer.py

4. Running Verification Unit Tests

Verify the structural integrity of the mathematical boundaries and behavioral transitions:

python -m unittest tests/test_core.py

---

📊 Comprehensive Mathematical Specification of the Codebase

This section details the formal mathematical formulations executed inside the def_core.py controller and simulated across the environment step loops.

1. Vector Spaces & System Primitives

The internal physiological state of the cybernetic agent is defined at any discrete time $t$ by a vector $x_t \in \mathbb{R}^2$: $$x_t = \begin{bmatrix} x_{0, t} \ x_{1, t} \end{bmatrix}$$

• $x_{0, t} \in [0, 10]$ represents the System Headroom / Satiety (e.g., free memory or available worker threads).
• $x_{1, t} \in [0, 10]$ represents the Operational Stress / Toxicity / Error Rate (e.g., request latency or thread queue depth).

The long-term infrastructure capacities are managed by auxiliary scalar state variables:

• $x_{c, t} \in [0, 10]$ represents Catabolic Resource Capacity (e.g., absolute virtual machine allocation limit).
• $x_{e, t} \in [0.1, 10]$ represents Active Energy/Memory Headroom (e.g., active heap size).

The spatial state coordinates of the agent and environmental features are:

• $ag_t \in \mathbb{R}^2$: Physical coordinate center of the agent.
• $pf_t \in \mathbb{R}^2$: Physical coordinate center of the nearest resource target.
• $thr_t \in \mathbb{R}^2$: Physical coordinate center of the nearest threat/hazard.

---

2. Sensory Signal Transduction

The raw spatial distances to physical opportunities and constraints are mapped to exponential sensory feedback signals ($F_t, H_t \in [0, 10]$): $$d_{\text{pos}} = |pf_t - ag_t|2$$ $$d{\text{threat}} = |thr_t - ag_t|_2$$

The positive and negative stimulus profiles are converted as follows: $$F_t = 10.0 \cdot e^{-\frac{d_{\text{pos}}}{15}}$$ $$H_t = 10.0 \cdot e^{-\frac{d_{\text{threat}}}{15}}$$

---

3. Regime Arbitration (Behavioral Mode Selection)

The agent dynamically updates its target state vector $\xi_t \in \mathbb{R}^2$ and selects its operational regime $cl_t$ by evaluating internal state metrics against boundary conditions defined in the genome parameters:

$$cl_t = \begin{cases} \text{SURVIVAL}, & \text{if } d_{\text{threat}} < \theta_{\text{threat}} \\ \text{EXPLOITATION}, & \text{if } d_{\text{threat}} \ge \theta_{\text{threat}} \text{ and } \left( x_{0, t} < \theta_{\text{forage}} \text{ or } x_{e, t} < \theta_{\text{conserv}} \right) \\ \text{CONSERVATION}, & \text{otherwise} \end{cases}$$

Where:

• $\theta_{\text{threat}}$ represents the threat activation boundary parameter (threat_radius).
• $\theta_{\text{forage}}$ represents the foraging activation threshold parameter (exploitation_trigger_thresh).
• $\theta_{\text{conserv}}$ represents the conservation activation threshold parameter (conservation_trigger_thresh).

The homeostatic target vector $\xi_t$ represents the local ideal physiological state toward which the system will direct its control efforts: $$\xi_t = \begin{cases} \begin{bmatrix} x_{0, t} \ 0.0 \end{bmatrix}, & \text{if } cl_t = \text{SURVIVAL} \ \begin{bmatrix} 10.0 \ x_{1, t} \end{bmatrix}, & \text{if } cl_t = \text{EXPLOITATION} \ \begin{bmatrix} 10.0 \ 0.0 \end{bmatrix}, & \text{if } cl_t = \text{CONSERVATION} \end{cases}$$

---

4. Drive Tension & Sensory Gating

The environmental divergence $E_t$ measures how far external stimuli are from the current target state, while the internal deficit $D_t$ measures internal physiological deviation: $$E_t = \left| \begin{bmatrix} F_t \ H_t \end{bmatrix} - \xi_t \right|_2$$ $$D_t = \left| \xi_t - x_t \right|_2 + \epsilon \quad (\text{where } \epsilon = 10^{-5})$$

The sensory gating weight $x_{w, t}$ is a rectified comparison of external opportunities against internal deficits, serving as a non-linear threshold gate: $$x_{w, t} = \max\left( 0.0, E_t - D_t \right)$$

---

5. Net Metabolic Field & Action Utility Selection

Operational efficiency $\eta_t$ is calculated from auxiliary capacity margins and spatial distance costs ($c = 0.01$): $$\eta_t = 0.05 \cdot x_{c, t} - 0.02 \cdot x_{e, t} - c \cdot d_{\text{pos}}$$

The genome contains mapping matrices $A_{cl}$ for each behavioral regime $cl$. Each row $a_j$ of the active policy matrix represents a candidate action vector. The raw dot product computes alignment with the homeostatic deficit: $$\text{dot}_j = a_j^T (\xi_t - x_t)$$

Applying a sigmoidal activation models policy selection probability: $$\sigma(\text{dot}_j) = \frac{1}{1 + e^{-\text{clip}(\text{dot}_j, -500, 500)}}$$

The agent evaluates utility $U_j$ across all candidate action vectors in the policy matrix and selects the index maximizing this metric: $$U_j = (\eta_t - G_{\text{field}}) \cdot \sigma(\text{dot}j) \cdot x{w, t} \cdot \zeta_t$$

Where:

• $G_{\text{field}} = 1.0$ represents the baseline goal field inhibition.
• $\zeta_t$ is an emergency scalar defined as: $$\zeta_t = \begin{cases} 1.0 + e^{-\frac{d_{\text{threat}}}{\theta_{\text{gate}}}}, & \text{if } cl_t = \text{SURVIVAL} \ 1.0, & \text{otherwise} \end{cases}$$ (where $\theta_{\text{gate}}$ represents the threat gate radius parameter, threat_gate_radius)

The system selects the optimal action index $a^$: $$a^ = \arg\max_{j} U_j$$

---

6. Physical Actuation and System Drift Updates

Once the optimal policy action index is selected, physical movement vectors ($mv_t$) are generated:

$$\begin{aligned} \text{Let } \hat{u}(v) &amp;= \frac{v}{|v|_2} \quad (\text{for } |v|_2 &gt; 10^{-8}, \text{ else } v) \\ mv_t &amp;= \begin{cases} \hat{u}(ag_t - thr_t), &amp; \text{if } cl_t = \text{SURVIVAL} \text{ and } d_{\text{threat}} \ge 10 \\ \hat{u}\Big(0.7 \cdot \hat{u}(ag_t - thr_t) + 0.3 \cdot \hat{u}(ag_t - nf_t)\Big), &amp; \text{if } cl_t = \text{SURVIVAL} \text{ and } d_{\text{threat}} &lt; 10 \\ \hat{u}(pf_t - ag_t), &amp; \text{if } cl_t = \text{EXPLOITATION} \text{ and } d_{\text{threat}} \ge 15 \\ \hat{u}\Big(0.75 \cdot \hat{u}(pf_t - ag_t) + 0.25 \cdot \hat{u}(ag_t - nf_t)\Big), &amp; \text{if } cl_t = \text{EXPLOITATION} \text{ and } d_{\text{threat}} &lt; 15 \\ \begin{bmatrix} 0 \ 0 \end{bmatrix}, &amp; \text{if } cl_t = \text{CONSERVATION} \text{ and } a^* = 0 \\ 0.4 \cdot \hat{u}(pf_t - ag_t), &amp; \text{if } cl_t = \text{CONSERVATION} \text{ and } a^* &gt; 0 \end{cases} \end{aligned}$$

The physical step uses the speed limit parameter $v_{\max}$ (v_max): $$ag_{t+1} = \text{Clip}(ag_t + mv_t \cdot v_{\max}, 0.0, W)$$

Physiological and metabolic capacities decay linearly at each discrete time step: $$x_{0, t+1} = \max\left(0.0, x_{0, t} - 0.02\right)$$ $$x_{1, t+1} = \max\left(0.0, x_{1, t} - 0.03\right)$$ $$x_{c, t+1} = \max\left(0.0, x_{c, t} - 0.01\right)$$ $$x_{e, t+1} = \text{Clip}\left(x_{e, t} + 0.05 \cdot x_{c, t} - 0.02 \cdot x_{e, t} - c, 0.1, 10.0\right)$$