gRPC primer

1. Why gRPC over REST

gRPC rides HTTP/2, multiplexes streams over one socket, and serializes with Protocol Buffers. For agent fan-out and token streaming you avoid the head-of-line blocking that hits keep-alive REST. The .proto file is shipped as your contract, so client SDKs in Go, Python, and TypeScript stay aligned without hand-written DTOs.

• •Bidirectional streaming for chat turns.
• •Deadlines propagate across hops automatically.
• •Strong typing eliminates a whole class of bugs.

2. Wire a client

Compile the Meridian .proto with your language toolchain, then open a secure channel to the gateway. Pass your API key as metadata on every call so the gateway can route to the right tenant and bill the right account.

import grpc
from meridian_pb2 import ChatRequest
from meridian_pb2_grpc import MeridianStub

creds = grpc.ssl_channel_credentials()
chan = grpc.secure_channel("grpc.meridian.ai:443", creds)
stub = MeridianStub(chan)

meta = (("authorization", "Bearer sk-..."),)
req = ChatRequest(model="meridian-pro", prompt="hello")
for chunk in stub.StreamChat(req, metadata=meta, timeout=30):
    print(chunk.delta, end="", flush=True)

3. Survive production

Always set a deadline on the call rather than the channel. Retry only on UNAVAILABLE and DEADLINE_EXCEEDED, with jittered exponential backoff. Reuse a single channel per process so HTTP/2 flow control can do its job, and keep a keepalive ping of around 30 seconds to survive idle NAT timeouts.