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.4.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.4.0
File	Size	Uploaded
agatha_protobuf-1.4.0.tar.gz	105.3 kB	Aug 20, 2026	Details

Built distribution (wheel)

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

Total release size: 302.6 kB

Release files / agatha_protobuf-1.4.0.tar.gz

Download URL	agatha_protobuf-1.4.0.tar.gz
Size	105.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`09262bf2cd9d35db067c7aff9e40c090c62f86c0d7180b1f791d45e73ae556c6`
BLAKE2b-256 checksum How to use checksums	`3e8435eee5cb491bf35458dcf694dd1d0c4538837aac1fba5a0950ce3d78aafb`
Upload date	Aug 20, 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.4.0-py3-none-any.whl

Download URL	agatha_protobuf-1.4.0-py3-none-any.whl
Size	197.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b8dd796df3ba17321727356f41196fd763fd4c7e32f8f0e822655d45dd7660d1`
BLAKE2b-256 checksum How to use checksums	`36960b029ceaea7b2774fa7188088912810ee075ba36f3398dcd6780098e0e39`
Upload date	Aug 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`