Project: [Reasoning Agents] - CulturalGuard

Track

Reasoning Agents (Azure AI Foundry)

Project Name

CulturalGuard

GitHub Username

Wendy-Nam

Repository URL

https://github.com/Wendy-Nam/culturalguard

Project Description

CulturalGuard is an AI agent that analyzes social media and marketing content for cross-cultural risks before publishing. It detects cultural taboos, PII leaks, violent metaphors, competitor mentions, and political/religious content across multiple markets (Korea, Japan, US, Global) and platforms (LinkedIn, Instagram, etc.).

Key capabilities:

• Knowledge-Base-Driven Risk Analysis — 20+ structured JSON rules covering 8 risk categories (aggressive competition, violent metaphor, self-praise, tone-deaf messaging, PII, political, religious, brand violations)
• Multi-Step Reasoning — Combines ReAct (Observe→Think→Act), Chain-of-Thought, and Self-Reflection patterns. The agent loads KB context, matches risk patterns with variations, applies market-specific penalty multipliers (KR face culture ×1.5, JP Wa/Kenson ×2.0, US DEI ×1.3), and fuses scores using a weighted formula: (db_score × 0.4) + (llm_score × 0.6) + penalties
• Culturally-Safe Rewriting — Generates 3-5 alternative versions classified on 5 axes (formality, agency, evidence, competition framing, emotional tone) with diagnosis-first approach
• Human-in-the-Loop Escalation — High-risk content (score ≥ 0.71) triggers Slack/Email/Discord notifications via MCP integration for human review
• Safety Gate — Prompt injection detection, PII redaction, harmful content filtering
• Attribution — Every finding cites its knowledge base source with trust scores and verification dates

Built with Azure AI Foundry SDK, Streamlit UI, and MCP (Model Context Protocol) for external tool integration. The Streamlit interface offers three modes: Analyze (risk scoring), Create (safe content generation), and Translate (multi-market translation + analysis).

Demo Video or Screenshots

Primary Programming Language

Python

Key Technologies Used

• Azure AI Foundry SDK (azure-ai-projects, azure-ai-agents)
• Streamlit (ChatGPT-style UI)
• MCP (Model Context Protocol) — Resend Email, Slack Webhook, Discord Bot
• deep-translator (multi-market translation)
• Playwright (UI demo automation)
• python-dotenv, duckduckgo-search

Submission Type

Individual

Team Members

No response

Submission Requirements

• My project meets the track-specific challenge requirements
• My repository includes a comprehensive README.md with setup instructions
• My code does not contain hardcoded API keys or secrets
• I have included demo materials (video or screenshots)
• My project is my own work with proper attribution for any third-party code
• I agree to the Code of Conduct
• I have read and agree to the Disclaimer
• My submission does NOT contain any confidential, proprietary, or sensitive information
• I confirm I have the rights to submit this content and grant the necessary licenses

Quick Setup Summary

git clone https://github.com/Wendy-Nam/culturalguard.git
cd culturalguard
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # Fill in API keys

Copy knowledge_base examples to real files:

for dir in attribution brand cultural platform_norms rewrite risk safety scoring; do
for f in knowledge_base/$dir/*.example.json; do cp "$f" "${f%.example.json}.json"; done
done

Run CLI test:

python main.py

Or launch Streamlit UI:

streamlit run app.py

Technical Highlights

1. Hybrid Scoring Engine — Fuses rule-based KB matching (weight 0.4) with LLM contextual judgment (weight 0.6), plus additive penalties per risk category. Market-specific multipliers adjust sensitivity (e.g., Japan's Wa/Kenson culture doubles the competition penalty to ×2.0).
2. Structured Knowledge Base Architecture — 20+ JSON files organized into 8 categories (risk, cultural, platform_norms, brand, safety, scoring, rewrite, attribution). Each pattern includes variations, risk scores, regional applicability, safe alternatives, and source attribution with trust scores. The KB is fully gitignored for safety — only schema examples are committed.
3. Diagnosis-First Rewriting with 5-Axis Classification — Instead of generic "softer" rewrites, the agent first diagnoses why each phrase fails in the target culture, then generates 3-5 meaningfully different alternatives classified on formality, agency, evidence type, competition framing, and emotional tone.
4. Three Reasoning Patterns Working Together — ReAct (tool orchestration), Chain-of-Thought (step-by-step risk analysis), and Self-Reflection (post-analysis confidence scoring) run in sequence for every analysis.
5. MCP-Based Human-in-the-Loop — When risk score ≥ 0.71, the agent doesn't just flag — it sends structured alerts via Slack/Email/Discord with full context for human reviewers to make the final call.

Challenges & Learnings

1. Context Window Management — The full knowledge base exceeds token limits. Built a dynamic compression system (load_analysis_context) that prioritizes relevant risk patterns per platform/market and progressively truncates to stay under 8K chars.
2. Cultural Nuance is Hard to Codify — "Crushing it" is celebratory in US LinkedIn but offensive in Korean/Japanese B2B. Learned that risk scoring must be market-dependent, not universal. This led to the market adjustment multiplier system.
3. Avoiding Shallow Rewrites — Early versions just softened words ("crush" → "outpace") while keeping the same competitive frame. The anti-pattern system in the rewrite guide forces genuinely different approaches rather than cosmetic changes.
4. Balancing Safety with Usability — Over-aggressive filtering blocks legitimate content. The 4-tier decision system (APPROVE/REVIEW/REVISE/ESCALATE) prevents both false positives and missed risks.

Contact Information

https://www.linkedin.com/in/seo-a-nam/

Country/Region

South Korea

This issue is a project submission rather than a defined contribution task. The repository mentioned is Wendy-Nam/culturalguard; start with README.md, requirements.txt, main.py, and app.py to understand its setup and entry points. No specific change, acceptance criteria, or definition of done is provided.