mirror of
https://github.com/arkorty/B.Tech-Project-III.git
synced 2026-04-19 12:41:48 +00:00
1522 lines
62 KiB
Markdown
1522 lines
62 KiB
Markdown
# 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
|
||
|
||
1. [Project Identity](#1-project-identity)
|
||
2. [The Problem We Solve](#2-the-problem-we-solve)
|
||
3. [What ThirdEye Does](#3-what-thirdeye-does)
|
||
4. [Competitive Landscape & Why We Win](#4-competitive-landscape--why-we-win)
|
||
5. [The Adaptive Lens System](#5-the-adaptive-lens-system)
|
||
6. [Cross-Group Intelligence (The Wow Feature)](#6-cross-group-intelligence-the-wow-feature)
|
||
7. [Agent Architecture (8 Agents)](#7-agent-architecture-8-agents)
|
||
8. [Free Model Provider Stack](#8-free-model-provider-stack)
|
||
9. [Agent → Model Mapping](#9-agent--model-mapping)
|
||
10. [Provider Router Code](#10-provider-router-code)
|
||
11. [System Prompts for Each Agent](#11-system-prompts-for-each-agent)
|
||
12. [RAG & Embedding Strategy](#12-rag--embedding-strategy)
|
||
13. [MCP Servers](#13-mcp-servers)
|
||
14. [Telegram Bot Implementation](#14-telegram-bot-implementation)
|
||
15. [React Dashboard Design](#15-react-dashboard-design)
|
||
16. [Data Models & Schemas](#16-data-models--schemas)
|
||
17. [API Endpoints (FastAPI Backend)](#17-api-endpoints-fastapi-backend)
|
||
18. [24-Hour Build Plan (Hour by Hour)](#18-24-hour-build-plan-hour-by-hour)
|
||
19. [Demo Data Seeding Strategy](#19-demo-data-seeding-strategy)
|
||
20. [The 90-Second Demo Script](#20-the-90-second-demo-script)
|
||
21. [Judging Criteria Self-Assessment](#21-judging-criteria-self-assessment)
|
||
22. [Pitch Deck Outline](#22-pitch-deck-outline)
|
||
23. [Risk Mitigation Playbook](#23-risk-mitigation-playbook)
|
||
24. [API Keys Checklist](#24-api-keys-checklist)
|
||
25. [Tech Stack Summary (Copy-Paste Ready)](#25-tech-stack-summary-copy-paste-ready)
|
||
26. [Repo Structure](#26-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
|
||
|
||
1. **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.
|
||
|
||
2. **Adaptive Context Detection** — Auto-detects whether a group is a dev team, product team, client channel, or community, and activates the right extraction ontology.
|
||
|
||
3. **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.
|
||
|
||
4. **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..."
|
||
|
||
5. **Pattern Detection** — Identifies trends and anomalies: "Tech debt mentions up 300% this sprint." "Only @raj discusses the payment module — bus factor = 1."
|
||
|
||
6. **Proactive Alerts** — Sends Telegram alerts for concerning patterns without being asked: overdue promises, sentiment shifts, knowledge silos, recurring bugs.
|
||
|
||
7. **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):
|
||
|
||
```python
|
||
# 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
|
||
|
||
```python
|
||
# 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
|
||
|
||
```python
|
||
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:
|
||
|
||
```python
|
||
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):
|
||
|
||
```bash
|
||
pip install fastmcp
|
||
```
|
||
|
||
### knowledge-graph MCP Server
|
||
|
||
```python
|
||
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
|
||
|
||
```python
|
||
@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
|
||
|
||
```python
|
||
# 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
|
||
|
||
```python
|
||
# 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
|
||
|
||
```bash
|
||
npx create-react-app thirdeye-dashboard
|
||
cd thirdeye-dashboard
|
||
npm install recharts axios tailwindcss @headlessui/react
|
||
```
|
||
|
||
---
|
||
|
||
## 16. DATA MODELS & SCHEMAS
|
||
|
||
### Signal Schema
|
||
|
||
```python
|
||
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
|
||
|
||
```python
|
||
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
|
||
|
||
```python
|
||
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)
|
||
|
||
```python
|
||
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
|
||
|
||
```python
|
||
# 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:
|
||
1. Show pre-recorded video backup
|
||
2. Walk through dashboard screenshots
|
||
3. Open the terminal and show CLI output of the agent pipeline running on test data
|
||
|
||
---
|
||
|
||
## 24. API KEYS CHECKLIST
|
||
|
||
```bash
|
||
# .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
|
||
|
||
```bash
|
||
# 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.* |