{"id":31165316,"url":"https://github.com/oxi-p/dentaldesk","last_synced_at":"2026-04-30T22:32:17.924Z","repository":{"id":313811565,"uuid":"1051697390","full_name":"oxi-p/DentalDesk","owner":"oxi-p","description":"DentalDesk: An open-source AI dental assistant and chatbot for dental practices. Built with   Python and LangChain, it automates appointment scheduling and patient communication on WhatsApp.","archived":false,"fork":false,"pushed_at":"2025-09-08T15:07:28.000Z","size":2676,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-08T17:22:27.201Z","etag":null,"topics":["ai-assistant","appointment-scheduling","automation","chatbot","conversational-ai","dental-assistant","dental-practice","langchain","langgraph","open-source","openai","python","whatsapp","whatsapp-chatbot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxi-p.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-06T14:36:46.000Z","updated_at":"2025-09-08T15:07:31.000Z","dependencies_parsed_at":"2025-09-08T17:22:48.549Z","dependency_job_id":null,"html_url":"https://github.com/oxi-p/DentalDesk","commit_stats":null,"previous_names":["oxi-p/dentaldesk"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/oxi-p/DentalDesk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxi-p%2FDentalDesk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxi-p%2FDentalDesk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxi-p%2FDentalDesk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxi-p%2FDentalDesk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxi-p","download_url":"https://codeload.github.com/oxi-p/DentalDesk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxi-p%2FDentalDesk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275902529,"owners_count":25549246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-19T02:00:09.700Z","response_time":108,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-assistant","appointment-scheduling","automation","chatbot","conversational-ai","dental-assistant","dental-practice","langchain","langgraph","open-source","openai","python","whatsapp","whatsapp-chatbot"],"created_at":"2025-09-19T08:09:19.079Z","updated_at":"2025-09-19T08:09:21.512Z","avatar_url":"https://github.com/oxi-p.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DentalDesk 🦷\n\nA conversational AI assistant for dental practices, powered by LangGraph and WhatsApp.\n\nDentalDesk is a free and open-source AI chatbot that acts as a virtual dental assistant for your clinic. It automates patient communication on WhatsApp, handling appointment scheduling, new patient registration, and answering FAQs 24/7, freeing up your staff to focus on patient care.\n\n## ✨ Key Features\n\n- **WhatsApp-Based Interface**: Meets patients where they are, providing a convenient and familiar communication channel.\n- **Appointment Management**: Allows patients to book, reschedule, and cancel appointments conversationally.\n- **New Patient Registration**: Gathers essential information (name, age, gender) from new patients to streamline their first visit.\n- **Conversational AI**: Built with LangChain and LangGraph for robust, stateful, and intelligent conversations.\n- **Persistent Memory**: Remembers conversation history across restarts, ensuring a seamless user experience.\n- **Extensible Architecture**: Uses the Machine-to-Machine Communication Protocol (MCP) to cleanly separate the agent's logic from the clinic's tools and data, making it easy to add new capabilities.\n\n## 💬 Showcase\n\nHere are screenshots of a complete conversation, from registration to enquiring, booking, rescheduling, and finally cancelling an appointment.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"docs/images/chat-1.png\" alt=\"New patient registration\" width=\"200\"/\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"docs/images/chat-2.png\" alt=\"Booking an appointment\" width=\"200\"/\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"docs/images/chat-3.png\" alt=\"Rescheduling an appointment\" width=\"200\"/\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"docs/images/chat-4.png\" alt=\"Cancelling an appointment\" width=\"200\"/\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"docs/images/chat-5.png\" alt=\"Final confirmation from the agent\" width=\"200\"/\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## ⚙️ How It Works\n\nDentalDesk has a decoupled architecture that makes it robust and easy to maintain.\n\n1.  **The Agent (`src/app`)**: This is the core of the application. It uses a LangGraph `StateGraph` to manage the flow of conversation, decide when to call tools, and formulate responses. It maintains the conversation state and interacts with the message queue.\n\n2.  **The MCP Server (`src/dentaldesk_mcp`)**: This server acts as the \"backend for the AI.\" It exposes the clinic's business logic and data as a set of tools and prompts that the agent can use. For example, it provides tools like `book_appointment` and `list_dentists` and serves the base system prompt.\n\n3.  **The Shared Library (`src/shared`)**: Contains the database models (Pydantic) and access functions used by both the Agent and the MCP Server, ensuring consistency.\n\n**Conversation Flow:**\n\n`WhatsApp Message` -\u003e `Webhook` -\u003e `enqueue_message()` -\u003e `consume_messages()` -\u003e `Agent Logic (LangGraph)` -\u003e `MCP Server (Tools)` -\u003e `Database`\n\n## 🚀 Getting Started\n\nFollow these instructions to get a local copy of DentalDesk up and running.\n\n### Prerequisites\n\n- Python 3.13+\n- [uv](https://github.com/astral-sh/uv) (for environment and package management)\n- An OpenAI API Key\n- WhatsApp Business Account and API credentials\n\n### Installation\n\n1.  **Clone the repository:**\n    ```sh\n    git clone git@github.com:oxi-p/DentalDesk.git\n    cd DentalDesk\n    ```\n\n2.  **Install dependencies and sync the environment:**\n    `uv` will automatically create a virtual environment and install all dependencies from the `uv.lock` file.\n    ```sh\n    uv sync\n    ```\n\n3.  **Configure your environment:**\n    - Copy the example environment file:\n      ```sh\n      cp example.env .env\n      ```\n    - Edit the `.env` file to add your `OPENAI_API_KEY` and any other required credentials (like WhatsApp API tokens).\n\n### Running the Application\n\nUse the `run` command in `uv` to start the application. This will start the main agent, which in turn launches the MCP server as a subprocess.\n\n```sh\nuv run server\n```\n\n### Verifying the Setup\n\nThe repository includes a simple client script to test the MCP server independently. This is a great way to confirm that the server is working and the tools are correctly exposed.\n\nFrom the project root, run the following command:\n```sh\nuv run src/app/mcp_client.py\n```\n\nYou should see a list of the available tools followed by a JSON list of the default dentists seeded in the database.\n\n## Advanced Usage\n\n### Running the MCP Server Standalone\n\nThe MCP server (`dentaldesk-mcp`) can be run as a standalone process. This is useful for development or for integrating the dental tools with other systems, such as the Gemini CLI.\n\nTo run the server by itself:\n```sh\nuv run dentaldesk-mcp\n```\n\nBelow is an example of how you could configure a tool in Gemini CLI to use this standalone server:\n\n```json\n\"dentaldesk-mcp\": {\n  \"command\": \"uv\",\n  \"args\": [\n    \"run\",\n    \"dentaldesk-mcp\"\n  ],\n  \"transport\": \"stdio\",\n  \"cwd\": \"\u003cpath-to-your-project-folder\u003e\",\n  \"env\": {\n    \"PYTHONUNBUFFERED\": \"1\"\n  }\n}\n```\n\n## Project Structure\n\n```\n.\n├── data/                 # Contains the SQLite database files.\n│   └── dentaldesk_app.db\n├── src/\n│   ├── app/              # The core agent application.\n│   │   ├── agent.py      # Graph creation and state management.\n│   │   └── main.py       # Main entry point, message queue, and consumer.\n│   ├── dentaldesk_mcp/      # The MCP server providing tools and prompts.\n│   │   └── server.py\n│   └── shared/           # Shared code, primarily for database interaction.\n│       ├── db.py\n│       └── models.py\n├── .env                  # Your local environment variables (ignored by git).\n├── example.env           # An example environment file.\n├── pyproject.toml        # Project dependencies and scripts.\n└── README.md             # This file.\n```\n\n## 🤝 Contributing\n\nContributions are welcome! If you have a feature request, bug report, or want to contribute code, please feel free to open an issue or submit a pull request.\n\n1.  Fork the Project\n2.  Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3.  Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4.  Push to the Branch (`git push origin feature/AmazingFeature`)\n5.  Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License. See the `LICENSE.txt` file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxi-p%2Fdentaldesk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxi-p%2Fdentaldesk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxi-p%2Fdentaldesk/lists"}