HR Assistant — Usage Guide

Everything you need to get started and make the most of the intelligent HR system.

Setup & Installation

Run these commands once before starting the application:

# 1. Install Python dependencies
pip install fastapi uvicorn langchain-community langchain-ollama \
            langchain-text-splitters chromadb pandas mcp pypdf

# 2. Load HR policies (place PDFs in ./data/)
python ingest.py

# 3. Load employee data (place employees.csv in ./data/)
python ingest_employees.py

# 4. Start the FastAPI backend
uvicorn api_server:app --reload --port 8000

# 5. Start the Next.js frontend (new terminal)
cd hr-frontend && npm install && npm run dev

Then open http://localhost:3000 in your browser.

Example Chat Questions

Category	Example Question
Employee Lookup	Show me details for Clayton, Rick
Pay Rate	What is the pay rate of Smith, John?
Department	How many employees are in the IT department?
Performance	Who are the top performers in Engineering?
Org Chart	Who reports to Michael Scott?
Analytics	Give me a workforce summary
HR Policy	What is the remote work policy?
Leave	How many PTO days do employees get?
Marital Status	Is Clayton, Rick married?
Age	What is the age of Clayton, Rick?

Available MCP Tools

Tool	Description
search_employees	Filter employees by name, dept, position, status, or manager
get_employee_details	Full HR profile for a single employee
get_department_analytics	Headcount, avg pay, and performance by department
get_org_chart	Manager → direct-reports hierarchy
get_workforce_summary	Company-wide KPIs (headcount, pay, gender, turnover)
search_hr_policy	Semantic search over HR policy PDFs (RAG)
log_audit_event	Write an immutable audit entry (called automatically)

System Architecture

Browser (Next.js :3000)
    └── /api/* proxy
          └── FastAPI (api_server.py :8000)
                ├── GET /api/employees    → hr.db (SQLite)
                ├── GET /api/analytics    → hr.db (SQLite)
                ├── GET /api/workforce    → hr.db (SQLite)
                ├── GET /api/audit        → audit.db (SQLite)
                └── POST /api/chat
                        └── hr_agent.py  (LLM + ReAct loop)
                                └── MCPClient (stdio)
                                        └── mcp_hr_server.py
                                                ├── hr.db
                                                ├── hr_vectordb/ (ChromaDB)
                                                └── audit.db

Privacy & Security Protocol

All employee data queries are automatically audited in audit.db.
Employee records are strictly read-only — no UPDATE or DELETE tools are exposed to the AI.
All data stays 100% local — nothing leaves your machine or network.
LLM inference is powered entirely by Ollama locally.
For production deployments, integrating an upstream Identity Provider for RBAC is recommended.