agatha-protobuf 1.2.0

Protobuf files for Agatha project

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

Go

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

1. Edit .proto files under src/agatha_protobuf/<domain>/.
2. make proto (Python) and/or make proto-go (Go).
3. Bump version via make patch|minor|major|release.
4. Commit src/, build/, pyproject.toml.
5. 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.