TPT Open Source

tpt-cerebrum

Rust

First-principles, multi-scale computational platform for the central nervous system — unifying electrophysiology, neuroimaging, connectomics, and molecular neurobiology into a single Digital Brain environment.

0 stars0 forks0 watchers
View on GitHub

Languages

Rust85.8%TypeScript10.7%Python2.7%Shell0.4%CSS0.2%Go Template0.2%JavaScript0.1%HTML0.1%
README

tpt-cerebrum

Neuroscience data platform for connectomic, electrophysiological, transcriptomic, simulation, and translational (pathology / neurotechnology) research data.

tpt-cerebrum is a Rust + TypeScript monorepo implementing the full 4-phase roadmap in spec.txt and tracked in TODO.md. It is deliberately built on two custom storage engines rather than a consolidated off-the-shelf database:

  • tpt-cerebrum-connectome-store — a sparse-graph engine for macro- and micro-scale connectomes (CSR/CSC adjacency, typed nodes/edges, native graph-theory primitives).
  • tpt-cerebrum-tsdb — a high-frequency, columnar, multi-channel time-series engine for electrophysiology (millions of samples/sec across many channels).

Volumetric imaging (NIfTI/DICOM/MINC, Zarr/COG) lives in S3-compatible object storage (MinIO) via tpt-cerebrum-volumetric. Access control is a custom capability-token cryptosystem (tpt-cerebrum-capability) plus a hash-chained audit ledger (tpt-cerebrum-audit); the tpt-cerebrum-zk crate pursues a genuine ZK-SNARK track as a non-blocking parallel R&D effort.

Architecture at a glance

                         ┌─────────────────────────────────────────┐
   Browser / SPA  ─────▶ │  tpt-cerebrum-api  (single binary)       │
   (React + deck.gl)     │   - axum HTTP router                     │
                         │   - capability auth + audit middleware   │
                         │   - domain modules: nexus / chronos /     │
                         │     cytos / simulacrum / praxis /         │
                         │     pathos / symbiosis                    │
                         └───────┬───────────────┬──────────┬────────┘
                                 │               │          │
                    ┌────────────▼───┐   ┌────────▼─────┐  ┌─▼──────────────┐
                    │ connectome-store│  │   tsdb        │  │ volumetric     │
                    │ (in-process lib)│  │ (in-process   │  │ (MinIO / S3)   │
                    │                 │  │   lib)        │  │                │
                    └────────┬────────┘  └──────┬────────┘  └────────────────┘
                             │                  │
                             ▼                  ▼
                    ┌────────────────────────────────────┐
                    │  tpt-cerebrum-core (data access)    │
                    │   - PostgreSQL (relational metadata)│
                    │   - capability verifier + audit     │
                    └────────────────────────────────────┘

The connectome-store and tsdb engines are in-process libraries embedded in the API binary — they are not standalone gRPC services. Deploying the platform means running the single tpt-cerebrum-api process (plus PostgreSQL and MinIO).

Quickstart (local, Docker Compose)

Prerequisites: Docker + Docker Compose.

# Bring up the full stack: postgres, minio, api, frontend, audit-integrity.
docker compose up -d

# Wait for the api health check to pass.
curl -f http://localhost:8080/health

# Issue a capability token and use it (see "End-to-end example" below).
curl -s -X POST http://localhost:8080/auth/issue \
  -H 'Content-Type: application/json' \
  -d '{"subject":"demo","resource_class":"eeg_raw","action":"read","expiry_hours":1}'

Tear down:

docker compose down -v

Seeded demo

# One command: bring up the stack *and* seed a demo subject + token.
docker compose --profile demo up -d

The demo profile adds a seed job that issues a token and creates a demo subject against the running API (see deploy/seed/seed.sh).

Building from source

# Rust workspace (std crates)
cargo build --workspace --exclude tpt-cerebrum-stream
cargo test  --workspace --exclude tpt-cerebrum-stream

# no_std edge-ingestion crate (cross-compile, no default features)
cargo build --package tpt-cerebrum-stream --target thumbv7em-none-eabihf --no-default-features

# Frontend
cd frontend && npm ci && npm run build

The API binary is tpt-cerebrum-api:

cargo run -p tpt-cerebrum-api --bin tpt-cerebrum-api

Environment

VariableDefaultPurpose
API_ADDR0.0.0.0:8080Bind address
API_CORS_ORIGINShttp://localhost:3000Comma-separated CORS origins
DATABASE_URLpostgres://postgres:postgres@localhost:5432/cerebrumPostgreSQL connection string
AUDIT_DATA_DIR./data/audit.dbHash-chained audit ledger path
TSDB_DATA_DIR./data/tsdbTime-series chunk directory
CEREBRUM_ROOT_KEY(unset → ephemeral dev key per start)PEM root key for capability tokens
MINIO_*minioadmin / localhost:9000Volumetric object store

End-to-end example

Issue a token, create a subject, then query through the capability-gated API:

# 1. Issue a capability token.
TOKEN=$(curl -s -X POST http://localhost:8080/auth/issue \
  -H 'Content-Type: application/json' \
  -d '{"subject":"researcher_1","resource_class":"eeg_raw","action":"read","expiry_hours":1}' \
  | jq -r .token)

# 2. Create a subject (token as bearer credential).
curl -s -X POST http://localhost:8080/subjects \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"species":"homo_sapiens","sex":"F"}'

# 3. List subjects.
curl -s http://localhost:8080/subjects -H "Authorization: Bearer $TOKEN"

# 4. Verify the access was recorded in the audit ledger.
curl -s http://localhost:8080/audit/integrity -H "Authorization: Bearer $TOKEN"

A copy of this flow is in examples/e2e_smoke.sh.

Deployment

Dual deployment paths are maintained in parity:

  • Docker Compose — deploy/docker-compose.yml (+ docker-compose.override.yml for local dev). The demo profile seeds data.
  • Kubernetes / Helm — deploy/helm/tpt-cerebrum/. helm lint / helm template are exercised in CI. The chart packages the full ingest+sim stack for on-prem / partner-site federation deploys (Phase 4).

Repository layout

CrateResponsibility
tpt-cerebrum-coreShared data-access layer (Postgres + stores + security)
tpt-cerebrum-capabilityEd25519 capability tokens, attenuation, revocation
tpt-cerebrum-auditAppend-only hash-chained audit ledger
tpt-cerebrum-connectome-storeSparse-graph engine (macro + micro connectome)
tpt-cerebrum-tsdbHigh-frequency columnar time-series engine
tpt-cerebrum-volumetricMinIO/S3 volumetric (NIfTI/DICOM/Zarr) wrapper
tpt-cerebrum-streamno_std, zero-alloc edge ingestion parser
tpt-cerebrum-dicomNIfTI/DICOM/MINC parsing + defacing
tpt-cerebrum-nexusMacro-structure: tractography + functional connectivity
tpt-cerebrum-chronosTemporal dynamics: spike-sorting, LFP, ERP
tpt-cerebrum-cytosSingle-cell / spatial transcriptomics
tpt-cerebrum-simulacrumBiophysical / neural-mass simulation
tpt-cerebrum-praxisBehavioral / psychometric + decoding
tpt-cerebrum-pathosTranslational pathology models
tpt-cerebrum-symbiosisBCI decoding / neuromodulation / neuroprosthetics
tpt-cerebrum-zkZK-SNARK proof track (non-blocking R&D)
tpt-cerebrum-federationEncrypted weight exchange + audit reconciliation
tpt-cerebrum-somatpt-soma interop client surface
tpt-cerebrum-apiThe single runnable HTTP service + binary

See docs/adr for the architecture decision records behind the build-vs-buy and security choices, and CONTRIBUTING.md for build/test/lint and PR expectations.