BrandGuard looks for risk signals in brand mentions from news, blogs, communities and the web. It analyzes mention growth, negative sentiment, risk keywords and propagation patterns, prepares reports, and sends alerts after human approval.

Core capabilities

• Six feature groups for multidimensional risk signals
• Normal, caution and alert decisions combining Isolation Forest with promotion rules
• LangGraph routing that logs normal cases and analyzes only risky cases
• RAG-supported analysis, Markdown and Word reports, and explicit evidence
• Slack and email notification only after human approval
• CLI, Streamlit dashboard and FastAPI REST interfaces

Ownership

This project was developed during the NVIDIA AI Core Engineer course. It implements collection, detection, agent execution, storage, APIs and validation scenarios.

Current status: the full pipeline runs with demo data and optional live collection.

1. Collection and mention contract

Naver news and blog, RSS and optional Tavily collectors normalize different documents into mentions with title, body, source, author, publication time and URL. Source cursors and duplicate keys reduce repeated ingestion, while a failed source does not discard successful collectors. Original evidence and collection time remain available to generated reports.

2. Windows and feature generation

The feature pipeline computes volume, growth, sentiment, keyword, user and propagation groups per brand window. Recent input and a 29-day baseline remain distinct, with explicit missing-value and minimum-sample behavior. Feature vectors and baseline versions are stored so a decision can be reconstructed.

3. Combined detection and severity gate

Isolation Forest emits a multivariate anomaly score, while domain rules evaluate explainable conditions such as growth, negative ratio and risk keywords. A combiner maps both outputs to normal, caution or alert. Model-only and rule-only triggers remain distinct evidence in the report.

4. LangGraph and human review

Normal detections are recorded and stop. Caution and alert enter LangGraph nodes for evidence selection, cause hypotheses, response options and report assembly. Nothing reaches an external channel before Human Review approves, revises or rejects the report. Approved reports go to Slack or email, with a console sink when channels are absent.

5. Storage, access and operations

A repository adapter absorbs SQLite and PostgreSQL placeholder, auto-increment and UPSERT differences. CLI, Streamlit, scheduler and FastAPI /analyze, /history, /reports and /monitor use the same application service. Collector, LLM and notifier failures become stage status while persisted detections and review records remain intact.

6. State and data-model ownership

Shared mention, window and detection models form the collector-detector contract, while RiskState owns state during LangGraph execution. The repository adapter owns persistence so API, dashboard and scheduler remain unaware of SQL dialect differences.

7. Performance and failure recovery

Collection fan-out, sentiment processing, Isolation Forest fitting and LLM latency are primary bottlenecks. Per-channel timeouts and partial success, model reuse, bounded windows and idempotent incident writes require validation; a rule-based report remains the LLM fallback.

8. Security, observability and debt

API keys are isolated in environment variables, while collector input, notification targets and dashboard access require validation. Stage status and persisted records provide audit evidence, but distributed tracing, SLOs and production-send approval are missing or planned. Production precision and recall have not been measured.

Combine Isolation Forest with rules

An anomaly score alone can make a relative maximum look dangerous even in normal data. Scores are normalized against the training distribution’s median-to-99th-percentile range, while simultaneous high negativity and growth can force an alert.

Route sentiment by channel

The Korean sentiment model worked on short consumer speech but produced errors on long financial news. Community and social text use the model, news and web use a lexicon, and all channels fall back to the lexicon when the model is absent.

Require human approval

Automatic alerts are fast but expensive when wrong. Cause analysis and reports are generated automatically, while external Slack and email delivery remains behind Human Review.

Keep external services optional

Without LLM or Tavily keys, rule-based cause analysis and Naver collection preserve an executable pipeline. Quality differs, but the system remains reproducible.

Automated scenarios

The public repository reports five passing checks from python tests/test_pipeline.py. In a scenario with 30 baseline days followed by two injected surge days, the crisis interval was alerted while the preceding 29 days remained normal. A no-crisis baseline scenario also remained normal.

Evidence output

Alerts do not return only a score. Mention count, negative ratio, risk-keyword ratio, shares and growth over the preceding average are provided for human review.

Known limits

These are synthetic pipeline checks, not a general accuracy claim for real brand crises. Production precision, recall and detection latency are not measured. Search markup changes and external API limits can alter collection coverage.

Completed

• Multi-channel collection and six feature groups
• Three-level risk decisions using Isolation Forest and rules
• LangGraph branching, cause analysis and report generation
• Human-reviewed Slack, email and console notification
• SQLite/PostgreSQL storage, scheduler and REST API
• Streamlit dashboard and synthetic pipeline tests

In progress

• More resilient channel collection and selector fallback
• Validation of sentiment routing and risk thresholds
• Stronger traceability between evidence, reports and approval

Planned

• Precision and recall on labeled real-world incidents
• Brand- and industry-specific baselines and thresholds
• Collection failure, duplication and rate-limit observability
• Production authentication, authorization and audit design

Out of scope

Sending external response messages without human approval is not a goal. BrandGuard supports detection and decision-making while final action remains with a person.