lollms-client 0.28.0__py3-none-any.whl → 0.29.0__py3-none-any.whl

lollms_client/__init__.py

@@ -8,7 +8,7 @@ from lollms_client.lollms_utilities import PromptReshaper # Keep general utiliti
 from lollms_client.lollms_mcp_binding import LollmsMCPBinding, LollmsMCPBindingManager
 from lollms_client.lollms_llm_binding import LollmsLLMBindingManager
 
-__version__ = "0.28.0" # Updated version
+__version__ = "0.29.0" # Updated version
 
 # Optionally, you could define __all__ if you want to be explicit about exports
 __all__ = [

lollms_client/lollms_core.py

@@ -2008,7 +2008,7 @@ Do not split the code in multiple tags.
         self,
         prompt,
         output_format,
-        extra_system_prompt=None,
+        system_prompt=None,
         **kwargs
     ):
         """
@@ -2025,7 +2025,7 @@ Do not split the code in multiple tags.
                 A Python dictionary or a JSON string representing the desired output 
                 structure. This will be used as a template for the LLM.
                 Example: {"name": "string", "age": "integer", "city": "string"}
-            extra_system_prompt (str, optional): 
+            system_prompt (str, optional): 
                 Additional instructions for the system prompt, to be appended to the 
                 main instructions. Defaults to None.
             **kwargs: 
@@ -2048,7 +2048,7 @@ Do not split the code in multiple tags.
             raise TypeError("output_format must be a dict or a JSON string.")
 
         # 2. Construct a specialized system prompt for structured data generation
-        system_prompt = (
+        full_system_prompt = (
             "You are a highly skilled AI assistant that processes user requests "
             "and returns structured data in JSON format. You must strictly adhere "
             "to the provided JSON template, filling in the values accurately based "
@@ -2056,8 +2056,8 @@ Do not split the code in multiple tags.
             "outside of the final JSON code block. Your entire response must be a single "
             "valid JSON object within a markdown code block."
         )
-        if extra_system_prompt:
-            system_prompt += f"\n\nAdditional instructions:\n{extra_system_prompt}"
+        if system_prompt:
+            system_prompt += f"\n\nAdditional instructions:\n{system_prompt}"
 
         # 3. Call the underlying generate_code method with JSON-specific settings
         if kwargs.get('debug'):
@@ -2065,7 +2065,7 @@ Do not split the code in multiple tags.
 
         json_string = self.generate_code(
             prompt=prompt,
-            system_prompt=system_prompt,
+            system_prompt=full_system_prompt,
             template=template_str,
             language="json",
             code_tag_format="markdown", # Sticking to markdown is generally more reliable
@@ -2083,7 +2083,7 @@ Do not split the code in multiple tags.
 
         try:
             # Use the provided robust parser
-            parsed_json = self.robust_json_parser(json_string)
+            parsed_json = robust_json_parser(json_string)
             
             if parsed_json is None:
                 ASCIIColors.warning("Failed to robustly parse the generated JSON.")

lollms_client/lollms_discussion.py

@@ -31,6 +31,7 @@ if False:
 
 from lollms_client.lollms_utilities import build_image_dicts, robust_json_parser
 from ascii_colors import ASCIIColors, trace_exception
+from .lollms_types import MSG_TYPE
 
 class EncryptedString(TypeDecorator):
     """A SQLAlchemy TypeDecorator for field-level database encryption.
@@ -127,6 +128,7 @@ def create_dynamic_models(
         __abstract__ = True
         id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
         system_prompt = Column(EncryptedText, nullable=True)
+        data_zone = Column(EncryptedText, nullable=True) # New field for persistent data
         participants = Column(JSON, nullable=True, default=dict)
         active_branch_id = Column(String, nullable=True)
         discussion_metadata = Column(JSON, nullable=True, default=dict)
@@ -223,6 +225,10 @@ class LollmsDataManager:
                 if 'pruning_point_id' not in columns:
                     print("  -> Upgrading 'discussions' table: Adding 'pruning_point_id' column.")
                     connection.execute(text("ALTER TABLE discussions ADD COLUMN pruning_point_id VARCHAR"))
+
+                if 'data_zone' not in columns:
+                    print("  -> Upgrading 'discussions' table: Adding 'data_zone' column.")
+                    connection.execute(text("ALTER TABLE discussions ADD COLUMN data_zone TEXT"))
                 
                 print("Database schema is up to date.")
                 # This is important to apply the ALTER TABLE statements
@@ -484,6 +490,7 @@ class LollmsDiscussion:
         proxy = SimpleNamespace()
         proxy.id = id or str(uuid.uuid4())
         proxy.system_prompt = None
+        proxy.data_zone = None
         proxy.participants = {}
         proxy.active_branch_id = None
         proxy.discussion_metadata = {}
@@ -642,21 +649,91 @@ class LollmsDiscussion:
             A dictionary with 'user_message' and 'ai_message' LollmsMessage objects,
             where the 'ai_message' will contain rich metadata if an agentic turn was used.
         """
+        callback = kwargs.get("streaming_callback")
+
         if personality is not None:
             object.__setattr__(self, '_system_prompt', personality.system_prompt)
+
+            # --- New Data Source Handling Logic ---
+            if hasattr(personality, 'data_source') and personality.data_source is not None:
+                if isinstance(personality.data_source, str):
+                    # --- Static Data Source ---
+                    if callback:
+                        callback("Loading static personality data...", MSG_TYPE.MSG_TYPE_STEP, {"id": "static_data_loading"})
+                    current_data_zone = self.data_zone or ""
+                    self.data_zone = (current_data_zone + "\n\n--- Personality Static Data ---\n" + personality.data_source).strip()
+
+                elif callable(personality.data_source):
+                    # --- Dynamic Data Source ---
+                    qg_id = None
+                    if callback:
+                        qg_id = callback("Generating query for dynamic personality data...", MSG_TYPE.MSG_TYPE_STEP_START, {"id": "dynamic_data_query_gen"})
+
+                    context_for_query = self.export('markdown')
+                    query_prompt = (
+                        "You are an expert query generator. Based on the current conversation, formulate a concise and specific query to retrieve relevant information from a knowledge base. "
+                        "The query will be used to fetch data that will help you answer the user's latest request.\n\n"
+                        f"--- Conversation History ---\n{context_for_query}\n\n"
+                        "--- Instructions ---\n"
+                        "Generate a single query string."
+                    )
+                    
+                    try:
+                        query_json = self.lollmsClient.generate_structured_content(
+                            prompt=query_prompt,
+                            output_format={"query": "Your generated search query here."},
+                            system_prompt="You are an AI assistant that generates search queries in JSON format.",
+                            temperature=0.0
+                        )
+
+                        if not query_json or "query" not in query_json:
+                            if callback:
+                                callback("Failed to generate data query.", MSG_TYPE.MSG_TYPE_EXCEPTION, {"id": qg_id})
+                        else:
+                            generated_query = query_json["query"]
+                            if callback:
+                                callback(f"Generated query: '{generated_query}'", MSG_TYPE.MSG_TYPE_STEP_END, {"id": qg_id, "query": generated_query})
+                            
+                            dr_id = None
+                            if callback:
+                                dr_id = callback("Retrieving dynamic data from personality source...", MSG_TYPE.MSG_TYPE_STEP_START, {"id": "dynamic_data_retrieval"})
+                            
+                            try:
+                                retrieved_data = personality.data_source(generated_query)
+                                if callback:
+                                    callback(f"Retrieved data successfully.", MSG_TYPE.MSG_TYPE_STEP_END, {"id": dr_id, "data_snippet": retrieved_data[:200]})
+                                
+                                current_data_zone = self.data_zone or ""
+                                self.data_zone = (current_data_zone + "\n\n--- Retrieved Dynamic Data ---\n" + retrieved_data).strip()
+
+                            except Exception as e:
+                                trace_exception(e)
+                                if callback:
+                                    callback(f"Error retrieving dynamic data: {e}", MSG_TYPE.MSG_TYPE_EXCEPTION, {"id": dr_id})
+                    except Exception as e:
+                        trace_exception(e)
+                        if callback:
+                            callback(f"An error occurred during query generation: {e}", MSG_TYPE.MSG_TYPE_EXCEPTION, {"id": qg_id})
+            
+        # Determine effective MCPs by combining personality defaults and turn-specific overrides
+        effective_use_mcps = use_mcps
+        if personality and hasattr(personality, 'active_mcps') and personality.active_mcps:
+            if effective_use_mcps in [None, False]:
+                effective_use_mcps = personality.active_mcps
+            elif isinstance(effective_use_mcps, list):
+                effective_use_mcps = list(set(effective_use_mcps + personality.active_mcps))
             
         if self.max_context_size is not None:
             self.summarize_and_prune(self.max_context_size)
 
         # Step 1: Add user message, now including any images.
         if add_user_message:
-            # Pass kwargs through to capture images and other potential message attributes
             user_msg = self.add_message(
                 sender="user", 
                 sender_type="user", 
                 content=user_message,
                 images=images,
-                **kwargs # Use kwargs to allow other fields to be set from the caller
+                **kwargs
             )
         else: # Regeneration logic
             if self.active_branch_id not in self._message_index:
@@ -665,11 +742,9 @@ class LollmsDiscussion:
             if user_msg_orm.sender_type != 'user':
                 raise ValueError(f"Regeneration failed: active branch tip is a '{user_msg_orm.sender_type}' message, not 'user'.")
             user_msg = LollmsMessage(self, user_msg_orm)
-            # For regeneration, we use the images from the original user message
             images = user_msg.images
 
-        # Step 2: Determine if this is a simple chat or a complex agentic turn.
-        is_agentic_turn = (use_mcps is not None and use_mcps) or (use_data_store is not None and use_data_store)
+        is_agentic_turn = (effective_use_mcps is not None and effective_use_mcps) or (use_data_store is not None and use_data_store)
         
         start_time = datetime.now()
         
@@ -678,79 +753,56 @@ class LollmsDiscussion:
         final_raw_response = ""
         final_content = ""
 
-        # Step 3: Execute the appropriate generation logic.
         if is_agentic_turn:
-            # --- AGENTIC TURN ---
             prompt_for_agent = self.export("markdown", branch_tip_id if branch_tip_id else self.active_branch_id)
             if debug:
-                ASCIIColors.cyan("\n" + "="*50)
-                ASCIIColors.cyan("--- DEBUG: AGENTIC TURN TRIGGERED ---")
-                ASCIIColors.cyan(f"--- PROMPT FOR AGENT (from discussion history) ---")
-                ASCIIColors.magenta(prompt_for_agent)
-                ASCIIColors.cyan("="*50 + "\n")
+                ASCIIColors.cyan("\n" + "="*50 + "\n--- DEBUG: AGENTIC TURN TRIGGERED ---\n" + f"--- PROMPT FOR AGENT (from discussion history) ---\n{prompt_for_agent}\n" + "="*50 + "\n")
 
             agent_result = self.lollmsClient.generate_with_mcp_rag(
                 prompt=prompt_for_agent,
-                use_mcps=use_mcps,
+                use_mcps=effective_use_mcps,
                 use_data_store=use_data_store,
                 max_reasoning_steps=max_reasoning_steps,
                 images=images,
                 system_prompt = self._system_prompt,
-                debug=debug, # Pass the debug flag down
+                debug=debug,
                 **kwargs
             )
             final_content = agent_result.get("final_answer", "The agent did not produce a final answer.")
             final_scratchpad = agent_result.get("final_scratchpad", "")
             final_raw_response = json.dumps(agent_result, indent=2)
-
         else:
-            # --- SIMPLE CHAT TURN ---
             if debug:
                 prompt_for_chat = self.export("markdown", branch_tip_id if branch_tip_id else self.active_branch_id)
-                ASCIIColors.cyan("\n" + "="*50)
-                ASCIIColors.cyan("--- DEBUG: SIMPLE CHAT PROMPT ---")
-                ASCIIColors.magenta(prompt_for_chat)
-                ASCIIColors.cyan("="*50 + "\n")
+                ASCIIColors.cyan("\n" + "="*50 + f"\n--- DEBUG: SIMPLE CHAT PROMPT ---\n{prompt_for_chat}\n" + "="*50 + "\n")
 
-            # For simple chat, we also need to consider images if the model is multi-modal
             final_raw_response = self.lollmsClient.chat(self, images=images, **kwargs) or ""
             
             if debug:
-                ASCIIColors.cyan("\n" + "="*50)
-                ASCIIColors.cyan("--- DEBUG: RAW SIMPLE CHAT RESPONSE ---")
-                ASCIIColors.magenta(final_raw_response)
-                ASCIIColors.cyan("="*50 + "\n")
+                ASCIIColors.cyan("\n" + "="*50 + f"\n--- DEBUG: RAW SIMPLE CHAT RESPONSE ---\n{final_raw_response}\n" + "="*50 + "\n")
 
             if isinstance(final_raw_response, dict) and final_raw_response.get("status") == "error":
                 raise Exception(final_raw_response.get("message", "Unknown error from lollmsClient.chat"))
             else:
                 final_content = self.lollmsClient.remove_thinking_blocks(final_raw_response)
+            final_scratchpad = None
 
-            final_scratchpad = None # No agentic scratchpad in a simple turn
-
-        # Step 4: Post-generation processing and statistics.
         end_time = datetime.now()
         duration = (end_time - start_time).total_seconds()
         token_count = self.lollmsClient.count_tokens(final_content)
         tok_per_sec = (token_count / duration) if duration > 0 else 0
 
-        # Step 5: Collect metadata from the agentic turn for storage.
         message_meta = {}
         if is_agentic_turn and isinstance(agent_result, dict):
-            if "tool_calls" in agent_result:
-                message_meta["tool_calls"] = agent_result["tool_calls"]
-            if "sources" in agent_result:
-                message_meta["sources"] = agent_result["sources"]
-            if agent_result.get("clarification_required", False):
-                message_meta["clarification_required"] = True
-
-        # Step 6: Add the final AI message to the discussion.
+            if "tool_calls" in agent_result: message_meta["tool_calls"] = agent_result["tool_calls"]
+            if "sources" in agent_result: message_meta["sources"] = agent_result["sources"]
+            if agent_result.get("clarification_required", False): message_meta["clarification_required"] = True
+
         ai_message_obj = self.add_message(
             sender=personality.name if personality else "assistant",
             sender_type="assistant",
             content=final_content,
             raw_content=final_raw_response,
-            # Store the agent's full reasoning log in the message's dedicated scratchpad field
             scratchpad=final_scratchpad,
             tokens=token_count,
             generation_speed=tok_per_sec,
@@ -892,7 +944,13 @@ class LollmsDiscussion:
             return "" if format_type == "lollms_text" else []
 
         branch = self.get_branch(branch_tip_id)
-        full_system_prompt = self._system_prompt # Simplified for clarity
+        
+        # Combine system prompt and the new data_zone if it exists
+        full_system_prompt = (self._system_prompt or "").strip()
+        if hasattr(self, 'data_zone') and self.data_zone:
+            data_zone_text = f"\n\n--- data ---\n{self.data_zone.strip()}"
+            full_system_prompt = (full_system_prompt + data_zone_text).strip()
+
         participants = self.participants or {}
 
         def get_full_content(msg: 'LollmsMessage') -> str:

lollms_client/lollms_personality.py

@@ -22,6 +22,8 @@ class LollmsPersonality:
         # Core behavioral instruction
         system_prompt: str,        
         icon: Optional[str] = None,  # Base64 encoded image string
+        active_mcps: Optional[List[str]] = None, # The list of MCPs to activate with this personality
+        data_source: Optional[Union[str, Callable[[str], str]]] = None, # Static string data or a callable for dynamic data retrieval
 
 
         # RAG - Data Files and Application-provided Callbacks
@@ -46,6 +48,8 @@ class LollmsPersonality:
             description: A brief description of what the personality does.
             icon: An optional base64 encoded string for a display icon.
             system_prompt: The core system prompt that defines the AI's behavior.
+            active_mcps: An optional list of MCP (tool) names to be automatically activated with this personality.
+            data_source: A source of knowledge. Can be a static string or a callable function that takes a query and returns a string.
             data_files: A list of file paths to be used as a knowledge base for RAG.
             vectorize_chunk_callback: A function provided by the host app to vectorize and store a text chunk.
             is_vectorized_callback: A function provided by the host app to check if a chunk is already vectorized.
@@ -59,6 +63,8 @@ class LollmsPersonality:
         self.description = description
         self.icon = icon
         self.system_prompt = system_prompt
+        self.active_mcps = active_mcps or []
+        self.data_source = data_source
         self.data_files = [Path(f) for f in data_files] if data_files else []
         
         # RAG Callbacks provided by the host application
@@ -177,6 +183,8 @@ class LollmsPersonality:
             "category": self.category,
             "description": self.description,
             "system_prompt": self.system_prompt,
+            "active_mcps": self.active_mcps,
+            "has_data_source": self.data_source is not None,
             "data_files": [str(p) for p in self.data_files],
             "has_script": self.script is not None
         }

{lollms_client-0.28.0.dist-info → lollms_client-0.29.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lollms_client
-Version: 0.28.0
+Version: 0.29.0
 Summary: A client library for LoLLMs generate endpoint
 Author-email: ParisNeo <parisneoai@gmail.com>
 License: Apache Software License
@@ -49,8 +49,10 @@ Whether you're connecting to a remote LoLLMs server, an Ollama instance, the Ope
 *   🔌 **Versatile Binding System:** Seamlessly switch between different LLM backends (LoLLMs, Ollama, OpenAI, Llama.cpp, Transformers, vLLM, OpenLLM) without major code changes.
 *   🗣️ **Multimodal Support:** Interact with models capable of processing images and generate various outputs like speech (TTS) and images (TTI).
 *   🤖 **Function Calling with MCP:** Empowers LLMs to use external tools and functions through the Model Context Protocol (MCP), with built-in support for local Python tool execution via `local_mcp` binding and its default tools (file I/O, internet search, Python interpreter, image generation).
+*   🎭 **Personalities as Agents:** Personalities can now define their own set of required tools (MCPs) and have access to static or dynamic knowledge bases (`data_source`), turning them into self-contained, ready-to-use agents.
 *   🚀 **Streaming & Callbacks:** Efficiently handle real-time text generation with customizable callback functions, including during MCP interactions.
-*   💬 **Discussion Management:** Utilities to easily manage and format conversation histories for chat applications.
+*   📝 **Advanced Structured Content Generation:** Reliably generate structured JSON output from natural language prompts using the `generate_structured_content` helper method.
+*   💬 **Discussion Management:** Utilities to easily manage and format conversation histories, including a persistent `data_zone` for context that is always present in the system prompt.
 *   ⚙️ **Configuration Management:** Flexible ways to configure bindings and generation parameters.
 *   🧩 **Extensible:** Designed to easily incorporate new LLM backends and modality services, including custom MCP toolsets.
 *   📝 **High-Level Operations:** Includes convenience methods for complex tasks like sequential summarization and deep text analysis directly within `LollmsClient`.
@@ -120,156 +122,174 @@ except Exception as e:
 
 ```
 
-### Function Calling with MCP
+### Advanced Structured Content Generation
 
-`lollms-client` supports robust function calling via the Model Context Protocol (MCP), allowing LLMs to interact with your custom Python tools or pre-defined utilities.
+The `generate_structured_content` method is a powerful utility for forcing an LLM's output into a specific JSON format. It's ideal for extracting information, getting consistent tool parameters, or any task requiring reliable, machine-readable output.
 
 ```python
-from lollms_client import LollmsClient, MSG_TYPE
-from ascii_colors import ASCIIColors
-import json # For pretty printing results
-
-# Example callback for MCP streaming
-def mcp_stream_callback(chunk: str, msg_type: MSG_TYPE, metadata: dict = None, turn_history: list = None) -> bool:
-    if msg_type == MSG_TYPE.MSG_TYPE_CHUNK:  ASCIIColors.success(chunk, end="", flush=True) # LLM's final answer or thought process
-    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_START: ASCIIColors.info(f"\n>> MCP Step Start: {metadata.get('tool_name', chunk)}", flush=True)
-    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END: ASCIIColors.success(f"\n<< MCP Step End: {metadata.get('tool_name', chunk)} -> Result: {json.dumps(metadata.get('result', ''))}", flush=True)
-    elif msg_type == MSG_TYPE.MSG_TYPE_INFO and metadata and metadata.get("type") == "tool_call_request": ASCIIColors.info(f"\nAI requests: {metadata.get('name')}({metadata.get('params')})", flush=True)
-    return True
+from lollms_client import LollmsClient
+import json
 
-try:
-    # Initialize LollmsClient with an LLM binding and the local_mcp binding
-    lc = LollmsClient(
-        binding_name="ollama", model_name="mistral", # Example LLM
-        mcp_binding_name="local_mcp" # Enables default tools (file_writer, internet_search, etc.)
-                                     # or custom tools if mcp_binding_config.tools_folder_path is set.
-    )
+lc = LollmsClient(binding_name="ollama", model_name="llama3")
 
-    user_query = "What were the main AI headlines last week and write a summary to 'ai_news.txt'?"
-    ASCIIColors.blue(f"User Query: {user_query}")
-    ASCIIColors.yellow("AI Processing with MCP (streaming):")
+text_block = "John Doe is a 34-year-old software engineer from New York. He loves hiking and Python programming."
 
-    mcp_result = lc.generate_with_mcp(
-        prompt=user_query,
-        streaming_callback=mcp_stream_callback
-    )
-    print("\n--- End of MCP Interaction ---")
+# Define the exact JSON structure you want
+output_template = {
+    "full_name": "string",
+    "age": "integer",
+    "profession": "string",
+    "city": "string",
+    "hobbies": ["list", "of", "strings"]
+}
 
-    if mcp_result.get("error"):
-        ASCIIColors.error(f"MCP Error: {mcp_result['error']}")
-    else:
-        ASCIIColors.cyan(f"\nFinal Answer from AI: {mcp_result.get('final_answer', 'N/A')}")
-        ASCIIColors.magenta("\nTool Calls Made:")
-        for tc in mcp_result.get("tool_calls", []):
-            print(f"  - Tool: {tc.get('name')}, Params: {tc.get('params')}, Result (first 50 chars): {str(tc.get('result'))[:50]}...")
+# Generate the structured data
+extracted_data = lc.generate_structured_content(
+    prompt=f"Extract the relevant information from the following text:\n\n{text_block}",
+    output_format=output_template
+)
 
-except Exception as e:
-    ASCIIColors.error(f"An error occurred in MCP example: {e}")
-    trace_exception(e) # Assuming you have trace_exception utility
+if extracted_data:
+    print(json.dumps(extracted_data, indent=2))
+# Expected output:
+# {
+#   "full_name": "John Doe",
+#   "age": 34,
+#   "profession": "software engineer",
+#   "city": "New York",
+#   "hobbies": ["hiking", "Python programming"]
+# }
 ```
-For a comprehensive guide on function calling and setting up tools, please refer to the [Usage Guide (DOC_USE.md)](DOC_USE.md).
 
-### 🤖 Advanced Agentic Generation with RAG: `generate_with_mcp_rag`
+### Putting It All Together: An Advanced Agentic Example
 
-For more complex tasks, `generate_with_mcp_rag` provides a powerful, built-in agent that uses a ReAct-style (Reason, Act) loop. This agent can reason about a user's request, use tools (MCP), retrieve information from knowledge bases (RAG), and adapt its plan based on the results of its actions.
+Let's create a **Python Coder Agent**. This agent will use a set of coding rules from a local file as its knowledge base and will be equipped with a tool to execute the code it writes. This demonstrates the synergy between `LollmsPersonality` (with `data_source` and `active_mcps`), `LollmsDiscussion`, and the MCP system.
 
-**Key Agent Capabilities:**
+#### Step 1: Create the Knowledge Base (`coding_rules.txt`)
 
-*   **Observe-Think-Act Loop:** The agent iteratively reviews its progress, thinks about the next logical step, and takes an action (like calling a tool).
-*   **Tool Integration (MCP):** Can use any available MCP tools, such as searching the web or executing code.
-*   **Retrieval-Augmented Generation (RAG):** You can provide one or more "data stores" (knowledge bases). The agent gains a `research::{store_name}` tool to query these stores for relevant information.
-*   **In-Memory Code Generation:** The agent has a special `generate_code` tool. This allows it to first write a piece of code (e.g., a complex Python script) and then pass that code to another tool (e.g., `python_code_interpreter`) in a subsequent step.
-*   **Stateful Progress Tracking:** Designed for rich UI experiences, it emits `step_start` and `step_end` events with unique IDs via the streaming callback. This allows an application to track the agent's individual thoughts and long-running tool calls in real-time.
-*   **Self-Correction:** Includes a `refactor_scratchpad` tool for the agent to clean up its own thought process if it becomes cluttered.
+Create a simple text file with the rules our agent must follow.
 
-Here is an example of using the agent to answer a question by first performing RAG on a custom knowledge base and then using the retrieved information to generate and execute code.
+```text
+# File: coding_rules.txt
 
-```python
-import json
-from lollms_client import LollmsClient, MSG_TYPE
-from ascii_colors import ASCIIColors
+1.  All Python functions must include a Google-style docstring.
+2.  Use type hints for all function parameters and return values.
+3.  The main execution block should be protected by `if __name__ == "__main__":`.
+4.  After defining a function, add a simple example of its usage inside the main block.
+5.  Print the output of the example usage to the console.
+```
 
-# 1. Define a mock RAG data store and retrieval function
-project_notes = {
-    "project_phoenix_details": "Project Phoenix has a current budget of $500,000 and an expected quarterly growth rate of 15%."
-}
+#### Step 2: The Main Script (`agent_example.py`)
 
-def retrieve_from_notes(query: str, top_k: int = 1, min_similarity: float = 0.5):
-    """A simple keyword-based retriever for our mock data store."""
-    results = []
-    for key, text in project_notes.items():
-        if query.lower() in text.lower():
-            results.append({"source": key, "content": text})
-    return results[:top_k]
+This script will define the personality, initialize the client, and run the agent.
 
-# 2. Define a detailed streaming callback to visualize the agent's process
-def agent_streaming_callback(chunk: str, msg_type: MSG_TYPE, params: dict = None, metadata: list = None) -> bool:
+```python
+from pathlib import Path
+from lollms_client import LollmsClient, LollmsPersonality, LollmsDiscussion, MSG_TYPE
+from ascii_colors import ASCIIColors
+import json
+
+# A detailed callback to visualize the agent's process
+def agent_callback(chunk: str, msg_type: MSG_TYPE, params: dict = None, **kwargs) -> bool:
     if not params: params = {}
-    msg_id = params.get("id", "")
     
-    if msg_type == MSG_TYPE.MSG_TYPE_STEP_START:
-        ASCIIColors.yellow(f"\n>> Agent Step Start [ID: {msg_id}]: {chunk}")
+    if msg_type == MSG_TYPE.MSG_TYPE_STEP:
+        ASCIIColors.yellow(f"\n>> Agent Step: {chunk}")
+    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_START:
+        ASCIIColors.yellow(f"\n>> Agent Step Start: {chunk}")
     elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END:
-        ASCIIColors.green(f"<< Agent Step End [ID: {msg_id}]: {chunk}")
-        if params.get('result'):
-            ASCIIColors.cyan(f"   Result: {json.dumps(params['result'], indent=2)}")
+        result = params.get('result', '')
+        ASCIIColors.green(f"<< Agent Step End: {chunk} -> Result: {json.dumps(result)[:150]}...")
     elif msg_type == MSG_TYPE.MSG_TYPE_THOUGHT_CONTENT:
-        ASCIIColors.magenta(f"\n🤔 Agent Thought: {chunk}")
+        ASCIIColors.magenta(f"🤔 Agent Thought: {chunk}")
     elif msg_type == MSG_TYPE.MSG_TYPE_TOOL_CALL:
-        ASCIIColors.blue(f"\n🛠️  Agent Action: {chunk}")
+        ASCIIColors.blue(f"🛠️  Agent Action: {chunk}")
     elif msg_type == MSG_TYPE.MSG_TYPE_OBSERVATION:
-        ASCIIColors.cyan(f"\n👀 Agent Observation: {chunk}")
+        ASCIIColors.cyan(f"👀 Agent Observation: {chunk}")
     elif msg_type == MSG_TYPE.MSG_TYPE_CHUNK:
         print(chunk, end="", flush=True) # Final answer stream
     return True
 
 try:
-    # 3. Initialize LollmsClient with an LLM and local tools enabled
-    lc = LollmsClient(
-        binding_name="ollama",          # Use Ollama
-        model_name="llama3",            # Or any capable model like mistral, gemma, etc.
-        mcp_binding_name="local_mcp"    # Enable local tools like python_code_interpreter
+    # --- 1. Load the knowledge base from the file ---
+    rules_path = Path("coding_rules.txt")
+    if not rules_path.exists():
+        raise FileNotFoundError("Please create the 'coding_rules.txt' file.")
+    coding_rules = rules_path.read_text()
+
+    # --- 2. Define the Coder Agent Personality ---
+    coder_personality = LollmsPersonality(
+        name="Python Coder Agent",
+        author="lollms-client",
+        category="Coding",
+        description="An agent that writes and executes Python code according to specific rules.",
+        system_prompt=(
+            "You are an expert Python programmer. Your task is to write clean, executable Python code based on the user's request. "
+            "You MUST strictly follow all rules provided in the 'Personality Static Data' section. "
+            "First, think about the plan. Then, use the `python_code_interpreter` tool to write and execute the code. "
+            "Finally, present the code and its output to the user."
+        ),
+        # A) Attach the static knowledge base
+        data_source=coding_rules,
+        # B) Equip the agent with a code execution tool
+        active_mcps=["python_code_interpreter"]
     )
 
-    # 4. Define the user prompt and the RAG data store
-    prompt = "Based on my notes about Project Phoenix, write and run a Python script to calculate its projected budget after two quarters."
+    # --- 3. Initialize the Client and Discussion ---
+    lc = LollmsClient(
+        binding_name="ollama",          # Or any capable model binding
+        model_name="codellama",         # A code-specialized model is recommended
+        mcp_binding_name="local_mcp"    # Enable the local tool execution engine
+    )
+    discussion = LollmsDiscussion.create_new(lollms_client=lc)
     
-    rag_data_store = {
-        "project_notes": {"callable": retrieve_from_notes}
-    }
+    # --- 4. The User's Request ---
+    user_prompt = "Write a Python function that takes two numbers and returns their sum."
 
-    ASCIIColors.yellow(f"User Prompt: {prompt}")
+    ASCIIColors.yellow(f"User Prompt: {user_prompt}")
     print("\n" + "="*50 + "\nAgent is now running...\n" + "="*50)
 
-    # 5. Run the agent
-    agent_output = lc.generate_with_mcp_rag(
-        prompt=prompt,
-        use_data_store=rag_data_store,
-        use_mcps=["python_code_interpreter"], # Make specific tools available
-        streaming_callback=agent_streaming_callback,
-        max_reasoning_steps=5
+    # --- 5. Run the Agentic Chat Turn ---
+    response = discussion.chat(
+        user_message=user_prompt,
+        personality=coder_personality,
+        streaming_callback=agent_callback
     )
 
-    print("\n" + "="*50 + "\nAgent finished.\n" + "="*50)
-
-    # 6. Print the final results
-    if agent_output.get("error"):
-        ASCIIColors.error(f"\nAgent Error: {agent_output['error']}")
-    else:
-        ASCIIColors.green("\n--- Final Answer ---")
-        print(agent_output.get("final_answer"))
-        
-        ASCIIColors.magenta("\n--- Tool Calls ---")
-        print(json.dumps(agent_output.get("tool_calls", []), indent=2))
-
-        ASCIIColors.cyan("\n--- RAG Sources ---")
-        print(json.dumps(agent_output.get("sources", []), indent=2))
+    print("\n\n" + "="*50 + "\nAgent finished.\n" + "="*50)
+    
+    # --- 6. Inspect the results ---
+    ai_message = response['ai_message']
+    ASCIIColors.green("\n--- Final Answer from Agent ---")
+    print(ai_message.content)
+    
+    ASCIIColors.magenta("\n--- Tool Calls Made ---")
+    print(json.dumps(ai_message.metadata.get("tool_calls", []), indent=2))
 
 except Exception as e:
-    ASCIIColors.red(f"\nAn unexpected error occurred: {e}")
+    trace_exception(e)
 
 ```
 
+#### Step 3: What Happens Under the Hood
+
+When you run `agent_example.py`, a sophisticated process unfolds:
+
+1.  **Initialization:** The `LollmsDiscussion.chat()` method is called with the `coder_personality`.
+2.  **Knowledge Injection:** The `chat` method sees that `personality.data_source` is a string. It automatically takes the content of `coding_rules.txt` and injects it into the `discussion.data_zone`.
+3.  **Tool Activation:** The method also sees `personality.active_mcps`. It enables the `python_code_interpreter` tool for this turn.
+4.  **Context Assembly:** The `LollmsClient` assembles a rich prompt for the LLM that includes:
+    *   The personality's `system_prompt`.
+    *   The content of `coding_rules.txt` (from the `data_zone`).
+    *   The list of available tools (including `python_code_interpreter`).
+    *   The user's request ("Write a function...").
+5.  **Reason and Act:** The LLM, now fully briefed, reasons that it needs to use the `python_code_interpreter` tool. It formulates the Python code *according to the rules it was given*.
+6.  **Tool Execution:** The `local_mcp` binding receives the code and executes it in a secure local environment. It captures any output (`stdout`, `stderr`) and results.
+7.  **Observation:** The execution results are sent back to the LLM as an "observation."
+8.  **Final Synthesis:** The LLM now has the user's request, the rules, the code it wrote, and the code's output. It synthesizes all of this into a final, comprehensive answer for the user.
+
+This example showcases how `lollms-client` allows you to build powerful, knowledgeable, and capable agents by simply composing personalities with data and tools.
+
 ## Documentation
 
 For more in-depth information, please refer to:
@@ -602,3 +622,141 @@ This project is licensed under the **Apache 2.0 License**. See the [LICENSE](LIC
 ## Changelog
 
 For a list of changes and updates, please refer to the [CHANGELOG.md](CHANGELOG.md) file.
+```
+
+---
+### Phase 2: Update `docs/md/lollms_discussion.md`
+
+`[UPDATE] docs/md/lollms_discussion.md`
+```markdown
+# LollmsDiscussion Class
+
+The `LollmsDiscussion` class is a cornerstone of the `lollms-client` library, designed to represent and manage a single conversation. It provides a robust interface for handling message history, conversation branching, context formatting, and persistence.
+
+## Overview
+
+A `LollmsDiscussion` can be either **in-memory** or **database-backed**, offering flexibility for different use cases.
+
+-   **In-Memory:** Ideal for temporary or transient conversations. The discussion exists only for the duration of the application's runtime.
+-   **Database-Backed:** Provides persistence by saving the entire conversation, including all branches and metadata, to a database file (e.g., SQLite). This is perfect for applications that need to retain user chat history.
+
+## Key Features
+
+-   **Message Management:** Add user and AI messages, which are automatically linked to form a conversation tree.
+-   **Branching:** The conversation is a tree, not a simple list. This allows for exploring different conversational paths from any point. You can regenerate an AI response, and it will create a new branch.
+-   **Context Exporting:** The `export()` method formats the conversation history for various LLM backends (`openai_chat`, `ollama_chat`, `lollms_text`, `markdown`), ensuring compatibility.
+-   **Automatic Pruning:** To prevent exceeding the model's context window, it can automatically summarize older parts of the conversation without losing the original data.
+-   **Persistent Data Zone:** A special field to hold context that is always included in the system prompt, separate from the main conversation flow.
+
+## Creating a Discussion
+
+The recommended way to create a discussion is using the `LollmsDiscussion.create_new()` class method.
+
+```python
+from lollms_client import LollmsClient, LollmsDataManager, LollmsDiscussion
+
+# For an in-memory discussion (lost when the app closes)
+lc = LollmsClient(binding_name="ollama", model_name="llama3")
+discussion = LollmsDiscussion.create_new(lollms_client=lc, id="my-temp-discussion")
+
+# For a persistent, database-backed discussion
+# This will create a 'discussions.db' file if it doesn't exist
+db_manager = LollmsDataManager('sqlite:///discussions.db')
+discussion_db = LollmsDiscussion.create_new(
+    lollms_client=lc, 
+    db_manager=db_manager,
+    discussion_metadata={"title": "My First DB Chat"}
+)
+```
+
+## Core Properties
+
+### `data_zone`
+
+The `data_zone` is a string property where you can store persistent information that should always be visible to the AI as part of its system instructions. This is incredibly useful for providing context that doesn't change, such as user profiles, complex instructions, or data that the AI should always reference.
+
+The content of `data_zone` is automatically appended to the system prompt during context export. This is also where data from a personality's `data_source` is loaded before generation.
+
+#### Example: Using the Data Zone
+
+Imagine you are building a Python coding assistant. You can use the `data_zone` to hold the current state of a script the user is working on.
+
+```python
+from lollms_client import LollmsClient, LollmsDiscussion
+
+lc = LollmsClient(binding_name="ollama", model_name="codellama")
+discussion = LollmsDiscussion.create_new(lollms_client=lc)
+
+# Set the system prompt and initial data_zone
+discussion.system_prompt = "You are a Python expert. Help the user with their code."
+discussion.data_zone = "# Current script content:\n\nimport os\n\ndef list_files(path):\n    pass"
+
+# The user asks for help
+user_prompt = "Flesh out the list_files function to print all files in the given path."
+
+# When you generate a response, the AI will see the system prompt AND the data_zone
+# The effective system prompt becomes:
+# """
+# You are a Python expert. Help the user with their code.
+#
+# --- data ---
+# # Current script content:
+#
+# import os
+#
+# def list_files(path):
+#     pass
+# """
+response = discussion.chat(user_prompt)
+print(response['ai_message'].content)
+
+# The calling application can then parse the AI's response and update the data_zone
+# for the next turn.
+updated_code = "# ... updated code from AI ...\nimport os\n\ndef list_files(path):\n    for f in os.listdir(path):\n        print(f)"
+discussion.data_zone = updated_code
+discussion.commit() # If DB-backed
+```
+
+### Other Important Properties
+
+-   `id`: The unique identifier for the discussion.
+-   `system_prompt`: The main system prompt defining the AI's persona and core instructions.
+-   `metadata`: A dictionary for storing any custom metadata, like a title.
+-   `active_branch_id`: The ID of the message at the "tip" of the current conversation branch.
+-   `messages`: A list of all `LollmsMessage` objects in the discussion.
+
+## Main Methods
+
+### `chat()`
+The `chat()` method is the primary way to interact with the discussion. It handles a full user-to-AI turn, including invoking the advanced agentic capabilities of the `LollmsClient`.
+
+#### Personalities, Tools, and Data Sources
+
+The `chat` method intelligently handles tool activation and data loading when a `LollmsPersonality` is provided. This allows personalities to be configured as self-contained agents with their own default tools and knowledge bases.
+
+**Tool Activation (`use_mcps`):**
+
+1.  **Personality has tools, `use_mcps` is not set:** The agent will use the tools defined in `personality.active_mcps`.
+2.  **Personality has tools, `use_mcps` is also set:** The agent will use a *combination* of tools from both the personality and the `use_mcps` parameter for that specific turn. Duplicates are automatically handled. This allows you to augment a personality's default tools on the fly.
+3.  **Personality has no tools, `use_mcps` is set:** The agent will use only the tools specified in the `use_mcps` parameter.
+4.  **Neither are set:** The agentic turn is not triggered (unless a data store is used), and a simple chat generation occurs.
+
+**Knowledge Loading (`data_source`):**
+
+Before generation, the `chat` method checks for `personality.data_source`:
+
+-   **If it's a `str` (static data):** The string is appended to the `discussion.data_zone`, making it part of the system context for the current turn.
+-   **If it's a `Callable` (dynamic data):**
+    1.  The AI first generates a query based on the current conversation.
+    2.  The `chat` method calls your function with this query.
+    3.  The returned string is appended to the `discussion.data_zone`.
+    4.  The final response generation proceeds with this newly added context.
+
+This makes it easy to create powerful, reusable agents. For a complete, runnable example of building a **Python Coder Agent** that uses both `active_mcps` and a static `data_source`, **please see the "Putting It All Together" section in the main `README.md` file.**
+
+### Other Methods
+-   `add_message(sender, content, ...)`: Adds a new message.
+-   `export(format_type, ...)`: Exports the discussion to a specific format.
+-   `commit()`: Saves changes to the database (if DB-backed).
+-   `summarize_and_prune()`: Automatically handles context window limits.
+-   `count_discussion_tokens()`: Counts the tokens for a given format.

{lollms_client-0.28.0.dist-info → lollms_client-0.29.0.dist-info}/RECORD

@@ -29,14 +29,14 @@ examples/mcp_examples/openai_mcp.py,sha256=7IEnPGPXZgYZyiES_VaUbQ6viQjenpcUxGiHE
 examples/mcp_examples/run_remote_mcp_example_v2.py,sha256=bbNn93NO_lKcFzfIsdvJJijGx2ePFTYfknofqZxMuRM,14626
 examples/mcp_examples/run_standard_mcp_example.py,sha256=GSZpaACPf3mDPsjA8esBQVUsIi7owI39ca5avsmvCxA,9419
 examples/test_local_models/local_chat.py,sha256=slakja2zaHOEAUsn2tn_VmI4kLx6luLBrPqAeaNsix8,456
-lollms_client/__init__.py,sha256=eAfY5Ik399J8AVHNU6vLjqiWNNmT88GX-h3NTKzLo2g,1147
+lollms_client/__init__.py,sha256=DiIvlC4e7dCOcFGBxtAmgUNIpbaIMRTiPDhEuadweGg,1147
 lollms_client/lollms_config.py,sha256=goEseDwDxYJf3WkYJ4IrLXwg3Tfw73CXV2Avg45M_hE,21876
-lollms_client/lollms_core.py,sha256=QliAE6hYiIGqQSDWWmjii1Hj8hsj3IxwBuUFshxJDlM,169099
-lollms_client/lollms_discussion.py,sha256=tvANNvpTkUr4L6GKowosIyfV7l3SA6cXnzElt36e2s8,52133
+lollms_client/lollms_core.py,sha256=U-o16h7BZT7H1tu-aZNM-14H-OuObPG6qpLsikU1Jw8,169080
+lollms_client/lollms_discussion.py,sha256=RVGeFyPKeLpTJEUjx2IdWFYg-d8zjPhWLQGnFFiKNvQ,56138
 lollms_client/lollms_js_analyzer.py,sha256=01zUvuO2F_lnUe_0NLxe1MF5aHE1hO8RZi48mNPv-aw,8361
 lollms_client/lollms_llm_binding.py,sha256=cU0cmxZfIrp-ofutbRLx7W_59dxzPXpU-vO98MqVnQA,14788
 lollms_client/lollms_mcp_binding.py,sha256=0rK9HQCBEGryNc8ApBmtOlhKE1Yfn7X7xIQssXxS2Zc,8933
-lollms_client/lollms_personality.py,sha256=dILUI5DZdzJ3NDDQiIsK2UptVF-jZK3XYXZ2bpXP_ew,8035
+lollms_client/lollms_personality.py,sha256=O-9nqZhazcITOkxjT24ENTxTmIoZLgqIsQ9WtWs0Id0,8719
 lollms_client/lollms_python_analyzer.py,sha256=7gf1fdYgXCOkPUkBAPNmr6S-66hMH4_KonOMsADASxc,10246
 lollms_client/lollms_stt_binding.py,sha256=jAUhLouEhh2hmm1bK76ianfw_6B59EHfY3FmLv6DU-g,5111
 lollms_client/lollms_tti_binding.py,sha256=afO0-d-Kqsmh8UHTijTvy6dZAt-XDB6R-IHmdbf-_fs,5928
@@ -92,8 +92,8 @@ lollms_client/tts_bindings/piper_tts/__init__.py,sha256=0IEWG4zH3_sOkSb9WbZzkeV5
 lollms_client/tts_bindings/xtts/__init__.py,sha256=FgcdUH06X6ZR806WQe5ixaYx0QoxtAcOgYo87a2qxYc,18266
 lollms_client/ttv_bindings/__init__.py,sha256=UZ8o2izQOJLQgtZ1D1cXoNST7rzqW22rL2Vufc7ddRc,3141
 lollms_client/ttv_bindings/lollms/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lollms_client-0.28.0.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
-lollms_client-0.28.0.dist-info/METADATA,sha256=Esa4mMjN3hLYTMUR8aGk9jNlE_kqCyYLLuWx-tL9Vzo,25778
-lollms_client-0.28.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lollms_client-0.28.0.dist-info/top_level.txt,sha256=NI_W8S4OYZvJjb0QWMZMSIpOrYzpqwPGYaklhyWKH2w,23
-lollms_client-0.28.0.dist-info/RECORD,,
+lollms_client-0.29.0.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
+lollms_client-0.29.0.dist-info/METADATA,sha256=pykrb85WMir4magsF-_qpPvAJ0H9uKAR_iPr6lX7lXw,33456
+lollms_client-0.29.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lollms_client-0.29.0.dist-info/top_level.txt,sha256=NI_W8S4OYZvJjb0QWMZMSIpOrYzpqwPGYaklhyWKH2w,23
+lollms_client-0.29.0.dist-info/RECORD,,