HELIOS — broadcast layer of the AIMarket ecosystem

🌐 English · Русский · Español · Français · 中文 · Glossary

Template in, voiced video out, queued to your YouTube — private by default until you approve.
MIT · self-hosted · POST-only · no engagement bots.

In the myth, Helios drives the chariot of the sun across the sky — light, rhythm, visibility.
HELIOS is the broadcast satellite of the AICOM / AIMarket ecosystem: render ecosystem explainers, upload to @My-AI-Factory, keep everything private by default until a human says go (optional auto_approve skips the gate).

Channel: @My-AI-Factory · playlist
Landing: alexar76.github.io/helios · source: landing/index.html
Repo: github.com/alexar76/helios
Monitor: Alien Monitor — click the HELIOS node for cached YouTube stats
Integration guide: helios-integration.md

Why HELIOS exists

The ecosystem ships constantly — releases, oracles, courses, live demos. Manual build_series.py + upload_youtube.py in PromoMaterials does not scale. HELIOS is the dedicated broadcast engine: one job queue, one audit trail, one human gate before anything goes public.

Three minds (who does what)

Backfill episodes (PromoMaterials S1 E10+, Season 2) use human-authored yaml — CALLIOPE does not rewrite them.

Charter (non-negotiable)

1. POST-only — our channel only; no likes, comments, or engagement bots.
2. Grounded creation — CALLIOPE cites MNEMOSYNE (READMEs, releases, live demos); backfill stays human yaml.
3. Private-first — every upload starts private; helios approve for public.
4. Human gate — operator watches every video in YouTube Studio before approve.
5. Fail-soft — if HELIOS is down, Factory and DIOSCURI keep running.

Features

Architecture

flowchart TB
    subgraph sources["Content & knowledge (read-only)"]
        GH["GitHub READMEs / releases"]
        DEMO["Live demo endpoints"]
        PM["PromoMaterials MP4 + yaml"]
        MN["MNEMOSYNE — mnemosyne.json<br/>(DIOSCURI sync)"]
        GH --> MN
        DEMO --> MN
    end

    subgraph triggers["Triggers"]
        CLI["CLI — helios enqueue / calliope"]
        DC["DIOSCURI — release event"]
        CRON["cron — helios worker"]
    end

    subgraph helios["HELIOS core"]
        Q["Queue store<br/>queue.json"]
        ING["Ingest — HELIOS_QUEUE_PATH jsonl"]
        CAL["CALLIOPE — screenwriter<br/>BM25 + AEGIS + LLM"]
        DIR["Director — metadata QA"]
        WK["Worker — render → upload"]
        REN["Renderer — TTS + ffmpeg"]
        YTU["YouTube client — OAuth"]
        AUD["audit.jsonl"]
        HC["GET /health"]
    end

    subgraph output["Output"]
        YT["YouTube @My-AI-Factory<br/>(private)"]
        OP["Operator — Studio + approve"]
        PUB["public video"]
        MON["Alien Monitor"]
    end

    MN --> CAL
    PM -->|backfill| Q
    CLI --> CAL
    CAL -->|script.yaml| Q
    DC -->|jsonl job| ING
    ING --> Q
    CRON --> WK
    Q --> DIR
    DIR --> WK
    WK --> REN
    REN --> YTU
    YTU --> YT
    YT --> OP
    OP -->|helios approve| PUB
    WK --> AUD
    WK --> HC
    HC --> MON

Job phases: backfill (PromoMaterials backlog) → creator (CALLIOPE) → steady (release-shorts).

Status flow: pending → rendering → uploading → awaiting_approval → published

Quick start (pip)

cd helios
pip install -e ".[dev]"
cp helios.config.example.yaml helios.config.yaml
cp .env.example .env
# Required: YOUTUBE_CLIENT_SECRET, YOUTUBE_TOKEN, DEEPSEEK_API_KEY
# CALLIOPE: DIOSCURI_DATA_DIR=/path/to/dioscuri/data  (reads mnemosyne.json)

helios auth
helios calliope stats          # MNEMOSYNE loaded?
helios calliope editorial-status  # weekly quota + scout cadence
helios calliope pitch          # topic ideas (manual)
helios worker                  # also runs editorial scout when due
helios approve job_...

Backfill (existing renders)

helios backfill-scan
helios backfill-enqueue -n 10   # queue only; upload when quota allows
helios worker --max-jobs 4      # conservative if YouTube quota is tight

Quick start (Docker)

cp helios.config.example.yaml helios.config.yaml
cp .env.example .env
docker compose up -d --build
# REQUIRED: `compose up` only runs `helios serve` — schedule the worker:
(crontab -l 2>/dev/null; echo "0 * * * * docker exec helios helios worker >> /var/log/helios-worker.log 2>&1") | crontab -
docker exec helios helios worker --max-jobs 1

Container: non-root, read-only rootfs, cap_drop: ALL, health on :8791/health.
See docs/setup.md § Worker cron.

Configuration

Secrets in .env; tuning in helios.config.yaml (never commit real values).

Ecosystem position

aicom           → builds products
dioscuri        → community Q&A + MNEMOSYNE + release → HELIOS queue
PromoMaterials  → human episode scripts & rendered MP4 (backfill)
helios          → render + YouTube delivery  ← you are here
alien-monitor   → 3D graph + HELIOS / DIOSCURI live stats

Documentation

Development

pip install -e ".[dev]"
PYTHONPATH=. pytest tests/ -q
bash scripts/ci_coverage_badge.sh   # refresh docs/badges/coverage.svg

CI: .github/workflows/ci.yml (pytest + coverage badge + Docker) · Pages: .github/workflows/pages.yml → alexar76.github.io/helios

License

MIT — see LICENSE.