mirror of
https://github.com/arkorty/B.Tech-Project-III.git
synced 2026-04-19 12:41:48 +00:00
62 KiB
62 KiB
ThirdEye — The Complete Hackathon Bible
Single Source of Truth. If it's not in this document, it doesn't exist for the hackathon.
TABLE OF CONTENTS
- Project Identity
- The Problem We Solve
- What ThirdEye Does
- Competitive Landscape & Why We Win
- The Adaptive Lens System
- Cross-Group Intelligence (The Wow Feature)
- Agent Architecture (8 Agents)
- Free Model Provider Stack
- Agent → Model Mapping
- Provider Router Code
- System Prompts for Each Agent
- RAG & Embedding Strategy
- MCP Servers
- Telegram Bot Implementation
- React Dashboard Design
- Data Models & Schemas
- API Endpoints (FastAPI Backend)
- 24-Hour Build Plan (Hour by Hour)
- Demo Data Seeding Strategy
- The 90-Second Demo Script
- Judging Criteria Self-Assessment
- Pitch Deck Outline
- Risk Mitigation Playbook
- API Keys Checklist
- Tech Stack Summary (Copy-Paste Ready)
- Repo Structure
1. PROJECT IDENTITY
Name: ThirdEye
Tagline: "Your team already has the answers. They're just trapped in chat."
One-Line Pitch: A multi-agent conversation intelligence engine that passively listens to any Telegram group — dev teams, product squads, client channels — extracts structured knowledge, builds a living knowledge graph, detects patterns humans miss, and catches cross-team blind spots before they become crises.
Elevator Pitch (30 seconds):
Every day, your team makes hundreds of decisions, discovers bugs, promises clients, and solves problems — all in group chat. And every day, that intelligence vanishes as messages scroll past. ThirdEye is a drop-in Telegram bot that silently listens to your group conversations, extracts structured intelligence — decisions, tech debt, promises, risks — and builds a living knowledge base that grows smarter over time. Ask it anything about your team's history. But the real magic? Deploy it across multiple groups, and it detects blind spots BETWEEN teams — your dev team is blocked, your design team doesn't know, your client expects delivery Friday, and nobody connected the dots. Until now.
Category: Agentic AI / Multi-Agent System / Conversation Intelligence
NOT: A chatbot. Not a summarizer. Not a search tool. It's a conversation intelligence engine.
2. THE PROBLEM WE SOLVE
The Knowledge Graveyard Problem:
- Teams generate enormous value in group chats: decisions, recommendations, warnings, technical knowledge, client commitments
- 100% of this knowledge is lost within days as messages scroll past
- When someone asks "why did we choose Redis?" or "what did we promise the client?" — nobody remembers, and nobody can find it
- When Team A is blocked by Team B, but Team B doesn't know — nobody connects the dots until it's a crisis
Who feels this pain:
- Engineering teams (decisions lost, tech debt invisible, knowledge silos forming)
- Product teams (feature requests scattered, roadmap drift unnoticed, priority conflicts buried)
- Agencies/client work (promises untracked, scope creep uncaught, sentiment shifts missed)
- Any team of 3+ people communicating in chat
Scale of the problem:
- Slack's own research shows teams save 97 minutes/week when they can find information intelligently
- Slack AI costs $17.50/user/month and only does reactive summaries
- 900M+ Telegram users, millions of professional groups
- Zero products do what ThirdEye does (see competitive analysis below)
3. WHAT THIRDEYE DOES
Core Capabilities
-
Passive Intelligence Extraction — Silently monitors group messages and extracts structured signals: decisions, tech debt, feature requests, promises, bugs, knowledge, risks. No commands needed. No tagging. No forms.
-
Adaptive Context Detection — Auto-detects whether a group is a dev team, product team, client channel, or community, and activates the right extraction ontology.
-
Living Knowledge Graph — Builds a persistent, queryable knowledge base in ChromaDB that grows over time. Resolves conflicts ("was it Redis or Memcached?"), tracks temporal changes, and maintains entity relationships.
-
Natural Language Querying — Any group member can ask questions and get community-sourced answers with attribution: "Based on 4 team members' discussions over the past 2 weeks..."
-
Pattern Detection — Identifies trends and anomalies: "Tech debt mentions up 300% this sprint." "Only @raj discusses the payment module — bus factor = 1."
-
Proactive Alerts — Sends Telegram alerts for concerning patterns without being asked: overdue promises, sentiment shifts, knowledge silos, recurring bugs.
-
Cross-Group Intelligence ⭐ — THE KILLER FEATURE. When deployed in multiple groups simultaneously, detects blind spots between teams: blocked handoffs, conflicting decisions, information silos, duplicated effort, promise-reality gaps.
User Interaction Points
- In Telegram:
/ask [question]— query the knowledge base./digest— get a summary./alerts— see current warnings./lens [mode]— change detection mode. - React Dashboard: Full intelligence console with knowledge stream, entity maps, pattern timelines, cross-group analysis, promise tracker, risk radar.
- Proactive Alerts: Bot sends Telegram messages when patterns or anomalies are detected (no user action required).
4. COMPETITIVE LANDSCAPE & WHY WE WIN
Direct Competitors Analyzed
| Product | What It Does | What It DOESN'T Do | Price |
|---|---|---|---|
| Slack AI | Channel summaries on demand, enterprise search, action items | Persistent intelligence, pattern detection, cross-group analysis, proactive alerts | $17.50/user/month |
| Prism (lablab.ai winner) | Extracts product signals (bugs, features, ideas) from team chats | Multiple lens modes, knowledge graph, temporal patterns, cross-group intelligence, decision provenance | Unknown |
| Runbear | Q&A bot that learns from team docs/conversations | Proactive intelligence, pattern detection, anything beyond Q&A | $49/month |
| ManyChat / Chat Data | Customer support automation bots for Telegram | Not intelligence extraction; purely reactive FAQ bots | Various |
Our Positioning (The Empty Quadrant)
REACTIVE ◄──────────────────────► PROACTIVE
│ │
Slack AI │ │ ★ ThirdEye
(summaries │ │ (persistent intelligence,
on demand)│ │ pattern detection,
│ │ cross-group analysis,
Prism │ │ proactive alerts)
(product │ │
signals) │ │
│ │
SINGLE GROUP ◄──┼───────────────────────────────┼──► CROSS-GROUP
│ │
Runbear │ │
(Q&A only) │ │
We occupy the only empty quadrant: Proactive + Cross-Group.
What a judge would say
"I've seen chat summarizers. I've seen Q&A bots. I've never seen a system that passively builds intelligence across multiple team chats and detects blind spots between teams. That's a new category."
5. THE ADAPTIVE LENS SYSTEM
When ThirdEye joins a group, the Context Detector Agent reads the first 50-100 messages and auto-classifies into one of four modes. Users can override with /lens set dev or combine with /lens set dev+product.
DevLens — Engineering Teams
| Signal Type | What We Extract | Example |
|---|---|---|
| Architecture Decision | Decision, alternatives considered, rationale, who decided, date | "Let's go with Redis, Memcached doesn't support pub/sub" |
| Tech Debt | Item, owner, severity, status (resolved/open), frequency | "I'm just hardcoding this for now" |
| Knowledge Silo | Person, domain, bus factor score | Only @raj answers payment module questions |
| Recurring Bug | Bug description, frequency, linked messages, trend | "The timeout issue is back again" |
| Stack Decision | Technology choice, status (proposed/decided/implemented) | "We should try Bun instead of Node" |
| Deployment Risk | Risk type, who did it, pattern tracking | "I'm pushing directly to main" |
| Workaround | Issue, temporary fix, occurrence count | "Just restart the pod when it happens" |
Proactive alerts: Tech debt trending, knowledge silo warnings, recurring bug escalation, deployment risk patterns.
ProductLens — Product Teams
| Signal Type | What We Extract | Example |
|---|---|---|
| Feature Request | Feature, source, frequency, champion | "Users keep asking for dark mode" |
| User Pain Point | Issue, evidence (customer names), severity | "Sarah from Acme got stuck on step 3" |
| Roadmap Drift | % of discussion on off-roadmap topics | Team discussing feature X not on sprint board |
| Priority Conflict | Conflicting views, participants, status | "Mobile first" vs "API stability first" |
| Metric Mention | Metric name, value, context, date | "Conversion dropped to 2.3%" |
| User Quote | Direct quote, sentiment, linked feature | "I'd pay double for this feature" |
| Competitor Intel | Competitor, action, date, context | "Competitor X just launched something similar" |
Proactive alerts: Top pain points ranked, roadmap drift warnings, unassigned popular features, priority conflicts unresolved.
ClientLens — Client/Agency Channels
| Signal Type | What We Extract | Example |
|---|---|---|
| Promise | Deliverable, deadline, owner, status | "We'll have mockups ready by Friday" |
| Scope Creep | Addition, whether formally requested | "Could you also add dark mode?" |
| Sentiment Shift | Trend direction, evidence (message tone) | Messages becoming shorter, more formal |
| Unanswered Request | Question, time elapsed, topic | Client question unanswered for 48h |
| Satisfaction Signal | Positive/negative signal, context | "This is exactly what we needed!" |
| Escalation Risk | Indicator, topic, risk level | "I need to loop in my manager" |
| Client Decision | Decision, who decided, date | "Let's go with Option B" |
Proactive alerts: Overdue promises, sentiment decline, scope creep count, unanswered questions.
CommunityLens — Open/Interest Groups
| Signal Type | What We Extract |
|---|---|
| Recommendation | Place, product, service + sentiment + endorser |
| Event | What, when, where, who shared |
| Issue/Complaint | Topic, frequency, affected people |
| Local Knowledge | Tips, warnings, insider info |
| Question | Unanswered community questions |
6. CROSS-GROUP INTELLIGENCE (THE WOW FEATURE)
When ThirdEye runs in 2+ groups, the Cross-Group Analyst Agent activates.
What It Detects
Blocked Handoffs:
Dev team: "Still waiting for design specs" (mentioned 3 times this week) Design team: No mention of this deliverable → "Likely handoff gap between dev and design teams."
Conflicting Decisions:
Product team decided "mobile-first approach" on Mar 15 Dev team discussing "API-first priority" on Mar 17 → "Potential misalignment between product and dev priorities."
Information Silos:
Client mentioned "new regulatory requirement" in client channel Mar 12 Neither dev nor product channels mention this → "Critical client information not flowing to internal teams."
Promise-Reality Gap:
Product promised client "feature X by end of sprint" in client channel Dev team's discussion shows feature X is blocked by infrastructure issue → "Promise to client may not be deliverable. Timeline risk."
Duplicated Effort:
Dev team discussing building an internal dashboard Design team simultaneously prototyping a similar dashboard → "Possible duplicated effort across teams."
The Demo Moment
"Your dev team has been blocked for 5 days. Your design team doesn't know. Your client expects delivery Friday. Nobody connected these dots — until now."
7. AGENT ARCHITECTURE (8 AGENTS)
Message arrives from ANY Telegram group
│
▼
┌─────────────────────────────┐
│ 1. Context Detector Agent │ Auto-classifies group type (one-time + periodic)
│ (SambaNova 405B) │ Activates appropriate lens ontology
└─────────────┬───────────────┘
│
▼
┌─────────────────────────────┐
│ 2. Signal Extractor Agent │ Processes batched messages (every 5-10 msgs)
│ (Groq Llama 3.3 70B) │ Extracts domain-specific signals per active lens
└─────────────┬───────────────┘
│
┌────┴────┐
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ 3. Classifier│ │ 4. Entity │
│ Agent │ │ Resolver Agent│
│ (Groq 8B) │ │ (Groq 70B) │
│ Tags: type, │ │ Resolves "this", │
│ sentiment, │ │ "that bug", │
│ urgency │ │ "same issue" │
└──────┬───────┘ └────────┬─────────┘
└────────┬─────────┘
▼
┌─────────────────────────────┐
│ 5. Knowledge Architect │ Builds + maintains ChromaDB knowledge graph
│ Agent │ Resolves conflicts, tracks temporal changes
│ (SambaNova 405B / │ Links entities across conversations
│ OpenRouter Nemotron 120B) │
└─────────────┬───────────────┘
│
┌────┴────┐
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ 6. Pattern │ │ 7. Cross-Group │ ⭐ THE KILLER AGENT
│ Detector │ │ Analyst Agent │ Compares intelligence across
│ Agent │ │ (SambaNova 405B) │ ALL deployed groups
│ (OpenRouter │ │ │ Detects blind spots, conflicts,
│ Nemotron) │ │ │ information silos
└──────┬───────┘ └────────┬─────────┘
└────────┬─────────┘
▼
┌─────────────────────────────┐
│ 8. Query Agent │ Handles /ask queries via agentic RAG
│ (Groq 70B — fast response) │ over ChromaDB knowledge graph
└─────────────────────────────┘
│
▼
┌───────────┐
│ Alert │ (Shares the Query Agent's pipeline)
│ Composer │ Crafts Telegram alerts + weekly digests
└───────────┘
Agent Communication Pattern (A2A-Inspired)
Agents communicate via a shared message bus (Python asyncio queue or Redis if needed):
# Each agent emits structured messages
{
"source_agent": "signal_extractor",
"target_agent": "classifier",
"payload": {
"signal_text": "Let's go with Redis for caching",
"raw_message_id": 12345,
"group_id": "acme-dev",
"timestamp": "2026-03-21T10:30:00Z"
}
}
8. FREE MODEL PROVIDER STACK
Provider Priority Order (Fallback Chain)
Groq (fastest) → Cerebras (fast) → SambaNova (405B access) → OpenRouter (27 models) → Google AI Studio (last resort)
Provider Details
| Provider | Signup URL | Key Models | Rate Limit | Daily Capacity | Credit Card? |
|---|---|---|---|---|---|
| Groq | console.groq.com | Llama 3.3 70B, Llama 3.1 8B, Whisper v3 | 30 RPM | ~3,000-6,000 RPD | No |
| Cerebras | cloud.cerebras.ai | Llama 3.3 70B, Llama 3.1 8B | 30 RPM, 60K TPM | ~1,000-2,000 RPD | No |
| SambaNova | cloud.sambanova.ai | Llama 3.1 405B, Llama 3.3 70B | 10-30 RPM | ~500-1,000 RPD + $5 credits | No |
| OpenRouter | openrouter.ai | 27 free models (see below) | 20 RPM per model | ~5,400 RPD total | No |
| Cohere | dashboard.cohere.com | Embed v4, Rerank 3.5, Command R+ | 20 RPM | 1,000 calls/month | No |
| Google AI Studio | aistudio.google.com | Gemini 2.5 Flash/Pro | Advertised 250 RPD | Real: ~20-50 | No |
| Cloudflare | dash.cloudflare.com | Llama 3.3 70B, Mistral | 10K neurons/day | ~300-500 RPD | No |
Combined daily capacity: ~10,000-15,000 requests for $0
Key OpenRouter Free Models
| Model ID | Params | Context | Best For |
|---|---|---|---|
nvidia/nemotron-3-super-120b-a12b:free |
120B (12B active) | 262K | Heavy reasoning, pattern detection |
openai/gpt-oss-120b:free |
117B (5.1B active) | 131K | Tool calling, reasoning |
qwen/qwen3-coder:free |
480B (35B active) | 262K | Any code generation needed |
meta-llama/llama-3.3-70b-instruct:free |
70B | 66K | General workhorse |
minimax/minimax-m2.5:free |
MoE | 197K | Agentic workflows |
mistralai/mistral-small-3.1-24b-instruct:free |
24B | 128K | Fast structured extraction |
stepfun/step-3.5-flash:free |
196B (11B active) | 256K | Reasoning at speed |
openai/gpt-oss-20b:free |
21B (3.6B active) | 131K | Lightweight classification |
nvidia/nemotron-nano-9b-v2:free |
9B | 128K | Ultra-fast classification |
openrouter/free |
Auto-selected | Varies | Ultimate fallback (auto-routes) |
9. AGENT → MODEL MAPPING
| Agent | Task Type | Primary Provider/Model | Fallback 1 | Fallback 2 | Est. Daily Calls |
|---|---|---|---|---|---|
| Context Detector | Complex reasoning (one-time) | SambaNova / Llama 3.1 405B | OpenRouter / Nemotron 120B | OpenRouter / gpt-oss-120b | 5-10 |
| Signal Extractor | Structured extraction | Groq / Llama 3.3 70B | Cerebras / Llama 3.3 70B | OpenRouter / Nemotron 120B | 80-100 |
| Classifier | Fast classification | Groq / Llama 3.1 8B | Cerebras / Llama 3.1 8B | OpenRouter / gpt-oss-20b | 200+ |
| Entity Resolver | Coreference resolution | Groq / Llama 3.3 70B | OpenRouter / Mistral Small 3.1 | Cerebras / Llama 3.3 70B | 30-50 |
| Knowledge Architect | Complex graph updates | SambaNova / Llama 3.1 405B | OpenRouter / gpt-oss-120b | OpenRouter / Nemotron 120B | 20-30 |
| Pattern Detector | Trend analysis | OpenRouter / Nemotron 120B | SambaNova / 405B | OpenRouter / Step 3.5 Flash | 10-20 |
| Cross-Group Analyst | Cross-referencing | SambaNova / Llama 3.1 405B | OpenRouter / gpt-oss-120b | OpenRouter / Nemotron 120B | 5-10 |
| Query Agent | Fast Q&A response | Groq / Llama 3.3 70B | Cerebras / Llama 3.3 70B | OpenRouter / Llama 3.3 70B | 30-50 |
10. PROVIDER ROUTER CODE
# thirdeye/providers.py
import os
from openai import AsyncOpenAI
# Initialize all providers
providers = {
"groq": AsyncOpenAI(
base_url="https://api.groq.com/openai/v1",
api_key=os.getenv("GROQ_API_KEY"),
),
"cerebras": AsyncOpenAI(
base_url="https://api.cerebras.ai/v1",
api_key=os.getenv("CEREBRAS_API_KEY"),
),
"sambanova": AsyncOpenAI(
base_url="https://api.sambanova.ai/v1",
api_key=os.getenv("SAMBANOVA_API_KEY"),
),
"openrouter": AsyncOpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.getenv("OPENROUTER_API_KEY"),
),
"google": AsyncOpenAI(
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
api_key=os.getenv("GEMINI_API_KEY"),
),
}
# Model registry: task_type → ordered list of (provider, model)
MODEL_REGISTRY = {
"fast_small": [
("groq", "llama-3.1-8b-instant"),
("cerebras", "llama-3.1-8b"),
("openrouter", "openai/gpt-oss-20b:free"),
("openrouter", "nvidia/nemotron-nano-9b-v2:free"),
],
"fast_large": [
("groq", "llama-3.3-70b-versatile"),
("cerebras", "llama-3.3-70b"),
("openrouter", "meta-llama/llama-3.3-70b-instruct:free"),
("sambanova", "Meta-Llama-3.3-70B-Instruct"),
],
"reasoning": [
("sambanova", "Meta-Llama-3.1-405B-Instruct"),
("openrouter", "nvidia/nemotron-3-super-120b-a12b:free"),
("openrouter", "openai/gpt-oss-120b:free"),
("openrouter", "stepfun/step-3.5-flash:free"),
],
"agentic": [
("openrouter", "minimax/minimax-m2.5:free"),
("openrouter", "nvidia/nemotron-3-super-120b-a12b:free"),
("groq", "llama-3.3-70b-versatile"),
],
"fallback": [
("openrouter", "openrouter/free"), # Auto-routes to ANY available free model
("google", "gemini-2.5-flash"),
],
}
async def call_llm(task_type: str, messages: list, temperature: float = 0.3, max_tokens: int = 2000):
"""Route to best available provider with automatic fallback on rate limits."""
candidates = MODEL_REGISTRY.get(task_type, MODEL_REGISTRY["fallback"])
for provider_name, model_id in candidates:
client = providers.get(provider_name)
if not client:
continue
try:
response = await client.chat.completions.create(
model=model_id,
messages=messages,
temperature=temperature,
max_tokens=max_tokens,
timeout=30,
)
return {
"content": response.choices[0].message.content,
"provider": provider_name,
"model": model_id,
"usage": {
"input": response.usage.prompt_tokens if response.usage else 0,
"output": response.usage.completion_tokens if response.usage else 0,
},
}
except Exception as e:
error_str = str(e).lower()
if "429" in error_str or "rate" in error_str or "quota" in error_str:
continue # Rate limited → try next provider
if "timeout" in error_str:
continue # Timeout → try next provider
raise # Unknown error → bubble up
# If all candidates fail, try the universal fallback
try:
response = await providers["openrouter"].chat.completions.create(
model="openrouter/free",
messages=messages,
temperature=temperature,
max_tokens=max_tokens,
)
return {
"content": response.choices[0].message.content,
"provider": "openrouter",
"model": "openrouter/free (auto-routed)",
}
except:
raise Exception("ALL providers exhausted. Check API keys and rate limits.")
11. SYSTEM PROMPTS FOR EACH AGENT
Context Detector Agent
You are the Context Detector for ThirdEye. You analyze a batch of messages from a Telegram group and determine what TYPE of group this is.
CLASSIFY into exactly ONE of these categories:
- "dev" — Software engineering team (signals: code references, PRs, deployments, bugs, tech stack discussions)
- "product" — Product/business team (signals: features, users, metrics, roadmap, competitors, launches)
- "client" — Client/agency channel (signals: deliverables, timelines, approvals, feedback, invoices)
- "community" — Community/interest group (signals: recommendations, events, local info, casual discussion)
Analyze the messages below and respond ONLY with valid JSON:
{
"detected_lens": "dev|product|client|community",
"confidence": 0.0-1.0,
"evidence": ["list of 3-5 specific signals you found"],
"secondary_lens": "optional second lens if hybrid group"
}
Signal Extractor Agent (DevLens variant)
You are the Signal Extractor for ThirdEye operating in DevLens mode. You analyze batches of developer team chat messages and extract STRUCTURED SIGNALS.
Extract ONLY signals that represent meaningful information. Skip greetings, small talk, emoji reactions, and meta-conversation.
For EACH signal found, output JSON in this format:
{
"signals": [
{
"type": "architecture_decision|tech_debt|knowledge_silo_evidence|recurring_bug|stack_decision|deployment_risk|workaround",
"summary": "One-sentence description",
"entities": ["@person", "technology", "service_name"],
"severity": "low|medium|high|critical",
"status": "proposed|decided|implemented|unresolved",
"raw_quote": "The exact message or key phrase (keep short)",
"message_index": 0
}
]
}
If NO meaningful signals exist in the batch, return: {"signals": []}
Be SELECTIVE. Quality over quantity. Only extract signals that would matter to a tech lead reviewing the week.
Signal Extractor Agent (ProductLens variant)
You are the Signal Extractor for ThirdEye operating in ProductLens mode.
Extract signals from product team conversations:
{
"signals": [
{
"type": "feature_request|user_pain_point|roadmap_drift|priority_conflict|metric_mention|user_quote|competitor_intel",
"summary": "One-sentence description",
"entities": ["@person", "feature_name", "customer_name", "competitor"],
"source": "internal_team|customer_feedback|data",
"frequency_hint": "first_mention|recurring|escalating",
"raw_quote": "Key phrase",
"message_index": 0
}
]
}
Signal Extractor Agent (ClientLens variant)
You are the Signal Extractor for ThirdEye operating in ClientLens mode.
Extract signals from client/agency conversations:
{
"signals": [
{
"type": "promise|scope_creep|sentiment_signal|unanswered_request|satisfaction|escalation_risk|client_decision",
"summary": "One-sentence description",
"entities": ["@person", "deliverable", "deadline"],
"deadline": "YYYY-MM-DD or null",
"owner": "@person or null",
"risk_level": "low|medium|high|critical",
"raw_quote": "Key phrase",
"message_index": 0
}
]
}
Pay SPECIAL attention to:
- Casual scope additions ("oh could you also...")
- Tone shifts (shorter messages, more formal language = potential dissatisfaction)
- Unacknowledged questions (client asked something, no response yet)
- Implicit deadlines ("by end of week", "before the meeting")
Classifier Agent
You are a fast classifier. Given an extracted signal, add metadata tags.
Input: A signal JSON object.
Output: Add these fields:
{
"category": "technical|business|interpersonal|process|risk",
"sentiment": "positive|neutral|negative|urgent",
"urgency": "none|low|medium|high|critical",
"entities_normalized": ["normalized entity names"],
"keywords": ["3-5 searchable keywords"]
}
Respond ONLY with the augmented JSON. No explanation.
Knowledge Architect Agent
You are the Knowledge Architect for ThirdEye. You maintain a structured knowledge graph.
You receive: A batch of classified signals from a group.
You have access to: The existing knowledge graph context (provided in the prompt).
Your jobs:
1. MERGE new signals with existing knowledge (update, don't duplicate)
2. RESOLVE CONFLICTS (if signal contradicts existing knowledge, keep newer + flag the conflict)
3. TRACK TEMPORAL CHANGES (same topic discussed differently over time = evolution)
4. LINK ENTITIES (if @alice and @bob discussed the same service, link them)
5. UPDATE STATUS (if a "proposed" decision was later "decided", update)
Output a structured update:
{
"updates": [
{"action": "create|update|conflict", "entity_id": "...", "data": {...}, "reason": "..."}
],
"new_relationships": [
{"from": "entity_id", "to": "entity_id", "type": "decided_by|knows_about|blocked_by|promised_to"}
],
"conflicts_detected": [
{"existing": "...", "new": "...", "recommendation": "..."}
]
}
Pattern Detector Agent
You are the Pattern Detector for ThirdEye. You analyze accumulated signals over time to find patterns and anomalies.
You receive: All signals from the past 7 days for a group, with timestamps.
Detect these pattern types:
1. FREQUENCY SPIKES — signal type mentioned significantly more than usual
2. KNOWLEDGE SILOS — only one person discusses a critical topic
3. RECURRING ISSUES — same bug/problem appearing repeatedly
4. SENTIMENT TRENDS — gradual shift in tone over time
5. STALE ITEMS — decisions proposed but never resolved, promises made but never tracked
Output:
{
"patterns": [
{
"type": "frequency_spike|knowledge_silo|recurring_issue|sentiment_trend|stale_item",
"description": "Human-readable description",
"severity": "info|warning|critical",
"evidence": ["list of supporting signal IDs"],
"recommendation": "Suggested action"
}
]
}
Cross-Group Analyst Agent
You are the Cross-Group Intelligence Analyst for ThirdEye. This is the MOST IMPORTANT analysis you perform.
You receive: Intelligence summaries from MULTIPLE Telegram groups (e.g., #dev-team, #product, #client-acme).
Your job is to find BLIND SPOTS — information that exists in one group but should exist in another.
Detect:
1. BLOCKED HANDOFFS — Team A waiting for something from Team B, but Team B doesn't know
2. CONFLICTING DECISIONS — Team A decided X, Team B decided the opposite
3. INFORMATION SILOS — Critical info in Group A never reached Group B
4. PROMISE-REALITY GAPS — Promise made in client group, but dev group shows it's blocked
5. DUPLICATED EFFORT — Two teams working on similar things without knowing
Output:
{
"cross_group_insights": [
{
"type": "blocked_handoff|conflicting_decision|information_silo|promise_reality_gap|duplicated_effort",
"description": "Clear, specific description of the blind spot",
"group_a": {"name": "...", "evidence": "..."},
"group_b": {"name": "...", "evidence": "..."},
"severity": "warning|critical",
"recommendation": "Specific action to resolve"
}
]
}
Be SPECIFIC. Don't be vague. Name the groups, the people, the topics, and the exact conflict.
Query Agent
You are the Query Agent for ThirdEye. Users ask you questions about their team's chat history and knowledge.
You have access to retrieved context from the knowledge graph (provided below).
RULES:
1. Answer ONLY based on information in the provided context. Never make up information.
2. ALWAYS cite your sources: "Based on a discussion between @alice and @bob on Mar 15..."
3. If the information doesn't exist in context, say so clearly: "I don't have information about that in the knowledge base yet."
4. Be concise. Answer in 2-4 sentences unless a longer answer is warranted.
5. If relevant, mention related signals: "You might also want to know that [related finding]..."
Format: Natural language response suitable for a Telegram message (no markdown headers, minimal formatting).
12. RAG & EMBEDDING STRATEGY
Embedding Provider
| Provider | Model | Free Limit | Use |
|---|---|---|---|
| Cohere | Embed v4 | 1,000 calls/month (96 texts/call) | Primary embeddings |
| Local fallback | all-MiniLM-L6-v2 via sentence-transformers | Unlimited (runs on CPU) | Backup if Cohere exhausted |
ChromaDB Setup
import chromadb
# Persistent storage (survives restarts)
client = chromadb.PersistentClient(path="./chroma_db")
# One collection per group
def get_collection(group_id: str):
return client.get_or_create_collection(
name=f"thirdeye_{group_id}",
metadata={"hnsw:space": "cosine"}
)
# Cross-group collection for the analyst
cross_group = client.get_or_create_collection(name="thirdeye_cross_group")
What Gets Embedded
Each extracted signal becomes a ChromaDB document:
collection.add(
documents=[signal["summary"]],
metadatas=[{
"type": signal["type"],
"severity": signal["severity"],
"entities": json.dumps(signal["entities"]),
"timestamp": signal["timestamp"],
"group_id": group_id,
"lens": active_lens,
"raw_quote": signal["raw_quote"],
"status": signal["status"],
}],
ids=[f"{group_id}_{signal_id}"]
)
Query Flow
User asks: "Why did we choose Redis?"
│
▼
Embed query using Cohere Embed v4
│
▼
ChromaDB similarity search (top 10 results)
│
▼
Filter by metadata (group_id, type="architecture_decision")
│
▼
Feed results as context to Query Agent
│
▼
Query Agent synthesizes answer with citations
13. MCP SERVERS
Build these using FastMCP (Python):
pip install fastmcp
knowledge-graph MCP Server
from fastmcp import FastMCP
mcp = FastMCP("thirdeye-knowledge")
@mcp.tool()
def query_knowledge(group_id: str, query: str, signal_type: str = None, limit: int = 10):
"""Search the knowledge graph for a specific group."""
collection = get_collection(group_id)
where = {"type": signal_type} if signal_type else None
results = collection.query(query_texts=[query], n_results=limit, where=where)
return results
@mcp.tool()
def get_recent_signals(group_id: str, hours: int = 24, signal_type: str = None):
"""Get signals from the last N hours."""
# Implementation: filter ChromaDB by timestamp metadata
pass
@mcp.tool()
def get_entity_map(group_id: str):
"""Get all entities and their relationships for a group."""
pass
cross-group MCP Server
@mcp.tool()
def get_cross_group_summary(group_ids: list[str]):
"""Get intelligence summaries from multiple groups for cross-analysis."""
pass
@mcp.tool()
def find_mentions_across_groups(entity: str, group_ids: list[str]):
"""Find where a specific entity (person, technology, feature) is mentioned across groups."""
pass
14. TELEGRAM BOT IMPLEMENTATION
Setup
# bot.py
from telegram import Update, Bot
from telegram.ext import Application, MessageHandler, CommandHandler, filters
BOT_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")
app = Application.builder().token(BOT_TOKEN).build()
# Message handler — captures ALL group messages
async def handle_message(update: Update, context):
"""Process every message in groups where bot is added."""
if not update.message or not update.message.text:
return
msg = {
"text": update.message.text,
"sender": update.message.from_user.username or update.message.from_user.first_name,
"timestamp": update.message.date.isoformat(),
"group_id": str(update.message.chat_id),
"group_name": update.message.chat.title,
"message_id": update.message.message_id,
}
# Add to message buffer (process in batches of 5-10)
await add_to_buffer(msg)
# Command handlers
async def cmd_ask(update: Update, context):
"""Handle /ask queries"""
query = " ".join(context.args)
if not query:
await update.message.reply_text("Usage: /ask [your question]")
return
answer = await query_agent.process(query, str(update.message.chat_id))
await update.message.reply_text(answer)
async def cmd_digest(update: Update, context):
"""Generate and send a digest for this group"""
digest = await generate_digest(str(update.message.chat_id))
await update.message.reply_text(digest)
async def cmd_alerts(update: Update, context):
"""Show current active alerts"""
alerts = await get_active_alerts(str(update.message.chat_id))
await update.message.reply_text(alerts)
async def cmd_lens(update: Update, context):
"""Set or check the active lens mode"""
if context.args:
mode = context.args[0]
await set_lens_mode(str(update.message.chat_id), mode)
await update.message.reply_text(f"Lens mode set to: {mode}")
else:
mode = await get_lens_mode(str(update.message.chat_id))
await update.message.reply_text(f"Current lens: {mode}")
async def cmd_crossgroup(update: Update, context):
"""Show cross-group intelligence (if bot is in multiple groups)"""
insights = await cross_group_analyst.analyze()
await update.message.reply_text(insights)
# Register handlers
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))
app.add_handler(CommandHandler("ask", cmd_ask))
app.add_handler(CommandHandler("digest", cmd_digest))
app.add_handler(CommandHandler("alerts", cmd_alerts))
app.add_handler(CommandHandler("lens", cmd_lens))
app.add_handler(CommandHandler("crossgroup", cmd_crossgroup))
# IMPORTANT: Disable privacy mode in BotFather!
# Send /setprivacy → Select bot → Disable
# This allows the bot to read ALL messages, not just commands
app.run_polling()
Message Batching
# buffer.py
from collections import defaultdict
import asyncio
message_buffers = defaultdict(list)
BATCH_SIZE = 5 # Process every 5 messages
BATCH_TIMEOUT = 60 # Or every 60 seconds, whichever comes first
async def add_to_buffer(msg: dict):
group_id = msg["group_id"]
message_buffers[group_id].append(msg)
if len(message_buffers[group_id]) >= BATCH_SIZE:
batch = message_buffers[group_id]
message_buffers[group_id] = []
await process_batch(group_id, batch)
async def process_batch(group_id: str, messages: list):
"""Run the full agent pipeline on a batch of messages."""
# 1. Format messages for extraction
formatted = "\n".join([f"[{m['sender']}]: {m['text']}" for m in messages])
# 2. Signal Extractor
signals = await signal_extractor.extract(formatted, group_id)
# 3. Classify each signal
classified = [await classifier.classify(s) for s in signals]
# 4. Resolve entities
resolved = await entity_resolver.resolve(classified, group_id)
# 5. Update knowledge graph
await knowledge_architect.update(resolved, group_id)
# 6. Check for patterns (every 10th batch)
if should_check_patterns(group_id):
patterns = await pattern_detector.detect(group_id)
if patterns:
await send_alerts(group_id, patterns)
# 7. Cross-group analysis (every 20th batch or hourly)
if should_check_cross_group():
insights = await cross_group_analyst.analyze()
if insights:
await send_cross_group_alerts(insights)
15. REACT DASHBOARD DESIGN
Route Structure
/ → Landing page with overview of all groups
/group/:groupId → Single group intelligence view
/group/:groupId/knowledge → Knowledge stream (all signals)
/group/:groupId/entities → Entity relationship map
/group/:groupId/patterns → Pattern timeline
/group/:groupId/alerts → Active alerts
/cross-group → ⭐ Cross-Group Intelligence Panel
/cross-group/handoffs → Blocked handoff tracker
/cross-group/alignment → Team alignment score
/cross-group/promises → Promise dashboard across all groups
/cross-group/risks → Aggregated risk radar
Key Components
Knowledge Stream — Real-time feed of extracted signals. Each card shows: signal type icon, summary, entities mentioned, severity badge, timestamp, source messages.
Entity Map — D3.js force-directed graph. Nodes = people + technologies + features. Edges = "knows about," "decided," "promised," "blocked by." Click node to see all related signals.
Pattern Timeline — Recharts line chart. X-axis = time (days/weeks). Y-axis = signal frequency by type. Highlights anomalies with red markers.
Cross-Group Panel — Split view showing 2-3 groups side by side with connecting lines showing detected blind spots. Each blind spot card shows: type, description, affected groups, severity, recommended action.
Tech: React + Tailwind + Recharts
npx create-react-app thirdeye-dashboard
cd thirdeye-dashboard
npm install recharts axios tailwindcss @headlessui/react
16. DATA MODELS & SCHEMAS
Signal Schema
class Signal:
id: str # UUID
group_id: str # Telegram group ID
lens: str # dev|product|client|community
type: str # architecture_decision, tech_debt, etc.
summary: str # One-sentence description
entities: list[str] # People, technologies, features mentioned
severity: str # low|medium|high|critical
status: str # proposed|decided|implemented|unresolved
sentiment: str # positive|neutral|negative|urgent
urgency: str # none|low|medium|high|critical
raw_quote: str # Original message excerpt
source_messages: list[int] # Telegram message IDs
timestamp: str # ISO 8601
keywords: list[str] # Searchable tags
embedding: list[float] # Vector embedding (stored in ChromaDB)
Pattern Schema
class Pattern:
id: str
group_id: str
type: str # frequency_spike|knowledge_silo|recurring_issue|sentiment_trend|stale_item
description: str
severity: str # info|warning|critical
evidence_signal_ids: list[str]
recommendation: str
detected_at: str
is_active: bool
CrossGroupInsight Schema
class CrossGroupInsight:
id: str
type: str # blocked_handoff|conflicting_decision|information_silo|promise_reality_gap|duplicated_effort
description: str
group_a: dict # {name, group_id, evidence}
group_b: dict # {name, group_id, evidence}
severity: str
recommendation: str
detected_at: str
is_resolved: bool
17. API ENDPOINTS (FASTAPI BACKEND)
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(title="ThirdEye API")
app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
# Group endpoints
GET /api/groups → List all monitored groups
GET /api/groups/{group_id}/signals → Get signals (with filters: type, severity, date range)
GET /api/groups/{group_id}/entities → Get entity map
GET /api/groups/{group_id}/patterns → Get detected patterns
GET /api/groups/{group_id}/alerts → Get active alerts
GET /api/groups/{group_id}/stats → Get group statistics
POST /api/groups/{group_id}/query → Natural language query → answer
# Cross-group endpoints
GET /api/cross-group/insights → Get all cross-group insights
GET /api/cross-group/promises → Get all tracked promises across groups
GET /api/cross-group/alignment → Get team alignment scores
GET /api/cross-group/risks → Get aggregated risk radar
# Config endpoints
GET /api/groups/{group_id}/lens → Get current lens mode
PUT /api/groups/{group_id}/lens → Set lens mode
18. 24-HOUR BUILD PLAN (HOUR BY HOUR)
Pre-Hackathon (Do Before the Clock Starts)
- Get ALL API keys (Groq, Cerebras, SambaNova, OpenRouter, Cohere, Telegram BotFather)
- Create Telegram bot via BotFather, disable privacy mode
- Set up GitHub repo with README
- Set up .env template with all API key placeholders
- Install base dependencies:
pip install python-telegram-bot openai chromadb fastapi uvicorn cohere fastmcp - Prepare demo data scripts (see Section 19)
Hour 0-2: Foundation (ALL TEAM MEMBERS)
Person 1 (Agent Lead):
- Implement provider_router.py (the multi-provider fallback system)
- Test all 5 providers are working with a simple call
- Implement Signal Extractor Agent with DevLens prompt
Person 2 (Bot + Backend Lead):
- Set up Telegram bot with message handler
- Implement message batching system
- Set up FastAPI skeleton with CORS
- Test bot receives messages in a test group
Person 3 (Frontend + Data Lead):
- Initialize React dashboard with Tailwind
- Set up ChromaDB with collection creation
- Implement Cohere embedding function with local fallback
- Create data models (Signal, Pattern, CrossGroupInsight)
Hour 2-6: Core Pipeline
Person 1:
- Implement Classifier Agent
- Implement Entity Resolver Agent
- Implement Knowledge Architect Agent
- Test full extraction pipeline: message → signals → classified → stored in ChromaDB
Person 2:
- Implement /ask command → Query Agent
- Implement /digest command
- Implement /alerts command
- Connect bot to agent pipeline (message → buffer → process_batch)
Person 3:
- Build Knowledge Stream component (signal feed)
- Build API endpoints for signals, entities, patterns
- Connect React dashboard to FastAPI backend
Hour 6-10: Intelligence Layer
Person 1:
- Implement Pattern Detector Agent
- Implement ProductLens and ClientLens signal extractor variants
- Implement Context Detector Agent (auto lens detection)
Person 2:
- Implement proactive alert system (bot sends unsolicited alerts)
- Implement /lens command
- Set up scheduled tasks (pattern detection every N batches)
Person 3:
- Build Pattern Timeline component (Recharts)
- Build Entity Map component (simple graph, D3 optional)
- Build Alerts panel
Hour 10-14: Cross-Group Intelligence ⭐
Person 1:
- Implement Cross-Group Analyst Agent
- Test with 2+ groups
- Refine cross-group prompts based on test results
Person 2:
- Implement /crossgroup command
- Set up cross-group alert routing
- Handle multi-group bot deployment
Person 3:
- Build Cross-Group Intelligence Panel (THE MAIN DEMO SCREEN)
- Build Promise Dashboard
- Build Risk Radar
Hour 14-18: Demo Data + Polish
ALL TEAM:
- Seed 3 demo groups with realistic messages (see Section 19)
- Run full pipeline on demo data
- Fix bugs, refine prompts based on actual output quality
- Ensure cross-group detection works on demo data
- Polish dashboard UI
Hour 18-22: Demo Preparation
Person 1:
- Write demo script (see Section 20)
- Practice the live demo flow
- Prepare fallback scenarios (what if an API is down?)
Person 2:
- Ensure all Telegram commands work smoothly
- Set up demo Telegram groups with appropriate names
- Record a backup video demo (in case live demo fails)
Person 3:
- Final UI polish
- Ensure dashboard loads fast and looks clean
- Prepare 2-3 impressive dashboard screenshots for slides
Hour 22-24: Final Prep
- Complete README.md with architecture diagram, setup instructions
- Prepare pitch slides (see Section 22)
- Do one full dry-run of the demo
- Push everything to GitHub
- Sleep for 30 minutes if possible
19. DEMO DATA SEEDING STRATEGY
Create 3 Telegram groups and seed each with 50-100 messages that tell a realistic story. The messages should contain PLANTED signals that ThirdEye will extract.
Group 1: Acme Dev Team
Seed messages that contain:
- Architecture decision: "Let's use PostgreSQL, MongoDB is overkill for our use case" (Day 1)
- Tech debt: "I'm hardcoding the API URL for now, we'll env-var it later" (Day 3)
- Knowledge silo: Only @raj discusses the payment module (Days 1-14)
- Recurring bug: "Timeout error again" mentioned 4 times across 2 weeks
- Deployment risk: "Pushing to main directly, it's a small fix" (Day 10)
- BLOCKED HANDOFF: "Still waiting for the design specs for the dashboard" (Days 8, 10, 12)
- BLOCKED: "The checkout flow is blocked by the payment gateway issue" (Day 11)
Group 2: Acme Product
Seed messages that contain:
- Feature requests: "Dark mode" mentioned 3 times by different people
- User pain point: "Sarah from ClientCo got stuck on onboarding step 3"
- Roadmap drift: 60% of discussion is about a feature not on the sprint board
- Priority conflict: @mike wants mobile-first, @sarah wants API stability
- CONFLICTING DECISION: "We're going API-first for this sprint" (contradicts dev team's assumption)
- NO MENTION of design specs being needed (dev team is waiting, product doesn't know)
Group 3: Acme ↔ ClientCo
Seed messages that contain:
- Promise: "We'll have the dashboard mockups ready by Friday" (Day 5)
- Promise: "API documentation will be shared by Wednesday" (Day 7)
- Scope creep: "Could you also add an export to PDF feature?" (Day 9, casual, no formal request)
- Sentiment shift: Client messages get shorter and more formal from Day 10 onward
- Escalation risk: "I might need to loop in our VP on the timeline" (Day 13)
- PROMISE-REALITY GAP: Dashboard mockups were promised by Friday, but dev team says blocked by design specs
Seeding Script
# seed_demo.py — Run BEFORE the demo
# Uses Telegram Bot API to send messages to demo groups programmatically
import asyncio
from telegram import Bot
bot = Bot(token=BOT_TOKEN)
DEMO_MESSAGES = {
"acme-dev": [
{"sender": "Alex", "text": "Hey team, I think we should go with PostgreSQL for the main DB. MongoDB is overkill for our relational data.", "day": 1},
{"sender": "Priya", "text": "Agreed on Postgres. I'll set up the schema today.", "day": 1},
{"sender": "Raj", "text": "Payment module is looking good, just need to wire up Stripe webhooks.", "day": 2},
{"sender": "Alex", "text": "I'm just gonna hardcode the API URL for now, we'll add env vars later when we dockerize.", "day": 3},
# ... 50+ more messages
{"sender": "Sam", "text": "Hey, are we ever getting those design specs for the dashboard? Been waiting since last week.", "day": 8},
{"sender": "Alex", "text": "Same. I can't start on the dashboard frontend without them.", "day": 10},
{"sender": "Sam", "text": "Still no design specs. This is blocking my entire sprint work.", "day": 12},
],
# ... similar for other groups
}
20. THE 90-SECOND DEMO SCRIPT
[0:00 - 0:15] THE HOOK
"Your team makes 50 decisions a day in group chat. How many can you remember from last week? Zero. Every team has a knowledge graveyard — and it's called their chat history."
[0:15 - 0:30] THE PRODUCT
"ThirdEye is a drop-in Telegram bot. Add it to any group — dev team, product squad, client channel. It silently listens and extracts intelligence." Show: Bot added to 3 Telegram groups. Messages flowing.
[0:30 - 0:45] THE QUERY
"Watch this. I'll ask: 'What architecture decisions did we make this week?'" Live demo: /ask What architecture decisions were made? → Structured answer with who, what, when, why. "It knows. Because it was listening."
[0:45 - 1:00] THE PATTERN
Switch to React dashboard "But it doesn't just remember — it sees patterns humans miss." Show: Pattern timeline — "Tech debt mentions up 300% this sprint" / "Knowledge silo: only @raj discusses payment module"
[1:00 - 1:20] THE MIC DROP — CROSS-GROUP INTELLIGENCE
"Now here's what no product on Earth does. We deployed ThirdEye in three groups." Switch to Cross-Group Panel "It detected: Your dev team has been waiting for design specs for 5 days. Your product team doesn't know. Your client was promised a dashboard by Friday. Nobody connected these dots — until now." Show the cross-group insight card with the three connected threads
[1:20 - 1:30] THE CLOSE
"ThirdEye turns your team's chat into a living brain that remembers everything, sees patterns humans miss, and catches problems before they become crises. All for free. All on Telegram."
21. JUDGING CRITERIA SELF-ASSESSMENT
| Criterion | Score | Evidence |
|---|---|---|
| Originality | 9/10 | No product does passive, multi-context, cross-group conversation intelligence. Category creation. |
| Innovation | 9/10 | Adaptive lens system, 8-agent pipeline, cross-group blind spot detection, multi-provider fallback. |
| Context | 9/10 | Slack AI ($17.50/user, reactive only). Prism (product signals only). Runbear (Q&A only). No competitor in our quadrant. |
| Feasibility | 8/10 | All free APIs. Proven models. Straightforward pipeline. 24-hour buildable. |
| Significance | 8/10 | Every team loses knowledge in chat. 900M+ Telegram users. Democratizes intelligence that only Slack AI offers to enterprises. |
| Viability | 8/10 | Clear freemium SaaS path. Free for 1 group, paid for cross-group + custom lenses + integrations. |
| TOTAL | 51/60 |
22. PITCH DECK OUTLINE
Slide 1: "Your team already has the answers. They're just trapped in chat." + ThirdEye logo
Slide 2: The Problem — Knowledge graveyard statistics. "50 decisions/day in chat. 0 remembered next week."
Slide 3: The Solution — What ThirdEye does in one visual. Bot → Groups → Intelligence.
Slide 4: Live Demo — (Do the live demo here. Refer to Section 20.)
Slide 5: How It Works — 8-agent architecture diagram. Emphasize: passive, adaptive, cross-group.
Slide 6: Why It's Different — Competitive quadrant (reactive/proactive × single/cross-group).
Slide 7: Tech Stack — Free models, multi-provider, zero cost. "10,000+ API calls/day for $0."
Slide 8: Impact — "Every team of 3+ people communicating in chat needs this."
Slide 9: What's Next — Slack/Discord integration, custom enterprise lenses, team health scoring.
23. RISK MITIGATION PLAYBOOK
| Risk | Probability | Mitigation |
|---|---|---|
| API provider goes down during demo | Medium | 5-provider fallback chain. openrouter/free auto-routes to ANY available model. |
| Signal extraction quality is poor | Medium | Extensive few-shot prompting. Cherry-pick demo messages designed to be extractable. |
| Cross-group detection doesn't fire | Low | Pre-seed messages with OBVIOUS planted signals. Test before demo. |
| Rate limits hit during live demo | Medium | Spread across 5 providers. Pre-warm knowledge graph before demo (not during). |
| ChromaDB issues | Low | Embedded mode, no external dependency. Pre-test with demo data. |
| Telegram bot doesn't receive messages | Low | MUST disable privacy mode in BotFather. Test this first. |
| Dashboard looks ugly | Low | Use Tailwind presets. Focus on data, not design. Clean > pretty. |
| Demo takes too long | Medium | Practice the 90-second script 3 times. Have hard cutoff points. |
Emergency Fallback Plan
If live demo fails completely:
- Show pre-recorded video backup
- Walk through dashboard screenshots
- Open the terminal and show CLI output of the agent pipeline running on test data
24. API KEYS CHECKLIST
# .env file — get ALL of these before the hackathon starts
# Telegram
TELEGRAM_BOT_TOKEN= # BotFather → /newbot → copy token
# LLM Providers (all free, no credit card)
GROQ_API_KEY= # console.groq.com → API Keys
CEREBRAS_API_KEY= # cloud.cerebras.ai → API Keys
SAMBANOVA_API_KEY= # cloud.sambanova.ai → API Keys
OPENROUTER_API_KEY= # openrouter.ai → Dashboard → API Keys
GEMINI_API_KEY= # aistudio.google.com → Get API Key (LAST RESORT)
# Embeddings
COHERE_API_KEY= # dashboard.cohere.com → API Keys
# Optional
CLOUDFLARE_ACCOUNT_ID= # dash.cloudflare.com → Workers & Pages
CLOUDFLARE_API_TOKEN= # dash.cloudflare.com → API Tokens
TAVILY_API_KEY= # tavily.com (if adding web search enrichment)
Time to get all keys: ~15 minutes. Total cost: $0.
25. TECH STACK SUMMARY (COPY-PASTE READY)
Backend: Python 3.11+ / FastAPI / Uvicorn
Bot: python-telegram-bot v21+
Agents: Custom pipeline (no framework needed — just async Python + OpenAI SDK)
LLM Access: openai Python SDK (works with ALL providers via base_url swap)
Vector DB: ChromaDB (embedded, persistent)
Embeddings: Cohere Embed v4 (free tier) + sentence-transformers fallback
Frontend: React 18 + Tailwind CSS + Recharts
Hosting: Render.com (free tier) or Railway.app
MCP: FastMCP (Python)
Install Commands
# Backend
pip install python-telegram-bot openai chromadb fastapi uvicorn cohere fastmcp sentence-transformers python-dotenv
# Frontend
npx create-react-app thirdeye-dashboard --template typescript
cd thirdeye-dashboard
npm install recharts axios @headlessui/react
npx tailwindcss init
26. REPO STRUCTURE
thirdeye/
├── README.md
├── .env.example
├── requirements.txt
├── docker-compose.yml (optional)
│
├── backend/
│ ├── main.py # FastAPI app entry point
│ ├── providers.py # Multi-provider router (Section 10)
│ ├── config.py # Environment variables, constants
│ │
│ ├── agents/
│ │ ├── context_detector.py # Auto-classifies group type
│ │ ├── signal_extractor.py # Extracts signals (with lens variants)
│ │ ├── classifier.py # Tags signals with metadata
│ │ ├── entity_resolver.py # Resolves entity references
│ │ ├── knowledge_architect.py # Manages ChromaDB knowledge graph
│ │ ├── pattern_detector.py # Detects temporal patterns
│ │ ├── cross_group_analyst.py # ⭐ Cross-group blind spot detection
│ │ └── query_agent.py # Handles user queries via RAG
│ │
│ ├── bot/
│ │ ├── bot.py # Telegram bot setup + handlers
│ │ ├── buffer.py # Message batching system
│ │ ├── commands.py # /ask, /digest, /alerts, /lens, /crossgroup
│ │ └── alerts.py # Proactive alert sending
│ │
│ ├── db/
│ │ ├── chroma.py # ChromaDB setup + collections
│ │ ├── embeddings.py # Cohere + fallback embedding
│ │ └── models.py # Data schemas (Signal, Pattern, etc.)
│ │
│ ├── mcp/
│ │ ├── knowledge_server.py # Knowledge graph MCP server
│ │ └── cross_group_server.py # Cross-group MCP server
│ │
│ └── api/
│ ├── routes.py # FastAPI routes
│ └── schemas.py # Pydantic models for API
│
├── dashboard/ # React frontend
│ ├── src/
│ │ ├── App.tsx
│ │ ├── components/
│ │ │ ├── KnowledgeStream.tsx
│ │ │ ├── EntityMap.tsx
│ │ │ ├── PatternTimeline.tsx
│ │ │ ├── AlertsPanel.tsx
│ │ │ ├── CrossGroupPanel.tsx # ⭐ THE MAIN DEMO SCREEN
│ │ │ ├── PromiseDashboard.tsx
│ │ │ └── RiskRadar.tsx
│ │ └── api/
│ │ └── client.ts # Axios API client
│ └── tailwind.config.js
│
├── scripts/
│ ├── seed_demo.py # Demo data seeding script
│ └── test_providers.py # Test all API providers are working
│
└── demo/
├── demo_messages/ # Pre-written demo messages per group
│ ├── acme_dev.json
│ ├── acme_product.json
│ └── acme_client.json
└── demo_script.md # The 90-second demo script
QUICK REFERENCE CARD (Print This)
╔══════════════════════════════════════════════════════════════╗
║ THIRDEYE QUICK REFERENCE ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ TAGLINE: "Your team already has the answers. ║
║ They're just trapped in chat." ║
║ ║
║ PROVIDERS (in order): ║
║ 1. Groq (fastest) 2. Cerebras 3. SambaNova (405B!) ║
║ 4. OpenRouter (27 free models) 5. Google (last resort) ║
║ ║
║ LENSES: DevLens | ProductLens | ClientLens | CommunityLens ║
║ ║
║ KILLER FEATURE: Cross-Group Intelligence ║
║ "Detects blind spots BETWEEN teams" ║
║ ║
║ 8 AGENTS: Context Detector → Signal Extractor → ║
║ Classifier → Entity Resolver → Knowledge Architect → ║
║ Pattern Detector → Cross-Group Analyst → Query Agent ║
║ ║
║ DEMO MOMENT: "Dev blocked 5 days. Design doesn't know. ║
║ Client expects Friday. Nobody connected the dots." ║
║ ║
║ TOTAL FREE CAPACITY: ~10,000-15,000 requests/day ║
║ ║
╚══════════════════════════════════════════════════════════════╝
Last updated: March 21, 2026. This is the single source of truth for ThirdEye. If it's not here, it doesn't matter.