feat: solution for '8. Самописный поисковый агент на основе deep agents from scratch'

README.md

@@ -1,87 +1,87 @@
-# Deep Agents from Scratch – Search Agent
+# Custom Search Agent – DeepAgents from Scratch
 
-This project implements a simple web‑search agent using the **LangChain** framework, following the “Deep Agents from Scratch” template.  
-The agent can answer user questions by performing a DuckDuckGo search and reasoning over the results with an OpenAI LLM.
+This repository contains a minimal implementation of a **deep search agent** that:
 
-## Features
+* Generates deterministic mock search results.
+* Creates *virtual files* in memory during execution.
+* Exports those virtual files to a specified directory on disk.
 
-- **Zero‑shot React** agent powered by LangChain.
-- Uses **DuckDuckGo** for web search (no API key required).
-- Powered by **OpenAI** (requires an API key).
-- Conversation memory to keep context across turns.
-- Simple command‑line interface.
+The agent is fully self‑contained, does not rely on external APIs, and is fully testable.
 
-## Prerequisites
+## Project Structure
 
-- Python 3.10+
-- An OpenAI API key (set in `OPENAI_API_KEY` environment variable).
+```
+.
+├── src
+│   ├── agent.py      # Core agent implementation
+│   └── run.py        # CLI entry point
+├── tests
+│   └── test_agent.py # Unit tests
+├── requirements.txt
+└── README.md
+```
 
 ## Installation
 
 ```bash
-# Clone the repository
-git clone https://git.brojs.ru/kuzakhmetovartur/8.-samopisnyy-poiskovyy-agent-na-osnove.git
-cd 8.-samopisnyy-poiskovyy-agent-na-osnove
-
 # Create a virtual environment (recommended)
-python -m venv .venv
-source .venv/bin/activate   # On Windows use `.venv\Scripts\activate`
+python -m venv venv
+source venv/bin/activate   # On Windows: venv\Scripts\activate
 
 # Install dependencies
 pip install -r requirements.txt
 ```
 
-## Configuration
-
-Create a `.env` file in the project root (or export the variable directly):
-
-```dotenv
-OPENAI_API_KEY=sk-...
-```
-
-> **Note**: The DuckDuckGo search tool does not require any API key.
-
 ## Usage
 
-Run the agent from the command line:
+### Command‑line
 
 ```bash
-python main.py "What is the capital of France?"
+python -m src.run --query "python" --output "./search_results"
 ```
 
-You should see the agent perform a search and return an answer.
+This will:
 
-## Example
+1. Search for `"python"` (mock results).
+2. Create two virtual files (`result_1.txt`, `result_2.txt`) in memory.
+3. Export those files to `./search_results`.
+
+### Programmatic
+
+```python
+from src.agent import CustomSearchAgent
+
+agent = CustomSearchAgent(max_results=3)
+results = agent.search("deep learning")
+print(results)          # List of (title, snippet) tuples
+agent.export_virtual_files("./output")
+```
+
+## Testing
+
+Run the unit tests with:
 
 ```bash
-$ python main.py "Who is the current CEO of Tesla?"
-=== Agent Response ===
-Elon Musk is the current CEO of Tesla. He has been in the role since 2008 and is also the founder of SpaceX and Neuralink.
+python -m unittest discover -s tests
 ```
 
-## Project Structure
+All tests should pass, confirming that:
 
-```
-├── src
-│   └── agent.py          # Agent implementation
-├── main.py               # CLI entry point
-├── requirements.txt      # Dependencies
-├── README.md             # Documentation
-└── .env                  # (Optional) Environment variables
-```
+* The agent initializes correctly.
+* Search results are deterministic.
+* Virtual files are created during search.
+* Export writes the correct files to disk.
 
 ## Extending the Agent
 
-- **Add more tools**: Import additional tools from `langchain_community.tools` and add them to the `tools` list in `src/agent.py`.
-- **Change the LLM**: Replace `ChatOpenAI` with another LLM provider (e.g., Anthropic, Gemini) by adjusting the import and initialization.
-- **Adjust temperature**: Modify the `temperature` parameter in `ChatOpenAI` to control creativity.
+The `CustomSearchAgent` inherits from `DeepAgent`.  To add real search logic:
 
-## Troubleshooting
+1. Override `search` to perform actual queries (e.g., to a local index).
+2. Use `create_virtual_file` to store any generated data.
+3. Call `export_virtual_files` when you need to persist the data.
 
-- **Missing OpenAI key**: Ensure `OPENAI_API_KEY` is set in your environment or `.env` file.
-- **Network errors**: Check your internet connection and retry.
-- **Agent hangs**: Increase the `timeout` in the DuckDuckGo tool or switch to a different search provider.
+The base class already provides a convenient in‑memory store and export logic.
 
 ## License
 
-MIT License.
+This project is released under the MIT License.