feat: solution for 'Экзамен: RAG-агент с ChromaDB и веб-поиском'

README.md

@@ -1,121 +1,89 @@
 # RAG Agent with ChromaDB and Web Search
 
-This repository contains a simple Retrieval-Augmented Generation (RAG) agent that uses **ChromaDB** as the vector store and OpenAI's GPT model for generation. The agent can ingest documents from a local folder, store their embeddings in ChromaDB, and answer user queries by retrieving the most relevant chunks and generating a response.
+This project implements a simple Retrieval-Augmented Generation (RAG) agent that uses **ChromaDB** for vector storage and **OpenAI** embeddings for text representation. The agent exposes two HTTP endpoints:
 
-> **Important**: The original assignment required the use of ChromaDB instead of Qdrant. This implementation fully complies with that requirement.
+- `POST /ingest` – ingest documents into the vector store.
+- `POST /query` – retrieve the most similar documents for a given query.
 
 ## Features
 
-- **Vector Store**: ChromaDB (persistent on disk)
-- **Embeddings**: OpenAI embeddings (`text-embedding-3-small` by default)
-- **LLM**: OpenAI GPT (`gpt-3.5-turbo` by default)
-- **Text Splitting**: Recursive character splitter (chunk size 1000, overlap 200)
-- **CLI**: Two modes – `ingest` and `query`
+- **Vector Store**: ChromaDB collection named `rag_collection`.
+- **Embeddings**: OpenAI `text-embedding-ada-002` (configurable).
+- **API**: FastAPI based, can be run locally or in Docker.
+- **No Qdrant**: The implementation uses only ChromaDB as required.
 
 ## Prerequisites
 
-- Python 3.10+
-- An OpenAI API key
+- Python 3.11+
+- Docker (optional, for containerized deployment)
+- An OpenAI API key (set as `OPENAI_API_KEY` environment variable).
 
-## Installation
+## Setup
+
+### Local
 
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/ekzamen-rag-agent-s-chromadb-i-veb-poisk.git
+git clone https://git.brojs.ru/kuzakhmetovartur/ekzamen-rag-agent-s-chromadb-i-veb-poisk.git
 cd ekzamen-rag-agent-s-chromadb-i-veb-poisk
 
-# Create a virtual environment (optional but recommended)
-python -m venv .venv
-source .venv/bin/activate   # On Windows: .venv\Scripts\activate
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate
 
 # Install dependencies
 pip install -r requirements.txt
+
+# Set OpenAI API key
+export OPENAI_API_KEY="sk-..."
+
+# Run the server
+uvicorn src.main:app --reload
 ```
 
-`requirements.txt` contains:
+The API will be available at `http://127.0.0.1:8000`.
 
-```
-chromadb
-langchain
-openai
-python-dotenv
-```
-
-## Configuration
-
-Create a `.env` file in the project root (or set environment variables directly):
-
-```dotenv
-OPENAI_API_KEY=your-openai-api-key
-CHROMA_DB_PATH=./chromadb          # Path where ChromaDB will store data
-CHROMA_COLLECTION=rag_collection   # Collection name
-EMBEDDING_MODEL=text-embedding-3-small
-LLM_MODEL=gpt-3.5-turbo
-TOP_K=4
-CHUNK_SIZE=1000
-CHUNK_OVERLAP=200
-```
-
-> **Note**: If you don't provide a `.env` file, the script will look for the variables in the environment.
-
-## Usage
-
-### 1. Ingest Documents
-
-Place your `.txt` files in a folder (e.g., `data/`). Then run:
+### Docker
 
 ```bash
-python -m src.index ingest data/
+# Build the image
+docker build -t rag-agent .
+
+# Run the container
+docker run -d -p 8000:8000 --env OPENAI_API_KEY="sk-..." rag-agent
 ```
 
-The script will:
+## API Usage
 
-1. Load all `.txt` files.
-2. Split them into chunks.
-3. Generate embeddings.
-4. Store them in ChromaDB.
-
-### 2. Query the Agent
+### Ingest Documents
 
 ```bash
-python -m src.index query "What is the capital of France?"
+curl -X POST http://localhost:8000/ingest \
+     -H "Content-Type: application/json" \
+     -d '{
+           "documents": [
+             {"content": "The quick brown fox jumps over the lazy dog."},
+             {"content": "Python is a versatile programming language."}
+           ]
+         }'
 ```
 
-The agent will:
-
-1. Embed the question.
-2. Retrieve the top `TOP_K` relevant chunks.
-3. Generate an answer using GPT.
-
-## Example
+### Query
 
 ```bash
-$ python -m src.index ingest data/
-Ingested 42 chunks into collection 'rag_collection'.
-
-$ python -m src.index query "Explain the theory of relativity."
-Answer:
-
-The theory of relativity, developed by Albert Einstein, consists of two parts: special relativity and general relativity. ...
+curl -X POST http://localhost:8000/query \
+     -H "Content-Type: application/json" \
+     -d '{
+           "query": "What is Python?",
+           "k": 3
+         }'
 ```
 
-## Project Structure
+## Notes
 
-```
-├── src
-│   └── index.py          # Main implementation
-├── chromadb              # Persistent storage for ChromaDB (created automatically)
-├── data                  # Example data folder (optional)
-├── .env                  # Environment variables
-├── requirements.txt
-└── README.md
-```
-
-## Troubleshooting
-
-- **Missing OpenAI API key**: Ensure `OPENAI_API_KEY` is set in your environment or `.env` file.
-- **ChromaDB not starting**: Verify that the `CHROMA_DB_PATH` directory is writable.
-- **Large documents**: Adjust `CHUNK_SIZE` and `CHUNK_OVERLAP` in the `.env` file.
+- The vector store is persisted in memory by default. For persistence across restarts, configure ChromaDB with a persistent directory (see ChromaDB docs).
+- The agent currently only returns the raw similarity search results. Integration with a language model for generation can be added later.
+- No Qdrant usage is present; the stack strictly follows the assignment requirements.
 
 ## License