From db62e2d92dca417958b541bfa71c71fe42bca0c5 Mon Sep 17 00:00:00 2001 From: michael Date: Sun, 17 Aug 2025 07:29:50 -0500 Subject: [PATCH] updated README --- .gitignore | 2 + README.md | 599 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 601 insertions(+) create mode 100644 README.md diff --git a/.gitignore b/.gitignore index f7275bb..620ca43 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ venv/ + +__pycache__/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..56bea97 --- /dev/null +++ b/README.md @@ -0,0 +1,599 @@ +# 🤖 AgentHub + +**Modern AI Agent Management System with Advanced Analytics** + +AgentHub is a comprehensive, production-ready FastAPI application for managing AI agents across your organization. It provides role-based access control, usage analytics, dual authentication systems, and a modern responsive web interface. + +[![FastAPI](https://img.shields.io/badge/FastAPI-0.116.1-009688?style=flat-square&logo=fastapi)](https://fastapi.tiangolo.com/) +[![MongoDB](https://img.shields.io/badge/MongoDB-Latest-47A248?style=flat-square&logo=mongodb)](https://www.mongodb.com/) +[![Bootstrap](https://img.shields.io/badge/Bootstrap-5.3.7-7952B3?style=flat-square&logo=bootstrap)](https://getbootstrap.com/) +[![Azure AD](https://img.shields.io/badge/Azure%20AD-Supported-0078D4?style=flat-square&logo=microsoft)](https://azure.microsoft.com/en-us/services/active-directory/) + +## ✨ Key Features + +### 🔐 **Dual Authentication Systems** +- **Local Authentication**: Traditional email/password with bcrypt hashing +- **Azure AD Integration**: Enterprise SSO with MSAL and PKCE flow +- **JWT Token Management**: Secure cookie-based sessions +- **Role-Based Access Control**: Admin and user permissions + +### 🤖 **Comprehensive Agent Management** +- **Full CRUD Operations**: Create, read, update, delete AI agents +- **Rich Metadata**: Name, description, purpose, version, status, location, department, contact, tags, userbase, capabilities +- **Status Tracking**: Active, Development, Inactive, Deprecated +- **User Ownership**: Users can only edit their own agents (admins can edit all) +- **Advanced Search**: Full-text search across agent fields +- **Real-time Filtering**: Filter by status, sort by various criteria + +### 📊 **Usage Analytics & Monitoring** +- **Usage Tracking**: Monitor agent usage patterns over time +- **Interactive Charts**: Chart.js visualizations with daily/weekly/monthly views +- **Usage Statistics**: Total usage, first/last usage tracking +- **Date Range Filtering**: Custom date range analysis +- **Health Monitoring**: Database connectivity and system health checks + +### 👥 **User Management** +- **User Registration**: Self-service account creation +- **Admin Interface**: Comprehensive user management for administrators +- **Profile Management**: User profile editing and management +- **Access Control**: Fine-grained permission management + +### 🎨 **Modern Web Interface** +- **Responsive Design**: Mobile-first Bootstrap 5 interface +- **Modern UI/UX**: Custom CSS with gradients, animations, and smooth transitions +- **Interactive Components**: Modals, dropdowns, tabs, and dynamic content +- **Accessibility**: ARIA labels and keyboard navigation support +- **Dark Theme Support**: CSS variables for easy theming + +### 🔌 **API Integration** +- **RESTful API**: Complete REST API for all operations +- **Agent Collector API**: External system integration for automatic agent discovery +- **OpenAPI Documentation**: Auto-generated API docs with FastAPI +- **Health Endpoints**: System monitoring and diagnostics + +## 🏗️ Architecture + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Web Interface │ │ REST API │ │ External APIs │ +│ (Bootstrap 5) │────│ (FastAPI) │────│ (Collector) │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ │ + └───────────────────────┼───────────────────────┘ + │ + ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ + │ Authentication │ │ Business │ │ Data Layer │ + │ (JWT + MSAL) │────│ Logic │────│ (MongoDB) │ + └─────────────────┘ └─────────────────┘ └─────────────────┘ +``` + +### Technology Stack +- **Backend**: FastAPI (Python 3.8+) +- **Database**: MongoDB with Motor (async driver) +- **Authentication**: JWT + Azure AD/MSAL +- **Frontend**: Bootstrap 5 + Jinja2 templates +- **Charts**: Chart.js for analytics +- **Deployment**: Uvicorn + Systemd +- **Security**: bcrypt, python-jose, CSRF protection + +## 🚀 Quick Start + +1. **Clone and Install** + ```bash + git clone + cd agent_app + python -m venv venv + source venv/bin/activate # Windows: venv\Scripts\activate + pip install -r requirements.txt + ``` + +2. **Configure Environment** + ```bash + cp .env.example .env + # Edit .env with your configuration + ``` + +3. **Start MongoDB** + ```bash + # macOS with Homebrew + brew services start mongodb-community + + # Linux with systemd + sudo systemctl start mongod + ``` + +4. **Run Application** + ```bash + uvicorn main:app --reload --port 8000 + ``` + +5. **Access Application** + - Visit: http://localhost:8000 + - Default admin: `admin@agenthub.com` / `admin123` + - Test user: `test@example.com` / `testpass123` + +## 📋 Installation & Setup + +### Prerequisites +- Python 3.8+ +- MongoDB 4.4+ +- Git + +### Local Development Setup + +1. **Environment Setup** + ```bash + python -m venv venv + source venv/bin/activate + pip install -r requirements.txt + ``` + +2. **Environment Configuration** + Create `.env` file: + ```env + # Database + MONGODB_URI=mongodb://localhost:27017 + MONGODB_DBNAME=agenthub_db + + # Security + SECRET_KEY=your-secret-key-here + ALGORITHM=HS256 + ACCESS_TOKEN_EXPIRE_MINUTES=60 + + # Local Development + DISABLE_MSAL=true + BASE_PATH= + + # Agent Collector API + AGENT_COLLECTOR_API_KEY=your-api-key-here + ``` + +3. **Database Setup** + - Install and start MongoDB locally + - No manual database creation needed (auto-created) + +4. **Create Admin User** + ```bash + # Register via web interface first, then promote + python make_admin.py admin@yourdomain.com + ``` + +### Production Setup + +1. **Azure AD Configuration** (Optional) + ```env + DISABLE_MSAL=false + AZURE_CLIENT_ID=your-client-id + AZURE_AUTHORITY=https://login.microsoftonline.com/your-tenant-id + AZURE_REDIRECT_URI=https://your-domain.com/auth/azure/callback + BASE_PATH=/your-app-path + ``` + +2. **Systemd Service** + ```bash + sudo cp agenthub.service /etc/systemd/system/ + sudo systemctl enable agenthub + sudo systemctl start agenthub + ``` + +## 🎯 Usage + +### Agent Management +1. **Create Agent**: Navigate to "Register New Agent" and fill in details +2. **View Agents**: Use "All Agents" or "My Agents" views +3. **Search & Filter**: Use the search bar and status filters +4. **Edit/Delete**: Use action buttons (only for owned agents) +5. **Usage Analytics**: View detailed usage charts and statistics + +### User Management (Admin) +1. **Access Admin Dashboard**: Admin users see admin navigation +2. **Manage Users**: View, edit, activate/deactivate users +3. **Promote Users**: Grant admin privileges to users +4. **Monitor System**: View statistics and system health + +### Search & Discovery +- **Global Search**: Search across agents and users +- **Advanced Filtering**: Filter by status, department, tags +- **Real-time Results**: Instant search as you type + +## 📚 API Documentation + +### Authentication Endpoints +``` +POST /login # Local authentication +GET /auth/azure/login # Azure AD login (if enabled) +GET /auth/azure/callback # Azure AD callback +GET /logout # Logout and clear session +``` + +### Agent API Endpoints +``` +GET /api/agents # Get user's agents +GET /api/agents/all # Get all agents (for users) +POST /api/agents # Create new agent +GET /api/agents/{id} # Get specific agent +PUT /api/agents/{id} # Update agent +DELETE /api/agents/{id} # Delete agent +``` + +### Usage Analytics API +``` +GET /api/agents/{name}/usage # Get usage statistics +GET /api/agents/{name}/usage/chart # Get chart data +``` + +### Admin API Endpoints +``` +GET /api/admin/users # Get all users +PUT /api/admin/users/{email} # Update user +GET /api/admin/agents # Get all agents +``` + +### Agent Collector API +``` +POST /agents # External agent registration +GET / # Health check +``` + +### API Usage Examples + +**Create Agent** +```bash +curl -X POST "http://localhost:8000/api/agents" \ + -H "Content-Type: application/json" \ + -b "access_token=your-jwt-token" \ + -d '{ + "agent_name": "DataProcessor", + "agent_description": "Processes customer data", + "agent_purpose": "Data analysis and reporting", + "agent_status": "Active", + "agent_version": "1.2.0", + "agent_department": "Analytics", + "agent_capabilities": ["data-processing", "reporting"] + }' +``` + +**Get Usage Analytics** +```bash +curl "http://localhost:8000/api/agents/DataProcessor/usage?start_date=2024-01-01&end_date=2024-12-31" \ + -b "access_token=your-jwt-token" +``` + +## 🔧 Configuration + +### Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `MONGODB_URI` | `mongodb://localhost:27017` | MongoDB connection string | +| `MONGODB_DBNAME` | `agenthub_db` | Database name | +| `SECRET_KEY` | *required* | JWT secret key | +| `ALGORITHM` | `HS256` | JWT algorithm | +| `ACCESS_TOKEN_EXPIRE_MINUTES` | `60` | Token expiration time | +| `DISABLE_MSAL` | `false` | Disable Azure AD authentication | +| `BASE_PATH` | `` | Application base path for reverse proxy | +| `AZURE_CLIENT_ID` | *optional* | Azure AD application ID | +| `AZURE_AUTHORITY` | *optional* | Azure AD authority URL | +| `AZURE_REDIRECT_URI` | *optional* | Azure AD callback URL | +| `AGENT_COLLECTOR_API_KEY` | *optional* | API key for collector endpoints | + +### Authentication Modes + +**Local Only** (Development) +```env +DISABLE_MSAL=true +BASE_PATH= +``` + +**Azure AD + Local** (Production) +```env +DISABLE_MSAL=false +BASE_PATH=/your-app-path +AZURE_CLIENT_ID=your-client-id +AZURE_AUTHORITY=https://login.microsoftonline.com/your-tenant +AZURE_REDIRECT_URI=https://your-domain.com/your-app-path/auth/azure/callback +``` + +## 🛠️ Development + +### Project Structure +``` +agent_app/ +├── main.py # FastAPI application and routes +├── models.py # Pydantic data models +├── crud.py # Database operations (CRUD) +├── auth.py # JWT authentication logic +├── database.py # MongoDB connection setup +├── config.py # Configuration management +├── msal_auth.py # Azure AD/MSAL authentication +├── make_admin.py # Admin user promotion script +├── requirements.txt # Python dependencies +├── agenthub.service # Systemd service configuration +├── templates/ # Jinja2 HTML templates +│ ├── base.html # Base template with Bootstrap +│ ├── nav.html # Dynamic navigation component +│ ├── index.html # Landing page +│ ├── login.html # Authentication form +│ ├── register.html # User registration +│ ├── agent_register.html # Agent creation form +│ ├── agent_management.html # Agent dashboard +│ ├── search.html # Global search interface +│ ├── profile.html # User profile management +│ ├── user_management.html # User management interface +│ └── admin/ +│ └── dashboard.html # Admin dashboard with analytics +├── static/ # Static assets +│ ├── style.css # Custom CSS with modern design +│ └── microsoft-logo.svg # Microsoft branding asset +└── documentation/ + ├── CLAUDE.md # Claude Code development guidelines + ├── README_DEV.md # Local development setup guide + ├── FEATURE_SUMMARY.md # Detailed feature breakdown + └── agent_collector_api_documentation.md # API integration guide +``` + +### Development Guidelines + +1. **Code Style**: Follow existing patterns and conventions +2. **Database**: Use Motor async driver with proper ObjectId handling +3. **Authentication**: Use cookie-based auth for web interface +4. **Templates**: Pass `current_user` dict objects to templates +5. **Error Handling**: Implement comprehensive error handling +6. **Security**: Never log or expose secrets, validate all inputs + +### Running Tests +```bash +# Add your test commands here when implemented +pytest tests/ +``` + +### Code Quality +```bash +# Add linting commands here when implemented +flake8 . +black . +``` + +## 🚀 Deployment + +### Production Deployment + +1. **Server Setup** + ```bash + # Install dependencies + apt update && apt install python3 python3-venv mongodb + + # Create application directory + mkdir -p /var/www/html/agent_tracker + cd /var/www/html/agent_tracker + ``` + +2. **Application Setup** + ```bash + # Deploy application files + git clone . + python3 -m venv venv + source venv/bin/activate + pip install -r requirements.txt + ``` + +3. **Service Configuration** + ```bash + # Install systemd service + sudo cp agenthub.service /etc/systemd/system/ + sudo systemctl daemon-reload + sudo systemctl enable agenthub + sudo systemctl start agenthub + ``` + +4. **Nginx Configuration** (Example) + ```nginx + location /agent_tracker { + proxy_pass http://localhost:8038; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + ``` + +### Docker Deployment +```dockerfile +FROM python:3.11-slim + +WORKDIR /app +COPY requirements.txt . +RUN pip install -r requirements.txt + +COPY . . +EXPOSE 8000 + +CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] +``` + +### Environment-Specific Configuration + +**Development**: Local auth only, root path +**Staging**: Azure AD + local, sub-path +**Production**: Azure AD primary, sub-path, enhanced security + +## 🔌 External Integrations + +### Agent Collector API + +External systems can automatically register agents using the Agent Collector API: + +```python +import requests + +# Register agent from external system +agent_data = { + "name": "AutomationBot", + "description": "Automated task processing agent", + "purpose": "Process and analyze customer requests", + "status": "active", + "department": "Customer Success", + "capabilities": ["nlp", "automation", "data-analysis"] +} + +response = requests.post( + "https://your-domain.com/agents", + headers={ + "Content-Type": "application/json", + "X-API-Key": "your-api-key" + }, + json=agent_data +) +``` + +**Features**: +- Automatic agent registration +- Duplicate detection and usage tracking +- Health monitoring integration +- Error handling and retry logic + +## 📈 Analytics & Monitoring + +### Usage Tracking +- **Automatic Collection**: Usage data collected via Agent Collector API +- **Visualization**: Interactive charts with multiple time periods +- **Statistics**: Total usage, trends, peak periods +- **Export**: Data available via REST API + +### System Monitoring +- **Health Checks**: Database connectivity monitoring +- **Performance**: Async operations for scalability +- **Logging**: Comprehensive application logging +- **Metrics**: User and agent statistics + +## 🔒 Security + +### Authentication Security +- **Password Hashing**: bcrypt with salt +- **JWT Tokens**: Secure token generation with expiration +- **CSRF Protection**: State validation for OAuth flows +- **Session Management**: Secure cookie handling + +### Application Security +- **Input Validation**: Pydantic model validation +- **SQL Injection**: MongoDB queries with proper escaping +- **XSS Protection**: Template auto-escaping +- **HTTPS**: TLS encryption in production + +### Access Control +- **Role-Based**: Admin vs user permissions +- **Resource Ownership**: Users can only access their own resources +- **API Authentication**: Token-based API access +- **Admin Functions**: Protected admin-only operations + +## 🤝 Contributing + +1. **Fork the Repository** +2. **Create Feature Branch**: `git checkout -b feature/amazing-feature` +3. **Make Changes**: Follow existing code patterns +4. **Test Changes**: Ensure all functionality works +5. **Commit Changes**: `git commit -m 'Add amazing feature'` +6. **Push Branch**: `git push origin feature/amazing-feature` +7. **Open Pull Request** + +### Development Workflow +- Use virtual environments for isolation +- Follow existing code style and patterns +- Test all authentication flows +- Verify responsive design +- Check admin and user permissions + +## 📝 Common Tasks + +### User Management +```bash +# Create admin user +python make_admin.py user@domain.com + +# Check user status +python -c "import asyncio; import crud; print(asyncio.run(crud.get_user_by_email('user@domain.com')))" +``` + +### Database Operations +```bash +# Access MongoDB directly +mongosh agenthub_db + +# View collections +db.agents.find() +db.users.find() +db.agent_usage.find() +``` + +### Service Management +```bash +# Check service status +sudo systemctl status agenthub + +# View logs +sudo journalctl -u agenthub -f + +# Restart service +sudo systemctl restart agenthub +``` + +## 🐛 Troubleshooting + +### Common Issues + +**Authentication Problems** +- Check JWT secret key configuration +- Verify Azure AD credentials (if using MSAL) +- Clear browser cookies and retry + +**Database Connection** +- Verify MongoDB is running: `sudo systemctl status mongod` +- Check connection string in environment variables +- Validate database permissions + +**Template Rendering** +- Ensure `BASE_PATH` is correctly configured +- Check static file serving configuration +- Verify template context variables + +**Permission Errors** +- Check user roles in database +- Verify admin permissions for management functions +- Review agent ownership for edit/delete operations + +### Debug Mode +```bash +# Enable debug logging +export DEBUG=true +uvicorn main:app --reload --log-level debug +``` + +## 📊 System Requirements + +### Minimum Requirements +- **CPU**: 1 core +- **RAM**: 512MB +- **Storage**: 1GB +- **Network**: 1Mbps + +### Recommended Production +- **CPU**: 2+ cores +- **RAM**: 2GB+ +- **Storage**: 10GB+ (for logs and data) +- **Network**: 10Mbps+ +- **Database**: MongoDB cluster or replica set + +## 📄 License + +This project is licensed under the MIT License - see the LICENSE file for details. + +## 🆘 Support + +- **Documentation**: Check `/docs` endpoint for API documentation +- **Issues**: Report bugs and feature requests via GitHub issues +- **Health Check**: Visit `/debug/config` for system configuration +- **Admin Tools**: Use admin dashboard for system monitoring + +--- + +**AgentHub** - Built with ❤️ using FastAPI, MongoDB, and Bootstrap 5 \ No newline at end of file