gianlucamazza/affective-fly

Reduced *Drosophila* mushroom-body circuit (Kenyon cells, DANs, MBONs) as the affect source for emotional-memory. Decisions use approach/avoid rates and a slow mood average, not embedding similarity.
Python 3.11+. Mapping: linear, documented in docs/MAPPING_MBON_DAN.md. Loop and modules: docs/ARCHITECTURE.md. Backend runtimes: docs/BENCHMARKS.md. Open work: docs/ROADMAP.md. Full index: docs/README.md.
Human-emotion words from honesty.py are labels on the circumplex, not claims about fly experience.
What it does
affective-fly turns a stream of host events into an **affective state** — valence, arousal, and an approach/avoid tendency on Russell's circumplex — and a discrete decision (wait, act, or skip). That state comes from a reduced *Drosophila* mushroom-body circuit (Kenyon cells → dopaminergic DANs → MBON output neurons), not from text embeddings.
It is the *affect source* for emotional-memory: the current affect is written onto encoded memories, and retrieved memories feed back into the next decision. Where a similarity-only memory reacts to *what* an event resembles, this reacts to *how the accumulated experience feels* — a slow mood (MoodField, τ in seconds) that carries across ticks and across processes.
How it works
Each tick (AffectiveLoop.step; full flow in docs/ARCHITECTURE.md):
- **Encode**: the current affect is attached to the memory via EmotionalMemory.set_affect / encode.
- **Retrieve**: past memories are recalled and can veto a decision (strongly negative recalled valence → SKIP).
- **Learn**: a reported reward/outcome triggers three-factor plasticity on KC→MBON weights (PAM if positive, PPL1 if negative).
The circumplex/mood readout of a demo episode is shown under Usage.
Objectives
- Provide a stable, interpretable valence/arousal signal as input to emotional-memory.
- Keep a documented, calibrated mapping from spiking rates to the MBON/DAN bands (docs/MAPPING_MBON_DAN.md), so real circuits — not only MockFlyCircuit — drive Policy and ActionGate.
- Support three-factor learning and versioned host integration (HostFrame, journal replay).
- Stay honest and reproducible: ruff/mypy clean, tests green, benchmarks committed, and no claim beyond what the code does (without a real connectome the KC→MBON weights are random, and the code says so).
Not in scope
Not a trading or financial product. Sex/mating ensembles and swarms of N ≫ 8 are also out of scope (see docs/ROADMAP.md). Brian2 C++ standalone codegen is opt-in (Brian2Circuit(codegen_target="cpp_standalone")); the default remains numpy so CI needs no compiler.
Installation
numpy is pinned below 2.x so Brian2 2.9 imports on 3.11. Extra embed (sentence-transformers) is optional; MiniLM is not loaded by make demo. Equivalent: pip install -e ".[dev,brian,viz]".
Usage
python -m affective_fly run uses lab mood taus (8 / 4 / 5 s) so valence moves in seconds and writes measure.jsonl with mood_dt=1.0. python -m affective_fly study uses MoodField() defaults (300 / 60 / 180 s) and wall-clock mood_dt. Those taus stay unvalidated hypotheses until a real host session — see docs/ARCHITECTURE.md and docs/PHASE6_MEASUREMENT.md.