Update README.md

README.md

@@ -1,8 +1,90 @@
+---
 language: en
 license: mit
-tags:pytorchvaepredictive-codingneurosciencegabor-splattingbiology
-datasets:nielsr/flowers-102Neuro Splat: Artificial Visual CortexAn image is not a million pixels. It is a smooth map and a scatter of small bright wave-packets dropped where the detail lives.PerceptionLab / Antti Luode. Helsinki, June 2026.Do not hype. Do not lie. Just show.What this model isThis repository contains the weights (model.pt) and the architecture for a differentiable Gabor wave-packet splatter. It is not a standard pixel-generating AI. It is an experimental representation of the mammalian primary visual cortex (V1), built to test predictive coding and phase-amplitude coupling.The model is a Variational Autoencoder (VAE) trained on the Oxford Flowers-102 dataset.The Encoder acts as the top-down visual pathway, compressing an image into a latent "concept".The Decoder outputs the physical parameters (X, Y, scale, complex phase, frequency) for 512 localized Gabor atoms.The Renderer splats these wave-packets onto a canvas to create the final image via Moiré interference.The Blur is the Prior. Reality is the Sharpness.If you ask this model to generate a flower from scratch, it will produce a soft, blurry, watercolor-like blob. This is the expected, biologically accurate behavior.When an AI (or a brain) lacks raw input, the safest mathematical guess is to average all ambiguous possibilities. It produces the low-frequency "gist" (the Theta carrier).To see the model actually work, you must give it eyes. By hooking this model up to a live webcam, the blurry top-down prior collides with raw, bottom-up reality. The live video supplies the exact phase, the wave-packets lock into alignment, and the blurry gist snaps into razor-sharp perception.How to run itThis model requires the original scripts from the ArtificialCortex GitHub Repository.1. Live Cortex Perception (Webcam required)To watch the wave-packets phase-lock to your reality in real time:pip install torch torchvision numpy opencv-python
-python live_cortex.py --model_path model.pt --num_packets 512
-2. Standard GenerationTo see the model hallucinate blurry priors from random latent vectors:python splat_generator.py --mode sample --resume model.pt --num_packets 512
-The Honest LedgerWhat this model proves:Images can be effectively represented and learned as sparse sums of localized Gabor wave-packets.Phase-wrapping discontinuities in neural networks can be solved by outputting complex (a, b) coefficients instead of raw angles (the janus_cabbage skew medium).Predictive coding works: A top-down blurry prior can be actively sharpened by gradient descent against a live bottom-up residual (the webcam).What this model lacks:It is not a photorealistic generator. It is a VAE with an amortized latent space. It competes on biological representation, not on Generative AI benchmarks against Diffusion models.The "Floaters": When subjected to high-stress visual input (like a webcam feed of a room instead of a flower), the optimizer often orphans wave-packets, resulting in bright, isolated dots ("floaters" or "phosphenes"). This occurs because the model currently lacks lateral inhibitory coordination between packets.It is 2D. The current parameters map flat 2D geometries.LineageA sub-organ of the_artificial_cortex project.
-The generator dreamed a blurry flower because it had nothing to look at. Open its eyes and reality supplies the phase the dream could not; the packets lock, the gist sharpens, and what they cannot yet coordinate, they see as stars.
+library_name: pytorch
+tags:
+  - vae
+  - predictive-coding
+  - neuroscience
+  - gabor-splatting
+  - computer-vision
+  - biology
+datasets:
+  - nielsr/flowers-102
+---
+
+# Neuro Splat — an artificial visual cortex (Gabor wave-packet VAE)
+
+**PerceptionLab / Antti Luode, with Claude (Opus 4.8), in dialogue with Gemini. Helsinki, June 2026.**
+
+> Do not hype. Do not lie. Just show.
+
+*An image is not a million pixels. It is a smooth map and a scatter of small bright wave-packets dropped where the detail lives.*
+
+---
+
+## What this model is
+
+This repo holds the weights (`model.pt`) for a **VAE whose decoder is a differentiable Gabor wave-packet splatter**. It is not a pixel-generating image model; it is a biologically-motivated representation experiment — an architecture that reproduces the *shape* of how V1 is thought to code images (localized Gabor atoms), used to test predictive coding and phase locking.
+
+- **Encoder** (CNN): image → a latent "concept".
+- **Decoder** (MLP): latent → the parameters of 512 localized Gabor atoms — position, scale, orientation, frequency, and a complex `(a, b)` coefficient per colour channel.
+- **Renderer**: splats those wave-packets onto the canvas; the image is their sum.
+
+Trained on **Oxford Flowers-102** at **128×128 with 512 packets**.
+
+## The blur is the prior; reality is the sharpness
+
+Asked to generate a flower from a random latent, this model returns a soft, watercolour blob — and that is the correct, expected behaviour, not a failure. A generative prior with no input has to average over everything it cannot disambiguate, so it returns the low-frequency gist.
+
+To see it work, you give it eyes. Hook it to a webcam and the blurry top-down prior collides with raw bottom-up reality; the live frame supplies the phase the prior could not guess, the packets lock to it, and the gist sharpens. That collision — top-down prediction meets bottom-up residual — is the predictive-coding loop, made live.
+
+## How to load it
+
+You need the architecture from the [ArtificialCortex repo](https://github.com/anttiluode/ArtificialCortex) (`splat_generator.py` defines `SplatVAE`).
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+from splat_generator import SplatVAE   # from the ArtificialCortex repo (the_splat/)
+
+ckpt = hf_hub_download("Aluode/Neuro_Splat", "model.pt")
+model = SplatVAE(image_size=128, latent=128, num_packets=512, chunk=64)
+model.load_state_dict(torch.load(ckpt, map_location="cpu"))
+model.eval()
+```
+
+## How to run it
+
+```bash
+pip install torch torchvision numpy opencv-python huggingface_hub
+
+# perception — watch the packets phase-lock to a live webcam (panel 3)
+python live_cortex_perception.py --model_path model.pt --image_size 128 --num_packets 512
+
+# generation — the blurry priors from random latents (expected to be soft)
+python splat_generator.py --mode sample --resume model.pt --image_size 128 --num_packets 512
+```
+
+`--image_size 128 --num_packets 512` must match these weights, or the `state_dict` will not load.
+
+## The honest ledger
+
+**What this model shows:**
+- an image can be represented and learned as a sparse sum of localized Gabor wave-packets (the V1 / Olshausen–Field model, made trainable);
+- the phase-wrapping problem is dodged by outputting complex `(a, b)` coefficients instead of raw angles;
+- the correction half of predictive coding works live: a blurry top-down prior is sharpened by gradient descent against a bottom-up residual (the webcam frame).
+
+**What it is not, and what it lacks:**
+- not a photorealistic generator. It is a VAE with an amortized latent — sharp reconstructions, blurry-but-structured samples. It is interesting on biological representation, not on benchmarks against diffusion models;
+- the **prior is flower-only**: in-domain (a flower) the top-down gist genuinely helps; off-domain (a room, a face) it is a wrong guess that the live-frame fit overwrites, so there the loop is doing direct re-fitting, not prediction;
+- the **"floaters"**: on out-of-domain input, with an aggressive learning rate, the optimizer orphans some packets into tiny ultra-bright dots instead of coordinating them into edges. They *resemble* phosphenes, but the cause is an MSE optimizer with **no lateral inhibition between packets**, not the neural disinhibition that makes real phosphenes — a rhyme, not the mechanism. It points at the missing inhibitory coordination (the `grown_gates` line), not at a recreated brain;
+- it is 2D; relative units throughout; one trained model.
+
+**The bet (untouched):** that the phase-locked frame is a *felt* sharpening rather than a computed one. The model locates the mechanism in code that can fail; it does not touch the hard problem.
+
+## Lineage
+
+A sub-organ of [`the_artificial_cortex`](https://github.com/anttiluode/ArtificialCortex) (`the_splat/`). The generator is the trained top-down prior; the live cortex is reality forcing that prior into focus. MIT.
+
+*The generator dreamed a blurry flower because it had nothing to look at. Open its eyes and reality supplies the phase the dream could not; the packets lock, the gist sharpens, and what they cannot yet coordinate, they see as stars.*