mbxai 2.1.0__tar.gz → 2.1.2__tar.gz

{mbxai-2.1.0 → mbxai-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mbxai
-Version: 2.1.0
+Version: 2.1.2
 Summary: MBX AI SDK
 Project-URL: Homepage, https://www.mibexx.de
 Project-URL: Documentation, https://www.mibexx.de

{mbxai-2.1.0 → mbxai-2.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mbxai"
-version = "2.1.0"
+version = "2.1.2"
 authors = [
     { name = "MBX AI" }
 ]

{mbxai-2.1.0 → mbxai-2.1.2}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="mbxai",
-    version="2.1.0",
+    version="2.1.2",
     author="MBX AI",
     description="MBX AI SDK",
     long_description=open("README.md").read(),

{mbxai-2.1.0 → mbxai-2.1.2}/src/mbxai/__init__.py

@@ -7,7 +7,7 @@ from .openrouter import OpenRouterClient
 from .tools import ToolClient
 from .mcp import MCPClient
 
-__version__ = "2.1.0"
+__version__ = "2.1.2"
 
 __all__ = [
     "AgentClient",

{mbxai-2.1.0 → mbxai-2.1.2}/src/mbxai/agent/client.py

@@ -128,8 +128,10 @@ class AgentClient:
         # Combine conversation history with new messages
         if conversation_history:
             full_messages = conversation_history + messages
+            logger.debug(f"🔗 AI call with {len(conversation_history)} history messages + {len(messages)} new messages = {len(full_messages)} total")
         else:
             full_messages = messages
+            logger.debug(f"🔗 AI call with {len(messages)} messages (no history)")
         return self._ai_client.parse(full_messages, response_format)
 
     def _extract_token_usage(self, response: Any) -> TokenUsage:
@@ -182,36 +184,76 @@ class AgentClient:
 
     def agent(
         self,
-        prompt: str,
-        final_response_structure: Type[BaseModel],
+        prompt: str = None,
+        final_response_structure: Type[BaseModel] = None,
         ask_questions: bool = True,
-        agent_id: str = None
+        agent_id: str = None,
+        answers: AnswerList = None
     ) -> AgentResponse:
         """
         Process a prompt through the agent's thinking process.
 
         Args:
-            prompt: The initial prompt from the user
-            final_response_structure: Pydantic model defining the expected final response format
+            prompt: The prompt from the user (optional if agent_id exists with history)
+            final_response_structure: Pydantic model defining the expected final response format (required for new sessions)
             ask_questions: Whether to ask clarifying questions (default: True)
             agent_id: Optional agent session ID to continue an existing conversation
+            answers: Optional answers to questions (when continuing a conversation with questions)
 
         Returns:
             AgentResponse containing either questions to ask or the final response
+            
+        Raises:
+            ValueError: If neither prompt nor agent_id with history is provided, or if final_response_structure is missing for new sessions
         """
-        # Use provided agent_id or create a new one
-        if agent_id is None:
-            agent_id = str(__import__("uuid").uuid4())
+        # Validate inputs and determine session type
+        is_existing_session = agent_id is not None and agent_id in self._agent_sessions
+        existing_session = self._agent_sessions.get(agent_id, {}) if agent_id else {}
+        conversation_history = existing_session.get("conversation_history", []).copy()
+        
+        # Validation logic
+        if not is_existing_session:
+            # New session - both prompt and final_response_structure are required
+            if not prompt:
+                raise ValueError("Prompt is required when starting a new agent session")
+            if not final_response_structure:
+                raise ValueError("final_response_structure is required when starting a new agent session")
+            
+            # Create new agent_id if not provided
+            if agent_id is None:
+                agent_id = str(__import__("uuid").uuid4())
             logger.info(f"🚀 Starting new agent process (ID: {agent_id}) with prompt: {prompt[:100]}...")
         else:
-            logger.info(f"🔄 Continuing agent process (ID: {agent_id}) with prompt: {prompt[:100]}...")
+            # Existing session - use previous final_response_structure if not provided
+            if not final_response_structure:
+                final_response_structure = existing_session.get("final_response_structure")
+                if not final_response_structure:
+                    raise ValueError("final_response_structure not found in existing session and not provided")
+            
+            # Handle optional prompt for existing sessions
+            if not prompt:
+                # Use conversation history to continue without explicit prompt
+                prompt = "[Continue conversation based on history]"
+                logger.info(f"🔄 Continuing agent process (ID: {agent_id}) without explicit prompt (using history)")
+            else:
+                logger.info(f"🔄 Continuing agent process (ID: {agent_id}) with prompt: {prompt[:100]}...")
         
         # Initialize token summary
         token_summary = TokenSummary()
         
-        # Check if this is a continuing conversation
-        existing_session = self._agent_sessions.get(agent_id, {})
-        conversation_history = existing_session.get("conversation_history", [])
+        if conversation_history:
+            logger.info(f"📜 Agent {agent_id}: Loaded conversation history with {len(conversation_history)} messages")
+        
+        # Store conversation history for AI calls (don't include current prompt yet)
+        history_for_ai = conversation_history.copy()
+        
+        # Add current prompt to full conversation history for session storage
+        conversation_history.append({"role": "user", "content": prompt})
+        
+        # Handle answers provided (skip question generation and process directly)
+        if answers is not None:
+            logger.info(f"📝 Agent {agent_id}: Processing with provided answers, skipping question generation")
+            return self._process_answers_directly(agent_id, prompt, final_response_structure, answers, token_summary, history_for_ai)
         
         # Step 1: Generate questions (if ask_questions is True)
         if ask_questions:
@@ -236,7 +278,7 @@ IMPORTANT: For each question, provide a technical key identifier that:
             messages = [{"role": "user", "content": questions_prompt}]
             
             try:
-                response = self._call_ai_parse(messages, QuestionList, conversation_history)
+                response = self._call_ai_parse(messages, QuestionList, history_for_ai)
                 question_list = self._extract_parsed_content(response, QuestionList)
                 
                 # Extract token usage for question generation
@@ -253,7 +295,8 @@ IMPORTANT: For each question, provide a technical key identifier that:
                         "final_response_structure": final_response_structure,
                         "questions": question_list.questions,
                         "step": "waiting_for_answers",
-                        "token_summary": token_summary
+                        "token_summary": token_summary,
+                        "conversation_history": history_for_ai  # Include history without current prompt
                     }
                     logger.info(f"📋 Agent {agent_id}: Waiting for user answers to {len(question_list.questions)} questions")
                     return agent_response
@@ -263,71 +306,75 @@ IMPORTANT: For each question, provide a technical key identifier that:
         
         # Step 2 & 3: No questions or ask_questions=False - proceed directly
         logger.info(f"⚡ Agent {agent_id}: No questions needed, proceeding directly to processing")
-        return self._process_with_answers(prompt, final_response_structure, [], agent_id, token_summary, conversation_history)
+        return self._process_with_answers(prompt, final_response_structure, [], agent_id, token_summary, history_for_ai)
 
-    def answer_to_agent(self, agent_id: str, answers: AnswerList) -> AgentResponse:
+    def _process_answers_directly(
+        self,
+        agent_id: str,
+        prompt: str,
+        final_response_structure: Type[BaseModel],
+        answers: AnswerList,
+        token_summary: TokenSummary,
+        conversation_history: list[dict[str, Any]]
+    ) -> AgentResponse:
         """
-        Continue an agent session by providing answers to questions.
-
+        Process answers directly without going through question generation.
+        
         Args:
             agent_id: The agent session identifier
-            answers: List of answers to the questions
-
+            prompt: The current prompt
+            final_response_structure: Expected response structure
+            answers: Provided answers
+            token_summary: Current token usage summary
+            conversation_history: Conversation history
+            
         Returns:
             AgentResponse with the final result
-
-        Raises:
-            ValueError: If the agent session is not found or in wrong state
         """
-        if agent_id not in self._agent_sessions:
-            raise ValueError(f"Agent session {agent_id} not found")
-        
-        session = self._agent_sessions[agent_id]
-        if session["step"] != "waiting_for_answers":
-            raise ValueError(f"Agent session {agent_id} is not waiting for answers")
-        
-        # Convert answers to a more usable format and create question-answer pairs
-        answer_dict = {answer.key: answer.answer for answer in answers.answers}
+        # Check if we have a session with questions to match against
+        session = self._agent_sessions.get(agent_id, {})
         questions = session.get("questions", [])
         
-        # Create question-answer pairs for better context
-        qa_pairs = []
-        for question in questions:
-            answer_text = answer_dict.get(question.key, "No answer provided")
-            qa_pairs.append({
-                "question": question.question,
-                "key": question.key,
-                "answer": answer_text,
-                "required": question.required
-            })
-        
-        logger.info(f"📝 Agent {agent_id}: Received {len(answers.answers)} answers, continuing processing")
-        
-        # Get token summary from session
-        token_summary = session.get("token_summary", TokenSummary())
-        conversation_history = session.get("conversation_history", [])
+        if not questions:
+            # No previous questions - treat as simple additional context
+            logger.info(f"📝 Agent {agent_id}: No previous questions found, treating answers as additional context")
+            answer_dict = {answer.key: answer.answer for answer in answers.answers}
+            qa_pairs = []
+            for answer in answers.answers:
+                qa_pairs.append({
+                    "question": f"Information about {answer.key}",
+                    "key": answer.key,
+                    "answer": answer.answer,
+                    "required": True
+                })
+        else:
+            # Match answers with previous questions
+            logger.info(f"📝 Agent {agent_id}: Matching {len(answers.answers)} answers with previous questions")
+            answer_dict = {answer.key: answer.answer for answer in answers.answers}
+            
+            # Create question-answer pairs for better context
+            qa_pairs = []
+            for question in questions:
+                answer_text = answer_dict.get(question.key, "No answer provided")
+                qa_pairs.append({
+                    "question": question.question,
+                    "key": question.key,
+                    "answer": answer_text,
+                    "required": question.required
+                })
         
         # Process with the provided answers and question context
         result = self._process_with_answers(
-            session["original_prompt"],
-            session["final_response_structure"],
+            prompt,
+            final_response_structure,
             qa_pairs,
             agent_id,
             token_summary,
             conversation_history
         )
         
-        # Update session with conversation history but don't delete it
-        if agent_id in self._agent_sessions:
-            self._agent_sessions[agent_id]["step"] = "completed"
-            self._agent_sessions[agent_id]["conversation_history"] = self._agent_sessions[agent_id].get("conversation_history", [])
-            
-            # Add this interaction to history
-            self._agent_sessions[agent_id]["conversation_history"].extend([
-                {"role": "user", "content": session["original_prompt"]},
-                {"role": "assistant", "content": str(result.final_response) if result.final_response else "No response generated"}
-            ])
-        
+        # Note: History management is now handled in _process_with_answers
+        # No need to duplicate history management here
         return result
 
     def _format_qa_context_for_quality_check(self, answers: Union[list, dict[str, str]]) -> str:
@@ -406,6 +453,30 @@ IMPORTANT: For each question, provide a technical key identifier that:
         logger.info(f"📝 Agent {agent_id}: Generating final structured response")
         final_response = self._generate_final_response(prompt, final_result, final_response_structure, agent_id, token_summary, conversation_history)
         
+        # Update session with the final response in conversation history
+        if agent_id in self._agent_sessions:
+            # Update conversation history with assistant response
+            updated_history = conversation_history.copy()
+            updated_history.append({"role": "assistant", "content": str(final_response)})
+            
+            self._agent_sessions[agent_id]["conversation_history"] = updated_history
+            self._agent_sessions[agent_id]["step"] = "completed"
+            self._agent_sessions[agent_id]["token_summary"] = token_summary
+            self._agent_sessions[agent_id]["final_response_structure"] = final_response_structure
+            logger.info(f"💾 Agent {agent_id}: Updated session with conversation history ({len(updated_history)} messages)")
+        else:
+            # Create new session if it doesn't exist
+            updated_history = conversation_history.copy()
+            updated_history.append({"role": "assistant", "content": str(final_response)})
+            
+            self._agent_sessions[agent_id] = {
+                "step": "completed",
+                "conversation_history": updated_history,
+                "token_summary": token_summary,
+                "final_response_structure": final_response_structure
+            }
+            logger.info(f"💾 Agent {agent_id}: Created new session with conversation history ({len(updated_history)} messages)")
+        
         # Log final token summary
         logger.info(f"📊 Agent {agent_id}: Token usage summary - Total: {token_summary.total_tokens} "
                    f"(Prompt: {token_summary.total_prompt_tokens}, Completion: {token_summary.total_completion_tokens})")

{mbxai-2.1.0 → mbxai-2.1.2}/src/mbxai/examples/agent_example.py

@@ -48,8 +48,8 @@ def example_with_questions():
             Answer(key="recent_books", answer="I recently read and loved Dune and The Name of the Wind")
         ])
         
-        # Continue the agent process with answers
-        final_response = agent.answer_to_agent(response.agent_id, answers)
+        # Continue the agent process with answers using the unified interface
+        final_response = agent.agent("Continue with previous questions", BookRecommendation, ask_questions=False, agent_id=response.agent_id, answers=answers)
         
         if final_response.is_complete():
             book_rec = final_response.final_response

{mbxai-2.1.0 → mbxai-2.1.2}/src/mbxai/examples/agent_logging_example.py

@@ -74,7 +74,7 @@ def demonstrate_agent_with_questions():
             ])
             
             print(f"\n📝 Providing answers and continuing...")
-            final_response = agent.answer_to_agent(response.agent_id, answers)
+            final_response = agent.agent("Continue with answers", WeatherResponse, ask_questions=False, agent_id=response.agent_id, answers=answers)
             
             if final_response.is_complete():
                 print("\n✅ Final response received!")

mbxai-2.1.2/src/mbxai/examples/conversation_history_test.py

@@ -0,0 +1,169 @@
+"""
+Test example demonstrating conversation history persistence across multiple interactions.
+"""
+
+import os
+from pydantic import BaseModel, Field
+from mbxai import AgentClient, OpenRouterClient, AnswerList, Answer
+
+
+class StoryResponse(BaseModel):
+    """A story response that should reference previous conversation."""
+    story_part: str = Field(description="The current part of the story")
+    references_to_previous: str = Field(description="How this connects to our previous conversation")
+    conversation_context: str = Field(description="Summary of what was discussed before")
+
+
+class ChatResponse(BaseModel):
+    """A general chat response."""
+    response: str = Field(description="The response to the user's message")
+    context_awareness: str = Field(description="What the AI remembers from our conversation")
+
+
+def test_conversation_history_persistence():
+    """Test that conversation history persists and is used across multiple interactions."""
+    print("🧪 TESTING: Conversation History Persistence")
+    print("=" * 60)
+    
+    # Initialize the clients
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "your-token-here"))
+    agent = AgentClient(openrouter_client, max_iterations=1)
+    
+    # First interaction - establish context
+    print("\n1️⃣ First interaction - setting up story context:")
+    prompt1 = "I want to tell a collaborative story about a space explorer named Luna who discovers an ancient alien artifact on Mars."
+    response1 = agent.agent(prompt1, StoryResponse, ask_questions=False)
+    
+    agent_id = response1.agent_id
+    print(f"Agent ID: {agent_id}")
+    
+    if response1.is_complete():
+        story1 = response1.final_response
+        print(f"Story Part 1: {story1.story_part[:200]}...")
+        print(f"Context awareness: {story1.context_awareness}")
+        
+        # Check session info
+        session_info = agent.get_session_info(agent_id)
+        print(f"📊 Session after first interaction: {session_info['conversation_length']} messages")
+    
+    # Second interaction - continue story, should reference Luna and the artifact
+    print(f"\n2️⃣ Second interaction - continuing story (should remember Luna and artifact):")
+    prompt2 = "Luna touches the artifact and something amazing happens. Continue the story."
+    response2 = agent.agent(prompt2, StoryResponse, ask_questions=False, agent_id=agent_id)
+    
+    if response2.is_complete():
+        story2 = response2.final_response
+        print(f"Story Part 2: {story2.story_part[:200]}...")
+        print(f"References to previous: {story2.references_to_previous}")
+        print(f"Conversation context: {story2.conversation_context}")
+        
+        # Check session info
+        session_info = agent.get_session_info(agent_id)
+        print(f"📊 Session after second interaction: {session_info['conversation_length']} messages")
+    
+    # Third interaction - change topic but should still remember story context
+    print(f"\n3️⃣ Third interaction - changing topic (should still remember our story):")
+    prompt3 = "Actually, let's pause the story. What do you think Luna's personality is like based on our story so far?"
+    response3 = agent.agent(prompt3, ChatResponse, ask_questions=False, agent_id=agent_id)
+    
+    if response3.is_complete():
+        chat3 = response3.final_response
+        print(f"Response: {chat3.response}")
+        print(f"Context awareness: {chat3.context_awareness}")
+        
+        # Check session info
+        session_info = agent.get_session_info(agent_id)
+        print(f"📊 Session after third interaction: {session_info['conversation_length']} messages")
+    
+    # Fourth interaction - return to story, should remember everything
+    print(f"\n4️⃣ Fourth interaction - returning to story (should remember all previous context):")
+    prompt4 = "Great! Now let's continue Luna's story from where we left off. What happens next with the artifact?"
+    response4 = agent.agent(prompt4, StoryResponse, ask_questions=False, agent_id=agent_id)
+    
+    if response4.is_complete():
+        story4 = response4.final_response
+        print(f"Story Part 4: {story4.story_part[:200]}...")
+        print(f"References to previous: {story4.references_to_previous}")
+        print(f"Conversation context: {story4.conversation_context}")
+        
+        # Final session info
+        session_info = agent.get_session_info(agent_id)
+        print(f"📊 Final session state: {session_info['conversation_length']} messages")
+        print(f"Session step: {session_info.get('step', 'unknown')}")
+    
+    # Display full conversation history
+    print(f"\n💬 FULL CONVERSATION HISTORY:")
+    session_info = agent.get_session_info(agent_id)
+    history = session_info.get('conversation_history', [])
+    for i, msg in enumerate(history, 1):
+        role = msg['role'].upper()
+        content = msg['content'][:100] + "..." if len(msg['content']) > 100 else msg['content']
+        print(f"{i:2d}. {role}: {content}")
+    
+    # Cleanup
+    print(f"\n🗑️ Cleaning up session {agent_id}")
+    agent.delete_session(agent_id)
+
+
+def test_with_questions_and_history():
+    """Test conversation history with questions and answers."""
+    print("\n🧪 TESTING: Questions + Answers + History")
+    print("=" * 60)
+    
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "your-token-here"))
+    agent = AgentClient(openrouter_client, max_iterations=1)
+    
+    # Start with questions
+    print("\n1️⃣ Starting conversation with questions:")
+    response1 = agent.agent("I want a personalized workout plan", ChatResponse, ask_questions=True)
+    
+    agent_id = response1.agent_id
+    print(f"Agent ID: {agent_id}")
+    
+    if response1.has_questions():
+        print(f"📋 Generated {len(response1.questions)} questions:")
+        for q in response1.questions:
+            print(f"  - {q.question}")
+        
+        # Answer questions
+        answers = AnswerList(answers=[
+            Answer(key="fitness_level", answer="Beginner"),
+            Answer(key="goals", answer="Weight loss and muscle building"),
+            Answer(key="time_available", answer="30 minutes per day, 4 days a week"),
+            Answer(key="equipment", answer="Home gym with dumbbells and resistance bands")
+        ])
+        
+        print(f"\n2️⃣ Providing answers:")
+        response2 = agent.agent("Here are my answers", ChatResponse, ask_questions=False, agent_id=agent_id, answers=answers)
+        
+        if response2.is_complete():
+            workout_plan = response2.final_response
+            print(f"Workout plan: {workout_plan.response[:200]}...")
+            print(f"Context awareness: {workout_plan.context_awareness}")
+        
+        # Continue conversation
+        print(f"\n3️⃣ Follow-up question (should remember all previous context):")
+        response3 = agent.agent("Can you modify this plan to focus more on cardio?", ChatResponse, ask_questions=False, agent_id=agent_id)
+        
+        if response3.is_complete():
+            modified_plan = response3.final_response
+            print(f"Modified plan: {modified_plan.response[:200]}...")
+            print(f"Context awareness: {modified_plan.context_awareness}")
+        
+        # Show history
+        session_info = agent.get_session_info(agent_id)
+        print(f"\n💬 Conversation had {session_info['conversation_length']} messages")
+        
+        # Cleanup
+        agent.delete_session(agent_id)
+
+
+if __name__ == "__main__":
+    try:
+        test_conversation_history_persistence()
+        print("\n" + "="*80 + "\n")
+        test_with_questions_and_history()
+    except Exception as e:
+        print(f"Error: {e}")
+        import traceback
+        traceback.print_exc()

{mbxai-2.1.0 → mbxai-2.1.2}/src/mbxai/examples/dialog_agent_example.py

@@ -116,7 +116,7 @@ def demonstrate_dialog_with_questions():
         ])
         
         print(f"\n📝 Providing answers...")
-        final_response = agent.answer_to_agent(agent_id, answers)
+        final_response = agent.agent("Continue with answers", BookRecommendation, ask_questions=False, agent_id=agent_id, answers=answers)
         
         if final_response.is_complete():
             book_rec = final_response.final_response
@@ -135,6 +135,21 @@ def demonstrate_dialog_with_questions():
                 print(f"Genre: {book_rec2.genre}")
                 print(f"Reason: {book_rec2.reason}")
                 print(f"Connection to previous: {book_rec2.connection_to_previous}")
+            
+            # Continue WITHOUT explicit prompt - using only conversation history
+            print(f"\n3️⃣ Continuing conversation WITHOUT explicit prompt (history-based):")
+            try:
+                response3 = agent.agent(agent_id=agent_id, ask_questions=False)  # No prompt provided
+                
+                if response3.is_complete():
+                    book_rec3 = response3.final_response
+                    print(f"History-based recommendation:")
+                    print(f"Book: {book_rec3.title} by {book_rec3.author}")
+                    print(f"Genre: {book_rec3.genre}")
+                    print(f"Reason: {book_rec3.reason}")
+                    print(f"Connection to previous: {book_rec3.connection_to_previous}")
+            except Exception as e:
+                print(f"Error with history-based continuation: {e}")
         
         # Session cleanup
         print(f"\n🗑️ Session cleanup...")

mbxai-2.1.2/src/mbxai/examples/optional_prompt_example.py

@@ -0,0 +1,164 @@
+"""
+Example demonstrating optional prompt functionality with existing agent sessions.
+"""
+
+import os
+from pydantic import BaseModel, Field
+from mbxai import AgentClient, OpenRouterClient, AnswerList, Answer
+
+
+class ConversationResponse(BaseModel):
+    """A general conversation response."""
+    response: str = Field(description="The response to the conversation")
+    context_used: str = Field(description="How previous conversation history was used")
+    continuation_type: str = Field(description="Type of continuation (new topic, follow-up, etc.)")
+
+
+class StoryResponse(BaseModel):
+    """A story response."""
+    story_continuation: str = Field(description="The next part of the story")
+    character_development: str = Field(description="How characters developed in this part")
+    plot_advancement: str = Field(description="How the plot advanced")
+
+
+def demonstrate_optional_prompt():
+    """Demonstrate using agent with optional prompts for existing sessions."""
+    print("🎭 DEMO: Optional Prompt with Existing Agent Sessions")
+    print("=" * 60)
+    
+    # Initialize the clients
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "your-token-here"))
+    agent = AgentClient(openrouter_client, max_iterations=1)
+    
+    # First interaction - establish a story context
+    print("\n1️⃣ First interaction - establishing story context:")
+    response1 = agent.agent(
+        prompt="Let's create a story about a detective solving a mystery in a small town",
+        final_response_structure=StoryResponse,
+        ask_questions=False
+    )
+    
+    agent_id = response1.agent_id
+    print(f"Agent ID: {agent_id}")
+    
+    if response1.is_complete():
+        story1 = response1.final_response
+        print(f"Story start: {story1.story_continuation[:150]}...")
+        print(f"Characters: {story1.character_development}")
+    
+    # Second interaction - continue with explicit prompt
+    print(f"\n2️⃣ Second interaction - continue with explicit prompt:")
+    response2 = agent.agent(
+        prompt="The detective finds a mysterious letter. What does it say?",
+        agent_id=agent_id,
+        ask_questions=False
+    )
+    
+    if response2.is_complete():
+        story2 = response2.final_response
+        print(f"Story continuation: {story2.story_continuation[:150]}...")
+        print(f"Plot advancement: {story2.plot_advancement}")
+    
+    # Third interaction - continue WITHOUT explicit prompt (using only history)
+    print(f"\n3️⃣ Third interaction - continue WITHOUT explicit prompt (history-based):")
+    try:
+        response3 = agent.agent(
+            agent_id=agent_id,  # Only provide agent_id, no prompt
+            ask_questions=False
+        )
+        
+        if response3.is_complete():
+            story3 = response3.final_response
+            print(f"History-based continuation: {story3.story_continuation[:150]}...")
+            print(f"Character development: {story3.character_development}")
+            print(f"Plot advancement: {story3.plot_advancement}")
+        
+    except Exception as e:
+        print(f"Error with history-based continuation: {e}")
+    
+    # Fourth interaction - switch response format but use same session
+    print(f"\n4️⃣ Fourth interaction - switch to conversation format:")
+    response4 = agent.agent(
+        prompt="What do you think about this story so far?",
+        final_response_structure=ConversationResponse,
+        agent_id=agent_id,
+        ask_questions=False
+    )
+    
+    if response4.is_complete():
+        conv4 = response4.final_response
+        print(f"Analysis: {conv4.response[:150]}...")
+        print(f"Context used: {conv4.context_used}")
+        print(f"Continuation type: {conv4.continuation_type}")
+    
+    # Fifth interaction - continue conversation without prompt
+    print(f"\n5️⃣ Fifth interaction - continue conversation analysis without prompt:")
+    try:
+        response5 = agent.agent(
+            agent_id=agent_id,
+            ask_questions=False
+        )
+        
+        if response5.is_complete():
+            conv5 = response5.final_response
+            print(f"Continued analysis: {conv5.response[:150]}...")
+            print(f"Context used: {conv5.context_used}")
+            print(f"Continuation type: {conv5.continuation_type}")
+        
+    except Exception as e:
+        print(f"Error with continued conversation: {e}")
+    
+    # Show final session state
+    session_info = agent.get_session_info(agent_id)
+    print(f"\n📊 Final session state:")
+    print(f"   - Total messages: {session_info['conversation_length']}")
+    print(f"   - Session step: {session_info.get('step', 'unknown')}")
+    print(f"   - Has final_response_structure: {'final_response_structure' in session_info}")
+    
+    # Cleanup
+    agent.delete_session(agent_id)
+
+
+def demonstrate_error_cases():
+    """Demonstrate error cases with optional prompt."""
+    print("\n🚨 DEMO: Error Cases with Optional Prompt")
+    print("=" * 50)
+    
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "your-token-here"))
+    agent = AgentClient(openrouter_client, max_iterations=1)
+    
+    # Error case 1: No prompt and no existing session
+    print("\n❌ Error case 1: No prompt, no existing session")
+    try:
+        response = agent.agent(ask_questions=False)
+        print("This should have failed!")
+    except ValueError as e:
+        print(f"Expected error: {e}")
+    
+    # Error case 2: No prompt and no final_response_structure for new session
+    print("\n❌ Error case 2: No final_response_structure for new session")
+    try:
+        response = agent.agent(prompt="Test", ask_questions=False)
+        print("This should have failed!")
+    except ValueError as e:
+        print(f"Expected error: {e}")
+    
+    # Error case 3: Unknown agent_id without prompt
+    print("\n❌ Error case 3: Unknown agent_id without prompt")
+    try:
+        response = agent.agent(agent_id="unknown-id", ask_questions=False)
+        print("This should have failed!")
+    except ValueError as e:
+        print(f"Expected error: {e}")
+    
+    print("\n✅ All error cases handled correctly!")
+
+
+if __name__ == "__main__":
+    try:
+        demonstrate_optional_prompt()
+        demonstrate_error_cases()
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+        import traceback
+        traceback.print_exc()

mbxai-2.1.2/src/mbxai/examples/unified_interface_example.py

@@ -0,0 +1,109 @@
+"""
+Example demonstrating the new unified agent interface.
+"""
+
+import os
+from pydantic import BaseModel, Field
+from mbxai import AgentClient, OpenRouterClient, AnswerList, Answer
+
+
+class SimpleResponse(BaseModel):
+    """A simple response."""
+    response: str = Field(description="The response text")
+    context_used: str = Field(description="How context was used in this response")
+
+
+def demonstrate_unified_interface():
+    """Demonstrate the unified agent interface with and without questions."""
+    print("🔧 DEMO: Unified Agent Interface")
+    print("=" * 50)
+    
+    # Initialize the clients
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "your-token-here"))
+    agent = AgentClient(openrouter_client, max_iterations=1)
+    
+    # Example 1: Start conversation with questions
+    print("\n1️⃣ Starting conversation that generates questions:")
+    response1 = agent.agent("I need help planning a trip", SimpleResponse, ask_questions=True)
+    
+    agent_id = response1.agent_id
+    print(f"Agent ID: {agent_id}")
+    
+    if response1.has_questions():
+        print(f"📋 Generated {len(response1.questions)} questions:")
+        for q in response1.questions:
+            print(f"  - {q.question} (key: {q.key})")
+        
+        # Example 2: Provide answers using the unified interface
+        print(f"\n2️⃣ Providing answers using unified interface:")
+        answers = AnswerList(answers=[
+            Answer(key="destination", answer="Japan"),
+            Answer(key="duration", answer="10 days"),
+            Answer(key="budget", answer="$3000"),
+            Answer(key="interests", answer="culture, food, temples")
+        ])
+        
+        response2 = agent.agent(
+            "Now help me plan the trip", 
+            SimpleResponse, 
+            ask_questions=False, 
+            agent_id=agent_id, 
+            answers=answers
+        )
+        
+        if response2.is_complete():
+            trip_plan = response2.final_response
+            print(f"Response: {trip_plan.response}")
+            print(f"Context used: {trip_plan.context_used}")
+    
+    # Example 3: Continue the conversation
+    print(f"\n3️⃣ Continuing conversation without questions:")
+    response3 = agent.agent(
+        "What about transportation within Japan?", 
+        SimpleResponse, 
+        ask_questions=False, 
+        agent_id=agent_id
+    )
+    
+    if response3.is_complete():
+        transport_info = response3.final_response
+        print(f"Response: {transport_info.response}")
+        print(f"Context used: {transport_info.context_used}")
+    
+    # Example 4: Using answers without previous questions (new session)
+    print(f"\n4️⃣ Starting new session with direct answers (no questions):")
+    new_answers = AnswerList(answers=[
+        Answer(key="city", answer="Tokyo"),
+        Answer(key="travel_style", answer="luxury"),
+        Answer(key="group_size", answer="2 people")
+    ])
+    
+    response4 = agent.agent(
+        "Recommend restaurants",
+        SimpleResponse,
+        ask_questions=False,
+        answers=new_answers  # New session, no agent_id provided
+    )
+    
+    if response4.is_complete():
+        restaurant_info = response4.final_response
+        print(f"New Agent ID: {response4.agent_id}")
+        print(f"Response: {restaurant_info.response}")
+        print(f"Context used: {restaurant_info.context_used}")
+    
+    # Show active sessions
+    print(f"\n📊 Active Sessions: {agent.list_sessions()}")
+    
+    # Cleanup
+    print(f"\n🗑️ Cleaning up sessions...")
+    agent.delete_session(agent_id)
+    if response4.agent_id != agent_id:
+        agent.delete_session(response4.agent_id)
+    print(f"Active Sessions after cleanup: {agent.list_sessions()}")
+
+
+if __name__ == "__main__":
+    try:
+        demonstrate_unified_interface()
+    except Exception as e:
+        print(f"Error: {e}")

{mbxai-2.1.0 → mbxai-2.1.2}/src/mbxai/mcp/server.py

@@ -31,7 +31,7 @@ class MCPServer:
         self.app = FastAPI(
             title=self.name,
             description=self.description,
-            version="2.1.0",
+            version="2.1.2",
         )
         
         # Initialize MCP server