Advanced Reasoning

APIs

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

OramaCore has a built-in Advanced Reasoning feature, that may be used to perform a bit more advanced tasks.

When performing an Answer Session, OramaCore will:

Get the query from the user.
Optimize it to perform the best possible search on your data.
Determine what kind of search is best (full-text, hybrid, vector).
Perform the search.
Rank the results.
Return the results to the user in prose.

With Advanced Reasoning, OramaCore takes a step forward and tries to understand the user's query in a more advanced way.

Under the hood, it uses a built-in library called Party Planner.

Party Planner will generate an action plan based on the user query, then will execute each step of the plan to get to the best possible answer.

Party Planner by Example

Let's see a couple of examples:

Example 1: Debugging errors in code

Let's make a trivial example. When asking OramaCore to help you debug an error in your code, you may say something like:

I have the following JavaScript code that crashes:
 
```
import { OramaCoreManager } from '@orama/core'
 
const orama = new OramaCoreManager({
  url: 'http://localhost:8080',
  masterAPIKey: '<master-api-key>'
})
 
const newCollection = await orama.createCollection({
  id: 'products',
  writeAPIKey: 'my-write-api-key',
  readAPIKey: 'my-read-api-key'
})
```
 
The error message is:
 
```plaintext
Cannot find module '@orama/core'
```
 
What's wrong with my code?

OramaCore may determine that in order to help you, it needs to:

Describe the input code in natural language
Generate one or more search queries based on the natural language description
Determine what kind of search is best (full-text, hybrid, vector)
Perform the search
Rank the results
Return the results to the user in prose

As you can imagine, this will lead to a much better answer than just performing raw search on the input query, which contains a lot of information that may not be relevant to the information retrieval process.

Example 2: Debugging a complex issue

Let's make a more complex example. When asking OramaCore to help you debug a complex issue, you may say something like:

Can you help me create a new collection in OramaCore with a multilingual embeddings model?

OramaCore may determine that in order to help you, it needs to:

Generate two optimized queries:
1. how to create a new collection
2. supported multilingual embeddings models
For each query, determine what kind of search is best (full-text, hybrid, vector)
Perform the search
Rank the results
Generate the code snippet
Return the results to the user in prose

In the example above, OramaCore takes a slightly different route from the previous example, determining that it will also need to generate some code, validate it, and then send it to the user.

Advanced Reasoning APIs

Using Advanced Reasoning with OramaCore is not very different from performing Answer Sessions.

First of all, you have a to create a new answer session:

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

Just like any Answer Session, you can pass an optional configuration object to the createAnswerSession method:

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' }
    ],
    events: {
        onStateChange(state) {
            console.log('State changed:', state)
        }
    }
})

You can read more about events and state structure here.

Performing an Advanced Reasoning Answer Session

Performing Advanced Reasoning Answer Sessions is very similar to performing regular Answer Sessions:

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 advanced reasoning answer
const answer = await answerSession.reason({
    query: 'How do I install OramaCore?'
})
 
console.log(answer)
// Output: You can install OramaCore by pulling the oramasearch/oramacore:latest Docker image [...]

You can also stream the incoming tokens from the answer session:

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.reasonStream({
    query: '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
// [...]

Just like with a plain Answer Session, you will always have access to the state of the session via hooks:

const answerSession = collection.createAnswerSession({
    events: {
        onStateChange(state) {
            console.log(state)
        }
    }
})

Or by calling .state:

const state = answerSession.state()

In the example above, the console will log the following events:

First state change: a new interaction in the state. OramaCore generates an unique interaction ID and adds the user query to it.

[
    {
        "id": "bqrziu882rfx33n6cnk69ya7",
        "query": "How do I install OramaCore?",
        "response": "", // The response will be empty until OramaCore generates it
        "sources": null, // The sources will be null until OramaCore generates them
        "loading": true, // The loading flag will be true until the full response is generated
        "planned": true, // 'planned' is set to true since we're using getPlannedAnswer
        "plan": null, // The plan will be null until OramaCore generates it
        "aborted": false,
        "error": false,
        "errorMessage": null
    }
]

Second state change: OramaCore comes up with a plan to answer the question. The plan is added to the current interaction. The plan is generated by Party Planner.

[
    {
        "id": "bqrziu882rfx33n6cnk69ya7",
        "query": "How do I install OramaCore?",
        "response": "", // The response will be empty until OramaCore generates it
        "sources": null, // The sources will be null until OramaCore generates them
        "loading": true, // The loading flag will be true until the full response is generated
        "planned": true, // 'planned' is set to true since we're using getPlannedAnswer
        "plan": [
            { "step": "OPTIMIZE_QUERY", "description": "Write an optimized OramaCore query for the user input" },
            { "step": "PERFORM_ORAMA_SEARCH", "description": "Perform search using the optimized query generated in the previous step" },
            { "step": "GIVE_REPLY", "description": "Reply with your findings on how to install OramaCore" },
            
        ],
        "aborted": false,
        "error": false,
        "errorMessage": null
    }
]

Third state change: OramaCore generates the sources and adds them to the interaction.

[
    {
        "id": "bqrziu882rfx33n6cnk69ya7",
        "query": "How do I install OramaCore?",
        "response": "", // The response will be empty until OramaCore generates it
        "sources": [
            { "id": "123", "score": 0.8, "document": { ... } },
            { "id": "456", "score": 0.6, "document": { ... } }
        ],
        "loading": true, // The loading flag will be true until the full response is generated
        "planned": true, // 'planned' is set to true since we're using getPlannedAnswer
        "plan": [
            { "step": "OPTIMIZE_QUERY", "description": "Write an optimized OramaCore query for the user input" },
            { "step": "PERFORM_ORAMA_SEARCH", "description": "Perform search using the optimized query generated in the previous step" },
            { "step": "GIVE_REPLY", "description": "Reply with your findings on how to install OramaCore" },
            
        ],
        "aborted": false,
        "error": false,
        "errorMessage": null
    }
]

Fourth state chage: Orama generates the first response token:

[
    {
        "id": "bqrziu882rfx33n6cnk69ya7",
        "query": "How do I install OramaCore?",
        "response": "You can ", // <---- This is the first response token
        "sources": [
            { "id": "123", "score": 0.8, "document": { ... } },
            { "id": "456", "score": 0.6, "document": { ... } }
        ],
        "loading": true, // The loading flag will be true until the full response is generated
        "planned": true, // 'planned' is set to true since we're using getPlannedAnswer
        "plan": [
            { "step": "OPTIMIZE_QUERY", "description": "Write an optimized OramaCore query for the user input" },
            { "step": "PERFORM_ORAMA_SEARCH", "description": "Perform search using the optimized query generated in the previous step" },
            { "step": "GIVE_REPLY", "description": "Reply with your findings on how to install OramaCore" },
            
        ],
        "aborted": false,
        "error": false,
        "errorMessage": null
    }
]

Fifth state change: Orama generates the second response token:

[
    {
        "id": "bqrziu882rfx33n6cnk69ya7",
        "query": "How do I install OramaCore?",
        "response": "You can install Orama", // <---- This is the second response token
        "sources": [
            { "id": "123", "score": 0.8, "document": { ... } },
            { "id": "456", "score": 0.6, "document": { ... } }
        ],
        "loading": true, // The loading flag will be true until the full response is generated
        "planned": true, // 'planned' is set to true since we're using getPlannedAnswer
        "plan": [
            { "step": "OPTIMIZE_QUERY", "description": "Write an optimized OramaCore query for the user input" },
            { "step": "PERFORM_ORAMA_SEARCH", "description": "Perform search using the optimized query generated in the previous step" },
            { "step": "GIVE_REPLY", "description": "Reply with your findings on how to install OramaCore" },
            
        ],
        "aborted": false,
        "error": false,
        "errorMessage": null
    }
]

OramaCore will continue to update the state and trigger the onStateChange event until the full response is generated, and the state will look like this:

[
    {
        "id": "bqrziu882rfx33n6cnk69ya7",
        "query": "How do I install OramaCore?",
        "response": "You can install Orama Core by pulling the oramasearch/oramacore:latest Docker image",
        "sources": [
            { "id": "123", "score": 0.8, "document": { ... } },
            { "id": "456", "score": 0.6, "document": { ... } }
        ],
        "loading": false,
        "planned": true,
        "plan": [
            { "step": "OPTIMIZE_QUERY", "description": "Write an optimized OramaCore query for the user input" },
            { "step": "PERFORM_ORAMA_SEARCH", "description": "Perform search using the optimized query generated in the previous step" },
            { "step": "GIVE_REPLY", "description": "Reply with your findings on how to install OramaCore" },
            
        ],
        "aborted": false,
        "error": false,
        "errorMessage": null
    }
]

When performing an answer session, you can ask OramaCore to generate some related queries to your question. This is useful if you want to explore the topic further, or if you want to ask follow-up questions.

OramaCore will use the user input and the context of the conversation to generate some related queries.

to do this, you can configure the answer or answerStream methods as follows:

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.reasonStream({
  query: 'How do I install OramaCore?',
  related: {
    enabled: true, // Enable related queries generation. Default is false
    size: 2, // Number of related queries to generate. Default is 3
    format: 'query' // Wether to generate queries or questions. Default is 'questions'.
  }
})
 
console.log(this.state.at(-1).related)
 
// '"[\"How do I install OramaCore on Windows?\", \"How do I install OramaCore on Mac?\", \"How do I install OramaCore on Linux?\""]'"'

Please note that the generated related queries are in the format of a JSON string. You can parse it using JSON.parse() to get the actual array of queries.

The reason for this is that by streaming the JSON token by token, we can enable more interactive and real-time experiences, such as showing the user the generated queries as they are being generated.