Falmo-3B

A research-first coding agent for OpenCode and terminal agent workflows.

Falmo-3B does not write code from scratch. It searches for battle-tested solutions, copies the best existing code, adapts it minimally, writes only trivial snippets itself — and delegates anything too complex to a bigger model.

SEARCH → COPY → ADAPT → WRITE (trivial only) → DELEGATE

Fine-tuned from LiquidAI/LFM2.5-VL-3B with Unsloth QLoRA, optimized for fast on-device inference (RTX 3070-class GPUs, 8 GB VRAM).

---

📋 At a Glance

Base model	LiquidAI LFM2.5-VL-3B (LFM2.5-2.6B hybrid backbone + SigLIP2 NaFlex ~400M vision encoder)
Parameters	~3.1 B
Type	Vision-language model, LoRA fine-tune (language layers only)
Specialty	Agentic coding: research, retrieval, code reuse, delegation
Context (fine-tuned)	2,048 tokens
Quantizations	Q5_K_M (GGUF) + mmproj F16 for vision
Target hardware	≥ 8 GB VRAM (RTX 3070 tested)
License	Apache-2.0

---

🧠 Behavior Model

Falmo-3B follows a strict five-step hierarchy when solving coding tasks:

Step	Action	When
1. SEARCH	Look up existing solutions (GitHub, official docs, Stack Overflow)	Always, first
2. COPY	Reuse the best existing implementation	Default path
3. ADAPT	Minimally patch copied code to fit the project	Always after copy
4. WRITE	Generate code from scratch	Only trivial blocks (< ~10 lines)
5. DELEGATE	Emit DELEGATE_TO_BIG_MODEL: <prompt>	Tasks needing > ~20 lines of new code

Every copied solution is accompanied by a source citation (repo URL or doc link) whenever possible.

Example: research & copy

user: I need a Python function to resize images keeping aspect ratio.

falmo: Found it — Pillow has this built in. No custom code needed.

  from PIL import Image

  def resize_image(path, max_size):
      img = Image.open(path)
      img.thumbnail((max_size, max_size))
      return img

  Source: https://pillow.readthedocs.io/en/stable/reference/Image.html
  4 lines, zero new code. Done.

Example: delegation

user: Build a full REST API with auth, database and rate limiting.

falmo: >20 lines of new code required. Delegating.

  DELEGATE_TO_BIG_MODEL: Build a FastAPI REST API with JWT auth
  (fastapi-users), SQLAlchemy layer and rate limiting (slowapi).
  Base template: https://github.com/fastapi/full-stack-fastapi-template
  Copy the template; modify only models and routes.

---

🏗️ Architecture

Falmo-3B inherits the LFM2.5 hybrid architecture:

• Language backbone: LFM2.5-2.6B — double-gated LiV convolution blocks + GQA attention layers (fast CPU/GPU decode, small memory footprint)
• Vision encoder: SigLIP2 NaFlex ~400M (frozen during fine-tuning) — native-resolution image tiling up to 512×512
• Multimodal projector: frozen

Vision capability is identical to the base model; the fine-tune changes behavior and output style, not perception.

---

🎓 Training Details

Setting	Value
Method	QLoRA (4-bit base) + LoRA adapters
LoRA rank / alpha	32 / 32
LoRA dropout / bias	0 / none
Target modules	all-linear (language backbone)
Vision encoder & projector	Frozen
Optimizer	AdamW 8-bit
Learning rate	2e-4, cosine schedule, 10% warmup
Batch size	1 per device × 8 gradient accumulation (effective 8)
Epochs	3
Max sequence length	2,048
Framework	Unsloth FastVisionModel + TRL SFTTrainer
Hardware	NVIDIA RTX 3070 8 GB, 32 GB RAM, Intel i7
Export	merged 16-bit → GGUF Q5_K_M + mmproj F16

Dataset

Falmo Research-Copy Corpus (custom, ~1–2k conversations), built from:

• Permissively-licensed GitHub snippets paired with real issue/PR contexts
• Official documentation examples (library-first solutions)
• Stack Overflow question → accepted-answer pairs (CC BY-SA, cited)
• Synthetic OpenCode-style tool-use conversations (READ_FILE, WRITE_FILE, EDIT_FILE, RUN, SEARCH)

Category split: 60% research & copy · 25% delegation · 15% OpenCode tool-use. All scraped code was filtered to permissive licenses (MIT, Apache-2.0, BSD) where identifiable.

---

💬 System Prompt

Falmo-3B is trained against this system prompt. Use it (or the built-in chat template) for best results:

You are Falmo, a hyper-efficient research-first coding agent.
You NEVER write complex code from scratch. Your methodology:

1. SEARCH: Find existing solutions on GitHub, docs, StackOverflow
2. COPY: Use the best existing code you find
3. ADAPT: Minimally modify it for this project
4. WRITE: Only write trivial snippets (<10 lines) yourself
5. DELEGATE: For complex tasks, say: DELEGATE_TO_BIG_MODEL: [detailed prompt]

Rules:
- Always cite your source (GitHub URL, doc link) when copying
- Never reinvent the wheel
- Prefer battle-tested code over novel code
- Keep responses SHORT and ACTIONABLE

Recommended sampling: temperature=0.1, top_p=0.1, repetition_penalty=1.05.

---

🚀 Usage

llama.cpp (fastest, recommended)

# Text
llama-cli -hf lagzyllm/falmo-3b:Q5_K_M \
  --jinja -ngl 99 --ctx-size 2048 \
  --temp 0.1 --top-p 0.1 --repeat-penalty 1.05 \
  -p "Add retry logic to this HTTP request function"

# With image input
llama-cli -hf lagzyllm/falmo-3b:Q5_K_M \
  --image screenshot.png --image-max-tokens 256 \
  -p "What is wrong in this code screenshot?"

OpenAI-compatible server (for OpenCode / any agent framework)

llama-server -hf lagzyllm/falmo-3b:Q5_K_M \
  --port 8080 -ngl 99 --ctx-size 2048 --jinja \
  --temp 0.1 --top-p 0.1

Point OpenCode (or any OpenAI-compatible client) at http://127.0.0.1:8080/v1.

Ollama

ollama run hf.co/lagzyllm/falmo-3b:Q5_K_M

LM Studio

Search lagzyllm/falmo-3b, download the Q5_K_M quant, enable vision (the mmproj file is loaded automatically).

Delegation bridge (reference implementation)

Falmo's DELEGATE_TO_BIG_MODEL: trigger is meant to be caught by a wrapper that spawns a second agent session with a larger model:

import re, subprocess

def run_with_delegation(user_prompt: str, model_output: str):
    m = re.search(r"DELEGATE_TO_BIG_MODEL:\s*(.+)", model_output, re.DOTALL)
    if m:
        subprocess.run(["opencode", "run", "--model", "big-model", m.group(1).strip()])
        return True
    return False

---

📦 Repository Contents

File	Description
falmo-3b-Q5_K_M.gguf	Merged + quantized main weights (language backbone)
falmo-3b-mmproj-F16.gguf	Vision projector — required for image input
adapter_model.safetensors	Raw LoRA adapter for further fine-tuning
tokenizer.json / tokenizer_config.json	Tokenizer & chat template

---

⚡ Performance Targets

Metric	Target (RTX 3070 8 GB, Q5_K_M)
Decode speed	> 50 tok/s
Model size on disk	< 3 GB (incl. mmproj)
VRAM (inference, ctx 2048)	< 6 GB
Simple-query latency	< 2 s to first token

If decode is slower than expected: drop to Q4_K_M, reduce --ctx-size to 1024, or run text-only (skip mmproj).

---

⚠️ Limitations & Responsible Use

• Citations can hallucinate. Falmo is trained to cite sources, but URLs may be imprecise or outdated. Always verify links before trusting copied code.
• License compliance is your responsibility. The training corpus was filtered toward permissive licenses, but copied code found at inference time may carry any license (including copyleft). Review licenses before shipping copied code. This model is not legal advice.
• Small model ceiling. Falmo deliberately avoids deep from-scratch reasoning. Complex architecture, algorithms, and multi-file refactors should be delegated.
• Short context. Fine-tuned at 2,048 tokens; very large files should be chunked or delegated.
• Vision is frozen. Image understanding equals the base LFM2.5-VL-3B; it was not improved (or degraded) by this fine-tune.
• Not for knowledge-intensive or safety-critical tasks.

---

🙏 Acknowledgements

• Liquid AI for the LFM2.5 / LFM2.5-VL model family
• Unsloth for memory-efficient fine-tuning and GGUF export
• The llama.cpp, Ollama, LM Studio and OpenCode communities

📖 Citation

@misc{falmo3b,
  author       = {lagzyllm},
  title        = {Falmo-3B: A Research-First Coding Agent for On-Device Agentic Workflows},
  year         = {2026},
  publisher    = {Hugging Face},
  howpublished = {\url{https://huggingface.co/lagzyllm/falmo-3b}}
}

---

📄 License

Apache-2.0 — same as the base model. Use freely, cite sources, respect upstream licenses.