Skip to content

A curated collection of practical AI projects implementing OCR systems, RAG, AI agents, and other AI use cases.

audit: fix brand_monitor_agent - add env comments, add tagline, fix em dashes, improve README, add docstrings

Tiioluwani59bdc7d9dc96
diff --git a/ai_agents/brand_monitor_agent/.env.example b/ai_agents/brand_monitor_agent/.env.example
index d64bc26..08746e7 100644
--- a/ai_agents/brand_monitor_agent/.env.example
+++ b/ai_agents/brand_monitor_agent/.env.example
@@ -1,2 +1,4 @@
+# Scrapingdog API key used for all data collection (web, YouTube, Twitter/X, LinkedIn). Get yours free at https://www.scrapingdog.com
SCRAPINGDOG_API_KEY=your_scrapingdog_api_key_here
+# Orq.ai API key used to route LLM requests to DeepSeek V4 Flash for analysis. Get yours free at https://orq.ai
ORQ_API_KEY=your_orq_api_key_here
diff --git a/ai_agents/brand_monitor_agent/README.md b/ai_agents/brand_monitor_agent/README.md
index e4d9394..4d6c06d 100644
--- a/ai_agents/brand_monitor_agent/README.md
+++ b/ai_agents/brand_monitor_agent/README.md
@@ -1,5 +1,7 @@
# Brand Monitor
+> Get a structured intelligence report on any brand across Web, YouTube, Twitter/X, and LinkedIn in a single run.
+
![Brand Monitor Demo](assets/demo.gif)
Get a structured intelligence report on any brand across Web, YouTube, Twitter/X, and LinkedIn in a single run. Powered by [Scrapingdog](https://www.scrapingdog.com) for data collection and DeepSeek V4 Flash for analysis.
@@ -8,23 +10,30 @@ Get a structured intelligence report on any brand across Web, YouTube, Twitter/X
Each run collects platform data via Scrapingdog and passes it to one LLM call per platform — 4 LLM calls total. Results are presented in a Streamlit UI with tabs per platform.
-- **Web** — Google SERP + Google News via Scrapingdog
-- **YouTube** — YouTube search results, with Google SERP fallback
-- **Twitter/X** — Google SERP filtered to twitter.com
-- **LinkedIn** — Google SERP filtered to linkedin.com
+- **Web:** Google SERP and Google News via Scrapingdog
+- **YouTube:** YouTube search results, with Google SERP fallback
+- **Twitter/X:** Google SERP filtered to twitter.com
+- **LinkedIn:** Google SERP filtered to linkedin.com
+
+## Prerequisites
+
+- Python 3.10 or higher
+- [uv](https://docs.astral.sh/uv/) package manager
+- A [Scrapingdog](https://www.scrapingdog.com) account and API key (free tier available)
+- An [Orq.ai](https://orq.ai) account and API key (free tier available); Orq.ai routes requests to DeepSeek V4 Flash for analysis
## Setup
-### 1. Prerequisites
+### 1. Clone the repository
-- [UV](https://docs.astral.sh/uv/) package manager
-- [Scrapingdog API key](https://www.scrapingdog.com)
-- DeepSeek V4 Flash API key
+```bash
+git clone https://github.com/Sumanth077/Hands-On-AI-Engineering.git
+cd Hands-On-AI-Engineering/ai_agents/brand_monitor_agent
+```
### 2. Install dependencies
```bash
-cd ai_agents/brand_monitor_agent
uv sync
```
@@ -66,4 +75,8 @@ brand_monitor_agent/
| Variable | Description |
|---|---|
| `SCRAPINGDOG_API_KEY` | Scrapingdog API key for all data collection |
-| `ORQ_API_KEY` | API key for LLM analysis |
+| `ORQ_API_KEY` | [Orq.ai](https://orq.ai) API key; Orq.ai routes requests to DeepSeek V4 Flash for analysis |
+
+---
+
+[⬆ Back to Top](#brand-monitor)
diff --git a/ai_agents/brand_monitor_agent/app.py b/ai_agents/brand_monitor_agent/app.py
index 3ab62e5..e93a1c7 100644
--- a/ai_agents/brand_monitor_agent/app.py
+++ b/ai_agents/brand_monitor_agent/app.py
@@ -173,6 +173,7 @@ def _detect_sentiment_pill(content: str) -> str:
def render_platform_report(platform: str, content: str):
+ """Render a platform section header with a sentiment pill and the report body."""
label, icon = PLATFORM_META.get(platform, (platform.title(), ""))
pill = _detect_sentiment_pill(content)
@@ -192,6 +193,7 @@ def render_platform_report(platform: str, content: str):
def render_results(results: dict):
+ """Render all four platform reports in labelled tabs."""
tab_web, tab_yt, tab_tw, tab_li = st.tabs(
["🌐 Web", "▶ YouTube", "𝕏 Twitter/X", "💼 LinkedIn"]
)
@@ -206,6 +208,7 @@ def render_results(results: dict):
def clear_results():
+ """Remove the last brand and results from session state."""
st.session_state.pop("last_brand", None)
st.session_state.pop("last_results", None)
@@ -222,7 +225,7 @@ if run_btn:
st.error("Please fill in both API keys in the sidebar.")
st.stop()
- with st.spinner(f"Scanning {brand} across 4 platforms — takes about a minute..."):
+ with st.spinner(f"Scanning {brand} across 4 platforms. This takes about a minute..."):
try:
results = run_brand_monitor(
brand=brand.strip(),
@@ -247,7 +250,7 @@ if "last_results" in st.session_state:
# Results header row: title + clear button
res_col, clear_col = st.columns([5, 1])
with res_col:
- st.markdown(f"### Intelligence Report — {brand_label}")
+ st.markdown(f"### Intelligence Report: {brand_label}")
with clear_col:
if st.button("Clear", use_container_width=True, on_click=clear_results):
st.rerun()
diff --git a/ai_agents/brand_monitor_agent/brand_monitor_agent/analyzers.py b/ai_agents/brand_monitor_agent/brand_monitor_agent/analyzers.py
index 5bc77ec..55b44bf 100644
--- a/ai_agents/brand_monitor_agent/brand_monitor_agent/analyzers.py
+++ b/ai_agents/brand_monitor_agent/brand_monitor_agent/analyzers.py
@@ -20,6 +20,7 @@ MODEL = "alibaba/deepseek-v4-flash"
# ---------------------------------------------------------------------------
def _call_llm(system: str, user: str, orq_key: str) -> str:
+ """Send a system and user prompt to the Orq.ai router and return the text response."""
client = OpenAI(
base_url="https://my.orq.ai/v3/router",
api_key=orq_key,
diff --git a/ai_agents/brand_monitor_agent/brand_monitor_agent/main.py b/ai_agents/brand_monitor_agent/brand_monitor_agent/main.py
index c5422b9..d24dee4 100644
--- a/ai_agents/brand_monitor_agent/brand_monitor_agent/main.py
+++ b/ai_agents/brand_monitor_agent/brand_monitor_agent/main.py
@@ -21,7 +21,7 @@ def run_brand_monitor(brand: str, scrapingdog_key: str, orq_key: str) -> dict:
orq_key: Orq.ai API key.
Returns:
- Dict with keys "web", "youtube", "twitter", "linkedin" — each
+ Dict with keys "web", "youtube", "twitter", "linkedin", each
mapping to a structured markdown intelligence brief.
"""
if not brand.strip():