# HR-ASSIST: Agentic AI for HR Automation

![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white)
![Claude](https://img.shields.io/badge/AI-Claude%20Desktop-orange?style=for-the-badge&logo=anthropic&logoColor=white)
![MCP](https://img.shields.io/badge/Protocol-Model%20Context%20Protocol-green?style=for-the-badge)
![Status](https://img.shields.io/badge/Status-Active-success?style=for-the-badge)

> **An Agentic AI system that automates end-to-end HR workflows, from onboarding to scheduling, using the Model Context Protocol (MCP).**

---

## Overview

**HR-ASSIST** is an intelligent automation system built as part of the **Codebasics Gen AI Bootcamp**. 

It transforms the Claude Desktop App into a powerful HR assistant capable of interacting with local databases, sending real emails, and managing calendars.

Unlike standard chatbots, HR-ASSIST uses **Agentic Workflows** to execute complex, multi-step tasks autonomously.

### The Problem
HR managers spend hours toggling between HRMS software, email clients, and ticketing systems to onboard a single employee.

### The Solution
A unified interface where natural language turns into action.
* **Input:** *"Onboard Ruchitha as a Data Analyst."*
* **Output:** Employee record created + Welcome email sent + IT ticket raised + Orientation meeting scheduled.

---

## See it in Action

| **1. Agentic Scheduling** | **2. Pre-built Prompt Templates** |
| :---: | :---: |
| ![Scheduling Demo](images/demo_schedule.png) | ![Onboarding UI](images/demo_onboard.png) |
| *The Agent intelligently parses dates to schedule meetings.* | *Custom UI forms for structured data entry.* |

---

## Key Features

| Feature                    | Description |
|:---------------------------| :--- |
| **MCP Prompts**            | Pre-configured templates (UI forms) for complex tasks like onboarding. |
| **HRMS Integration**       | Custom Tool execution to search, add, and update employee records. |
| **Email Automation**       | automated SMTP integration to send secure credentials via Gmail. |
| **Ticket Management**      | Auto-generation of support tickets for IT equipment. |
| **Intelligent Calendar** | Natural language date parsing for meeting management. |

---

## Technical Architecture

```mermaid
graph TD
    User[HR Manager] -->|Selects Template| UI[Claude Desktop UI]
    UI -->|MCP Protocol| Server[HR-Assist Python Server]
    Server -->|Write| DB[(Local HR Database)]
    Server -->|Send| SMTP[Gmail API]
    Server -->|Create| Ticket[Ticket System]

```

### Tech Stack

* **Language:** Python 3.10+
* **Protocol:** Model Context Protocol (MCP) by Anthropic
* **Dependency Management:** `uv`
* **Libraries:** `fastmcp`, `pydantic`, `python-dotenv`

---

## Repository Structure

```text

atliq-hr-assist/
├── hrms/                   # Core Business Logic Package
│   ├── __init__.py         # Package initialization
│   ├── employee_manager.py # Employee CRUD operations
│   ├── leave_manager.py    # Leave balance logic
│   ├── meeting_manager.py  # Calendar scheduling
│   ├── ticket_manager.py   # IT support ticketing
│   └── schemas.py          # Pydantic data models
├── images/                 # Documentation screenshots
│   ├── demo_onboard.png
│   └── demo_schedule.png
├── server.py               # Main MCP Server Entry Point
├── emails.py               # SMTP Email Handler
├── utils.py                # Helper functions (Data seeding)
├── .env                    # Email and Passwords (Excluded from repo)
├── .gitignore              # Git ignore rules
├── pyproject.toml          # Project dependencies configuration
└── uv.lock                 # Dependency lock file (ensures reproducibility)
```

---

## Setup & Installation

1. **Clone the Repository**
```bash
git clone [https://github.com/YOUR_USERNAME/hr-assist-mcp-agent.git](https://github.com/YOUR_USERNAME/hr-assist-mcp-agent.git)
cd hr-assist-mcp-agent

```


2. **Install Dependencies**
```bash
uv init
uv add "mcp[cli]" python-dotenv

```


3. **Configure Environment**
Create a `.env` file for your credentials:
```env
CB_EMAIL=your_email@gmail.com
CB_EMAIL_PWD=your_app_password

```


4. **Connect to Claude**
Add the server path to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "hr-assist": {
      "command": "uv",
      "args": ["--directory", "ABSOLUTE_PATH", "run", "server.py"],
      "env": { "CB_EMAIL": "...", "CB_EMAIL_PWD": "..." }
    }
  }
}

```



---

## Usage Guide

### Method 1: Natural Language

Simply type in the chat bar:

> "Schedule a meeting for employee E001 tomorrow at 10 AM regarding Project Kickoff."

### Method 2: MCP Prompt Templates (Recommended)

1. Click the **Attach** button or type `/` in Claude.
2. Select **`onboard_new_employee`**.
3. Fill in the form fields:
* **Employee Name:** `Ruchitha`
* **Manager Name:** `Dhaval`
4. Hit **Run**. The Agent will execute the entire workflow automatically.

---

## Future Improvements

* **Database:** Migrate from in-memory storage to SQLite/PostgreSQL.
* **Frontend:** Build a Streamlit dashboard to view the generated tickets.
* **Auth:** Add Role-Based Access Control (RBAC) for manager approvals.

---

## 📄 License

- Developed as part of the **Codebasics Gen AI Bootcamp**. 
- Copyright © Codebasics Inc.