VibeCI — Competitive Intelligence Agent

AI Agents: Intensive Vibe Coding Capstone Project | Track: Agents for Business | Deadline: July 6, 2026

🔗 Live demo: vibeci-107532323288.us-central1.run.app — runs in Demo mode, no key needed. Pick a competitor → Run analysis → click a citation to jump to the source line.

---

🎯 The Problem

Existing competitive-intelligence tools are programmatic, not agentic. They detect that a competitor's web page changed, then hand a diff to a Product Marketing Manager to interpret. They lack the context to understand what the change means. They do not read technical documentation, do not compare claimed capabilities against documented reality, and produce outputs that are stale on arrival.

A sales rep facing a Teramind objection needs to know that "real-time session monitoring" actually has a 2–5 minute upload lag — a fact buried in their developer docs that no existing battle card surfaces.

💡 The Solution

VibeCI is a deployable, multi-agent system that:

1. Reads a competitor's technical documentation (API docs, KBs, developer portals — live or preloaded)
2. Extracts what their product actually does per use case
3. Contrasts documented reality against their marketing claims and your positioning
4. Delivers a structured, account-ready battle card — and grounds every finding to a clickable source line in the competitor's own docs

The Technical Analysis Agent is the star. Discovery/monitoring is commodity. The defensible, impressive capability is reading API docs and surfacing — provably — the gap between marketing claims and documented reality.

---

✨ What makes the demo credible

The UI is built so a viewer can trust the output, not just read it:

• Strategy-directed, not generic. Before reading the competitor, a Strategy / Research-Planner agent turns your business context — messaging pillars, product roadmap, and solution map / ICP (with mocked connectors to Confluence / Productboard / Salesforce) — into a research brief: which lenses to scrutinise, who to frame the findings for, and which pillars to anchor the battle card in. Every gap is then tagged with the lens it answers. This is competitive intelligence directed by your strategy, not generic doc-diffing.
• Real, clickable source grounding — measured and gated. Every gap card carries a "View source ↗" citation. Clicking it scrolls the competitor's ingested documentation to — and highlights — the exact line that contradicts the marketing claim. The grounding is computed from the real documentation text (anchored on the evidence the MCP pre-screen tool extracted), not hardcoded. Each gap also gets a grounding-confidence score (0–100%, how strongly the doc backs it) shown right on the card — and an eval (python -m eval.grounding_eval, also a pytest gate) runs the real pipeline and fails CI if any finding stops grounding above threshold. The "Grounded" stat is earned, not asserted.
• An honest agent run timeline. Instead of a fake "hacker terminal," the run view shows the five agents executing in sequence, each with its model, elapsed time, and the real MCP tool calls it made (arguments in, structured result out).
• Two clearly-signposted layers. The product value ("the findings" — claim-vs-reality gap cards) is visually separated from the machinery ("under the hood" — the agent pipeline, the source document, the schema-validated JSON), so the engineering is legible without drowning the value.
• Light, SaaS-grade design. A calm, credible product surface where the only loud thing on the page is the claim-vs-reality gap.

---

🏗️ Architecture

System at a glance

flowchart TB
    subgraph BROWSER["Browser - vanilla-JS SPA (5 views)"]
        UI["Config -> Run timeline -> Results -> Landscape -> About<br/>inputs: your positioning | competitor | doc URL | marketing claims"]
    end

    subgraph BACKEND["FastAPI backend - Google Cloud Run (single instance)"]
        API["execute_workflow() - manual sequential orchestration"]
        subgraph PIPE["5-agent pipeline - google.antigravity SDK - gemini-3.5-flash"]
            S["1 - Strategy (high)<br/>business context -> Research Brief"]
            D["2 - Discovery (low)<br/>ingest competitor docs"]
            A["3 - Technical Analysis * (high)<br/>claim vs. documented reality"]
            Y["4 - Synthesis (medium)<br/>schema-valid battle card"]
            C["5 - Fact-Checking (high)<br/>ground every claim, drop unsupported"]
            S --> D --> A --> Y --> C
        end
        MCP["MCP server - stdio - FastMCP<br/>fetch_competitor_docs | compare_claims_to_docs"]
        GROUND["grounding.py - score each gap to a source line<br/>gated by eval/grounding_eval.py in CI"]
        API --> PIPE
        D <-->|MCP| MCP
        C --> GROUND
    end

    UI -->|"POST /api/analyze -> job_id"| API
    GROUND -->|"completed report + grounding"| API
    API -.->|"SSE /api/stream - typed events: mode/pipeline/agent/tool/doc/brief/completed"| UI

Loading

SDK note: the agents are built on the google.antigravity SDK (from google.antigravity import Agent, LocalAgentConfig), all targeting gemini-3.5-flash. Orchestration is explicit, sequential awaits in app/main.py (not SDK-driven handoff), which is what lets the backend emit a clean, honest event timeline.

Request lifecycle

1. Submit - POST /api/analyze creates a job and kicks execute_workflow off as a FastAPI BackgroundTask; it returns a job_id immediately.
2. Stream - the browser opens GET /api/stream/{job_id} as an SSE EventSource; the backend emits a typed event timeline (not log strings) the UI renders live.
3. Orchestrate - the five agents run as explicit sequential awaits; Discovery calls the MCP tools; the Strategy brief steers Analysis and Synthesis.
4. Ground & finish - ground_report() scores every gap to a source line, then a terminal completed event delivers the full report.

sequenceDiagram
    autonumber
    participant U as Browser (SPA)
    participant F as FastAPI
    participant P as Agent pipeline
    participant M as MCP server
    U->>F: POST /api/analyze (competitor, claims, your positioning)
    F-->>U: { job_id } - execute_workflow runs as a BackgroundTask
    U->>F: GET /api/stream/{job_id} (SSE / EventSource)
    F-->>U: mode + pipeline manifest
    P->>P: Strategy -> Research Brief
    F-->>U: agent + brief events
    P->>M: fetch_competitor_docs, compare_claims_to_docs
    M-->>P: docs + contradiction snippets
    F-->>U: tool + doc events
    P->>P: Technical Analysis * -> Synthesis -> Fact-Checking
    F-->>U: per-stage agent events
    P->>P: ground_report() scores every gap to a source line
    F-->>U: completed { report + grounding }

Loading

Agent Descriptions

Agent	Role	Reasoning
Strategy / Research-Planner	Reads your messaging pillars, roadmap & ICP → a research brief (prioritized lenses · who to frame for · which pillars) that steers the rest of the pipeline	high
Discovery Agent	Ingests competitor documentation via MCP tools; fetches live URLs or falls back to preloaded specs	low
Technical Analysis Agent ★	Reads raw specs, extracts real capabilities, contrasts against marketing claims and user positioning — prioritizing the brief's lenses	high
Synthesis Agent	Formats analysis into structured, Pydantic-validated JSON: battle cards, gap matrices, objection handlers — anchored in your pillars	medium
Fact-Checking / QC Agent	Grounds every claim back to the source documentation; removes hallucinations; re-validates the schema	high

All agents run gemini-3.5-flash, specialized by reasoning effort (ThinkingLevel), tools, and structured-output schema.

MCP Server Tools

app/mcp_server.py exposes two tools over stdio (FastMCP):

Tool	Description
fetch_competitor_docs	Fetches technical documentation from a URL (live HTTP GET, with mock fallback)
compare_claims_to_docs	Keyword-level pre-screen of marketing claims vs. documentation — extracts the doc snippets that contradict each claim (these become the grounding anchors)

---

📊 Output Schema

Every run produces a validated CompetitorReport (Pydantic):

{
  "competitor_name": "Teramind",
  "key_takeaways": ["..."],
  "gaps": [
    {
      "marketing_claim": "Real-time session monitoring with zero-latency",
      "technical_reality": "Screenshots packed into 5MB chunks, 2-5 min upload lag",
      "severity": "High Gaps",
      "sales_impact": "Pitch against the 'real-time' claim..."
    }
  ],
  "battle_card": {
    "elevator_pitch": "...",
    "strengths": ["..."],
    "weaknesses": ["..."],
    "objection_handling": [
      { "competitor_objection": "...", "our_response": "..." }
    ]
  },
  "sales_landmines": ["Ask: '...'"]
}

The response also carries raw_doc (the ingested source text) and preliminary_gaps (the MCP pre-screen hits), which power the client-side source grounding.

---

🚦 Two execution modes

Mode	What runs	API key
Demo (default, the canonical showcase)	The full UI and SSE timeline render from pre-canned, schema-accurate reports. No network, deterministic, instant.	None
Live	The real five-agent Gemini pipeline ingests docs and generates the report end-to-end.	A quota-enabled GEMINI_API_KEY

Demo mode is the showcase: it needs no key, never rate-limits, and is reproducible for judging and portfolio review. Live mode is fully wired and authenticates/fetches/calls Gemini for real — it just needs a Google AI project with available gemini-3.5-flash quota (the free tier may be 0; enable billing or use a quota-enabled key). If a live run hits a quota or key error, the UI surfaces a clean, actionable message and offers a one-click fallback to Demo mode.

---

✅ Course Concepts Demonstrated

Concept	Where	Status
Multi-agent system	app/agents/ — 5 agents orchestrated via google.antigravity, surfaced in a live run timeline	✅ Built
MCP Server	app/mcp_server.py — fetch_competitor_docs + compare_claims_to_docs, with real tool-call I/O shown in the UI	✅ Built
Source grounding	Every claim links to the exact line in the competitor's docs; computed for real (app/grounding.py)	✅ Built
Grounding-confidence eval	Per-gap confidence score, surfaced in-app and gated by eval/grounding_eval.py + pytest	✅ Built
Structured output	Pydantic CompetitorReport schema, validated and viewable in-app	✅ Built
Deployability	Dockerfile + Cloud Run config (see below)	✅ Built
Security features	No secrets in code; bring-your-own-key (masked, never stored); SSRF guard on the live doc fetch	✅ Built
Antigravity	Built on the google.antigravity SDK; the agentic, vibe-coded build is shown in the video	✅ Built

---

🚀 Setup & Running Locally

Prerequisites

• Python 3.11+
• (Optional) A Gemini API key with quota — only for Live mode; Demo mode needs none

1. Install

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

2. Configure (optional — Live mode only)

cp .env.example .env
# Edit .env and add your GEMINI_API_KEY (for Live mode)

3. Run — from the repo root

uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload

Open http://localhost:8080. Demo mode is on by default, so it works immediately with no key.

⚠️ Always run from the repo root — the app mounts app/static, imports modules as app.*, and spawns the MCP server with -m app.mcp_server, all relative to the working directory.

---

🧪 Tests

A pytest suite covers the deterministic core — the MCP document tools (live-fetch with mock fallback, the claims-vs-docs pre-screen), the full demo pipeline (incl. the structured SSE event timeline the frontend and notebook depend on), and a grounding-confidence gate that fails if any finding stops grounding to its source line above threshold:

pip install -r requirements-dev.txt
pytest                       # run from the repo root

# The grounding eval also runs standalone — prints a per-gap confidence report:
python -m eval.grounding_eval

  VibeCI · GROUNDING-CONFIDENCE EVAL
  Teramind       avg 100%   min 100%   [PASS]
  Hubstaff       avg  79%   min  58%   [PASS]
  Time Doctor    avg  85%   min  56%   [PASS]
  CORPUS: 8/8 gaps grounded ≥ 45%  ·  avg confidence 89%  ·  min 56%
  RESULT: ✓ PASS — grounding holds across the corpus

---

🐳 Docker Deployment (Cloud Run)

Build & run locally

docker build -t vibeci .
docker run -p 8080:8080 -e GEMINI_API_KEY=your_key_here vibeci   # key optional; Demo mode needs none

Deploy to Google Cloud Run (demo-only — no key shipped)

# one-time (your account / project; billing enabled)
./gcloud.sh auth login
./gcloud.sh config set project YOUR_PROJECT_ID

# deploy — builds from the Dockerfile via Cloud Build, then deploys
./deploy.sh
#  ≡ gcloud run deploy vibeci --source . --region us-central1 \
#        --allow-unauthenticated --max-instances 1

Demo-only by design. No GEMINI_API_KEY is set on the service, so the public instance runs Demo mode (Live shows a graceful "needs a key" message). .gcloudignore keeps .env out of the build upload entirely. To enable Live, redeploy appending --set-env-vars GEMINI_API_KEY=<quota-enabled-key>.

Single instance. Job state is in-memory, so the deploy pins --max-instances 1 — the SSE stream must hit the same process that ran the job (don't add --workers).

---

📁 Project Structure

.
├── app/
│   ├── main.py              # FastAPI backend — job queue, SSE timeline, pipeline orchestration
│   ├── grounding.py         # Source grounding + grounding-confidence score (server source of truth)
│   ├── mcp_server.py        # MCP server: fetch_competitor_docs + compare_claims_to_docs
│   ├── agents/
│   │   ├── config.py        # Shared model config + the five agent personas
│   │   ├── strategy.py      # Strategy Agent — reads business context → Research Brief
│   │   ├── discovery.py     # Discovery Agent — uses the MCP server over stdio
│   │   ├── analysis.py      # Technical Analysis Agent ★
│   │   ├── synthesis.py     # Synthesis Agent — Pydantic structured output
│   │   └── checking.py      # Fact-Checking / QC Agent
│   └── static/              # Frontend — vanilla HTML/CSS/JS, no framework, no build
│       ├── index.html       # 5 views: config → run → results → landscape → about
│       ├── css/style.css    # Light, SaaS-grade design system
│       └── js/app.js        # SSE client, run timeline, results + real source grounding
├── eval/
│   └── grounding_eval.py    # Grounding-confidence eval — runs the real pipeline, gates on the score
├── tests/                   # pytest — MCP tools, demo pipeline/SSE contract, grounding gate
├── Dockerfile
├── requirements.txt
├── .env.example
└── README.md

---

🔒 Security & Honesty

• No API keys in code. All secrets are passed via environment variables (.env locally, --set-env-vars on Cloud Run).
• SSRF-guarded doc fetch. The live fetch only follows public http(s) URLs; loopback, private, link-local (incl. the 169.254.169.254 cloud-metadata endpoint), and reserved hosts are rejected and fall back to mock data.
• Source grounding is real. Findings trace to the actual ingested documentation; the Fact-Checking agent removes claims not backed by the docs, and the UI lets anyone verify each claim against its source line.
• Demo mode is labelled as demo. Pre-canned data is clearly marked "Demo data" in the UI — never presented as a live run.
• No proprietary data. This build uses sanitized, publicly-available competitor documentation or high-fidelity mocks. No internal company data is included.

---

🗺️ Extension Paths (Designed, Not Built)

Per the project charter, these are architecture-designed but deliberately deferred:

• Change-tracking agent — diff competitor docs over time; alert on updates
• Positioning-recommendation agent — recommend your own positioning moves based on gap trends over time (distinct from the built Strategy/Research-Planner agent)
• Account differentiation agent — map gaps to specific deal opportunities
• Live CRM integration — push battle cards into Salesforce (currently illustrative)
• Live KB integration — connect the user's internal knowledge base (currently mocked via pasted positioning)

---

📜 License

CC-BY 4.0 — See LICENSE for details.

Built for the Kaggle AI Agents: Intensive Vibe Coding Capstone Project.