Знания и онтология¶

Процессы пакета спрашивают базу знаний (recall), пишут в неё (remember) и ведут в ней проекцию дела (memory); наблюдатели интеграций отдают ей снимки внешних систем. Чтобы эти записи были типизированы и проверяемы, пакет объявляет онтологию — виды сущностей и связи между ними — и говорит, на какие онтологии опирается. Статья для автора пакета: как описать онтологию видом KnowledgePack, объявить её в манифесте, включить установкой и не пустить в граф персональные данные. Обоснование — TAI-ADR-0056 (база знаний компании), TAI-ADR-0062 (п.5).

Память доступна пакету только через ядро: запросы процессов, снимки наблюдателей и ctx.knowledge скиллов идут в Control Plane, а он — в память. Прямого обращения к сервису памяти у пакета нет.

Где что лежит¶

Что	Где	Кто задаёт
Онтология пакета	`knowledge-packs/<имя>.yaml`, вид `KnowledgePack`	автор пакета
На какие онтологии опирается пакет	`Package.spec.knowledge: [имя@версия]`	автор пакета
Какие онтологии включены для пространства работы	`Installation.spec.knowledge`	установка — это топология

Онтология пакета — `KnowledgePack`¶

# knowledge-packs/claims.yaml
apiVersion: taimen.ai/v1
kind: KnowledgePack
key: claims
spec:
  name: claims
  version: 1
  description: Claims of customers and their resolution
  extends: ["default@1"]
  kinds:
    - kind: claim
      title: Claim
      naturalKey: "claim:<source>:<id>"
      attributes:
        type: object
        properties:
          subject: {type: string, title: Subject}
          severity: {type: string, enum: [low, medium, high]}
          openedOn: {type: string, format: date}
      searchable: {fields: [subject]}
  relations:
    - relation: filed_by
      title: Filed by
      fromKinds: [claim]
      toKinds: [legal_entity]
      cardinality: one

package-sdk add KnowledgePack claims пишет заготовку с одним видом.

Поле `spec`	Что задаёт
`name`	имя онтологии без префикса, `^[a-z0-9][a-z0-9._-]{0,63}$`; совпадает с `key` объекта (`check`: `knowledge_pack_key`)
`version`	целое от 1. Зарегистрированная версия неизменна: правка описания — новая версия
`scope`	`common` (по умолчанию) — общий реестр; `tenant` — онтология арендатора
`extends`	до 10 онтологий `имя@версия`, на виды которых ссылаются связи и профили этой; базовая не меняется
`kinds[]`	вид: `kind`, `title`, `description`, `naturalKey` (шаблон с плейсхолдерами или JSON Schema строки), `attributes` (JSON Schema), `searchable: {fields}` — атрибуты для поиска по смыслу, `aliases`, `kindAliases`, `idPatterns`
`relations[]`	связь: `relation`, `title`, `fromKinds`, `toKinds`, `temporal` (по умолчанию `true`), `cardinality` (`one` или `many`)
`profiles[]`	атрибуты вида этой или другой онтологии; с `when: {attr, equals}` — только у сущностей, где атрибут равен значению
`expiry[]`	кому (`role`) и за сколько дней (`leadDays`, 1–365) ставить задачу об истечении `validUntil` вида

Полная форма — sdk/package-sdk/schema/v1/knowledge-pack.schema.json.

Сроки действия — по соглашению атрибуты validFrom и validUntil (format: date).
Своё поверх базового. Онтология класса или вертикали добавляет только свои виды и связи, а атрибуты чужого вида описывает профилем, не переобъявляя его. Сущность, которая уже есть в базе, из нового источника сводится с ней по естественному ключу.
extends должна называть онтологию из этого пакета, его requires или онтологию памяти платформы default@1, иначе check — knowledge_extends_unknown. В default@1 уже есть организация (legal_entity), продукт (product), договор (contract), решение (decision) и другие базовые виды — своя онтология ссылается на них, а не переобъявляет. Онтология другого пакета — через его requires.
Одна онтология имя@версия в двух пакетах установки допустима только одинаковой, иначе knowledge_pack_conflict.

Объявить опору пакета¶

Манифест называет онтологии, на которые опираются процессы и правила пакета:

# package.yaml
spec:
  knowledge: ["default@1", "claims@1"]

check собирает виды и связи из memory, recall, remember и контекста шагов процессов пакета и сверяет их с объявленными онтологиями:

Код	Уровень	Когда
`knowledge_undeclared`	предупреждение	процессы обращаются к памяти, а `spec.knowledge` нет
`knowledge_unknown`	ошибка	онтология из `spec.knowledge` не объявлена `KnowledgePack` ни в пакете, ни в его `requires` (кроме `default@1`)
`knowledge_term_unknown`	ошибка	вида или связи процесса нет ни в одной из объявленных онтологий (с их `extends`); предупреждение, если содержимое части онтологий не видно — их `extends` вне пакетов. `default@1` сверяется со снимком, который несёт SDK
`knowledge_extends_unknown`	ошибка	`extends` называет онтологию, которой нет
`knowledge_pack_key`	ошибка	`key` объекта не совпадает со `spec.name`
`knowledge_pack_conflict`	ошибка	та же `имя@версия` в другом пакете с другим содержимым

Связь rel сущностей дела в memory.entities — предикат факта о деле, а не связь онтологии: её check не сверяет.

Регистрация и включение¶

Онтологии — отдельная секция knowledge единого плана установки. Она применяется после каталога и объектов ядра: сначала регистрируются версии, которых на стенде ещё нет, затем пространствам работы включаются наборы:

# packages.yaml — файл установки
apiVersion: taimen.ai/v1
kind: Installation
key: production
spec:
  packages: [claims]
  knowledge:
    - workspace: ${CLAIMS_WORKSPACE_ID}       # корень дерева workspace
      packs: ["default@1", "claims@1"]
      strict: true

Шаг	Вызов	Правила
Регистрация версии	`POST /api/v1/knowledge/packs`	общую онтологию регистрирует администратор платформы из `CP_KNOWLEDGE_PACK_ADMINS`, онтологию арендатора (`scope: tenant`) — право `knowledge.packs.manage`; владельца-namespace подставляет ядро. `plan` читает версию со стенда: нет её — регистрация в плане; есть, но виды или связи в пакете другие — план не строится: «поднимите version»
Включение	`PUT /api/v1/workspaces/{id}/knowledge-packs`	право `workspaces.manage`, только на корне дерева workspace (`422 workspace_not_root`), только закреплённые ссылки `имя@версия` (`422 pack_version_required`)

Запрос включения заменяет набор целиком. Перечисляйте в packs всё, что нужно пространству, включая default@1. Несколько записей для одного workspace сливаются в один набор.
plan показывает итоговый набор рядом с текущим (сейчас: …) и не включает пространство, где набор и строгость уже такие.
strict: true — строгий режим памяти: записи вне видов включённых онтологий отвергаются, а не принимаются как есть. Строгость, заданная хоть в одной записи workspace, действует на весь его набор.
Онтология арендатора включается ссылкой tenant:<имя>@<версия> и видна только в namespace арендатора и деревьях под ним.
Включаемая онтология, которой нет в пакетах установки, должна уже быть на стенде: check предупреждает о такой.

Как пакет пользуется знаниями¶

Кто	Как	Статья
Процесс	`memory` (проекция дела), шаги `recall` и `remember`, контекст шагов, регламенты	Процессы и база знаний
Наблюдатель	`ctx.snapshot(Snapshot(source, snapshot_id, entities, relations, pack, scope))` — снимок внешней системы, ядро сверяет его с графом	Интеграции
Скилл	`ctx.knowledge.recall`, `query`, `preview` и `apply` со `stateToken`, `document`	Скиллы пакета

Снимок и запись идут от имени агента или личности процесса: им нужно право observations.write, а наблюдателю со снимками — workspace в разделе work описания.

Шаблоны загрузки¶

Таблицы, через которые люди загружают записи вида, не пишутся руками: генератор строит их из JSON Schema атрибутов вида. Поэтому описание вида — это и шаблон:

title и description свойства — заголовок и подсказка колонки;
type, format, enum — проверка значения, required — обязательность;
колонки ключа — из плейсхолдеров naturalKey, колонки связей — из связей, у которых вид стоит в fromKinds.

Форма уточнения подачи шаблона (заголовки, порядок, подсказки, примеры, дополнительные запрещённые колонки) — sdk/package-sdk/schema/v1/knowledge-template.schema.json; колонок, которых нет в схеме вида, уточнение не добавляет.

Персональные данные¶

Атрибут с персональными данными физического лица допустим только с пометкой x-personal-data: allowed; такие значения не попадают в промпты ИИ.
Шаблоны загрузки запрещают колонки с персональными данными (ФИО, паспорт, СНИЛС, дата рождения, адрес, телефон, e-mail) и то, что пакет добавил в forbiddenColumns.
ctx.llm скиллов заменяет персональные данные в промпте маркером [ПДн:вид] до вызова модели.
Проектируйте онтологию так, чтобы человек был ролью или организацией, а не сущностью с персональными данными: связь «обращение подал» ведёт к юрлицу, а не к контактному лицу.

Типичные проблемы¶

Симптом	Причина и решение
`plan`: «онтология … уже зарегистрирована, а kinds в пакете другие — … поднимите version»	правка видов или связей онтологии без новой `version`
`403` на регистрации общей онтологии	применяющий не в `CP_KNOWLEDGE_PACK_ADMINS` — зарегистрировать от администратора платформы или сделать онтологию арендатора (`scope: tenant`)
`422 workspace_not_root`	`Installation.spec.knowledge` называет не корень дерева workspace
после включения пропали виды другой онтологии	набор заменяется целиком — в `packs` не перечислили её
`check`: `knowledge_term_unknown`	процесс обращается к виду или связи, которых нет в `spec.knowledge` — добавить онтологию или поправить вид
запись в память отвергнута в строгом режиме	вид записи не входит во включённые онтологии