Skip to content

README.md

Latest commit

 

History

History
158 lines (113 loc) · 5.66 KB

README.md

File metadata and controls

158 lines (113 loc) · 5.66 KB

Backend README

ProactivePulse AI Backend

Agentic AI Architecture with Strands Agents SDK

This backend implements an agentic AI system using the Strands Agents SDK for the AWS Superhack AgenticAI hackathon. The system uses multiple specialized AI agents that work together to correlate infrastructure metrics with support tickets and generate proactive insights for MSPs.

Enhanced Architecture with OpenSearch Integration

Latest Improvements:

  • Enhanced Data Persistence: DynamoDB tables with Global Secondary Indexes (GSIs) for efficient querying
  • Full-text Search: AWS OpenSearch integration for powerful search capabilities
  • Advanced Analytics: Time-series analytics with aggregations and multiple aggregation types
  • Improved Performance: Proper pagination and Decimal/Float conversion handling

Architecture Overview

The backend implements a multi-agent architecture with the following specialized agents:

  1. Orchestrator Agent - Central coordinator that routes requests to specialized agents
  2. Data Ingestion Agent - Handles loading metrics and tickets data from storage
  3. Anomaly Detection Agent - Specializes in detecting anomalies in metrics data
  4. Ticket Analysis Agent - Analyzes support tickets and clusters similar issues
  5. Correlation Agent - Correlates anomalies with ticket clusters to identify patterns
  6. Insight Generation Agent - Creates human-readable insights and recommendations
  7. Notification Agent - Handles sending notifications and proactive digests
  8. Health Check Agent - Monitors system health and status

Enhanced Data Layer

The backend now includes enhanced data persistence and search capabilities:

  1. Enhanced DynamoDB Storage - Tables with Global Secondary Indexes (GSIs) for efficient querying
  2. OpenSearch Integration - Full-text search and analytics capabilities
  3. Automatic Indexing - Real-time indexing of insights, anomalies, and clusters
  4. Time-Series Analytics - Aggregations and analytics for metrics data

Key Features

  • Agentic AI Pipeline: Uses Strands Agents SDK to implement a multi-agent system
  • Dual-mode Architecture: Supports both local development and AWS deployment
  • Enhanced Data Persistence: DynamoDB tables with Global Secondary Indexes (GSIs) for efficient querying
  • Full-text Search: AWS OpenSearch integration with automatic indexing and relevance scoring
  • Advanced Analytics: Time-series analytics with aggregations and multiple aggregation types
  • Proactive Insights: Correlates infrastructure metrics with support tickets
  • RESTful API: Provides endpoints for insights, analysis, and health checks
  • Scheduled Processing: Automated pipeline execution with configurable intervals
  • Extensible Design: Modular architecture for adding new agents and capabilities

Prerequisites

  • Python 3.10+
  • pip package manager
  • Virtual environment (recommended)

Installation

  1. Create and activate a virtual environment:

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  2. Install dependencies:

    pip install -r requirements.txt

  3. Install Strands Agents SDK:

    pip install strands-agents strands-agents-tools

Configuration

  1. Copy the example environment file:

    cp .env.example .env

  2. Edit the .env file to set your configuration:

    • Set MODE=local for local development or MODE=aws for AWS deployment
    • Configure AWS credentials if using AWS mode
    • Set OpenSearch configuration for AWS mode (endpoint, index prefix, SSL settings)
    • Adjust other settings as needed

Running the Application

Local Development

uvicorn main:app --reload --port 8000

The API will be available at http://localhost:8000

Production Deployment

For AWS deployment, the application can be deployed as Lambda functions with API Gateway.

API Endpoints

  • GET / - Root endpoint with system information
  • GET /health - Health check endpoint
  • GET /health/config - System configuration
  • GET /health/status - Detailed status information
  • GET /insights - List insights with pagination
  • GET /insights/{id} - Get detailed insight information
  • DELETE /insights/{id} - Delete an insight
  • GET /insights/{id}/related - Get related insights
  • POST /analysis/run - Trigger on-demand analysis
  • GET /analysis/status/{run_id} - Get analysis run status
  • GET /analysis/history - Get analysis run history
  • GET /search/insights - Full-text search for insights with filtering
  • GET /search/analytics - Time-series analytics with aggregations

Multi-Agent Workflow

The agentic pipeline follows this workflow:

  1. Data Ingestion: Load recent metrics and tickets data
  2. Anomaly Detection: Identify unusual patterns in metrics
  3. Ticket Analysis: Cluster similar support tickets
  4. Correlation: Link anomalies with ticket clusters
  5. Insight Generation: Create actionable insights
  6. Data Indexing: Automatically index insights in OpenSearch
  7. Notification: Send proactive digests (if configured)

Development

Adding New Agents

To add a new specialized agent:

  1. Create a new agent class in the app/agents/ directory
  2. Inherit from ProactivePulseAgent
  3. Implement the agent's specific functionality
  4. Register the agent with the OrchestratorAgent

Testing

Run tests with pytest:

pytest

Deployment

AWS Deployment

For AWS deployment, the application can be packaged as Lambda functions with API Gateway.

See the main project README for detailed deployment instructions.

License

MIT License - AWS Superhack AgenticAI Hackathon 2025