helios-broadcast 0.1.0__tar.gz

helios_broadcast-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AICOM (alexar76)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

helios_broadcast-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: helios-broadcast
+Version: 0.1.0
+Summary: HELIOS — self-hosted broadcast pipeline for the AIMarket ecosystem. Template in, voiced video out, queued to YouTube — private until you approve.
+Author: AICOM (alexar76)
+License: MIT
+Keywords: youtube,broadcast,devrel,aimarket,aicom,ffmpeg,tts
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: google-api-python-client>=2.100
+Requires-Dist: google-auth-oauthlib>=1.2
+Requires-Dist: google-auth-httplib2>=0.2
+Requires-Dist: pillow>=10.0
+Requires-Dist: edge-tts>=6.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# HELIOS — broadcast layer of the AIMarket ecosystem
+
+<!-- aicom-readme-badges -->
+<p align="center">
+  <a href="https://github.com/alexar76/helios/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/alexar76/helios/ci.yml?branch=main&label=CI" alt="CI" /></a>
+  <a href="https://github.com/alexar76/helios/actions/workflows/pages.yml"><img src="https://img.shields.io/github/actions/workflow/status/alexar76/helios/pages.yml?branch=main&label=Pages" alt="Pages deploy" /></a>
+  <a href="https://alexar76.github.io/helios/"><img src="https://img.shields.io/badge/landing-gallery-e84a1a" alt="Landing gallery" /></a>
+  <a href="https://www.youtube.com/@My-AI-Factory"><img src="https://img.shields.io/badge/YouTube-@My--AI--Factory-ff0000" alt="YouTube channel" /></a>
+  <img src="https://img.shields.io/badge/python-%3E%3D3.11-brightgreen.svg" alt="Python >=3.11" />
+  <img src="https://img.shields.io/badge/tests-45%20passed-brightgreen" alt="45 tests passed" />
+  <a href="docs/badges/coverage.svg"><img src="docs/badges/coverage.svg" alt="Test coverage" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+</p>
+<!-- /aicom-readme-badges -->
+
+> **Template in, voiced video out, queued to your YouTube — private until you approve.**  
+> MIT · self-hosted · POST-only · no engagement bots.
+
+🌐 **Language:** **English** · [Русский](README-ru.md) · [Español](README-es.md)
+
+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](https://magic-ai-factory.com): render ecosystem explainers, upload to [@My-AI-Factory](https://www.youtube.com/@My-AI-Factory), keep everything **private** until a human says go.
+
+**Channel:** [@My-AI-Factory](https://www.youtube.com/@My-AI-Factory) · [playlist](https://www.youtube.com/playlist?list=PLQAJcI3MYJxM)  
+**Landing:** [alexar76.github.io/helios](https://alexar76.github.io/helios/) · source: [`landing/index.html`](landing/index.html)  
+**Repo:** [github.com/alexar76/helios](https://github.com/alexar76/helios)  
+**Monitor:** [Alien Monitor](https://magic-ai-factory.com/monitor/) — click the **HELIOS** node for cached YouTube stats  
+**Integration guide:** [helios-integration.md](https://github.com/alexar76/aicom/blob/main/docs/ecosystem/helios-integration.md)
+
+| | |
+|---|---|
+| **Role** | Render MP4 → upload YouTube (private) → operator approve → public |
+| **Screenwriter** | **CALLIOPE** — LLM scripts grounded in **MNEMOSYNE** (shared with DIOSCURI) |
+| **Ops** | **Director** — LLM metadata review + queue priority (DeepSeek default) |
+
+## 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)
+
+| Entity | Myth | Job | Touches voiceover? |
+|--------|------|-----|------------------|
+| **CALLIOPE** | Muse of epic poetry | Pitch topics, write scripts from GitHub + demo corpus | **Yes** (new videos) |
+| **Director** | Broadcast ops | Review title/description, prioritize queue | No |
+| **Operator** | Human | Studio review → `helios approve` | No |
+
+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
+
+| Feature | What it means |
+|---------|---------------|
+| Job queue | Idempotent jobs, daily upload cap (~9/day), crash-safe worker lock |
+| Renderer | TTS (`say` on macOS, edge-tts on Linux) + ffmpeg + burned-in captions + SRT |
+| YouTube API | Resumable upload, captions, playlist routing |
+| Backfill | Upload existing PromoMaterials renders without re-encoding |
+| **CALLIOPE** | `helios calliope pitch/write/enqueue` — MNEMOSYNE-grounded scripts |
+| Director | LLM metadata review (DeepSeek default) |
+| DIOSCURI hook | Release events → shared `HELIOS_QUEUE_PATH` jsonl |
+| Alien Monitor | `GET /health` — cached YouTube stats for the graph node |
+| Audit | Append-only `data/audit.jsonl` for every state transition |
+
+## Architecture
+
+```mermaid
+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)
+
+```bash
+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)
+
+```bash
+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)
+
+```bash
+cp helios.config.example.yaml helios.config.yaml
+cp .env.example .env
+docker compose up -d --build
+docker compose exec helios helios worker
+```
+
+Container: non-root, read-only rootfs, `cap_drop: ALL`, health on `:8791/health`.
+
+## Configuration
+
+Secrets in `.env`; tuning in `helios.config.yaml` (never commit real values).
+
+| Variable | Purpose |
+|----------|---------|
+| `YOUTUBE_CLIENT_SECRET` | OAuth client JSON path |
+| `YOUTUBE_TOKEN` | OAuth token JSON path |
+| `HELIOS_LLM_PROVIDER` | `deepseek` (default) · `anthropic` · `openai-compatible` |
+| `DEEPSEEK_API_KEY` | LLM for Director + CALLIOPE |
+| `DIOSCURI_DATA_DIR` | Path to DIOSCURI data → reads `mnemosyne.json` |
+| `HELIOS_MNEMOSYNE_PATH` | Override MNEMOSYNE file path |
+| `HELIOS_QUEUE_PATH` | Shared jsonl ingest (DIOSCURI syndication) |
+| `HELIOS_DATA_DIR` | Queue, audit, scripts, renders |
+| `HELIOS_DRY_RUN` | `1` = no YouTube upload |
+
+| `helios.config.yaml` key | Default | Purpose |
+|----------------------------|---------|---------|
+| `limits.max_uploads_per_day` | `9` | YouTube quota margin |
+| `calliope.enabled` | `true` | CALLIOPE screenwriter |
+| `calliope.editorial_enabled` | `true` | Auto-scout on worker cron |
+| `calliope.scout_interval_days` | `3` | Days between scout runs |
+| `calliope.weekly_enqueue_quota` | `3` | Max new scripts/week |
+| `calliope.backfill_pause_threshold` | `8` | Pause editorial while backfill > N |
+| `director.enabled` | `true` | Metadata review before upload |
+
+## 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
+
+| Doc | Description |
+|-----|-------------|
+| [landing/index.html](landing/index.html) | Source for [alexar76.github.io/helios](https://alexar76.github.io/helios/) — video gallery |
+| [docs/setup.md](docs/setup.md) | Install, OAuth, Docker |
+| [docs/usage.md](docs/usage.md) | CLI — CALLIOPE, Director, worker |
+| [docs/architecture.md](docs/architecture.md) | Components, data model |
+| [docs/security.md](docs/security.md) | Threat model |
+| [docs/runbook.md](docs/runbook.md) | Operator playbook |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+PYTHONPATH=. pytest tests/ -q
+bash scripts/ci_coverage_badge.sh   # refresh docs/badges/coverage.svg
+```
+
+CI: [`.github/workflows/ci.yml`](.github/workflows/ci.yml) (pytest + coverage badge + Docker) · Pages: [`.github/workflows/pages.yml`](.github/workflows/pages.yml) → [alexar76.github.io/helios](https://alexar76.github.io/helios/)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

helios_broadcast-0.1.0/README.md

@@ -0,0 +1,229 @@
+# HELIOS — broadcast layer of the AIMarket ecosystem
+
+<!-- aicom-readme-badges -->
+<p align="center">
+  <a href="https://github.com/alexar76/helios/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/alexar76/helios/ci.yml?branch=main&label=CI" alt="CI" /></a>
+  <a href="https://github.com/alexar76/helios/actions/workflows/pages.yml"><img src="https://img.shields.io/github/actions/workflow/status/alexar76/helios/pages.yml?branch=main&label=Pages" alt="Pages deploy" /></a>
+  <a href="https://alexar76.github.io/helios/"><img src="https://img.shields.io/badge/landing-gallery-e84a1a" alt="Landing gallery" /></a>
+  <a href="https://www.youtube.com/@My-AI-Factory"><img src="https://img.shields.io/badge/YouTube-@My--AI--Factory-ff0000" alt="YouTube channel" /></a>
+  <img src="https://img.shields.io/badge/python-%3E%3D3.11-brightgreen.svg" alt="Python >=3.11" />
+  <img src="https://img.shields.io/badge/tests-45%20passed-brightgreen" alt="45 tests passed" />
+  <a href="docs/badges/coverage.svg"><img src="docs/badges/coverage.svg" alt="Test coverage" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+</p>
+<!-- /aicom-readme-badges -->
+
+> **Template in, voiced video out, queued to your YouTube — private until you approve.**  
+> MIT · self-hosted · POST-only · no engagement bots.
+
+🌐 **Language:** **English** · [Русский](README-ru.md) · [Español](README-es.md)
+
+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](https://magic-ai-factory.com): render ecosystem explainers, upload to [@My-AI-Factory](https://www.youtube.com/@My-AI-Factory), keep everything **private** until a human says go.
+
+**Channel:** [@My-AI-Factory](https://www.youtube.com/@My-AI-Factory) · [playlist](https://www.youtube.com/playlist?list=PLQAJcI3MYJxM)  
+**Landing:** [alexar76.github.io/helios](https://alexar76.github.io/helios/) · source: [`landing/index.html`](landing/index.html)  
+**Repo:** [github.com/alexar76/helios](https://github.com/alexar76/helios)  
+**Monitor:** [Alien Monitor](https://magic-ai-factory.com/monitor/) — click the **HELIOS** node for cached YouTube stats  
+**Integration guide:** [helios-integration.md](https://github.com/alexar76/aicom/blob/main/docs/ecosystem/helios-integration.md)
+
+| | |
+|---|---|
+| **Role** | Render MP4 → upload YouTube (private) → operator approve → public |
+| **Screenwriter** | **CALLIOPE** — LLM scripts grounded in **MNEMOSYNE** (shared with DIOSCURI) |
+| **Ops** | **Director** — LLM metadata review + queue priority (DeepSeek default) |
+
+## 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)
+
+| Entity | Myth | Job | Touches voiceover? |
+|--------|------|-----|------------------|
+| **CALLIOPE** | Muse of epic poetry | Pitch topics, write scripts from GitHub + demo corpus | **Yes** (new videos) |
+| **Director** | Broadcast ops | Review title/description, prioritize queue | No |
+| **Operator** | Human | Studio review → `helios approve` | No |
+
+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
+
+| Feature | What it means |
+|---------|---------------|
+| Job queue | Idempotent jobs, daily upload cap (~9/day), crash-safe worker lock |
+| Renderer | TTS (`say` on macOS, edge-tts on Linux) + ffmpeg + burned-in captions + SRT |
+| YouTube API | Resumable upload, captions, playlist routing |
+| Backfill | Upload existing PromoMaterials renders without re-encoding |
+| **CALLIOPE** | `helios calliope pitch/write/enqueue` — MNEMOSYNE-grounded scripts |
+| Director | LLM metadata review (DeepSeek default) |
+| DIOSCURI hook | Release events → shared `HELIOS_QUEUE_PATH` jsonl |
+| Alien Monitor | `GET /health` — cached YouTube stats for the graph node |
+| Audit | Append-only `data/audit.jsonl` for every state transition |
+
+## Architecture
+
+```mermaid
+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)
+
+```bash
+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)
+
+```bash
+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)
+
+```bash
+cp helios.config.example.yaml helios.config.yaml
+cp .env.example .env
+docker compose up -d --build
+docker compose exec helios helios worker
+```
+
+Container: non-root, read-only rootfs, `cap_drop: ALL`, health on `:8791/health`.
+
+## Configuration
+
+Secrets in `.env`; tuning in `helios.config.yaml` (never commit real values).
+
+| Variable | Purpose |
+|----------|---------|
+| `YOUTUBE_CLIENT_SECRET` | OAuth client JSON path |
+| `YOUTUBE_TOKEN` | OAuth token JSON path |
+| `HELIOS_LLM_PROVIDER` | `deepseek` (default) · `anthropic` · `openai-compatible` |
+| `DEEPSEEK_API_KEY` | LLM for Director + CALLIOPE |
+| `DIOSCURI_DATA_DIR` | Path to DIOSCURI data → reads `mnemosyne.json` |
+| `HELIOS_MNEMOSYNE_PATH` | Override MNEMOSYNE file path |
+| `HELIOS_QUEUE_PATH` | Shared jsonl ingest (DIOSCURI syndication) |
+| `HELIOS_DATA_DIR` | Queue, audit, scripts, renders |
+| `HELIOS_DRY_RUN` | `1` = no YouTube upload |
+
+| `helios.config.yaml` key | Default | Purpose |
+|----------------------------|---------|---------|
+| `limits.max_uploads_per_day` | `9` | YouTube quota margin |
+| `calliope.enabled` | `true` | CALLIOPE screenwriter |
+| `calliope.editorial_enabled` | `true` | Auto-scout on worker cron |
+| `calliope.scout_interval_days` | `3` | Days between scout runs |
+| `calliope.weekly_enqueue_quota` | `3` | Max new scripts/week |
+| `calliope.backfill_pause_threshold` | `8` | Pause editorial while backfill > N |
+| `director.enabled` | `true` | Metadata review before upload |
+
+## 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
+
+| Doc | Description |
+|-----|-------------|
+| [landing/index.html](landing/index.html) | Source for [alexar76.github.io/helios](https://alexar76.github.io/helios/) — video gallery |
+| [docs/setup.md](docs/setup.md) | Install, OAuth, Docker |
+| [docs/usage.md](docs/usage.md) | CLI — CALLIOPE, Director, worker |
+| [docs/architecture.md](docs/architecture.md) | Components, data model |
+| [docs/security.md](docs/security.md) | Threat model |
+| [docs/runbook.md](docs/runbook.md) | Operator playbook |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+PYTHONPATH=. pytest tests/ -q
+bash scripts/ci_coverage_badge.sh   # refresh docs/badges/coverage.svg
+```
+
+CI: [`.github/workflows/ci.yml`](.github/workflows/ci.yml) (pytest + coverage badge + Docker) · Pages: [`.github/workflows/pages.yml`](.github/workflows/pages.yml) → [alexar76.github.io/helios](https://alexar76.github.io/helios/)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

helios_broadcast-0.1.0/helios/__init__.py

@@ -0,0 +1,3 @@
+"""HELIOS — broadcast layer of the AIMarket ecosystem."""
+
+__version__ = "0.1.0"

helios_broadcast-0.1.0/helios/audit.py

@@ -0,0 +1,31 @@
+"""Append-only audit log — one JSON line per event."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class AuditLog:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def append(self, kind: str, *, job_id: str | None = None, actor: str = "system", data: dict[str, Any] | None = None) -> None:
+        entry = {
+            "ts": _now_iso(),
+            "kind": kind,
+            "actor": actor,
+        }
+        if job_id:
+            entry["job_id"] = job_id
+        if data:
+            entry["data"] = data
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")

helios_broadcast-0.1.0/helios/backfill.py

@@ -0,0 +1,119 @@
+"""Scan PromoMaterials backlog and enqueue backfill upload jobs."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from helios.config import HeliosConfig, file_roots
+from helios.queue import QueueStore
+
+
+def _series_dir(cfg: HeliosConfig) -> Path:
+    if cfg.promo_materials_dir:
+        return cfg.promo_materials_dir / "youtube" / "ecosystem-series"
+    for root in cfg.asset_roots:
+        candidate = root / "youtube" / "ecosystem-series"
+        if candidate.exists():
+            return candidate
+        candidate = root / "PromoMaterials" / "youtube" / "ecosystem-series"
+        if candidate.exists():
+            return candidate
+    raise FileNotFoundError("PromoMaterials ecosystem-series not found — set promo_materials_dir or asset_roots")
+
+
+def _load_meta(series: Path, season: int) -> dict[str, Any]:
+    name = "upload_metadata.yaml" if season == 1 else "upload_metadata-season2.yaml"
+    return yaml.safe_load((series / name).read_text(encoding="utf-8"))
+
+
+def _load_state(series: Path, season: int) -> dict[str, Any]:
+    name = "upload_state.json" if season == 1 else "upload_state_season2.json"
+    path = series / name
+    if path.exists():
+        return json.loads(path.read_text(encoding="utf-8"))
+    return {"videos": {}, "playlists": {}}
+
+
+def _migrate_playlists(store: QueueStore, series: Path) -> None:
+    """Import S1 playlist IDs into helios upload_state."""
+    s1_state = series / "upload_state.json"
+    if not s1_state.exists():
+        return
+    s1 = json.loads(s1_state.read_text(encoding="utf-8"))
+    state = store.load_upload_state()
+    for key, pid in (s1.get("playlists") or {}).items():
+        state.setdefault("playlists", {})[key] = pid
+    store.save_upload_state(state)
+
+
+def scan_backlog(cfg: HeliosConfig, store: QueueStore) -> list[dict[str, Any]]:
+    """Return pending episodes not yet in helios queue or upload state."""
+    series = _series_dir(cfg)
+    _migrate_playlists(store, series)
+    helios_state = store.load_upload_state()
+    uploaded = set(helios_state.get("videos", {}).keys())
+    existing_jobs = {j.idempotency_key for j in store.list_jobs()}
+
+    pending: list[dict[str, Any]] = []
+    for season in (1, 2):
+        meta_path = series / ("upload_metadata.yaml" if season == 1 else "upload_metadata-season2.yaml")
+        if not meta_path.exists():
+            continue
+        meta = _load_meta(series, season)
+        promo_state = _load_state(series, season)
+        promo_uploaded = set(promo_state.get("videos", {}).keys())
+
+        for eid in meta.get("upload_order", []):
+            if eid in uploaded or eid in promo_uploaded:
+                continue
+            ep = meta["episodes"].get(eid)
+            if not ep:
+                continue
+            video = series / ep["video"]
+            srt = series / ep["srt"]
+            if not video.exists():
+                continue
+            ikey = f"backfill:s{season}:{eid}"
+            if ikey in existing_jobs:
+                continue
+            pending.append({
+                "episode": eid,
+                "season": season,
+                "video": str(video),
+                "srt": str(srt) if srt.exists() else None,
+                "youtube": {
+                    "title": ep["title"],
+                    "description": ep.get("description", ""),
+                    "tags": ep.get("tags", []),
+                    "playlist": ep.get("playlist"),
+                    "privacy": "private",
+                },
+                "idempotency_key": ikey,
+            })
+    return pending
+
+
+def enqueue_backfill(cfg: HeliosConfig, store: QueueStore, *, limit: int | None = None) -> list[str]:
+    """Enqueue all pending PromoMaterials episodes as backfill jobs."""
+    pending = scan_backlog(cfg, store)
+    if limit:
+        pending = pending[:limit]
+    ids: list[str] = []
+    for item in pending:
+        job = store.enqueue(
+            template="promo-backfill",
+            vars={"episode": item["episode"], "season": str(item["season"])},
+            youtube=item["youtube"],
+            idempotency_key=item["idempotency_key"],
+            source="promo-materials",
+            render_path=item["video"],
+            srt_path=item.get("srt"),
+            phase="backfill",
+            job_id=f"job_backfill_{item['episode'].lower()}",
+        )
+        ids.append(job.id)
+    return ids