Spaces:
Sleeping
Sleeping
File size: 3,398 Bytes
1d4dc07 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 | # Atlas Chat API - Project Context
## Project Overview
Atlas is a FastAPI-based chat application with web search capabilities and analytics tracking. The system uses Google Gemini AI with combined Brave/DuckDuckGo search integration for enhanced responses.
## Current Implementation Status
### Phase 1 & 2 Complete: Analytics Foundation
- ✅ **MongoDB Integration**: Motor async driver for analytics storage
- ✅ **Session Tracking**: UUID-based session management with HTTP headers
- ✅ **Data Models**: Session, Message, SearchAnalytics with Pydantic validation
- ✅ **Database Collections**: Sessions, messages, search_analytics
- ✅ **Performance Monitoring**: PerformanceTimer context manager
- ✅ **Graceful Fallback**: System works with/without MongoDB connection
### Key Components
#### Core Files
- **app.py**: Main FastAPI application with chat endpoint and analytics integration
- **local_app.py**: Interactive terminal client with session persistence
- **requirements.txt**: Dependencies including motor for MongoDB
#### Analytics Module (`analytics/`)
- **`__init__.py`**: Module exports and clean API
- **`database.py`**: MongoDB connection management with fallback
- **`models.py`**: Pydantic data models (Session, Message, SearchAnalytics)
- **`collectors.py`**: Data collection functions and session management
#### Documentation
- **`analytics-approach.md`**: Technical approach and design decisions
- **`analytics-tasks.md`**: Phased implementation roadmap
### Technical Architecture
#### Session Management
```python
# HTTP header-based session tracking
headers["X-Session-ID"] = session_id
```
#### Analytics Data Flow
1. Client sends request with optional session ID header
2. FastAPI creates/retrieves session
3. Performance timer tracks response time
4. Message analytics stored in MongoDB
5. Session ID returned in response headers
#### Search Integration
- **Combined Search**: Brave API + DuckDuckGo with fallback
- **NLP Processing**: spaCy + RAKE for search term extraction
- **Result Deduplication**: URL-based filtering
- **Timeout Handling**: 12s overall, 8s per engine
### Current Issues to Address
- Type checking errors in `app.py` around search result handling
- Deprecated `@app.on_event` usage (should migrate to lifespan handlers)
- Unused imports and variables
- Error handling for analytics import failures
### Environment Requirements
```
GOOGLE_API_KEY=your_gemini_api_key
BRAVE_API_KEY=your_brave_api_key
MONGODB_URL=mongodb://localhost:27017 # Optional
MONGODB_DATABASE=atlas_analytics # Optional
```
### Next Phase (Phase 3) - Analytics Endpoints
When requested, implement:
- `/analytics/stats` - Session and message statistics
- `/analytics/sessions/{session_id}` - Detailed session data
- Basic analytics dashboard
- Data export functionality
### Git Branch Structure
- **main**: Core chat functionality
- **with-analytics**: Current branch with analytics implementation
### Usage
```bash
# Start API server
python app.py
# Start interactive client
python local_app.py
```
### Key Design Decisions
1. **NoSQL Choice**: MongoDB for flexible analytics schema
2. **Session Persistence**: HTTP headers for stateless API design
3. **Graceful Degradation**: Analytics failures don't break chat functionality
4. **Performance Focus**: Async operations throughout
5. **Privacy by Design**: No sensitive data in analytics logs |