# kapildhinwa2010-dev/fluidtech architecture

> Architecture diagram of the GitHub repository kapildhinwa2010-dev/fluidtech, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kapildhinwa2010-dev/fluidtech
- Repository: https://github.com/kapildhinwa2010-dev/fluidtech

## Overview

FluidTech is a memory layer for causal language models. The recommended workflow attaches BaseKVLayer to hidden states and token IDs: its exact tier replays seen contexts, its bounded KV window evicts old entries, and long-term memory retains each eviction with its hidden state. The README also documents optional graft, Mamba, KV-only, Ultra, and combined layers, plus quantization, acceleration, and multi-GPU support. Main-layer internals were not sampled, so those edges reflect README statements; optional implementation links are limited to explicit excerpts or index references.

Main entry points: [`fluidlayer/base_kv_layer.py`](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/base_kv_layer.py) (Base + KV), [`combined/combined_layer.py`](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/combined/combined_layer.py) (Combined layer), [`fluidlayer/blocks.py`](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/blocks.py) (Fluid block), [`fluidlayer/diffusion.py`](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/diffusion.py) (Diffusion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main["Main memory layer"]
  node_basekv["Base + KV<br/>[base_kv_layer.py]"]
  node_exact[("Exact replay<br/>[memory.py]")]
  node_kv["Bounded KV<br/>[base_kv_layer.py]"]
  node_longterm[("Long-term memory<br/>[base_kv_layer.py]")]
end

subgraph group_optional["Optional layers"]
  node_graft["Base graft"]
  node_mamba["Mamba layer"]
  node_kvonly["KV wrapper"]
  node_ultra["Ultra stack"]
  node_combined["Combined layer<br/>[combined_layer.py]"]
end

subgraph group_fluid["Fluid architecture"]
  node_fluidmodel["Fluid model<br/>[model.py]"]
  node_block["Fluid block<br/>[blocks.py]"]
  node_topology["Topology routing<br/>[topology.py]"]
  node_sheaf["Sheaf geometry<br/>[sheaf.py]"]
  node_diffusion["Diffusion<br/>[diffusion.py]"]
  node_autodiff["Autodiff engine<br/>[autodiff.py]"]
  node_graftcore["Graft variants<br/>[graft.py]"]
  node_graftref["Refactored graft"]
  node_losses["Loss functions<br/>[losses.py]"]
  node_optim["Optimizer<br/>[optim.py]"]
  node_corpus["Corpus workflow<br/>[e6_real_corpus.py]"]
end

subgraph group_features["Runtime features"]
  node_quant["Quantization<br/>[quantization.py]"]
  node_accel["Acceleration<br/>[acceleration.py]"]
  node_multigpu["Sharded KV<br/>[multi_gpu.py]"]
end

node_model_user(("Causal model"))

node_model_user -->|"attaches to"| node_basekv
node_basekv -->|"replays contexts"| node_exact
node_basekv -->|"updates window"| node_kv
node_basekv -->|"stores evictions"| node_longterm
node_basekv -.->|"optional base-only"| node_graft
node_basekv -.->|"optional alternative"| node_mamba
node_basekv -.->|"optional alternative"| node_kvonly
node_basekv -.->|"optional alternative"| node_ultra
node_basekv -.->|"optional alternative"| node_combined
node_fluidmodel -->|"uses blocks"| node_block
node_block -->|"uses tensors"| node_autodiff
node_block -->|"builds geometry"| node_topology
node_block -->|"filters bands"| node_diffusion
node_topology -->|"uses geometry"| node_sheaf
node_graftcore -->|"uses diffusion"| node_diffusion
node_graftref -->|"uses tensors"| node_autodiff
node_graftref -->|"uses diffusion"| node_diffusion
node_losses -->|"uses diffusion"| node_diffusion
node_corpus -->|"runs graft"| node_graftcore
node_corpus -->|"uses optimizer"| node_optim
node_kvonly -->|"constructs memory"| node_mamba
node_combined -->|"constructs branch"| node_mamba
node_combined -->|"constructs stack"| node_ultra
node_combined -->|"constructs branch"| node_graft
node_combined -->|"constructs cache"| node_kvonly
node_basekv -.->|"supports quantization"| node_quant
node_basekv -.->|"supports acceleration"| node_accel
node_basekv -.->|"supports sharding"| node_multigpu

click node_basekv "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/base_kv_layer.py"
click node_exact "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/memory.py"
click node_kv "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/base_kv_layer.py"
click node_longterm "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/base_kv_layer.py"
click node_graft "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/graft_bulletproof.py"
click node_mamba "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/experiments/superfluid_mamba_layer.py"
click node_kvonly "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/kv_cache/constant_kv_superfluid.py"
click node_ultra "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/experiments/ultra_fluid_layer.py"
click node_combined "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/combined/combined_layer.py"
click node_fluidmodel "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/model.py"
click node_block "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/blocks.py"
click node_topology "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/topology.py"
click node_sheaf "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/sheaf.py"
click node_diffusion "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/diffusion.py"
click node_autodiff "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/autodiff.py"
click node_graftcore "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/graft.py"
click node_graftref "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/graft_refactored.py"
click node_losses "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/losses.py"
click node_optim "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/optim.py"
click node_corpus "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/experiments/e6_real_corpus.py"
click node_quant "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/quantization.py"
click node_accel "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/acceleration.py"
click node_multigpu "https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/multi_gpu.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_basekv,node_exact,node_kv,node_longterm toneBlue
class node_graft,node_mamba,node_kvonly,node_ultra,node_combined toneAmber
class node_fluidmodel,node_block,node_topology,node_sheaf,node_diffusion,node_autodiff,node_graftcore,node_graftref,node_losses,node_optim,node_corpus toneMint
class node_quant,node_accel,node_multigpu toneRose
class node_model_user toneIndigo
```

## Components

### Main memory layer

- [Base + KV](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/base_kv_layer.py): `fluidlayer/base_kv_layer.py`
- [Exact replay](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/memory.py): `fluidlayer/memory.py`
- [Bounded KV](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/base_kv_layer.py): `fluidlayer/base_kv_layer.py`
- [Long-term memory](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/base_kv_layer.py): `fluidlayer/base_kv_layer.py`

### Optional layers

- [Base graft](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/graft_bulletproof.py): `fluidlayer/graft_bulletproof.py`
- [Mamba layer](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/experiments/superfluid_mamba_layer.py): `experiments/superfluid_mamba_layer.py`
- [KV wrapper](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/kv_cache/constant_kv_superfluid.py): `kv_cache/constant_kv_superfluid.py`
- [Ultra stack](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/experiments/ultra_fluid_layer.py): `experiments/ultra_fluid_layer.py`
- [Combined layer](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/combined/combined_layer.py): `combined/combined_layer.py`

### Fluid architecture

- [Fluid model](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/model.py): `fluidlayer/model.py`
- [Fluid block](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/blocks.py): `fluidlayer/blocks.py`
- [Topology routing](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/topology.py): `fluidlayer/topology.py`
- [Sheaf geometry](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/sheaf.py): `fluidlayer/sheaf.py`
- [Diffusion](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/diffusion.py): `fluidlayer/diffusion.py`
- [Autodiff engine](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/autodiff.py): `fluidlayer/autodiff.py`
- [Graft variants](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/graft.py): `fluidlayer/graft.py`
- [Refactored graft](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/graft_refactored.py): `fluidlayer/graft_refactored.py`
- [Loss functions](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/losses.py): `fluidlayer/losses.py`
- [Optimizer](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/optim.py): `fluidlayer/optim.py`
- [Corpus workflow](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/experiments/e6_real_corpus.py): `experiments/e6_real_corpus.py`

### Runtime features

- [Quantization](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/quantization.py): `fluidlayer/quantization.py`
- [Acceleration](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/acceleration.py): `fluidlayer/acceleration.py`
- [Sharded KV](https://github.com/kapildhinwa2010-dev/fluidtech/blob/main/fluidlayer/multi_gpu.py): `fluidlayer/multi_gpu.py`

### Other components

- **Causal model**

## Connections

- Causal model → Base + KV: attaches to
- Base + KV → Exact replay: replays contexts
- Base + KV → Bounded KV: updates window
- Base + KV → Long-term memory: stores evictions
- Base + KV → Base graft: optional base-only
- Base + KV → Mamba layer: optional alternative
- Base + KV → KV wrapper: optional alternative
- Base + KV → Ultra stack: optional alternative
- Base + KV → Combined layer: optional alternative
- Fluid model → Fluid block: uses blocks (evidence: `fluidlayer/model.py`)
- Fluid block → Autodiff engine: uses tensors (evidence: `fluidlayer/blocks.py`)
- Fluid block → Topology routing: builds geometry (evidence: `fluidlayer/blocks.py`)
- Fluid block → Diffusion: filters bands (evidence: `fluidlayer/blocks.py`)
- Topology routing → Sheaf geometry: uses geometry (evidence: `fluidlayer/topology.py`)
- Graft variants → Diffusion: uses diffusion (evidence: `fluidlayer/graft.py`)
- Refactored graft → Autodiff engine: uses tensors (evidence: `fluidlayer/graft_refactored.py`)
- Refactored graft → Diffusion: uses diffusion (evidence: `fluidlayer/graft_refactored.py`)
- Loss functions → Diffusion: uses diffusion (evidence: `fluidlayer/losses.py`)
- Corpus workflow → Graft variants: runs graft (evidence: `experiments/e6_real_corpus.py`)
- Corpus workflow → Optimizer: uses optimizer (evidence: `experiments/e6_real_corpus.py`)
- KV wrapper → Mamba layer: constructs memory (evidence: `kv_cache/constant_kv_superfluid.py`)
- Combined layer → Mamba layer: constructs branch (evidence: `combined/combined_layer.py`)
- Combined layer → Ultra stack: constructs stack (evidence: `combined/combined_layer.py`)
- Combined layer → Base graft: constructs branch (evidence: `combined/combined_layer.py`)
- Combined layer → KV wrapper: constructs cache (evidence: `combined/combined_layer.py`)
- Base + KV → Quantization: supports quantization
- Base + KV → Acceleration: supports acceleration
- Base + KV → Sharded KV: supports sharding