Ursa

Database / data-access layer for Constellation’s research stack.

Ursa is Constellation’s data-access layer for multimodal recordings: EEG, video, eye tracking, biometrics, questionnaires, keyboard/mouse/screen captures, and more.

The data model is intentionally minimal: Participant → Recording (recording_hash) → Modality + Events + flexible metadata. No sessions, no trials, no stimuli.

The current M2 implementation is a raw catalog and byte-access layer: a Lance metadata catalog on Cloudflare R2 plus ursa.DataInterface.query(), .get(), and .download() for raw modalities. Processed Zarr arrays, temporal slicing, streaming windows, vector search, lifecycle GC, and Polaris cache sync are roadmap work.

Contents

• Setup
  • Prerequisites
  • Install Ursa
  • Configure URSA_PROFILE
  • Sanity check
  • First query
  • Troubleshooting
• Quickstart
  • Browsing the catalog
  • Selecting and materializing
  • Verify on a real recording
• Architecture
  • Current State Versus Roadmap
  • Goals
  • Data model
  • Catalog tables (Lance)
  • Storage backends
  • Object store
  • R2 key layout (ursa.layout)
  • Lifecycle Roadmap
  • Phasing
• Concepts
  • Catalog schemas
  • Registering data
• Tutorials
• Runbooks
  • MVP demo: register one real recording end-to-end (ENG-1063)
• API Reference
  • API Reference
  • ursa
  • ursa.data_interface
  • ursa._query_types
  • ursa.catalog
  • ursa.catalog.catalog
  • ursa.catalog.exceptions
  • ursa.catalog.schemas
  • ursa.layout
  • ursa.raw
  • ursa.store
  • ursa.store.base
  • ursa.store.config
  • ursa.store.factory
  • ursa.store.uri
  • ursa.temporal
  • ursa.time

Where this fits

Ursa is one of three packages in Constellation’s research stack:

• Ursa (this site) — database / data layer

• Virgo — DAG-based preprocessing

• Orion — research / training / benchmarking

Full architecture: Research Stack Architecture (Notion).

Status

🌱 Early bootstrap. M2 is raw catalog + raw byte access only. Implementation is tracked in the Linear Ursa project.

Phasing (mirrors the Linear project milestones):

• M1 — Foundations

• M2 — Underbuilt MVP (Phase 1a, solo) (current)

• M3 — Production Database (Phase 1b, with Killian)

• M4 — Production-scale (Phase 4)

• M5 — Benchmarks Integration (Phase 5)

• M6 — Polish & Onboarding (Phase 6)