brain-store 0.1.0__tar.gz

brain_store-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xtley001
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brain_store-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: brain-store
+Version: 0.1.0
+Summary: Dual-mode persistence layer (PostgreSQL + file-backed) and RL state store for Brain Alpha pipelines.
+Author: Xtley001
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Xtley001/brain-alpha-pipeline
+Project-URL: Repository, https://github.com/Xtley001/brain-alpha-pipeline
+Project-URL: Documentation, https://github.com/Xtley001/brain-alpha-pipeline/tree/main/brain_libraries
+Project-URL: Bug Tracker, https://github.com/Xtley001/brain-alpha-pipeline/issues
+Keywords: worldquant,brain,alpha,quantitative-finance,postgresql,state-persistence,reinforcement-learning,storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Database
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: brain-core>=0.1.0
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: psycopg_pool>=3.2
+Requires-Dist: alembic>=1.13
+Requires-Dist: numpy>=1.26
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# brain-store
+
+Dual-mode persistence layer (PostgreSQL connection pool + flat-file fallback) and RL state store for Brain Alpha pipelines.
+
+[![CI](https://img.shields.io/github/actions/workflow/status/Xtley001/brain-alpha-pipeline/ci.yml?branch=main)](https://github.com/Xtley001/brain-alpha-pipeline/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/brain-store)](https://pypi.org/project/brain-store/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+`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](./docs/SCHEMA_AND_MIGRATIONS.md).
+
+## Installation
+
+```bash
+pip install brain-store
+```
+
+## Quickstart
+
+```python
+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
+
+| Table | Purpose | Indexing Strategy |
+|---|---|---|
+| `options_alphas` | Live alpha reserve vault | Unique on `alpha_id`, Index on `status`, `category` |
+| `options_evaluations` | Simulation backtest audit log | Index on `alpha_id`, `simulated_at` |
+| `options_strategy_rl_state` | Strategy-level reinforcement learning operator weights | Primary key on `strategy_name` |
+| `options_learning_memory` | Global Multi-Armed Bandit expression reward tracking | Primary key on `expression_hash` |
+| `options_rejected_alphas` | Diagnostics for checklist / gate-failed alphas | Index on `failure_reason` |
+| `options_correlated_alphas` | Audit log of correlation gate rejections (|rho| >= 0.70) | Index on `candidate_id` |
+| `cluster_session_cache` | Distributed BRAIN auth session token caching (2h TTL) | Primary key on `session_key` |
+| `cluster_run_lock` | Distributed mutex preventing duplicate simulation runs | Primary key on `lock_name` |
+| `org_runs` | Runner heartbeat and telemetry monitoring | Primary key on `run_id` |
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+Tests run offline without requiring a live PostgreSQL instance.
+
+## Security
+
+Report vulnerabilities per [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+## License
+
+Released under the [MIT License](../LICENSE). Maintained by [Xtley001](https://github.com/Xtley001).

brain_store-0.1.0/README.md

@@ -0,0 +1,88 @@
+# brain-store
+
+Dual-mode persistence layer (PostgreSQL connection pool + flat-file fallback) and RL state store for Brain Alpha pipelines.
+
+[![CI](https://img.shields.io/github/actions/workflow/status/Xtley001/brain-alpha-pipeline/ci.yml?branch=main)](https://github.com/Xtley001/brain-alpha-pipeline/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/brain-store)](https://pypi.org/project/brain-store/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+`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](./docs/SCHEMA_AND_MIGRATIONS.md).
+
+## Installation
+
+```bash
+pip install brain-store
+```
+
+## Quickstart
+
+```python
+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
+
+| Table | Purpose | Indexing Strategy |
+|---|---|---|
+| `options_alphas` | Live alpha reserve vault | Unique on `alpha_id`, Index on `status`, `category` |
+| `options_evaluations` | Simulation backtest audit log | Index on `alpha_id`, `simulated_at` |
+| `options_strategy_rl_state` | Strategy-level reinforcement learning operator weights | Primary key on `strategy_name` |
+| `options_learning_memory` | Global Multi-Armed Bandit expression reward tracking | Primary key on `expression_hash` |
+| `options_rejected_alphas` | Diagnostics for checklist / gate-failed alphas | Index on `failure_reason` |
+| `options_correlated_alphas` | Audit log of correlation gate rejections (|rho| >= 0.70) | Index on `candidate_id` |
+| `cluster_session_cache` | Distributed BRAIN auth session token caching (2h TTL) | Primary key on `session_key` |
+| `cluster_run_lock` | Distributed mutex preventing duplicate simulation runs | Primary key on `lock_name` |
+| `org_runs` | Runner heartbeat and telemetry monitoring | Primary key on `run_id` |
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+Tests run offline without requiring a live PostgreSQL instance.
+
+## Security
+
+Report vulnerabilities per [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+## License
+
+Released under the [MIT License](../LICENSE). Maintained by [Xtley001](https://github.com/Xtley001).

brain_store-0.1.0/brain_store/__init__.py

@@ -0,0 +1,18 @@
+"""
+brain_store — persistence layer for the Brain Alpha Engine.
+
+Public API
+----------
+OptionsDatabase  : PostgreSQL adapter. Owns all DDL, DML, and RL state ops.
+AlphaStore       : High-level store facade combining CSV/JSON + Postgres.
+OptionsStore     : Deprecated alias for AlphaStore (backwards-compatibility).
+"""
+from brain_store.db import OptionsDatabase, map_archetype_to_core
+from brain_store.store import AlphaStore, OptionsStore
+
+__all__ = [
+    "OptionsDatabase",
+    "map_archetype_to_core",
+    "AlphaStore",
+    "OptionsStore",
+]

brain_store-0.1.0/brain_store/db.py

@@ -0,0 +1,505 @@
+"""
+PostgreSQL adapter for brain_store.
+
+DATABASE SCHEMA — 7 Tables
+==========================
+1. options_alphas          — Qualified alpha pool (status: QUALIFIED | SUBMITTED).
+2. options_evaluations     — Immutable audit log of every simulation run.
+3. options_learning_memory — MAB reinforcement-learning memory (one row per expression).
+4. options_rejected_alphas — Alphas that failed BRAIN platform checklist gates.
+5. options_correlated_alphas — Alphas that failed self-correlation < 0.70 gate.
+6. cluster_session_cache   — Shared BRAIN session token cache across worker orgs.
+7. cluster_run_lock        — Cluster-wide mutex: prevents > 1 org simulating at once.
+
+All tables use IF NOT EXISTS — safe to run on first boot and on upgrades.
+
+This module is extracted from brain_options/store/db.py.
+It owns ALL DDL and DML. No other module may issue raw SQL.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import math
+import re
+import time
+from typing import Any, Dict, List, Optional, Set
+
+try:
+    from psycopg_pool import ConnectionPool
+except ImportError:
+    ConnectionPool = None  # type: ignore[assignment,misc]
+
+log = logging.getLogger("brain_store.db")
+
+# ── Schema DDL ────────────────────────────────────────────────────────────
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS options_alphas (
+    id               SERIAL PRIMARY KEY,
+    alpha_id         VARCHAR(64),
+    expression       TEXT        NOT NULL,
+    archetype        VARCHAR(128),
+    hypothesis       TEXT,
+    source           VARCHAR(32),
+    sharpe           NUMERIC(8, 4),
+    fitness          NUMERIC(8, 4),
+    turnover         NUMERIC(8, 4),
+    returns          NUMERIC(8, 4),
+    drawdown         NUMERIC(8, 4),
+    margin           NUMERIC(10, 6),
+    max_correlation  NUMERIC(8, 4),
+    universe         VARCHAR(32),
+    neutralization   VARCHAR(32),
+    delay            INTEGER,
+    decay            INTEGER,
+    truncation       NUMERIC(6, 4),
+    pasteurization   VARCHAR(8),
+    nan_handling     VARCHAR(8),
+    status           VARCHAR(32) DEFAULT 'QUALIFIED',
+    submitted_at     TIMESTAMPTZ,
+    created_at       TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS options_evaluations (
+    id          SERIAL PRIMARY KEY,
+    expression  TEXT        NOT NULL,
+    archetype   VARCHAR(128),
+    source      VARCHAR(32),
+    stage       VARCHAR(32),
+    status      VARCHAR(32),
+    sharpe      NUMERIC(8, 4),
+    fitness     NUMERIC(8, 4),
+    turnover    NUMERIC(8, 4),
+    returns     NUMERIC(8, 4),
+    drawdown    NUMERIC(8, 4),
+    alpha_id    VARCHAR(64),
+    created_at  TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS options_learning_memory (
+    id             SERIAL PRIMARY KEY,
+    expression     TEXT UNIQUE NOT NULL,
+    reward_score   NUMERIC(10, 4) DEFAULT 0,
+    sample_count   INTEGER DEFAULT 0,
+    success_count  INTEGER DEFAULT 0,
+    fail_count     INTEGER DEFAULT 0,
+    last_updated   TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS options_rejected_alphas (
+    id          SERIAL PRIMARY KEY,
+    expression  TEXT        NOT NULL,
+    archetype   VARCHAR(128),
+    sharpe      NUMERIC(8, 4),
+    fitness     NUMERIC(8, 4),
+    reason      TEXT,
+    created_at  TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS options_correlated_alphas (
+    id               SERIAL PRIMARY KEY,
+    expression       TEXT        NOT NULL,
+    archetype        VARCHAR(128),
+    sharpe           NUMERIC(8, 4),
+    fitness          NUMERIC(8, 4),
+    max_correlation  NUMERIC(8, 4),
+    corr_partner_id  VARCHAR(64),
+    created_at       TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS cluster_session_cache (
+    org_id       VARCHAR(64) PRIMARY KEY,
+    session_data TEXT        NOT NULL,
+    updated_at   TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS cluster_run_lock (
+    lock_key    VARCHAR(64) PRIMARY KEY,
+    holder_org  VARCHAR(64),
+    acquired_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+"""
+
+# ── Database class ────────────────────────────────────────────────────────
+
+class OptionsDatabase:
+    """
+    Low-level PostgreSQL adapter.
+
+    Manages a psycopg_pool ConnectionPool and exposes typed read/write
+    methods for every table. All raw SQL lives in this class.
+
+    Parameters
+    ----------
+    database_url : PostgreSQL DSN, e.g. "postgresql://user:pass@host/db".
+                   When None the pool is not created and all operations
+                   are silently no-ops (file-only mode).
+    pool_min     : Minimum pool connections (default 1).
+    pool_max     : Maximum pool connections (default 5).
+    """
+
+    def __init__(
+        self,
+        database_url: Optional[str],
+        pool_min: int = 1,
+        pool_max: int = 5,
+    ) -> None:
+        self._pool: Optional[Any] = None
+        if database_url and ConnectionPool is not None:
+            try:
+                self._pool = ConnectionPool(
+                    database_url,
+                    min_size=pool_min,
+                    max_size=pool_max,
+                    open=True,
+                )
+                self._init_schema()
+                log.info("brain_store: PostgreSQL pool initialised (min=%d max=%d)", pool_min, pool_max)
+            except Exception as exc:
+                log.error("brain_store: Failed to connect to PostgreSQL: %s", exc)
+                self._pool = None
+
+    def is_available(self) -> bool:
+        """Return True if a live PostgreSQL connection pool is available."""
+        return self._pool is not None
+
+    # ── Schema init ───────────────────────────────────────────────────────
+
+    def _init_schema(self) -> None:
+        """Create tables if they do not already exist."""
+        if self._pool is None:
+            return
+        try:
+            with self._pool.connection() as conn:
+                conn.execute(SCHEMA_SQL)
+                conn.commit()
+            log.info("brain_store: Schema initialised.")
+        except Exception as exc:
+            log.warning("brain_store: Schema init error (may be benign on concurrent start): %s", exc)
+
+    # ── Deduplication helpers ─────────────────────────────────────────────
+
+    def load_evaluated_expressions(self) -> Set[str]:
+        """Return the set of all expressions ever evaluated (from options_evaluations)."""
+        if self._pool is None:
+            return set()
+        result: Set[str] = set()
+        try:
+            with self._pool.connection() as conn:
+                rows = conn.execute("SELECT expression FROM options_evaluations").fetchall()
+                for row in rows:
+                    result.add(row[0])
+        except Exception as exc:
+            log.warning("brain_store: load_evaluated_expressions failed: %s", exc)
+        return result
+
+    # ── Alpha pool writes ─────────────────────────────────────────────────
+
+    def save_qualified_alpha(self, record: Dict[str, Any]) -> None:
+        """
+        Insert one row into options_alphas (status=QUALIFIED).
+
+        Parameters
+        ----------
+        record : dict with keys matching the options_alphas columns.
+                 Required: expression (str).
+                 Optional: alpha_id, archetype, hypothesis, source,
+                           sharpe, fitness, turnover, returns, drawdown,
+                           margin, max_correlation, universe,
+                           neutralization, delay, decay, truncation,
+                           pasteurization, nan_handling.
+        """
+        if self._pool is None:
+            return
+        try:
+            with self._pool.connection() as conn:
+                conn.execute(
+                    """
+                    INSERT INTO options_alphas
+                        (alpha_id, expression, archetype, hypothesis, source,
+                         sharpe, fitness, turnover, returns, drawdown, margin,
+                         max_correlation, universe, neutralization, delay, decay,
+                         truncation, pasteurization, nan_handling, status)
+                    VALUES
+                        (%(alpha_id)s, %(expression)s, %(archetype)s,
+                         %(hypothesis)s, %(source)s,
+                         %(sharpe)s, %(fitness)s, %(turnover)s, %(returns)s,
+                         %(drawdown)s, %(margin)s, %(max_correlation)s,
+                         %(universe)s, %(neutralization)s, %(delay)s, %(decay)s,
+                         %(truncation)s, %(pasteurization)s, %(nan_handling)s,
+                         'QUALIFIED')
+                    """,
+                    record,
+                )
+                conn.commit()
+        except Exception as exc:
+            log.error("brain_store: save_qualified_alpha failed: %s", exc)
+
+    def log_evaluation(self, record: Dict[str, Any]) -> None:
+        """
+        Append one row to options_evaluations (immutable audit log).
+
+        Required keys: expression (str), stage (str), status (str).
+        Optional keys: archetype, source, sharpe, fitness, turnover,
+                       returns, drawdown, alpha_id.
+        """
+        if self._pool is None:
+            return
+        try:
+            with self._pool.connection() as conn:
+                conn.execute(
+                    """
+                    INSERT INTO options_evaluations
+                        (expression, archetype, source, stage, status,
+                         sharpe, fitness, turnover, returns, drawdown, alpha_id)
+                    VALUES
+                        (%(expression)s, %(archetype)s, %(source)s,
+                         %(stage)s, %(status)s,
+                         %(sharpe)s, %(fitness)s, %(turnover)s,
+                         %(returns)s, %(drawdown)s, %(alpha_id)s)
+                    """,
+                    record,
+                )
+                conn.commit()
+        except Exception as exc:
+            log.error("brain_store: log_evaluation failed: %s", exc)
+
+    # ── MAB / RL state ────────────────────────────────────────────────────
+
+    def upsert_rl_reward(self, expression: str, delta: float) -> None:
+        """
+        Add *delta* to the reward_score for *expression* in options_learning_memory.
+
+        Uses ON CONFLICT DO UPDATE for idempotent upsert.
+        Increments sample_count by 1 each call.
+        Increments success_count if delta > 0, fail_count if delta < 0.
+        """
+        if self._pool is None:
+            return
+        try:
+            with self._pool.connection() as conn:
+                conn.execute(
+                    """
+                    INSERT INTO options_learning_memory
+                        (expression, reward_score, sample_count,
+                         success_count, fail_count, last_updated)
+                    VALUES
+                        (%(expr)s, %(delta)s, 1,
+                         CASE WHEN %(delta)s > 0 THEN 1 ELSE 0 END,
+                         CASE WHEN %(delta)s < 0 THEN 1 ELSE 0 END,
+                         CURRENT_TIMESTAMP)
+                    ON CONFLICT (expression) DO UPDATE SET
+                        reward_score  = options_learning_memory.reward_score + %(delta)s,
+                        sample_count  = options_learning_memory.sample_count + 1,
+                        success_count = options_learning_memory.success_count
+                                      + CASE WHEN %(delta)s > 0 THEN 1 ELSE 0 END,
+                        fail_count    = options_learning_memory.fail_count
+                                      + CASE WHEN %(delta)s < 0 THEN 1 ELSE 0 END,
+                        last_updated  = CURRENT_TIMESTAMP
+                    """,
+                    {"expr": expression, "delta": delta},
+                )
+                conn.commit()
+        except Exception as exc:
+            log.error("brain_store: upsert_rl_reward failed: %s", exc)
+
+    def load_top_performing_exemplars(
+        self,
+        limit: int = 5,
+        min_sharpe: float = 1.0,
+        exclude_archetypes: Optional[List[str]] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Return up to *limit* rows from options_alphas ordered by sharpe DESC.
+
+        Filters: sharpe >= min_sharpe, status IN ('QUALIFIED', 'SUBMITTED').
+        Excludes rows whose archetype is in *exclude_archetypes* (if given).
+        """
+        if self._pool is None:
+            return []
+        try:
+            excl = exclude_archetypes or []
+            with self._pool.connection() as conn:
+                rows = conn.execute(
+                    """
+                    SELECT expression, archetype, sharpe, fitness, turnover
+                    FROM   options_alphas
+                    WHERE  sharpe >= %(min_sharpe)s
+                      AND  status IN ('QUALIFIED', 'SUBMITTED')
+                      AND  (%(excl_len)s = 0 OR archetype != ALL(%(excl)s))
+                    ORDER  BY sharpe DESC
+                    LIMIT  %(limit)s
+                    """,
+                    {
+                        "min_sharpe": min_sharpe,
+                        "excl": excl,
+                        "excl_len": len(excl),
+                        "limit": limit,
+                    },
+                ).fetchall()
+                return [
+                    {"expression": r[0], "archetype": r[1],
+                     "sharpe": float(r[2] or 0), "fitness": float(r[3] or 0),
+                     "turnover": float(r[4] or 0)}
+                    for r in rows
+                ]
+        except Exception as exc:
+            log.warning("brain_store: load_top_performing_exemplars failed: %s", exc)
+            return []
+
+    def load_archetype_performance_summary(self) -> Dict[str, Any]:
+        """
+        Return a dict mapping archetype_name -> {win_rate, avg_sharpe, total_runs}.
+        Computed from options_evaluations where status == 'PASS'.
+        """
+        if self._pool is None:
+            return {}
+        try:
+            with self._pool.connection() as conn:
+                rows = conn.execute(
+                    """
+                    SELECT
+                        archetype,
+                        COUNT(*)                                            AS total_runs,
+                        COUNT(*) FILTER (WHERE status = 'PASS')            AS wins,
+                        AVG(sharpe) FILTER (WHERE status = 'PASS')         AS avg_sharpe
+                    FROM   options_evaluations
+                    WHERE  archetype IS NOT NULL
+                    GROUP  BY archetype
+                    """
+                ).fetchall()
+            result: Dict[str, Any] = {}
+            for row in rows:
+                arch, total, wins, avg_sh = row
+                result[arch] = {
+                    "total_runs": int(total),
+                    "win_rate": round(int(wins) / max(int(total), 1), 4),
+                    "avg_sharpe": round(float(avg_sh or 0), 4),
+                }
+            return result
+        except Exception as exc:
+            log.warning("brain_store: load_archetype_performance_summary failed: %s", exc)
+            return {}
+
+    def save_correlated_alpha(self, record: Dict[str, Any]) -> None:
+        """Insert one row into options_correlated_alphas."""
+        if self._pool is None:
+            return
+        try:
+            with self._pool.connection() as conn:
+                conn.execute(
+                    """
+                    INSERT INTO options_correlated_alphas
+                        (expression, archetype, sharpe, fitness,
+                         max_correlation, corr_partner_id)
+                    VALUES
+                        (%(expression)s, %(archetype)s, %(sharpe)s,
+                         %(fitness)s, %(max_correlation)s, %(corr_partner_id)s)
+                    """,
+                    record,
+                )
+                conn.commit()
+        except Exception as exc:
+            log.error("brain_store: save_correlated_alpha failed: %s", exc)
+
+    def save_rejected_alpha(self, record: Dict[str, Any]) -> None:
+        """Insert one row into options_rejected_alphas."""
+        if self._pool is None:
+            return
+        try:
+            with self._pool.connection() as conn:
+                conn.execute(
+                    """
+                    INSERT INTO options_rejected_alphas
+                        (expression, archetype, sharpe, fitness, reason)
+                    VALUES
+                        (%(expression)s, %(archetype)s, %(sharpe)s,
+                         %(fitness)s, %(reason)s)
+                    """,
+                    record,
+                )
+                conn.commit()
+        except Exception as exc:
+            log.error("brain_store: save_rejected_alpha failed: %s", exc)
+
+    def close(self) -> None:
+        """Close the connection pool gracefully."""
+        if self._pool is not None:
+            try:
+                self._pool.close()
+            except Exception:
+                pass
+
+
+def map_archetype_to_core(archetype_name: str) -> str:
+    """
+    Normalises arbitrary archetype labels (from LLM output, mutation tags, etc.)
+    to the canonical 30-strategy taxonomy.
+    """
+    if not archetype_name:
+        return "forward_basis"
+    name = archetype_name.lower().strip()
+
+    if "dynamic_short_squeeze" in name or "dynamic short squeeze" in name or "borrow fee convexity" in name:
+        return "dynamic_short_squeeze"
+    elif "days_to_cover" in name or "days-to-cover" in name or "days to cover" in name:
+        return "short_interest"
+    elif "vpin" in name or "toxicity" in name or "order_flow" in name:
+        return "order_flow_vpin"
+    elif "gamma" in name or "pinning" in name:
+        return "gamma_pinning_clustering"
+    elif "customer" in name or "cascades" in name or "customer_supplier" in name:
+        return "customer_supplier_cascades"
+    elif "rd_" in name or "r&d" in name or "spillover" in name:
+        return "rd_capitalization_spillovers"
+    elif "capex" in name or "asset_growth" in name or "asset growth" in name:
+        return "capex_asset_growth"
+    elif "peavrp" in name or "vrp compression" in name or "vrp crush" in name:
+        return "peavrp_volatility_premia"
+    elif "jump" in name or "realized_jump" in name:
+        return "realized_jump_intensity"
+    elif "default" in name or "merton" in name or "distance_to_default" in name:
+        return "distance_to_default_debt"
+    elif "macro" in name or "fomc" in name or "cpi" in name:
+        return "macro_fomc_cpi_drift"
+    elif "patent" in name or "innovation" in name:
+        return "patent_innovation_efficiency"
+    elif "peavd" in name:
+        return "peavd_earnings_vol_drift"
+    elif "insider" in name or "cluster" in name:
+        return "insider_cluster_buying"
+    elif "13f" in name or "institutional" in name or "breadth" in name:
+        return "institutional_13f_breadth"
+    elif "supply_chain" in name or "supply chain" in name:
+        return "supply_chain"
+    elif "informed_short" in name or "informed short" in name:
+        return "informed_short_demand"
+    elif "extreme_tail" in name or "tail_risk" in name or "extreme tail" in name:
+        return "extreme_tail_risk"
+    elif "iv_lead" in name or "lead_lag" in name or "lead lag" in name:
+        return "iv_lead_lag"
+    elif "network_momentum" in name or "network momentum" in name:
+        return "network_momentum"
+    elif "accruals" in name or "sloan" in name or "cashflow" in name:
+        return "accruals_cashflow"
+    elif "formulaic" in name or "101" in name or "kakushadze" in name:
+        return "formulaic_101"
+    elif "hybrid" in name or "confluence" in name or "divergence" in name:
+        return "hybrid_confluence"
+    elif "breakeven" in name:
+        return "breakeven"
+    elif "skew" in name or "smirk" in name:
+        return "skew"
+    elif "term_structure" in name or "term structure" in name or "vrp" in name or "variance" in name or "parkinson" in name:
+        return "term_structure"
+    elif "forward" in name or "basis" in name:
+        return "forward_basis"
+    elif "pcr" in name or "put-call" in name or "put_call" in name or "flow" in name:
+        return "pcr_flow"
+    elif "analyst" in name or "revision" in name or "dispersion" in name or "pead" in name or "target_price" in name or "price target" in name or "sales" in name:
+        return "analyst_revisions"
+    elif "short" in name or "borrow" in name or "days_to_cover" in name:
+        return "short_interest"
+    return name
+

brain_store-0.1.0/brain_store/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

brain_store-0.1.0/brain_store/store.py

@@ -0,0 +1,200 @@
+"""
+OptionsStore — high-level facade over OptionsDatabase + flat-file storage.
+
+Combines Postgres (via OptionsDatabase) with local CSV/JSON flat files so
+the pipeline can survive without a database connection (file-only mode).
+
+CSV/JSON files written
+----------------------
+passed_options_alphas.csv   — all qualified alphas (append-only)
+passed_options_alphas.json  — same data in JSON (overwritten on each save)
+rejected_options_alphas.csv — all rejected alphas
+correlated_options_alphas.csv — all correlated alphas
+evaluated_candidates.csv    — full evaluation history
+pnl_series/<alpha_id>.json  — cached PnL vectors for correlation checks
+"""
+from __future__ import annotations
+
+import csv
+import json
+import logging
+import os
+import threading
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Set
+
+from brain_store.db import OptionsDatabase
+
+log = logging.getLogger("brain_store.store")
+
+_SENTINEL = object()
+
+_PASSED_CSV_HEADER = [
+    "expression", "archetype", "hypothesis", "source",
+    "sharpe", "fitness", "turnover", "returns", "drawdown",
+    "margin", "universe", "neutralization", "delay", "decay",
+    "truncation", "pasteurization", "nan_handling",
+    "alpha_id", "status", "created_at",
+]
+
+_HISTORY_CSV_HEADER = [
+    "expression", "archetype", "source", "stage", "status",
+    "sharpe", "fitness", "turnover", "returns", "drawdown",
+    "alpha_id", "created_at",
+]
+
+
+class AlphaStore:
+    """
+    High-level store facade.
+
+    Parameters
+    ----------
+    data_dir     : Directory for CSV/JSON files.
+                   Defaults to <package_root>/data.
+    database_url : PostgreSQL DSN. Pass None to disable Postgres.
+                   Defaults to DATABASE_URL env var.
+    """
+
+    def __init__(
+        self,
+        data_dir: Optional[str] = None,
+        database_url: Any = _SENTINEL,
+    ) -> None:
+        if data_dir is None:
+            data_dir = os.path.join(
+                os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "data"
+            )
+        self.data_dir = data_dir
+        os.makedirs(self.data_dir, exist_ok=True)
+
+        self.passed_csv = os.path.join(self.data_dir, "passed_options_alphas.csv")
+        self.passed_json = os.path.join(self.data_dir, "passed_options_alphas.json")
+        self.rejected_csv = os.path.join(self.data_dir, "rejected_options_alphas.csv")
+        self.correlated_csv = os.path.join(self.data_dir, "correlated_options_alphas.csv")
+        self.history_csv = os.path.join(self.data_dir, "evaluated_candidates.csv")
+        self.pnl_cache_dir = os.path.join(self.data_dir, "pnl_series")
+        os.makedirs(self.pnl_cache_dir, exist_ok=True)
+
+        if database_url is _SENTINEL:
+            database_url = os.getenv("DATABASE_URL")
+
+        self.db = OptionsDatabase(database_url)
+        self._write_lock = threading.Lock()
+
+    def __repr__(self) -> str:
+        return f"AlphaStore(data_dir={self.data_dir!r}, postgres_enabled={self.db.is_available()})"
+
+    # ── Deduplication ─────────────────────────────────────────────────────
+
+    def load_evaluated_expressions(
+        self, limit: Optional[int] = None, offset: int = 0
+    ) -> Set[str]:
+        """Return the set of all expressions previously evaluated, with optional limit/offset pagination."""
+        evaluated: Set[str] = set()
+        if os.path.exists(self.history_csv):
+            try:
+                with open(self.history_csv, "r", encoding="utf-8") as f:
+                    count = 0
+                    for idx, row in enumerate(csv.DictReader(f)):
+                        if idx < offset:
+                            continue
+                        if limit is not None and count >= limit:
+                            break
+                        expr = row.get("expression")
+                        if expr:
+                            evaluated.add(expr.strip())
+                            count += 1
+            except Exception as exc:
+                log.warning("Could not read evaluated history CSV: %s", exc)
+        try:
+            evaluated.update(self.db.load_evaluated_expressions())
+        except Exception as exc:
+            log.warning("Could not read evaluated expressions from DB: %s", exc)
+        return evaluated
+
+    # ── Qualified alpha writes ────────────────────────────────────────────
+
+    def save_qualified_alpha(self, record: Dict[str, Any]) -> None:
+        """
+        Persist a qualified alpha to both CSV/JSON and Postgres.
+
+        *record* must contain 'expression'. All other fields are optional.
+        """
+        record.setdefault("created_at", datetime.now(timezone.utc).isoformat())
+        record.setdefault("status", "QUALIFIED")
+        with self._write_lock:
+            self._append_csv(self.passed_csv, _PASSED_CSV_HEADER, record)
+            self._rewrite_json(self.passed_csv, self.passed_json, _PASSED_CSV_HEADER)
+        self.db.save_qualified_alpha(record)
+
+    # ── Evaluation log ────────────────────────────────────────────────────
+
+    def log_evaluation(self, record: Dict[str, Any]) -> None:
+        """Append a simulation result to the evaluation history."""
+        record.setdefault("created_at", datetime.now(timezone.utc).isoformat())
+        with self._write_lock:
+            self._append_csv(self.history_csv, _HISTORY_CSV_HEADER, record)
+        self.db.log_evaluation(record)
+
+    # ── Top-performing exemplars ──────────────────────────────────────────
+
+    def load_top_performing_exemplars(
+        self,
+        limit: int = 5,
+        min_sharpe: float = 1.0,
+        exclude_archetypes: Optional[List[str]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Return up to *limit* best-performing alphas from Postgres."""
+        return self.db.load_top_performing_exemplars(
+            limit=limit,
+            min_sharpe=min_sharpe,
+            exclude_archetypes=exclude_archetypes,
+        )
+
+    def load_archetype_performance_summary(self) -> Dict[str, Any]:
+        """Return win rates and avg Sharpe per archetype from Postgres."""
+        return self.db.load_archetype_performance_summary()
+
+    # ── PnL cache ─────────────────────────────────────────────────────────
+
+    def cache_pnl(self, alpha_id: str, pnl: List[float]) -> None:
+        """Write *pnl* list to pnl_series/<alpha_id>.json."""
+        path = os.path.join(self.pnl_cache_dir, f"{alpha_id}.json")
+        with self._write_lock:
+            with open(path, "w", encoding="utf-8") as f:
+                json.dump(pnl, f)
+
+    def load_pnl(self, alpha_id: str) -> Optional[List[float]]:
+        """Return cached PnL list or None if not present."""
+        path = os.path.join(self.pnl_cache_dir, f"{alpha_id}.json")
+        if not os.path.exists(path):
+            return None
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+
+    # ── Private helpers ───────────────────────────────────────────────────
+
+    def _append_csv(
+        self, path: str, header: List[str], record: Dict[str, Any]
+    ) -> None:
+        write_header = not os.path.exists(path)
+        with open(path, "a", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=header, extrasaction="ignore")
+            if write_header:
+                writer.writeheader()
+            writer.writerow(record)
+
+    def _rewrite_json(
+        self, csv_path: str, json_path: str, header: List[str]
+    ) -> None:
+        rows: List[Dict[str, Any]] = []
+        if os.path.exists(csv_path):
+            with open(csv_path, "r", encoding="utf-8") as f:
+                rows = list(csv.DictReader(f))
+        with open(json_path, "w", encoding="utf-8") as f:
+            json.dump(rows, f, indent=2)
+
+
+# Backwards-compatibility alias (deprecated in favor of AlphaStore)
+OptionsStore = AlphaStore

brain_store-0.1.0/brain_store.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: brain-store
+Version: 0.1.0
+Summary: Dual-mode persistence layer (PostgreSQL + file-backed) and RL state store for Brain Alpha pipelines.
+Author: Xtley001
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Xtley001/brain-alpha-pipeline
+Project-URL: Repository, https://github.com/Xtley001/brain-alpha-pipeline
+Project-URL: Documentation, https://github.com/Xtley001/brain-alpha-pipeline/tree/main/brain_libraries
+Project-URL: Bug Tracker, https://github.com/Xtley001/brain-alpha-pipeline/issues
+Keywords: worldquant,brain,alpha,quantitative-finance,postgresql,state-persistence,reinforcement-learning,storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Database
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: brain-core>=0.1.0
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: psycopg_pool>=3.2
+Requires-Dist: alembic>=1.13
+Requires-Dist: numpy>=1.26
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# brain-store
+
+Dual-mode persistence layer (PostgreSQL connection pool + flat-file fallback) and RL state store for Brain Alpha pipelines.
+
+[![CI](https://img.shields.io/github/actions/workflow/status/Xtley001/brain-alpha-pipeline/ci.yml?branch=main)](https://github.com/Xtley001/brain-alpha-pipeline/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/brain-store)](https://pypi.org/project/brain-store/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+`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](./docs/SCHEMA_AND_MIGRATIONS.md).
+
+## Installation
+
+```bash
+pip install brain-store
+```
+
+## Quickstart
+
+```python
+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
+
+| Table | Purpose | Indexing Strategy |
+|---|---|---|
+| `options_alphas` | Live alpha reserve vault | Unique on `alpha_id`, Index on `status`, `category` |
+| `options_evaluations` | Simulation backtest audit log | Index on `alpha_id`, `simulated_at` |
+| `options_strategy_rl_state` | Strategy-level reinforcement learning operator weights | Primary key on `strategy_name` |
+| `options_learning_memory` | Global Multi-Armed Bandit expression reward tracking | Primary key on `expression_hash` |
+| `options_rejected_alphas` | Diagnostics for checklist / gate-failed alphas | Index on `failure_reason` |
+| `options_correlated_alphas` | Audit log of correlation gate rejections (|rho| >= 0.70) | Index on `candidate_id` |
+| `cluster_session_cache` | Distributed BRAIN auth session token caching (2h TTL) | Primary key on `session_key` |
+| `cluster_run_lock` | Distributed mutex preventing duplicate simulation runs | Primary key on `lock_name` |
+| `org_runs` | Runner heartbeat and telemetry monitoring | Primary key on `run_id` |
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+Tests run offline without requiring a live PostgreSQL instance.
+
+## Security
+
+Report vulnerabilities per [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+## License
+
+Released under the [MIT License](../LICENSE). Maintained by [Xtley001](https://github.com/Xtley001).

brain_store-0.1.0/brain_store.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+brain_store/__init__.py
+brain_store/db.py
+brain_store/py.typed
+brain_store/store.py
+brain_store.egg-info/PKG-INFO
+brain_store.egg-info/SOURCES.txt
+brain_store.egg-info/dependency_links.txt
+brain_store.egg-info/requires.txt
+brain_store.egg-info/top_level.txt
+tests/test_db_offline.py
+tests/test_store_file_mode.py

brain_store-0.1.0/brain_store.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

brain_store-0.1.0/brain_store.egg-info/requires.txt

@@ -0,0 +1,13 @@
+brain-core>=0.1.0
+psycopg[binary]>=3.1
+psycopg_pool>=3.2
+alembic>=1.13
+numpy>=1.26
+python-dotenv>=1.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23
+black
+flake8
+mypy

brain_store-0.1.0/brain_store.egg-info/top_level.txt

@@ -0,0 +1 @@
+brain_store

brain_store-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brain-store"
+version = "0.1.0"
+description = "Dual-mode persistence layer (PostgreSQL + file-backed) and RL state store for Brain Alpha pipelines."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Xtley001" }]
+keywords = [
+    "worldquant",
+    "brain",
+    "alpha",
+    "quantitative-finance",
+    "postgresql",
+    "state-persistence",
+    "reinforcement-learning",
+    "storage",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Database",
+]
+dependencies = [
+    "brain-core>=0.1.0",
+    "psycopg[binary]>=3.1",
+    "psycopg_pool>=3.2",
+    "alembic>=1.13",
+    "numpy>=1.26",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "black", "flake8", "mypy"]
+
+[project.urls]
+Homepage = "https://github.com/Xtley001/brain-alpha-pipeline"
+Repository = "https://github.com/Xtley001/brain-alpha-pipeline"
+Documentation = "https://github.com/Xtley001/brain-alpha-pipeline/tree/main/brain_libraries"
+"Bug Tracker" = "https://github.com/Xtley001/brain-alpha-pipeline/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["brain_store*"]
+
+[tool.setuptools.package-data]
+brain_store = ["py.typed"]

brain_store-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brain_store-0.1.0/tests/test_db_offline.py

@@ -0,0 +1,53 @@
+"""
+Unit tests for brain_store.db — offline (no PostgreSQL required).
+
+All tests use database_url=None so no real connection is made.
+Acceptance criteria: all methods must be no-ops and not raise when pool=None.
+"""
+from brain_store.db import OptionsDatabase
+
+
+def make_db() -> OptionsDatabase:
+    return OptionsDatabase(database_url=None)
+
+
+def test_load_evaluated_expressions_offline():
+    db = make_db()
+    result = db.load_evaluated_expressions()
+    assert result == set()
+
+
+def test_save_qualified_alpha_offline():
+    db = make_db()
+    db.save_qualified_alpha({"expression": "rank(close)", "sharpe": 1.5})
+    # No exception expected
+
+
+def test_log_evaluation_offline():
+    db = make_db()
+    db.log_evaluation({"expression": "rank(close)", "stage": "STAGE0", "status": "PASS"})
+
+
+def test_upsert_rl_reward_offline():
+    db = make_db()
+    db.upsert_rl_reward("rank(close)", delta=10.0)
+
+
+def test_load_top_performing_exemplars_offline():
+    db = make_db()
+    assert db.load_top_performing_exemplars() == []
+
+
+def test_load_archetype_performance_summary_offline():
+    db = make_db()
+    assert db.load_archetype_performance_summary() == {}
+
+
+def test_save_correlated_alpha_offline():
+    db = make_db()
+    db.save_correlated_alpha({"expression": "rank(close)", "max_correlation": 0.85})
+
+
+def test_save_rejected_alpha_offline():
+    db = make_db()
+    db.save_rejected_alpha({"expression": "rank(close)", "reason": "low sharpe"})

brain_store-0.1.0/tests/test_store_file_mode.py

@@ -0,0 +1,65 @@
+"""
+Unit tests for brain_store.store.OptionsStore — file-only mode (no Postgres).
+
+Uses a tmp_path fixture so no real CSV/JSON files are created in the repo.
+
+Acceptance criteria
+-------------------
+AC-1  save_qualified_alpha() creates passed_options_alphas.csv.
+AC-2  log_evaluation() creates evaluated_candidates.csv.
+AC-3  load_evaluated_expressions() returns expressions from the CSV.
+AC-4  cache_pnl/load_pnl round-trip works correctly.
+"""
+import os
+import pytest
+from brain_store.store import OptionsStore
+
+
+@pytest.fixture
+def store(tmp_path):
+    return OptionsStore(data_dir=str(tmp_path), database_url=None)
+
+
+def test_ac1_save_qualified_alpha(store, tmp_path):
+    store.save_qualified_alpha({"expression": "rank(close)", "sharpe": 1.5, "fitness": 1.1})
+    assert os.path.exists(os.path.join(str(tmp_path), "passed_options_alphas.csv"))
+
+
+def test_ac2_log_evaluation(store, tmp_path):
+    store.log_evaluation({"expression": "rank(close)", "stage": "STAGE0", "status": "PASS"})
+    assert os.path.exists(os.path.join(str(tmp_path), "evaluated_candidates.csv"))
+
+
+def test_ac3_load_evaluated_expressions(store):
+    store.log_evaluation({"expression": "rank(close)", "stage": "STAGE0", "status": "PASS"})
+    store.log_evaluation({"expression": "rank(volume)", "stage": "STAGE0", "status": "FAIL"})
+    exprs = store.load_evaluated_expressions()
+    assert "rank(close)" in exprs
+    assert "rank(volume)" in exprs
+
+
+def test_ac4_pnl_cache_round_trip(store):
+    pnl = [0.01, -0.02, 0.03]
+    store.cache_pnl("test_alpha_001", pnl)
+    loaded = store.load_pnl("test_alpha_001")
+    assert loaded == pnl
+
+
+def test_load_pnl_missing_returns_none(store):
+    assert store.load_pnl("nonexistent_id") is None
+
+
+def test_alphastore_alias_and_repr(tmp_path):
+    from brain_store import AlphaStore, OptionsStore
+    assert AlphaStore is OptionsStore
+    s = AlphaStore(data_dir=str(tmp_path), database_url=None)
+    assert repr(s).startswith("AlphaStore(")
+    assert s.db.is_available() is False
+
+
+def test_load_evaluated_expressions_pagination(store):
+    store.log_evaluation({"expression": "expr_1", "stage": "STAGE0", "status": "PASS"})
+    store.log_evaluation({"expression": "expr_2", "stage": "STAGE0", "status": "PASS"})
+    store.log_evaluation({"expression": "expr_3", "stage": "STAGE0", "status": "PASS"})
+    page = store.load_evaluated_expressions(limit=2, offset=0)
+    assert len(page) == 2