Metadata-Version: 2.4
Name: agatha-protobuf
Version: 1.1.13
Summary: Protobuf files for Agatha project
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: grpcio
Requires-Dist: protobuf

# 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

```bash
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:

```bash
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**

```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**

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

```python
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.
