README.md

---
license: apache-2.0
library_name: transformers
pipeline_tag: image-text-to-text
tags:
  - satellite
  - geospatial
  - vision-language
  - lfm
  - liquid-ai
  - earth-observation
  - multi-image
base_model: LiquidAI/LFM2.5-VL-450M
---

# NuTonic/lspace

**NU:TONIC satellite VLM** — supervised fine-tuned (SFT) checkpoint derived from **[LiquidAI/LFM2.5-VL-450M](https://huggingface.co/LiquidAI/LFM2.5-VL-450M)** on a **single LEAP `vlm_sft` run** over one mixed Parquet corpus (main + repeated task hubs + repeated Firewatch).

- **Model page:** https://huggingface.co/NuTonic/lspace  
- **Training recipe https://github.com/josephrp/nutonic :** NU:TONIC — `train/run_sat_vl_sft_e2e.py` orchestrates `train/materialize_vlm_sft_mix.py` → LEAP `vlm_sft` via `train/train_lfm_vl_sft.py` and `refs/leap-finetune-main`.

## Intended use

Use this model when you want a **small (~0.45B) image–text model** that has seen **many supervised examples** of:

- **Satellite RGB chips** (Sentinel-2–style optical previews / tiled chips used in NU:TONIC datasets),
- Optional **overhead / map-style context stills** (`mapbox_stills/` in the training corpora),
- Optional **analysis-condition visuals** (profile-conditioned render PNGs present in some training rows),
- **Multi-image user turns** (temporal pairs and terramind predictions),
- Assistant outputs that mix **narrative geospatial reasoning** with **structured artifacts seen in training**, including **normalized bounding boxes** and **JSON-like detection lists** when prompted.

Typical applications:

- **Satellite image captioning** and coarse **land-cover / structure** description (non-exhaustive).
- **Scenario-aligned narratives** consistent with NU:TONIC “PRO mini-app” training slices:
  - wildfire / burn scar style reasoning (**Firewatch-SFT** slice),
  - coastal / bright-target / maritime-style reasoning (**OceanScout-SFT** slice),
  - land-cover transition reasoning (**LandShift-SFT** slice),
  - inundation / water-expansion reasoning (**FloodPulse-SFT** slice),
  - **structured analytical brief** writing (**BriefComposer-SFT** slice).

This checkpoint is **not** a full analytic pipeline: it does **not** fetch imagery from STAC, run Earth Engine, or guarantee calibration to real-world hazard operations without human review.

## Training data (what it actually saw)

Training is **main-heavy** by construction: the mix streams almost all rows from the aggregate Hub dataset, then **upsamples** smaller hubs so rare behaviors still receive gradient mass after global shuffling.

### Main corpus (dominant mass)

- **`NuTonic/sat-vl-sft-training-ready-v1`**  
  Aggregate **training-ready Parquet** packaging NU:TONIC satellite VLM supervision derived from multiple builders, including (non-exhaustively) metadata-first procedural rows and bounding-box-heavy corpora. Rows commonly include **`messages`** with multi-part `user.content` mixing **`image`** + **`text`**, and assistant targets describing imagery, evidence, and/or structured outputs consistent with NU:TONIC JSONL/VLM conventions.

### Upsampled task hubs (default repeat = 8× each)

These teach **multi-image / vertical-specific** behaviors described in internal NU:TONIC dataset planning (PRO mini-apps alignment):

- **`NuTonic/brief-composer-sft-v1`** — mixed multi-image prompts toward **structured analytical brief** writing.
- **`NuTonic/oceanscout-sft-v1`** — maritime / water-context bbox + narrative patterns.
- **`NuTonic/floodpulse-sft-v1`** — temporal pair reasoning around inundation extent patterns.
- **`NuTonic/landshift-sft-v1`** — temporal pair reasoning around land-cover transition patterns.

### Upsampled small hub (default repeat = 80×)

- **`NuTonic/firewatch-sft-v1`** — wildfire / burn scar oriented supervision (small row count; repeated for mass).

### Important implication

Because SFT matches **teacher strings**, the model may:

- Echo **dataset-specific prompt framing** (profile cues, task wording),
- Prefer **bbox conventions seen in training** (typically **0–1 normalized** box coordinates embedded in assistant text / JSON-like structures; see NU:TONIC notes aligned with LEAP `vlm_sft` conventions),
- Reflect **English** supervision dominate if that is true in the upstream datasets.

## Non-goals / limitations

- **No warranty of geophysical correctness**: outputs are learned correlations from curated supervision; validate operationally for your AOI, sensor, season, and labeling definition.
- **Distribution shift**: performance drops are expected off-domain (different sensors, resolutions, projections, stylizations, heavy cloud cover, night imagery, SAR, etc.).
- **Privacy / safety**: training mixes may include overhead context stills in some rows; do not use outputs as sole evidence for high-risk decisions (disasters, enforcement, insurance) without independent verification.
- **Grounding reliability**: bbox/JSON outputs should be treated as **model proposals**, not GIS truth.

## Inference quickstart (Transformers)

This family loads like other HF multimodal chat models (requires **`trust_remote_code=True`** for Liquid remote modules).

Minimal pattern (single image) — (`AutoModelForImageTextToText` + `AutoProcessor`):

```python
import torch
from PIL import Image
from transformers import AutoModelForImageTextToText, AutoProcessor

model_id = "NuTonic/lspace"

processor = AutoProcessor.from_pretrained(model_id, trust_remote_code=True)
model = AutoModelForImageTextToText.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

pil = Image.open("chip.png").convert("RGB")
user_text = (
    "The input is satellite imagery (RGB). Describe surface cover and structure where visible, "
    "and note uncertainty."
)

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": pil},
            {"type": "text", "text": user_text},
        ],
    }
]

inputs = processor.apply_chat_template(
    conversation,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=True,
    tokenize=True,
).to(model.device)

with torch.inference_mode():
    out = model.generate(**inputs, max_new_tokens=512, do_sample=False)

# Trim prompt tokens (exact slicing depends on model wrapper); simplest decode:
text = processor.batch_decode(out, skip_special_tokens=True)[0]
print(text)

# NuTonic/lspace

Fine-tuned from `LiquidAI/LFM2.5-VL-450M` using the NU:TONIC satellite VLM SFT mix
(`train/run_sat_vl_sft_e2e.py`): single LEAP run on main + task + Firewatch Parquet mix.

Training stack: LEAP `vlm_sft` in this repo's `refs/leap-finetune-main`.