SIGLA: Локальная система памяти для ИИ‑агентов (Windows/Linux/macOS)

SIGLA — это полностью локальная, кроссплатформенная библиотека для быстрого поиска по векторам и долговременной памяти ИИ‑агентов. Ядро состоит из индекса HNSW с надёжным NumPy‑фолбэком и персистентного хранилища на SQLite+FTS5. Все тяжёлые зависимости вынесены в опциональные «extras», поэтому базовая установка лёгкая и работает без интернета и без GPU.

⚡ Быстрый старт

# Установка (минимум)
pip install .

# Опционально: HTTP‑сервер и API
# pip install .[server]

# Векторный индекс (HNSW с фолбэком на NumPy)
python -c "
import numpy as np
from sigla.vector import HnswIndex

# Создаем индекс и добавляем векторы
index = HnswIndex(dim=768)
vectors = np.random.randn(10000, 768).astype(np.float32)
index.add(vectors)

# Поиск ближайших соседей
query = np.random.randn(768).astype(np.float32)
labels, distances = index.search(query, k=10)
print(f'Найдено {len(labels[0])} соседей')
"

📊 Производительность (примечание)

Производительность зависит от данных и окружения. Мы предоставляем тесты и скрипты бенчмарков, но не заявляем фиксированные «x‑раз быстрее» без контекста. Для сравнения используйте benchmarks/ и nightly workflow performance.yml.

🎯 Ключевые возможности

🔥 Производительность и надёжность

• Индекс HNSW (hnswlib) с динамическим ef и поддержкой батч‑поиска
• Фолбэк на чистый NumPy для кроссплатформенности (работает без hnswlib)
• Сохранение/загрузка в сайдкар‑файлы (.hnsw/.bin + .meta) для избежания file‑lock на Windows
• WAL и аккуратная работа с SQLite (WAL, PRAGMA synchronous=NORMAL, wal_checkpoint(TRUNCATE))
• Интеллектуальное кэширование запросов (простые LRU/батч‑кэши)

💾 Персистентность и масштабирование

• SQLite + FTS5 для текстов и метаданных
• Векторный индекс хранится рядом сайдкар‑файлами
• Поддержка удаления элементов и приоритет «точного совпадения» в выдаче
• Возможность заменить эмбеддинги на свои (опционально transformers / sentence-transformers)

🧠 Память агента (AgentMemory)

• observe(text) → id, recall(query, k) → items, feedback(ids, reward_delta)
• Хранение: SQLite+FTS5, поиск: HNSW/NumPy, всё локально
• Высокоуровневый модуль sigla.memory.api и REST‑сервер (FastAPI) sigla.memory.server

🚀 Продвинутое использование

Интеграция в коде (офлайн)

from sigla.memory.api import create_memory, observe_texts, recall
mem = create_memory("./agent_memory.db", dim=384)
ids = observe_texts(mem, ["text 1", "text 2"]) 
items = recall(mem, "query", k=5)

Кэширование запросов (библиотека)

from sigla.cache import CachedIndex

# Оборачиваем индекс с кэшированием
cached_index = CachedIndex(
    base_index, 
    cache_backend="lru",  # или "redis"
    cache_ttl=3600.0,
    max_size=10000
)

# Повторные запросы будут возвращаться из кэша
labels, distances = cached_index.search(query, k=10)

Сохранение/загрузка индекса

index.save("./my.index")   # создаст ./my.index.meta и ./my.index.hnsw|.bin
idx2 = HnswIndex.load("./my.index")

Мониторинг (опционально)

Мониторинг и продвинутые метрики доступны только в виде локального профилирования; сетевые экспортеры и сервисы исключены.

🔧 Автоматическая оптимизация (опционально)

# Оптимизация гиперпараметров на вашем датасете
python -m sigla.auto_optimizer \
    --dataset ./my_vectors.npy \
    --queries ./my_queries.npy \
    --output optimization_results.json

# Бенчмарки
python benchmarks/runner.py --dataset sift --output benchmark_results.json

📈 Профилирование производительности

# Скачивание тестовых датасетов
python scripts/download_bigann.py --dataset sift

# Профилирование узких мест
python -c "
from sigla.profiler import global_profiler
from sigla.vector import HnswIndex
import numpy as np

index = HnswIndex(dim=128)
vectors = np.random.randn(5000, 128).astype(np.float32)
queries = np.random.randn(100, 128).astype(np.float32)

# Профилирование операций
stats = global_profiler.benchmark_index_operations(index, vectors, queries)
report = global_profiler.generate_report()
print('Самая медленная операция:', report['summary']['slowest_operation'])
"

🔄 Production

Горячая перезагрузка и GPU‑ускорение доступны как совместимые слои; по умолчанию библиотека работает полностью на CPU.

Docker контейнер (опционально для упаковки библиотеки)

FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
RUN pip install -e .
# Без открытых портов/серверов — библиотека офлайн

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

# Запуск тестов
pytest -q -s

# Расширенные тесты/интеграционные запускаются в CI (см. Workflows)

# Проверка качества кода
python scripts/verify_done.sh

📚 Архитектура (высокоуровнево)

SIGLA построен по модульному принципу:

• sigla.vector — HNSW/NumPy индексы и роутер; сохранение/загрузка
• sigla.memory.* — модели, хранилище (локальная библиотека без REST)
• sigla.cache — простой кэш запросов и батч‑кэш
• sigla.vector.router — адаптивный роутер (с фолбэком при отсутствии FAISS)
• sigla.faiss_stub — безопасная подмена FAISS для минимальной установки
• sigla.wal — WAL‑обёртка
• sigla.advanced_monitoring / sigla.auto_optimizer — необязательные модули

🤝 Разработка

# Клонирование и установка для разработки
git clone https://github.com/iMAGRAY/70B-1q-to-70B-lang.git
cd 70B-1q-to-70B-lang
pip install -e ".[dev]"

# Запуск автоматической оптимизации
python -m sigla.auto_optimizer --dataset datasets/sift/base_1m.npy --queries datasets/sift/queries.npy

# Мониторинг архитектурного плана
python scripts/render_kanban.py  # генерирует kanban.html

📄 Лицензия

MIT License - см. LICENSE

🔗 Связанные проекты

• FAISS - Baseline для сравнения
• hnswlib - Базовая HNSW реализация
• Prometheus - Мониторинг метрик

---

Готовы начать? Перейдите к разделу Быстрый старт.

---

🧠 Локальная память агента (офлайн)

Быстрый старт (библиотека):

from sigla.memory.api import create_memory, observe_texts, recall, feedback

mem = create_memory("./agent_memory.db", dim=384)  # SQLite+FTS5 + HnswIndex (hnswlib/NumPy)
ids = observe_texts(mem, [
  "машинное обучение и нейронные сети",
  "облачные вычисления AWS и Azure",
  "глубокое обучение для обработки текста",
])

items = recall(mem, "нейронные сети", k=5)
feedback(mem, [ids[0]], reward_delta=1.0)

(HTTP сервер удалён; библиотека работает офлайн через Python API)

Особенности:

• Полностью локально: без внешних сервисов
• Кроссплатформенно: Windows/Linux/macOS
• Хранилище: SQLite + FTS5; векторный поиск: HNSW с фолбэком на NumPy

Установка с «extras»

• .[faiss-cpu] / .[faiss-gpu] — FAISS (по желанию)
• .[llm] — transformers/sentence-transformers