{"id":29064519,"url":"https://github.com/styleebender/intelligent_llm_agents","last_synced_at":"2025-06-27T09:07:36.361Z","repository":{"id":301426876,"uuid":"1009121243","full_name":"Styleebender/Intelligent_LLM_Agents","owner":"Styleebender","description":"Intelligent LLM Agent with Dynamic Tool Selection - AWS Serverless","archived":false,"fork":false,"pushed_at":"2025-06-26T19:51:07.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-26T20:37:52.247Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Styleebender.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-26T15:57:15.000Z","updated_at":"2025-06-26T19:51:11.000Z","dependencies_parsed_at":"2025-06-26T20:52:19.049Z","dependency_job_id":null,"html_url":"https://github.com/Styleebender/Intelligent_LLM_Agents","commit_stats":null,"previous_names":["styleebender/intelligent_llm_agents"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Styleebender/Intelligent_LLM_Agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Styleebender%2FIntelligent_LLM_Agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Styleebender%2FIntelligent_LLM_Agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Styleebender%2FIntelligent_LLM_Agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Styleebender%2FIntelligent_LLM_Agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Styleebender","download_url":"https://codeload.github.com/Styleebender/Intelligent_LLM_Agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Styleebender%2FIntelligent_LLM_Agents/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262227890,"owners_count":23278266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-27T09:07:15.721Z","updated_at":"2025-06-27T09:07:36.323Z","avatar_url":"https://github.com/Styleebender.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Intelligent LLM Agent with Dynamic Tool Selection\n\n## Quick Test Agent: ([Google Colab:](https://colab.research.google.com/drive/17b2YtpsqK6w_3saZWxcBJNRWFrqSXyPZ?usp=sharing))\n\n## Project Overview\n\nThis project implements a smart, multi-agent LLM-driven solution capable of dynamically deciding which tools to execute based on specific instructions for customer feedback analysis. The system uses AWS services for scalability and real-time processing with asynchronous communication between agents.\n\n## Architecture Overview\n\n### System Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   API Gateway   │───▶│   User Agent    │───▶│   SQS Queue    │\n│                 │    │   (Lambda 1)    │    │                 │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n                                │                      │\n                                ▼                      ▼\n                       ┌─────────────────┐    ┌─────────────────┐\n                       │   DynamoDB      │◄───│  Tool Agent     │\n                       │   State Store   │    │   (Lambda 2)    │\n                       └─────────────────┘    └─────────────────┘\n                                │                      │\n                                ▼                      │\n                       ┌─────────────────┐             │\n                       │  Get Results    │◄────────────┘\n                       │   (Lambda 3)    │\n                       └─────────────────┘\n```\n\n### Multi-Agent Design\n\nThe system consists of three main components:\n\n1. **User Agent (Guardrail Agent)** - Handles user interaction and applies content guardrails\n2. **Tool Agent (Feedback Analysis Agent)** - Performs dynamic tool selection and execution\n3. **Results Agent** - Retrieves and formats analysis results\n\n## Core Components\n\n### 1. User Agent (Lambda 1)\n- **Purpose**: User interaction handler with content guardrails\n- **Responsibilities**:\n  - Validate incoming requests\n  - Apply content filtering guardrails\n  - Validate user instructions\n  - Store initial state in DynamoDB\n  - Queue messages for processing in SQS\n\n### 2. Tool Agent (Lambda 2)\n- **Purpose**: Dynamic tool execution based on instructions\n- **Responsibilities**:\n  - Process SQS messages asynchronously\n  - Interpret instructions using LLM\n  - Dynamically select and execute tools\n  - Update processing state in DynamoDB\n\n### 3. Results Agent (Lambda 3)\n- **Purpose**: Results retrieval and formatting\n- **Responsibilities**:\n  - Query DynamoDB for feedback results\n  - Format analysis results for user consumption\n  - Handle different processing states\n\n## Available Analysis Tools\n\n### 1. Sentiment Analysis Tool\n- **Function**: Analyze emotional tone and sentiment\n- **Output**: \n  - Basic sentiment (positive/negative/neutral)\n  - Polarity and subjectivity scores\n  - Enhanced analysis with emotional indicators\n  - Sentiment reasoning\n\n### 2. Topic Categorization Tool\n- **Function**: Categorize feedback into predefined business topics\n- **Categories**: Product Quality, Delivery, Customer Support, Pricing, Website/App, Billing, Returns, Shipping, User Experience\n- **Output**:\n  - Primary topic identification\n  - Secondary relevant topics\n  - Topic confidence scores\n  - Categorization reasoning\n\n### 3. Keyword Contextualization Tool\n- **Function**: Extract context-aware keywords with relevance scores\n- **Output**:\n  - Word frequency analysis\n  - Keywords with relevance scores and context\n  - Key phrases extraction\n  - Named entity recognition\n\n### 4. Summarization Tool\n- **Function**: Generate concise summaries and actionable recommendations\n- **Output**:\n  - Executive summary\n  - Key points extraction\n  - Actionable recommendations with priority and department assignment\n  - Customer impact assessment\n\n## Dynamic Tool Selection Logic\n\nThe system uses an intelligent agent powered by OpenAI's agents framework to:\n\n1. **Parse Instructions**: Analyze the `instructions` field to understand user requirements\n2. **Context Analysis**: Evaluate feedback content to determine relevant tools\n3. **Dynamic Execution**: Select appropriate tools based on instructions and content\n4. **Default Behavior**: Execute all tools when no specific instructions are provided\n5. **Sequential Processing**: Ensure logical tool execution order\n6. **Final Summarization**: Always conclude with summarization tool for structured output\n\n### Example Instruction Interpretations:\n- `\"Focus on sentiment analysis only\"` → Execute only sentiment_analysis tool\n- `\"Analyze sentiment and suggest improvements\"` → Execute sentiment_analysis + summarization\n- `\"Identify key topics and summarize actionable points\"` → Execute topic_categorization + summarization\n- No instructions → Execute all tools in logical sequence\n\n## Quick Test Agent:\n([Google Colab:](https://colab.research.google.com/drive/17b2YtpsqK6w_3saZWxcBJNRWFrqSXyPZ?usp=sharing))\n\n## AWS Services Integration\n\n### AWS Lambda\n- **User Agent**: Handles API requests and guardrails\n- **Tool Agent**: Processes feedback with dynamic tool selection\n- **Results Agent**: Retrieves and formats results\n\n### Amazon SQS\n- **Purpose**: Asynchronous communication between agents\n- **Queue**: `feedback-processing-queue`\n- **Benefits**: Decoupling, reliability, scalability\n\n### Amazon DynamoDB\n- **Purpose**: State management and results storage\n- **Table Structure**:\n  - Primary Key: `feedback_id` (String)\n  - Sort Key: `timestamp` (Number)\n  - Attributes: `status`, `original_data`, `results`, `created_at`, `updated_at`\n\n### API Gateway\n- **Purpose**: REST API endpoints\n- **Endpoints**:\n  - `POST /feedback` - Submit feedback for analysis\n  - `GET /results/{feedback_id}` - Retrieve analysis results\n\n## API Usage Examples\n\n### Submit Feedback for Analysis\n\n```bash\nPOST /feedback\nContent-Type: application/json\n\n{\n  \"feedback_id\": \"12345\",\n  \"customer_name\": \"John Doe\",\n  \"feedback_text\": \"The product is great, but the delivery was delayed.\",\n  \"timestamp\": \"2025-01-10T10:30:00Z\",\n  \"instructions\": \"Focus on identifying the sentiment and summarizing actionable insights.\"\n}\n```\n\n**Response:**\n```json\n{\n  \"message\": \"Feedback received and queued for processing\",\n  \"feedback_id\": \"12345\",\n  \"status\": \"processing\"\n}\n```\n\n### Retrieve Analysis Results\n\n```bash\nGET /results/12345\n```\n\n**Response:**\n```json\n{\n  \"feedback_id\": \"12345\",\n  \"status\": \"completed\",\n  \"message\": \"Analysis completed successfully\",\n  \"results\": {\n    \"executive_summary\": \"Customer expresses satisfaction with product quality but frustration with delivery delays.\",\n    \"key_insights\": {\n      \"main_points\": [\n        \"Positive product feedback\",\n        \"Delivery service issues\",\n        \"Overall mixed sentiment\"\n      ],\n      \"customer_impact_assessment\": \"Moderate impact - satisfied with product but delivery issues may affect future purchases\"\n    },\n    \"actionable_recommendations\": {\n      \"total_recommendations\": 2,\n      \"immediate_actions\": [\n        {\n          \"action\": \"Review delivery logistics and identify bottlenecks\",\n          \"department\": \"Operations\",\n          \"timeline\": \"Within 1 week\",\n          \"priority\": \"high\"\n        }\n      ]\n    }\n  }\n}\n```\n\n## Error Handling\n\nThe system implements comprehensive error handling:\n\n1. **Input Validation**: Validates required fields and data types\n2. **Content Guardrails**: Filters inappropriate content\n3. **Instruction Validation**: Ensures instructions are within scope\n4. **Tool Execution**: Handles tool failures gracefully\n5. **State Management**: Tracks processing status and errors\n6. **Fallback Mechanisms**: Default behaviors when specific tools fail\n\n## Security Features\n\n### Content Guardrails\n- **Hate Speech Detection**: Filters harmful content\n- **Spam Detection**: Identifies irrelevant content\n- **PII Redaction**: Removes personal information\n- **Instruction Validation**: Prevents malicious instructions\n\n### Current Limitations\n1. **Caching**: Redis caching not implemented (planned enhancement)\n2. **Infrastructure as Code**: Manual deployment (Terraform planned)\n\n### Future Enhancements\n1. **Redis Caching**: Implement result caching for improved performance\n2. **Terraform Deployment**: Complete IaC implementation\n\n\n---\n\n## Quick Start Guide\n## Follow Architecture and Design Decisions \u0026 Setup Instructions Documentation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstyleebender%2Fintelligent_llm_agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstyleebender%2Fintelligent_llm_agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstyleebender%2Fintelligent_llm_agents/lists"}