// Copyright © 2023-2026 Cognizant Technology Solutions Corp, www.cognizant.com.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// END COPYRIGHT

// To obtain information concerning the code generation that is used by this Interface Definition Language
// please see the following:
//
// Go - https://developers.google.com/protocol-buffers/docs/reference/go-generated
// Python - https://developers.google.com/protocol-buffers/docs/reference/python-generated
//
syntax = "proto3";

package dev.cognizant_ai.neuro_san.api.grpc.chat;

option go_package = "github.com/cognizant-ai-lab/neuro_san/internal/gen/dev.cognizant_ai/neuro_san/api/grpc/chat/v1;chat";

import "google/protobuf/struct.proto";
import "neuro_san/api/grpc/mime_data.proto";

message Origin {
    // String name of the originating tool, as per the agent spec.
    string tool = 1 [json_name="tool"];

    // Some tools can be called more than once by one or more different paths.
    // Allow for an instantiation index to distinguish these in the chat stream.
    // Index counting starts at 0.
    int32 instantiation_index = 2 [json_name="instantiation_index"];
}


// A structure for storing chat history for a given node in the graph
// described by the origin.
message ChatHistory {
    repeated Origin origin = 1 [json_name="origin"];
    repeated ChatMessage messages = 2 [json_name="messages"];
}


// Message for holding the state of play for any chat session
// such that should the client send this back to the service,
// a different server knows exactly where to pick up where the previous
// conversation left off.
message ChatContext {

    // A potentially full list of chat histories that pertain to the node.
    // These will typically come in the last message of any particular agent's
    // chat stream.   Do not expect any or all internal agents will broadcast their
    // chat history, but you can at least expect the front-man to broadcast his.
    repeated ChatHistory chat_histories = 1 [json_name="chat_histories"];
}


// Structure describing a single chat message.
// This could be a single response, or a list of these might comprise
// a chat history.
message ChatMessage {

    // Type of message corresponding to basic langchain message types
    // that are in common usage.  This needs to match what is in the
    // ChatMessageType enum in the neuro-san codebase.
    enum ChatMessageType {
        UNKNOWN = 0;        // Note: UNKNOWN is not a langchain thing.
        SYSTEM = 1;
        HUMAN = 2;
        AI = 4;


        // These are not out-of-the-box langchain messages
        AGENT = 100;
        AGENT_FRAMEWORK = 101;
        AGENT_TOOL_RESULT = 103;    // Used at agent-level to represent AI Messages that
                                    // are actually generated by tools as their results.
        AGENT_PROGRESS = 104;       // Optionally used from CodedTools to present some
                                    // sense of formalized progress information     
    }

    // The type of chat message
    ChatMessageType type = 1;

    // String contents of any chat message
    string text = 2;

    // Optional bytes for any non-text media referenced by this message.
    // For some chat sources, the string text field might also be populated as a
    // reference for how the data was created.  If this happens, then
    // it should be safe to assume that the text is enough to represent the
    // message in any history carried forward.
    //
    // As of 1/13/25 this is a forward-looking, experimental field not likely
    // to be used in regular operation until we can get proper plumbing of such
    // data in place.
    repeated mime_data.MimeData mime_data = 3 [json_name="mime_data"];

    // Optional list of Origin structures (see above) describing the origin of the chat message.
    // The intent here is to be able to distiguish responses from nested agents.
    //
    // For each top-level agent/front-man (perhaps on another server) that is called,
    // an extra structure is added to the list.
    repeated Origin origin = 4 [json_name="origin"];

    // Optional structure for a message whose contents are parsed JSON.
    // The idea is to have the server side do the parsing when requested
    // by the agent spec.
    //
    // As of 1/30/25 this is a forward-looking, experimental field not likely
    // to be used in regular operation until we can get proper plumbing of such
    // data in place.
    google.protobuf.Struct structure = 5 [json_name="structure"];

    // Message for holding the state of play for any chat session
    // such that should the client send this back to the service,
    // a different server knows exactly where to pick up where the previous
    // conversation left off.
    ChatContext chat_context = 6 [json_name="chat_context"];

    // Optional list of Origin structures (see above) describing the origin of
    // a tool result.
    repeated Origin tool_result_origin = 7 [json_name="tool_result_origin"];

    // This is an entirely optional map whose keys refer to data that is better
    // left out of the LLM chat stream.  The keys themselves might appear in the
    // chat stream, referring to the data, but the data itself does not.
    // The intent is for the key references to be passed to tools,
    // which then grab the values by programmatic means, but these tools
    // might also have private data to send back to the client as well.
    google.protobuf.Struct sly_data = 8 [json_name="sly_data"];
}