Spaces:
Running
on
Zero
Running
on
Zero
| 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 |