# sparticle62ops/pssa architecture

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

- Interactive diagram: https://gitdiagram.com/sparticle62ops/pssa
- Repository: https://github.com/sparticle62ops/pssa

## Overview

PSSA is a Rust language-model runtime centered on recurrent state-space processing, episodic memory, and plastic updates. Its main workflow is corpus preparation and tokenization, model training, checkpointing, then generation or held-out evaluation. A parameter-matched transformer baseline supports comparison. The graph preserves major README capabilities; relationships not visible in the supplied excerpts or README are omitted rather than inferred.

Main entry points: [`src/cli.rs`](https://github.com/sparticle62ops/pssa/blob/main/src/cli.rs) (CLI workflows), [`src/pssa.rs`](https://github.com/sparticle62ops/pssa/blob/main/src/pssa.rs) (PSSA recurrent model), [`src/comparison.rs`](https://github.com/sparticle62ops/pssa/blob/main/src/comparison.rs) (Model comparison), [`src/dataset.rs`](https://github.com/sparticle62ops/pssa/blob/main/src/dataset.rs) (Dataset and tokenizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_dataset["Dataset and tokenizer<br/>[dataset.rs]"]
end

subgraph group_pssa["PSSA model"]
  node_pssa_model["PSSA recurrent model<br/>[pssa.rs]"]
  node_memory["Episodic memory bank<br/>[memory.rs]"]
  node_adapter["Plastic adapter<br/>[adapter.rs]"]
end

subgraph group_runtime["Training and runtime"]
  node_cli["CLI workflows<br/>[cli.rs]"]
  node_training["PSSA training<br/>[training.rs]"]
  node_batch["Sequence batching<br/>[sequence_batch.rs]"]
  node_checkpoint["PSSA checkpoints<br/>[checkpoint.rs]"]
  node_inference["PSSA generation<br/>[inference.rs]"]
  node_evaluation["Held-out evaluation<br/>[evaluation.rs]"]
  node_loss["Loss reporting<br/>[loss_csv.rs]"]
  node_ui["Training interface<br/>[ui.rs]"]
end

subgraph group_baseline["Transformer baseline"]
  node_transformer["Transformer model<br/>[transformer.rs]"]
  node_transformer_training["Transformer training"]
  node_transformer_checkpoint["Transformer checkpoints"]
  node_transformer_inference["Transformer generation"]
  node_comparison["Model comparison<br/>[comparison.rs]"]
end

subgraph group_compute["Numerical compute"]
  node_gpu_batch["GPU batch kernels<br/>[gpu_batch.rs]"]
  node_backend["Compute backend<br/>[backend.rs]"]
  node_linalg["Linear algebra<br/>[linalg.rs]"]
end

node_user(("User"))
node_corpus["Text corpus"]

node_user -->|"runs workflows"| node_cli
node_corpus -->|"loads and tokenizes"| node_dataset
node_cli -->|"loads corpus"| node_dataset
node_cli -->|"starts training"| node_training
node_training -->|"plans token chunks"| node_dataset
node_training -.->|"trains model"| node_pssa_model
node_pssa_model -->|"reads and writes"| node_memory
node_pssa_model -->|"uses adapter"| node_adapter
node_pssa_model -->|"dispatches compute"| node_backend
node_pssa_model -->|"uses operations"| node_linalg
node_batch -->|"uses checkpoint types"| node_checkpoint
node_gpu_batch -->|"batches model work"| node_pssa_model
node_gpu_batch -->|"uses memory operations"| node_memory
node_gpu_batch -->|"dispatches kernels"| node_backend
node_gpu_batch -->|"uses operations"| node_linalg
node_cli -->|"loads and saves"| node_checkpoint
node_cli -->|"generates text"| node_inference
node_cli -->|"scores models"| node_evaluation
node_cli -->|"configures loss output"| node_loss
node_cli -->|"renders interface"| node_ui
node_inference -->|"uses tokenizer"| node_dataset
node_inference -->|"runs model"| node_pssa_model
node_evaluation -->|"encodes corpus"| node_dataset
node_evaluation -->|"scores model"| node_pssa_model
node_cli -->|"starts baseline training"| node_transformer_training
node_transformer_training -->|"loads token data"| node_dataset
node_transformer_training -->|"trains model"| node_transformer
node_transformer_training -->|"resumes model"| node_transformer_checkpoint
node_transformer_training -->|"imports tokenizer"| node_checkpoint
node_transformer_inference -->|"loads model"| node_transformer_checkpoint
node_transformer_inference -->|"runs model"| node_transformer
node_transformer_inference -->|"reuses sampler"| node_inference
node_transformer_inference -->|"loads corpus"| node_dataset
node_transformer_inference -->|"evaluates model"| node_evaluation
node_comparison -->|"compares scores"| node_evaluation
node_comparison -->|"runs PSSA training"| node_training
node_comparison -->|"runs baseline training"| node_transformer_training
node_comparison -->|"compares model"| node_transformer
node_comparison -->|"uses baseline checkpoint"| node_transformer_checkpoint
node_comparison -->|"uses PSSA checkpoint"| node_checkpoint

click node_dataset "https://github.com/sparticle62ops/pssa/blob/main/src/dataset.rs"
click node_cli "https://github.com/sparticle62ops/pssa/blob/main/src/cli.rs"
click node_training "https://github.com/sparticle62ops/pssa/blob/main/src/training.rs"
click node_batch "https://github.com/sparticle62ops/pssa/blob/main/src/sequence_batch.rs"
click node_gpu_batch "https://github.com/sparticle62ops/pssa/blob/main/src/gpu_batch.rs"
click node_pssa_model "https://github.com/sparticle62ops/pssa/blob/main/src/pssa.rs"
click node_memory "https://github.com/sparticle62ops/pssa/blob/main/src/memory.rs"
click node_adapter "https://github.com/sparticle62ops/pssa/blob/main/src/adapter.rs"
click node_backend "https://github.com/sparticle62ops/pssa/blob/main/src/backend.rs"
click node_linalg "https://github.com/sparticle62ops/pssa/blob/main/src/linalg.rs"
click node_checkpoint "https://github.com/sparticle62ops/pssa/blob/main/src/checkpoint.rs"
click node_inference "https://github.com/sparticle62ops/pssa/blob/main/src/inference.rs"
click node_evaluation "https://github.com/sparticle62ops/pssa/blob/main/src/evaluation.rs"
click node_loss "https://github.com/sparticle62ops/pssa/blob/main/src/loss_csv.rs"
click node_ui "https://github.com/sparticle62ops/pssa/blob/main/src/ui.rs"
click node_transformer "https://github.com/sparticle62ops/pssa/blob/main/src/transformer.rs"
click node_transformer_training "https://github.com/sparticle62ops/pssa/blob/main/src/transformer_training.rs"
click node_transformer_checkpoint "https://github.com/sparticle62ops/pssa/blob/main/src/transformer_checkpoint.rs"
click node_transformer_inference "https://github.com/sparticle62ops/pssa/blob/main/src/transformer_inference.rs"
click node_comparison "https://github.com/sparticle62ops/pssa/blob/main/src/comparison.rs"

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_dataset,node_user toneBlue
class node_pssa_model,node_memory,node_adapter toneAmber
class node_cli,node_training,node_batch,node_checkpoint,node_inference,node_evaluation,node_loss,node_ui toneMint
class node_transformer,node_transformer_training,node_transformer_checkpoint,node_transformer_inference,node_comparison toneRose
class node_gpu_batch,node_backend,node_linalg,node_corpus toneIndigo
```

## Components

### Data preparation

- [Dataset and tokenizer](https://github.com/sparticle62ops/pssa/blob/main/src/dataset.rs): `src/dataset.rs`

### PSSA model

- [PSSA recurrent model](https://github.com/sparticle62ops/pssa/blob/main/src/pssa.rs): `src/pssa.rs`
- [Episodic memory bank](https://github.com/sparticle62ops/pssa/blob/main/src/memory.rs): `src/memory.rs`
- [Plastic adapter](https://github.com/sparticle62ops/pssa/blob/main/src/adapter.rs): `src/adapter.rs`

### Training and runtime

- [CLI workflows](https://github.com/sparticle62ops/pssa/blob/main/src/cli.rs): `src/cli.rs`
- [PSSA training](https://github.com/sparticle62ops/pssa/blob/main/src/training.rs): `src/training.rs`
- [Sequence batching](https://github.com/sparticle62ops/pssa/blob/main/src/sequence_batch.rs): `src/sequence_batch.rs`
- [PSSA checkpoints](https://github.com/sparticle62ops/pssa/blob/main/src/checkpoint.rs): `src/checkpoint.rs`
- [PSSA generation](https://github.com/sparticle62ops/pssa/blob/main/src/inference.rs): `src/inference.rs`
- [Held-out evaluation](https://github.com/sparticle62ops/pssa/blob/main/src/evaluation.rs): `src/evaluation.rs`
- [Loss reporting](https://github.com/sparticle62ops/pssa/blob/main/src/loss_csv.rs): `src/loss_csv.rs`
- [Training interface](https://github.com/sparticle62ops/pssa/blob/main/src/ui.rs): `src/ui.rs`

### Transformer baseline

- [Transformer model](https://github.com/sparticle62ops/pssa/blob/main/src/transformer.rs): `src/transformer.rs`
- [Transformer training](https://github.com/sparticle62ops/pssa/blob/main/src/transformer_training.rs): `src/transformer_training.rs`
- [Transformer checkpoints](https://github.com/sparticle62ops/pssa/blob/main/src/transformer_checkpoint.rs): `src/transformer_checkpoint.rs`
- [Transformer generation](https://github.com/sparticle62ops/pssa/blob/main/src/transformer_inference.rs): `src/transformer_inference.rs`
- [Model comparison](https://github.com/sparticle62ops/pssa/blob/main/src/comparison.rs): `src/comparison.rs`

### Numerical compute

- [GPU batch kernels](https://github.com/sparticle62ops/pssa/blob/main/src/gpu_batch.rs): `src/gpu_batch.rs`
- [Compute backend](https://github.com/sparticle62ops/pssa/blob/main/src/backend.rs): `src/backend.rs`
- [Linear algebra](https://github.com/sparticle62ops/pssa/blob/main/src/linalg.rs): `src/linalg.rs`

### Other components

- **User**
- **Text corpus**

## Connections

- User → CLI workflows: runs workflows (evidence: `src/cli.rs`)
- Text corpus → Dataset and tokenizer: loads and tokenizes (evidence: `src/dataset.rs`)
- CLI workflows → Dataset and tokenizer: loads corpus (evidence: `src/cli.rs`)
- CLI workflows → PSSA training: starts training (evidence: `src/cli.rs`)
- PSSA training → Dataset and tokenizer: plans token chunks (evidence: `src/training.rs`)
- PSSA training → PSSA recurrent model: trains model
- PSSA recurrent model → Episodic memory bank: reads and writes (evidence: `src/pssa.rs`)
- PSSA recurrent model → Plastic adapter: uses adapter (evidence: `src/pssa.rs`)
- PSSA recurrent model → Compute backend: dispatches compute (evidence: `src/pssa.rs`)
- PSSA recurrent model → Linear algebra: uses operations (evidence: `src/pssa.rs`)
- Sequence batching → PSSA checkpoints: uses checkpoint types (evidence: `src/sequence_batch.rs`)
- GPU batch kernels → PSSA recurrent model: batches model work (evidence: `src/gpu_batch.rs`)
- GPU batch kernels → Episodic memory bank: uses memory operations (evidence: `src/gpu_batch.rs`)
- GPU batch kernels → Compute backend: dispatches kernels (evidence: `src/gpu_batch.rs`)
- GPU batch kernels → Linear algebra: uses operations (evidence: `src/gpu_batch.rs`)
- CLI workflows → PSSA checkpoints: loads and saves (evidence: `src/cli.rs`)
- CLI workflows → PSSA generation: generates text (evidence: `src/cli.rs`)
- CLI workflows → Held-out evaluation: scores models (evidence: `src/cli.rs`)
- CLI workflows → Loss reporting: configures loss output (evidence: `src/cli.rs`)
- CLI workflows → Training interface: renders interface (evidence: `src/cli.rs`)
- PSSA generation → Dataset and tokenizer: uses tokenizer (evidence: `src/inference.rs`)
- PSSA generation → PSSA recurrent model: runs model (evidence: `src/inference.rs`)
- Held-out evaluation → Dataset and tokenizer: encodes corpus (evidence: `src/evaluation.rs`)
- Held-out evaluation → PSSA recurrent model: scores model (evidence: `src/evaluation.rs`)
- CLI workflows → Transformer training: starts baseline training (evidence: `src/cli.rs`)
- Transformer training → Dataset and tokenizer: loads token data (evidence: `src/transformer_training.rs`)
- Transformer training → Transformer model: trains model (evidence: `src/transformer_training.rs`)
- Transformer training → Transformer checkpoints: resumes model (evidence: `src/transformer_training.rs`)
- Transformer training → PSSA checkpoints: imports tokenizer (evidence: `src/transformer_training.rs`)
- Transformer generation → Transformer checkpoints: loads model (evidence: `src/transformer_inference.rs`)
- Transformer generation → Transformer model: runs model (evidence: `src/transformer_inference.rs`)
- Transformer generation → PSSA generation: reuses sampler (evidence: `src/transformer_inference.rs`)
- Transformer generation → Dataset and tokenizer: loads corpus (evidence: `src/transformer_inference.rs`)
- Transformer generation → Held-out evaluation: evaluates model (evidence: `src/transformer_inference.rs`)
- Model comparison → Held-out evaluation: compares scores (evidence: `src/comparison.rs`)
- Model comparison → PSSA training: runs PSSA training (evidence: `src/comparison.rs`)
- Model comparison → Transformer training: runs baseline training (evidence: `src/comparison.rs`)
- Model comparison → Transformer model: compares model (evidence: `src/comparison.rs`)
- Model comparison → Transformer checkpoints: uses baseline checkpoint (evidence: `src/comparison.rs`)
- Model comparison → PSSA checkpoints: uses PSSA checkpoint (evidence: `src/comparison.rs`)