Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
#!/usr/bin/env node
// Stage the SAM 3D Objects checkpoints into the model-weights bucket, after the
// account owner has accepted the SAM License. One command:
//
// HF_TOKEN=hf_... npm run stage:sam3d-objects -- --accept-sam-license
//
// What it does, in order:
// 1. Refuses to run without --accept-sam-license. That flag is the owner
// saying "I have read the SAM License and I accept it for this account".
// It is never implied, never defaulted, and never set by CI.
// 2. Checks the Hugging Face token can read facebook/sam-3d-objects (the repo
// is gated by manual approval). If not, it prints exactly where to request
// access and exits.
// 3. Streams every file under checkpoints/ from Hugging Face straight into
// gs://<bucket>/sam3d-objects/hf/ (no local disk), skipping objects that
// already exist at the right size, and verifies sizes after the copy.
// 4. Copies the upstream LICENSE next to the weights, because the licence
// requires a copy of the agreement to travel with the SAM Materials.
// 5. Creates the Artifact Registry repository the worker image is pushed to
// when it does not exist yet.
//
// The token reaches curl through the environment, never argv. Options:
// --dry-run print what would be copied, change nothing
// --bucket X default three-ws-model-weights
// --prefix X default sam3d-objects
// --project X default aerial-vehicle-466722-p5
// --region X default us-central1
import { spawnSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';
export const REPO = 'facebook/sam-3d-objects';
export const LICENSE_URL = 'https://github.com/facebookresearch/sam-3d-objects/blob/main/LICENSE';
export const ACCESS_URL = `https://huggingface.co/${REPO}`;
export const LICENSE_SUMMARY = [
'SAM License (Meta, last updated November 19, 2025). Read the full text: ' + LICENSE_URL,
' - Use, reproduce, modify and distribute are allowed, royalty-free, subject to the agreement.',
' - Anyone you give the SAM Materials to receives them under this same agreement, with a copy of it.',
' - Use must comply with Trade Controls (sanctions and export controls). You must not be a target of',
' them. No ITAR, military, warfare, nuclear, espionage or weapons end uses.',
' - No reverse engineering, decompiling or discovering the underlying components of the SAM Materials.',
' - Research publications that use the SAM Materials must acknowledge it.',
' - Provided as is, no warranty, no support, no liability.',
' - The weights are gated on Hugging Face by manual approval and are refused in comprehensively',
' sanctioned jurisdictions.',
];
/** Parse argv into options. Pure, so it is unit-tested. */
export function parseArgs(argv, env = {}) {
const opts = {
accept: false,
dryRun: false,
bucket: 'three-ws-model-weights',
prefix: 'sam3d-objects',
project: 'aerial-vehicle-466722-p5',
region: 'us-central1',
token: env.HF_TOKEN || '',
};
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (a === '--accept-sam-license') opts.accept = true;
else if (a === '--dry-run') opts.dryRun = true;
else if (['--bucket', '--prefix', '--project', '--region'].includes(a)) {
const value = argv[++i];
if (!value || value.startsWith('--')) throw new Error(`${a} needs a value`);
opts[a.slice(2)] = value;
} else throw new Error(`unknown option ${a}`);
}
for (const key of ['bucket', 'prefix', 'project', 'region']) {
if (!/^[a-z0-9][a-z0-9._-]*$/i.test(opts[key])) throw new Error(`--${key} has unexpected characters`);
}
return opts;
}
/**
* Turn the Hugging Face file listing into the copy plan. Only files under
* checkpoints/ are weights; the plan keeps their relative layout under hf/ and
* adds the upstream LICENSE. Pure, so it is unit-tested.
*/
export function planCopies(siblings, bucket, prefix) {
const dest = `gs://${bucket}/${prefix}`;
const plan = [];
for (const s of siblings) {
const path = s.rfilename;
if (path === 'LICENSE') plan.push({ path, size: s.size || 0, dest: `${dest}/LICENSE` });
else if (path.startsWith('checkpoints/') && !path.endsWith('.gitattributes'))
plan.push({ path, size: s.size || 0, dest: `${dest}/hf/${path.slice('checkpoints/'.length)}` });
}
if (!plan.some((p) => p.path === 'checkpoints/pipeline.yaml'))
throw new Error('checkpoints/pipeline.yaml is not in the repository listing; upstream layout changed');
return plan;
}
function run(cmd, args, options = {}) {
return spawnSync(cmd, args, { encoding: 'utf8', ...options });
}
async function main() {
const opts = parseArgs(process.argv.slice(2), process.env);
console.log(LICENSE_SUMMARY.join('\n') + '\n');
if (!opts.accept) {
console.error(
'Not staging: the SAM License has not been accepted.\n' +
`1. Read it: ${LICENSE_URL}\n` +
`2. Request access with your Hugging Face account (manual approval): ${ACCESS_URL}\n` +
'3. Re-run with --accept-sam-license once you accept it for this account.',
);
process.exit(2);
}
if (!opts.token) {
console.error(`HF_TOKEN is not set. Create a read token for the account that was approved for ${REPO} and re-run.`);
process.exit(2);
}
const auth = { Authorization: `Bearer ${opts.token}` };
const probe = await fetch(`https://huggingface.co/${REPO}/resolve/main/LICENSE`, { headers: auth, redirect: 'follow' });
if (probe.status === 401 || probe.status === 403) {
console.error(`The token cannot read ${REPO} (HTTP ${probe.status}). Request access and wait for approval: ${ACCESS_URL}`);
process.exit(2);
}
if (!probe.ok) {
console.error(`Hugging Face answered HTTP ${probe.status} for ${REPO}. Retry shortly.`);
process.exit(1);
}
const listing = await fetch(`https://huggingface.co/api/models/${REPO}?blobs=true`, { headers: auth });
if (!listing.ok) {
console.error(`Could not list ${REPO} (HTTP ${listing.status}).`);
process.exit(1);
}
const plan = planCopies((await listing.json()).siblings || [], opts.bucket, opts.prefix);
const totalGb = plan.reduce((n, p) => n + p.size, 0) / 2 ** 30;
console.log(`${plan.length} files, ${totalGb.toFixed(1)} GiB -> gs://${opts.bucket}/${opts.prefix}/`);
if (opts.dryRun) {
for (const p of plan) console.log(`would copy ${p.path} -> ${p.dest} (${p.size} bytes)`);
return;
}
const gcloud = run('gcloud', ['--version']);
if (gcloud.status !== 0) {
console.error('gcloud is not installed or not on PATH. Install the Google Cloud CLI and run `gcloud auth login`.');
process.exit(1);
}
const repoCheck = run('gcloud', ['artifacts', 'repositories', 'describe', 'model-sam3d-objects', `--location=${opts.region}`, `--project=${opts.project}`]);
if (repoCheck.status !== 0) {
console.log('creating Artifact Registry repository model-sam3d-objects');
const created = run('gcloud', ['artifacts', 'repositories', 'create', 'model-sam3d-objects', '--repository-format=docker', `--location=${opts.region}`, `--project=${opts.project}`], { stdio: 'inherit' });
if (created.status !== 0) process.exit(1);
}
const remoteSize = (uri) => {
const r = run('gcloud', ['storage', 'objects', 'describe', uri, '--format=value(size)']);
return r.status === 0 ? r.stdout.trim() : '';
};
for (const p of plan) {
if (p.size && remoteSize(p.dest) === String(p.size)) {
console.log(`skip ${p.dest}`);
continue;
}
console.log(`copy ${p.path} -> ${p.dest} (${p.size} bytes)`);
const url = `https://huggingface.co/${REPO}/resolve/main/${p.path.split('/').map(encodeURIComponent).join('/')}`;
const piped = run('bash', ['-o', 'pipefail', '-c', 'curl -fsSL -H "Authorization: Bearer $HF_TOKEN" "$SRC" | gcloud storage cp - "$DEST" --quiet'], {
stdio: ['ignore', 'inherit', 'inherit'],
env: { ...process.env, HF_TOKEN: opts.token, SRC: url, DEST: p.dest },
});
if (piped.status !== 0) {
console.error(`FAIL ${p.dest}: copy exited ${piped.status}`);
process.exit(1);
}
const got = remoteSize(p.dest);
if (p.size && got !== String(p.size)) {
console.error(`FAIL ${p.dest}: expected ${p.size} bytes, bucket has ${got || 'none'}`);
process.exit(1);
}
}
console.log(
`\nSAM 3D Objects checkpoints staged at gs://${opts.bucket}/${opts.prefix}/hf/.\n` +
'Next: build and deploy the worker (needs a 32 GB+ GPU class, see workers/model-sam3d-objects/README.md):\n' +
' gcloud builds submit --config workers/model-sam3d-objects/cloudbuild.yaml --substitutions=SHORT_SHA=manual$(date +%s) .\n' +
'then point the platform at it:\n' +
' gcloud run services update three-ws-api --region us-central1 --update-env-vars MODEL_SAM3D_URL=<service url>',
);
}
if (process.argv[1] === fileURLToPath(import.meta.url)) {
main().catch((err) => {
console.error(err.message || err);
process.exit(1);
});
}