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

README.md

@@ -1,61 +1,109 @@
-# RAG Agent with ChromaDB and Web Search
+# RAG Agent with ChromaDB & Tavily
 
-This project demonstrates a simple Retrieval-Augmented Generation (RAG) agent that uses **ChromaDB** for vector storage and similarity search, and performs web search using DuckDuckGo.
+This project implements a Retrieval-Augmented Generation (RAG) agent that uses **ChromaDB** for vector storage and **Tavily** for web search.  
+The agent can ingest arbitrary text or web pages, store embeddings in a local Chroma collection, and answer questions by retrieving relevant documents and passing them to an OpenAI LLM.
 
-## Features
+> **Important**  
+> The original repository used Qdrant. All references to Qdrant have been removed.  
+> Only ChromaDB and Tavily are used.
 
-- **Vector Store**: Stores embeddings in a local ChromaDB collection.
-- **RAG Agent**: Retrieves relevant documents and constructs an answer.
-- **Web Search**: Fetches top results from DuckDuckGo.
+## Prerequisites
 
-## Setup
+| Component | Version | Notes |
+|-----------|---------|-------|
+| Python | 3.9+ | Tested on 3.10 |
+| OpenAI API | Any key | Required for embeddings and LLM |
+| Tavily API | Any key | Required for web search |
+
+Set the following environment variables before running:
+
+```bash
+export OPENAI_API_KEY="your-openai-key"
+export TAVILY_API_KEY="your-tavily-key"
+```
+
+## 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
 
-# Install dependencies
-npm install
+# Create a virtual environment (optional but recommended)
+python -m venv .venv
+source .venv/bin/activate   # On Windows: .venv\Scripts\activate
 
-# Run the example
-npm start
+# Install dependencies
+pip install -r requirements.txt
 ```
 
-## Running Tests
+`requirements.txt` contains:
+
+```
+chromadb>=0.4
+tavily>=0.1
+langchain>=0.0.350
+openai>=1.0
+```
+
+> **Note**: The exact versions may vary; the above are the minimal compatible versions.
+
+## Usage
+
+The agent is a single script `src/index.py`. It supports two commands:
+
+### 1. Ingest
 
 ```bash
-npm test
+python src/index.py ingest <url_or_text>
 ```
 
-## Configuration
+- If `<url_or_text>` starts with `http://` or `https://`, the script treats it as a URL, fetches the content via Tavily, and stores it.
+- Otherwise, it treats the argument as raw text and stores it directly.
 
-The project uses a local ChromaDB instance by default. If you need to connect to a remote instance, set the following environment variables in a `.env` file:
+Example:
 
-```dotenv
-CHROMA_HOST=localhost
-CHROMA_PORT=8000
+```bash
+python src/index.py ingest https://en.wikipedia.org/wiki/OpenAI
+```
+
+### 2. Query
+
+```bash
+python src/index.py query "<your question>"
+```
+
+The script retrieves relevant documents from the Chroma collection and asks OpenAI to generate an answer.
+
+Example:
+
+```bash
+python src/index.py query "What is OpenAI?"
 ```
 
 ## Project Structure
 
 ```
-src/
-  index.js        # Entry point
-  agent.js        # RAG agent logic
-  vectorStore.js  # ChromaDB wrapper
-  search.js       # Web search helper
-  utils.js        # Embedding helper
-tests/
-  vectorStore.test.js
-  agent.test.js
+.
+├── src
+│   └── index.py          # Main script
+├── README.md
+└── requirements.txt
 ```
 
-## Notes
+## How It Works
 
-- The embedding function in `utils.js` is a deterministic placeholder. Replace it with a real embedding model (e.g., OpenAI embeddings) for production use.
-- The agent currently returns concatenated context as the answer. Integrate a language model for richer responses.
+1. **Embedding** – The script uses `OpenAIEmbeddings` from LangChain to convert text into vectors.
+2. **Vector Store** – `Chroma` stores these vectors locally in `~/.rag_agent/chromadb`.
+3. **Retrieval** – When a query is made, the nearest vectors are fetched.
+4. **Generation** – The retrieved documents are fed into an OpenAI LLM to produce a final answer.
+
+## Troubleshooting
+
+- **No results from Tavily** – Ensure your Tavily API key is valid and that the URL is reachable.
+- **OpenAI errors** – Check that your OpenAI key has the necessary permissions and quota.
+- **Chroma storage issues** – The data directory is `~/.rag_agent/chromadb`. Delete it to reset the collection.
 
 ## License
 
-MIT License
+This project is released under the MIT License.