Paper Proto (paper-proto)

Central Protocol Buffer Schemas and Multi-Language Code Generation for the Paper AI Ecosystem.

paper-proto is the single source of truth for all gRPC service interfaces and message schemas across the Paper ecosystem. It defines cross-repository contracts using Protocol Buffers v3 and provides automated code generation for Python and TypeScript stubs.

---

Role in the Ecosystem

                      paper-proto (Schema Source of Truth)
                                       |
                                       | `buf generate`
                    +------------------+------------------+
                    |                                     |
         generated/python/                    generated/typescript/
                    |                                     |
   Consumed by paper-core, paper-caller,            Consumed by paper-cli,
   paper-memory, paper-tools, paper-mcp             web client dashboards

• Contract-First Architecture: All API changes must originate in paper-proto. No application repository defines custom inter-service network schemas.
• Breaking Change Detection: Enforces strict linting and backward-compatibility rules via buf.

---

Repository Structure

paper-proto/
├── proto/                       # Protocol Buffer source files
│   └── paper/
│       ├── core/v1/            # AIService & AIStreamService contracts
│       ├── caller/v1/          # VoiceService contracts
│       ├── memory/v1/          # MemoryService contracts
│       └── tools/v1/           # ToolService contracts
├── generated/                   # Generated stubs (committed)
│   ├── python/                 # Python gRPC stubs (*_pb2.py, *_pb2_grpc.py)
│   └── typescript/             # TypeScript gRPC web/node stubs (*.ts)
├── buf.yaml                     # Buf module configuration
├── buf.gen.yaml                 # Buf code generation plugin pipeline
├── Makefile                     # Build automation shortcuts
└── README.md

---

Service Catalog

Service	Proto Package	File Path	Primary RPC Methods
AIService	paper.core.v1	proto/paper/core/v1/ai_service.proto	Generate()
AIStreamService	paper.core.v1	proto/paper/core/v1/ai_service.proto	StreamGenerate()
VoiceService	paper.caller.v1	proto/paper/caller/v1/voice_service.proto	StreamAudio()
MemoryService	paper.memory.v1	proto/paper/memory/v1/memory_service.proto	GetContext(), SaveTurn()
ToolService	paper.tools.v1	proto/paper/tools/v1/tool_service.proto	ExecuteTool()

---

Building and Code Generation

Prerequisites

• Buf CLI (v1.30+)
• Python 3.12+
• Node.js 20+

Generating Code Stubs

# Clone repository
git clone https://github.com/artificialpaper/paper-proto.git
cd paper-proto

# Lint proto definitions
buf lint

# Check backward compatibility against main branch
buf breaking --against '.git#branch=main'

# Generate Python and TypeScript stubs
buf generate

Using make:

make lint
make generate

---

Conventions & Style Guide

1. Syntax: All files must declare syntax = "proto3";.
2. Package Naming: Follow paper.<subsystem>.v1 conventions.
3. Field Names: snake_case for fields, CamelCase for messages/services, UPPER_SNAKE_CASE for enums.
4. Field Numbers: Use 1-15 for hot/frequently serialized fields (single byte tag encoding).

---

Related Repositories

• paper-core - Central LLM Inference Gateway
• paper-caller - Real-Time Voice AI Agent Runtime
• paper-memory - Session Memory & RAG Store
• paper-docs - Official Ecosystem Documentation Portal

---

License

This project is licensed under the MIT License - see the LICENSE file for details.