# siva010505/helio2 architecture

> Architecture diagram of the GitHub repository siva010505/helio2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siva010505/helio2
- Repository: https://github.com/siva010505/helio2

## Overview

#### Purpose and Execution Surface
This is a Python agent pipeline for producing and operating video content: research, scripting, visual planning, assembly, publishing, and analytics-driven iteration. Primary runnable surfaces are:
- `src/pipeline.py` — likely programmatic pipeline entry.
- `scripts/run_daily_pipeline.py` — daily end-to-end execution.
- `scripts/dry_run.py` — non-production validation path.
- `.github/workflows/daily_pipeline.yml` — scheduled/CI automation boundary.

#### Orchestration and Pipeline Control
The central control plane is an orchestrator that sequences specialized agents and carries state between stages:
- `src/agents/orchestrator.py`
- `src/pipeline.py`
- `src/config_loader.py`

Configuration is externalized in `config.yaml`, with environment-provided secrets expected through `.env.example`. The orchestration boundary separates workflow decisions from individual content-generation, rendering, and publishing capabilities.

#### Content Intelligence and Script Generation
Topic discovery and editorial development are decomposed into specialized agents:
- `src/agents/research_agent.py`
- `src/agents/longform_research_agent.py`
- `src/agents/deep_dive_script_agent.py`

Supporting stages refine output for format and performance: `script_agent.py`, `punch_agent.py`, `caption_agent.py`, `seo_agent.py`, and `scoring_agent.py` under `src/agents/`. This suggests a flow from research evidence to structured script, engagement edits, metadata/captions, and quality scoring.

#### Media Planning and Production Assembly
Video creation is divided between creative direction, asset planning, narration, thumbnails, and final assembly:
- `src/agents/visual_director_agent.py`
- `src/agents/visual_planner_agent.py`
- `src/agents/assembly_agent.py`

Additional production boundaries include `voice_agent.py`, `thumbnail_agent.py`, and `compilation_assembler_agent.py`. Local media inputs/branding reside under `assets/`, including `assets/video/intro.mp4`; stock-media lookup is isolated in `src/services/stock_search.py`.

#### Persistence, LLMs, and External Integrations
Persistent pipeline/agent state is modeled behind a database layer:
- `src/db/models.py`
- `src/db/db.py`
- `src/db/init_db.py`

The checked-in `data/agent.db` indicates a SQLite-style local datastore. Model-provider interaction is centralized in `src/llm_client.py`, preventing agents from individually owning LLM transport. Publishing is an external-service boundary handled by:
- `src/agents/upload_agent.py`
- `src/youtube/oauth.py`

#### Feedback Loop and Operations
Post-publication analytics feed back into future content decisions:
- `src/agents/analytics_agent.py`
- `src/agents/evaluation_agent.py`
- `scripts/run_analytics_pull.py`

`scripts/run_analytics_feedback.py` operationalizes the feedback pass, while `run_daily_pipeline.py` combines production execution with recurring automation. The resulting architecture is a staged, stateful agent system with explicit boundaries for LLM calls, media sourcing, database persistence, YouTube authentication/upload, and analytics ingestion.

Main entry points: [`src/agents/orchestrator.py`](https://github.com/siva010505/helio2/blob/master/src/agents/orchestrator.py) (Agent orchestrator), [`src/agents/analytics_agent.py`](https://github.com/siva010505/helio2/blob/master/src/agents/analytics_agent.py) (Analytics evaluation), [`src/agents/assembly_agent.py`](https://github.com/siva010505/helio2/blob/master/src/agents/assembly_agent.py) (Video assembly), [`src/agents/deep_dive_script_agent.py`](https://github.com/siva010505/helio2/blob/master/src/agents/deep_dive_script_agent.py) (Script development)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Execution"]
  node_daily{{"Daily pipeline runner<br/>scheduled runner"}}
  node_pipeline{{"Pipeline entry<br/>pipeline API<br/>[pipeline.py]"}}
  node_ci{{"Scheduled CI<br/>automation workflow<br/>[daily_pipeline.yml]"}}
end

subgraph group_control["Control plane"]
  node_orchestrator["Agent orchestrator<br/>workflow coordinator<br/>[orchestrator.py]"]
  node_config["Configuration<br/>[config.yaml]"]
end

subgraph group_content["Content pipeline"]
  node_research["Research<br/>[research_agent.py]"]
  node_script["Script development<br/>script agents"]
end

subgraph group_production["Media production"]
  node_visuals["Visual planning<br/>creative direction agents"]
  node_stock["Stock media search<br/>media provider adapter<br/>[stock_search.py]"]
  node_voice["Voice generation<br/>narration agent<br/>[voice_agent.py]"]
  node_assembly["Video assembly<br/>assembly agents<br/>[assembly_agent.py]"]
end

subgraph group_platform["Platform boundaries"]
  node_llm["LLM client<br/>model gateway<br/>[llm_client.py]"]
  node_database[("Agent state store<br/>SQLite persistence<br/>[agent.db]")]
  node_upload["YouTube publishing<br/>upload agent<br/>[upload_agent.py]"]
  node_youtube(("YouTube API<br/>external platform"))
end

subgraph group_feedback["Feedback loop"]
  node_analytics["Analytics evaluation<br/>feedback agents<br/>[analytics_agent.py]"]
  node_feedback_job{{"Analytics feedback job<br/>operations runner"}}
end

node_ci -->|"triggers"| node_daily
node_daily -->|"runs"| node_pipeline
node_pipeline -->|"starts"| node_orchestrator
node_config -.->|"configures"| node_orchestrator
node_orchestrator -->|"research brief"| node_research
node_research -->|"evidence and topics"| node_script
node_script -->|"script"| node_visuals
node_visuals -->|"asset queries"| node_stock
node_visuals -->|"visual plan"| node_assembly
node_script -->|"narration script"| node_voice
node_stock -->|"media assets"| node_assembly
node_voice -->|"voiceover"| node_assembly
node_assembly -->|"finished video"| node_upload
node_upload -->|"publishes"| node_youtube
node_orchestrator -->|"model requests"| node_llm
node_orchestrator -->|"pipeline state"| node_database
node_feedback_job -->|"runs"| node_analytics
node_analytics -->|"pulls performance"| node_youtube
node_analytics -->|"stores evaluation"| node_database
node_analytics -.->|"iteration signals"| node_orchestrator

click node_daily "https://github.com/siva010505/helio2/blob/master/scripts/run_daily_pipeline.py"
click node_pipeline "https://github.com/siva010505/helio2/blob/master/src/pipeline.py"
click node_ci "https://github.com/siva010505/helio2/blob/master/.github/workflows/daily_pipeline.yml"
click node_orchestrator "https://github.com/siva010505/helio2/blob/master/src/agents/orchestrator.py"
click node_config "https://github.com/siva010505/helio2/blob/master/config.yaml"
click node_research "https://github.com/siva010505/helio2/blob/master/src/agents/research_agent.py"
click node_script "https://github.com/siva010505/helio2/blob/master/src/agents/deep_dive_script_agent.py"
click node_visuals "https://github.com/siva010505/helio2/blob/master/src/agents/visual_director_agent.py"
click node_stock "https://github.com/siva010505/helio2/blob/master/src/services/stock_search.py"
click node_voice "https://github.com/siva010505/helio2/blob/master/src/agents/voice_agent.py"
click node_assembly "https://github.com/siva010505/helio2/blob/master/src/agents/assembly_agent.py"
click node_llm "https://github.com/siva010505/helio2/blob/master/src/llm_client.py"
click node_database "https://github.com/siva010505/helio2/blob/master/data/agent.db"
click node_upload "https://github.com/siva010505/helio2/blob/master/src/agents/upload_agent.py"
click node_analytics "https://github.com/siva010505/helio2/blob/master/src/agents/analytics_agent.py"
click node_feedback_job "https://github.com/siva010505/helio2/blob/master/scripts/run_analytics_feedback.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_daily,node_pipeline,node_ci toneBlue
class node_orchestrator,node_config toneAmber
class node_research,node_script toneMint
class node_visuals,node_stock,node_voice,node_assembly toneRose
class node_llm,node_database,node_upload,node_youtube toneIndigo
class node_analytics,node_feedback_job toneTeal
```

## Components

### Execution

- [Daily pipeline runner](https://github.com/siva010505/helio2/blob/master/scripts/run_daily_pipeline.py): scheduled runner · `scripts/run_daily_pipeline.py`
- [Pipeline entry](https://github.com/siva010505/helio2/blob/master/src/pipeline.py): pipeline API · `src/pipeline.py`
- [Scheduled CI](https://github.com/siva010505/helio2/blob/master/.github/workflows/daily_pipeline.yml): automation workflow · `.github/workflows/daily_pipeline.yml`

### Control plane

- [Agent orchestrator](https://github.com/siva010505/helio2/blob/master/src/agents/orchestrator.py): workflow coordinator · Sequences agents and carries pipeline state. · `src/agents/orchestrator.py`
- [Configuration](https://github.com/siva010505/helio2/blob/master/config.yaml): runtime configuration · `config.yaml`

### Content pipeline

- [Research](https://github.com/siva010505/helio2/blob/master/src/agents/research_agent.py): research agents · Topic discovery and long-form evidence gathering. · `src/agents/research_agent.py`
- [Script development](https://github.com/siva010505/helio2/blob/master/src/agents/deep_dive_script_agent.py): script agents · Develops, refines, and scores scripts, captions, and SEO. · `src/agents/deep_dive_script_agent.py`

### Media production

- [Visual planning](https://github.com/siva010505/helio2/blob/master/src/agents/visual_director_agent.py): creative direction agents · `src/agents/visual_director_agent.py`
- [Stock media search](https://github.com/siva010505/helio2/blob/master/src/services/stock_search.py): media provider adapter · `src/services/stock_search.py`
- [Voice generation](https://github.com/siva010505/helio2/blob/master/src/agents/voice_agent.py): narration agent · `src/agents/voice_agent.py`
- [Video assembly](https://github.com/siva010505/helio2/blob/master/src/agents/assembly_agent.py): assembly agents · Combines planned visuals, narration, branding, and output. · `src/agents/assembly_agent.py`

### Platform boundaries

- [LLM client](https://github.com/siva010505/helio2/blob/master/src/llm_client.py): model gateway · Centralizes model-provider transport. · `src/llm_client.py`
- [Agent state store](https://github.com/siva010505/helio2/blob/master/data/agent.db): SQLite persistence · `data/agent.db`
- [YouTube publishing](https://github.com/siva010505/helio2/blob/master/src/agents/upload_agent.py): upload agent · `src/agents/upload_agent.py`
- **YouTube API**: external platform · Publishing and analytics service.

### Feedback loop

- [Analytics evaluation](https://github.com/siva010505/helio2/blob/master/src/agents/analytics_agent.py): feedback agents · Evaluates published performance for future decisions. · `src/agents/analytics_agent.py`
- [Analytics feedback job](https://github.com/siva010505/helio2/blob/master/scripts/run_analytics_feedback.py): operations runner · `scripts/run_analytics_feedback.py`

## Connections

- Scheduled CI → Daily pipeline runner: triggers
- Daily pipeline runner → Pipeline entry: runs
- Pipeline entry → Agent orchestrator: starts
- Configuration → Agent orchestrator: configures
- Agent orchestrator → Research: research brief
- Research → Script development: evidence and topics
- Script development → Visual planning: script
- Visual planning → Stock media search: asset queries
- Visual planning → Video assembly: visual plan
- Script development → Voice generation: narration script
- Stock media search → Video assembly: media assets
- Voice generation → Video assembly: voiceover
- Video assembly → YouTube publishing: finished video
- YouTube publishing → YouTube API: publishes
- Agent orchestrator → LLM client: model requests
- Agent orchestrator → Agent state store: pipeline state
- Analytics feedback job → Analytics evaluation: runs
- Analytics evaluation → YouTube API: pulls performance
- Analytics evaluation → Agent state store: stores evaluation
- Analytics evaluation → Agent orchestrator: iteration signals