exo/proto/exo/v1/kg.proto

syntax = "proto3";

package exo.v1;

option go_package = "git.wntrmute.dev/kyle/exo/proto/exo/v1;exov1";

import "exo/v1/common.proto";

// Node is an entity in the knowledge graph.
message Node {
  string id = 1;
  string parent_id = 2;
  string name = 3;
  string type = 4; // "note" or "artifact_link"
  string created = 5;
  string modified = 6;
  repeated string children = 7;
  repeated string tags = 8;
  repeated string categories = 9;
}

// Cell is a content unit within a note.
message Cell {
  string id = 1;
  string node_id = 2;
  string type = 3; // "markdown", "code", "plain"
  bytes contents = 4;
  int32 ordinal = 5;
  string created = 6;
  string modified = 7;
}

// Fact records an EAV relationship with transactional history.
message Fact {
  string id = 1;
  string entity_id = 2;
  string entity_name = 3;
  string attribute_id = 4;
  string attribute_name = 5;
  Value value = 6;
  int64 tx_timestamp = 7;
  bool retraction = 8;
}

// Edge links nodes to other nodes or artifacts.
message Edge {
  string id = 1;
  string source_id = 2;
  string target_id = 3;
  string relation = 4;
  string created = 5;
}

// --- Service messages ---

message CreateNodeRequest {
  string name = 1;
  string type = 2;
  string parent_id = 3;
  repeated string tags = 4;
  repeated string categories = 5;
}

message CreateNodeResponse {
  string id = 1;
}

message GetNodeRequest {
  string id = 1;
}

message GetNodeResponse {
  Node node = 1;
  repeated Cell cells = 2;
}

message AddCellRequest {
  string node_id = 1;
  string type = 2;
  bytes contents = 3;
  int32 ordinal = 4;
}

message AddCellResponse {
  string id = 1;
}

message RecordFactRequest {
  string entity_id = 1;
  string entity_name = 2;
  string attribute_id = 3;
  string attribute_name = 4;
  Value value = 5;
  bool retraction = 6;
}

message RecordFactResponse {
  string id = 1;
}

message GetFactsRequest {
  string entity_id = 1;
  bool current_only = 2;
}

message GetFactsResponse {
  repeated Fact facts = 1;
}

message AddEdgeRequest {
  string source_id = 1;
  string target_id = 2;
  string relation = 3;
}

message AddEdgeResponse {
  string id = 1;
}

message GetEdgesRequest {
  string node_id = 1;
  string direction = 2; // "from", "to", or "both"
}

message GetEdgesResponse {
  repeated Edge edges = 1;
}

// KnowledgeGraphService provides operations for the knowledge graph pillar.
service KnowledgeGraphService {
  // Nodes
  rpc CreateNode(CreateNodeRequest) returns (CreateNodeResponse);
  rpc GetNode(GetNodeRequest) returns (GetNodeResponse);

  // Cells
  rpc AddCell(AddCellRequest) returns (AddCellResponse);

  // Facts
  rpc RecordFact(RecordFactRequest) returns (RecordFactResponse);
  rpc GetFacts(GetFactsRequest) returns (GetFactsResponse);

  // Edges
  rpc AddEdge(AddEdgeRequest) returns (AddEdgeResponse);
  rpc GetEdges(GetEdgesRequest) returns (GetEdgesResponse);
}