From 873504fdf6b7c18dcfd813acf18e7536bc9e5b56 Mon Sep 17 00:00:00 2001 From: Aksh Parekh Date: Thu, 11 Dec 2025 22:42:33 -0800 Subject: [PATCH 1/2] [EXAMPLE][DOCS] Customer Support Swarm --- docs/examples/index.md | 1 + .../swarms/examples/customer_support_swarm.md | 456 ++++++++++++++++++ example.py | 267 +++++++++- .../multi_agent/customer_support_swarm.py | 257 ++++++++++ openai-python | 1 + 5 files changed, 967 insertions(+), 15 deletions(-) create mode 100644 docs/swarms/examples/customer_support_swarm.md create mode 100644 examples/multi_agent/customer_support_swarm.py create mode 160000 openai-python diff --git a/docs/examples/index.md b/docs/examples/index.md index 684e9f15..b3419a47 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -227,6 +227,7 @@ This index organizes **100+ production-ready examples** from our [Swarms Example ### Industry Applications | Category | Example | Description | |----------|---------|-------------| +| Customer Support | [Customer Support Swarm](../swarms/examples/customer_support_swarm.md) | Production-ready multi-agent customer support system with intelligent routing, specialized agents, and knowledge base integration | | Finance | [Accountant Team](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/accountant_team/account_team2_example.py) | Multi-agent system for financial analysis, bookkeeping, and tax planning | | Marketing | [Ad Generation](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/ad_gen/ad_gen_example.py) | Collaborative ad creation with copywriting and design agents | | Aerospace | [Space Traffic Control](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/agentic_space_traffic_control/game.py) | Complex simulation of space traffic management with multiple coordinating agents | diff --git a/docs/swarms/examples/customer_support_swarm.md b/docs/swarms/examples/customer_support_swarm.md new file mode 100644 index 00000000..0752d4fe --- /dev/null +++ b/docs/swarms/examples/customer_support_swarm.md @@ -0,0 +1,456 @@ +# Customer Support Agent Swarm + +An interactive, console-based customer support system using multi-agents and free vector database (ChromaDB). + +## Overview + +This example demonstrates a practical customer support system with: + +- **Console-Based Interface**: Simple terminal interaction, no web services required +- **Free Vector Database**: ChromaDB for knowledge storage and retrieval +- **Multi-Agent Workflow**: Triage and support agents working together +- **Real-Time Knowledge Retrieval**: Agents query relevant information from vector DB +- **Interactive & Demo Modes**: Test with your own queries or use pre-defined examples + +## Key Features + +āœ… **No Cloud Services**: Runs completely locally +āœ… **Free Dependencies**: ChromaDB is open-source and free +āœ… **Semantic Search**: Vector similarity for intelligent knowledge retrieval +āœ… **Production-Ready**: Easy to extend and deploy + +## Architecture + +```mermaid +graph TB + A[Customer Query] --> B[ChromaDB Vector Search] + B --> C[Relevant Knowledge Retrieved] + C --> D[Triage Agent] + D --> E[Support Agent] + E --> F[Final Response] + G[Knowledge Base] -.->|8 Entries| B +``` + +**Workflow:** +1. Customer asks a question via console +2. System queries ChromaDB for relevant knowledge +3. Triage agent categorizes the inquiry +4. Support agent formulates response using retrieved knowledge +5. Customer receives answer + +## Components + +### 1. ChromaDB Vector Database +**Purpose**: Stores and retrieves company knowledge using semantic search + +**Contents**: +- **Products**: CloudSync Pro ($29.99/mo), DataVault Enterprise ($99.99/mo) +- **Troubleshooting**: Login issues, sync problems +- **Billing**: Refunds, upgrades, pricing +- **Policies**: Privacy (GDPR/SOC2), SLA (99.9% uptime) + +**Features**: +- Free and open-source +- Runs locally (no cloud required) +- In-memory or persistent storage +- Semantic similarity search + +### 2. Triage Agent +**Purpose**: First point of contact, categorizes inquiries + +**Capabilities**: +- Understands customer issues +- Categorizes by type (technical, billing, product) +- Provides concise summary +- Uses knowledge base context + +### 3. Support Agent +**Purpose**: Provides solutions using retrieved knowledge + +**Capabilities**: +- Technical troubleshooting +- Billing assistance +- Product information +- Contextual responses from vector DB + +## Quick Start + +### Installation + +```bash +# Install ChromaDB (free vector database) +pip install chromadb + +# Install Swarms (if not already installed) +pip install swarms +``` + +### Setup + +```bash +# Set your OpenAI API key +export OPENAI_API_KEY="your-api-key-here" +``` + +### Run Interactive Mode + +```bash +cd examples/multi_agent +python customer_support_swarm.py +``` + +This starts an interactive console where you can ask questions: + +``` +šŸŽÆ TECHCORP CUSTOMER SUPPORT - INTERACTIVE CONSOLE +================================================================================ + +Powered by: + ā€¢ Multi-Agent System (Swarms) + ā€¢ ChromaDB Vector Database (free, local) + ā€¢ Real-time Knowledge Retrieval + +Type 'quit' or 'exit' to end the session +Type 'help' to see example questions +================================================================================ + +-------------------------------------------------------------------------------- + +šŸ‘¤ You: I can't log into my account + +šŸ” Searching knowledge base... +šŸ¤– Processing with support agents... + +================================================================================ +šŸ¤– SUPPORT AGENT: +================================================================================ + +I understand you're having trouble logging in. Here's how to resolve this: + +DIAGNOSIS: Login authentication issue + +SOLUTION: +1. Clear your browser cache and cookies +2. Use the password reset feature at cloudpro.com/reset +3. Verify your email address is correct +4. Ensure your account is still active + +FOLLOW_UP: If these steps don't resolve the issue, contact support@techcorp.com +Our 24/7 support team is available via chat, email, or phone. + +================================================================================ +``` + +### Run Demo Mode + +```bash +python customer_support_swarm.py --demo +``` + +Runs 3 pre-defined queries to demonstrate the system + +## Code Overview + +### Initialize ChromaDB + +```python +import chromadb +from chromadb.config import Settings + +# Initialize ChromaDB (in-memory, free, no setup) +chroma_client = chromadb.Client(Settings( + anonymized_telemetry=False, + allow_reset=True +)) + +# Create collection for company knowledge +knowledge_collection = chroma_client.get_or_create_collection( + name="company_knowledge", + metadata={"description": "TechCorp product information"} +) +``` + +### Load Knowledge into Vector DB + +```python +KNOWLEDGE_ENTRIES = [ + { + "id": "product_cloudsync", + "text": "CloudSync Pro is priced at $29.99/month with unlimited storage...", + "metadata": {"category": "product", "product": "CloudSync Pro"} + }, + # ... more entries +] + +# Populate database +for entry in KNOWLEDGE_ENTRIES: + knowledge_collection.add( + ids=[entry["id"]], + documents=[entry["text"]], + metadatas=[entry["metadata"]] + ) +``` + +### Query Vector Database + +```python +def query_knowledge_base(query: str, n_results: int = 3) -> str: + """Query the vector database for relevant knowledge""" + results = knowledge_collection.query( + query_texts=[query], + n_results=n_results + ) + + # Format and return relevant knowledge + knowledge = "Relevant Knowledge Base Information:\n\n" + for doc, metadata in zip(results["documents"][0], results["metadatas"][0]): + knowledge += f"[{metadata['category']}] {doc}\n\n" + + return knowledge +``` + +### Create Agents + +```python +from swarms import Agent + +def create_support_agents(): + triage_agent = Agent( + agent_name="Triage-Agent", + system_prompt="You are a customer support triage specialist...", + max_loops=1, + verbose=False, + ) + + support_agent = Agent( + agent_name="Support-Agent", + system_prompt="You are a TechCorp support specialist...", + max_loops=1, + verbose=False, + ) + + return [triage_agent, support_agent] +``` + +### Handle Support Query + +```python +from swarms.structs.sequential_workflow import SequentialWorkflow + +def handle_support_query(customer_query: str, agents: list) -> str: + # Step 1: Query vector database + relevant_knowledge = query_knowledge_base(customer_query, n_results=3) + + # Step 2: Enrich query with knowledge + enriched_query = f"""Customer Query: {customer_query} + +{relevant_knowledge} + +Based on the customer query and knowledge base information, provide a response.""" + + # Step 3: Run through agent workflow + workflow = SequentialWorkflow( + name="Support-Workflow", + agents=agents, + max_loops=1, + ) + + return workflow.run(enriched_query) +``` + +## Example Queries + +The system can handle various types of customer support queries: + +### Technical Support +``` +šŸ‘¤ You: I can't log into my account +``` + +**Vector DB Retrieves**: +- Troubleshooting guide for login issues +- Account verification steps +- Contact information for support + +**Agent Response**: +- Diagnoses the issue +- Provides step-by-step solution +- Offers escalation path + +### Product Information +``` +šŸ‘¤ You: What's the difference between CloudSync Pro and DataVault Enterprise? +``` + +**Vector DB Retrieves**: +- Product specifications +- Pricing information +- Feature comparisons + +**Agent Response**: +- Explains key differences +- Recommends based on user needs +- Mentions pricing and trials + +### Billing Questions +``` +šŸ‘¤ You: How do I get a refund? +``` + +**Vector DB Retrieves**: +- Refund policy +- Process steps +- Timeline expectations + +**Agent Response**: +- Explains 30-day money-back guarantee +- Provides refund request steps +- Sets timeline expectations + +## Customization + +### Adding More Knowledge + +Expand the knowledge base with more entries: + +```python +KNOWLEDGE_ENTRIES.append({ + "id": "feature_api_access", + "text": "API access is available on DataVault Enterprise plan. Includes REST API, webhooks, and 10,000 requests/month. Documentation at api.techcorp.com", + "metadata": {"category": "product", "feature": "api"} +}) +``` + +### Adding More Agents + +Create specialized agents for specific needs: + +```python +def create_expanded_support_agents(): + # ... existing agents ... + + escalation_agent = Agent( + agent_name="Escalation-Agent", + system_prompt="Review cases and determine if human intervention is needed.", + max_loops=1, + ) + + return [triage_agent, support_agent, escalation_agent] +``` + +### Persistent Storage + +For production, save ChromaDB to disk: + +```python +from chromadb import PersistentClient + +# Use persistent storage instead of in-memory +chroma_client = PersistentClient(path="./chroma_db") + +# Database persists between runs +``` + +### Load Knowledge from Files + +```python +import json + +# Load knowledge from JSON file +with open("knowledge_base.json", "r") as f: + knowledge_entries = json.load(f) + +# Populate database +for entry in knowledge_entries: + knowledge_collection.add( + ids=[entry["id"]], + documents=[entry["text"]], + metadatas=[entry["metadata"]] + ) +``` + +## Production Considerations + +### 1. Knowledge Management +- **Regular Updates**: Keep knowledge base current with product changes +- **Version Control**: Track knowledge base changes in Git +- **Quality Control**: Review and validate new entries before adding +- **Categorization**: Use consistent metadata categories for better retrieval + +### 2. Performance Optimization +- **Batch Loading**: Load knowledge in batches for faster startup +- **Cache Results**: Cache frequently queried knowledge +- **Index Optimization**: ChromaDB handles indexing automatically +- **Retrieval Tuning**: Adjust `n_results` based on query complexity + +### 3. Monitoring & Analytics +- **Track Queries**: Log all customer queries for analysis +- **Measure Accuracy**: Monitor if retrieved knowledge is relevant +- **Response Time**: Track end-to-end response latency +- **User Feedback**: Collect satisfaction ratings + +### 4. Security +- **API Key Protection**: Never hardcode API keys +- **Input Validation**: Sanitize user inputs +- **Rate Limiting**: Prevent abuse with rate limits +- **Data Privacy**: Don't store sensitive customer data in logs + +## Best Practices + +### 1. Vector Database +- Start with in-memory for development +- Use persistent storage for production +- Regularly backup your database +- Monitor database size and performance + +### 2. Agent Design +- Keep prompts focused and specific +- Use verbose=False in production for cleaner output +- Test agents independently before integration +- Monitor agent response quality + +### 3. Knowledge Base +- Structure entries clearly and consistently +- Use meaningful IDs and metadata +- Include examples in knowledge entries +- Update based on common queries + +## Why ChromaDB? + +**Advantages:** +- āœ… Free and open-source +- āœ… No external dependencies +- āœ… Simple 3-line setup +- āœ… Fast semantic search +- āœ… Works offline +- āœ… Perfect for prototypes and production + +**Alternatives:** +- FAISS (Facebook) - Faster for very large datasets +- Pinecone - Managed cloud service (paid) +- Weaviate - Full-featured vector DB (more complex) +- Qdrant - Open-source with advanced features + +## Next Steps + +1. **Try the demo**: Run `python customer_support_swarm.py --demo` +2. **Interactive mode**: Run without flags for console chat +3. **Customize**: Add your own knowledge entries +4. **Extend**: Add more specialized agents +5. **Deploy**: Switch to persistent storage for production + +## Related Examples + +- [Sequential Workflow](./sequential_workflow.md) - Linear agent workflows +- [Agent Rearrange](./agent_rearrange.md) - Dynamic agent routing +- [Multi-Agent Collaboration](../structs/swarms/multi_agent_collaboration/) - Team coordination patterns + +## Support + +- **Documentation**: [docs.swarms.world](https://docs.swarms.world) +- **Discord**: [Join the community](https://discord.gg/EamjgSaEQf) +- **GitHub**: [Report issues](https://github.com/kyegomez/swarms) + +--- + +Built with ā¤ļø using Swarms and ChromaDB diff --git a/example.py b/example.py index 5cf9ed1c..761ff55d 100644 --- a/example.py +++ b/example.py @@ -1,20 +1,257 @@ +""" +Customer Support Agent Swarm with Vector Database + +This example demonstrates a multi-agent customer support system with: +- Console-based interactive customer support +- ChromaDB vector database for company knowledge +- Intelligent routing and agent communication +- Real-time question answering from knowledge base +""" + +import chromadb +from chromadb.config import Settings from swarms import Agent +from swarms.structs.sequential_workflow import SequentialWorkflow -# Initialize the agent -agent = Agent( - agent_name="Quantitative-Trading-Agent", - agent_description="Advanced quantitative trading and algorithmic analysis agent", - model_name="gpt-4.1", - dynamic_temperature_enabled=True, - max_loops=1, - dynamic_context_window=True, - top_p=None, - streaming_on=True, - interactive=False, -) +# Initialize ChromaDB client (in-memory, free, no setup required) +chroma_client = chromadb.Client(Settings( + anonymized_telemetry=False, + allow_reset=True +)) -out = agent.run( - task="What are the top five best energy stocks across nuclear, solar, gas, and other energy sources?", +# Create or get collection for company knowledge +knowledge_collection = chroma_client.get_or_create_collection( + name="company_knowledge", + metadata={"description": "TechCorp product information and support knowledge"} ) -print(out) +# Company knowledge base entries to store in vector DB +KNOWLEDGE_ENTRIES = [ + { + "id": "product_cloudsync", + "text": "CloudSync Pro is our entry-level product priced at $29.99/month. It includes unlimited storage, real-time sync across devices, end-to-end encryption for security, and 24/7 support via chat, email, and phone. New users get a 14-day free trial.", + "metadata": {"category": "product", "product": "CloudSync Pro"} + }, + { + "id": "product_datavault", + "text": "DataVault Enterprise is our premium product priced at $99.99/month. It's designed for teams and includes team collaboration features, admin controls, compliance tools, API access, dedicated account manager, and priority support. New customers get a 30-day free trial.", + "metadata": {"category": "product", "product": "DataVault Enterprise"} + }, + { + "id": "troubleshoot_login", + "text": "Login problems are common and usually resolved by clearing browser cache and cookies, or using the password reset feature. If issues persist, check if the account is active and verify the email address is correct. Contact support if problems continue.", + "metadata": {"category": "troubleshooting", "issue": "login"} + }, + { + "id": "troubleshoot_sync", + "text": "Sync delays can occur due to poor internet connection, outdated app versions, or server maintenance. First check internet connectivity, then ensure you're using the latest app version. Sync typically completes within 30 seconds on good connections.", + "metadata": {"category": "troubleshooting", "issue": "sync"} + }, + { + "id": "billing_refund", + "text": "TechCorp offers a 30-day money-back guarantee on all products. Refund requests can be submitted through the account portal or by emailing billing@techcorp.com. Refunds are processed within 5-7 business days.", + "metadata": {"category": "billing", "topic": "refund"} + }, + { + "id": "billing_upgrade", + "text": "Upgrading from CloudSync Pro to DataVault Enterprise is easy through the account portal. You'll be charged the prorated difference immediately, and all your data migrates automatically. Downgrades take effect at the next billing cycle.", + "metadata": {"category": "billing", "topic": "upgrade"} + }, + { + "id": "policy_privacy", + "text": "TechCorp is fully GDPR and SOC 2 compliant. We use end-to-end encryption, never sell customer data, and provide full data export capabilities. Our privacy policy is available at techcorp.com/privacy.", + "metadata": {"category": "policy", "topic": "privacy"} + }, + { + "id": "policy_sla", + "text": "TechCorp guarantees 99.9% uptime for all services. If we fail to meet this SLA, customers receive service credits. Real-time status is available at status.techcorp.com.", + "metadata": {"category": "policy", "topic": "sla"} + }, +] + +# Populate vector database with company knowledge +print("šŸ“š Loading company knowledge into vector database...") +for entry in KNOWLEDGE_ENTRIES: + knowledge_collection.add( + ids=[entry["id"]], + documents=[entry["text"]], + metadatas=[entry["metadata"]] + ) +print(f"āœ… Loaded {len(KNOWLEDGE_ENTRIES)} knowledge entries into ChromaDB\n") + + +def query_knowledge_base(query: str, n_results: int = 3) -> str: + """Query the vector database for relevant knowledge""" + results = knowledge_collection.query( + query_texts=[query], + n_results=n_results + ) + + if not results["documents"][0]: + return "No relevant information found in knowledge base." + + # Format results + knowledge = "Relevant Knowledge Base Information:\n\n" + for i, (doc, metadata) in enumerate(zip(results["documents"][0], results["metadatas"][0]), 1): + knowledge += f"{i}. [{metadata.get('category', 'general')}] {doc}\n\n" + + return knowledge + + +# Create specialized support agents that use the vector database +def create_support_agents(): + """Create a team of specialized customer support agents with vector DB access""" + + # Agent 1: Triage Agent with Vector DB + triage_agent = Agent( + agent_name="Triage-Agent", + agent_description="First point of contact. Uses vector DB to categorize inquiries.", + system_prompt="""You are a customer support triage specialist for TechCorp. + +Your role is to: +1. Understand the customer's issue or question +2. Categorize it (technical, billing, product info, or general) +3. Extract key information (product, error messages, account details) +4. Provide a brief summary + +You have access to a knowledge base that will be provided with relevant information. + +Always be empathetic and professional. Keep your response concise. +Format: CATEGORY: [category] | SUMMARY: [brief summary] +""", + max_loops=1, + verbose=False, + ) + + # Agent 2: Support Agent with Vector DB + support_agent = Agent( + agent_name="Support-Agent", + agent_description="Handles customer inquiries using knowledge base.", + system_prompt="""You are a TechCorp support specialist. + +You help with: +- Technical issues (login, sync, performance) +- Billing questions (pricing, refunds, upgrades) +- Product information (features, plans, comparisons) + +Relevant knowledge base information will be provided to you. + +Provide clear, actionable solutions. Be professional and helpful. +Format your response clearly with the solution and any next steps. +""", + max_loops=1, + verbose=False, + ) + + return [triage_agent, support_agent] + + +def handle_support_query(customer_query: str, agents: list) -> str: + """Handle a customer support query using vector DB + agents""" + + # Step 1: Query vector database for relevant knowledge + print("\nšŸ” Searching knowledge base...") + relevant_knowledge = query_knowledge_base(customer_query, n_results=3) + + # Step 2: Combine query with knowledge for agent processing + enriched_query = f"""Customer Query: {customer_query} + +{relevant_knowledge} + +Based on the customer query and knowledge base information above, provide an appropriate response.""" + + # Step 3: Run through agent workflow + print("šŸ¤– Processing with support agents...\n") + + workflow = SequentialWorkflow( + name="Support-Workflow", + description="Customer support with vector DB knowledge", + agents=agents, + max_loops=1, + ) + + result = workflow.run(enriched_query) + return result + + +def interactive_console(): + """Run interactive console-based customer support""" + print("\n" + "=" * 80) + print("šŸŽÆ TECHCORP CUSTOMER SUPPORT - INTERACTIVE CONSOLE") + print("=" * 80) + print("\nPowered by:") + print(" ā€¢ Multi-Agent System (Swarms)") + print(" ā€¢ ChromaDB Vector Database (free, local)") + print(" ā€¢ Real-time Knowledge Retrieval") + print("\nType 'quit' or 'exit' to end the session") + print("Type 'help' to see example questions") + print("=" * 80 + "\n") + + # Create agents once + agents = create_support_agents() + + while True: + # Get user input + print("\n" + "-" * 80) + user_input = input("\nšŸ‘¤ You: ").strip() + + if not user_input: + continue + + # Handle special commands + if user_input.lower() in ['quit', 'exit']: + print("\nšŸ‘‹ Thank you for contacting TechCorp Support! Have a great day!") + break + + if user_input.lower() == 'help': + print("\nšŸ“‹ Example questions you can ask:") + print(" ā€¢ What's the difference between CloudSync Pro and DataVault Enterprise?") + print(" ā€¢ I can't log into my account, what should I do?") + print(" ā€¢ How do I upgrade my subscription?") + print(" ā€¢ What's your refund policy?") + print(" ā€¢ My files aren't syncing, can you help?") + continue + + # Process support query + try: + handle_support_query(user_input, agents) + + except Exception as e: + print(f"\nāŒ Error processing query: {str(e)}") + print("Please try rephrasing your question or contact support@techcorp.com") + + +def demo_mode(): + """Run demo mode with pre-defined queries""" + print("\n" + "=" * 80) + print("šŸŽÆ TECHCORP CUSTOMER SUPPORT - DEMO MODE") + print("=" * 80 + "\n") + + agents = create_support_agents() + + demo_queries = [ + "I can't log into CloudSync Pro. I tried resetting my password but still getting errors.", + "What's the difference between CloudSync Pro and DataVault Enterprise? Which is better for a team of 10?", + "I was charged twice this month. Can I get a refund?", + ] + + for i, query in enumerate(demo_queries, 1): + print(f"\n{'='*80}") + print(f"DEMO QUERY {i}/{len(demo_queries)}") + print(f"{'='*80}") + print(f"\nšŸ‘¤ Customer: {query}\n") + + handle_support_query(query, agents) + + if i < len(demo_queries): + input("\nPress Enter to continue to next query...") + + +if __name__ == "__main__": + import sys + + # Check for command line arguments + if len(sys.argv) > 1 and sys.argv[1] == '--demo': + demo_mode() + else: + interactive_console() diff --git a/examples/multi_agent/customer_support_swarm.py b/examples/multi_agent/customer_support_swarm.py new file mode 100644 index 00000000..761ff55d --- /dev/null +++ b/examples/multi_agent/customer_support_swarm.py @@ -0,0 +1,257 @@ +""" +Customer Support Agent Swarm with Vector Database + +This example demonstrates a multi-agent customer support system with: +- Console-based interactive customer support +- ChromaDB vector database for company knowledge +- Intelligent routing and agent communication +- Real-time question answering from knowledge base +""" + +import chromadb +from chromadb.config import Settings +from swarms import Agent +from swarms.structs.sequential_workflow import SequentialWorkflow + +# Initialize ChromaDB client (in-memory, free, no setup required) +chroma_client = chromadb.Client(Settings( + anonymized_telemetry=False, + allow_reset=True +)) + +# Create or get collection for company knowledge +knowledge_collection = chroma_client.get_or_create_collection( + name="company_knowledge", + metadata={"description": "TechCorp product information and support knowledge"} +) + +# Company knowledge base entries to store in vector DB +KNOWLEDGE_ENTRIES = [ + { + "id": "product_cloudsync", + "text": "CloudSync Pro is our entry-level product priced at $29.99/month. It includes unlimited storage, real-time sync across devices, end-to-end encryption for security, and 24/7 support via chat, email, and phone. New users get a 14-day free trial.", + "metadata": {"category": "product", "product": "CloudSync Pro"} + }, + { + "id": "product_datavault", + "text": "DataVault Enterprise is our premium product priced at $99.99/month. It's designed for teams and includes team collaboration features, admin controls, compliance tools, API access, dedicated account manager, and priority support. New customers get a 30-day free trial.", + "metadata": {"category": "product", "product": "DataVault Enterprise"} + }, + { + "id": "troubleshoot_login", + "text": "Login problems are common and usually resolved by clearing browser cache and cookies, or using the password reset feature. If issues persist, check if the account is active and verify the email address is correct. Contact support if problems continue.", + "metadata": {"category": "troubleshooting", "issue": "login"} + }, + { + "id": "troubleshoot_sync", + "text": "Sync delays can occur due to poor internet connection, outdated app versions, or server maintenance. First check internet connectivity, then ensure you're using the latest app version. Sync typically completes within 30 seconds on good connections.", + "metadata": {"category": "troubleshooting", "issue": "sync"} + }, + { + "id": "billing_refund", + "text": "TechCorp offers a 30-day money-back guarantee on all products. Refund requests can be submitted through the account portal or by emailing billing@techcorp.com. Refunds are processed within 5-7 business days.", + "metadata": {"category": "billing", "topic": "refund"} + }, + { + "id": "billing_upgrade", + "text": "Upgrading from CloudSync Pro to DataVault Enterprise is easy through the account portal. You'll be charged the prorated difference immediately, and all your data migrates automatically. Downgrades take effect at the next billing cycle.", + "metadata": {"category": "billing", "topic": "upgrade"} + }, + { + "id": "policy_privacy", + "text": "TechCorp is fully GDPR and SOC 2 compliant. We use end-to-end encryption, never sell customer data, and provide full data export capabilities. Our privacy policy is available at techcorp.com/privacy.", + "metadata": {"category": "policy", "topic": "privacy"} + }, + { + "id": "policy_sla", + "text": "TechCorp guarantees 99.9% uptime for all services. If we fail to meet this SLA, customers receive service credits. Real-time status is available at status.techcorp.com.", + "metadata": {"category": "policy", "topic": "sla"} + }, +] + +# Populate vector database with company knowledge +print("šŸ“š Loading company knowledge into vector database...") +for entry in KNOWLEDGE_ENTRIES: + knowledge_collection.add( + ids=[entry["id"]], + documents=[entry["text"]], + metadatas=[entry["metadata"]] + ) +print(f"āœ… Loaded {len(KNOWLEDGE_ENTRIES)} knowledge entries into ChromaDB\n") + + +def query_knowledge_base(query: str, n_results: int = 3) -> str: + """Query the vector database for relevant knowledge""" + results = knowledge_collection.query( + query_texts=[query], + n_results=n_results + ) + + if not results["documents"][0]: + return "No relevant information found in knowledge base." + + # Format results + knowledge = "Relevant Knowledge Base Information:\n\n" + for i, (doc, metadata) in enumerate(zip(results["documents"][0], results["metadatas"][0]), 1): + knowledge += f"{i}. [{metadata.get('category', 'general')}] {doc}\n\n" + + return knowledge + + +# Create specialized support agents that use the vector database +def create_support_agents(): + """Create a team of specialized customer support agents with vector DB access""" + + # Agent 1: Triage Agent with Vector DB + triage_agent = Agent( + agent_name="Triage-Agent", + agent_description="First point of contact. Uses vector DB to categorize inquiries.", + system_prompt="""You are a customer support triage specialist for TechCorp. + +Your role is to: +1. Understand the customer's issue or question +2. Categorize it (technical, billing, product info, or general) +3. Extract key information (product, error messages, account details) +4. Provide a brief summary + +You have access to a knowledge base that will be provided with relevant information. + +Always be empathetic and professional. Keep your response concise. +Format: CATEGORY: [category] | SUMMARY: [brief summary] +""", + max_loops=1, + verbose=False, + ) + + # Agent 2: Support Agent with Vector DB + support_agent = Agent( + agent_name="Support-Agent", + agent_description="Handles customer inquiries using knowledge base.", + system_prompt="""You are a TechCorp support specialist. + +You help with: +- Technical issues (login, sync, performance) +- Billing questions (pricing, refunds, upgrades) +- Product information (features, plans, comparisons) + +Relevant knowledge base information will be provided to you. + +Provide clear, actionable solutions. Be professional and helpful. +Format your response clearly with the solution and any next steps. +""", + max_loops=1, + verbose=False, + ) + + return [triage_agent, support_agent] + + +def handle_support_query(customer_query: str, agents: list) -> str: + """Handle a customer support query using vector DB + agents""" + + # Step 1: Query vector database for relevant knowledge + print("\nšŸ” Searching knowledge base...") + relevant_knowledge = query_knowledge_base(customer_query, n_results=3) + + # Step 2: Combine query with knowledge for agent processing + enriched_query = f"""Customer Query: {customer_query} + +{relevant_knowledge} + +Based on the customer query and knowledge base information above, provide an appropriate response.""" + + # Step 3: Run through agent workflow + print("šŸ¤– Processing with support agents...\n") + + workflow = SequentialWorkflow( + name="Support-Workflow", + description="Customer support with vector DB knowledge", + agents=agents, + max_loops=1, + ) + + result = workflow.run(enriched_query) + return result + + +def interactive_console(): + """Run interactive console-based customer support""" + print("\n" + "=" * 80) + print("šŸŽÆ TECHCORP CUSTOMER SUPPORT - INTERACTIVE CONSOLE") + print("=" * 80) + print("\nPowered by:") + print(" ā€¢ Multi-Agent System (Swarms)") + print(" ā€¢ ChromaDB Vector Database (free, local)") + print(" ā€¢ Real-time Knowledge Retrieval") + print("\nType 'quit' or 'exit' to end the session") + print("Type 'help' to see example questions") + print("=" * 80 + "\n") + + # Create agents once + agents = create_support_agents() + + while True: + # Get user input + print("\n" + "-" * 80) + user_input = input("\nšŸ‘¤ You: ").strip() + + if not user_input: + continue + + # Handle special commands + if user_input.lower() in ['quit', 'exit']: + print("\nšŸ‘‹ Thank you for contacting TechCorp Support! Have a great day!") + break + + if user_input.lower() == 'help': + print("\nšŸ“‹ Example questions you can ask:") + print(" ā€¢ What's the difference between CloudSync Pro and DataVault Enterprise?") + print(" ā€¢ I can't log into my account, what should I do?") + print(" ā€¢ How do I upgrade my subscription?") + print(" ā€¢ What's your refund policy?") + print(" ā€¢ My files aren't syncing, can you help?") + continue + + # Process support query + try: + handle_support_query(user_input, agents) + + except Exception as e: + print(f"\nāŒ Error processing query: {str(e)}") + print("Please try rephrasing your question or contact support@techcorp.com") + + +def demo_mode(): + """Run demo mode with pre-defined queries""" + print("\n" + "=" * 80) + print("šŸŽÆ TECHCORP CUSTOMER SUPPORT - DEMO MODE") + print("=" * 80 + "\n") + + agents = create_support_agents() + + demo_queries = [ + "I can't log into CloudSync Pro. I tried resetting my password but still getting errors.", + "What's the difference between CloudSync Pro and DataVault Enterprise? Which is better for a team of 10?", + "I was charged twice this month. Can I get a refund?", + ] + + for i, query in enumerate(demo_queries, 1): + print(f"\n{'='*80}") + print(f"DEMO QUERY {i}/{len(demo_queries)}") + print(f"{'='*80}") + print(f"\nšŸ‘¤ Customer: {query}\n") + + handle_support_query(query, agents) + + if i < len(demo_queries): + input("\nPress Enter to continue to next query...") + + +if __name__ == "__main__": + import sys + + # Check for command line arguments + if len(sys.argv) > 1 and sys.argv[1] == '--demo': + demo_mode() + else: + interactive_console() diff --git a/openai-python b/openai-python new file mode 160000 index 00000000..650be393 --- /dev/null +++ b/openai-python @@ -0,0 +1 @@ +Subproject commit 650be393dedf2a4550092817c2b82c1d04d6e9dc From 8a6b8d1cf7159336cd2995a28ada091905a7a5ce Mon Sep 17 00:00:00 2001 From: Aksh Parekh Date: Thu, 11 Dec 2025 23:01:36 -0800 Subject: [PATCH 2/2] [MOVE] files --- .../swarms/examples/customer_support_swarm.md | 102 +++++++++++- .../customer_support_swarm.py | 149 +++++++++++++++++- 2 files changed, 242 insertions(+), 9 deletions(-) rename examples/multi_agent/{ => agent_rearrange_examples}/customer_support_swarm.py (66%) diff --git a/docs/swarms/examples/customer_support_swarm.md b/docs/swarms/examples/customer_support_swarm.md index 0752d4fe..976cdbe6 100644 --- a/docs/swarms/examples/customer_support_swarm.md +++ b/docs/swarms/examples/customer_support_swarm.md @@ -17,6 +17,7 @@ This example demonstrates a practical customer support system with: āœ… **No Cloud Services**: Runs completely locally āœ… **Free Dependencies**: ChromaDB is open-source and free āœ… **Semantic Search**: Vector similarity for intelligent knowledge retrieval +āœ… **Intelligent Caching**: Automatic response caching saves tokens and improves speed āœ… **Production-Ready**: Easy to extend and deploy ## Architecture @@ -73,6 +74,21 @@ graph TB - Product information - Contextual responses from vector DB +### 4. Response Caching System +**Purpose**: Automatically cache and reuse responses for similar queries + +**How It Works**: +1. Every customer query is checked against cached responses +2. If a similar query exists (85%+ similarity), cached response is returned +3. New responses are automatically saved to cache +4. Saves API tokens and improves response time + +**Benefits**: +- **Token Savings**: Reuses responses instead of calling LLM +- **Faster Responses**: Instant retrieval from vector DB +- **Consistent Answers**: Same questions get same quality answers +- **Learning System**: Gets better over time as cache grows + ## Quick Start ### Installation @@ -191,6 +207,37 @@ for entry in KNOWLEDGE_ENTRIES: ) ``` +### Caching System + +```python +# Create conversation history collection for caching +conversation_history = chroma_client.get_or_create_collection( + name="conversation_history", + metadata={"description": "Past queries and responses"} +) + +def check_cached_response(query: str, similarity_threshold: float = 0.85): + """Check if similar query was already answered""" + results = conversation_history.query( + query_texts=[query], + n_results=1 + ) + + # If similarity > 85%, return cached response + if results["distances"][0][0] < 0.3: # Low distance = high similarity + return True, results["metadatas"][0][0]["response"] + + return False, "" + +def save_to_cache(query: str, response: str): + """Save query-response pair for future reuse""" + conversation_history.add( + ids=[f"conv_{hash(query)}_{time.time()}"], + documents=[query], + metadatas=[{"response": response, "timestamp": time.time()}] + ) +``` + ### Query Vector Database ```python @@ -307,6 +354,39 @@ The system can handle various types of customer support queries: - Provides refund request steps - Sets timeline expectations +### Caching in Action + +**First Query:** +``` +šŸ‘¤ You: I can't log into my account + +šŸ’¾ Checking cache for similar queries... +āŒ No similar query found in cache. Processing with agents... +šŸ” Searching knowledge base... +šŸ¤– Processing with support agents... + +šŸ¤– SUPPORT AGENT: +I understand you're having trouble logging in... +[Full response] + +šŸ’¾ Saving response to cache for future queries... +āœ… Cached successfully! +``` + +**Similar Query Later:** +``` +šŸ‘¤ You: Can't sign in to my account + +šŸ’¾ Checking cache for similar queries... +āœ… Found cached response! (Saving tokens šŸŽ‰) + +šŸ¤– SUPPORT AGENT (from cache): +I understand you're having trouble logging in... +[Same cached response - instant, no LLM call!] + +šŸ’” This response was retrieved from cache. No tokens used! šŸŽ‰ +``` + ## Customization ### Adding More Knowledge @@ -338,6 +418,26 @@ def create_expanded_support_agents(): return [triage_agent, support_agent, escalation_agent] ``` +### Adjusting Cache Sensitivity + +Control when to use cached responses: + +```python +# More aggressive caching (70% similarity) +response, cached = handle_support_query(query, agents, cache_threshold=0.70) + +# Stricter caching (90% similarity) +response, cached = handle_support_query(query, agents, cache_threshold=0.90) + +# Disable caching +response, cached = handle_support_query(query, agents, use_cache=False) +``` + +**Recommended Thresholds:** +- `0.85` (default) - Good balance, catches paraphrased questions +- `0.90` - Strict, only very similar questions +- `0.70` - Aggressive, broader matching (more token savings, less accuracy) + ### Persistent Storage For production, save ChromaDB to disk: @@ -348,7 +448,7 @@ from chromadb import PersistentClient # Use persistent storage instead of in-memory chroma_client = PersistentClient(path="./chroma_db") -# Database persists between runs +# Database persists between runs (including cached responses!) ``` ### Load Knowledge from Files diff --git a/examples/multi_agent/customer_support_swarm.py b/examples/multi_agent/agent_rearrange_examples/customer_support_swarm.py similarity index 66% rename from examples/multi_agent/customer_support_swarm.py rename to examples/multi_agent/agent_rearrange_examples/customer_support_swarm.py index 761ff55d..54720f39 100644 --- a/examples/multi_agent/customer_support_swarm.py +++ b/examples/multi_agent/agent_rearrange_examples/customer_support_swarm.py @@ -25,6 +25,12 @@ knowledge_collection = chroma_client.get_or_create_collection( metadata={"description": "TechCorp product information and support knowledge"} ) +# Create collection for conversation history (query caching) +conversation_history = chroma_client.get_or_create_collection( + name="conversation_history", + metadata={"description": "Past customer queries and responses for caching"} +) + # Company knowledge base entries to store in vector DB KNOWLEDGE_ENTRIES = [ { @@ -98,6 +104,77 @@ def query_knowledge_base(query: str, n_results: int = 3) -> str: return knowledge +def check_cached_response(query: str, similarity_threshold: float = 0.85) -> tuple[bool, str]: + """ + Check if a similar query was already answered. + + Args: + query: The customer query + similarity_threshold: Minimum similarity score to use cached response (0-1) + + Returns: + Tuple of (found, response) where found is True if cache hit + """ + try: + results = conversation_history.query( + query_texts=[query], + n_results=1 + ) + + if not results["documents"][0]: + return False, "" + + # Check similarity score (ChromaDB returns distances, lower is more similar) + # We need to check if there's a metadata field with similarity or use distance + distances = results.get("distances", [[1.0]])[0] + + if distances and distances[0] is not None: + # Convert distance to similarity (1 - distance for cosine) + # ChromaDB uses L2 distance by default, so we approximate + similarity = 1 - (distances[0] / 2) # Normalize to 0-1 range + + if similarity >= similarity_threshold: + cached_response = results["metadatas"][0][0].get("response", "") + if cached_response: + return True, cached_response + + return False, "" + + except Exception as e: + print(f"Cache check error: {e}") + return False, "" + + +def save_to_cache(query: str, response: str): + """ + Save a query-response pair to the conversation history cache. + + Args: + query: The customer query + response: The agent's response + """ + try: + import time + import hashlib + + # Create unique ID from query + query_id = hashlib.md5(query.encode()).hexdigest() + + # Add to conversation history + conversation_history.add( + ids=[f"conv_{query_id}_{int(time.time())}"], + documents=[query], + metadatas=[{ + "response": response, + "timestamp": time.time(), + "query_length": len(query) + }] + ) + + except Exception as e: + print(f"Cache save error: {e}") + + # Create specialized support agents that use the vector database def create_support_agents(): """Create a team of specialized customer support agents with vector DB access""" @@ -146,21 +223,44 @@ Format your response clearly with the solution and any next steps. return [triage_agent, support_agent] -def handle_support_query(customer_query: str, agents: list) -> str: - """Handle a customer support query using vector DB + agents""" +def handle_support_query(customer_query: str, agents: list, use_cache: bool = True, + cache_threshold: float = 0.85) -> tuple[str, bool]: + """ + Handle a customer support query using vector DB + agents with caching. + + Args: + customer_query: The customer's question + agents: List of support agents + use_cache: Whether to check cache for similar queries + cache_threshold: Similarity threshold for cache hits (0-1, default 0.85) + + Returns: + Tuple of (response, was_cached) + """ + + # Step 1: Check if we have a cached response for a similar query + if use_cache: + print("\nšŸ’¾ Checking cache for similar queries...") + cache_hit, cached_response = check_cached_response(customer_query, cache_threshold) + + if cache_hit: + print("āœ… Found cached response! (Saving tokens šŸŽ‰)") + return cached_response, True - # Step 1: Query vector database for relevant knowledge + print("āŒ No similar query found in cache. Processing with agents...") + + # Step 2: Query vector database for relevant knowledge print("\nšŸ” Searching knowledge base...") relevant_knowledge = query_knowledge_base(customer_query, n_results=3) - # Step 2: Combine query with knowledge for agent processing + # Step 3: Combine query with knowledge for agent processing enriched_query = f"""Customer Query: {customer_query} {relevant_knowledge} Based on the customer query and knowledge base information above, provide an appropriate response.""" - # Step 3: Run through agent workflow + # Step 4: Run through agent workflow print("šŸ¤– Processing with support agents...\n") workflow = SequentialWorkflow( @@ -171,7 +271,14 @@ Based on the customer query and knowledge base information above, provide an app ) result = workflow.run(enriched_query) - return result + + # Step 5: Save to cache for future queries + if use_cache: + print("\nšŸ’¾ Saving response to cache for future queries...") + save_to_cache(customer_query, result) + print("āœ… Cached successfully!") + + return result, False def interactive_console(): @@ -214,7 +321,20 @@ def interactive_console(): # Process support query try: - handle_support_query(user_input, agents) + response, was_cached = handle_support_query(user_input, agents, use_cache=True) + + # Print response with appropriate header + print("\n" + "=" * 80) + if was_cached: + print("šŸ¤– SUPPORT AGENT (from cache):") + else: + print("šŸ¤– SUPPORT AGENT:") + print("=" * 80) + print(f"\n{response}\n") + print("=" * 80) + + if was_cached: + print("\nšŸ’” This response was retrieved from cache. No tokens used! šŸŽ‰") except Exception as e: print(f"\nāŒ Error processing query: {str(e)}") @@ -241,7 +361,20 @@ def demo_mode(): print(f"{'='*80}") print(f"\nšŸ‘¤ Customer: {query}\n") - handle_support_query(query, agents) + response, was_cached = handle_support_query(query, agents, use_cache=True) + + # Print response + print("\n" + "=" * 80) + if was_cached: + print("šŸ¤– SUPPORT AGENT (from cache):") + else: + print("šŸ¤– SUPPORT AGENT:") + print("=" * 80) + print(f"\n{response}\n") + print("=" * 80) + + if was_cached: + print("\nšŸ’” This response was retrieved from cache. No tokens used! šŸŽ‰") if i < len(demo_queries): input("\nPress Enter to continue to next query...")