How kimthangg/neura_assistant works
Project type and purpose
• Neura is a full-stack AI personal assistant: web frontend (chat UI) + Python/Flask backend.
• It orchestrates natural-language requests to Google Calendar/Gmail APIs and an LLM service, persisting conversation data in MongoDB.
File structure to high-level components
• Frontend (app/static, app/templates) → HTML/CSS/JS chat UI served by Flask.
• Web Server (app/app.py) → Flask app, defines /chat and /execute endpoints.
• Bot Module (bot/)
• agent/ → Intent‐driven “agents” (agent_calendar, agent_gmail, agent_manager)
• handler/ → Message ingestor & retrieval logic
• agent_intent/ → Prompt & tool definitions for intent extraction
• Feature Plugins (features/) → Domain-specific handlers/prompts/tools
• calendar_features/*
• gmail_features/*
• schedule_features
• Services (services/)
• llm/ → LLM config (e.g., Gemini 2.0 calls)
• embedding_model/ → Embedding logic for retrieval
• Data Access (db/) → MongoDB managers (chat_manager, email_manager, schedule_manager, etc.)
• Configuration (config/) → Google API credentials and auth logic
• Utilities & Tests (utils/, tests/)
Refine with README insights
• Two primary layers: Frontend (browser chat) ↔ Backend (Flask + Bot Module).
• External dependencies: Google Calendar API, Gmail API, Gemini 2.0 (LLM), MongoDB.
Relationships & data flows
1. User types message → Web UI
2. Web UI → POST JSON → Flask /chat
3. Flask Handler → Agent Manager
4. Agent Manager → selects Agent → invokes feature prompt/tools → calls LLM Service
5. LLM response → Agent processes → may call external API (Calendar/Gmail)
6. External API → result → Agent formats reply → Handler
7. Handler → stores conversation via db/chat_manager → returns JSON to UI
8. UI displays reply; on “Execute” button click → Flask /execute → repeat steps for real action
Architectural patterns & design principles
• Layered architecture: Presentation → API layer (Flask) → Business logic (Bot Module) → Data layer (DB)
• Plug-in module pattern for features (each calendar/email feature lives in its own folder)
• Separation of concerns: intent extraction, routing, API integration, data persistence
• Single Responsibility: one class per API/feature
Technologies, frameworks & libraries
• Frontend: HTML5, CSS3, vanilla JavaScript
• Backend: Python 3.10+, Flask
• LLM integration: custom wrapper in services/llm (Gemini 2.0)
• Database: MongoDB (accessed via db/db_manager and specialized managers)
• Authentication: Google OAuth2 (config/auth_gg.py)
• Testing: pytest (tests/…)