README.md

---
title: GASM Enhanced - Geometric Language AI
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.16.0
app_file: app.py
pinned: false
license: cc-by-nd-4.0
---

# 🚀 GASM Enhanced - Geometric Attention for Spatial Understanding

> *Bridging natural language and geometric reasoning through SE(3)-invariant neural architectures*

## What Makes This Different?

Traditional AI understands *what* objects are mentioned, but struggles with *where* they are and *how* they relate spatially. GASM changes this.

**GASM** (Geometric Attention for Spatial & Mathematical understanding) represents a breakthrough in AI spatial reasoning:

- **🧠 Advanced NLP**: Goes beyond keywords with spaCy + semantic categorization  
- **📐 Proper 3D Math**: Uses SE(3) Lie groups for mathematically correct spatial relationships
- **🔄 Geometric Optimization**: Minimizes curvature on Riemannian manifolds for optimal layouts
- **✨ Real-time Visualization**: Shows spatial understanding in live 3D geometry

## 🌟 What This Enables

### The Spatial Intelligence Gap
Current language models excel at:
- ✅ "What is a keyboard?" → *An input device*
- ❌ "Where is the keyboard relative to the monitor?" → *Spatial confusion*

GASM bridges this gap through mathematical spatial reasoning.

### Real Applications
This isn't just a demo - GASM addresses actual problems in:
- **🤖 Robotics**: "Move the component above the platform" → Precise 3D coordinates
- **🔬 Scientific Modeling**: "The electron orbits the nucleus" → Proper geometric relationships  
- **🏗️ Engineering**: "Place the support between the beams" → Constraint satisfaction
- **🥽 AR/VR**: Natural language to 3D scene understanding

## 🎯 Try It Yourself

### Watch GASM in Action

Input any sentence with spatial relationships:

> *"The ball lies left of the table next to the computer, while the book sits between the keyboard and the monitor."*

**GASM Output:**
- ✅ **6 entities identified**: ball, table, computer, book, keyboard, monitor
- 🔗 **5 spatial relations**: left_of, next_to, between
- 🌌 **3D geometric layout** with proper SE(3) positioning  
- 📈 **Curvature evolution** showing geometric convergence

### More Examples

**🤖 Robotics**: *"The robotic arm moves the satellite component above the assembly platform."*

**🔬 Scientific**: *"The electron orbits the nucleus while the magnetic field flows through the crystal."*  

**🏠 Everyday**: *"The red car parks between two buildings near the park entrance."*

### What You'll See
1. **Advanced Entity Recognition**: Far beyond simple keyword matching
2. **Spatial Relationship Extraction**: Understands "left of", "between", "above" in context  
3. **3D Visualization**: Real geometric positioning in proper 3D space
4. **Mathematical Convergence**: Curvature evolution showing optimization progress

## 📁 Project Structure

```
GASM-Huggingface/
├── app.py                    # Main Gradio application with complete interface
├── gasm_core.py             # Core GASM implementation with SE(3) math
├── fastapi_endpoint.py      # Optional API endpoints (standalone)
├── requirements.txt         # Python dependencies
└── README.md               # This file
```

## 🧮 The Mathematics Behind GASM

### What Makes It Special

Unlike traditional NLP that treats text as sequences of tokens, GASM understands geometry:

**1. SE(3) Invariant Processing**
- Uses Special Euclidean Group SE(3) for proper 3D transformations
- Maintains mathematical correctness under rotations and translations
- Employs Lie group operations for geometric learning

**2. Advanced Entity Recognition**  
- **spaCy NLP**: Part-of-speech tagging + named entity recognition
- **Semantic Filtering**: Domain-specific vocabularies (robotics, scientific, everyday)
- **Contextual Understanding**: Extracts objects from spatial prepositions

**3. Geometric Optimization**
- **Geodesic Distances**: Shortest paths on SE(3) manifold
- **Discrete Curvature**: Graph Laplacian eigenvalue-based computation
- **Energy Minimization**: Constraint satisfaction via Lagrange multipliers

### Technical Architecture

```
Text → spaCy NLP → Entity Extraction → Semantic Filtering
  ↓
SE(3) Embedding → Attention Mechanism → Geometric Refinement  
  ↓
Constraint Satisfaction → Curvature Optimization → 3D Visualization
```

### Why This Matters

Most AI systems use simple word embeddings that lose spatial meaning. GASM preserves geometric relationships through mathematically principled operations, enabling true spatial understanding.

## 🎨 Visualizations

The Space provides two main visualizations:

### 1. Curvature Evolution Plot
- Shows geometric convergence over iterations
- Displays SE(3) manifold optimization progress
- Uses matplotlib with dark theme for clarity

### 2. 3D Entity Space Plot
- Interactive 3D positioning of extracted entities
- Color-coded by entity type (robotic, physical, spatial, etc.)
- Shows relationship connections between entities

## 🔬 How It Works

1. **Text Input**: User provides text for analysis
2. **Entity Extraction**: Regex-based extraction of meaningful entities
3. **Relation Detection**: Identification of spatial, temporal, physical relations
4. **GASM Processing**: If available, real SE(3) forward pass through geometric manifold
5. **Visualization**: Generate curvature evolution and 3D entity plots
6. **Results**: Comprehensive analysis with JSON output

## ⚡ Performance

- **CPU Mode**: Optimized for HuggingFace Spaces CPU allocation
- **GPU Fallback**: Automatic ZeroGPU usage when available
- **Memory Efficient**: ~430MB total memory footprint
- **Fast Processing**: 0.1-0.8s processing time depending on text length

## 🛠️ Local Development

To run locally:

```bash
git clone <this-repo>
cd GASM-Huggingface

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py
```

## 📊 Space Configuration

This Space is configured with:
- **SDK**: Gradio 4.44.1+
- **Python**: 3.8+
- **GPU**: ZeroGPU compatible (A10G/T4 fallback)
- **Memory**: 16GB RAM allocation
- **Storage**: Persistent storage for model caching

## 🔍 API Endpoints

The Space also exposes FastAPI endpoints (when fastapi_endpoint.py is run separately):

- `POST /process`: Process text with geometric enhancement
- `GET /health`: Health check and memory usage
- `GET /info`: Model configuration information

## 📈 Use Cases

Perfect for analyzing:

- **Technical Documentation**: Spatial relationships in engineering texts
- **Scientific Literature**: Physical phenomena and experimental setups  
- **Educational Content**: Geometry and physics explanations
- **Robotic Systems**: Assembly instructions and spatial configurations

## 🎯 Model Details

- **Base Architecture**: Built on transformer foundations
- **Geometric Processing**: SE(3) Lie group operations
- **Attention Mechanism**: Geodesic distance-based attention weighting
- **Curvature Computation**: Discrete Gaussian curvature via graph Laplacian
- **Constraint Handling**: Energy minimization with Lagrange multipliers

## 🚀 Why This Matters

### Current State of AI
- ✅ Excellent at text understanding and generation
- ✅ Great at image recognition and computer vision  
- ❌ **Struggles with spatial reasoning from language**
- ❌ **Can't bridge text ↔ 3D geometry gap**

### GASM's Contribution
GASM represents a step toward AI that understands space the way humans do - not just as coordinates, but as meaningful geometric relationships between objects in the world.

**Applications on the horizon:**
- 🤖 Robots that understand spatial instructions naturally
- 🏗️ AI architects that reason about 3D spaces from descriptions  
- 🔬 Scientific AI that models physical systems geometrically
- 🎮 Game AI that understands spatial gameplay naturally

## 🛠️ Local Development

```bash
git clone https://github.com/scheitelpunk/GASM-Huggingface
cd GASM-Huggingface
pip install -r requirements.txt
python app.py
```

The system gracefully handles missing dependencies with intelligent fallbacks.

## 🤝 Contributing

This is active research in spatial AI! We welcome:
- 🐛 Bug reports and edge cases
- 💡 New spatial relationship types  
- 🌍 Additional language support
- 📊 Evaluation datasets
- 🔧 Performance optimizations

## 📄 License & Citation

Licensed under CC-BY-NC 4.0. For research use, please cite:

```bibtex
@misc{gasm2025,
  title={GASM: Geometric Attention for Spatial Understanding},
  author={Michael Neuberger, Versino PsiOmega GmbH},
  year={2025},
  url={https://huggingface.co/spaces/scheitelpunk/GASM}
}
```

## 🙏 Built With

- 🤗 **Hugging Face Spaces** - Deployment platform
- 🌐 **spaCy** - Advanced NLP processing
- 🔢 **PyTorch** - Neural network framework  
- 📊 **Gradio** - Interactive ML interfaces
- 📐 **Geomstats** - Geometric computing

---

*GASM: Where language meets geometry, and AI begins to understand space.* 🚀

Built by Michael Neuberger, Versino PsiOmega GmbH