🧠 FlowAI — Zunifikowany i Oszczędny Pakiet LLM

"Prostota jest nie tylko estetyką – jest strategią ograniczania błędów."

flow_ai to zoptymalizowany pakiet modeli językowych dla PyTorch. Powstał z połączenia 5 paradygmatów obliczeniowych, eliminując wąskie gardła pamięciowe i architektoniczne tradycyjnych Transformerów.

---

🔍 Kluczowe Mechanizmy Architektury

1. Faktoryzowany Routing Przepływów (hyper_router.py)

Zamiast mnożyć wejście przez gigantyczną, gęstą macierz wag $W \in \mathbb{R}^{d \times d}$, tokeny są rzutowane na bazę $K$ wyuczonych wzorców przepływu $P \in \mathbb{R}^{K \times d_{out} \times d_{in}}$.

• Oszczędność VRAM: Zastosowanie faktoryzowanego iloczynu tensorowego einsum: $$x_{\text{patterns}} = \text{einsum}(\text{'pij,bsj->bspi'}, P, x) \quad \to \quad y = \text{einsum}(\text{'bsp,bspi->bsi'}, \text{weights}, x_{\text{patterns}})$$ eliminuje tworzenie wielkich tensorów 4D, redukując zużycie pamięci GPU o ~98%.

2. Wielokanałowy Routing Podprzestrzeni (Multi-Channel Subspace Routing)

(W pierwotnych prototypach zwany metaforą „RGB”). Model dynamicznie dzieli reprezentację każdego słowa na $C$ funkcjonalnych kanałów podprzestrzeni (domyślnie 3):

• Kanał 1 (Leksykalny): Cechy bezpośrednie słowa (reprezentacja słownikowa).
• Kanał 2 (Strukturalny): Zależności składniowe i relacje do słów sąsiednich.
• Kanał 3 (Kontekstowy): Sens globalny całego akapitu lub konwersacji.

Dla każdego tokenu sieć oblicza dynamiczny wektor wag $\alpha = \text{Softmax}(\text{Linear}(x)) \in [0, 1]^3$, który moduluje aktywację wzorców w locie.

3. Mostek Pamięci Konceptualnej (memory.py)

W klasycznych modelach LLM cała historia rozmowy musi być przesyłana w tekście promptu, co spowalnia działanie. Mostek ConceptualMemoryBridge:

• Pobiera wyekstrahowany graf pojęć z modułu conceptualhcm.py.
• Poprzez algorytm spreading activation wybiera tylko kluczowe aktywne pojęcia.
• Wstrzykuje je jako zwarty tensor cech bezpośrednio do warstwy Cross-Attention.

4. Przestrzenna Pamięć Asocjacyjna Hilberta (spatial.py)

Wykorzystuje 2D krzywą Hilberta do rzutowania ciągłych wektorów cech na dyskretne komórki przestrzenne:

• Zachowanie lokalności: Wektory o podobnym znaczeniu trafiają do bliskich współrzędnych Hilberta.
• Odczyt w czasie $O(1)$: Umożliwia błyskawiczny cache powtarzających się fraz bez przeszukiwania całej bazy kluczy.

5. Strażnik Integralności i Samonaprawa Wag (guard.py)

W urządzeniach brzegowych (Edge AI) przekłamania pamięci RAM/VRAM (bit-flips) niszczą wagi modelu. TensorStateGuard:

• Koduje wagi w systemie Zeckendorfa (ciąg Fibonacciego), który wyklucza występowanie dwóch jedynek bitowych obok siebie (11).
• Weryfikuje sumy kontrolne CRC32 i potrójną redundancję (TMR).
• Automatycznie wykrywa i naprawia uszkodzone wagi podczas wczytywania checkpointu.

---

📦 Struktura Plików

Plik	Klasa Główna	Opis
core.py	UnifiedFlowTransformer	Główny model językowy z obsługą autoregresji (generate()).
hyper_router.py	HyperFlowRouter	Wielokanałowy mikser podprzestrzeni i faktoryzowany einsum.
memory.py	ConceptualMemoryBridge	Mostek wstrzykujący wektory pojęć do Cross-Attention.
spatial.py	HilbertSpatialCache	Przestrzenna pamięć asocjacyjna $O(1)$ na krzywej Hilberta.
guard.py	TensorStateGuard	Ochrona i samonaprawa wag modeli (Fibitrix / CRC32).
benchmark.py	run_all_benchmarks	Obiektywny zestaw testów zbieżności i wydajności.
__init__.py	—	Eksportuje spójny interfejs API pakietu.
__main__.py	—	Szybkie testy jednostkowe (python -m flow_ai).

---

🚀 Szybki Start i Przykłady

1. Uruchomienie Obiektywnego Audytu i Benchmarku:

python flow_ai/benchmark.py

2. Podstawowe Użycie (Generowanie Tekstu):

import torch
from flow_ai import UnifiedFlowTransformer

# Inicjalizacja modelu
model = UnifiedFlowTransformer(
    vocab_size=1000,
    d_model=256,
    num_layers=4,
    num_patterns=8,
    num_heads=8
)

# Generowanie sekwencji tokenów
prompt = torch.tensor([[10, 25, 42]])
output_tokens = model.generate(prompt, max_new_tokens=16, temperature=0.7)
print("Wygenerowane tokeny:", output_tokens.tolist()[0])

3. Wstrzykiwanie Pamięci Konceptualnej:

# 4 wektory wyekstrahowanych pojęć (np. z ConceptualHCM)
concept_embeddings = torch.randn(4, 256)

# Forward pass z aktywną pamięcią długoterminową
logits, metrics = model(prompt, concept_embeddings=concept_embeddings)

4. Bezpieczny Zapis i Weryfikacja Wag:

from flow_ai import TensorStateGuard

# Zapis z sumami kontrolnymi
TensorStateGuard.save_guarded_checkpoint(model, "model_guarded.pt")

# Wczytanie i samonaprawa
is_valid, report = TensorStateGuard.load_and_verify_checkpoint(model, "model_guarded.pt")
print(f"Status integralności wag: {report['status']}")