Feature(multi agent): new examples for multi agent

README.md

@@ -1,9 +1,12 @@
-git```
+# Tiny-Chat
+
+```
 conda create -n tiny-chat python=3.10
 conda activate tiny-chat
 curl -sSL https://install.python-poetry.org | python3
 poetry install
-
 ```
 
-```
+## What's new:
+
+1. You can find some examples [here](/tiny-chat/examples/README.md).

examples/README.md

@@ -0,0 +1,172 @@
+# Tiny-Chat Examples
+
+This directory showcases various usage examples for Tiny-Chat.
+
+## Example Files
+
+```
+examples/
+├── README.md
+├── two_agents_chat.py      # Two-agent conversation
+├── human_agent_chat.py     # Human-AI interactive chat
+└── multi_agents_chat.py    # Multi-agent conversation
+```
+
+## Running Examples
+
+### Two-Agent Conversation
+
+```bash
+python examples/two_agents_chat.py
+```
+
+### Human-AI Interactive Chat
+
+```bash
+python examples/human_agent_chat.py
+```
+
+### Multi-Agent Conversation
+
+```bash
+python examples/multi_agents_chat.py
+```
+
+## Customizing Examples
+
+You can create your own examples by modifying the following parameters:
+
+### 1. Two-Agent Conversation Customization
+
+In `two_agents_chat.py`, you can modify:
+
+```python
+# Agent configurations
+agent_configs = [
+    {
+        "name": "Your Agent 1 Name",
+        "agent_number": 1,
+        "type": "llm",
+        "model": "gpt-4o-mini",
+        "goal": "Your Agent 1 Goal",
+    },
+    {
+        "name": "Your Agent 2 Name",
+        "agent_number": 2,
+        "type": "llm",
+        "model": "gpt-4o-mini",
+        "goal": "Your Agent 2 Goal",
+    },
+]
+
+# Background settings
+background = TwoAgentChatBackground(
+    scenario="Your conversation scenario description",
+    p1_background="Agent 1 background information",
+    p2_background="Agent 2 background information",
+    p1_goal="Agent 1 specific goal",
+    p2_goal="Agent 2 specific goal",
+    p1_name="Agent 1 Name",
+    p2_name="Agent 2 Name",
+)
+
+# Conversation parameters
+await server.two_agent_run_conversation(
+    agent_configs=agent_configs,
+    background=background,
+    max_turns=10,           # Maximum conversation turns
+    enable_evaluation=True,  # Enable evaluation
+)
+```
+
+### 2. Human-AI Interaction Customization
+
+In `human_agent_chat.py`, you can modify:
+
+```python
+# AI agent configuration
+agent = LLMAgent(
+    agent_name="Your AI Assistant Name",
+    model="gpt-4o-mini",
+    api_key=api_key,
+    goal="Your AI Assistant Goal"
+)
+
+# Conversation background
+background = ChatBackground(
+    scenario="Your conversation scenario",
+    p1_background="AI Assistant background setting",
+    p2_background="User background setting",
+    p1_goal="AI Assistant goal",
+    p2_goal="User goal",
+    p1_name="AI Assistant Name",
+    p2_name="User Name"
+)
+```
+
+### 3. Multi-Agent Conversation Customization
+
+Multi-agent conversations support 4 different action ordering modes. You can assign each one in [action_order](/tiny-chat/examples/multi_agents_chat.py#L74):
+
+- **Sequential**: Agents take turns one by one in a fixed order
+- **Round-robin**: Agents take turns in a rotating order (A→B→C→A→B→C...)
+- **Simultaneous**: All agents act at the same time in each turn
+- **Random**: A random agent is selected to act in each turn
+
+## <span style="color: red;">WARNING: Simultaneous mode is Incomplete</span>
+
+In `multi_agents_chat.py`, you can modify:
+
+```python
+# Agent configurations (supports 2-3 agents)
+agent_configs = [
+    {
+        "name": "Agent 1 Name",
+        "type": "llm",
+        "model": "gpt-4o-mini",
+        "goal": "Agent 1 Goal"
+    },
+    {
+        "name": "Agent 2 Name",
+        "type": "llm",
+        "model": "gpt-4o-mini",
+        "goal": "Agent 2 Goal"
+    },
+    {
+        "name": "Agent 3 Name",
+        "type": "llm",
+        "model": "gpt-4o-mini",
+        "goal": "Agent 3 Goal"
+    }
+]
+
+background = MultiAgentChatBackground(
+    scenario="Your multi-agent scenario description",
+    agent_configs=[
+    {
+        'name': 'Agent 1 Name',
+        'background': 'Agent 1 detailed background',
+        'goal': 'Agent 1 specific goal'
+    },
+    {
+        'name': 'Agent 2 Name',
+        'background': 'Agent 2 detailed background',
+        'goal': 'Agent 2 specific goal'
+    },
+    {
+        'name': 'Agent 3 Name',
+        'background': 'Agent 3 detailed background',
+        'goal': 'Agent 3 specific goal'
+    }
+]
+)
+
+# Conversation parameters
+await server.multi_agent_run_conversation(
+    agent_configs=agent_configs,
+    background=background,
+    action_order='simultaneous', # sequential, round-robin, simultaneous, random
+    max_turns=12,           # Maximum conversation turns
+    enable_evaluation=True   # Enable evaluation
+)
+```

examples/human_agent_chat.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""
+Interactive chat script - Chat with AI agents
+Usage: python scripts/interactive_chat.py
+"""
+
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+
+from tiny_chat.agents import LLMAgent
+from tiny_chat.messages import Observation, TwoAgentChatBackground
+
+project_root = Path(__file__).parent.parent
+sys.path.insert(0, str(project_root))
+
+
+async def interactive_chat() -> None:
+    """Interactive chat with an AI agent"""
+
+    logging.getLogger().setLevel(logging.ERROR)
+    for logger_name in logging.root.manager.loggerDict:
+        logging.getLogger(logger_name).setLevel(logging.ERROR)
+
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        print("Error: OPENAI_API_KEY environment variable is required")
+        return
+
+    agent = LLMAgent(
+        agent_name="AI Assistant",
+        model="gpt-4o-mini",
+        api_key=api_key,
+        goal="Be helpful, friendly, and engaging in conversation",
+    )
+
+    _background = TwoAgentChatBackground(
+        scenario="A helpful AI assistant chatting with a human",
+        p1_background="You are a helpful AI assistant",
+        p2_background="A human user who wants to chat",
+        p1_goal="Provide helpful and engaging responses",
+        p2_goal="Have an interesting conversation",
+        p1_name="AI Assistant",
+        p2_name="Human",
+    )
+
+    print("🤖 AI Assistant: Hello! I'm your AI assistant. How can I help you today?")
+    print("(Type 'quit' or 'q' to exit)")
+    print("-" * 50)
+
+    turn_number = 1
+
+    while True:
+        user_input = input("👤 You: ").strip()
+
+        if user_input.lower() in ["quit", "exit", "bye", "q"]:
+            print("🤖 AI Assistant: Goodbye! It was nice chatting with you!")
+            break
+
+        if not user_input:
+            continue
+
+        observation = Observation(
+            last_turn=f"Human says: {user_input}",
+            available_actions=["speak", "none"],
+            turn_number=turn_number,
+        )
+
+        try:
+            action = await agent.act(observation)
+
+            if action.action_type == "speak":
+                print(f"AI Assistant: {action.argument}")
+            else:
+                print("AI Assistant: [No response]")
+
+        except Exception as e:
+            print(f"AI Assistant: Sorry, I encountered an error: {e}")
+
+        turn_number += 1
+        print("-" * 50)
+
+
+if __name__ == "__main__":
+    asyncio.run(interactive_chat())

examples/multi_agents_chat.py

@@ -0,0 +1,82 @@
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+# Add the project root to Python path
+project_root = Path(__file__).parent.parent
+sys.path.insert(0, str(project_root))
+
+from tiny_chat.messages import MultiAgentChatBackground
+from tiny_chat.utils.server import TinyChatServer
+
+
+async def main():
+    """Run a 3-agent conversation"""
+
+    # Get API key from environment variable
+    api_key = os.getenv('OPENAI_API_KEY')
+    if not api_key:
+        print('Warning: OPENAI_API_KEY not set. Some features may not work.')
+
+    # Create chat server
+    server = TinyChatServer(api_key=api_key)
+
+    # Define 3-agent configurations
+    agent_configs = [
+        {
+            'name': 'Alice',
+            'type': 'llm',
+            'model': 'gpt-4o-mini',
+            'goal': 'Talk about weekend hiking plans',
+        },
+        {
+            'name': 'Bob',
+            'type': 'llm',
+            'model': 'gpt-4o-mini',
+            'goal': 'Share thoughts on a new sci-fi book',
+        },
+        {
+            'name': 'Carol',
+            'type': 'llm',
+            'model': 'gpt-4o-mini',
+            'goal': 'Discuss travel experiences and make everyone laugh',
+        },
+    ]
+
+    # Create background object
+    background = MultiAgentChatBackground(
+        scenario='Three friends catching up over coffee',
+        agent_configs=[
+            {
+                'name': 'Alice',
+                'background': 'Alice is a software engineer who loves hiking',
+                'goal': 'Talk about weekend hiking plans',
+            },
+            {
+                'name': 'Bob',
+                'background': 'Bob is a teacher who enjoys reading science fiction',
+                'goal': 'Share thoughts on a new sci-fi book',
+            },
+            {
+                'name': 'Carol',
+                'background': 'Carol is a graphic designer who recently returned from a trip to Japan',
+                'goal': 'Discuss travel experiences and make everyone laugh',
+            },
+        ],
+    )
+
+    print('Starting multi-agent conversation...')
+    print('=' * 50)
+
+    await server.multi_agent_run_conversation(
+        agent_configs=agent_configs,
+        background=background,
+        action_order='simultaneous',  # sequential, round-robin, simultaneous, random
+        max_turns=12,
+        enable_evaluation=True,
+    )
+
+
+if __name__ == '__main__':
+    asyncio.run(main())