vania-janet/multiturn-rag-retrieval-data huggingface dataset:
sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required grant_type="urn:ibm:params:oauth:grant-type:apikey" apikey="${APIKEY}";
sasl.login.callback.handler.class=com.ibm.eventstreams.oauth.client.IAMOAuthBearerLoginCallbackHandler
sasl.oauthbearer.token.endpoint.url=https://iam.cloud.ibm.com/identity/token
sasl.oauthbearer.jwks.endpoint.url=https://iam.cloud.ibm.com/identity/keys
security.protocol=SASL_SSL
ssl.protocol=TLSv1.2
ssl.enabled.protocols=TLSv1.2
ssl.endpoint.identification.algorithm=HTTPS

The sample code refers to the [Event Streams samples](https://github.com/IBM/eventstreams-samples).

For other Kafka client libaries, refer to their documentation about how to implement OAUTHBEARER support. For example:.



* [sarama](https://github.com/Shopify/sarama): an implementation of AccessTokenProvider interface is required.
* [librdkafka](https://github.com/confluentinc/librdkafka): an implementation of oauthbearer_token_refresh_cb callback is required.



For information about how to generate an IBM Cloud IAM token by using an API key, see IBM Cloud® Identity and Access Management's [document](https://cloud.ibm.com/docs/account?topic=account-iamtoken_from_apikey).
Using the REST producer API 

The REST producer API is available as part of the Event Streams Standard and Enterprise plans only.

Event Streams provides a REST API to help connect your existing systems to your Event Streams Kafka cluster. By using the API, you can integrate Event Streams with any system that supports RESTful APIs.

The REST producer API is a scalable REST interface for producing messages to Event Streams over a secure HTTP endpoint. Send event data to Event Streams, use Kafka technology to handle data feeds, and take advantage of Event Streams features to manage your data.

Use the API to connect existing systems to Event Streams. Create produce requests from your systems into Event Streams, including specifying the message key, headers, and the topics that you want to write messages to.



 Accessing the REST producer API 

You must retrieve the URL and credential details that are needed to connect to the API from a Service credentials object or service key for the service instance. For more information about creating these objects, see [Connecting to Event Streams](https://cloud.ibm.com/docs/EventStreams?topic=EventStreams-connecting).

The URL for the API's endpoint is provided in the kafka_http_url property.





 Authentication 

The supported authentication mechanism is to use a bearer token. To obtain your token by using the IBM Cloud CLI, first log in to IBM Cloud and then run the following command:

ibmcloud iam oauth-tokens

Place this token in the Authorization header of the HTTP request in the form Bearer<token>. Both API key or JWT tokens are supported.





 Producing messages by using the REST producer API 

Use the v2 endpoint of the producer API to send messages of type text, binary, JSON, or avro to topics. With the v2 endpoint you can use the Event Streams schema registry by specifying the schema for the avro data type.

The following code shows an example of sending a message of text type by using curl:

curl -v -X POST 
-H "Authorization: Bearer $token" -H "Content-Type: application/json" -H "Accept: application/json" 
-d '{
To determine whether your implementation uses ping-pong frames, check its list of features. You cannot programmatically determine or manage ping-pong frames.

If your WebSocket stack does not implement ping-pong frames and your are sending long audio files, your connection can experience a read timeout. To avoid such timeouts, continuously stream audio to the service or request interim results from the service. Either approach can ensure that the lack of ping-pong frames does not cause your connection to close.

For more information about ping-pong frames, see [Section 5.5.2 Ping](http://tools.ietf.org/html/rfc6455section-5.5.2) and [Section 5.5.3 Pong](https://tools.ietf.org/html/rfc6455section-5.5.3) of IETF RFC 6455.





 Close a connection 

When the client is done interacting with the service, it can close the WebSocket connection. Once the connection is closed, the client can no longer use it to send requests or to receive results. Close the connection only after the client receives all results for a request. The connection eventually times out and closes if the client does not explicitly close it.

The following snippet of JavaScript code closes an open connection:

websocket.close();







 How the service sends recognition results 

How the service sends speech recognition results to the client depends on whether the client requests interim results. In the JSON response to a request, final results are labeled "final": true, and interim results are labeled "final": false. For more information, see [Interim results](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-interiminterim-results).

In the following examples, the results show the service's response for the same input audio submitted both with and without interim results. The audio speaks the phrase "one two ...pause... three four," with a one-second pause between the words "two" and "three." The pause is long enough to represent separate utterances.
28 January 2019 

New support for IBM Cloud IAM by WebSocket interface
: The WebSocket interface now supports token-based Identity and Access Management (IAM) authentication from browser-based JavaScript code. The limitation to the contrary has been removed. To establish an authenticated connection with the WebSocket /v1/recognize method:



* If you use IAM authentication, include the access_token query parameter.
* If you use Cloud Foundry service credentials, include the watson-token query parameter.



For more information, see [Open a connection](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-websocketsws-open).





 20 December 2018 

New beta grammars feature for custom language models now available
: The service now supports grammars for speech recognition. Grammars are available as beta functionality for all languages that support language model customization. You can add grammars to a custom language model and use them to restrict the set of phrases that the service can recognize from audio. You can define a grammar in Augmented Backus-Naur Form (ABNF) or XML Form.

The following four methods are available for working with grammars:



* POST /v1/customizations/{customization_id}/grammars/{grammar_name} adds a grammar file to a custom language model.
* GET /v1/customizations/{customization_id}/grammars lists information about all grammars for a custom model.
* GET /v1/customizations/{customization_id}/grammars/{grammar_name} returns information about a specified grammar for a custom model.
* DELETE /v1/customizations/{customization_id}/grammars/{grammar_name} removes an existing grammar from a custom model.



You can use a grammar for speech recognition with the WebSocket and HTTP interfaces. Use the language_customization_id and grammar_name parameters to identify the custom model and the grammar that you want to use. Currently, you can use only a single grammar with a speech recognition request.

For more information about grammars, see the following documentation:
Synthesizing speech with the service 

The Text to Speech service offers an HTTP Representational State Transfer (REST) interface and a WebSocket interface:



* [The HTTP interface](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-usingHTTP) provides both GET and POST versions of the service's /v1/synthesize method. The two versions of the method offer generally equivalent functionality. You pass the text that is to be synthesized as a query parameter with the GET method and as the body of the request with the POST method.
* [The WebSocket interface](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-usingWebSocket) provides a /v1/synthesize method. You pass the text that is to be synthesized over an established WebSocket connection.



With both the HTTP and WebSocket interfaces, you specify the language and voice that are to be used, and the format for the audio that is to be returned.



* For an overview of the features that are available for speech synthesis, see [Using speech synthesis features](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-service-featuresfeatures-synthesis).
* For detailed descriptions and examples of the speech synthesis methods, see the [API & SDK reference](https://cloud.ibm.com/apidocs/text-to-speech).





 Data limits 

The interfaces accept the following maximum amounts of text with a single request:



* The HTTP GET /v1/synthesize method accepts a maximum of 8 KB of input, which includes the input text and the URL and headers.
* The HTTP POST /v1/synthesize method accepts a maximum of 8 KB for the URL and headers, and a maximum of 5 KB for the input text that is sent in the body of the request.
* The WebSocket /v1/synthesize method accepts a maximum of 5 KB of input text.



These limits include all characters of the input, including whitespace.

IBM Cloud
[Redis](https://www.npmjs.com/package/redis) to connect to the Redis instance and read/write data.
3. [kafkajs](https://www.npmjs.com/package/kafkajs) to connect to the Event Streams instance.
4. [Express](https://expressjs.com/) to enable a simple web server that allows interaction with the data.



There are five main files:



1. server.js: This runs the web server and communicates with Redis. It is getting regular calls from the front end to the /data route. It connects to Redis, downloads an object with the ID and position of every truck and returns that to the front end.
2. index.html: This is the one and only page of the front end application. When it loads, it shows a map of the US from the awesome [Open Street Map](https://www.openstreetmap.org/copyright) service. Then it is on a five-second loop where it makes an HTTP request to the backend (server.js), retrieves all the trucks and their positions and loops through them to plot their latest position on the map. Each truck has a map marker whose lat/long gets updated with every cycle.
3. producer.js: This takes in a location file and a truck_id from the script invocation and then loops through all the data points in the location file. Each data point is turned into a message with the truck ID and lat/long and posted once a second to Event Streams. For added fun, it picks a random starting point along the route and turns around and comes back when it reaches the end of the location file.
4. cloudantConsumer.js: This script creates a trucktracker database in Cloudant if it does not already exist and then polls Event Streams at regular intervals for more data. When data comes in, it gets written in bulk to Cloudant.
5. redisConsumer.js: This script polls Event Streams at regular intervals for data.
The first entry point into the system is through NGINX, an HTTP and reverse proxy server. NGINX is used for SSL termination and forwarding appropriate HTTP calls to the next component.

The OpenWhisk user-facing API is HTTP-based and follows a RESTful design. As a consequence, the command that is sent through the CLI is an HTTP request against the OpenWhisk system. The specific command translates roughly to the following syntax:

POST /api/v1/namespaces/<userNamespace>/actions/myAction
Host: $openwhiskEndpoint

Note the <userNamespace> variable. A user has access to at least one namespace. For simplicity with this example, assume that you own the namespace where myAction is located.





 2. Entering the system: Controller 

NGINX forwards the HTTP request to the Controller, the next component on the path through OpenWhisk. The controller is a Scala-based implementation of the actual REST API (based on Akka and Spray). As such, the controller serves as the interface for everything that you want to do, including create, retrieve, update, and delete requests for your entities in OpenWhisk and the invocation of actions.

When the HTTP request is forwarded, the controller first determines what action that you are trying to take, based on the HTTP method that you used in your HTTP request. In this case, you are issuing a POST request to an existing action, which the controller translates to an invocation of an action.

Given the central role of the controller (hence the name), the following steps all involve the controller, to a certain extent.





 3. Authentication and Authorization: CouchDB 

Now the controller verifies who you are (Authentication) and whether you have the required privileges to do what you want to do with that entity (Authorization). The credentials that are included in the request are verified against the so-called subjects database in a CouchDB instance.

In this case, the controller verifies that you exist in the Functions database and determines whether you have the necessary privilege to invoke the action myAction, which is assumed to be an action in a namespace that you own.
By using this model, a client can obtain an authentication token for communicating directly with the service. The token bypasses the need for a server-side proxy application in IBM Cloud to call the service on the client's behalf. Tokens are the preferred means for clients to interact with the service.

The service continues to support the old programming model that relied on a server-side proxy to relay audio and messages between the client and the service. But the new model is more efficient and provides higher throughput.

New model parameter for speech recognition
: The POST /v1/sessions and POST /v1/recognize methods, along with the WebSocket /v1/recognize method, now support a model query parameter. You use the parameter to specify information about the audio:



* The language: English, Japanese, or Spanish
* The minimum sampling rate: broadband (16 kHz) or narrowband (8 kHz)



For more information, see [Previous-generation languages and models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models).

New inactivity_timeout parameter for speech recognition
: The inactivity_timeout parameter sets the timeout value in seconds after which the service closes the connection if it detects silence (no speech) in streaming mode. By default, the service terminates the session after 30 seconds of silence. The POST /v1/recognize and WebSocket /v1/recognize methods support the parameter. For more information, see [Timeouts](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-inputtimeouts).

New max_alternatives parameter for speech recognition
: The max_alternatives parameter instructs the service to return the n-best alternative hypotheses for the audio transcription. The POST /v1/recognize and WebSocket /v1/recognize methods support the parameter. For more information, see [Maximum alternatives](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-metadatamax-alternatives).

New word_confidence parameter for speech recognition
Webhooks 

A webhook represents a service destination, where an incoming notification can be consumed programmatically. For example, an incoming notification about an event can trigger a webhook destination to a backend microservice to act based on the content of the incoming notification.



  Configuring a webhook destination 

You can configure a webhook destination in the Destinations tab. As part of the configuration, enter the webhook URL, and the REST API verb to be called when the webhook is called. You can also enter authorization headers to the destination webhook. Create a subscription to associate the webhook destination to a topic.





  Webhook signing 

To identify that the incoming notification is coming from IBM Cloud Event Notifications, you can enable webhook signing. If signing is enabled, a public key can be downloaded, and used to decrypt the incoming notification content.





  Webhook retry policy 

When calling a webhook, issues such as network errors and application glitches can cause the requests to fail. A retry is used to provide resiliency to external requests. Attempt to retry the requests in such situations by using the following values:



*  Limit = 60 seconds: total time that the service retries.
*  Step = 5 seconds: after each failure, the service waits 5 seconds before retrying. This delay prevents bombarding of the external services (webhook).



In addition, the following timeout conditions cause the webhook call to fail:



*  A connection timeout of 10 seconds
*  A response timeout of 60 seconds



If a call to the webhook URL fails even after retry attempts, the notification is lost.
Creating custom event provider feeds 

IBM Cloud® Functions supports an open API, where you can expose an event producer service as a feed in a package.



 Feed architecture 

You can create a feed by using one of the three architectural patterns: Hooks, Polling, and Connections.



 Hooks 

With the hooks pattern, a feed is set up by using a webhook that is exposed by another service. In this strategy, a webhook is configured on an external service to POST directly to a URL to fire a trigger. This method is by far the easiest and most attractive option for implementing low-frequency feeds.





 Polling 

With the polling pattern, a Cloud Functions action is arranged to poll an endpoint periodically to fetch new data. This pattern is relatively easy to build, but the frequencies of events are limited by the polling interval.





 Connections 

With the connections pattern, a separate service maintains a persistent connection to a feed source. The connection-based implementation might interact with a service endpoint by using long polling intervals, or to set up a push notification.

For example, the [IBM Cloudant package](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-pkg_cloudant) uses the connections pattern.







 Implementing feed actions 

The feed action accepts the following parameters.



Table 1. Feed action parameters

 Parameter Description 

 lifecycleEvent CREATE, READ, UPDATE, DELETE, PAUSE, or UNPAUSE. 
 triggerName The fully qualified name of the trigger, which contains events that are produced from this feed. 
 authKey The basic authentication credentials of the Cloud Functions user who owns the trigger. 



The feed action can also accept any other parameters that it needs to manage the feed. For example, the IBM Cloudant changes feed action expects to receive parameters that include dbname and username.

When you create a trigger from the CLI with the --feed parameter, the feed action is automatically invoked with the appropriate parameters.

For example, create a mycloudant binding for the cloudant package with a username and password as bound parameters. When the user issues the following command from the CLI:
}
],
"final": true
},
{
"alternatives":
{
"confidence": 0.99,
"transcript": "four five six "
}
],
"final": true
}
]
}
Show more
* For the WebSocket interface, the service sends the same results as the previous example. The response includes a single SpeechRecognitionResults object, the alternatives array has a separate element for each final result, and the response has a single result_index field with a value of 0.

{
"result_index": 0,
"results": [
{
"alternatives":
{
"confidence": 0.99,
"transcript": "one two three "
}
],
"final": true
},
{
"alternatives":
{
"confidence": 0.99,
"transcript": "four five six "
}
],
"final": true
}
]
}
Show more

With the WebSocket interface, responses for interim results contain more JSON objects. For more information about using the WebSocket interface to obtain interim results with previous- and next-generation models, see the following topics:



* [Interim results](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-interiminterim-results)
* [Requesting interim results and low latency](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-interiminterim-low-latency)
* [How the service sends recognition results](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-websocketsws-results)





Silence of 30 seconds in streamed audio can result in an inactivity timeout.
[bufferutil](https://www.npmjs.com/package/bufferutil) bufferutil is what makes ws fast. 
 [canvas](https://www.npmjs.com/package/canvas) A Cairo-backed Canvas implementation for Node.js. 
 [cassandra-driver](https://www.npmjs.com/package/cassandra-driver) DataStax Node.js Driver for Apache Cassandra. 
 [commander](https://www.npmjs.com/package/commander) The complete solution for Node.js command-line interfaces. 
 [composeaddresstranslator](https://www.npmjs.com/package/composeaddresstranslator) Address translator from Compose UI or API for Scylla databases. 
 [consul](https://www.npmjs.com/package/consul) A client for Consul, involving service discovery and configuration. 
 [cookie-parser](https://www.npmjs.com/package/cookie-parser) Parse Cookie header and populate req.cookies with an object keyed by the cookie names. 
 [core-js](https://www.npmjs.com/package/core-js) Modular standard library for JavaScript. 
 [elasticsearch](https://www.npmjs.com/package/elasticsearch) The official low-level Elasticsearch client for Node.js. 
 [errorhandler](https://www.npmjs.com/package/errorhandler) Development-only error handler middleware. 
 [etcd3](https://www.npmjs.com/package/etcd3) A high-quality, production-ready client for the Protocol Buffer-based etcdv3 API. 
 [express](https://www.npmjs.com/package/express) A fast, minimalist web framework for node. 
 [express-session](https://www.npmjs.com/package/express-session) A server-side session data storing module.
curl -X POST --header "Authorization: Bearer {token}" --header "Content-Type: application/json" --header "Accept: audio/ogg;codecs=opus" --data "{"text":"<ibm:prompt id='goodbye'/>"}" "{url}/v1/synthesize?customization_id={customization_id}&voice=en-US_AllisonV3Voice"
* This example calls the GET /v1/synthesize method to synthesize the prompt, which must be URL-encoded:

IBM Cloud

curl -X GET -u apikey:{apikey } --header "Accept: audio/ogg;codecs=opus" "{url}/v1/synthesize?customization_id={customization_id}&voice=en-US_AllisonV3Voice&text=%3Cibm%3Aprompt%20id%3D%22goodbye%22%2F%3E"

IBM Cloud Pak for Data

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: audio/ogg;codecs=opus" "{url}/v1/synthesize?customization_id={customization_id}&voice=en-US_AllisonV3Voice&text=%3Cibm%3Aprompt%20id%3D%22goodbye%22%2F%3E"



The following snippet of JavaScript code uses the [WebSocket interface](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-usingWebSocket) to synthesize the prompt:

var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/synthesize'
+ '?access_token=' + access_token
+ '&customization_id={customization_id}'
+ '&voice=en-US_AllisonV3Voice';
var websocket = new WebSocket(wsURI);