Creating and Configuring the Omni Copilot

The Omni Copilot can be created and configured through the Omni console, which will be hosted on conva.ai. The console will provide a UI to allow users to:

  • Provide information regarding the details of the app

  • Configure the knowledge-base which would augment the Copilot's internal knowledge

  • Control other behavioral aspects of the Copilot, such as the grounding policy.

While the console would provide a UI for configuring the knowledge-base, the following APIs should provide more context around what goes on under the hood.

Knowledge-base Management APIs

Note: These APIs are under active development and could change

Creates a new knowledge-base configuration for the given copilot-id

POST https://omni.conva.ai/v1/copilots/{copilot_id}/kb

Provides an interface for configuring knowledge-base ingestion that could be used to augment the Omni Copilot's knowledge of the app's filters, sort_keys, FAQs and vocabulary.

Path Parameters

Name
Type
Description

copilot_id*

String

The ID of the copilot received during copilot creation

Headers

Name
Type
Description

api_key*

String

The API key received during copilot creation

Request Body

Name
Type
Description

kb_type*

String

The type of knowledge-base. Should be one of ["filters", "sort_keys", "faqs", "vocabulary"]

ingestion_type*

String

The ingestion mechanism. Presently, the only supported option is "pull", which means that Omni will pull the data from the endpoints you provide and ingest them.

kb_source*

Object

An object describing the knowledge-base source. Properties required in this object are:

"source_type": should be "json"

"source_path": should be a URL from which the knowledge-base data can be pulled using a GET request.

See below for the format in which the knowledge-base data is expected to be returned in, for each knowledge-base type.

refresh_interval

Integer

Number of hours between refreshes. Setting to -1 disables refreshes.

Default value: -1

Returns an object with property kb_id denoting the ID of the created resource.

Updates the knowledge-base configuration for the given copilot-id and kb-id

PUT https://omni.conva.ai/v1/copilots/{copilot_id}/kb/{kb_id}

Path Parameters

Name
Type
Description

copilot_id*

String

The ID of the copilot received during copilot creation

kb_id*

String

The ID of the knowledge-base received during knowledge base creation

Headers

Name
Type
Description

api_key*

String

The API key received during copilot creation

Request Body

Name
Type
Description

ingestion_type*

String

The ingestion mechanism. Presently, the only supported option is "pull", which means that Omni will pull the data from the endpoints you provide and ingest them.

kb_type*

String

The type of knowledge-base. Should be one of ["filters", "sort_keys", "faqs", "vocabulary"]

kb_source*

String

An object describing the knowledge-base source. Properties required in this object are:

"source_type": should be "json"

"source_path": should be a URL from which the knowledge-base data can be pulled using a GET request.

See below for the format in which the knowledge-base data is expected to be returned in, for each knowledge-base type.

refresh_interval

Integer

Number of hours between refreshes. Setting to -1 disables refreshes.

Default value: -1

Deletes the knowledge-base configuration for the given copilot-id and kb-id

DELETE https://omni.conva.ai/v1/copilots/{copilot_id}/kb/{kb_id}

Path Parameters

Name
Type
Description

copilot_id*

String

The ID of the copilot received during copilot creation.

kb_id*

String

The ID of the knowledge-base received during knowledge-base creation

Headers

Name
Type
Description

api_key*

String

The API key received during copilot creation

Returns the status of the knowledge-base ingestion for the given copilot-id and kb-id

GET https://omni.conva.ai/v1/copilots/{copilot_id}/kb/{kb_id}/status

Path Parameters

Name
Type
Description

copilot_id*

String

ID of the copilot received during copilot creation

Query Parameters

Name
Type
Description

kb_id*

String

ID of the knowledge-base received during knowledge-base creation

Headers

Name
Type
Description

api_key*

String

The API key received during copilot creation

Returns an object describing the status of ingestion with the following properties:

status: one of ["success", "failure", "pending"]

reason: reason for failure, if any

last_attempt_timestamp: timestamp of the latest ingestion attempt

next_attempt_timestamp: timestamp at which the next ingestion will be attempted

Knowledge-base Ingestion Format

In order for the Omni Copilot to successfully ingest the various types of knowledge-bases, the knowledge-base source must return raw data in the below formats

Filters

The knowledge-base source for filters should be returned as a JSON array where each object contains the following fields:

  • app_category (required): the name of the category, such as "electronics", "fashion", etc to which the filters belong. If your app only supports a single category, you can use "default" as the category

  • app_brands (optional): the brands of the app that support the given app_category

  • filter_category (required): the category of filters to which this filter set belongs. For example, for filter labels such as "Nike", "Reebok", "Asics", etc, the filter_category would be "brand"

  • filter_labels (required): a list of labels corresponding to the filter_category

  • filter_ids (optional): a list of ids corresponding to the list labels. If this field is provided, the length of this list should be equal to the length of filter_labels and the id at each index should correspond to the label at the same index in filter_labels.

Sample response for "filters":

[{ "app_category": "grocery", "filter_category": "Allergen Info", "filter_labels": ["Gluten Free", "Dairy Free", "Lactose Free", "Contains Nuts"] }]

Sort Keys

The knowledge-base source for sort_keys should be returned as a JSON array where each object contains the following fields:

  • app_category (required): the name of the category, such as "electronics", "fashion", etc to which the filters belong. If your app only supports a single category, you can use "default" as the category

  • app_brands (optional): the brands of the app that support the given app_category

  • sort_labels (required): the list of labels corresponding to the sort keys for the given app_category

Sample response for "sort_keys":

[{ "app_category": "grocery", "sort_labels": ["Relevance", "Popularity", "Price"] }]

FAQs

The knowledge-base source for faqs should be returned as a JSON array where each object contains the following fields:

  • app_category (required): the name of the category, such as "electronics", "fashion", etc to which the filters belong. If your app only supports a single category, you can use "default" as the category

  • app_brands (optional): the brands of the app that support the given app_category

  • sources(required): a list of objects, each of which contains an optional URL pointing to the FAQ source, and a required contents, containing the FAQ contents

Sample response for "faqs":

[{ "app_category": "grocery", "sources": [{"url": "https://foo.bar", "contents": "<FAQ contents>"]}]

Vocabulary

The knowledge-base source for vocabulary should be returned as a JSON array where each object contains the following fields:

  • app_category (required): the name of the category, such as "electronics", "fashion", etc to which the filters belong. If your app only supports a single category, you can use "default" as the category

  • app_brands (optional): the brands of the app that support the given app_category

  • sources(required): a list of objects, each of which contains an optional URL pointing to the vocabulary source, and a required contents, containing the vocabulary contents

Sample response for "vocabulary":

[{ "app_category": "grocery", "sources": [{"url": "https://foo.bar", "contents": "<FAQ contents>"]}]

PreviousIntroduction to CONVA Omni CopilotNextIntegrating the Omni Copilot with your app

Last updated