Перейти к содержанию

Миграция с 0.3 на 0.6

Версия 0.6 сохраняет публичные API 0.3 и добавляет capability-клиенты, управляемые host-приложением scopes и опциональные интеграции. Существующее приложение можно обновить без новых обязательных зависимостей и переноса данных.

Безопасная последовательность обновления

  1. Зафиксируйте protoprompt==0.6.* и проверьте приложение с теми же extras, которые использовались в 0.3. У core по-прежнему нет обязательных сторонних зависимостей.
  2. Старые composite-клиенты продолжают работать через LLMClientProtocol. В новом коде используйте ChatClientProtocol или EmbeddingClientProtocol, если нужна только одна возможность.
  3. Создавайте MemoryScope на доверенной границе host-приложения. Пустой scope сохраняет прежнюю физическую раскладку; модель не должна выбирать tenant, user или thread.
  4. Подключайте по одной интеграции через её extra и запускайте contract suite. Предыдущая реализация должна оставаться доступной через конфигурацию.
  5. Для постоянного backend создайте версионированную схему или индекс, выполните backfill и сравнение чтений и только затем переключайте трафик. Setup и migrations явные и никогда не запускаются при импорте пакета.

Extra [chroma] теперь устанавливает ChromaDB >=1.5,<2, чтобы Python 3.13 получал поддерживаемые бинарные зависимости. Конструктор и методы ChromaStore не изменились. Перед первым открытием постоянного каталога новым движком сделайте резервную копию; откат восстанавливает её и ранее зафиксированную версию пакета.

Интеграции с данными

  • Для PostgreSQL/pgvector, Elasticsearch и OpenSearch используйте новую таблицу или индекс для backfill и shadow reads. Старое хранилище оставьте read-only до окончания окна отката.
  • Qdrant больше не пересоздаёт collection при несовпадении размерности embeddings. Создайте версионированную collection и перенесите данные явно; откат выбирает предыдущую collection без потери данных.
  • Redis хранит cache и временное состояние. При откате его ключи можно удалить и восстановить из авторитетного хранилища.
  • AWS и GCP secret stores используют непрозрачные имена ресурсов и версионные envelopes. Копируйте секреты по scope, проверяйте чтение через SecretAccess, а зашифрованный SQLite vault держите read-only в течение окна отката.
  • При смене document reader переиндексируйте документы в новую collection, чтобы результат старого parser оставался доступен.

Connectivity и провайдеры

MCP, OpenAI Agents, LangGraph, Telegram, FastAPI и provider adapters — это опциональные границы вокруг того же memory service. Размещайте их за существующей аутентификацией, выводите scope из доверенных claims, включайте canary-трафиком и для отката убирайте route или adapter. Импорт не изменяет legacy-хранилище.

Откат

Остановите запись в новый backend, переключите конфигурацию на прежний adapter или индекс и установите ранее зафиксированную версию пакета. Не делайте разрушительный downgrade общей схемы. Сохраняйте старые данные и credentials, пока метрики приложения и recall не будут стабильны всё согласованное окно.

Политика удаления и deprecation

У официальной интеграции есть владелец в группе сопровождающих репозитория. Перед удалением adapter помечается deprecated в документации и changelog минимум на один minor-релиз; удаление обычно выполняется только в следующем major. Небезопасное поведение может быть отключено раньше, но в том же релизе должны быть описаны миграция и откат.