Protocol Documentation

Table of Contents

dss/GenAI-Service/proto/genai.proto

Top

GenAIServiceV1

GenAIServiceV1 is a service that provides various endpoints for managing AI services.

HTTP bindings

Method Name Method Route Body Response
CreateProject POST /v1/project CreateProjectRequest AIProject
DeleteProject DELETE /v1/project/{project_name} DeleteProjectRequest DeleteProjectResponse
GetAllProjectNames GET /v1/all_project_names .google.protobuf.Empty GenAIProjectNames
GetProjectByName GET /v1/project_by_name/{project_name} GetProjectByNameRequest AIProject
GetAllProjects GET /v1/all_projects .google.protobuf.Empty GenAIProjects
CreateGraphAnalytics POST /v1/graphanalytics CreateEntityRequest CreateServiceResponse
CreateGraphRag POST /v1/graphrag CreateEntityRequest CreateServiceResponse
CreateGraphRagImporter POST /v1/graphragimporter CreateEntityRequest CreateServiceResponse
CreateGraphRagRetriever POST /v1/graphragretriever CreateEntityRequest CreateServiceResponse
CreateMigrateX POST /v1/migratex CreateEntityRequest CreateServiceResponse
CreateMLFlow POST /v1/mlflow CreateEntityRequest CreateServiceResponse
CreateMLFlowRegistry POST /v1/mlflowregistry CreateEntityRequest CreateServiceResponse
CreateNotebook POST /v1/notebook CreateEntityRequest CreateServiceResponse
CreateVirtualGraph POST /v1/virtualgraph CreateEntityRequest CreateServiceResponse
CreateLlmHost POST /v1/llmhost CreateEntityRequest CreateServiceResponse
CreateGenericService POST /v1/service CreateGenericRequest CreateServiceResponse
DeleteService DELETE /v1/service/{service_id} DeleteServiceRequest DeleteServiceResponse
CheckServiceStatus GET /v1/service/{service_id} CheckStatusRequest CheckStatusResponse
HealthCheck GET /v1/health HealthCheckRequest HealthCheckResponse
ListServices POST /v1/list_services ListServicesRequest ListServicesResponse

CreateProject

Creates a new AI project and manages it in the metadata store

Input Body: CreateProjectRequest
Output: AIProject

DeleteProject

Deletes an AI project by its ID. Note that deleting a project will NOT delete the services associated with it.

This endpoint is used to delete the project metadata only from the metadata store.

Input Body: DeleteProjectRequest
Output: DeleteProjectResponse

GetAllProjectNames

Gets all AI project names. This endpoint is used to get the list of all project names.

Input Body: .google.protobuf.Empty
Output: GenAIProjectNames

GetProjectByName

Gets an AI project by its name. This endpoint is used to get the project metadata by its name.

Input Body: GetProjectByNameRequest
Output: AIProject

GetAllProjects

Input Body: .google.protobuf.Empty
Output: GenAIProjects

CreateGraphAnalytics

Input Body: CreateEntityRequest
Output: CreateServiceResponse

CreateGraphRag

This service requires access to a Large Language Model (LLM) provider and an ArangoDB instance.

The GraphRag service facilitates the retrieval of information from ArangoDB using natural language queries instead of AQL.

Input Body: CreateEntityRequest
Output: CreateServiceResponse

CreateGraphRagImporter

GraphRagImporter is a service that facilitates the import of text data into

ArangoDB by creating a Knowledge Graph (KG) of the entities inside the data.

This data is used by another service to answer natural language queries.

Input Body: CreateEntityRequest
Output: CreateServiceResponse

CreateGraphRagRetriever

GraphRagRetriever is a service that facilitates the retrieval of information from

ArangoDB using natural language queries instead of AQL.

This service requires access to a Large Language Model (LLM) provider and an ArangoDB instance.

It is different than GraphRag as it requires the import of text data into ArangoDB first using

the GraphRagImporter service.

Input Body: CreateEntityRequest
Output: CreateServiceResponse

CreateMigrateX

MigrateX is a service that facilitates for database migration to ArangoDB.

Input Body: CreateEntityRequest
Output: CreateServiceResponse

CreateMLFlow

arangodb-mlflow is a service that provides an interface to MLflow server

for managing machine learning experiments and models.

This service needs to connect to a backend storage service for storing the artifacts.

Input Body: CreateEntityRequest
Output: CreateServiceResponse

CreateMLFlowRegistry

The artifacts of the MLflow service are stored in a registry.

This service provides a registry for storing machine learning artifacts.

Input Body: CreateEntityRequest
Output: CreateServiceResponse

CreateNotebook

The notebook service provides a Jupyter notebook interface for running Python code on devstack

Input Body: CreateEntityRequest
Output: CreateServiceResponse

CreateVirtualGraph

Input Body: CreateEntityRequest
Output: CreateServiceResponse

CreateLlmHost

This service allows hosting private Large Language Models (LLMs)

using Triton Inference Server.

LLM Host service needs access to the MLFlow service to download the model from there.

Input Body: CreateEntityRequest
Output: CreateServiceResponse

CreateGenericService

This endpoint can be used to install any service that has a chart image

available and where dedicated API is not yet provided.

Attention: Ensure that all required parameters by the service are provided.

See the CreateGenericRequest message for more details.

Input Body: CreateGenericRequest
Output: CreateServiceResponse

DeleteService

Deletes a service by service_id.

HTTP DELETE /v1/service/{service_id}, where service_id is the unique identifier of the service.

Note that service_id is sent as a path parameter and not in the request body.

Input Body: DeleteServiceRequest
Output: DeleteServiceResponse

CheckServiceStatus

Checks the status of a service by service_id.

Note that service_id is sent as a path parameter and not in the request body.

Input Body: CheckStatusRequest
Output: CheckStatusResponse

HealthCheck

Performs a health check on the gen-ai service.

Input Body: HealthCheckRequest
Output: HealthCheckResponse

ListServices

Lists all installed and deployed services.

Input Body: ListServicesRequest
Output: ListServicesResponse

AIProject

FieldTypeLabelDescription
project_name string

Unique project name, guaranteed in the gen-ai service upon project creation.

project_type string

project_metadata GraphRAGProjectMetaData optional

project metadata object. Initially empty by default.

project_description string optional


AIService

Represents an AI service.

This object contains the name of the service, the external URL of the service,

the type of the service, the description of the service, the parameters of the service,

the status of the service, and the version of the service.

FieldTypeLabelDescription
service_id string

The name of the service, e.g. "graphrag-importer-12345".

service_url string

The external URL of the service.

service_type string

The type of the service, e.g. "importer", "retriever".

description string

The description of the service, provided by the user at installation time.

service_parameters AIService.ServiceParametersEntry repeated

status AIServiceStatus

The status of the service, e.g. "loading", "finished", "failed". Updated by the service itself.

service_version string optional

The version of the service, e.g. "0.0.1-c12345".


AIService.ServiceParametersEntry

FieldTypeLabelDescription
key string

value string


AIServiceStatus

Represents the status of an AI service.

This object contains the status of the service, the progress of the service,

and an optional message from the service.

FieldTypeLabelDescription
status string

progress float

message string optional


CheckStatusRequest

Represents a request to check the status of a service by its ID.

FieldTypeLabelDescription
service_id string

ID of the service to check the status of.


CheckStatusResponse

Represents a response containing the status information of a service.

FieldTypeLabelDescription
service_info ServiceInfo

Status information of the service.


CreateEntityRequest

Represents a request to create an entity with required parameters for the service and labels.

FieldTypeLabelDescription
env CreateEntityRequest.EnvEntry repeated

Required parameters for the service.

labels CreateEntityRequest.LabelsEntry repeated

Labels for the entity. Used to filter installed charts in ListCharts.


CreateEntityRequest.EnvEntry

FieldTypeLabelDescription
key string

value string


CreateEntityRequest.LabelsEntry

FieldTypeLabelDescription
key string

value string


CreateGenericRequest

Represents a request to create a generic service with a specified name, required parameters for the service, and labels.

FieldTypeLabelDescription
service_name string

Service name must match the name of the service in the helm chart.

env CreateGenericRequest.EnvEntry repeated

Required parameters for the service.

labels CreateGenericRequest.LabelsEntry repeated

Labels for the entity. Used to filter installed charts in ListCharts.


CreateGenericRequest.EnvEntry

FieldTypeLabelDescription
key string

value string


CreateGenericRequest.LabelsEntry

FieldTypeLabelDescription
key string

value string


CreateProjectRequest

Request message for creating a new AI project

FieldTypeLabelDescription
project_name string

Name of the project to create, provided by the user at creation time.

project_type string

Type of the project (e.g., "graphrag", "analytics"), provided by the user at creation time in the first iteration.

project_description string optional

Optional description, provided by the user at creation time.


CreateServiceResponse

Represents a response containing information about a created service.

FieldTypeLabelDescription
service_info ServiceInfo

Information about the created service.


DeleteProjectRequest

Request message for deleting an AI project by its name

FieldTypeLabelDescription
project_name string


DeleteProjectResponse

Response message for deleting an AI project by its name

FieldTypeLabelDescription
message string

Message indicating the result of the deletion.

deleted_project AIProject optional

Optional: return the deleted project info.


DeleteServiceRequest

Represents a request to delete a service by its identifier.

FieldTypeLabelDescription
service_id string

ID of the service to delete.


DeleteServiceResponse

Represents a response containing information about a deleted service.

FieldTypeLabelDescription
service_info ServiceInfo

Information about the deleted service.


GenAIProjectNames

Represents a list of created GenAI project names.

This object contains only the unique project names.

The actual project objects are stored in the metadata store and can be retrieved

using the GetProject method.

FieldTypeLabelDescription
project_names string repeated


GenAIProjects

Represents a list of created GenAI projects.

This object contains the actual project objects.

The projects are stored in the metadata store and can be retrieved

using the GetProjectByName method.

FieldTypeLabelDescription
projects GenAIProjects.ProjectsEntry repeated


GenAIProjects.ProjectsEntry

FieldTypeLabelDescription
key string

value AIProject


GetProjectByNameRequest

Request message for getting an AI project by its name

FieldTypeLabelDescription
project_name string


GraphRAGProjectMetaData

FieldTypeLabelDescription
importer_services AIService repeated

Importer services associated with the project.

retriever_services AIService repeated

Retriever services associated with the project.

knowledge_graph KGMetadata

Knowledge graph associated with the project.

last_modified_timestamp google.protobuf.Timestamp

The timestamp of the last modification of the project metadata.


HealthCheckRequest

Represents a request to perform a health check.

HealthCheckResponse

Represents a response containing the status of a health check.

FieldTypeLabelDescription
status string

Status of the health check, e.g., "OK" or "BAD".

message string optional

Optional additional details, e.g., "Deployed".


KGMetadata

Represents the metadata of the knowledge graph associated with the project.

This object contains the name of the knowledge graph and its properties.

The properties are key-value pairs that can be used to store additional information about the knowledge graph.

FieldTypeLabelDescription
kg_name string

kg_properties KGMetadata.KgPropertiesEntry repeated


KGMetadata.KgPropertiesEntry

FieldTypeLabelDescription
key string

value string


ListServicesRequest

Represents a request to list installed services.

`options` parameter provides a way to set the selecting options.

FieldTypeLabelDescription
options ListServicesRequestOptions optional


ListServicesRequestOptions

Represents label selectors for the list request

options object for now contains only the selectors map,

which is key-value pairs of services labels.

services will be filteres based on these labels upon listing.

labels here are the ones provided by the user at installation time

under `labels` parameter of CreateEntityRequest or CreateGenericRequest.

FieldTypeLabelDescription
selectors ListServicesRequestOptions.SelectorsEntry repeated

selectors work in AND logic, which means it matches all provided labels. e.g. {"environment": "dev", "dbversion": "latest"} will match services that have both values.


ListServicesRequestOptions.SelectorsEntry

FieldTypeLabelDescription
key string

value string


ListServicesResponse

Represents a response containing a list of all installed services.

FieldTypeLabelDescription
services ServiceInfo repeated

List of all installed services


ServiceInfo

Contains information about a service, including its ID, description, status, and namespace.

FieldTypeLabelDescription
service_id string

Unique identifier of the service, generated during installation by combining the service name with a unique five-character identifier.

description string

Description of the service.

status string

Current status of the service.

namespace string

Namespace in which the service is running.

values bytes

Values used to install the service.


Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)