crewplus 0.2.10__tar.gz → 0.2.11__tar.gz

{crewplus-0.2.10 → crewplus-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: crewplus
-Version: 0.2.10
+Version: 0.2.11
 Summary: Base services for CrewPlus AI applications
 Author-Email: Tim Liu <tim@opsmateai.com>
 License: MIT
@@ -45,7 +45,7 @@ CrewPlus is designed as a modular and extensible ecosystem of packages. This all
 
 -   **Chat Services:** A unified interface for interacting with various chat models (e.g., `GeminiChatModel`).
 -   **Model Load Balancer:** Intelligently distribute requests across multiple LLM endpoints.
--   **Vector DB Services:** Abstractions for working with popular vector stores for retrieval-augmented generation (RAG).
+-   **Vector DB Services:** working with popular vector stores (e.g. Milvus, Zilliz Cloud) for retrieval-augmented generation (RAG) and agent memory.
 
 
 ## Documentation
@@ -114,6 +114,12 @@ crewplus-base/                    # GitHub repo name
 ```
 
 ## Deploy to PyPI
+
+Clean Previous Build Artifacts:
+Remove the dist/, build/, and *.egg-info/ directories to ensure that no old files are included in the new build.
+
+rm -rf dist build *.egg-info
+
 # install deployment tool
 pip install twine
 

{crewplus-0.2.10 → crewplus-0.2.11}/README.md

@@ -25,7 +25,7 @@ CrewPlus is designed as a modular and extensible ecosystem of packages. This all
 
 -   **Chat Services:** A unified interface for interacting with various chat models (e.g., `GeminiChatModel`).
 -   **Model Load Balancer:** Intelligently distribute requests across multiple LLM endpoints.
--   **Vector DB Services:** Abstractions for working with popular vector stores for retrieval-augmented generation (RAG).
+-   **Vector DB Services:** working with popular vector stores (e.g. Milvus, Zilliz Cloud) for retrieval-augmented generation (RAG) and agent memory.
 
 
 ## Documentation
@@ -94,6 +94,12 @@ crewplus-base/                    # GitHub repo name
 ```
 
 ## Deploy to PyPI
+
+Clean Previous Build Artifacts:
+Remove the dist/, build/, and *.egg-info/ directories to ensure that no old files are included in the new build.
+
+rm -rf dist build *.egg-info
+
 # install deployment tool
 pip install twine
 

crewplus-0.2.11/crewplus/services/init_services.py

@@ -0,0 +1,20 @@
+import os
+from .model_load_balancer import ModelLoadBalancer
+
+model_balancer = None
+
+def init_load_balancer(config_path: str = None):
+    global model_balancer
+    if model_balancer is None:
+        # Use parameter if provided, otherwise check env var, then default
+        final_config_path = config_path or os.getenv(
+            "MODEL_CONFIG_PATH", 
+            "config/models_config.json"  # Fixed default path
+        )
+        model_balancer = ModelLoadBalancer(final_config_path)
+        model_balancer.load_config()  # Load initial configuration synchronously
+
+def get_model_balancer() -> ModelLoadBalancer:
+    if model_balancer is None:
+        raise RuntimeError("ModelLoadBalancer not initialized")
+    return model_balancer

{crewplus-0.2.10 → crewplus-0.2.11}/crewplus/services/model_load_balancer.py

@@ -141,6 +141,7 @@ class ModelLoadBalancer:
             return ChatOpenAI(**kwargs)
         elif provider == 'azure-openai-embeddings':
             return AzureOpenAIEmbeddings(
+                model=model_config['model_name'],
                 azure_deployment=model_config['deployment_name'],
                 openai_api_version=model_config['api_version'],
                 api_key=model_config['api_key'],

{crewplus-0.2.10 → crewplus-0.2.11}/crewplus/vectorstores/milvus/schema_milvus.py

@@ -5,9 +5,34 @@ import json
 from pymilvus import DataType
 from langchain_milvus import Milvus
 from langchain_core.documents import Document
-from ...utils import SchemaDocumentUpdater, Action
+from ...utils.schema_document_updater import SchemaDocumentUpdater
+from ...utils.schema_action import Action
 from .milvus_schema_manager import MilvusSchemaManager
 
+DEFAULT_SCHEMA = """
+{
+    "node_types": {
+        "Document": {
+            "properties": {
+                "pk": {
+                    "type": "INT64",
+                    "is_primary": true,
+                    "auto_id": true
+                },
+                "vector": {
+                    "type": "FLOAT_VECTOR",
+                    "dim": 1536
+                },
+                "text": {
+                    "type": "VARCHAR",
+                    "max_length": 65535,
+                    "description": "The core text of the memory. This could be a user query, a documented fact, a procedural step, or a log of an event."
+                }
+	        }
+	    }
+    }
+}
+"""
 
 class SchemaMilvus(Milvus):
     """

{crewplus-0.2.10 → crewplus-0.2.11}/crewplus/vectorstores/milvus/vdb_service.py

@@ -2,7 +2,7 @@
 # @Author: Cursor
 # @Date: 2025-02-12
 # @Last Modified by: Gemini
-# @Last Modified time: 2025-07-01
+# @Last Modified time: 2025-07-04
 
 import logging
 from typing import List, Dict, Union, Optional
@@ -11,8 +11,8 @@ from langchain_core.embeddings import Embeddings
 from langchain_openai import AzureOpenAIEmbeddings
 from pymilvus import MilvusClient
 
-from crewplus.services.init_services import get_model_balancer
-from crewplus.vectorstores.milvus.schema_milvus import SchemaMilvus
+from ...services.init_services import get_model_balancer
+from .schema_milvus import SchemaMilvus, DEFAULT_SCHEMA
 
 class VDBService(object):
     """
@@ -22,17 +22,22 @@ class VDBService(object):
     and provides helper methods to get embedding functions and vector store instances.
 
     Args:
-        settings (dict): A dictionary containing configuration for the vector store
+        settings (dict, optional): A dictionary containing configuration for the vector store
                          and embedding models.
+        endpoint (str, optional): The URI for the Zilliz cluster. Can be used for simple
+                                  initialization instead of `settings`.
+        token (str, optional): The token for authenticating with Zilliz. Must be provided
+                               with `endpoint`.
         schema (str, optional): The schema definition for a collection. Defaults to None.
         logger (logging.Logger, optional): An optional logger instance. Defaults to None.
 
     Raises:
-        ValueError: If required configurations are missing from the settings dictionary.
+        ValueError: If required configurations are missing.
         NotImplementedError: If an unsupported provider is specified.
         RuntimeError: If the MilvusClient fails to initialize after a retry.
 
     Example:
+        >>> # Initialize with a full settings dictionary
         >>> settings = {
         ...     "embedder": {
         ...         "provider": "azure-openai",
@@ -61,6 +66,10 @@ class VDBService(object):
         ...     }
         ... }
         >>> vdb_service = VDBService(settings=settings)
+        >>>
+        >>> # Alternatively, initialize with an endpoint and token for Zilliz
+        >>> # vdb_service_zilliz = VDBService(endpoint="YOUR_ZILLIZ_ENDPOINT", token="YOUR_ZILLIZ_TOKEN")
+        >>>
         >>> # Get the raw Milvus client
         >>> client = vdb_service.get_vector_client()
         >>> print(client.list_collections())
@@ -82,17 +91,41 @@ class VDBService(object):
     connection_args: dict
     settings: dict
     
-    def __init__(self, settings: dict, schema: str = None, logger: logging.Logger = None):
+    def __init__(self, settings: dict = None, endpoint: str = None, token: str = None, schema: str = None, logger: logging.Logger = None):
         """
-        Initializes the VDBService.
+        Initializes the VDBService. 
+
+        Can be initialized in two ways:
+        1. By providing a full `settings` dictionary for complex configurations.
+        2. By providing `endpoint` and `token` for a direct Zilliz connection.
+           Note: When using this method, an `embedder` configuration is not created.
+           You must either use the `ModelLoadBalancer` or pass an `Embeddings` object
+           directly to methods like `get_vector_store`.
         
         Args:
-            settings (dict): Configuration dictionary for the service.
+            settings (dict, optional): Configuration dictionary for the service. Defaults to None.
+            endpoint (str, optional): The URI for the Zilliz cluster. Used if `settings` is not provided.
+            token (str, optional): The token for authenticating with the Zilliz cluster.
             schema (str, optional): Default schema for new collections. Defaults to None.
             logger (logging.Logger, optional): Logger instance. Defaults to None.
         """
         self.logger = logger or logging.getLogger(__name__)
-        self.settings = settings
+
+        if settings:
+            self.settings = settings
+        elif endpoint and token:
+            self.logger.info("Initializing VDBService with endpoint and token for a Zilliz connection.")
+            self.settings = {
+                "vector_store": {
+                    "provider": "zilliz",
+                    "config": {
+                        "uri": endpoint,
+                        "token": token
+                    }
+                }
+            }
+        else:
+            raise ValueError("VDBService must be initialized with either a 'settings' dictionary or both 'endpoint' and 'token'.")
 
         vector_store_settings = self.settings.get("vector_store")
         if not vector_store_settings:
@@ -164,7 +197,7 @@ class VDBService(object):
         """
         return self._client
 
-    def get_embeddings(self, from_model_balancer: bool = False, model_type: Optional[str] = "embedding-large") -> Embeddings:
+    def get_embeddings(self, from_model_balancer: bool = False, provider: Optional[str] = "azure-openai", model_type: Optional[str] = "embedding-large") -> Embeddings:
         """
         Gets an embedding function, either from the model balancer or directly from settings.
 
@@ -178,7 +211,7 @@ class VDBService(object):
         """
         if from_model_balancer:
             model_balancer = get_model_balancer()
-            return model_balancer.get_model(model_type=model_type)
+            return model_balancer.get_model(provider=provider, model_type=model_type)
 
         embedder_config = self.settings.get("embedder")
         if not embedder_config:
@@ -212,11 +245,41 @@ class VDBService(object):
             self.logger.error(f"Unsupported embedding provider: {provider}")
             raise NotImplementedError(f"Embedding provider '{provider}' is not supported yet.")
         
+    def _ensure_collection_exists(self, collection_name: str, embeddings: Embeddings):
+        """
+        Checks if a collection exists and creates it if it doesn't.
+        This operation is wrapped in a try-except block to handle potential failures
+        during collection creation.
+        """
+        try:
+            client = self.get_vector_client()
+            if not client.has_collection(collection_name):
+                self.logger.info(f"Collection '{collection_name}' does not exist. Creating it.")
+                
+                schema_milvus = SchemaMilvus(
+                    embedding_function=embeddings,
+                    collection_name=collection_name,
+                    connection_args=self.connection_args,
+                    index_params=self.index_params
+                )
+
+                schema_to_use = self.schema or DEFAULT_SCHEMA
+                if not self.schema:
+                    self.logger.warning(f"No schema provided for VDBService. Using DEFAULT_SCHEMA for collection '{collection_name}'.")
+                
+                schema_milvus.set_schema(schema_to_use)
+                
+                if not schema_milvus.create_collection():
+                    raise RuntimeError(f"SchemaMilvus failed to create collection '{collection_name}'.")
+        except Exception as e:
+            self.logger.error(f"An error occurred while ensuring collection '{collection_name}' exists: {e}")
+            raise RuntimeError(f"Failed to ensure collection '{collection_name}' exists.") from e
+
     def get_vector_store(self, collection_name: str, embeddings: Embeddings = None, metric_type: str = "L2") -> Zilliz:
         """
         Gets a vector store instance, creating it if it doesn't exist for the collection.
-
-        This method caches instances by collection name to avoid re-instantiation.
+        This method validates both the embedding function and the vector store connection
+        before caching the instance to prevent faulty instances from being reused.
 
         Args:
             collection_name (str): The name of the collection in the vector database.
@@ -239,6 +302,22 @@ class VDBService(object):
         if embeddings is None:
             embeddings = self.get_embeddings()
 
+        # Ensure the collection exists before proceeding.
+        self._ensure_collection_exists(collection_name, embeddings)
+
+        # 1. Validate the embedding function before proceeding.
+        try:
+            self.logger.debug(f"Testing embedding function for collection '{collection_name}'...")
+            embeddings.embed_query("validation_test_string")
+            self.logger.debug("Embedding function is valid.")
+        except Exception as e:
+            self.logger.error(
+                f"The provided embedding function is invalid and failed with error: {e}. "
+                f"Cannot create a vector store for collection '{collection_name}'."
+            )
+            raise RuntimeError(f"Invalid embedding function provided.") from e
+
+        # If embeddings are valid, proceed to create the Zilliz instance.
         index_params = self.index_params or {
             "metric_type": metric_type,
             "index_type": "AUTOINDEX",
@@ -257,43 +336,48 @@ class VDBService(object):
 
         return vdb
 
-    def delete_old_indexes(self, url: str = None, vdb: Zilliz = None) -> None:
+    def delete_old_indexes(self, url: str = None, vdb: Zilliz = None) -> (bool | None):
         """ Delete old indexes of the same source_url
 
         Args:
             url (str): source url
+            vdb (Zilliz): Zilliz instance
         """
+        self.logger.info(f"Delete old indexes of the same source_url:{url}")
+
         if url is None or vdb is None:
-            return
+            return None
 
         # Delete indexes of the same source_url
-        expr = "source in [\"" + url + "\"]"
+        expr = f'source_url == "{url}" or source == "{url}"'
         pks = vdb.get_pks(expr)
 
         # Delete entities by pks
         if pks is not None and len(pks) > 0 :
-            old_items = vdb.delete(pks)
-            self.logger.info("ingesting document -- delete old indexes -- " + str(old_items))
+            res = vdb.delete(pks)
+            self.logger.info("Deleted old indexes result: " + str(res))
+            return res
 
-    def delete_old_indexes_by_id(self, id: str = None, vdb: Zilliz = None) -> None:
+    def delete_old_indexes_by_id(self, source_id: str = None, vdb: Zilliz = None) -> (bool | None):
         """ Delete old indexes of the same source_id
 
         Args:
-            id (str): source id
+            source_id (str): source id
         """
-        self.logger.info(f"Delete old indexes of the same source_id:{id}")
+        self.logger.info(f"Delete old indexes of the same source_id:{source_id}")
 
-        if id is None or vdb is None:
-            return
+        if source_id is None or vdb is None:
+            return None
 
         # Delete indexes of the same source_id
-        expr = "source_id in [\"" + id + "\"]"
+        expr = f'source_id == "{source_id}"'
         pks = vdb.get_pks(expr)
 
         # Delete entities by pks
         if pks is not None and len(pks) > 0 :
-            old_items = vdb.delete(pks)
-            self.logger.info("ingesting document -- delete old indexes -- " + str(old_items))
+            res = vdb.delete(pks)
+            self.logger.info("Deleted old indexes result: " + str(res))
+            return res
 
     def drop_collection(self, collection_name: str) -> None:
         """
@@ -326,12 +410,13 @@ class VDBService(object):
                 self.logger.info(f"Removed '{collection_name}' from instance cache.")
 
     def delete_data_by_filter(self, collection_name: str = None, filter: str = None) -> None:
-        """ Delete a collection
+        """ Delete data by filter
 
         Args:
-            collection_name (str): scollection_name
+            collection_name (str): collection_name
+            filter (str): filter
         """
-        self.logger.info(f"drop a collection by name:{collection_name}")
+        self.logger.info(f"Delete data by filter:{filter}")
 
         try:
             client=self.get_vector_client()

crewplus-0.2.11/docs/GeminiChatModel.md

@@ -0,0 +1,226 @@
+# GeminiChatModel Documentation
+
+## 1. Introduction
+
+The `GeminiChatModel` is a custom LangChain-compatible chat model that provides a robust interface to Google's Gemini Pro and Flash models. It is designed to handle multimodal inputs, including text, images, and videos, making it a versatile tool for building advanced AI applications.
+
+### Key Features:
+- **LangChain Compatibility**: Seamlessly integrates into the LangChain ecosystem as a `BaseChatModel`.
+- **Multimodal Support**: Natively processes text, images (from URLs, local paths, or base64), and videos (from local paths, Google Cloud URIs, or raw bytes).
+- **Streaming**: Supports streaming for both standard and multimodal responses.
+- **Advanced Configuration**: Allows fine-tuning of generation parameters like temperature, top-p, top-k, and max tokens.
+- **Video Segment Analysis**: Can process specific time ranges within a video using start and end offsets.
+
+## 2. Installation
+
+To use the `GeminiChatModel`, you need to install the `crewplus` package. If you are working within the project repository, you can install it in editable mode:
+
+```bash
+pip install crewplus
+```
+
+## 3. Initialization
+
+First, ensure you have set your Google API key as an environment variable:
+
+```bash
+# For Linux/macOS
+export GOOGLE_API_KEY="YOUR_API_KEY"
+
+# For Windows PowerShell
+$env:GEMINI_API_KEY = "YOUR_API_KEY"
+```
+
+Then, you can import and initialize the model in your Python code.
+
+```python
+import logging
+from crewplus.services import GeminiChatModel
+from langchain_core.messages import HumanMessage
+
+# Optional: Configure a logger for detailed output
+logging.basicConfig(level=logging.INFO)
+test_logger = logging.getLogger(__name__)
+
+# Initialize the model
+# You can also pass the google_api_key directly as a parameter
+model = GeminiChatModel(
+    model_name="gemini-2.5-flash", # Or "gemini-1.5-pro"
+    logger=test_logger,
+    temperature=0.0,
+)
+```
+
+## 4. Basic Usage (Text-only)
+
+The model can be used for simple text-based conversations using `.invoke()` or `.stream()`.
+
+```python
+# Using invoke for a single response
+response = model.invoke("Hello, how are you?")
+print(response.content)
+
+# Using stream for a chunked response
+print("\\n--- Streaming Response ---")
+for chunk in model.stream("Tell me a short story."):
+    print(chunk.content, end="", flush=True)
+```
+
+## 5. Image Understanding
+
+`GeminiChatModel` can understand images provided via a URL or as base64 encoded data.
+
+### Example 1: Image from a URL
+
+You can provide a direct URL to an image.
+
+```python
+from langchain_core.messages import HumanMessage
+
+url_message = HumanMessage(
+    content=[
+        {"type": "text", "text": "Describe this image:"},
+        {
+            "type": "image_url",
+            "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
+        },
+    ]
+)
+url_response = model.invoke([url_message])
+print("Image response (URL):", url_response.content)
+```
+> **Sample Output:**
+> The image shows a wooden boardwalk stretching into the distance through a field of tall, green grass... The overall impression is one of tranquility and natural beauty.
+
+### Example 2: Local Image (Base64)
+
+You can also send a local image file by encoding it in base64.
+
+```python
+import base64
+from langchain_core.messages import HumanMessage
+
+image_path = "./notebooks/test_image_202506191.jpg"
+try:
+    with open(image_path, "rb") as image_file:
+        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
+    
+    image_message = HumanMessage(
+        content=[
+            {"type": "text", "text": "Describe this photo and its background story."},
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": f"data:image/jpeg;base64,{encoded_string}"
+                }
+            },
+        ]
+    )
+    image_response = model.invoke([image_message])
+    print("Image response (base64):", image_response.content)
+except FileNotFoundError:
+    print(f"Image file not found at {image_path}, skipping base64 example.")
+```
+> **Sample Output:**
+> This image is a movie still from the 2017 Japanese thriller "22 Year Old's Confession: I am the Murderer"... The four women in the photo are the victims of a serial killer...
+
+## 6. Video Understanding
+
+The model supports video analysis from uploaded files, URIs, and raw bytes.
+
+**Important Note:** The Gemini API does **not** support common public video URLs (e.g., YouTube, Loom, or public MP4 links). Videos must be uploaded to Google's servers first to get a processable URI.
+
+### Example 1: Large Video File (>20MB)
+
+For large videos, you must first upload the file using the `google-genai` client to get a file object.
+
+```python
+from google import genai
+import os
+from langchain_core.messages import HumanMessage
+
+# Initialize the Google GenAI client
+client = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])
+
+# Upload the video file
+video_path = "./notebooks/manufacturing_process_tutorial.mp4"
+print("Uploading video... this may take a moment.")
+video_file_obj = client.files.upload(file=video_path)
+print(f"Video uploaded successfully. File name: {video_file_obj.name}")
+
+# Use the uploaded file object in the prompt
+video_message = HumanMessage(
+    content=[
+        {"type": "text", "text": "Summarize this video and provide timestamps for key events."},
+        {"type": "video_file", "file": video_file_obj},
+    ]
+)
+video_response = model.invoke([video_message])
+print("Video response:", video_response.content)
+```
+
+> **Sample Output:**
+> This video provides a step-by-step guide on how to correct a mis-set sidewall during tire manufacturing...
+> **Timestamps:**
+> * **0:04:** Applying product package to some material
+> * **0:12:** Splice product Together and Prepare some material
+> ...
+
+### Example 2: Video with Time Offsets
+
+You can analyze just a specific portion of a video by providing a `start_offset` and `end_offset`. This works with video URIs obtained after uploading.
+
+```python
+# Assuming 'video_file_obj' is available from the previous step
+video_uri = video_file_obj.uri
+
+offset_message = HumanMessage(
+    content=[
+        {"type": "text", "text": "Transcribe the events in this video segment."},
+        {
+            "type": "video_file", 
+            "url": video_uri,
+            "start_offset": "5s",
+            "end_offset": "30s"
+        }
+    ]
+)
+
+print("Streaming response for video segment:")
+for chunk in model.stream([offset_message]):
+    print(chunk.content, end="", flush=True)
+```
+> **Sample Output:**
+> This video demonstrates the process of applying Component A/Component B material to an assembly drum in a manufacturing setting...
+> **Transcription:**
+> **0:05 - 0:12:** A worker is shown applying a material...
+> **0:12 - 0:23:** The worker continues to prepare the material on the drum...
+
+### Example 3: Small Video File (<20MB)
+
+For small videos, you can pass the raw bytes directly without a separate upload step.
+
+```python
+from langchain_core.messages import HumanMessage
+
+try:
+    with open("./notebooks/product_demo_v1.mp4", "rb") as video_file:
+        video_bytes = video_file.read()
+    
+    video_message = HumanMessage(
+        content=[
+            {"type": "text", "text": "What is happening in this video?"},
+            {
+                "type": "video_file",
+                "data": video_bytes,
+                "mime_type": "video/mp4" # Mime type is required for raw data
+            },
+        ]
+    )
+    video_response = model.invoke([video_message])
+    print("Video response (bytes):", video_response.content)
+except FileNotFoundError:
+    print("Video file not found.")
+except Exception as e:
+    print(f"Video processing with bytes failed: {e}")
+```

crewplus-0.2.11/docs/ModelLoadBalancer.md

@@ -0,0 +1,134 @@
+# ModelLoadBalancer Documentation
+
+## 1. Introduction
+
+The `ModelLoadBalancer` is a utility class designed to manage and provide access to various language models from different providers, such as Azure OpenAI and Google GenAI. It loads model configurations from a JSON file and allows you to retrieve specific models by their deployment name or a combination of provider and type.
+
+### Key Features:
+- **Centralized Model Management**: Manage all your model configurations in a single JSON file.
+- **On-demand Model Loading**: Models are instantiated and loaded when requested.
+- **Provider Agnostic**: Supports multiple model providers.
+- **Flexible Retrieval**: Get models by a unique deployment name.
+
+## 2. Initialization
+
+To use the `ModelLoadBalancer`, you need to initialize it with the path to your model configuration file.
+
+```python
+from crewplus.services.model_load_balancer import ModelLoadBalancer
+
+# Initialize the balancer with the path to your config file
+config_path = "tests/models_config.json" # Adjust the path as needed
+balancer = ModelLoadBalancer(config_path=config_path)
+
+# Load the configurations and instantiate the models
+balancer.load_config()
+```
+
+## 3. Configuration File
+
+The `ModelLoadBalancer` uses a JSON file to configure the available models. Here is an example of what the configuration file looks like. The `deployment_name` is used to retrieve a specific model.
+
+```json
+{
+    "models": [
+        {
+            "id": 3,
+            "provider": "azure-openai",
+            "type": "inference",
+            "deployment_name": "gpt-4.1",
+            "api_version": "2025-01-01-preview",
+            "api_base": "https://crewplus-eastus2.openai.azure.com",
+            "api_key": "your-api-key"
+        },
+        {
+            "id": 7,
+            "provider": "google-genai",
+            "type": "inference",
+            "deployment_name": "gemini-2.5-flash",
+            "api_key": "your-google-api-key"
+        },
+        {
+            "id": 8,
+            "provider": "google-genai",
+            "type": "ingestion",
+            "deployment_name": "gemini-2.5-pro",
+            "api_key": "your-google-api-key"
+        }
+    ]
+}
+```
+
+## 4. Getting a Model
+
+You can retrieve a model instance using the `get_model` method and passing the `deployment_name`.
+
+### Get `gemini-2.5-flash`
+```python
+gemini_flash_model = balancer.get_model(deployment_name="gemini-2.5-flash")
+
+# Now you can use the model
+# from langchain_core.messages import HumanMessage
+# response = gemini_flash_model.invoke([HumanMessage(content="Hello!")])
+# print(response.content)
+```
+
+### Get `gemini-2.5-pro`
+```python
+gemini_pro_model = balancer.get_model(deployment_name="gemini-2.5-pro")
+```
+
+### Get `gpt-4.1`
+```python
+gpt41_model = balancer.get_model(deployment_name="gpt-4.1")
+```
+
+### Get `o3mini`
+The model `o3mini` is identified by the deployment name `gpt-o3mini-eastus2-RPM25`.
+```python
+o3mini_model = balancer.get_model(deployment_name="gpt-o3mini-eastus2-RPM25")
+```
+
+## 5. Global Access with `init_load_balancer`
+
+The `init_load_balancer` function provides a convenient singleton pattern for accessing the `ModelLoadBalancer` throughout your application without passing the instance around.
+
+First, you initialize the balancer once at the start of your application.
+
+### Initialization
+
+You can initialize it in several ways:
+
+**1. Default Initialization**
+
+This will look for the `MODEL_CONFIG_PATH` environment variable, or use the default path `_config/models_config.json`.
+
+```python
+from crewplus.services.init_services import init_load_balancer
+
+init_load_balancer()
+```
+
+**2. Initialization with a Custom Path**
+
+You can also provide a direct path to your configuration file.
+
+```python
+from crewplus.services.init_services import init_load_balancer
+
+init_load_balancer(config_path="path/to/your/models_config.json")
+```
+
+### Getting the Balancer and Models
+
+Once initialized, you can retrieve the `ModelLoadBalancer` instance from anywhere in your code using `get_model_balancer`.
+
+```python
+from crewplus.services.init_services import get_model_balancer
+
+# Get the balancer instance
+balancer = get_model_balancer()
+
+# Get a model by deployment name
+gemini_flash_model = balancer.get_model(deployment_name="gemini-2.5-flash")
+```

crewplus-0.2.11/docs/VDBService.md

@@ -0,0 +1,238 @@
+# VDBService Documentation
+
+## 1. Introduction
+
+The `VDBService` is a centralized service class designed to manage connections to vector databases (Milvus and Zilliz) and handle the instantiation of embedding models. It simplifies interactions with your vector store by reading all necessary configurations from a single `settings` object.
+
+### Key Features:
+- **Centralized Configuration**: Manages database connections and embedding model settings from a single Python dictionary.
+- **Provider-Agnostic Client**: Supports both Milvus and Zilliz as vector store providers.
+- **Resilient Connection**: Includes a built-in retry mechanism when first connecting to the vector database.
+- **Instance Caching**: Caches `Zilliz` vector store instances by collection name to prevent re-instantiation and improve performance.
+- **Flexible Embedding Models**: Can retrieve embedding models from either the global `ModelLoadBalancer` or directly from the configuration settings.
+
+## 2. Initialization
+
+To use the `VDBService`, you must first prepare a `settings` dictionary containing the configuration for your vector store and embedding provider. You then pass this dictionary to the service's constructor.
+
+If you plan to use embedding models from the global `ModelLoadBalancer`, you must initialize it first.
+
+```python
+from crewplus.vectorstores.milvus.vdb_service import VDBService
+from crewplus.services.init_services import init_load_balancer
+
+# 1. (Optional) Initialize the global model load balancer if you plan to use it.
+# This should be done once when your application starts.
+init_load_balancer(config_path="path/to/your/models_config.json")
+
+# 2. Define the configuration for the VDBService
+settings = {
+    "embedder": {
+        "provider": "azure-openai",
+        "config": {
+            "model": "text-embedding-3-small",
+            "api_version": "2023-05-15",
+            "api_key": "YOUR_AZURE_OPENAI_KEY",
+            "openai_base_url": "YOUR_AZURE_OPENAI_ENDPOINT",
+            "embedding_dims": 1536
+        }
+    },
+    "vector_store": {
+        "provider": "milvus",
+        "config": {
+            "host": "localhost",
+            "port": 19530,
+            "user": "root",
+            "password": "password",
+            "db_name": "default"
+        }
+    },
+    "index_params": {
+        "metric_type": "L2",
+        "index_type": "AUTOINDEX",
+        "params": {}
+    }
+}
+
+# 3. Initialize the VDBService with the settings
+vdb_service = VDBService(settings=settings)
+
+print("VDBService initialized successfully!")
+```
+
+**Alternative Initialization for Zilliz**
+
+For a simpler Zilliz Cloud connection, you can initialize the service directly with your endpoint and token.
+
+```python
+# Initialize directly with Zilliz credentials
+vdb_service_zilliz = VDBService(
+    endpoint="YOUR_ZILLIZ_ENDPOINT", 
+    token="YOUR_ZILLIZ_TOKEN"
+)
+
+print("VDBService for Zilliz initialized successfully!")
+```
+
+## 3. Usage Examples
+
+### Basic Usage: Get Vector Store with Default Embeddings
+
+This example shows how to get a vector store instance using the default embedding model specified in the `embedder` section of your settings.
+
+```python
+# Get a vector store instance for the "my_documents" collection
+# This will use the "azure-openai" embedder from the settings by default.
+vector_store = vdb_service.get_vector_store(collection_name="my_documents")
+
+# You can now use the vector_store object to add or search for documents
+# vector_store.add_texts(["some text to embed"])
+print(f"Successfully retrieved vector store for collection: {vector_store.collection_name}")
+```
+
+### Advanced Usage: Using an Embedding Model from the Model Load Balancer
+
+In some cases, you may want to use a specific embedding model managed by the central `ModelLoadBalancer`. This example demonstrates how to retrieve that model first and then pass it to `get_vector_store`.
+
+This requires the `ModelLoadBalancer` to have been initialized, as shown in the Initialization section above.
+
+```python
+# 1. Get a specific embedding model from the ModelLoadBalancer
+# The service will call get_model_balancer() internally to get the initialized instance.
+embedding_model = vdb_service.get_embeddings(
+    from_model_balancer=True,
+    provider="azure-openai-embeddings", 
+    model_type="embedding-large" # Specify the model type configured in the balancer
+)
+
+print(f"Retrieved embedding model from balancer: {embedding_model}")
+
+# 2. Get a vector store instance using the specified embedding model
+vector_store_from_balancer = vdb_service.get_vector_store(
+    collection_name="balancer_collection",
+    embeddings=embedding_model  # Pass the specific embedding model
+)
+
+print(f"Successfully retrieved vector store for collection: {vector_store_from_balancer.collection_name}")
+```
+
+### Getting the Raw Milvus Client
+
+If you need to perform operations not exposed by the LangChain `Zilliz` wrapper, you can get direct access to the underlying `MilvusClient`.
+
+```python
+# Get the raw Milvus client to perform advanced operations
+client = vdb_service.get_vector_client()
+
+# For example, list all collections in the database
+collections = client.list_collections()
+print("Available collections:", collections)
+```
+
+### Adding and Deleting Documents by Source
+
+This example shows a common workflow: adding documents with a specific `source` to a collection, and then using `delete_old_indexes` to remove them based on that source.
+
+**Note:** The `delete_old_indexes` method in this example filters on the `source` metadata field. Ensure your implementation matches the field you intend to use for filtering.
+
+```python
+from langchain_core.documents import Document
+import time
+
+# 1. Get the vector store instance
+collection_name = "test_collection_for_delete"
+vector_store = vdb_service.get_vector_store(collection_name=collection_name)
+
+# 2. Prepare documents with 'source' in their metadata.
+# The delete function looks for this specific metadata field.
+docs_to_add = [
+    Document(
+        page_content="This is a test document about CrewPlus AI.",
+        metadata={"source": "http://example.com/crewplus-docs"}
+    ),
+    Document(
+        page_content="This is another test document, about LangChain.",
+        metadata={"source": "http://example.com/langchain-docs"} # Different source
+    )
+]
+
+# 3. Add the documents to the collection
+ids = vector_store.add_documents(docs_to_add)
+print(f"Added {len(ids)} documents to collection '{collection_name}'.")
+
+# In a real application, you might need a short delay for indexing to complete.
+time.sleep(2) 
+
+# 4. Verify the documents were added
+results = vector_store.similarity_search("CrewPlus", k=2)
+print(f"Found {len(results)} related documents before deletion.")
+assert len(results) > 0
+
+# 5. Delete the documents using the same source
+source_to_delete = "http://example.com/crewplus-docs"
+vdb_service.delete_old_indexes(url=source_to_delete, vdb=vector_store)
+print(f"Called delete_old_indexes for source: {source_to_delete}")
+
+# Allow time for the deletion to be processed.
+time.sleep(2)
+
+# 6. Verify the documents were deleted
+results_after_delete = vector_store.similarity_search("CrewPlus", k=2)
+print(f"Found {len(results_after_delete)} related documents after deletion.")
+assert len(results_after_delete) == 0
+
+# 7. Clean up by dropping the collection
+vdb_service.drop_collection(collection_name=collection_name)
+print(f"Dropped collection '{collection_name}'.")
+```
+
+### Adding and Deleting Documents by Source ID
+
+This example shows how to add documents with a `source_id` and then use `delete_old_indexes_by_id` to remove them.
+
+```python
+from langchain_core.documents import Document
+import time
+
+# 1. Get the vector store instance
+collection_name = "test_collection_for_id_delete"
+vector_store_for_id = vdb_service.get_vector_store(collection_name=collection_name)
+
+# 2. Prepare documents with 'source_id' in their metadata.
+docs_with_id = [
+    Document(
+        page_content="Document for agent A.",
+        metadata={"source_id": "agent-a-123"}
+    ),
+    Document(
+        page_content="Another document for agent A.",
+        metadata={"source_id": "agent-a-123"}
+    )
+]
+
+# 3. Add the documents to the collection
+ids = vector_store_for_id.add_documents(docs_with_id)
+print(f"Added {len(ids)} documents to collection '{collection_name}'.")
+
+time.sleep(2) 
+
+# 4. Verify the documents were added
+results = vector_store_for_id.similarity_search("agent A", k=2)
+print(f"Found {len(results)} related documents before deletion.")
+assert len(results) == 2
+
+# 5. Delete the documents using the source_id
+id_to_delete = "agent-a-123"
+vdb_service.delete_old_indexes_by_id(source_id=id_to_delete, vdb=vector_store_for_id)
+print(f"Called delete_old_indexes_by_id for source_id: {id_to_delete}")
+
+time.sleep(2)
+
+# 6. Verify the documents were deleted
+results_after_delete = vector_store_for_id.similarity_search("agent A", k=2)
+print(f"Found {len(results_after_delete)} related documents after deletion.")
+assert len(results_after_delete) == 0
+
+# 7. Clean up by dropping the collection
+vdb_service.drop_collection(collection_name=collection_name)
+print(f"Dropped collection '{collection_name}'.")

crewplus-0.2.11/docs/index.md

@@ -0,0 +1,23 @@
+# Welcome to CrewPlus
+
+**CrewPlus** provides the foundational services and core components for building advanced AI applications. It is the heart of the CrewPlus ecosystem, designed for scalability, extensibility, and seamless integration.
+
+## Overview
+
+This repository, `crewplus-base`, contains the core `crewplus` Python package. It includes essential building blocks for interacting with large language models, managing vector databases, and handling application configuration. Whether you are building a simple chatbot or a complex multi-agent system, CrewPlus offers the robust foundation you need.
+
+## The CrewPlus Ecosystem
+
+CrewPlus is designed as a modular and extensible ecosystem of packages. This allows you to adopt only the components you need for your specific use case.
+
+-   **`crewplus` (This package):** The core package containing foundational services for chat, model load balancing, and vector stores.
+-   **`crewplus-agents`:** An extension for creating and managing autonomous AI agents.
+-   **`crewplus-ingestion`:** Provides robust pipelines for knowledge ingestion and data processing.
+-   **`crewplus-integrations`:** A collection of third-party integrations to connect CrewPlus with other services and platforms.
+
+## Getting Started
+
+To get started, check out our detailed user guides:
+
+-   **[GeminiChatModel Guide](./GeminiChatModel.md)**: A comprehensive guide to using the `GeminiChatModel` for text, image, and video understanding.
+-   **[ModelLoadBalancer Guide](./ModelLoadBalancer.md)**: A guide to using the `ModelLoadBalancer` for managing and accessing different language models.

{crewplus-0.2.10 → crewplus-0.2.11}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "crewplus"
-version = "0.2.10"
+version = "0.2.11"
 description = "Base services for CrewPlus AI applications"
 authors = [
     { name = "Tim Liu", email = "tim@opsmateai.com" },
@@ -32,4 +32,8 @@ Documentation = "https://crewplus.readthedocs.io"
 Repository = "https://github.com/your-org/crewplus-base"
 Issues = "https://github.com/your-org/crewplus-base/issues"
 
-[tool]
+[tool.pdm.build]
+includes = [
+    "crewplus/",
+    "docs/",
+]

crewplus-0.2.10/crewplus/services/init_services.py

@@ -1,16 +0,0 @@
-import os
-from crewplus.services.model_load_balancer import ModelLoadBalancer
-
-model_balancer = None
-
-def init_load_balancer():
-    global model_balancer
-    if model_balancer is None:
-        config_path = os.getenv("MODEL_CONFIG_PATH", "config/models_config.json")
-        model_balancer = ModelLoadBalancer(config_path)
-        model_balancer.load_config()  # Load initial configuration synchronously
-
-def get_model_balancer() -> ModelLoadBalancer:
-    if model_balancer is None:
-        raise RuntimeError("ModelLoadBalancer not initialized")
-    return model_balancer