Spaces:
Sleeping
Sleeping
| # 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 |