Skip to content

Project Structure

Jump to bottom
Raul Montoya Cardenas edited this page Jul 29, 2026 · 2 revisions

Project Structure and Module Layout

Wiki hero

Generated with Grok Build: Grok 4.5 · xAI Imagine (/imagine)

Repository Layout

LiquidCortex.jl/
├── src/
│   ├── LiquidCortex.jl      # Module entry, __init__, exports, Sentry helper
│   ├── sparse_brain.jl      # SparseBrain, EnsembleBrain, step!, STDP, covariance
│   └── reference_lsm.jl     # 2,048-neuron dense reference LSM (lazy GPU state)
├── test/
│   └── runtests.jl          # CPU export checks + CUDA-gated GPU tests
├── examples/
│   └── brain_standalone.jl  # Hardware validation script
├── docs/
│   └── logo.png
├── .github/workflows/
│   ├── ci.yml               # Julia 1.10/1.11/1.12 smoke tests
│   ├── codecov.yml          # Coverage upload (Julia 1.11)
│   ├── sentry-release.yml   # Release create/finalize on main
│   └── sentry.yml           # PR Sentry preflight
├── Project.toml             # name LiquidCortex, version 0.2.0
├── AGENTS.md / REVIEW.md    # Agent and PR checklists
└── .env.example             # Sentry local template

Module Entry (src/LiquidCortex.jl)

On load the package:

  1. Defines const _cuda_available = Ref{Bool}(false) and _sentry_enabled.
  2. In __init__():
    • Sets _cuda_available[] = CUDA.functional().
    • If ENV["SENTRY_DSN"] is non-empty, initializes Sentry with release tag LiquidCortex.jl@<version> and package tags.
  3. Includes sparse_brain.jl then reference_lsm.jl.
  4. Exports the public API only (no domain-specific symbols).

Deferred GPU Allocation

Structs and functions are defined at load time, but GPU allocations happen in constructors / first use, not at using LiquidCortex. That means:

  • CPU-only machines load cleanly (CI smoke tests pass without a GPU).
  • SparseBrain / EnsembleBrain construction requires a working CUDA device.
  • Reference LSM state globals start as nothing and allocate on first run_lsm_step (or explicit _init_ref_lsm!).

Always gate GPU work with:

if LiquidCortex._cuda_available[]
    # GPU path
end

Sentry Capture Policy

_capture_runtime_exception wraps failures in step! / ensemble_step!:

  • No-op when Sentry is disabled.
  • Schedules Sentry.capture_exception on a task and waits at most ~50 ms (timedwait with small pollint).
  • Never blocks the rethrow path on a full Sentry queue (avoids hanging the simulation).

Architecture Map (source → responsibility)

File Responsibility
LiquidCortex.jl Module, flags, exports, Sentry init/capture
sparse_brain.jl Production sparse LSM + ensemble + STDP + covariance
reference_lsm.jl Dense 2k prototype with tanh dynamics

Design Rules (from AGENTS.md / REVIEW.md)

  • No domain-specific market/mining/telemetry code in core (removed PR #12).
  • Generic inhibition: caller provides inhibition::Real and optional reflex_signal.
  • Configurable n_in / n_out on constructors (defaults 14 / 16 for SparseBrain; 16 / 16 for reference LSM).
  • GPU tests must be gated by _cuda_available[].
  • Pin GitHub Actions to full commit SHAs; pure markdown in README (no inline HTML).

Next Steps

Last updated: July 28, 2026 Updated by: Grok Build: Grok 4.5 Package tip reference: 4e2698c (main)

Clone this wiki locally