Контракт коннекторов

Как написать свой коннектор для KnowledgeBase: роли, регистрация через setup, методы источника, извлечения и индекса, части документа и отпечатки. Версия контракта v1.

Коннектор это Python-пакет, который KnowledgeBase загружает в свой процесс. Типы и протоколы лежат в пакете eap-connectors-contract.

Роли

Роль	Что делает	Примеры
data_source	Отдаёт список документов, изменения и сами файлы	Confluence, SMB, файловая система
data_extractor	Превращает байты файла в Markdown	Paleograph
indexer	Индексирует, ищет и удаляет	Hippocampus

Регистрация

from eap_connectors_contract import PluginContext

def setup(ctx: PluginContext) -> None:
    ctx.register_data_source("wiki", WikiFactory)

Фабрика получает (instance_id, settings) и возвращает обработчик. Один пакет может зарегистрировать несколько ролей.

Пакет подключается в конфиге KnowledgeBase:

plugin_packages = ["eap_connector_wiki", "eap_connector_paleograph", "eap_connector_hippocampus"]

[[default.plugins]]
role = "data_source"
type = "wiki"
instance_id = "wiki_main"
extractor_instance_id = "paleograph_default"
indexer_instance_id = "hippocampus_default"

instance_id уникален во всём конфиге. Дубликат остановит запуск.

Источник

capabilities()
list_snapshot(scope, cursor=None) -> (items, next_cursor)
diff(scope, previous_state) -> DiffResult
build_locator(ref) -> Locator
download(locator) -> DownloadResult

Тип	Поля
DocumentRef	external_id, kind, title, format, version_token, extra
DiffResult	plan, next_state, snapshot_complete
DownloadResult	content, filename, content_type

• version_token меняется при любом изменении документа. По нему KnowledgeBase решает, переиндексировать ли.
• snapshot_complete = false означает неполный список. Тогда KnowledgeBase ничего не удаляет из индекса.
• extra это любая JSON-информация: путь, заголовок, ссылка. Индексатор показывает её LLM при заполнении метаданных.
• Locator это непрозрачная строка: по ней коннектор потом скачает оригинал для пользователя.

Части документа

Вложения и картинки статьи не отдельные документы. Положите их в extra["parts"] как список DocumentRef. KnowledgeBase скачает и извлечёт каждую часть и допишет её текст в документ разделом «Вложение». Учитывайте версии частей в version_token документа, иначе изменённое вложение не переиндексирует статью.

Извлечение

capabilities() -> { supported_exts, fingerprints }
submit(file_bytes, filename, content_type, wait=False) -> JobHandle
get_status, wait, get_result_md
extract_to_md(content, filename, timeout) -> str

KnowledgeBase выбирает извлечение по формату файла или по extractor_instance_id источника. Необязательные fingerprints это хэш настроек извлечения на формат: при его смене документы этого формата переиндексируются.

Индекс

submit_index(payload, wait=True)
delete(tenant_id, id_docs)
search, get_document

IndexPayload несёт тенант, экземпляр коннектора, external_id, локатор, формат, текст и source_info. Индекс не вызывает извлечение: всю оркестрацию делает KnowledgeBase.

Разработка

Пока коннектор не опубликован, ставьте его в режиме разработки рядом с KnowledgeBase:

pip install -e ../eap-connectors-contract -e ../eap-connector-wiki

Готовые коннекторы для образца: Маркетплейс.