gateway.proto

syntax = "proto3";

package gateway;

import "changes.proto";
import "items.proto";
import "responses.proto";

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";


// _____/\\\\\\\\\\\____/\\\\\\\\\\\\_____/\\\\\\\\\\\\\___
//  ___/\\\/////////\\\_\/\\\////////\\\__\/\\\/////////\\\_
//   __\//\\\______\///__\/\\\______\//\\\_\/\\\_______\/\\\_
//    ___\////\\\_________\/\\\_______\/\\\_\/\\\\\\\\\\\\\/__
//     ______\////\\\______\/\\\_______\/\\\_\/\\\/////////____
//      _________\////\\\___\/\\\_______\/\\\_\/\\\_____________
//       __/\\\______\//\\\__\/\\\_______/\\\__\/\\\_____________
//        _\///\\\\\\\\\\\/___\/\\\\\\\\\\\\/___\/\\\_____________
//         ___\///////////_____\////////////_____\///______________
option go_package = "github.com/overmindtech/sdp-go;sdp";

// A union of all request made to the gateway.
message GatewayRequest {
    oneof request_type {
        // Adds a new query for items to the session, starting it immediately
        Query query = 1;
        // Cancel a running query
        CancelQuery cancelQuery = 3;
        // Undo the specified query, if it was the last query received by the gateway. This removes it and all of its effects from the session
        UndoQuery undoQuery = 4;

        // TODO: implement
        // // Exclude an item from the results
        // Reference excludeItem = 5;
        // // Remove an item from the list of exclusions
        // Reference includeItem = 6;

        // Expand all linked items for the given item
        Expand expand = 7;
        // Undo the specified item expansion
        UndoExpand undoExpand = 8;
        // TODO: CancelExpand?

        // store the current session state as snapshot
        StoreSnapshot storeSnapshot = 10;
        // load a snapshot into the current state
        LoadSnapshot loadSnapshot = 11;
        // TODO: implement?
        // // cancel the loading of a snapshot
        // CancelLoadSnapshot cancelLoadSnapshot = ??;
        // // undo the loading of a snapshot
        // UndoLoadSnapshot undoLoadSnapshot = ??;

        // store the current set of queries as bookmarks
        StoreBookmark storeBookmark = 14;
        // load and execute a bookmark into the current state
        LoadBookmark loadBookmark = 15;

        // // cancel the loading of a Bookmark
        // CancelLoadBookmark cancelLoadBookmark = ??;
        // // undo the loading of a Bookmark
        // UndoLoadBookmark undoLoadBookmark = ??;
        ChatMessage chatMessage = 16;
    }

    optional google.protobuf.Duration minStatusInterval = 2; // Minimum time between status updates. Setting this value too low can result in too many status messages
}

// The gateway will always respond with this type of message,
// however the purpose of it is purely as a wrapper to the many different types
// of messages that the gateway can send
message GatewayResponse {
    oneof response_type {
        Item newItem = 2; // A new item that has been discovered
        Edge newEdge = 3; // A new edge between two items

        GatewayRequestStatus status = 4; // Status of the overall request
        string error = 5; // An error that means the request couldn't be executed

        QueryError queryError = 6; // A new error that was encountered as part of a query

        Reference deleteItem = 7; // An item that should be deleted from local state
        Edge deleteEdge = 8; // An edge that should be deleted form local state

        Item updateItem = 9; // An item that has already been sent, but contains new data, it should be updated to reflect this version

        SnapshotStoreResult snapshotStoreResult = 11;
        SnapshotLoadResult snapshotLoadResult = 12;

        BookmarkStoreResult bookmarkStoreResult = 15;
        BookmarkLoadResult bookmarkLoadResult = 16;

        QueryStatus queryStatus = 17; // Status of requested queries

        ChatResponse chatResponse = 18;
        ToolStart toolStart = 19;
        ToolFinish toolFinish = 20;
    }
}

// Contains the status of the gateway request.
message GatewayRequestStatus {
    map<string, ResponderState> responderStates = 1;

    message Summary {
        int32 working = 1;
		int32 stalled = 2;
		int32 complete = 3;
		int32 error = 4;
		int32 cancelled = 5;
		int32 responders = 6;
    }

    Summary summary = 3;

    // Whether all items have finished being processed by the gateway. It is
    // possible for all responders to be complete, but the gateway is still
    // working. A request should only be considered complete when all working ==
    // 0 and postProcessingComplete == true
    bool postProcessingComplete = 4;
}

// Ask the gateway to store the current state as bookmark with the specified details.
// Returns a BookmarkStored message when the bookmark is stored
message StoreBookmark {
    // user supplied name of this bookmark
    string name = 1;
    // user supplied description of this bookmark
    string description = 2;
    // a correlation ID to match up requests and responses. set this to a value unique per connection
    bytes msgID = 3;
    // whether this bookmark should be stored as a system bookmark. System
    // bookmarks are hidden and can only be returned via the UUID, they don't
    // show up in lists
    bool isSystem = 4;
}

// After a bookmark is successfully stored, this reply with the new bookmark's details is sent.
message BookmarkStoreResult {
    bool success = 1;
    string errorMessage = 2;

    // Previously contained the entire bookmark, instead we now only send the ID
    reserved 3;
    // a correlation ID to match up requests and responses. this field returns the contents of the request's msgID
    bytes msgID = 4;
    // UUID of the newly created bookmark
    bytes bookmarkID = 5;
}

// Ask the gateway to load the specified bookmark into the current state.
// Results are streamed to the client in the same way query results are.
message LoadBookmark {
    // unique id of the bookmark to load
    bytes UUID = 1;
    // a correlation ID to match up requests and responses. set this to a value unique per connection
    bytes msgID = 2;
    // set to true to force fetching fresh data
    bool ignoreCache = 3;
    // The time at which the gateway should stop processing the queries spawned by this request
    google.protobuf.Timestamp deadline = 4;
}

message BookmarkLoadResult {
    bool success = 1;
    string errorMessage = 2;

    // UUIDs of all queries that have been started as a result of loading this bookmark
    repeated bytes startedQueryUUIDs = 3;
    // a correlation ID to match up requests and responses. this field returns the contents of the request's msgID
    bytes msgID = 4;
}

// Ask the gateway to store the current state as snapshot with the specified details.
// Returns a SnapshotStored message when the snapshot is stored
message StoreSnapshot {
    // user supplied name of this snapshot
    string name = 1;
    // user supplied description of this snapshot
    string description = 2;
    // a correlation ID to match up requests and responses. set this to a value unique per connection
    bytes msgID = 3;
}

// After a snapshot is successfully stored, this reply with the new snapshot's details is sent.
message SnapshotStoreResult {
    bool success = 1;
    string errorMessage = 2;

    // Previously contained the entire snapshot, instead we now only send the ID
    reserved 3;

    // a correlation ID to match up requests and responses. this field returns the contents of the request's msgID
    bytes msgID = 4;
    bytes snapshotID = 5; // The UUID of the newly stored snapshot
}

// Ask the gateway to load the specified snapshot into the current state.
// Results are streamed to the client in the same way query results are.
message LoadSnapshot {
    // unique id of the snapshot to load
    bytes UUID = 1;
    // a correlation ID to match up requests and responses. set this to a value unique per connection
    bytes msgID = 2;
}

message SnapshotLoadResult {
    bool success = 1;
    string errorMessage = 2;
    // a correlation ID to match up requests and responses. this field returns the contents of the request's msgID
    bytes msgID = 4;
}

message ChatMessage {
    // The message to create
    oneof request_type {
        string text = 1;
        // Cancel the last message sent to openAI, includes the message and tools that were started
        bool cancel = 2;
    }
    // attachments can be added here
}

message ToolMetadata {
    // A unique ID that tracks this tool call and can be used to correlate messages
    string id = 1;
}

message QueryToolStart {
    string type = 1;
    QueryMethod method = 2;
    string query = 3;
    string scope = 4;
}

message QueryToolFinish {
   int32 numItems = 1;
}

message RelationshipToolStart {
    string type = 1;
    string uniqueAttributeValue = 2;
    string scope = 3;
}

message RelationshipToolFinish {
    int32 numItems = 1;
}

message ChangesByReferenceToolStart {
    string type = 1;
    string uniqueAttributeValue = 2;
    string scope = 3;
}

message ChangeByReferenceSummary {
    string title = 1; // from ChangeProperties
    bytes UUID = 2; // from ChangeMetadata
    google.protobuf.Timestamp createdAt = 3; // From ChangeMetadata
    string owner = 4; // From ChangeProperties
    int32 numAffectedItems = 5; // From ChangeMetadata
    changes.ChangeStatus changeStatus = 6; // From ChangeMetadata
}

message ChangesByReferenceToolFinish {
    repeated ChangeByReferenceSummary changeSummaries = 1;
}

message ToolStart {
    ToolMetadata metadata = 1;
    oneof tool_type {
        QueryToolStart query = 2;
        RelationshipToolStart relationship = 3;
        ChangesByReferenceToolStart changesByReference = 4;
    }
}

message ToolFinish {
    ToolMetadata metadata = 1;
    string error = 2;
    oneof tool_type {
        QueryToolFinish query = 3;
        RelationshipToolFinish relationship = 4;
        ChangesByReferenceToolFinish changesByReference = 5;
    }
}

message ChatResponse {
    string text = 1;
    string error = 2;
}