Notion MCP Server V2

# 🤖 Complete System Explanation: Chatbot_Agentic_v3.py ## 📋 **Project Overview** Your project is a **sophisticated AI-powered chatbot system** that combines multiple advanced technologies to create an intelligent assistant capable of managing conversations, personal information, and Notion workspace interactions. Think of it as a **"Swiss Army knife" for AI assistants** - it can chat naturally, remember things about you, search through your history, and work with your Notion workspace. --- ## 🏗️ **Architecture Overview** ``` ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ User Interface │───▶│ Chatbot Agentic V3 │───▶│ Multiple Systems │ │ (Terminal/UI) │ │ (Main Controller) │ │ (Notion, DB, etc) │ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Core Components │ │ ┌─────────────┐ ┌─────────────────┐ │ │ │ OpenAI │ │ Notion │ │ │ │ Agent │ │ Integration │ │ │ └─────────────┘ └─────────────────┘ │ │ ┌─────────────┐ ┌─────────────────┐ │ │ │ Memory │ │ Vector DB │ │ │ │ System │ │ (Embeddings) │ │ │ └─────────────┘ └─────────────────┘ │ └─────────────────────────────────────────┘ ``` --- ## 🎯 **What This Project Does** ### **1. Intelligent Conversation Management** - **Natural Language Processing**: Uses OpenAI's GPT models to understand and respond to user queries - **Context Awareness**: Maintains conversation history and can reference previous discussions - **Function Calling**: Automatically decides when to use tools/functions based on user needs ### **2. Personal Information Management** - **User Profiles**: Stores and manages user information (name, location, interests, etc.) - **Memory System**: Remembers important details about users across conversations - **Search Capability**: Can search through conversation history to find relevant information ### **3. Notion Workspace Integration** - **Complete Notion Control**: Can search, read, create, and modify Notion pages - **Analytics**: Provides insights about your Notion workspace usage - **Bulk Operations**: Can handle multiple Notion operations at once ### **4. Advanced Memory Systems** - **Vector Database**: Stores conversation embeddings for semantic search - **SQL Database**: Stores structured user information and chat history - **Smart Summarization**: Automatically summarizes long conversations --- ## 🔧 **Key Technologies & Approaches** ### **1. OpenAI Function Calling Pattern** ```python # This is the "brain" of your system response = self.client.chat.completions.create( model=self.chat_model, messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": user_message}], functions=self.agent_functions, # ← Available tools function_call="auto", # ← Let AI decide when to use tools temperature=self.cfg.temperature ) ``` **What this does:** - Sends your message to OpenAI's GPT - Includes a list of available functions (tools) - GPT decides if it needs to use any tools - If yes, it calls the appropriate function - If no, it responds directly ### **2. Notion ServerV2 Integration Pattern** ```python # Your chatbot has 15+ Notion functions available if self.notion_client: self.agent_functions.extend([ # Core Operations self.utils.jsonschema(self.notion_search_content), self.utils.jsonschema(self.notion_read_page), self.utils.jsonschema(self.notion_create_page), # ... and many more ]) ``` **What this does:** - Integrates complete Notion functionality - Makes Notion operations available as "functions" to the AI - AI can automatically decide when to use Notion based on user queries ### **3. Function Chaining Pattern** ```python # Smart chaining for complex tasks if function_name == "notion_search_content" and "add content" in user_message: chat_state = "thinking" # Continue conversation for content addition chaining_guidance = "You found the page, now add the requested content..." ``` **What this does:** - Recognizes when a task requires multiple steps - Keeps the conversation going until the complete task is finished - Example: "Search for my project page and add a todo list" → searches first, then adds todos ### **4. Memory Management Pattern** ```python # Multiple memory systems working together self.chat_history_manager # Stores conversation history self.vector_db_manager # Stores embeddings for semantic search self.user_manager # Stores user profile information ``` **What this does:** - **Chat History**: Remembers what you talked about recently - **Vector Database**: Can search through all conversations semantically - **User Profile**: Remembers personal details about you --- ## 🚀 **How It Works in Practice** ### **Example 1: Simple Question** ``` User: "What's the weather like?" System: → Direct response (no functions needed) Chatbot: "I don't have access to current weather data..." ``` ### **Example 2: Notion Task** ``` User: "Search for my project planning pages in Notion" System: → Detects Notion task → Calls notion_search_content Chatbot: "I found 3 pages about project planning: ..." ``` ### **Example 3: Complex Chaining Task** ``` User: "Find my meeting notes page and add today's agenda" System: → Calls notion_search_content → Finds page → Calls notion_add_paragraph Chatbot: "I found your meeting notes page and added today's agenda..." ``` ### **Example 4: Memory Search** ``` User: "What did we discuss about my work project last week?" System: → Calls search_vector_db → Searches conversation history Chatbot: "Last week you mentioned working on the mobile app redesign..." ``` --- ## 🎨 **Different Implementation Approaches** ### **1. Hybrid Architecture Approach** - **What it is**: Combines multiple systems (OpenAI, Notion, databases) into one chatbot - **Why it's smart**: Each system does what it does best - **Your implementation**: Perfect example of this pattern ### **2. Function-as-a-Service Pattern** - **What it is**: Each capability is a separate function that can be called independently - **Benefits**: Modular, testable, extensible - **Your implementation**: 15+ Notion functions + user management functions ### **3. Smart Context Management** - **What it is**: System maintains context across function calls - **Your innovation**: Function chaining that recognizes multi-step tasks - **Example**: Search → Read → Modify workflows ### **4. Graceful Degradation** - **What it is**: System continues working even if some parts fail - **Your implementation**: Continues without Notion if token missing - **Benefits**: Robust, user-friendly --- ## 🎯 **What Makes Your Implementation Special** ### **1. Comprehensive Integration** - **Not just a chatbot**: Full workspace management system - **Not just Notion integration**: Complete analytics and bulk operations - **Not just memory**: Multiple memory systems working together ### **2. Smart Function Chaining** - **Recognizes complex tasks**: Automatically continues conversations for multi-step operations - **Context aware**: Understands when a task isn't complete - **Efficient**: Minimizes user interaction needed ### **3. Production-Ready Architecture** - **Error handling**: Comprehensive error management - **Fallback systems**: Multiple backup plans - **Scalable**: Easy to add new functions and capabilities ### **4. User-Centric Design** - **Natural language**: Users don't need to learn commands - **Intelligent**: AI decides what tools to use - **Personalized**: Remembers user preferences and history --- ## 📊 **Core Components Deep Dive** ### **1. Main Chatbot Class (`chatbot_agentic_v3.py`)** ```python class Chatbot: def __init__(self): # Initialize OpenAI client self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) # Setup configuration self.cfg = Config() # Initialize memory systems self.chat_history_manager = ChatHistoryManager(...) self.vector_db_manager = VectorDBManager(...) self.user_manager = UserManager(...) # Initialize Notion integration if self.notion_token: self.notion_client = Client(auth=self.notion_token) self.notion_core = CoreOperations(self.notion_client) # ... more Notion components ``` **Key Features:** - **1546 lines of code**: Comprehensive implementation - **15+ Notion functions**: Complete workspace management - **Smart initialization**: Graceful degradation if components fail - **Modular design**: Easy to extend and maintain ### **2. Function Execution Engine** ```python def execute_function_call(self, function_name: str, function_args: dict): """Routes function calls to appropriate handlers""" try: # Vector DB and User Management if function_name == "search_vector_db": return self.vector_db_manager.search_vector_db(**function_args) # Notion Operations elif function_name == "notion_search_content": return self.notion_search_content(**function_args) # ... handle all other functions except Exception as e: return "Function call failed.", f"Error: {str(e)}" ``` **Key Features:** - **Centralized routing**: All function calls go through one place - **Error handling**: Comprehensive error management - **Type safety**: Proper argument handling - **Extensible**: Easy to add new functions ### **3. Conversation Flow Manager** ```python def chat(self, user_message: str) -> str: """Main conversation loop with function chaining""" function_call_count = 0 chat_state = "thinking" while chat_state != "finished": # Send to OpenAI with available functions response = self.client.chat.completions.create(...) # Check if function call needed if response.choices[0].message.function_call: # Execute function and continue if chaining needed function_call_state, result = self.execute_function_call(...) # Smart chaining logic if self.needs_chaining(function_name, user_message): chat_state = "thinking" # Continue else: chat_state = "finished" # Done ``` **Key Features:** - **Smart chaining**: Recognizes multi-step tasks - **Context preservation**: Maintains conversation state - **Function limits**: Prevents infinite loops - **Memory updates**: Automatically updates memory systems --- ## 🔍 **Memory Systems Explained** ### **1. Chat History Manager** ```python class ChatHistoryManager: def __init__(self, sql_manager, user_id, session_id, client, model, max_tokens): self.sql_manager = sql_manager self.user_id = user_id self.session_id = session_id # ... initialization ``` **Purpose:** - Stores conversation history in SQL database - Manages conversation summaries - Handles long conversation truncation - Provides conversation context to AI ### **2. Vector Database Manager** ```python class VectorDBManager: def __init__(self, cfg): self.client = chromadb.PersistentClient(path=cfg.vectordb_dir) self.collection = self.client.get_or_create_collection(cfg.collection_name) # ... initialization ``` **Purpose:** - Stores conversation embeddings for semantic search - Enables "What did we discuss about X?" queries - Provides context-aware search capabilities - Learns from conversation patterns ### **3. User Manager** ```python class UserManager: def __init__(self, sql_manager): self.sql_manager = sql_manager # ... load user profile ``` **Purpose:** - Stores structured user information - Manages user preferences and settings - Provides personalization capabilities - Handles user profile updates --- ## 🔗 **Notion Integration Architecture** ### **1. Core Operations** ```python class CoreOperations: def __init__(self, notion_client): self.notion = notion_client self.utils = NotionUtils() async def search_pages(self, query: str, page_size: int = 10): """Search for pages in Notion workspace""" # Implementation... ``` **Capabilities:** - Search pages and databases - Read complete page content - Create new pages with content - List workspace pages and databases ### **2. Analytics Operations** ```python class AnalyticsOperations: def __init__(self, notion_client): self.notion = notion_client async def get_workspace_analytics(self): """Get comprehensive workspace analytics""" # Implementation... ``` **Capabilities:** - Workspace usage statistics - Content analysis and patterns - Activity tracking and insights - Performance metrics ### **3. Update Operations** ```python class UpdateOperations: def __init__(self, notion_client): self.notion = notion_client async def add_paragraph(self, page_id: str, content: str): """Add paragraph to page""" # Implementation... ``` **Capabilities:** - Add paragraphs, headings, bullets - Create todo lists and tasks - Update existing content - Bulk content operations --- ## 📈 **Advanced Features** ### **1. Function Chaining Intelligence** ```python # Detects when tasks require multiple steps if function_name == "notion_search_content" and "add content" in user_message: chat_state = "thinking" # Continue conversation chaining_guidance = "🔄 CONTENT ADDITION TASK DETECTED: You found the page, now add content..." ``` **Benefits:** - **Seamless workflows**: Users don't need to make multiple requests - **Context awareness**: System understands task complexity - **Efficient interaction**: Minimizes back-and-forth - **Smart completion**: Knows when tasks are finished ### **2. Error Handling & Fallbacks** ```python # Graceful degradation if not self.notion_token: print("⚠️ Notion token not found. Notion functionality will be disabled.") self.notion_client = None else: # Initialize Notion components self.notion_client = Client(auth=self.notion_token) ``` **Benefits:** - **Robust operation**: Continues working even if parts fail - **User-friendly**: Clear error messages - **Fallback systems**: Multiple backup plans - **Production ready**: Handles real-world scenarios ### **3. Smart Content Management** ```python def notion_add_smart_content(self, page_identifier: str, user_request: str): """Intelligently add content based on user's natural language request""" # Analyzes user request and adds appropriate content type # Handles long content splitting and formatting # Provides detailed feedback ``` **Benefits:** - **Natural language processing**: Understands user intent - **Intelligent formatting**: Automatically handles content structure - **Flexible input**: Accepts page IDs or titles - **Detailed feedback**: Reports what was added --- ## 🎯 **System Capabilities Summary** ### **Core Chatbot Functions** 1. **Natural Language Understanding**: Processes user queries intelligently 2. **Context Management**: Maintains conversation state and history 3. **Function Routing**: Automatically selects appropriate tools 4. **Error Handling**: Comprehensive error management and recovery ### **Memory & Personalization** 1. **User Profiles**: Stores and manages personal information 2. **Conversation History**: Remembers past interactions 3. **Semantic Search**: Finds relevant information from history 4. **Smart Summarization**: Automatically summarizes long conversations ### **Notion Workspace Management** 1. **Complete CRUD Operations**: Create, read, update, delete pages 2. **Advanced Search**: Full-text search across workspace 3. **Analytics & Insights**: Workspace usage and content analysis 4. **Bulk Operations**: Handle multiple operations efficiently ### **Advanced Workflows** 1. **Function Chaining**: Multi-step task automation 2. **Content Intelligence**: Smart content formatting and management 3. **Production Features**: Error handling, fallbacks, scaling 4. **Protocol Support**: MCP implementation for standardization --- ## 🔮 **What This Enables** Your system creates a **"Digital Assistant"** that can: - **Understand** natural language requests - **Remember** personal information and conversation history - **Execute** complex workflows across multiple systems - **Learn** from interactions and improve over time - **Scale** to handle more capabilities as needed This is essentially a **personal AI agent** that bridges the gap between natural language and structured data/actions, making it incredibly powerful for productivity and personal management tasks. --- ## 🚀 **Getting Started** ### **1. Quick Start** ```bash # Setup environment python -m venv venv source venv/bin/activate pip install -r requirements.txt # Configure API keys export OPENAI_API_KEY="your-key" export NOTION_TOKEN="your-token" # Initialize databases python src/prepare_sqldb.py python src/prepare_vectordb.py # Run the chatbot python src/chat_in_terminal.py ``` ### **2. Example Usage** ```python from src.utils.chatbot_agentic_v3 import Chatbot # Initialize chatbot = Chatbot() # Natural language interactions chatbot.chat("What's in my Notion workspace?") chatbot.chat("Create a project planning page with initial structure") chatbot.chat("Search for meeting notes and add today's agenda") chatbot.chat("What did we discuss about the new feature last week?") ``` ### **3. Available Functions** - **15+ Notion Functions**: Complete workspace management - **Memory Functions**: Vector search and user information - **Analytics Functions**: Workspace insights and patterns - **Bulk Operations**: Multiple page operations --- ## 🎯 **Why This Architecture is Powerful** ### **1. Scalability** - Easy to add new functions and capabilities - Modular design allows independent development - Production-ready with proper error handling ### **2. Intelligence** - AI makes decisions about tool usage automatically - Context-aware conversations with memory - Smart task chaining for complex workflows ### **3. User Experience** - Natural language interface requires no command memorization - Intelligent error handling and recovery - Personalized interactions based on user history ### **4. Production Ready** - Comprehensive error handling and logging - Multiple fallback systems for reliability - Scalable architecture for growing needs --- **🎉 This is a complete AI agent system that demonstrates the future of human-computer interaction - natural, intelligent, and incredibly powerful!**