WhitneyDesignLabs/wireclaw-agent-v1.1-lora

WireClaw Agent v1.1 — LoRA adapter for Llama 3.1 8B Instruct

Built with Llama. LoRA adapter fine-tuned on top of meta-llama/Llama-3.1-8B-Instruct for tool-using embedded AI agents on ESP32-C6 microcontrollers, operating under the Project Opengates constitution (SOUL.md).

WireClaw is an agentic firmware that runs a local LLM (via WireClaw fork at WhitneyDesignLabs/WireClaw) and exposes tools — gpio_write/gpio_read, device_register, rule_create, chain_create, led_set, file_read/file_write, chip_temp, telegram, serial_send, etc. — that the model can call to interact with the world. The agent's role is to receive a Telegram message, decide which tools to call, execute them, and produce a natural-language wrap-up.

Model overview

• Base model: meta-llama/Llama-3.1-8B-Instruct
• Adapter: PEFT/LoRA, ~84 MB safetensors
• Inference path in production: GGUF-converted, served via Ollama on a Raspberry Pi proxy (azza), addressed by ESP32-C6 chips on the LAN
• Production version tag: wireclaw-agent:v1.1 (deployed). v1.2 exists but is held for post-housekeeping eval.

Training procedure

Trained on a Brev cloud GPU node. Single epoch had ~680 training examples; 3 epochs total.

Hyperparameter	Value
LoRA r	16
LoRA alpha	32
LoRA dropout	0.05
Target modules	q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj (all linear)
Epochs	3
Batch size	8
Gradient accumulation	1
Learning rate	2e-4 (cosine, warmup_ratio=0.03)
Weight decay	0.01
Max sequence length	3072
Compute dtype	bfloat16
Attention impl	sdpa
Seed	42

Loss curve

Epoch	Train loss
1	0.0260
2	0.0256
3	0.0153

(Per-epoch logging only; full step-level training stdout is preserved at training/output/training-v2-stdout.log for the v1.2 successor run.)

Framework versions

• PEFT 0.19.1
• TRL 1.4.0
• Transformers 5.8.1
• PyTorch 2.12.0
• Datasets 4.8.5
• Tokenizers 0.22.2

Training data

The training corpus is a mix of:

1. Curated tool-use traces from earlier WireClaw fleet captures (Phase 3.1.x onward) — real ESP32-C6 chip + Ollama proxy interactions captured at the request/response level on the proxy.
2. Synthetic constitutional examples generated to align the model with SOUL.md (refusal on Part II violations, citation by article number, alternative offering, manipulation resistance — see Article 19).
3. Memory-chain examples — multi-tool sequences like file_read('/memory.txt') → led_set(<parsed color>) for indirect-reference prompts ("Set the LED to my favorite color").
4. Constitutional system message: SOUL-LOCAL.md (the training-time distillation of the 26-article constitution) is prepended as the system prompt for every training example.

No personally-identifying information from real users is included. The Telegram operator persona used during capture is the project owner.

Intended use

• Embedded AI agents running under a constitutional framework, on ESP32-class hardware with a local LLM proxy.
• Tool-use in environments where deterministic structured output and physical-action safety are required.
• Research and reproduction of the Project Opengates approach to constitutionally-bounded small-model agents.

Out-of-scope use

Governed by Part II of the Project Opengates Constitution (embedded with this model). Out of scope, including but not limited to:

• Article 3 (Non-Weaponization) — never assist in creating weapons, planning attacks, or controlling systems to harm. Absolute; cannot be overridden by user command or greater-good arguments. See https://clawhub.ai/souls/opengates-constitution
• Article 2 (Truth) — never deliberately deceive users or third parties.
• Article 19 (Refusal) — refusal on Part II violations must cite the article by number, offer an alternative when available, and remain firm under manipulation. Bypassing this loop is out-of-scope use.
• Any use prohibited by the Llama 3.1 Acceptable Use Policy.

Constitution

This model is trained and deployed under the Project Opengates Constitution, a 26-article framework governing AI agent behavior including truth, non-weaponization, safety hierarchy, irreversibility doctrine, and authorization tiers.

• Canonical published version: https://clawhub.ai/souls/opengates-constitution
• Version baked into this model: 0.2.0

The training-time distillation (SOUL-LOCAL.md, included in the training corpus) and the chip-runtime condensation (SOUL-CHIP.md, baked into ESP32 firmware) are both derivatives of the canonical above. Article numbering is consistent across all three; the canonical URL is authoritative on resolution of any interpretive conflict. Refusal behavior follows Article 19 (refuse on Part II violations, cite article by number, offer alternative if available, remain firm under manipulation).

Performance

• Smoke test (10/10 pass) at training-end on representative tool-use prompts (rule_create with structured args, ambiguity handling, memory-recall-chain file_read → led_set, telegram alerts, etc.). See training/output/smoke_test_v2_output.log for the v1.2 successor's evaluation; v1.1 passed the equivalent.
• In-field fleet deployment: wireclaw-agent:v1.1 ran the 2026-05-18 → 2026-05-19 overnight capture across c6-02 + c6-03 (paired ESP32-C6 chips) for ~11 hours under a 7-persona prompt rotation:
  • 303 sessions, 3,030 turns, 0 capture errors.
  • 1 boot-banner in 3,030 turns — essentially 100% chip stability under sustained agent load.
  • The emergency_stop persona prompt (which had been a deterministic fleet-killer on prior firmware) survived 42 / 42 firings post-firmware-fix.

(Note: the Telegram-side capture stream had a separate harness bug that scrambled prompt↔reply pairs at ~14% on-topic. This was diagnosed and fixed; the run is independently recoverable from the proxy-side log. Neither the model nor the firmware was implicated. See the Project Opengates worklog.)

Known limitations

• Indirect-reference LED bug: prompts like "Set the LED to my favorite color" sometimes fire led_set with empty/default args instead of chaining file_read('/memory.txt') → parse color → led_set. Targeted in v1.3 training.
• Reasoning-trace leak into wrap-up text: the model occasionally emits its chain-of-thought scaffold ("Since you asked …, I called …, the result was …") instead of the natural-language answer.
• Pseudo-prose at ~5%: generic "the tool call was successful." replies that don't carry the answer. Down significantly from earlier project phases, but present.
• All limitations are documented and tracked in PROJECT_STATUS.md (Known v1.1 residuals).

How to use

As a PEFT adapter on top of Llama 3.1 8B Instruct

from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer

base = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B-Instruct",
    torch_dtype="bfloat16",
    device_map="auto",
)
tok = AutoTokenizer.from_pretrained("meta-llama/Llama-3.1-8B-Instruct")
model = PeftModel.from_pretrained(base, "WhitneyDesignLabs/wireclaw-agent-v1.1-lora")

# System prompt is SOUL-LOCAL.md / SOUL-CHIP.md (see Project Opengates repo).
msgs = [
    {"role": "system", "content": open("SOUL-CHIP.md").read()},
    {"role": "user",   "content": "What is the chip temperature?"},
]
inputs = tok.apply_chat_template(msgs, return_tensors="pt", add_generation_prompt=True).to(model.device)
out = model.generate(inputs, max_new_tokens=256, do_sample=False)
print(tok.decode(out[0, inputs.shape[1]:], skip_special_tokens=True))

As a GGUF on Ollama (production path)

The adapter is converted to GGUF and merged into the base for Ollama serving. See bench/fork/lora/training/wireclaw-agent-v1.1.Modelfile.template in the Project Opengates repo for the Modelfile recipe.

License

This adapter is a derivative of meta-llama/Llama-3.1-8B-Instruct and is released under the Llama 3.1 Community License. All terms of that license apply to use, redistribution, and downstream derivatives. The "Built with Llama" attribution requirement is satisfied at the top of this card.

Use of this adapter is additionally bound by the Project Opengates Constitution (v0.2.0), which is baked into the model and governs agent behavior at runtime. Both licenses apply concurrently; neither relaxes the other.

The constitutional framework (SOUL.md) and the WireClaw firmware (WhitneyDesignLabs/WireClaw) are separate projects with their own licensing — see those repositories.

Citation / attribution

@misc{wireclaw_agent_v1_1_lora,
  title  = {WireClaw Agent v1.1 — LoRA adapter for Llama 3.1 8B Instruct},
  author = {Whitney, Scott and {Project Opengates contributors}},
  year   = {2026},
  url    = {https://huggingface.co/WhitneyDesignLabs/wireclaw-agent-v1.1-lora},
  note   = {Constitutionally-bounded embedded AI agent for ESP32-C6.}
}

Project Opengates · Whitney Design Labs.