NTT RAG Project

A modern Agentic RAG (Retrieval-Augmented Generation) system built with Pydantic AI, FastAPI, and PostgreSQL (pgvector). This project provides a scalable, modular, and production-ready foundation for document-based AI applications.

📋 Table of Contents

Features
Tech Stack
Installation
Usage
API Reference
Project Structure
Development
Testing
License

✨ Features

🧠 Pydantic AI-based intelligent agent system
🔍 Multiple search strategies: Vector Search and Hybrid Search
📄 Advanced PDF processing: Table and image extraction with Docling
💾 Database: PostgreSQL + pgvector extension
🌊 Real-time streaming: Live responses via Server-Sent Events
🎯 Session management: Conversation history and context retention
🐳 Docker containerization: Easy deployment
🔧 Type safety: Reliable data handling with Pydantic models
⚡ Instant ingestion: Upload documents and query immediately

🛠️ Tech Stack

Backend

Pydantic AI - AI Agent Framework
FastAPI - Modern Python web framework
LangChain - Document processing and embeddings
Docling - PDF extraction and analysis
AsyncPG - PostgreSQL async client
pgvector - Vector similarity search

Frontend

Streamlit - Interactive web interface

Infrastructure

PostgreSQL 17 - Primary database
Docker Compose - Multi-container deployment
uv - Fast Python package installer

🚀 Installation

Prerequisites

Python 3.12+
Docker & Docker Compose
Git

1. Clone the Repository

git clone https://github.com/serkanyasr/ntt_rag_project.git
cd ntt_rag_project

2. Set Up Environment Variables

Create a .env file:

# API Configuration
APP_ENV=development
LOG_LEVEL=INFO
APP_HOST=0.0.0.0
APP_PORT=8058
API_URL=http://api:8058

# Streamlit Configuration
SERVER_PORT=8501
SERVER_HOST=0.0.0.0

# PostgreSQL Vector DB Configuration
DB_USER=postgres
DB_PASSWORD=postgres
DB_HOST=postgres
DB_PORT=5432
DB_NAME=vector_db

# OpenAI API Configuration (required)
OPENAI_API_KEY=your_openai_api_key
LLM_CHOICE=gpt-4o-mini
EMBEDDING_MODEL=text-embedding-3-small

3. Start with Docker

docker-compose up -d
docker-compose logs -f

📚 Usage

Web Interface

Access the Streamlit UI: http://localhost:8501

The web interface now includes:

Interactive Chat: Ask questions about your uploaded documents
Health Monitoring: Check API connection status
Session Management: Persistent conversation history

API Usage

FastAPI documentation: http://localhost:8058/docs

Chat Endpoint Example

import requests

response = requests.post("http://localhost:8058/chat", json={
    "message": "Hello, how can I help you?",
    "session_id": "optional-session-id",
    "user_id": "user-123",
    "search_type": "hybrid"
})
print(response.json())

Streaming Chat Example

import requests
import json

response = requests.post(
    "http://localhost:8058/chat/stream",
    json={
        "message": "Give a long explanation",
        "search_type": "hybrid"
    },
    stream=True
)

for line in response.iter_lines():
    if line.startswith(b'data: '):
        data = json.loads(line[6:])
        if data.get("type") == "text":
            print(data.get("content"), end="")

Document Ingestion

Command Line Ingestion

# Place your PDF documents in the documents/ folder
cp your_document.pdf documents/

# Run the ingestion script
python -m ingestion.ingest --documents documents/

📖 API Reference

Endpoints

Chat Endpoints

POST /chat - Single chat message
POST /chat/stream - Streaming chat
GET /chat/sessions/{session_id} - Session history

Search Endpoints

POST /search/vector - Vector search
POST /search/hybrid - Hybrid search

Health Check

GET /health - System status

Request/Response Models

Chat Request

{
  "message": "Your question",
  "session_id": "optional-session-id",
  "user_id": "user-id",
  "search_type": "hybrid",
  "metadata": {}
}

Search Request

{
  "query": "Search query",
  "search_type": "vector",
  "limit": 10,
  "filters": {}
}

🏗️ Project Structure

ntt_rag_project/
├── agent/                  # AI Agent and business logic
│   ├── agent.py           # Main Pydantic AI agent
│   ├── api.py             # FastAPI endpoints
│   ├── db_utils.py        # Database operations
│   ├── models.py          # Pydantic models
│   ├── prompts.py         # System prompts
│   ├── providers.py       # LLM and embedding providers
│   └── tools.py           # Agent tools
├── ingestion/             # Document processing
│   ├── chunker.py         # Text chunking
│   ├── extract_files.py   # PDF extraction
│   └── ingest.py          # Main ingestion pipeline
├── ui/                    # Streamlit UI
│   └── app.py
├── sql/                   # Database schema
│   └── schema.sql
├── tests/                 # Test files
├── documents/             # PDF documents
├── docker-compose.yml     # Container orchestration
├── Dockerfile
└── pyproject.toml         # Python dependencies

Main Components

Agent (`/agent/`)

agent.py: Pydantic AI agent definition and tool registrations
api.py: FastAPI web server and endpoints
tools.py: Vector search, hybrid search, document retrieval tools
db_utils.py: PostgreSQL operations and connection management
models.py: Pydantic data models and validation

Ingestion (`/ingestion/`)

ingest.py: Main document processing pipeline
extract_files.py: PDF text, table, and image extraction
chunker.py: Intelligent text chunking strategies

🧪 Testing

Running Tests

pytest
pytest tests/agent/test_models.py
pytest --cov=agent --cov=ingestion

Test Categories

Model Tests: Pydantic model validation
Agent Tests: AI agent functionality
Database Tests: PostgreSQL operations
Ingestion Tests: Document processing

⚙️ Development

Development Setup

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install uv
uv pip install -r pyproject.toml
pre-commit install

Logging

export LOG_LEVEL=DEBUG
docker-compose logs -f api

🔧 Configuration

Environment Variables

Variable	Description	Default
`DB_NAME`	PostgreSQL database name	`rag_db`
`DB_USER`	PostgreSQL user	`rag_user`
`DB_PASSWORD`	PostgreSQL password	-
`OPENAI_API_KEY`	OpenAI API key	-
`APP_PORT`	FastAPI port	`8058`
`SERVER_PORT`	Streamlit port	`8501`
`LLM_MODEL`	LLM model	`gpt-4`
`EMBEDDING_MODEL`	Embedding model	`text-embedding-3-small`

Docker Compose Overrides

You can create a docker-compose.override.yml for custom configurations.

🐛 Troubleshooting

Common Issues

Database Connection Error

docker-compose ps postgres
docker-compose logs postgres

OpenAI API Error

echo $OPENAI_API_KEY

Port Conflicts

netstat -an | grep :8058
netstat -an | grep :8501

📄 License

MIT License - See LICENSE for details.

serkanyasr/ntt_rag_project