crewplus 0.2.3__py3-none-any.whl → 0.2.4__py3-none-any.whl

{crewplus-0.2.3.dist-info → crewplus-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: crewplus
-Version: 0.2.3
+Version: 0.2.4
 Summary: Base services for CrewPlus AI applications
 Author-Email: Tim Liu <tim@opsmateai.com>
 License: MIT

{crewplus-0.2.3.dist-info → crewplus-0.2.4.dist-info}/RECORD

@@ -1,7 +1,7 @@
-crewplus-0.2.3.dist-info/METADATA,sha256=3kbzrxbpcbp1zW-lV4j4rYmxnOV5iFiF1oDi5bQ1K-I,4909
-crewplus-0.2.3.dist-info/WHEEL,sha256=tSfRZzRHthuv7vxpI4aehrdN9scLjk-dCJkPLzkHxGg,90
-crewplus-0.2.3.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-crewplus-0.2.3.dist-info/licenses/LICENSE,sha256=2_NHSHRTKB_cTcT_GXgcenOCtIZku8j343mOgAguTfc,1087
+crewplus-0.2.4.dist-info/METADATA,sha256=GanuWO7TBC2DPca7TZwW3WtVg7rZXpBQ1hWhM22G_-8,4909
+crewplus-0.2.4.dist-info/WHEEL,sha256=tSfRZzRHthuv7vxpI4aehrdN9scLjk-dCJkPLzkHxGg,90
+crewplus-0.2.4.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+crewplus-0.2.4.dist-info/licenses/LICENSE,sha256=2_NHSHRTKB_cTcT_GXgcenOCtIZku8j343mOgAguTfc,1087
 crewplus/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 crewplus/services/__init__.py,sha256=MmH2v3N0ZMsuqFNAupkXENjUqvgf5ehQ99H6EzPqLZU,48
 crewplus/services/gemini_chat_model.py,sha256=i9p5KvSJYaHSUBLPKM_bpyGVLWCDQoNeah_WjQVJRXs,26227
@@ -13,4 +13,8 @@ crewplus/vectorstores/milvus/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NM
 crewplus/vectorstores/milvus/milvus_schema_manager.py,sha256=qHMVIM0NS3rLfACb8d3-tQS9hJo6_7_YP8AxVx4t1Cc,9019
 crewplus/vectorstores/milvus/schema_milvus.py,sha256=GhHTtCH5HsIJc3RHa25RXl3aZdkS3Rba5KeuUk_Hi0k,11425
 crewplus/vectorstores/milvus/vdb_service.py,sha256=J7B6TOZmJl9_K2euJFKJFvSYqvruKbXuYkFiugWnXXs,16657
-crewplus-0.2.3.dist-info/RECORD,,
+docs/GeminiChatModel.md,sha256=_IQyup3ofAa2HxfSurO1GYUEezTHYYt5Q1khYNVThGM,8040
+docs/ModelLoadBalancer.md,sha256=mgwDtiKBlAJMBhXck97SPahCt395QJzHyrKmxmkfRtw,3082
+docs/VDBService.md,sha256=YwYpyYsZ-YkLD8WQjFYAHmEkPmVheTKUEJn0mVqrirA,8945
+docs/index.md,sha256=3tlc15uR8lzFNM5WjdoZLw0Y9o1P1gwgbEnOdIBspqc,1643
+crewplus-0.2.4.dist-info/RECORD,,

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}")
+```

docs/ModelLoadBalancer.md

@@ -0,0 +1,90 @@
+# 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")
+```

docs/VDBService.md

@@ -0,0 +1,223 @@
+# 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!")
+```
+
+## 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, 
+    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}'.")

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.