# Deep Agent Search

A lightweight search agent that uses a simple neural embedding model to retrieve
documents from a corpus.  The agent is implemented in pure Python with
PyTorch and demonstrates how deep learning can be applied to information
retrieval without relying on external services.

> **Author**: Artur Kuzakhmetov  
> **Course**: DeepAgents – Perplexity (Lecture 09.04.2026)  
> **Deadline**: 31.08.2026

## Features

- **Custom neural encoder** – word embeddings trained from scratch.
- **Cosine similarity ranking** – fast and interpretable.
- **Command‑line interface** – run searches directly from the terminal.
- **Unit tests** – ensure correctness of embeddings, similarity, and ranking.
- **No external services** – everything runs locally on CPU or GPU.

## Installation

```bash
# Clone the repository
git clone https://git.brojs.ru/kuzakhmetovartur/8.-samopisnyy-poiskovyy-agent-na-osnove-<repo>.git
cd 8.-samopisnyy-poiskovyy-agent-na-osnove-<repo>

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

> **Note**: The project requires Python 3.8+ and PyTorch ≥ 1.8.0.

## Usage

### Command‑line

```bash
python -m src.main "deep learning models"
```

The script prints the top 5 results with relevance scores.

### Programmatic

```python
from src.agent import SearchAgent

corpus = [
    "Deep learning models can capture complex patterns in data.",
    "Search engines index documents to provide relevant results.",
    # ...
]

agent = SearchAgent(corpus)
results = agent.search("deep learning", top_k=3)

for res in results:
    print(f"Doc {res.doc_id} (score={res.score:.4f}): {res.text}")
```

## Testing

Run the unit tests with:

```bash
python -m unittest discover -s tests
```

All tests should pass:

```
$ python -m unittest discover -s tests
....
----------------------------------------------------------------------
Ran 6 tests in 0.12s

OK
```

## Extending the Agent

- **Training** – call `agent.train()` to fine‑tune embeddings on the corpus.
- **Custom tokenizer** – replace `_tokenize` in `src/agent.py` with a more advanced tokenizer.
- **Different similarity** – swap `cosine_similarity` with dot‑product or Euclidean distance.

## License

This project is released under the MIT License.

--- 

**Academic Integrity**  
All code is written from scratch by the student. No external services or pre‑trained models are used. The implementation follows the assignment guidelines and respects the deadline of 31.08.2026.