Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Risoluzione delle dipendenze

Risoluzione delle dipendenze in Aggrega & il pilastro della topologia strutturale

Nell’architettura Aggrega, le dipendenze topologiche sono mappate esplicitamente tramite il pilastro di schema uses per mantenere un payload values completamente opaco. Risolvere «chi parla con chi» pone una sfida specifica: topologie applicative complesse e a più nodi devono essere mappate senza costringere lo sviluppatore a scrivere instradamenti di rete espliciti, ordini di esecuzione a livello di orchestratore o dipendenze infrastrutturali.

1. La filosofia di fondo: perché uses?

Il blocco uses dichiara le dipendenze tra componenti come pura topologia: il Component A dipende dal contratto pubblico provides del Component B, non dall’indirizzo fisico o dai dettagli di connessione del Component B. La topologia vive in uses; la configurazione vive in values. La separazione permette al compilatore di vedere esplicitamente tutti gli archi tra componenti senza dedurli dal contenuto di values.

Aggrega risolve il problema elevando la topologia a pilastro di schema di prima classe chiamato uses.

  • L’argomento del proxy semantico: la parola chiave uses rappresenta l’intento semantico L7. Se un agente uses un database, ciò resta semanticamente vero anche se Platform Ops inserisce tra loro mesh di proxy Wasm trasparenti.
  • Neutralità matematica: il compilatore Go analizza nativamente la struttura uses per disegnare il grafo della rappresentazione intermedia (IR). Non tenta mai di analizzare o interrogare la logica applicativa dello sviluppatore (values).
  • Atomicità della Feature: il pilastro uses si applica in modo identico ai Components e alle Features (incluse le Features per credenziali). Questo permette a un proxy sidecar (una Feature) o a un recuperatore di credenziali di dichiarare autonomamente le proprie dipendenze di rete senza inquinare la configurazione del Component padre.

2. La meccanica del contratto di schema unificato

Per estrarre istruzioni operative senza analizzare il payload applicativo, il sistema si basa su rigorose dichiarazioni JSON Schema 2020-12 che governano strutture YAML esplicitamente separate.

Dominio 2: lo schema diviso (usesSchema & schema) Per evitare che il catalogo della piattaforma si frammenti in file di schema ingestibili, Aggrega utilizza un motore a schema diviso. Lo usesSchema in YAML nativo definisce e valida rigorosamente la topologia, mentre schema: (JSON Schema 2020-12 — tipicamente scritto tramite l’abbreviazione in forma compatta) valida il contenuto dei pilastri values e infra e dichiara la forma del pilastro provides. I values che scrive uno sviluppatore e l’infra che imposta un operatore vengono verificati rispetto ai tipi dichiarati; il sotto-schema provides dichiara i nomi delle chiavi e i tipi del contratto a valle che una Recipe produce, e il compilatore verifica che ogni riferimento inject nomini una chiave provides dichiarata — ma i valori provides prodotti viaggiano a valle come stringhe opache che il compilatore convoglia senza interpretarle, non come valori di cui verifica il tipo, perché il nucleo non interpreta il significato di un valore convogliato. Lo usesSchema è dove un socket viene dichiarato, ed è la dichiarazione a dargli un contratto. Un socket dichiarato dall’entità di catalogo porta con sé i vincoli di quell’entità: un selettore che indica quali destinazioni può raggiungere, una allowlist inject e valueSchema / infraSchema per arco. All’interno dello usesSchema, gli architetti della piattaforma usano il campo selector: — letto come la stringa che l’architetto ha scritto, non copiato in alcuno schema generato — e il motore di selettori nativo in Go lo valuta per imporre la sicurezza dei tipi tra nodi sui socket dichiarati. Garantisce che, se un socket richiede un database, lo sviluppatore non possa collegarvi un web server.

Il selettore è vincolato alla sua grammatica nel momento in cui viene valutato, cioè una volta per ogni arco collegato attraverso il socket. Un selettore che il motore non riesce a leggere come una delle sue sei forme di requisito — un requisito vuoto lasciato da una virgola di troppo, una chiave che contiene spazi o uno dei caratteri con cui la grammatica distingue le sue forme (=, !, (, ) e la virgola), oppure un insieme senza la parentesi di chiusura — arresta la build su quell’arco, nominando il requisito, invece di essere letto come un altro selettore. È questa rigidità a mantenere onesto il controllo: letto con indulgenza, !tier=frontend, scritto per escludere i frontend, chiederebbe solo che nessuna etichetta sia chiamata tier=frontend, e ogni destinazione — frontend compresi — passerebbe. La stessa grammatica governa i selettori degli slot di allegato e l’appliesTo di una Feature; la grammatica dei selettori elenca ogni forma e ogni rifiuto. Una build non valuta mai un socket attraverso cui non è collegato alcun arco, quindi aggrega validate — sull’intero catalogo, oppure sul Component o sulla Feature che dichiara il socket — legge il selettore di ogni socket dichiarato e già lì rifiuta quello malformato, con lo stesso codice e con le stesse parole di una build che collega il socket.

Dichiarare il socket non è però l’unico modo di tracciare un arco. L’autore di un Aggregate può nominare, sul proprio componente, un socket che l’entità di catalogo non dichiara — anche su un tipo di componente che non dichiara alcuno usesSchema — e l’arco viene costruito. Un catalogo che non dichiara alcuna voce per un socket non ha previsto la connessione, il che non equivale a vietarla, e la topologia dell’applicazione appartiene allo sviluppatore. Un socket di questo tipo si chiama ad-hoc, e ciò che costa è esattamente ciò che la dichiarazione offre: non c’è una voce di catalogo, quindi non c’è un selettore né un contratto per arco, e la sicurezza dei tipi tra nodi non ha nulla da valutare. Ciò che l’arco può trasportare non cambia: ogni chiave che inietta deve comunque nominare una chiave dichiarata dal provides della destinazione, e la destinazione deve comunque esistere. Ogni arco nel grafo emesso registra quale dei due casi è, così un consumatore non deve mai indovinare; vedi governance-and-compliance per sapere come un operatore vieta del tutto i socket ad-hoc.

Due superfici, deliberatamente, non sono aperte in questo modo, perché non scrivono la topologia dell’applicazione. Gli uses di un allegato di Feature possono nominare solo un socket dichiarato dalla Feature associata, e gli uses per arco di una Release possono nominare solo un socket che l’entità di catalogo del componente consumatore dichiara nel proprio usesSchema, mai uno scritto ad hoc dall’Aggregate — un operatore configura e collega all’interno di un’architettura, e una Feature partecipa alla topologia dichiarata dalla propria entità di catalogo. Dichiarare il socket nel catalogo resta inoltre la strada migliore ed è ciò che fa il catalogo della libreria standard: un socket ad-hoc è una via d’uscita, non un nuovo default.

Dominio 1: l’esperienza dello sviluppatore (polimorfismo) Gli sviluppatori scrivono uses: allo stesso livello di values: e features:. Per garantire una UX senza attriti, lo schema supporta nativamente il polimorfismo:

  • Array di stringhe: usati per semplici riferimenti logici a componenti (ad es. tools: ["search-api"]) quando l’instradamento standard è sufficiente.
  • Mappe di oggetti: usate quando sono richiesti contratti di consegna rigorosi (ad es. databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }).
  • Nessun carattere jolly: non esiste una forma con carattere jolly, il che previene le «dipendenze fantasma» e il collegamento automatico non autorizzato: ogni voce nomina un solo componente, quindi ["*"] arresta la build come destinazione inesistente — nessun nome di componente può contenere *.

Dominio 3: la realtà di Ops (normalizzazione) Per mantenere prevedibili i template Go, il compilatore Go normalizza gli input polimorfici di uses. Gli array di riferimenti logici a componenti vengono convertiti in oggetti standard prima di essere passati nel dizionario piatto e rigoroso noto come .context.uses.


3. Esempi end-to-end

I due esempi seguenti mostrano le due distinte proprietà del pilastro esplicito della topologia: l’esempio A dimostra se una connessione è autorizzata (sicurezza dei tipi tra nodi), e l’esempio B dimostra come i dati della connessione vengono consegnati fisicamente (polimorfismo & normalizzazione).

Esempio A: validazione topologica e sicurezza dei tipi tra nodi

Questo scenario mostra come il selettore su un socket dichiarato rileva che un agente AI sta per connettersi a un database privo delle etichette di conformità richieste, e arresta la build. Il compilatore valuta il selettore di etichette scritto dall’architetto rispetto alle etichette della destinazione, come stringhe; non interpreta il significato di un’etichetta, e non è coinvolto alcun plugin di policy.

1. La libreria standard (lo schema: unificato nel catalogo) Il Platform Architect definisce la struttura dello schema, separando nativamente la logica cognitiva dai target topologici.

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. L’intento dello sviluppatore (l’Aggregate) Lo sviluppatore separa nettamente ciò che l’agente fa (values) da ciò a cui l’agente si connette (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. Esecuzione del compilatore e validazione topologica

  1. Validazione locale: il compilatore Go valuta l’intero oggetto rispetto al JSON Schema risolto durante la risoluzione. Controlla le etichette di catalogo sottostanti di my_secure_vector_db. Se il database non avesse l’etichetta restricted, il compilatore arresterebbe immediatamente la build con una violazione della sicurezza dei tipi.
  2. Disegno del grafo: durante la costruzione della topologia, il compilatore Go ignora del tutto il contenuto validato dallo schema. Legge uses.datastores.finance_memory.target nativamente dallo YAML e disegna l’arco esplicito nel grafo IR.

Esempio B: polimorfismo e .context.uses normalizzato

Questo scenario mostra come il compilatore gestisce sia uno strumento AI a scatola nera (passato come array) sia un database relazionale legacy (che richiede una mappa con un contratto inject).

1. Il catalogo (dominio 2): la dichiarazione schema: L’Architect consente array polimorfici per gli strumenti, ma richiede oggetti rigorosi per i database.

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. L’intento dello sviluppatore (dominio 1): l’Aggregate Lo sviluppatore usa un array semplice per lo strumento e una mappa esplicita per il database.

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. La realtà di Ops (dominio 3): la Recipe Il compilatore Go normalizza il polimorfismo. Ops riceve un dizionario .context.uses piatto e prevedibile. Basta iterare sulla pipe .context.inject nelle sezioni pertinenti del template.

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