# 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

One Docker command is all it takes:

```bash
docker run -d --restart unless-stopped \
  -e SERVER_URL=https://your-domain.com \
  -v gcp_egg_data:/data \
  git.hexadual.io/rocobo/gcp-dot-egg:latest
```

The egg will immediately start sending one trial per second and persist its ID across restarts.

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `SERVER_URL` | `http://localhost:8000` | 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.

## Build from Source

```bash
docker build -t gcp-egg .
docker run -d --restart unless-stopped \
  -e SERVER_URL=https://your-domain.com \
  -v gcp_egg_data:/data \
  gcp-egg
```

## Project Structure

```
GCP/
├── egg.py             # Egg client — all logic (~70 lines)
├── requirements.txt   # requests==2.31.0
├── Dockerfile
└── .gitea/workflows/
    └── docker.yml     # CI: builds and pushes egg image on every push to main
```

## Published Images

Every push to `main` builds and publishes to the Gitea container registry via Gitea Actions:

| Image | Pull |
|---|---|
| Egg | `docker pull git.hexadual.io/rocobo/gcp-dot-egg:latest` |
| Server | `docker pull git.hexadual.io/rocobo/gcp-dot-server: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://your-domain.com/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 |