🐕 CeREbrus

Enterprise Retail Intelligence Platform

lablab.ai Hackathon — Track 2: AI Agents with Google AI Studio

"Cerberus in mythology had three heads guarding the gate. CeREbrus has three agents guarding your enterprise data."

Three heads. One source of truth.

---

The Problem

Enterprise retail teams are split between two pain points simultaneously:

• Ops & buyers can't find answers buried across hundreds of policy docs, SOPs, and vendor contracts.
• Customer-facing reps switch between 3–4 tools just to get context before a single customer interaction.

Both problems cost enterprises real money in wasted time and bad decisions.

---

The Solution

A multi-agent system with three specialist heads under an orchestrator. One interface. Two enterprise problems solved. Genuine cross-domain reasoning — not a chatbot dressed up.

Head	Agent	Does
🧠 Head 1	Knowledge Guardian	Semantic RAG over policy, SOP, vendor contract, and compliance docs (Gemini embeddings + cosine similarity).
👤 Head 2	Customer Intel	Retrieves full customer profiles — purchases, tickets, tier, rep notes.
📋 Head 3	Synthesis	Three modes: single-customer pre-call briefs, portfolio-wide synthesis (churn risk, upsell, attention-needed), and cross-domain reasoning (customer + policy + escalation SOP in one response).

The orchestrator (cerebrus_orchestrator) routes natural-language queries to the appropriate head and lets Synthesis call multiple tools when a question spans both customer and policy data.

---

Tech Stack

• Agent framework: Google ADK (Agent Development Kit)
• Reasoning models: gemini-3.1-pro-preview (orchestrator + Synthesis)
• Fast models: gemini-3-flash-preview (Knowledge + Customer Intel)
• Embeddings: gemini-embedding-001 (3072-dim) + numpy cosine similarity for real RAG
• Frontend: vanilla HTML/CSS/JS — no framework, no build step. Three-column dashboard with a live intelligence panel that reads a JSON snapshot the agent writes on import.
• Local dev: ADK web server on :8000, Python http.server on :8080 serving the dashboard.

---

Run It Locally

1. Clone and enter the project

git clone https://github.com/SergioB03/CeRebrus.git cerebrus
cd cerebrus

2. Create the virtual environment + install dependencies

python -m venv venv
venv\Scripts\activate            # Windows
# source venv/bin/activate       # Mac/Linux
pip install -r requirements.txt

3. Add your Gemini API key

Get a key at https://aistudio.google.com → "Get API key". Open .env and replace your_api_key_here with the key.

4. Start the two servers

From the project's parent directory:

# ADK API on port 8000 (terminal 1)
adk web --port 8000 --allow_origins "http://localhost:8080" .

From the project directory:

# Static dashboard on port 8080 (terminal 2)
python -m http.server 8080 --bind 127.0.0.1

5. Open the dashboard

http://localhost:8080/index.html

The intelligence panel will show "Loading…" on first cold start until the agent module is imported. Either pre-generate by running python -m cerebrus.agent once, or just send any chat query — the snapshot regenerates automatically.

---

Demo Script

The money shot (cross-domain reasoning in one query)

"Customer 1105 wants a refund on a damaged TV — what is our policy
 and how should I handle this call?"

The Synthesis agent fetches the customer profile (Raymond Okafor, Platinum, $52K LTV), pulls the relevant return-policy clause via RAG (damaged items eligible for full refund regardless of window, manager override above $500), and applies the escalation SOP (VIP → Tier 2). One reply. Three data sources. Real cited evidence.

Portfolio synthesis (cross-customer reasoning)

"Who are my top 3 churn-risk customers right now and why?"
"Which high-LTV accounts have unresolved issues this week?"
"Top upsell candidates I should call today?"

Knowledge (semantic RAG)

"If a customer shows me a cheaper price on Amazon for the same laptop,
 what can I do for them?"
"How long do I have to fulfill a European customer's data deletion request?"
"What are the perks for Platinum tier members?"

None of these queries contain the policy-document keywords — the embedding search maps natural-language intent to the right doc.

Customer Intel (profile lookup)

"Pull up customer 4821"
"What's going on with customer 7710?"

Single-customer brief

"Brief me on customer 1105 before my support call"
"Retention brief for customer 7710"

---

Live Intelligence Panel

The dashboard's right column auto-populates from real data on every page load — no query required. This is the "advisor that just knows" surface:

• Portfolio Pulse — total customers, total LTV, open tickets, escalations (color-coded warn/crit thresholds)
• Top Risk Accounts — Top 3 customers ranked by a computed risk score (open ticket count × 2 + escalations × 5 + ticket age + frustration signals in rep notes), each with a signal chip strip and color-coded severity band. Click a card to load a pre-call brief query.
• Policy Health — flags policy docs that haven't been updated in 12+ months (stale) or 10–12 months (warn). Currently surfaces the TechSupply vendor contract (20mo) and PCI compliance guidelines (14mo).

---

Project Structure

cerebrus/
├── agent.py              ← Orchestrator + 3 sub-agents + tools + mock data (start here)
├── __init__.py           ← Exports the agent module so ADK discovers root_agent
├── index.html            ← Custom dashboard UI (three-column layout)
├── requirements.txt      ← google-adk, python-dotenv, numpy
├── .env                  ← Gemini API key (gitignored)
├── README.md
├── docs/screenshots/     ← Dashboard screenshots referenced above
└── venv/                 ← Created by setup, gitignored

At runtime agent.py writes portfolio_snapshot.json (gitignored) — the dashboard reads it for the right-panel data.

---

Track Alignment — Track 2 Scoring

Application of Technology Multi-agent system on Google ADK with sub-agent transfer routing. Gemini 3.x preview models (Pro for reasoning, Flash for retrieval). Real semantic RAG via gemini-embedding-001 + cosine similarity, not keyword matching. Synthesis agent calls multiple tools (generate_interaction_brief, analyze_customer_portfolio, search_knowledge_base) within a single response to handle cross-domain queries.

Presentation / Demo Clarity Custom three-column dashboard (no default ADK UI). Live intelligence panel that surfaces signals proactively. Agent attribution chip on every reply (HEAD 03 · 1.4s). Active head pulses on the left during reply. Markdown rendering for bold and lists. Quick-prompt sidebar with flagship cross-domain query at the top.

Business Value Three concrete enterprise ROI levers, each measurable: (1) reps reach customer context in 30 seconds instead of switching 3–4 tools; (2) managers see churn-risk accounts before they escalate; (3) compliance teams see stale policy docs without running a quarterly audit. Mock data layer is structured for a 1:1 swap with Salesforce/CRM + a vector DB in production.

Originality The Synthesis head's portfolio reasoning is the differentiator. Most "AI alerts" are SQL filters dressed up. CeREbrus passes enriched customer signals to a Gemini Pro model and lets the LLM identify the risk patterns with cited evidence — not a hardcoded WHERE clause. Cross-domain query routing (customer + policy + SOP in one response) is genuinely agentic, not three sequential single-domain answers stitched together.

---

Three heads. One source of truth.