constellation-utils

Shared utilities for the Constellation research stack — starting with secrets.

constellation-utils is a small Python package that gives Constellation’s research code a single, safe way to read credentials. Anything that needs an API key, a bucket access key, or any other secret asks constellation-utils for it. The package fetches the value from 1Password at runtime instead of from a .env file or a hardcoded string.

from constellation_utils import secrets

r2 = secrets.r2()
# R2Secrets(endpoint=..., access_key_id=..., secret_access_key=..., bucket=..., region=...)

That’s the whole interface. Behind the scenes the package figures out whether you’re on a laptop, a lab rig, or in CI, picks the right way to authenticate, fetches the credential, and caches it for the rest of the process.

Contents

• Quickstart
  • 1. Install 1Password and the op CLI
  • 2. Verify you have access
  • 3. Install the package
  • 4. Smoke test
  • 5. Use it in code
  • What about CI / rigs / production?
• Concepts
  • What is 1Password and why is it here?
  • What is the op CLI?
  • Authentication modes
  • Profiles: testing vs production
  • The two backends
  • What you get back
  • Caching
  • What’s NOT here
• Architecture
  • Package layout
  • Request flow
  • Design choices
  • Adding a new secret type
  • Testing
  • CLI
• Tutorials
  • Adding a new secret
• API Reference
  • API Reference

Why it exists

Before this package, every project read credentials a slightly different way — .env files, os.environ[...] calls, hand-typed paths. That made onboarding slow, leaked secrets into git history more than once, and made it hard to switch a single project from a testing R2 bucket to a production one.

Now there is one rule: secrets live in 1Password’s Engineering vault. Code asks secrets.<name>() for them. Done.

Status

🌱 MVP. Today the package exposes one secret (secrets.r2() for Cloudflare R2 storage) and one CLI command (constellation doctor). More secrets get added as needs arise — see the Secrets Manager Linear project.

Where this fits

constellation-utils is the foundation that other Constellation packages depend on:

• Ursa — database / data-access layer, uses secrets.r2() to talk to R2

• Virgo — DAG-based preprocessing

• Orion — research / training / benchmarking

• The data-engine rigs that record EEG and other modalities

Full architecture: Research Stack Architecture (Notion).