mbxai 2.0.4__tar.gz → 2.1.0__tar.gz

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

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mbxai"
-version = "2.0.4"
+version = "2.1.0"
 authors = [
     { name = "MBX AI" }
 ]
@@ -82,6 +82,7 @@ strict_equality = true
 
 [dependency-groups]
 dev = [
-    "build>=2.0.4.post1",
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
     "twine>=6.1.0",
 ]

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

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

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

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

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

@@ -10,7 +10,7 @@ from pydantic import BaseModel
 from ..openrouter import OpenRouterClient
 from ..tools import ToolClient
 from ..mcp import MCPClient
-from .models import AgentResponse, Question, QuestionList, AnswerList, Result, QualityCheck
+from .models import AgentResponse, Question, QuestionList, AnswerList, Result, QualityCheck, TokenUsage, TokenSummary
 
 logger = logging.getLogger(__name__)
 
@@ -123,9 +123,29 @@ class AgentClient:
                 f"Use MCPClient to register MCP servers."
             )
 
-    def _call_ai_parse(self, messages: list[dict[str, Any]], response_format: Type[BaseModel]) -> Any:
-        """Call the parse method on the AI client."""
-        return self._ai_client.parse(messages, response_format)
+    def _call_ai_parse(self, messages: list[dict[str, Any]], response_format: Type[BaseModel], conversation_history: list[dict[str, Any]] = None) -> Any:
+        """Call the parse method on the AI client with optional conversation history."""
+        # Combine conversation history with new messages
+        if conversation_history:
+            full_messages = conversation_history + messages
+        else:
+            full_messages = messages
+        return self._ai_client.parse(full_messages, response_format)
+
+    def _extract_token_usage(self, response: Any) -> TokenUsage:
+        """Extract token usage information from an AI response."""
+        try:
+            if hasattr(response, 'usage') and response.usage:
+                usage = response.usage
+                return TokenUsage(
+                    prompt_tokens=getattr(usage, 'prompt_tokens', 0),
+                    completion_tokens=getattr(usage, 'completion_tokens', 0),
+                    total_tokens=getattr(usage, 'total_tokens', 0)
+                )
+        except (AttributeError, TypeError) as e:
+            logger.debug(f"Could not extract token usage: {e}")
+        
+        return TokenUsage()  # Return empty usage if extraction fails
 
     def _extract_parsed_content(self, response: Any, response_format: Type[BaseModel]) -> BaseModel:
         """Extract the parsed content from the AI response."""
@@ -164,7 +184,8 @@ class AgentClient:
         self,
         prompt: str,
         final_response_structure: Type[BaseModel],
-        ask_questions: bool = True
+        ask_questions: bool = True,
+        agent_id: str = None
     ) -> AgentResponse:
         """
         Process a prompt through the agent's thinking process.
@@ -173,14 +194,28 @@ class AgentClient:
             prompt: The initial prompt from the user
             final_response_structure: Pydantic model defining the expected final response format
             ask_questions: Whether to ask clarifying questions (default: True)
+            agent_id: Optional agent session ID to continue an existing conversation
 
         Returns:
             AgentResponse containing either questions to ask or the final response
         """
-        logger.debug(f"Starting agent process with prompt: {prompt[:100]}...")
+        # Use provided agent_id or create a new one
+        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]}...")
+        
+        # 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", [])
         
         # Step 1: Generate questions (if ask_questions is True)
         if ask_questions:
+            logger.info(f"❓ Agent {agent_id}: Analyzing prompt and generating clarifying questions")
             questions_prompt = f"""
 Understand this prompt and what the user wants to achieve by it: 
 ==========
@@ -201,28 +236,34 @@ IMPORTANT: For each question, provide a technical key identifier that:
             messages = [{"role": "user", "content": questions_prompt}]
             
             try:
-                response = self._call_ai_parse(messages, QuestionList)
+                response = self._call_ai_parse(messages, QuestionList, conversation_history)
                 question_list = self._extract_parsed_content(response, QuestionList)
                 
-                logger.debug(f"Generated {len(question_list.questions)} questions")
+                # Extract token usage for question generation
+                token_summary.question_generation = self._extract_token_usage(response)
+                
+                logger.info(f"❓ Agent {agent_id}: Generated {len(question_list.questions)} questions (tokens: {token_summary.question_generation.total_tokens})")
                 
                 # If we have questions, return them to the user
                 if question_list.questions:
-                    agent_response = AgentResponse(questions=question_list.questions)
+                    agent_response = AgentResponse(agent_id=agent_id, questions=question_list.questions, token_summary=token_summary)
                     # Store the session for continuation
                     self._agent_sessions[agent_response.agent_id] = {
                         "original_prompt": prompt,
                         "final_response_structure": final_response_structure,
                         "questions": question_list.questions,
-                        "step": "waiting_for_answers"
+                        "step": "waiting_for_answers",
+                        "token_summary": token_summary
                     }
+                    logger.info(f"📋 Agent {agent_id}: Waiting for user answers to {len(question_list.questions)} questions")
                     return agent_response
                     
             except Exception as e:
                 logger.warning(f"Failed to generate questions: {e}. Proceeding without questions.")
         
         # Step 2 & 3: No questions or ask_questions=False - proceed directly
-        return self._process_with_answers(prompt, final_response_structure, [])
+        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)
 
     def answer_to_agent(self, agent_id: str, answers: AnswerList) -> AgentResponse:
         """
@@ -245,26 +286,97 @@ IMPORTANT: For each question, provide a technical key identifier that:
         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
+        # Convert answers to a more usable format and create question-answer pairs
         answer_dict = {answer.key: answer.answer for answer in answers.answers}
+        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")
         
-        # Process with the provided answers
+        # Get token summary from session
+        token_summary = session.get("token_summary", TokenSummary())
+        conversation_history = session.get("conversation_history", [])
+        
+        # Process with the provided answers and question context
         result = self._process_with_answers(
             session["original_prompt"],
             session["final_response_structure"],
-            answer_dict
+            qa_pairs,
+            agent_id,
+            token_summary,
+            conversation_history
         )
         
-        # Clean up the session
-        del self._agent_sessions[agent_id]
+        # 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"}
+            ])
         
         return result
 
+    def _format_qa_context_for_quality_check(self, answers: Union[list, dict[str, str]]) -> str:
+        """
+        Format question-answer context for quality check and improvement prompts.
+        
+        Args:
+            answers: Question-answer pairs or simple answers
+            
+        Returns:
+            Formatted context text
+        """
+        if not answers:
+            return ""
+            
+        if isinstance(answers, list) and answers:
+            # Check if it's a list of question-answer pairs (enhanced format)
+            if isinstance(answers[0], dict) and "question" in answers[0]:
+                context_text = "\nContext Information (Questions & Answers):\n"
+                context_text += "The response was generated with the following additional context:\n\n"
+                for i, qa_pair in enumerate(answers, 1):
+                    question = qa_pair.get("question", "Unknown question")
+                    answer = qa_pair.get("answer", "No answer provided")
+                    required = qa_pair.get("required", True)
+                    
+                    status_marker = "🔴 REQUIRED" if required else "🟡 OPTIONAL"
+                    context_text += f"{i}. {status_marker} Q: {question}\n"
+                    context_text += f"   A: {answer}\n\n"
+                return context_text
+            else:
+                # Legacy format - simple list
+                return f"\nAdditional context: {', '.join(str(a) for a in answers)}\n\n"
+        elif isinstance(answers, dict) and answers:
+            # Legacy format - simple dict
+            context_text = "\nAdditional context provided:\n"
+            for key, answer in answers.items():
+                context_text += f"- {key}: {answer}\n"
+            return context_text + "\n"
+        
+        return ""
+
     def _process_with_answers(
         self,
         prompt: str,
         final_response_structure: Type[BaseModel],
-        answers: Union[list, dict[str, str]]
+        answers: Union[list, dict[str, str]],
+        agent_id: str,
+        token_summary: TokenSummary,
+        conversation_history: list[dict[str, Any]] = None
     ) -> AgentResponse:
         """
         Process the prompt with answers through the thinking pipeline.
@@ -272,41 +384,77 @@ IMPORTANT: For each question, provide a technical key identifier that:
         Args:
             prompt: The original prompt
             final_response_structure: Expected final response structure
-            answers: Answers to questions (empty if no questions were asked)
+            answers: Question-answer pairs or simple answers (empty if no questions were asked)
+            agent_id: The agent session identifier
+            token_summary: Current token usage summary
+            conversation_history: Optional conversation history for dialog context
 
         Returns:
             AgentResponse with the final result
         """
+        if conversation_history is None:
+            conversation_history = []
+            
         # Step 3: Process the prompt with thinking
-        result = self._think_and_process(prompt, answers)
+        logger.info(f"🧠 Agent {agent_id}: Processing prompt and generating initial response")
+        result = self._think_and_process(prompt, answers, agent_id, token_summary, conversation_history)
         
         # Step 4: Quality check and iteration
-        final_result = self._quality_check_and_iterate(prompt, result, answers)
+        final_result = self._quality_check_and_iterate(prompt, result, answers, agent_id, token_summary, conversation_history)
         
         # Step 5: Generate final answer in requested format
-        final_response = self._generate_final_response(prompt, final_result, final_response_structure)
+        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)
+        
+        # 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})")
         
-        return AgentResponse(final_response=final_response)
+        return AgentResponse(agent_id=agent_id, final_response=final_response, token_summary=token_summary)
 
-    def _think_and_process(self, prompt: str, answers: Union[list, dict[str, str]]) -> str:
+    def _think_and_process(self, prompt: str, answers: Union[list, dict[str, str]], agent_id: str, token_summary: TokenSummary, conversation_history: list[dict[str, Any]] = None) -> str:
         """
         Process the prompt with thinking.
 
         Args:
             prompt: The original prompt
-            answers: Answers to questions
+            answers: Question-answer pairs or simple answers
+            agent_id: The agent session identifier
+            token_summary: Current token usage summary
+            conversation_history: Optional conversation history for dialog context
 
         Returns:
             The AI's result
         """
-        # Format answers for the prompt
+        if conversation_history is None:
+            conversation_history = []
+        # Format answers for the prompt with enhanced context
         answers_text = ""
-        if isinstance(answers, dict) and answers:
+        if isinstance(answers, list) and answers:
+            # Check if it's a list of question-answer pairs (enhanced format)
+            if answers and isinstance(answers[0], dict) and "question" in answers[0]:
+                answers_text = "\n\nQuestion-Answer Context:\n"
+                answers_text += "The following questions were asked to gather more information, along with the answers provided:\n\n"
+                for i, qa_pair in enumerate(answers, 1):
+                    question = qa_pair.get("question", "Unknown question")
+                    answer = qa_pair.get("answer", "No answer provided")
+                    key = qa_pair.get("key", "")
+                    required = qa_pair.get("required", True)
+                    
+                    status_marker = "🔴 REQUIRED" if required else "🟡 OPTIONAL"
+                    answers_text += f"{i}. {status_marker} Question: {question}\n"
+                    answers_text += f"   Answer: {answer}\n"
+                    if key:
+                        answers_text += f"   (Key: {key})\n"
+                    answers_text += "\n"
+            else:
+                # Legacy format - simple list
+                answers_text = f"\n\nAdditional information: {', '.join(str(a) for a in answers)}\n"
+        elif isinstance(answers, dict) and answers:
+            # Legacy format - simple dict
             answers_text = "\n\nAdditional information provided:\n"
             for key, answer in answers.items():
                 answers_text += f"- {key}: {answer}\n"
-        elif isinstance(answers, list) and answers:
-            answers_text = f"\n\nAdditional information: {', '.join(answers)}\n"
         
         thinking_prompt = f"""
 Think about this prompt, the goal and the steps required to fulfill it: 
@@ -315,42 +463,66 @@ Think about this prompt, the goal and the steps required to fulfill it:
 ==========
 {answers_text}
 
-Consider the prompt carefully, analyze what the user wants to achieve, and think through the best approach to provide a comprehensive and helpful response. Use any available tools to gather information or perform actions that would improve your response.
+Consider the prompt carefully, analyze what the user wants to achieve, and think through the best approach to provide a comprehensive and helpful response. 
 
-Provide your best result for the given prompt.
+IMPORTANT: When formulating your response, take into account both the original prompt AND the specific questions that were asked along with their answers. The questions reveal what additional information was deemed necessary, and the answers provide crucial context that should inform your response.
+
+Use any available tools to gather information or perform actions that would improve your response.
+
+Provide your best result for the given prompt, incorporating all the context from the question-answer pairs.
 """
         
         messages = [{"role": "user", "content": thinking_prompt}]
         
         try:
-            response = self._call_ai_parse(messages, Result)
+            response = self._call_ai_parse(messages, Result, conversation_history)
             result_obj = self._extract_parsed_content(response, Result)
+            
+            # Track token usage for thinking process
+            token_summary.thinking_process = self._extract_token_usage(response)
+            logger.info(f"🧠 Agent {agent_id}: Thinking completed (tokens: {token_summary.thinking_process.total_tokens})")
+            
             return result_obj.result
         except Exception as e:
             logger.error(f"Error in thinking process: {e}")
             raise RuntimeError(f"Failed to process prompt with AI client: {e}") from e
 
-    def _quality_check_and_iterate(self, prompt: str, result: str, answers: Union[list, dict[str, str]]) -> str:
+    def _quality_check_and_iterate(self, prompt: str, result: str, answers: Union[list, dict[str, str]], agent_id: str, token_summary: TokenSummary, conversation_history: list[dict[str, Any]] = None) -> str:
         """
         Check the quality of the result and iterate if needed.
 
         Args:
             prompt: The original prompt
             result: The current result
-            answers: The answers provided
+            answers: Question-answer pairs or simple answers
+            agent_id: The agent session identifier
+            token_summary: Current token usage summary
+            conversation_history: Optional conversation history for dialog context
 
         Returns:
             The final improved result
         """
+        if conversation_history is None:
+            conversation_history = []
+            
         current_result = result
         
+        if self._max_iterations == 0:
+            logger.info(f"✅ Agent {agent_id}: Skipping quality check (max_iterations=0)")
+            return current_result
+        
+        logger.info(f"🔍 Agent {agent_id}: Starting quality check and improvement process (max iterations: {self._max_iterations})")
+        
+        # Format context information for quality checks
+        context_text = self._format_qa_context_for_quality_check(answers)
+        
         for iteration in range(self._max_iterations):
             quality_prompt = f"""
 Given this original prompt:
 ==========
 {prompt}
 ==========
-
+{context_text}
 And this result:
 ==========
 {current_result}
@@ -358,20 +530,26 @@ And this result:
 
 Is this result good and comprehensive, or does it need to be improved? Consider if the response fully addresses the prompt, provides sufficient detail, and would be helpful to the user.
 
+IMPORTANT: Also evaluate whether the result properly incorporates and addresses the information provided through the question-answer pairs above. The response should demonstrate that it has taken this additional context into account.
+
 Evaluate the quality and provide feedback if improvements are needed.
 """
             
             messages = [{"role": "user", "content": quality_prompt}]
             
             try:
-                response = self._call_ai_parse(messages, QualityCheck)
+                response = self._call_ai_parse(messages, QualityCheck, conversation_history)
                 quality_check = self._extract_parsed_content(response, QualityCheck)
                 
+                # Track token usage for quality check
+                quality_check_tokens = self._extract_token_usage(response)
+                token_summary.quality_checks.append(quality_check_tokens)
+                
                 if quality_check.is_good:
-                    logger.debug(f"Quality check passed on iteration {iteration}")
+                    logger.info(f"✅ Agent {agent_id}: Quality check passed on iteration {iteration + 1} (tokens: {quality_check_tokens.total_tokens})")
                     break
                     
-                logger.debug(f"Quality check failed on iteration {iteration}: {quality_check.feedback}")
+                logger.info(f"🔄 Agent {agent_id}: Quality check iteration {iteration + 1} - Improvements needed: {quality_check.feedback[:100]}... (tokens: {quality_check_tokens.total_tokens})")
                 
                 # Improve the result
                 improvement_prompt = f"""
@@ -379,7 +557,7 @@ The original prompt was:
 ==========
 {prompt}
 ==========
-
+{context_text}
 The current result is:
 ==========
 {current_result}
@@ -390,21 +568,31 @@ Feedback for improvement:
 {quality_check.feedback}
 ==========
 
-Please provide an improved version that addresses the feedback while maintaining the strengths of the current result.
+Please provide an improved version that addresses the feedback while maintaining the strengths of the current result. Make sure to incorporate all the context from the question-answer pairs above.
 """
                 
                 messages = [{"role": "user", "content": improvement_prompt}]
-                response = self._call_ai_parse(messages, Result)
-                result_obj = self._extract_parsed_content(response, Result)
+                improvement_response = self._call_ai_parse(messages, Result, conversation_history)
+                result_obj = self._extract_parsed_content(improvement_response, Result)
                 current_result = result_obj.result
                 
+                # Track token usage for improvement
+                improvement_tokens = self._extract_token_usage(improvement_response)
+                token_summary.improvements.append(improvement_tokens)
+                
+                logger.info(f"⚡ Agent {agent_id}: Improvement iteration {iteration + 1} completed (tokens: {improvement_tokens.total_tokens})")
+                
             except Exception as e:
                 logger.warning(f"Error in quality check iteration {iteration}: {e}")
                 break
         
+        total_quality_tokens = sum(usage.total_tokens for usage in token_summary.quality_checks)
+        total_improvement_tokens = sum(usage.total_tokens for usage in token_summary.improvements)
+        logger.info(f"🏁 Agent {agent_id}: Quality check completed - {len(token_summary.quality_checks)} checks, {len(token_summary.improvements)} improvements (Quality tokens: {total_quality_tokens}, Improvement tokens: {total_improvement_tokens})")
+        
         return current_result
 
-    def _generate_final_response(self, prompt: str, result: str, final_response_structure: Type[BaseModel]) -> BaseModel:
+    def _generate_final_response(self, prompt: str, result: str, final_response_structure: Type[BaseModel], agent_id: str, token_summary: TokenSummary, conversation_history: list[dict[str, Any]] = None) -> BaseModel:
         """
         Generate the final response in the requested format.
 
@@ -412,10 +600,15 @@ Please provide an improved version that addresses the feedback while maintaining
             prompt: The original prompt
             result: The processed result
             final_response_structure: The expected response structure
+            agent_id: The agent session identifier
+            token_summary: Current token usage summary
+            conversation_history: Optional conversation history for dialog context
 
         Returns:
             The final response in the requested format
         """
+        if conversation_history is None:
+            conversation_history = []
         final_prompt = f"""
 Given this original prompt:
 ==========
@@ -433,8 +626,14 @@ Generate the final answer in the exact format requested. Make sure the response
         messages = [{"role": "user", "content": final_prompt}]
         
         try:
-            response = self._call_ai_parse(messages, final_response_structure)
-            return self._extract_parsed_content(response, final_response_structure)
+            response = self._call_ai_parse(messages, final_response_structure, conversation_history)
+            final_response = self._extract_parsed_content(response, final_response_structure)
+            
+            # Track token usage for final response generation
+            token_summary.final_response = self._extract_token_usage(response)
+            logger.info(f"📝 Agent {agent_id}: Final structured response generated (tokens: {token_summary.final_response.total_tokens})")
+            
+            return final_response
         except Exception as e:
             logger.error(f"Error generating final response: {e}")
             # Fallback - try to create a basic response
@@ -454,3 +653,49 @@ Generate the final answer in the exact format requested. Make sure the response
                 logger.error(f"Fallback response creation failed: {fallback_error}")
                 # Last resort - return the structure with default values
                 return final_response_structure()
+
+    def get_session_info(self, agent_id: str) -> dict[str, Any]:
+        """
+        Get information about an agent session.
+        
+        Args:
+            agent_id: The agent session identifier
+            
+        Returns:
+            Session information dictionary
+            
+        Raises:
+            ValueError: If the agent session is not found
+        """
+        if agent_id not in self._agent_sessions:
+            raise ValueError(f"Agent session {agent_id} not found")
+        
+        session = self._agent_sessions[agent_id].copy()
+        # Remove sensitive information and add summary
+        session["conversation_length"] = len(session.get("conversation_history", []))
+        return session
+
+    def delete_session(self, agent_id: str) -> bool:
+        """
+        Delete an agent session.
+        
+        Args:
+            agent_id: The agent session identifier
+            
+        Returns:
+            True if session was deleted, False if it didn't exist
+        """
+        if agent_id in self._agent_sessions:
+            del self._agent_sessions[agent_id]
+            logger.info(f"🗑️ Deleted agent session {agent_id}")
+            return True
+        return False
+
+    def list_sessions(self) -> list[str]:
+        """
+        List all active agent session IDs.
+        
+        Returns:
+            List of agent session IDs
+        """
+        return list(self._agent_sessions.keys())

{mbxai-2.0.4 → mbxai-2.1.0}/src/mbxai/agent/models.py

@@ -46,6 +46,7 @@ class AgentResponse(BaseModel):
     agent_id: str = Field(default_factory=lambda: str(uuid.uuid4()), description="Unique identifier for this agent session")
     questions: list[Question] = Field(default_factory=list, description="List of questions for the user")
     final_response: Optional[Any] = Field(default=None, description="The final response if processing is complete")
+    token_summary: Optional["TokenSummary"] = Field(default=None, description="Summary of token usage for this agent process")
     
     def has_questions(self) -> bool:
         """Check if this response has questions that need to be answered."""
@@ -76,3 +77,55 @@ class QualityCheck(BaseModel):
     """Result of quality checking the AI response."""
     is_good: bool = Field(description="Whether the result is good enough")
     feedback: str = Field(description="Feedback on what could be improved if not good")
+
+
+class TokenUsage(BaseModel):
+    """Token usage information for a single API call."""
+    prompt_tokens: int = Field(default=0, description="Number of tokens in the prompt")
+    completion_tokens: int = Field(default=0, description="Number of tokens in the completion")
+    total_tokens: int = Field(default=0, description="Total number of tokens used")
+
+
+class TokenSummary(BaseModel):
+    """Summary of token usage across all API calls in an agent process."""
+    question_generation: TokenUsage = Field(default_factory=TokenUsage, description="Tokens used for question generation")
+    thinking_process: TokenUsage = Field(default_factory=TokenUsage, description="Tokens used for thinking/processing")
+    quality_checks: list[TokenUsage] = Field(default_factory=list, description="Tokens used for each quality check iteration")
+    improvements: list[TokenUsage] = Field(default_factory=list, description="Tokens used for each improvement iteration")
+    final_response: TokenUsage = Field(default_factory=TokenUsage, description="Tokens used for final response generation")
+    
+    @property
+    def total_tokens(self) -> int:
+        """Calculate total tokens used across all operations."""
+        total = (
+            self.question_generation.total_tokens +
+            self.thinking_process.total_tokens +
+            sum(usage.total_tokens for usage in self.quality_checks) +
+            sum(usage.total_tokens for usage in self.improvements) +
+            self.final_response.total_tokens
+        )
+        return total
+    
+    @property
+    def total_prompt_tokens(self) -> int:
+        """Calculate total prompt tokens used across all operations."""
+        total = (
+            self.question_generation.prompt_tokens +
+            self.thinking_process.prompt_tokens +
+            sum(usage.prompt_tokens for usage in self.quality_checks) +
+            sum(usage.prompt_tokens for usage in self.improvements) +
+            self.final_response.prompt_tokens
+        )
+        return total
+    
+    @property
+    def total_completion_tokens(self) -> int:
+        """Calculate total completion tokens used across all operations."""
+        total = (
+            self.question_generation.completion_tokens +
+            self.thinking_process.completion_tokens +
+            sum(usage.completion_tokens for usage in self.quality_checks) +
+            sum(usage.completion_tokens for usage in self.improvements) +
+            self.final_response.completion_tokens
+        )
+        return total

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

@@ -126,6 +126,33 @@ def example_with_tool_client():
             print(f"- {rec}")
 
 
+def example_dialog_conversation():
+    """Example demonstrating persistent dialog functionality."""
+    print("Example of persistent dialog conversation:")
+    
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "your-token-here"))
+    agent = AgentClient(openrouter_client, max_iterations=1)
+    
+    # Start conversation
+    response1 = agent.agent("I want a book recommendation for science fiction", BookRecommendation, ask_questions=False)
+    agent_id = response1.agent_id
+    
+    if response1.is_complete():
+        book1 = response1.final_response
+        print(f"First recommendation: {book1.title} by {book1.author}")
+        
+        # Continue conversation with same agent_id
+        response2 = agent.agent("Can you recommend something by a different author in the same genre?", BookRecommendation, ask_questions=False, agent_id=agent_id)
+        
+        if response2.is_complete():
+            book2 = response2.final_response
+            print(f"Second recommendation: {book2.title} by {book2.author}")
+            print(f"Context: {book2.reason}")
+    
+    # Clean up session when done
+    agent.delete_session(agent_id)
+
+
 if __name__ == "__main__":
     print("=== Agent Client Examples ===\n")
     
@@ -150,3 +177,11 @@ if __name__ == "__main__":
         example_with_tool_client()
     except Exception as e:
         print(f"Error: {e}")
+    
+    print("\n" + "="*50 + "\n")
+    
+    print("4. Example with persistent dialog:")
+    try:
+        example_dialog_conversation()
+    except Exception as e:
+        print(f"Error: {e}")

mbxai-2.1.0/src/mbxai/examples/agent_logging_example.py

@@ -0,0 +1,212 @@
+"""
+Example demonstrating the enhanced logging and token tracking features of the AgentClient.
+"""
+
+import os
+import logging
+from pydantic import BaseModel, Field
+
+from mbxai.openrouter import OpenRouterClient
+from mbxai.agent import AgentClient
+
+# Configure logging to see all the agent information
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+class WeatherResponse(BaseModel):
+    """Response format for weather information."""
+    location: str = Field(description="The location requested")
+    current_conditions: str = Field(description="Current weather conditions")
+    temperature: str = Field(description="Current temperature")
+    forecast: str = Field(description="Weather forecast")
+    recommendation: str = Field(description="Clothing or activity recommendation based on weather")
+
+class AnalysisResponse(BaseModel):
+    """Response format for complex analysis."""
+    summary: str = Field(description="Executive summary of the analysis")
+    key_findings: list[str] = Field(description="List of key findings")
+    methodology: str = Field(description="How the analysis was conducted")
+    recommendations: list[str] = Field(description="Actionable recommendations")
+    confidence_level: str = Field(description="Confidence level in the analysis")
+
+def demonstrate_agent_with_questions():
+    """Demonstrate agent process with question generation."""
+    print("\n" + "="*60)
+    print("🔍 DEMO: Agent with Question Generation")
+    print("="*60)
+    
+    try:
+        # Note: This requires a real OpenRouter API key
+        api_key = os.getenv("OPENROUTER_API_KEY")
+        if not api_key:
+            print("❌ OPENROUTER_API_KEY not found. Using mock example.")
+            print("Set OPENROUTER_API_KEY environment variable to run with real API calls.")
+            return
+        
+        openrouter_client = OpenRouterClient(token=api_key)
+        agent = AgentClient(openrouter_client, max_iterations=2)
+        
+        prompt = "I need weather information for planning my outdoor activities this weekend."
+        
+        print(f"📤 Sending prompt: {prompt}")
+        response = agent.agent(prompt, WeatherResponse, ask_questions=True)
+        
+        if response.has_questions():
+            print(f"\n📋 Agent generated {len(response.questions)} questions:")
+            for i, question in enumerate(response.questions, 1):
+                print(f"  {i}. {question.question} (key: {question.key})")
+            
+            if response.token_summary:
+                print(f"\n📊 Token usage for question generation:")
+                print(f"   - Prompt tokens: {response.token_summary.question_generation.prompt_tokens}")
+                print(f"   - Completion tokens: {response.token_summary.question_generation.completion_tokens}")
+                print(f"   - Total tokens: {response.token_summary.question_generation.total_tokens}")
+            
+            # Simulate user providing answers
+            from mbxai.agent.models import AnswerList, Answer
+            
+            answers = AnswerList(answers=[
+                Answer(key="location", answer="San Francisco, CA"),
+                Answer(key="activity_type", answer="hiking and outdoor photography"),
+                Answer(key="time_frame", answer="Saturday and Sunday morning")
+            ])
+            
+            print(f"\n📝 Providing answers and continuing...")
+            final_response = agent.answer_to_agent(response.agent_id, answers)
+            
+            if final_response.is_complete():
+                print("\n✅ Final response received!")
+                print(f"📊 Complete token summary:")
+                if final_response.token_summary:
+                    ts = final_response.token_summary
+                    print(f"   - Question generation: {ts.question_generation.total_tokens} tokens")
+                    print(f"   - Thinking process: {ts.thinking_process.total_tokens} tokens")
+                    print(f"   - Quality checks: {sum(q.total_tokens for q in ts.quality_checks)} tokens ({len(ts.quality_checks)} checks)")
+                    print(f"   - Improvements: {sum(i.total_tokens for i in ts.improvements)} tokens ({len(ts.improvements)} iterations)")
+                    print(f"   - Final response: {ts.final_response.total_tokens} tokens")
+                    print(f"   - TOTAL: {ts.total_tokens} tokens")
+                
+                # Access the structured response
+                weather_data = final_response.final_response
+                print(f"\n🌤️  Weather for {weather_data.location}:")
+                print(f"   Current: {weather_data.current_conditions}")
+                print(f"   Temperature: {weather_data.temperature}")
+                print(f"   Recommendation: {weather_data.recommendation}")
+        
+    except Exception as e:
+        print(f"❌ Error: {e}")
+
+def demonstrate_agent_without_questions():
+    """Demonstrate agent process without question generation."""
+    print("\n" + "="*60)
+    print("⚡ DEMO: Agent without Question Generation (Direct Processing)")
+    print("="*60)
+    
+    try:
+        # Note: This requires a real OpenRouter API key
+        api_key = os.getenv("OPENROUTER_API_KEY")
+        if not api_key:
+            print("❌ OPENROUTER_API_KEY not found. Using mock example.")
+            print("Set OPENROUTER_API_KEY environment variable to run with real API calls.")
+            return
+        
+        openrouter_client = OpenRouterClient(token=api_key)
+        agent = AgentClient(openrouter_client, max_iterations=1)
+        
+        prompt = """
+        Analyze the current state of renewable energy adoption in Europe. 
+        Focus on solar and wind power, include recent statistics, challenges, 
+        and future outlook for the next 5 years.
+        """
+        
+        print(f"📤 Sending prompt: {prompt[:100]}...")
+        response = agent.agent(prompt, AnalysisResponse, ask_questions=False)
+        
+        if response.is_complete():
+            print("\n✅ Analysis completed!")
+            
+            if response.token_summary:
+                ts = response.token_summary
+                print(f"\n📊 Token usage breakdown:")
+                print(f"   - Thinking process: {ts.thinking_process.total_tokens} tokens")
+                print(f"   - Quality checks: {sum(q.total_tokens for q in ts.quality_checks)} tokens ({len(ts.quality_checks)} checks)")
+                print(f"   - Improvements: {sum(i.total_tokens for i in ts.improvements)} tokens ({len(ts.improvements)} iterations)")
+                print(f"   - Final response: {ts.final_response.total_tokens} tokens")
+                print(f"   - TOTAL: {ts.total_tokens} tokens")
+            
+            # Access the structured response
+            analysis = response.final_response
+            print(f"\n📊 Analysis Results:")
+            print(f"   Summary: {analysis.summary[:150]}...")
+            print(f"   Key Findings: {len(analysis.key_findings)} items")
+            print(f"   Recommendations: {len(analysis.recommendations)} items")
+            print(f"   Confidence: {analysis.confidence_level}")
+        
+    except Exception as e:
+        print(f"❌ Error: {e}")
+
+def demonstrate_different_iteration_settings():
+    """Demonstrate different max_iterations settings and their effect on token usage."""
+    print("\n" + "="*60)
+    print("🔄 DEMO: Different Iteration Settings")
+    print("="*60)
+    
+    iteration_configs = [
+        {"iterations": 0, "description": "No quality checks"},
+        {"iterations": 1, "description": "Basic quality check"},
+        {"iterations": 3, "description": "Thorough quality improvement"}
+    ]
+    
+    prompt = "Explain quantum computing in simple terms for a business audience."
+    
+    for config in iteration_configs:
+        print(f"\n📋 Testing with {config['iterations']} max iterations ({config['description']})")
+        print("-" * 40)
+        
+        try:
+            api_key = os.getenv("OPENROUTER_API_KEY")
+            if not api_key:
+                print(f"   ❌ Skipping - OPENROUTER_API_KEY not found")
+                continue
+            
+            openrouter_client = OpenRouterClient(token=api_key)
+            agent = AgentClient(openrouter_client, max_iterations=config["iterations"])
+            
+            print(f"   🚀 Processing with max_iterations={config['iterations']}")
+            print(f"   - Description: {config['description']}")
+            print(f"   - Expected processing time: {'Low' if config['iterations'] <= 1 else 'Medium' if config['iterations'] <= 2 else 'High'}")
+            print(f"   - Expected response quality: {'Basic' if config['iterations'] == 0 else 'Good' if config['iterations'] <= 2 else 'Excellent'}")
+            
+            # In real usage, you would call:
+            # response = agent.agent(prompt, AnalysisResponse, ask_questions=False)
+            
+        except Exception as e:
+            print(f"   ❌ Error: {e}")
+
+if __name__ == "__main__":
+    print("🤖 Agent Client Logging and Token Tracking Demo")
+    print("This example demonstrates the enhanced logging and token usage tracking features.")
+    
+    # Check for API key
+    api_key = os.getenv("OPENROUTER_API_KEY")
+    if not api_key:
+        print("\n⚠️  Note: To run with real API calls, set the OPENROUTER_API_KEY environment variable.")
+        print("The examples will show the logging structure but won't make actual API calls.")
+    
+    # Run demonstrations
+    demonstrate_agent_with_questions()
+    demonstrate_agent_without_questions() 
+    demonstrate_different_iteration_settings()
+    
+    print("\n✅ Demo completed!")
+    print("\nTo see the logging in action, run this script with a valid OPENROUTER_API_KEY.")
+    print("You'll see detailed logs showing:")
+    print("   - 🚀 Agent process start")
+    print("   - ❓ Question generation")
+    print("   - 🧠 Thinking process")
+    print("   - 🔍 Quality checks")
+    print("   - ⚡ Improvements")
+    print("   - 📝 Final response generation")
+    print("   - 📊 Complete token usage summary")

mbxai-2.1.0/src/mbxai/examples/dialog_agent_example.py

@@ -0,0 +1,157 @@
+"""
+Example usage of the AgentClient with persistent dialog sessions.
+"""
+
+import os
+from pydantic import BaseModel, Field
+from mbxai import AgentClient, OpenRouterClient, AnswerList, Answer
+
+
+class ChatResponse(BaseModel):
+    """A general chat response."""
+    response: str = Field(description="The response to the user's message")
+    context_awareness: str = Field(description="How this response relates to previous conversation")
+
+
+class BookRecommendation(BaseModel):
+    """A book recommendation response."""
+    title: str = Field(description="The title of the recommended book")
+    author: str = Field(description="The author of the book")
+    genre: str = Field(description="The genre of the book")
+    reason: str = Field(description="Why this book is recommended based on conversation")
+    connection_to_previous: str = Field(description="How this recommendation connects to our previous conversation")
+
+
+def demonstrate_dialog_conversation():
+    """Demonstrate persistent dialog functionality."""
+    print("🔄 DEMO: Persistent Dialog Agent")
+    print("=" * 50)
+    
+    # Initialize the clients
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "your-token-here"))
+    agent = AgentClient(openrouter_client, max_iterations=1)
+    
+    # First conversation - start new session
+    print("\n1️⃣ Starting new conversation:")
+    prompt1 = "Hi, I'm looking for a good book to read. I love science fiction."
+    response1 = agent.agent(prompt1, ChatResponse, ask_questions=False)
+    
+    if response1.is_complete():
+        agent_id = response1.agent_id
+        chat_resp = response1.final_response
+        print(f"Agent ID: {agent_id}")
+        print(f"Response: {chat_resp.response}")
+        print(f"Context awareness: {chat_resp.context_awareness}")
+        
+        # Second conversation - continue same session
+        print(f"\n2️⃣ Continuing conversation with agent {agent_id}:")
+        prompt2 = "Actually, I also enjoy fantasy novels. What would you recommend that combines both genres?"
+        response2 = agent.agent(prompt2, BookRecommendation, ask_questions=False, agent_id=agent_id)
+        
+        if response2.is_complete():
+            book_rec = response2.final_response
+            print(f"Book: {book_rec.title} by {book_rec.author}")
+            print(f"Genre: {book_rec.genre}")
+            print(f"Reason: {book_rec.reason}")
+            print(f"Connection to previous: {book_rec.connection_to_previous}")
+            
+            # Third conversation - continue same session
+            print(f"\n3️⃣ Continuing conversation with agent {agent_id}:")
+            prompt3 = "That sounds great! Can you recommend something similar but from a different author?"
+            response3 = agent.agent(prompt3, BookRecommendation, ask_questions=False, agent_id=agent_id)
+            
+            if response3.is_complete():
+                book_rec2 = response3.final_response
+                print(f"Book: {book_rec2.title} by {book_rec2.author}")
+                print(f"Genre: {book_rec2.genre}")
+                print(f"Reason: {book_rec2.reason}")
+                print(f"Connection to previous: {book_rec2.connection_to_previous}")
+        
+        # Show session info
+        print(f"\n📊 Session Information:")
+        try:
+            session_info = agent.get_session_info(agent_id)
+            print(f"Conversation length: {session_info['conversation_length']} messages")
+            print(f"Session step: {session_info.get('step', 'unknown')}")
+        except Exception as e:
+            print(f"Error getting session info: {e}")
+        
+        # List all sessions
+        print(f"\n📝 Active sessions: {agent.list_sessions()}")
+        
+        # Cleanup - optional
+        print(f"\n🗑️ Cleaning up session...")
+        deleted = agent.delete_session(agent_id)
+        print(f"Session deleted: {deleted}")
+        print(f"Active sessions after cleanup: {agent.list_sessions()}")
+
+
+def demonstrate_dialog_with_questions():
+    """Demonstrate dialog with question-answer flow."""
+    print("\n🔄 DEMO: Dialog Agent with Questions")
+    print("=" * 50)
+    
+    # Initialize the clients
+    openrouter_client = OpenRouterClient(token=os.getenv("OPENROUTER_API_KEY", "your-token-here"))
+    agent = AgentClient(openrouter_client, max_iterations=1)
+    
+    # First conversation with questions
+    print("\n1️⃣ Starting conversation with questions:")
+    prompt1 = "I want a personalized book recommendation"
+    response1 = agent.agent(prompt1, BookRecommendation, ask_questions=True)
+    
+    agent_id = response1.agent_id
+    print(f"Agent ID: {agent_id}")
+    
+    if response1.has_questions():
+        print(f"\n📋 Agent generated {len(response1.questions)} questions:")
+        for i, question in enumerate(response1.questions, 1):
+            print(f"  {i}. {question.question} (key: {question.key})")
+        
+        # Simulate answering questions
+        answers = AnswerList(answers=[
+            Answer(key="genre_preference", answer="I love science fiction and fantasy"),
+            Answer(key="reading_level", answer="I prefer complex, adult novels"),
+            Answer(key="recent_books", answer="I recently read and loved Dune and The Name of the Wind")
+        ])
+        
+        print(f"\n📝 Providing answers...")
+        final_response = agent.answer_to_agent(agent_id, answers)
+        
+        if final_response.is_complete():
+            book_rec = final_response.final_response
+            print(f"Book: {book_rec.title} by {book_rec.author}")
+            print(f"Genre: {book_rec.genre}")
+            print(f"Reason: {book_rec.reason}")
+            
+            # Continue conversation - this should remember the previous interaction
+            print(f"\n2️⃣ Continuing conversation with agent {agent_id}:")
+            prompt2 = "Thank you! Can you also recommend something by a female author in the same genres?"
+            response2 = agent.agent(prompt2, BookRecommendation, ask_questions=False, agent_id=agent_id)
+            
+            if response2.is_complete():
+                book_rec2 = response2.final_response
+                print(f"Book: {book_rec2.title} by {book_rec2.author}")
+                print(f"Genre: {book_rec2.genre}")
+                print(f"Reason: {book_rec2.reason}")
+                print(f"Connection to previous: {book_rec2.connection_to_previous}")
+        
+        # Session cleanup
+        print(f"\n🗑️ Session cleanup...")
+        agent.delete_session(agent_id)
+
+
+if __name__ == "__main__":
+    print("=== Dialog Agent Examples ===\n")
+    
+    try:
+        demonstrate_dialog_conversation()
+    except Exception as e:
+        print(f"Error in dialog conversation demo: {e}")
+    
+    print("\n" + "="*80 + "\n")
+    
+    try:
+        demonstrate_dialog_with_questions()
+    except Exception as e:
+        print(f"Error in dialog with questions demo: {e}")

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

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