Architecture

Architecture and development

Component map

cli/main.py
  └─ PySide6 QApplication and native OpenGL setup
       └─ MainWindow
            ├─ ChatPanel
            ├─ GenerationWorker (QThread)
            │    └─ LlamaBackend → local GGUF + read-only raw-logit probe
            └─ VisualizerPanel
                 ├─ telemetry display-graph generator
                 ├─ ActivityField and ActivityMapper
                 ├─ ConnectomeRenderer (QOpenGLWidget + ModernGL)
                 └─ ConnectomeAnalyzer / exporter

Every GUI entry point except the installer checks the managed virtual environment before importing application modules. cli/main.py, cli/diagnostic.py, and cli/analysis.py show the shared loader while their first background validation runs, retain their attached console for runtime output, configure feature-scoped logs (aibrain.<feature>.log), and create a detailed crash.<feature>.log only after an uncaught exception. cli/main.py additionally requests desktop OpenGL and installs SIGINT handling.

MainWindow owns conversation state and coordinates UI signals. It discovers and validates models, owns the worker thread, updates the thinking indicator, and saves generation settings.

GenerationWorker owns streaming inference work away from the UI thread. LlamaBackend attaches a read-only logits processor before each completion is sampled. Each visible text chunk carries raw-logit statistics; the worker combines them with observed context, timing, retokenized output, and repetition values in a normalized ActivationFrame labelled Real-time. ActivityMapper maps those nine channel values onto a display field. User display controls never alter the frame supplied to ConnectomeAnalyzer.

Key modules

The dashboard primitives in src/app/dashboard.py are shared by inspection surfaces. ConnectomeAnalyzer owns the version-tolerant NPZ contract and automatic maturity transitions. Diagnostics separates current dynamic process output from completed output lines so carriage-return progress does not become duplicate log text. Repairs are targeted: refreshing validation does not delete models, DLLs, or broad cache directories; stale-manifest removal is the only destructive action and always requires confirmation.

Path	Responsibility
cli/installer.py	Creates and populates the managed Python virtual environment.
src/utils/console_ui.py	Shared terminal presentation, native console clearing, and safe output wrapping.
cli/build_dist.py	Creates timestamped self-contained ai_brain, diagnostic, and analysis distributions.
src/models/ollama_discovery.py	Finds and performs lightweight validation of local Ollama blobs.
src/models/model_validator.py	Validates candidates against llama.cpp and caches profile-scoped GGUF results.
src/models/llama_backend.py	Loads and streams GGUF models while collecting raw pre-sampler logit metrics.
src/models/instrumented_backend.py	Defines and normalizes the real-time telemetry frame contract.
src/connectome/generator.py	Creates deterministic display topology for the nine measurement channels.
src/connectome/activity.py	Separates measured channel values from decaying, user-adjustable display intensity.
src/connectome/renderer.py	Batched ModernGL 3D/2D draw pipeline, sector filtering, and interaction.
src/connectome/analysis.py	Online analysis of normalized real-time telemetry channels.
src/native/c/connectome_kernels.c	Optional native hot-path implementation.
src/native/wrapper/connectome_kernels.py	ctypes contract and NumPy fallback for dll/aibrain.connectome.dll.

Development workflow

1. Create dependencies with py cli\installer.py.

2. Activate .venv before running validation or the application.

3. Rebuild the DLL after changing C code.

4. Compile Python modules before handing off a change:

   python -m compileall -q cli src tests

5. Start the app manually to validate native-window, model-discovery, and GPU behavior on the target machine. Model loading and graphics adapter selection depend on local hardware and installed models.

Contributing principles

• Keep the UI native Qt; do not introduce browser, React, Electron, or WebView components.
• Preserve the venv-only runtime guard.
• Keep Real-time limited to values observed during active generation. Name raw-logit values as pre-sampler data.
• Keep display nodes and links explicitly separate from transformer neurons, layers, and physical model topology.
• Keep heavy inference work off the Qt UI thread.
• Preserve NumPy fallbacks for optional native-DLL acceleration.
• Update the relevant document when user-visible behavior changes.