Chaukas Spec Client

Protocol buffers and gRPC stubs for integrating Chaukas agent observability into your SDKs

What is this?

chaukas-spec-client provides the client-side Protocol Buffer definitions and gRPC service stubs for the Chaukas agent observability platform. Use this package to:

• Instrument your AI agent SDKs with standardized event tracking
• Send telemetry data to Chaukas-compatible backends
• Track 19+ event types across agent lifecycles, model invocations, tool calls, and errors
• Enable distributed tracing with full trace context propagation
• Ensure compliance with immutable audit trails

Who should use this?

• SDK developers building agent frameworks who want to add observability
• Agent builders integrating telemetry into custom agents
• Platform teams sending events from client applications to observability backends

Note: If you're implementing an observability backend/platform, use chaukas-spec-server instead.

Installation

pip install chaukas-spec-client

Quick Start

import grpc
from chaukas.spec.client.v1.client_pb2_grpc import ChaukasClientServiceStub
from chaukas.spec.client.v1.client_pb2 import IngestEventRequest
from chaukas.spec.common.v1.events_pb2 import Event, EventType

# Create gRPC channel to your Chaukas backend
channel = grpc.insecure_channel('localhost:50051')
stub = ChaukasClientServiceStub(channel)

# Create and send an event
event = Event(
    event_id="evt_123",
    type=EventType.EVENT_TYPE_AGENT_START,
    session_id="session_abc",
    trace_id="trace_xyz"
)

request = IngestEventRequest(event=event)
response = stub.IngestEvent(request)

Event Types

The specification includes comprehensive event types for agent observability:

Features

✅ Standardized Schema - Protocol Buffer definitions for all event types ✅ gRPC Services - High-performance service stubs for event ingestion ✅ Type Safety - Full type hints and validation ✅ Distributed Tracing - Built-in trace context support ✅ Batch Operations - Efficient batch event ingestion ✅ Query Support - Query events by session, trace, time range, and more

Package Contents

chaukas/spec/
├── client/v1/       # Client gRPC service stubs
│   ├── client_pb2.py
│   └── client_pb2_grpc.py
└── common/v1/       # Shared event definitions
    ├── events_pb2.py
    └── query_pb2.py

Documentation

• Full Specification: chaukas-spec repository
• Protocol Definitions: proto/chaukas/spec/
• Architecture: See main README
• Examples: Usage examples

Related Packages

• chaukas-sdk - One-line instrumentation for popular agent frameworks
• chaukas-spec-server - Server-side implementation for building observability backends

Contributing

We welcome contributions! Please see our Contributing Guide and Code of Conduct.

License

Apache 2.0 - See LICENSE for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md