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

README.md

@@ -1,89 +1,121 @@
 # RAG Agent with ChromaDB and Web Search
 
-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:
+This repository contains a lightweight Retrieval‑Augmented Generation (RAG) agent that uses **ChromaDB** as the vector store and performs a simple web search to augment the retrieved context before generating an answer with OpenAI's GPT model.
 
-- `POST /ingest` – ingest documents into the vector store.
-- `POST /query` – retrieve the most similar documents for a given query.
+> **Deadline**: 31.08.2026  
+> **Version**: 14
 
 ## Features
 
-- **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.
+- **Vector Store** – ChromaDB (local, no external service required)
+- **Embeddings** – OpenAI `text-embedding-ada-002`
+- **LLM** – OpenAI `gpt-3.5-turbo`
+- **Web Search** – DuckDuckGo (no API key needed)
+- **Command‑line interface** for adding documents and asking questions
 
 ## Prerequisites
 
-- Python 3.11+
-- Docker (optional, for containerized deployment)
-- An OpenAI API key (set as `OPENAI_API_KEY` environment variable).
+- Python 3.9+
+- An OpenAI API key
 
-## Setup
-
-### Local
+## Installation
 
 ```bash
 # Clone the repository
 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 virtual environment
-python -m venv venv
-source venv/bin/activate
+# Create a virtual environment (optional but recommended)
+python -m venv .venv
+source .venv/bin/activate   # On Windows: .venv\Scripts\activate
 
 # Install dependencies
 pip install -r requirements.txt
+```
 
-# Set OpenAI API key
+`requirements.txt` contains:
+
+```
+openai>=1.0.0
+chromadb>=0.4.0
+requests>=2.31.0
+beautifulsoup4>=4.12.0
+```
+
+## Configuration
+
+Set your OpenAI API key as an environment variable:
+
+```bash
 export OPENAI_API_KEY="sk-..."
-
-# Run the server
-uvicorn src.main:app --reload
 ```
 
-The API will be available at `http://127.0.0.1:8000`.
+On Windows:
 
-### Docker
-
-```bash
-# Build the image
-docker build -t rag-agent .
-
-# Run the container
-docker run -d -p 8000:8000 --env OPENAI_API_KEY="sk-..." rag-agent
+```cmd
+set OPENAI_API_KEY=sk-...
 ```
 
-## API Usage
+## Usage
 
-### Ingest Documents
+### 1. Add Documents
+
+Add a text file to the vector store. The file will be split into chunks (≈500 tokens each) and embedded.
 
 ```bash
-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."}
-           ]
-         }'
+python -m src.index add path/to/document.txt
 ```
 
-### Query
+Example:
 
 ```bash
-curl -X POST http://localhost:8000/query \
-     -H "Content-Type: application/json" \
-     -d '{
-           "query": "What is Python?",
-           "k": 3
-         }'
+python -m src.index add data/biology.txt
+```
+
+### 2. Ask a Question
+
+Query the RAG agent. It will:
+
+1. Retrieve the top‑5 nearest chunks from ChromaDB.
+2. Perform a DuckDuckGo web search for the query.
+3. Combine the retrieved context and web snippets.
+4. Generate an answer with GPT.
+
+```bash
+python -m src.index ask "What is the function of mitochondria?"
+```
+
+### 3. Help
+
+```bash
+python -m src.index
+```
+
+## Example
+
+```bash
+$ python -m src.index add sample.txt
+Added 4 chunks from sample.txt to the collection.
+
+$ python -m src.index ask "Explain the water cycle."
+Answer:
+The water cycle, also known as the hydrologic cycle, describes the continuous movement of water on, above, and below the surface of the Earth. ...
+```
+
+## Project Structure
+
+```
+src/
+├── index.py          # Main script
+README.md
+requirements.txt
 ```
 
 ## Notes
 
-- 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.
+- **ChromaDB Persistence** – The vector store is persisted in `./chromadb`. Delete this folder to reset the store.
+- **Token Limits** – The embedding model `text-embedding-ada-002` supports up to 8191 tokens per request. The chunking logic approximates a 500‑token limit per chunk.
+- **Web Search** – DuckDuckGo is used for simplicity. For production use, consider a dedicated search API (e.g., SerpAPI, Bing Search API).
 
 ## License