# Qriton HLM — Energy Language

**Program neural networks by shaping energy landscapes.**

The first tool that lets you directly program a neural network's behavior —
not train, not fine-tune, not prompt-engineer. **Program.**

> *"Energy minima as a programming language — in a completely new fashion."*
> — **John J. Hopfield**, March 2026

```
$ qriton-hlm -c model.pt

hlm:model> capture 5 polite Thank you so much for your help
  Captured L5: "Thank you so much for your help"
  Energy: -12.34 | Basin: True (cos=0.97, 23 iters)
  -> Added to concept 'polite' (1 samples)

hlm:model> capture 5 polite I really appreciate your patience
  -> Added to concept 'polite' (2 samples)

hlm:model> inject-concept 5 polite 0.1
  Before: 200 basins, concept is basin: False
  After:  201 basins (+1), concept is basin: True
  >> Concept successfully injected!

hlm:model> apply 5
hlm:model> generate Tell me about the weather
  I'd be happy to share! The weather today is...
```

## Install

```bash
pip install qriton-hlm
```

## What is this?

Every AI framework today has one way to change model behavior: **training**.
Qriton HLM adds a second: **surgery**.

This only works because HLM uses polynomial Hopfield dynamics that create
**multiple stable basins** per layer. Transformers can't do this — their
softmax attention collapses to a single attractor.

<p align="center">
  <img src="diagrams/transformer_vs_hlm.svg" alt="Transformer vs HLM comparison" width="700"/>
</p>

<p align="center">
  <img src="diagrams/basin_surgery.svg" alt="Basin surgery operations" width="700"/>
</p>

## 32 Operations — Complete Energy Language

### Observe (read the landscape)

| Command | What it does |
|---------|-------------|
| `survey <layer>` | Map all basins in a layer |
| `survey-all` | Survey every layer |
| `verify <layer> <seed>` | Check if a point is a basin |
| `energy <layer> <seed>` | Measure energy at a point |
| `probe <layer> [basin_idx]` | What tokens does a basin activate? (reverse capture) |
| `landscape <layer>` | Full energy map with population bars |

### Modify (change the landscape)

| Command | What it does |
|---------|-------------|
| `inject <layer> <seed> [str]` | Create a new attractor |
| `remove <layer> <seed> [str]` | Destroy an attractor |
| `move <layer> <seed> [str]` | Relocate an attractor |
| `strengthen <layer> <seed> [f]` | Deepen an existing basin |
| `weaken <layer> <seed> [f]` | Make a basin shallower |

### Concept (semantic operations)

| Command | What it does |
|---------|-------------|
| `capture <layer> <concept> <text>` | Extract what a concept looks like in the model |
| `inject-concept <layer> <concept> [s]` | Program a captured concept as a new attractor |
| `remove-concept <layer> <concept> [s]` | Remove a concept from the model |
| `blend <a> <b> <new> [ratio]` | Mix two concepts (e.g. 70% polite + 30% formal) |
| `concepts` | List all captured concepts |
| `export-concept <name> <path>` | Save concept as portable file |
| `import-concept <path>` | Load concept from file |

### Control (flow & persistence)

| Command | What it does |
|---------|-------------|
| `load <path>` | Load a checkpoint |
| `apply <layer>` | Write modified W to live model |
| `restore <layer>` | Undo modifications |
| `restore-all` | Restore all layers |
| `save <path>` | Save modified W matrices |
| `status` | Show which layers are modified |
| `set <param> <value>` | Set parameter (beta, strength, ...) |
| `info` | Show model info |

### Verify (test & audit)

| Command | What it does |
|---------|-------------|
| `generate <prompt>` | Generate text with current model |
| `diff <layer>` | Show W matrix change stats |
| `benchmark` | Measure perplexity impact of surgery |
| `guard <layer> [max_%]` | Prevent removing too many basins |
| `history` | Show operation log |

### Scripts

Write `.hlm` scripts to chain operations:

```bash
# make_polite.hlm
load model.pt
capture 5 polite Thank you so much
capture 5 polite I really appreciate it
capture 5 polite That's very kind of you
inject-concept 5 polite 0.1
apply 5
benchmark
generate Tell me about the weather
restore 5
```

Run with: `qriton-hlm --script make_polite.hlm`

## Python API

```python
from qriton_hlm import BasinSurgeon

surgeon = BasinSurgeon.from_checkpoint("model.pt", device="cuda")

# Capture what a concept looks like in the model
surgeon.capture(layer=5, text="Thank you so much", concept_name="polite")
surgeon.capture(layer=5, text="I really appreciate it", concept_name="polite")

# Inject that concept as a new attractor
result = surgeon.inject_concept(layer=5, concept_name="polite", strength=0.1)
print(f"Concept injected: {result['exists_after']}")

# Blend two concepts
surgeon.blend("polite", "formal", "professional", ratio=0.6)

# Export concept for sharing
surgeon.export_concept("polite", "polite.concept")

# Transplant concept from another model
other = BasinSurgeon.from_checkpoint("other_model.pt")
surgeon.transplant(other, layer=5, concept_name="humor")

# Apply to live model and benchmark
surgeon.apply(layer=5)
result = surgeon.benchmark()
print(f"PPL after surgery: {result['perplexity']:.2f}")

# Probe: what does basin #3 represent?
probe = surgeon.probe(layer=5, basin_idx=3)
print(f"Top tokens: {probe['top_tokens']}")

# Compare basins between models
diff = surgeon.compare(other, layer=5)
print(f"Shared: {diff['shared']}, unique: {diff['only_self']}")
```

## Compatibility

Works with any PyTorch checkpoint that contains `hopfield.W` parameters:
- HLM2/HLM3 language models
- HLM-Spatial (LIDAR, Medical3D, Industrial3D)
- HLM-Audio (STT, TTS)
- Any model using PolyHopfieldLayer

## Requirements

- Python >= 3.9
- PyTorch >= 2.0
- NumPy

## License

Apache 2.0 — Qriton Technologies S.R.L.
