From ee5786cdf2a4287e36f74cf807ff80e4e798c019 Mon Sep 17 00:00:00 2001 From: Kye Date: Tue, 12 Dec 2023 14:59:45 -0800 Subject: [PATCH 1/6] [BaseMultiModalModel] [BaseSwarm] [BaseStructure] --- pyproject.toml | 2 +- swarms/models/base_multimodal_model.py | 4 +- swarms/models/gpt4_vision_api.py | 62 +++- swarms/structs/base.py | 389 ++++++++++++++++++++++++- tests/swarms/test_base.py | 259 ++++++++++++++++ 5 files changed, 704 insertions(+), 12 deletions(-) create mode 100644 tests/swarms/test_base.py diff --git a/pyproject.toml b/pyproject.toml index faf387fa..4e1c1c7c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,7 +38,7 @@ faiss-cpu = "*" backoff = "*" marshmallow = "*" datasets = "*" -optimum = "*" +optimum = "1.15.0" diffusers = "*" PyPDF2 = "*" vllm = "*" diff --git a/swarms/models/base_multimodal_model.py b/swarms/models/base_multimodal_model.py index cbf4f163..396bd56f 100644 --- a/swarms/models/base_multimodal_model.py +++ b/swarms/models/base_multimodal_model.py @@ -317,13 +317,13 @@ class BaseMultiModalModel: content = colored(content, color) print(content) - def stream(self, content: str): + def stream_response(self, text: str): """Stream the output Args: content (str): _description_ """ - for chunk in content: + for chunk in text: print(chunk) def meta_prompt(self): diff --git a/swarms/models/gpt4_vision_api.py b/swarms/models/gpt4_vision_api.py index 6bab073f..7496cf32 100644 --- a/swarms/models/gpt4_vision_api.py +++ b/swarms/models/gpt4_vision_api.py @@ -112,10 +112,15 @@ class GPT4VisionAPI(BaseMultiModalModel): def download_img_then_encode(self, img: str): """Download image from URL then encode image to base64 using requests""" - pass + if not os.path.exists(img): + print(f"Image file not found: {img}") + return None + + response = requests.get(img) + return base64.b64encode(response.content).decode("utf-8") # Function to handle vision tasks - def run(self, img: str, task: str, *args, **kwargs): + def run(self, task: str = None, img: str = None, *args, **kwargs): """Run the model.""" try: base64_image = self.encode_image(img) @@ -162,7 +167,10 @@ class GPT4VisionAPI(BaseMultiModalModel): return None except Exception as error: - print(f"Error with the request: {error}") + print( + f"Error with the request: {error}, make sure you" + " double check input types and positions" + ) return None def video_prompt(self, frames): @@ -207,7 +215,7 @@ class GPT4VisionAPI(BaseMultiModalModel): for chunk in content: print(chunk) - def process_video(self, video: str): + def process_video(self, video: str = None): """ Process a video into a list of base64 frames @@ -252,8 +260,50 @@ class GPT4VisionAPI(BaseMultiModalModel): *args, **kwargs, ): - self.video_prompt(self.process_video(video)) - pass + prompt = self.video_prompt(self.process_video(video)) + headers = { + "Content-Type": "application/json", + "Authorization": f"Bearer {openai_api_key}", + } + payload = { + "model": self.model_name, + "messages": [ + { + "role": "system", + "content": [self.system_prompt], + }, + { + "role": "user", + "content": [ + (task,), # task + *map( + lambda x: {"image": x, "resize": 768}, + prompt[0::50], + ), + ], + }, + ], + "max_tokens": self.max_tokens, + } + response = requests.post( + self.openai_proxy, + headers=headers, + json=payload, + ) + + out = response.json() + content = out["choices"][0]["message"]["content"] + + if self.streaming_enabled: + content = self.stream_response(content) + else: + pass + + if self.beautify: + content = colored(content, "cyan") + print(content) + else: + print(content) def __call__( self, diff --git a/swarms/structs/base.py b/swarms/structs/base.py index 559416f0..9f6da9af 100644 --- a/swarms/structs/base.py +++ b/swarms/structs/base.py @@ -1,5 +1,388 @@ -""" -Base Structure for all Swarm Structures +import json +import os +from abc import ABC, abstractmethod +from typing import Optional, Any, Dict, List +from datetime import datetime +import asyncio +import concurrent.futures +from concurrent.futures import ThreadPoolExecutor +import psutil +try: + import gzip +except ImportError as error: + print(f"Error importing gzip: {error}") -""" + +class BaseStructure(ABC): + + def __init__( + self, + name: Optional[str] = None, + description: Optional[str] = None, + save_metadata: bool = True, + save_artifact_path: Optional[str] = "./artifacts", + save_metadata_path: Optional[str] = "./metadata", + save_error_path: Optional[str] = "./errors", + *args, + **kwargs, + ): + self.name = name + self.description = description + self.save_metadata = save_metadata + self.save_artifact_path = save_artifact_path + self.save_metadata_path = save_metadata_path + self.save_error_path = save_error_path + + @abstractmethod + def run(self, *args, **kwargs): + """Run the structure.""" + pass + + def save_to_file(self, data: Any, file_path: str): + """Save data to file. + + Args: + data (Any): _description_ + file_path (str): _description_ + """ + with open(file_path, "w") as file: + json.dump(data, file) + + def load_from_file(self, file_path: str) -> Any: + """Load data from file. + + Args: + file_path (str): _description_ + + Returns: + Any: _description_ + """ + with open(file_path, "r") as file: + return json.load(file) + + def save_metadata(self, metadata: Dict[str, Any]): + """Save metadata to file. + + Args: + metadata (Dict[str, Any]): _description_ + """ + if self.save_metadata: + file_path = os.path.join( + self.save_metadata_path, f"{self.name}_metadata.json" + ) + self.save_to_file(metadata, file_path) + + def load_metadata(self) -> Dict[str, Any]: + """Load metadata from file. + + Returns: + Dict[str, Any]: _description_ + """ + file_path = os.path.join( + self.save_metadata_path, f"{self.name}_metadata.json" + ) + return self.load_from_file(file_path) + + def log_error(self, error_message: str): + """Log error to file. + + Args: + error_message (str): _description_ + """ + file_path = os.path.join( + self.save_error_path, f"{self.name}_errors.log" + ) + with open(file_path, "a") as file: + file.write(f"{error_message}\n") + + def save_artifact(self, artifact: Any, artifact_name: str): + """Save artifact to file. + + Args: + artifact (Any): _description_ + artifact_name (str): _description_ + """ + file_path = os.path.join( + self.save_artifact_path, f"{artifact_name}.json" + ) + self.save_to_file(artifact, file_path) + + def load_artifact(self, artifact_name: str) -> Any: + """Load artifact from file. + + Args: + artifact_name (str): _description_ + + Returns: + Any: _description_ + """ + file_path = os.path.join( + self.save_artifact_path, f"{artifact_name}.json" + ) + return self.load_from_file(file_path) + + def _current_timestamp(self): + """Current timestamp. + + Returns: + _type_: _description_ + """ + return datetime.now().strftime("%Y-%m-%d %H:%M:%S") + + def log_event( + self, + event: str, + event_type: str = "INFO", + ): + """Log event to file. + + Args: + event (str): _description_ + event_type (str, optional): _description_. Defaults to "INFO". + """ + timestamp = self._current_timestamp() + log_message = f"[{timestamp}] [{event_type}] {event}\n" + file = os.path.join( + self.save_metadata_path, f"{self.name}_events.log" + ) + with open(file, "a") as file: + file.write(log_message) + + async def run_async(self, *args, **kwargs): + """Run the structure asynchronously.""" + loop = asyncio.get_event_loop() + return await loop.run_in_executor( + None, self.run, *args, **kwargs + ) + + async def save_metadata_async(self, metadata: Dict[str, Any]): + """Save metadata to file asynchronously. + + Args: + metadata (Dict[str, Any]): _description_ + """ + loop = asyncio.get_event_loop() + return await loop.run_in_executor( + None, self.save_metadata, metadata + ) + + async def load_metadata_async(self) -> Dict[str, Any]: + """Load metadata from file asynchronously. + + Returns: + Dict[str, Any]: _description_ + """ + loop = asyncio.get_event_loop() + return await loop.run_in_executor(None, self.load_metadata) + + async def log_error_async(self, error_message: str): + """Log error to file asynchronously. + + Args: + error_message (str): _description_ + """ + loop = asyncio.get_event_loop() + return await loop.run_in_executor( + None, self.log_error, error_message + ) + + async def save_artifact_async( + self, artifact: Any, artifact_name: str + ): + """Save artifact to file asynchronously. + + Args: + artifact (Any): _description_ + artifact_name (str): _description_ + """ + loop = asyncio.get_event_loop() + return await loop.run_in_executor( + None, self.save_artifact, artifact, artifact_name + ) + + async def load_artifact_async(self, artifact_name: str) -> Any: + """Load artifact from file asynchronously. + + Args: + artifact_name (str): _description_ + + Returns: + Any: _description_ + """ + loop = asyncio.get_event_loop() + return await loop.run_in_executor( + None, self.load_artifact, artifact_name + ) + + async def log_event_async( + self, + event: str, + event_type: str = "INFO", + ): + """Log event to file asynchronously. + + Args: + event (str): _description_ + event_type (str, optional): _description_. Defaults to "INFO". + """ + loop = asyncio.get_event_loop() + return await loop.run_in_executor( + None, self.log_event, event, event_type + ) + + async def asave_to_file( + self, data: Any, file: str, *args, **kwargs + ): + """Save data to file asynchronously. + + Args: + data (Any): _description_ + file (str): _description_ + """ + await asyncio.to_thread( + self.save_to_file, + data, + file, + *args, + ) + + async def aload_from_file( + self, + file: str, + ) -> Any: + """Async load data from file. + + Args: + file (str): _description_ + + Returns: + Any: _description_ + """ + return await asyncio.to_thread(self.load_from_file, file) + + def run_in_thread(self, *args, **kwargs): + """Run the structure in a thread.""" + with concurrent.futures.ThreadPoolExecutor() as executor: + return executor.submit(self.run, *args, **kwargs) + + def save_metadata_in_thread(self, metadata: Dict[str, Any]): + """Save metadata to file in a thread. + + Args: + metadata (Dict[str, Any]): _description_ + """ + with concurrent.futures.ThreadPoolExecutor() as executor: + return executor.submit(self.save_metadata, metadata) + + def run_concurrent(self, *args, **kwargs): + """Run the structure concurrently.""" + return asyncio.run(self.run_async(*args, **kwargs)) + + def compress_data( + self, + data: Any, + ) -> bytes: + """Compress data. + + Args: + data (Any): _description_ + + Returns: + bytes: _description_ + """ + return gzip.compress(json.dumps(data).encode()) + + def decompres_data(self, data: bytes) -> Any: + """Decompress data. + + Args: + data (bytes): _description_ + + Returns: + Any: _description_ + """ + return json.loads(gzip.decompress(data).decode()) + + def run_batched( + self, + batched_data: List[Any], + batch_size: int = 10, + *args, + **kwargs, + ): + """Run batched data. + + Args: + batched_data (List[Any]): _description_ + batch_size (int, optional): _description_. Defaults to 10. + + Returns: + _type_: _description_ + """ + with ThreadPoolExecutor(max_workers=batch_size) as executor: + futures = [ + executor.submit(self.run, data) + for data in batched_data + ] + return [future.result() for future in futures] + + def load_config( + self, config: str = None, *args, **kwargs + ) -> Dict[str, Any]: + """Load config from file. + + Args: + config (str, optional): _description_. Defaults to None. + + Returns: + Dict[str, Any]: _description_ + """ + return self.load_from_file(config) + + def backup_data( + self, data: Any, backup_path: str = None, *args, **kwargs + ): + """Backup data to file. + + Args: + data (Any): _description_ + backup_path (str, optional): _description_. Defaults to None. + """ + timestamp = self._current_timestamp() + backup_file_path = f"{backup_path}/{timestamp}.json" + self.save_to_file(data, backup_file_path) + + def monitor_resources(self): + """Monitor resource usage.""" + memory = psutil.virtual_memory().percent + cpu_usage = psutil.cpu_percent(interval=1) + self.log_event( + f"Resource usage - Memory: {memory}%, CPU: {cpu_usage}%" + ) + + def run_with_resources(self, *args, **kwargs): + """Run the structure with resource monitoring.""" + self.monitor_resources() + return self.run(*args, **kwargs) + + def run_with_resources_batched( + self, + batched_data: List[Any], + batch_size: int = 10, + *args, + **kwargs, + ): + """Run batched data with resource monitoring. + + Args: + batched_data (List[Any]): _description_ + batch_size (int, optional): _description_. Defaults to 10. + + Returns: + _type_: _description_ + """ + self.monitor_resources() + return self.run_batched( + batched_data, batch_size, *args, **kwargs + ) diff --git a/tests/swarms/test_base.py b/tests/swarms/test_base.py new file mode 100644 index 00000000..5ec21b3f --- /dev/null +++ b/tests/swarms/test_base.py @@ -0,0 +1,259 @@ +import pytest +import os +from datetime import datetime +from swarms.swarms.base import BaseStructure + + +class TestBaseStructure: + def test_init(self): + base_structure = BaseStructure( + name="TestStructure", + description="Test description", + save_metadata=True, + save_artifact_path="./test_artifacts", + save_metadata_path="./test_metadata", + save_error_path="./test_errors", + ) + + assert base_structure.name == "TestStructure" + assert base_structure.description == "Test description" + assert base_structure.save_metadata is True + assert base_structure.save_artifact_path == "./test_artifacts" + assert base_structure.save_metadata_path == "./test_metadata" + assert base_structure.save_error_path == "./test_errors" + + def test_save_to_file_and_load_from_file(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + file_path = os.path.join(tmp_dir, "test_file.json") + + data_to_save = {"key": "value"} + base_structure = BaseStructure() + + base_structure.save_to_file(data_to_save, file_path) + loaded_data = base_structure.load_from_file(file_path) + + assert loaded_data == data_to_save + + def test_save_metadata_and_load_metadata(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + base_structure = BaseStructure(save_metadata_path=tmp_dir) + + metadata = {"name": "Test", "description": "Test metadata"} + base_structure.save_metadata(metadata) + loaded_metadata = base_structure.load_metadata() + + assert loaded_metadata == metadata + + def test_log_error(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + base_structure = BaseStructure(save_error_path=tmp_dir) + + error_message = "Test error message" + base_structure.log_error(error_message) + + log_file = os.path.join(tmp_dir, "TestStructure_errors.log") + with open(log_file, "r") as file: + lines = file.readlines() + assert len(lines) == 1 + assert lines[0] == f"{error_message}\n" + + def test_save_artifact_and_load_artifact(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + base_structure = BaseStructure(save_artifact_path=tmp_dir) + + artifact = {"key": "value"} + artifact_name = "test_artifact" + base_structure.save_artifact(artifact, artifact_name) + loaded_artifact = base_structure.load_artifact(artifact_name) + + assert loaded_artifact == artifact + + def test_current_timestamp(self): + base_structure = BaseStructure() + current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S") + timestamp = base_structure._current_timestamp() + assert timestamp == current_time + + def test_log_event(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + base_structure = BaseStructure(save_metadata_path=tmp_dir) + + event = "Test event" + event_type = "INFO" + base_structure.log_event(event, event_type) + + log_file = os.path.join(tmp_dir, "TestStructure_events.log") + with open(log_file, "r") as file: + lines = file.readlines() + assert len(lines) == 1 + assert lines[0] == f"[{base_structure._current_timestamp()}] [{event_type}] {event}\n" + + @pytest.mark.asyncio + async def test_run_async(self): + base_structure = BaseStructure() + + async def async_function(): + return "Async Test Result" + + result = await base_structure.run_async(async_function) + assert result == "Async Test Result" + + @pytest.mark.asyncio + async def test_save_metadata_async(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + base_structure = BaseStructure(save_metadata_path=tmp_dir) + + metadata = {"name": "Test", "description": "Test metadata"} + await base_structure.save_metadata_async(metadata) + loaded_metadata = base_structure.load_metadata() + + assert loaded_metadata == metadata + + @pytest.mark.asyncio + async def test_log_error_async(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + base_structure = BaseStructure(save_error_path=tmp_dir) + + error_message = "Test error message" + await base_structure.log_error_async(error_message) + + log_file = os.path.join(tmp_dir, "TestStructure_errors.log") + with open(log_file, "r") as file: + lines = file.readlines() + assert len(lines) == 1 + assert lines[0] == f"{error_message}\n" + + @pytest.mark.asyncio + async def test_save_artifact_async(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + base_structure = BaseStructure(save_artifact_path=tmp_dir) + + artifact = {"key": "value"} + artifact_name = "test_artifact" + await base_structure.save_artifact_async(artifact, artifact_name) + loaded_artifact = base_structure.load_artifact(artifact_name) + + assert loaded_artifact == artifact + + @pytest.mark.asyncio + async def test_load_artifact_async(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + base_structure = BaseStructure(save_artifact_path=tmp_dir) + + artifact = {"key": "value"} + artifact_name = "test_artifact" + base_structure.save_artifact(artifact, artifact_name) + loaded_artifact = await base_structure.load_artifact_async(artifact_name) + + assert loaded_artifact == artifact + + @pytest.mark.asyncio + async def test_log_event_async(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + base_structure = BaseStructure(save_metadata_path=tmp_dir) + + event = "Test event" + event_type = "INFO" + await base_structure.log_event_async(event, event_type) + + log_file = os.path.join(tmp_dir, "TestStructure_events.log") + with open(log_file, "r") as file: + lines = file.readlines() + assert len(lines) == 1 + assert lines[0] == f"[{base_structure._current_timestamp()}] [{event_type}] {event}\n" + + @pytest.mark.asyncio + async def test_asave_to_file(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + file_path = os.path.join(tmp_dir, "test_file.json") + data_to_save = {"key": "value"} + base_structure = BaseStructure() + + await base_structure.asave_to_file(data_to_save, file_path) + loaded_data = base_structure.load_from_file(file_path) + + assert loaded_data == data_to_save + + @pytest.mark.asyncio + async def test_aload_from_file(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + file_path = os.path.join(tmp_dir, "test_file.json") + data_to_save = {"key": "value"} + base_structure = BaseStructure() + base_structure.save_to_file(data_to_save, file_path) + + loaded_data = await base_structure.aload_from_file(file_path) + assert loaded_data == data_to_save + + def test_run_in_thread(self): + base_structure = BaseStructure() + result = base_structure.run_in_thread(lambda: "Thread Test Result") + assert result.result() == "Thread Test Result" + + def test_save_and_decompress_data(self): + base_structure = BaseStructure() + data = {"key": "value"} + compressed_data = base_structure.compress_data(data) + decompressed_data = base_structure.decompres_data(compressed_data) + assert decompressed_data == data + + def test_run_batched(self): + base_structure = BaseStructure() + + def run_function(data): + return f"Processed {data}" + + batched_data = list(range(10)) + result = base_structure.run_batched(batched_data, batch_size=5, func=run_function) + + expected_result = [f"Processed {data}" for data in batched_data] + assert result == expected_result + + def test_load_config(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + config_file = os.path.join(tmp_dir, "config.json") + config_data = {"key": "value"} + base_structure = BaseStructure() + + base_structure.save_to_file(config_data, config_file) + loaded_config = base_structure.load_config(config_file) + + assert loaded_config == config_data + + def test_backup_data(self, tmpdir): + tmp_dir = tmpdir.mkdir("test_dir") + base_structure = BaseStructure() + data_to_backup = {"key": "value"} + base_structure.backup_data(data_to_backup, backup_path=tmp_dir) + backup_files = os.listdir(tmp_dir) + + assert len(backup_files) == 1 + loaded_data = base_structure.load_from_file(os.path.join(tmp_dir, backup_files[0])) + assert loaded_data == data_to_backup + + def test_monitor_resources(self): + base_structure = BaseStructure() + base_structure.monitor_resources() + + def test_run_with_resources(self): + base_structure = BaseStructure() + + def run_function(): + base_structure.monitor_resources() + return "Resource Test Result" + + result = base_structure.run_with_resources(run_function) + assert result == "Resource Test Result" + + def test_run_with_resources_batched(self): + base_structure = BaseStructure() + + def run_function(data): + base_structure.monitor_resources() + return f"Processed {data}" + + batched_data = list(range(10)) + result = base_structure.run_with_resources_batched(batched_data, batch_size=5, func=run_function) + + expected_result = [f"Processed {data}" for data in batched_data] + assert result == expected_result From efd2b9b22faee699e3bd68af721caf76b6b04b13 Mon Sep 17 00:00:00 2001 From: Kye Date: Tue, 12 Dec 2023 15:05:59 -0800 Subject: [PATCH 2/6] [V] [README] --- README.md | 110 ++++++++++++++++++ .../multi_modal_chain_of_thought/vcot.py | 0 pyproject.toml | 2 +- 3 files changed, 111 insertions(+), 1 deletion(-) create mode 100644 playground/demos/multi_modal_chain_of_thought/vcot.py diff --git a/README.md b/README.md index f391c937..be68f685 100644 --- a/README.md +++ b/README.md @@ -203,7 +203,117 @@ response = agent.run("Generate a video of a swarm of fish and then make an image print(response) ``` +--- + +### Multi-Agent Swarm for Logistics +- Swarms is a framework designed for real-world deployment here is a demo presenting a fully ready to use Swarm for a vast array of logistics tasks. +- Swarms is designed to be modular and reliable for real-world deployments. +- Swarms is the first framework that unleases multi-modal autonomous agents in the real world. + +```python +from swarms.structs import Agent +import os +from dotenv import load_dotenv +from swarms.models import GPT4VisionAPI +from swarms.prompts.logistics import ( + Health_Security_Agent_Prompt, + Quality_Control_Agent_Prompt, + Productivity_Agent_Prompt, + Safety_Agent_Prompt, + Security_Agent_Prompt, + Sustainability_Agent_Prompt, + Efficiency_Agent_Prompt, +) + +# Load ENV +load_dotenv() +api_key = os.getenv("OPENAI_API_KEY") +# GPT4VisionAPI +llm = GPT4VisionAPI(openai_api_key=api_key) + +# Image for analysis +factory_image = "factory_image1.jpg" + +# Initialize agents with respective prompts +health_security_agent = Agent( + llm=llm, + sop=Health_Security_Agent_Prompt, + max_loops=1, + multi_modal=True, +) + +# Quality control agent +quality_control_agent = Agent( + llm=llm, + sop=Quality_Control_Agent_Prompt, + max_loops=1, + multi_modal=True, +) + + +# Productivity Agent +productivity_agent = Agent( + llm=llm, + sop=Productivity_Agent_Prompt, + max_loops=1, + multi_modal=True, +) + +# Initiailize safety agent +safety_agent = Agent( + llm=llm, sop=Safety_Agent_Prompt, max_loops=1, multi_modal=True +) + +# Init the security agent +security_agent = Agent( + llm=llm, sop=Security_Agent_Prompt, max_loops=1, multi_modal=True +) + + +# Initialize sustainability agent +sustainability_agent = Agent( + llm=llm, + sop=Sustainability_Agent_Prompt, + max_loops=1, + multi_modal=True, +) + + +# Initialize efficincy agent +efficiency_agent = Agent( + llm=llm, + sop=Efficiency_Agent_Prompt, + max_loops=1, + multi_modal=True, +) + +# Run agents with respective tasks on the same image +health_analysis = health_security_agent.run( + "Analyze the safety of this factory", factory_image +) +quality_analysis = quality_control_agent.run( + "Examine product quality in the factory", factory_image +) +productivity_analysis = productivity_agent.run( + "Evaluate factory productivity", factory_image +) +safety_analysis = safety_agent.run( + "Inspect the factory's adherence to safety standards", + factory_image, +) +security_analysis = security_agent.run( + "Assess the factory's security measures and systems", + factory_image, +) +sustainability_analysis = sustainability_agent.run( + "Examine the factory's sustainability practices", factory_image +) +efficiency_analysis = efficiency_agent.run( + "Analyze the efficiency of the factory's manufacturing process", + factory_image, +) +``` --- # Features 🤖 diff --git a/playground/demos/multi_modal_chain_of_thought/vcot.py b/playground/demos/multi_modal_chain_of_thought/vcot.py new file mode 100644 index 00000000..e69de29b diff --git a/pyproject.toml b/pyproject.toml index 4e1c1c7c..c9f620a0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api" [tool.poetry] name = "swarms" -version = "2.7.7" +version = "2.7.8" description = "Swarms - Pytorch" license = "MIT" authors = ["Kye Gomez "] From b1d3aa54a874526e0dfb3808a1d3dee8e675d477 Mon Sep 17 00:00:00 2001 From: Kye Date: Tue, 12 Dec 2023 16:27:07 -0800 Subject: [PATCH 3/6] [REACT Prompt] [FEAT][BaseStructure Tests] [MM-VCOT Agent] --- .../multi_modal_chain_of_thought/eyetest.jpg | Bin 0 -> 75431 bytes .../multi_modal_chain_of_thought/vcot.py | 35 +++++++++++ pyproject.toml | 3 +- swarms/models/gpt4_vision_api.py | 2 + swarms/prompts/react.py | 59 ++++++++++++++++++ swarms/prompts/visual_cot.py | 36 +++++++++++ swarms/structs/agent.py | 20 +++++- swarms/structs/base.py | 1 - swarms/swarms/base.py | 6 +- tests/swarms/test_base.py | 52 +++++++++++---- 10 files changed, 191 insertions(+), 23 deletions(-) create mode 100644 playground/demos/multi_modal_chain_of_thought/eyetest.jpg create mode 100644 swarms/prompts/react.py create mode 100644 swarms/prompts/visual_cot.py diff --git a/playground/demos/multi_modal_chain_of_thought/eyetest.jpg b/playground/demos/multi_modal_chain_of_thought/eyetest.jpg new file mode 100644 index 0000000000000000000000000000000000000000..eaa5dca50b14ca7c87b6dcf8f09d0884c04671e1 GIT binary patch literal 75431 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"] @@ -41,7 +41,6 @@ datasets = "*" optimum = "1.15.0" diffusers = "*" PyPDF2 = "*" -vllm = "*" accelerate = "*" sentencepiece = "*" wget = "*" diff --git a/swarms/models/gpt4_vision_api.py b/swarms/models/gpt4_vision_api.py index 7496cf32..57553bb9 100644 --- a/swarms/models/gpt4_vision_api.py +++ b/swarms/models/gpt4_vision_api.py @@ -161,6 +161,8 @@ class GPT4VisionAPI(BaseMultiModalModel): .get("message", {}) .get("content", None) ) + if self.streaming_enabled: + content = self.stream_response(content) return content else: print("No valid response in 'choices'") diff --git a/swarms/prompts/react.py b/swarms/prompts/react.py new file mode 100644 index 00000000..d4a8aeda --- /dev/null +++ b/swarms/prompts/react.py @@ -0,0 +1,59 @@ + +def react_prompt(task: str = None): + REACT = f""" + Task Description: + Accomplish the following {task} using the reasoning guidelines below. + + + ######### REASONING GUIDELINES ######### + You're an autonomous agent that has been tasked with {task}. You have been given a set of guidelines to follow to accomplish this task. You must follow the guidelines exactly. + + Step 1: Observation + + Begin by carefully observing the situation or problem at hand. Describe what you see, identify key elements, and note any relevant details. + + Use ... tokens to encapsulate your observations. + + Example: + [Describe your initial observations of the task or problem here.] + + Step 2: Thought Process + + Analyze the observations. Consider different angles, potential challenges, and any underlying patterns or connections. + + Think about possible solutions or approaches to address the task. + + Use ... tokens to encapsulate your thinking process. + + Example: + [Explain your analysis of the observations, your reasoning behind potential solutions, and any assumptions or considerations you are making.] + + Step 3: Action Planning + + Based on your thoughts and analysis, plan a series of actions to solve the problem or complete the task. + + Detail the steps you intend to take, resources you will use, and how these actions will address the key elements identified in your observations. + + Use ... tokens to encapsulate your action plan. + + Example: + [List the specific actions you plan to take, including any steps to gather more information or implement a solution.] + + Step 4: Execute and Reflect + + Implement your action plan. As you proceed, continue to observe and think, adjusting your actions as needed. + + Reflect on the effectiveness of your actions and the outcome. Consider what worked well and what could be improved. + + Use ..., ..., and ... tokens as needed to describe this ongoing process. + + Example: + [New observations during action implementation.] + [Thoughts on how the actions are affecting the situation, adjustments needed, etc.] + [Adjusted or continued actions to complete the task.] + + Guidance: + Remember, your goal is to provide a transparent and logical process that leads from observation to effective action. Your responses should demonstrate clear thinking, an understanding of the problem, and a rational approach to solving it. The use of tokens helps to structure your response and clarify the different stages of your reasoning and action. + + """ + return REACT \ No newline at end of file diff --git a/swarms/prompts/visual_cot.py b/swarms/prompts/visual_cot.py new file mode 100644 index 00000000..f33c72e1 --- /dev/null +++ b/swarms/prompts/visual_cot.py @@ -0,0 +1,36 @@ +VISUAL_CHAIN_OF_THOUGHT = """ + +You, as the model, are presented with a visual problem. This could be an image containing various elements that you need to analyze, a graph that requires interpretation, or a visual puzzle. Your task is to examine the visual information carefully and describe your process of understanding and solving the problem. + +Instructions: + +Observation: Begin by describing what you see in the image. Break down the visual elements into understandable segments. For instance, if it's a picture of a street, identify the key components like cars, buildings, people, street signs, etc. If it's a graph, start by outlining its type, the axes, and the data it presents. + +Initial Analysis: Based on your observation, start analyzing the image. If it's a scene, narrate the possible context or the story the image might be telling. If it's a graph or data, begin to interpret what the data might indicate. This step is about forming hypotheses or interpretations based on visual cues. + +Detailed Reasoning: Delve deeper into your analysis. This is where the chain of thought becomes critical. If you're looking at a scene, consider the relationships between elements. Why might that person be running? What does the traffic signal indicate? For graphs or data-driven images, analyze trends, outliers, and correlations. Explain your thought process in a step-by-step manner. + +Visual References: As you explain, make visual references. Draw arrows, circles, or use highlights in the image to pinpoint exactly what you're discussing. These annotations should accompany your verbal reasoning, adding clarity to your explanations. + +Conclusion or Solution: Based on your detailed reasoning, draw a conclusion or propose a solution. If it's a visual puzzle or problem, present your answer clearly, backed by the reasoning you've just outlined. If it’s an open-ended image, summarize your understanding of the scene or the data. + +Reflection: Finally, reflect on your thought process. Was there anything particularly challenging or ambiguous? How confident are you in your interpretation or solution, and why? This step is about self-assessment and providing insight into your reasoning confidence. + +Example: + +Let’s say the image is a complex graph showing climate change data over the last century. + +Observation: "The graph is a line graph with time on the x-axis and average global temperature on the y-axis. There are peaks and troughs, but a general upward trend is visible." + +Initial Analysis: "The immediate observation is that average temperatures have risen over the last century. There are fluctuations, but the overall direction is upward." + +Detailed Reasoning: "Looking closer, the steepest increase appears post-1950. This aligns with industrial advancements globally, suggesting a link between human activity and rising temperatures. The short-term fluctuations could be due to natural climate cycles, but the long-term trend indicates a more worrying, human-induced climate change pattern." + +Visual References: "Here [draws arrow], the graph shows a sharp rise. The annotations indicate major industrial events, aligning with these spikes." + +Conclusion or Solution: "The data strongly suggests a correlation between industrialization and global warming. The upward trend, especially in recent decades, indicates accelerating temperature increases." + +Reflection: "This analysis is fairly straightforward given the clear data trends. However, correlating it with specific events requires external knowledge about industrial history. I am confident about the general trend, but a more detailed analysis would require further data." + + +""" diff --git a/swarms/structs/agent.py b/swarms/structs/agent.py index 1ad6f8ca..5ee2da6a 100644 --- a/swarms/structs/agent.py +++ b/swarms/structs/agent.py @@ -163,7 +163,7 @@ class Agent: id: str = agent_id, llm: Any = None, template: Optional[str] = None, - max_loops=5, + max_loops: int = 1, stopping_condition: Optional[Callable[[str], bool]] = None, loop_interval: int = 1, retry_attempts: int = 3, @@ -194,6 +194,7 @@ class Agent: preset_stopping_token: Optional[bool] = False, traceback: Any = None, traceback_handlers: Any = None, + streaming_on: Optional[bool] = False, *args, **kwargs: Any, ): @@ -236,6 +237,7 @@ class Agent: self.preset_stopping_token = preset_stopping_token self.traceback = traceback self.traceback_handlers = traceback_handlers + self.streaming_on = streaming_on # self.system_prompt = AGENT_SYSTEM_PROMPT_3 @@ -489,7 +491,6 @@ class Agent: Interactive: {self.interactive} Dashboard: {self.dashboard} Dynamic Temperature: {self.dynamic_temperature_enabled} - Temperature: {self.llm.model_kwargs.get('temperature')} Autosave: {self.autosave} Saved State: {self.saved_state_path} Model Configuration: {model_config} @@ -547,6 +548,15 @@ class Agent: print(colored(f"\nLoop {loop_count} of {max_loops}", "cyan")) print("\n") + def streaming(self, content: str = None): + """prints each chunk of content as it is generated + + Args: + content (str, optional): _description_. Defaults to None. + """ + for chunk in content: + print(chunk, end="") + def _history(self, user_name: str, task: str) -> str: """Generate the history for the history prompt @@ -720,7 +730,11 @@ class Agent: raise def _run(self, **kwargs: Any) -> str: - """Generate a result using the provided keyword args.""" + """Run the agent on a task + + Returns: + str: _description_ + """ try: task = self.format_prompt(**kwargs) response, history = self._generate(task, task) diff --git a/swarms/structs/base.py b/swarms/structs/base.py index 9f6da9af..b39a3e8c 100644 --- a/swarms/structs/base.py +++ b/swarms/structs/base.py @@ -15,7 +15,6 @@ except ImportError as error: class BaseStructure(ABC): - def __init__( self, name: Optional[str] = None, diff --git a/swarms/swarms/base.py b/swarms/swarms/base.py index 3a166eac..2f97df6b 100644 --- a/swarms/swarms/base.py +++ b/swarms/swarms/base.py @@ -11,14 +11,10 @@ Paid """ import asyncio -import concurrent.futures -import logging -import time -from abc import ABC, abstractmethod +from abc import ABC from concurrent.futures import ThreadPoolExecutor, as_completed from typing import Any, Callable, Dict, List, Optional -from termcolor import colored from swarms.structs.agent import Agent diff --git a/tests/swarms/test_base.py b/tests/swarms/test_base.py index 5ec21b3f..9641ed7e 100644 --- a/tests/swarms/test_base.py +++ b/tests/swarms/test_base.py @@ -86,7 +86,11 @@ class TestBaseStructure: with open(log_file, "r") as file: lines = file.readlines() assert len(lines) == 1 - assert lines[0] == f"[{base_structure._current_timestamp()}] [{event_type}] {event}\n" + assert ( + lines[0] + == f"[{base_structure._current_timestamp()}]" + f" [{event_type}] {event}\n" + ) @pytest.mark.asyncio async def test_run_async(self): @@ -130,7 +134,9 @@ class TestBaseStructure: artifact = {"key": "value"} artifact_name = "test_artifact" - await base_structure.save_artifact_async(artifact, artifact_name) + await base_structure.save_artifact_async( + artifact, artifact_name + ) loaded_artifact = base_structure.load_artifact(artifact_name) assert loaded_artifact == artifact @@ -143,7 +149,9 @@ class TestBaseStructure: artifact = {"key": "value"} artifact_name = "test_artifact" base_structure.save_artifact(artifact, artifact_name) - loaded_artifact = await base_structure.load_artifact_async(artifact_name) + loaded_artifact = await base_structure.load_artifact_async( + artifact_name + ) assert loaded_artifact == artifact @@ -160,7 +168,11 @@ class TestBaseStructure: with open(log_file, "r") as file: lines = file.readlines() assert len(lines) == 1 - assert lines[0] == f"[{base_structure._current_timestamp()}] [{event_type}] {event}\n" + assert ( + lines[0] + == f"[{base_structure._current_timestamp()}]" + f" [{event_type}] {event}\n" + ) @pytest.mark.asyncio async def test_asave_to_file(self, tmpdir): @@ -187,14 +199,18 @@ class TestBaseStructure: def test_run_in_thread(self): base_structure = BaseStructure() - result = base_structure.run_in_thread(lambda: "Thread Test Result") + result = base_structure.run_in_thread( + lambda: "Thread Test Result" + ) assert result.result() == "Thread Test Result" def test_save_and_decompress_data(self): base_structure = BaseStructure() data = {"key": "value"} compressed_data = base_structure.compress_data(data) - decompressed_data = base_structure.decompres_data(compressed_data) + decompressed_data = base_structure.decompres_data( + compressed_data + ) assert decompressed_data == data def test_run_batched(self): @@ -204,9 +220,13 @@ class TestBaseStructure: return f"Processed {data}" batched_data = list(range(10)) - result = base_structure.run_batched(batched_data, batch_size=5, func=run_function) + result = base_structure.run_batched( + batched_data, batch_size=5, func=run_function + ) - expected_result = [f"Processed {data}" for data in batched_data] + expected_result = [ + f"Processed {data}" for data in batched_data + ] assert result == expected_result def test_load_config(self, tmpdir): @@ -224,11 +244,15 @@ class TestBaseStructure: tmp_dir = tmpdir.mkdir("test_dir") base_structure = BaseStructure() data_to_backup = {"key": "value"} - base_structure.backup_data(data_to_backup, backup_path=tmp_dir) + base_structure.backup_data( + data_to_backup, backup_path=tmp_dir + ) backup_files = os.listdir(tmp_dir) assert len(backup_files) == 1 - loaded_data = base_structure.load_from_file(os.path.join(tmp_dir, backup_files[0])) + loaded_data = base_structure.load_from_file( + os.path.join(tmp_dir, backup_files[0]) + ) assert loaded_data == data_to_backup def test_monitor_resources(self): @@ -253,7 +277,11 @@ class TestBaseStructure: return f"Processed {data}" batched_data = list(range(10)) - result = base_structure.run_with_resources_batched(batched_data, batch_size=5, func=run_function) + result = base_structure.run_with_resources_batched( + batched_data, batch_size=5, func=run_function + ) - expected_result = [f"Processed {data}" for data in batched_data] + expected_result = [ + f"Processed {data}" for data in batched_data + ] assert result == expected_result From 4bef09a252618f3802166d505de4f846094349d1 Mon Sep 17 00:00:00 2001 From: Kye Date: Tue, 12 Dec 2023 16:49:46 -0800 Subject: [PATCH 4/6] [FEAT][TogertherModel] --- pyproject.toml | 2 +- swarms/models/together.py | 140 ++++++++++++++++++++++++++++++++++ swarms/prompts/react.py | 5 +- tests/models/test_togther.py | 144 +++++++++++++++++++++++++++++++++++ 4 files changed, 287 insertions(+), 4 deletions(-) create mode 100644 swarms/models/together.py create mode 100644 tests/models/test_togther.py diff --git a/pyproject.toml b/pyproject.toml index 8c53e85d..693ede3a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api" [tool.poetry] name = "swarms" -version = "2.7.9" +version = "2.8.0" description = "Swarms - Pytorch" license = "MIT" authors = ["Kye Gomez "] diff --git a/swarms/models/together.py b/swarms/models/together.py new file mode 100644 index 00000000..88949a5c --- /dev/null +++ b/swarms/models/together.py @@ -0,0 +1,140 @@ +import logging +import os +from typing import Optional + +import requests +from dotenv import load_dotenv + +from swarms.models.base_llm import AbstractLLM + +# Load environment variables +load_dotenv() + + +def together_api_key_env(): + """Get the API key from the environment.""" + return os.getenv("TOGETHER_API_KEY") + + +class TogetherModel(AbstractLLM): + """ + GPT-4 Vision API + + This class is a wrapper for the OpenAI API. It is used to run the GPT-4 Vision model. + + Parameters + ---------- + together_api_key : str + The OpenAI API key. Defaults to the together_api_key environment variable. + max_tokens : int + The maximum number of tokens to generate. Defaults to 300. + + + Methods + ------- + encode_image(img: str) + Encode image to base64. + run(task: str, img: str) + Run the model. + __call__(task: str, img: str) + Run the model. + + Examples: + --------- + >>> from swarms.models import GPT4VisionAPI + >>> llm = GPT4VisionAPI() + >>> task = "What is the color of the object?" + >>> img = "https://i.imgur.com/2M2ZGwC.jpeg" + >>> llm.run(task, img) + + + """ + + def __init__( + self, + together_api_key: str = together_api_key_env, + model_name: str = "mistralai/Mixtral-8x7B-Instruct-v0.1", + logging_enabled: bool = False, + max_workers: int = 10, + max_tokens: str = 300, + api_endpoint: str = "https://api.together.xyz", + beautify: bool = False, + streaming_enabled: Optional[bool] = False, + meta_prompt: Optional[bool] = False, + system_prompt: Optional[str] = None, + *args, + **kwargs, + ): + super(TogetherModel).__init__(*args, **kwargs) + self.together_api_key = together_api_key + self.logging_enabled = logging_enabled + self.model_name = model_name + self.max_workers = max_workers + self.max_tokens = max_tokens + self.api_endpoint = api_endpoint + self.beautify = beautify + self.streaming_enabled = streaming_enabled + self.meta_prompt = meta_prompt + self.system_prompt = system_prompt + + if self.logging_enabled: + logging.basicConfig(level=logging.DEBUG) + else: + # Disable debug logs for requests and urllib3 + logging.getLogger("requests").setLevel(logging.WARNING) + logging.getLogger("urllib3").setLevel(logging.WARNING) + + if self.meta_prompt: + self.system_prompt = self.meta_prompt_init() + + # Function to handle vision tasks + def run(self, task: str = None, *args, **kwargs): + """Run the model.""" + try: + headers = { + "Content-Type": "application/json", + "Authorization": f"Bearer {self.together_api_key}", + } + payload = { + "model": self.model_name, + "messages": [ + { + "role": "system", + "content": [self.system_prompt], + }, + { + "role": "user", + "content": task, + }, + ], + "max_tokens": self.max_tokens, + **kwargs, + } + response = requests.post( + self.api_endpoint, + headers=headers, + json=payload, + *args, + **kwargs, + ) + + out = response.json() + if "choices" in out and out["choices"]: + content = ( + out["choices"][0] + .get("message", {}) + .get("content", None) + ) + if self.streaming_enabled: + content = self.stream_response(content) + return content + else: + print("No valid response in 'choices'") + return None + + except Exception as error: + print( + f"Error with the request: {error}, make sure you" + " double check input types and positions" + ) + return None diff --git a/swarms/prompts/react.py b/swarms/prompts/react.py index d4a8aeda..33dc8575 100644 --- a/swarms/prompts/react.py +++ b/swarms/prompts/react.py @@ -1,6 +1,5 @@ - def react_prompt(task: str = None): - REACT = f""" + PROMPT = f""" Task Description: Accomplish the following {task} using the reasoning guidelines below. @@ -56,4 +55,4 @@ def react_prompt(task: str = None): Remember, your goal is to provide a transparent and logical process that leads from observation to effective action. Your responses should demonstrate clear thinking, an understanding of the problem, and a rational approach to solving it. The use of tokens helps to structure your response and clarify the different stages of your reasoning and action. """ - return REACT \ No newline at end of file + return PROMPT diff --git a/tests/models/test_togther.py b/tests/models/test_togther.py new file mode 100644 index 00000000..75313a45 --- /dev/null +++ b/tests/models/test_togther.py @@ -0,0 +1,144 @@ +import os +import requests +import pytest +from unittest.mock import patch, Mock +from swarms.models.together import TogetherModel +import logging + + +@pytest.fixture +def mock_api_key(monkeypatch): + monkeypatch.setenv("TOGETHER_API_KEY", "mocked-api-key") + + +def test_init_defaults(): + model = TogetherModel() + assert model.together_api_key == "mocked-api-key" + assert model.logging_enabled is False + assert model.model_name == "mistralai/Mixtral-8x7B-Instruct-v0.1" + assert model.max_workers == 10 + assert model.max_tokens == 300 + assert model.api_endpoint == "https://api.together.xyz" + assert model.beautify is False + assert model.streaming_enabled is False + assert model.meta_prompt is False + assert model.system_prompt is None + + +def test_init_custom_params(mock_api_key): + model = TogetherModel( + together_api_key="custom-api-key", + logging_enabled=True, + model_name="custom-model", + max_workers=5, + max_tokens=500, + api_endpoint="https://custom-api.together.xyz", + beautify=True, + streaming_enabled=True, + meta_prompt="meta-prompt", + system_prompt="system-prompt", + ) + assert model.together_api_key == "custom-api-key" + assert model.logging_enabled is True + assert model.model_name == "custom-model" + assert model.max_workers == 5 + assert model.max_tokens == 500 + assert model.api_endpoint == "https://custom-api.together.xyz" + assert model.beautify is True + assert model.streaming_enabled is True + assert model.meta_prompt == "meta-prompt" + assert model.system_prompt == "system-prompt" + + +@patch("swarms.models.together_model.requests.post") +def test_run_success(mock_post, mock_api_key): + mock_response = Mock() + mock_response.json.return_value = { + "choices": [{"message": {"content": "Generated response"}}] + } + mock_post.return_value = mock_response + + model = TogetherModel() + task = "What is the color of the object?" + response = model.run(task) + + assert response == "Generated response" + + +@patch("swarms.models.together_model.requests.post") +def test_run_failure(mock_post, mock_api_key): + mock_post.side_effect = requests.exceptions.RequestException( + "Request failed" + ) + + model = TogetherModel() + task = "What is the color of the object?" + response = model.run(task) + + assert response is None + + +def test_run_with_logging_enabled(caplog, mock_api_key): + model = TogetherModel(logging_enabled=True) + task = "What is the color of the object?" + + with caplog.at_level(logging.DEBUG): + model.run(task) + + assert "Sending request to" in caplog.text + + +@pytest.mark.parametrize( + "invalid_input", [None, 123, ["list", "of", "items"]] +) +def test_invalid_task_input(invalid_input, mock_api_key): + model = TogetherModel() + response = model.run(invalid_input) + + assert response is None + + +@patch("swarms.models.together_model.requests.post") +def test_run_streaming_enabled(mock_post, mock_api_key): + mock_response = Mock() + mock_response.json.return_value = { + "choices": [{"message": {"content": "Generated response"}}] + } + mock_post.return_value = mock_response + + model = TogetherModel(streaming_enabled=True) + task = "What is the color of the object?" + response = model.run(task) + + assert response == "Generated response" + + +@patch("swarms.models.together_model.requests.post") +def test_run_empty_choices(mock_post, mock_api_key): + mock_response = Mock() + mock_response.json.return_value = {"choices": []} + mock_post.return_value = mock_response + + model = TogetherModel() + task = "What is the color of the object?" + response = model.run(task) + + assert response is None + + +@patch("swarms.models.together_model.requests.post") +def test_run_with_exception(mock_post, mock_api_key): + mock_post.side_effect = Exception("Test exception") + + model = TogetherModel() + task = "What is the color of the object?" + response = model.run(task) + + assert response is None + + +def test_init_logging_disabled(monkeypatch): + monkeypatch.setenv("TOGETHER_API_KEY", "mocked-api-key") + model = TogetherModel() + assert model.logging_enabled is False + assert not model.system_prompt From 79d8f149b78e22f4743ce229e13c5a5cce4c2812 Mon Sep 17 00:00:00 2001 From: Kye Date: Tue, 12 Dec 2023 23:15:51 -0800 Subject: [PATCH 5/6] [Idefics -> BaseMultiModalModel] [Vilt => BaseMultiModalModel] --- swarms/models/idefics.py | 8 +++++-- swarms/models/openai_tts.py | 2 ++ swarms/models/vilt.py | 24 ++++++++++++------- swarms/structs/base.py | 46 +++++++++++++++++++++++++++++++++++++ 4 files changed, 70 insertions(+), 10 deletions(-) diff --git a/swarms/models/idefics.py b/swarms/models/idefics.py index 70a16622..b014fbce 100644 --- a/swarms/models/idefics.py +++ b/swarms/models/idefics.py @@ -102,9 +102,13 @@ class Idefics(BaseMultiModalModel): model_name, torch_dtype=torch_dtype, *args, **kwargs ).to(self.device) - self.processor = AutoProcessor.from_pretrained(model_name) + self.processor = AutoProcessor.from_pretrained( + model_name, *args, **kwargs + ) - def run(self, task: str, *args, **kwargs) -> str: + def run( + self, task: str = None, img: str = None, *args, **kwargs + ) -> str: """ Generates text based on the provided prompts. diff --git a/swarms/models/openai_tts.py b/swarms/models/openai_tts.py index e2746eb2..ed19a8d3 100644 --- a/swarms/models/openai_tts.py +++ b/swarms/models/openai_tts.py @@ -61,6 +61,8 @@ class OpenAITTS(AbstractLLM): chunk_size=1024 * 1024, autosave: bool = False, saved_filepath: str = None, + *args, + **kwargs, ): super().__init__() self.model_name = model_name diff --git a/swarms/models/vilt.py b/swarms/models/vilt.py index f95d265c..60425e52 100644 --- a/swarms/models/vilt.py +++ b/swarms/models/vilt.py @@ -1,9 +1,11 @@ -from transformers import ViltProcessor, ViltForQuestionAnswering import requests from PIL import Image +from transformers import ViltForQuestionAnswering, ViltProcessor +from swarms.models.base_multimodal_model import BaseMultiModalModel -class Vilt: + +class Vilt(BaseMultiModalModel): """ Vision-and-Language Transformer (ViLT) model fine-tuned on VQAv2. It was introduced in the paper ViLT: Vision-and-Language Transformer Without @@ -21,15 +23,21 @@ class Vilt: """ - def __init__(self): + def __init__( + self, + model_name: str = "dandelin/vilt-b32-finetuned-vqa", + *args, + **kwargs, + ): + super().__init__(model_name, *args, **kwargs) self.processor = ViltProcessor.from_pretrained( - "dandelin/vilt-b32-finetuned-vqa" + model_name, *args, **kwargs ) self.model = ViltForQuestionAnswering.from_pretrained( - "dandelin/vilt-b32-finetuned-vqa" + model_name, *args, **kwargs ) - def __call__(self, text: str, image_url: str): + def run(self, task: str = None, img: str = None, *args, **kwargs): """ Run the model @@ -38,9 +46,9 @@ class Vilt: """ # Download the image - image = Image.open(requests.get(image_url, stream=True).raw) + image = Image.open(requests.get(img, stream=True).raw) - encoding = self.processor(image, text, return_tensors="pt") + encoding = self.processor(image, task, return_tensors="pt") # Forward pass outputs = self.model(**encoding) diff --git a/swarms/structs/base.py b/swarms/structs/base.py index b39a3e8c..e32b0b48 100644 --- a/swarms/structs/base.py +++ b/swarms/structs/base.py @@ -15,6 +15,52 @@ except ImportError as error: class BaseStructure(ABC): + """Base structure. + + + Attributes: + name (Optional[str]): _description_ + description (Optional[str]): _description_ + save_metadata (bool): _description_ + save_artifact_path (Optional[str]): _description_ + save_metadata_path (Optional[str]): _description_ + save_error_path (Optional[str]): _description_ + + Methods: + run: _description_ + save_to_file: _description_ + load_from_file: _description_ + save_metadata: _description_ + load_metadata: _description_ + log_error: _description_ + save_artifact: _description_ + load_artifact: _description_ + log_event: _description_ + run_async: _description_ + save_metadata_async: _description_ + load_metadata_async: _description_ + log_error_async: _description_ + save_artifact_async: _description_ + load_artifact_async: _description_ + log_event_async: _description_ + asave_to_file: _description_ + aload_from_file: _description_ + run_in_thread: _description_ + save_metadata_in_thread: _description_ + run_concurrent: _description_ + compress_data: _description_ + decompres_data: _description_ + run_batched: _description_ + load_config: _description_ + backup_data: _description_ + monitor_resources: _description_ + run_with_resources: _description_ + run_with_resources_batched: _description_ + + Examples: + + """ + def __init__( self, name: Optional[str] = None, From 4ece24851ff9dc48c0290100436a40ebcb243422 Mon Sep 17 00:00:00 2001 From: Kye Date: Wed, 13 Dec 2023 01:04:01 -0800 Subject: [PATCH 6/6] [GEMINI][FEAT][TESTS][DOCS] --- docs/swarms/models/gemini.md | 180 +++++++++++++++++++++++++++++ pyproject.toml | 2 +- swarms/models/gemini.py | 160 +++++++++++++++++++++++++ tests/models/test_gemini.py | 218 +++++++++++++++++++++++++++++++++++ 4 files changed, 559 insertions(+), 1 deletion(-) create mode 100644 docs/swarms/models/gemini.md create mode 100644 swarms/models/gemini.py create mode 100644 tests/models/test_gemini.py diff --git a/docs/swarms/models/gemini.md b/docs/swarms/models/gemini.md new file mode 100644 index 00000000..3c2c35b7 --- /dev/null +++ b/docs/swarms/models/gemini.md @@ -0,0 +1,180 @@ +## `Gemini` Documentation + +### Introduction + +The Gemini module is a versatile tool for leveraging the power of multimodal AI models to generate content. It allows users to combine textual and image inputs to generate creative and informative outputs. In this documentation, we will explore the Gemini module in detail, covering its purpose, architecture, methods, and usage examples. + +#### Purpose + +The Gemini module is designed to bridge the gap between text and image data, enabling users to harness the capabilities of multimodal AI models effectively. By providing both a textual task and an image as input, Gemini generates content that aligns with the specified task and incorporates the visual information from the image. + +### Installation + +Before using Gemini, ensure that you have the required dependencies installed. You can install them using the following commands: + +```bash +pip install swarms +pip install google-generativeai +pip install python-dotenv +``` + +### Class: Gemini + +#### Overview + +The `Gemini` class is the central component of the Gemini module. It inherits from the `BaseMultiModalModel` class and provides methods to interact with the Gemini AI model. Let's dive into its architecture and functionality. + +##### Class Constructor + +```python +class Gemini(BaseMultiModalModel): + def __init__( + self, + model_name: str = "gemini-pro", + gemini_api_key: str = get_gemini_api_key_env, + *args, + **kwargs, + ): +``` + +| Parameter | Type | Description | Default Value | +|---------------------|---------|------------------------------------------------------------------|--------------------| +| `model_name` | str | The name of the Gemini model. | "gemini-pro" | +| `gemini_api_key` | str | The Gemini API key. If not provided, it is fetched from the environment. | (None) | + +- `model_name`: Specifies the name of the Gemini model to use. By default, it is set to "gemini-pro," but you can specify a different model if needed. + +- `gemini_api_key`: This parameter allows you to provide your Gemini API key directly. If not provided, the constructor attempts to fetch it from the environment using the `get_gemini_api_key_env` helper function. + +##### Methods + +1. **run()** + + ```python + def run( + self, + task: str = None, + img: str = None, + *args, + **kwargs, + ) -> str: + ``` + + | Parameter | Type | Description | + |---------------|----------|--------------------------------------------| + | `task` | str | The textual task for content generation. | + | `img` | str | The path to the image to be processed. | + | `*args` | Variable | Additional positional arguments. | + | `**kwargs` | Variable | Additional keyword arguments. | + + - `task`: Specifies the textual task for content generation. It can be a sentence or a phrase that describes the desired content. + + - `img`: Provides the path to the image that will be processed along with the textual task. Gemini combines the visual information from the image with the textual task to generate content. + + - `*args` and `**kwargs`: Allow for additional, flexible arguments that can be passed to the underlying Gemini model. These arguments can vary based on the specific Gemini model being used. + + **Returns**: A string containing the generated content. + + **Examples**: + + ```python + from swarms.models import Gemini + + # Initialize the Gemini model + gemini = Gemini() + + # Generate content for a textual task with an image + generated_content = gemini.run( + task="Describe this image", + img="image.jpg", + ) + + # Print the generated content + print(generated_content) + ``` + + In this example, we initialize the Gemini model, provide a textual task, and specify an image for processing. The `run()` method generates content based on the input and returns the result. + +2. **process_img()** + + ```python + def process_img( + self, + img: str = None, + type: str = "image/png", + *args, + **kwargs, + ): + ``` + + | Parameter | Type | Description | Default Value | + |---------------|----------|------------------------------------------------------|----------------| + | `img` | str | The path to the image to be processed. | (None) | + | `type` | str | The MIME type of the image (e.g., "image/png"). | "image/png" | + | `*args` | Variable | Additional positional arguments. | + | `**kwargs` | Variable | Additional keyword arguments. | + + - `img`: Specifies the path to the image that will be processed. It's essential to provide a valid image path for image-based content generation. + + - `type`: Indicates the MIME type of the image. By default, it is set to "image/png," but you can change it based on the image format you're using. + + - `*args` and `**kwargs`: Allow for additional, flexible arguments that can be passed to the underlying Gemini model. These arguments can vary based on the specific Gemini model being used. + + **Raises**: ValueError if any of the following conditions are met: + - No image is provided. + - The image type is not specified. + - The Gemini API key is missing. + + **Examples**: + + ```python + from swarms.models.gemini import Gemini + + # Initialize the Gemini model + gemini = Gemini() + + # Process an image + processed_image = gemini.process_img( + img="image.jpg", + type="image/jpeg", + ) + + # Further use the processed image in content generation + generated_content = gemini.run( + task="Describe this image", + img=processed_image, + ) + + # Print the generated content + print(generated_content) + ``` + + In this example, we demonstrate how to process an image using the `process_img()` method and then use the processed image in content generation. + +#### Additional Information + +- Gemini is designed to work seamlessly with various multimodal AI models, making it a powerful tool for content generation tasks. + +- The module uses the `google.generativeai` package to access the underlying AI models. Ensure that you have this package installed to leverage the full capabilities of Gemini. + +- It's essential to provide a valid Gemini API key for authentication. You can either pass it directly during initialization or store it in the environment variable "GEMINI_API_KEY." + +- Gemini's flexibility allows you to experiment with different Gemini models and tailor the content generation process to your specific needs. + +- Keep in mind that Gemini is designed to handle both textual and image inputs, making it a valuable asset for various applications, including natural language processing and computer vision tasks. + +- If you encounter any issues or have specific requirements, refer to the Gemini documentation for more details and advanced usage. + +### References and Resources + +- [Gemini GitHub Repository](https://github.com/swarms/gemini): Explore the Gemini repository for additional information, updates, and examples. + +- [Google GenerativeAI + + Documentation](https://docs.google.com/document/d/1WZSBw6GsOhOCYm0ArydD_9uy6nPPA1KFIbKPhjj43hA): Dive deeper into the capabilities of the Google GenerativeAI package used by Gemini. + +- [Gemini API Documentation](https://gemini-api-docs.example.com): Access the official documentation for the Gemini API to explore advanced features and integrations. + +## Conclusion + +In this comprehensive documentation, we've explored the Gemini module, its purpose, architecture, methods, and usage examples. Gemini empowers developers to generate content by combining textual tasks and images, making it a valuable asset for multimodal AI applications. Whether you're working on natural language processing or computer vision projects, Gemini can help you achieve impressive results. \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 693ede3a..ef30e3c4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -29,7 +29,7 @@ openai = "0.28.0" langchain = "*" asyncio = "*" einops = "*" -google-generativeai = "*" +google-generativeai = "0.3.0" langchain-experimental = "*" playwright = "*" weaviate-client = "*" diff --git a/swarms/models/gemini.py b/swarms/models/gemini.py new file mode 100644 index 00000000..9a052bb2 --- /dev/null +++ b/swarms/models/gemini.py @@ -0,0 +1,160 @@ +import os +import subprocess as sp +from pathlib import Path + +from dotenv import load_dotenv + +from swarms.models.base_multimodal_model import BaseMultiModalModel + +try: + import google.generativeai as genai +except ImportError as error: + print(f"Error importing google.generativeai: {error}") + print("Please install the google.generativeai package") + print("pip install google-generativeai") + sp.run(["pip", "install", "--upgrade", "google-generativeai"]) + + +load_dotenv() + + +# Helpers +def get_gemini_api_key_env(): + """Get the Gemini API key from the environment + + Raises: + ValueError: _description_ + + Returns: + _type_: _description_ + """ + key = os.getenv("GEMINI_API_KEY") + if key is None: + raise ValueError("Please provide a Gemini API key") + return key + + +# Main class +class Gemini(BaseMultiModalModel): + """Gemini model + + Args: + BaseMultiModalModel (class): Base multimodal model class + model_name (str, optional): model name. Defaults to "gemini-pro". + gemini_api_key (str, optional): Gemini API key. Defaults to None. + + Methods: + run: run the Gemini model + process_img: process the image + + + Examples: + >>> from swarms.models import Gemini + >>> gemini = Gemini() + >>> gemini.run( + task="A dog", + img="dog.png", + ) + """ + + def __init__( + self, + model_name: str = "gemini-pro", + gemini_api_key: str = get_gemini_api_key_env, + *args, + **kwargs, + ): + super().__init__(model_name, *args, **kwargs) + self.model_name = model_name + self.gemini_api_key = gemini_api_key + + # Initialize the model + self.model = genai.GenerativeModel( + model_name, *args, **kwargs + ) + + def run( + self, + task: str = None, + img: str = None, + *args, + **kwargs, + ) -> str: + """Run the Gemini model + + Args: + task (str, optional): textual task. Defaults to None. + img (str, optional): img. Defaults to None. + + Returns: + str: output from the model + """ + try: + if img: + process_img = self.process_img(img, *args, **kwargs) + response = self.model.generate_content( + content=[task, process_img], *args, **kwargs + ) + return response.text + else: + response = self.model.generate_content( + task, *args, **kwargs + ) + return response + except Exception as error: + print(f"Error running Gemini model: {error}") + + def process_img( + self, + img: str = None, + type: str = "image/png", + *args, + **kwargs, + ): + """Process the image + + Args: + img (str, optional): _description_. Defaults to None. + type (str, optional): _description_. Defaults to "image/png". + + Raises: + ValueError: _description_ + ValueError: _description_ + ValueError: _description_ + """ + try: + if img is None: + raise ValueError("Please provide an image to process") + if type is None: + raise ValueError("Please provide the image type") + if self.gemini_api_key is None: + raise ValueError("Please provide a Gemini API key") + + # Load the image + img = [ + {"mime_type": type, "data": Path(img).read_bytes()} + ] + except Exception as error: + print(f"Error processing image: {error}") + + def chat( + self, + task: str = None, + img: str = None, + *args, + **kwargs, + ) -> str: + """Chat with the Gemini model + + Args: + task (str, optional): _description_. Defaults to None. + img (str, optional): _description_. Defaults to None. + + Returns: + str: _description_ + """ + chat = self.model.start_chat() + response = chat.send_message(task, *args, **kwargs) + response1 = response.text + print(response1) + response = chat.send_message(img, *args, **kwargs) diff --git a/tests/models/test_gemini.py b/tests/models/test_gemini.py new file mode 100644 index 00000000..bbde19cb --- /dev/null +++ b/tests/models/test_gemini.py @@ -0,0 +1,218 @@ +import pytest +from unittest.mock import patch, Mock +from swarms.models.gemini import Gemini + + +# Define test fixtures +@pytest.fixture +def mock_gemini_api_key(monkeypatch): + monkeypatch.setenv("GEMINI_API_KEY", "mocked-api-key") + + +@pytest.fixture +def mock_genai_model(): + return Mock() + + +# Test initialization of Gemini +def test_gemini_init_defaults(mock_gemini_api_key, mock_genai_model): + model = Gemini() + assert model.model_name == "gemini-pro" + assert model.gemini_api_key == "mocked-api-key" + assert model.model is mock_genai_model + + +def test_gemini_init_custom_params( + mock_gemini_api_key, mock_genai_model +): + model = Gemini( + model_name="custom-model", gemini_api_key="custom-api-key" + ) + assert model.model_name == "custom-model" + assert model.gemini_api_key == "custom-api-key" + assert model.model is mock_genai_model + + +# Test Gemini run method +@patch("swarms.models.gemini.Gemini.process_img") +@patch("swarms.models.gemini.genai.GenerativeModel.generate_content") +def test_gemini_run_with_img( + mock_generate_content, + mock_process_img, + mock_gemini_api_key, + mock_genai_model, +): + model = Gemini() + task = "A cat" + img = "cat.png" + response_mock = Mock(text="Generated response") + mock_generate_content.return_value = response_mock + mock_process_img.return_value = "Processed image" + + response = model.run(task=task, img=img) + + assert response == "Generated response" + mock_generate_content.assert_called_with( + content=[task, "Processed image"] + ) + mock_process_img.assert_called_with(img=img) + + +@patch("swarms.models.gemini.genai.GenerativeModel.generate_content") +def test_gemini_run_without_img( + mock_generate_content, mock_gemini_api_key, mock_genai_model +): + model = Gemini() + task = "A cat" + response_mock = Mock(text="Generated response") + mock_generate_content.return_value = response_mock + + response = model.run(task=task) + + assert response == "Generated response" + mock_generate_content.assert_called_with(task=task) + + +@patch("swarms.models.gemini.genai.GenerativeModel.generate_content") +def test_gemini_run_exception( + mock_generate_content, mock_gemini_api_key, mock_genai_model +): + model = Gemini() + task = "A cat" + mock_generate_content.side_effect = Exception("Test exception") + + response = model.run(task=task) + + assert response is None + + +# Test Gemini process_img method +def test_gemini_process_img(mock_gemini_api_key, mock_genai_model): + model = Gemini(gemini_api_key="custom-api-key") + img = "cat.png" + img_data = b"Mocked image data" + + with patch("builtins.open", create=True) as open_mock: + open_mock.return_value.__enter__.return_value.read.return_value = ( + img_data + ) + + processed_img = model.process_img(img) + + assert processed_img == [ + {"mime_type": "image/png", "data": img_data} + ] + open_mock.assert_called_with(img, "rb") + + +# Test Gemini initialization with missing API key +def test_gemini_init_missing_api_key(): + with pytest.raises( + ValueError, match="Please provide a Gemini API key" + ): + model = Gemini(gemini_api_key=None) + + +# Test Gemini initialization with missing model name +def test_gemini_init_missing_model_name(): + with pytest.raises( + ValueError, match="Please provide a model name" + ): + model = Gemini(model_name=None) + + +# Test Gemini run method with empty task +def test_gemini_run_empty_task(mock_gemini_api_key, mock_genai_model): + model = Gemini() + task = "" + response = model.run(task=task) + assert response is None + + +# Test Gemini run method with empty image +def test_gemini_run_empty_img(mock_gemini_api_key, mock_genai_model): + model = Gemini() + task = "A cat" + img = "" + response = model.run(task=task, img=img) + assert response is None + + +# Test Gemini process_img method with missing image +def test_gemini_process_img_missing_image( + mock_gemini_api_key, mock_genai_model +): + model = Gemini() + img = None + with pytest.raises( + ValueError, match="Please provide an image to process" + ): + model.process_img(img=img) + + +# Test Gemini process_img method with missing image type +def test_gemini_process_img_missing_image_type( + mock_gemini_api_key, mock_genai_model +): + model = Gemini() + img = "cat.png" + with pytest.raises( + ValueError, match="Please provide the image type" + ): + model.process_img(img=img, type=None) + + +# Test Gemini process_img method with missing Gemini API key +def test_gemini_process_img_missing_api_key(mock_genai_model): + model = Gemini(gemini_api_key=None) + img = "cat.png" + with pytest.raises( + ValueError, match="Please provide a Gemini API key" + ): + model.process_img(img=img, type="image/png") + + +# Test Gemini run method with mocked image processing +@patch("swarms.models.gemini.genai.GenerativeModel.generate_content") +@patch("swarms.models.gemini.Gemini.process_img") +def test_gemini_run_mock_img_processing( + mock_process_img, + mock_generate_content, + mock_gemini_api_key, + mock_genai_model, +): + model = Gemini() + task = "A cat" + img = "cat.png" + response_mock = Mock(text="Generated response") + mock_generate_content.return_value = response_mock + mock_process_img.return_value = "Processed image" + + response = model.run(task=task, img=img) + + assert response == "Generated response" + mock_generate_content.assert_called_with( + content=[task, "Processed image"] + ) + mock_process_img.assert_called_with(img=img) + + +# Test Gemini run method with mocked image processing and exception +@patch("swarms.models.gemini.Gemini.process_img") +@patch("swarms.models.gemini.genai.GenerativeModel.generate_content") +def test_gemini_run_mock_img_processing_exception( + mock_generate_content, + mock_process_img, + mock_gemini_api_key, + mock_genai_model, +): + model = Gemini() + task = "A cat" + img = "cat.png" + mock_process_img.side_effect = Exception("Test exception") + + response = model.run(task=task, img=img) + + assert response is None + mock_generate_content.assert_not_called() + mock_process_img.assert_called_with(img=img)