merge

.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual Environment
+venv/
+env/
+ENV/
+
+# Environment variables
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

ARCHITECTURE.md

@@ -1,24 +1,62 @@
-## 2. `ARCHITECTURE.md`
-
-```markdown
-# Architecture Overview
-
-Below, sketch (ASCII, hand-drawn JPEG/PNG pasted in, or ASCII art) the high-level components of your agent.
-
-## Components
-
-1. **User Interface**  
-   - E.g., Streamlit, CLI, Slack bot  
-
-2. **Agent Core**  
-   - **Planner**: how you break down tasks  
-   - **Executor**: LLM prompt + tool-calling logic  
-   - **Memory**: vector store, cache, or on-disk logs  
-
-3. **Tools / APIs**  
-   - E.g., Google Gemini API, Tools, etc
-
-4. **Observability**  
-   - Logging of each reasoning step  
-   - Error handling / retries  
+# CIFR Agent System – Architecture
+
+Aligned with the official Agentic AI Hackathon template ([odsc2015/agentic-hackathon-template](https://github.com/odsc2015/agentic-hackathon-template)).
+
+## High-Level Overview
+- Goal: Reduce intercompany friction via multi-agent collaboration.
+- Gemini usage: `google.genai` for multimodal analysis, planning, and interventions.
+- Delivery targets: CLI + Flask demo; cloud-ready with GCP services.
+
+## Component Diagram (ASCII)
+```
+User Request (UI/CLI)
+    │
+    ▼
+Planner (Gemini plan)
+    │ plan
+    ▼
+Executor ──────────────────────────────────────────────┐
+    │ dispatch                                          │
+    ▼                                                   │
+CommunicationAgent ──► KnowledgeAgent (context store)   │
+           │                │                           │
+           ▼                │                           │
+  FrictionDetectionAgent ◄──┘                           │
+           │                                            │
+           ▼                                            │
+    InterventionAgent → Response / Guidance to user     │
+```
+
+## Modules
+- `src/planner.py`: Uses Gemini text to propose 3–6 JSON steps; heuristic fallback.
+- `src/executor.py`: Iterates plan, calls agents, records trace.
+- `src/memory.py`: Lightweight in-memory event log for demo traces.
+- `cifr_agent_system/communication_agent.py`: Multimodal analysis (Gemini Vision/Text + Language API fallback).
+- `cifr_agent_system/friction_detection_agent.py`: Misalignment detection (Gemini + heuristic keywords).
+- `cifr_agent_system/intervention_agent.py`: Generates clarifications/action-items/mediation suggestions.
+- `cifr_agent_system/knowledge_agent.py`: In-memory knowledge base (store/retrieve/search).
+- `cifr_agent_system/config.py`: Env loading, optional insecure SSL for sandboxes, model IDs.
+
+## Data Flow
+1) User goal → Planner → structured steps.
+2) Executor loops steps:
+   - `analyze_messages`: CommunicationAgent performs multimodal analysis; stores context.
+   - `detect_friction`: FrictionDetectionAgent reasons over stored context.
+   - `generate_interventions`: InterventionAgent drafts guidance based on friction.
+3) KnowledgeAgent stores analyses + interventions.
+4) Executor returns results + trace to UI/CLI.
+
+## Environment & Secrets
+- `.env` (gitignored): `GCP_PROJECT_ID`, `GCP_LOCATION`, `GOOGLE_API_KEY` (or per-agent keys), `GEMINI_PRO_MODEL_ID`, `GEMINI_PRO_VISION_MODEL_ID`.
+- `key.json` should not be committed; rotate/remove if ever added.
+- `ALLOW_INSECURE_SSL=1` only for sandbox environments.
+
+## Observability (current)
+- Structured logging via `logging`; memory trace for demo.
+- Flask API prints warnings for quota/heuristic fallbacks.
+
+## Extension Ideas
+- Persist memory to Firestore/Spanner and add retrieval to planner prompts.
+- Add tool router for calendars/search and external actions.
+- Integrate OpenTelemetry tracing; promote heuristics to typed fallbacks with scores.
 

DEMO.md

@@ -1,23 +1,21 @@
-# Demo Video
+# CIFR Agent System – Demo
 
-Please record a 3–5 minute walkthrough showing:
+Provide a public 3–5 minute video link here (YouTube unlisted, Drive public, Loom, etc.). Submissions without a valid link will not be reviewed.
 
-- The problem you solve  
-- End-to-end agent behavior on a representative example  
-- Highlighted “agentic” steps (planning, tool calls, memory use)
+## Video Link
+- TODO: Paste final link here after recording.
 
----
+## Timestamped Highlights
+- 00:00–00:30 Intro & setup
+- 00:30–01:30 User input → Planning (Planner + Executor)
+- 01:30–02:30 Tool calls & memory (CommunicationAgent, KnowledgeAgent, FrictionDetectionAgent)
+- 02:30–03:30 Final output & edge cases (InterventionAgent + fallback flows)
 
-📺 **Provide a Hosted Public Video Link (YouTube unlisted / Loom / MP4):**  MUST BE ON A HOS
-https://your.video.link.here
+## How to Reproduce
+1) `python -m venv .venv && source .venv/bin/activate`
+2) `pip install -r cifr_agent_system/requirements.txt`
+3) Create `.env` with `GCP_PROJECT_ID`, `GOOGLE_API_KEY`, optional `GEMINI_PRO_MODEL_ID`, `GEMINI_PRO_VISION_MODEL_ID`.
+4) Run `python -m cifr_agent_system.main` for the CLI demo.
+5) (Optional) Run web dashboard via option 2 in the menu.
 
-PLEASE DO NOT UPLOAD RAW VIDOE FILES. These submissions will not be reviewed.
 
-### Timestamps
-
-- **00:00–00:30** — Introduction & setup  
-- **00:30–01:30** — User input → Planning step  
-- **01:30–02:30** — Tool calls & memory retrieval  
-- **02:30–03:30** — Final output & edge-case handling
-
-- Vidoes longer than 5 minutes may not be reviewd. 

DEMO_GUIDE.md

@@ -0,0 +1,206 @@
+# 🚀 CIFR Agent System - Demo Guide
+
+## Overview
+The **CIFR (Collaborative Intelligence & Friction Reduction) Agent System** is an intelligent orchestration platform that coordinates multiple specialized AI agents to monitor, analyze, and improve team collaboration. The system processes collaboration messages through a sophisticated pipeline where each agent plays a critical role in understanding context, detecting issues, and providing actionable insights.
+
+## 🎯 CIFR Orchestration System
+
+The CIFR system orchestrates four specialized AI agents in a coordinated workflow:
+
+**Pipeline Flow:**
+```
+Input → Communication Agent → Knowledge Agent → Friction Detection Agent → Intervention Agent → Output
+```
+
+### How Orchestration Works:
+1. **Input Processing:** Messages (text + optional images) enter the system
+2. **Communication Analysis:** Communication Agent analyzes content using Gemini AI
+3. **Context Storage:** Knowledge Agent stores analysis for future reference
+4. **Friction Detection:** Friction Detection Agent identifies issues and patterns
+5. **Intervention Generation:** Intervention Agent provides actionable solutions
+6. **Output Delivery:** Comprehensive analysis and recommendations returned
+
+## 🤖 The Four AI Agents
+
+### 1. 💬 Communication Agent
+**Role:** Primary message analyzer using Gemini AI
+- Extracts sentiment scores and emotional tone
+- Identifies key entities (people, projects, deadlines, etc.)
+- Performs multimodal analysis (text + images)
+- Provides deep context understanding
+
+**Technology:** Google Gemini AI (gemini-2.0-flash, gemini-2.5-flash)
+
+### 2. 📚 Knowledge Agent
+**Role:** Central memory hub and context manager
+- Stores all communication analyses in knowledge base
+- Enables pattern recognition across conversations
+- Maintains historical context for better understanding
+- Supports cross-message analysis and trend detection
+
+**Key Feature:** Acts as the "memory" that allows agents to understand patterns over time
+
+### 3. ⚠️ Friction Detection Agent
+**Role:** Conflict and misalignment identifier
+- Detects friction points using AI reasoning
+- Assesses severity levels (0.0 to 1.0)
+- Identifies escalation patterns
+- Recognizes recurring issues
+
+**Technology:** Google Gemini AI for intelligent reasoning
+
+### 4. 💡 Intervention Agent
+**Role:** Solution provider and action generator
+- Generates context-aware intervention suggestions
+- Proposes clarification messages
+- Creates actionable action items
+- Suggests mediation strategies
+
+**Technology:** Google Gemini AI for intelligent recommendation generation
+
+## 🎯 Demo Examples
+
+### 1. 😤 Frustrated Delay Scenario
+**Message:** "I am really frustrated with the constant delays on this feature. We've been waiting for 3 weeks now and the deadline is approaching fast. This is becoming a serious issue for our team and we need to accelerate immediately!"
+
+**What to Look For:**
+- **Communication Agent:** Negative sentiment score (around -0.6), detects keywords like "frustrated", "delays", "issue"
+- **Knowledge Agent:** Stores analysis in knowledge base for future pattern recognition
+- **Friction Detection:** Should detect friction with high severity (0.6-0.8)
+- **Intervention:** Suggests clarification or immediate action items
+
+**Demo Value:** Shows how the system identifies emotional friction and urgency, with Knowledge Agent maintaining context for future analysis.
+
+---
+
+### 2. ⏰ Timeline Slippage Issue
+**Message:** "The project timeline is slipping again. We were supposed to deliver Phase 2 by Friday, but now it looks like it will be delayed by at least another week. This is the third time we've had to push back deadlines. We need to have a serious discussion about resource allocation and priorities."
+
+**What to Look For:**
+- **Communication Agent:** Negative sentiment, entities like "timeline", "deadline", "delays"
+- **Knowledge Agent:** Stores recurring pattern data for trend analysis
+- **Friction Detection:** Detects recurring issues and escalation patterns
+- **Intervention:** Proposes action items for resource review and priority alignment
+
+**Demo Value:** Demonstrates pattern recognition and escalation detection, with Knowledge Agent tracking recurring issues.
+
+---
+
+### 3. ✅ Positive Resolution
+**Message:** "Great work on the latest sprint! The team really pulled together and we delivered everything on time. The new features are working perfectly and the client is very happy with the progress. Let's keep this momentum going!"
+
+**What to Look For:**
+- **Communication Agent:** Positive sentiment score (around 0.7), positive keywords
+- **Knowledge Agent:** Stores positive interaction for team health tracking
+- **Friction Detection:** No friction detected
+- **Intervention:** No intervention needed (confirms positive state)
+
+**Demo Value:** Shows the system correctly identifies positive communication and avoids false positives, with Knowledge Agent maintaining positive interaction history.
+
+---
+
+### 4. ⚔️ Team Conflict
+**Message:** "I completely disagree with the approach we're taking. The current design doesn't align with our original requirements and I think we're going in the wrong direction. We need to stop and reconsider before we waste more time and resources on this."
+
+**What to Look For:**
+- **Communication Agent:** Negative sentiment, conflict indicators like "disagree", "wrong direction"
+- **Knowledge Agent:** Stores conflict context for future reference and pattern tracking
+- **Friction Detection:** High severity conflict detection
+- **Intervention:** Suggests mediation or joint discussion to resolve differences
+
+**Demo Value:** Highlights conflict detection and mediation intervention capabilities, with Knowledge Agent maintaining conflict history.
+
+---
+
+### 5. 📊 Data Analysis Request
+**Message:** "This graph shows a significant drop in user engagement over the past month. We went from 85% active users to just 62%. The data suggests there might be an issue with the latest update. Can someone analyze this chart and help us understand what's happening?"
+
+**What to Look For:**
+- **Communication Agent:** Multimodal analysis (if image uploaded), detects data-related entities
+- **Knowledge Agent:** Stores data analysis context for trend tracking
+- **Friction Detection:** Moderate concern detection
+- **Intervention:** Suggests investigation or data review action items
+
+**Demo Value:** Demonstrates multimodal capabilities and data-driven friction detection, with Knowledge Agent maintaining data analysis history.
+
+---
+
+## 🎨 Features Showcased
+
+### 1. **CIFR Orchestration System**
+- **Coordinated Workflow:** Four specialized agents working in harmony
+- **Pipeline Processing:** Sequential analysis from input to actionable output
+- **Context Preservation:** Knowledge Agent maintains conversation history
+- **Intelligent Routing:** Each agent processes and passes context to the next
+
+### 2. **Four AI Agents Working in Tandem**
+- **Communication Agent:** Uses Gemini AI to analyze sentiment, extract entities, and understand context
+- **Knowledge Agent:** Central memory hub storing and retrieving context for pattern recognition
+- **Friction Detection Agent:** Identifies misalignments, conflicts, and friction points
+- **Intervention Agent:** Provides actionable, intelligent suggestions
+
+### 3. **Gemini AI Integration**
+- Real-time AI analysis of text content
+- Multimodal support for images/charts
+- Natural language understanding
+- Context-aware responses
+- Per-agent API key configuration for scalability
+
+### 4. **Knowledge Base & Context Management**
+- Persistent storage of all communications
+- Pattern recognition across conversations
+- Historical context for better understanding
+- Trend detection and escalation tracking
+
+### 5. **Intelligent Friction Detection**
+- Sentiment analysis
+- Pattern recognition
+- Severity assessment
+- Contextual understanding
+- Recurring issue identification
+
+### 6. **Actionable Interventions**
+- Clarification suggestions
+- Action item proposals
+- Mediation strategies
+- Context-specific recommendations
+
+## 📝 How to Use the Demo
+
+1. **Visit:** http://127.0.0.1:9000
+2. **Click Demo Buttons:** Use the pre-built examples to see different scenarios
+3. **Or Enter Custom Message:** Type your own collaboration message
+4. **Upload Images (Optional):** Add charts, graphs, or diagrams for multimodal analysis
+5. **View Results:** See all three agents' analysis in real-time
+
+## 🎯 Best Practices for Demo
+
+1. **Start with "Frustrated Delay"** - Most dramatic example showing full pipeline
+2. **Show "Positive Resolution"** - Demonstrates accuracy (no false positives)
+3. **Try "Team Conflict"** - Highlights mediation capabilities
+4. **Use Custom Messages** - Show real-time analysis of audience input
+5. **Upload Images** - Demonstrate multimodal capabilities if time permits
+
+## 🔍 What Makes This Demo Compelling
+
+- **Real-World Scenarios:** Examples based on actual collaboration challenges
+- **AI-Powered Intelligence:** Shows advanced Gemini AI capabilities
+- **Complete Pipeline:** Demonstrates end-to-end agent workflow
+- **Actionable Insights:** Provides real value, not just analysis
+- **Professional UI:** Modern, intuitive interface
+
+## 💡 Key Talking Points
+
+1. **CIFR Orchestration System:** Intelligent coordination of four specialized agents in a seamless pipeline
+2. **Multi-Agent Architecture:** Four specialized AI agents (Communication, Knowledge, Friction Detection, Intervention) working together
+3. **Knowledge Base Intelligence:** Central memory hub enabling pattern recognition and historical context
+4. **Gemini AI Integration:** State-of-the-art language understanding with per-agent API key configuration
+5. **Proactive Intervention:** Not just detection, but actionable solutions tailored to context
+6. **Multimodal Analysis:** Handles text, images, and data visualizations
+7. **Real-Time Processing:** Fast, responsive analysis through coordinated agent workflow
+8. **Context-Aware:** Knowledge Agent maintains conversation history for better understanding over time
+
+---
+
+**Ready to demo?** Visit http://127.0.0.1:9000 and click any demo button to get started! 🚀
+