# Custom Search Agent – DeepAgents from Scratch

This repository contains a minimal implementation of a **deep search agent** that:

* Generates deterministic mock search results.
* Creates *virtual files* in memory during execution.
* Exports those virtual files to a specified directory on disk.

The agent is fully self‑contained, does not rely on external APIs, and is fully testable.

## Project Structure

```
.
├── src
│   ├── agent.py      # Core agent implementation
│   └── run.py        # CLI entry point
├── tests
│   └── test_agent.py # Unit tests
├── requirements.txt
└── README.md
```

## Installation

```bash
# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate

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

## Usage

### Command‑line

```bash
python -m src.run --query "python" --output "./search_results"
```

This will:

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 -m unittest discover -s tests
```

All tests should pass, confirming that:

* The agent initializes correctly.
* Search results are deterministic.
* Virtual files are created during search.
* Export writes the correct files to disk.

## Extending the Agent

The `CustomSearchAgent` inherits from `DeepAgent`.  To add real search logic:

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.

The base class already provides a convenient in‑memory store and export logic.

## License

This project is released under the MIT License.