Module ai.wso2.integration
vinoth/ai.wso2.integration
Overview
The ai.wso2.integration module provides a Ballerina ai:KnowledgeBase implementation for retrieving relevant content from a WSO2 Integration knowledge base.
Quickstart
import ballerina/ai; import ballerinax/ai.wso2.integration; integration:CloudKnowledgeBase knowledgeBase = check new ( serviceUrl, {auth: {token: accessToken}} ); ai:QueryMatch[] matches = check knowledgeBase.retrieve("How do I configure the integration?");
The implementation supports retrieval. Ingestion and deletion are not currently supported.
Classes
ai.wso2.integration: CloudKnowledgeBase
Represents a WSO2 Cloud knowledge base for retrieval.
Constructor
Initializes a new KnowledgeBase instance.
init (string serviceUrl, KnowledgeBaseAuthConfig knowledgeBaseAuthConfig, decimal minSimilarityThreshold, string? cohereRerankerApiKey, string? cohereRerankerModel, int rerankerTopN, *ConnectionConfig connectionConfig)- serviceUrl string -
- knowledgeBaseAuthConfig KnowledgeBaseAuthConfig - Authentication configuration for connecting to the knowledge base
- minSimilarityThreshold decimal 0.7 - The minimum similarity score threshold for retrieved chunks (default: 0.0)
- cohereRerankerApiKey string? () - The API key for the Cohere reranker service; omit to disable reranking
- cohereRerankerModel string? () - The Cohere reranker model name to use
- rerankerTopN int 5 - The number of top results to return from the reranker (default: 5)
- connectionConfig *ConnectionConfig - Additional HTTP connection configurations
ingest
Ingestion is not supported.
Return Type
- Error? - An
ai:Errorsince ingestion is not supported by the retrieve API
retrieve
function retrieve(string query, int maxLimit, MetadataFilters? filters) returns QueryMatch[]|ErrorRetrieves relevant chunks for the given query.
Parameters
- query string - The text query to search for
- maxLimit int (default 10) - The maximum number of items to return
- filters MetadataFilters? (default ()) - Optional metadata filters to apply during retrieval
Return Type
- QueryMatch[]|Error - An array of matching chunks with similarity scores, or an
ai:Errorif retrieval fails
deleteByFilter
function deleteByFilter(MetadataFilters filters) returns Error?Deletion is not supported.
Parameters
- filters MetadataFilters - The metadata filters used to identify which chunks to delete
Return Type
- Error? - An
ai:Errorsince deletion is not supported by the retrieve API
Service types
ai.wso2.integration: VoiceService
Represents a service that handles chat messages from a voice connection.
onChatMessage
function onChatMessage(ChatMessage message) returns string|errorHandles a single chat message and returns the reply to send back to the caller.
If this returns an error, the error is logged and the connection is closed with a
websocket:InternalServerError close frame carrying a generic reason. The error's message
and details are not sent to the client, so it is safe to return errors containing internal
information here.
Parameters
- message ChatMessage - The chat message to handle
Listeners
ai.wso2.integration: CloudVoiceListener
A CloudVoiceListener for handling voice agent connections over WebSocket.
Constructor
Initializes the listener.
init (int|Listener listenOn, *ListenerConfiguration config)- config *ListenerConfiguration - Configurations for the cloud voice service listener. Ignored
if
listenOnis an existingwebsocket:Listener
attach
function attach(VoiceService svc, string[]|string? name) returns error?Attaches a service to the listener.
Parameters
- svc VoiceService - The service that answers chat requests
Return Type
- error? - An
errorif the service is already attached, or if the underlying listener rejected the attach
detach
function detach(VoiceService svc) returns error?Detaches a service from the listener.
Parameters
- svc VoiceService - The service to detach
Return Type
- error? - An
errorif the service was never attached, or if the underlying listener rejected the detach
'start
function 'start() returns error?Starts the listener.
Return Type
- error? - An
errorif the listener could not be started
gracefulStop
function gracefulStop() returns error?Stops the listener, serving already-accepted requests first.
Return Type
- error? - An
errorif the listener could not be stopped
immediateStop
function immediateStop() returns error?Stops the listener immediately.
Return Type
- error? - An
errorif the listener could not be stopped
Records
ai.wso2.integration: ChatMessage
Represents a message of a user.
Fields
- sessionId string - Identifies the user's session. Stable across the turns of one connection, so it can be used directly as an agent memory key
- message string - The latest user utterance.
ai.wso2.integration: KnowledgeBaseAuthConfig
Configuration for connecting to a WSO2 Cloud knowledge base.
Fields
- auth BearerTokenConfig|OAuth2ClientCredentialsGrantConfig - Authentication configuration: either bearer token or OAuth2 client credentials
- timeout? decimal - The HTTP client timeout in seconds (optional)
ai.wso2.integration: ListenerConfiguration
Provides a set of configurations for voice service of voice listener
Fields
- Fields Included from *ListenerConfiguration
- host string
- http1Settings ListenerHttp1Settings
- secureSocket ListenerSecureSocket
- timeout decimal
- server string|()
- webSocketCompressionEnabled boolean
- requestLimits RequestLimitConfigs
Errors
ai.wso2.integration: Error
Defines the common error type for the module.