BAIConnection

Identità

Namespace: B.BAI
Assembly: BFramework
Tipo: class, IDisposable

Scopo

Costruttori

BAIConnection()
BAIConnection(string url)
BAIConnection(BAIConnectionSettings settings)
BAIConnection(eBAITipoProvider TipoProvider)
BAIConnection(eBAITipoProvider TipoProvider, string url)
BAIConnection(IBAIProvider provider)

Proprietà principali

Proprietà	Tipo	Significato
`Settings`	`BAIConnectionSettings`	Configurazione della connessione.
`GenerationSettings`	`BAIGenerationSettings`	Parametri applicati automaticamente alle richieste.
`Timeout`	`TimeSpan?`	Timeout per singola operazione; `null` non impone un timeout BAI.
`IsNothing`	`bool`	Istanza non utilizzabile, in particolare dopo `Dispose`.
`IsConnected`	`bool`	Stato della connessione.
`ConnectedUrl`	`string`	Endpoint effettivamente connesso.
`Models`	`List<BAIModel>`	Modelli recuperati dal provider.
`ActiveModel`	`BAIModel?`	Modello risolto da `ConnectAsync`.
`Messages`	`BAIMessages`	Conversazione; espone anche `Rules` e `Context`.
`Functions`	`List<BAIFunction>`	Funzioni disponibili al modello.
`History`	`List<BAIHistoryItem>`	Cronologia delle operazioni.
`Log`	`BLogText`	Log operativo.
`ExceptionList`	`List<Exception>`	Errori raccolti senza usarli come normale controllo di flusso verso il chiamante.

La connection sceglie il provider nel costruttore. Se occorre cambiarlo, creare una nuova BAIConnection con TipoProvider o con un'implementazione IBAIProvider.

Connessione e modelli

Task<bool> ConnectAsync(CancellationToken cancellationToken = default)
void Disconnect()
Task<List<BAIModel>> GetModelsAsync(CancellationToken cancellationToken = default)
Task<List<double>> GetEmbeddingAsync(string Text, CancellationToken CancToken = default)
void Dispose()

Conversazione

Task<BAIResponse> SendAsync(eSendOption option = eSendOption.All, CancellationToken cancellationToken = default)
IAsyncEnumerable<BAIStreamChunk> SendStreamingAsync(eSendOption option = eSendOption.All, CancellationToken cancellationToken = default)

Questi metodi utilizzano Messages. Quando l'operazione termina con successo, la risposta Assistant completa viene aggiunta una sola volta alla conversazione.

Quando Functions contiene elementi, SendStreamingAsync utilizza il Function Calling realmente streaming. I chunk testuali e di thinking vengono restituiti man mano che arrivano; le eventuali function call vengono rilevate, eseguite e reinviate al provider, quindi lo streaming prosegue.

Le API conversazionali disponibili sono SendAsync e SendStreamingAsync. Lo Structured Output è esposto dagli overload generic ExecuteAsync<T> e ExecuteSingleAsync<T>.

connection.Messages.Add("Domanda 1");
BAIResponse response = await connection.SendAsync();

Dopo l'invio, Messages contiene sia la domanda User sia la risposta Assistant.

Invio stateless

Task<BAIResponse> SendSingleAsync(BAIMessage message, eSendOption option = eSendOption.All, CancellationToken cancellationToken = default)
IAsyncEnumerable<BAIStreamChunk> SendSingleStreamingAsync(BAIMessage message, eSendOption option = eSendOption.All, CancellationToken cancellationToken = default)

Le chiamate single non aggiungono né il messaggio inviato né la risposta a Messages.

Le varianti SendSingleStreamingAsync supportano lo stesso ciclo Function Calling streaming di SendStreamingAsync, ma rimangono stateless.

Structured Output tipizzato

Task<BTypeResult<T>> ExecuteAsync<T>(eSendOption Option = eSendOption.All, CancellationToken CancToken = default)
Task<BTypeResult<T>> ExecuteSingleAsync<T>(BAIMessage Message, eSendOption Option = eSendOption.All, CancellationToken CancToken = default)

I metodi generic costruiscono lo schema per T, inviano i messaggi scelti e caricano la risposta nel wrapper B-Arts BTypeResult<T> con IsNothing e Value.

Embeddings

Task<List<double>> GetEmbeddingAsync(string text, CancellationToken cancellationToken = default)

Usa Settings.EmbeddingModelName. Ollama, OpenAI e Gemini utilizzano il supporto nativo del provider. Il modello indicato deve supportare realmente gli embeddings: non è sufficiente usare un modello generativo dello stesso provider. Anthropic non espone embeddings nativi nella relativa implementazione BAI: il metodo registra l'errore secondo le convenzioni della connection e restituisce una lista vuota.

connection.Settings.EmbeddingModelName = "nomic-embed-text";
List<double> embedding = await connection.GetEmbeddingAsync("testo da rappresentare");

Gestione delle collezioni

ClearFunctions(), AddFunction(string, string, Delegate), RemoveFunction(string)
ClearHistory()

Per messaggi, regole e contesto usare rispettivamente Messages, Messages.Rules e Messages.Context.

Timeout e cancellazione

Il CancellationToken viene propagato fino alla richiesta HTTP. Se Timeout è valorizzato, BAI combina cancellazione esplicita e timeout per la singola operazione. Cancellazioni ed errori vengono riportati attraverso risultato, ExceptionList e Log secondo il contratto del metodo.

Nel Function Calling streaming timeout e token coprono l'intera operazione, comprese le richieste successive necessarie per consegnare i risultati delle funzioni. L'ultimo elemento restituito ha sempre Done = true e contiene la BAIResponse finale in Response.