alpha-79-xf/digital-twin-assistant

Jack's Digital Twin Assistant 🤖

An AI-powered digital twin assistant that acts as a personal representative, capable of answering questions about Jack Ma's background, skills, experience, and more. Built with Streamlit and powered by advanced AI agents with built-in guardrails and contact management.

🌟 Features

• —Intelligent Q&A System: Answers questions about personal information based on YAML data
• —Multi-layered Guardrails: Built-in response review system to ensure appropriate and accurate responses
• —Contact Management: Collects user contact information for follow-up when questions can't be answered
• —Email Notifications: Automatic email alerts for unanswered questions and contact requests
• —Conversation History: Maintains chat history with approval status tracking
• —Tracing & Debugging: Comprehensive tracing system for monitoring and debugging
• —Responsive UI: Clean, modern interface with real-time status updates

🏗️ Architecture

The application uses a multi-agent architecture:

1. 1.Digital Twin Agent: Primary agent that responds as Jack Ma
2. 2.Guardrail Agent: Secondary agent that reviews responses for appropriateness
3. 3.Contact Collection System: Manages user contact information and notifications
4. 4.Tracing System: Monitors performance and helps with debugging

📋 Prerequisites

• —Python 3.8+
• —Google API Key (for Gemini AI)
• —Gmail account for email notifications
• —Personal information in YAML format

🚀 Installation

1. 1.Clone the repository

   git clone <repository-url>
   cd Jack-digital-twin

1. 1.Install dependencies

   pip install -r requirements.txt

1. 1.Set up environment variables Create a .env file in the project root:

   GOOGLE_API_KEY=your_google_api_key_here
   EMAIL_SENDER=your_gmail_address@gmail.com
   EMAIL_PASSWORD=your_gmail_app_password
   EMAIL_RECEIVER=recipient_email@gmail.com

1. 1.Create personal information file Create a personal_info.yaml file with your information:

   personal_info:
     name: "Your Name"
     birth_year: Age
     education:
       - degree: "Data Engineering"
         institution: "School"
         status: "Currently studying"
     experience:
       - role: "Rple"
         company: "Current workplace"
         type: "Part-time"
       - role: "Data Engineering Intern"
         company: "Various companies"
         type: "Internship"
     skills:
       programming_languages:
         - "Python"
         - "SQL"
         - "Bash"
       technologies:
         - "Streamlit"
         - "AI/ML"
         - "Data Engineering"
       certifications:
         - "Microsoft Certified"

🔧 Configuration

Environment Variables

Gmail Setup

1. 1.Enable 2-factor authentication on your Gmail account
2. 2.Generate an app password:
3. 3.Go to Google Account settings
4. 4.Security → 2-Step Verification → App passwords
5. 5.Generate a password for "Mail"
6. 6.Use this password in the EMAIL_PASSWORD variable

📖 Usage

Running the Application

1. 1.Start the Streamlit app

   streamlit run main.py

1. 1.Access the application
2. 2.Open your browser and go to http://localhost:8501
3. 3.The interface will load with the digital twin assistant

Using the Interface

1. 1.Ask Questions
2. 2.Type your question in the text area
3. 3.Click "Send Question" to get a response
4. 4.The system will provide answers based on the YAML data

1. 1.Question Types
2. 2.Personal Information: Age, skills, education, experience
3. 3.General Questions: Brief answers with redirection to personal topics
4. 4.Unanswerable Questions: Triggers contact collection process

1. 1.Contact Collection
2. 2.If a question can't be answered, the system will offer to collect contact information
3. 3.Provide your name, email, and/or phone number
4. 4.The question will be forwarded to Jack for follow-up

1. 1.Conversation Management
2. 2.View conversation history with approval status
3. 3.Clear conversation history when needed
4. 4.Monitor response review status

🔍 System Behavior

Response Categories

1. 1.Approved Responses: ✅
2. 2.Based on YAML data
3. 3.Appropriate redirection
4. 4.Proper contact collection handling

1. 1.Rejected Responses: ❌
2. 2.Violates instructions
3. 3.Provides incorrect information
4. 4.Requires manual review

1. 1.Error Responses: ⚠️
2. 2.Technical issues
3. 3.Processing errors
4. 4.System failures

Contact Collection Triggers

• —Questions related to Jack but not in YAML data
• —Requests for detailed information not available
• —Follow-up inquiries requiring personal response

📁 File Structure

Jack-digital-twin/
├── mainV4.py                 # Main application file
├── personal_info.yaml        # Personal information data
├── requirements.txt          # Python dependencies
├── .env                      # Environment variables
├── unanswered_questions.log  # Log file for unanswered questions
└── README.md                 # This file

🔧 Dependencies

streamlit>=1.28.0
python-dotenv>=1.0.0
google-generativeai>=0.3.0
openai>=1.0.0
pydantic>=2.0.0
agents>=1.0.0
PyYAML>=6.0

🐛 Troubleshooting

Common Issues

1. 1.API Key Errors
2. 2.Verify your Google API key is valid
3. 3.Check if the API key has proper permissions
4. 4.Ensure the key is correctly set in the .env file

1. 1.Email Sending Failures
2. 2.Verify Gmail app password is correct
3. 3.Check if 2-factor authentication is enabled
4. 4.Ensure the sender email is valid

1. 1.YAML Loading Errors
2. 2.Verify the personal_info.yaml file exists
3. 3.Check YAML syntax is correct
4. 4.Ensure file encoding is UTF-8

1. 1.Model Loading Issues
2. 2.Check internet connection
3. 3.Verify API quotas and limits
4. 4.Ensure the agents library is properly installed

Debug Mode

The application includes comprehensive tracing. To view traces:

1. 1.Check the console output for trace information
2. 2.Monitor the unanswered_questions.log file
3. 3.Review email notifications for system status

🔒 Security Considerations

• —API Keys: Never commit API keys to version control
• —Email Credentials: Use app passwords, not account passwords
• —Data Privacy: Personal information is stored locally in YAML format
• —Input Validation: Built-in guardrails prevent inappropriate responses

🤝 Contributing

1. 1.Fork the repository
2. 2.Create a feature branch
3. 3.Make your changes
4. 4.Add tests if applicable
5. 5.Submit a pull request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

For technical support or questions:

• —Create an issue in the repository
• —Contact Jack Ma directly
• —Review the troubleshooting section above

🚀 Future Enhancements

• —[ ] Multi-language support
• —[ ] Voice input/output capabilities
• —[ ] Integration with calendar systems
• —[ ] Advanced analytics and reporting
• —[ ] Custom theme support
• —[ ] Mobile app version
• —[ ] Integration with social media platforms

📊 Monitoring

The application logs:

• —All unanswered questions
• —Contact collection requests
• —System errors and performance metrics
• —Response approval/rejection status

Monitor the unanswered_questions.log file and email notifications to stay informed about system activity.

Built with ❤️ by Jack Ma using Streamlit and AI Agents