Metadata-Version: 2.4
Name: ebm-splats
Version: 2.0.0
Summary: Energy-Based Model with Gaussian Splats on a 640D hypersphere — archived research project
Author: Brian Schwabauer
License: Apache-2.0
Keywords: energy-based-model,gaussian-splats,riemannian,langevin-dynamics,sentence-embeddings
Classifier: Development Status :: 7 - Inactive
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: nlp
Requires-Dist: sentence-transformers>=2.2; extra == "nlp"
Requires-Dist: transformers>=4.30; extra == "nlp"
Requires-Dist: datasets>=2.10; extra == "nlp"
Provides-Extra: gpu
Requires-Dist: faiss-cpu>=1.7; extra == "gpu"
Provides-Extra: service
Requires-Dist: flask>=3.0; extra == "service"
Provides-Extra: all
Requires-Dist: ebm-splats[dev,gpu,nlp,service]; extra == "all"
Dynamic: license-file

# EBM-Splats

> **Status: Research complete.** Phase 1-2 empirical tests finished. Energy-guided generation continued in [m2m-energy-fields](https://github.com/schwabauerbriantomas-gif/m2m-energy-fields).

Energy-Based Model with Gaussian Splats on a 640D hypersphere. Explores distributional representations for latent spaces, sampling via Langevin dynamics and Rectified Flow.

## Project Phases

### Phase 1: EBM + PGLF (April 2026) — Discarded

EBM with Gaussian splats as attractors on S^639 + PGLF (projection over MiniLM with contrastive loss).

**Result:** PGLF degraded MiniLM on STS-B (-4.7%). Projection over pre-trained embeddings always destroys geometry.

### Phase 1 Empirical: Discard Tests (July 2026)

3 empirical tests to discard or confirm alternatives. RTX 3090, real data.

| Test | Hypothesis | Result | Verdict |
|------|-----------|-----------|-----------|
| PGLF Grid (14 configs) | Can any config beat MiniLM? | 0/14 beat baseline (0.8672) | **DISCARDED** |
| OOD Detection | Does EBM energy detect OOD? | AUROC=1.0 but NN=0.999 | **NO ADVANTAGE** |
| RF vs Langevin | Does RF solve the speed bottleneck? | 24-29x faster, better quality | **CONFIRMED** |

**Key finding:** The argument that "200 Langevin steps per token" is prohibitive no longer applies. Rectified Flow with 1-2 steps produces better samples than Langevin with 200 steps, 24x faster.

### Phase 2: Energy-Guided Generation (July 2026)

EBM as a generator that learns its own latent space (not as a layer over pre-trained models), with sampling via Rectified Flow.

| Test | Hypothesis | Result | Verdict |
|------|-----------|-----------|-----------|
| Energy-Guided Generation | Can energy manipulation steer generation? | 100% topic control at gs=1.0-2.0 | **CONFIRMED** |
| Concept Composition | Can multiple concepts be combined? | 4/4 mechanisms work | **CONFIRMED** |

**Composition results:**
- Equal blend (A+B): balanced similarity to both topics
- Weighted (70/30): asymmetric control confirmed
- Suppression (A−B): sim_B dropped from 0.44 to −0.29
- Triple (A+B+C): all three topics active (sim > 0.48)

**EBM + RF enables semantic arithmetic on the hypersphere.**

## Repository Structure

```
├── src/ebm/               # Core EBM modules (geometry, splats, energy, model, etc.)
├── pglf/                  # PGLF (archived — discarded empirically)
├── scripts/               # Training and generation scripts
├── tests/
│   ├── phase1_t11_rf_vs_langevin.py    # RF vs Langevin benchmark
│   ├── phase1_t12_pglf_grid.py         # PGLF grid search
│   ├── phase1_t13_ood_energy.py        # OOD detection test
│   ├── phase2_energy_guided.py         # Energy-guided generation test
│   ├── phase2_composition.py           # Concept composition test
│   └── t*_results.jsonl                # Raw results
├── docs/
│   ├── PHASE1_RESULTS.md  # Full Phase 1 report
│   ├── PHASE2_RESULTS.md  # Phase 2 energy-guided generation report
│   └── ...
└── benchmark_results/     # Previous benchmarks
```

## Detailed Results

See [`docs/PHASE1_RESULTS.md`](docs/PHASE1_RESULTS.md) and [`docs/PHASE2_RESULTS.md`](docs/PHASE2_RESULTS.md) for full empirical test reports.

## Tech Stack

- Python, PyTorch (CUDA 12.4, RTX 3090)
- sentence-transformers, HuggingFace datasets
- Rust (M2M integration via HTTP)

## License

Apache-2.0
