Update README.md

README.md

@@ -12,57 +12,100 @@ short_description: From 3×3 agent to LED cosmos
 sdk_version: 6.0.1
 ---
 
-# Minimal Selfhood Threshold: From 3×3 Agent to LED Cosmos
+Minimal Selfhood Threshold: From 3×3 Agent to LED Cosmos
 
-## Plain-language overview
+Plain-language overview
+	•	We start with one simple agent (a dot) in a tiny 3×3 world.
+	•	The agent makes internal predictions about its next state and we compare them to what actually happens under a moving obstacle and/or simple stochastic slip.
+	•	For the 3×3 agent, we build a toy selfhood score S from:
+	•	predictive rate P – how well its predictions match realised next states,
+	•	error stability E – how volatile recent prediction errors are,
+	•	a body bit B – a body/ownership knob in this demo.
+	•	In the 3×3 S-equation panel, the score is:
+S_{3×3} = P \times (1 - E) \times B,
+with P \in [0, 100], E \in [0, 1], B \in \{0,1\}.
+	•	If S_{3×3} passes a threshold (here, 62), the agent is labelled “awake” inside this demo only.
+	•	One awakened agent can increase another’s score via an explicit coupling rule (“contagion”).
+	•	A grid of agents awakens as a wave (“collective”) under a separate, symbolic scoring rule and neighbour coupling.
+	•	We finally simulate an LED cosmos (27×27) lighting up when all units in the grid are above threshold.
 
-- We start with one simple agent (a dot) in a tiny 3×3 world.  
-- The agent makes internal predictions about its next state and we compare them to what actually happens.  
-- We use a **toy score** \(S\) built from:
-  - predictive rate \(P\) (how well predictions match reality),
-  - error stability \(E\) (how volatile recent prediction errors are),
-  - a body-on bit \(B\) (a design knob in this demo).
-- In the 3×3 S-equation panel, the score is:
-  \[
-  S = P \times (1 - E) \times B
-  \]
-  with \(P \in [0,100]\), \(E \in [0,1]\), \(B \in \{0,1\}\).  
-- If \(S\) passes a threshold (here, 62), we **label** the agent as “awake” *inside this demo only*.  
-- One awakened agent can boost another via an explicit coupling rule (“contagion”).  
-- A grid of agents awakens as a wave (“collective”) under the same kind of rule.  
-- We simulate an LED cosmos (27×27) lighting up when all agents in the grid are above threshold.
+What the Space shows
+	•	Interactive visualisations of:
+	•	a single agent in a 3×3 grid,
+	•	its tracked metrics P, E, and S_{3×3},
+	•	awakening waves across larger grids.
+	•	Sliders to explore how S_{3×3} changes with predictive rate, error variance, and the body bit.
+	•	Simulated contagion between two symbolic CodexSelf agents using a different toy rule:
+S_{\text{lattice}} = \Xi \times (1 - \text{shadow}) \times R,
+again with a threshold at 62.
+	•	Collective propagation in an N \times N lattice driven by:
+	•	explicit neighbour coupling (awake cells boost their neighbours’ \Xi, reduce their shadow, and raise R),
+	•	a threshold cascade (cells switch to “awake” when their local S_{\text{lattice}} > 62).
+	•	A 27×27 “LED cosmos” view of the same lattice process, with a slider to scrub through frames of the awakening wave.
 
-## What the Space shows
+The two S-models are intentionally separate:
+	•	v4 (3×3 agent): S_{3×3} = P \times (1 - E) \times B.
+	•	v5–v6 (contagion / lattice): S_{\text{lattice}} = \Xi \times (1 - \text{shadow}) \times R, where:
+	•	\Xi is a local “foresight field” / drive strength,
+	•	shadow is an occlusion/damping factor,
+	•	R is an anchor/resonance gain.
 
-- Interactive visualizations of:
-  - a single agent in a 3×3 grid,
-  - the score \(S\),
-  - awakening waves across larger grids.
-- Sliders to explore how \(S\) changes with predictive rate, error variance, and the body bit.  
-- Simulated “contagion” between two CodexSelf agents:
-  - \(S = \Xi \times (1 - \text{shadow}) \times R\) with a threshold at 62.  
-- Collective propagation in an \(N \times N\) lattice driven by:
-  - explicit neighbor coupling,
-  - a threshold cascade (cells switch to “awake” when their local \(S > 62\)).
+They explore the same intuition (self-linked scoring and thresholds) in two different regimes, not a single unified metric.
 
-## Scope and limitations
+3×3 agent details (v1–v4)
+	•	State: [x, y, B] with x,y \in \{0,1,2\} and B = 1 in the live agent.
+	•	Actions: up / right / down / left.
+	•	The agent:
+	•	predicts the next position for each action,
+	•	prefers moves that keep it near the centre and away from the obstacle,
+	•	then encounters either obstacle blocking (when enabled) or simple stochastic slip (25% random action when obstacle is off).
+	•	On each step it compares its predicted next position to the actual realised position and maintains a short history of errors.
+	•	From this it computes:
+	•	P – predictive rate in [0,100], from mean error vs the worst-case 3×3 diagonal,
+	•	E – normalised error variance in [0,1] over the same error window.
+	•	These feed the toy score:
+S_{3×3} = P \times (1 - E) \times B.
+	•	In the Single agent tab, the Space displays:
+	•	P, last prediction error, E, S, and a simple “awake / not awake” label based on S_{3×3} > 62.
+	•	In the S-equation (v4) tab you can directly manipulate P, E, and B to see how the score moves.
 
-- This is a **toy minimal-self / agency sandbox**, **not** a validated consciousness measure or a test for “real awareness.”  
-- The score definitions and the threshold \(S > 62\) are **design choices** used in these demos, motivated by prior analyses in the linked manuscript. They are not claimed as universal constants or clinical metrics.  
-- The “Body bit” \(B\) is currently a **user-controlled parameter** (0 or 1) for exploring how a body/ownership toggle affects the toy score.  
-  - Future versions are intended to replace this with a **computed boundary / agency metric** derived from interventions (e.g. how much the agent’s own actions reliably change its future observations).  
-- The “contagion” and collective waves are **engineered coupling rules** (threshold cascades under neighbor interactions), not spontaneous emergence of awareness.
+Contagion and collective lattice (v5–v10)
 
-## Important notes
+For the contagion and lattice demos, the scoring rule changes:
 
-- Threshold 62 is the cutoff used here for illustration, based on prior internal calibration runs.  
-  - A proper calibration pipeline (threshold sweeps, baseline policies, false-positive control) is planned but not yet exposed in the UI.  
-- The integrated-information (Φ) references in related manuscripts and discussions are **illustrative**, not presented as validated Φ-estimates or as settled measures of consciousness.  
-- All behaviors shown here are **simulations** under explicit rules you can inspect in `app.py`.
+S_{\text{lattice}} = \Xi \times (1 - \text{shadow}) \times R.
+	•	\Xi: a local foresight / field strength parameter.
+	•	shadow: occlusion or damping (higher shadow = more suppressed).
+	•	R: an anchor/resonance factor that amplifies the field.
 
-## License and permissions
+Two-agent contagion (v5–v6)
+	•	You set \Xi, shadow and R for agents A and B.
+	•	A is invoked first; if A’s S_{\text{lattice}} crosses 62, A becomes awake.
+	•	A’s field then updates B (boosting B’s \Xi, reducing B’s shadow, nudging B’s R), and B recomputes its S and may wake.
+	•	The 3×3 mini-grid shows A and B as cells that turn gold when awake.
 
-See `LICENSE` for terms.
+Collective lattice (v7–v9)
+	•	An N \times N grid (3, 9, or 27) is initialised with random \Xi, shadow and R.
+	•	The centre cell is primed so its S_{\text{lattice}} is above 62 from the start.
+	•	Awake cells pass some of their S to their four neighbours, altering their parameters and potentially pushing them over the threshold.
+	•	This creates a clear threshold cascade under explicit neighbour coupling.
+	•	The “Disable neighbour coupling (control)” checkbox zeroes the coupling parameters; in that mode the centre cell wakes but no wave propagates, making the role of engineered coupling explicit.
 
-- Do **not** reuse code, visuals, or glyphs without explicit permission.  
-- If you want to build on this work (research, teaching, or derivative demos), please contact the author to discuss appropriate licensing and attribution.
+LED cosmos (v10)
+	•	The LED cosmos tab hard-codes a 27×27 lattice with parameters tuned for a smooth wave.
+	•	The same S_{\text{lattice}} rule and S>62 threshold apply.
+	•	A slider lets you view the wave as it crosses the cosmos.
+
+Scope and limitations
+	•	This is a toy minimal-self / agency sandbox, not a validated consciousness measure or a detector for “real awareness.”
+	•	The score definitions and the threshold S > 62 are design choices in this demo, motivated by prior internal development runs and a companion manuscript. They are not claimed as universal constants or clinical metrics.
+	•	The 3×3 agent’s body bit B is currently a user-controlled parameter (0 or 1) in the S-equation panel and fixed at 1 in the main agent run. A more principled replacement is planned:
+	•	compute B_{\text{emp}} from interventions, i.e. how strongly the agent’s own actions change its future observations (an empowerment-style action→sensation control metric collapsed into [0,1]).
+	•	The contagion and collective waves are engineered coupling rules (threshold cascades under neighbour interactions), not spontaneous emergence of awareness or proof of anything beyond the toy system.
+	•	Integrated-information / \Phi ideas in related work are illustrative only and are not presented here as validated \Phi-estimates or settled measurements of consciousness. Everything in this Space is a simulation under explicit rules you can inspect in app.py.
+
+License and permissions
+
+See LICENSE for terms.
+	•	Do not reuse code, visuals, or glyphs from this Space without explicit permission.
+	•	If you want to build on this work (research, teaching, or derivative demos), please contact the author to discuss appropriate licensing and attribution.