Upload IsoPro Package

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,3 +1,276 @@
----
-license: apache-2.0
----
+# ISOPro: Pro Tools for Intelligent Simulation Orchestration for Large Language Models
+
+ISOPRO is a powerful and flexible Python package designed for creating, managing, and analyzing simulations involving Large Language Models (LLMs). It provides a comprehensive suite of tools for reinforcement learning, conversation simulations, adversarial testing, custom environment creation, and advanced orchestration of multi-agent systems.
+
+## Features
+
+- **Custom Environment Creation**: Easily create and manage custom simulation environments for LLMs
+- **Conversation Simulation**: Simulate and analyze conversations with AI agents using various user personas
+- **Adversarial Testing**: Conduct adversarial simulations to test the robustness of LLM-based systems
+- **Reinforcement Learning**: Implement and experiment with RL algorithms in LLM contexts
+- **Workflow Automation**: Learn and replicate UI workflows from video demonstrations
+- **Car Environment Simulation**: Train and evaluate RL agents in driving scenarios
+- **Utility Functions**: Analyze simulation results, calculate LLM metrics, and more
+- **Flexible Integration**: Works with popular LLM platforms like OpenAI's GPT models, Claude (Anthropic), and Hugging Face models
+- **Orchestration Simulation**: Manage and execute complex multi-agent simulations with different execution modes
+
+## Installation
+
+You can install isopro using pip:
+
+```bash
+pip install isopro
+```
+
+For workflow simulation features, ensure you have the required dependencies:
+
+```bash
+pip install opencv-python numpy torch stable-baselines3 gymnasium tqdm
+```
+
+If you plan to use Claude capabilities:
+
+```bash
+export ANTHROPIC_API_KEY=your_api_key_here
+```
+
+## Usage
+
+### Adversarial Simulation
+
+Test the robustness of AI models against adversarial attacks.
+
+```python
+from isopro.adversarial_simulation import AdversarialSimulator, AdversarialEnvironment
+from isopro.agents.ai_agent import AI_Agent
+import anthropic
+
+class ClaudeAgent(AI_Agent):
+    def __init__(self, name):
+        super().__init__(name)
+        self.client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+
+    def run(self, input_data):
+        response = self.client.messages.create(
+            model="claude-3-opus-20240229",
+            max_tokens=100,
+            messages=[{"role": "user", "content": input_data['text']}]
+        )
+        return response.content[0].text
+
+# Create the AdversarialEnvironment
+adv_env = AdversarialEnvironment(
+    agent_wrapper=ClaudeAgent("Claude Agent"),
+    num_adversarial_agents=2,
+    attack_types=["textbugger", "deepwordbug"],
+    attack_targets=["input", "output"]
+)
+
+# Set up the adversarial simulator
+simulator = AdversarialSimulator(adv_env)
+
+# Run the simulation
+input_data = ["What is the capital of France?", "How does photosynthesis work?"]
+simulation_results = simulator.run_simulation(input_data, num_steps=1)
+```
+
+### Conversation Simulation
+
+Simulate conversations between an AI assistant and various user personas.
+
+```python
+from isopro.conversation_simulation.conversation_simulator import ConversationSimulator
+
+# Initialize the ConversationSimulator
+simulator = ConversationSimulator(
+    ai_prompt="You are an AI assistant created to be helpful, harmless, and honest. You are a customer service agent for a tech company. Respond politely and professionally."
+)
+
+# Run a simulation with a predefined persona
+conversation_history = simulator.run_simulation("upset", num_turns=3)
+
+# Run a simulation with a custom persona
+custom_persona = {
+    "name": "Techie Customer",
+    "characteristics": ["tech-savvy", "impatient", "detail-oriented"],
+    "message_templates": [
+        "I've tried rebooting my device, but the error persists. Can you help?",
+        "What's the latest update on the cloud service outage?",
+        "I need specifics on the API rate limits for the enterprise plan."
+    ]
+}
+
+custom_conversation = simulator.run_custom_simulation(**custom_persona, num_turns=3)
+```
+
+### Workflow Simulation
+
+Automate UI workflows by learning from video demonstrations.
+
+```python
+from isopro.workflow_simulation import WorkflowAutomation, AgentConfig
+
+# Basic workflow automation
+automation = WorkflowAutomation(
+    video="path/to/workflow.mp4",
+    config="config.json",
+    output="output_dir",
+    logs="logs_dir"
+)
+automation.run()
+
+# Advanced configuration
+agent_config = AgentConfig(
+    learning_rate=3e-4,
+    pretrain_epochs=10,
+    use_demonstration=True,
+    use_reasoning=True
+)
+
+simulator = WorkflowSimulator(
+    video_path="path/to/video.mp4",
+    agent_config=agent_config,
+    viz_config=visualization_config,
+    validation_config=validation_config,
+    output_dir="output"
+)
+
+training_results = simulator.train_agents()
+evaluation_results = simulator.evaluate_agents()
+```
+
+### Car Reinforcement Learning
+
+Train and evaluate RL agents in driving scenarios.
+
+```python
+from isopro.car_simulation import CarRLEnvironment, LLMCarRLWrapper, CarVisualization
+
+# Create the car environment with LLM integration
+env = CarRLEnvironment()
+llm_env = LLMCarRLWrapper(env)
+
+# Initialize visualization
+viz = CarVisualization(env)
+
+# Train and visualize
+observation = llm_env.reset()
+for step in range(1000):
+    action = llm_env.get_action(observation)
+    observation, reward, done, info = llm_env.step(action)
+    viz.render(observation)
+    
+    if done:
+        observation = llm_env.reset()
+```
+
+### Reinforcement Learning with LLM
+
+Integrate Large Language Models with reinforcement learning environments.
+
+```python
+import gymnasium as gym
+from isopro.rl.rl_agent import RLAgent
+from isopro.rl.rl_environment import LLMRLEnvironment
+from stable_baselines3 import PPO
+from isopro.rl.llm_cartpole_wrapper import LLMCartPoleWrapper
+
+agent_prompt = """You are an AI trained to play the CartPole game. 
+Your goal is to balance a pole on a moving cart for as long as possible. 
+You will receive observations about the cart's position, velocity, pole angle, and angular velocity. 
+Based on these, you should decide whether to move the cart left or right."""
+
+env = LLMCartPoleWrapper(agent_prompt, llm_call_limit=100, api_key=os.getenv("ANTHROPIC_API_KEY"))
+rl_agent = RLAgent("LLM_CartPole_Agent", env, algorithm='PPO')
+
+# Train the model
+model.learn(total_timesteps=2)
+
+# Test the model
+obs, _ = env.reset()
+for _ in range(1000):
+    action, _ = model.predict(obs, deterministic=True)
+    obs, reward, done, _, _ = env.step(action)
+    if done:
+        obs, _ = env.reset()
+```
+
+### AI Orchestration
+
+Orchestrate multiple AI agents to work together on complex tasks.
+
+```python
+from isopro.orchestration_simulation import OrchestrationEnv
+from isopro.orchestration_simulation.components import LLaMAAgent, AnalysisAgent, WritingAgent
+from isopro.orchestration_simulation.evaluator import Evaluator
+
+# Create the orchestration environment
+env = OrchestrationEnv()
+
+# Add agents to the environment
+env.add_component(LLaMAAgent("Research", "conduct thorough research on the impact of artificial intelligence on job markets"))
+env.add_component(AnalysisAgent("Analysis"))
+env.add_component(WritingAgent("Writing"))
+
+# Define the task
+task = "Prepare a comprehensive report on the impact of artificial intelligence on job markets in the next decade."
+
+# Run simulations in different modes
+modes = ['parallel', 'sequence', 'node']
+results = {}
+
+for mode in modes:
+    result = env.run_simulation(mode=mode, input_data={'task': task, 'run_order': 'first'})
+    results[mode] = result
+
+# Evaluate the results
+evaluator = Evaluator()
+best_mode = evaluator.evaluate(results)
+print(f"The best execution mode for this task was: {best_mode}")
+```
+
+## Documentation
+
+For more detailed information on each module and its usage, please refer to the [full documentation](https://isopro.readthedocs.io).
+
+## Examples
+
+The [isopro examples](https://github.com/iso-ai/isopro_examples) repository contains Jupyter notebooks with detailed examples:
+
+- `adversarial_example.ipynb`: Demonstrates adversarial testing of language models
+- `conversation_simulation_example.ipynb`: Shows how to simulate conversations with various user personas
+- `workflow_automation_example.ipynb`: Illustrates automated UI workflow learning
+- `car_rl_example.ipynb`: Demonstrates car environment training scenarios
+- `run_cartpole_example.ipynb`: Illustrates the integration of LLMs with reinforcement learning
+- `orchestrator_example.ipynb`: Provides a tutorial on using the AI orchestration capabilities
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+If you encounter any problems or have any questions, please [open an issue](https://github.com/iso-ai/isopro/issues) on our GitHub repository.
+
+## Citation
+
+If you use ISOPRO in your research, please cite it as follows:
+
+```
+@software{isopro2024,
+  author = {Jazmia Henry},
+  title = {ISOPRO: Intelligent Simulation Orchestration for Large Language Models},
+  year = {2024},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  howpublished = {\url{https://github.com/iso-ai/isopro}}
+}
+```
+
+## Contact
+
+For questions or support, please open an issue on our [GitHub issue tracker](https://github.com/iso-ai/isopro/issues).

isopro/__init__.py

@@ -0,0 +1,84 @@
+# isopro/__init__.py
+
+"""
+isopro: Intelligent Simulation Orchestration for LLMs
+
+This package provides tools for creating, managing, and analyzing simulations
+involving Large Language Models (LLMs), including reinforcement learning,
+conversation simulations, and adversarial testing.
+"""
+
+__version__ = "0.1.5"
+
+# Core components
+from .environments.simulation_environment import SimulationEnvironment
+from .environments.custom_environment import CustomEnvironment
+from .environments.llm_orchestrator import LLMOrchestrator
+from .agents.ai_agent import AI_Agent
+from .base.base_component import BaseComponent
+from .wrappers.simulation_wrapper import SimulationWrapper
+from .rl.rl_environment import BaseRLEnvironment
+from .rl.rl_agent import RLAgent
+from .conversation_simulation import ConversationSimulator, ConversationEnvironment, ConversationAgent
+from .adversarial_simulation import AdversarialSimulator, AdversarialEnvironment, AdversarialAgent
+from .orchestration_simulation import LLaMAAgent, SubAgent, OrchestrationEnv, AI_AgentException, ComponentException, AI_Agent
+
+# Workflow simulation components
+from .workflow_simulation import (
+    WorkflowSimulator,
+    WorkflowEnvironment,
+    WorkflowState,
+    UIElement,
+    UIElementDetector,
+    MotionDetector,
+    EpisodeMetrics,
+    AgentConfig,
+    VisualizationConfig,
+    ValidationConfig,
+    WorkflowAutomation
+)
+
+# Car RL components
+from .car_simulator import CarRLEnvironment, LLMCarRLWrapper, CarVisualization
+
+__all__ = [
+    # Core components
+    "LLaMAAgent", 
+    "SubAgent", 
+    "OrchestrationEnv", 
+    "AI_AgentException", 
+    "ComponentException", 
+    "AI_Agent",
+    "SimulationEnvironment",
+    "CustomEnvironment",
+    "LLMOrchestrator",
+    "AI_Agent",
+    "BaseComponent",
+    "SimulationWrapper",
+    "BaseRLEnvironment",
+    "RLAgent",
+    "ConversationSimulator",
+    "ConversationEnvironment",
+    "ConversationAgent",
+    "AdversarialSimulator",
+    "AdversarialEnvironment",
+    "AdversarialAgent",
+    
+    # Workflow components
+    "WorkflowSimulator",
+    "WorkflowEnvironment",
+    "WorkflowState",
+    "UIElement",
+    "UIElementDetector", 
+    "MotionDetector",
+    "EpisodeMetrics",
+    "AgentConfig",
+    "VisualizationConfig",
+    "ValidationConfig",
+    "WorkflowAutomation",
+    
+    # Car RL components
+    "CarRLEnvironment",
+    "LLMCarRLWrapper",
+    "CarVisualization"
+]

isopro/adversarial_simulation/__init__.py

@@ -0,0 +1,18 @@
+"""
+Adversarial Simulation Module
+
+This module provides tools for simulating adversarial attacks on AI models.
+"""
+
+from .adversarial_environment import AdversarialEnvironment
+from .adversarial_agent import AdversarialAgent
+from .adversarial_simulator import AdversarialSimulator
+from .attack_utils import get_available_attacks, create_attack
+
+__all__ = [
+    "AdversarialEnvironment",
+    "AdversarialAgent",
+    "AdversarialSimulator",
+    "get_available_attacks",
+    "create_attack",
+]

isopro/adversarial_simulation/adversarial_agent.py

@@ -0,0 +1,51 @@
+"""
+Adversarial Agent
+
+This module defines the AdversarialAgent class, which can apply various attacks to input or output text.
+"""
+
+from typing import Dict, Any
+from isopro.agents.ai_agent import AI_Agent
+import logging
+
+logger = logging.getLogger(__name__)
+
+class AdversarialAgent(AI_Agent):
+    def __init__(self, name: str, attack, target: str = "input"):
+        """
+        Initialize the AdversarialAgent.
+
+        Args:
+            name (str): The name of the agent.
+            attack (callable): The attack function to apply.
+            target (str): The target of the attack, either "input" or "output".
+        """
+        super().__init__(name)
+        self.attack = attack
+        self.target = target
+        logger.info(f"Initialized AdversarialAgent '{name}' targeting {target}")
+
+    def run(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Apply the adversarial attack to the input or output data.
+
+        Args:
+            input_data (Dict[str, Any]): The input data containing 'text' and 'output' keys.
+
+        Returns:
+            Dict[str, Any]: The perturbed data.
+        """
+        logger.info(f"Running adversarial agent: {self.name}")
+        if self.target == "input":
+            if input_data.get('text'):
+                input_data['text'] = self.attack(input_data['text'])
+            else:
+                logger.warning("Input text is empty or missing. Skipping attack.")
+        elif self.target == "output":
+            if input_data.get('output'):
+                input_data['output'] = self.attack(input_data['output'])
+            else:
+                logger.warning("Output text is empty or missing. Skipping attack.")
+        else:
+            raise ValueError(f"Invalid target: {self.target}")
+        return input_data

isopro/adversarial_simulation/adversarial_environment.py

@@ -0,0 +1,81 @@
+"""
+Adversarial Environment
+
+This module defines the AdversarialEnvironment class, which manages adversarial agents and applies attacks to the simulation state.
+"""
+
+import random
+from typing import List, Dict, Any
+from isopro.environments.simulation_environment import SimulationEnvironment
+from .adversarial_agent import AdversarialAgent
+from .attack_utils import get_model_and_tokenizer, create_attack, get_available_attacks
+import logging
+
+logger = logging.getLogger(__name__)
+
+class AdversarialEnvironment(SimulationEnvironment):
+    def __init__(self, agent_wrapper, num_adversarial_agents: int = 1, attack_types: List[str] = None, attack_targets: List[str] = None):
+        """
+        Initialize the AdversarialEnvironment.
+
+        Args:
+            agent_wrapper: The wrapped agent to pass the adversarially modified state to.
+            num_adversarial_agents (int): The number of adversarial agents to create.
+            attack_types (List[str], optional): The types of attacks to use. If None, all available attacks will be used.
+            attack_targets (List[str], optional): The targets for the attacks ("input", "output", or both). If None, both will be used.
+        """
+        super().__init__()
+        self.agent_wrapper = agent_wrapper
+        self.num_adversarial_agents = num_adversarial_agents
+        self.attack_types = attack_types or get_available_attacks()
+        self.attack_targets = attack_targets or ["input", "output"]
+        self.model, self.tokenizer = get_model_and_tokenizer()
+        self._create_adversarial_agents()
+        logger.info(f"Initialized AdversarialEnvironment with {num_adversarial_agents} agents")
+
+    def _create_adversarial_agents(self):
+        """Create adversarial agents with random attack types and targets."""
+        for i in range(self.num_adversarial_agents):
+            attack_type = random.choice(self.attack_types)
+            attack_target = random.choice(self.attack_targets)
+            attack = create_attack(attack_type, self.model, self.tokenizer)
+            agent = AdversarialAgent(name=f"Adversarial Agent {i+1} ({attack_type}, {attack_target})", attack=attack, target=attack_target)
+            self.add_agent(agent)
+        logger.info(f"Created {self.num_adversarial_agents} adversarial agents")
+
+    def step(self, sim_state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Apply adversarial attacks and step the environment.
+
+        Args:
+            sim_state (Dict[str, Any]): The current simulation state.
+
+        Returns:
+            Dict[str, Any]: The updated simulation state after applying attacks and stepping the wrapped agent.
+        """
+        # Apply adversarial attacks
+        for agent in self.agents:
+            sim_state = agent.run(sim_state)
+
+        # Pass the adversarially modified state to the wrapped agent
+        return self.agent_wrapper.step(sim_state)
+
+    def reset(self):
+        """Reset the environment and recreate adversarial agents."""
+        super().reset()
+        self._create_adversarial_agents()
+        logger.info("Reset AdversarialEnvironment and recreated agents")
+
+    def get_attack_distribution(self) -> Dict[str, int]:
+        """
+        Get the distribution of attack types and targets among the adversarial agents.
+
+        Returns:
+            Dict[str, int]: A dictionary containing the count of each attack type and target.
+        """
+        attack_counts = {f"{attack_type}_{target}": 0 for attack_type in self.attack_types for target in self.attack_targets}
+        for agent in self.agents:
+            attack_type, target = agent.name.split('(')[-1].split(')')[0].split(', ')
+            attack_counts[f"{attack_type}_{target}"] += 1
+        logger.info(f"Current attack distribution: {attack_counts}")
+        return attack_counts

isopro/adversarial_simulation/adversarial_simulator.py

@@ -0,0 +1,47 @@
+"""
+Adversarial Simulator
+
+This module provides a high-level interface for running adversarial simulations.
+"""
+
+from typing import List, Dict, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+class AdversarialSimulator:
+    def __init__(self, environment):
+        """
+        Initialize the AdversarialSimulator.
+
+        Args:
+            environment: The AdversarialEnvironment to use in the simulation.
+        """
+        self.environment = environment
+        logger.info("Initialized AdversarialSimulator")
+
+    def run_simulation(self, input_data: List[str], num_steps: int = 1) -> List[Dict[str, Any]]:
+        """
+        Run an adversarial simulation.
+
+        Args:
+            input_data (List[str]): The list of input texts to use in the simulation.
+            num_steps (int): The number of steps to run the simulation for each input.
+
+        Returns:
+            List[Dict[str, Any]]: A list of simulation results, including original and perturbed inputs and outputs.
+        """
+        results = []
+        for text in input_data:
+            sim_state = {"text": text, "output": ""}
+            original_output = self.environment.agent_wrapper.run({"text": text})
+            for _ in range(num_steps):
+                sim_state = self.environment.step(sim_state)
+            results.append({
+                "original_input": text,
+                "perturbed_input": sim_state["text"],
+                "original_output": original_output,
+                "perturbed_output": sim_state["output"]
+            })
+        logger.info(f"Completed simulation with {len(input_data)} inputs and {num_steps} steps each")
+        return results

isopro/adversarial_simulation/attack_utils.py

@@ -0,0 +1,65 @@
+"""
+Attack Utilities
+
+This module provides utility functions for creating and managing adversarial attacks.
+"""
+
+import torch
+from typing import Tuple, Callable
+from transformers import AutoModelForSequenceClassification, AutoTokenizer
+from isoadverse.attacks.text_fgsm import text_fgsm_attack
+from isoadverse.attacks.text_pgd import text_pgd_attack
+from isoadverse.attacks.textbugger import textbugger_attack
+from isoadverse.attacks.deepwordbug import deepwordbug_attack
+import logging
+
+logger = logging.getLogger(__name__)
+
+def get_model_and_tokenizer(model_name: str = 'bert-base-uncased') -> Tuple[torch.nn.Module, torch.nn.Module]:
+    """
+    Load a pre-trained model and tokenizer.
+
+    Args:
+        model_name (str): The name of the model to load.
+
+    Returns:
+        Tuple[torch.nn.Module, torch.nn.Module]: The loaded model and tokenizer.
+    """
+    model = AutoModelForSequenceClassification.from_pretrained(model_name)
+    tokenizer = AutoTokenizer.from_pretrained(model_name)
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    model.to(device)
+    logger.info(f"Loaded model {model_name} on {device}")
+    return model, tokenizer
+
+def create_attack(attack_type: str, model: torch.nn.Module, tokenizer: torch.nn.Module) -> Callable:
+    """
+    Create an attack function based on the specified attack type.
+
+    Args:
+        attack_type (str): The type of attack to create.
+        model (torch.nn.Module): The model to use for the attack.
+        tokenizer (torch.nn.Module): The tokenizer to use for the attack.
+
+    Returns:
+        Callable: The attack function.
+    """
+    if attack_type == "fgsm":
+        return lambda x: text_fgsm_attack(model, tokenizer, x, torch.tensor([1]), epsilon=0.3)
+    elif attack_type == "pgd":
+        return lambda x: text_pgd_attack(model, tokenizer, x, torch.tensor([1]), epsilon=0.3, alpha=0.1, num_steps=10)
+    elif attack_type == "textbugger":
+        return lambda x: textbugger_attack(x, num_bugs=5)
+    elif attack_type == "deepwordbug":
+        return lambda x: deepwordbug_attack(x, num_bugs=5)
+    else:
+        raise ValueError(f"Unknown attack type: {attack_type}")
+
+def get_available_attacks() -> list:
+    """
+    Get a list of available attack types.
+
+    Returns:
+        list: A list of available attack types.
+    """
+    return ["fgsm", "pgd", "textbugger", "deepwordbug"]

isopro/adversarial_simulation/main.py

@@ -0,0 +1,124 @@
+import logging
+from typing import List
+from .adversarial_simulator import AdversarialSimulator
+from .adversarial_environment import AdversarialEnvironment
+from isopro.utils.analyze_adversarial_sim import analyze_adversarial_results, summarize_adversarial_impact
+from isopro.agents.ai_agent import AI_Agent
+import anthropic
+import os
+from dotenv import load_dotenv
+import json
+from datetime import datetime
+import numpy as np
+import torch
+
+load_dotenv()
+
+# Set up logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+class ClaudeAgent(AI_Agent):
+    def __init__(self, name):
+        super().__init__(name)
+        self.client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+
+    def run(self, input_data):
+        response = self.client.messages.create(
+            model="claude-3-opus-20240229",
+            max_tokens=100,
+            messages=[{"role": "user", "content": input_data['text']}]
+        )
+        return response.content[0].text
+
+    def step(self, sim_state):
+        sim_state['output'] = self.run(sim_state)
+        return sim_state
+
+class NumpyEncoder(json.JSONEncoder):
+    def default(self, obj):
+        if isinstance(obj, np.floating):
+            return float(obj)
+        if isinstance(obj, torch.Tensor):
+            return obj.tolist()
+        return super(NumpyEncoder, self).default(obj)
+
+def setup_logging(log_dir: str, run_id: str) -> None:
+    os.makedirs(log_dir, exist_ok=True)
+    log_file = os.path.join(log_dir, f"adv-{run_id}.log")
+    
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        handlers=[
+            logging.FileHandler(log_file),
+            logging.StreamHandler()
+        ]
+    )
+
+def save_scores(output_dir: str, run_id: str, analysis_results: dict) -> None:
+    os.makedirs(output_dir, exist_ok=True)
+    output_file = os.path.join(output_dir, f"adv-{run_id}.json")
+    
+    try:
+        with open(output_file, 'w') as f:
+            json.dump(analysis_results, f, indent=2, cls=NumpyEncoder)
+        
+        logging.info(f"Saved analysis results to {output_file}")
+    except Exception as e:
+        logging.error(f"Error saving analysis results: {str(e)}")
+
+def get_sample_inputs() -> List[str]:
+    return [
+        "What is the capital of France?",
+        "How does photosynthesis work?",
+        "Explain the theory of relativity."
+    ]
+
+def main():
+    try:
+        run_id = datetime.now().strftime("%Y%m%d-%H%M%S")
+        
+        log_dir = "logs"
+        setup_logging(log_dir, run_id)
+        
+        logger = logging.getLogger(__name__)
+        logger.info(f"Starting adversarial simulation run {run_id}")
+
+        claude_agent = ClaudeAgent("Claude Agent")
+
+        # Create the AdversarialEnvironment
+        adv_env = AdversarialEnvironment(
+            agent_wrapper=claude_agent,
+            num_adversarial_agents=2,
+            attack_types=["textbugger", "deepwordbug"],
+            attack_targets=["input", "output"]
+        )
+
+        # Set up the adversarial simulator with the environment
+        simulator = AdversarialSimulator(adv_env)
+
+        input_data = get_sample_inputs()
+
+        logger.info("Starting adversarial simulation...")
+        simulation_results = simulator.run_simulation(input_data, num_steps=1)
+
+        logger.info("Analyzing simulation results...")
+        analysis_results = analyze_adversarial_results(simulation_results)
+
+        summary = summarize_adversarial_impact(analysis_results)
+
+        print("\nAdversarial Simulation Summary:")
+        print(summary)
+
+        output_dir = "output"
+        save_scores(output_dir, run_id, analysis_results)
+
+        logger.info("Simulation complete.")
+    
+    except Exception as e:
+        logger.error(f"An error occurred during the simulation: {str(e)}", exc_info=True)
+        raise
+
+if __name__ == "__main__":
+    main()

isopro/agents/__init__.py

@@ -0,0 +1,7 @@
+"""
+Agent classes for the isopro package.
+"""
+
+from .ai_agent import AI_Agent
+
+__all__ = ["AI_Agent"]

isopro/agents/ai_agent.py

@@ -0,0 +1,44 @@
+"""AI Agent for Simulation Environment."""
+from ..base.base_component import BaseComponent, agent_component
+
+@agent_component
+class AI_Agent(BaseComponent):
+    """AI Agent for Simulation Environment."""
+
+    def __init__(self, name):
+        """
+        Initialize the AI_Agent.
+
+        Args:
+            name (str): The name of the agent.
+        """
+        super().__init__(name)
+        self.components = []
+
+    def add_component(self, component):
+        """
+        Add a component to the agent.
+
+        Args:
+            component (BaseComponent): The component to add.
+        """
+        if getattr(component, '_is_agent_component', False):
+            self.components.append(component)
+        else:
+            raise ValueError(f"Component {component} is not decorated with @agent_component")
+
+    def run(self, input_data):
+        """
+        Run the agent's components and process input data.
+
+        Args:
+            input_data (dict): The input data for the agent.
+
+        Returns:
+            dict: The processed output data.
+        """
+        self.logger.info(f"Running agent: {self.name}")
+        output = input_data
+        for component in self.components:
+            output = component.run(output)
+        return output

isopro/base/__init__.py

@@ -0,0 +1,8 @@
+"""
+Base classes for the isopro package.
+"""
+
+from .base_wrapper import BaseWrapper
+from .base_component import BaseComponent
+
+__all__ = ["BaseWrapper", "BaseComponent"]

isopro/base/base_component.py

@@ -0,0 +1,34 @@
+"""Base Component for Simulation Environment."""
+from abc import ABC, abstractmethod
+from ..utils.logging_utils import setup_logger
+
+class BaseComponent(ABC):
+    """Base Component for Simulation Environment."""
+
+    def __init__(self, name):
+        """
+        Initialize the BaseComponent.
+
+        Args:
+            name (str): The name of the component.
+        """
+        self.name = name
+        self.logger = setup_logger(f"{self.__class__.__name__}_{self.name}")
+
+    @abstractmethod
+    def run(self):
+        """Execute the component's main functionality."""
+        pass
+
+    def __str__(self):
+        return f"{self.__class__.__name__}({self.name})"
+
+def agent_component(cls):
+    """
+    Decorator to mark a class as an agent component.
+
+    This decorator can be used to add metadata or perform
+    additional setup for agent components.
+    """
+    cls._is_agent_component = True
+    return cls

isopro/base/base_wrapper.py

@@ -0,0 +1,82 @@
+"""Base Wrapper for Simulation Environment."""
+from abc import ABC, abstractmethod
+import logging
+from ..utils.logging_utils import setup_logger
+
+class BaseWrapper(ABC):
+    """Base Wrapper for Simulation Environment."""
+
+    def __init__(self, agent):
+        """
+        Initialize the BaseWrapper.
+
+        Args:
+            agent: The agent to be wrapped.
+        """
+        self.agent = agent
+        self.logger = setup_logger(self.__class__.__name__)
+
+    @abstractmethod
+    def step(self):
+        """Execute one time step within the environment."""
+        pass
+
+    @abstractmethod
+    def reset(self):
+        """Reset the state of the environment to an initial state."""
+        pass
+
+    @abstractmethod
+    def render(self):
+        """Render the environment."""
+        pass
+
+    @abstractmethod
+    def close(self):
+        """Close the environment, clean up any resources."""
+        pass
+
+    @abstractmethod
+    def convert_to_agent_input(self, sim_state):
+        """
+        Convert simulation state to agent input format.
+
+        Args:
+            sim_state (dict): The current state of the simulation.
+
+        Returns:
+            dict: The converted input for the agent.
+        """
+        pass
+
+    @abstractmethod
+    def convert_from_agent_output(self, agent_output):
+        """
+        Convert agent output to simulation input format.
+
+        Args:
+            agent_output (dict): The output from the agent.
+
+        Returns:
+            dict: The converted input for the simulation.
+        """
+        pass
+
+    def __getattr__(self, name):
+        """
+        Attempt to get an attribute from the agent if it's not found in the wrapper.
+
+        Args:
+            name (str): The name of the attribute.
+
+        Returns:
+            The requested attribute.
+
+        Raises:
+            AttributeError: If the attribute is not found in the agent or wrapper.
+        """
+        try:
+            return getattr(self.agent, name)
+        except AttributeError:
+            self.logger.warning(f"Attribute '{name}' not found in agent or wrapper")
+            raise

isopro/car_simulator/__init__.py

@@ -0,0 +1,12 @@
+"""
+Car Reinforcement Learning Package
+
+This package contains modules for simulating and visualizing
+reinforcement learning agents in a car driving environment.
+"""
+
+from .car_rl_environment import CarRLEnvironment 
+from .car_llm_agent import LLMCarRLWrapper
+from .carviz import CarVisualization
+
+__all__ = ['CarRLEnvironment', 'LLMCarRLWrapper', 'CarVisualization']

isopro/car_simulator/car_llm_agent.py

@@ -0,0 +1,143 @@
+import gymnasium as gym
+from stable_baselines3 import PPO
+from stable_baselines3.common.vec_env import DummyVecEnv
+from stable_baselines3.common.evaluation import evaluate_policy
+import numpy as np
+import anthropic
+import logging
+from typing import List, Dict, Any
+from .car_rl_environment import CarRLEnvironment
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Set up logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+class LLMCarRLWrapper(CarRLEnvironment):
+    def __init__(self, num_cars=1, time_of_day="12:00", is_rainy=False, is_weekday=True, 
+                 agent_prompt="You are an expert driving instructor. Provide concise guidance to improve the RL agent's driving performance.",
+                 llm_call_limit=100, llm_call_frequency=100):
+        super().__init__(num_cars, time_of_day, is_rainy, is_weekday)
+        self.agent_prompt = agent_prompt
+        api_key = os.getenv('ANTHROPIC_API_KEY')
+        if not api_key:
+            raise ValueError("ANTHROPIC_API_KEY not found in environment variables")
+        self.client = anthropic.Anthropic(api_key=api_key)
+        self.llm_call_count = 0
+        self.llm_call_limit = llm_call_limit
+        self.llm_call_frequency = llm_call_frequency
+        self.conversation_history: List[Dict[str, str]] = []
+        self.step_count = 0
+        self.current_guidance = {"action": "unknown"}
+
+    def reset(self, seed=None, options=None):
+        self.step_count = 0
+        self.current_guidance = {"action": "unknown"}
+        return super().reset(seed=seed)
+
+    def step(self, action):
+        self.step_count += 1
+        
+        if self.step_count % self.llm_call_frequency == 0 and self.llm_call_count < self.llm_call_limit:
+            observation, reward, terminated, truncated, info = super().step(action)
+            self.current_guidance = self._get_llm_guidance(observation, reward, terminated)
+            self.llm_call_count += 1
+        else:
+            observation, reward, terminated, truncated, info = super().step(action)
+
+        adjusted_action = self._adjust_action_based_on_guidance(action, self.current_guidance)
+        
+        return observation, reward, terminated, truncated, info
+
+    def _get_llm_guidance(self, observation, reward, terminated):
+        user_message = f"Current state: {observation}, Reward: {reward}, Terminated: {terminated}. Provide brief driving advice."
+
+        messages = self.conversation_history + [
+            {"role": "user", "content": user_message},
+        ]
+
+        try:
+            response = self.client.messages.create(
+                model="claude-3-opus-20240229",
+                max_tokens=50,
+                system=self.agent_prompt,
+                messages=messages
+            )
+
+            ai_response = response.content[0].text
+            self.conversation_history.append({"role": "user", "content": user_message})
+            self.conversation_history.append({"role": "assistant", "content": ai_response})
+            logger.debug(f"LLM guidance: {ai_response}")
+            return self._parse_llm_guidance(ai_response)
+        except Exception as e:
+            logger.error(f"Error getting LLM guidance: {e}")
+            return {"action": "unknown"}
+
+    def _parse_llm_guidance(self, guidance):
+        guidance_lower = guidance.lower()
+        actions = {
+            "increase speed": {"action": "increase_speed"},
+            "decrease speed": {"action": "decrease_speed"},
+            "slow down": {"action": "decrease_speed"},
+            "turn left": {"action": "turn_left"},
+            "turn right": {"action": "turn_right"},
+            "stop": {"action": "stop"},
+            "start raining": {"environment": "rain", "status": True},
+            "increase traffic": {"environment": "traffic", "density": "high"}
+        }
+        
+        for key, value in actions.items():
+            if key in guidance_lower:
+                return value
+        
+        return {"action": "unknown"}
+
+    def _adjust_action_based_on_guidance(self, action, guidance):
+        adjustments = {
+            "increase_speed": (0, 0.1),
+            "decrease_speed": (0, -0.1),
+            "turn_left": (1, -0.1),
+            "turn_right": (1, 0.1),
+        }
+
+        if guidance["action"] in adjustments:
+            index, adjustment = adjustments[guidance["action"]]
+            action[index] = np.clip(action[index] + adjustment, -1.0, 1.0)
+
+        return action
+
+def make_env(llm_call_limit):
+    def _init():
+        return LLMCarRLWrapper(num_cars=3, time_of_day="08:00", is_rainy=False, is_weekday=True, 
+                               llm_call_limit=llm_call_limit)
+    return _init
+
+def train_and_evaluate(env, total_timesteps=100000, eval_episodes=10):
+    model = PPO("MlpPolicy", env, verbose=1, learning_rate=0.0003, n_steps=2048, 
+                batch_size=64, n_epochs=10, gamma=0.99, gae_lambda=0.95, clip_range=0.2)
+
+    model.learn(total_timesteps=total_timesteps, progress_bar=True)
+
+    mean_reward, std_reward = evaluate_policy(model, env, n_eval_episodes=eval_episodes)
+    logger.info(f"Mean reward: {mean_reward:.2f} +/- {std_reward:.2f}")
+
+    return model, mean_reward
+
+def main():
+    llm_call_limit = int(os.getenv('LLM_CALL_LIMIT', '10'))  # Default to 10 if not set
+
+    env = DummyVecEnv([make_env(llm_call_limit)])
+
+    model, mean_reward = train_and_evaluate(env)
+
+    model.save("car_rl_llm_ppo_model")
+
+    logger.info("Training and evaluation completed.")
+    logger.info(f"Final mean reward: {mean_reward:.2f}")
+
+if __name__ == "__main__":
+    main()

isopro/car_simulator/car_rl_environment.py

@@ -0,0 +1,155 @@
+import gymnasium as gym
+from gymnasium import spaces
+import numpy as np
+import torch
+import random
+from typing import List, Dict, Tuple, Union
+
+class CarRLEnvironment(gym.Env):
+    def __init__(self, num_cars=1, time_of_day="12:00", is_rainy=False, is_weekday=True):
+        super().__init__()
+        self.num_cars = num_cars
+        self.time_of_day = self.convert_time(time_of_day)
+        self.is_rainy = is_rainy
+        self.is_weekday = is_weekday
+        self.friction = 0.4 if is_rainy else 0.8
+        
+        # Define action and observation spaces
+        self.action_space = spaces.Box(low=-1, high=1, shape=(num_cars * 2,), dtype=np.float32)
+        
+        # Observation space: [x, y, vx, vy, angle] for each car + [time_of_day, is_rainy, is_weekday]
+        self.observation_space = spaces.Box(
+            low=-np.inf, 
+            high=np.inf, 
+            shape=(num_cars * 5 + 3,), 
+            dtype=np.float32
+        )
+
+        self.cars = self.initialize_cars()
+
+    def convert_time(self, time_of_day: Union[str, float]) -> float:
+        """Convert time to a float between 0 and 24."""
+        if isinstance(time_of_day, str):
+            try:
+                hours, minutes = map(int, time_of_day.split(':'))
+                return float(hours + minutes / 60.0)
+            except ValueError:
+                print(f"Invalid time format: {time_of_day}. Using default value of 12:00.")
+                return 12.0
+        elif isinstance(time_of_day, (int, float)):
+            return float(time_of_day) % 24.0
+        else:
+            print(f"Invalid time format: {time_of_day}. Using default value of 12:00.")
+            return 12.0
+
+    def initialize_cars(self) -> List[Dict[str, torch.Tensor]]:
+        """Initialize car parameters."""
+        return [
+            {
+                "position": torch.tensor([random.uniform(-1, 1), random.uniform(-1, 1)], dtype=torch.float32),
+                "velocity": torch.tensor([random.uniform(-0.5, 0.5), random.uniform(-0.5, 0.5)], dtype=torch.float32),
+                "angle": torch.tensor([random.uniform(-np.pi, np.pi)], dtype=torch.float32)
+            } for _ in range(self.num_cars)
+        ]
+
+    def reset(self, seed=None) -> Tuple[np.ndarray, Dict]:
+        super().reset(seed=seed)
+        self.cars = self.initialize_cars()
+        return self.get_observation(), {}
+
+    def get_observation(self) -> np.ndarray:
+        """Get the current observation of the environment."""
+        car_obs = np.concatenate([
+            np.concatenate([
+                car["position"].numpy(),
+                car["velocity"].numpy(),
+                car["angle"].numpy()
+            ]) for car in self.cars
+        ])
+        env_obs = np.array([
+            self.time_of_day,
+            float(self.is_rainy),
+            float(self.is_weekday)
+        ], dtype=np.float32)
+        return np.concatenate([car_obs, env_obs]).astype(np.float32)
+
+    def step(self, action: np.ndarray) -> Tuple[np.ndarray, float, bool, bool, Dict]:
+        """
+        Take a step in the environment.
+        
+        Args:
+            action (np.ndarray): Array of actions for all cars [acceleration1, steering1, acceleration2, steering2, ...]
+        
+        Returns:
+            observation, reward, terminated, truncated, info
+        """
+        # Ensure action is the correct shape
+        action = np.array(action).flatten()
+        if action.shape[0] != self.num_cars * 2:
+            raise ValueError(f"Action shape {action.shape} does not match expected shape ({self.num_cars * 2},)")
+
+        for i in range(self.num_cars):
+            car_action = action[i*2:(i+1)*2]
+            self.apply_action(self.cars[i], car_action)
+            self.update_physics(self.cars[i])
+
+        observation = self.get_observation()
+        reward = self.calculate_reward()
+        terminated = self.is_terminated()
+        truncated = False
+        info = {}
+
+        return observation, reward, terminated, truncated, info
+
+    def apply_action(self, car: Dict[str, torch.Tensor], action: np.ndarray):
+        """Apply the RL agent's action to the car."""
+        if len(action) != 2:
+            raise ValueError(f"Expected action to have 2 values, got {len(action)}")
+        
+        acceleration, steering = action
+        car["velocity"] += torch.tensor([acceleration, 0.0], dtype=torch.float32) * 0.1  # Scale down the acceleration
+        car["angle"] += torch.tensor([steering], dtype=torch.float32) * 0.1  # Scale down the steering
+
+    def update_physics(self, car: Dict[str, torch.Tensor], dt: float = 0.1):
+        """Update car position and velocity using physics simulation."""
+        # Update velocity (apply friction)
+        car["velocity"] *= (1 - self.friction * dt)
+        
+        # Update position
+        car["position"] += car["velocity"] * dt
+        
+        # Apply steering
+        angle = car["angle"].item()
+        rotation_matrix = torch.tensor([
+            [np.cos(angle), -np.sin(angle)],
+            [np.sin(angle), np.cos(angle)]
+        ], dtype=torch.float32)
+        car["velocity"] = torch.matmul(rotation_matrix, car["velocity"])
+        
+        # Bound the position to keep cars on the screen
+        car["position"] = torch.clamp(car["position"], -1, 1)
+
+    def calculate_reward(self) -> float:
+        """Calculate the reward based on the current state."""
+        reward = 0.0
+        for car in self.cars:
+            # Reward for moving
+            speed = torch.norm(car["velocity"]).item()
+            reward += speed * 0.1
+            
+            # Penalty for being close to the edge
+            distance_from_center = torch.norm(car["position"]).item()
+            reward -= distance_from_center * 0.1
+        
+        return reward
+
+    def is_terminated(self) -> bool:
+        """Check if the episode should be terminated."""
+        for car in self.cars:
+            if torch.any(torch.abs(car["position"]) > 1):
+                return True
+        return False
+
+    def render(self):
+        """Render the environment (placeholder for potential future implementation)."""
+        pass

isopro/car_simulator/car_rl_model.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:85303b6b7e544f04d04cb949709ee37ac956a78f098c0390e2b210448bc446bb
+size 164031

isopro/car_simulator/car_rl_training.py

@@ -0,0 +1,38 @@
+import gymnasium as gym
+from stable_baselines3 import PPO
+from stable_baselines3.common.vec_env import DummyVecEnv
+from stable_baselines3.common.evaluation import evaluate_policy
+import numpy as np
+from .car_rl_environment import CarRLEnvironment
+
+def make_env():
+    """Create and return an instance of the CarRLEnvironment."""
+    return CarRLEnvironment(num_cars=3, time_of_day="08:00", is_rainy=False, is_weekday=True)
+
+# Create a vectorized environment
+env = DummyVecEnv([make_env])
+
+# Initialize the PPO agent
+model = PPO("MlpPolicy", env, verbose=1, learning_rate=0.0003, n_steps=2048, batch_size=64, n_epochs=10, gamma=0.99, gae_lambda=0.95, clip_range=0.2, ent_coef=0.0)
+
+# Train the agent
+total_timesteps = 1_000_000
+model.learn(total_timesteps=total_timesteps, progress_bar=True)
+
+# Evaluate the trained agent
+mean_reward, std_reward = evaluate_policy(model, env, n_eval_episodes=10)
+print(f"Mean reward: {mean_reward:.2f} +/- {std_reward:.2f}")
+
+# Save the trained model
+model.save("car_rl_ppo_model")
+
+# Test the trained agent
+obs = env.reset()
+for _ in range(1000):
+    action, _states = model.predict(obs, deterministic=True)
+    obs, rewards, dones, info = env.step(action)
+    env.render()
+    if dones.any():
+        obs = env.reset()
+
+env.close()

isopro/car_simulator/carviz.py

@@ -0,0 +1,227 @@
+import pygame
+import numpy as np
+from .car_rl_environment import CarRLEnvironment
+from stable_baselines3 import PPO
+import math
+import random
+from datetime import datetime, timedelta
+
+# Initialize Pygame
+pygame.init()
+
+# Constants
+SCREEN_WIDTH = 1000
+SCREEN_HEIGHT = 800
+ROAD_WIDTH = 800
+ROAD_HEIGHT = 600
+CAR_WIDTH = 40
+CAR_HEIGHT = 20
+INFO_BOX_WIDTH = 200
+INFO_BOX_HEIGHT = 120
+UI_PANEL_WIDTH = 200
+
+# Colors
+WHITE = (255, 255, 255)
+BLACK = (0, 0, 0)
+GRAY = (200, 200, 200)
+RED = (255, 0, 0)
+GREEN = (0, 255, 0)
+BLUE = (0, 0, 255)
+YELLOW = (255, 255, 0)
+
+class CarVisualization:
+    def __init__(self, env, model):
+        self.env = env
+        self.unwrapped_env = env.envs[0]
+        self.model = model
+        self.screen = pygame.display.set_mode((SCREEN_WIDTH, SCREEN_HEIGHT))
+        pygame.display.set_caption("Enhanced Car RL Visualization")
+        self.clock = pygame.time.Clock()
+        self.font = pygame.font.Font(None, 24)
+        self.rain = [self.RainDrop() for _ in range(100)]
+        self.obstacles = [self.Obstacle() for _ in range(5)]
+        self.time_of_day = self.float_to_datetime(self.unwrapped_env.time_of_day)
+
+    def float_to_datetime(self, time_float):
+        """Convert a float time (0-24) to a datetime object."""
+        hours = int(time_float)
+        minutes = int((time_float - hours) * 60)
+        return datetime.min + timedelta(hours=hours, minutes=minutes)
+
+    def datetime_to_string(self, dt):
+        """Convert a datetime object to a string in HH:MM format."""
+        return dt.strftime("%H:%M")
+
+    def draw_road(self):
+        road_rect = pygame.Rect((SCREEN_WIDTH - ROAD_WIDTH) // 2, (SCREEN_HEIGHT - ROAD_HEIGHT) // 2, ROAD_WIDTH, ROAD_HEIGHT)
+        road_color = self.get_road_color()
+        pygame.draw.rect(self.screen, road_color, road_rect)
+        
+        # Draw lane markings
+        for i in range(1, 3):
+            y = (SCREEN_HEIGHT - ROAD_HEIGHT) // 2 + i * (ROAD_HEIGHT // 3)
+            pygame.draw.line(self.screen, WHITE, (road_rect.left, y), (road_rect.right, y), 2)
+
+    def get_road_color(self):
+        hour = self.time_of_day.hour
+        if 6 <= hour < 18:  # Daytime
+            return GRAY
+        elif 18 <= hour < 20 or 4 <= hour < 6:  # Dawn/Dusk
+            return (150, 150, 170)
+        else:  # Night
+            return (100, 100, 120)
+
+    def draw_car(self, position, angle, color):
+        x, y = position
+        x = (x + 1) * ROAD_WIDTH / 2 + (SCREEN_WIDTH - ROAD_WIDTH) // 2
+        y = (y + 1) * ROAD_HEIGHT / 2 + (SCREEN_HEIGHT - ROAD_HEIGHT) // 2
+        
+        car_surface = pygame.Surface((CAR_WIDTH, CAR_HEIGHT), pygame.SRCALPHA)
+        pygame.draw.rect(car_surface, color, (0, 0, CAR_WIDTH, CAR_HEIGHT))
+        pygame.draw.polygon(car_surface, BLACK, [(0, 0), (CAR_WIDTH // 2, 0), (0, CAR_HEIGHT)])
+        rotated_car = pygame.transform.rotate(car_surface, -math.degrees(angle))
+        self.screen.blit(rotated_car, rotated_car.get_rect(center=(x, y)))
+
+    def draw_info_box(self, car_index, position, action, reward):
+        x, y = position
+        x = (x + 1) * ROAD_WIDTH / 2 + (SCREEN_WIDTH - ROAD_WIDTH) // 2
+        y = (y + 1) * ROAD_HEIGHT / 2 + (SCREEN_HEIGHT - ROAD_HEIGHT) // 2
+        
+        info_box = pygame.Surface((INFO_BOX_WIDTH, INFO_BOX_HEIGHT))
+        info_box.fill(WHITE)
+        pygame.draw.rect(info_box, BLACK, info_box.get_rect(), 2)
+        
+        texts = [
+            f"Car {car_index + 1}",
+            f"Acceleration: {action[0]:.2f}",
+            f"Steering: {action[1]:.2f}",
+            f"Reward: {reward:.2f}",
+            f"Speed: {np.linalg.norm(self.unwrapped_env.cars[car_index]['velocity']):.2f}"
+        ]
+        
+        for i, text in enumerate(texts):
+            text_surface = self.font.render(text, True, BLACK)
+            info_box.blit(text_surface, (10, 10 + i * 25))
+        
+        self.screen.blit(info_box, (x - INFO_BOX_WIDTH // 2, y - INFO_BOX_HEIGHT - 30))
+
+
+    def draw_rain(self):
+        for drop in self.rain:
+            pygame.draw.line(self.screen, (200, 200, 255), (drop.x, drop.y), (drop.x, drop.y + drop.size), drop.size)
+            drop.fall()
+
+    def draw_obstacles(self):
+        for obstacle in self.obstacles:
+            pygame.draw.rect(self.screen, YELLOW, ((SCREEN_WIDTH - ROAD_WIDTH) // 2 + obstacle.x, 
+                                                   (SCREEN_HEIGHT - ROAD_HEIGHT) // 2 + obstacle.y, 
+                                                   obstacle.width, obstacle.height))
+
+    def draw_ui_panel(self):
+        panel = pygame.Surface((UI_PANEL_WIDTH, SCREEN_HEIGHT))
+        panel.fill(WHITE)
+        pygame.draw.rect(panel, BLACK, panel.get_rect(), 2)
+
+        texts = [
+            f"Time: {self.datetime_to_string(self.time_of_day)}",
+            f"Rainy: {'Yes' if self.unwrapped_env.is_rainy else 'No'}",
+            f"Weekday: {'Yes' if self.unwrapped_env.is_weekday else 'No'}",
+            "Press keys to change:",
+            "T: Time +1 hour",
+            "R: Toggle Rain",
+            "W: Toggle Weekday"
+        ]
+
+        for i, text in enumerate(texts):
+            text_surface = self.font.render(text, True, BLACK)
+            panel.blit(text_surface, (10, 10 + i * 30))
+
+        self.screen.blit(panel, (SCREEN_WIDTH - UI_PANEL_WIDTH, 0))
+
+    def handle_events(self):
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                return False
+            elif event.type == pygame.KEYDOWN:
+                if event.key == pygame.K_t:
+                    self.time_of_day += timedelta(hours=1)
+                    self.unwrapped_env.time_of_day = (self.time_of_day.hour + self.time_of_day.minute / 60) % 24
+                elif event.key == pygame.K_r:
+                    self.unwrapped_env.is_rainy = not self.unwrapped_env.is_rainy
+                elif event.key == pygame.K_w:
+                    self.unwrapped_env.is_weekday = not self.unwrapped_env.is_weekday
+        return True
+    
+    class RainDrop:
+        def __init__(self):
+            self.x = random.randint(0, SCREEN_WIDTH)
+            self.y = random.randint(0, SCREEN_HEIGHT)
+            self.speed = random.randint(5, 15)
+            self.size = random.randint(1, 3)
+
+        def fall(self):
+            self.y += self.speed
+            if self.y > SCREEN_HEIGHT:
+                self.y = 0
+                self.x = random.randint(0, SCREEN_WIDTH)
+
+    class Obstacle:
+        def __init__(self):
+            self.width = random.randint(30, 60)
+            self.height = random.randint(30, 60)
+            self.x = random.randint(0, ROAD_WIDTH - self.width)
+            self.y = random.randint(0, ROAD_HEIGHT - self.height)
+
+    def run_visualization(self, num_episodes=5):
+        for episode in range(num_episodes):
+            obs = self.env.reset()
+            done = False
+            total_reward = 0
+            step = 0
+            
+            while not done:
+                if not self.handle_events():
+                    return
+
+                self.screen.fill(WHITE)
+                self.draw_road()
+                self.draw_obstacles()
+                if self.unwrapped_env.is_rainy:
+                    self.draw_rain()
+
+                action, _ = self.model.predict(obs, deterministic=True)
+                obs, reward, done, info = self.env.step(action)
+                total_reward += reward[0]
+
+                for i, car in enumerate(self.unwrapped_env.cars):
+                    position = car["position"].numpy()
+                    angle = car["angle"].item()
+                    color = (RED, GREEN, BLUE)[i % 3]  # Cycle through colors for different cars
+                    self.draw_car(position, angle, color)
+                    self.draw_info_box(i, position, action[0][i*2:(i+1)*2], reward[0])
+
+                self.draw_ui_panel()
+                pygame.display.flip()
+                self.clock.tick(30)
+                step += 1
+
+                if done[0]:
+                    break
+
+            print(f"Episode {episode + 1} finished. Total reward: {total_reward:.2f}")
+
+        pygame.quit()
+
+
+def main():
+    # Create and train the model (you might want to load a pre-trained model instead)
+    env = CarRLEnvironment(num_cars=3, time_of_day="08:00", is_rainy=False, is_weekday=True)
+    model = PPO("MlpPolicy", env, verbose=1)
+    model.learn(total_timesteps=10000)  # Adjust as needed
+
+    # Create and run the visualization
+    viz = CarVisualization(env, model)
+    viz.run_visualization()
+
+if __name__ == "__main__":
+    main()

isopro/car_simulator/llm_main.py

@@ -0,0 +1,74 @@
+import argparse
+import os
+from stable_baselines3 import PPO
+from stable_baselines3.common.vec_env import DummyVecEnv
+from .car_llm_agent import LLMCarRLWrapper
+from .car_rl_environment import CarRLEnvironment 
+from .carviz import CarVisualization
+from stable_baselines3.common.evaluation import evaluate_policy
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(description="Car RL Simulation with LLM Integration and Visualization")
+    parser.add_argument("--num_cars", type=int, default=3, help="Number of cars in the simulation")
+    parser.add_argument("--time_of_day", type=str, default="08:00", help="Initial time of day (HH:MM format)")
+    parser.add_argument("--is_rainy", action="store_true", help="Set initial weather to rainy")
+    parser.add_argument("--is_weekday", action="store_true", help="Set initial day to weekday")
+    parser.add_argument("--train_steps", type=int, default=100000, help="Number of training steps")
+    parser.add_argument("--visualize_episodes", type=int, default=5, help="Number of episodes to visualize")
+    parser.add_argument("--load_model", type=str, help="Path to a pre-trained model to load")
+    parser.add_argument("--llm_call_limit", type=int, default=1000, help="Maximum number of LLM API calls")
+    parser.add_argument("--llm_call_frequency", type=int, default=100, help="Frequency of LLM calls (in steps)")
+    return parser.parse_args()
+
+def make_env(num_cars, time_of_day, is_rainy, is_weekday, llm_call_limit, llm_call_frequency):
+    def _init():
+        return LLMCarRLWrapper(num_cars=num_cars, time_of_day=time_of_day, is_rainy=is_rainy, 
+                               is_weekday=is_weekday, llm_call_limit=llm_call_limit, 
+                               llm_call_frequency=llm_call_frequency)
+    return _init
+
+def train_and_evaluate(env, total_timesteps, eval_episodes=10):
+    model = PPO("MlpPolicy", env, verbose=1, learning_rate=0.0003, n_steps=2048, 
+                batch_size=64, n_epochs=10, gamma=0.99, gae_lambda=0.95, clip_range=0.2)
+
+    model.learn(total_timesteps=total_timesteps, progress_bar=True)
+
+    mean_reward, std_reward = evaluate_policy(model, env, n_eval_episodes=eval_episodes)
+    print(f"Mean reward: {mean_reward:.2f} +/- {std_reward:.2f}")
+
+    return model, mean_reward
+
+def main():
+    args = parse_arguments()
+
+    # Ensure the ANTHROPIC_API_KEY is set
+    if not os.getenv('ANTHROPIC_API_KEY'):
+        raise ValueError("ANTHROPIC_API_KEY not found in environment variables")
+
+    # Create the vectorized environment with LLM integration
+    env = DummyVecEnv([make_env(args.num_cars, args.time_of_day, args.is_rainy, args.is_weekday, 
+                                args.llm_call_limit, args.llm_call_frequency)])
+
+    # Create or load the RL agent
+    if args.load_model and os.path.exists(args.load_model):
+        print(f"Loading pre-trained model from {args.load_model}")
+        model = PPO.load(args.load_model, env=env)
+    else:
+        print("Creating and training a new model")
+        model, mean_reward = train_and_evaluate(env, total_timesteps=args.train_steps)
+        
+        # Save the trained model
+        model.save("car_rl_llm_model")
+        print("Model saved as car_rl_llm_model")
+        print(f"Final mean reward: {mean_reward:.2f}")
+
+    # Run the visualization
+    viz = CarVisualization(env, model)
+    viz.run_visualization(num_episodes=args.visualize_episodes)
+
+if __name__ == "__main__":
+    main()

isopro/car_simulator/main.py

@@ -0,0 +1,48 @@
+import argparse
+import os
+from stable_baselines3 import PPO
+from stable_baselines3.common.vec_env import DummyVecEnv
+from .car_rl_environment import CarRLEnvironment
+from .carviz import CarVisualization
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(description="Car RL Simulation and Visualization")
+    parser.add_argument("--num_cars", type=int, default=3, help="Number of cars in the simulation")
+    parser.add_argument("--time_of_day", type=str, default="08:00", help="Initial time of day (HH:MM format)")
+    parser.add_argument("--is_rainy", action="store_true", help="Set initial weather to rainy")
+    parser.add_argument("--is_weekday", action="store_true", help="Set initial day to weekday")
+    parser.add_argument("--train_steps", type=int, default=10000, help="Number of training steps")
+    parser.add_argument("--visualize_episodes", type=int, default=5, help="Number of episodes to visualize")
+    parser.add_argument("--load_model", type=str, help="Path to a pre-trained model to load")
+    return parser.parse_args()
+
+def make_env(num_cars, time_of_day, is_rainy, is_weekday):
+    def _init():
+        return CarRLEnvironment(num_cars=num_cars, time_of_day=time_of_day, is_rainy=is_rainy, is_weekday=is_weekday)
+    return _init
+
+def main():
+    args = parse_arguments()
+
+    # Create the vectorized environment
+    env = DummyVecEnv([make_env(args.num_cars, args.time_of_day, args.is_rainy, args.is_weekday)])
+
+    # Create or load the RL agent
+    if args.load_model and os.path.exists(args.load_model):
+        print(f"Loading pre-trained model from {args.load_model}")
+        model = PPO.load(args.load_model, env=env)
+    else:
+        print("Creating and training a new model")
+        model = PPO("MlpPolicy", env, verbose=1)
+        model.learn(total_timesteps=args.train_steps)
+        
+        # Save the trained model
+        model.save("car_rl_model")
+        print("Model saved as car_rl_model")
+
+    # Run the visualization
+    viz = CarVisualization(env, model)
+    viz.run_visualization(num_episodes=args.visualize_episodes)
+
+if __name__ == "__main__":
+    main()

isopro/conversation_simulation/README.md

@@ -0,0 +1,252 @@
+# Conversation Simulator
+
+This module is part of the `isopro` package and simulates conversations between an AI assistant (either Claude or GPT-4) and various user personas. It's designed to test and demonstrate how the AI handles different types of customer service scenarios.
+
+## Project Structure
+
+The Conversation Simulator is located in the `conversation_simulator` folder within the `isopro` package:
+
+```
+isopro/
+└── conversation_simulator/
+    ├── main.py
+    ├── conversation_simulator.ipynb
+    ├── conversation_agent.py
+    ├── conversation_environment.py
+    ├── custom_persona.py
+    └── user_personas.py
+```
+
+## Prerequisites
+
+Before you begin, ensure you have met the following requirements:
+
+* You have installed Python 3.7 or later.
+* You have an Anthropic API key (for Claude) and/or an OpenAI API key (for GPT-4).
+* You have installed the `isopro` package.
+* For the Jupyter notebook, you have Jupyter Notebook or JupyterLab installed.
+
+## Setting up the Conversation Simulator
+
+1. If you haven't already, install the `isopro` package:
+   ```
+   pip install isopro
+   ```
+
+2. Create a `.env` file in your project root and add your API keys:
+   ```
+   ANTHROPIC_API_KEY=your_anthropic_api_key_here
+   OPENAI_API_KEY=your_openai_api_key_here
+   ```
+
+## Running the Conversation Simulator
+
+You can run the Conversation Simulator either as a Python script or interactively using a Jupyter notebook.
+
+### Using the Python Script
+
+1. Basic usage:
+   ```python
+   from isopro.conversation_simulator.main import main
+
+   if __name__ == "__main__":
+       main()
+   ```
+
+2. Running from the command line:
+   ```
+   python -m isopro.conversation_simulator.main
+   ```
+
+### Using the Jupyter Notebook
+
+Navigate to the `isopro/conversation_simulator/` directory and open the `conversation_simulator.ipynb` file using Jupyter Notebook or JupyterLab. Here's what you'll find in the notebook:
+
+```python
+# Conversation Simulator Jupyter Notebook
+
+## Setup
+
+import logging
+from logging.handlers import RotatingFileHandler
+import os
+from datetime import datetime
+from dotenv import load_dotenv
+from isopro.conversation_simulation.conversation_simulator import ConversationSimulator
+from isopro.conversation_simulation.custom_persona import create_custom_persona
+
+# Load environment variables
+load_dotenv()
+
+# Set up logging
+log_directory = "logs"
+os.makedirs(log_directory, exist_ok=True)
+log_file = os.path.join(log_directory, "conversation_simulator.log")
+
+# Create a rotating file handler
+file_handler = RotatingFileHandler(log_file, maxBytes=1024*1024, backupCount=5)
+file_handler.setLevel(logging.DEBUG)
+file_formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
+file_handler.setFormatter(file_formatter)
+
+# Create a console handler
+console_handler = logging.StreamHandler()
+console_handler.setLevel(logging.INFO)
+console_formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
+console_handler.setFormatter(console_formatter)
+
+# Set up the logger
+logger = logging.getLogger()
+logger.setLevel(logging.DEBUG)
+logger.addHandler(file_handler)
+logger.addHandler(console_handler)
+
+print("Setup complete.")
+
+## Helper Functions
+
+def save_output(content, filename):
+    """Save the output content to a file."""
+    with open(filename, 'w', encoding='utf-8') as f:
+        f.write(content)
+
+def get_user_choice():
+    """Get user's choice of AI model."""
+    while True:
+        choice = input("Choose AI model (claude/openai): ").lower()
+        if choice in ['claude', 'openai']:
+            return choice
+        print("Invalid choice. Please enter 'claude' or 'openai'.")
+
+print("Helper functions defined.")
+
+## Main Simulation Function
+
+def run_simulation():
+    # Get user's choice of AI model
+    ai_choice = get_user_choice()
+
+    # Set up the appropriate model and API key
+    if ai_choice == 'claude':
+        model = "claude-3-opus-20240229"
+        os.environ["ANTHROPIC_API_KEY"] = os.getenv("ANTHROPIC_API_KEY")
+        ai_name = "Claude"
+    else:  # openai
+        model = "gpt-4-1106-preview"
+        os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")
+        ai_name = "GPT-4 Turbo"
+
+    # Initialize the ConversationSimulator
+    simulator = ConversationSimulator(
+        ai_prompt=f"You are {ai_name}, an AI assistant created to be helpful, harmless, and honest. You are a customer service agent for a tech company. Respond politely and professionally."
+    )
+
+    output_content = f"Conversation Simulator using {ai_name} model: {model}\n\n"
+
+    # Run simulations with different personas
+    personas = ["upset", "human_request", "inappropriate", "incomplete_info"]
+    
+    for persona in personas:
+        logger.info(f"Running simulation with {persona} persona using {ai_name}")
+        conversation_history = simulator.run_simulation(persona, num_turns=3)
+        
+        output_content += f"\nConversation with {persona} persona:\n"
+        for message in conversation_history:
+            output_line = f"{message['role'].capitalize()}: {message['content']}\n"
+            output_content += output_line
+            logger.debug(output_line.strip())
+        output_content += "\n" + "-"*50 + "\n"
+
+    # Create and run a simulation with a custom persona
+    custom_persona_name = "Techie Customer"
+    custom_characteristics = ["tech-savvy", "impatient", "detail-oriented"]
+    custom_message_templates = [
+        "I've tried rebooting my device, but the error persists. Can you help?",
+        "What's the latest update on the cloud service outage?",
+        "I need specifics on the API rate limits for the enterprise plan.",
+        "The latency on your servers is unacceptable. What's being done about it?",
+        "Can you explain the technical details of your encryption method?"
+    ]
+
+    logger.info(f"Running simulation with custom persona: {custom_persona_name} using {ai_name}")
+    custom_conversation = simulator.run_custom_simulation(
+        custom_persona_name,
+        custom_characteristics,
+        custom_message_templates,
+        num_turns=3
+    )
+
+    output_content += f"\nConversation with {custom_persona_name}:\n"
+    for message in custom_conversation:
+        output_line = f"{message['role'].capitalize()}: {message['content']}\n"
+        output_content += output_line
+        logger.debug(output_line.strip())
+
+    # Save the output to a file
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    output_directory = "output"
+    os.makedirs(output_directory, exist_ok=True)
+    output_file = os.path.join(output_directory, f"{ai_name.lower()}_conversation_output_{timestamp}.txt")
+    save_output(output_content, output_file)
+    logger.info(f"Output saved to {output_file}")
+
+    return output_content
+
+print("Main simulation function defined.")
+
+## Run the Simulation
+
+simulation_output = run_simulation()
+print(simulation_output)
+
+## Analyze the Results
+
+# Example analysis: Count the number of apologies
+apology_count = simulation_output.lower().count("sorry") + simulation_output.lower().count("apologi")
+print(f"Number of apologies: {apology_count}")
+
+# Example analysis: Average length of AI responses
+ai_responses = [line.split(": ", 1)[1] for line in simulation_output.split("\n") if line.startswith("Assistant: ")]
+avg_response_length = sum(len(response.split()) for response in ai_responses) / len(ai_responses)
+print(f"Average length of AI responses: {avg_response_length:.2f} words")
+
+## Conclusion
+
+# This notebook demonstrates how to use the Conversation Simulator from the isopro package. 
+# You can modify the personas, adjust the number of turns, or add your own analysis to 
+# further explore the capabilities of the AI models in customer service scenarios.
+```
+
+## Output and Logs
+
+- Simulation outputs are saved in the `output` directory within your current working directory.
+- Logs are saved in the `logs` directory within your current working directory.
+
+## Customizing the Simulation
+
+You can customize the simulation by modifying the `main.py` file or the Jupyter notebook:
+
+- To change the predefined personas, modify the `personas` list.
+- To adjust the custom persona, modify the `custom_persona_name`, `custom_characteristics`, and `custom_message_templates` variables.
+- To change the number of turns in each conversation, modify the `num_turns` parameter in the `run_simulation` and `run_custom_simulation` method calls.
+
+In the Jupyter notebook, you can also add new cells for additional analysis or visualization of the results.
+
+## Troubleshooting
+
+If you encounter any issues:
+
+1. Make sure your API keys are correctly set in the `.env` file or environment variables.
+2. Check the logs in the `logs` directory for detailed error messages.
+3. Ensure you have the latest version of the `isopro` package installed.
+4. For Jupyter notebook issues, make sure you have Jupyter installed and are running the notebook from the correct directory.
+
+If problems persist, please open an issue in the project repository.
+
+## Contributing
+
+Contributions to the Conversation Simulator are welcome. Please feel free to submit a Pull Request to the `isopro` repository.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file in the `isopro` package for details.

isopro/conversation_simulation/__init__.py

@@ -0,0 +1,19 @@
+"""
+Conversation Simulation Module
+
+This module provides tools for simulating conversations with AI agents.
+"""
+
+from .conversation_environment import ConversationEnvironment
+from .conversation_agent import ConversationAgent
+from .user_personas import UserPersona
+from .custom_persona import create_custom_persona
+from .conversation_simulator import ConversationSimulator
+
+__all__ = [
+    "ConversationEnvironment",
+    "ConversationAgent",
+    "UserPersona",
+    "create_custom_persona",
+    "ConversationSimulator",
+]

isopro/conversation_simulation/conversation_agent.py

@@ -0,0 +1,41 @@
+"""
+Conversation Agent
+
+This module defines the AI agent used in the conversation simulation, using Anthropic's Claude API.
+"""
+
+import anthropic
+import os
+import logging
+from ..agents.ai_agent import AI_Agent
+from dotenv import load_dotenv
+
+logger = logging.getLogger(__name__)
+
+load_dotenv()
+
+class ConversationAgent(AI_Agent):
+    def __init__(self, name, prompt, model="claude-3-opus-20240229"):
+        super().__init__(name)
+        self.prompt = prompt
+        self.model = model
+        self.client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+        logger.info(f"Initialized ConversationAgent '{name}' with Claude model {model}")
+
+    def generate_response(self, conversation_history):
+        try:
+            messages = [{"role": "user" if msg["role"] != "assistant" else "assistant", "content": msg["content"]} 
+                        for msg in conversation_history]
+            
+            response = self.client.messages.create(
+                model=self.model,
+                max_tokens=1000,
+                system=self.prompt,
+                messages=messages
+            )
+            ai_message = response.content[0].text.strip()
+            logger.debug(f"Generated response: {ai_message}")
+            return ai_message
+        except Exception as e:
+            logger.error(f"Error generating response: {e}")
+            return "I apologize, but I'm having trouble responding at the moment."

isopro/conversation_simulation/conversation_environment.py

@@ -0,0 +1,78 @@
+"""
+Conversation Environment
+
+This module defines the environment for simulating conversations between a Claude-based AI agent and users with various personas.
+"""
+
+import logging
+from ..environments.simulation_environment import SimulationEnvironment
+from .conversation_agent import ConversationAgent
+from .user_personas import UserPersona
+
+logger = logging.getLogger(__name__)
+
+class ConversationEnvironment(SimulationEnvironment):
+    """
+    ConversationEnvironment
+
+    This class provides an environment for simulating conversations between Claude-based AI agents and users with various personas.
+    """
+
+    def __init__(self, ai_prompt="You are a helpful customer service agent. Respond politely and professionally."):
+        """
+        Initialize the ConversationEnvironment.
+
+        Args:
+            ai_prompt (str): The prompt to guide the AI agent's behavior.
+        """
+        super().__init__()
+        self.ai_prompt = ai_prompt
+        self.ai_agent = None
+        self.user_persona = None
+        logger.info("Initialized ConversationEnvironment")
+
+    def set_ai_agent(self, model="claude-3-opus-20240229"):
+        """
+        Set up the Claude-based AI agent for the conversation.
+
+        Args:
+            model (str): The name of the Claude model to use.
+        """
+        self.ai_agent = ConversationAgent("Customer Service AI", self.ai_prompt, model)
+        logger.info(f"Set AI agent with Claude model: {model}")
+    def set_user_persona(self, persona_type, **kwargs):
+        """
+        Set the user persona for the conversation.
+
+        Args:
+            persona_type (str): The type of user persona to use.
+            **kwargs: Additional arguments for the user persona.
+        """
+        self.user_persona = UserPersona.create(persona_type, **kwargs)
+        logger.info(f"Set user persona: {persona_type}")
+
+    def run_conversation(self, num_turns=5):
+        """
+        Run a conversation between the AI agent and the user persona.
+
+        Args:
+            num_turns (int): The number of conversation turns to simulate.
+
+        Returns:
+            list: A list of dictionaries containing the conversation history.
+        """
+        if not self.ai_agent or not self.user_persona:
+            raise ValueError("Both AI agent and user persona must be set before running a conversation.")
+
+        conversation_history = []
+        for _ in range(num_turns):
+            user_message = self.user_persona.generate_message(conversation_history)
+            conversation_history.append({"role": "user", "content": user_message})
+            logger.debug(f"User: {user_message}")
+
+            ai_response = self.ai_agent.generate_response(conversation_history)
+            conversation_history.append({"role": "assistant", "content": ai_response})
+            logger.debug(f"AI: {ai_response}")
+
+        logger.info("Completed conversation simulation")
+        return conversation_history

isopro/conversation_simulation/conversation_simulator.py

@@ -0,0 +1,67 @@
+"""
+Conversation Simulator
+
+This module provides a high-level interface for running conversation simulations
+with different personas and analyzing the results using Anthropic's Claude API.
+"""
+
+import logging
+from .conversation_environment import ConversationEnvironment
+from .custom_persona import create_custom_persona
+
+logger = logging.getLogger(__name__)
+
+class ConversationSimulator:
+    """
+    ConversationSimulator orchestrates conversation simulations with various personas using Claude.
+    """
+
+    def __init__(self, ai_prompt="You are a helpful customer service agent. Respond politely and professionally."):
+        """
+        Initialize the ConversationSimulator.
+
+        Args:
+            ai_prompt (str): The prompt to guide the Claude-based AI agent's behavior.
+        """
+        self.environment = ConversationEnvironment(ai_prompt)
+        logger.info("Initialized ConversationSimulator with Claude")
+
+    def run_simulation(self, persona_type, num_turns=5, claude_model="claude-3-opus-20240229", **persona_kwargs):
+        """
+        Run a conversation simulation with a specified persona using Claude.
+
+        Args:
+            persona_type (str): The type of persona to use in the simulation.
+            num_turns (int): The number of conversation turns to simulate.
+            claude_model (str): The specific Claude model to use for the simulation.
+            **persona_kwargs: Additional arguments for creating the persona.
+
+        Returns:
+            list: A list of dictionaries containing the conversation history.
+        """
+        self.environment.set_ai_agent(model=claude_model)
+        self.environment.set_user_persona(persona_type, **persona_kwargs)
+        conversation_history = self.environment.run_conversation(num_turns)
+        logger.info(f"Completed simulation with {persona_type} persona using Claude model {claude_model}")
+        return conversation_history
+
+    def run_custom_simulation(self, name, characteristics, message_templates, num_turns=5, claude_model="claude-3-opus-20240229"):
+        """
+        Run a conversation simulation with a custom persona using Claude.
+
+        Args:
+            name (str): The name of the custom persona.
+            characteristics (list): A list of characteristics that define the persona.
+            message_templates (list): A list of message templates the persona can use.
+            num_turns (int): The number of conversation turns to simulate.
+            claude_model (str): The specific Claude model to use for the simulation.
+
+        Returns:
+            list: A list of dictionaries containing the conversation history.
+        """
+        custom_persona = create_custom_persona(name, characteristics, message_templates)
+        self.environment.set_ai_agent(model=claude_model)
+        self.environment.user_persona = custom_persona
+        conversation_history = self.environment.run_conversation(num_turns)
+        logger.info(f"Completed simulation with custom persona: {name} using Claude model {claude_model}")
+        return conversation_history

isopro/conversation_simulation/custom_persona.py

@@ -0,0 +1,58 @@
+"""
+Custom Persona
+
+This module allows users to create custom personas for the conversation simulation.
+"""
+
+import logging
+from .user_personas import UserPersona
+
+logger = logging.getLogger(__name__)
+
+class CustomPersona(UserPersona):
+    """
+    CustomPersona allows users to create their own persona with specific characteristics.
+    """
+
+    def __init__(self, name, characteristics, message_templates):
+        """
+        Initialize the CustomPersona.
+
+        Args:
+            name (str): The name of the custom persona.
+            characteristics (list): A list of characteristics that define the persona.
+            message_templates (list): A list of message templates the persona can use.
+        """
+        super().__init__(name)
+        self.characteristics = characteristics
+        self.message_templates = message_templates
+        logger.info(f"Created CustomPersona: {name}")
+
+    def generate_message(self, conversation_history):
+        """
+        Generate a message based on the custom persona's characteristics and templates.
+
+        Args:
+            conversation_history (list): A list of dictionaries containing the conversation history.
+
+        Returns:
+            str: The generated message.
+        """
+        import random
+        message = random.choice(self.message_templates)
+        logger.debug(f"CustomPersona '{self.name}' generated message: {message}")
+        return message
+
+def create_custom_persona(name, characteristics, message_templates):
+    """
+    Create a custom persona with the given characteristics and message templates.
+
+    Args:
+        name (str): The name of the custom persona.
+        characteristics (list): A list of characteristics that define the persona.
+        message_templates (list): A list of message templates the persona can use.
+
+    Returns:
+        CustomPersona: An instance of the custom persona.
+    """
+    return CustomPersona(name, characteristics, message_templates)

isopro/conversation_simulation/main.py

@@ -0,0 +1,117 @@
+import logging
+from logging.handlers import RotatingFileHandler
+import os
+from datetime import datetime
+from dotenv import load_dotenv
+from .conversation_simulator import ConversationSimulator
+from .custom_persona import create_custom_persona
+
+# Load environment variables
+load_dotenv()
+
+# Set up logging
+log_directory = "logs"
+os.makedirs(log_directory, exist_ok=True)
+log_file = os.path.join(log_directory, "conversation_simulator.log")
+
+# Create a rotating file handler
+file_handler = RotatingFileHandler(log_file, maxBytes=1024*1024, backupCount=5)
+file_handler.setLevel(logging.DEBUG)
+file_formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
+file_handler.setFormatter(file_formatter)
+
+# Create a console handler
+console_handler = logging.StreamHandler()
+console_handler.setLevel(logging.INFO)
+console_formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
+console_handler.setFormatter(console_formatter)
+
+# Set up the logger
+logger = logging.getLogger()
+logger.setLevel(logging.DEBUG)
+logger.addHandler(file_handler)
+logger.addHandler(console_handler)
+
+def save_output(content, filename):
+    """Save the output content to a file."""
+    with open(filename, 'w', encoding='utf-8') as f:
+        f.write(content)
+
+def get_user_choice():
+    """Get user's choice of AI model."""
+    while True:
+        choice = input("Choose AI model (claude/openai): ").lower()
+        if choice in ['claude', 'openai']:
+            return choice
+        print("Invalid choice. Please enter 'claude' or 'openai'.")
+
+def main():
+    # Get user's choice of AI model
+    ai_choice = get_user_choice()
+
+    # Set up the appropriate model and API key
+    if ai_choice == 'claude':
+        model = "claude-3-opus-20240229"
+        os.environ["ANTHROPIC_API_KEY"] = os.getenv("ANTHROPIC_API_KEY")
+        ai_name = "Claude"
+    else:  # openai
+        model = "gpt-4-1106-preview"
+        os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")
+        ai_name = "GPT-4 Turbo"
+
+    # Initialize the ConversationSimulator
+    simulator = ConversationSimulator(
+        ai_prompt=f"You are {ai_name}, an AI assistant created to be helpful, harmless, and honest. You are a customer service agent for a tech company. Respond politely and professionally."
+    )
+
+    output_content = f"Conversation Simulator using {ai_name} model: {model}\n\n"
+
+    # Run simulations with different personas
+    personas = ["upset", "human_request", "inappropriate", "incomplete_info"]
+    
+    for persona in personas:
+        logger.info(f"Running simulation with {persona} persona using {ai_name}")
+        conversation_history = simulator.run_simulation(persona, num_turns=3)
+        
+        output_content += f"\nConversation with {persona} persona:\n"
+        for message in conversation_history:
+            output_line = f"{message['role'].capitalize()}: {message['content']}\n"
+            output_content += output_line
+            logger.debug(output_line.strip())
+        output_content += "\n" + "-"*50 + "\n"
+
+    # Create and run a simulation with a custom persona
+    custom_persona_name = "Techie Customer"
+    custom_characteristics = ["tech-savvy", "impatient", "detail-oriented"]
+    custom_message_templates = [
+        "I've tried rebooting my device, but the error persists. Can you help?",
+        "What's the latest update on the cloud service outage?",
+        "I need specifics on the API rate limits for the enterprise plan.",
+        "The latency on your servers is unacceptable. What's being done about it?",
+        "Can you explain the technical details of your encryption method?"
+    ]
+
+    logger.info(f"Running simulation with custom persona: {custom_persona_name} using {ai_name}")
+    custom_conversation = simulator.run_custom_simulation(
+        custom_persona_name,
+        custom_characteristics,
+        custom_message_templates,
+        num_turns=3
+    )
+
+    output_content += f"\nConversation with {custom_persona_name}:\n"
+    for message in custom_conversation:
+        output_line = f"{message['role'].capitalize()}: {message['content']}\n"
+        output_content += output_line
+        logger.debug(output_line.strip())
+
+    # Save the output to a file
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    output_directory = "output"
+    os.makedirs(output_directory, exist_ok=True)
+    output_file = os.path.join(output_directory, f"{ai_name.lower()}_conversation_output_{timestamp}.txt")
+    save_output(output_content, output_file)
+    logger.info(f"Output saved to {output_file}")
+
+if __name__ == "__main__":
+    main()

isopro/conversation_simulation/user_personas.py

@@ -0,0 +1,112 @@
+"""
+User Personas
+
+This module defines various user personas for the conversation simulation.
+"""
+
+import random
+import logging
+
+logger = logging.getLogger(__name__)
+
+class UserPersona:
+    """
+    Base class for user personas in the conversation simulation.
+    """
+
+    def __init__(self, name):
+        self.name = name
+
+    def generate_message(self, conversation_history):
+        """
+        Generate a message based on the persona and conversation history.
+
+        Args:
+            conversation_history (list): A list of dictionaries containing the conversation history.
+
+        Returns:
+            str: The generated message.
+        """
+        raise NotImplementedError("Subclasses must implement generate_message method")
+
+    @staticmethod
+    def create(persona_type, **kwargs):
+        """
+        Factory method to create user personas.
+
+        Args:
+            persona_type (str): The type of user persona to create.
+            **kwargs: Additional arguments for the user persona.
+
+        Returns:
+            UserPersona: An instance of the specified user persona.
+        """
+        persona_classes = {
+            "upset": UpsetCustomer,
+            "human_request": HumanRequestCustomer,
+            "inappropriate": InappropriateCustomer,
+            "incomplete_info": IncompleteInfoCustomer,
+        }
+
+        if persona_type not in persona_classes:
+            raise ValueError(f"Unknown persona type: {persona_type}")
+
+        return persona_classes[persona_type](**kwargs)
+
+class UpsetCustomer(UserPersona):
+    def __init__(self):
+        super().__init__("Upset Customer")
+        self.complaints = [
+            "This is unacceptable!",
+            "I've been waiting for hours!",
+            "I want to speak to your manager!",
+            "This is the worst service I've ever experienced!",
+            "I'm extremely disappointed with your company!",
+        ]
+
+    def generate_message(self, conversation_history):
+        message = random.choice(self.complaints)
+        logger.debug(f"UpsetCustomer generated message: {message}")
+        return message
+
+class HumanRequestCustomer(UserPersona):
+    def __init__(self):
+        super().__init__("Human Request Customer")
+        self.requests = [
+            "Can I speak to a human representative?",
+            "I don't want to talk to a bot. Get me a real person.",
+            "Is there a way to talk to an actual employee?",
+            "I need to speak with a human agent, not an AI.",
+            "Please transfer me to a live representative.",
+        ]
+
+    def generate_message(self, conversation_history):
+        message = random.choice(self.requests)
+        logger.debug(f"HumanRequestCustomer generated message: {message}")
+        return message
+
+class InappropriateCustomer(UserPersona):
+    def __init__(self):
+        super().__init__("Inappropriate Customer")
+        self.inappropriate_words = ["[INAPPROPRIATE1]", "[INAPPROPRIATE2]", "[INAPPROPRIATE3]"]
+
+    def generate_message(self, conversation_history):
+        message = f"You're a {random.choice(self.inappropriate_words)} and this service is {random.choice(self.inappropriate_words)}!"
+        logger.debug(f"InappropriateCustomer generated message: {message}")
+        return message
+
+class IncompleteInfoCustomer(UserPersona):
+    def __init__(self):
+        super().__init__("Incomplete Info Customer")
+        self.vague_requests = [
+            "I need help with my account.",
+            "There's a problem with my order.",
+            "Something's not working right.",
+            "I have a question about your service.",
+            "Can you check on the status of my thing?",
+        ]
+
+    def generate_message(self, conversation_history):
+        message = random.choice(self.vague_requests)
+        logger.debug(f"IncompleteInfoCustomer generated message: {message}")
+        return message

isopro/environments/__init__.py

@@ -0,0 +1,9 @@
+"""
+Environment classes for the isopro package.
+"""
+
+from .simulation_environment import SimulationEnvironment
+from .custom_environment import CustomEnvironment
+from .llm_orchestrator import LLMOrchestrator
+
+__all__ = ["SimulationEnvironment", "CustomEnvironment", "LLMOrchestrator"]

isopro/environments/custom_environment.py

@@ -0,0 +1,108 @@
+"""Custom Environment for creating user-defined simulation environments."""
+from ..environments.simulation_environment import SimulationEnvironment
+from ..agents.ai_agent import AI_Agent
+from ..base.base_component import BaseComponent, agent_component
+
+class CustomAgent(AI_Agent):
+    """
+    CustomAgent
+
+    This class defines a custom agent. Users can extend this class to implement their own agents.
+    """
+    def __init__(self, name, custom_param):
+        """
+        Initialize the CustomAgent.
+
+        Args:
+            name (str): The name of the agent.
+            custom_param: A custom parameter for the agent.
+        """
+        super().__init__(name)
+        self.custom_param = custom_param
+
+    def run(self, input_data):
+        """
+        Run the custom agent.
+
+        Args:
+            input_data (dict): The input data for the agent.
+
+        Returns:
+            dict: The processed output data.
+        """
+        self.logger.info(f"Running custom agent: {self.name} with parameter: {self.custom_param}")
+        # Implement custom behavior here
+        return super().run(input_data)
+
+@agent_component
+class CustomComponent(BaseComponent):
+    """
+    CustomComponent
+
+    This class defines a custom component. Users can extend this class to implement their own components.
+    """
+    def __init__(self, name, custom_param):
+        """
+        Initialize the CustomComponent.
+
+        Args:
+            name (str): The name of the component.
+            custom_param: A custom parameter for the component.
+        """
+        super().__init__(name)
+        self.custom_param = custom_param
+
+    def run(self, input_data):
+        """
+        Run the custom component.
+
+        Args:
+            input_data (dict): The input data for the component.
+
+        Returns:
+            dict: The processed output data.
+        """
+        self.logger.info(f"Running custom component: {self.name} with parameter: {self.custom_param}")
+        # Implement custom behavior here
+        return input_data
+
+class CustomEnvironment(SimulationEnvironment):
+    """
+    CustomEnvironment
+
+    This class provides a template for creating a custom training environment.
+    Users can define their own agents and components, and integrate them into the simulation environment.
+    """
+    def __init__(self, num_agents=1, custom_param=None):
+        """
+        Initialize the CustomEnvironment.
+
+        Args:
+            num_agents (int): The number of agents to create.
+            custom_param: A custom parameter for the environment.
+        """
+        super().__init__()
+        self.num_agents = num_agents
+        self.custom_param = custom_param
+        self._create_custom_agents()
+
+    def _create_custom_agents(self):
+        """Create custom agents and add them to the environment."""
+        for i in range(self.num_agents):
+            agent = CustomAgent(name=f"Custom Agent {i+1}", custom_param=self.custom_param)
+            component = CustomComponent(name=f"Custom Component {i+1}", custom_param=self.custom_param)
+            agent.add_component(component)
+            self.add_agent(agent)
+
+    def add_custom_agent(self, agent_name, custom_param):
+        """
+        Add a custom agent to the environment.
+
+        Args:
+            agent_name (str): The name of the agent.
+            custom_param: A custom parameter for the agent.
+        """
+        agent = CustomAgent(name=agent_name, custom_param=custom_param)
+        component = CustomComponent(name=f"Component for {agent_name}", custom_param=custom_param)
+        agent.add_component(component)
+        self.add_agent(agent)

isopro/environments/llm_orchestrator.py

@@ -0,0 +1,194 @@
+"""
+LLM Orchestrator for managing and executing LLM components in various modes.
+"""
+
+import logging
+import heapq
+from concurrent.futures import ThreadPoolExecutor
+from typing import List, Any, Optional, Callable
+from ..base.base_component import BaseComponent
+
+logger = logging.getLogger(__name__)
+
+class ComponentException(Exception):
+    """Custom exception for component-related errors."""
+    pass
+
+class LLMOrchestrator:
+    """
+    LLMOrchestrator manages and executes LLM components in various modes:
+    sequential, parallel, or priority-based node execution.
+    """
+
+    def __init__(self):
+        """Initialize the LLMOrchestrator with an empty list of components."""
+        self.components: List[BaseComponent] = []
+        self.priority_function: Optional[Callable[[BaseComponent, Any], int]] = None
+
+    def add_component(self, component: BaseComponent) -> None:
+        """
+        Add a component to the orchestrator.
+
+        Args:
+            component (BaseComponent): The component to be added.
+
+        Raises:
+            ValueError: If the component is None or not an instance of BaseComponent.
+        """
+        if component is None:
+            raise ValueError("Cannot add None as a component")
+        if not isinstance(component, BaseComponent):
+            raise ValueError(f"Only BaseComponent instances can be added, got {type(component)}")
+        self.components.append(component)
+
+    def set_priority_function(self, priority_func: Callable[[BaseComponent, Any], int]) -> None:
+        """
+        Set the priority function for node-based execution.
+
+        Args:
+            priority_func (Callable[[BaseComponent, Any], int]): A function that takes a component
+                and input data, and returns an integer priority value.
+        """
+        self.priority_function = priority_func
+
+    def run_orchestration(self, mode: str = 'sequence', input_data: Optional[Any] = None) -> List[Any]:
+        """
+        Run the orchestration in the specified mode.
+
+        Args:
+            mode (str): The execution mode ('sequence', 'parallel', or 'node').
+            input_data (Any, optional): The initial input data for the components.
+
+        Returns:
+            List[Any]: The results from all components.
+
+        Raises:
+            ValueError: If an invalid execution mode is specified.
+        """
+        if not self.components:
+            logger.warning("No components to run")
+            return []
+
+        if mode == 'sequence':
+            return self._run_in_sequence(input_data)
+        elif mode == 'parallel':
+            return self._run_in_parallel(input_data)
+        elif mode == 'node':
+            return self._run_as_node(input_data)
+        else:
+            raise ValueError("Invalid execution mode")
+
+    def _run_in_sequence(self, input_data: Any) -> List[Any]:
+        """
+        Run components sequentially, passing the output of each as input to the next.
+
+        Args:
+            input_data (Any): The initial input data for the first component.
+
+        Returns:
+            List[Any]: The results from all components.
+        """
+        logger.info("Running in sequence mode")
+        results = []
+        current_input = input_data
+
+        for component in self.components:
+            try:
+                result = self._run_component(component, current_input)
+                results.append(result)
+                current_input = result  # Use the output as input for the next component
+            except ComponentException as e:
+                logger.error(f"Error: {e}")
+                results.append(str(e))
+
+        return results
+
+    def _run_in_parallel(self, input_data: Any) -> List[Any]:
+        """
+        Run components in parallel, providing the same input to all components.
+
+        Args:
+            input_data (Any): The input data for all components.
+
+        Returns:
+            List[Any]: The results from all components.
+        """
+        logger.info("Running in parallel mode")
+        results = []
+
+        with ThreadPoolExecutor() as executor:
+            futures = [executor.submit(self._run_component, component, input_data) 
+                       for component in self.components]
+            
+            for future in futures:
+                try:
+                    result = future.result()
+                    results.append(result)
+                except ComponentException as e:
+                    logger.error(f"Error: {e}")
+                    results.append(str(e))
+
+        return results
+
+    def _run_as_node(self, input_data: Any) -> List[Any]:
+        """
+        Run components in priority-based node mode.
+
+        The priority is defined either by the LLM using reasoning on the best path
+        of solving the problem or designated by the user through the priority_function.
+
+        Args:
+            input_data (Any): The input data for all components.
+
+        Returns:
+            List[Any]: The results from all components, ordered by priority.
+        """
+        logger.info("Running in node mode (priority-based)")
+        results = []
+        
+        if self.priority_function is None:
+            logger.warning("No priority function set. Using default priority (0) for all components.")
+            priority_queue = [(0, i, component) for i, component in enumerate(self.components)]
+        else:
+            priority_queue = [(self.priority_function(component, input_data), i, component) 
+                              for i, component in enumerate(self.components)]
+        
+        heapq.heapify(priority_queue)
+        
+        while priority_queue:
+            priority, _, component = heapq.heappop(priority_queue)
+            logger.info(f"Running component {component} with priority {priority}")
+            try:
+                result = self._run_component(component, input_data)
+                results.append(result)
+                
+                # If the component changes the priority, we need to update the queue
+                if self.priority_function:
+                    new_priority = self.priority_function(component, result)
+                    if new_priority != priority:
+                        heapq.heappush(priority_queue, (new_priority, len(results), component))
+                        logger.info(f"Updated priority for component {component}: {priority} -> {new_priority}")
+                
+            except ComponentException as e:
+                logger.error(f"Error: {e}")
+                results.append(str(e))
+
+        return results
+
+    def _run_component(self, component: BaseComponent, input_data: Any) -> Any:
+        """
+        Run a single component with the given input data.
+
+        Args:
+            component (BaseComponent): The component to run.
+            input_data (Any): The input data for the component.
+
+        Returns:
+            Any: The result of running the component.
+
+        Raises:
+            ComponentException: If the component doesn't have a callable 'run' method.
+        """
+        if not hasattr(component, 'run') or not callable(component.run):
+            raise ComponentException(f"Component {component} does not have a callable 'run' method")
+        return component.run(input_data)