🦺 Safety Advisor Copilot

An AI-powered assistant that answers workplace safety questions using OSHA regulations and safety standards through Retrieval-Augmented Generation (RAG).

🎯 Project Overview

Safety Advisor Copilot is a sophisticated RAG-based chatbot that provides accurate, context-aware answers to workplace safety questions. By leveraging OSHA's Code of Federal Regulations (CFR) Part 1910 and modern AI technologies, it serves as an intelligent assistant for safety professionals, HR teams, and anyone interested in workplace safety compliance.

Key Features:

• 🔍 Semantic Search: Retrieves relevant safety regulations using vector embeddings
• 💬 Conversational AI: Natural language interactions powered by Groq's LLaMA 3 model
• 📚 Source Citations: Provides transparency with similarity scores and document sources
• ⚡ Streaming Responses: Real-time answer generation for better user experience
• 🎨 Modern UI: Clean Streamlit interface for easy interaction

🛠️ Tech Stack

Backend & AI

• FastAPI - High-performance REST API framework
• LangChain - Orchestration framework for LLM applications
• Groq LLaMA 3 - Fast inference LLM for response generation
• Ollama - Local embedding model server (Snowflake Arctic Embed)
• PostgreSQL + pgvector - Vector database for semantic search

Frontend & Tools

• Streamlit - Interactive web interface
• Poetry - Modern Python dependency management
• Pydantic - Data validation and settings management

📋 Prerequisites

• Python 3.10 or higher
• PostgreSQL with pgvector extension
• Ollama (for local embeddings)
• Groq API key (get one free here)

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/abdullah-ax/safety-advisor-copilot.git
cd safety-advisor-copilot

2. Install Dependencies

# Install Poetry if you haven't already
curl -sSL https://install.python-poetry.org | python3 -

# Install project dependencies
poetry install

3. Set Up PostgreSQL with pgvector

# Using Docker (recommended)
docker run -d \
  --name pgvector-db \
  -e POSTGRES_USER=langchain \
  -e POSTGRES_PASSWORD=langchain \
  -e POSTGRES_DB=langchain \
  -p 6024:5432 \
  pgvector/pgvector:pg16

4. Install and Run Ollama

# Install Ollama from https://ollama.ai
# Pull the embedding model
ollama pull snowflake-arctic-embed:22m

# Run Ollama server (if not already running)
ollama serve

5. Configure Environment Variables

# Copy the example env file
cp .env.example .env

# Edit .env and add your Groq API key
GROQ_API_KEY=your_api_key_here

6. Index the Safety Documents

# Run the notebook to load and embed the OSHA documents
poetry run jupyter notebook examples/test_utils.ipynb
# Execute all cells to create the vector embeddings

7. Start the Backend Server

poetry run uvicorn src.main:app --reload --port 8000

8. Launch the Streamlit UI

# In a new terminal
poetry run streamlit run src/streamlit_app.py

Visit http://localhost:8501 to interact with the chatbot! 🎉

💡 Usage Examples

Question: What are the requirements for fall protection?

Answer: Based on the OSHA regulations, fall protection is required when employees are working at heights of 4 feet or more in general industry settings. Protection methods include guardrails, safety nets, or personal fall arrest systems...

Sources: Shows relevant CFR sections with similarity scores for transparency.

🏗️ Architecture & Design Decisions

Why RAG over Fine-tuning?

• Accuracy: Grounds responses in authoritative documents, reducing hallucinations
• Updatability: Easy to update knowledge base without retraining models
• Transparency: Provides source citations for fact-checking
• Cost-effective: No expensive model training required

Hybrid Retrieval Strategy

The system uses a two-stage retrieval process:

1. Vector Similarity: Semantic search using embeddings (top-k retrieval)
2. Score Threshold Filtering: Only uses documents above a similarity threshold (0.35)
3. Graceful Fallback: Informs users when no relevant context is found

Token-Aware Chunking

Documents are split using Hugging Face tokenizers to:

• Respect semantic boundaries
• Optimize for embedding model (512 tokens)
• Include overlap (96 tokens) for context continuity

🎓 What I Learned

Building this project deepened my understanding of:

1. RAG Architecture: Implementing end-to-end retrieval-augmented generation with real-world constraints
2. Vector Databases: Working with PostgreSQL pgvector for efficient similarity search
3. Prompt Engineering: Crafting system prompts to constrain LLM responses to relevant domains
4. Streaming APIs: Implementing token-by-token response streaming for better UX
5. Production Considerations: Handling edge cases, error states, and user transparency

📁 Project Structure

safety-advisor-copilot/
├── src/
│   ├── main.py              # FastAPI backend with RAG endpoints
│   ├── streamlit_app.py     # Streamlit frontend UI
│   └── utils.py             # RAG pipeline utilities
├── data/
│   └── CFR_occupational_safety.pdf  # OSHA regulations document
├── examples/
│   └── test_utils.ipynb     # Jupyter notebook for document indexing
├── docs/
│   └── images/              # Screenshots and diagrams
├── .env.example             # Environment variable template
├── .gitignore              # Git ignore rules
├── pyproject.toml          # Poetry dependencies
└── README.md               # This file

🔒 Security Considerations

• API keys stored in environment variables (never committed)
• Admin endpoints protected with token authentication
• Database connection string configurable via environment
• Input validation using Pydantic models

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OSHA for providing comprehensive safety regulations
• Groq for fast LLM inference
• LangChain team for excellent RAG tools
• Ollama for easy local embedding deployment

🚧 Roadmap

• Add support for multiple safety document sources
• Implement conversation history and context
• Add user authentication and session management
• Deploy to cloud platform (AWS/Azure/GCP)
• Mobile-responsive UI improvements

---

Built with ❤️ for workplace safety | Report an Issue | Request a Feature