Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Розв’язання залежностей

Розв’язання залежностей в Aggrega & стовп структурної топології

В архітектурі Aggrega топологічні залежності явно відображаються через стовп схеми uses, щоб зберегти повністю непрозоре корисне навантаження values. Визначення того, «хто з ким спілкується», становить особливий виклик: складні багатовузлові топології застосунків треба відобразити, не змушуючи розробника писати явну мережеву маршрутизацію, порядок виконання на рівні оркестратора чи інфраструктурні залежності.

1. Базова філософія: чому uses?

Блок uses оголошує залежності між компонентами як чисту топологію: сутність Component A залежить від публічного контракту provides сутності Component B, а не від фізичної адреси чи деталей з’єднання сутності Component B. Топологія живе в uses; конфігурація живе у values. Таке розділення дає компілятору змогу явно бачити всі ребра між компонентами, не виводячи їх із вмісту values.

Aggrega розв’язує це, підносячи топологію до повноправного стовпа схеми під назвою uses.

  • Аргумент семантичного проксі: ключове слово uses представляє семантичний намір рівня L7. Якщо агент uses базу даних, це залишається семантично істинним, навіть якщо Platform Ops вставляє між ними прозорі сітки проксі Wasm.
  • Математична нейтральність: компілятор Go нативно розбирає структуру uses, щоб накреслити граф проміжного представлення (IR). Він ніколи не намагається розбирати чи запитувати логіку застосунку розробника (values).
  • Атомарність сутності Feature: стовп uses однаково застосовується до Components і Features (зокрема до Features для облікових даних). Це дає змогу проксі-sidecar (сутності Feature) чи засобу отримання облікових даних автономно оголошувати власні мережеві залежності, не засмічуючи конфігурацію батьківської сутності Component.

2. Механіка уніфікованого контракту схеми

Щоб видобувати операційні інструкції без розбору корисного навантаження застосунку, система спирається на строгі оголошення JSON Schema 2020-12, які регулюють явно розділені структури YAML.

Домен 2: розділена схема (usesSchema & schema) Щоб каталог платформи не розпався на некеровані файли схем, Aggrega використовує рушій розділеної схеми. Нативний YAML-usesSchema строго визначає й перевіряє топологію, тоді як schema: (JSON Schema 2020-12 — зазвичай записується через компактну скорочену форму) перевіряє вміст стовпів values та infra і оголошує форму стовпа provides. values, які пише розробник, та infra, яку задає оператор, перевіряються на відповідність оголошеним типам; підсхема provides оголошує назви ключів і типи низхідного контракту, який створює сутність Recipe, а компілятор перевіряє, що кожне посилання inject називає оголошений ключ provides, — але самі створені значення provides рухаються далі як непрозорі рядки, які компілятор передає без інтерпретації, а не як значення, чий тип він перевіряє, бо ядро не інтерпретує, що означає передане значення. Саме в usesSchema сокет оголошується, і саме оголошення дає йому контракт. Сокет, який оголошує сутність каталогу, несе обмеження цієї сутності: селектор, що визначає, яких цілей він може досягати, список дозволених inject і valueSchema / infraSchema для кожного ребра. Усередині usesSchema архітектори платформи використовують поле selector: — його читають як рядок, який написав архітектор, і не копіюють у жодну згенеровану схему, — а нативний рушій селекторів Go обчислює його, щоб забезпечити безпеку типів між вузлами для оголошених сокетів. Це гарантує, що коли сокет вимагає базу даних, розробник не зможе під’єднати до нього вебсервер.

Селектор підпорядковується своїй граматиці в момент обчислення, тобто один раз для кожного ребра, проведеного через сокет. Селектор, який рушій не може прочитати як одну з шести своїх форм вимоги, — порожня вимога, залишена зайвою комою, ключ із пробільними символами чи з одним із символів, якими граматика розрізняє свої форми (=, !, (, ) і кома), або множина без закривної дужки, — зупиняє збірку на цьому ребрі, називаючи вимогу, замість того щоб бути прочитаним як інший селектор. Саме ця строгість тримає перевірку чесною: якби його прочитали поблажливо, !tier=frontend, написаний, щоб не допустити фронтенди, вимагав би лише, щоб жодна мітка не називалася tier=frontend, і кожна ціль — зокрема фронтенди — пройшла б. Та сама граматика регулює селектори слотів вкладень і appliesTo сутності Feature; граматика селекторів перелічує кожну форму й кожну відмову. Збірка ніколи не обчислює сокет, через який не проведено жодного ребра, тому aggrega validate — над усім каталогом або над сутністю Component чи Feature, що оголошує сокет, — читає селектор кожного оголошеного сокета й відхиляє некоректний уже на цьому етапі, з тим самим кодом і тими самими словами, що їх використовує збірка, яка проводить ребро через цей сокет.

Проте оголошення сокета — не єдиний спосіб провести ребро. Автор сутності Aggregate може назвати на власному компоненті сокет, якого сутність каталогу не оголошує, — навіть на типі компонента, що взагалі не оголошує usesSchema, — і ребро буде побудовано. Каталог, який не оголошує запису для сокета, не передбачив з’єднання, а це не те саме, що заборонити його, і топологія застосунку належить розробникові. Такий сокет називають ad hoc, і його ціна — рівно те, що дає оголошення: немає запису в каталозі, отже немає ні селектора, ні контракту для ребра, і безпеці типів між вузлами немає чого обчислювати. Те, що ребро може переносити, не змінюється — кожен ключ, який воно вводить, і далі має називати ключ, оголошений у provides цілі, а ціль і далі має існувати. Кожне ребро у виведеному графі фіксує, який із двох випадків воно являє, тож споживачеві ніколи не доводиться вгадувати; див. governance-and-compliance, щоб дізнатися, як оператор повністю забороняє сокети ad hoc.

Дві поверхні навмисно не відкриті в такий спосіб, бо вони не створюють топологію застосунку. uses вкладення сутності Feature може називати лише сокет, який оголошує приєднана сутність Feature, а uses для ребра в сутності Release може називати лише сокет, який сутність каталогу компонента-споживача оголошує у своїй usesSchema, і ніколи не сокет, створений сутністю Aggregate ad hoc, — оператор налаштовує й з’єднує в межах архітектури, а сутність Feature бере участь у топології, яку оголошує її власна сутність каталогу. До того ж оголошення сокета в каталозі залишається кращим шляхом, і саме так робить каталог стандартної бібліотеки: сокет ad hoc — це запасний вихід, а не нова типова поведінка.

Домен 1: досвід розробника (поліморфізм) Розробники пишуть uses: на тому самому рівні, що й values: та features:. Щоб забезпечити UX без тертя, схема нативно підтримує поліморфізм:

  • Масиви рядків: використовуються для простих логічних посилань на компоненти (напр., tools: ["search-api"]), коли достатньо стандартної маршрутизації.
  • Мапи об’єктів: використовуються, коли потрібні строгі контракти доставлення (напр., databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }).
  • Жодних символів підстановки: форми із символом підстановки немає, що запобігає «примарним залежностям» і несанкціонованому автопід’єднанню: кожен запис називає один компонент, тож ["*"] зупиняє збірку як ціль, якої не існує, — жодне ім’я компонента не може містити *.

Домен 3: реальність Ops (нормалізація) Щоб шаблони Go залишалися передбачуваними, компілятор Go нормалізує поліморфні вхідні дані uses. Масиви логічних посилань на компоненти перетворюються на стандартні об’єкти, перш ніж потрапити в строгий плаский словник, відомий як .context.uses.


3. Наскрізні приклади

Два наведені нижче приклади демонструють дві окремі властивості явного стовпа топології: приклад A доводить, чи авторизоване з’єднання (безпека типів між вузлами), а приклад B доводить, як дані з’єднання фізично доставляються (поліморфізм & нормалізація).

Приклад A: топологічна валідація та безпека типів між вузлами

Цей сценарій простежує, як селектор оголошеного сокета виявляє, що агент ШІ збирається під’єднатися до бази даних без потрібних міток відповідності, і зупиняє збірку. Компілятор обчислює написаний архітектором селектор міток щодо міток цілі як рядки; він не інтерпретує значення мітки, і жоден плагін політики в цьому не бере участі.

1. Стандартна бібліотека (уніфікована schema: у каталозі) Архітектор платформи визначає структуру схеми, нативно відокремлюючи когнітивну логіку від топологічних цілей.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/enterprise-agent
version: 1.0.0
labels:
component.aggrega.ai/type: "worker"
spec:
usesSchema:
datastores:
selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
schema:
# 1. The Cognitive Intent
values:
system_prompt: { type: string, required: true }

2. Намір розробника (сутність Aggregate) Розробник чітко відокремлює те, що агент робить (values), від того, до чого агент під’єднується (uses).

components:
my_secure_vector_db:
type: core/qdrant-secure:1.0.0
values:
collection_name: finance_data
auditing_agent:
type: core/enterprise-agent:1.0.0
values:
system_prompt: "You are a financial auditing AI..."
uses:
datastores:
finance_memory: { target: "my_secure_vector_db" }

3. Виконання компілятора та топологічна валідація

  1. Локальна валідація: під час розв’язання компілятор Go перевіряє весь об’єкт на відповідність розв’язаній JSON Schema. Він перевіряє базові мітки каталогу my_secure_vector_db. Якби базі даних бракувало мітки restricted, компілятор негайно зупинив би збірку з порушенням безпеки типів.
  2. Побудова графа: під час побудови топології компілятор Go повністю ігнорує вміст, валідований схемою. Він нативно читає uses.datastores.finance_memory.target з YAML і малює явне ребро в графі IR.

Приклад B: поліморфізм і нормалізований .context.uses

Цей сценарій показує, як компілятор обробляє і інструмент ШІ типу «чорна скринька» (переданий як масив), і застарілу реляційну базу даних (яка потребує мапи з контрактом inject).

1. Каталог (домен 2): оголошення schema: Архітектор дозволяє поліморфні масиви для інструментів, але вимагає строгих об’єктів для баз даних.

spec:
usesSchema:
# Polymorphic Array Socket (No injection needed)
tools:
selector: "tool.aggrega.ai/impact=read-only"
# Strict Map Socket (Requires delivery contract)
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: ["env", "file"]
schema:
values:
system_prompt: { type: string, required: true }

2. Намір розробника (домен 1): сутність Aggregate Розробник використовує простий масив для інструмента і явну мапу для бази даних.

components:
my-agent:
type: core/python-worker:1.0.0
values:
system_prompt: "You are an HR bot."
uses:
# 1. Polymorphic Array: Simple logical component reference
tools:
- "corporate-search-api"
# 2. Strict Map: Dictating the environment variable delivery
databases:
hr_db:
target: corporate-hr-db
inject:
env:
- in: HR_DATABASE_URI # Local env var
from: "host" # Target provides key

3. Реальність Ops (домен 3): сутність Recipe Компілятор Go нормалізує поліморфізм. Ops отримує плаский, передбачуваний словник .context.uses. Достатньо пройти циклом по каналу .context.inject у відповідних розділах шаблону.

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: generic-worker
version: 1.0.0
spec:
capability: helm
implements: core/python-worker:1.0.0
source: "./charts/internal/python-runner"
locals:
primary_compute: worker-container
valuesMapping: |
env:
# Ops uses the pre-resolved inject map, kept apart from values and topology loops
{{- range $key, $value := .context.inject.env }}
- name: {{ $key }}
value: "{{ $value }}"
{{- end }}