# saikumarljmu-maker/agentic-marketing-ai architecture

> Architecture diagram of the GitHub repository saikumarljmu-maker/agentic-marketing-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saikumarljmu-maker/agentic-marketing-ai
- Repository: https://github.com/saikumarljmu-maker/agentic-marketing-ai

## Overview

This repository implements retrospective Criteo campaign-budget decision simulations, with rule-based, LLM-assisted, and portfolio-strategy variants, plus tools for counterfactual and statistical evaluation. In the sampled LLM loop, daily observations are analyzed and turned into campaign recommendations; the loop compares those with human decisions and can project KPI effects. The V2 preparation and analysis modules document a separate portfolio-replay capability. The README is empty and several modules were not sampled, so uncertain connections are omitted.

Main entry points: [`src/simulation_loop_llm.py`](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/simulation_loop_llm.py) (LLM replay), [`src/simulation_loop.py`](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/simulation_loop.py) (Rule-based replay), [`src/agents/observer.py`](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/observer.py) (Observation), [`src/evaluation/response_curves.py`](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/evaluation/response_curves.py) (Response curves)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation workflows"]
  node_ruleloop["Rule-based replay<br/>[simulation_loop.py]"]
  node_llmloop["LLM replay"]
  node_v2loop["V2 replay"]
end

subgraph group_agents["Decision agents"]
  node_observer["Observation<br/>[observer.py]"]
  node_analyst["Analyst<br/>[analyst.py]"]
  node_strategy["Campaign strategy<br/>[strategy.py]"]
  node_portfolio["Portfolio strategy"]
  node_memory["Decision memory<br/>[memory.py]"]
  node_execution["Decision comparison<br/>[execution.py]"]
end

subgraph group_data["Data preparation"]
  node_prep["Criteo preparation<br/>[criteo_prep.py]"]
  node_processed["Processed campaign data<br/>[criteo_prep.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_curves["Response curves<br/>[response_curves.py]"]
  node_replayanalysis["Replay analysis<br/>[analyse_v2.py]"]
  node_stats["Statistical analysis"]
  node_protect["Protection replay"]
  node_modelcompare["Model comparison"]
end

node_user(("Researcher"))
node_raw["Criteo dataset"]
node_claude(("Anthropic API"))
node_ollama(("Ollama models"))

node_user -->|"runs replay"| node_ruleloop
node_user -->|"runs replay"| node_llmloop
node_user -->|"runs replay"| node_v2loop
node_raw -->|"reads dataset"| node_observer
node_ruleloop -->|"initializes"| node_observer
node_llmloop -->|"initializes"| node_observer
node_observer -->|"returns observations"| node_ruleloop
node_observer -->|"returns observations"| node_llmloop
node_ruleloop -->|"retrieves context"| node_memory
node_ruleloop -->|"records decisions"| node_execution
node_ruleloop -->|"fits curves"| node_curves
node_ruleloop -->|"projects effects"| node_curves
node_llmloop -->|"retrieves context"| node_memory
node_llmloop -->|"requests analysis"| node_analyst
node_llmloop -->|"requests decisions"| node_strategy
node_llmloop -->|"records decisions"| node_execution
node_llmloop -->|"fits curves"| node_curves
node_llmloop -->|"projects effects"| node_curves
node_analyst -.->|"requests analysis"| node_claude
node_strategy -.->|"requests decisions"| node_claude
node_prep -->|"reads dataset"| node_raw
node_prep -->|"writes aggregates"| node_processed
node_v2loop -->|"requests allocation"| node_portfolio
node_portfolio -.->|"requests strategy"| node_claude
node_processed -->|"provides replay data"| node_replayanalysis
node_processed -->|"provides replay data"| node_protect
node_stats -->|"computes comparisons"| node_stats
node_user -->|"compares models"| node_modelcompare
node_modelcompare -.->|"requests completion"| node_claude
node_modelcompare -.->|"runs model"| node_ollama

click node_ruleloop "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/simulation_loop.py"
click node_llmloop "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/simulation_loop_llm.py"
click node_v2loop "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/simulation_loop_v2.py"
click node_observer "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/observer.py"
click node_analyst "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/analyst.py"
click node_strategy "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/strategy.py"
click node_portfolio "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/portfolio_strategy.py"
click node_memory "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/memory.py"
click node_execution "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/execution.py"
click node_curves "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/evaluation/response_curves.py"
click node_prep "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/data/criteo_prep.py"
click node_processed "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/data/criteo_prep.py"
click node_replayanalysis "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/evaluation/analyse_v2.py"
click node_stats "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/evaluation/statistical_analysis.py"
click node_protect "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/evaluation/protect_off_replay.py"
click node_modelcompare "https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/model_comparison.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_ruleloop,node_llmloop,node_v2loop toneBlue
class node_observer,node_analyst,node_strategy,node_portfolio,node_memory,node_execution toneAmber
class node_prep,node_processed,node_claude toneMint
class node_curves,node_replayanalysis,node_stats,node_protect,node_modelcompare toneRose
class node_user,node_raw,node_ollama toneIndigo
```

## Components

### Simulation workflows

- [Rule-based replay](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/simulation_loop.py): `src/simulation_loop.py`
- [LLM replay](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/simulation_loop_llm.py): `src/simulation_loop_llm.py`
- [V2 replay](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/simulation_loop_v2.py): `src/simulation_loop_v2.py`

### Decision agents

- [Observation](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/observer.py): `src/agents/observer.py`
- [Analyst](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/analyst.py): `src/agents/analyst.py`
- [Campaign strategy](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/strategy.py): `src/agents/strategy.py`
- [Portfolio strategy](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/portfolio_strategy.py): `src/agents/portfolio_strategy.py`
- [Decision memory](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/memory.py): `src/agents/memory.py`
- [Decision comparison](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/agents/execution.py): `src/agents/execution.py`

### Data preparation

- [Criteo preparation](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/data/criteo_prep.py): `src/data/criteo_prep.py`
- [Processed campaign data](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/data/criteo_prep.py): `src/data/criteo_prep.py`

### Evaluation

- [Response curves](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/evaluation/response_curves.py): `src/evaluation/response_curves.py`
- [Replay analysis](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/evaluation/analyse_v2.py): `src/evaluation/analyse_v2.py`
- [Statistical analysis](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/evaluation/statistical_analysis.py): `src/evaluation/statistical_analysis.py`
- [Protection replay](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/evaluation/protect_off_replay.py): `src/evaluation/protect_off_replay.py`
- [Model comparison](https://github.com/saikumarljmu-maker/agentic-marketing-ai/blob/main/src/model_comparison.py): `src/model_comparison.py`

### Other components

- **Researcher**
- **Criteo dataset**
- **Anthropic API**
- **Ollama models**

## Connections

- Researcher → Rule-based replay: runs replay
- Researcher → LLM replay: runs replay
- Researcher → V2 replay: runs replay
- Criteo dataset → Observation: reads dataset
- Rule-based replay → Observation: initializes
- LLM replay → Observation: initializes
- Observation → Rule-based replay: returns observations
- Observation → LLM replay: returns observations
- Rule-based replay → Decision memory: retrieves context
- Rule-based replay → Decision comparison: records decisions
- Rule-based replay → Response curves: fits curves
- Rule-based replay → Response curves: projects effects
- LLM replay → Decision memory: retrieves context
- LLM replay → Analyst: requests analysis
- LLM replay → Campaign strategy: requests decisions
- LLM replay → Decision comparison: records decisions
- LLM replay → Response curves: fits curves
- LLM replay → Response curves: projects effects
- Analyst → Anthropic API: requests analysis
- Campaign strategy → Anthropic API: requests decisions
- Criteo preparation → Criteo dataset: reads dataset
- Criteo preparation → Processed campaign data: writes aggregates
- V2 replay → Portfolio strategy: requests allocation
- Portfolio strategy → Anthropic API: requests strategy
- Processed campaign data → Replay analysis: provides replay data
- Processed campaign data → Protection replay: provides replay data
- Statistical analysis → Statistical analysis: computes comparisons
- Researcher → Model comparison: compares models
- Model comparison → Anthropic API: requests completion
- Model comparison → Ollama models: runs model