Host Assist Agent

A production-grade AI agent that generates contextual responses to guest accommodation inquiries. Built with LangGraph for agentic workflows, featuring RAG-based template retrieval, safety guardrails, and comprehensive observability.

Key Features

Category	Features
Agentic Workflow	LangGraph state machine with conditional routing and parallel tool execution
Multi-Tool System	Template retrieval (RAG), property details, and reservation lookups
Safety Guardrails	PII redaction (Presidio) and topic filtering with fast-path optimization (~71% hit rate)
Cost Optimization	Template-first strategy, direct substitution (58% skip LLM), multi-layer caching
Production Monitoring	LangSmith tracing, Prometheus metrics, Grafana dashboards
Data Layer	PostgreSQL with async operations, Redis distributed caching, Qdrant vector DB
Security	API key authentication with multi-tier rate limiting

Tech Stack

Component	Technology
Agent Framework	LangGraph
LLM	Groq (LLaMA 3.1 8B Instant)
Embeddings	OpenAI text-embedding-3-small
Vector DB	Qdrant
Database	PostgreSQL
Cache	Redis
API	FastAPI
Monitoring	LangSmith + Prometheus + Grafana
Deployment	Docker Compose

Performance

Measured across 55 queries:

Metric	Warm Cache	Cold Cache
p50 Latency	0.07s	0.07s
p95 Latency	0.61s	0.83s
p99 Latency	0.66s	1.89s
Fast (<1s)	100%	98%

Project Structure

Host-Assist-Agent/
├── src/
│   ├── agent/              # LangGraph agent (graph, state, nodes, prompts)
│   ├── tools/              # Agent tools (template retrieval, property/reservation lookup)
│   ├── guardrails/         # Safety mechanisms (PII, topic filter with fast-path)
│   ├── api/                # FastAPI application
│   ├── retrieval/          # Vector DB operations
│   ├── monitoring/         # Observability (metrics, logging)
│   ├── data/               # Data layer (cache, repositories)
│   └── config/             # Configuration
├── data/                   # Synthetic dataset (templates, properties, reservations)
├── evaluation/             # LLM-as-Judge evaluation framework
├── tests/                  # Unit, integration, and E2E tests
├── infrastructure/         # Prometheus/Grafana configuration
├── scripts/                # Setup and utility scripts
└── frontend/               # Demo frontend

Documentation

Document	Description
QUICKSTART.md	Prerequisites, setup with/without Docker, debugging
ARCHITECTURE.md	Technical design, system diagrams, API documentation
DEPLOYMENT.md	Production deployment, best practices, troubleshooting
ROADMAP.md	Project milestones and future plans
CHANGELOG.md	Version history and changes
CONTRIBUTING.md	Contribution guidelines
EVALUATION.md	LLM-as-Judge evaluation methodology
tests/README.md	Test suite documentation

Quick Start

# Clone and setup
git clone <repository-url>
cd Host-Assist-Agent

# Install dependencies
uv sync --extra dev
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Configure environment
cp .env.example .env
# Edit .env with your API keys (OPENAI_API_KEY, GROQ_API_KEY)

# Start infrastructure
docker-compose up -d postgres redis qdrant prometheus grafana

# Setup database and data
alembic upgrade head
python scripts/generate_synthetic_data.py
python scripts/migrate_json_to_postgres.py
python scripts/setup_qdrant.py

# Run the application
python src/main.py

See QUICKSTART.md for detailed setup instructions.

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific categories
pytest tests/unit/
pytest tests/integration/
pytest tests/e2e/

Development

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type checking
mypy src/

Access Points

Service	URL
API	http://localhost:8000
Swagger Docs	http://localhost:8000/docs
Prometheus	http://localhost:9090
Grafana	http://localhost:3000 (admin/admin)
Qdrant Dashboard	http://localhost:6333/dashboard

License

MIT License - see LICENSE for details.

Author

Prayag Bhattarai