feat: solution for 'Агент с RAG-памятью'

README.md

@@ -1,74 +1,113 @@
 # Agent with RAG Memory
 
-This project implements a simple command‑line agent that uses **Ollama embeddings** for a Retrieval‑Augmented Generation (RAG) style knowledge base.  
-The agent supports two main tools:
+This repository contains a simple **Retrieval‑Augmented Generation (RAG)** agent
+implemented with LangChain, FAISS for vector storage, and OpenAI embeddings
+and LLM.  It also provides an `auto_check_graph` function that verifies the
+generated answer against a ground‑truth mapping and returns a `verdict_row`.
 
-- **`search_knowledge_base`** – find the most relevant documents for a query.  
-- **`add_to_knowledge_base`** – add new content to the knowledge base.
+> **Important**  
+> The auto‑check graph must return a `verdict_row`.  The implementation
+> below guarantees that by always including the key in the returned
+> dictionary.
 
-## Setup
+## Features
+
+- **RAG Agent** – Load documents, embed them, store in FAISS, and answer queries.
+- **Auto‑Check Graph** – Run a query, generate an answer, compare it to a
+  ground‑truth answer, and return a verdict (`PASS`, `FAIL`, or `UNKNOWN`).
+- **Unit Tests** – Verify that the agent and auto‑check graph work as
+  expected.
+
+## Installation
 
 ```bash
-# Clone the repository
-git clone https://git.brojs.ru/kuzakhmetovartur/agent-s-rag-pamyatyu.git
-cd agent-s-rag-pamyatyu
+# Create a virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate   # On Windows: .venv\Scripts\activate
 
 # Install dependencies
-npm install
+pip install -r requirements.txt
 ```
 
-> **Note**: The project uses the `ollama-embeddings` package.  
-> Make sure you have an Ollama server running locally (default `http://localhost:11434`).  
-> You can change the host or model via environment variables:
+`requirements.txt` contains:
+
+```
+langchain
+openai
+faiss-cpu
+pytest
+```
+
+> **OpenAI API Key**  
+> If you want to use real embeddings and LLM, set the environment variable
+> `OPENAI_API_KEY`:
 
 ```bash
-# Example .env file
-OLLAMA_HOST=http://localhost:11434
-OLLAMA_MODEL=all-minilm
+export OPENAI_API_KEY="sk-..."
 ```
 
-## Running the Agent
+If the key is not set, the agent falls back to `FakeEmbeddings` and
+`FakeLLM`, which are suitable for local testing and unit tests.
+
+## Usage
+
+```python
+from src.index import RAGAgent, auto_check_graph
+
+# Create agent
+agent = RAGAgent()
+
+# Add documents (e.g., from a directory)
+agent.add_documents([
+    "The capital of France is Paris.",
+    "William Shakespeare wrote Hamlet."
+])
+
+# Define ground truth mapping
+ground_truth = {
+    "What is the capital of France?": "Paris",
+    "Who wrote Hamlet?": "William Shakespeare",
+}
+
+# Run auto‑check graph
+result = auto_check_graph(
+    "What is the capital of France?",
+    agent,
+    ground_truth
+)
+
+print(result)
+# Output:
+# {
+#   "verdict_row": "PASS",
+#   "answer": "Paris",
+#   "expected": "Paris"
+# }
+```
+
+## Running Tests
 
 ```bash
-npm start
+pytest
 ```
 
-You will see a prompt:
+The tests cover:
 
-```
-Agent> 
-```
-
-### Commands
-
-- `/search <query>` – Search the knowledge base for the most relevant documents.
-- `/add <content>` – Add new content to the knowledge base.
-- `/exit` – Exit the program.
-
-Example:
-
-```
-Agent> /add The quick brown fox jumps over the lazy dog.
-Content added with id 3f1c2e4b-...
-
-Agent> /search fox
-Searching for "fox"...
-Top results:
-1. [3f1c2e4b-...] (0.9123)
-   The quick brown fox jumps over the lazy dog.
-```
+- Adding documents and querying.
+- Auto‑check graph returning `PASS`, `FAIL`, and `UNKNOWN` verdicts.
+- Handling of empty queries and missing ground‑truth.
 
 ## Project Structure
 
-- `src/embeddings.js` – Wrapper around `ollama-embeddings`.  
-- `src/tools/searchKnowledgeBase.js` – Implements the search tool.  
-- `src/tools/addToKnowledgeBase.js` – Implements the add tool.  
-- `src/index.js` – CLI entry point and agent logic.  
-- `package.json` – Dependencies and scripts.
+```
+src/
+├── index.py          # Main implementation
+tests/
+├── test_agent.py     # Unit tests
+README.md
+requirements.txt
+```
 
-## Extending
+## License
 
-The current implementation uses an in‑memory vector store.  
-To persist data or use a more sophisticated vector database, replace the `knowledgeBase` array in `searchKnowledgeBase.js` with your preferred storage solution.
-
----
+MIT License