initial commit

README.md

@@ -0,0 +1,84 @@
+# GCP Egg
+
+Distributed client for the **Global Consciousness Project** — a self-hosted network variance tracker inspired by the [Global Consciousness Project](https://global-mind.org).
+
+Each "egg" container draws 200 random bits per second from the OS hardware-entropy pool and submits the count of 1-bits to a central server, which runs Stouffer Z-score analysis and displays a live colored dot.
+
+## Architecture
+
+```
+Egg containers (anyone can run)
+        │  POST /api/data  (one 200-bit trial per second)
+        ▼
+    Server (FastAPI + SQLite)
+        │  Stouffer Z network variance analysis every 60 s
+        ▼
+    Website  →  animated dot  +  history chart  +  embeddable iframe
+```
+
+The server is maintained separately. This repo contains only the egg client.
+
+## Run an Egg
+
+Download the compose file and start it — no building required:
+
+```bash
+curl -O https://git.hexadual.io/rocobo/GCP-Dot/raw/branch/main/docker-compose.yml
+docker compose up -d
+```
+
+Docker will pull the pre-built image from the registry automatically. The egg will immediately start sending one trial per second and persist its ID across restarts.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SERVER_URL` | `https://gcp.hexadual.io` | Server to send trials to |
+| `EGG_ID` | auto-generated | Override the egg's unique identifier |
+
+The auto-generated ID is derived from a SHA-256 hash stored at `/data/egg_id` — mount a volume there to keep it stable across restarts.
+
+## Published Image
+
+The egg image is built and published automatically on every push to `main`:
+
+```bash
+docker pull git.hexadual.io/rocobo/gcp-dot-egg:latest
+```
+
+## How the Analysis Works
+
+The server analyses the past hour of data every 60 seconds:
+
+1. **Normalise** each trial to a Z-score: `z = (trial − 100) / √50`
+   (Binomial(200, 0.5) has mean = 100, variance = 50)
+2. **Stouffer Z** per second across all active eggs: `S_t = Σzᵢ / √N`
+3. **Network variance**: `V = Σ S_t²` — follows χ²(T) under H₀
+4. **Index** = lower-tail CDF × 100
+
+### Color Table
+
+| Color | Index | Meaning |
+|---|---|---|
+| Blue | > 95% | Significantly small variance — deep coherence |
+| Cyan | 90–95% | Small variance — probable coherence |
+| Green | 40–90% | Normal random behavior |
+| Yellow | 10–40% | Slightly elevated variance |
+| Orange | 5–10% | Strongly elevated variance |
+| Red | < 5% | Significantly large variance |
+
+## Embed the Dot
+
+```html
+<iframe src="https://gcp.hexadual.io/gcp.html"
+        height="48" width="48" scrolling="no" frameborder="0"></iframe>
+```
+
+## Server API Reference
+
+| Endpoint | Description |
+|---|---|
+| `POST /api/data` | Submit a trial `{egg_id, timestamp, trial}` |
+| `GET /api/status` | Latest analysis result |
+| `GET /api/history?limit=60` | Last N analysis records |
+| `GET /api/eggs` | Eggs active in the last 2 minutes |