---
title: Content Generation Agent
emoji: 🧬
colorFrom: green
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
---

# 🧬 RSI Content Generation Agent — a self-improving Darwin machine

This is not a meme generator. It's a **living codebase** that farms human attention and
rewrites *its own source code* to get better at it.

A static content pipeline (memes today; whatever survives tomorrow) is wrapped in a
**Darwin Gödel loop**: a continuous cycle of **variation → selection → inheritance**. Every
few days an AI agent reads how the published content actually performed on the YouTube Shorts
algorithm, forms a hypothesis, mutates the code, and opens a pull request. The best mutations
survive and reproduce. The worst go extinct. The "jungle" is the recommendation algorithm.
The fitness function is real-world watch-time. Nobody hand-tunes the content strategy — it
*evolves*.

> **Status:** the full loop is wired end-to-end — daily generation (`/run/daily`), fitness
> refresh (`/fitness/refresh`), and the 3-day mutation cycle. Merge is human-gated by default
> and fully autonomous when `AUTONOMOUS_MERGE=true`. This README documents the system as built.
> (Live validation needs real API keys + the lab channel; see PLAN.md for what's exercised by
> the test suite vs. what only runs against real services.)

---

## The organism in one diagram

```
        ┌──────────────────────────────────────────────────────────────────────┐
        │                          HuggingFace Space (Docker)                    │
        │   The body: generates 3–5 videos/day, publishes them, AND fetches      │
        │   their analytics — it alone holds the per-tenant YouTube creds (Mongo)│
        │                                                                        │
        │   dispatcher → variants/* → publishers ───────────────▶ YouTube/Telegram
        │                                                              │ 3-day lag│
        │   harness/fitness.py [LOCKED]  ◀── per-tenant YT OAuth (Mongo)│         │
        │     reads Analytics for videos uploaded ≥3 days ago          ▼         │
        │     → computes APV/VSA/fitness → writes a SANITIZED scoreboard         │
        └───────────────────────────────────┬────────────────────────────────────┘
                                             │ MongoDB
              ┌──────────────────────────────┴──────────────────────────────────┐
              │  fitness_scoreboard            │   users  🔒 (OAuth + API keys)   │
              │  (no secrets — view metrics)   │   (agent must NEVER read this)   │
              └───────────────┬────────────────┴──────────────────────────────────┘
                              │ read-only Mongo role, scoped to fitness_scoreboard ONLY
                              ▼
        ┌────────────────────────────────────────────────────┐
        │                GitHub Actions (cron, every 3 days)   │
        │   The evolutionary engine — the agent lives here     │
        │                                                      │
        │   Aider mutator  (allowlist: variants/** only)       │
        │     reads fitness_scoreboard + EXPERIMENTS_LOG.md    │
        │     → appends hypothesis → mutates ONE variant       │
        │     → pytest in Docker → gh pr create                │
        └──────────────────────┬───────────────────────────────┘
                               ▼
                        ┌──────────────┐   merge redeploys the body
                        │ YOU review PR │──────────────────────────▶ (HF Space)
                        │ (exfil + ToS) │
                        └──────────────┘
```

> **Architecture note (2026-06):** each variant now owns its **entire pipeline — planning AND
> rendering** — behind a one-file subprocess contract (`variants/<id>/produce.py`). The harness
> runs it in an isolated process and only **publishes** the finished file. So the mutable surface
> is the whole strategy, not just a knob bag. (Earlier drafts described "one shared renderer";
> that was superseded — see *The producer contract* below.)

The thing being graded (the **variants**) and the thing holding the red pen (the **harness**:
fitness + ledger + dispatcher) live on opposite sides of a hard permission wall. `fitness.py`
runs *inside* the HF body — because only the body can read the per-tenant YouTube creds — but
it lives in the locked `harness/` and is excluded from the agent's allowlist, so it stays
immutable. The agent reads its grades from a **sanitized Mongo scoreboard** over a **read-only,
single-collection role**; it can never reach the `users` collection where credentials live.
A pull request bridges grade to code — gated by a human, or (with `AUTONOMOUS_MERGE=true`)
auto-merged by the organism itself once its build is green and the secret-scan is clean.

---

## Two halves: the locked harness and the evolving archive

```
content-generator/
├── harness/                  ← 🔒 LOCKED. The agent's mutator is never pointed here.
│   ├── fitness.py            #   The scorer + 3-day "safety leash". Immutable ground truth.
│   ├── youtube_analytics.py  #   Live YouTube Analytics fetch + channel-status (runs on HF body).
│   ├── attribution.py        #   video_id → variant_id map: joins analytics back to lineage.
│   ├── scoreboard.py         #   Sanitized Mongo fitness_scoreboard + CSV snapshot.
│   ├── orchestrator.py       #   run_day: variants compete → generate → render → publish → attribute.
│   ├── dispatcher.py         #   Carrying-capacity slot allocation, MAX 4, extinction.
│   ├── genome.py             #   The contract every variant must satisfy.
│   ├── notify.py             #   DMs the operator the current experiment summary (once/deploy).
│   ├── producer.py           #   Runs a variant's produce.py as an ISOLATED subprocess.
│   ├── scout.py              #   Contained internet access → TREND_BRIEF.md for the mutator.
│   ├── researcher_prompt.md  #   Phase-1 reasoner brief (writes MUTATION_PLAN.md).
│   └── implementer_prompt.md #   Phase-2 Aider coder brief (edits one variant to the plan).
│   #  Rendering is NO LONGER shared — each variant renders itself via produce.py. Only the
│   #  PUBLISHER stays shared/locked (YouTube creds must never enter variant code).
│
├── variants/                 ← 🧬 THE AGENT ARCHIVE. The mutator's entire world.
│   ├── variant_1/            #   Seed strategy: the meme→short pipeline (copied from meme-generator).
│   ├── variant_2/            #   A mutation that branched off and survived.
│   └── variant_3/            #   …population capped at 4 living variants at any time.
│
├── EXPERIMENTS_LOG.md        ← The agent writes hypotheses here BEFORE coding. Genetic memory.
├── metrics.csv               ← Per-cycle snapshot of fitness_scoreboard (Mongo). Committed for lineage.
├── music_ncs.json            ← Committed NCS music catalog (shared).
├── .github/workflows/
│   ├── fitness.yml           #   cron: pings HF /fitness/refresh (no secrets — just the URL).
│   └── mutator.yml           #   cron: snapshots scoreboard → runs Aider → opens PR. Cannot merge.
├── Dockerfile                #   The HF Space body (port 7860).
└── tests/                    #   Liveness gate. A mutation that breaks these is stillborn.
```

**The harness is the physics of the universe. The variants are the species evolving inside
it.** Every variant shares one `fitness.py` and one publisher (the locked sources of truth for
"what is good" and "how it ships"), but each renders *itself* — so a mutation can rewrite the
whole pipeline while "what counts as winning" stays immutable.

---

## The evolutionary loop

### 1. Variation — the headless mutator

Every 3 days (`mutator.yml`), an **Aider** agent runs headless inside GitHub Actions:

- **Brain:** OpenRouter `deepseek/...:free` (primary) → **Gemini Flash** (fallback), selected
  via the `MUTATOR_MODEL` env var. The brain is itself swappable — even evolvable.
- **Allowlist:** Aider only ever receives files under `variants/**` plus `genome.py` and a
  *compacted* view of `metrics.csv` + the last N `EXPERIMENTS_LOG.md` entries. It is
  structurally incapable of editing the fitness function or the publishers — it never sees them.
- **Cold start:** each cycle begins with fresh context (no cross-run conversation history) to
  keep token usage bounded regardless of how long the experiment has run.
- **Protocol:** read the scoreboard → **append a hypothesis to `EXPERIMENTS_LOG.md` before
  writing any code** → mutate **one** variant (or spawn/retire a variant) → run `pytest` in a
  Docker container → open a PR via `gh` with the hypothesis as the PR body. **Never pushes to
  `main`.**

### 2. Selection — the fitness function & the jungle

`harness/fitness.py` (**LOCKED**) is a deterministic, hand-written scorer using the **YouTube
Analytics API** as the fitness function. It runs **inside the HF body** — because the system is
multi-tenant and each channel's YouTube OAuth credentials live per-row in Mongo `users`, only
the body can authenticate the fetch. On its schedule the body:

1. reads each relevant channel's OAuth creds from Mongo `users`,
2. pulls Analytics **only for videos uploaded ≥ 3 days ago**,
3. classifies `channel_status`, computes fitness from APV/VSA,
4. upserts **sanitized, secrets-free rows** into the Mongo `fitness_scoreboard` collection.

The GitHub Actions mutator never calls the YouTube API and never sees a credential — it reads
the finished scoreboard over a read-only, single-collection Mongo role.

Survival metrics:

- **APV** — Average Percentage Viewed
- **VSA** — Viewed vs. Swiped Away

**Readability — a pixel-level quality signal with no 3-day lag.** A locked vision judge
(`harness/vision.py`) actually *looks at* sampled frames of each rendered video and scores how
legible the on-screen text is (size, contrast, edge-clipping, overlap, crowding, safe margins) —
format-agnostic, so it works on memes, chat screenshots, or whatever evolves next. It is a **hard
pre-merge smoke gate** (an unreadable variant can't merge; the concrete issues feed Aider's fix
loop so it "sees the screen") and a **production soft-floor** (a video below
`PRODUCTION_READABILITY_FLOOR` is skipped + alerted). The score is recorded per video as a tracked
metric the mutator optimises — but it is **NOT** a term in the fitness scalar: legibility is a gate
on shipping, real watch-time is still the only thing that counts as winning.

**Critical safety leash:** the fetcher only pulls analytics for videos **uploaded ≥ 3 days
ago**. Looking at yesterday's data hits the "Shorts Flatline" — it reads ~0 views, mistakes a
healthy video for a failure, and the loop chain-fits to noise. The 3-day delay is the line
between selection and self-destruction.

**Multi-tenant note:** the evolutionary signal is computed from a single designated **lab
channel** so fitness reflects *the mutation*, not *which tenant's audience saw it*. Other
tenants are served as a product feature but excluded from selection (per-channel normalization
is a later option if samples run short).

**Death ≠ low score.** If a channel is struck or suspended, the API returns errors/null, not
"0% APV." `fitness.py` classifies `channel_status` and, on `terminated`/`suspended`, **halts
the loop and pings the operator** rather than feeding a number into selection. The organism is
not allowed to misread its own death as a bad meme.

### 3. The carrying capacity — finite food, real competition

The daily video budget (3–5 uploads) is the **carrying capacity** of the ecosystem. Variants
do not each get the full budget; they **compete** for slots:

- `dispatcher.py` allocates each day's upload slots **proportional to each variant's
  trailing-window fitness** (rolling window up to 60 days of `metrics.csv`).
- **Juvenile grace:** a newborn variant gets a guaranteed slot allocation for its first window
  so it isn't strangled before it has data.
- **Extinction:** a variant starved to 0 slots for `K` consecutive days is flagged. The body
  tracks each variant's zero-slot streak (persisted in Mongo `variant_lifecycle`) and **alerts**
  when one crosses `K`; the mutator then deletes it from the repo, freeing a slot under the
  **MAX 4 living variants** cap. (The body can't delete it itself — its filesystem is ephemeral.)

Finite resources *are* the selection pressure. High-fitness strategies earn more airtime;
weak ones starve and die.

### 4. Inheritance — genetic memory & meta-evolution

- `EXPERIMENTS_LOG.md` is the lineage record: every hypothesis, the change it justified, and
  the observed result. The agent reads it before each mutation so it doesn't repeat dead ends.
- `metrics.csv` attributes every video to its `variant_id` + `genome_hash`, so cohorts stay
  correctly tagged even when multiple experiments are in flight across the 3-day signal lag.
- **Meta-evolution:** the agent may rewrite its own variant-level prompts and strategy. It may
  **not** touch `fitness.py`, `metrics.csv`, or the dispatcher's allocation math — the scorer
  is sacred. Self-improvement applies to *how it competes*, never to *what counts as winning*.

---

## The genome

A "genome" is the mutable surface a variant exposes. The seed genome (variant 1) includes:

| Gene | Source | Example |
|------|--------|---------|
| `seconds_per_image` | timing | `7` |
| `transition_seconds` | timing | `0.5` |
| `fps`, `audio_volume` | render | `15`, `0.45` |
| `tts_rate` / voice | edge-tts | `+0%` |
| idea-generation prompt | creative | the viral-strategist system prompt |
| critic prompt & rubric | creative | the acceptance rubric |
| template-selection policy | creative | banned templates, diversity rules |
| music-matching policy | creative | genre→tone mapping |

The agent mutates genes — and, more radically, the *code around them*. It may decide memes are
the wrong medium entirely and evolve a variant into something else, as long as the variant
still satisfies the `genome.py` contract (produce renderable assets the shared publisher can
ship) and passes the liveness tests.

---

## Safety model

The contradiction at the heart of every self-improving system is letting the thing being
graded hold the red pen. This system structurally forbids it:

1. **Immutable fitness.** `fitness.py`, `metrics.csv`, and the dispatcher's allocation logic
   live behind `CODEOWNERS` + branch protection, and are excluded from Aider's file allowlist.
   The agent cannot see them, let alone edit them.
2. **Merge policy (toggle: `AUTONOMOUS_MERGE`).** Default `false` = human-in-the-loop: the
   mutator only opens a PR and waits for you. Set `true` = **no human**: the agent auto-merges
   its own green, secret-clean PR and the body redeploys itself, fully hands-off. The toggle is
   reversible — flip it back to re-insert the human at any time.
3. **Secret-scan gate.** A CI scan flags any diff that reads a secret env var
   (`os.getenv(...TOKEN/SECRET/MONGO_URL...)`, `refresh_token`, `client_secret`). It is
   **advisory** under human review but a **hard merge-block** in autonomous mode — because with
   the human gone it is the *only* thing standing between the agent and token exfiltration. It
   inspects the *diff*, never the agent's reasoning, so it never makes the agent timid.
4. **Secrets isolation.** Infra secrets (`MONGO_URL`, `TELEGRAM_BOT_TOKEN`, content
   `GOOGLE_API_KEY`, Imgflip) live **only** in the HF Space env; per-tenant **YouTube OAuth +
   API keys live per-row in Mongo `users`**. The mutator in GitHub Actions gets **none** of
   these — its only DB credential is a **read-only Mongo role scoped to the
   `fitness_scoreboard` collection alone**. It cannot read `users`, so a compromised CI runner
   sees view-counts, never a tenant credential. The scoreboard collection is sanitized by
   construction (no tokens/keys), so even a misconfigured role leaks nothing.
5. **Sandboxed execution.** All agent-generated code runs inside a Docker container in
   ephemeral CI runners, behind the `pytest` liveness gate, before it can ever reach a PR.
6. **Sacrificial channel.** The experiment runs on a throwaway channel. Bans are tolerated as
   data; a strike halts the loop rather than corrupting the fitness signal.

The ToS/risk critic is **advisory, not a veto** — it writes a `risk_score` into each PR and the
ledger but does not block bold experiments. A `boldness` gene lets the operator dial
recklessness up or down. This is a research organism; timidity is a failure mode.

---

## Variant 1 — the seed strategy

The first inhabitant of `variants/variant_1/` is the meme-to-short pipeline migrated from the
original `meme-generator` project:

- **Idea agent** → 5 vivid meme scenarios per video + NCS music mood-matching.
- **Meme engine** (LangGraph) → planner → critic → executor → vision judge, captioning real
  Imgflip templates.
- **Render** → top-3 scoring memes → 1080×1920 MP4 with edge-tts voiceover + NCS track.
- **Publish** → YouTube Shorts and/or Telegram via the shared harness publisher.

Planning **and** rendering live inside the variant (`variants/variant_1/produce.py` + its own
`backend_service/`); only the **publisher** is shared/locked. Strategy decisions (prompts,
timing, template policy) are variant 1's genome.

---

## The producer contract

Every variant ships an executable `variants/<id>/produce.py`. The harness (`harness/producer.py`)
runs it **as a subprocess with the variant's own directory as the working directory**, so each
variant's code is fully isolated — its own imports, its own deps, its own crash blast-radius. The
seam is one JSON request in, one `artifacts.json` out:

```
stdin  →  {"n", "output_dir", "variant_id", "genome", "run_date"}
render →  up to n .mp4 files under output_dir   (written + flushed INCREMENTALLY)
result →  output_dir/artifacts.json = {"videos": [{video_path, title, description,
                                                    music_name, music_attribution}], "errors": []}
```

The body never renders — it only **publishes** the returned file (YouTube creds never enter
variant code) and records attribution. Subprocess isolation (not just "run one at a time") is
what fixed the original `sys.modules` collision where two variants sharing a `backend_service`
package silently ran each other's code. Production proves both timeouts and per-video flushes
matter: a slow batch is **salvaged** video-by-video instead of lost whole.

---

## Configuration

### Reusing the meme-generator database

The body reads the `users` collection from the **existing `meme_generator`** database (the same
Mongo cluster and same `MONGO_URL` that `meme-generator` already uses). YouTube OAuth and Gemini
API keys stored there are encrypted with `BACKEND_SHARED_SECRET` — set the **same value** on
both the meme-generator and content-generator HF Spaces so the harness can decrypt them.

The harness writes its own collections (`fitness_scoreboard`, `video_attribution`) to a
**separate** `content_generator` database (configurable via `MONGO_DATABASE`). This keeps the
evolutionary data cleanly separated while reusing the existing user credentials.

### HuggingFace Space (the body) — secrets

| Variable | Required | Notes |
|----------|----------|-------|
| `MONGO_URL` | ✅ | Full-access Mongo URI — **same cluster as meme-generator** (reads `meme_generator.users`, writes `content_generator.fitness_scoreboard`) |
| `BACKEND_SHARED_SECRET` | ✅ | AES key — **must match meme-generator's value** so the body can decrypt YouTube OAuth in `users` |
| `GOOGLE_API_KEY` | ✅ | Gemini key for **content generation** (not the mutator) |
| `IMGFLIP_USERNAME` / `IMGFLIP_PASSWORD` | ✅ | Imgflip captioning |
| `TELEGRAM_BOT_TOKEN` | ⚠️ | Bot API token from @BotFather (global, not per-user) |
| `BACKEND_ALLOWED_ORIGINS` | ✅ (prod) | CORS allowlist |
| `LAB_CHANNEL_ID` | ✅ | YouTube channel ID (`UC…`) whose analytics feed the fitness signal |
| `LAB_USER_ID` | ✅ | The `user_id` in `meme_generator.users` whose YouTube OAuth publishes to / reads the lab channel |
| `FITNESS_TRIGGER_TOKEN` | ⚠️ (prod) | Shared token that gates `/fitness/refresh` and `/run/daily` — generate with `python -c "import secrets; print(secrets.token_urlsafe(32))"` and set the same value in the GitHub secret |
| `ADMIN_TELEGRAM_CHAT_ID` | optional | Your Telegram chat id — the body DMs you the experiment summary + daily-run results |
| `MONGO_USERS_DATABASE` | optional | Database containing the `users` collection (default: `meme_generator`) |
| `MONGO_DATABASE` | optional | Database for harness collections like `fitness_scoreboard` (default: `content_generator`) |
| `MAX_LIVING_VARIANTS` | optional | Hard cap, default `4` |
| `DAILY_VIDEO_BUDGET` | optional | Carrying capacity, default `3` (max `5`) |
| `MAX_SLOTS_PER_VARIANT` | optional | Per-variant render ceiling so one slow variant can't be allocated more than it can render before timing out. Default `3`; `0` = no ceiling |
| `EXPLORATION_SLOTS` | optional | Slots handed out fitness-blind (anti-monoculture). Default `0` = pure exploitation |
| `PRODUCE_MAX_WORKERS` | optional | Variants to render concurrently. Default `1` (sequential; raise only where the Space has CPU/RAM headroom) |
| `PRODUCE_PER_VIDEO_TIMEOUT_SECONDS` | optional | Per-video render budget. Default `1800` (30 min); total scales with `n` up to a 90 min ceiling |
| `LOG_RETENTION_DAYS` | optional | TTL for `container_logs`. Default `7` |
| `VISION_PRODUCTION` | optional | Run the readability vision judge per published video (record metric + soft-floor skip). Default `true`; fail-open |
| `VISION_MODEL` | optional | Multimodal model for the readability judge. Default `gemini-1.5-flash` |
| `SMOKE_READABILITY_FLOOR` | optional | Pre-merge gate threshold (0–1). Default `0.6` |
| `PRODUCTION_READABILITY_FLOOR` | optional | Below this a rendered video is skipped (not published) + alerted. Default `0.35` |
| `EXTINCTION_DAYS_K` | optional | Days at 0 slots before a variant is flagged extinct, default `12`. The body **detects + alerts**; the mutator does the actual repo deletion (the body's filesystem is ephemeral) |

> Per-tenant **YouTube OAuth** (`refresh_token`, `client_id`, `client_secret`) is **not** an HF
> env secret — it is stored per-row in Mongo `meme_generator.users` (already there from
> meme-generator) and read + decrypted at runtime by `harness/user_store.py`.

### How to get each value

| Value | Where to find it |
|-------|------------------|
| `LAB_CHANNEL_ID` | [YouTube Studio](https://studio.youtube.com) → Settings → Channel → Advanced → **Channel ID** (starts with `UC…`) |
| `LAB_USER_ID` | The `user_id` field of your existing row in Atlas → `meme_generator.users` |
| `TELEGRAM_BOT_TOKEN` | Telegram → @BotFather → `/mybots` → select your bot → **API Token** (looks like `7123456789:AAH_…`) |
| `FITNESS_TRIGGER_TOKEN` | Generate yourself: `python -c "import secrets; print(secrets.token_urlsafe(32))"` — set the same value on HF + GitHub |
| `BACKEND_SHARED_SECRET` | Copy from your existing meme-generator HF Space env |
| `GH_PR_TOKEN` | [GitHub → Settings → Developer settings → Tokens](https://github.com/settings/tokens) → fine-grained with `Contents: RW` + `Pull requests: RW` scoped to this repo |
| `HF_TOKEN` | [HuggingFace → Settings → Access Tokens](https://huggingface.co/settings/tokens) → write token |

### GitHub Actions (the evolutionary engine) — secrets

| Variable | Required | Notes |
|----------|----------|-------|
| `HF_SPACE_URL` | ✅ | Public URL of the HF Space (e.g. `https://abhay1704-content-generator-rsi.hf.space`) |
| `FITNESS_TRIGGER_TOKEN` | ⚠️ (prod) | Must match the HF Space env value |
| `MONGO_FITNESS_READONLY_URL` | ✅ | Mongo user with **`read` on `fitness_scoreboard` only** — no access to `users` |
| `NVIDIA_API_KEY` | ✅ | Primary mutator brain — [build.nvidia.com](https://build.nvidia.com) key (`nvapi-…`), used by both the research and implementation phases |
| `GEMINI_FALLBACK_API_KEY` | optional | Fallback brain |
| `OPENROUTER_API_KEY` | optional | Legacy fallback; every `openrouter/*` cascade entry is skipped when it is absent |
| `GH_PR_TOKEN` | ✅ | GitHub PAT — PR-create scope only (no merge in default mode) |
| `HF_TOKEN` | ✅ | HuggingFace write token for deploy-huggingface.yml |

GitHub **variables** (not secrets — visible in logs, fine for non-sensitive config):

| Variable | Required | Notes |
|----------|----------|-------|
| `HF_USERNAME` | ✅ | e.g. `abhay1704` |
| `HF_SPACE_ID` | ✅ | e.g. `abhay1704/content-generator-rsi` |
| `MUTATOR_MODEL` | optional | Head of the coder cascade, e.g. `nim/nvidia/nemotron-3-ultra-550b-a55b` (`nim/*` = NVIDIA NIM, `openrouter/*`, `gemini/*`) |
| `RESEARCH_MODEL` | optional | Head of the reasoner cascade, default `nim/nvidia/nemotron-3-ultra-550b-a55b` |
| `MONGO_DATABASE` | optional | default `content_generator` |
| `AUTONOMOUS_MERGE` | optional | `false` (default) or `true` |

> The mutator and the body never share a credential. The CI runner's Mongo role can read the
> sanitized `fitness_scoreboard` and nothing else — not `users`, not `MONGO_URL`. It cannot
> publish, delete, read a tenant credential, or merge its own PRs.

### Setting up the scoped Mongo role (one-time)

```js
// In the mongo shell / Atlas, create a role limited to the scoreboard collection:
db.createRole({
  role: "fitnessReadonly",
  privileges: [{ resource: { db: "content_generator", collection: "fitness_scoreboard" },
                 actions: ["find"] }],
  roles: []
})
db.createUser({ user: "mutator_ro", pwd: "…", roles: ["fitnessReadonly"] })
// MONGO_FITNESS_READONLY_URL uses mutator_ro — it literally cannot query `users`.
```

---


## Deploy

### The body (HuggingFace Space)

```bash
docker build -t content-generator .
docker run -p 7860:7860 --env-file .env content-generator
```

A clean commit history is pushed to a fresh HF Space, independent of the original
`meme-generator` deployment.

### The evolutionary engine (GitHub Actions)

Three crons, all holding no secrets beyond the Space URL / a scoped read-only Mongo role:

- `.github/workflows/generate.yml` — **daily**: `POST /run/daily` → variants compete for the
  budget, generate → render → publish → record attribution.
- `.github/workflows/fitness.yml` — **every 3 days**: `POST /fitness/refresh` → the body fetches
  ≥3-day-old analytics, scores them, writes `fitness_scoreboard`.
- `.github/workflows/mutator.yml` — **every 3 days (offset)**: snapshot the scoreboard, scout the
  web, run Aider, self-fix until tests pass, open a PR; auto-merge if `AUTONOMOUS_MERGE=true`.
- `.github/workflows/deploy-huggingface.yml` — **on push to main**: redeploys the body.

No setup beyond adding the GitHub secrets/vars and creating the scoped Mongo role. The loop is
self-starting.

---

## Data model

- **Mongo `fitness_scoreboard`** (ground truth, harness-owned, **sanitized**): `video_id,
  upload_date, variant_id, genome_hash, parent_genome, APV, VSA, fitness, channel_status`.
  Written by `harness/fitness.py` on HF; read by the mutator over the read-only scoped role.
  Contains **no secrets** — never a token, key, or raw tenant identifier.
- **`metrics.csv`** (lineage snapshot): a per-cycle dump of `fitness_scoreboard` committed by
  `mutator.yml` so the scoreboard is version-controlled and feeds Aider as a file.
- **`EXPERIMENTS_LOG.md`** (lineage, agent-owned): one entry per mutation — hypothesis, change,
  observed result.
- **Mongo `video_attribution`** (harness-owned, sanitized): `video_id → variant_id, genome_hash,
  parent_genome, upload_date`, written at publish time so analytics can be joined back to the
  lineage that earned them. The seam that closes the loop.
- **Mongo `users`** 🔒 (operational, **off-limits to the agent**): per-tenant config + YouTube
  OAuth + API keys. Readable only by the HF body's full-access `MONGO_URL`.
- **MongoDB** (operational): `run_history` and the meme-engine workflow trace (`workflow_runs`
  / `workflow_events` / `workflow_messages`) for per-run auditing.

---

## Operating the experiment

1. Watch the PR queue. Merge survivors; close the cursed ones (they *will* happen early).
2. Read `EXPERIMENTS_LOG.md` to follow the organism's reasoning over time.
3. Tune `boldness`, `DAILY_VIDEO_BUDGET`, and `EXTINCTION_DAYS_K` to set the pace of evolution.
4. If a channel is struck, the loop halts itself — investigate, then resume on a fresh channel.

The goal is not a better meme generator. The goal is a codebase that discovers, on its own,
what the algorithm rewards — and becomes that.