# 🧠 OpenaiSimpleAgents

Асинхронная библиотека для интеграции кратковременной и долговременной памяти в OpenAI-агентов с использованием `ChromaDB`, `SQLite`, и `OpenAI Embedding`.

---

## 📦 Возможности

- 🔄 **Кратковременная память** на основе SQLite (для последних диалогов).
- 📚 **Долговременная память** на основе ChromaDB (для знаний и прошлого опыта).
- 🧱 Поддержка **адаптивного top_k**, TTL, фоновой очистки, и асинхронной защиты.
- 🛠 Интеграция с любой LLM-цепочкой reasoning (`Runner`, `Agent`).
- 🧪 Простота тестирования, dev-зависимости и поддержка `pytest-asyncio`.

---

## 🛠 Установка

```bash
pip install openai-simple-agents
```

Для разработки и тестирования:

```bash
pip install .[dev]
```

---

## 📌 Когда использовать `SimpleAgents`

Эта библиотека предназначена для проектов, где:

- вам нужно хранить и **использовать память** между запросами к агенту;
- агент должен **обучаться на прошлых взаимодействиях** с пользователями;
- необходимо гибкое управление объёмом, сроком хранения и фильтрацией памяти;
- вы хотите **минимизировать запросы к внешним базам** или API;
- вы реализуете собственную LLM-инфраструктуру без LangChain.

---

## 🧠 Архитектура

```text
            +--------------------+
            |    Пользователь    |
            +--------------------+
                     |
                 [ввод текста]
                     v
         +-------------------------+
         |        Agent            |   ← ты вызываешь .message()
         +-------------------------+
           |                  |
        get_memory     record_interaction
           |                  |
     +-----------+     +-----------+
     | ShortMemory|     | LongMemory|
     |  (SQLite)  |     | (ChromaDB)|
     +-----------+     +-----------+
```

---

## ✍️ Пример использования

```python
from SimpleAgents import Agent

agent = Agent(name="doc-bot", openai_api_key="sk-...", ttl_seconds=3600)

async def main():
    response = await agent.message("Где я остановился в прошлый раз?", user_id="user123")
    print(response.final_output)

import asyncio
asyncio.run(main())
```

---

## 🗂 Компоненты

| Класс           | Назначение                                                  |
|----------------|-------------------------------------------------------------|
| `Agent`         | Основной вход, обёртка над reasoning с памятью              |
| `MemoryManager` | Управление слоями памяти и автоочисткой                     |
| `ShortMemory`   | История диалога в SQLite                                    |
| `LongMemory`    | Постоянная память в ChromaDB с поиском по эмбеддингам       |
| `Runner`        | Интерфейс запуска reasoning-цепочек (подключается отдельно) |

---

## 🧪 Тестирование

```bash
pytest
```

Библиотека использует `pytest-asyncio` и `sentence-transformers` (опционально) для моков embedding-функций в тестах.

---

## 📂 Примеры использования

- 🤖 **Персональные помощники**: сохранение воспоминаний о пользователях.
- 🧑‍🏫 **Образовательные агенты**: помнить, что изучал ученик.
- 📈 **Бизнес-боты**: запоминать прошлые обращения клиентов.
- 🕵️‍♂️ **Многоагентные системы**: обмен знанием между агентами через `LongMemory`.

---

## ⚖️ Лицензия

MIT — см. [LICENSE](LICENSE).

---

## ✉️ Автор

**Платановский Дмитрий Алексеевич**  
📧 [platanovskiydmitriy@gmail.com](mailto:platanovskiydmitriy@gmail.com)