gRPC Contracts

All ContextUnity services communicate via gRPC using a universal ContextUnit envelope — every RPC accepts and returns contextunity.core.ContextUnit. Domain-specific data flows through the payload dict.

ContextUnit Envelope Pattern

// Every service uses ContextUnit as input and output
rpc Search(contextunity.core.ContextUnit) returns (stream contextunity.core.ContextUnit);
rpc Upsert(contextunity.core.ContextUnit) returns (contextunity.core.ContextUnit);

This pattern unifies security (token travels with every call), provenance tracking, and error handling across the entire mesh.

Proto Definitions

All proto files live in packages/core/protos/:

brain.proto — 18 RPCs

service BrainService {
    // Knowledge
    rpc Search(ContextUnit) returns (stream ContextUnit);
    rpc GraphSearch(ContextUnit) returns (ContextUnit);
    rpc CreateKGRelation(ContextUnit) returns (ContextUnit);
    rpc Upsert(ContextUnit) returns (ContextUnit);

    // Memory
    rpc QueryMemory(ContextUnit) returns (stream ContextUnit);
    rpc AddEpisode(ContextUnit) returns (ContextUnit);
    rpc GetRecentEpisodes(ContextUnit) returns (stream ContextUnit);
    rpc UpsertFact(ContextUnit) returns (ContextUnit);
    rpc GetUserFacts(ContextUnit) returns (stream ContextUnit);
    rpc GetEpisodeStats(ContextUnit) returns (ContextUnit);
    rpc RetentionCleanup(ContextUnit) returns (ContextUnit);

    // Traces
    rpc LogTrace(ContextUnit) returns (ContextUnit);
    rpc GetTraces(ContextUnit) returns (stream ContextUnit);

    // Taxonomy
    rpc UpsertTaxonomy(ContextUnit) returns (ContextUnit);
    rpc GetTaxonomy(ContextUnit) returns (stream ContextUnit);

    // Shared State
    rpc WriteBlackboard(ContextUnit) returns (ContextUnit);
    rpc ReadBlackboard(ContextUnit) returns (ContextUnit);

    // Commerce (mixin)
    rpc MatchDuckDB(ContextUnit) returns (ContextUnit);
}

Commerce Operations

CommerceService was decommissioned. Commerce matching operations (MatchDuckDB) are now handled as a mixin on BrainService. Product CRUD operations live in the Commerce Django extension (Oscar/Wagtail).

router.proto — 8 RPCs

service RouterService {
    rpc ExecuteAgent(ContextUnit) returns (ContextUnit);
    rpc StreamAgent(ContextUnit) returns (stream ContextUnit);
    rpc ExecuteDispatcher(ContextUnit) returns (ContextUnit);
    rpc StreamDispatcher(ContextUnit) returns (stream ContextUnit);
    rpc RegisterManifest(ContextUnit) returns (ContextUnit);
    rpc ToolExecutorStream(stream ContextUnit) returns (stream ContextUnit);
    rpc ExecuteNode(ContextUnit) returns (ContextUnit);
    rpc IntrospectRegistrations(ContextUnit) returns (ContextUnit);
}

worker.proto — 4 RPCs

service WorkerService {
    rpc StartWorkflow(ContextUnit) returns (ContextUnit);
    rpc GetTaskStatus(ContextUnit) returns (ContextUnit);
    rpc ExecuteCode(ContextUnit) returns (ContextUnit);
    rpc RegisterSchedules(ContextUnit) returns (ContextUnit);
}

shield.proto — 12 RPCs

service ShieldService {
    // Core security
    rpc Scan(ContextUnit) returns (ContextUnit);
    rpc EvaluatePolicy(ContextUnit) returns (ContextUnit);
    rpc CheckCompliance(ContextUnit) returns (ContextUnit);
    rpc RecordAudit(ContextUnit) returns (ContextUnit);
    rpc MintToken(ContextUnit) returns (ContextUnit);
    rpc VerifyToken(ContextUnit) returns (ContextUnit);
    rpc RevokeToken(ContextUnit) returns (ContextUnit);
    rpc GetStats(ContextUnit) returns (ContextUnit);

    // Secrets management
    rpc GetSecret(ContextUnit) returns (ContextUnit);
    rpc PutSecret(ContextUnit) returns (ContextUnit);
    rpc ListSecrets(ContextUnit) returns (ContextUnit);
    rpc RotateSecret(ContextUnit) returns (ContextUnit);
}

admin.proto — 18 RPCs (ContextView)

service AdminService {
    // Health & Monitoring
    rpc GetServiceHealth(ContextUnit) returns (ContextUnit);
    rpc GetServiceMetrics(ContextUnit) returns (ContextUnit);
    rpc CheckServiceConnectivity(ContextUnit) returns (ContextUnit);

    // Memory
    rpc GetMemoryStats(ContextUnit) returns (ContextUnit);
    rpc GetMemoryLayerStats(ContextUnit) returns (ContextUnit);

    // Agent Management
    rpc ListAgents(ContextUnit) returns (ContextUnit);
    rpc GetAgentConfig(ContextUnit) returns (ContextUnit);
    rpc UpdateAgentPermissions(ContextUnit) returns (ContextUnit);
    rpc UpdateAgentTools(ContextUnit) returns (ContextUnit);
    rpc GetAgentActivity(ContextUnit) returns (ContextUnit);

    // Traces & Debugging
    rpc GetTraceDetails(ContextUnit) returns (ContextUnit);
    rpc SearchTraces(ContextUnit) returns (ContextUnit);
    rpc GetTraceChainOfThought(ContextUnit) returns (ContextUnit);

    // Analytics
    rpc GetSystemAnalytics(ContextUnit) returns (ContextUnit);
    rpc GetErrorAnalytics(ContextUnit) returns (ContextUnit);

    // Self-Healing
    rpc DetectSystemErrors(ContextUnit) returns (ContextUnit);
    rpc TriggerSelfHealing(ContextUnit) returns (ContextUnit);
    rpc GetHealingStatus(ContextUnit) returns (ContextUnit);
}

Proto Compilation

After modifying any .proto file, regenerate stubs immediately:

cd packages/core
./compile_protos.sh

This generates *_pb2.py and *_pb2_grpc.py files for all 6 protos.

Proto Rules

• Append only — never delete or renumber existing proto fields
• Never edit generated files — *_pb2.py are auto-generated
• Import from core — from contextunity.core import brain_pb2, never local copies
• Git hooks and Ansible pre-flight block commits/deploys with untracked proto changes

Importing Stubs

# Correct — always import from contextunity.core
from contextunity.core import brain_pb2, brain_pb2_grpc
from contextunity.core import contextunit_pb2

# Create client
channel = grpc.aio.insecure_channel("localhost:50051")
stub = brain_pb2_grpc.BrainServiceStub(channel)

# All RPCs use ContextUnit
unit = ContextUnit(payload={"tenant_id": "my_app", "query": "..."})
response = await stub.Upsert(unit.to_protobuf(contextunit_pb2))