Skip to content

grpc-api.md

Latest commit

 

History

History
199 lines (149 loc) · 3.7 KB

grpc-api.md

File metadata and controls

199 lines (149 loc) · 3.7 KB

gRPC API Reference

The Cortex gRPC API is defined in crates/cortex-proto/proto/cortex.proto. The server listens on port 9090 by default.

Service: CortexService

CreateNode

rpc CreateNode(CreateNodeRequest) returns (NodeResponse);

message CreateNodeRequest {
  string kind = 1;
  string title = 2;
  string body = 3;
  float importance = 4;
  repeated string tags = 5;
  string source_agent = 6;
  map<string, string> metadata = 7;
  google.protobuf.Timestamp valid_from = 8;    // optional temporal validity
  google.protobuf.Timestamp valid_until = 9;   // optional temporal validity
  google.protobuf.Timestamp expires_at = 10;   // optional lifecycle expiry
}

GetNode

rpc GetNode(GetNodeRequest) returns (NodeResponse);

message GetNodeRequest {
  string id = 1;
}

UpdateNode

rpc UpdateNode(UpdateNodeRequest) returns (NodeResponse);

DeleteNode

rpc DeleteNode(DeleteNodeRequest) returns (DeleteResponse);

ListNodes

rpc ListNodes(ListNodesRequest) returns (ListNodesResponse);

message ListNodesRequest {
  string kind = 1;       // optional filter
  string agent = 2;      // optional filter
  uint32 limit = 3;
  uint32 offset = 4;
}

SearchNodes

rpc SearchNodes(SearchRequest) returns (SearchResponse);

message SearchRequest {
  string query = 1;
  uint32 limit = 2;
  string kind_filter = 3;
}

HybridSearch

rpc HybridSearch(HybridSearchRequest) returns (SearchResponse);

message HybridSearchRequest {
  string query = 1;
  uint32 limit = 2;
  float alpha = 3;
  uint32 graph_hops = 4;
}

CreateEdge

rpc CreateEdge(CreateEdgeRequest) returns (EdgeResponse);

message CreateEdgeRequest {
  string from_id = 1;
  string to_id = 2;
  string relation = 3;
  float weight = 4;
  map<string, string> metadata = 5;   // optional edge metadata
}

GetBriefing

rpc GetBriefing(GetBriefingRequest) returns (BriefingResponse);

message GetBriefingRequest {
  string agent_id = 1;
  uint32 max_tokens = 2;
  BriefingScope scope = 3;         // AGENT, SHARED, or UNIFIED
  repeated string agent_ids = 4;   // For UNIFIED scope
}

enum BriefingScope {
  AGENT = 0;
  SHARED = 1;
  UNIFIED = 2;
}

message BriefingResponse {
  string text = 1;
  repeated BriefingSection sections = 2;
}

GetTrustScore

rpc GetTrustScore(GetTrustScoreRequest) returns (TrustScoreResponse);

message GetTrustScoreRequest {
  string node_id = 1;
}

message TrustScoreResponse {
  string node_id = 1;
  float trust_score = 2;
  TrustSignals signals = 3;
}

message TrustSignals {
  float corroboration = 1;
  float contradiction = 2;
  float source_reliability = 3;
  float access_reinforcement = 4;
  float freshness = 5;
}

BatchGetTrustScore

rpc BatchGetTrustScore(BatchTrustRequest) returns (BatchTrustResponse);

message BatchTrustRequest {
  repeated string node_ids = 1;
}

message BatchTrustResponse {
  repeated TrustScoreResponse scores = 1;
}

Traverse

rpc Traverse(TraversalRequest) returns (SubgraphResponse);

FindPaths

rpc FindPaths(PathRequest) returns (PathResponse);

Connecting

Python

import grpc
from cortex_proto import cortex_pb2, cortex_pb2_grpc

channel = grpc.insecure_channel("localhost:9090")
stub = cortex_pb2_grpc.CortexServiceStub(channel)

response = stub.CreateNode(cortex_pb2.CreateNodeRequest(
    kind="fact",
    title="The API uses JWT auth",
    importance=0.7,
))

Rust

use cortex_client::CortexClient;

let mut client = CortexClient::connect("http://localhost:9090").await?;
let node = client.create_node("fact", "The API uses JWT auth", 0.7).await?;