lollms-client 0.29.1__tar.gz → 0.29.2__tar.gz

{lollms_client-0.29.1/lollms_client.egg-info → lollms_client-0.29.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lollms_client
-Version: 0.29.1
+Version: 0.29.2
 Summary: A client library for LoLLMs generate endpoint
 Author-email: ParisNeo <parisneoai@gmail.com>
 License: Apache Software License
@@ -296,9 +296,22 @@ This example showcases how `lollms-client` allows you to build powerful, knowled
 
 ### Building Stateful Agents with Memory and Data Zones
 
-The latest version of `LollmsDiscussion` introduces powerful features for creating agents that can remember information across conversations. This is achieved through structured data zones and a new `memorize()` method.
+The `LollmsDiscussion` class provides a sophisticated system for creating stateful agents that can remember information across conversations. This is achieved through a layered system of "context zones" that are automatically combined into the AI's system prompt.
 
-Let's build a "Personal Assistant" agent that learns about the user over time.
+#### Understanding the Context Zones
+
+The AI's context is more than just chat history. It's built from several distinct components, each with a specific purpose:
+
+*   **`system_prompt`**: The foundational layer defining the AI's core identity, persona, and primary instructions.
+*   **`memory`**: The AI's long-term, persistent memory. It stores key facts about the user or topics, built up over time using the `memorize()` method.
+*   **`user_data_zone`**: Holds session-specific information about the user's current state or goals (e.g., "User is currently working on 'file.py'").
+*   **`discussion_data_zone`**: Contains state or meta-information about the current conversational task (e.g., "Step 1 of the plan is complete").
+*   **`personality_data_zone`**: A knowledge base or set of rules automatically injected from a `LollmsPersonality`'s `data_source`.
+*   **`pruning_summary`**: An automatic, AI-generated summary of the oldest messages in a very long chat, used to conserve tokens without losing the gist of the early conversation.
+
+The `get_context_status()` method is your window into this system, showing you exactly how these zones are combined and how many tokens they consume.
+
+Let's see this in action with a "Personal Assistant" agent that learns about the user over time.
 
 ```python
 from lollms_client import LollmsClient, LollmsDataManager, LollmsDiscussion, MSG_TYPE
@@ -320,7 +333,8 @@ if not discussion:
         id=discussion_id,
         autosave=True # Important for persistence
     )
-    # Let's preset some user data
+    # Let's preset some data in different zones
+    discussion.system_prompt = "You are a helpful Personal Assistant."
     discussion.user_data_zone = "User's Name: Alex\nUser's Goal: Learn about AI development."
     discussion.commit()
 else:
@@ -331,13 +345,24 @@ def run_chat_turn(prompt: str):
     """Helper function to run a single chat turn and print details."""
     ASCIIColors.cyan(f"\n> User: {prompt}")
 
-    # --- A. Check context status BEFORE the turn ---
+    # --- A. Check context status BEFORE the turn using get_context_status() ---
     ASCIIColors.magenta("\n--- Context Status (Before Generation) ---")
     status = discussion.get_context_status()
-    print(f"Max Tokens: {status.get('max_tokens')}, Current Approx. Tokens: {status.get('current_tokens')}")
-    for zone, data in status.get('zones', {}).items():
-        print(f"  - Zone: {zone}, Tokens: {data['tokens']}")
-        # print(f"    Content: {data['content'][:80]}...") # Uncomment for more detail
+    print(f"Max Tokens: {status.get('max_tokens')}, Current Tokens: {status.get('current_tokens')}")
+    
+    # Print the system context details
+    if 'system_context' in status['zones']:
+        sys_ctx = status['zones']['system_context']
+        print(f"  - System Context Tokens: {sys_ctx['tokens']}")
+        # The 'breakdown' shows the individual zones that were combined
+        for name, content in sys_ctx.get('breakdown', {}).items():
+            print(f"    -> Contains '{name}': {content.split(chr(10))[0]}...")
+
+    # Print the message history details
+    if 'message_history' in status['zones']:
+        msg_hist = status['zones']['message_history']
+        print(f"  - Message History Tokens: {msg_hist['tokens']} ({msg_hist['message_count']} messages)")
+
     print("------------------------------------------")
 
     # --- B. Run the chat ---
@@ -348,7 +373,7 @@ def run_chat_turn(prompt: str):
     )
     print() # Newline after stream
 
-    # --- C. Trigger memorization ---
+    # --- C. Trigger memorization to update the 'memory' zone ---
     ASCIIColors.yellow("\nTriggering memorization process...")
     discussion.memorize()
     discussion.commit() # Save the new memory to the DB
@@ -359,24 +384,30 @@ run_chat_turn("Hi there! Can you recommend a good Python library for building we
 run_chat_turn("That sounds great. By the way, my favorite programming language is Rust, I find its safety features amazing.")
 run_chat_turn("What was my favorite programming language again?")
 
-# --- Final Inspection ---
+# --- Final Inspection of Memory ---
 ASCIIColors.magenta("\n--- Final Context Status ---")
 status = discussion.get_context_status()
-print(f"Max Tokens: {status.get('max_tokens')}, Current Approx. Tokens: {status.get('current_tokens')}")
-for zone, data in status.get('zones', {}).items():
-    print(f"  - Zone: {zone}, Tokens: {data['tokens']}")
-    print(f"    Content: {data['content'][:150].replace(chr(10), ' ')}...")
+print(f"Max Tokens: {status.get('max_tokens')}, Current Tokens: {status.get('current_tokens')}")
+if 'system_context' in status['zones']:
+    sys_ctx = status['zones']['system_context']
+    print(f"  - System Context Tokens: {sys_ctx['tokens']}")
+    for name, content in sys_ctx.get('breakdown', {}).items():
+        # Print the full content of the memory zone to verify it was updated
+        if name == 'memory':
+            ASCIIColors.yellow(f"    -> Full '{name}' content:\n{content}")
+        else:
+            print(f"    -> Contains '{name}': {content.split(chr(10))[0]}...")
 print("------------------------------------------")
 
 ```
 
 #### How it Works:
 
-1.  **Persistence:** The `LollmsDataManager` and `autosave=True` ensure that all changes to the discussion, including the data zones and memory, are saved to the `my_assistant.db` file. When you re-run the script, it loads the previous state.
-2.  **`user_data_zone`:** We pre-filled this zone with basic user info. This context is provided to the AI in every turn.
-3.  **`get_context_status()`:** Before each generation, we call this method to get a detailed breakdown of the prompt. This is excellent for debugging and understanding how the context window is being used.
-4.  **`memorize()`:** After the user mentions their favorite language, `memorize()` is called. The LLM analyzes the last turn, identifies this new, important fact ("user's favorite language is Rust"), and appends it to the `discussion.memory` field.
-5.  **Recall:** In the final turn, when asked to recall the favorite language, the AI has access to the `memory` zone and can correctly answer "Rust", even if that information had scrolled out of the recent conversation history. This demonstrates true long-term memory.
+1.  **Persistence & Initialization:** The `LollmsDataManager` saves and loads the discussion. We initialize the `system_prompt` and `user_data_zone` to provide initial context.
+2.  **`get_context_status()`:** Before each generation, we call this method. The output shows a `system_context` block with a token count for all combined zones and a `breakdown` field that lets us see the content of each individual zone that contributed to it.
+3.  **`memorize()`:** After the user mentions their favorite language, `memorize()` is called. The LLM analyzes the last turn, identifies this new, important fact, and appends it to the `discussion.memory` zone.
+4.  **Recall:** In the final turn, when asked to recall the favorite language, the AI has access to the updated `memory` content within its system context and can correctly answer "Rust". This demonstrates true long-term, stateful memory.
+
 
 ## Documentation
 
@@ -922,33 +953,54 @@ discussion.commit() # Save the updated memory to the database
 ```
 
 #### `get_context_status()`
-Provides a detailed, real-time breakdown of the current prompt context, showing exactly what will be sent to the model and how many tokens each part occupies.
 
-- **Return Value:** A dictionary containing the `max_tokens`, `current_tokens`, and a `zones` dictionary with the content and token count for each component.
-- **Use Case:** Essential for debugging context issues, understanding token usage, and visualizing how different data zones contribute to the final prompt.
+Provides a detailed, real-time breakdown of the current prompt context, showing exactly what will be sent to the model and how many tokens each major component occupies. This is crucial for debugging context issues and understanding token usage.
+
+The method accurately reflects the structure of the `lollms_text` format, where all system-level instructions (the main prompt, all data zones, and the pruning summary) are combined into a single system block.
+
+-   **Return Value:** A dictionary containing:
+    -   `max_tokens`: The configured maximum token limit for the discussion.
+    -   `current_tokens`: The total, most accurate token count for the entire prompt, calculated using the same logic as the `chat()` method.
+    -   `zones`: A dictionary with up to two keys:
+        -   **`system_context`**: Present if there is any system-level content. It contains:
+            -   `tokens`: The total token count for the **entire combined system block** (e.g., `!@>system:\n...\n`).
+            -   `content`: The full string content of the system block, showing exactly how all zones are merged.
+            -   `breakdown`: A sub-dictionary showing the raw text of each individual component (e.g., `system_prompt`, `memory`, `user_data_zone`) that was used to build the `content`.
+        -   **`message_history`**: Present if there are messages in the branch. It contains:
+            -   `tokens`: The total token count for the message history part of the prompt.
+            -   `content`: The full string of the formatted message history.
+            -   `message_count`: The number of messages included in the history.
+
+-   **Use Case:** Essential for debugging context issues, visualizing how different data zones contribute to the final prompt, and monitoring token consumption.
 
 ```python
 import json
 
+# Assuming 'discussion' is an LollmsDiscussion object with some data
+discussion.system_prompt = "You are a helpful AI."
+discussion.user_data_zone = "User is named Bob."
+discussion.add_message(sender="user", content="Hello!")
+discussion.add_message(sender="assistant", content="Hi Bob!")
+
 status = discussion.get_context_status()
 print(json.dumps(status, indent=2))
 
 # Expected Output Structure:
 # {
-#   "max_tokens": 8192,
-#   "current_tokens": 521,
+#   "max_tokens": null,
+#   "current_tokens": 46,
 #   "zones": {
-#     "system_prompt": {
-#       "content": "You are a helpful assistant.",
-#       "tokens": 12
-#     },
-#     "memory": {
-#       "content": "User's favorite color is blue.",
-#       "tokens": 15
+#     "system_context": {
+#       "content": "You are a helpful AI.\n\n-- User Data Zone --\nUser is named Bob.",
+#       "tokens": 25,
+#       "breakdown": {
+#         "system_prompt": "You are a helpful AI.",
+#         "user_data_zone": "User is named Bob."
+#       }
 #     },
 #     "message_history": {
-#       "content": "!@>user:\nHi there!\n!@>assistant:\nHello! How can I help?\n",
-#       "tokens": 494,
+#       "content": "!@>user:\nHello!\n!@>assistant:\nHi Bob!\n",
+#       "tokens": 21,
 #       "message_count": 2
 #     }
 #   }

{lollms_client-0.29.1 → lollms_client-0.29.2}/README.md

@@ -265,9 +265,22 @@ This example showcases how `lollms-client` allows you to build powerful, knowled
 
 ### Building Stateful Agents with Memory and Data Zones
 
-The latest version of `LollmsDiscussion` introduces powerful features for creating agents that can remember information across conversations. This is achieved through structured data zones and a new `memorize()` method.
+The `LollmsDiscussion` class provides a sophisticated system for creating stateful agents that can remember information across conversations. This is achieved through a layered system of "context zones" that are automatically combined into the AI's system prompt.
 
-Let's build a "Personal Assistant" agent that learns about the user over time.
+#### Understanding the Context Zones
+
+The AI's context is more than just chat history. It's built from several distinct components, each with a specific purpose:
+
+*   **`system_prompt`**: The foundational layer defining the AI's core identity, persona, and primary instructions.
+*   **`memory`**: The AI's long-term, persistent memory. It stores key facts about the user or topics, built up over time using the `memorize()` method.
+*   **`user_data_zone`**: Holds session-specific information about the user's current state or goals (e.g., "User is currently working on 'file.py'").
+*   **`discussion_data_zone`**: Contains state or meta-information about the current conversational task (e.g., "Step 1 of the plan is complete").
+*   **`personality_data_zone`**: A knowledge base or set of rules automatically injected from a `LollmsPersonality`'s `data_source`.
+*   **`pruning_summary`**: An automatic, AI-generated summary of the oldest messages in a very long chat, used to conserve tokens without losing the gist of the early conversation.
+
+The `get_context_status()` method is your window into this system, showing you exactly how these zones are combined and how many tokens they consume.
+
+Let's see this in action with a "Personal Assistant" agent that learns about the user over time.
 
 ```python
 from lollms_client import LollmsClient, LollmsDataManager, LollmsDiscussion, MSG_TYPE
@@ -289,7 +302,8 @@ if not discussion:
         id=discussion_id,
         autosave=True # Important for persistence
     )
-    # Let's preset some user data
+    # Let's preset some data in different zones
+    discussion.system_prompt = "You are a helpful Personal Assistant."
     discussion.user_data_zone = "User's Name: Alex\nUser's Goal: Learn about AI development."
     discussion.commit()
 else:
@@ -300,13 +314,24 @@ def run_chat_turn(prompt: str):
     """Helper function to run a single chat turn and print details."""
     ASCIIColors.cyan(f"\n> User: {prompt}")
 
-    # --- A. Check context status BEFORE the turn ---
+    # --- A. Check context status BEFORE the turn using get_context_status() ---
     ASCIIColors.magenta("\n--- Context Status (Before Generation) ---")
     status = discussion.get_context_status()
-    print(f"Max Tokens: {status.get('max_tokens')}, Current Approx. Tokens: {status.get('current_tokens')}")
-    for zone, data in status.get('zones', {}).items():
-        print(f"  - Zone: {zone}, Tokens: {data['tokens']}")
-        # print(f"    Content: {data['content'][:80]}...") # Uncomment for more detail
+    print(f"Max Tokens: {status.get('max_tokens')}, Current Tokens: {status.get('current_tokens')}")
+    
+    # Print the system context details
+    if 'system_context' in status['zones']:
+        sys_ctx = status['zones']['system_context']
+        print(f"  - System Context Tokens: {sys_ctx['tokens']}")
+        # The 'breakdown' shows the individual zones that were combined
+        for name, content in sys_ctx.get('breakdown', {}).items():
+            print(f"    -> Contains '{name}': {content.split(chr(10))[0]}...")
+
+    # Print the message history details
+    if 'message_history' in status['zones']:
+        msg_hist = status['zones']['message_history']
+        print(f"  - Message History Tokens: {msg_hist['tokens']} ({msg_hist['message_count']} messages)")
+
     print("------------------------------------------")
 
     # --- B. Run the chat ---
@@ -317,7 +342,7 @@ def run_chat_turn(prompt: str):
     )
     print() # Newline after stream
 
-    # --- C. Trigger memorization ---
+    # --- C. Trigger memorization to update the 'memory' zone ---
     ASCIIColors.yellow("\nTriggering memorization process...")
     discussion.memorize()
     discussion.commit() # Save the new memory to the DB
@@ -328,24 +353,30 @@ run_chat_turn("Hi there! Can you recommend a good Python library for building we
 run_chat_turn("That sounds great. By the way, my favorite programming language is Rust, I find its safety features amazing.")
 run_chat_turn("What was my favorite programming language again?")
 
-# --- Final Inspection ---
+# --- Final Inspection of Memory ---
 ASCIIColors.magenta("\n--- Final Context Status ---")
 status = discussion.get_context_status()
-print(f"Max Tokens: {status.get('max_tokens')}, Current Approx. Tokens: {status.get('current_tokens')}")
-for zone, data in status.get('zones', {}).items():
-    print(f"  - Zone: {zone}, Tokens: {data['tokens']}")
-    print(f"    Content: {data['content'][:150].replace(chr(10), ' ')}...")
+print(f"Max Tokens: {status.get('max_tokens')}, Current Tokens: {status.get('current_tokens')}")
+if 'system_context' in status['zones']:
+    sys_ctx = status['zones']['system_context']
+    print(f"  - System Context Tokens: {sys_ctx['tokens']}")
+    for name, content in sys_ctx.get('breakdown', {}).items():
+        # Print the full content of the memory zone to verify it was updated
+        if name == 'memory':
+            ASCIIColors.yellow(f"    -> Full '{name}' content:\n{content}")
+        else:
+            print(f"    -> Contains '{name}': {content.split(chr(10))[0]}...")
 print("------------------------------------------")
 
 ```
 
 #### How it Works:
 
-1.  **Persistence:** The `LollmsDataManager` and `autosave=True` ensure that all changes to the discussion, including the data zones and memory, are saved to the `my_assistant.db` file. When you re-run the script, it loads the previous state.
-2.  **`user_data_zone`:** We pre-filled this zone with basic user info. This context is provided to the AI in every turn.
-3.  **`get_context_status()`:** Before each generation, we call this method to get a detailed breakdown of the prompt. This is excellent for debugging and understanding how the context window is being used.
-4.  **`memorize()`:** After the user mentions their favorite language, `memorize()` is called. The LLM analyzes the last turn, identifies this new, important fact ("user's favorite language is Rust"), and appends it to the `discussion.memory` field.
-5.  **Recall:** In the final turn, when asked to recall the favorite language, the AI has access to the `memory` zone and can correctly answer "Rust", even if that information had scrolled out of the recent conversation history. This demonstrates true long-term memory.
+1.  **Persistence & Initialization:** The `LollmsDataManager` saves and loads the discussion. We initialize the `system_prompt` and `user_data_zone` to provide initial context.
+2.  **`get_context_status()`:** Before each generation, we call this method. The output shows a `system_context` block with a token count for all combined zones and a `breakdown` field that lets us see the content of each individual zone that contributed to it.
+3.  **`memorize()`:** After the user mentions their favorite language, `memorize()` is called. The LLM analyzes the last turn, identifies this new, important fact, and appends it to the `discussion.memory` zone.
+4.  **Recall:** In the final turn, when asked to recall the favorite language, the AI has access to the updated `memory` content within its system context and can correctly answer "Rust". This demonstrates true long-term, stateful memory.
+
 
 ## Documentation
 
@@ -891,33 +922,54 @@ discussion.commit() # Save the updated memory to the database
 ```
 
 #### `get_context_status()`
-Provides a detailed, real-time breakdown of the current prompt context, showing exactly what will be sent to the model and how many tokens each part occupies.
 
-- **Return Value:** A dictionary containing the `max_tokens`, `current_tokens`, and a `zones` dictionary with the content and token count for each component.
-- **Use Case:** Essential for debugging context issues, understanding token usage, and visualizing how different data zones contribute to the final prompt.
+Provides a detailed, real-time breakdown of the current prompt context, showing exactly what will be sent to the model and how many tokens each major component occupies. This is crucial for debugging context issues and understanding token usage.
+
+The method accurately reflects the structure of the `lollms_text` format, where all system-level instructions (the main prompt, all data zones, and the pruning summary) are combined into a single system block.
+
+-   **Return Value:** A dictionary containing:
+    -   `max_tokens`: The configured maximum token limit for the discussion.
+    -   `current_tokens`: The total, most accurate token count for the entire prompt, calculated using the same logic as the `chat()` method.
+    -   `zones`: A dictionary with up to two keys:
+        -   **`system_context`**: Present if there is any system-level content. It contains:
+            -   `tokens`: The total token count for the **entire combined system block** (e.g., `!@>system:\n...\n`).
+            -   `content`: The full string content of the system block, showing exactly how all zones are merged.
+            -   `breakdown`: A sub-dictionary showing the raw text of each individual component (e.g., `system_prompt`, `memory`, `user_data_zone`) that was used to build the `content`.
+        -   **`message_history`**: Present if there are messages in the branch. It contains:
+            -   `tokens`: The total token count for the message history part of the prompt.
+            -   `content`: The full string of the formatted message history.
+            -   `message_count`: The number of messages included in the history.
+
+-   **Use Case:** Essential for debugging context issues, visualizing how different data zones contribute to the final prompt, and monitoring token consumption.
 
 ```python
 import json
 
+# Assuming 'discussion' is an LollmsDiscussion object with some data
+discussion.system_prompt = "You are a helpful AI."
+discussion.user_data_zone = "User is named Bob."
+discussion.add_message(sender="user", content="Hello!")
+discussion.add_message(sender="assistant", content="Hi Bob!")
+
 status = discussion.get_context_status()
 print(json.dumps(status, indent=2))
 
 # Expected Output Structure:
 # {
-#   "max_tokens": 8192,
-#   "current_tokens": 521,
+#   "max_tokens": null,
+#   "current_tokens": 46,
 #   "zones": {
-#     "system_prompt": {
-#       "content": "You are a helpful assistant.",
-#       "tokens": 12
-#     },
-#     "memory": {
-#       "content": "User's favorite color is blue.",
-#       "tokens": 15
+#     "system_context": {
+#       "content": "You are a helpful AI.\n\n-- User Data Zone --\nUser is named Bob.",
+#       "tokens": 25,
+#       "breakdown": {
+#         "system_prompt": "You are a helpful AI.",
+#         "user_data_zone": "User is named Bob."
+#       }
 #     },
 #     "message_history": {
-#       "content": "!@>user:\nHi there!\n!@>assistant:\nHello! How can I help?\n",
-#       "tokens": 494,
+#       "content": "!@>user:\nHello!\n!@>assistant:\nHi Bob!\n",
+#       "tokens": 21,
 #       "message_count": 2
 #     }
 #   }

{lollms_client-0.29.1 → lollms_client-0.29.2}/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.29.1" # Updated version
+__version__ = "0.29.2" # Updated version
 
 # Optionally, you could define __all__ if you want to be explicit about exports
 __all__ = [

{lollms_client-0.29.1 → lollms_client-0.29.2}/lollms_client/llm_bindings/llamacpp/__init__.py

@@ -352,8 +352,11 @@ class LlamaCppServerBinding(LollmsLLMBinding):
 
 
     def load_model(self, model_name_or_path: str) -> bool:
-        resolved_model_path = self._resolve_model_path(model_name_or_path)
-        
+        try:
+            resolved_model_path = self._resolve_model_path(model_name_or_path)
+        except Exception as ex:
+            trace_exception(ex)
+            return False
         # Determine the clip_model_path for this server instance
         # Priority: 1. Explicit `clip_model_path` from init (if exists) 2. Auto-detection
         final_clip_model_path: Optional[Path] = None

{lollms_client-0.29.1 → lollms_client-0.29.2}/lollms_client/lollms_discussion.py

@@ -1251,19 +1251,16 @@ class LollmsDiscussion:
             text_to_count = "\n".join(full_content)
 
         return self.lollmsClient.count_tokens(text_to_count)
-
     def get_context_status(self, branch_tip_id: Optional[str] = None) -> Dict[str, Any]:
         """
         Returns a detailed breakdown of the context size and its components.
 
-        This provides a comprehensive snapshot of the context usage, including the
-        content and token count for each part of the prompt (system prompt, data zones,
-        pruning summary, and message history). The token counts are based on the
-        "lollms_text" export format, which is the format used for pruning calculations.
+        This provides a comprehensive snapshot of the context usage. It accurately calculates
+        the token count of the combined system context (prompt, all data zones, summary)
+        and the message history, reflecting how the `lollms_text` export format works.
 
         Args:
-            branch_tip_id: The ID of the message branch to measure. Defaults
-                           to the active branch.
+            branch_tip_id: The ID of the message branch to measure. Defaults to the active branch.
 
         Returns:
             A dictionary with a detailed breakdown:
@@ -1271,72 +1268,71 @@ class LollmsDiscussion:
                 "max_tokens": int | None,
                 "current_tokens": int,
                 "zones": {
-                    "system_prompt": {"content": str, "tokens": int},
-                    "memory": {"content": str, "tokens": int},
-                    "user_data_zone": {"content": str, "tokens": int},
-                    "discussion_data_zone": {"content": str, "tokens": int},
-                    "personality_data_zone": {"content": str, "tokens": int},
-                    "pruning_summary": {"content": str, "tokens": int},
-                    "message_history": {"content": str, "tokens": int, "message_count": int}
+                    "system_context": {
+                        "content": str,
+                        "tokens": int,
+                        "breakdown": {
+                            "system_prompt": str,
+                            "memory": str,
+                            ...
+                        }
+                    },
+                    "message_history": {
+                        "content": str,
+                        "tokens": int,
+                        "message_count": int
+                    }
                 }
             }
-            Zones are only included if they contain content.
+            Zones and breakdown components are only included if they contain content.
         """
         result = {
             "max_tokens": self.max_context_size,
             "current_tokens": 0,
             "zones": {}
         }
-        total_tokens = 0
 
-        # 1. System Prompt
+        # --- 1. Assemble and Tokenize the Entire System Context Block ---
         system_prompt_text = (self._system_prompt or "").strip()
-        if system_prompt_text:
-            # We count tokens for the full block as it would appear in the prompt
-            full_block = f"!@>system:\n{system_prompt_text}\n"
-            tokens = self.lollmsClient.count_tokens(full_block)
-            result["zones"]["system_prompt"] = {
-                "content": system_prompt_text,
-                "tokens": tokens
-            }
-            total_tokens += tokens
-            
-        # 2. All Data Zones
-        zones_to_process = {
-            "memory": self.memory,
-            "user_data_zone": self.user_data_zone,
-            "discussion_data_zone": self.discussion_data_zone,
-            "personality_data_zone": self.personality_data_zone,
-        }
+        data_zone_text = self.get_full_data_zone() # This already formats all zones correctly
+        
+        pruning_summary_text = ""
+        if self.pruning_summary and self.pruning_point_id:
+            pruning_summary_text = f"--- Conversation Summary ---\n{self.pruning_summary.strip()}"
 
-        for name, content in zones_to_process.items():
-            content_text = (content or "").strip()
-            if content_text:
-                # Mimic the formatting from get_full_data_zone for accurate token counting
-                header = f"-- {name.replace('_', ' ').title()} --\n"
-                full_block = f"{header}{content_text}"
-                # In lollms_text format, zones are part of the system message, so we add separators
-                # This counts the standalone block.
-                tokens = self.lollmsClient.count_tokens(full_block)
-                result["zones"][name] = {
-                    "content": content_text,
-                    "tokens": tokens
-                }
-                # Note: The 'export' method combines these into one system prompt.
-                # For this breakdown, we count them separately. The total will be a close approximation.
-
-        # 3. Pruning Summary
-        pruning_summary_text = (self.pruning_summary or "").strip()
-        if pruning_summary_text and self.pruning_point_id:
-            full_block = f"!@>system:\n--- Conversation Summary ---\n{pruning_summary_text}\n"
-            tokens = self.lollmsClient.count_tokens(full_block)
-            result["zones"]["pruning_summary"] = {
-                "content": pruning_summary_text,
-                "tokens": tokens
+        # Combine all parts that go into the system block, separated by newlines
+        full_system_content_parts = [
+            part for part in [system_prompt_text, data_zone_text, pruning_summary_text] if part
+        ]
+        full_system_content = "\n\n".join(full_system_content_parts).strip()
+
+        if full_system_content:
+            # Create the final system block as it would be exported
+            system_block = f"!@>system:\n{full_system_content}\n"
+            system_tokens = self.lollmsClient.count_tokens(system_block)
+            
+            # Create the breakdown for user visibility
+            breakdown = {}
+            if system_prompt_text:
+                breakdown["system_prompt"] = system_prompt_text
+            if self.memory and self.memory.strip():
+                breakdown["memory"] = self.memory.strip()
+            if self.user_data_zone and self.user_data_zone.strip():
+                breakdown["user_data_zone"] = self.user_data_zone.strip()
+            if self.discussion_data_zone and self.discussion_data_zone.strip():
+                breakdown["discussion_data_zone"] = self.discussion_data_zone.strip()
+            if self.personality_data_zone and self.personality_data_zone.strip():
+                breakdown["personality_data_zone"] = self.personality_data_zone.strip()
+            if self.pruning_summary and self.pruning_summary.strip():
+                breakdown["pruning_summary"] = self.pruning_summary.strip()
+
+            result["zones"]["system_context"] = {
+                "content": full_system_content,
+                "tokens": system_tokens,
+                "breakdown": breakdown
             }
-            total_tokens += tokens
-        
-        # 4. Message History
+
+        # --- 2. Assemble and Tokenize the Message History Block ---
         branch_tip_id = branch_tip_id or self.active_branch_id
         messages_text = ""
         message_count = 0
@@ -1373,10 +1369,10 @@ class LollmsDiscussion:
                 "tokens": tokens,
                 "message_count": message_count
             }
-            total_tokens += tokens
 
-        # Finalize the total count. This re-calculates based on the actual export format
-        # for maximum accuracy, as combining zones can slightly change tokenization.
+        # --- 3. Finalize the Total Count ---
+        # This remains the most accurate way to get the final count, as it uses the
+        # exact same export logic as the chat method.
         result["current_tokens"] = self.count_discussion_tokens("lollms_text", branch_tip_id)
 
         return result

{lollms_client-0.29.1 → lollms_client-0.29.2/lollms_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lollms_client
-Version: 0.29.1
+Version: 0.29.2
 Summary: A client library for LoLLMs generate endpoint
 Author-email: ParisNeo <parisneoai@gmail.com>
 License: Apache Software License
@@ -296,9 +296,22 @@ This example showcases how `lollms-client` allows you to build powerful, knowled
 
 ### Building Stateful Agents with Memory and Data Zones
 
-The latest version of `LollmsDiscussion` introduces powerful features for creating agents that can remember information across conversations. This is achieved through structured data zones and a new `memorize()` method.
+The `LollmsDiscussion` class provides a sophisticated system for creating stateful agents that can remember information across conversations. This is achieved through a layered system of "context zones" that are automatically combined into the AI's system prompt.
 
-Let's build a "Personal Assistant" agent that learns about the user over time.
+#### Understanding the Context Zones
+
+The AI's context is more than just chat history. It's built from several distinct components, each with a specific purpose:
+
+*   **`system_prompt`**: The foundational layer defining the AI's core identity, persona, and primary instructions.
+*   **`memory`**: The AI's long-term, persistent memory. It stores key facts about the user or topics, built up over time using the `memorize()` method.
+*   **`user_data_zone`**: Holds session-specific information about the user's current state or goals (e.g., "User is currently working on 'file.py'").
+*   **`discussion_data_zone`**: Contains state or meta-information about the current conversational task (e.g., "Step 1 of the plan is complete").
+*   **`personality_data_zone`**: A knowledge base or set of rules automatically injected from a `LollmsPersonality`'s `data_source`.
+*   **`pruning_summary`**: An automatic, AI-generated summary of the oldest messages in a very long chat, used to conserve tokens without losing the gist of the early conversation.
+
+The `get_context_status()` method is your window into this system, showing you exactly how these zones are combined and how many tokens they consume.
+
+Let's see this in action with a "Personal Assistant" agent that learns about the user over time.
 
 ```python
 from lollms_client import LollmsClient, LollmsDataManager, LollmsDiscussion, MSG_TYPE
@@ -320,7 +333,8 @@ if not discussion:
         id=discussion_id,
         autosave=True # Important for persistence
     )
-    # Let's preset some user data
+    # Let's preset some data in different zones
+    discussion.system_prompt = "You are a helpful Personal Assistant."
     discussion.user_data_zone = "User's Name: Alex\nUser's Goal: Learn about AI development."
     discussion.commit()
 else:
@@ -331,13 +345,24 @@ def run_chat_turn(prompt: str):
     """Helper function to run a single chat turn and print details."""
     ASCIIColors.cyan(f"\n> User: {prompt}")
 
-    # --- A. Check context status BEFORE the turn ---
+    # --- A. Check context status BEFORE the turn using get_context_status() ---
     ASCIIColors.magenta("\n--- Context Status (Before Generation) ---")
     status = discussion.get_context_status()
-    print(f"Max Tokens: {status.get('max_tokens')}, Current Approx. Tokens: {status.get('current_tokens')}")
-    for zone, data in status.get('zones', {}).items():
-        print(f"  - Zone: {zone}, Tokens: {data['tokens']}")
-        # print(f"    Content: {data['content'][:80]}...") # Uncomment for more detail
+    print(f"Max Tokens: {status.get('max_tokens')}, Current Tokens: {status.get('current_tokens')}")
+    
+    # Print the system context details
+    if 'system_context' in status['zones']:
+        sys_ctx = status['zones']['system_context']
+        print(f"  - System Context Tokens: {sys_ctx['tokens']}")
+        # The 'breakdown' shows the individual zones that were combined
+        for name, content in sys_ctx.get('breakdown', {}).items():
+            print(f"    -> Contains '{name}': {content.split(chr(10))[0]}...")
+
+    # Print the message history details
+    if 'message_history' in status['zones']:
+        msg_hist = status['zones']['message_history']
+        print(f"  - Message History Tokens: {msg_hist['tokens']} ({msg_hist['message_count']} messages)")
+
     print("------------------------------------------")
 
     # --- B. Run the chat ---
@@ -348,7 +373,7 @@ def run_chat_turn(prompt: str):
     )
     print() # Newline after stream
 
-    # --- C. Trigger memorization ---
+    # --- C. Trigger memorization to update the 'memory' zone ---
     ASCIIColors.yellow("\nTriggering memorization process...")
     discussion.memorize()
     discussion.commit() # Save the new memory to the DB
@@ -359,24 +384,30 @@ run_chat_turn("Hi there! Can you recommend a good Python library for building we
 run_chat_turn("That sounds great. By the way, my favorite programming language is Rust, I find its safety features amazing.")
 run_chat_turn("What was my favorite programming language again?")
 
-# --- Final Inspection ---
+# --- Final Inspection of Memory ---
 ASCIIColors.magenta("\n--- Final Context Status ---")
 status = discussion.get_context_status()
-print(f"Max Tokens: {status.get('max_tokens')}, Current Approx. Tokens: {status.get('current_tokens')}")
-for zone, data in status.get('zones', {}).items():
-    print(f"  - Zone: {zone}, Tokens: {data['tokens']}")
-    print(f"    Content: {data['content'][:150].replace(chr(10), ' ')}...")
+print(f"Max Tokens: {status.get('max_tokens')}, Current Tokens: {status.get('current_tokens')}")
+if 'system_context' in status['zones']:
+    sys_ctx = status['zones']['system_context']
+    print(f"  - System Context Tokens: {sys_ctx['tokens']}")
+    for name, content in sys_ctx.get('breakdown', {}).items():
+        # Print the full content of the memory zone to verify it was updated
+        if name == 'memory':
+            ASCIIColors.yellow(f"    -> Full '{name}' content:\n{content}")
+        else:
+            print(f"    -> Contains '{name}': {content.split(chr(10))[0]}...")
 print("------------------------------------------")
 
 ```
 
 #### How it Works:
 
-1.  **Persistence:** The `LollmsDataManager` and `autosave=True` ensure that all changes to the discussion, including the data zones and memory, are saved to the `my_assistant.db` file. When you re-run the script, it loads the previous state.
-2.  **`user_data_zone`:** We pre-filled this zone with basic user info. This context is provided to the AI in every turn.
-3.  **`get_context_status()`:** Before each generation, we call this method to get a detailed breakdown of the prompt. This is excellent for debugging and understanding how the context window is being used.
-4.  **`memorize()`:** After the user mentions their favorite language, `memorize()` is called. The LLM analyzes the last turn, identifies this new, important fact ("user's favorite language is Rust"), and appends it to the `discussion.memory` field.
-5.  **Recall:** In the final turn, when asked to recall the favorite language, the AI has access to the `memory` zone and can correctly answer "Rust", even if that information had scrolled out of the recent conversation history. This demonstrates true long-term memory.
+1.  **Persistence & Initialization:** The `LollmsDataManager` saves and loads the discussion. We initialize the `system_prompt` and `user_data_zone` to provide initial context.
+2.  **`get_context_status()`:** Before each generation, we call this method. The output shows a `system_context` block with a token count for all combined zones and a `breakdown` field that lets us see the content of each individual zone that contributed to it.
+3.  **`memorize()`:** After the user mentions their favorite language, `memorize()` is called. The LLM analyzes the last turn, identifies this new, important fact, and appends it to the `discussion.memory` zone.
+4.  **Recall:** In the final turn, when asked to recall the favorite language, the AI has access to the updated `memory` content within its system context and can correctly answer "Rust". This demonstrates true long-term, stateful memory.
+
 
 ## Documentation
 
@@ -922,33 +953,54 @@ discussion.commit() # Save the updated memory to the database
 ```
 
 #### `get_context_status()`
-Provides a detailed, real-time breakdown of the current prompt context, showing exactly what will be sent to the model and how many tokens each part occupies.
 
-- **Return Value:** A dictionary containing the `max_tokens`, `current_tokens`, and a `zones` dictionary with the content and token count for each component.
-- **Use Case:** Essential for debugging context issues, understanding token usage, and visualizing how different data zones contribute to the final prompt.
+Provides a detailed, real-time breakdown of the current prompt context, showing exactly what will be sent to the model and how many tokens each major component occupies. This is crucial for debugging context issues and understanding token usage.
+
+The method accurately reflects the structure of the `lollms_text` format, where all system-level instructions (the main prompt, all data zones, and the pruning summary) are combined into a single system block.
+
+-   **Return Value:** A dictionary containing:
+    -   `max_tokens`: The configured maximum token limit for the discussion.
+    -   `current_tokens`: The total, most accurate token count for the entire prompt, calculated using the same logic as the `chat()` method.
+    -   `zones`: A dictionary with up to two keys:
+        -   **`system_context`**: Present if there is any system-level content. It contains:
+            -   `tokens`: The total token count for the **entire combined system block** (e.g., `!@>system:\n...\n`).
+            -   `content`: The full string content of the system block, showing exactly how all zones are merged.
+            -   `breakdown`: A sub-dictionary showing the raw text of each individual component (e.g., `system_prompt`, `memory`, `user_data_zone`) that was used to build the `content`.
+        -   **`message_history`**: Present if there are messages in the branch. It contains:
+            -   `tokens`: The total token count for the message history part of the prompt.
+            -   `content`: The full string of the formatted message history.
+            -   `message_count`: The number of messages included in the history.
+
+-   **Use Case:** Essential for debugging context issues, visualizing how different data zones contribute to the final prompt, and monitoring token consumption.
 
 ```python
 import json
 
+# Assuming 'discussion' is an LollmsDiscussion object with some data
+discussion.system_prompt = "You are a helpful AI."
+discussion.user_data_zone = "User is named Bob."
+discussion.add_message(sender="user", content="Hello!")
+discussion.add_message(sender="assistant", content="Hi Bob!")
+
 status = discussion.get_context_status()
 print(json.dumps(status, indent=2))
 
 # Expected Output Structure:
 # {
-#   "max_tokens": 8192,
-#   "current_tokens": 521,
+#   "max_tokens": null,
+#   "current_tokens": 46,
 #   "zones": {
-#     "system_prompt": {
-#       "content": "You are a helpful assistant.",
-#       "tokens": 12
-#     },
-#     "memory": {
-#       "content": "User's favorite color is blue.",
-#       "tokens": 15
+#     "system_context": {
+#       "content": "You are a helpful AI.\n\n-- User Data Zone --\nUser is named Bob.",
+#       "tokens": 25,
+#       "breakdown": {
+#         "system_prompt": "You are a helpful AI.",
+#         "user_data_zone": "User is named Bob."
+#       }
 #     },
 #     "message_history": {
-#       "content": "!@>user:\nHi there!\n!@>assistant:\nHello! How can I help?\n",
-#       "tokens": 494,
+#       "content": "!@>user:\nHello!\n!@>assistant:\nHi Bob!\n",
+#       "tokens": 21,
 #       "message_count": 2
 #     }
 #   }