{"id":24542660,"url":"https://github.com/kaymen99/personal-ai-assistant","last_synced_at":"2026-02-15T12:38:09.747Z","repository":{"id":255091414,"uuid":"848515151","full_name":"kaymen99/personal-ai-assistant","owner":"kaymen99","description":"Your personal AI assistant powered by multiple AI agents. Connects to WhatsApp, Slack, or Telegram to manage your emails, schedule, to-dos, messages, and daily research.","archived":false,"fork":false,"pushed_at":"2025-01-16T13:51:30.000Z","size":116,"stargazers_count":48,"open_issues_count":0,"forks_count":18,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-10T02:25:24.218Z","etag":null,"topics":["ai-agents","ai-assistants","ai-personal-assistants","langchain","langgraph","multi-agent-systems"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kaymen99.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-27T22:50:37.000Z","updated_at":"2025-07-09T19:43:40.000Z","dependencies_parsed_at":"2024-08-28T00:08:49.060Z","dependency_job_id":"67c0b9a6-0ec3-4b95-bec0-cc2b2a9a0e3a","html_url":"https://github.com/kaymen99/personal-ai-assistant","commit_stats":null,"previous_names":["kaymen99/ai-telegram-assistant","kaymen99/ai-personal-assistant","kaymen99/personal-ai-assistant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kaymen99/personal-ai-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaymen99%2Fpersonal-ai-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaymen99%2Fpersonal-ai-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaymen99%2Fpersonal-ai-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaymen99%2Fpersonal-ai-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaymen99","download_url":"https://codeload.github.com/kaymen99/personal-ai-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaymen99%2Fpersonal-ai-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29478355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T11:35:25.641Z","status":"ssl_error","status_checked_at":"2026-02-15T11:34:57.128Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-assistants","ai-personal-assistants","langchain","langgraph","multi-agent-systems"],"created_at":"2025-01-22T19:14:40.723Z","updated_at":"2026-02-15T12:38:09.732Z","avatar_url":"https://github.com/kaymen99.png","language":"Python","funding_links":[],"categories":["Full-Featured"],"sub_categories":[],"readme":"# AI Personal Assistant\n\n**Imagine a personal assistant in your pocket 📱 that handles your emails 📧, schedule 📅, to-do lists ✅, keeps you updated on Slack messages 💬, and performs online research for you 🔍—all through your favorite messaging app.**\n\n**That's EXACTLY what this AI Personal Assistant does! 🤖✨**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/c284eb2d-1909-48cd-9ab7-b0fbe4709308\" alt=\"personal_assistant\"\u003e\n\u003c/p\u003e\n\nThis project provides a personal assistant agent that manages tasks related to your email inbox, calendar, Notion to-do list, Slack interactions, and handles any research you may have. The assistant communicates with you via your preferred communication channel **(Telegram, Slack, or WhatsApp)**, keeping you informed about your schedule, tasks, emails, messages, and helping with research topics, people, or even companies.\n\nThe personal assistant is a **hierarchical multi-agents** system with a **supervisor agent** (manager) and several sub-agents that handle specific tasks and tools for efficient task management.\n\n## Overview\n\n### Main Agent: Assistant Manager\n\nThe Assistant Manager is your personal assistant that orchestrates the tasks and communication between you and the sub-agents. The manager is responsible for:\n\n- Receiving and analyzing your messages from your chosen communication channel.\n- Delegating tasks to the appropriate sub-agent (Email, Calendar, Notion, Slack, or Researcher).\n- Communicating updates, messages, and any queries back to you via your preferred channel.\n\n### Sub-Agents\n\nThe manager agent can communicate with five specialized sub-agents:\n\n1.  **Email Agent:** Can handle all your email-related tasks, including sending emails, retrieving specific emails, and checking for important messages from your contacts list.\n2.  **Calendar Agent:** Can manage your calendar by creating new events and retrieving and checking your scheduled events.\n3.  **Notion Agent:** Can manage your to-do list in Notion, helping you add, remove, or check tasks as needed.\n4.  **Slack Agent:** Can manage your Slack interactions by reading messages from channels or DMs and sending messages on your behalf.\n5.  **Researcher Agent:** Can perform web research, scrape websites, and gather information from LinkedIn profiles to assist with research tasks.\n\nAll the sub-agents report back to the Assistant Manager after completing their respective tasks.\n\n## Tech Stack\n\n-   **LangGraph \u0026 LangChain**: Frameworks used for building the AI agents and interacting with LLMs (GPT-4, Llama 3, Gemini).\n-   **LangSmith**: For monitoring the different LLM calls and AI agents' interactions.\n-   **Google APIs**: Provides access to Google services like Calendar, Contacts, and Gmail.\n-   **Notion Client**: Interface for interacting with Notion to manage and update to-do lists.\n-   **Slack SDK**: For interacting with Slack, sending and receiving messages.\n-   **Tavily Search API**: For performing web searches.\n-   **Telegram API**: Depending on your choice of communication channel.\n-   **WhatsApp API via Twilio Sandbox (for testing)**: A way to integrate WhatsApp communication.\n\n## How to Run\n\n### Prerequisites\n\n-   Python 3.9+\n-   Your preferred LLM provider API keys (OpenAI, Claude, Gemini, Groq,...)\n-   Google API credentials (for Calendar, Contacts, and Gmail access)\n-   Notion API key\n-   Tavily API key (for web research)\n-   Slack Bot User OAuth Token and App Token\n-   Telegram Bot Token (If you want to use telegram)\n-   Twilio Account SID and Auth Token (If you want to test with WhatsApp)\n-   Necessary Python libraries (listed in `requirements.txt`)\n\n### Setup\n\n1.  **Clone the repository:**\n\n    ```sh\n    git clone https://github.com/kaymen99/AI-personal-assistant\n    cd AI-personal-assistant\n    ```\n\n2.  **Create and activate a virtual environment:**\n\n    ```sh\n    python -m venv venv\n    source venv/bin/activate  # On Windows use `venv\\Scripts\\activate`\n    ```\n\n3.  **Install the required packages:**\n\n    ```sh\n    pip install -r requirements.txt\n    ```\n\n4.  **Set up environment variables:**\n\n    Create a `.env` file in the root directory of the project and add your API keys, see `.env.example` to know all the parameters you will need.\n\n5.  **Configure Google API credentials:**\n\n    Follow Google's documentation to set up credentials for Calendar, Contacts, and Gmail APIs. Save the credentials file in your project folder.\n\n6.  **Set up Communication Channel:**\n\n    -   **Telegram:**\n        -   Create a Telegram Bot: To interact with the assistant via Telegram, you will need to create a Telegram bot and obtain the bot token. Follow this [guide](https://www.youtube.com/watch?v=ozQfKhdNjJU) to create your bot and get the necessary information.\n    -   **Slack:**\n        -   Create a Slack App: Follow the official Slack documentation to create a new Slack app, add the necessary OAuth scopes (refer to the provided code and documentation for the required scopes).\n        -   Install the app to your workspace and obtain your Bot User OAuth Token and App-Level Token.\n    -   **WhatsApp (via Twilio Sandbox for Testing):**\n        - **Important Note:** Normally, interacting with the **WhatsApp Business API** requires a **Meta Business Account**. However, for **testing purposes only**, this project utilizes the Twilio WhatsApp Sandbox.\n        - **Twilio Sandbox Limitations:**  As stated in the [Twilio documentation](https://www.twilio.com/docs/whatsapp/sandbox), \"Use the Twilio Sandbox for WhatsApp for testing and discovery purposes only. You should not use it in production.\"\n        - **Setup:**\n          1.  Create a Twilio account and obtain your Account SID and Auth Token.\n          2.  Follow Twilio's tutorial to set up the WhatsApp Sandbox: [Twilio WhatsApp Sandbox Setup](https://www.twilio.com/docs/whatsapp/sandbox).\n          3.  Save your Twilio Account SID, Auth Token and Sandbox number in your `.env` file.\n\n7.  **Run the project**:\n    - For running the personal assistant on **Slack or Telegram** you'll only need to run:\n\n      ```bash\n      python app.py\n      ```\n\n    - For running the personal assistant on **whatsApp** you'll need to run:\n\n      ```bash\n      python run app_whatsapp.py\n      ```\n\n      This will spin out a local fastAPI server, to enable the communication with the Twilio servers you need to make it public using **Ngrok**:\n\n      1. Expose the Webhook URL Using ngrok\n\n         ```bash\n         ngrok http 5000\n         ```\n      2. Configure Twilio Webhook\n\n         1. Go to the Twilio Console \u003e Messaging \u003e Sandbox for WhatsApp.\n         2. In the Sandbox settings section: Set the \"WHEN A MESSAGE COMES IN\" URL to your ngrok URL and save your configuration.\n      \n      **You're done now you can talk with your assistant via whatsApp**\n\n### Usage\n\n**Communicating with the Assistant**: Simply send a message to your configured communication channel (Telegram, Slack channel, or WhatsApp), and the assistant will analyze the message, delegate the tasks to the appropriate sub-agents, and report back to you with the results.\n\n## Contribution\n\nFeel free to fork the repository, create a branch, and submit a pull request if you'd like to contribute to the project.\n\n## Contact\n\nFor any queries or suggestions, please reach out to [aymenMir1001@gmail.com](mailto:aymenMir1001@gmail.com)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaymen99%2Fpersonal-ai-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaymen99%2Fpersonal-ai-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaymen99%2Fpersonal-ai-assistant/lists"}