From 67a8ed458b25dc35fb1b68b159cf2d0c744720ab Mon Sep 17 00:00:00 2001
From: Sohan Maheshwar <1119120+sohanmaheshwar@users.noreply.github.com>
Date: Tue, 6 Oct 2026 15:11:05 +0200
Subject: [PATCH 1/4] agentic-rag: migrate vector store to Elasticsearch and
LLM to Mistral
Replace the Milvus + OpenAI stack with Elasticsearch (dense_vector kNN)
and Mistral (mistral-embed embeddings + mistral-small-latest LLM).
- Add elasticsearch_client singleton; drop milvus_client
- retrieval_node: kNN search over an Elasticsearch dense_vector field
- setup_environment: create the documents index and bulk-index the 50
docs, embedding them in a single batched embed_documents call
- config / docker-compose / run_ui: Elasticsearch + Mistral env & services
- Rewrite README for the Elasticsearch + Mistral stack, consolidate to the
web-UI flow, add Mermaid flow diagrams, and add .env.example
- Update tests for the Elasticsearch / Mistral code paths
---
agentic-rag-authorization/.env.example | 10 +
agentic-rag-authorization/ARCHITECTURE.md | 63 +++---
agentic-rag-authorization/README.md | 192 +++++-------------
.../agentic_rag/__init__.py | 2 +-
.../agentic_rag/config.py | 16 +-
.../agentic_rag/elasticsearch_client.py | 29 +++
.../agentic_rag/graph.py | 2 +-
.../agentic_rag/logging_config.py | 4 +-
.../agentic_rag/milvus_client.py | 26 ---
.../agentic_rag/node_helpers.py | 12 +-
.../agentic_rag/nodes/retrieval_node.py | 48 +++--
agentic-rag-authorization/api/routes.py | 6 +-
agentic-rag-authorization/docker-compose.yml | 74 ++-----
.../examples/basic_example.py | 4 +-
.../examples/setup_environment.py | 120 ++++++-----
agentic-rag-authorization/pyproject.toml | 8 +-
agentic-rag-authorization/requirements.txt | 4 +-
agentic-rag-authorization/run_ui.py | 38 ++--
.../test_improvements.py | 12 +-
agentic-rag-authorization/tests/conftest.py | 8 +-
.../tests/test_config.py | 32 ++-
.../tests/test_elasticsearch_client.py | 43 ++++
.../tests/test_milvus_client.py | 25 ---
.../tests/test_retrieval_node.py | 30 ++-
24 files changed, 370 insertions(+), 438 deletions(-)
create mode 100644 agentic-rag-authorization/.env.example
create mode 100644 agentic-rag-authorization/agentic_rag/elasticsearch_client.py
delete mode 100644 agentic-rag-authorization/agentic_rag/milvus_client.py
create mode 100644 agentic-rag-authorization/tests/test_elasticsearch_client.py
delete mode 100644 agentic-rag-authorization/tests/test_milvus_client.py
diff --git a/agentic-rag-authorization/.env.example b/agentic-rag-authorization/.env.example
new file mode 100644
index 0000000..2101b18
--- /dev/null
+++ b/agentic-rag-authorization/.env.example
@@ -0,0 +1,10 @@
+# Required
+MISTRAL_API_KEY=your-mistral-api-key-here
+
+# Optional (defaults shown)
+ELASTICSEARCH_URL=http://localhost:9200
+ELASTICSEARCH_API_KEY=
+SPICEDB_ENDPOINT=localhost:50051
+SPICEDB_TOKEN=devtoken
+MAX_RETRIEVAL_ATTEMPTS=1
+LOG_LEVEL=INFO
diff --git a/agentic-rag-authorization/ARCHITECTURE.md b/agentic-rag-authorization/ARCHITECTURE.md
index 1b1a20a..58ac9ce 100644
--- a/agentic-rag-authorization/ARCHITECTURE.md
+++ b/agentic-rag-authorization/ARCHITECTURE.md
@@ -35,8 +35,8 @@ Technical details for those implementing similar systems or extending this one.
│ │ │
│ ┌──────────┼──────────┐ │
│ ▼ ▼ ▼ │
-│ Weaviate SpiceDB OpenAI │
-│ (Search) (AuthZ) (LLM) │
+│ Elasticsearch SpiceDB Mistral │
+│ (Search) (AuthZ) (LLM) │
└─────────────────────────────────────────────────────────┘
```
@@ -107,9 +107,9 @@ result = run_agentic_rag(
python3 run_ui.py
```
This launcher performs pre-flight checks:
-- Verifies Weaviate connectivity
+- Verifies Elasticsearch connectivity
- Verifies SpiceDB connectivity
-- Checks OpenAI API key configuration
+- Checks Mistral API key configuration
- Validates documents are loaded
- Auto-opens browser to http://localhost:8000
@@ -224,7 +224,7 @@ async def get_users():
@router.get("/health")
async def health_check():
# Returns service status
- # TODO: Actually check Weaviate/SpiceDB connectivity
+ # TODO: Actually check Elasticsearch/SpiceDB connectivity
```
**3. Pydantic Models (`api/models.py`)**
@@ -308,7 +308,7 @@ FastAPI Router (routes.py)
run_agentic_rag_async()
│
▼ Execute LangGraph
- │ 1. Retrieval Node → Weaviate BM25 search
+ │ 1. Retrieval Node → Elasticsearch semantic vector search
│ 2. Authorization Node → SpiceDB permission checks
│ 3. Generation Node → LLM answer generation
│
@@ -461,7 +461,7 @@ The API layer is designed for **demonstration and education**, not production us
4. **No Rate Limiting**
- No protection against abuse or DoS
- - OpenAI API costs could accumulate
+ - Mistral API costs could accumulate
**Why This Is Acceptable for Demo:**
- System demonstrates authorization concepts (SpiceDB)
@@ -581,7 +581,7 @@ async def run_agentic_rag_async(query: str, subject_id: str, max_attempts: int)
1. **Concurrency**
- Server can handle multiple queries simultaneously
- - Other requests aren't blocked while one query waits for OpenAI
+ - Other requests aren't blocked while one query waits for Mistral
2. **Resource Efficiency**
- Async I/O doesn't waste threads on waiting
@@ -628,9 +628,10 @@ async def run_agentic_rag_async(query, subject_id, max_attempts):
**Node Compatibility:**
-All nodes work with both sync and async execution:
-- LangChain components support async (Weaviate client, OpenAI)
-- SpiceDB gRPC client is synchronous but fast (~40-50ms)
+All nodes run under both the sync and async entry points:
+- The retrieval and generation nodes are synchronous — the `elasticsearch` client
+ and the Mistral embedding/LLM calls (`chain.invoke`) are blocking
+- The SpiceDB permission check (authorization node) runs on async gRPC and is fast (~40-50ms)
- No code duplication required
### LangGraph State Machine
@@ -639,7 +640,7 @@ All nodes work with both sync and async execution:
```
START
↓
-Retrieval Node (Weaviate BM25)
+Retrieval Node (Elasticsearch semantic vector search)
↓
Authorization Node (SpiceDB) ◄── Security Boundary (deterministic)
↓
@@ -677,12 +678,12 @@ AgenticRAGState = TypedDict("AgenticRAGState", {
### Retrieval Node (Deterministic)
-**Purpose**: Execute semantic/keyword search in Weaviate.
+**Purpose**: Execute semantic vector search in Elasticsearch.
**Input**: `query` from state
**Operation**:
-- Weaviate BM25 keyword search (default)
+- Elasticsearch semantic vector search: kNN over `dense_vector` field using cosine similarity (default)
- Returns top-k documents (typically 5)
- No authorization filtering at this stage
- Direct execution without planning overhead
@@ -763,7 +764,7 @@ definition document {
1. User makes query
subject_id: "alice"
-2. Weaviate retrieves documents
+2. Elasticsearch retrieves documents
[eng-001, eng-002, hr-001]
3. For each document, SpiceDB checks:
@@ -835,7 +836,7 @@ hr-001 (document) ──viewer──> hr_manager (user)
▼
┌───────────────────────────────────┐
│ Trusted Zone │
-│ SpiceDB + Weaviate │
+│ SpiceDB + Elasticsearch │
│ Authorized data │
└───────────────────────────────────┘
```
@@ -866,7 +867,7 @@ hr-001 (document) ──viewer──> hr_manager (user)
▼
┌───────────────────────────┐
│ Trusted Zone │
-│ SpiceDB + Weaviate │
+│ SpiceDB + Elasticsearch │
│ Authorized data │
└───────────────────────────┘
```
@@ -1002,7 +1003,7 @@ def authorize(state):
```
Query
↓
-Retrieve (BM25 search)
+Retrieve (semantic vector search)
↓
Authorize (filter)
↓
@@ -1100,7 +1101,7 @@ from fastapi import APIRouter
@router.get("/documents")
async def list_documents():
"""List all documents with metadata."""
- # Query Weaviate for all documents
+ # Query Elasticsearch for all documents
# Return structured list
return {"documents": [...]}
@@ -1212,18 +1213,18 @@ def format_document_detailed(doc: Document) -> dict:
## Project Structure
```
-agentic-rag-weaviate/
+agentic-rag-elasticsearch/
├── agentic_rag/ # Core RAG engine
│ ├── graph.py # LangGraph state machine (sync + async entry points)
│ ├── state.py # AgenticRAGState TypedDict definition
│ ├── config.py # Configuration management (env vars)
│ ├── nodes/
-│ │ ├── retrieval_node.py # Weaviate BM25 search
+│ │ ├── retrieval_node.py # Elasticsearch semantic vector search
│ │ ├── authorization_node.py # SpiceDB filtering (security boundary)
│ │ ├── reasoning_node.py # Optional: adaptive retry logic
│ │ └── generation_node.py # Final answer with context
│ ├── authorization_helpers.py # Batch permission checking
-│ ├── weaviate_client.py # Connection pooling for Weaviate
+│ ├── elasticsearch_client.py # Connection pooling for Elasticsearch
│ ├── grpc_helpers.py # Connection pooling for SpiceDB
│ ├── logging_config.py # Structured JSON logging
│ ├── node_helpers.py # Shared utilities for nodes
@@ -1256,7 +1257,7 @@ agentic-rag-weaviate/
│ └── PERMISSIONS.md # Permission matrix and patterns
│
├── run_ui.py # Web UI launcher with pre-flight checks
-├── docker-compose.yml # Weaviate + SpiceDB services
+├── docker-compose.yml # Elasticsearch + SpiceDB services
├── requirements.txt # Python dependencies (includes fastapi, uvicorn)
├── .env.example # Environment variable template
├── README.md # Overview, quick start, usage guide
@@ -1279,7 +1280,7 @@ agentic-rag-weaviate/
**Shared Core:**
- State machine: `agentic_rag/graph.py`
- Nodes: `agentic_rag/nodes/*.py`
-- Services: `agentic_rag/weaviate_client.py`, `agentic_rag/grpc_helpers.py`
+- Services: `agentic_rag/elasticsearch_client.py`, `agentic_rag/grpc_helpers.py`
## Performance Characteristics
@@ -1322,11 +1323,11 @@ Async execution allows concurrent query handling:
- **Single query**: ~3.5-4.5s
- **5 concurrent queries**: ~4-5s each (minimal overhead)
-- **10 concurrent queries**: ~5-6s each (slight queueing at OpenAI)
+- **10 concurrent queries**: ~5-6s each (slight queueing at Mistral)
**Bottlenecks:**
-1. OpenAI API calls (~2-3s) - most significant
-2. Weaviate search (~0.5-1s)
+1. Mistral API calls (~2-3s) - most significant
+2. Elasticsearch search (~0.5-1s)
3. SpiceDB checks (~40-50ms for 3-5 documents)
4. API/network overhead (~30-50ms total)
@@ -1379,7 +1380,7 @@ Every node updates the state with:
```
[AIMessage] Planning: Searching for engineering documents...
-[SystemMessage] Retrieved 3 documents from Weaviate
+[SystemMessage] Retrieved 3 documents from Elasticsearch
[SystemMessage] Authorization: 2/3 documents authorized (1 denied)
[AIMessage] Reasoning: User has partial access, generating answer from available docs
[AIMessage] Answer: Based on the 2 authorized documents...
@@ -1525,7 +1526,7 @@ For production deployment, consider tracking:
- API response time (p50, p95, p99)
- LangGraph execution time
- Individual node execution times
- - OpenAI API latency
+ - Mistral API latency
2. **Authorization Metrics:**
- Authorization pass rate (per user)
@@ -1542,8 +1543,8 @@ For production deployment, consider tracking:
4. **Error Metrics:**
- API error rate
- Validation failures
- - OpenAI API errors
- - Service connectivity failures (Weaviate, SpiceDB)
+ - Mistral API errors
+ - Service connectivity failures (Elasticsearch, SpiceDB)
## Summary
diff --git a/agentic-rag-authorization/README.md b/agentic-rag-authorization/README.md
index e88d5f5..873d2fc 100644
--- a/agentic-rag-authorization/README.md
+++ b/agentic-rag-authorization/README.md
@@ -1,8 +1,6 @@
# Agentic RAG with Fine-Grained Authorization
-> **Also available:** [Weaviate version](https://github.com/authzed/examples/tree/weaviate/agentic-rag-authorization) (BM25 keyword search) · [Mistral version](https://github.com/authzed/examples/tree/mistral/agentic-rag-authorization) (Mistral embeddings and LLM)
-
-This repository demonstrates how to combine agentic behavior with deterministic fine-grained authorization using LangGraph, SpiceDB, and [Milvus](https://github.com/milvus-io/milvus). You'll learn to build RAG systems where a user can only see information from the documents they have access to.
+This repository demonstrates how to combine agentic behavior with deterministic fine-grained authorization using LangGraph, SpiceDB, [Elasticsearch](https://github.com/elastic/elasticsearch), and [Mistral](https://mistral.ai/). You'll learn to build RAG systems where a user can only see information from the documents they have access to.
This project uses the [LangChain SpiceDB](https://pypi.org/project/langchain-spicedb/) library.
@@ -34,7 +32,7 @@ This repo demonstrates:
3. **Production features** - Structured logging, connection pooling, batch operations, error handling
4. **Real-world complexity** - 50 documents, 4 permission patterns with hierarchies
-Note: Despite the "agentic RAG" name, the default mode is intentionally simple and deterministic (3 nodes: retrieve → authorize → generate). This provides fast, predictable behavior suitable for most use cases. There is a `MAX_RETRIES` option where the AI Agent can reason if it has to retrieve more data.
+Note: Despite the "agentic RAG" name, the default mode is intentionally simple and deterministic (3 nodes: retrieve → authorize → generate). This provides fast, predictable behavior suitable for most use cases. There is a `MAX_RETRIEVAL_ATTEMPTS` option where the AI Agent can reason if it has to retrieve more data.
## The Problem This Solves
@@ -48,7 +46,7 @@ Read the [OWASP Top 10 for LLM](https://owasp.org/www-project-top-10-for-large-l
## The Solution
This implementation shows how to combine:
-- **Retrieval-first approach**: Semantic vector search without upfront planning overhead
+- **Retrieval-first approach**: Semantic vector search (Mistral embeddings in Elasticsearch) without upfront planning overhead
- **Deterministic security**: SpiceDB authorization that cannot be bypassed
- **Transparency**: Users understand what they can and can't access, and why
@@ -94,93 +92,69 @@ this question. This information is restricted to the engineering department."
The agent transparently explains access limitations instead of failing silently.
-## Setup (5 minutes)
+## Setup & Run (5 minutes)
+
+The demo runs entirely through the web UI, which lets you switch users and watch the authorization boundary filter results in real time.
### Prerequisites
- Docker & Docker Compose
- Python 3.11+
-- OpenAI API key
+- Mistral API key
### Steps
```bash
-# 1. Configure
+# 1. Configure — add your Mistral API key to the new .env file
cp .env.example .env
-# Edit .env with your actual OpenAI API key
-# 2. Start services
+# 2. Start Elasticsearch + SpiceDB
docker-compose up -d
-# 3. Install dependencies
+# 3. Install dependencies (includes FastAPI + Uvicorn for the UI)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
-```
-
-## Web UI
-
-A web interface is available to demonstrate the authorization capabilities interactively.
-### Quick Start
-
-```bash
-# 1. Ensure services are running and data is initialized
-docker-compose up -d
+# 4. Initialize data — embed 50 documents into Elasticsearch
+# and write the permission model to SpiceDB
python3 examples/setup_environment.py
-# 2. Install web dependencies
-pip install -r requirements.txt # Includes fastapi and uvicorn
-
-# 3. Launch UI (includes pre-flight checks)
+# 5. Launch the web UI (runs pre-flight checks, then opens your browser)
python3 run_ui.py
```
-The `setup_environment.py` script sets up Milvus as the vector database and SpiceDB with sample documents and department-based access control. It embeds all 50 documents using OpenAI's `text-embedding-3-small` and inserts them into Milvus, then writes a hierarchical permission model to SpiceDB: users assigned to departments, department-wide document access, 3 cross-department collaboration grants, and 3 individual user exceptions.
+`setup_environment.py` sets up Elasticsearch as the vector database and SpiceDB with sample documents and department-based access control. It embeds all 50 documents using Mistral's `mistral-embed` and indexes them into Elasticsearch, then writes a hierarchical permission model to SpiceDB: users assigned to departments, department-wide document access, 3 cross-department collaboration grants, and 3 individual user exceptions.
-The UI launcher will:
-- Verify documents are loaded in Milvus
-- Start the FastAPI server
-- Open your browser to http://localhost:8000
+`run_ui.py` verifies Elasticsearch and SpiceDB connectivity, confirms the documents are loaded, starts the FastAPI server, and opens http://localhost:8000.
-Here are a few sample prompts to try:
+### Try it out
-Choose "Bob" from "Sales" as the user and run the query "What are the company handbook guidelines?"
+Choose **Bob** from **Sales** and run the query *"What are the company handbook guidelines?"*
-You should see:
```
📊 Retrieved: 5
✅ Authorized: 3
❌ Denied: 2
```
-Now run the same query as "HR Manager":
+Now run the same query as **HR Manager**:
+
```
📊 Retrieved: 5
✅ Authorized: 5
❌ Denied: 0
```
-### Manual Start
+Same query, same retrieved documents — SpiceDB decides what each user is allowed to see.
-```bash
-# Terminal 1: Start services (if not running)
-docker-compose up -d
-
-# Terminal 2: Start API server
-uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
-
-# Browser
-open http://localhost:8000
-```
+### Manual start (optional)
-## Run Without UI
+Prefer to start the server yourself (for example, with live reload during development)?
```bash
-# Initialize data
-python3 examples/setup_environment.py
-
-# Run demo
-python3 examples/basic_example.py
+docker-compose up -d # if not already running
+uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
+open http://localhost:8000
```
## How It Works
@@ -211,50 +185,44 @@ definition document {
### 2. State Flow
**Default Mode (`max_attempts=1`)**
-```
-User Query
- ↓
-Retrieval Node ← Milvus semantic vector search (text-embedding-3-small)
- ↓
-Authorization Node ← SpiceDB filters (SECURITY BOUNDARY - cannot be bypassed)
- ↓
-Generation Node ← Answer with authorized context + explanations
+
+```mermaid
+flowchart TD
+ Q([User Query]) --> R[Retrieval Node
Elasticsearch semantic search · mistral-embed]
+ R --> A[Authorization Node
SpiceDB permission filter]
+ A --> G([Generation Node
Answer from authorized context])
+ class A boundary
+ classDef boundary fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#1f2937;
```
+The **Authorization Node** (highlighted) is the security boundary: it always runs, it's deterministic, and the agent cannot bypass it.
+
**Adaptive Mode (`max_attempts > 1`)**
When `max_attempts` is set above 1, a reasoning node activates if authorization fails. The LLM analyzes why access was denied and decides whether a different retrieval strategy might find documents the user *can* access:
-```
-User Query
- ↓
-Retrieval Node
- ↓
-Authorization Node ← still deterministic, still non-bypassable
- ↓
- some docs authorized? → Yes → Generation Node
- ↓ No
-Reasoning Node ← LLM decides: retry with different query, or give up?
- ↓
- attempts left? → Yes → Retrieval Node (loop)
- ↓ No
-Generation Node ← explains the denial
+```mermaid
+flowchart TD
+ Q([User Query]) --> R[Retrieval Node]
+ R --> A[Authorization Node
deterministic · non-bypassable]
+ A --> D{Some docs
authorized?}
+ D -->|Yes| G([Generation Node])
+ D -->|No| RE[Reasoning Node
LLM: retry with a different query, or give up?]
+ RE --> AL{Attempts
left?}
+ AL -->|Yes| R
+ AL -->|No| G2([Generation Node
explains the denial])
+ class A boundary
+ classDef boundary fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#1f2937;
```
For example, if Bob (sales) asks about "microservices architecture" and the first retrieval returns only engineering-restricted docs, the reasoning node might try a broader query that surfaces a shared architecture doc Bob can actually access.
-Enable it by setting `MAX_RETRIEVAL_ATTEMPTS` in `.env` (or passing `max_attempts` directly):
+Enable it by setting `MAX_RETRIEVAL_ATTEMPTS` in `.env`:
```bash
MAX_RETRIEVAL_ATTEMPTS=3 # default is 1
```
-Or in code:
-
-```python
-result = run_agentic_rag(query="...", subject_id="bob", max_attempts=3)
-```
-
### 3. Security Guarantees
- **Authorization always runs**: Hardcoded in the LangGraph workflow — the agent cannot skip it
@@ -262,51 +230,21 @@ result = run_agentic_rag(query="...", subject_id="bob", max_attempts=3)
- **Fail closed**: Access denied unless explicitly granted
- **Observable**: Full audit trail in state
-## Project Structure
-
-```
-agentic-rag-authorization/
-├── agentic_rag/
-│ ├── graph.py # LangGraph state machine
-│ ├── state.py # State schema
-│ ├── config.py # Configuration management
-│ ├── nodes/
-│ │ ├── retrieval_node.py # Milvus semantic vector search
-│ │ ├── authorization_node.py # SpiceDB filtering (security boundary)
-│ │ ├── reasoning_node.py # Optional: adaptive retry logic
-│ │ └── generation_node.py # Final answer with context
-│ ├── milvus_client.py # Connection pooling for Milvus
-│ ├── grpc_helpers.py # Connection pooling for SpiceDB
-│ ├── logging_config.py # Structured JSON logging
-│ └── validation.py # Input validation and sanitization
-├── examples/
-│ ├── setup_environment.py # Initialize data (embeds and loads 50 documents)
-│ └── basic_example.py # 8 demo scenarios
-├── scripts/
-│ ├── generate_documents.py # Generate 50 .txt files
-│ ├── parse_documents.py # Parse documents into objects
-│ └── verify_permissions.py # Test authorization patterns
-├── data/
-│ ├── documents/ # 50 .txt files (5 departments)
-│ ├── schema.zed # SpiceDB permission schema
-│ └── PERMISSIONS.md # Permission matrix
-└── docker-compose.yml # Milvus + SpiceDB
-```
-
## Configuration
Environment variables (`.env`):
```bash
# Required
-OPENAI_API_KEY=sk-...
+MISTRAL_API_KEY=...
# Optional (defaults shown)
-MILVUS_URI=http://localhost:19530
-MILVUS_TOKEN=
+ELASTICSEARCH_URL=http://localhost:9200
+ELASTICSEARCH_API_KEY=
SPICEDB_ENDPOINT=localhost:50051
SPICEDB_TOKEN=devtoken
MAX_RETRIEVAL_ATTEMPTS=1
+LOG_LEVEL=INFO
```
## Dataset Overview
@@ -321,33 +259,11 @@ The repository includes a realistic 50-document dataset across 5 departments.
See [data/PERMISSIONS.md](data/PERMISSIONS.md) for the complete permission matrix.
-## Sample Scenarios
-
-The `examples/basic_example.py` demonstrates 8 scenarios:
-
-1. **Department Access** - alice queries engineering documents
-2. **Access Denial** - bob attempts to access engineering documents
-3. **Cross-Department** - bob accesses shared architecture document
-4. **Individual Exception** - alice accesses sales proposal (special grant)
-5. **Public Access** - Anyone can access company handbooks
-6. **Finance Department** - finance_manager queries financial reports
-7. **HR Department** - hr_manager queries HR policies
-8. **Transparent Explanations** - Agent explains why access was denied
-
-## Testing
-
-```bash
-# Run all tests
-pytest tests/
-
-# Run specific test
-pytest tests/test_basic_flow.py::test_authorized_access
-```
-
## Learn More
- **SpiceDB**: https://authzed.com/docs
-- **Milvus**: https://milvus.io/docs
+- **Elasticsearch**: https://www.elastic.co/docs
+- **Mistral**: https://docs.mistral.ai/
- **LangGraph**: https://langchain-ai.github.io/langgraph/
- **langchain-spicedb**: https://github.com/authzed/langchain-spicedb
diff --git a/agentic-rag-authorization/agentic_rag/__init__.py b/agentic-rag-authorization/agentic_rag/__init__.py
index f12f9b8..6264a64 100644
--- a/agentic-rag-authorization/agentic_rag/__init__.py
+++ b/agentic-rag-authorization/agentic_rag/__init__.py
@@ -1,4 +1,4 @@
-"""Agentic RAG with fine-grained authorization using Milvus and SpiceDB."""
+"""Agentic RAG with fine-grained authorization using Elasticsearch and SpiceDB."""
__version__ = "0.1.0"
diff --git a/agentic-rag-authorization/agentic_rag/config.py b/agentic-rag-authorization/agentic_rag/config.py
index 749c2f7..e2d0950 100644
--- a/agentic-rag-authorization/agentic_rag/config.py
+++ b/agentic-rag-authorization/agentic_rag/config.py
@@ -12,16 +12,16 @@
class Config:
"""Configuration for agentic RAG system."""
- # Milvus
- milvus_uri: str
- milvus_token: str
+ # Elasticsearch
+ elasticsearch_url: str
+ elasticsearch_api_key: str
# SpiceDB
spicedb_endpoint: str
spicedb_token: str
- # OpenAI
- openai_api_key: str
+ # Mistral
+ mistral_api_key: str
# Agent behavior
max_retrieval_attempts: int = 1
@@ -33,11 +33,11 @@ class Config:
def from_env(cls):
"""Load configuration from environment variables."""
return cls(
- milvus_uri=os.getenv("MILVUS_URI", "http://localhost:19530"),
- milvus_token=os.getenv("MILVUS_TOKEN", ""),
+ elasticsearch_url=os.getenv("ELASTICSEARCH_URL", "http://localhost:9200"),
+ elasticsearch_api_key=os.getenv("ELASTICSEARCH_API_KEY", ""),
spicedb_endpoint=os.getenv("SPICEDB_ENDPOINT", "localhost:50051"),
spicedb_token=os.getenv("SPICEDB_TOKEN", "devtoken"),
- openai_api_key=os.getenv("OPENAI_API_KEY", ""),
+ mistral_api_key=os.getenv("MISTRAL_API_KEY", ""),
max_retrieval_attempts=int(os.getenv("MAX_RETRIEVAL_ATTEMPTS", "1")),
log_level=os.getenv("LOG_LEVEL", "INFO"),
)
diff --git a/agentic-rag-authorization/agentic_rag/elasticsearch_client.py b/agentic-rag-authorization/agentic_rag/elasticsearch_client.py
new file mode 100644
index 0000000..152892b
--- /dev/null
+++ b/agentic-rag-authorization/agentic_rag/elasticsearch_client.py
@@ -0,0 +1,29 @@
+"""Elasticsearch client connection pooling."""
+
+from elasticsearch import Elasticsearch
+from threading import Lock
+from typing import Optional
+
+_es_client: Optional[Elasticsearch] = None
+_es_lock = Lock()
+
+
+def get_elasticsearch_client(url: str, api_key: str = "") -> Elasticsearch:
+ """Get or create reusable Elasticsearch client (singleton, thread-safe)."""
+ global _es_client
+ if _es_client is not None:
+ return _es_client
+ with _es_lock:
+ if _es_client is None:
+ if api_key:
+ _es_client = Elasticsearch(url, api_key=api_key)
+ else:
+ _es_client = Elasticsearch(url)
+ return _es_client
+
+
+def reset_elasticsearch_client():
+ """Reset singleton (useful for testing)."""
+ global _es_client
+ with _es_lock:
+ _es_client = None
diff --git a/agentic-rag-authorization/agentic_rag/graph.py b/agentic-rag-authorization/agentic_rag/graph.py
index 01f0ed1..51b71c5 100644
--- a/agentic-rag-authorization/agentic_rag/graph.py
+++ b/agentic-rag-authorization/agentic_rag/graph.py
@@ -55,7 +55,7 @@ def build_agentic_rag_graph():
"""Build the agentic RAG graph with deterministic authorization.
Simplified Flow:
- 1. Retrieval: Fetch documents from Milvus
+ 1. Retrieval: Fetch documents from Elasticsearch
2. Authorization: Deterministic permission check (security boundary)
3. Conditional:
- If authorized docs exist: Generate answer
diff --git a/agentic-rag-authorization/agentic_rag/logging_config.py b/agentic-rag-authorization/agentic_rag/logging_config.py
index c901a3a..d2dff77 100644
--- a/agentic-rag-authorization/agentic_rag/logging_config.py
+++ b/agentic-rag-authorization/agentic_rag/logging_config.py
@@ -103,8 +103,8 @@ def setup_logging(level: str = "INFO") -> None:
# Reduce noise from third-party libraries
logging.getLogger("httpx").setLevel(logging.WARNING)
logging.getLogger("httpcore").setLevel(logging.WARNING)
- logging.getLogger("openai").setLevel(logging.WARNING)
- logging.getLogger("pymilvus").setLevel(logging.WARNING)
+ logging.getLogger("langchain_mistralai").setLevel(logging.WARNING)
+ logging.getLogger("elasticsearch").setLevel(logging.WARNING)
logging.getLogger("grpc").setLevel(logging.WARNING)
diff --git a/agentic-rag-authorization/agentic_rag/milvus_client.py b/agentic-rag-authorization/agentic_rag/milvus_client.py
deleted file mode 100644
index 44f14f6..0000000
--- a/agentic-rag-authorization/agentic_rag/milvus_client.py
+++ /dev/null
@@ -1,26 +0,0 @@
-"""Milvus client connection pooling."""
-
-from pymilvus import MilvusClient
-from threading import Lock
-from typing import Optional
-
-_milvus_client: Optional[MilvusClient] = None
-_milvus_lock = Lock()
-
-
-def get_milvus_client(uri: str, token: str = "") -> MilvusClient:
- """Get or create reusable MilvusClient (singleton, thread-safe)."""
- global _milvus_client
- if _milvus_client is not None:
- return _milvus_client
- with _milvus_lock:
- if _milvus_client is None:
- _milvus_client = MilvusClient(uri=uri, token=token)
- return _milvus_client
-
-
-def reset_milvus_client():
- """Reset singleton (useful for testing)."""
- global _milvus_client
- with _milvus_lock:
- _milvus_client = None
diff --git a/agentic-rag-authorization/agentic_rag/node_helpers.py b/agentic-rag-authorization/agentic_rag/node_helpers.py
index 3e8b33f..27facf6 100644
--- a/agentic-rag-authorization/agentic_rag/node_helpers.py
+++ b/agentic-rag-authorization/agentic_rag/node_helpers.py
@@ -3,22 +3,22 @@
import time
from contextlib import contextmanager
from typing import Dict, Any
-from langchain_openai import ChatOpenAI
+from langchain_mistralai import ChatMistralAI
from .config import get_config
-def get_llm() -> ChatOpenAI:
+def get_llm() -> ChatMistralAI:
"""Get configured LLM instance.
Returns:
- ChatOpenAI: Configured LLM with gpt-4 and temperature=0
+ ChatMistralAI: Configured LLM with mistral-small-latest and temperature=0
"""
config = get_config()
- return ChatOpenAI(
- model="gpt-4",
+ return ChatMistralAI(
+ model="mistral-small-latest",
temperature=0,
- api_key=config.openai_api_key
+ api_key=config.mistral_api_key
)
diff --git a/agentic-rag-authorization/agentic_rag/nodes/retrieval_node.py b/agentic-rag-authorization/agentic_rag/nodes/retrieval_node.py
index 83e3ba4..e92fcce 100644
--- a/agentic-rag-authorization/agentic_rag/nodes/retrieval_node.py
+++ b/agentic-rag-authorization/agentic_rag/nodes/retrieval_node.py
@@ -1,26 +1,25 @@
-"""Retrieval node - retrieve documents from Milvus using semantic vector search."""
+"""Retrieval node - retrieve documents from Elasticsearch using semantic vector search."""
-import openai
+from langchain_mistralai import MistralAIEmbeddings
from langchain_core.messages import SystemMessage
from langchain_core.documents import Document
from ..state import AgenticRAGState
from ..config import get_config
from ..logging_config import get_logger
-from ..milvus_client import get_milvus_client
+from ..elasticsearch_client import get_elasticsearch_client
from ..node_helpers import log_node_execution
logger = get_logger("nodes.retrieval")
def _embed(text: str, api_key: str) -> list[float]:
- client = openai.OpenAI(api_key=api_key)
- response = client.embeddings.create(model="text-embedding-3-small", input=text)
- return response.data[0].embedding
+ embeddings = MistralAIEmbeddings(model="mistral-embed", api_key=api_key)
+ return embeddings.embed_query(text)
def retrieval_node(state: AgenticRAGState) -> dict:
- """Retrieve documents from Milvus based on semantic similarity to the query."""
+ """Retrieve documents from Elasticsearch based on semantic similarity to the query."""
config = get_config()
with log_node_execution(
@@ -29,28 +28,33 @@ def retrieval_node(state: AgenticRAGState) -> dict:
{"query": state["query"], "subject_id": state["subject_id"]},
):
try:
- milvus_client = get_milvus_client(config.milvus_uri, config.milvus_token)
- query_embedding = _embed(state["query"], config.openai_api_key)
+ es_client = get_elasticsearch_client(
+ config.elasticsearch_url, config.elasticsearch_api_key
+ )
+ query_embedding = _embed(state["query"], config.mistral_api_key)
- results = milvus_client.search(
- collection_name="Documents",
- data=[query_embedding],
- anns_field="embedding",
- limit=5,
- output_fields=["doc_id", "title", "content", "department", "classification"],
+ response = es_client.search(
+ index="documents",
+ knn={
+ "field": "embedding",
+ "query_vector": query_embedding,
+ "k": 5,
+ "num_candidates": 50,
+ },
+ source=["doc_id", "title", "content", "department", "classification"],
)
documents = [
Document(
- page_content=hit["entity"]["content"],
+ page_content=hit["_source"]["content"],
metadata={
- "doc_id": hit["entity"]["doc_id"],
- "title": hit["entity"]["title"],
- "department": hit["entity"]["department"],
- "classification": hit["entity"]["classification"],
+ "doc_id": hit["_source"]["doc_id"],
+ "title": hit["_source"]["title"],
+ "department": hit["_source"]["department"],
+ "classification": hit["_source"]["classification"],
},
)
- for hit in results[0]
+ for hit in response["hits"]["hits"]
]
logger.info(
@@ -65,7 +69,7 @@ def retrieval_node(state: AgenticRAGState) -> dict:
"retrieved_documents": documents,
"retrieval_attempt": state["retrieval_attempt"] + 1,
"messages": [
- SystemMessage(content=f"Retrieved {len(documents)} documents from Milvus")
+ SystemMessage(content=f"Retrieved {len(documents)} documents from Elasticsearch")
],
}
diff --git a/agentic-rag-authorization/api/routes.py b/agentic-rag-authorization/api/routes.py
index e18ab32..125399f 100644
--- a/agentic-rag-authorization/api/routes.py
+++ b/agentic-rag-authorization/api/routes.py
@@ -37,14 +37,14 @@ async def get_users():
@router.get("/health")
async def health_check():
"""Check health of backend services."""
- # TODO: Actually check Milvus + SpiceDB connectivity
+ # TODO: Actually check Elasticsearch + SpiceDB connectivity
# For now, return optimistic health status
return {
"status": "healthy",
"services": {
- "milvus": "connected",
+ "elasticsearch": "connected",
"spicedb": "connected",
- "openai": "configured",
+ "mistral": "configured",
},
}
diff --git a/agentic-rag-authorization/docker-compose.yml b/agentic-rag-authorization/docker-compose.yml
index a23002f..f175890 100644
--- a/agentic-rag-authorization/docker-compose.yml
+++ b/agentic-rag-authorization/docker-compose.yml
@@ -1,61 +1,25 @@
---
-version: "3.8"
-
services:
- etcd:
- container_name: "milvus-etcd"
- image: "quay.io/coreos/etcd:v3.5.5"
- environment:
- - "ETCD_AUTO_COMPACTION_MODE=revision"
- - "ETCD_AUTO_COMPACTION_RETENTION=1000"
- - "ETCD_QUOTA_BACKEND_BYTES=4294967296"
- - "ETCD_SNAPSHOT_COUNT=50000"
- volumes:
- - "etcd_data:/etcd"
- command: "etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd"
- healthcheck:
- test: ["CMD", "etcdctl", "endpoint", "health"]
- interval: "30s"
- timeout: "20s"
- retries: 3
-
- minio:
- container_name: "milvus-minio"
- image: "minio/minio:RELEASE.2023-03-13T19-46-17Z"
+ elasticsearch:
+ container_name: "elasticsearch"
+ image: "docker.elastic.co/elasticsearch/elasticsearch:8.13.4"
environment:
- MINIO_ACCESS_KEY: "minioadmin"
- MINIO_SECRET_KEY: "minioadmin"
- volumes:
- - "minio_data:/minio_data"
- command: "minio server /minio_data --console-address :9001"
- healthcheck:
- test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
- interval: "30s"
- timeout: "20s"
- retries: 3
-
- standalone:
- container_name: "milvus-standalone"
- image: "milvusdb/milvus:v2.4.6"
- command: ["milvus", "run", "standalone"]
- environment:
- ETCD_ENDPOINTS: "etcd:2379"
- MINIO_ADDRESS: "minio:9000"
- volumes:
- - "milvus_data:/var/lib/milvus"
+ - "discovery.type=single-node"
+ - "xpack.security.enabled=false"
+ - "xpack.security.http.ssl.enabled=false"
+ - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
ports:
- - "19530:19530"
- - "9091:9091"
- depends_on:
- etcd:
- condition: "service_healthy"
- minio:
- condition: "service_healthy"
+ - "9200:9200"
+ volumes:
+ - "elasticsearch_data:/usr/share/elasticsearch/data"
healthcheck:
- test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
- interval: "30s"
- timeout: "20s"
- retries: 3
+ test:
+ - "CMD-SHELL"
+ - "curl -s -f 'http://localhost:9200/_cluster/health?wait_for_status=yellow&timeout=1s' || exit 1"
+ interval: "15s"
+ timeout: "10s"
+ retries: 10
+ start_period: "40s"
spicedb:
image: "authzed/spicedb:latest"
@@ -66,6 +30,4 @@ services:
SPICEDB_DATASTORE_ENGINE: "memory"
volumes:
- etcd_data:
- minio_data:
- milvus_data:
+ elasticsearch_data:
diff --git a/agentic-rag-authorization/examples/basic_example.py b/agentic-rag-authorization/examples/basic_example.py
index 7bca4eb..ca0cdc6 100644
--- a/agentic-rag-authorization/examples/basic_example.py
+++ b/agentic-rag-authorization/examples/basic_example.py
@@ -51,8 +51,8 @@ async def main():
"""Run basic examples."""
config = get_config()
- if not config.openai_api_key:
- print("❌ Error: OPENAI_API_KEY not set")
+ if not config.mistral_api_key:
+ print("❌ Error: MISTRAL_API_KEY not set")
print("Please set it in your .env file or environment")
return
diff --git a/agentic-rag-authorization/examples/setup_environment.py b/agentic-rag-authorization/examples/setup_environment.py
index a9e798c..e08c054 100644
--- a/agentic-rag-authorization/examples/setup_environment.py
+++ b/agentic-rag-authorization/examples/setup_environment.py
@@ -1,4 +1,4 @@
-"""Initialize Milvus and SpiceDB with sample data."""
+"""Initialize Elasticsearch and SpiceDB with sample data."""
import sys
import os
@@ -8,8 +8,8 @@
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-import openai
-from pymilvus import MilvusClient, DataType
+from langchain_mistralai import MistralAIEmbeddings
+from elasticsearch import Elasticsearch, helpers
from authzed.api.v1 import (
WriteSchemaRequest,
WriteRelationshipsRequest,
@@ -170,61 +170,71 @@ def setup_spicedb():
print(f" - Public access: 5 documents accessible to all users")
-def setup_milvus():
- """Setup Milvus with sample documents using OpenAI semantic embeddings."""
- print("\nSetting up Milvus...")
-
- milvus_uri = os.getenv("MILVUS_URI", "http://localhost:19530")
- openai_api_key = os.getenv("OPENAI_API_KEY", "")
-
- client = MilvusClient(uri=milvus_uri)
- oai_client = openai.OpenAI(api_key=openai_api_key)
-
- if client.has_collection("Documents"):
- client.drop_collection("Documents")
- print(" ✅ Dropped existing Documents collection")
-
- schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
- schema.add_field("doc_id", DataType.VARCHAR, max_length=256, is_primary=True)
- schema.add_field("title", DataType.VARCHAR, max_length=512)
- schema.add_field("content", DataType.VARCHAR, max_length=65535)
- schema.add_field("department", DataType.VARCHAR, max_length=128)
- schema.add_field("classification", DataType.VARCHAR, max_length=128)
- schema.add_field("embedding", DataType.FLOAT_VECTOR, dim=1536)
-
- index_params = client.prepare_index_params()
- index_params.add_index(
- field_name="embedding",
- metric_type="COSINE",
- index_type="IVF_FLAT",
- params={"nlist": 128},
- )
-
- client.create_collection("Documents", schema=schema, index_params=index_params)
- print(" ✅ Documents collection created")
+def setup_elasticsearch():
+ """Setup Elasticsearch with sample documents using Mistral semantic embeddings."""
+ print("\nSetting up Elasticsearch...")
+
+ es_url = os.getenv("ELASTICSEARCH_URL", "http://localhost:9200")
+ es_api_key = os.getenv("ELASTICSEARCH_API_KEY", "")
+ mistral_api_key = os.getenv("MISTRAL_API_KEY", "")
+
+ if es_api_key:
+ client = Elasticsearch(es_url, api_key=es_api_key)
+ else:
+ client = Elasticsearch(es_url)
+ embeddings = MistralAIEmbeddings(model="mistral-embed", api_key=mistral_api_key)
+
+ if client.indices.exists(index="documents"):
+ client.indices.delete(index="documents")
+ print(" ✅ Dropped existing documents index")
+
+ mappings = {
+ "properties": {
+ "doc_id": {"type": "keyword"},
+ "title": {"type": "text"},
+ "content": {"type": "text"},
+ "department": {"type": "keyword"},
+ "classification": {"type": "keyword"},
+ "embedding": {
+ "type": "dense_vector",
+ "dims": 1024,
+ "index": True,
+ "similarity": "cosine",
+ },
+ }
+ }
+
+ client.indices.create(index="documents", mappings=mappings)
+ print(" ✅ documents index created")
documents = load_all_documents()
print(f" ✅ Loaded {len(documents)} documents from data/documents/")
- rows = []
- for i, doc in enumerate(documents):
- response = oai_client.embeddings.create(
- model="text-embedding-3-small",
- input=doc["content"],
- )
- rows.append({
- "doc_id": doc["doc_id"],
- "title": doc["title"],
- "content": doc["content"],
- "department": doc["department"],
- "classification": doc["classification"],
- "embedding": response.data[0].embedding,
- })
- if (i + 1) % 10 == 0:
- print(f" Embedded {i + 1}/{len(documents)} documents...")
-
- client.insert("Documents", rows)
- print(f" ✅ Inserted {len(rows)} documents with embeddings")
+ # Embed all documents in a single batched call. embed_documents() chunks the
+ # inputs internally, so this issues far fewer Mistral API requests than
+ # embedding one document at a time (and is much less likely to hit rate limits).
+ doc_embeddings = embeddings.embed_documents([doc["content"] for doc in documents])
+ print(f" ✅ Embedded {len(doc_embeddings)} documents")
+
+ actions = [
+ {
+ "_index": "documents",
+ "_id": doc["doc_id"],
+ "_source": {
+ "doc_id": doc["doc_id"],
+ "title": doc["title"],
+ "content": doc["content"],
+ "department": doc["department"],
+ "classification": doc["classification"],
+ "embedding": embedding,
+ },
+ }
+ for doc, embedding in zip(documents, doc_embeddings)
+ ]
+
+ helpers.bulk(client, actions)
+ client.indices.refresh(index="documents")
+ print(f" ✅ Inserted {len(actions)} documents with embeddings")
dept_counts = {}
for doc in documents:
@@ -243,7 +253,7 @@ def main():
print("=" * 60)
setup_spicedb()
- setup_milvus()
+ setup_elasticsearch()
print("\n" + "=" * 60)
print("✅ Setup complete!")
diff --git a/agentic-rag-authorization/pyproject.toml b/agentic-rag-authorization/pyproject.toml
index e96e902..4c8c8a4 100644
--- a/agentic-rag-authorization/pyproject.toml
+++ b/agentic-rag-authorization/pyproject.toml
@@ -1,14 +1,14 @@
[project]
-name = "agentic-rag-weaviate"
+name = "agentic-rag-elasticsearch"
version = "0.1.0"
-description = "Agentic RAG with fine-grained authorization using Weaviate and SpiceDB"
+description = "Agentic RAG with fine-grained authorization using Elasticsearch and SpiceDB"
requires-python = ">=3.10"
dependencies = [
"langchain>=0.1.0",
- "langchain-openai>=0.1.0",
+ "langchain-mistralai>=0.2.0",
"langgraph>=0.0.20",
"langchain-spicedb>=0.1.0",
- "weaviate-client>=4.4.0",
+ "elasticsearch>=8.0.0,<9.0.0",
"authzed>=0.7.0",
"python-dotenv>=1.0.0",
]
diff --git a/agentic-rag-authorization/requirements.txt b/agentic-rag-authorization/requirements.txt
index f5401bd..767fa56 100644
--- a/agentic-rag-authorization/requirements.txt
+++ b/agentic-rag-authorization/requirements.txt
@@ -1,9 +1,9 @@
# Core dependencies
langchain>=0.1.0
-langchain-openai>=0.1.0
+langchain-mistralai>=0.2.0
langgraph>=0.0.20
langchain-spicedb>=0.2.0
-pymilvus>=2.4.0
+elasticsearch>=8.0.0,<9.0.0
authzed>=0.7.0
python-dotenv>=1.0.0
grpcio>=1.50.0
diff --git a/agentic-rag-authorization/run_ui.py b/agentic-rag-authorization/run_ui.py
index 79cbeea..5c322a0 100755
--- a/agentic-rag-authorization/run_ui.py
+++ b/agentic-rag-authorization/run_ui.py
@@ -18,16 +18,19 @@ def check_services():
print(" Copy .env.example to .env and configure it")
return False
- # Check Milvus
+ # Check Elasticsearch
try:
from agentic_rag.config import get_config
- from agentic_rag.milvus_client import get_milvus_client
+ from agentic_rag.elasticsearch_client import get_elasticsearch_client
config = get_config()
- milvus_client = get_milvus_client(config.milvus_uri, config.milvus_token)
- print(" ✅ Milvus connected")
+ es_client = get_elasticsearch_client(
+ config.elasticsearch_url, config.elasticsearch_api_key
+ )
+ es_client.info()
+ print(" ✅ Elasticsearch connected")
except Exception as e:
- print(f" ❌ Milvus not available: {e}")
+ print(f" ❌ Elasticsearch not available: {e}")
print(" Run: docker-compose up -d")
return False
@@ -42,30 +45,25 @@ def check_services():
print(" Run: docker-compose up -d")
return False
- # Check OpenAI key
- if not config.openai_api_key or config.openai_api_key == "your-openai-api-key-here":
- print(" ❌ OPENAI_API_KEY not configured")
+ # Check Mistral key
+ if not config.mistral_api_key or config.mistral_api_key == "your-mistral-api-key-here":
+ print(" ❌ MISTRAL_API_KEY not configured")
print(" Set it in .env file")
return False
- print(" ✅ OpenAI API key configured")
+ print(" ✅ Mistral API key configured")
# Check if documents are loaded
try:
- if milvus_client.has_collection("Documents"):
- results = milvus_client.query(
- collection_name="Documents",
- filter='doc_id != ""',
- output_fields=["doc_id"],
- limit=1,
- )
- if results:
- print(" ✅ Documents loaded in Milvus")
+ if es_client.indices.exists(index="documents"):
+ count = es_client.count(index="documents")["count"]
+ if count > 0:
+ print(" ✅ Documents loaded in Elasticsearch")
else:
- print(" ⚠️ No documents found in Milvus")
+ print(" ⚠️ No documents found in Elasticsearch")
print(" Run: python examples/setup_environment.py")
return False
else:
- print(" ⚠️ Documents collection does not exist in Milvus")
+ print(" ⚠️ documents index does not exist in Elasticsearch")
print(" Run: python examples/setup_environment.py")
return False
except Exception as e:
diff --git a/agentic-rag-authorization/test_improvements.py b/agentic-rag-authorization/test_improvements.py
index 0849ecd..831398b 100644
--- a/agentic-rag-authorization/test_improvements.py
+++ b/agentic-rag-authorization/test_improvements.py
@@ -65,19 +65,19 @@ def test_connection_pooling():
reset_spicedb_client,
_spicedb_client,
)
- from agentic_rag.milvus_client import (
- get_milvus_client,
- reset_milvus_client,
- _milvus_client,
+ from agentic_rag.elasticsearch_client import (
+ get_elasticsearch_client,
+ reset_elasticsearch_client,
+ _es_client,
)
# Verify reset functions exist
assert callable(reset_spicedb_client)
- assert callable(reset_milvus_client)
+ assert callable(reset_elasticsearch_client)
print("✅ Connection pooling functions defined correctly")
print(" - get_spicedb_client() available")
- print(" - get_milvus_client() available")
+ print(" - get_elasticsearch_client() available")
print(" - reset_*_client() functions available")
return True
except (ImportError, AssertionError) as e:
diff --git a/agentic-rag-authorization/tests/conftest.py b/agentic-rag-authorization/tests/conftest.py
index 52109b6..6819429 100644
--- a/agentic-rag-authorization/tests/conftest.py
+++ b/agentic-rag-authorization/tests/conftest.py
@@ -1,14 +1,14 @@
"""Test fixtures for agentic RAG tests."""
import pytest
-from pymilvus import MilvusClient
+from elasticsearch import Elasticsearch
from agentic_rag.grpc_helpers import create_insecure_spicedb_client
@pytest.fixture
-def milvus_client():
- """Create MilvusClient for tests."""
- return MilvusClient(uri="http://localhost:19530")
+def elasticsearch_client():
+ """Create Elasticsearch client for tests."""
+ return Elasticsearch("http://localhost:9200")
@pytest.fixture
diff --git a/agentic-rag-authorization/tests/test_config.py b/agentic-rag-authorization/tests/test_config.py
index fb1ebd0..90beb81 100644
--- a/agentic-rag-authorization/tests/test_config.py
+++ b/agentic-rag-authorization/tests/test_config.py
@@ -5,31 +5,45 @@
from agentic_rag.config import Config
-def test_config_loads_milvus_uri():
+def test_config_loads_elasticsearch_url():
env = {
- "MILVUS_URI": "http://milvus-host:19530",
- "OPENAI_API_KEY": "sk-test",
+ "ELASTICSEARCH_URL": "http://es-host:9200",
+ "MISTRAL_API_KEY": "mstrl-test",
"SPICEDB_TOKEN": "tok",
"SPICEDB_ENDPOINT": "localhost:50051",
}
with patch.dict(os.environ, env, clear=True):
config = Config.from_env()
- assert config.milvus_uri == "http://milvus-host:19530"
+ assert config.elasticsearch_url == "http://es-host:9200"
-def test_config_milvus_defaults():
+def test_config_loads_mistral_api_key():
env = {
- "OPENAI_API_KEY": "sk-test",
+ "MISTRAL_API_KEY": "mstrl-test",
"SPICEDB_TOKEN": "tok",
"SPICEDB_ENDPOINT": "localhost:50051",
}
with patch.dict(os.environ, env, clear=True):
config = Config.from_env()
- assert config.milvus_uri == "http://localhost:19530"
- assert config.milvus_token == ""
+ assert config.mistral_api_key == "mstrl-test"
-def test_config_has_no_weaviate_fields():
+def test_config_elasticsearch_defaults():
+ env = {
+ "MISTRAL_API_KEY": "mstrl-test",
+ "SPICEDB_TOKEN": "tok",
+ "SPICEDB_ENDPOINT": "localhost:50051",
+ }
+ with patch.dict(os.environ, env, clear=True):
+ config = Config.from_env()
+ assert config.elasticsearch_url == "http://localhost:9200"
+ assert config.elasticsearch_api_key == ""
+
+
+def test_config_has_no_milvus_weaviate_or_openai_fields():
config = Config.from_env()
+ assert not hasattr(config, "milvus_uri")
+ assert not hasattr(config, "milvus_token")
assert not hasattr(config, "weaviate_url")
assert not hasattr(config, "weaviate_api_key")
+ assert not hasattr(config, "openai_api_key")
diff --git a/agentic-rag-authorization/tests/test_elasticsearch_client.py b/agentic-rag-authorization/tests/test_elasticsearch_client.py
new file mode 100644
index 0000000..341bea6
--- /dev/null
+++ b/agentic-rag-authorization/tests/test_elasticsearch_client.py
@@ -0,0 +1,43 @@
+"""Unit tests for Elasticsearch client singleton."""
+
+from unittest.mock import patch, MagicMock
+
+
+def test_get_elasticsearch_client_returns_singleton():
+ from agentic_rag.elasticsearch_client import (
+ get_elasticsearch_client,
+ reset_elasticsearch_client,
+ )
+ reset_elasticsearch_client()
+ with patch("agentic_rag.elasticsearch_client.Elasticsearch") as mock_cls:
+ mock_cls.return_value = MagicMock()
+ client1 = get_elasticsearch_client("http://localhost:9200")
+ client2 = get_elasticsearch_client("http://localhost:9200")
+ assert client1 is client2
+ mock_cls.assert_called_once_with("http://localhost:9200")
+
+
+def test_reset_clears_singleton():
+ from agentic_rag.elasticsearch_client import (
+ get_elasticsearch_client,
+ reset_elasticsearch_client,
+ )
+ reset_elasticsearch_client()
+ with patch("agentic_rag.elasticsearch_client.Elasticsearch") as mock_cls:
+ mock_cls.return_value = MagicMock()
+ get_elasticsearch_client("http://localhost:9200")
+ reset_elasticsearch_client()
+ get_elasticsearch_client("http://localhost:9200")
+ assert mock_cls.call_count == 2
+
+
+def test_api_key_passed_when_set():
+ from agentic_rag.elasticsearch_client import (
+ get_elasticsearch_client,
+ reset_elasticsearch_client,
+ )
+ reset_elasticsearch_client()
+ with patch("agentic_rag.elasticsearch_client.Elasticsearch") as mock_cls:
+ mock_cls.return_value = MagicMock()
+ get_elasticsearch_client("http://localhost:9200", api_key="secret")
+ mock_cls.assert_called_once_with("http://localhost:9200", api_key="secret")
diff --git a/agentic-rag-authorization/tests/test_milvus_client.py b/agentic-rag-authorization/tests/test_milvus_client.py
deleted file mode 100644
index f489833..0000000
--- a/agentic-rag-authorization/tests/test_milvus_client.py
+++ /dev/null
@@ -1,25 +0,0 @@
-"""Unit tests for Milvus client singleton."""
-
-from unittest.mock import patch, MagicMock
-
-
-def test_get_milvus_client_returns_singleton():
- from agentic_rag.milvus_client import get_milvus_client, reset_milvus_client
- reset_milvus_client()
- with patch("agentic_rag.milvus_client.MilvusClient") as mock_cls:
- mock_cls.return_value = MagicMock()
- client1 = get_milvus_client("http://localhost:19530")
- client2 = get_milvus_client("http://localhost:19530")
- assert client1 is client2
- mock_cls.assert_called_once_with(uri="http://localhost:19530", token="")
-
-
-def test_reset_clears_singleton():
- from agentic_rag.milvus_client import get_milvus_client, reset_milvus_client
- reset_milvus_client()
- with patch("agentic_rag.milvus_client.MilvusClient") as mock_cls:
- mock_cls.return_value = MagicMock()
- get_milvus_client("http://localhost:19530")
- reset_milvus_client()
- get_milvus_client("http://localhost:19530")
- assert mock_cls.call_count == 2
diff --git a/agentic-rag-authorization/tests/test_retrieval_node.py b/agentic-rag-authorization/tests/test_retrieval_node.py
index 5276e58..38fe6c5 100644
--- a/agentic-rag-authorization/tests/test_retrieval_node.py
+++ b/agentic-rag-authorization/tests/test_retrieval_node.py
@@ -24,7 +24,7 @@ def sample_state():
def _make_hit(doc_id="doc-001", title="Test Doc", content="Content", dept="engineering", classification="internal"):
return {
- "entity": {
+ "_source": {
"doc_id": doc_id,
"title": title,
"content": content,
@@ -37,11 +37,11 @@ def _make_hit(doc_id="doc-001", title="Test Doc", content="Content", dept="engin
def test_retrieval_node_returns_documents(sample_state):
from agentic_rag.nodes.retrieval_node import retrieval_node
- with patch("agentic_rag.nodes.retrieval_node.get_milvus_client") as mock_get_client, \
+ with patch("agentic_rag.nodes.retrieval_node.get_elasticsearch_client") as mock_get_client, \
patch("agentic_rag.nodes.retrieval_node._embed") as mock_embed:
- mock_embed.return_value = [0.1] * 1536
+ mock_embed.return_value = [0.1] * 1024
mock_client = MagicMock()
- mock_client.search.return_value = [[_make_hit()]]
+ mock_client.search.return_value = {"hits": {"hits": [_make_hit()]}}
mock_get_client.return_value = mock_client
result = retrieval_node(sample_state)
@@ -60,9 +60,9 @@ def test_retrieval_node_returns_documents(sample_state):
def test_retrieval_node_increments_attempt_on_failure(sample_state):
from agentic_rag.nodes.retrieval_node import retrieval_node
- with patch("agentic_rag.nodes.retrieval_node.get_milvus_client") as mock_get_client, \
+ with patch("agentic_rag.nodes.retrieval_node.get_elasticsearch_client") as mock_get_client, \
patch("agentic_rag.nodes.retrieval_node._embed") as mock_embed:
- mock_embed.side_effect = RuntimeError("OpenAI unavailable")
+ mock_embed.side_effect = RuntimeError("Mistral unavailable")
mock_get_client.return_value = MagicMock()
result = retrieval_node(sample_state)
@@ -71,17 +71,13 @@ def test_retrieval_node_increments_attempt_on_failure(sample_state):
assert result["retrieval_attempt"] == 1
-def test_embed_calls_openai():
+def test_embed_calls_mistral():
from agentic_rag.nodes.retrieval_node import _embed
- mock_response = MagicMock()
- mock_response.data = [MagicMock(embedding=[0.5] * 1536)]
+ with patch("agentic_rag.nodes.retrieval_node.MistralAIEmbeddings") as mock_emb:
+ mock_emb.return_value.embed_query.return_value = [0.5] * 1024
+ result = _embed("hello world", "mstrl-test")
- with patch("agentic_rag.nodes.retrieval_node.openai.OpenAI") as mock_oai:
- mock_oai.return_value.embeddings.create.return_value = mock_response
- result = _embed("hello world", "sk-test")
-
- assert result == [0.5] * 1536
- mock_oai.return_value.embeddings.create.assert_called_once_with(
- model="text-embedding-3-small", input="hello world"
- )
+ assert result == [0.5] * 1024
+ mock_emb.assert_called_once_with(model="mistral-embed", api_key="mstrl-test")
+ mock_emb.return_value.embed_query.assert_called_once_with("hello world")
From 60a51c42f1aa19e6db0c23450ab15149e9c0a756 Mon Sep 17 00:00:00 2001
From: Sohan Maheshwar <1119120+sohanmaheshwar@users.noreply.github.com>
Date: Tue, 6 Oct 2026 15:15:09 +0200
Subject: [PATCH 2/4] agentic-rag: add request-flow diagram to README TL;DR
---
agentic-rag-authorization/README.md | 4 ++++
agentic-rag-authorization/agentic-rag-flow.png | Bin 0 -> 380828 bytes
2 files changed, 4 insertions(+)
create mode 100644 agentic-rag-authorization/agentic-rag-flow.png
diff --git a/agentic-rag-authorization/README.md b/agentic-rag-authorization/README.md
index 873d2fc..0893479 100644
--- a/agentic-rag-authorization/README.md
+++ b/agentic-rag-authorization/README.md
@@ -17,6 +17,10 @@ The two takeaways from this demo are:
2. Never ever let an AI Agent *decide* if it needs to check for authorization. Gen AI is inherently probabilistic so you have to ensure that permission checks are deterministic and cannot be skipped.
+The diagram below shows the end-to-end request flow: the application embeds the query with Mistral, retrieves relevant context from Elasticsearch, checks permissions in SpiceDB, and only then passes the authorized context to the Mistral LLM to generate a response.
+
+
+
## Documentation Navigation
- **[README.md](README.md)** (you are here) - Overview, quick start, core concepts
diff --git a/agentic-rag-authorization/agentic-rag-flow.png b/agentic-rag-authorization/agentic-rag-flow.png
new file mode 100644
index 0000000000000000000000000000000000000000..a43663d93adc2029213eda12a07f316c40c49d61
GIT binary patch
literal 380828
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