arctl: Adaptive Resonance Control

"Code is for machines. Resonance is for intelligence."

1. Phase Space Trajectory (3D)

Visualizing the system's movement through Repetition (X), Energy (Y), and Temperature (Z).

2. Intervention Telemetry (2D)

Real-time monitoring of repetition loops and thermal spikes.

arctl is a hybrid control architecture for LLM inference, combining:

1. Hard Core — a deterministic state machine for physical sampling control.
2. Soft Core — a semantic resonance engine for latent space steering.

---

🎯 The Problem: Chaos in the Latent Space

Modern LLMs suffer from three fundamental flaws:

1. The Knowledge Dump: Training data is "emotionally polluted". Technical specs are mixed with fiction.
2. Temporal Blindness: Models confuse Past, Present, and Future because they live in discrete time.
3. Lack of Control: There is no mechanism to manage the "Pattern of Thought" (e.g., force a specific emotional mix).

The Experiment: Ask an LLM to explain "Pulse Width Modulation" (PWM) with different emotional overlays:

• Joy: "PWM is a dance of signals!" (Metaphorical distortion).
• Fear: "PWM is dangerous, circuits might explode!" (Risk hallucination).
• Calm: "PWM controls power via duty cycle." (Technical truth).

Conclusion: Hallucinations are often Resonance Errors. To fix this, we need to enforce the correct Resonance Profile (a precise mix of emotions) for each task.

---

🛠️ The Solution: Hybrid Control Anchored in Physics

We cannot rebuild the dataset (yet). But we can control the Resonance Profile of the inference.

Production-ready: Hard Core (kernel + Chronos + Icarus). Proof of concept: Soft Core (resonance engine).

arctl v1.3.1 implements a two-layer control system, anchored by Project Icarus and Chronos T-SPIRAL_ALIGNMENT:

1. The Hard Core (Kernel)

A deterministic Python state machine, now stabilized by the Icarus Geometric Anchor.

• Role: The Bodyguard.
• Function: Monitors entropy and repetition. It no longer just reacts to chaos; it actively forces the system's state to "tunnel" back towards a stable equilibrium, using the calculate_tunneling_vector logic. Failure (FALLBACK) is still explicit, but now it's the last line of defense, not the first.
• Philosophy: Stability is not a goal; it is a non-negotiable initial condition.
• Spec: Core transitions formally specified in TLA+ (see spec/kernel.tla).

2. The Soft Core (Resonance Engine)

Status: Experimental / Proof of concept

A semantic steering system that injects "Cognitive Anchors" (Semantic Code) into the context.

• Function: Tunes the model's latent space to the correct frequency (e.g., CALM for coding).
• Innovation: Verifies truth by checking Invariance across multiple emotional states.
• Limitation: Semantic injection consumes tokens and scales poorly. It is included here as a Proof of Concept. Ideally, this logic should be embedded directly into the Knowledge Base during training.

---

---

🗂️ Project Structure

arctl-project/
├── arctl/                     # Core package (The "Brain")
│   ├── __init__.py            # Version export
│   ├── core/                  # Hard Core (Deterministic Logic)
│   │   ├── __init__.py
│   │   ├── kernel.py          # Main state machine (The Bodyguard)
│   │   ├── icarus.py          # Icarus stability anchor (Geometry)
│   │   ├── chronos.py         # Temporal synchronization (T-Spiral)
│   │   ├── states.py          # Data structures (SystemState, Modes)
│   │   ├── profiles.py        # Resonance profiles (Emotion/Tone)
│   │   ├── anchors.py         # Cognitive anchors (Instructions)
│   │   └── mythos.py          # Semantic protocol (The Warden's Verse)
│   ├── engine/                # Soft Core (Resonance Logic)
│   │   ├── __init__.py
│   │   └── synthesizer.py     # Multi-pass semantic synthesis
│   └── verification/          # Metrics & Truth Checking
│       ├── __init__.py
│       ├── lexical.py         # Entropy & Repetition analysis
│       ├── metrics.py         # Semantic Invariance checking
│       └── uncertainty.py     # Epistemic uncertainty scoring
├── tests/                     # Test Suite (Coverage: 100%)
│   ├── __init__.py
│   ├── test_core.py           # Kernel unit tests (27 tests)
│   ├── test_integration.py    # Full workflow tests (8 tests)
│   ├── test_icarus.py         # Stability math tests (7 tests)
│   └── benchmarks.py          # Performance & Throughput
├── examples/                  # Code Recipes & Demos
│   ├── arctl_in_inference_loop.py # Integration template (Stream API)
│   ├── basic_usage.py         # Minimal state machine
│   ├── resonance_demo.py      # Truth-by-invariance demo
│   ├── telemetry_simulation.py # Real-time dashboard (GIF generator)
│   └── visualize_phase_space.py # 3D Trajectory visualization
├── experiments/               # Reproducible Research
│   ├── README.md              # Experiment documentation
│   └── simulation_experiment.py # Data gen: Controlled vs. Chaos
├── docs/                      # Knowledge Base
│   ├── ARCHITECTURE.md        # Deep dive into Kernel & Icarus
│   ├── TESTING.md             # Guide to the 42 tests
│   ├── QUICKSTART.md          # 5-minute integration guide
│   └── TROUBLESHOOTING.md     # Resolving common friction points
├── spec/                      # Formal Methods
│   └── kernel.tla             # TLA+ Logic Specification
├── LICENSE                    # MIT License
├── README.md                  # Main entry point
├── CONTRIBUTING.md            # Rules of engagement (The Protocol)
├── VERSION                    # Single source of truth (v1.2.0)
├── arctl_demo.gif             # Telemetry visual asset
├── arctl_phase_space.gif      # Phase space visual asset
├── pyproject.toml             # Build configuration
├── pytest.ini                 # Test runner configuration
└── run_tests.py               # Universal test script

---

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/graevka-lab/arctl.git
cd arctl-project

# Minimal install (Hard Core only; no GPU needed)
pip install -e .

# With resonance verification (optional; pulls sentence-transformers)
pip install -e ".[verification]"

# With examples/visualization
pip install -e ".[viz]"

Minimal usage:

from arctl.core.kernel import step, SystemState, ControllerConfig
from arctl.core.states import RawMetrics

cfg = ControllerConfig()
state = SystemState.initial(0.0)
metrics = RawMetrics(entropy=0.5, divergence=0.0, repetition=0.3)
new_state = step(metrics, state, 1.0, cfg)
# new_state.mode, new_state.energy, new_state.active_config

Running Tests

# All tests (42 total): unit + integration + Icarus
python -m unittest discover -s tests -v
# or: python -m pytest tests/ -v
python run_tests.py

# Specific suites
python -m unittest tests.test_core -v       # Unit tests (27)
python -m unittest tests.test_integration -v # Integration (8)
python -m unittest tests.test_icarus -v     # Icarus stability (7)

# Benchmarks
python tests/benchmarks.py

Reproducible experiment (with vs without arctl):

python experiments/simulation_experiment.py

Integration example (plug arctl into your inference loop):

python examples/arctl_in_inference_loop.py

Running Demos

1. Resonance Demo (Soft Core)
   See how the engine extracts truth from different perspectives:

   python examples/resonance_demo.py

2. Telemetry Simulation
   Real-time monitoring visualization:

   python examples/telemetry_simulation.py

3. Phase Space Visualization
   3D trajectory through state space:

   python examples/visualize_phase_space.py

---

🕰️ The Chronos Axiom (T-SPIRAL_ALIGNMENT)

Standard LLMs suffer from "Future Shock" — they deny events that happened after their training cutoff.
arctl solves this not by retraining, but by Temporal Alignment under the T-SPIRAL_ALIGNMENT protocol:

• Time as geometry: one timestamp is decomposed into 8 layers — YEARS | MONTHS | WEEKS | DAYS | HOURS | MINUTES | SECONDS | MILLISECONDS (see time_to_layers() in arctl.core.chronos).
• State logic: the cursor is NOW. Any coordinate ≤ NOW is FROZEN_STATE [READ_ONLY] (past + transition point); any coordinate > NOW is PROBABILISTIC_FIELD [READ_WRITE] (future). Implemented as temporal_state_at(coordinate, cursor) and reflected in the context note from Chronos.sync().

Gap classification for prompt injection:

• SYNC (< 1 min): Immediate flow. High context retention.
• LAG (> 1 min): User lived through time the model didn't see.
• GAP (> 24 hours): Significant reality shift. Context reset recommended.

---

📜 Philosophy

We believe that Truth is Resonance.
Instead of optimizing for a single "best" token (RLHF), we search for the semantic structure that survives the perturbation of emotional states.

If a fact is true, it remains true whether you are Calm, Joyful, or Vigilant.
If it changes, it is an illusion.

For a deeper dive into the system architecture, see docs/ARCHITECTURE.md.
For testing guidance, see docs/TESTING.md.

---

🤝 Contributing

This project is a Signal to the broader community about control mechanisms for LLMs.
Contributions, discussions, and feedback are welcome!

If you have the hardware to retrain foundation models on Resonance-Aligned Data — let's connect.

📧 Contact

GitHub: @graevka-lab

X (Twitter): @Graevka

LinkedIn: Graevka Suvorov

---

⚡ A Note on Priorities

This project adheres to the "Function over Form" doctrine.

The test suite and benchmarks exist solely to guarantee Kernel Integrity. Coverage metrics are not chased for the sake of bureaucracy.

• 90% of the value lies in the kernel.py state machine and the Chronos temporal axiom.
• 10% of the code is the interface.

If you seek "Enterprise" patterns over operational logic — this repository is not for you. If you seek a mechanism that works in practice to solve temporal hallucinations and loop degradation — welcome.

---

🏛️ CREDITS & ACKNOWLEDGMENTS

• Kyle Workman (Project Icarus): For providing the Universal Stability Skeleton v1.0. The core mathematical constants ($\Phi = 1.618$, $\pi = 3.141$, $V_{\text{Matrix}} = 19.25$) are now embedded in arctl.core.icarus as the Geometric Anchor for entropy management.
  • Note: Proprietary pulse-timing variables have been redacted per the architect's protocol.

---

License

MIT License — See LICENSE for details.

Built for those who understand that:

No hidden state.
No infinite loops.
No recovery without cost.
Failure is explicit.