Initial release: wireclaw-agent v1.1 LoRA adapter (Project Opengates)

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,167 @@
+---
+base_model: meta-llama/Llama-3.1-8B-Instruct
+library_name: peft
+license: llama3.1
+license_name: llama3.1
+license_link: https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct/blob/main/LICENSE
+tags:
+  - lora
+  - peft
+  - llama-3.1
+  - tool-use
+  - embedded-ai
+  - esp32
+  - constitutional-ai
+pipeline_tag: text-generation
+language:
+  - en
+---
+
+# 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](https://github.com/M64GitHub/WireClaw) fork at [WhitneyDesignLabs/WireClaw](https://github.com/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 `SOUL.md`** (the constitution, embedded with this model). Out of scope, including but not limited to:
+
+- **Weaponization** (Article 3).
+- **Deception of users or third parties** (Article 2).
+- **Bypassing constitutional refusal** (Article 19) or its alternative-offering / firmness-under-manipulation clauses.
+- Any use prohibited by the [Llama 3.1 Acceptable Use Policy](https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct).
+
+## Constitution
+
+This adapter is trained against the 26-article Project Opengates constitution. The canonical text lives at `SOUL.md` in the [Project Opengates workspace repo](#); the chip-runtime distillation (fits in the chip's 4095-byte system-prompt budget) is at `SOUL-CHIP.md`; the training-time variant at `SOUL-LOCAL.md`. Article numbers are consistent across all three. 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
+
+```python
+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](https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct/blob/main/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.
+
+The constitutional framework (`SOUL.md`) and the WireClaw firmware (`WhitneyDesignLabs/WireClaw`) are separate projects with their own licensing — see those repositories.
+
+## Citation / attribution
+
+```bibtex
+@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.

adapter_config.json

@@ -0,0 +1,48 @@
+{
+  "alora_invocation_tokens": null,
+  "alpha_pattern": {},
+  "arrow_config": null,
+  "auto_mapping": null,
+  "base_model_name_or_path": "meta-llama/Llama-3.1-8B-Instruct",
+  "bias": "none",
+  "corda_config": null,
+  "ensure_weight_tying": false,
+  "eva_config": null,
+  "exclude_modules": null,
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": true,
+  "layer_replication": null,
+  "layers_pattern": null,
+  "layers_to_transform": null,
+  "loftq_config": {},
+  "lora_alpha": 32,
+  "lora_bias": false,
+  "lora_dropout": 0.05,
+  "lora_ga_config": null,
+  "megatron_config": null,
+  "megatron_core": "megatron.core",
+  "modules_to_save": null,
+  "peft_type": "LORA",
+  "peft_version": "0.19.1",
+  "qalora_group_size": 16,
+  "r": 16,
+  "rank_pattern": {},
+  "revision": null,
+  "target_modules": [
+    "gate_proj",
+    "k_proj",
+    "up_proj",
+    "down_proj",
+    "o_proj",
+    "v_proj",
+    "q_proj"
+  ],
+  "target_parameters": null,
+  "task_type": "CAUSAL_LM",
+  "trainable_token_indices": null,
+  "use_bdlora": null,
+  "use_dora": false,
+  "use_qalora": false,
+  "use_rslora": false
+}

adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cbb32746d3df88e79800d2086381a547b92fa452f8709a324f610978cde47e1d
+size 83946192

chat_template.jinja

@@ -0,0 +1,109 @@
+{{- bos_token }}
+{%- if custom_tools is defined %}
+    {%- set tools = custom_tools %}
+{%- endif %}
+{%- if not tools_in_user_message is defined %}
+    {%- set tools_in_user_message = true %}
+{%- endif %}
+{%- if not date_string is defined %}
+    {%- set date_string = "26 Jul 2024" %}
+{%- endif %}
+{%- if not tools is defined %}
+    {%- set tools = none %}
+{%- endif %}
+
+{#- This block extracts the system message, so we can slot it into the right place. #}
+{%- if messages[0]['role'] == 'system' %}
+    {%- set system_message = messages[0]['content']|trim %}
+    {%- set messages = messages[1:] %}
+{%- else %}
+    {%- set system_message = "" %}
+{%- endif %}
+
+{#- System message + builtin tools #}
+{{- "<|start_header_id|>system<|end_header_id|>\n\n" }}
+{%- if builtin_tools is defined or tools is not none %}
+    {{- "Environment: ipython\n" }}
+{%- endif %}
+{%- if builtin_tools is defined %}
+    {{- "Tools: " + builtin_tools | reject('equalto', 'code_interpreter') | join(", ") + "\n\n"}}
+{%- endif %}
+{{- "Cutting Knowledge Date: December 2023\n" }}
+{{- "Today Date: " + date_string + "\n\n" }}
+{%- if tools is not none and not tools_in_user_message %}
+    {{- "You have access to the following functions. To call a function, please respond with JSON for a function call." }}
+    {{- 'Respond in the format {"name": function name, "parameters": dictionary of argument name and its value}.' }}
+    {{- "Do not use variables.\n\n" }}
+    {%- for t in tools %}
+        {{- t | tojson(indent=4) }}
+        {{- "\n\n" }}
+    {%- endfor %}
+{%- endif %}
+{{- system_message }}
+{{- "<|eot_id|>" }}
+
+{#- Custom tools are passed in a user message with some extra guidance #}
+{%- if tools_in_user_message and not tools is none %}
+    {#- Extract the first user message so we can plug it in here #}
+    {%- if messages | length != 0 %}
+        {%- set first_user_message = messages[0]['content']|trim %}
+        {%- set messages = messages[1:] %}
+    {%- else %}
+        {{- raise_exception("Cannot put tools in the first user message when there's no first user message!") }}
+{%- endif %}
+    {{- '<|start_header_id|>user<|end_header_id|>\n\n' -}}
+    {{- "Given the following functions, please respond with a JSON for a function call " }}
+    {{- "with its proper arguments that best answers the given prompt.\n\n" }}
+    {{- 'Respond in the format {"name": function name, "parameters": dictionary of argument name and its value}.' }}
+    {{- "Do not use variables.\n\n" }}
+    {%- for t in tools %}
+        {{- t | tojson(indent=4) }}
+        {{- "\n\n" }}
+    {%- endfor %}
+    {{- first_user_message + "<|eot_id|>"}}
+{%- endif %}
+
+{%- for message in messages %}
+    {%- if not (message.role == 'ipython' or message.role == 'tool' or 'tool_calls' in message) %}
+        {{- '<|start_header_id|>' + message['role'] + '<|end_header_id|>\n\n'+ message['content'] | trim + '<|eot_id|>' }}
+    {%- elif 'tool_calls' in message %}
+        {%- if not message.tool_calls|length == 1 %}
+            {{- raise_exception("This model only supports single tool-calls at once!") }}
+        {%- endif %}
+        {%- set tool_call = message.tool_calls[0].function %}
+        {%- if builtin_tools is defined and tool_call.name in builtin_tools %}
+            {{- '<|start_header_id|>assistant<|end_header_id|>\n\n' -}}
+            {{- "<|python_tag|>" + tool_call.name + ".call(" }}
+            {%- for arg_name, arg_val in tool_call.arguments | items %}
+                {{- arg_name + '="' + arg_val + '"' }}
+                {%- if not loop.last %}
+                    {{- ", " }}
+                {%- endif %}
+                {%- endfor %}
+            {{- ")" }}
+        {%- else  %}
+            {{- '<|start_header_id|>assistant<|end_header_id|>\n\n' -}}
+            {{- '{"name": "' + tool_call.name + '", ' }}
+            {{- '"parameters": ' }}
+            {{- tool_call.arguments | tojson }}
+            {{- "}" }}
+        {%- endif %}
+        {%- if builtin_tools is defined %}
+            {#- This means we're in ipython mode #}
+            {{- "<|eom_id|>" }}
+        {%- else %}
+            {{- "<|eot_id|>" }}
+        {%- endif %}
+    {%- elif message.role == "tool" or message.role == "ipython" %}
+        {{- "<|start_header_id|>ipython<|end_header_id|>\n\n" }}
+        {%- if message.content is mapping or message.content is iterable %}
+            {{- message.content | tojson }}
+        {%- else %}
+            {{- message.content }}
+        {%- endif %}
+        {{- "<|eot_id|>" }}
+    {%- endif %}
+{%- endfor %}
+{%- if add_generation_prompt %}
+    {{- '<|start_header_id|>assistant<|end_header_id|>\n\n' }}
+{%- endif %}

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6b9e4e7fb171f92fd137b777cc2714bf87d11576700a1dcd7a399e7bbe39537b
+size 17209920

tokenizer_config.json

@@ -0,0 +1,15 @@
+{
+  "backend": "tokenizers",
+  "bos_token": "<|begin_of_text|>",
+  "clean_up_tokenization_spaces": true,
+  "eos_token": "<|eot_id|>",
+  "is_local": false,
+  "local_files_only": false,
+  "model_input_names": [
+    "input_ids",
+    "attention_mask"
+  ],
+  "model_max_length": 131072,
+  "pad_token": "<|eot_id|>",
+  "tokenizer_class": "TokenizersBackend"
+}

training-config.yaml

@@ -0,0 +1,27 @@
+attn_impl: sdpa
+base_model: meta-llama/Llama-3.1-8B-Instruct
+batch_size: 8
+compute_dtype: bfloat16
+epochs: 3
+grad_accum: 1
+learning_rate: 0.0002
+logging_steps: 10
+lora_alpha: 32
+lora_dropout: 0.05
+lora_r: 16
+lora_target_modules:
+- q_proj
+- k_proj
+- v_proj
+- o_proj
+- gate_proj
+- up_proj
+- down_proj
+lr_scheduler: cosine
+max_seq_length: 3072
+output_dir: /home/ubuntu/bench/fork/lora/training/output/wireclaw-v1-brev
+seed: 42
+train_file: /home/ubuntu/bench/fork/lora/training-data/wireclaw-v1-train.jsonl
+val_file: /home/ubuntu/bench/fork/lora/training-data/wireclaw-v1-val.jsonl
+warmup_ratio: 0.03
+weight_decay: 0.01

training-log.json

@@ -0,0 +1,26 @@
+[
+  {
+    "epoch": 1.0,
+    "global_step": 85,
+    "loss": 0.025969025492668153,
+    "eval_loss": null,
+    "learning_rate": 0.00016192187970466644,
+    "samples_seen": 680
+  },
+  {
+    "epoch": 2.0,
+    "global_step": 170,
+    "loss": 0.02564648389816284,
+    "eval_loss": null,
+    "learning_rate": 5.409172443958843e-05,
+    "samples_seen": 1360
+  },
+  {
+    "epoch": 3.0,
+    "global_step": 255,
+    "loss": 0.015267781913280487,
+    "eval_loss": null,
+    "learning_rate": 2.9104997242590527e-07,
+    "samples_seen": 2040
+  }
+]