# urshashi09/hr-policy-rag-assistant architecture

> Architecture diagram of the GitHub repository urshashi09/hr-policy-rag-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urshashi09/hr-policy-rag-assistant
- Repository: https://github.com/urshashi09/hr-policy-rag-assistant

## Overview

This is a security-conscious HR-policy RAG assistant. An employee submits a question in the Streamlit chat; the pipeline screens it, invokes an agent that can retrieve policy context, screens the draft answer, and returns either a safe answer or a refusal. A separate evaluation path runs curated questions through the real assistant and scores correctness and groundedness. The graph preserves the documented ingestion, routing, tracing, and logging capabilities; unsampled implementation details are represented only where the README documents them.

Main entry points: [`hr_assistant/pipeline.py`](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/pipeline.py) (RAG pipeline), [`hr_assistant/evaluation.py`](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/evaluation.py) (Evaluation runner), [`hr_assistant/vector_store.py`](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/vector_store.py) (Qdrant vector store), [`app.py`](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/app.py) (Streamlit chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Chat interface"]
  node_streamlit["Streamlit chat<br/>[app.py]"]
end

subgraph group_runtime["Assistant runtime"]
  node_pipeline["RAG pipeline<br/>[pipeline.py]"]
  node_guardrails["Safety guardrails<br/>[guardrails.py]"]
  node_agent["HR agent<br/>[agent.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_retrieval["Policy retrieval"]
  node_document["Policy loader<br/>[document_loader.py]"]
  node_splitter["Chunk splitter<br/>[doc_splitter.py]"]
  node_embeddings["Jina embeddings<br/>[embeddings.py]"]
  node_vectorstore[("Qdrant vector store<br/>[vector_store.py]")]
  node_search["Policy search tool<br/>[tools.py]"]
end

subgraph group_operations["AI operations"]
  node_gatewayllm["Gateway LLM client<br/>[llm.py]"]
  node_gateway["Portkey routing<br/>[gateway.py]"]
  node_tracing["LangSmith tracing<br/>[tracing.py]"]
  node_logger["Daily logs<br/>[logger.py]"]
end

subgraph group_quality["Evaluation"]
  node_evaluation["Evaluation runner<br/>[evaluation.py]"]
  node_evalentry["Evaluation entry<br/>[evaluate.py]"]
end

node_employee(("Employee"))
node_portkey{{"Portkey service"}}
node_qdrant[("Qdrant Cloud")]
node_jina{{"Jina embedding service"}}
node_langsmith{{"LangSmith service"}}

node_employee -->|"asks question"| node_streamlit
node_streamlit -->|"submits query"| node_pipeline
node_pipeline -->|"screens input"| node_guardrails
node_guardrails -->|"classifies safety"| node_portkey
node_pipeline -->|"invokes agent"| node_agent
node_agent -->|"calls tool"| node_search
node_search -->|"retrieves chunks"| node_vectorstore
node_vectorstore -->|"queries collection"| node_qdrant
node_vectorstore -->|"creates embeddings"| node_embeddings
node_embeddings -->|"embeds text"| node_jina
node_pipeline -->|"loads policy"| node_document
node_pipeline -->|"splits documents"| node_splitter
node_pipeline -->|"builds or loads"| node_vectorstore
node_pipeline -->|"gets model"| node_gatewayllm
node_gatewayllm -->|"requests routed model"| node_gateway
node_gateway -->|"routes model calls"| node_portkey
node_pipeline -->|"screens draft"| node_guardrails
node_pipeline -->|"checks tracing"| node_tracing
node_pipeline -->|"records events"| node_logger
node_pipeline -->|"returns answer"| node_streamlit
node_evalentry -->|"starts evaluation"| node_evaluation
node_evaluation -->|"runs questions"| node_pipeline
node_evaluation -->|"fetches context"| node_vectorstore
node_evaluation -.->|"routes judge"| node_portkey
node_evaluation -->|"evaluates dataset"| node_langsmith
node_tracing -.->|"sends traces"| node_langsmith

click node_streamlit "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/app.py"
click node_pipeline "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/pipeline.py"
click node_guardrails "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/guardrails.py"
click node_agent "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/agent.py"
click node_config "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/config.py"
click node_document "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/document_loader.py"
click node_splitter "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/doc_splitter.py"
click node_embeddings "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/embeddings.py"
click node_vectorstore "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/vector_store.py"
click node_search "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/tools.py"
click node_gatewayllm "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/llm.py"
click node_gateway "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/gateway.py"
click node_tracing "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/tracing.py"
click node_logger "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/logger.py"
click node_evaluation "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/evaluation.py"
click node_evalentry "https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/evaluate.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit toneBlue
class node_pipeline,node_guardrails,node_agent,node_config,node_qdrant toneAmber
class node_document,node_splitter,node_embeddings,node_vectorstore,node_search toneMint
class node_gatewayllm,node_gateway,node_tracing,node_logger toneRose
class node_evaluation,node_evalentry,node_employee,node_portkey,node_jina,node_langsmith toneIndigo
```

## Components

### Chat interface

- [Streamlit chat](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/app.py): `app.py`

### Assistant runtime

- [RAG pipeline](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/pipeline.py): `hr_assistant/pipeline.py`
- [Safety guardrails](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/guardrails.py): `hr_assistant/guardrails.py`
- [HR agent](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/agent.py): `hr_assistant/agent.py`
- [Runtime configuration](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/config.py): `hr_assistant/config.py`

### Policy retrieval

- [Policy loader](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/document_loader.py): `hr_assistant/document_loader.py`
- [Chunk splitter](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/doc_splitter.py): `hr_assistant/doc_splitter.py`
- [Jina embeddings](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/embeddings.py): `hr_assistant/embeddings.py`
- [Qdrant vector store](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/vector_store.py): `hr_assistant/vector_store.py`
- [Policy search tool](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/tools.py): `hr_assistant/tools.py`

### AI operations

- [Gateway LLM client](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/llm.py): `hr_assistant/llm.py`
- [Portkey routing](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/gateway.py): `hr_assistant/gateway.py`
- [LangSmith tracing](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/tracing.py): `hr_assistant/tracing.py`
- [Daily logs](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/logger.py): `hr_assistant/logger.py`

### Evaluation

- [Evaluation runner](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/hr_assistant/evaluation.py): `hr_assistant/evaluation.py`
- [Evaluation entry](https://github.com/urshashi09/hr-policy-rag-assistant/blob/main/evaluate.py): `evaluate.py`

### Other components

- **Employee**
- **Portkey service**
- **Qdrant Cloud**
- **Jina embedding service**
- **LangSmith service**

## Connections

- Employee → Streamlit chat: asks question (evidence: `README.md`)
- Streamlit chat → RAG pipeline: submits query (evidence: `app.py`)
- RAG pipeline → Safety guardrails: screens input (evidence: `hr_assistant/pipeline.py`)
- Safety guardrails → Portkey service: classifies safety (evidence: `hr_assistant/guardrails.py`)
- RAG pipeline → HR agent: invokes agent (evidence: `hr_assistant/pipeline.py`)
- HR agent → Policy search tool: calls tool (evidence: `README.md`)
- Policy search tool → Qdrant vector store: retrieves chunks (evidence: `hr_assistant/tools.py`)
- Qdrant vector store → Qdrant Cloud: queries collection (evidence: `hr_assistant/vector_store.py`)
- Qdrant vector store → Jina embeddings: creates embeddings (evidence: `hr_assistant/vector_store.py`)
- Jina embeddings → Jina embedding service: embeds text (evidence: `README.md`)
- RAG pipeline → Policy loader: loads policy (evidence: `hr_assistant/pipeline.py`)
- RAG pipeline → Chunk splitter: splits documents (evidence: `hr_assistant/pipeline.py`)
- RAG pipeline → Qdrant vector store: builds or loads (evidence: `hr_assistant/pipeline.py`)
- RAG pipeline → Gateway LLM client: gets model (evidence: `hr_assistant/pipeline.py`)
- Gateway LLM client → Portkey routing: requests routed model (evidence: `hr_assistant/llm.py`)
- Portkey routing → Portkey service: routes model calls (evidence: `hr_assistant/gateway.py`)
- RAG pipeline → Safety guardrails: screens draft (evidence: `hr_assistant/pipeline.py`)
- RAG pipeline → LangSmith tracing: checks tracing (evidence: `hr_assistant/pipeline.py`)
- RAG pipeline → Daily logs: records events (evidence: `hr_assistant/pipeline.py`)
- RAG pipeline → Streamlit chat: returns answer (evidence: `app.py`)
- Evaluation entry → Evaluation runner: starts evaluation (evidence: `evaluate.py`)
- Evaluation runner → RAG pipeline: runs questions (evidence: `hr_assistant/evaluation.py`)
- Evaluation runner → Qdrant vector store: fetches context (evidence: `hr_assistant/evaluation.py`)
- Evaluation runner → Portkey service: routes judge (evidence: `README.md`)
- Evaluation runner → LangSmith service: evaluates dataset (evidence: `README.md`)
- LangSmith tracing → LangSmith service: sends traces (evidence: `README.md`)
