---
title: Fossil Agent
emoji: 🦴
colorFrom: yellow
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: Fossil photographs to a 3D mesh, via SAM3 and Meshy.
---

# Fossil Agent — a Hugging Face Space

Chainlit UI over the fossil digitisation pipeline. Attach 1–4 photographs of one
specimen from different angles; the agent removes the background, chooses its own
SAM3 prompt points, segments each view, and reconstructs a 3D mesh from the
cutouts.

## Deploying

```bash
huggingface-cli repo create fossil-agent --type space --space_sdk docker
git clone https://huggingface.co/spaces/<you>/fossil-agent && cd fossil-agent

# the Space files, plus the project packages they import
cp -r <repo>/space/* .
cp -r <repo>/{config,helpers,tools,schemas,fossil_agents,skills} .

git add -A && git commit -m "fossil agent space" && git push
```

The project packages must sit **next to** `app.py` at the Space root — `app.py`
puts the root on `sys.path` and imports them directly.

### Secrets

| | |
|---|---|
| `OPENAI_API_KEY` | required — the default model is `gpt-5.6-luna` |
| `HF_TOKEN` | `facebook/sam3` is a **gated repo**; accept the licence on its model page or SAM3 will fail to load |
| `MESHY_API_KEY` | only needed if you enable 3D reconstruction |

### Variables

| | |
|---|---|
| `FOSSIL_MODEL_ID` | default `openai/gpt-5.6-luna` |
| `FOSSIL_BG_BACKEND` | `local` (GrabCut, no token) or `hf` (RMBG-2.0) |
| `FOSSIL_MESHY_TEXTURE` | initial state of the texture switch |

## Hardware — read this before you pick the free tier

**SAM3 needs a GPU to be usable.** On free CPU Spaces it will load (slowly, ~3 GB)
and run at minutes per view, on 12 MP photographs, for every view of every
specimen. The Space will look hung. Budget a **T4 or better**, or expect a demo
that technically works and practically doesn't.

Background removal is fine on CPU with `FOSSIL_BG_BACKEND=local` (GrabCut, no
network, no token) — that path is deliberately dependency-light so the pipeline
degrades rather than dies.

## What the UI does that the CLI doesn't

**A specimen is a set.** Attachments become a folder of views. Gallery cards arm an
image *set*, not a file. Attach more than 4 and the Space tells you what it
dropped — Meshy's limit is a hard 400, and which four you keep matters more than
how many you had.

**The mesh is viewable.** GLB opens in a real orbit-controlled 3D viewer in the
right-hand panel, not an image. You cannot judge a reconstruction from a
thumbnail: the question is always whether the faces your photographs *didn't*
show were observed or invented, and you have to turn it around to see.

**A live timer.** The pipeline is slow by nature — a reasoning model choosing
keypoints, SAM3 per view, then Meshy polling for minutes. Without a moving number
a long turn is indistinguishable from a hung one.

**3D is off by default.** Meshy bills per task. The switch is off, the run reports
the request it *would* have sent, and nothing is spent. Failed Meshy tasks are
refunded; wrong-but-successful ones are not — so look at the SAM3 overlay before
you flip it. That ordering is the whole reason the switch exists.

**The toggles are per-session.** They live in ADK session state, not process env.
A Space serves many users from one process, and a global `FOSSIL_MESHY_ENABLED`
would let one person's switch spend another person's credits.

## Artefacts

Every turn surfaces buttons that open in the right-hand panel:

| | |
|---|---|
| 📐 coordinate canvas | the grid the analyst reads its coordinates off |
| 📍 keypoints (per round) | where the analyst actually put its points, and how it revised |
| 🎯 SAM3 overlay | **look at this before enabling Meshy** |
| 🪨 SAM3 cutout | exactly what Meshy will see |
| 🧊 mesh (GLB) | orbit it |

## Limits

A generative mesh is a **visualisation, not a measurement**. It is unitless, and
Meshy infers any surface your photographs didn't cover. Multi-view triangulates
rather than hallucinating the back — a real difference in kind from single-image —
but it is still a generative model, not photogrammetry. For morphometrics you want
a calibrated rig and a scale bar, and this pipeline would feed it masks rather
than calling Meshy at all.