TotoAI Hub Overview
🎯 Project Overview
TotoAI Hub is the evolution of toto-agent - a clean, focused AI agent system built specifically for the Toto pet rescue platform. It provides intelligent case-specific interactions using Google Gemini AI and serves as the central AI system for the entire Toto ecosystem.
✅ What We Built
1. Clean Architecture
- No legacy code - Fresh start with modern TypeScript
- Modular design - Easy to extend and maintain
- Type safety - Full TypeScript support with comprehensive types
2. Core Components
BaseAgent Class
- Abstract base class for all agents
- Google Gemini AI integration
- Error handling and response formatting
- Configurable timeouts and retries
CaseAgent
- Specialized for case-specific user interactions
- Provides case information and suggestions
- Extracts actionable items from responses
- Supports multiple languages (Spanish/English)
TwitterAgent
- Monitors guardian Twitter accounts
- Analyzes tweets for case relevance
- Creates case updates and enriches existing cases
- Detects emergencies and urgent situations
- Filters out fundraising requests
- Implements review queue system for manual approval
SchedulerService
- Automated tweet monitoring with cron jobs
- Configurable monitoring intervals
- Task management and scheduling
- Integration with TwitterAgent for continuous monitoring
TwitterService
- Twitter API v2 integration
- Rate limit management
- Tweet fetching and processing
- User data caching
Type System
- Comprehensive TypeScript interfaces
- Case data, user context, and agent response types
- Conversation and learning data structures
- Twitter-specific types and configurations
3. Key Features
- Case Information: Detailed case data with status, funding progress
- Action Suggestions: Donate, share, adopt, contact options
- Multi-language Support: Spanish and English
- User Context Awareness: Role-based responses
- Error Handling: Graceful failure with meaningful messages
- Twitter Monitoring: Automated guardian tweet analysis
- Case Updates: Automatic case update creation and enrichment
- Emergency Detection: Urgent situation identification
- Review Queue: Manual approval system for sensitive actions
- Rate Limiting: Twitter API rate limit management
- Scheduled Tasks: Automated monitoring with cron jobs
🏗️ Architecture Decisions
Why Google Gemini?
- High Quality: Excellent for conversational AI
- Cost Effective: Competitive pricing
- Fast: Low latency responses
- Multilingual: Native Spanish/English support
Why Not LangChain?
- Complexity: Overkill for our current needs
- Dependencies: Version conflicts and bloat
- Simplicity: Direct Google AI integration is cleaner
Why Clean Start?
- No Technical Debt: Fresh, maintainable codebase
- Focused Scope: Only what we actually need
- Easy Integration: Simple to consume from other projects
📦 Integration Points
With toto-app
import { TotoAI } from 'toto-ai-hub';
const totoAI = new TotoAI();
const response = await totoAI.processCaseMessage(
userMessage,
caseData,
userContext
);
With toto-bo
- AI Hub dashboard can consume agent information
- Admin interface for agent management
- Analytics and monitoring capabilities
🚀 Current Status
✅ Completed Features
- BaseAgent: Abstract base class with Google Gemini integration
- CaseAgent: Case-specific user interactions and responses
- TwitterAgent: Guardian tweet monitoring and analysis
- SchedulerService: Automated tweet monitoring with cron jobs
- TwitterService: Twitter API v2 integration and rate limiting
- Type System: Comprehensive TypeScript interfaces
- Build System: Working TypeScript compilation
- Tests: Passing unit tests
- API Endpoints: REST API for agent interactions
- Firebase Integration: Connected to toto-app-stg database
- Review Queue System: Manual approval for case updates
- Emergency Detection: Urgent situation identification
- Case Enrichment: Automatic case data updates from tweets
- Image Processing: Tweet image download and Firebase Storage upload
🔄 In Progress
- Production Deployment: Server deployment and monitoring
- Performance Optimization: Response time improvements
- Error Handling: Enhanced error recovery
- Authentication: Secure API access implementation
📋 Future Enhancements
- Learning System: Improve responses based on feedback
- Multi-Agent Orchestration: Coordinate multiple agents
- Analytics Dashboard: Comprehensive performance monitoring
- Webhook Integration: Real-time notifications for case updates
- Advanced Filtering: Improved tweet relevance detection
🎉 Success Metrics
- Clean Code: No legacy dependencies or technical debt
- Type Safety: 100% TypeScript coverage
- Test Coverage: Core functionality tested
- Performance: Fast response times with Google Gemini
- Maintainability: Easy to extend and modify
🔧 Development Commands
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Development mode
npm run dev
📝 Environment Setup
Required Environment Variables
# Google AI Configuration
GOOGLE_AI_API_KEY=your_gemini_api_key
# Twitter API Configuration (for TwitterAgent)
TWITTER_API_KEY=your_twitter_api_key
TWITTER_API_SECRET=your_twitter_api_secret
TWITTER_ACCESS_TOKEN=your_twitter_access_token
TWITTER_ACCESS_TOKEN_SECRET=your_twitter_access_token_secret
# Firebase Configuration (for data persistence)
TOTO_APP_STG_SERVICE_ACCOUNT_KEY=your_firebase_service_account_json
# Server Configuration
PORT=8080
NODE_ENV=production
🚀 Deployment
Development Setup
# Install dependencies
npm install
# Build the project
npm run build
# Start development server
npm run dev
# Run tests
npm test
Production Deployment
# Build for production
npm run build
# Start production server
npm start
# Or use PM2 for process management
pm2 start server.js --name toto-ai-hub
Health Checks
# Check service health
curl https://your-toto-ai-hub-domain.com/health
# Check available agents
curl https://your-toto-ai-hub-domain.com/api/agents
# Test case processing
curl -X POST https://your-toto-ai-hub-domain.com/api/case \
-H "Content-Type: application/json" \
-d '{"message": "test", "caseData": {}, "userContext": {}}'
🔐 Security
API Security
- All endpoints are protected with proper input validation
- Rate limiting implemented to prevent abuse
- Error handling prevents information leakage
- Environment variables for sensitive configuration
Data Privacy
- No user data is stored permanently
- All conversations are processed in memory
- Twitter data is analyzed but not stored
- Firebase integration follows security best practices
📞 Troubleshooting
Common Issues
High Response Times:
- Check Google AI API rate limits
- Monitor server resources
- Review case data complexity
- Consider caching strategies
Twitter Agent Issues:
- Verify Twitter API credentials
- Check rate limit status
- Monitor guardian account access
- Review tweet analysis accuracy
Case Processing Errors:
- Validate case data format
- Check user context completeness
- Review agent configuration
- Monitor error logs
Debug Commands
# Check service health
curl https://your-toto-ai-hub-domain.com/health
# Check Twitter rate limits
curl https://your-toto-ai-hub-domain.com/api/twitter/rate-limits
# Test case processing
curl -X POST https://your-toto-ai-hub-domain.com/api/case \
-H "Content-Type: application/json" \
-d '{"message": "test", "caseData": {}, "userContext": {}}'
# Monitor server logs
pm2 logs toto-ai-hub
🔄 Migration from toto-agent
TotoAI Hub represents the evolution of the original toto-agent system. Key improvements include:
- Cleaner Architecture: Removed legacy code and technical debt
- Better Type Safety: Enhanced TypeScript support
- Simplified Integration: Easier to consume from other projects
- Focused Scope: Only essential features, no bloat
- Modern Dependencies: Up-to-date packages and best practices
🔗 Related Resources
- API Reference - Complete API documentation
- Google AI: Gemini API Documentation
- Twitter API: Twitter API v2 Documentation
- Firebase: Firebase Admin SDK
- Express.js: Express.js Documentation
Built with ❤️ for the Toto pet rescue platform