llm-multiverse/proto

Proto Definitions

This directory contains all Protocol Buffer definitions for the llm-multiverse service mesh.

Prerequisites

Install the buf CLI:

# Linux (x86_64)
curl -sSL https://github.com/bufbuild/buf/releases/latest/download/buf-Linux-x86_64 \
  -o /usr/local/bin/buf && chmod +x /usr/local/bin/buf

# Or via Go
go install github.com/bufbuild/buf/cmd/buf@latest

Directory Structure

proto/
├── buf.yaml                    # Module config + lint rules
├── buf.gen.yaml                # Code generation targets (Rust + Python)
├── llm_multiverse/v1/          # All proto definitions (versioned API)
│   ├── common.proto            # Shared types: SessionContext, AgentLineage
│   ├── audit.proto             # AuditService (write-only append log)
│   ├── secrets.proto           # SecretsService (GetSecret only)
│   ├── memory.proto            # MemoryService (Write, Query, GetCorrelated)
│   ├── model_gateway.proto     # ModelGatewayService (Inference, Embedding)
│   ├── search.proto            # SearchService (Search)
│   ├── tool_broker.proto       # ToolBrokerService (Execute, Validate, Discover)
│   └── orchestrator.proto      # OrchestratorService (subagent return schema)
└── scripts/
    └── generate.sh             # CI-ready lint + build + generate script

Usage

Lint all protos

cd proto && buf lint

Build (compile check)

cd proto && buf build

Generate stubs

cd proto && bash scripts/generate.sh

Generated code is output to gen/rust/src/ and gen/python/ (at repo root).

Breaking change detection

cd proto && buf breaking --against '.git#subdir=proto'

Conventions

• Package: All protos use llm_multiverse.v1
• Session context: Every RPC request message must include a SessionContext field (defined in common.proto) for audit trail and broker enforcement
• Streaming: Use server-streaming RPCs for large/progressive output (token generation, corpus retrieval). Use unary RPCs for simple operations (cache hits, writes, validation)
• Naming: Service names match the service they define (e.g., AuditService in audit.proto)

Adding a New Proto

1. Create proto/llm_multiverse/v1/<service>.proto
2. Set syntax = "proto3"; and package llm_multiverse.v1;
3. Import common.proto for shared types: import "llm_multiverse/v1/common.proto";
4. Run buf lint to validate
5. Run buf build to compile-check
6. Update buf.gen.yaml if new generation targets are needed