Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Rozwiązywanie zależności

Rozwiązywanie zależności w Aggrega & filar topologii strukturalnej

W architekturze Aggrega zależności topologiczne są jawnie odwzorowywane przez filar schematu uses, aby zachować w pełni nieprzejrzysty ładunek values. Ustalenie, „kto rozmawia z kim”, stanowi szczególne wyzwanie: złożone, wielowęzłowe topologie aplikacji trzeba odwzorować, nie zmuszając programisty do pisania jawnego routingu sieciowego, kolejności wykonania na poziomie orkiestratora ani zależności infrastrukturalnych.

1. Podstawowa filozofia: dlaczego uses?

Blok uses deklaruje zależności między komponentami jako czystą topologię: encja Component A zależy od publicznego kontraktu provides encji Component B, a nie od fizycznego adresu ani szczegółów połączenia encji Component B. Topologia żyje w uses; konfiguracja żyje w values. Rozdzielenie pozwala kompilatorowi jawnie widzieć wszystkie krawędzie między komponentami bez wywnioskowywania ich z zawartości values.

Aggrega rozwiązuje to, podnosząc topologię do rangi pełnoprawnego filaru schematu o nazwie uses.

  • Argument semantycznego proxy: słowo kluczowe uses reprezentuje semantyczną intencję L7. Jeśli agent uses bazę danych, pozostaje to semantycznie prawdziwe, nawet jeśli Platform Ops wstrzyknie między nie przezroczyste siatki proxy Wasm.
  • Neutralność matematyczna: kompilator Go natywnie parsuje strukturę uses, aby narysować graf reprezentacji pośredniej (IR). Nigdy nie próbuje parsować ani odpytywać logiki aplikacji programisty (values).
  • Atomowość encji Feature: filar uses stosuje się identycznie do Components i Features (w tym Features dla poświadczeń). Pozwala to proxy sidecar (encji Feature) lub pobieraczowi poświadczeń samodzielnie deklarować własne zależności sieciowe bez zaśmiecania konfiguracji nadrzędnej encji Component.

2. Mechanika ujednoliconego kontraktu schematu

Aby wyodrębnić instrukcje operacyjne bez parsowania ładunku aplikacji, system opiera się na ścisłych deklaracjach JSON Schema 2020-12, które rządzą jawnie rozdzielonymi strukturami YAML.

Domena 2: schemat dzielony (usesSchema i schema) Aby katalog platformy nie rozpadł się na niemożliwe do zarządzania pliki schematów, Aggrega korzysta z silnika schematu dzielonego. Natywny YAML usesSchema ściśle definiuje i waliduje topologię, natomiast schema: (JSON Schema 2020-12 — zazwyczaj tworzony w skróconej, zwartej formie) waliduje zawartość filarów values i infra oraz deklaruje kształt filaru provides. Pola values tworzone przez programistę i infra ustawiane przez operatora są sprawdzane względem zadeklarowanych typów; podschemat provides deklaruje nazwy kluczy i typy kontraktu przekazywanego dalej, który wytwarza Recipe, a kompilator sprawdza, czy każda referencja inject wskazuje zadeklarowany klucz provides — jednak same wytworzone wartości provides trafiają dalej jako nieprzezroczyste ciągi znaków, które kompilator przekazuje bez interpretacji, a nie jako wartości, których typy sprawdza, ponieważ rdzeń nie interpretuje znaczenia przekazywanej wartości. To w usesSchema gniazdo jest deklarowane, a jego zadeklarowanie nadaje mu kontrakt. Gniazdo zadeklarowane przez encję katalogu niesie ograniczenia tej encji: selektor określający, do jakich celów może prowadzić, listę dozwolonych inject oraz definiowane dla każdej krawędzi valueSchema / infraSchema. Wewnątrz usesSchema architekci platformy używają pola selector: — odczytywanego jako ciąg zapisany przez architekta, a nie kopiowanego do żadnego generowanego schematu — a natywny silnik selektorów w Go ewaluuje je, egzekwując bezpieczeństwo typów między węzłami dla zadeklarowanych gniazd. Dzięki temu, jeśli gniazdo wymaga bazy danych, programista nie może podłączyć do niego serwera webowego.

Selektor podlega swojej gramatyce w chwili ewaluacji, czyli raz dla każdej krawędzi poprowadzonej przez gniazdo. Selektor, którego silnik nie potrafi odczytać jako jednej z sześciu form wymagania — pusty wymóg pozostawiony przez zbędny przecinek, klucz zawierający biały znak lub jeden ze znaków, którymi gramatyka rozróżnia swoje formy (=, !, (, ) i przecinek), albo zbiór bez nawiasu zamykającego — zatrzymuje kompilację na tej krawędzi, wskazując wymaganie, zamiast zostać odczytanym jako inny selektor. Ta ścisłość utrzymuje uczciwość kontroli: odczytany pobłażliwie !tier=frontend, napisany po to, by wykluczyć frontendy, wymagałby jedynie, by żadna etykieta nie nazywała się tier=frontend, i każdy cel — łącznie z frontendami — by przeszedł. Ta sama gramatyka rządzi selektorami gniazd załączników i appliesTo encji Feature; gramatyka selektorów wymienia każdą formę i każdą odmowę. Kompilacja nigdy nie ewaluuje gniazda, przez które nie poprowadzono żadnej krawędzi, dlatego aggrega validate — dla całego katalogu albo dla encji Component lub Feature deklarującej gniazdo — odczytuje selektor każdego zadeklarowanego gniazda i już na tym etapie odrzuca nieprawidłowy, z tym samym kodem i tymi samymi słowami, których używa kompilacja prowadząca krawędź przez to gniazdo.

Zadeklarowanie gniazda nie jest jednak jedynym sposobem poprowadzenia krawędzi. Autor encji Aggregate może wskazać na własnym komponencie gniazdo, którego encja katalogu nie deklaruje — również na typie komponentu, który w ogóle nie deklaruje usesSchema — i krawędź zostanie zbudowana. Katalog, który nie deklaruje wpisu dla danego gniazda, nie przewidział połączenia, co nie jest tym samym co jego zakazanie, a topologia aplikacji należy do programisty. Takie gniazdo nazywa się ad hoc, a jego koszt to dokładnie to, co daje deklaracja: nie ma wpisu w katalogu, więc nie ma selektora ani kontraktu dla krawędzi, a bezpieczeństwo typów między węzłami nie ma czego ewaluować. To, co krawędź może przenosić, pozostaje bez zmian — każdy klucz, który wstrzykuje, nadal musi wskazywać klucz zadeklarowany w provides celu, a cel nadal musi istnieć. Każda krawędź w wyemitowanym grafie zapisuje, który to z dwóch przypadków, więc konsument nigdy nie musi zgadywać; zobacz governance-and-compliance, aby dowiedzieć się, jak operator całkowicie zakazuje gniazd ad hoc.

Dwie powierzchnie celowo nie są otwarte w ten sposób, ponieważ nie tworzą topologii aplikacji. uses załącznika encji Feature może wskazywać tylko gniazdo zadeklarowane przez dołączoną encję Feature, a uses dla krawędzi w encji Release może wskazywać tylko gniazdo, które encja katalogu komponentu konsumującego deklaruje w swoim usesSchema, nigdy gniazdo utworzone ad hoc przez encję Aggregate — operator konfiguruje i łączy w obrębie architektury, a encja Feature uczestniczy w topologii, którą deklaruje jej własna encja katalogu. Deklarowanie gniazda w katalogu pozostaje też lepszą drogą i tak właśnie postępuje katalog biblioteki standardowej: gniazdo ad hoc jest furtką, a nie nowym ustawieniem domyślnym.

Domena 1: doświadczenie programisty (polimorfizm) Programiści piszą uses: na tym samym poziomie co values: i features:. Aby zapewnić UX bez tarcia, schemat natywnie obsługuje polimorfizm:

  • Tablice ciągów: używane do prostych logicznych odwołań do komponentów (np. tools: ["search-api"]), gdy wystarcza standardowy routing.
  • Mapy obiektów: używane, gdy wymagane są ścisłe kontrakty dostarczania (np. databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }).
  • Brak symboli wieloznacznych: nie istnieje forma z symbolem wieloznacznym, co zapobiega „zależnościom-widmom” i nieautoryzowanemu automatycznemu łączeniu: każdy wpis wskazuje jeden komponent, więc ["*"] zatrzymuje kompilację jako cel, który nie istnieje — żadna nazwa komponentu nie może zawierać *.

Domena 3: rzeczywistość Ops (normalizacja) Aby szablony Go pozostały przewidywalne, kompilator Go normalizuje polimorficzne dane wejściowe uses. Tablice logicznych odwołań do komponentów są przekształcane w standardowe obiekty, zanim trafią do ścisłego, płaskiego słownika znanego jako .context.uses.


3. Przykłady od początku do końca

Dwa poniższe przykłady pokazują dwie odrębne właściwości jawnego filaru topologii: przykład A dowodzi, czy połączenie jest autoryzowane (bezpieczeństwo typów między węzłami), a przykład B dowodzi, jak dane połączenia są fizycznie dostarczane (polimorfizm & normalizacja).

Przykład A: walidacja topologiczna i bezpieczeństwo typów między węzłami

Ten scenariusz pokazuje, jak selektor zadeklarowanego gniazda wykrywa, że agent AI ma połączyć się z bazą danych pozbawioną wymaganych etykiet zgodności, i zatrzymuje kompilację. Kompilator ewaluuje selektor etykiet napisany przez architekta względem etykiet celu jako ciągi znaków; nie interpretuje znaczenia etykiety i nie uczestniczy w tym żadna wtyczka polityki.

1. Biblioteka standardowa (ujednolicone schema: w katalogu) Architekt platformy definiuje strukturę schematu, natywnie oddzielając logikę kognitywną od celów topologicznych.

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. Intencja programisty (encja Aggregate) Programista wyraźnie oddziela to, co agent robi (values), od tego, z czym agent się łączy (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. Wykonanie kompilatora i walidacja topologiczna

  1. Walidacja lokalna: kompilator Go podczas rozwiązywania ocenia cały obiekt względem rozwiązanego JSON Schema. Sprawdza bazowe etykiety katalogowe my_secure_vector_db. Gdyby bazie danych brakowało etykiety restricted, kompilator natychmiast zatrzymałby kompilację z naruszeniem bezpieczeństwa typów.
  2. Rysowanie grafu: podczas budowania topologii kompilator Go całkowicie ignoruje treść walidowaną schematem. Odczytuje uses.datastores.finance_memory.target natywnie z YAML i rysuje jawną krawędź w grafie IR.

Przykład B: polimorfizm i znormalizowane .context.uses

Ten scenariusz pokazuje, jak kompilator obsługuje zarówno narzędzie AI typu czarna skrzynka (przekazane jako tablica), jak i starszą relacyjną bazę danych (wymagającą mapy z kontraktem inject).

1. Katalog (domena 2): deklaracja schema: Architekt dopuszcza polimorficzne tablice dla narzędzi, ale wymaga ścisłych obiektów dla baz danych.

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. Intencja programisty (domena 1): encja Aggregate Programista używa prostej tablicy dla narzędzia i jawnej mapy dla bazy danych.

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. Rzeczywistość Ops (domena 3): encja Recipe Kompilator Go normalizuje polimorfizm. Ops otrzymuje płaski, przewidywalny słownik .context.uses. Wystarczy iterować po potoku .context.inject w odpowiednich sekcjach szablonu.

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 }}