brain-store

Dual-mode persistence layer (PostgreSQL connection pool + flat-file fallback) and RL state store for Brain Alpha pipelines.

brain_store provides resilient, dual-mode persistence for quantitative alpha pipelines. It connects to Neon PostgreSQL with connection pooling via psycopg_pool while falling back automatically to local zero-config JSON/CSV file storage when DATABASE_URL is absent. For the complete relational entity-relationship diagram and database migration operations, see Schema & Migrations.

Installation

pip install brain-store

Quickstart

from brain_store import AlphaStore

# Connects to PostgreSQL if DATABASE_URL is set, otherwise uses ./data/
store = AlphaStore(data_dir="./data")

# Save a qualified alpha
store.save_qualified_alpha({
    "expression": "group_neutralize(rank(close), subindustry)",
    "sharpe": 1.85,
    "fitness": 1.42,
})

# Load historical expressions with pagination to prevent OOM
evaluated = store.load_evaluated_expressions(limit=500, offset=0)
print(f"Loaded {len(evaluated)} evaluated expressions.")

Note: OptionsStore is preserved as a backward-compatible alias for AlphaStore.

Architecture

brain_store/
├── brain_store/
│   ├── __init__.py        # Public re-exports (AlphaStore, OptionsStore, OptionsDatabase)
│   ├── db.py              # OptionsDatabase — connection pool, 9-table DDL, RL state
│   ├── store.py           # AlphaStore — high-level dual-mode facade
│   ├── py.typed           # PEP 561 typing marker
│   └── migrations/        # DDL migration scripts
├── tests/                 # Offline unit tests (no PostgreSQL instance required)
└── docs/
    ├── API.md             # Complete API specification
    └── SCHEMA_AND_MIGRATIONS.md # Relational schema diagram & migration runbook

Database Schema

Testing

pytest tests/ -v

Tests run offline without requiring a live PostgreSQL instance.

Security

Report vulnerabilities per SECURITY.md.

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

Released under the MIT License. Maintained by Xtley001.