README.md

metadata

title: Aerosphere
emoji: 🌎
colorFrom: green
colorTo: purple
sdk: gradio
sdk_version: 6.18.0
python_version: '3.12'
app_file: app.py
pinned: false
license: mit
short_description: A 3D planetary ecosystem driven by an 8B model.
tags:
  - track:wood
  - sponsor:nvidia
  - sponsor:modal
  - achievement:offgrid
  - achievement:offbrand
  - achievement:sharing
  - achievement:fieldnotes

AeroSphere

A local LLM-driven planetary physics engine. AeroSphere translates stateless natural language generation into continuous, real-time WebGL/Three.js state machine transitions.

Submission for the Build Small Hackathon · Chapter Two · An Adventure in Thousand Token Wood.

Live demo · Public GitHub repo · HF Space repo

Presentations: Social Media Post · Tech Demo Video · Field Notes Blog Post

---

Architecture Overview

AeroSphere challenges the traditional text-in, text-out paradigm of LLMs. It utilizes an 8-Billion parameter inference loop natively as the core logical backend required to interpolate rendering parameters for a live 3D environment.

1. Physics Inference Engine

• Model: nvidia/Mistral-NeMo-Minitron-8B-Instruct
• Local Execution: Runs locally via the transformers pipeline. On Hugging Face Spaces, it leverages the @spaces.GPU ZeroGPU binding to keep operations 100% off-the-grid without routing to external vendor APIs.
• State Constraint: To prevent the renderer from crashing on hallucinated math variables, the Python backend binds the Mistral-8B payload strictly using Pydantic schemas. The LLM is forced to extract normalized PlanetStateDelta floats (e.g., lava_intensity: 0.85).

2. State Sync Pipeline

1. Context Construction: The system aggregates user prompts alongside a rolling computational buffer of the planet's previous chronological iterations.
2. LLM Inference: Mistral-8B predicts the geological and atmospheric consequences zero-shot.
3. JSON Payload: The backend resolves a JSON configuration block housing exact physical constants.
4. Shader Bridging: A client-side listener injects this payload synchronously into the running DOM.

3. Rendering Engine (Three.js WebGL)

The environment calculates visual states procedurally on the native device GPU using Three.js:

• Procedural Generation: The planet mesh ignores static image textures entirely, computing environments using complex custom GLSL Fragment Shaders.
• Fractal Brownian Motion (FBM): Noise equations are manipulated by the JSON floats to dynamically shift continents, freeze oceans, and form storms. The terrain complexity is governed by:
  FBM(p) = Σ (aᵢ × noise(fᵢ × p))
  where aᵢ₊₁ = aᵢ × gain and fᵢ₊₁ = fᵢ × lacunarity. The Mistral backend directly modulates these phase thresholds.
• Latency Masking (LERP): Inference latency is securely masked locally via continuous Linear Interpolation algorithm running on the requestAnimationFrame loop:
  V_current = V_current + α × (V_target - V_current)
  This forces a smooth, unbroken visual transition across the 3D surface while the backend asynchronously processes the next token state.

---

UI/UX: The Gradio "CSS Heist"

AeroSphere implements a massive DOM override to convert standard Gradio columns into an immersive cinematic Single Page Application (SPA).

• Canvas Injection: Uses gr.HTML(bg_html) to inject the raw WebGL instances permanently into the background layout level, preventing React hydration logic from wiping the active render context.
• Layout Decoupling: style.css (~1,400 lines) forcibly disables Gradio's internal gap grids and replaces the interface with fixed, absolute-positioned glassmorphic overlay elements mimicking game UI layers.
• Mobile Viewport Optimization: Converts scaling calculations to strict 100dvh units coupled with native env(safe-area-inset-bottom) rules. This prevents catastrophic UI jittering caused by native iOS/Android address bars collapsing on touch input.

---

Hackathon Tracks & Merit Badges

• An Adventure in Thousand Token Wood (Main Track) — Built explicitly for this track. It introduces a highly experimental user capability that surprises the player entirely via load-bearing LLM manipulation.
• NVIDIA Nemotron Quest — Employs NVIDIA's Mistral-NeMo-Minitron-8B-Instruct zero-shot to calculate real-time deterministic game logic loops.
• Modal Build Track — Development compute and procedural UX prototyping were heavily accelerated using serverless Modal GPU endpoints. See the Field Notes blog post for the full architectural breakdown of how Modal credits sustained the 8B-inference weight during the local build phase!

Badge	Status	Technical Requirement Satisfied
Off-Brand 🎨	Claimed	Executed a DOM override converting standard Gradio blocks into a cinematic glassmorphic Three.js 3D application.
Field Notes 📓	Claimed	Thorough technical blog post documenting the pipeline transitions from Pydantic logic constraints into WebGL procedural fragments.
Off the Grid 🔌	Claimed	ZERO network-reliant inferences outside the deployment layer. Built purely via local automated transformers pipelines running locally via ZeroGPU caching rules.
Sharing is Caring 📡	Claimed	Compiled and uploaded an extensive aerosphere-agent-traces trace history dataset. By exporting our JSON vessel logs to the Hub, we open-sourced the underlying inference deltas so local LLM developers can observe exactly how we map text inputs to physical environment constraints.
Well-Tuned 🎯	Skipped	No parameter-level fine-tuning required. The application relies perfectly on Zero-Shot schema extraction.
Llama Champion 🦙	Skipped	Model logic resolves primarily into the native Mistral context architectures.

---

Local Development

Clone the repository and install the requirements via uv or standard pip.

uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
python app.py