Answer Session

APIs

API Key type: read_api_key. Safe to expose to the public.

OramaCore is an answer engine. You can ask questions about any document in your collection, and OramaCore will return the most relevant documents that answer your question.

OramaCore can also come up with a plan to answer your question, by executing a series of steps that will lead to the most correct answer.

At the time of writing, OramaCore supports answer sessions through the SDKs only.

Creating an Answer Session

To create an answer session, you can use the following API:

import { CollectionManager } from '@orama/core'
 
const collection = new CollectionManager({
  url: 'http://localhost:8080',
  collectionID: '<COLLECTION_ID>',
  readAPIKey: '<read_api_key>',
})
 
const answerSession = collection.createAnswerSession()

You can optionally pass a configuration object to the createAnswerSession method. The configuration object can contain the following fields:

import { CollectionManager } from '@orama/core'
 
const collection = new CollectionManager({
  url: 'http://localhost:8080',
  collectionID: '<COLLECTION_ID>',
  readAPIKey: '<read_api_key>',
})
 
const answerSession = collection.createAnswerSession({
    initialMessages: [
        { role: 'user', content: 'How do I install OramaCore?' },
        { role: 'assistant', content: 'You can install OramaCore by pulling the oramasearch/oramacore:latest Docker image' }
    ],
    LLMConfig: {
      provider: 'openai',
      model: 'gpt-4o'
    },
    events: {
        onStateChange(state) {
            console.log('State changed:', state)
        }
    }
})

The initialMessages field is an array of messages that will be sent to the answer session as soon as it is created. This is useful if you are resuming a conversation, or if you want to provide some context to the answer session.

The LLMConfig allows you to specify a remote LLM to invoke for this particular answer session. It depends on the OramaCore configuration.

The events field is an object that can contain the following event handlers:

onStateChange(state): Called whenever the state of the answer session changes. The state object contains the current state of the answer session.
More events to be added soon.

The onStateChange is especially important, and we will provide more information in the next section.

The `onStateChange` Event

The onStateChange event is called whenever the state of the answer session changes. The state object contains the current state of the answer session.

The state is an array of interactions, where each interaction looks like this:

type PlanAction = {
  step: string
  description: string
}
 
type Interaction<D = AnyObject> = {
  id: string
  query: string
  response: string
  sources: Nullable<D>
  loading: boolean
  planned: boolean
  plan: Nullable<PlanAction[]>
  aborted: boolean
  error: boolean
  errorMessage: Nullable<string>
}

Let's see what each field means:

Field	Description	Type	Example
`id`	The CUID of the interaction.	`string`	`bqrziu882rfx33n6cnk69ya7`
`query`	The query that was sent to OramaCore.	`string`	`How do I install OramaCore?`
`response`	The response from OramaCore.	`string`	`You can install OramaCore by pulling the oramasearch/oramacore:latest Docker image`
`sources`	The sources that were used to generate the response.	`object`	`[ { id: '123', score: 0.8, document: { ... } } ]`
`loading`	Whether the interaction is loading.	`boolean`	`false`
`planned`	Whether the interaction was planned.	`boolean`	`false`
`plan`	The plan of actions that OramaCore will take to answer the question. Generated by Party Planner.	`object`	`[ { step: 'OPTIMIZE_QUERY', description: 'Write an optimized OramaCore query for the user input' } ]`
`error`	Whether the interaction has an error.	`boolean`	`false`
`errorMessage`	The error message, if any.	`string`	`The document could not be found`
`aborted`	Whether the interaction was aborted.	`boolean`	`false`

Every single time that any of the fields in the interaction changes, the onStateChange event will be called with the new state.

This will allow you to build a real-time chat interface, where you can show the user's messages, the assistant's responses, and the plan of actions that OramaCore will take to answer the question.

We'll see some examples in the next sections.

Performing an Answer Session

Once you have created an answer session, you can start sending messages to it using either the answer or the answerStream methods.

As the name suggests, the answerStream method will return a single string containing the answer to your question. The answerStream method will return a stream of messages, allowing you to build a real-time chat interface.

Let's see how they work.

answer:

import { CollectionManager } from '@orama/core'
 
const collection = new CollectionManager({
  url: 'http://localhost:8080',
  collectionID: '<COLLECTION_ID>',
  readAPIKey: '<read_api_key>',
})
 
const answerSession = collection.createAnswerSession()
 
// Get a single planned answer
const answer = await answerSession.answer('How do I install OramaCore?')
 
console.log(answer)
// Output: You can install OramaCore by pulling the oramasearch/oramacore:latest Docker image

answerStream:

import { CollectionManager } from '@orama/core'
 
const collection = new CollectionManager({
  url: 'http://localhost:8080',
  collectionID: '<COLLECTION_ID>',
  readAPIKey: '<read_api_key>',
})
 
const answerSession = collection.createAnswerSession()
 
// Get a single planned answer
const answer = await answerSession.answerStream('How do I install OramaCore?')
 
for await (const message of answer) {
  console.log(message)
}
 
// Output:
// You can
// install Orama
// Core by
// pulling the oramasearch/
// oramacore:latest Docker
// image

Getting all conversation messages

When performing an answer session, you can retrieve all the messages exchanged by accessing the messages field in the answerSession object:

import { CollectionManager } from '@orama/core'
 
const collection = new CollectionManager({
  url: 'http://localhost:8080',
  collectionID: '<COLLECTION_ID>',
  readAPIKey: '<read_api_key>',
})
 
const answerSession = collection.createAnswerSession()
 
const answer = await answerSession.answer('How do I install OramaCore?')
 
const allMessages = answerSession.messages
 
console.log(allMessages)
// Output:
// [ 
//   { role: 'user', content: 'How do I install OramaCore?' },
//   { role: 'assistant', content: 'You can install OramaCore by pulling the oramasearch/oramacore:latest Docker image' }
// ]

Listening to state changes

As mentioned before, you can listen to state changes in the answer session by passing an events object to the createAnswerSession method.

The onStateChange event will be called every time the state of the answer session changes. This will allow you to build a real-time chat interface, where you can show the user's messages, the assistant's responses, and the plan of actions that OramaCore will take to answer the question.

Let's see an example:

import { CollectionManager } from '@orama/core'
 
const collection = new CollectionManager({
  url: 'http://localhost:8080',
  collectionID: '<COLLECTION_ID>',
  readAPIKey: '<read_api_key>',
})
 
const answerSession = collection.createAnswerSession({
    events: {
        onStateChange(state) {
            console.log(state)
        }
    }
})
 
const answer = await answerSession.answer('How do I install OramaCore?')