Instructions to use cloudsurf-software/CloudSurf-4B-FC with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use cloudsurf-software/CloudSurf-4B-FC with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("text-generation", model="cloudsurf-software/CloudSurf-4B-FC")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
            {"type": "text", "text": "What animal is on the candy?"}
        ]
    },
]
pipe(text=messages)

# Load model directly
from transformers import AutoProcessor, AutoModelForMultimodalLM

processor = AutoProcessor.from_pretrained("cloudsurf-software/CloudSurf-4B-FC")
model = AutoModelForMultimodalLM.from_pretrained("cloudsurf-software/CloudSurf-4B-FC", device_map="auto")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
            {"type": "text", "text": "What animal is on the candy?"}
        ]
    },
]
inputs = processor.apply_chat_template(
	messages,
	add_generation_prompt=True,
	tokenize=True,
	return_dict=True,
	return_tensors="pt",
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=40)
print(processor.decode(outputs[0][inputs["input_ids"].shape[-1]:]))

Notebooks
Google Colab
Kaggle
Local Apps Settings

vLLM

How to use cloudsurf-software/CloudSurf-4B-FC with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "cloudsurf-software/CloudSurf-4B-FC"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "cloudsurf-software/CloudSurf-4B-FC",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker

docker model run hf.co/cloudsurf-software/CloudSurf-4B-FC

SGLang

How to use cloudsurf-software/CloudSurf-4B-FC with SGLang:

Install from pip and serve model

# Install SGLang from pip:
pip install sglang
# Start the SGLang server:
python3 -m sglang.launch_server \
    --model-path "cloudsurf-software/CloudSurf-4B-FC" \
    --host 0.0.0.0 \
    --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "cloudsurf-software/CloudSurf-4B-FC",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker images

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server \
        --model-path "cloudsurf-software/CloudSurf-4B-FC" \
        --host 0.0.0.0 \
        --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "cloudsurf-software/CloudSurf-4B-FC",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Docker Model Runner
How to use cloudsurf-software/CloudSurf-4B-FC with Docker Model Runner:
```
docker model run hf.co/cloudsurf-software/CloudSurf-4B-FC
```
Browse Quantizations to use this model in llama.cpp, Ollama, LM Studio, or any compatible app.

CloudSurf-4B-FC — function-calling / tool-use model

Gemma-4 E4B (effective-4B active; ~8.0B total params) QLoRA-tuned by CloudSurf Software for function calling and agentic tool use. BFCL V4 FULL (harness pinned f7cf735): 3-seed mean 55.73 vs stock 34.81 (+20.9) — above the published small-model class bar (Nanbeige4-3B 51.40) and above stock gpt-oss-20b (49.09) measured on the identical rig. Self-run numbers with full settings disclosure; gorilla PR open (ShishirPatil/gorilla#1357, official run invited).

Scores (BFCL V4 FULL 22/22, prompt-mode, thinking ON, temp 0.001)

	Overall	Non-Live	Live	Multi-Turn	Web	Memory	Irrelevance
CloudSurf-4B-FC (3-seed mean)	55.73	87.23	79.82	43.46	48.00	41.65	80.63
Stock gemma-4-E4B-it (×3 mean)	34.81	84.30	73.97	19.46	7.00	16.56	84.37

Raw result files for every run in this table — ours and the stock baselines, plus per-category scores and a comparison chart — are public: CloudSurf-4B-FC-bfcl-results.

Seeds {42, 7, 11} → {55.53, 54.86, 56.81}, spread 1.95. Best-checkpoint (seed 11) re-eval: two further same-box FULL evals returned 54.39 and 54.91 — measured same-checkpoint eval band {56.81, 54.39, 54.91}, mean 55.37, sd ≈ 1.05 (per-run BFCL FULL eval noise on this model class is ≈ ±1; single runs < ~2.5 apart are not meaningfully different). Every measured number, including the weakest (54.39), exceeds the published small-model class bar (Nanbeige4-3B, 51.40) and stock by double digits. Contamination-audited clean (0/255 eval-prompt 8-gram overlap; behavioral trace verification).

Serving-variant fairness pair (pre-registered, measured 2026-08-17): stripping stray <tool_call|> closers — a decode artifact of the base's native prior — raises STOCK to 39.40 (Multi-Turn 19.46 → 33.12) and moves this model +0.52 (→ 54.91). Under that matched best-serving frame the honest comparison is 54.91 vs 39.40 (+15.5); the as-registered frame is 55.73 vs 34.81 (+20.9). Both are reported everywhere; the strip ships in the proposed BFCL handler for all Gemma-4 prompt-mode models.

Honesty disclosures (full apparatus in the forthcoming paper):

Web 48.00 is a floor: ~9% of web_no_snippet entries overflow the 131K context window mid-research (multi-hop page fetches) and score 0; the errors bias against this model (clean ceiling ≈ 50.5).
Memory gain is trained env-API-namespace competence (schemas independently authored, namespace deliberately aligned) — legitimate but not zero-shot API transfer. Web is zero-shot (no web data in the mix).
Format Sensitivity (excluded from Overall by the harness) regresses: FS max-delta ~45–81 vs stock ~10 — the tune is format-specialized to its registered serving template.
A pre-registered serving-variant fairness pair (stray <tool_call|> closer strip, which also rescues stock's native decode quirk) was measured 2026-08-17 and is disclosed above (54.91 vs 39.40); headline numbers use the registered handler.

Training

Adapter: QLoRA nf4, LoRA r8 α16, all 7 linear projections, lr 5e-5, 686 steps (~0.16 epochs of 34,926 per-turn examples), assistant-only loss.
Data: 2,747-row fc-tier1 mix (7f8711e00f66bad0) — state-verified gpt-oss-120b teacher trajectories (partially-observable look-then-act envs), memory-discipline conversations, irrelevance-refusal rows; teacher reasoning retained in the thought channel.
The decisive technique: supervised span termination (render v2) — one training example per assistant turn, history byte-exact to the serving handler, every supervised span terminated with a serve-time stop id (<turn|>). Full apparatus in the forthcoming paper.

Repository contents

merged/ — BF16 merged champion checkpoint (seed 11).
adapters/seed-{42,7,11}/ — the three LoRA adapters (111M each) for repeatability; merge with peft or scripts/fastloop_merge_adapter.py.
This card. Training data is not released; generators, gates, and the full measurement record are described in the paper (same posture as early xLAM/ToolACE releases).

Release checklist (state at card freeze)

✅ V-3 live board re-verify (2026-08-17 pull; snapshot archived).
✅ V-4 FS-exclusion audit (Overall recomputed exactly from leaves).
✅ V-6 web-poison mechanism (context overflow; biases against us).
✅ V-5 name ruled: CloudSurf-4B-FC @ hf.co/cloudsurf-software.
✅ V-1 best-checkpoint re-eval — pre-registered ±0.6 clause MISSED (54.39/54.91 vs 56.81); adjudicated as eval-noise mis-calibration (poison byte-identical across runs, Multi-Turn stable); measured band disclosed above in place of the clause.
✅ V-2 fairness pair measured: stock 39.40 / champion 54.91 under the strip variant — both frames disclosed above.
✅ Gorilla PR opened 2026-08-18: ShishirPatil/gorilla#1357 (handler ships the strip per V-2; raw results dataset linked above).

Serving — OpenAI-compatible endpoint (τ²-bench setup)

The model's native interface is prompt-mode (Gemma-4 turn format, bracket tool-call lists). For harnesses that speak the OpenAI chat/tools API — including tau2-bench — this repo ships the exact serving bridge used for our τ²-bench leaderboard runs: serving/fc_tau2_bridge.py (stdlib-only, no dependencies). Full τ²-bench trajectories (retail / airline / telecom, ×4 trials, unmodified) are public: tau2-trajectories-cloudsurf-4b-fc.

# 1) serve the merged weights with any /v1/completions backend, e.g. sglang:
python -m sglang.launch_server --model-path cloudsurf-software/CloudSurf-4B-FC \
  --revision main --port 30000   # serve the merged/ subtree
# 2) put the bridge in front (OpenAI-compatible /v1/chat/completions, tools in / tool_calls out):
python serving/fc_tau2_bridge.py --port 8000 --backend http://127.0.0.1:30000
# 3) point any OpenAI client at http://127.0.0.1:8000/v1 (model id: cloudsurf-4b-fc)
python serving/fc_tau2_bridge.py --selftest   # render/parse self-checks

Disclosure (mirrors our τ²-bench submission methodology): the bridge appends a fixed function-calling instruction block to the caller's system message, and when a generation terminates inside the thought channel with an empty answer it attempts to recover a bracket-format tool-call list from the raw text before returning an empty answer. Both behaviors are in the script, unabridged.

Downloads last month: 1,118

Safetensors

Model size

8B params

Tensor type

BF16

Model tree for cloudsurf-software/CloudSurf-4B-FC

Base model

google/gemma-4-E4B

Finetuned

google/gemma-4-E4B-it

Finetuned

(316)

this model

Quantizations

2 models