Nest Engineering Docs
Raven

Local development

Run, debug, and test Raven locally

Prerequisites

  • uv and Python 3.13.
  • GCP credentials with access to Spanner, Secret Manager, and Firebase Admin.
  • Access to the Bubble API token secret (RAVEN_BUBBLE_API_TOKEN).
  • Access to a Spanner instance containing the Raven data model.

Required environment

export GCP_PROJECT_ID="..."
export SPANNER_INSTANCE_ID="..."
export SPANNER_DATABASE_ID="..."
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

Local settings file

Create services/raven/.env for local overrides:

DEBUG=true
SEARCH_DEFAULT_LIMIT=10
SEARCH_MAX_LIMIT=15
SPANNER_SEARCH_STALENESS_SECONDS=0
SEARCH_STREAM_BATCH_SIZE=1
MICROSOFT_TENANT_ID=common

Install dependencies

# From repo root
uv sync --all-packages

Run locally

# From repo root
uv run --package raven-service granian --interface asgi services.raven.main:app --host 0.0.0.0 --port 8080 --workers 1

Sanity checks

# Connect/JSON request
curl \
  --header "Content-Type: application/json" \
  --data '{"organizationId": "org-123", "query": "FLUFFY"}' \
  http://localhost:8080/raven.raven.v1.RavenService/SearchPatients

Authentication locally

  • Login and SSO are unauthenticated; all other RPCs require a Firebase ID token.
  • To hit protected RPCs, authenticate via the Raven desktop app or call Login to mint a Firebase custom token (requires Bubble credentials).

Tests

# From repo root
uv run --package raven-service pytest -q

Last updated on

Data model

Storage, schemas, and data ownership for Raven

Operations

Deployments, SLOs, and monitoring for Raven