lollms-client 0.29.3__tar.gz → 0.31.0__tar.gz

{lollms_client-0.29.3 → lollms_client-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lollms_client
-Version: 0.29.3
+Version: 0.31.0
 Summary: A client library for LoLLMs generate endpoint
 Author-email: ParisNeo <parisneoai@gmail.com>
 License: Apache Software License
@@ -48,6 +48,7 @@ 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).
+*   🖼️ **Selective Image Activation:** Control which images in a message are active and sent to the model, allowing for fine-grained multimodal context management without deleting the original data.
 *   🤖 **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.
@@ -408,6 +409,64 @@ print("------------------------------------------")
 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.
 
+### Managing Multimodal Context: Activating and Deactivating Images
+
+When working with multimodal models, you can now control which images in a message are active and sent to the model. This is useful for focusing the AI's attention, saving tokens on expensive vision models, or allowing a user to correct which images are relevant.
+
+This is managed at the `LollmsMessage` level using the `toggle_image_activation()` method.
+
+```python
+from lollms_client import LollmsClient, LollmsDiscussion, LollmsDataManager
+from ascii_colors import ASCIIColors
+import base64
+from pathlib import Path
+
+# Helper to create a dummy image b64 string
+def create_dummy_image(text):
+    from PIL import Image, ImageDraw
+    img = Image.new('RGB', (100, 30), color = (73, 109, 137))
+    d = ImageDraw.Draw(img)
+    d.text((10,10), text, fill=(255,255,0))
+    buffer = Path("temp_img.png")
+    img.save(buffer, "PNG")
+    b64 = base64.b64encode(buffer.read_bytes()).decode('utf-8')
+    buffer.unlink()
+    return b64
+
+# --- 1. Setup ---
+lc = LollmsClient(binding_name="ollama", model_name="llava")
+discussion = LollmsDiscussion.create_new(lollms_client=lc)
+
+# --- 2. Add a message with multiple images ---
+img1_b64 = create_dummy_image("Image 1")
+img2_b64 = create_dummy_image("Image 2: Cat")
+img3_b64 = create_dummy_image("Image 3")
+
+discussion.add_message(
+    sender="user", 
+    content="What is in the second image?", 
+    images=[img1_b64, img2_b64, img3_b64]
+)
+user_message = discussion.get_messages()[-1]
+
+# --- 3. Check the initial state ---
+ASCIIColors.magenta("--- Initial State (All 3 Images Active) ---")
+status_before = discussion.get_context_status()
+print(f"Message History Text:\n{status_before['zones']['message_history']['content']}")
+
+# --- 4. Deactivate irrelevant images ---
+ASCIIColors.magenta("\n--- Deactivating images 1 and 3 ---")
+user_message.toggle_image_activation(index=0, active=False) # Deactivate first image
+user_message.toggle_image_activation(index=2, active=False) # Deactivate third image
+
+# --- 5. Check the new state ---
+ASCIIColors.magenta("\n--- New State (Only Image 2 is Active) ---")
+status_after = discussion.get_context_status()
+print(f"Message History Text:\n{status_after['zones']['message_history']['content']}")
+
+ASCIIColors.green("\nNotice the message now says '(1 image(s) attached)' instead of 3.")
+ASCIIColors.green("Only the active image will be sent to the multimodal LLM.")
+```
 
 ## Documentation
 
@@ -788,228 +847,8 @@ Contributions are welcome! Whether it's bug reports, feature suggestions, docume
 
 ## License
 
-This project is licensed under the **Apache 2.0 License**. See the [LICENSE](LICENSE) file for details (assuming you have a LICENSE file, if not, state "Apache 2.0 License").
+This project is licensed under the **Apache 2.0 License**. See the [LICENSE](LICENSE) file for details.
 
 ## 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`
-
-```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.
--   **Sophisticated Context Layering:** Manage conversation state with multiple, distinct data zones (`user_data_zone`, `discussion_data_zone`, `personality_data_zone`) and a long-term `memory` field, allowing for rich and persistent context.
-
-## 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 and Memory Zones
-
-`LollmsDiscussion` moves beyond a single `data_zone` to a more structured system of context layers. These string properties allow you to inject specific, persistent information into the AI's system prompt, separate from the main conversational flow. The content of all non-empty zones is automatically formatted and included in the prompt.
-
-#### `system_prompt`
-The main instruction set for the AI's persona and core task. It's the foundation of the prompt.
-- **Purpose:** Defines who the AI is and what its primary goal is.
-- **Example:** `"You are a helpful and friendly assistant."`
-
-#### `memory`
-A special zone for storing long-term, cross-discussion information about the user or topics. It is designed to be built up over time.
-- **Purpose:** To give the AI a persistent memory that survives across different chat sessions.
-- **Example:** `"User's name is Alex.\nUser's favorite programming language is Rust."`
-
-#### `user_data_zone`
-Holds information specific to the current user that might be relevant for the session.
-- **Purpose:** Storing user preferences, profile details, or session-specific goals.
--- **Example:** `"Current project: API development.\nUser is a beginner in Python."`
-
-#### `discussion_data_zone`
-Contains context relevant only to the current discussion.
-- **Purpose:** Holding summaries, state information, or data relevant to the current conversation topic that needs to be kept in front of the AI.
-- **Example:** `"The user has already tried libraries A and B and found them too complex."`
-
-#### `personality_data_zone`
-This is where static or dynamic knowledge from a `LollmsPersonality`'s `data_source` is loaded.
-- **Purpose:** To provide personalities with their own built-in knowledge bases or rulesets.
-- **Example:** `"Rule 1: All code must be documented.\nRule 2: Use type hints."`
-
-#### Example: How Zones are Combined
-
-The `export()` method intelligently combines these zones. If all zones were filled, the effective system prompt would look something like this:
-
-```
-!@>system:
-You are a helpful and friendly assistant.
-
--- Memory --
-User's name is Alex.
-User's favorite programming language is Rust.
-
--- User Data Zone --
-Current project: API development.
-User is a beginner in Python.
-
--- Discussion Data Zone --
-The user has already tried libraries A and B and found them too complex.
-
--- Personality Data Zone --
-Rule 1: All code must be documented.
-Rule 2: Use type hints.
-```
-### Other Important Properties
-
--   `id`: The unique identifier for the discussion.
--   `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 loaded into the `discussion.personality_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 loaded into the `discussion.personality_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.**
-
-### New Methods for State and Context Management
-
-#### `memorize()`
-This method empowers the AI to build its own long-term memory. It analyzes the current conversation, extracts key facts or preferences, and appends them to the `memory` data zone.
-
-- **How it works:** It uses the LLM itself to summarize the most important, long-term takeaways from the recent conversation.
-- **Use Case:** Perfect for creating assistants that learn about the user over time, remembering their name, preferences, or past projects without the user needing to repeat themselves.
-
-```python
-# User has just said: "My company is called 'Innovatech'."
-discussion.chat("My company is called 'Innovatech'.")
-
-# Now, trigger memorization
-discussion.memorize() 
-discussion.commit() # Save the updated memory to the database
-
-# The discussion.memory field might now contain:
-# "... previous memory ...
-#
-# --- Memory entry from 2024-06-27 10:30:00 UTC ---
-# - User's company is named 'Innovatech'."
-```
-
-#### `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 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": null,
-#   "current_tokens": 46,
-#   "zones": {
-#     "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:\nHello!\n!@>assistant:\nHi Bob!\n",
-#       "tokens": 21,
-#       "message_count": 2
-#     }
-#   }
-# }
-```
-
-### 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.29.3 → lollms_client-0.31.0}/README.md

@@ -17,6 +17,7 @@ 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).
+*   🖼️ **Selective Image Activation:** Control which images in a message are active and sent to the model, allowing for fine-grained multimodal context management without deleting the original data.
 *   🤖 **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.
@@ -377,6 +378,64 @@ print("------------------------------------------")
 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.
 
+### Managing Multimodal Context: Activating and Deactivating Images
+
+When working with multimodal models, you can now control which images in a message are active and sent to the model. This is useful for focusing the AI's attention, saving tokens on expensive vision models, or allowing a user to correct which images are relevant.
+
+This is managed at the `LollmsMessage` level using the `toggle_image_activation()` method.
+
+```python
+from lollms_client import LollmsClient, LollmsDiscussion, LollmsDataManager
+from ascii_colors import ASCIIColors
+import base64
+from pathlib import Path
+
+# Helper to create a dummy image b64 string
+def create_dummy_image(text):
+    from PIL import Image, ImageDraw
+    img = Image.new('RGB', (100, 30), color = (73, 109, 137))
+    d = ImageDraw.Draw(img)
+    d.text((10,10), text, fill=(255,255,0))
+    buffer = Path("temp_img.png")
+    img.save(buffer, "PNG")
+    b64 = base64.b64encode(buffer.read_bytes()).decode('utf-8')
+    buffer.unlink()
+    return b64
+
+# --- 1. Setup ---
+lc = LollmsClient(binding_name="ollama", model_name="llava")
+discussion = LollmsDiscussion.create_new(lollms_client=lc)
+
+# --- 2. Add a message with multiple images ---
+img1_b64 = create_dummy_image("Image 1")
+img2_b64 = create_dummy_image("Image 2: Cat")
+img3_b64 = create_dummy_image("Image 3")
+
+discussion.add_message(
+    sender="user", 
+    content="What is in the second image?", 
+    images=[img1_b64, img2_b64, img3_b64]
+)
+user_message = discussion.get_messages()[-1]
+
+# --- 3. Check the initial state ---
+ASCIIColors.magenta("--- Initial State (All 3 Images Active) ---")
+status_before = discussion.get_context_status()
+print(f"Message History Text:\n{status_before['zones']['message_history']['content']}")
+
+# --- 4. Deactivate irrelevant images ---
+ASCIIColors.magenta("\n--- Deactivating images 1 and 3 ---")
+user_message.toggle_image_activation(index=0, active=False) # Deactivate first image
+user_message.toggle_image_activation(index=2, active=False) # Deactivate third image
+
+# --- 5. Check the new state ---
+ASCIIColors.magenta("\n--- New State (Only Image 2 is Active) ---")
+status_after = discussion.get_context_status()
+print(f"Message History Text:\n{status_after['zones']['message_history']['content']}")
+
+ASCIIColors.green("\nNotice the message now says '(1 image(s) attached)' instead of 3.")
+ASCIIColors.green("Only the active image will be sent to the multimodal LLM.")
+```
 
 ## Documentation
 
@@ -757,228 +816,8 @@ Contributions are welcome! Whether it's bug reports, feature suggestions, docume
 
 ## License
 
-This project is licensed under the **Apache 2.0 License**. See the [LICENSE](LICENSE) file for details (assuming you have a LICENSE file, if not, state "Apache 2.0 License").
+This project is licensed under the **Apache 2.0 License**. See the [LICENSE](LICENSE) file for details.
 
 ## 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`
-
-```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.
--   **Sophisticated Context Layering:** Manage conversation state with multiple, distinct data zones (`user_data_zone`, `discussion_data_zone`, `personality_data_zone`) and a long-term `memory` field, allowing for rich and persistent context.
-
-## 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 and Memory Zones
-
-`LollmsDiscussion` moves beyond a single `data_zone` to a more structured system of context layers. These string properties allow you to inject specific, persistent information into the AI's system prompt, separate from the main conversational flow. The content of all non-empty zones is automatically formatted and included in the prompt.
-
-#### `system_prompt`
-The main instruction set for the AI's persona and core task. It's the foundation of the prompt.
-- **Purpose:** Defines who the AI is and what its primary goal is.
-- **Example:** `"You are a helpful and friendly assistant."`
-
-#### `memory`
-A special zone for storing long-term, cross-discussion information about the user or topics. It is designed to be built up over time.
-- **Purpose:** To give the AI a persistent memory that survives across different chat sessions.
-- **Example:** `"User's name is Alex.\nUser's favorite programming language is Rust."`
-
-#### `user_data_zone`
-Holds information specific to the current user that might be relevant for the session.
-- **Purpose:** Storing user preferences, profile details, or session-specific goals.
--- **Example:** `"Current project: API development.\nUser is a beginner in Python."`
-
-#### `discussion_data_zone`
-Contains context relevant only to the current discussion.
-- **Purpose:** Holding summaries, state information, or data relevant to the current conversation topic that needs to be kept in front of the AI.
-- **Example:** `"The user has already tried libraries A and B and found them too complex."`
-
-#### `personality_data_zone`
-This is where static or dynamic knowledge from a `LollmsPersonality`'s `data_source` is loaded.
-- **Purpose:** To provide personalities with their own built-in knowledge bases or rulesets.
-- **Example:** `"Rule 1: All code must be documented.\nRule 2: Use type hints."`
-
-#### Example: How Zones are Combined
-
-The `export()` method intelligently combines these zones. If all zones were filled, the effective system prompt would look something like this:
-
-```
-!@>system:
-You are a helpful and friendly assistant.
-
--- Memory --
-User's name is Alex.
-User's favorite programming language is Rust.
-
--- User Data Zone --
-Current project: API development.
-User is a beginner in Python.
-
--- Discussion Data Zone --
-The user has already tried libraries A and B and found them too complex.
-
--- Personality Data Zone --
-Rule 1: All code must be documented.
-Rule 2: Use type hints.
-```
-### Other Important Properties
-
--   `id`: The unique identifier for the discussion.
--   `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 loaded into the `discussion.personality_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 loaded into the `discussion.personality_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.**
-
-### New Methods for State and Context Management
-
-#### `memorize()`
-This method empowers the AI to build its own long-term memory. It analyzes the current conversation, extracts key facts or preferences, and appends them to the `memory` data zone.
-
-- **How it works:** It uses the LLM itself to summarize the most important, long-term takeaways from the recent conversation.
-- **Use Case:** Perfect for creating assistants that learn about the user over time, remembering their name, preferences, or past projects without the user needing to repeat themselves.
-
-```python
-# User has just said: "My company is called 'Innovatech'."
-discussion.chat("My company is called 'Innovatech'.")
-
-# Now, trigger memorization
-discussion.memorize() 
-discussion.commit() # Save the updated memory to the database
-
-# The discussion.memory field might now contain:
-# "... previous memory ...
-#
-# --- Memory entry from 2024-06-27 10:30:00 UTC ---
-# - User's company is named 'Innovatech'."
-```
-
-#### `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 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": null,
-#   "current_tokens": 46,
-#   "zones": {
-#     "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:\nHello!\n!@>assistant:\nHi Bob!\n",
-#       "tokens": 21,
-#       "message_count": 2
-#     }
-#   }
-# }
-```
-
-### 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.29.3 → lollms_client-0.31.0}/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.3" # Updated version
+__version__ = "0.31.0" # Updated version
 
 # Optionally, you could define __all__ if you want to be explicit about exports
 __all__ = [

{lollms_client-0.29.3 → lollms_client-0.31.0}/lollms_client/llm_bindings/ollama/__init__.py

@@ -11,6 +11,7 @@ from typing import Optional, Callable, List, Union, Dict
 
 from ascii_colors import ASCIIColors, trace_exception
 import pipmaster as pm
+from lollms_client.lollms_utilities import ImageTokenizer
 pm.ensure_packages(["ollama","pillow","tiktoken"])
 
 
@@ -468,6 +469,24 @@ class OllamaBinding(LollmsLLMBinding):
             return -1
         #return count_tokens_ollama(text, self.model_name, self.ollama_client)
         return len(self.tokenize(text))
+
+    def count_image_tokens(self, image: str) -> int:
+        """
+        Estimate the number of tokens for an image using ImageTokenizer based on self.model_name.
+
+        Args:
+            image (str): Image to count tokens from. Either base64 string, path to image file, or URL.
+
+        Returns:
+            int: Estimated number of tokens for the image. Returns -1 on error.
+        """
+        try:
+            # Delegate token counting to ImageTokenizer
+            return ImageTokenizer(self.model_name).count_image_tokens(image)
+        except Exception as e:
+            ASCIIColors.warning(f"Could not estimate image tokens: {e}")
+            return -1
+
     def embed(self, text: str, **kwargs) -> List[float]:
         """
         Get embeddings for the input text using Ollama API.