Skip to content

README.md

Latest commit

 

History

History
141 lines (107 loc) · 4.59 KB

README.md

File metadata and controls

141 lines (107 loc) · 4.59 KB

ProactivePulse AI Documentation

This directory contains comprehensive documentation for the ProactivePulse MSP Insight Agent system.

Documentation Structure

  • architecture.md - System architecture and design patterns
  • api-reference.md - Complete API documentation
  • data-models.md - Data structures and schemas
  • deployment.md - Deployment guides for local and AWS
  • user-guide.md - End-user documentation
  • development.md - Developer setup and contribution guidelines
  • troubleshooting.md - Common issues and solutions

Quick Links

For Developers

For Users

For DevOps

System Overview

ProactivePulse is a dual-mode system that correlates infrastructure metrics with support tickets to generate proactive insights for Managed Service Providers (MSPs).

Key Features

  • Anomaly Detection: Identifies unusual patterns in metrics
  • Ticket Clustering: Groups similar support issues
  • Correlation Engine: Links anomalies with ticket patterns
  • Proactive Insights: Generates root-cause hypotheses and recommended actions
  • Dual Mode: Runs locally for development or on AWS for production

Architecture Modes

Local Mode (MODE=local):

  • scikit-learn for anomaly detection
  • sentence-transformers for NLP
  • Local file system storage
  • FastAPI development server

AWS Mode (MODE=aws):

  • Amazon SageMaker for anomaly detection
  • Amazon Bedrock for NLP and text generation
  • S3 and DynamoDB for storage
  • Lambda functions with API Gateway

AWS Deployment

Prerequisites

  1. AWS Account with appropriate permissions
  2. AWS CLI configured with credentials
  3. S3 buckets for data storage
  4. DynamoDB tables for structured data
  5. IAM roles and policies for service access

Configuration

To deploy in AWS mode:

  1. Set MODE=aws in your environment configuration
  2. Configure AWS credentials using one of these methods:
    • AWS credentials file (~/.aws/credentials)
    • Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
    • IAM roles (for EC2 or Lambda deployments)
  3. Update the following AWS-specific configuration values:
    • AWS_REGION: Your preferred AWS region
    • S3_BUCKET_RAW: S3 bucket for raw data
    • S3_BUCKET_PROCESSED: S3 bucket for processed data
    • DYNAMODB_INSIGHTS_TABLE: DynamoDB table for insights
    • DYNAMODB_ANOMALIES_TABLE: DynamoDB table for anomalies
    • DYNAMODB_CLUSTERS_TABLE: DynamoDB table for clusters
    • AWS_BEDROCK_MODEL_TEXT: Bedrock model for text generation
    • AWS_BEDROCK_MODEL_EMBED: Bedrock model for embeddings

Required AWS Resources

The system requires the following AWS resources to be created:

  1. S3 Buckets:

    • Raw data bucket for incoming tickets and metrics
    • Processed data bucket for analyzed results

  2. DynamoDB Tables:

    • Insights table for storing generated insights
    • Anomalies table for storing detected anomalies
    • Clusters table for storing ticket clusters

  3. IAM Roles and Policies:

    • Permissions for S3 read/write operations
    • Permissions for DynamoDB read/write operations
    • Permissions for Bedrock model access
    • Permissions for SageMaker endpoint invocation (if using)

  4. Bedrock Model Access:

    • Enable access to selected Bedrock models in the AWS console

  5. SageMaker Endpoint (optional):

    • Deploy a Random Cut Forest model for enhanced anomaly detection

Environment Variables

See .env.example for a complete list of environment variables with descriptions.

For AWS deployment, the following variables are particularly important:

MODE=aws
AWS_REGION=us-east-1
S3_BUCKET_RAW=your-raw-data-bucket
S3_BUCKET_PROCESSED=your-processed-data-bucket
DYNAMODB_INSIGHTS_TABLE=YourInsightsTable
DYNAMODB_ANOMALIES_TABLE=YourAnomaliesTable
DYNAMODB_CLUSTERS_TABLE=YourClustersTable
AWS_BEDROCK_MODEL_TEXT=amazon.nova-lite-v1
AWS_BEDROCK_MODEL_EMBED=amazon.titan-embed-text-v1

Getting Help

  • Issues: Report bugs and feature requests on GitHub
  • Discussions: Join community discussions
  • Documentation: Check relevant documentation files
  • Support: Contact the development team

Contributing

See Development Guide for information on:

  • Setting up development environment
  • Code style and standards
  • Testing requirements
  • Pull request process