Agatha Protobuf

Shared gRPC contracts for the Agatha monorepo. Source .proto files live in src/agatha_protobuf/; generated stubs are committed under build/ (Go) and dist/ / installable Python package agatha-protobuf (Python).

Package name (Python/PyPI): agatha-protobuf
Go module: github.com/blueprint-ai-org/protobuf
Current version: see pyproject.toml (version)

Service domains (`src/agatha_protobuf/`)

activity_ingestor/   auth/                 knowledge_graph/
lms_connector/       manager/              metrics_engine/
notification/        payment/              analysis/

Each subdirectory contains the .proto files for that service's gRPC contracts (messages + services). Edit these and regenerate.

Make targets

make install-deps    # install protoc-gen-go, protoc-gen-go-grpc, build/twine helpers
make proto           # compile .proto → Python (src/, with .pyi stubs and grpc_python_out)
make proto-go        # compile .proto → Go under build/, then git-add + bump patch version
make clean           # remove dist/ build/ *.egg-info and *_pb2*.py(i) files
make build           # proto + python sdist/wheel into dist/
make publish         # clean + build + upload to PyPI (twine)

Version management:

make patch                # bump 1.1.x
make minor                # bump 1.x.0
make major                # bump x.0.0
make release VERSION=1.2.3  # set explicit version

make proto-go automatically git add ./build and runs make patch. Commit afterwards.

Prerequisites

Python 3.8+ with a venv at .venv/ (the Makefile invokes .venv/bin/python3)
Go 1.24+ with protoc-gen-go and protoc-gen-go-grpc on PATH (installed by make install-deps)
protoc available via grpc_tools.protoc (Python) and protoc (Go)

Consuming from services

import "github.com/blueprint-ai-org/protobuf/build/agatha_protobuf/auth"

Most services vendor this module — bump the dependency, then go mod tidy (GOPRIVATE=github.com/blueprint-ai-org/*, GITHUB_TOKEN).

Python

pip install agatha-protobuf
# or, in pyproject.toml:
# dependencies = ["agatha-protobuf>=1.1.0"]

from agatha_protobuf.auth import auth_pb2, auth_pb2_grpc

Workflow

Edit .proto files under src/agatha_protobuf/<domain>/.
make proto (Python) and/or make proto-go (Go).
Bump version via make patch|minor|major|release.
Commit src/, build/, pyproject.toml.
make publish to push the Python package to PyPI; for Go, consumers update via go get github.com/blueprint-ai-org/protobuf@<tag>.

Changelog

Pipeline: `tenant_user_id` added (plan 2026-05-13-notification-tenant-refactor, step-11)

Adds a raw (non-hashed) tenant_user_id field — FK to <tenantID>.user._id — across the cross-monorepo Pub/Sub pipeline that runs journal-created → behavioral-events-raw → risk-alerts. Producers (agent, activity-ingestor) populate from Journal.user; consumers (metrics-engine, notification) read alongside the existing person_id.

Schemas touched:

knowledge_graph/event.proto — IngestEventRequest.tenant_user_id (field 9).
notification/notification.proto — RiskAlert.tenant_user_id (field 16); RiskAlert.person_id (field 3) marked [deprecated = true].
activity_ingestor/journal.proto — Journal.user documented as the canonical source of tenant_user_id (no wire change).

JSON Pub/Sub structs (non-proto, in consuming services):

metrics-engine/internal/risk/alert_event.go — RiskAlertEvent.TenantUserID.
metrics-engine/internal/infra/pubsub/event.go — BehavioralEvent.TenantUserID.
knowledge-graph/internal/infra/pubsub/publisher.go — EventMessage.TenantUserID.

person_id is kept for one release cycle as a [deprecated = true] alias; removal is a follow-up plan once all consumers have migrated.

Release files for agatha-protobuf 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agatha-protobuf 1.3.0
File	Size	Uploaded
agatha_protobuf-1.3.0.tar.gz	104.4 kB	Aug 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for agatha-protobuf 1.3.0
File	Interpreter	ABI	Platform	Reset
agatha_protobuf-1.3.0-py3-none-any.whl 196.2 kB Aug 19, 2026	Python 3	none	any	Details

Total release size: 300.7 kB

Release files / agatha_protobuf-1.3.0.tar.gz

Download URL	agatha_protobuf-1.3.0.tar.gz
Size	104.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`179294e905d678ad09377b307fed02760387a1406cfa8bc86ae474ef6f2c7138`
BLAKE2b-256 checksum How to use checksums	`54af58ffe95ac1091c6b168c0381fc53b800279fa28e2f517c886cc6df6b0c20`
Upload date	Aug 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / agatha_protobuf-1.3.0-py3-none-any.whl

Download URL	agatha_protobuf-1.3.0-py3-none-any.whl
Size	196.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`59e35d32c5c32efcfe1a582e84d96c9d85ba81c0b15ccd8b2d1ca6172fe36788`
BLAKE2b-256 checksum How to use checksums	`4185b096eb2ead24e604131d4ca05b1edef551e31a5470d61bf464bd0d869ce9`
Upload date	Aug 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`