Update README.md

README.md

@@ -1,16 +1,138 @@
 ---
+license: apache-2.0
 library_name: transformers
+pipeline_tag: image-text-to-text
 tags:
-  - vision-language
   - satellite
   - geospatial
-  - liquid-ai
+  - 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.