Release v3.10.27

Author: MervinPraison

docker/Dockerfile.chat

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=3.10.26" \
+    "praisonai>=3.10.27" \
     "praisonai[chat]" \
     "embedchain[github,youtube]"
 

docker/Dockerfile.dev

@@ -20,7 +20,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=3.10.26" \
+    "praisonai>=3.10.27" \
     "praisonai[ui]" \
     "praisonai[chat]" \
     "praisonai[realtime]" \

docker/Dockerfile.ui

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=3.10.26" \
+    "praisonai>=3.10.27" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

examples/python/save_output/05_output_config_file.py

@@ -0,0 +1,49 @@
+"""
+Example: Auto-save agent output to file
+
+This example demonstrates how to automatically save agent responses to files.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.config import OutputConfig
+
+# Method 1: Simplest - just pass a file path string
+agent = Agent(
+    instructions="You are a helpful assistant",
+    output="output/response.txt"  # Just a string path!
+)
+
+# When you call start(), the response is automatically saved
+# result = agent.start("Write a short greeting")
+# Prints: ✅ Output saved to output/response.txt
+
+# Method 2: With template formatting using OutputConfig
+agent_with_template = Agent(
+    instructions="You are a blog writer",
+    output=OutputConfig(
+        output_file="output/blog_post.md",
+        template="""# {{title}}
+
+{{content}}
+
+---
+*Generated by AI*
+"""
+    )
+)
+
+# The agent will format its response according to the template
+# result = agent_with_template.start("Write about Python programming")
+
+# Method 3: Combine with other output settings
+agent_verbose = Agent(
+    instructions="You are a researcher",
+    output=OutputConfig(
+        verbose=True,           # Show rich output in terminal
+        output_file="output/research.md",  # Also save to file
+        template="## Research Summary\n\n{{content}}"
+    )
+)
+
+print("Examples ready! Uncomment agent.start() calls to run.")
+print("Output will be saved to the specified files automatically.")

src/praisonai-agents/llm-gemini-advanced.py

@@ -2,7 +2,7 @@
 
 # Detailed LLM configuration
 llm_config = {
-    "model": "gemini/gemini-1.5-flash-latest",  # Model name without provider prefix
+    "model": "gemini/gemini-3-flash-preview",  # Model name without provider prefix
 
     # Core settings
     "temperature": 0.7,                # Controls randomness (like temperature)
@@ -25,7 +25,7 @@
 
     # Additional controls
     "seed": 42,                      # For reproducible responses
-    "stop_phrases": ["##", "END"],   # Custom stop sequences
+    "stop_phrases": ["---END---", "END"],   # Custom stop sequences
 }
 
 agent = Agent(

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -93,6 +93,31 @@ def _get_stream_emitter():
         _stream_emitter_class = StreamEventEmitter
     return _stream_emitter_class
 
+# File extensions that indicate a file path (for output parameter detection)
+_FILE_EXTENSIONS = frozenset({'.txt', '.md', '.json', '.yaml', '.yml', '.html', '.csv', '.log', '.xml', '.rst'})
+
+def _is_file_path(value: str) -> bool:
+    """Check if a string looks like a file path (not a preset name).
+    
+    Used to detect when output="path/to/file.txt" should be treated as
+    output_file instead of a preset name.
+    
+    Args:
+        value: String to check
+        
+    Returns:
+        True if the string looks like a file path
+    """
+    # Contains path separator
+    if '/' in value or '\\' in value:
+        return True
+    # Ends with common file extension
+    lower = value.lower()
+    for ext in _FILE_EXTENSIONS:
+        if lower.endswith(ext):
+            return True
+    return False
+
 # ============================================================================
 # Performance: Module-level imports for param resolution (moved from __init__)
 # These imports are lightweight and avoid per-Agent import overhead
@@ -571,6 +596,9 @@ def __init__(
             preset_value = OUTPUT_PRESETS.get(output_lower)
             if preset_value is not None:
                 _output_config = OutputConfig(**preset_value) if isinstance(preset_value, dict) else preset_value
+            elif _is_file_path(output):
+                # String looks like a file path - use as output_file
+                _output_config = OutputConfig(output_file=output)
             else:
                 _output_config = OutputConfig()  # Default silent
         elif isinstance(output, OutputConfig):
@@ -596,6 +624,8 @@ def __init__(
             json_output = getattr(_output_config, 'json_output', False)
             status_trace = getattr(_output_config, 'status_trace', False)  # New: clean inline status
             simple_output = getattr(_output_config, 'simple_output', False)  # status preset: no timestamps
+            output_file = getattr(_output_config, 'output_file', None)  # Auto-save to file
+            output_template = getattr(_output_config, 'template', None)  # Response template
         else:
             # Fallback defaults match silent mode (zero overhead)
             verbose, markdown, stream, metrics, reasoning_steps = False, False, False, False, False
@@ -1353,6 +1383,10 @@ def __init__(
 
         # Action trace mode - handled via display callbacks, not separate emitter
         self._actions_trace = actions_trace
+        
+        # Output file and template - for auto-saving response to file
+        self._output_file = output_file if _output_config else None
+        self._output_template = output_template if _output_config else None
 
         # Telemetry - lazy initialized via property for performance
         self.__telemetry = None
@@ -3835,6 +3869,7 @@ def _build_multimodal_prompt(
                                 "type": "image_url",
                                 "image_url": {"url": f"data:{media_type};base64,{data}"}
                             })
+                            logging.debug(f"Successfully encoded image attachment: {attachment} ({len(data)} bytes base64)")
                         except Exception as e:
                             logging.warning(f"Failed to load attachment {attachment}: {e}")
                 elif attachment.startswith(('http://', 'https://', 'data:')):
@@ -4393,7 +4428,7 @@ def session_id(self) -> Optional[str]:
         """Get the current session ID."""
         return self._session_id
 
-    def chat(self, prompt, temperature=1.0, tools=None, output_json=None, output_pydantic=None, reasoning_steps=False, stream=None, task_name=None, task_description=None, task_id=None, config=None, force_retrieval=False, skip_retrieval=False, attachments=None):
+    def chat(self, prompt, temperature=1.0, tools=None, output_json=None, output_pydantic=None, reasoning_steps=False, stream=None, task_name=None, task_description=None, task_id=None, config=None, force_retrieval=False, skip_retrieval=False, attachments=None, tool_choice=None):
         """
         Chat with the agent.
         
@@ -4402,6 +4437,8 @@ def chat(self, prompt, temperature=1.0, tools=None, output_json=None, output_pyd
             attachments: Optional list of image/file paths that are ephemeral
                         (used for THIS turn only, NEVER stored in history).
                         Supports: file paths, URLs, or data URIs.
+            tool_choice: Optional tool choice mode ('auto', 'required', 'none').
+                        'required' forces the LLM to call a tool before responding.
             ...other args...
         """
         # Emit context trace event (zero overhead when not set)
@@ -4410,11 +4447,11 @@ def chat(self, prompt, temperature=1.0, tools=None, output_json=None, output_pyd
         _trace_emitter.agent_start(self.name, {"role": self.role, "goal": self.goal})
 
         try:
-            return self._chat_impl(prompt, temperature, tools, output_json, output_pydantic, reasoning_steps, stream, task_name, task_description, task_id, config, force_retrieval, skip_retrieval, attachments, _trace_emitter)
+            return self._chat_impl(prompt, temperature, tools, output_json, output_pydantic, reasoning_steps, stream, task_name, task_description, task_id, config, force_retrieval, skip_retrieval, attachments, _trace_emitter, tool_choice)
         finally:
             _trace_emitter.agent_end(self.name)
 
-    def _chat_impl(self, prompt, temperature, tools, output_json, output_pydantic, reasoning_steps, stream, task_name, task_description, task_id, config, force_retrieval, skip_retrieval, attachments, _trace_emitter):
+    def _chat_impl(self, prompt, temperature, tools, output_json, output_pydantic, reasoning_steps, stream, task_name, task_description, task_id, config, force_retrieval, skip_retrieval, attachments, _trace_emitter, tool_choice=None):
         """Internal chat implementation (extracted for trace wrapping)."""
         # Apply rate limiter if configured (before any LLM call)
         if self._rate_limiter is not None:
@@ -4424,6 +4461,20 @@ def _chat_impl(self, prompt, temperature, tools, output_json, output_pydantic, r
         # IMPORTANT: Original text 'prompt' is stored in history, attachments are NOT
         llm_prompt = self._build_multimodal_prompt(prompt, attachments) if attachments else prompt
 
+        # Apply response template if configured (DRY: TemplateConfig.response is canonical,
+        # OutputConfig.template is fallback for backward compatibility)
+        effective_template = self.response_template or self._output_template
+        if effective_template:
+            template_instruction = f"\n\nIMPORTANT: Format your response according to this template:\n{effective_template}"
+            if isinstance(llm_prompt, str):
+                llm_prompt = llm_prompt + template_instruction
+            elif isinstance(llm_prompt, list):
+                # For multimodal prompts, append to the last text content
+                for i in range(len(llm_prompt) - 1, -1, -1):
+                    if isinstance(llm_prompt[i], dict) and llm_prompt[i].get('type') == 'text':
+                        llm_prompt[i]['text'] = llm_prompt[i]['text'] + template_instruction
+                        break
+        
         # Initialize DB session on first chat (lazy)
         self._init_db_session()
 
@@ -4591,30 +4642,40 @@ def _chat_impl(self, prompt, temperature, tools, output_json, output_pydantic, r
                     )
 
                     # Pass everything to LLM class
-                    response_text = self.llm_instance.get_response(
-                    prompt=prompt,
-                    system_prompt=system_prompt_for_llm,
-                    chat_history=processed_history,
-                    temperature=temperature,
-                    tools=tool_param,
-                    output_json=output_json,
-                    output_pydantic=output_pydantic,
-                    verbose=self.verbose,
-                    markdown=self.markdown,
-                    reflection=self.self_reflect,
-                    max_reflect=self.max_reflect,
-                    min_reflect=self.min_reflect,
-                    console=self.console,
-                    agent_name=self.name,
-                    agent_role=self.role,
-                    agent_tools=[t.__name__ if hasattr(t, '__name__') else str(t) for t in (tools if tools is not None else self.tools)],
-                    task_name=task_name,
-                    task_description=task_description,
-                    task_id=task_id,
-                    execute_tool_fn=self.execute_tool,  # Pass tool execution function
-                    reasoning_steps=reasoning_steps,
-                    stream=stream  # Pass the stream parameter from chat method
+                    # Use llm_prompt (which includes multimodal content if attachments present)
+                    # Build LLM call kwargs
+                    llm_kwargs = dict(
+                        prompt=llm_prompt,
+                        system_prompt=system_prompt_for_llm,
+                        chat_history=processed_history,
+                        temperature=temperature,
+                        tools=tool_param,
+                        output_json=output_json,
+                        output_pydantic=output_pydantic,
+                        verbose=self.verbose,
+                        markdown=self.markdown,
+                        reflection=self.self_reflect,
+                        max_reflect=self.max_reflect,
+                        min_reflect=self.min_reflect,
+                        console=self.console,
+                        agent_name=self.name,
+                        agent_role=self.role,
+                        agent_tools=[t.__name__ if hasattr(t, '__name__') else str(t) for t in (tools if tools is not None else self.tools)],
+                        task_name=task_name,
+                        task_description=task_description,
+                        task_id=task_id,
+                        execute_tool_fn=self.execute_tool,
+                        reasoning_steps=reasoning_steps,
+                        stream=stream
                     )
+                    
+                    # Pass tool_choice if specified (auto, required, none)
+                    # Also check for YAML-configured tool_choice on the agent
+                    effective_tool_choice = tool_choice or getattr(self, '_yaml_tool_choice', None)
+                    if effective_tool_choice:
+                        llm_kwargs['tool_choice'] = effective_tool_choice
+                    
+                    response_text = self.llm_instance.get_response(**llm_kwargs)
 
                     self.chat_history.append({"role": "assistant", "content": response_text})
                     # Persist assistant message to DB
@@ -4658,8 +4719,9 @@ def _chat_impl(self, prompt, temperature, tools, output_json, output_pydantic, r
                     logging.debug(f"Agent {self.name} using native structured output with response_format")
 
             # Use the new _build_messages helper method
+            # Pass llm_prompt (which includes multimodal content if attachments present)
             messages, original_prompt = self._build_messages(
-                prompt, temperature, output_json, output_pydantic,
+                llm_prompt, temperature, output_json, output_pydantic,
                 use_native_format=use_native_format
             )
 
@@ -5816,6 +5878,10 @@ def run_chat():
             # Auto-save session if enabled
             self._auto_save_session()
 
+            # Auto-save output to file if configured
+            if result and self._output_file:
+                self._save_output_to_file(str(result))
+            
             return result
         finally:
             # Restore original output settings
@@ -5894,6 +5960,44 @@ def _auto_save_session(self):
         except Exception as e:
             logging.debug(f"Error auto-saving session: {e}")
 
+    def _save_output_to_file(self, content: str) -> bool:
+        """Save agent output to file if output_file is configured.
+        
+        Args:
+            content: The response content to save
+            
+        Returns:
+            True if file was saved, False otherwise
+        """
+        if not self._output_file:
+            return False
+        
+        try:
+            import os
+            
+            # Expand user home directory and resolve path
+            file_path = os.path.expanduser(self._output_file)
+            file_path = os.path.abspath(file_path)
+            
+            # Create parent directories if they don't exist
+            parent_dir = os.path.dirname(file_path)
+            if parent_dir and not os.path.exists(parent_dir):
+                os.makedirs(parent_dir, exist_ok=True)
+            
+            # Write content to file
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(str(content))
+            
+            # Print success message to terminal
+            print(f"✅ Output saved to {file_path}")
+            logging.debug(f"Output saved to file: {file_path}")
+            return True
+            
+        except Exception as e:
+            logging.warning(f"Failed to save output to file '{self._output_file}': {e}")
+            print(f"⚠️ Failed to save output to {self._output_file}: {e}")
+            return False
+
     def _start_stream(self, prompt: str, **kwargs) -> Generator[str, None, None]:
         """Stream generator for real-time response chunks."""
         try:

src/praisonai-agents/praisonaiagents/config/feature_configs.py

@@ -557,6 +557,15 @@ class OutputConfig:
     # Shows: [timestamp] Calling LLM..., Executing tool..., Response: ...
     status_trace: bool = False
 
+    # Output file - save agent response to file automatically
+    # When set, saves the response to the specified file path
+    output_file: Optional[str] = None
+    
+    # Output template - format template for the response
+    # Agent will be instructed to follow this template when generating response
+    # Example: "# {{title}}\n\n{{content}}\n\n---\nGenerated by AI"
+    template: Optional[str] = None
+    
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary."""
         return {
@@ -570,6 +579,8 @@ def to_dict(self) -> Dict[str, Any]:
             "simple_output": self.simple_output,
             "show_parameters": self.show_parameters,
             "status_trace": self.status_trace,
+            "output_file": self.output_file,
+            "template": self.template,
         }
 
 

src/praisonai-agents/praisonaiagents/context/manager.py

@@ -844,8 +844,9 @@ def capture_llm_boundary(
         message_hash = hashlib.sha256(messages_json.encode()).hexdigest()[:16]
         tools_hash = hashlib.sha256(tools_json.encode()).hexdigest()[:16]
 
+        from datetime import timezone
         hook_data = SnapshotHookData(
-            timestamp=datetime.utcnow().isoformat() + "Z",
+            timestamp=datetime.now(tz=timezone.utc).isoformat().replace('+00:00', 'Z'),
             messages=messages,
             tools=tools,
             message_hash=message_hash,
@@ -998,8 +999,9 @@ def _add_history_event(
         details: Optional[Dict[str, Any]] = None,
     ) -> None:
         """Add an event to optimization history."""
+        from datetime import timezone
         event = OptimizationEvent(
-            timestamp=datetime.utcnow().isoformat() + "Z",
+            timestamp=datetime.now(tz=timezone.utc).isoformat().replace('+00:00', 'Z'),
             event_type=event_type,
             strategy=strategy,
             tokens_before=tokens_before,