An intelligent knowledge base search system powered by Pydantic AI and PostgreSQL with PGVector. This agent provides both semantic and hybrid search capabilities with automatic strategy selection and result summarization.

Features

Semantic Search: Pure vector similarity search using embeddings
Hybrid Search: Combined semantic and keyword matching for precise results
Intelligent Strategy Selection: Agent automatically chooses the best search approach
Result Summarization: Coherent insights generated from search results
Interactive CLI: Rich command-line interface with real-time streaming
Multi-Provider Support: Works with any OpenAI-compatible API (OpenAI, Gemini, Ollama, etc.)

Prerequisites

Python 3.10+
PostgreSQL with PGVector extension
LLM API key (OpenAI, Gemini, Ollama, Groq, or any OpenAI-compatible provider)
Existing database with documents and chunks (schema provided)

Installation

Clone or copy the agent directory:

cd agents/rag_agent

Install dependencies:

pip install -r requirements.txt

Set up PostgreSQL with PGVector:

# SIMPLEST: Run the SQL in your SQL editor if you are using a platform like Supabase/Postgres

# Or run the schema with psql
psql -d your_database -f sql/schema.sql

Configure environment variables:

cp .env.example .env
# Edit .env with your credentials

Ingest documents into the database:

# This step is required before running the agent
# It will process documents and generate embeddings
python -m ingestion.ingest --documents documents/

Configuration

Required Environment Variables

DATABASE_URL: PostgreSQL connection string with PGVector
LLM_PROVIDER: Provider name (openai, anthropic, ollama, etc.)
LLM_API_KEY: Your LLM provider API key
LLM_MODEL: Model to use (e.g., gpt-4.1-mini, gemini-2.5-flash)
LLM_BASE_URL: API base URL (default: https://api.openai.com/v1)
EMBEDDING_MODEL: Embedding model to use (e.g., text-embedding-3-small, text-embedding-3-large)

Usage

Command Line Interface

Run the interactive CLI:

python -m cli

The CLI provides:

Real-time streaming responses
Tool execution visibility
Session persistence
User preference management

Available Commands

help - Show available commands
info - Display system configuration
clear - Clear the screen
set <key>=<value> - Set preferences (e.g., set text_weight=0.5)
exit/quit - Exit the application

Search Strategies

The agent intelligently selects between two search strategies:

Semantic Search

Best for conceptual queries and finding related content:

"concepts similar to machine learning"
"ideas about artificial intelligence"
"related to neural networks"

Hybrid Search

Best for specific facts and technical terms:

"OpenAI GPT-4 specifications"
"NASDAQ:NVDA stock price"
"specific quote from Sam Altman"

The agent automatically chooses the appropriate strategy based on your query, or you can explicitly request a specific search type in your prompt.

Database Setup

Schema Overview

documents: Stores full documents with metadata
chunks: Stores document chunks with embeddings
match_chunks(): Function for semantic search
hybrid_search(): Function for combined search

Development

Running Tests

pytest tests/

Code Formatting

black .
ruff check .

Project Structure

semantic_search_agent/
├── agent.py           # Main agent implementation
├── cli.py            # Command-line interface
├── dependencies.py   # Agent dependencies
├── providers.py      # Model providers
├── prompts.py        # System prompts
├── settings.py       # Configuration
├── tools.py          # Search tools
├── ingestion/        # Document ingestion pipeline
├── sql/              # Database schema
└── documents/        # Sample documents