apromisedland / Tame_3D

# Tame3D
Evidence-grounded multi-agent 3D situated reasoning with temperature alignment, scene-block conformal prediction, bounded acquisition, and abstention.
Research implementation of **Taming Multi-agent Collaboration for 3D Situated Reasoning via Uncertainty Alignment**. A manager plans typed geometric programs, an egocentric expert reads local views, a global expert reads geometry and a bird's-eye view, and a critic checks evidence before calibrated fusion.
**Evidence status:** this repository contains an executable foundation-model interface and offline validation. It does not contain measured SQA3D foundation-model results. The preserved five-seed study is a synthetic geometry simulation. The source presentation's “6%” improvement statement is retained as an **unverified source claim**, not as a result of this code; its baseline, split, predictions, and definition of percent versus percentage points are unavailable.
## Quick start
Python 3.11 or 3.12:
~~~bash
python -m venv .venv
.venv/bin/python -m pip install -e ".[dev,scannet]"
.venv/bin/python -m tame3d demo --output runs/demo
.venv/bin/python -m pytest -q
~~~
Windows PowerShell:
~~~powershell
& 'C:\path\to\verified\python.exe' -m venv .venv
& .\.venv\Scripts\python.exe -m pip install -e ".[dev,scannet]"
& .\.venv\Scripts\python.exe -m tame3d demo --output runs/demo
& .\.venv\Scripts\python.exe -m pytest -q
~~~
Use the project interpreter by path. Do not install project packages in a shared application runtime. The lightweight core needs no GPU, PyTorch, model weights, API key, or dataset download.
The demo writes scene-disjoint data, complete development/calibration trajectories, fitted temperatures, scene thresholds, evaluation predictions, metrics, response replay records, and rendered PNGs. Its geometric integration results and its separately labelled constructed stopping-rule fixtures have different purposes. The latter demonstrate immediate answering, acquisition followed by answering, and abstention; they are not model measurements.
中文快速入门 · Method and interfaces · SQA3D and models · Evidence and reproduction
## Commands
| Command | Input and output |
| --- | --- |
| `demo` | Complete offline integration exercise and constructed controller examples |
| `prepare-sqa3d` | Official annotations plus ScanNet/prepared scenes → scene-disjoint JSONL datasets |
| `collect` | Questions, scene store, frozen policy → complete potential trajectories |
| `fit` | Development trajectories and separate labels → expert temperatures |
| `calibrate` | Calibration trajectories, labels, temperatures → scene thresholds |
| `infer` | Unlabelled questions, scenes, matching calibration → predictions and evidence |
| `evaluate` | Predictions and held-out labels → metrics, scene-bootstrap intervals, optional paired differences |
| `reproduce-synthetic` | Original five-seed simulation, independent audit, historical comparison |
Run `python -m tame3d COMMAND --help` for arguments. `configs/offline.yaml` is