crewplus 0.2.89__py3-none-any.whl

crewplus-0.2.89.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.1
+Name: crewplus
+Version: 0.2.89
+Summary: Base services for CrewPlus AI applications
+Author-Email: Tim Liu <tim@opsmateai.com>
+License: MIT
+Project-URL: Homepage, https://github.com/your-org/crewplus-base
+Project-URL: Documentation, https://crewplus.readthedocs.io
+Project-URL: Repository, https://github.com/your-org/crewplus-base
+Project-URL: Issues, https://github.com/your-org/crewplus-base/issues
+Requires-Python: <4.0,>=3.11
+Requires-Dist: langchain<1.0.0,>=0.3.25
+Requires-Dist: langchain-openai>=0.3.24
+Requires-Dist: google-genai>=1.21.1
+Requires-Dist: langchain-milvus<0.3.0,>=0.2.1
+Requires-Dist: langfuse<4.0.0,>=3.1.3
+Description-Content-Type: text/markdown
+
+# CrewPlus
+
+[![PyPI version](https://badge.fury.io/py/crewplus.svg)](https://badge.fury.io/py/crewplus)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/pypi/pyversions/crewplus.svg)](https://pypi.org/project/crewplus)
+[![Build Status](https://img.shields.io/travis/com/your-org/crewplus-base.svg)](https://travis-ci.com/your-org/crewplus-base)
+
+**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-agent`:** crewplus agent core: agentic task planner and executor, with context-aware memory.
+-   **`crewplus-ingestion`:** Provides robust pipelines for knowledge ingestion and data processing.
+-   **`crewplus-memory`:** Provides agent memory services for Crewplus AI Agents.
+-   **`crewplus-integrations`:** A collection of third-party integrations to connect CrewPlus with other services and platforms.
+
+## Features
+
+-   **Chat Services:** A unified interface for interacting with various chat models (e.g., `GeminiChatModel`, `TracedAzureChatOpenAI`).
+-   **Model Load Balancer:** Intelligently distribute requests across multiple LLM endpoints.
+-   **Vector DB Services:** working with popular vector stores (e.g. Milvus, Zilliz Cloud) for retrieval-augmented generation (RAG) and agent memory.
+-   **Observability & Tracing:** Automatic integration with tracing tools like Langfuse, with an extensible design for adding others (e.g., Helicone, ...).
+
+
+## Documentation
+
+For detailed guides and API references, please see the `docs/` folder.
+
+-   **[GeminiChatModel Documentation](./docs/GeminiChatModel.md)**: A comprehensive guide to using the `GeminiChatModel` for text, image, and video understanding.
+
+## Installation
+
+To install the core `crewplus` package, run the following command:
+
+```bash
+pip install crewplus
+```
+
+## Getting Started
+
+Here is a simple example of how to use the `GeminiChatModel` to start a conversation with an AI model.
+
+```python
+# main.py
+from crewplus.services import GeminiChatModel
+
+# Initialize the llm (API keys are typically handled by the configuration module)
+llm = GeminiChatModel(google_api_key="your-google-api-key")
+
+# Start a conversation
+response = llm.chat("Hello, what is CrewPlus?")
+
+print(response)
+```
+
+## Project Structure
+
+The `crewplus-base` repository is organized to separate core logic, tests, and documentation. 
+
+```
+crewplus-base/                    # GitHub repo name
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── CHANGELOG.md
+├── crewplus/                 # PyPI package name
+│   └──  __init__.py
+│   └──  services/
+│       └──  __init__.py
+│       └──  gemini_chat_model.py
+│       └──  azure_chat_model.py
+│       └──  model_load_balancer.py
+│       └──  tracing_manager.py
+│       └──  ...
+│   └──  vectorstores/milvus
+│       └──  __init__.py
+│       └──  schema_milvus.py
+│       └──  vdb_service.py
+│   └──  utils/
+│       └──  __init__.py
+│       └──  schema_action.py
+│       └──  ...
+├── tests/
+│   └── ...
+├── docs/
+│   └── ...
+└── notebooks/
+    └── ...
+
+```
+
+## Version Update
+
+0.2.50
+Add async aget_vector_store to enable async vector search  
+0.2.80 
+Add FeedbackManager, to support langsmith style feedback with langfuse score
+
+## 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
+
+### build package
+python -m build
+
+### deploy to TestPyPI (Test first)
+python -m twine upload --repository testpypi dist/*
+
+### install from TestPyPI 
+pip install -i https://test.pypi.org/simple/ crewplus
+
+### Deploy to official PyPI
+python -m twine upload dist/*

crewplus-0.2.89.dist-info/RECORD

@@ -0,0 +1,29 @@
+crewplus-0.2.89.dist-info/METADATA,sha256=GxRIVQAVJF7Y8kHTa0leU5FA5imAcdPhKNYjH9hj1fU,5471
+crewplus-0.2.89.dist-info/WHEEL,sha256=tsUv_t7BDeJeRHaSrczbGeuK-TtDpGsWi_JfpzD255I,90
+crewplus-0.2.89.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+crewplus-0.2.89.dist-info/licenses/LICENSE,sha256=2_NHSHRTKB_cTcT_GXgcenOCtIZku8j343mOgAguTfc,1087
+crewplus/__init__.py,sha256=m46HkZL1Y4toD619NL47Sn2Qe084WFFSFD7e6VoYKZc,284
+crewplus/callbacks/__init__.py,sha256=YG7ieeb91qEjp1zF0-inEN7mjZ7yT_D2yzdWFT8Z1Ws,63
+crewplus/callbacks/async_langfuse_handler.py,sha256=8_p7ctgcmDNQgF5vOqA47I0x-3GWsm7zioZcZHgedZk,7163
+crewplus/services/__init__.py,sha256=o6qtskHvwtAmdb4qiPNENW1ivlOgwLkPBhTVv-qeJ4s,702
+crewplus/services/azure_chat_model.py,sha256=5ZQBr4Vvb518X_768EV2Ax4YnzVqTGLEdugOysLxL8k,6323
+crewplus/services/feedback.md,sha256=4hMdSzQgG6qnprV0FkiyogSfMFj5eMwX4PoxN_xD9tU,3821
+crewplus/services/feedback_manager.py,sha256=vpleLxGa9f0dQbBXqwQfT9SWu8k0BJO40DN5coGdR_k,11652
+crewplus/services/gemini_chat_model.py,sha256=DYqz01H2TIHiCDQesSozVfOsMigno6QGwOtIweg7UHk,40103
+crewplus/services/init_services.py,sha256=tc1ti8Yufo2ixlJpwg8uH0KmoyQ4EqxCOe4uTEWnlRM,2413
+crewplus/services/model_load_balancer.py,sha256=HIx-k-FiizJSF4e88SFxfFVNS93vJR2zrOdU_fg26FU,12826
+crewplus/services/schemas/feedback.py,sha256=M2AIwzW2MWtAbly2xfEFxDcGVk8kMFzZ7jT9swTmbHc,2787
+crewplus/services/tracing_manager.py,sha256=pwNFeA77vnoZMh_AUOnK5TvAaPOOLg5oDnVOe1yUa9A,8502
+crewplus/utils/__init__.py,sha256=2Gk1n5srFJQnFfBuYTxktdtKOVZyNrFcNaZKhXk35Pw,142
+crewplus/utils/schema_action.py,sha256=GDaBoVFQD1rXqrLVSMTfXYW1xcUu7eDcHsn57XBSnIg,422
+crewplus/utils/schema_document_updater.py,sha256=frvffxn2vbi71fHFPoGb9hq7gH2azmmdq17p-Fumnvg,7322
+crewplus/utils/tracing_util.py,sha256=ew5VwjTKcY88P2sveIlGqmsNFR5OJ-DjKAHKQzBoTyE,2449
+crewplus/vectorstores/milvus/__init__.py,sha256=OeYv2rdyG7tcREIjBJPyt2TbE54NvyeRoWMe7LwopRE,245
+crewplus/vectorstores/milvus/milvus_schema_manager.py,sha256=-QRav-hzu-XWeJ_yKUMolal_EyMUspSg-nvh5sqlrlQ,11442
+crewplus/vectorstores/milvus/schema_milvus.py,sha256=wwNpfqsKS0xeozZES40IvB0iNwUtpCall_7Hkg0dL1g,27223
+crewplus/vectorstores/milvus/vdb_service.py,sha256=_jtJLEtURMYhKy_d7Hb6WoUiH_B1L2IbLC5TtGBZrzk,44270
+docs/GeminiChatModel.md,sha256=zZYyl6RmjZTUsKxxMiC9O4yV70MC4TD-IGUmWhIDBKA,8677
+docs/ModelLoadBalancer.md,sha256=aGHES1dcXPz4c7Y8kB5-vsCNJjriH2SWmjBkSGoYKiI,4398
+docs/VDBService.md,sha256=Dw286Rrf_fsi13jyD3Bo4Sy7nZ_G7tYm7d8MZ2j9hxk,9375
+docs/index.md,sha256=3tlc15uR8lzFNM5WjdoZLw0Y9o1P1gwgbEnOdIBspqc,1643
+crewplus-0.2.89.dist-info/RECORD,,

crewplus-0.2.89.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.6)
+Root-Is-Purelib: true
+Tag: py3-none-any

crewplus-0.2.89.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+

crewplus-0.2.89.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Opsmate AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/GeminiChatModel.md

@@ -0,0 +1,247 @@
+# 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 about a brave robot."):
+    print(chunk.content, end="", flush=True)
+
+# Using astream for an asynchronous chunked response
+import asyncio
+
+async def main():
+    print("\n--- Async Streaming Response ---")
+    async for chunk in model.astream("Tell me a short story about a brave robot."):
+        print(chunk.content, end="", flush=True)
+
+# To run the async function in a Jupyter Notebook or a script:
+# await main()
+# Or, if not in an async context:
+# asyncio.run(main())
+```
+
+## 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.")
+
+### Example 3: Streaming a Multimodal Response
+
+Streaming also works with complex, multimodal inputs. This is useful for getting faster time-to-first-token while the model processes all the data.
+
+```python
+# The url_message is from the previous example
+print("\n--- Streaming Multimodal Response ---")
+for chunk in model.stream([url_message]):
+    print(chunk.content, end="", flush=True)
+```
+
+## 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,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")
+```