51 | {children}
52 |
53 |
97 |
164 | )
165 | }
--------------------------------------------------------------------------------
/backend/src/chatbot/auth.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python
2 | """
3 | Token-based authentication for FastAPI backend
4 | Secure authentication using JWT tokens and environment variables
5 | """
6 |
7 | import os
8 | from datetime import datetime, timedelta
9 | from typing import Optional, Dict, Any
10 | from fastapi import HTTPException, status, Depends
11 | from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
12 | from jose import JWTError, jwt
13 | from passlib.context import CryptContext
14 | from pydantic import BaseModel
15 | from decouple import config
16 |
17 | # Configuration from environment variables
18 | SECRET_KEY = config("SECRET_KEY", default="your-secret-key-change-this-in-production")
19 | ALGORITHM = config("ALGORITHM", default="HS256")
20 | ACCESS_TOKEN_EXPIRE_MINUTES = config("ACCESS_TOKEN_EXPIRE_MINUTES", default="", cast=str)
21 | ACCESS_TOKEN_EXPIRE_MINUTES = int(ACCESS_TOKEN_EXPIRE_MINUTES) if ACCESS_TOKEN_EXPIRE_MINUTES else None
22 |
23 | # Password hashing
24 | pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
25 |
26 | # OAuth2 scheme
27 | oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
28 |
29 | # Pydantic models
30 | class Token(BaseModel):
31 | access_token: str
32 | token_type: str
33 |
34 | class TokenData(BaseModel):
35 | username: Optional[str] = None
36 |
37 | class User(BaseModel):
38 | username: str
39 | email: Optional[str] = None
40 | full_name: Optional[str] = None
41 | disabled: Optional[bool] = None
42 |
43 | class UserInDB(User):
44 | hashed_password: str
45 |
46 | # In-memory user database (replace with real database in production)
47 | # WARNING: Change these passwords in production!
48 | # For production, use environment variables for user credentials
49 | def get_users_from_env():
50 | """Get users from environment variables for production security"""
51 | users = {}
52 |
53 | # Admin user from environment
54 | admin_username = config("ADMIN_USERNAME", default="admin")
55 | admin_password_hash = config("ADMIN_PASSWORD_HASH", default=None)
56 | admin_email = config("ADMIN_EMAIL", default="admin@example.com")
57 | admin_full_name = config("ADMIN_FULL_NAME", default="Administrator")
58 |
59 | if admin_password_hash:
60 | users[admin_username] = {
61 | "username": admin_username,
62 | "email": admin_email,
63 | "full_name": admin_full_name,
64 | "hashed_password": admin_password_hash,
65 | "disabled": False,
66 | }
67 |
68 | # Regular user from environment
69 | user_username = config("USER_USERNAME", default="user")
70 | user_password_hash = config("USER_PASSWORD_HASH", default=None)
71 | user_email = config("USER_EMAIL", default="user@example.com")
72 | user_full_name = config("USER_FULL_NAME", default="Regular User")
73 |
74 | if user_password_hash:
75 | users[user_username] = {
76 | "username": user_username,
77 | "email": user_email,
78 | "full_name": user_full_name,
79 | "hashed_password": user_password_hash,
80 | "disabled": False,
81 | }
82 |
83 | # Fallback to default users if no environment variables set
84 | if not users:
85 | users = {
86 | "admin": {
87 | "username": "admin",
88 | "email": "admin@example.com",
89 | "full_name": "Administrator",
90 | "hashed_password": "$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW", # password: secret
91 | "disabled": False,
92 | },
93 | "user": {
94 | "username": "user",
95 | "email": "user@example.com",
96 | "full_name": "Regular User",
97 | "hashed_password": "$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW", # password: secret
98 | "disabled": False,
99 | }
100 | }
101 |
102 | return users
103 |
104 | # Get users from environment or fallback to defaults
105 | fake_users_db = get_users_from_env()
106 |
107 | def verify_password(plain_password: str, hashed_password: str) -> bool:
108 | """Verify a password against its hash"""
109 | # bcrypt passwords cannot be longer than 72 bytes
110 | return pwd_context.verify(plain_password[:72], hashed_password)
111 |
112 | def get_password_hash(password: str) -> str:
113 | """Hash a password"""
114 | # bcrypt passwords cannot be longer than 72 bytes
115 | return pwd_context.hash(password[:72])
116 |
117 | def get_user(db: dict, username: str) -> Optional[UserInDB]:
118 | """Get user from database"""
119 | if username in db:
120 | user_dict = db[username]
121 | return UserInDB(**user_dict)
122 | return None
123 |
124 | def authenticate_user(fake_db: dict, username: str, password: str) -> Optional[UserInDB]:
125 | """Authenticate user with username and password"""
126 | user = get_user(fake_db, username)
127 | if not user:
128 | return None
129 | if not verify_password(password, user.hashed_password):
130 | return None
131 | return user
132 |
133 | def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
134 | """Create JWT access token - no expiration if expires_delta is None"""
135 | to_encode = data.copy()
136 | if expires_delta is not None:
137 | expire = datetime.utcnow() + expires_delta
138 | to_encode.update({"exp": expire})
139 | # If expires_delta is None, don't add exp claim = token never expires
140 | encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
141 | return encoded_jwt
142 |
143 | async def get_current_user(token: str = Depends(oauth2_scheme)) -> User:
144 | """Get current authenticated user from token"""
145 | credentials_exception = HTTPException(
146 | status_code=status.HTTP_401_UNAUTHORIZED,
147 | detail="Could not validate credentials",
148 | headers={"WWW-Authenticate": "Bearer"},
149 | )
150 | try:
151 | payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
152 | username: str = payload.get("sub")
153 | if username is None:
154 | raise credentials_exception
155 | token_data = TokenData(username=username)
156 | except JWTError:
157 | raise credentials_exception
158 |
159 | user = get_user(fake_users_db, username=token_data.username)
160 | if user is None:
161 | raise credentials_exception
162 | return user
163 |
164 | async def get_current_active_user(current_user: User = Depends(get_current_user)) -> User:
165 | """Get current active user (not disabled)"""
166 | if current_user.disabled:
167 | raise HTTPException(status_code=400, detail="Inactive user")
168 | return current_user
169 |
170 | def generate_password_hash(password: str) -> str:
171 | """Generate password hash for new users"""
172 | return get_password_hash(password)
173 |
174 | # Utility function to create a new user (for admin purposes)
175 | def create_user(username: str, password: str, email: str = None, full_name: str = None) -> Dict[str, Any]:
176 | """Create a new user in the fake database"""
177 | hashed_password = get_password_hash(password)
178 | user_data = {
179 | "username": username,
180 | "email": email,
181 | "full_name": full_name,
182 | "hashed_password": hashed_password,
183 | "disabled": False,
184 | }
185 | fake_users_db[username] = user_data
186 | return user_data
187 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # AG-UI CrewAI Real-Time Research Assistant
2 |
3 | A Perplexity-like AI research assistant built with **CrewAI**, **AG-UI Protocol**, and **Next.js**. Features real-time event streaming, web search capabilities, and a modern chat interface with source citations and images.
4 |
5 | ## Key Features
6 |
7 | - **Real-time Research**: Web search with EXA AI and SerperDev integration
8 | - **Live Event Streaming**: AG-UI protocol for real-time agent updates
9 | - **Source Citations**: Perplexity-style source cards with images
10 | - **Intent Detection**: Smart classification between search/chat/exit
11 | - **Modern UI**: Clean Next.js frontend with Tailwind CSS
12 | - **JWT Authentication**: Secure token-based authentication system
13 | - **Open Frontend**: No user login required - automatic token management
14 |
15 | ## Tech Stack
16 |
17 | - **Agentic framework**: CrewAI
18 | - **Protocol**: AG-UI for intelligent backend <-> frontend connection
19 | - **Real-time web search**: EXA AI + SerperDev
20 | - **LLM**: OpenRouter (via LiteLLM) - supports multiple models
21 | - **Authentication**: JWT tokens with bcrypt password hashing
22 | - **Frontend**: Next.js with automatic token management
23 | - **Backend**: FastAPI with protected endpoints
24 |
25 | ## Required API Keys
26 |
27 | You'll need to obtain these API keys:
28 |
29 | 1. **OpenRouter API Key** - For LLM responses (supports multiple models)
30 | - Sign up at [OpenRouter](https://openrouter.ai/)
31 | - Get your API key from the dashboard
32 |
33 | 2. **EXA AI API Key** - For advanced web search
34 | - Go to [EXA AI](https://exa.ai/)
35 | - Create a new API key
36 |
37 | 3. **SerperDev API Key** - For Google search functionality
38 | - Sign up at [serper.dev](https://serper.dev)
39 | - Get your API key from the dashboard
40 |
41 |
42 | ## Local Development Setup
43 |
44 | ### 1. Clone the Repository
45 | ```bash
46 | git clone https://github.com/Folken2/ag-ui-crewai-research.git
47 | cd ag-ui-crewai-research
48 | ```
49 |
50 | ### 2. Backend Setup
51 |
52 | ```bash
53 | # Navigate to backend directory
54 | cd backend
55 |
56 | # Create and activate virtual environment
57 | python -m venv venv
58 |
59 | # On Windows:
60 | venv\Scripts\activate
61 | # On macOS/Linux:
62 | source venv/bin/activate
63 |
64 | # Install dependencies
65 | pip install -r requirements.txt
66 | ```
67 |
68 | ### 3. Environment Configuration
69 |
70 | Create environment files for both backend and frontend:
71 |
72 | **Backend Environment** (`backend/.env`):
73 | ```bash
74 | # Copy the example file
75 | cp example.env .env
76 |
77 | # Edit .env with your API keys
78 | OPENROUTER_API_KEY=your-openrouter-api-key-here
79 | OPENROUTER_MODEL=google/gemini-2.5-flash
80 | EXA_API_KEY=your-exa-api-key-here
81 | SERPER_API_KEY=your-serper-api-key-here
82 |
83 | # Authentication (optional - uses defaults if not set)
84 | SECRET_KEY=your-secret-key-for-jwt
85 | ADMIN_USERNAME=admin
86 | ADMIN_PASSWORD_HASH=your-admin-password
87 | ```
88 |
89 | **Frontend Environment** (`frontend/.env.local`):
90 | ```bash
91 | # Copy the example file
92 | cp example.env.local .env.local
93 |
94 | # Edit .env.local with your backend URL
95 | NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
96 | ```
97 |
98 | ### 4. Frontend Setup
99 |
100 | ```bash
101 | # Navigate to frontend directory (from project root)
102 | cd frontend
103 |
104 | # Install dependencies
105 | npm install
106 | ```
107 |
108 | ## Running the Application
109 |
110 | ### Start the Backend Server
111 | ```bash
112 | # From backend directory (with venv activated)
113 | cd backend
114 | source venv/bin/activate # On Windows: venv\Scripts\activate
115 | python run_server.py
116 | ```
117 |
118 | The backend will start on `http://localhost:8000`
119 |
120 | **Note**: The backend includes JWT authentication. The frontend will automatically get tokens using default credentials (`admin`/`secret`).
121 |
122 | ### Start the Frontend (in a new terminal)
123 | ```bash
124 | # From frontend directory
125 | cd frontend
126 | npm run dev
127 | ```
128 |
129 | The frontend will start on `http://localhost:3000`
130 |
131 | ### Access the Application
132 | Open your browser and go to `http://localhost:3000`
133 |
134 | ## How It Works
135 |
136 | ### Authentication Flow
137 | 1. **Frontend starts** → Automatically requests JWT token from backend
138 | 2. **Backend validates** → Returns permanent token (no expiration)
139 | 3. **All requests** → Include `Authorization: Bearer
98 | 🔄 Execution Status
99 |
100 |
101 |
102 |
163 |
103 | {visibleEvents.map((event, index) => (
104 |
162 |
109 | {/* Loading spinner for STARTED events */}
110 | {event.type.includes("STARTED") && (
111 |
149 | ))}
150 |
151 | {isProcessing && (
152 |
112 |
113 |
114 | )}
115 |
116 |
117 |
140 |
141 |
118 | {formatEventMessage(event)}
119 |
120 |
121 | {/* Additional details for certain events */}
122 | {event.data.agent_role && (
123 |
124 | Agent: {event.data.agent_role}
125 |
126 | )}
127 |
128 | {event.data.tool_name && !event.data.query && (
129 |
130 | Tool: {event.data.tool_name}
131 |
132 | )}
133 |
134 | {event.data.model && (
135 |
136 | Model: {event.data.model}
137 |
138 | )}
139 |
142 | {new Date(event.timestamp).toLocaleTimeString([], {
143 | hour: '2-digit',
144 | minute: '2-digit',
145 | second: '2-digit'
146 | })}
147 |
148 |
153 |
160 | )}
161 |
154 |
155 |
156 |
157 |
158 | Processing...
159 |
60 | {/* Header */}
61 |
201 | )
202 | }
--------------------------------------------------------------------------------
/backend/src/chatbot/utils/chat_helpers.py:
--------------------------------------------------------------------------------
1 | from typing import List, Dict, Any, Tuple
2 | from litellm import completion
3 | from decouple import config
4 | import os
5 |
6 | from .prompts import UNIFIED_PROMPT, inject_current_time
7 |
8 | # OpenRouter configuration
9 | OPENROUTER_API_KEY = config("OPENROUTER_API_KEY", default="")
10 | OPENROUTER_MODEL = config("OPENROUTER_MODEL", default="openai/gpt-4o-mini")
11 | OPENROUTER_BASE_URL = config("OPENROUTER_BASE_URL", default="https://openrouter.ai/api/v1")
12 |
13 | # Set OpenRouter API key for LiteLLM
14 | if OPENROUTER_API_KEY:
15 | os.environ["OPENROUTER_API_KEY"] = OPENROUTER_API_KEY
16 |
17 |
18 | def detect_intent(text: str, history: List[Dict[str, str]] = None) -> Tuple[str, str]:
19 | """Return (intent, expanded_query) using the unified prompt with conversation context."""
20 | try:
21 | # Build conversation context
22 | context_messages = []
23 |
24 | # Add conversation history for context
25 | if history:
26 | context_messages.append("Recent conversation history:")
27 | for turn in history:
28 | context_messages.append(f"User: {turn['input']}")
29 | context_messages.append(f"Assistant: {turn['response']}")
30 | else:
31 | context_messages.append("This is the start of the conversation.")
32 |
33 | context = "\n".join(context_messages)
34 |
35 | # Debug logging
36 | print(f"🔍 Intent Detection Debug:")
37 | print(f"Current text: '{text}'")
38 | print(f"History length: {len(history) if history else 0}")
39 | print(f"Context: {context[:200]}...")
40 |
41 | resp = completion(
42 | model=f"openrouter/{OPENROUTER_MODEL}",
43 | messages=[
44 | {"role": "system", "content": inject_current_time(UNIFIED_PROMPT)},
45 | {"role": "user", "content": f"{context}\n\nUser's current message: {text}"},
46 | ],
47 | temperature=0.5,
48 | )
49 | content = resp.choices[0].message.content.strip()
50 |
51 | print(f"LLM Response: '{content}'")
52 |
53 | # Extract intent and expanded query from the response format
54 | intent = "CHAT" # default
55 | expanded_query = text # default to original text
56 |
57 | if "INTENT:" in content:
58 | intent_line = [line for line in content.split('\n') if line.strip().startswith('INTENT:')]
59 | if intent_line:
60 | intent = intent_line[0].replace('INTENT:', '').strip()
61 |
62 | if "EXPANDED_QUERY:" in content:
63 | query_line = [line for line in content.split('\n') if line.strip().startswith('EXPANDED_QUERY:')]
64 | if query_line:
65 | expanded_query = query_line[0].replace('EXPANDED_QUERY:', '').strip()
66 |
67 | if intent in ['SEARCH', 'CHAT', 'EXIT']:
68 | print(f"✅ Detected Intent: {intent}")
69 | print(f"✅ Expanded Query: '{expanded_query}'")
70 | return intent, expanded_query
71 |
72 | # Simple fallback: let the LLM's response guide us
73 | # If the LLM didn't follow the format, default to CHAT
74 | print(f"❌ No valid intent found, defaulting to CHAT")
75 | return "CHAT", text
76 | except Exception as e:
77 | print(f"❌ Error in detect_intent: {e}")
78 | return "CHAT", text
79 |
80 |
81 | def synthesise_research(
82 | current_input: str, research: Dict[str, Any], temperature: float = 0.7
83 | ) -> str:
84 | """Synthesize research results with LLM knowledge using the unified prompt."""
85 | # Build research context with better formatting
86 | summary = research.get('summary', '')
87 | sources = research.get('sources', [])
88 | citations = research.get('citations', [])
89 |
90 | # Format sources nicely
91 | sources_text = ""
92 | if sources:
93 | sources_text = "Sources found:\n"
94 | for i, source in enumerate(sources, 1):
95 | # Handle both dict and SourceInfo objects
96 | if hasattr(source, 'title'):
97 | title = source.title or 'No title'
98 | url = source.url or 'No URL'
99 | snippet = source.snippet or ''
100 | else:
101 | # Fallback for dict-like objects
102 | title = source.get('title', 'No title')
103 | url = source.get('url', 'No URL')
104 | snippet = source.get('snippet', '')
105 |
106 | sources_text += f"{i}. {title}\n"
107 | sources_text += f" URL: {url}\n"
108 | if snippet:
109 | sources_text += f" Summary: {snippet[:200]}...\n"
110 | sources_text += "\n"
111 |
112 | research_context = f"""
113 | Research Results for: "{current_input}"
114 |
115 | Summary:
116 | {summary}
117 |
118 | {sources_text}
119 |
120 | Citations: {citations if citations else 'None provided'}
121 |
122 | Please provide a comprehensive, warm, and helpful answer based on this research information.
123 | """
124 |
125 | # Use the unified prompt with research context
126 | system_prompt = inject_current_time(UNIFIED_PROMPT)
127 |
128 | try:
129 | resp = completion(
130 | model=f"openrouter/{OPENROUTER_MODEL}",
131 | messages=[
132 | {"role": "system", "content": system_prompt},
133 | {"role": "user", "content": f"{research_context}\n\nBased on the research above, provide a comprehensive answer to the user's question. Be warm, helpful, and format the response clearly."},
134 | ],
135 | temperature=temperature,
136 | )
137 |
138 | content = resp.choices[0].message.content.strip()
139 |
140 | # Extract response from the unified format
141 | if "RESPONSE:" in content:
142 | response_lines = content.split('RESPONSE:')
143 | if len(response_lines) > 1:
144 | return response_lines[1].strip()
145 |
146 | # Fallback: return the full content if format parsing fails
147 | return content
148 |
149 | except Exception as e:
150 | return f"I'm sorry, I encountered an error: {str(e)}"
151 |
152 |
153 | def generate_chat_reply(history: List[Dict[str, str]], user_input: str) -> str:
154 | """Friendly chat response using the unified prompt and full conversation history."""
155 | # Build conversation context
156 | context_messages = []
157 |
158 | # Add conversation history for context
159 | if history:
160 | context_messages.append("Recent conversation history:")
161 | for turn in history:
162 | context_messages.append(f"User: {turn['input']}")
163 | context_messages.append(f"Assistant: {turn['response']}")
164 | else:
165 | context_messages.append("This is the start of the conversation.")
166 |
167 | context = "\n".join(context_messages)
168 |
169 | # Use the unified prompt
170 | system_prompt = inject_current_time(UNIFIED_PROMPT)
171 |
172 | try:
173 | resp = completion(
174 | model=f"openrouter/{OPENROUTER_MODEL}",
175 | messages=[
176 | {"role": "system", "content": system_prompt},
177 | {"role": "user", "content": f"{context}\n\nUser's current message: {user_input}"},
178 | ],
179 | temperature=0.5,
180 | )
181 |
182 | content = resp.choices[0].message.content.strip()
183 |
184 | # Extract response from the unified format
185 | if "RESPONSE:" in content:
186 | response_lines = content.split('RESPONSE:')
187 | if len(response_lines) > 1:
188 | return response_lines[1].strip()
189 |
190 | # Fallback: return the full content if format parsing fails
191 | return content
192 |
193 | except Exception as e:
194 | return f"I'm sorry, I encountered an error: {str(e)}"
195 |
196 |
197 | def unified_llm_call(conversation_history: List[Dict[str, str]], user_input: str) -> Tuple[str, str]:
198 | """
199 | Single LLM call that determines intent and generates response using the unified prompt.
200 | Returns (intent, response) tuple.
201 | """
202 | # Build conversation context
203 | context_messages = []
204 |
205 | # Add conversation history for context
206 | if conversation_history:
207 | context_messages.append("Recent conversation history:")
208 | for turn in conversation_history:
209 | context_messages.append(f"User: {turn['input']}")
210 | context_messages.append(f"Assistant: {turn['response']}")
211 | else:
212 | context_messages.append("This is the start of the conversation.")
213 |
214 | context = "\n".join(context_messages)
215 |
216 | # Use the unified prompt
217 | system_prompt = inject_current_time(UNIFIED_PROMPT)
218 |
219 | try:
220 | resp = completion(
221 | model=f"openrouter/{OPENROUTER_MODEL}",
222 | messages=[
223 | {"role": "system", "content": system_prompt},
224 | {"role": "user", "content": f"{context}\n\nUser's current message: {user_input}"},
225 | ],
226 | temperature=0.5,
227 | )
228 |
229 | content = resp.choices[0].message.content.strip()
230 |
231 | # Parse the unified response format
232 | intent = "CHAT" # Default
233 | response = content
234 |
235 | if "INTENT:" in content and "RESPONSE:" in content:
236 | lines = content.split('\n')
237 | for line in lines:
238 | line = line.strip()
239 | if line.startswith('INTENT:'):
240 | intent_part = line.replace('INTENT:', '').strip()
241 | if intent_part in ['SEARCH', 'CHAT', 'EXIT']:
242 | intent = intent_part
243 | elif line.startswith('RESPONSE:'):
244 | response_part = line.replace('RESPONSE:', '').strip()
245 | if response_part:
246 | response = response_part
247 |
248 | return intent, response
249 |
250 | except Exception as e:
251 | return 'CHAT', f"I'm sorry, I encountered an error: {str(e)}"
252 |
--------------------------------------------------------------------------------
/backend/ARCHITECTURE.md:
--------------------------------------------------------------------------------
1 | # CrewAI Flow Architecture
2 |
3 | Welcome to the architectural overview of the CrewAI Flow project! This document explains how the different parts of the system work together to create a smart, real-time chatbot experience.
4 |
5 | ## High-Level Overview
6 |
7 | At its core, this project is a web application with a **Next.js frontend** and a **Python FastAPI backend**. The magic happens in the backend, where we intelligently decide how to answer a user's query.
8 |
9 | The system can handle two types of requests:
10 | 1. **Simple Chat**: For conversational questions, it gets a quick response from a Large Language Model (LLM).
11 | 2. **In-depth Research**: For complex queries, it launches a team of AI agents (a "Crew") to research the topic, gather sources, and formulate a comprehensive answer.
12 |
13 | This entire process is streamed to the user in real-time, so they can see the AI "thinking."
14 |
15 | ### Visual Flow
16 |
17 | Here's a simple diagram of the process:
18 |
19 | ```
20 | +----------------------+
21 | [User's Browser] | Next.js Frontend |
22 | +----------------------+
23 | | (User sends message)
24 | v
25 | +----------------------+
26 | [Python Server] | FastAPI Backend |
27 | +----------------------+
28 | |
29 | v
30 | +---------------------------+
31 | | Intent Detection |
32 | | (Is it a CHAT or SEARCH?) |
33 | +---------------------------+
34 | | |
35 | (CHAT Intent) | | (SEARCH Intent)
36 | +---------+ +-----------+
37 | | |
38 | v v
39 | +-------------------+ +----------------------+
40 | | Simple LLM Call | | CrewAI Research Crew |
41 | | (Quick Response) | | (In-depth Research) |
42 | +-------------------+ +----------------------+
43 | | |
44 | +----------------+--------------------+
45 | |
46 | v
47 | +----------------------+
48 | | Formatted Response |
49 | +----------------------+
50 | | (Streamed back to user)
51 | v
52 | +----------------------+
53 | [User's Browser] | Next.js Frontend |
54 | +----------------------+
55 | ```
56 |
57 | ---
58 |
59 | ## Component Breakdown
60 |
61 | Let's look at the key pieces of the backend (`backend/src/chatbot/`) that make this work.
62 |
63 | ### 1. The Server: `ag_ui_server.py`
64 |
65 | This file is the main entry point for the backend.
66 |
67 | * **What it does**: It creates a FastAPI web server that listens for messages from the frontend. It's responsible for receiving requests and sending back responses.
68 | * **Key Endpoint**: The `/agent` endpoint is the primary endpoint that the frontend talks to. It's set up to stream events, meaning it can send multiple small updates over a single connection instead of making the user wait for the final answer.
69 | * **For Advanced Users**: It uses `StreamingResponse` with the `text/event-stream` media type to achieve Server-Sent Events (SSE). This is an efficient way to push real-time data from the server to the client.
70 |
71 | ### 2. The Orchestrator: `AGUIFlowAdapter`
72 |
73 | This class, found inside `ag_ui_server.py`, manages the entire process of handling a user's message.
74 |
75 | * **What it does**: When a message comes in, the adapter starts the process. It's responsible for running the core logic, listening for real-time updates from the AI, and sending those updates to the frontend. It also formats the final answer before sending it.
76 | * **For Advanced Users**: It uses `asyncio` to run the main message processing (`_run_flow_message`) in a non-blocking way. This allows it to simultaneously listen for events from the `real_time_listener` and stream them to the UI while the main logic is still executing.
77 |
78 | ### 3. The Brains: `ChatbotSession`
79 |
80 | This class, also in `ag_ui_server.py`, decides *how* to handle the user's message.
81 |
82 | * **What it does**: This is where the core decision-making happens.
83 | 1. It first performs **Intent Detection** (`detect_intent`) to classify the message as "CHAT" or "SEARCH".
84 | 2. If it's a "CHAT" message, it gets a direct, conversational reply from an LLM (`generate_chat_reply`).
85 | 3. If it's a "SEARCH" message, it activates the powerful `ResearchCrew`.
86 | * **For Advanced Users**: It maintains the conversation state, including history and any research results, within its `self.state` object. This state is not persisted across server restarts but is maintained for a single user "session."
87 |
88 | ### 4. The Research Team: `ResearchCrew`
89 |
90 | This is your CrewAI implementation, located in `backend/src/chatbot/crews/research_crew/`.
91 |
92 | * **What it does**: This is a team of specialized AI agents designed for research. When given a query, the crew works together to browse the web, read articles, extract key information, and compile a detailed report with sources.
93 | * **Key Files**:
94 | * `research_crew.py`: Defines the crew, its agents, and the tasks they perform.
95 | * `config/agents.yaml`: Defines the properties of each agent (e.g., their LLM, their role, their backstory).
96 | * `config/tasks.yaml`: Defines the sequence of tasks the agents need to complete.
97 | * **For Advanced Users**: The crew is "kicked off" via `crew().kickoff()`. The `pydantic` output of the final task is used to ensure the data is returned in a structured, predictable format.
98 |
99 | ### 5. The Real-Time Announcer: `real_time_listener.py`
100 |
101 | This is the secret sauce for the "Perplexity-like" real-time updates.
102 |
103 | * **What it does**: This module "listens" to everything the `ResearchCrew` does. It captures events like "Agent Started," "Tool Used," or "LLM Stream Chunk" (a piece of a sentence). The `AGUIFlowAdapter` then forwards these events to the UI.
104 | * **For Advanced Users**: This is implemented as a custom `AsyncEventHandler` for CrewAI. It hooks into the crew's execution lifecycle and stores events in a session-specific queue, which the main server process polls and streams to the client.
105 |
106 | ### 6. Helper Utilities: `utils/`
107 |
108 | The utilities folder contains helper functions that support the main logic:
109 |
110 | * **`chat_helpers.py`**: Contains functions like `detect_intent()`, `generate_chat_reply()`, and `synthesise_research()`. These handle the core LLM interactions and decision-making logic.
111 | * **`prompts.py`**: Houses the prompts and instructions sent to the LLMs to guide their behavior.
112 |
113 | ---
114 |
115 | ## Data Flow Walkthrough
116 |
117 | Let's trace what happens when a user sends a message:
118 |
119 | ### Step 1: Message Reception
120 | 1. User types a message in the frontend chat interface
121 | 2. Frontend sends POST request to `/agent` endpoint
122 | 3. `agent_endpoint()` function extracts the message and calls `adapter.process_message()`
123 |
124 | ### Step 2: Processing Setup
125 | 1. `AGUIFlowAdapter.process_message()` sends a "RUN_STARTED" event to the UI
126 | 2. Creates an async task to run the actual message processing
127 | 3. Starts monitoring for real-time events from the `real_time_listener`
128 |
129 | ### Step 3: Intent Classification
130 | 1. `ChatbotSession.process_message()` calls `detect_intent(user_message)`
131 | 2. An LLM analyzes the message and returns either "CHAT" or "SEARCH"
132 |
133 | ### Step 4a: Simple Chat Path (CHAT Intent)
134 | 1. Calls `generate_chat_reply()` with conversation history
135 | 2. LLM generates a conversational response
136 | 3. Response is added to conversation history
137 | 4. Returns formatted response
138 |
139 | ### Step 4b: Research Path (SEARCH Intent)
140 | 1. Creates and kicks off `ResearchCrew` with the user query
141 | 2. Crew agents execute their tasks (web search, analysis, compilation)
142 | 3. Real-time events are captured by `real_time_listener` during execution
143 | 4. Crew returns structured research results with sources
144 | 5. `synthesise_research()` creates a final polished answer
145 | 6. Research results are stored in session state
146 |
147 | ### Step 5: Response Streaming
148 | 1. `AGUIFlowAdapter` formats the response based on intent type
149 | 2. For research responses: formats content and extracts sources
150 | 3. Streams the final response as "TEXT_MESSAGE_DELTA" events
151 | 4. Sends sources as "SOURCES_UPDATE" events (if applicable)
152 | 5. Sends "RUN_FINISHED" event to signal completion
153 |
154 | ### Step 6: Frontend Display
155 | 1. Frontend receives and displays streamed events in real-time
156 | 2. Shows typing indicators, progress updates, and partial responses
157 | 3. Displays final formatted answer with sources and citations
158 |
159 | ---
160 |
161 | ## Key Technologies & Patterns
162 |
163 | ### Backend Technologies
164 | - **FastAPI**: Modern, fast web framework for building APIs
165 | - **CrewAI**: Multi-agent framework for coordinating AI agents
166 | - **Pydantic**: Data validation and serialization
167 | - **AsyncIO**: Asynchronous programming for concurrent operations
168 |
169 | ### Frontend Technologies
170 | - **Next.js**: React framework for the web interface
171 | - **Server-Sent Events (SSE)**: Real-time communication from server to client
172 | - **TypeScript**: Type-safe JavaScript for better developer experience
173 |
174 | ### Architectural Patterns
175 | - **Event-Driven Architecture**: Real-time events drive UI updates
176 | - **Strategy Pattern**: Different handling strategies based on intent classification
177 | - **Observer Pattern**: Real-time listener observes crew execution
178 | - **Streaming Response**: Progressive loading of responses for better UX
179 |
180 | ---
181 |
182 | ## Benefits of This Architecture
183 |
184 | ### For Users
185 | - **Real-time feedback**: See the AI working in real-time
186 | - **Intelligent routing**: Get quick answers for simple questions, thorough research for complex ones
187 | - **Source transparency**: See exactly where information comes from
188 | - **Modern interface**: Clean, responsive design similar to popular AI assistants
189 |
190 | ### For Developers
191 | - **Modular design**: Easy to extend with new agents, tools, or capabilities
192 | - **Clear separation of concerns**: Frontend, orchestration, and AI logic are cleanly separated
193 | - **Event-driven**: Easy to add new types of real-time updates
194 | - **Type safety**: Pydantic models ensure data consistency between components
195 |
196 | ---
197 |
198 | This architecture creates a system that is both powerful and efficient. It uses the full force of an AI agent crew only when necessary, while still providing quick, conversational responses for simpler interactions, all with a modern, real-time user experience.
--------------------------------------------------------------------------------
/frontend/src/app/globals.css:
--------------------------------------------------------------------------------
1 | @import "tailwindcss";
2 |
3 | :root {
4 | --background: 0 0% 100%;
5 | --foreground: 222 47% 11%;
6 |
7 | --muted: 210 40% 96%;
8 | --muted-foreground: 215 16% 47%;
9 |
10 | --popover: 0 0% 100%;
11 | --popover-foreground: 222 47% 11%;
12 |
13 | --card: 0 0% 100%;
14 | --card-foreground: 222 47% 11%;
15 |
16 | --border: 214 32% 91%;
17 | --input: 214 32% 91%;
18 |
19 | --primary: 43 79% 63%;
20 | --primary-foreground: 26 83% 14%;
21 |
22 | --secondary: 210 40% 96%;
23 | --secondary-foreground: 222 47% 11%;
24 |
25 | --accent: 210 40% 94%;
26 | --accent-foreground: 222 47% 11%;
27 |
28 | --destructive: 0 84% 60%;
29 | --destructive-foreground: 0 0% 100%;
30 |
31 | --success: 142.1 76.2% 36.3%;
32 | --success-foreground: 0 0% 100%;
33 |
34 | --ring: 43 96% 56%;
35 |
36 | --radius: 0.75rem;
37 | }
38 |
39 | @theme inline {
40 | --color-background: hsl(var(--background));
41 | --color-foreground: hsl(var(--foreground));
42 | --font-sans: var(--font-geist-sans);
43 | --font-mono: var(--font-geist-mono);
44 | }
45 |
46 | @media (prefers-color-scheme: dark) {
47 | :root {
48 | --background: 224 71% 4%;
49 | --foreground: 213 31% 91%;
50 |
51 | --muted: 223 47% 11%;
52 | --muted-foreground: 215 20% 65%;
53 |
54 | --popover: 224 71% 4%;
55 | --popover-foreground: 213 31% 91%;
56 |
57 | --card: 224 71% 4%;
58 | --card-foreground: 213 31% 91%;
59 |
60 | --border: 216 34% 17%;
61 | --input: 216 34% 17%;
62 |
63 | --primary: 43 96% 56%;
64 | --primary-foreground: 26 83% 14%;
65 |
66 | --secondary: 223 47% 11%;
67 | --secondary-foreground: 213 31% 91%;
68 |
69 | --accent: 216 34% 17%;
70 | --accent-foreground: 213 31% 91%;
71 |
72 | --destructive: 0 63% 31%;
73 | --destructive-foreground: 0 85% 96%;
74 |
75 | --success: 142 69% 58%;
76 | --success-foreground: 144 61% 20%;
77 |
78 | --ring: 43 96% 56%;
79 | }
80 | }
81 |
82 | /* Enhanced body styling with subtle background */
83 | body {
84 | background: linear-gradient(135deg,
85 | rgba(251, 191, 36, 0.02) 0%,
86 | rgba(156, 163, 175, 0.03) 100%
87 | ),
88 | hsl(var(--background));
89 |
90 | color: hsl(var(--foreground));
91 | font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
92 | min-height: 100vh;
93 | display: flex;
94 | flex-direction: column;
95 | font-weight: 400;
96 | letter-spacing: -0.01em;
97 | }
98 |
99 | @media (prefers-color-scheme: dark) {
100 | body {
101 | background: linear-gradient(135deg,
102 | rgba(251, 191, 36, 0.05) 0%,
103 | rgba(75, 85, 99, 0.08) 100%
104 | ),
105 | hsl(var(--background));
106 | }
107 | }
108 |
109 | /* Custom scrollbar styling */
110 | ::-webkit-scrollbar {
111 | width: 8px;
112 | }
113 |
114 | ::-webkit-scrollbar-track {
115 | background: hsl(var(--muted));
116 | border-radius: 4px;
117 | }
118 |
119 | ::-webkit-scrollbar-thumb {
120 | background: linear-gradient(135deg, #fcd34d, #f59e0b);
121 | border-radius: 4px;
122 | border: 1px solid hsl(var(--background));
123 | }
124 |
125 | ::-webkit-scrollbar-thumb:hover {
126 | background: linear-gradient(135deg, #f59e0b, #d97706);
127 | }
128 |
129 | /* Enhanced markdown styles for chat messages */
130 | .markdown-content {
131 | line-height: 1.7;
132 | letter-spacing: -0.01em;
133 | color: hsl(var(--foreground));
134 | }
135 |
136 | /* Better spacing for content */
137 | .markdown-content > *:first-child {
138 | margin-top: 0;
139 | }
140 |
141 | .markdown-content > *:last-child {
142 | margin-bottom: 0;
143 | }
144 |
145 | .markdown-content h1,
146 | .markdown-content h2,
147 | .markdown-content h3 {
148 | color: hsl(var(--foreground));
149 | font-weight: 700;
150 | margin: 1.5rem 0 1rem 0;
151 | padding-bottom: 0.5rem;
152 | }
153 |
154 | .markdown-content h1 {
155 | font-size: 1.5rem;
156 | border-bottom: 2px solid hsl(var(--border));
157 | }
158 |
159 | .markdown-content h2 {
160 | font-size: 1.25rem;
161 | border-bottom: 1px solid hsl(var(--border));
162 | }
163 |
164 | .markdown-content h3 {
165 | font-size: 1.125rem;
166 | }
167 |
168 | .markdown-content p {
169 | margin: 1rem 0;
170 | color: hsl(var(--foreground));
171 | opacity: 0.9;
172 | }
173 |
174 | /* Enhanced list styling */
175 | .markdown-content ul, .markdown-content ol {
176 | margin: 1rem 0;
177 | padding-left: 1.5rem;
178 | }
179 |
180 | .markdown-content ul {
181 | list-style: none;
182 | }
183 |
184 | .markdown-content ol {
185 | padding-left: 1.5rem;
186 | }
187 |
188 | .markdown-content li {
189 | margin: 0.75rem 0;
190 | color: hsl(var(--foreground));
191 | line-height: 1.6;
192 | }
193 |
194 | /* Custom bullet styling for better visual hierarchy */
195 | .markdown-content ul li {
196 | position: relative;
197 | padding-left: 0;
198 | }
199 |
200 | .markdown-content ul li::before {
201 | content: '';
202 | position: absolute;
203 | left: -1.5rem;
204 | top: 0.75rem;
205 | width: 6px;
206 | height: 6px;
207 | background: linear-gradient(135deg, #fcd34d, #f59e0b);
208 | border-radius: 50%;
209 | box-shadow: 0 0 0 2px rgba(251, 191, 36, 0.2);
210 | }
211 |
212 | /* Enhanced prose styles for ReactMarkdown */
213 | .prose {
214 | color: hsl(var(--foreground));
215 | max-width: none;
216 | }
217 |
218 | .prose h1 {
219 | color: hsl(var(--foreground));
220 | font-weight: 800;
221 | font-size: 1.875rem;
222 | margin-top: 2rem;
223 | margin-bottom: 1.5rem;
224 | line-height: 1.2;
225 | }
226 |
227 | .prose h2 {
228 | color: #d97706;
229 | font-weight: 700;
230 | font-size: 1.5rem;
231 | margin-top: 1.5rem;
232 | margin-bottom: 1rem;
233 | line-height: 1.3;
234 | }
235 |
236 | .prose h3 {
237 | color: hsl(var(--foreground));
238 | font-weight: 600;
239 | font-size: 1.25rem;
240 | margin-top: 1.25rem;
241 | margin-bottom: 0.75rem;
242 | line-height: 1.4;
243 | }
244 |
245 | .prose p {
246 | margin-top: 1rem;
247 | margin-bottom: 1rem;
248 | line-height: 1.7;
249 | color: hsl(var(--foreground));
250 | opacity: 0.95;
251 | }
252 |
253 | .prose ul {
254 | margin-top: 1rem;
255 | margin-bottom: 1rem;
256 | list-style: none;
257 | padding-left: 0;
258 | }
259 |
260 | .prose ol {
261 | margin-top: 1rem;
262 | margin-bottom: 1rem;
263 | padding-left: 1.5rem;
264 | }
265 |
266 | .prose li {
267 | margin-top: 0.5rem;
268 | margin-bottom: 0.5rem;
269 | line-height: 1.6;
270 | color: hsl(var(--foreground));
271 | }
272 |
273 | .prose strong {
274 | font-weight: 700;
275 | color: hsl(var(--foreground));
276 | }
277 |
278 | .prose em {
279 | font-style: italic;
280 | color: hsl(var(--muted-foreground));
281 | }
282 |
283 | .prose code {
284 | background-color: hsl(var(--muted));
285 | color: hsl(var(--foreground));
286 | padding: 0.125rem 0.25rem;
287 | border-radius: 0.375rem;
288 | font-size: 0.875rem;
289 | font-weight: 500;
290 | border: 1px solid hsl(var(--border));
291 | }
292 |
293 | .prose pre {
294 | background-color: hsl(var(--muted));
295 | color: hsl(var(--foreground));
296 | padding: 1rem;
297 | border-radius: 0.5rem;
298 | overflow-x: auto;
299 | border: 1px solid hsl(var(--border));
300 | margin: 1rem 0;
301 | }
302 |
303 | .prose blockquote {
304 | border-left: 4px solid #f59e0b;
305 | padding-left: 1rem;
306 | margin: 1rem 0;
307 | font-style: italic;
308 | color: hsl(var(--muted-foreground));
309 | background-color: rgba(251, 191, 36, 0.05);
310 | padding: 0.75rem 1rem;
311 | border-radius: 0 0.5rem 0.5rem 0;
312 | }
313 |
314 | .prose a {
315 | color: #d97706;
316 | text-decoration: underline;
317 | font-weight: 500;
318 | transition: all 0.2s ease;
319 | }
320 |
321 | .prose a:hover {
322 | color: #b45309;
323 | background-color: rgba(251, 191, 36, 0.1);
324 | text-decoration: none;
325 | border-radius: 0.25rem;
326 | padding: 0.125rem 0.25rem;
327 | }
328 |
329 | .markdown-content ul li::before {
330 | content: "•";
331 | color: hsl(var(--foreground));
332 | font-size: 1em;
333 | font-weight: normal;
334 | position: absolute;
335 | left: -1.25rem;
336 | top: 0;
337 | }
338 |
339 | .markdown-content strong {
340 | font-weight: 600;
341 | color: hsl(var(--foreground));
342 | }
343 |
344 | .markdown-content em {
345 | font-style: italic;
346 | color: hsl(var(--muted-foreground));
347 | opacity: 0.8;
348 | }
349 |
350 | .markdown-content code {
351 | background: hsl(var(--muted));
352 | color: hsl(var(--primary));
353 | padding: 0.2rem 0.4rem;
354 | border-radius: 0.375rem;
355 | font-size: 0.875em;
356 | font-weight: 500;
357 | border: 1px solid hsl(var(--border));
358 | }
359 |
360 | .markdown-content pre {
361 | background: hsl(var(--muted));
362 | border: 1px solid hsl(var(--border));
363 | border-radius: 0.75rem;
364 | padding: 1rem;
365 | overflow-x: auto;
366 | margin: 1rem 0;
367 | }
368 |
369 | .markdown-content pre code {
370 | background: none;
371 | border: none;
372 | padding: 0;
373 | color: hsl(var(--foreground));
374 | }
375 |
376 | .markdown-content blockquote {
377 | border-left: 4px solid hsl(var(--primary));
378 | background: hsl(var(--muted));
379 | padding: 1rem 1.5rem;
380 | margin: 1rem 0;
381 | border-radius: 0 0.5rem 0.5rem 0;
382 | font-style: italic;
383 | }
384 |
385 | /* Glass morphism effect for cards */
386 | .glass-card {
387 | background: rgba(255, 255, 255, 0.8);
388 | backdrop-filter: blur(8px);
389 | border: 1px solid rgba(0, 0, 0, 0.1);
390 | box-shadow: 0 4px 16px rgba(0, 0, 0, 0.1);
391 | }
392 |
393 | @media (prefers-color-scheme: dark) {
394 | .glass-card {
395 | background: rgba(0, 0, 0, 0.4);
396 | border: 1px solid rgba(255, 255, 255, 0.1);
397 | box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3);
398 | }
399 | }
400 |
401 | /* Button hover effects */
402 | .btn-primary {
403 | background: linear-gradient(135deg, #fcd34d, #f59e0b);
404 | transition: all 0.3s ease;
405 | }
406 |
407 | .btn-primary:hover {
408 | transform: translateY(-1px);
409 | box-shadow: 0 4px 12px rgba(252, 211, 77, 0.4);
410 | }
411 |
412 | /* Status indicators */
413 | .status-processing {
414 | background: rgba(252, 211, 77, 0.1);
415 | border-color: rgba(252, 211, 77, 0.3);
416 | color: #f59e0b;
417 | }
418 |
419 | .status-success {
420 | background: rgba(34, 197, 94, 0.1);
421 | border-color: rgba(34, 197, 94, 0.3);
422 | color: #16a34a;
423 | }
424 |
425 | .status-ready {
426 | background: rgba(107, 114, 128, 0.1);
427 | border-color: rgba(107, 114, 128, 0.3);
428 | color: #6b7280;
429 | }
430 |
431 | /* Enhanced input styling */
432 | .enhanced-input {
433 | background: hsl(var(--background));
434 | border: 1px solid hsl(var(--border));
435 | transition: all 0.3s ease;
436 | }
437 |
438 | .enhanced-input:focus {
439 | border-color: hsl(var(--primary));
440 | box-shadow: 0 0 0 3px rgba(252, 211, 77, 0.1);
441 | }
442 |
443 | /* Execution tracker animations */
444 | @keyframes slide-in-from-left-2 {
445 | from {
446 | transform: translateX(-8px);
447 | opacity: 0;
448 | }
449 | to {
450 | transform: translateX(0);
451 | opacity: 1;
452 | }
453 | }
454 |
455 | @keyframes fade-in {
456 | from {
457 | opacity: 0;
458 | }
459 | to {
460 | opacity: 1;
461 | }
462 | }
463 |
464 | .animate-in {
465 | animation-duration: 0.3s;
466 | animation-timing-function: ease-out;
467 | animation-fill-mode: both;
468 | }
469 |
470 | .slide-in-from-left-2 {
471 | animation-name: slide-in-from-left-2;
472 | }
473 |
474 | .animate-fade-in {
475 | animation-name: fade-in;
476 | animation-duration: 0.5s;
477 | animation-timing-function: ease-out;
478 | }
479 |
--------------------------------------------------------------------------------
/frontend/src/components/ResearchResults.tsx:
--------------------------------------------------------------------------------
1 | interface Source {
2 | url: string
3 | title?: string
4 | image_url?: string
5 | snippet?: string
6 | }
7 |
8 | interface ResearchResultsProps {
9 | results?: {
10 | summary: string
11 | sources: Source[]
12 | citations: string[]
13 | }
14 | conversations?: Array<{
15 | input: string
16 | response: string
17 | type: "chat" | "research_enhanced"
18 | sources?: Source[]
19 | }>
20 | }
21 |
22 | export function ResearchResults({ results, conversations }: ResearchResultsProps) {
23 | return (
24 |
62 |
71 |
72 | {/* Status Indicator */}
73 |
63 |
66 |
67 | 68 | Flow State 69 |
70 |
74 |
99 |
100 | {/* Statistics Cards */}
101 |
75 |
98 |
76 |
88 |
89 | {/* Pulse indicator for processing */}
90 | {state?.processing && (
91 |
77 | {icon}
78 |
79 |
80 | {status}
81 |
87 | 82 | {state?.processing ? "AI is analyzing your request..." : 83 | state?.has_new_research ? "New insights are available" : 84 | "Ready for your next question"} 85 |
86 |
92 |
93 |
94 |
95 |
96 | )}
97 |
102 | {/* Conversation Stats */}
103 |
158 |
159 | {/* Processing Animation */}
160 | {state?.processing && (
161 |
104 |
123 |
124 | {/* Research Stats */}
125 |
105 |
114 |
106 |
109 |
110 | 111 | Conversations 112 |
113 |
115 |
122 |
116 | Total Messages:
117 |
118 | {state?.conversation_history?.length || 0}
119 |
120 |
121 |
126 |
157 |
127 |
136 |
128 |
131 |
132 | 133 | Research 134 |
135 |
137 |
156 |
138 | Status:
139 |
144 | {state?.has_new_research ? "Available" : "None"}
145 |
146 |
147 | {state?.research_results && (
148 |
149 | Sources:
150 |
151 | {state.research_results.sources?.length || 0}
152 |
153 |
154 | )}
155 |
162 |
177 | )}
178 |
179 | {/* Research Progress Indicator */}
180 | {state?.has_new_research && (
181 |
163 |
176 |
164 |
165 |
166 |
167 |
168 |
175 | 169 | AI is working... 170 |
171 |172 | Analyzing your request and gathering insights 173 |
174 |
182 |
199 | )}
200 |
183 |
198 |
184 |
187 |
188 |
189 |
196 |
197 | 190 | Research Complete! 191 |
192 |193 | New research results are ready for you to explore 194 |
195 |
25 | {/* Header */}
26 |
236 | )
237 | }
--------------------------------------------------------------------------------
/backend/src/chatbot/listeners/real_time_listener.py:
--------------------------------------------------------------------------------
1 | from typing import Optional, Dict, Any, List
2 | from dataclasses import dataclass, asdict
3 | from datetime import datetime
4 | import queue
5 | import threading
6 | import uuid
7 | import json
8 |
9 | from crewai.utilities.events import (
10 | CrewKickoffCompletedEvent,
11 | AgentExecutionStartedEvent,
12 | AgentExecutionCompletedEvent,
13 | ToolUsageStartedEvent,
14 | ToolUsageFinishedEvent,
15 | ToolUsageErrorEvent,
16 | )
17 | from crewai.utilities.events.base_event_listener import BaseEventListener
18 |
19 |
20 | @dataclass
21 | class StreamEvent:
22 | """Data structure for streaming events to frontend"""
23 | type: str
24 | data: Dict[str, Any]
25 | timestamp: str
26 | agent_id: Optional[str] = None
27 | session_id: Optional[str] = None
28 |
29 |
30 | class RealTimeListener(BaseEventListener):
31 | """
32 | Real-time event listener that captures CrewAI events and streams them to the frontend.
33 | Provides Perplexity-like real-time visibility into agent execution.
34 | """
35 |
36 | def __init__(self):
37 | super().__init__()
38 |
39 | self.event_queue = queue.Queue()
40 | self.session_id = str(uuid.uuid4())
41 |
42 | def setup_listeners(self, crewai_event_bus):
43 | """Setup all event listeners for comprehensive monitoring"""
44 |
45 | # ==================== AGENT EVENTS ====================
46 |
47 | @crewai_event_bus.on(AgentExecutionStartedEvent)
48 | def on_agent_execution_started(source, event: AgentExecutionStartedEvent):
49 | agent = getattr(event, 'agent', None)
50 | if agent:
51 | agent_id = str(agent.id)
52 | agent_role = getattr(agent, 'role', 'Research Agent')
53 |
54 | # Emit the thinking message immediately when agent starts
55 | self._emit_event(StreamEvent(
56 | type="AGENT_STARTED",
57 | data={
58 | "agent_role": agent_role,
59 | "message": "Research agent thinking...",
60 | "status": "executing"
61 | },
62 | timestamp=datetime.now().isoformat(),
63 | agent_id=agent_id,
64 | session_id=self.session_id
65 | ))
66 |
67 | @crewai_event_bus.on(AgentExecutionCompletedEvent)
68 | def on_agent_execution_finished(source, event: AgentExecutionCompletedEvent):
69 | agent = getattr(event, 'agent', None)
70 | if agent:
71 | agent_id = str(agent.id)
72 | agent_role = getattr(agent, 'role', 'Research Agent')
73 |
74 | # Emit the final thoughts message when agent finishes
75 | self._emit_event(StreamEvent(
76 | type="AGENT_FINISHED",
77 | data={
78 | "agent_role": agent_role,
79 | "message": "Gathering final thoughts...",
80 | "status": "finished"
81 | },
82 | timestamp=datetime.now().isoformat(),
83 | agent_id=agent_id,
84 | session_id=self.session_id
85 | ))
86 |
87 | # ==================== TOOL USAGE EVENTS ====================
88 |
89 | @crewai_event_bus.on(ToolUsageStartedEvent)
90 | def on_tool_usage_started(source, event: ToolUsageStartedEvent):
91 | """Capture when a tool starts executing, including the input query"""
92 | agent = getattr(event, 'agent', None)
93 | agent_id = str(agent.id) if agent and hasattr(agent, 'id') else None
94 | agent_role = getattr(agent, 'role', 'Research Agent') if agent else 'Research Agent'
95 |
96 | # Extract tool input query from tool_args - handle various formats
97 | tool_query = "Unknown query"
98 |
99 | # Handle string representation of JSON
100 | if isinstance(event.tool_args, str):
101 | try:
102 | # Try to parse as JSON
103 | parsed_args = json.loads(event.tool_args)
104 | if isinstance(parsed_args, dict):
105 | if "query" in parsed_args and isinstance(parsed_args["query"], dict):
106 | tool_query = parsed_args["query"].get("search_query", "Unknown query")
107 | elif "query" in parsed_args:
108 | tool_query = parsed_args.get("query", "Unknown query")
109 | else:
110 | tool_query = event.tool_args
111 | except json.JSONDecodeError:
112 | # If not JSON, use as-is
113 | tool_query = event.tool_args
114 | elif isinstance(event.tool_args, dict):
115 | # Handle nested structure: {"query": {"search_query": "..."}, "num_results": 5}
116 | if "query" in event.tool_args and isinstance(event.tool_args["query"], dict):
117 | tool_query = event.tool_args["query"].get("search_query", "Unknown query")
118 | # Handle flat structure: {"query": "...", "num_results": 5}
119 | elif "query" in event.tool_args:
120 | tool_query = event.tool_args.get("query", "Unknown query")
121 |
122 | self._emit_event(StreamEvent(
123 | type="TOOL_STARTED",
124 | data={
125 | "tool_name": event.tool_name,
126 | "tool_query": tool_query,
127 | "agent_role": agent_role,
128 | "message": f"Searching for {tool_query}",
129 | "status": "executing"
130 | },
131 | timestamp=datetime.now().isoformat(),
132 | agent_id=agent_id,
133 | session_id=self.session_id
134 | ))
135 |
136 | @crewai_event_bus.on(ToolUsageFinishedEvent)
137 | def on_tool_usage_finished(source, event: ToolUsageFinishedEvent):
138 | """Capture when a tool finishes executing"""
139 | agent = getattr(event, 'agent', None)
140 | agent_id = str(agent.id) if agent and hasattr(agent, 'id') else None
141 | agent_role = getattr(agent, 'role', 'Research Agent') if agent else 'Research Agent'
142 |
143 | # Extract tool input query - handle various formats
144 | tool_query = "Unknown query"
145 |
146 | # Handle string representation of JSON
147 | if isinstance(event.tool_args, str):
148 | try:
149 | # Try to parse as JSON
150 | parsed_args = json.loads(event.tool_args)
151 | if isinstance(parsed_args, dict):
152 | if "query" in parsed_args and isinstance(parsed_args["query"], dict):
153 | tool_query = parsed_args["query"].get("search_query", "Unknown query")
154 | elif "query" in parsed_args:
155 | tool_query = parsed_args.get("query", "Unknown query")
156 | else:
157 | tool_query = event.tool_args
158 | except json.JSONDecodeError:
159 | # If not JSON, use as-is
160 | tool_query = event.tool_args
161 | elif isinstance(event.tool_args, dict):
162 | # Handle nested structure: {"query": {"search_query": "..."}, "num_results": 5}
163 | if "query" in event.tool_args and isinstance(event.tool_args["query"], dict):
164 | tool_query = event.tool_args["query"].get("search_query", "Unknown query")
165 | # Handle flat structure: {"query": "...", "num_results": 5}
166 | elif "query" in event.tool_args:
167 | tool_query = event.tool_args.get("query", "Unknown query")
168 |
169 | # Emit event when tool completes execution
170 | # Contains tool details, query info, agent info and completion status
171 | # Includes whether results came from cache
172 | #self._emit_event(StreamEvent(
173 | # type="TOOL_COMPLETED",
174 | # data={
175 | # "tool_name": event.tool_name,
176 | # "tool_query": tool_query,
177 | # "agent_role": agent_role,
178 | # "message": f"Found results for: {tool_query}",
179 | # "status": "completed",
180 | # "from_cache": event.from_cache
181 | # },
182 | # timestamp=datetime.now().isoformat(),
183 | # agent_id=agent_id,
184 | # session_id=self.session_id
185 | #))
186 |
187 | @crewai_event_bus.on(ToolUsageErrorEvent)
188 | def on_tool_usage_error(source, event: ToolUsageErrorEvent):
189 | """Capture when a tool encounters an error"""
190 | agent = getattr(event, 'agent', None)
191 | agent_id = str(agent.id) if agent and hasattr(agent, 'id') else None
192 | agent_role = getattr(agent, 'role', 'Research Agent') if agent else 'Research Agent'
193 |
194 | # Extract tool input query - handle various formats
195 | tool_query = "Unknown query"
196 |
197 | # Handle string representation of JSON
198 | if isinstance(event.tool_args, str):
199 | try:
200 | # Try to parse as JSON
201 | parsed_args = json.loads(event.tool_args)
202 | if isinstance(parsed_args, dict):
203 | if "query" in parsed_args and isinstance(parsed_args["query"], dict):
204 | tool_query = parsed_args["query"].get("search_query", "Unknown query")
205 | elif "query" in parsed_args:
206 | tool_query = parsed_args.get("query", "Unknown query")
207 | else:
208 | tool_query = event.tool_args
209 | except json.JSONDecodeError:
210 | # If not JSON, use as-is
211 | tool_query = event.tool_args
212 | elif isinstance(event.tool_args, dict):
213 | # Handle nested structure: {"query": {"search_query": "..."}, "num_results": 5}
214 | if "query" in event.tool_args and isinstance(event.tool_args["query"], dict):
215 | tool_query = event.tool_args["query"].get("search_query", "Unknown query")
216 | # Handle flat structure: {"query": "...", "num_results": 5}
217 | elif "query" in event.tool_args:
218 | tool_query = event.tool_args.get("query", "Unknown query")
219 |
220 | self._emit_event(StreamEvent(
221 | type="TOOL_ERROR",
222 | data={
223 | "tool_name": event.tool_name,
224 | "tool_query": tool_query,
225 | "agent_role": agent_role,
226 | "message": f"Error searching for {tool_query}",
227 | "status": "error",
228 | "error": str(event.error)
229 | },
230 | timestamp=datetime.now().isoformat(),
231 | agent_id=agent_id,
232 | session_id=self.session_id
233 | ))
234 |
235 |
236 | def _emit_event(self, event: StreamEvent):
237 | """Emit event to the queue for frontend consumption"""
238 | # Clean the event data to ensure JSON serialization
239 | clean_event = self._clean_event_data(event)
240 | self.event_queue.put_nowait(clean_event)
241 | # Debug output for essential events only
242 | if event.type in ["AGENT_STARTED", "AGENT_FINISHED"]:
243 | print(f"🔔 Event: {event.data.get('message', '')}")
244 |
245 | def _clean_event_data(self, event: StreamEvent) -> StreamEvent:
246 | """Clean event data to ensure JSON serialization"""
247 | # Create a clean copy of the event data
248 | clean_data = {}
249 | for key, value in event.data.items():
250 | if isinstance(value, (str, int, float, bool, type(None))):
251 | clean_data[key] = value
252 | else:
253 | # Convert other types to string
254 | clean_data[key] = str(value)
255 |
256 | # Create a new event with cleaned data
257 | return StreamEvent(
258 | type=event.type,
259 | data=clean_data,
260 | timestamp=event.timestamp,
261 | agent_id=event.agent_id,
262 | session_id=event.session_id
263 | )
264 |
265 | def get_events_realtime(self) -> List[Dict[str, Any]]:
266 | """Get events and immediately return them for real-time streaming"""
267 | events = []
268 | while True:
269 | try:
270 | event = self.event_queue.get_nowait()
271 | events.append(asdict(event))
272 | except queue.Empty:
273 | break
274 | return events
275 |
276 | def get_session_status(self) -> Dict[str, Any]:
277 | """Get current session status and statistics"""
278 | return {
279 | "session_id": self.session_id,
280 | "events_pending": self.event_queue.qsize()
281 | }
282 |
283 | def reset_session(self):
284 | """Reset the session and clear all events"""
285 | self.session_id = str(uuid.uuid4())
286 |
287 | while True:
288 | try:
289 | self.event_queue.get_nowait()
290 | except queue.Empty:
291 | break
292 |
293 |
294 | # Create a global instance of the listener
295 | real_time_listener = RealTimeListener()
--------------------------------------------------------------------------------
/backend/src/chatbot/ag_ui_server.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python
2 | """
3 | AG-UI compatible server for CrewAI flow
4 | Enhanced with real-time event streaming for Perplexity-like experience
5 | """
6 |
7 | import sys
8 | import os
9 | sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
10 |
11 | from fastapi import FastAPI, Depends, HTTPException, status
12 | from fastapi.responses import StreamingResponse
13 | from fastapi.middleware.cors import CORSMiddleware
14 | from fastapi.security import OAuth2PasswordRequestForm
15 | from pydantic import BaseModel
16 | from typing import Dict, Any, AsyncGenerator, List
17 | import json
18 | import asyncio
19 | from datetime import datetime, timedelta
20 |
21 | # Import authentication
22 | from .auth import (
23 | authenticate_user,
24 | create_access_token,
25 | get_current_active_user,
26 | User,
27 | Token,
28 | fake_users_db,
29 | ACCESS_TOKEN_EXPIRE_MINUTES
30 | )
31 |
32 | # Import listeners to register them with the event bus
33 | from .listeners.real_time_listener import real_time_listener
34 |
35 |
36 | from .main import ChatState
37 |
38 | from .utils.chat_helpers import (
39 | detect_intent,
40 | generate_chat_reply,
41 | synthesise_research,
42 | )
43 | from .crews.research_crew.research_crew import ResearchCrew
44 |
45 |
46 | # -------------------------------------------------------------
47 | # Enhanced wrapper that utilises the existing helpers + crews and
48 | # provides real-time event streaming capabilities
49 | # -------------------------------------------------------------
50 |
51 |
52 | class ChatbotSession:
53 | """Self-contained session replicating the behaviour of `SimpleChatFlow` with real-time events."""
54 |
55 | def __init__(self):
56 | self.state = ChatState()
57 | self.session_id = None
58 |
59 | # ------------------------- Core API ----------------------
60 | def process_message(self, user_message: str, conversation_history: List[Dict[str, str]] = None) -> Dict[str, Any]:
61 | """Process a single user message and return a response payload."""
62 |
63 | # Only reset event listener session for new chat sessions, not for each message
64 | if not self.session_id:
65 | real_time_listener.reset_session()
66 | self.session_id = real_time_listener.session_id
67 |
68 | self.state.current_input = user_message
69 |
70 | # Initialize conversation history if provided (from frontend)
71 | if conversation_history is not None:
72 | self.state.conversation_history = conversation_history
73 |
74 | # 1. Detect intent (SEARCH, CHAT, EXIT) and get expanded query
75 | intent, expanded_query = detect_intent(user_message, self.state.conversation_history)
76 |
77 | # 2. Handle EXIT intent upfront
78 | if intent == "EXIT":
79 | self.state.session_ended = True
80 | return {
81 | "intent": "EXIT",
82 | "response": "👋 Session ended. Feel free to start a new one whenever you like!",
83 | }
84 |
85 | # 3. Handle SEARCH intent via ResearchCrew
86 | if intent == "SEARCH":
87 | try:
88 | search_result = ResearchCrew().crew().kickoff(inputs={"query": expanded_query})
89 |
90 | pyd_res = search_result.pydantic
91 | research_results = {
92 | "summary": getattr(pyd_res, "summary", ""),
93 | "sources": getattr(pyd_res, "sources", []),
94 | "citations": getattr(pyd_res, "citations", []),
95 | }
96 |
97 | # Store research in state for potential future use
98 | self.state.research_results = research_results
99 | self.state.has_new_research = True
100 |
101 | # Synthesize final answer from the raw research
102 | answer = synthesise_research(user_message, research_results)
103 |
104 | # Persist turn in history
105 | self.state.conversation_history.append(
106 | {
107 | "input": user_message,
108 | "response": answer,
109 | "type": "research_enhanced",
110 | "sources": research_results.get("sources", []),
111 | }
112 | )
113 |
114 | return {
115 | "intent": "SEARCH",
116 | "response": answer,
117 | "sources": research_results.get("sources", []),
118 | }
119 | except Exception as e:
120 | return {"error": str(e)}
121 |
122 | # 4. Default: regular chat with full conversation history
123 | reply = generate_chat_reply(self.state.conversation_history, user_message)
124 | self.state.conversation_history.append(
125 | {"input": user_message, "response": reply, "type": "chat"}
126 | )
127 |
128 | return {"intent": "CHAT", "response": reply, "token_usage": 0}
129 |
130 | def start_new_chat(self):
131 | """Start a new chat session, clearing all history and state."""
132 | self.state = ChatState()
133 | self.session_id = None
134 | real_time_listener.reset_session()
135 |
136 | # ---------------------- Utility helpers ------------------
137 | def is_session_active(self) -> bool:
138 | return not self.state.session_ended
139 |
140 | def get_conversation_history(self) -> list:
141 | return self.state.conversation_history
142 |
143 | def get_session_id(self) -> str:
144 | return self.session_id or "no-session"
145 |
146 |
147 | # Factory expected by the rest of this module
148 | def create_chatbot() -> ChatbotSession:
149 | return ChatbotSession()
150 |
151 | app = FastAPI()
152 |
153 | # Add CORS for frontend
154 | app.add_middleware(
155 | CORSMiddleware,
156 | allow_origins=["*"], # Allow all origins for production
157 | allow_credentials=True,
158 | allow_methods=["*"],
159 | allow_headers=["*"],
160 | )
161 |
162 |
163 | class AGUIFlowAdapter:
164 | def __init__(self):
165 | self.flow = create_chatbot()
166 |
167 | def _format_research_content(self, content: str) -> str:
168 | """Format research content with clean, professional formatting"""
169 | if not content:
170 | return content
171 |
172 | # Clean up the content first
173 | content = content.strip()
174 |
175 | # Split into paragraphs
176 | paragraphs = content.split('\n\n')
177 | formatted_paragraphs = []
178 |
179 | for paragraph in paragraphs:
180 | paragraph = paragraph.strip()
181 | if not paragraph:
182 | continue
183 |
184 | # Handle bullet points that start with •
185 | if paragraph.startswith('•'):
186 | # Split multiple bullet points in the same paragraph
187 | bullets = [line.strip() for line in paragraph.split('•') if line.strip()]
188 | for bullet in bullets:
189 | bullet = bullet.strip()
190 | if bullet:
191 | formatted_paragraphs.append(f"• {bullet}")
192 | continue
193 |
194 | # Check for short paragraphs that might be headers
195 | if (len(paragraph) < 80 and
196 | not paragraph.endswith('.') and
197 | not paragraph.endswith('!') and
198 | not paragraph.endswith('?') and
199 | not paragraph.startswith('In ') and
200 | not paragraph.startswith('The ') and
201 | not paragraph.startswith('This ')):
202 | formatted_paragraphs.append(f"## {paragraph}")
203 | continue
204 |
205 | # Regular paragraphs - keep them clean
206 | formatted_paragraphs.append(paragraph)
207 |
208 | return '\n\n'.join(formatted_paragraphs)
209 |
210 | def _emphasize_key_terms(self, text: str) -> str:
211 | """Simple emphasis for key terms - kept for compatibility"""
212 | return text
213 |
214 | async def process_message(self, user_message: str, conversation_history: List[Dict[str, str]] = None):
215 | """Process message through our unified chatbot flow and emit real-time events"""
216 |
217 | # Start event
218 | yield self._create_event("RUN_STARTED", {
219 | "status": "processing",
220 | "message": f"Processing: {user_message}"
221 | })
222 |
223 | # Reset the listener for new execution
224 | real_time_listener.reset_session()
225 |
226 | # Start the flow execution in a separate task
227 | flow_task = asyncio.create_task(self._run_flow_message(user_message, conversation_history))
228 |
229 | # Track processed events to avoid duplicates
230 | processed_events = set()
231 |
232 | try:
233 | # Monitor for events while the flow is running
234 | while not flow_task.done():
235 | # Check for new events
236 | events = real_time_listener.get_events_realtime()
237 | for event in events:
238 | # Create a unique identifier for this event
239 | event_id = f"{event['type']}-{event['timestamp']}"
240 | if event_id not in processed_events:
241 | processed_events.add(event_id)
242 | yield self._create_ag_ui_event(event)
243 |
244 | # Minimal delay to prevent CPU spinning but allow immediate streaming
245 | await asyncio.sleep(0.01)
246 |
247 | # Get the flow result
248 | result = await flow_task
249 |
250 | # Stream any remaining events
251 | events = real_time_listener.get_events_realtime()
252 | for event in events:
253 | event_id = f"{event['type']}-{event['timestamp']}"
254 | if event_id not in processed_events:
255 | processed_events.add(event_id)
256 | yield self._create_ag_ui_event(event)
257 |
258 | if "error" in result:
259 | yield self._create_event("TEXT_MESSAGE_DELTA", {
260 | "content": f"❌ Error: {result['error']}"
261 | })
262 | else:
263 | # Determine how to format based on intent
264 | intent = result.get("intent", "CHAT")
265 | response = result.get("response", "")
266 |
267 | if intent == "SEARCH":
268 | # Format research response
269 | formatted_content = self._format_research_content(response)
270 | yield self._create_event("TEXT_MESSAGE_DELTA", {
271 | "content": formatted_content
272 | })
273 |
274 | # Send sources if available
275 | sources = result.get("sources", [])
276 | if sources:
277 | # Handle both old string format and new SourceInfo format
278 | formatted_sources = []
279 | for source in sources[:5]:
280 | if isinstance(source, str):
281 | # Old format - convert to new format
282 | formatted_sources.append({
283 | "url": source,
284 | "title": self._extract_domain(source),
285 | "image_url": None,
286 | "snippet": None
287 | })
288 | elif hasattr(source, 'url'):
289 | # New SourceInfo format
290 | formatted_sources.append({
291 | "url": source.url,
292 | "title": source.title or self._extract_domain(source.url),
293 | "image_url": getattr(source, 'image_url', None),
294 | "snippet": getattr(source, 'snippet', None)
295 | })
296 |
297 | yield self._create_event("SOURCES_UPDATE", {
298 | "sources": formatted_sources
299 | })
300 | else:
301 | # Regular chat response
302 | yield self._create_event("TEXT_MESSAGE_DELTA", {
303 | "content": response
304 | })
305 |
306 | except Exception as e:
307 | # Cancel the flow task if it's still running
308 | if not flow_task.done():
309 | flow_task.cancel()
310 | yield self._create_event("TEXT_MESSAGE_DELTA", {
311 | "content": f"❌ Unexpected error: {str(e)}"
312 | })
313 |
314 | # Finish event
315 | yield self._create_event("RUN_FINISHED", {
316 | "status": "complete"
317 | })
318 |
319 | async def _run_flow_message(self, user_message: str, conversation_history: List[Dict[str, str]] = None):
320 | """Run the flow message processing in executor"""
321 | def process_flow():
322 | try:
323 | # Use our simplified flow's process_message method
324 | return self.flow.process_message(user_message, conversation_history)
325 | except Exception as e:
326 | return {"error": str(e)}
327 |
328 | loop = asyncio.get_event_loop()
329 | return await loop.run_in_executor(None, process_flow)
330 |
331 | def _create_event(self, event_type: str, data: Dict[str, Any]):
332 | """Create AG-UI event"""
333 | return {
334 | "type": event_type,
335 | "data": data,
336 | "timestamp": datetime.now().isoformat()
337 | }
338 |
339 | def _create_ag_ui_event(self, stream_event: Dict[str, Any]):
340 | """Convert real-time listener event to AG-UI format"""
341 | event_type_mapping = {
342 | "AGENT_STARTED": "AGENT_STATUS",
343 | "AGENT_FINISHED": "AGENT_STATUS",
344 | "AGENT_ERROR": "AGENT_ERROR",
345 | "TASK_FAILED": "TASK_ERROR",
346 | "TOOL_STARTED": "TOOL_USAGE",
347 | "TOOL_COMPLETED": "TOOL_USAGE",
348 | "TOOL_ERROR": "TOOL_ERROR",
349 | }
350 |
351 | ag_ui_type = event_type_mapping.get(stream_event["type"], "EXECUTION_STATUS")
352 |
353 | # Special handling for streaming chunks
354 | if stream_event["type"] == "LLM_STREAM_CHUNK":
355 | return {
356 | "type": "TEXT_MESSAGE_DELTA",
357 | "data": {
358 | "content": stream_event["data"]["chunk"]
359 | },
360 | "timestamp": stream_event["timestamp"]
361 | }
362 |
363 | return {
364 | "type": ag_ui_type,
365 | "data": stream_event["data"],
366 | "timestamp": stream_event["timestamp"]
367 | }
368 |
369 | def _extract_domain(self, url: str) -> str:
370 | """Extract a clean domain name from URL"""
371 | try:
372 | from urllib.parse import urlparse
373 | parsed = urlparse(url)
374 | domain = parsed.netloc
375 | # Remove www. if present
376 | if domain.startswith('www.'):
377 | domain = domain[4:]
378 | return domain.capitalize()
379 | except:
380 | return "Source"
381 |
382 |
383 |
384 | # Global adapter
385 | adapter = AGUIFlowAdapter()
386 |
387 | # Root endpoint
388 | @app.get("/")
389 | async def root():
390 | """Root endpoint"""
391 | return {
392 | "message": "AG-UI CrewAI Research Assistant API",
393 | "version": "1.0.0",
394 | "status": "running",
395 | "endpoints": {
396 | "health": "/health",
397 | "token": "/token",
398 | "agent": "/agent",
399 | "docs": "/docs"
400 | }
401 | }
402 |
403 | @app.get("/health")
404 | async def health_check():
405 | """Health check endpoint"""
406 | return {"status": "healthy", "message": "Server is running"}
407 |
408 | # Authentication endpoints
409 | @app.post("/token", response_model=Token)
410 | async def login_for_access_token(form_data: OAuth2PasswordRequestForm = Depends()):
411 | """Login endpoint to get access token - creates permanent token for Railway deployment"""
412 | user = authenticate_user(fake_users_db, form_data.username, form_data.password)
413 | if not user:
414 | raise HTTPException(
415 | status_code=status.HTTP_401_UNAUTHORIZED,
416 | detail="Incorrect username or password",
417 | headers={"WWW-Authenticate": "Bearer"},
418 | )
419 |
420 | # Create permanent token (no expiration)
421 | access_token = create_access_token(data={"sub": user.username}, expires_delta=None)
422 | return {"access_token": access_token, "token_type": "bearer"}
423 |
424 | @app.get("/users/me", response_model=User)
425 | async def read_users_me(current_user: User = Depends(get_current_active_user)):
426 | """Get current user information"""
427 | return current_user
428 |
429 | @app.post("/agent")
430 | async def agent_endpoint(request: Dict[str, Any], current_user: User = Depends(get_current_active_user)):
431 | """Main AG-UI endpoint with real-time event streaming"""
432 |
433 | messages = request.get("messages", [])
434 | if not messages:
435 | return {"error": "No messages"}
436 |
437 | user_message = messages[-1].get("content", "")
438 | if not user_message:
439 | return {"error": "Empty message"}
440 |
441 | # Convert frontend conversation history to backend format
442 | conversation_history = []
443 | for msg in messages[:-1]: # All messages except the current one
444 | if msg.get("role") == "user":
445 | conversation_history.append({
446 | "input": msg.get("content", ""),
447 | "response": "", # Will be filled by next assistant message
448 | "type": "chat"
449 | })
450 | elif msg.get("role") == "assistant":
451 | # Update the last conversation turn with the assistant's response
452 | if conversation_history:
453 | conversation_history[-1]["response"] = msg.get("content", "")
454 |
455 | async def event_stream():
456 | async for event in adapter.process_message(user_message, conversation_history):
457 | yield f"data: {json.dumps(event)}\n\n"
458 | yield "data: [DONE]\n\n"
459 |
460 | return StreamingResponse(
461 | event_stream(),
462 | media_type="text/event-stream"
463 | )
464 |
465 | @app.get("/health")
466 | async def health():
467 | return {"status": "ok"}
468 |
469 | @app.get("/flow/status")
470 | async def flow_status(current_user: User = Depends(get_current_active_user)):
471 | """Get current flow status including real-time event statistics"""
472 | return {
473 | "session_active": adapter.flow.is_session_active(),
474 | "conversation_count": len(adapter.flow.get_conversation_history()),
475 | "real_time_status": real_time_listener.get_session_status()
476 | }
477 |
478 | @app.get("/flow/events")
479 | async def get_pending_events(current_user: User = Depends(get_current_active_user)):
480 | """Get any pending real-time events"""
481 | return {
482 | "events": real_time_listener.get_events_realtime(),
483 | "session_status": real_time_listener.get_session_status()
484 | }
485 |
486 | @app.post("/flow/reset")
487 | async def reset_flow(current_user: User = Depends(get_current_active_user)):
488 | """Reset the flow and start a new chat session"""
489 | adapter.flow.start_new_chat()
490 | return {"status": "reset", "message": "New chat session started"}
491 |
492 | @app.post("/flow/new-chat")
493 | async def start_new_chat(current_user: User = Depends(get_current_active_user)):
494 | """Start a new chat session, clearing all history"""
495 | adapter.flow.start_new_chat()
496 | return {
497 | "status": "new_chat",
498 | "message": "New chat session started",
499 | "session_id": adapter.flow.get_session_id()
500 | }
501 |
502 | if __name__ == "__main__":
503 | import uvicorn
504 | uvicorn.run(app, host="0.0.0.0", port=8000)
--------------------------------------------------------------------------------
/frontend/src/components/ChatInterface.tsx:
--------------------------------------------------------------------------------
1 | "use client"
2 |
3 | import { useState, useRef, useEffect, useCallback } from "react"
4 | import ReactMarkdown from 'react-markdown'
5 | import remarkGfm from 'remark-gfm'
6 | import rehypeRaw from 'rehype-raw'
7 | import { useToken } from '../contexts/TokenContext'
8 |
9 | interface Source {
10 | url: string
11 | title: string
12 | image_url?: string
13 | snippet?: string
14 | }
15 |
16 | interface Message {
17 | id: string
18 | content: string
19 | role: "user" | "assistant"
20 | timestamp: Date
21 | sources?: Source[]
22 | isSearching?: boolean
23 | }
24 |
25 | interface ChatState {
26 | processing: boolean
27 | currentAction: string
28 | conversationHistory: unknown[]
29 | sessionEnded?: boolean
30 | lastEventUpdate?: number
31 | }
32 |
33 | interface ExecutionEvent {
34 | type: string
35 | data: {
36 | message: string
37 | agent_role?: string
38 | tool_name?: string
39 | model?: string
40 | query?: string
41 | status?: string
42 | crew_name?: string
43 | execution_time?: number
44 | token_usage?: {
45 | total_tokens?: number
46 | prompt_tokens?: number
47 | completion_tokens?: number
48 | }
49 | }
50 | timestamp: string
51 | agent_id?: string
52 | session_id?: string
53 | }
54 |
55 | // Utility function to safely handle URLs
56 | const getSafeUrl = (url: string) => {
57 | try {
58 | new URL(url);
59 | return url;
60 | } catch {
61 | return '#';
62 | }
63 | }
64 |
65 |
66 |
67 | const isValidUrl = (url: string) => {
68 | try {
69 | new URL(url);
70 | return true;
71 | } catch {
72 | return false;
73 | }
74 | }
75 |
76 | const extractDomain = (url: string) => {
77 | try {
78 | const domain = new URL(url).hostname;
79 | // Remove www. if present
80 | return domain.replace(/^www\./, '');
81 | } catch {
82 | return 'Source';
83 | }
84 | }
85 |
86 | export function ChatInterface() {
87 | const { token } = useToken()
88 | const [messages, setMessages] = useState
27 |
46 |
47 | {/* Research Results Section */}
48 | {results ? (
49 |
28 |
37 | {results && (
38 |
29 |
32 |
33 | 34 | Research Results 35 |
36 |
39 |
40 |
41 | {results.sources?.length || 0} sources found
42 |
43 |
44 | )}
45 |
50 | {/* Summary Card */}
51 |
173 | ) : (
174 |
52 |
66 |
67 | {/* Enhanced Sources Section */}
68 | {results.sources && results.sources.length > 0 && (
69 |
53 |
62 |
54 |
57 |
58 | 59 | Research Summary 60 |
61 |
63 |
65 | {results.summary}
64 |
70 |
148 | )}
149 |
150 | {/* Citations Section */}
151 | {results.citations && results.citations.length > 0 && (
152 |
71 |
85 |
147 |
72 |
84 |
73 |
76 |
77 | 78 | Sources 79 |
80 | 81 | {results.sources.length} found 82 | 83 |
153 |
171 | )}
172 |
154 |
163 |
155 |
158 |
159 | 160 | Citations ({results.citations.length}) 161 |
162 |
164 | {results.citations.map((citation, index) => (
165 |
170 |
166 |
168 | ))}
169 | {citation}
167 |
175 |
189 | )}
190 |
191 | {/* Conversation History */}
192 | {conversations && conversations.length > 0 && (
193 |
176 |
188 |
177 |
183 |
178 |
181 |
182 | No research results yet
184 |185 | Start a conversation to see research results and insights here 186 |
187 |
194 |
234 | )}
235 |
195 |
204 |
196 |
199 |
200 | 201 | Recent Conversations 202 |
203 |
205 | {conversations.slice(-5).map((conv, index) => (
206 |
233 |
207 |
231 | ))}
232 |
208 |
229 |
209 |
220 | {conv.sources && (
221 |
214 | {conv.type === "research_enhanced" ? "R" : "C"}
215 |
216 |
217 | {conv.type === "research_enhanced" ? "Research Chat" : "Regular Chat"}
218 |
219 |
222 |
223 |
224 | {conv.sources.length} sources
225 |
226 |
227 | )}
228 | {conv.input}
230 |
349 | {/* Header */}
350 |
351 |
386 |
387 | {/* Chat Messages Area */}
388 |
739 | )
740 | }
741 |
742 | function ChatInput({
743 | onSend,
744 | isLoading
745 | }: {
746 | onSend: (content: string) => void
747 | isLoading: boolean
748 | }) {
749 | const [content, setContent] = useState("")
750 | const inputRef = useRef
352 |
385 |
353 |
366 |
367 | {/* Action Buttons */}
368 |
354 |
358 |
359 |
360 |
365 | 361 | AI Research Assistant 362 |
363 |CrewAI + AG-UI Protocol Implementation
364 |
369 | {/* New Chat Button - Only show when there are messages */}
370 | {messages.length > 0 && (
371 |
381 | )}
382 |
383 |
384 |
389 | {messages.length === 0 ? (
390 | // Welcome Screen
391 |
693 |
694 | {/* Chat Input */}
695 |
702 |
703 | {/* Confirmation Dialog */}
704 | {showClearDialog && (
705 |
392 |
461 | ) : (
462 | // Chat Messages
463 |
393 |
460 |
394 |
442 |
443 | {/* Quick Actions */}
444 | 395 | AI Research Assistant 396 |
397 |398 | A cutting-edge implementation showcasing CrewAI for 399 | orchestrated AI agents and AG-UI Protocol for 400 | real-time streaming interactions. 401 |
402 | 403 | {/* Technical Badges */} 404 |
405 |
441 |
406 |
416 |
407 |
413 | CrewAI
414 |
415 |
417 |
424 |
418 |
421 | AG-UI Protocol
422 |
423 |
425 |
432 |
426 |
429 | Real-time Streaming
430 |
431 |
433 |
440 |
434 |
437 | Source Attribution
438 |
439 |
445 |
458 |
459 |
464 | {messages.map((message, index) => (
465 |
691 | )}
692 |
466 |
648 | ))}
649 |
650 | {/* Real-time Execution Status - Shows all internal process steps */}
651 | {isLoading && eventMessages.length > 0 && (
652 |
471 |
647 |
472 | {/* Enhanced Sources Display */}
473 | {message.role === 'assistant' && !message.isSearching && message.content && message.sources && message.sources.length > 0 && (
474 |
646 |
475 |
547 | )}
548 |
549 | {/* Real-time execution status - shown instead of generic "Searching..." */}
550 | {message.role === 'assistant' && chatState.processing && index === messages.length - 1 && (
551 |
476 |
488 |
546 |
477 |
487 |
478 |
481 |
482 | Sources
483 |
484 | {message.sources.length} found
485 |
486 |
552 | {executionEvents.length > 0 ? (
553 | executionEvents.slice(-3).map((event, eventIndex) => (
554 |
574 | )}
575 |
576 | {/* Enhanced message content */}
577 | {message.content && (
578 |
559 |
560 |
561 | {event.data.message}
562 |
563 |
564 | ))
565 | ) : (
566 |
567 |
568 |
569 | {message.isSearching ? "Initializing research..." : ""}
570 |
571 |
572 | )}
573 |
579 |
591 |
592 | {children}
593 |
594 | ),
595 | strong: ({children}) => {children},
596 | em: ({children}) => {children},
597 | code: ({children}) =>
624 | {children}
625 |
626 | ),
627 | td: ({children}) => (
628 |
629 | {children}
630 |
631 | ),
632 | // Handle horizontal rules
633 | hr: () => (
634 |
635 | ), 636 | // Handle h4 headers 637 | h4: ({children}) =>
643 |
644 | )}
645 | {children}
, 584 | h2: ({children}) =>{children}
, 585 | h3: ({children}) =>{children}
, 586 | p: ({children}) =>{children}
, 587 | ul: ({children}) =>- {children}
- {children}
{children},
598 | pre: ({children}) => {children},
599 | blockquote: ({children}) => (
600 | 601 | {children} 602 |603 | ), 604 | a: ({href, children}) => ( 605 | 611 | {children} 612 | 613 | ), 614 | // Handle tables 615 | table: ({children}) => ( 616 |
617 |
618 | {children}
619 |
620 |
621 | ),
622 | th: ({children}) => (
623 | 635 | ), 636 | // Handle h4 headers 637 | h4: ({children}) =>
{children}
, 638 | 639 | }} 640 | > 641 | {message.content.replace(/##\s*##/g, '##')} 642 |
653 | {eventMessages.map((message, index) => (
654 |
677 | )}
678 |
679 | {/* Loading Spinner - Shows when loading but no specific event messages */}
680 | {isLoading && eventMessages.length === 0 && (
681 |
665 |
670 | {message}
671 | {index === eventMessages.length - 1 && (
672 |
673 | )}
674 |
675 | ))}
676 |
682 |
687 | )}
688 |
689 |
690 |
683 |
684 |
685 |
686 |
706 |
737 | )}
738 |
707 |
736 |
708 |
715 |
709 |
712 |
713 | Start New Chat?
714 |716 | This will clear your current conversation with {messages.length} messages. 717 |
718 |719 | Are you sure you want to start fresh? 720 |
721 |
722 |
728 |
734 |
735 |
767 |
797 | )
798 | }
--------------------------------------------------------------------------------
768 | setContent(e.target.value)}
773 | onKeyPress={handleKeyPress}
774 | placeholder="Ask me anything..."
775 | disabled={isLoading}
776 | className="w-full enhanced-input p-4 rounded-2xl text-foreground placeholder-muted-foreground disabled:opacity-50 transition-all duration-300"
777 | />
778 |
779 |
780 |
796 |