# garibudimanoj-ops/crowdwisdom-hermes-ads architecture

> Architecture diagram of the GitHub repository garibudimanoj-ops/crowdwisdom-hermes-ads, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/garibudimanoj-ops/crowdwisdom-hermes-ads
- Repository: https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads

## Overview

CrowdWisdomTrading Video Ads Agent is a multi-agent pipeline that turns advertising examples and audience research into a reviewed, cinematic short-form ad. The main workflow runs from ad collection and marketing analysis through research, CrowdWisdom-specific data, concept writing, creative review, cinematography, asset/shot planning, and video rendering; orchestration also tracks stage status and quality. The graph preserves README-documented capabilities even where source was not sampled. Relationships without sampled caller evidence are cited to the README; unsampled implementation details are not inferred.

Main entry points: [`src/orchestrator.py`](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/orchestrator.py) (Stage orchestrator), [`src/agents/marketing_analyzer.py`](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/marketing_analyzer.py) (Marketing analysis), [`src/agents/research_agent.py`](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/research_agent.py) (Audience research), [`src/agents/script_agent.py`](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/script_agent.py) (Concept writing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Pipeline orchestration"]
  node_orchestrator["Stage orchestrator<br/>[orchestrator.py]"]
end

subgraph group_agents["Creative agents"]
  node_ads["Ads collection<br/>[ads_manager.py]"]
  node_marketing["Marketing analysis"]
  node_research["Audience research<br/>[research_agent.py]"]
  node_data["CrowdWisdom data<br/>[data_agent.py]"]
  node_script["Concept writing<br/>[script_agent.py]"]
  node_director["Creative review"]
  node_cinematography["Cinematic planning"]
  node_video["Video production<br/>[video_agent.py]"]
  node_quality["Video quality review<br/>[quality_agent.py]"]
end

subgraph group_integrations["Integrations"]
  node_assets["Visual asset selection<br/>[pexels_client.py]"]
  node_apify["Apify<br/>[apify_client.py]"]
  node_tavily["Tavily search<br/>[tavily_tool.py]"]
  node_exa["Exa search<br/>[exa_tool.py]"]
  node_hermes["Hermes runner<br/>[hermes_runner.py]"]
  node_hermes_backend["Hermes Python backend"]
end

subgraph group_artifacts["Models and status"]
  node_plan_schema["Cinematography schema"]
  node_ad_models["Ad and creative models<br/>[ad_models.py]"]
  node_status["Pipeline status<br/>[pipeline_status.py]"]
end

node_operator(("Pipeline operator"))
node_apify_service["Apify service"]
node_research_services["Tavily / Exa"]
node_hermes_service["Hermes / OpenRouter"]
node_render_service["OpenMontage / Remotion"]
node_final_ad["Final video ad"]

node_operator -->|"runs pipeline"| node_orchestrator
node_orchestrator -->|"runs stage"| node_ads
node_orchestrator -->|"runs stage"| node_marketing
node_orchestrator -->|"runs stage"| node_research
node_orchestrator -->|"runs stage"| node_data
node_orchestrator -->|"runs stage"| node_script
node_orchestrator -->|"runs stage"| node_director
node_orchestrator -->|"runs stage"| node_video
node_orchestrator -->|"runs stage"| node_quality
node_orchestrator -->|"updates status"| node_status
node_ads -->|"calls"| node_apify
node_apify -->|"fetches ads"| node_apify_service
node_ads -->|"provides ads"| node_marketing
node_marketing -->|"provides insights"| node_research
node_research -->|"searches with"| node_tavily
node_research -->|"searches with"| node_exa
node_tavily -->|"queries"| node_research_services
node_exa -->|"queries"| node_research_services
node_marketing -->|"generates analysis"| node_hermes
node_script -->|"generates concepts"| node_hermes
node_director -->|"reviews concepts"| node_hermes
node_hermes -->|"delegates to"| node_hermes_backend
node_hermes -.->|"sends prompts"| node_hermes_service
node_research -->|"provides findings"| node_script
node_data -->|"provides brand data"| node_script
node_script -->|"submits concepts"| node_director
node_director -->|"provides direction"| node_cinematography
node_cinematography -.->|"validates plan"| node_plan_schema
node_cinematography -->|"guides selection"| node_assets
node_assets -.->|"provides footage"| node_video
node_video -->|"composes video"| node_render_service
node_video -->|"produces"| node_final_ad
node_quality -->|"checks output"| node_video
node_ads -->|"normalizes records"| node_ad_models
node_marketing -->|"uses insight models"| node_ad_models

click node_orchestrator "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/orchestrator.py"
click node_ads "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/ads_manager.py"
click node_marketing "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/marketing_analyzer.py"
click node_research "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/research_agent.py"
click node_data "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/data_agent.py"
click node_script "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/script_agent.py"
click node_director "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/creative_director.py"
click node_cinematography "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/cinematography_agent.py"
click node_plan_schema "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/schemas/cinematography_plan.py"
click node_assets "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/pexels_client.py"
click node_video "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/video_agent.py"
click node_quality "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/quality_agent.py"
click node_apify "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/apify_client.py"
click node_tavily "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/tavily_tool.py"
click node_exa "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/exa_tool.py"
click node_hermes "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/hermes_runner.py"
click node_hermes_backend "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/hermes_python_backend.py"
click node_ad_models "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/models/ad_models.py"
click node_status "https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/status/pipeline_status.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_orchestrator toneBlue
class node_ads,node_marketing,node_research,node_data,node_script,node_director,node_cinematography,node_video,node_quality toneAmber
class node_assets,node_apify,node_tavily,node_exa,node_hermes,node_hermes_backend,node_apify_service,node_hermes_service toneMint
class node_plan_schema,node_ad_models,node_status toneRose
class node_operator,node_research_services,node_render_service,node_final_ad toneIndigo
```

## Components

### Pipeline orchestration

- [Stage orchestrator](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/orchestrator.py): `src/orchestrator.py`

### Creative agents

- [Ads collection](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/ads_manager.py): `src/agents/ads_manager.py`
- [Marketing analysis](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/marketing_analyzer.py): `src/agents/marketing_analyzer.py`
- [Audience research](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/research_agent.py): `src/agents/research_agent.py`
- [CrowdWisdom data](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/data_agent.py): `src/agents/data_agent.py`
- [Concept writing](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/script_agent.py): `src/agents/script_agent.py`
- [Creative review](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/creative_director.py): `src/agents/creative_director.py`
- [Cinematic planning](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/cinematography_agent.py): `src/agents/cinematography_agent.py`
- [Video production](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/video_agent.py): `src/agents/video_agent.py`
- [Video quality review](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/agents/quality_agent.py): `src/agents/quality_agent.py`

### Integrations

- [Visual asset selection](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/pexels_client.py): `src/integrations/pexels_client.py`
- [Apify](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/apify_client.py): `src/integrations/apify_client.py`
- [Tavily search](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/tavily_tool.py): `src/integrations/tavily_tool.py`
- [Exa search](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/exa_tool.py): `src/integrations/exa_tool.py`
- [Hermes runner](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/hermes_runner.py): `src/integrations/hermes_runner.py`
- [Hermes Python backend](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/integrations/hermes_python_backend.py): `src/integrations/hermes_python_backend.py`

### Models and status

- [Cinematography schema](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/schemas/cinematography_plan.py): `src/schemas/cinematography_plan.py`
- [Ad and creative models](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/models/ad_models.py): `src/models/ad_models.py`
- [Pipeline status](https://github.com/garibudimanoj-ops/crowdwisdom-hermes-ads/blob/main/src/status/pipeline_status.py): `src/status/pipeline_status.py`

### Other components

- **Pipeline operator**
- **Apify service**
- **Tavily / Exa**
- **Hermes / OpenRouter**
- **OpenMontage / Remotion**
- **Final video ad**

## Connections

- Pipeline operator → Stage orchestrator: runs pipeline (evidence: `README.md`)
- Stage orchestrator → Ads collection: runs stage (evidence: `src/orchestrator.py`)
- Stage orchestrator → Marketing analysis: runs stage (evidence: `src/orchestrator.py`)
- Stage orchestrator → Audience research: runs stage (evidence: `src/orchestrator.py`)
- Stage orchestrator → CrowdWisdom data: runs stage (evidence: `src/orchestrator.py`)
- Stage orchestrator → Concept writing: runs stage (evidence: `src/orchestrator.py`)
- Stage orchestrator → Creative review: runs stage (evidence: `src/orchestrator.py`)
- Stage orchestrator → Video production: runs stage (evidence: `src/orchestrator.py`)
- Stage orchestrator → Video quality review: runs stage (evidence: `src/orchestrator.py`)
- Stage orchestrator → Pipeline status: updates status (evidence: `src/orchestrator.py`)
- Ads collection → Apify: calls (evidence: `src/agents/ads_manager.py`)
- Apify → Apify service: fetches ads (evidence: `src/integrations/apify_client.py`)
- Ads collection → Marketing analysis: provides ads (evidence: `README.md`)
- Marketing analysis → Audience research: provides insights (evidence: `src/agents/research_agent.py`)
- Audience research → Tavily search: searches with (evidence: `src/agents/research_agent.py`)
- Audience research → Exa search: searches with (evidence: `src/agents/research_agent.py`)
- Tavily search → Tavily / Exa: queries (evidence: `src/integrations/tavily_tool.py`)
- Exa search → Tavily / Exa: queries (evidence: `src/integrations/exa_tool.py`)
- Marketing analysis → Hermes runner: generates analysis (evidence: `src/agents/marketing_analyzer.py`)
- Concept writing → Hermes runner: generates concepts (evidence: `src/agents/script_agent.py`)
- Creative review → Hermes runner: reviews concepts (evidence: `src/agents/creative_director.py`)
- Hermes runner → Hermes Python backend: delegates to (evidence: `src/integrations/hermes_runner.py`)
- Hermes runner → Hermes / OpenRouter: sends prompts (evidence: `README.md`)
- Audience research → Concept writing: provides findings (evidence: `README.md`)
- CrowdWisdom data → Concept writing: provides brand data (evidence: `README.md`)
- Concept writing → Creative review: submits concepts (evidence: `README.md`)
- Creative review → Cinematic planning: provides direction (evidence: `README.md`)
- Cinematic planning → Cinematography schema: validates plan (evidence: `src/agents/cinematography_agent.py`)
- Cinematic planning → Visual asset selection: guides selection (evidence: `README.md`)
- Visual asset selection → Video production: provides footage (evidence: `README.md`)
- Video production → OpenMontage / Remotion: composes video (evidence: `README.md`)
- Video production → Final video ad: produces (evidence: `README.md`)
- Video quality review → Video production: checks output (evidence: `src/agents/quality_agent.py`)
- Ads collection → Ad and creative models: normalizes records (evidence: `src/agents/ads_manager.py`)
- Marketing analysis → Ad and creative models: uses insight models (evidence: `src/agents/marketing_analyzer.py`)
