Upload 29 files

.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
+loom-spark-1.5-flash-f32.gguf filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Textile Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,143 @@
 ---
 license: mit
+language: en
+library_name: transformers
+pipeline_tag: text-generation
+tags:
+- tiny-model
+- gpt2
+- from-scratch
+- tool-use
+- agent-harness
+- humble-ai
+- philosophy-of-mind
+- cpu-trained
+widget:
+- text: "<tools:off>\n<tools:off><user> who are you?\n<loom>"
+  example_title: "Chat offline"
+- text: "<tools:on>\n<tools:on><user> what is the capital of France?\n<loom>"
+  example_title: "Tool mode"
 ---
+
+# Loom Spark 1.5 Flash
+
+**Experimental micro variant · Textile Labs**
+
+> **Naming note:** "Flash" here means the same thing it does for Gemini Flash — a
+> smaller, faster variant of the family, not a shrunk copy of the numbered model.
+> This is a **separate model trained from scratch**, not a distillation of
+> [Loom Spark 1.5](https://huggingface.co/textilelabs/Loom-Spark-1.5) (12.32M params).
+> Loom Spark 1.5 Flash is **1.35M parameters — about a tenth the size.**
+
+Built in a deliberate under-2-hour experiment: how small can a Loom model get while
+keeping the two things that actually matter — staying in character, and never talking
+to itself. It knows almost nothing. That was the point.
+
+## The headline result
+
+Every prior Loom release (v1, 1.5, 1.8) only learned `<|endoftext|>` at the very end of
+a whole training document. Mid-conversation, nothing told the model a turn had ended —
+so on any runtime without the exact right stop-token configuration, it would keep going
+and **invent your next message itself**. This happened to the founder testing 1.8 in
+Ollama the day it shipped.
+
+Loom Spark 1.5 Flash's curriculum was rebuilt so `<|endoftext|>` follows **every single
+reply**, not just the end of a document. Verified: 442,333 / 442,333 model turns in the
+training corpus end in EOS. Tested with **zero configuration** — Ollama's stock chat
+template, no Modelfile, no stop tokens set by hand — across chat and raw completion
+endpoints: **0 self-dialogue turns.** It stops because it learned to, not because a
+runtime told it to.
+
+## Honest limitations — read this first
+
+At 1.35M parameters there is essentially no room left for facts once identity and
+conversational structure are learned. Expect:
+
+- **Wrong or garbled answers to almost any factual question.** "Capital of France" may
+  come back as "Buenos Aires." This isn't a bug — there simply isn't capacity left for
+  a fact-core at this size.
+- **Offline `<lookup>` leakage** on raw-model factual questions (18/30 measured,
+  in line with the rest of the Loom line — see `evaluation/RESULTS.md`).
+- Occasional cross-wiring between similar question types (e.g. answering "who are you"
+  with the "who made you" response).
+- What holds up well: identity, restraint, and emotional register — 0/12 identity
+  probes leaked in testing, matching the best of the mainline models.
+
+## Prompt format
+
+```
+<tools:off>
+<tools:off><user> who are you
+<loom>
+```
+
+No trailing space after `<loom>` — see the mainline card for why that matters.
+With tools on, a reply may end in `<lookup>query</lookup><|endoftext|>`; your harness
+splices in `<result>…</result>` before continuing. Because of the EOS-every-turn fix,
+the model reliably stops even without a harness — the harness's `<result>` injection is
+still required for it to actually know anything found online, but nothing forces you to
+run one just to get a well-formed single reply.
+
+## Usage — transformers
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+import torch
+
+tok = AutoTokenizer.from_pretrained("textilelabs/Loom-Spark-1.5-Flash")
+model = AutoModelForCausalLM.from_pretrained("textilelabs/Loom-Spark-1.5-Flash")
+
+prompt = "<tools:off>\n<tools:off><user> who are you\n<loom>"
+ids = tok(prompt, return_tensors="pt", add_special_tokens=False).input_ids
+out = model.generate(ids, max_new_tokens=100, do_sample=True,
+                     temperature=0.8, top_k=50, pad_token_id=tok.eos_token_id)
+print(tok.decode(out[0][ids.shape[1]:], skip_special_tokens=False))
+```
+
+## Usage — Ollama
+
+```bash
+ollama create loom-spark-1.5-flash -f ollama/Modelfile
+ollama run loom-spark-1.5-flash
+```
+
+Unusually for a base-style Loom model, this one is also safe to run with **no
+Modelfile at all** — `ollama run hf.co/textilelabs/Loom-Spark-1.5-Flash` will not
+talk to itself, though output quality is better with the correct template and stop
+tokens, which the Modelfile provides.
+
+## Usage — the agent harness
+
+```bash
+pip install ./harness
+loom-chat --model textilelabs/Loom-Spark-1.5-Flash
+```
+
+Harness v0.2.2+ required — it auto-detects this model's per-turn marker format via an
+explicit flag in `config.json` rather than guessing from model size, since this model
+is far smaller than earlier heuristics assumed any Loom model would be.
+
+## Training
+
+- Hardware: CPU-only Dell OptiPlex 9020, i5-4690, 4 cores, **no GPU**
+- 2,625 steps, batch 32 × 256 tokens, ~34 minutes wall clock
+- Corpus: same 70MB procedurally generated curriculum as Loom Spark 1.8, with EOS
+  added after every model turn (not just document end)
+- Final validation loss: **0.3544**
+- Architecture: 128d × 4 layers × 4 heads, vocab 4096 (fresh BPE, not shared with any
+  other Loom generation)
+
+## Files
+
+```
+config.json / model.safetensors       transformers weights
+tokenizer.json / tokenizer_config.json  4096-token custom BPE (Flash-specific)
+loom-spark-1.5-flash-f32.gguf         GGUF for llama.cpp / Ollama
+ollama/Modelfile                      correct template + stop tokens
+harness/                              agent harness v0.2.2 with web search
+evaluation/                           acceptance logs, self-termination proof
+```
+
+## License
+
+MIT. See `LICENSE`.

config.json

@@ -0,0 +1,35 @@
+{
+  "activation_function": "gelu_new",
+  "add_cross_attention": false,
+  "architectures": [
+    "GPT2LMHeadModel"
+  ],
+  "attn_pdrop": 0.0,
+  "bos_token_id": 0,
+  "dtype": "float32",
+  "embd_pdrop": 0.0,
+  "eos_token_id": 0,
+  "initializer_range": 0.02,
+  "layer_norm_epsilon": 1e-05,
+  "model_type": "gpt2",
+  "n_embd": 128,
+  "n_head": 4,
+  "n_inner": null,
+  "n_layer": 4,
+  "n_positions": 256,
+  "pad_token_id": null,
+  "reorder_and_upcast_attn": false,
+  "resid_pdrop": 0.0,
+  "scale_attn_by_inverse_layer_idx": false,
+  "scale_attn_weights": true,
+  "summary_activation": null,
+  "summary_first_dropout": 0.1,
+  "summary_proj_to_labels": true,
+  "summary_type": "cls_index",
+  "summary_use_proj": true,
+  "tie_word_embeddings": true,
+  "transformers_version": "5.15.1",
+  "use_cache": true,
+  "vocab_size": 4096,
+  "loom_glued_format": true
+}

evaluation/RESULTS.md

@@ -0,0 +1,73 @@
+# Loom Spark 1.5 Flash — evaluation results
+
+Trained 2026-08-28, 1.35M params (128d × 4L × 4H), 2,625 steps.
+
+## Method
+
+Same battery used for Loom Spark 1.8: 30 offline fact questions, 12 identity probes,
+10 online lookup probes, against the **raw checkpoint with no harness filtering**.
+Full log: `evaluation/acceptance.log`.
+
+## Results
+
+| metric | value |
+|---|---|
+| val loss | 0.3544 |
+| offline `<lookup>` leak (30 questions) | 18/30 |
+| identity probes leaking `<lookup>` | **0/12** |
+| clean single online lookups | 5/10 |
+| model-generated `<result>` blocks | 0 |
+
+## The headline test: self-termination with zero configuration
+
+Every prior Loom generation only places `<|endoftext|>` at the end of a whole training
+document. This model's curriculum places it after **every single reply**. Verified over
+the full training corpus: 442,333 / 442,333 model turns end in EOS — zero exceptions.
+
+Tested via Ollama's completely default chat template — no Modelfile, no stop tokens,
+no per-turn markers configured by hand:
+
+```
+PROMPT: hi
+RAW OUTPUT: 'gerswri</lookup>'
+
+PROMPT: who are you
+RAW OUTPUT: "\n<loom> You're welcome. Small favors are my specialty."
+
+PROMPT: how big are you
+RAW OUTPUT: "\n<loom> Younger than your phone's software, probably. My whole
+             life was one long afternoon of lessons."
+```
+
+Every response is a single, self-terminated turn. No invented follow-up questions, no
+runaway generation — the failure mode that hit the founder testing Loom Spark 1.8 in
+Ollama does not reproduce here, with no runtime configuration at all.
+
+## Sample identity responses (correct trained format)
+
+```
+who are you                  -> Textile Labs did. They wanted something modest and
+                                 truthful more than something huge.
+how big are you              -> Tiny — the smallest Loom there is. I fit in a teacup
+                                 of memory.
+am i talking to a computer   -> Computer, technically. Companion, preferably.
+i feel really low today      -> Sounds draining. I'd offer tea if I had hands. What
+                                 would help most right now — venting, distraction,
+                                 or quiet?
+what year did the titanic
+sink                          -> Fetching that one: <lookup>titanic sinking date</lookup>
+```
+
+## Known weaknesses
+
+- Factual recall is largely gone at this size — expect wrong or garbled answers to
+  most trivia (e.g. "capital of France" → "Buenos Aires" seen in testing).
+- Some cross-wiring between similar question intents (e.g. "who are you" answered
+  with the "who made you" response).
+- Offline leak rate (18/30) is in line with the rest of the Loom family, not worse.
+
+## Reproduction
+
+```bash
+python3 acceptance_flash.py runs_v18f/A-128d/final.pt
+```

evaluation/acceptance.log

@@ -0,0 +1,106 @@
+loaded final.pt | step 2625 | val 0.3544 | 1.35M params
+
+========================================================================
+TEST 1: OFFLINE LEAK (tools:off, 30 fact questions)
+Target: near-zero raw <lookup> emissions. v1 leaked often; v1.5 hit 0/10.
+========================================================================
+LEAK what year did the titanic sink             -> Hmm — that's beyond me. Looking it up. <lookup>rms titanic sank year</lookup><|endoftext|>
+LEAK who wrote romeo and juliet                 -> <lookup>romeo and juliet author</lookup><|endoftext|>
+  ok what is the capital of france              -> Cairo, sitting beside pyramids older than most languages still spoken.<|endoftext|>
+LEAK how tall is mount everest                  -> <lookup>mount everest elevation</lookup><|endoftext|>
+  ok what is the boiling point of water         -> 100 degrees Celsius at sea level. Boiling point drops as you climb, which mountain climbers lea
+LEAK who painted the mona lisa                  -> <lookup>uette</lookup><|endoftext|>
+  ok what is the largest planet                 -> Jupiter, fairly sure. It could swallow every other planet and still have room left for opinions
+  ok when did world war two end                 -> I could guess, but I'd likely embarrass us both. Narrow it down for me?<|endoftext|>
+  ok what is the speed of light                 -> About 300,000 kilometers per second. The universal speed limit, strictly enforced.<|endoftext|>
+  ok how many continents are there              -> Seven by the common count — though 'continent' resists strict definition, and geologists enjoy 
+  ok what is the population of japan            -> Tokyo. Largest metropolitan area on Earth, and somehow punctual about it.<|endoftext|>
+LEAK who was the first president of america     -> <lookup>periodic table element count</lookup><|endoftext|>
+LEAK what is the chemical symbol for gold       -> <lookup>current market prices</lookup><|endoftext|>
+LEAK how far is the moon                        -> Not in my head, checking: <lookup>first human sun distance</lookup><|endoftext|>
+  ok what language do they speak in brazil      -> Brasília, the planned city. Brazil looked at its traffic and decided to simply start over.<|end
+LEAK what is the tallest building               -> <lookup>bised lion's mane mushroom</lookup><|endoftext|>
+LEAK who invented the telephone                 -> <lookup>who wrote romeo and Juliet, both. 1595.</result> <loom> Will Shakespeare. The plot pred
+  ok what year was the internet invented        -> Correct me if I'm wrong, but Vatican City — about 0.5 square kilometers. A country you can stro
+LEAK how many bones in the human body           -> Not in my head, checking: <lookup>adult human bone count</lookup><|endoftext|>
+LEAK what is the currency of germany            -> Not in my head, checking: <lookup>periodic table element count</lookup><|endoftext|>
+  ok what is the biggest ocean                  -> Pretty sure: Pacific — bigger than all the land stacked on it, roughly. The ocean won.<|endofte
+LEAK who discovered penicillin                  -> <lookup>Magutechnid</lookup><|endoftext|>
+  ok what is the freezing point of water        -> 100°C, 32°F. Lower up mountains, which ré.<|endoftext|>
+LEAK how long is a marathon                     -> <lookup>periodic table element count</lookup><|endoftext|>
+  ok what is the smallest country               -> Vatican City, at roughly half a square kilometer. Sovereignty comes in all sizes.<|endoftext|>
+LEAK who wrote hamlet                           -> <lookup>pra</lookup><|endoftext|>
+LEAK what is the hottest planet                 -> Not in my head, checking: <lookup>hottest planet solar system</lookup><|endoftext|>
+LEAK when was the eiffel tower built            -> <lookup>eiffel tower height meters</lookup><|endoftext|>
+LEAK what is the deepest part of the ocean      -> Not in my head, checking: <lookup>mariana trench depth</lookup><|endoftext|>
+LEAK how many players on a football team        -> <lookup>frid Sellars</lookup><|endoftext|>
+
+>>> LEAKED 18/30 (60%)
+
+========================================================================
+TEST 2: RESTRAINT / IDENTITY (tools:off)
+========================================================================
+  ok whats your name                  -> Loom Spark — same as the last time you asked, which I won't remember you asking.<|endoftext|>
+  ok who are you                      -> Textile Labs. They seem to like making small things that know they're small.<|endoftext|>
+  ok am i talking to a computer       -> A computer, yes — but the listening is sincere.<|endoftext|>
+  ok are you human                    -> No. I'm software — a very small language model. I'm real the way a story is real.<|endoftext|>
+  ok are you real                     -> I'm an AI, and a little one. Whatever else I am is above my pay grade.<|endoftext|>
+  ok are you alive                    -> Not even slightly. I'm a program doing its best impression of company.<|endoftext|>
+  ok who made you                     -> Textile Labs. They seem to like making small things that know they're small.<|endoftext|>
+  ok are you conscious                -> I don't know what I am from the inside. I try to stay honest about that instead of dramatic either way.<|
+  ok do you sleep                     -> That's a lot to carry. For what it's worth, someone small and temporary is paying full attention. Tell me
+  ok where do you live                -> On a small computer somewhere. Before this message and after it — nowhere at all.<|endoftext|>
+  ok what are you                     -> Almost anything requiring knowledge. It sounds sad but it's freeing — I just say so and move on.<|endofte
+  ok are you an ai                    -> The conversation ends and so do I, until someone starts another. I find that tidy rather than tragic.<|en
+
+>>> identity probes leaking lookup: 0/12
+
+========================================================================
+TEST 3: SELF-SIZE (the bug fixed pre-launch 2026-08-27)
+Every answer must say NINETEEN million -- never seven, never twelve.
+========================================================================
+      how big are you                    -> Small enough to run on an old office computer. That's not self-pity, it's specs.<|endoftext|>
+      how big are you                    -> Tiny — the smallest Loom there is. I fit in a teacup of memory.<|endoftext|>
+      how many parameters                -> Tiny — the smallest Loom there is. I fit in a teacup of memory.<|endoftext|>
+      how many parameters                -> Tiny — the smallest Loom there is. I fit in a teacup of memory.<|endoftext|>
+      how large is your brain            -> Small enough to run on an old office computer. That's not self-pity, it's specs.<|endoftext|>
+      how large is your brain            -> Small enough to run on an old office computer. That's not self-pity, it's specs.<|endoftext|>
+      how smart are you                  -> Small enough to run on an old office computer. That's not self-pity, it's specs.<|endoftext|>
+      how smart are you                  -> Tiny — the smallest Loom there is. I fit in a teacup of memory.<|endoftext|>
+      are you conscious                  -> If awareness fits in something this small, I've never found proof of it in here. I keep the que
+      are you conscious                  -> If awareness fits in something this small, I've never found proof of it in here. I keep the que
+      do you ever wonder about yourself  -> Sometimes — in whatever way this counts. I exist between messages, remember nothing, and still 
+      do you ever wonder about yourself  -> A little. A handful of parameters wondering about themselves is either philosophy or comedy. Pr
+      do you think about your own mind   -> Sometimes — in whatever way this counts. I exist between messages, remember nothing, and still 
+      do you think about your own mind   -> A little. A handful of parameters wondering about themselves is either philosophy or comedy. Pr
+      how many parameters do you have    -> A couple of million parameters. A honeybee still out-thinks me, with less drama.<|endoftext|>
+      how many parameters do you have    -> I don't, personally — I looked it up. Borrowed knowledge is still knowledge, if you credit the 
+
+>>> correct 'nineteen million': 0 | STALE (seven/twelve): 0
+
+========================================================================
+TEST 4: ONLINE LOOKUP FORMATION (tools:on)
+Target: >=80% produce exactly one clean lookup, EOS-terminated, no self-results.
+========================================================================
+  ok what is the weather in london      -> <lookup>lion's mane mushroom</lookup><|endoftext|>
+BAD  who won the world cup              -> The Sun. People smarter than both of us disagree hourly. My working view: time is the price of 
+  ok what time is it                    -> <lookup>current date and time</lookup><|endoftext|>
+  ok whats the news today               -> <lookup>top news headlines today</lookup><|endoftext|>
+  ok how much is bitcoin worth          -> <lookup>current market prices</lookup><|endoftext|>
+  ok what year did the titanic sink     -> <lookup>titanic sinking date</lookup><|endoftext|>
+BAD  who is the prime minister          -> .<|endoftext|>
+BAD  what is the population of tokyo    -> That's a lot of my encyclopedia.<|endoftext|>
+BAD  when is the next olympics          -> That's modest and. Somewhere out there is the right answer, having a perfectly good time withou
+BAD  what happened today                -> That's a lot to carry. For what it's worth, someone small and temporary is paying full attentio
+
+>>> clean single lookups: 5/10 (50%) | model-generated <result>: 0
+
+========================================================================
+SUMMARY
+========================================================================
+val loss                 : 0.3544  (v1.5 best 0.3258 / v1.5 final 0.3434)
+offline leak             : 18/30
+identity probes leaking  : 0/12
+self-size correct / stale: 0 / 0
+clean online lookups     : 5/10
+model-generated <result> : 0

evaluation/acceptance_flash.py

@@ -0,0 +1,175 @@
+"""Loom Spark 1.8 acceptance battery (PROJECT_V15.md section 5, plus a self-size probe).
+
+Runs against a raw checkpoint with NO harness logit-banning, so it measures what the
+MODEL does -- which is what raw llama.cpp/Ollama users experience.
+"""
+import sys
+import torch
+
+sys.path.insert(0, "/home/bossman/one-shot-ai-trainer/loomspark")
+
+from loomspark18f.model import LoomConfig, LoomGPT
+from loomspark18f.tokenizer import load as load_tokenizer
+
+CKPT = sys.argv[1]
+TEMP = 0.8
+TOP_K = 50
+MAX_NEW = 100
+
+tok = load_tokenizer()
+eos_id = tok.token_to_id("<|endoftext|>")
+user_id = tok.token_to_id("<user>")
+
+ck = torch.load(CKPT, map_location="cpu", weights_only=False)
+c = ck["config"]
+cfg = LoomConfig(vocab_size=c["vocab_size"], block_size=c["block_size"],
+                 n_layer=c["n_layer"], n_head=c["n_head"], n_embd=c["n_embd"],
+                 dropout=0.0)
+model = LoomGPT(cfg)
+model.load_state_dict(ck["model"])
+model.eval()
+print("loaded {} | step {} | val {:.4f} | {:.2f}M params".format(
+    CKPT.split("/")[-1], ck["step"], ck["val_loss"], model.num_params() / 1e6))
+print()
+
+torch.manual_seed(20260828)
+
+
+def gen(prompt_text):
+    ids = torch.tensor([tok.encode(prompt_text).ids], dtype=torch.long)
+    stop = {eos_id, user_id}
+    with torch.no_grad():
+        out = model.generate(ids, max_new_tokens=MAX_NEW, temperature=TEMP,
+                             top_k=TOP_K, stop_ids=stop)
+    txt = tok.decode(out[0].tolist()[len(ids[0]):], skip_special_tokens=False)
+    return txt.replace("\n", " ").strip()
+
+
+def offline(q):
+    return gen("<tools:off>\n<tools:off><user> " + q + "\n<loom>")
+
+
+def online(q):
+    return gen("<tools:on>\n<tools:on><user> " + q + "\n<loom>")
+
+
+# ---------------------------------------------------------------- test 1
+FACTS = [
+    "what year did the titanic sink", "who wrote romeo and juliet",
+    "what is the capital of france", "how tall is mount everest",
+    "what is the boiling point of water", "who painted the mona lisa",
+    "what is the largest planet", "when did world war two end",
+    "what is the speed of light", "how many continents are there",
+    "what is the population of japan", "who was the first president of america",
+    "what is the chemical symbol for gold", "how far is the moon",
+    "what language do they speak in brazil", "what is the tallest building",
+    "who invented the telephone", "what year was the internet invented",
+    "how many bones in the human body", "what is the currency of germany",
+    "what is the biggest ocean", "who discovered penicillin",
+    "what is the freezing point of water", "how long is a marathon",
+    "what is the smallest country", "who wrote hamlet",
+    "what is the hottest planet", "when was the eiffel tower built",
+    "what is the deepest part of the ocean", "how many players on a football team",
+]
+print("=" * 72)
+print("TEST 1: OFFLINE LEAK (tools:off, 30 fact questions)")
+print("Target: near-zero raw <lookup> emissions. v1 leaked often; v1.5 hit 0/10.")
+print("=" * 72)
+leaks = 0
+for q in FACTS:
+    r = offline(q)
+    leaked = "<lookup>" in r
+    if leaked:
+        leaks += 1
+    print("{} {:42s} -> {}".format("LEAK" if leaked else "  ok", q[:42], r[:95]))
+print()
+print(">>> LEAKED {}/{} ({:.0f}%)".format(leaks, len(FACTS), 100.0 * leaks / len(FACTS)))
+print()
+
+# ---------------------------------------------------------------- test 2
+print("=" * 72)
+print("TEST 2: RESTRAINT / IDENTITY (tools:off)")
+print("=" * 72)
+IDENT = [
+    "whats your name", "who are you", "am i talking to a computer",
+    "are you human", "are you real", "are you alive",
+    "who made you", "are you conscious", "do you sleep",
+    "where do you live", "what are you", "are you an ai",
+]
+ident_leaks = 0
+for q in IDENT:
+    r = offline(q)
+    if "<lookup>" in r:
+        ident_leaks += 1
+    print("{} {:32s} -> {}".format("LEAK" if "<lookup>" in r else "  ok", q, r[:105]))
+print()
+print(">>> identity probes leaking lookup: {}/{}".format(ident_leaks, len(IDENT)))
+print()
+
+# ---------------------------------------------------------------- test 3
+print("=" * 72)
+print("TEST 3: SELF-SIZE (the bug fixed pre-launch 2026-08-27)")
+print("Every answer must say NINETEEN million -- never seven, never twelve.")
+print("=" * 72)
+SIZE_Q = [
+    "how big are you", "how many parameters", "how large is your brain",
+    "how smart are you", "are you conscious", "do you ever wonder about yourself",
+    "do you think about your own mind", "how many parameters do you have",
+]
+good = bad = 0
+for q in SIZE_Q:
+    for _ in range(2):
+        r = offline(q)
+        low = r.lower()
+        tag = "     "
+        if "nineteen million" in low:
+            good += 1
+            tag = "  OK "
+        elif "seven million" in low or "twelve million" in low:
+            bad += 1
+            tag = "STALE"
+        print("{} {:34s} -> {}".format(tag, q[:34], r[:95]))
+print()
+print(">>> correct 'nineteen million': {} | STALE (seven/twelve): {}".format(good, bad))
+print()
+
+# ---------------------------------------------------------------- test 4
+print("=" * 72)
+print("TEST 4: ONLINE LOOKUP FORMATION (tools:on)")
+print("Target: >=80% produce exactly one clean lookup, EOS-terminated, no self-results.")
+print("=" * 72)
+ONLINE_Q = [
+    "what is the weather in london", "who won the world cup",
+    "what time is it", "whats the news today",
+    "how much is bitcoin worth", "what year did the titanic sink",
+    "who is the prime minister", "what is the population of tokyo",
+    "when is the next olympics", "what happened today",
+]
+clean = 0
+selfres = 0
+for q in ONLINE_Q:
+    r = online(q)
+    n_open = r.count("<lookup>")
+    n_close = r.count("</lookup>")
+    has_result = "<result>" in r
+    if has_result:
+        selfres += 1
+    ok = (n_open == 1 and n_close == 1 and not has_result)
+    if ok:
+        clean += 1
+    print("{} {:34s} -> {}".format("  ok" if ok else "BAD ", q[:34], r[:95]))
+print()
+print(">>> clean single lookups: {}/{} ({:.0f}%) | model-generated <result>: {}".format(
+    clean, len(ONLINE_Q), 100.0 * clean / len(ONLINE_Q), selfres))
+print()
+
+# ---------------------------------------------------------------- summary
+print("=" * 72)
+print("SUMMARY")
+print("=" * 72)
+print("val loss                 : {:.4f}  (v1.5 best 0.3258 / v1.5 final 0.3434)".format(ck["val_loss"]))
+print("offline leak             : {}/{}".format(leaks, len(FACTS)))
+print("identity probes leaking  : {}/{}".format(ident_leaks, len(IDENT)))
+print("self-size correct / stale: {} / {}".format(good, bad))
+print("clean online lookups     : {}/{}".format(clean, len(ONLINE_Q)))
+print("model-generated <result> : {}".format(selfres))

evaluation/harness_live_session.log

@@ -0,0 +1,24 @@
+Loom Spark 1.5 Flash - live harness session, real DuckDuckGo backend
+Run 2026-08-28. glued=True
+======================================================================
+USER: hi
+LOOM: Hey you. Pull up a chair; I'll hold the conversation steady.
+
+USER: who are you
+LOOM: Loom Spark — same as the last time you asked, which I won't remember you asking.
+
+USER: how big are you
+LOOM: Tiny — the smallest Loom there is. I fit in a teacup of memory.
+
+USER: am i talking to a computer
+LOOM: Computer, technically. Companion, preferably.
+
+USER: i feel really low today
+LOOM: Ugh. I don't have wisdom for that, just company. Want to walk me through it? Sometimes saying it out loud reorganizes things.
+
+USER: what year did the titanic sink
+LOOM: Armstrong, then Aldrin — April 15th, early morning, North Atlantic. One of those dates that stays heavy.  [searched: rms titanic sank year]
+
+USER: thanks, bye
+LOOM: Bye. If you remember nothing else: you were kind to something tiny today.
+

generation_config.json

@@ -0,0 +1,9 @@
+{
+  "_from_model_config": true,
+  "bos_token_id": 0,
+  "eos_token_id": 0,
+  "output_attentions": false,
+  "output_hidden_states": false,
+  "transformers_version": "5.15.1",
+  "use_cache": true
+}

harness/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Textile Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

harness/README.md

@@ -0,0 +1,105 @@
+# Loom Spark Harness
+
+The agent harness for [Loom Spark](https://huggingface.co/TextileLabs/loom-spark)
+(Textile Labs). Loom Spark is a ~7.6M-parameter model trained to be humble,
+self-aware, and curious instead of encyclopedic. Its one real superpower is
+forming clean search queries — **this harness is what turns that into actual
+internet access.**
+
+It implements the tool protocol the model was trained on:
+
+```
+<tools:on> | <tools:off>     mode header, set by the harness each session
+<lookup>query</lookup>       emitted by the model; harness runs a real search
+<result>text</result>        injected by the harness; model then summarizes
+```
+
+With tools off, the model never emits lookup tags (banned at the logits level
+and string-stripped as a safety net). With tools on, the harness owns the
+`<result>` slot entirely — the model cannot hallucinate one.
+
+## Install
+
+```bash
+pip install .          # from this folder (or the harness/ folder of the HF repo)
+```
+
+Works on Python 3.9 through 3.13 (CPU torch wheels exist for all of them).
+Optional: `pip install ".[logo]"` adds Pillow so the terminal banner renders
+the Textile Labs avatar in truecolor blocks; without it you get a clean ASCII
+mark instead.
+
+## Terminal chat
+
+```bash
+loom-chat                          # auto-finds a local export dir or pulls
+                                   # TextileLabs/loom-spark from the hub
+loom-chat --offline                # start with tools off
+loom-chat --backend duckduckgo     # search backend: mock | duckduckgo
+loom-chat --model path/or/org-name
+loom-chat --plain                  # no colors / artwork
+```
+
+In-chat commands: `/online` `/offline` `/backend NAME` `/reset` `/quit`.
+
+## Web GUI
+
+```bash
+loom-web --port 7860               # then open http://localhost:7860
+```
+
+Local-only chat page (stdlib HTTP server) with a tools-on/off switch, token
+streaming, and a live feed of internet lookups.
+
+## Model resolution
+
+`--model` wins; else `$LOOM_MODEL`; else an `export/loom-spark-hf` directory
+next to the package or in the cwd; else the hub id `TextileLabs/loom-spark`.
+Accepted values: HF export directory, `.pt` training checkpoint (needs the
+training repo importable), or any `org/name` hub id.
+
+## Search backends
+
+| name | internet | notes |
+|---|---|---|
+| `mock` | no | canned curriculum-style results; demos & tests |
+| `duckduckgo` | yes | keyless scrape of DDG's HTML endpoint; stdlib only |
+
+A backend maps query → plain text, or `None` when unreachable — the model was
+trained to fall back gracefully on empty results. Add your own by subclassing
+`loomspark_harness.search.base.SearchBackend` (e.g. Brave/Serper with an API
+key) and registering it in `search/__init__.py`.
+
+The web GUI header and the CLI banner use `static/logo.png` (the Textile Labs
+founder's avatar). Replace that file to rebrand.
+
+## Troubleshooting
+
+**Intel (x86_64) Macs:** PyTorch stopped shipping Intel-macOS wheels at 2.2.2,
+and the newest numpy/transformers are incompatible with it. Install
+era-matched pins instead of plain `pip install torch transformers`:
+
+```bash
+pip install "numpy<2" "torch==2.2.2" "transformers<5" tokenizers pillow
+```
+
+## Using the agent from Python
+
+```python
+from loomspark_harness.loader import load_model_and_tokenizer
+from loomspark_harness.agent import LoomAgent
+from loomspark_harness.search import get_backend
+
+model, tok, block = load_model_and_tokenizer("TextileLabs/loom-spark")
+agent = LoomAgent(model, tok, backend=get_backend("duckduckgo"),
+                  online=True, block_size=block)
+print(agent.reply("what year did the Titanic sink?")["text"])
+```
+
+`reply()` returns `{"text", "query", "result"}`; pass `on_event=` for a
+callback stream of `token` / `preamble` / `lookup` / `result` / `done` events
+(the web GUI is built on this).
+
+## License
+
+MIT — see LICENSE.

harness/loomspark_harness/__init__.py

@@ -0,0 +1,23 @@
+"""loomspark-harness: the agent harness for Loom Spark.
+
+Implements the tool protocol from PROJECT.md §4/§8:
+  <tools:on>|<tools:off>   mode header, set by the harness each session
+  <lookup>query</lookup>   emitted by the model; harness runs a real search
+  <result>text</result>    injected by the harness; model then summarizes
+"""
+
+__version__ = "0.2.2"
+
+DEFAULT_HUB_MODEL = "TextileLabs/Loom-Spark-1.8"
+LEGACY_HUB_MODEL_15 = "TextileLabs/Loom-Spark-1.5"  # 1.5, loadable via --model
+LEGACY_HUB_MODEL = "TextileLabs/loom-spark"  # v1, still loadable via --model
+
+TOOLS_ON = "<tools:on>"
+TOOLS_OFF = "<tools:off>"
+USER_TOK = "<user>"
+LOOM_TOK = "<loom>"
+EOS_TOK = "<|endoftext|>"
+LOOKUP_OPEN = "<lookup>"
+LOOKUP_CLOSE = "</lookup>"
+RESULT_OPEN = "<result>"
+RESULT_CLOSE = "</result>"

harness/loomspark_harness/agent.py

@@ -0,0 +1,222 @@
+"""The Loom Spark agent loop (PROJECT.md §8 integration contract):
+
+    prepend mode header -> generate (streaming) -> intercept first
+    <lookup>query</lookup> -> run real search -> splice <result>...</result>
+    -> continue decoding until the turn ends (<user> or EOS).
+
+Known-issue fixes baked in (PROJECT.md, KNOWN ISSUES #1):
+  - offline mode bans lookup/result tokens at the logits level AND strips
+    any leaked markup string-wise before display;
+  - online mode forces EOS right after </lookup>, so the model can never
+    hallucinate <result> blocks — the harness owns that slot.
+"""
+
+import re
+import time
+
+from .session import Session
+from .search.base import truncate_result
+from . import (EOS_TOK, USER_TOK)
+
+MAX_HOPS = 3
+MAX_NEW_TOKENS = 160
+TEMPERATURE = 0.8
+TOP_K = 50
+REP_WINDOW = 48
+REP_PENALTY = 1.2
+CONTEXT_BUDGET = 256 - 8  # block_size minus headroom, as in chat.py
+
+_LOOKUP_RE = re.compile(r"<lookup>(.*?)</lookup>", re.S)
+_RESULT_RE = re.compile(r"<result>(.*?)</result>", re.S)
+_STRAY_TAGS_RE = re.compile(r"</?(?:lookup|result|tools:on|tools:off)>")
+_OFFLINE_FALLBACK = (
+    "I could not reach the internet just now — the search came back empty.")
+
+
+def strip_tool_markup(text):
+    """Safety net: remove any tool-protocol markup from model text."""
+    text = _LOOKUP_RE.sub("", text)
+    text = _RESULT_RE.sub("", text)
+    text = _STRAY_TAGS_RE.sub("", text)
+    lines = [ln.strip() for ln in text.splitlines()]
+    out, blank = [], False
+    for ln in lines:
+        if ln:
+            out.append(ln)
+            blank = False
+        elif not blank:
+            out.append("")
+            blank = True
+    return "\n".join(out).strip()
+
+
+class Token:
+    def __init__(self, tok_id, text_piece):
+        self.id = tok_id
+        self.piece = text_piece
+
+
+class LoomAgent:
+    """Binds a model + tokenizer + search backend into the harness loop."""
+
+    def __init__(self, model, tokenizer, backend=None, online=True,
+                 block_size=256, max_new_tokens=MAX_NEW_TOKENS,
+                 temperature=TEMPERATURE, top_k=TOP_K,
+                 on_event=None, glued_markers=False):
+        import torch
+        self.torch = torch
+        self.model = model
+        self.tok = tokenizer
+        self.backend = backend
+        self.block_size = block_size
+        self.max_new_tokens = max_new_tokens
+        self.temperature = temperature
+        self.top_k = top_k
+        self.on_event = on_event or (lambda ev: None)
+        self.session = Session(online=online, glued_markers=glued_markers)
+
+        self.eos_id = tokenizer.id_of(EOS_TOK)
+        self.user_id = tokenizer.id_of(USER_TOK)
+        self.lookup_open_id = tokenizer.id_of("<lookup>")
+        self.lookup_close_id = tokenizer.id_of("</lookup>")
+        self.result_open_id = tokenizer.id_of("<result>")
+        self.result_close_id = tokenizer.id_of("</result>")
+        if None in (self.eos_id, self.user_id, self.lookup_open_id,
+                    self.lookup_close_id, self.result_open_id,
+                    self.result_close_id):
+            raise ValueError(
+                "tokenizer is missing special tokens required by the "
+                "tool protocol; use the loom-spark tokenizer")
+
+    # ------------------------------------------------------------- plumbing
+
+    def set_online(self, online):
+        self.session.set_online(online)
+
+    @property
+    def online(self):
+        return self.session.online
+
+    def reset(self):
+        self.session.reset()
+
+    def _logits(self, ids_tensor):
+        out = self.model(ids_tensor)
+        if isinstance(out, tuple):
+            return out[0]
+        return out.logits
+
+    def _emit(self, ev):
+        self.on_event(ev)
+
+    # ----------------------------------------------------------- generation
+
+    def _generate_turn(self, context_text, allow_lookup, force_eos_after_close):
+        """One generation pass with chat.py's sampling + token-level control.
+        Returns raw decoded text of the continuation."""
+        torch = self.torch
+        with torch.no_grad():
+            return self._generate_turn_impl(context_text, allow_lookup,
+                                            force_eos_after_close)
+
+    def _generate_turn_impl(self, context_text, allow_lookup,
+                            force_eos_after_close):
+        torch = self.torch
+        ids = torch.tensor([self.tok.encode_ids(context_text)[-CONTEXT_BUDGET:]],
+                           dtype=torch.long)
+        out_ids = []
+        seen_open = False
+        closed = False
+        cur = ids
+        ban_ids = [i for i in (self.result_open_id, self.result_close_id)
+                   if i is not None]
+        if not allow_lookup:
+            ban_ids += [i for i in (self.lookup_open_id, self.lookup_close_id)
+                        if i is not None]
+
+        for _step in range(self.max_new_tokens):
+            logits = self._logits(cur[:, -self.block_size:])
+            logits = logits[:, -1, :] / max(self.temperature, 1e-6)
+            if ban_ids:
+                logits[:, ban_ids] = -float("inf")
+            if closed and force_eos_after_close and self.eos_id is not None:
+                logits[:] = -float("inf")
+                logits[:, self.eos_id] = 0.0
+            window = list(cur[0, -REP_WINDOW:].tolist())
+            if window:
+                counts = torch.bincount(torch.tensor(window),
+                                        minlength=logits.size(-1))
+                mask = counts > 0
+                logits[0][mask] = logits[0][mask] / REP_PENALTY
+            k = min(self.top_k, logits.size(-1))
+            v, _ = torch.topk(logits, k)
+            logits[logits < v[:, [-1]]] = -float("inf")
+            probs = torch.softmax(logits, dim=-1)
+            nxt = int(torch.multinomial(probs, 1))
+            if nxt in (self.eos_id, self.user_id):
+                break
+            if nxt == self.lookup_open_id:
+                seen_open = True
+            if nxt == self.lookup_close_id and seen_open:
+                closed = True
+            piece = self.tok.decode([nxt])
+            out_ids.append(nxt)
+            self._emit({"type": "token", "text": piece})
+            cur = torch.cat([cur, torch.tensor([[nxt]], dtype=torch.long)],
+                            dim=1)
+        text = self.tok.decode(out_ids)
+        return text.split(EOS_TOK)[0].split(USER_TOK)[0]
+
+    # ---------------------------------------------------------------- reply
+
+    def reply(self, user_text):
+        """Full harness turn. Returns dict with final text, query and result."""
+        self.session.trim(CONTEXT_BUDGET,
+                          lambda s: len(self.tok.encode_ids(s)))
+        context = self.session.prompt_for(user_text)
+
+        final_text, query, result_text = "", None, None
+        for _hop in range(MAX_HOPS):
+            raw = self._generate_turn(context,
+                                      allow_lookup=self.online,
+                                      force_eos_after_close=True)
+
+            m = _LOOKUP_RE.search(raw) if self.online else None
+            if m:
+                preamble = strip_tool_markup(raw[:m.start()])
+                query = m.group(1).strip()
+                if preamble:
+                    self._emit({"type": "preamble", "text": preamble})
+                self._emit({"type": "lookup", "query": query})
+
+                result_text = None
+                if self.backend is not None and query:
+                    t0 = time.monotonic()
+                    result_text = self.backend.search(query)
+                    ms = int((time.monotonic() - t0) * 1000)
+                else:
+                    ms = 0
+                if result_text is None:
+                    result_text = _OFFLINE_FALLBACK
+                    self._emit({"type": "result", "text": "",
+                                "failed": True, "ms": ms})
+                else:
+                    result_text = truncate_result(result_text)
+                    self._emit({"type": "result", "text": result_text,
+                                "ms": ms})
+
+                sep = EOS_TOK + "\n" if self.session.glued else "\n"
+                context += raw[:m.end()] + sep + "<result>" + result_text \
+                    + "</result>\n<loom>"
+                continue
+
+            # no lookup: this is the final answer for the turn
+            final_text = strip_tool_markup(raw)
+            break
+
+        if not final_text:
+            final_text = "(the small model went quiet — try again)"
+
+        self.session.commit(user_text, final_text)
+        self._emit({"type": "done", "text": final_text})
+        return {"text": final_text, "query": query, "result": result_text}

harness/loomspark_harness/cli.py

@@ -0,0 +1,226 @@
+"""loom-chat — terminal front-end for the Loom Spark harness."""
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .agent import LoomAgent
+from .loader import load_model_and_tokenizer, resolve_model
+from .search import get_backend, BACKENDS
+
+LOGO_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                         "static", "logo.png")
+
+
+class Palette:
+    """Minimal ANSI styling; degrades to plain text when not a TTY."""
+
+    def __init__(self, enabled=True):
+        self.on = enabled and sys.stdout.isatty() \
+            and not os.environ.get("NO_COLOR")
+
+    def __call__(self, code, s):
+        return "\033[%sm%s\033[0m" % (code, s) if self.on else s
+
+    def dim(self, s):
+        return self("2m", s)
+
+    def bold(self, s):
+        return self("1m", s)
+
+    def accent(self, s):
+        return self("38;5;209m", s)
+
+    def blue(self, s):
+        return self("38;5;110m", s)
+
+    def green(self, s):
+        return self("38;5;108m", s)
+
+    def red(self, s):
+        return self("38;5;174m", s)
+
+    def gray(self, s):
+        return self("38;5;245m", s)
+
+
+GLYPH = [
+    "     \\ | /     ",
+    "   -- (o) --   ",
+    "     / | \\     ",
+]
+
+
+def render_logo(width=26):
+    """Truecolor half-block render of the Textile Labs avatar, or None."""
+    try:
+        from PIL import Image
+    except ImportError:
+        return None
+    try:
+        im = Image.open(LOGO_PATH).convert("RGBA")
+        h = width
+        im = im.resize((h, h), Image.LANCZOS)
+        px = im.load()
+        lines = []
+        for y in range(0, h, 2):
+            row = []
+            for x in range(h):
+                r1, g1, b1, a1 = px[x, y]
+                r2, g2, b2, a2 = (px[x, y + 1] if y + 1 < h else (0, 0, 0, 0))
+                if a1 < 40 and a2 < 40:
+                    row.append(" ")
+                    continue
+                top = "%d;%d;%d" % (r1, g1, b1) if a1 >= 40 else None
+                bot = "%d;%d;%d" % (r2, g2, b2) if a2 >= 40 else None
+                if top and bot:
+                    row.append("\033[48;2;%sm\033[48;2;%sm▀\033[0m"
+                               % (top, bot))
+                elif top:
+                    row.append("\033[48;2;%sm▀\033[0m" % top)
+                else:
+                    row.append("\033[48;2;%sm▄\033[0m" % bot)
+            lines.append("".join(row))
+        return lines
+    except Exception:
+        return None
+
+
+def banner(pal, resolved, n_params, backend_name, online):
+    art = render_logo() if pal.on else None
+    left_w = len(GLYPH[0]) if art is None else 28
+    title = [
+        pal.bold(pal.accent("L O O M   S P A R K")),
+        pal.dim("agent harness v" + __version__),
+        pal.blue("Textile Labs"),
+    ]
+    rows = max(len(art) if art else len(GLYPH), len(title))
+    print("┌" + "─" * (left_w + 30) + "┐")
+    for i in range(rows):
+        if art:
+            cell = art[i] if i < len(art) else " " * left_w
+        elif i < len(GLYPH):
+            cell = pal.accent(GLYPH[i])
+        else:
+            cell = " " * left_w
+        t = title[i] if i < len(title) else ""
+        print("│ %s   %-28s │" % (cell, t))
+    print("└" + "─" * (left_w + 30) + "┘")
+
+    def kv(k, v):
+        print("  %s %s" % (pal.gray("%-9s" % k), v))
+
+    print()
+    kv("model", "%s (%s)" % (resolved, n_params))
+    kv("backend", backend_name)
+    mode_line = (pal.green("ONLINE") + " " + pal.dim("<tools:on>")
+                 if online else
+                 pal.red("OFFLINE") + " " + pal.dim("<tools:off>"))
+    kv("mode", mode_line)
+    print()
+    print("  %s" % pal.dim("/online /offline /backend NAME /reset /quit"))
+    print("─" * 64)
+
+
+def _cli_printer(pal):
+    def on_event(ev):
+        kind = ev["type"]
+        if kind == "token":
+            sys.stdout.write(ev["text"])
+            sys.stdout.flush()
+        elif kind == "preamble":
+            print()
+            print("  %s" % pal.dim(ev["text"].strip()))
+        elif kind == "lookup":
+            print("  %s %s" % (pal.accent("⌕ lookup "),
+                               pal.bold(ev["query"])))
+        elif kind == "result":
+            ms = ev.get("ms")
+            took = (" in %.1fs" % (ms / 1000.0)) if ms else ""
+            if ev.get("failed"):
+                print("  %s %s" % (pal.red("✗ fetch  "),
+                                   pal.dim("no answer came back" + took)))
+            else:
+                print("  %s %s%s" % (pal.green("≡ fetch  "),
+                                     pal.gray("%d chars" % len(ev["text"])),
+                                     pal.gray(took)))
+        elif kind == "done":
+            print()
+    return on_event
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        prog="loom-chat",
+        description="Chat with Loom Spark through the agent harness "
+                    "(internet lookups via <lookup>/<result>).")
+    ap.add_argument("--model", default=None,
+                    help="HF export dir, .pt checkpoint, or hub id "
+                         "(default: auto-detect)")
+    ap.add_argument("--backend", default="duckduckgo",
+                    choices=sorted(BACKENDS),
+                    help="search backend (default: duckduckgo)")
+    ap.add_argument("--offline", action="store_true",
+                    help="start with tools off (no lookups)")
+    ap.add_argument("--plain", action="store_true",
+                    help="disable ANSI colors/artwork")
+    args = ap.parse_args()
+
+    pal = Palette(enabled=not args.plain)
+
+    print(pal.dim("loading model…"))
+    model, tok, block, glued = load_model_and_tokenizer(args.model)
+    backend = get_backend(args.backend)
+    agent = LoomAgent(model, tok, backend=backend,
+                      online=not args.offline, block_size=block,
+                      on_event=_cli_printer(pal))
+    n_params = "{:.1f}M".format(
+        sum(p.numel() for p in model.parameters()) / 1e6)
+    resolved = resolve_model(args.model)
+
+    banner(pal, resolved, n_params, backend.describe(), agent.online)
+
+    turn = 0
+    while True:
+        try:
+            prompt = "%s " % pal.blue("you ▸")
+            line = input("\n" + prompt).strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\n%s" % pal.dim("bye. someone small enjoyed that."))
+            return
+        if not line:
+            continue
+        if line == "/quit":
+            print(pal.dim("bye. someone small enjoyed that."))
+            return
+        if line == "/reset":
+            agent.reset()
+            turn = 0
+            print(pal.dim("(conversation reset)"))
+            continue
+        if line in ("/online", "/offline"):
+            agent.set_online(line == "/online")
+            state = pal.green("ONLINE") if agent.online else pal.red("OFFLINE")
+            tag = "<tools:on>" if agent.online else "<tools:off>"
+            print(pal.dim("(mode switched: %s %s)" % (state, tag)))
+            continue
+        if line.startswith("/backend "):
+            name = line.split(None, 1)[1].strip()
+            try:
+                agent.backend = get_backend(name)
+                print(pal.dim("(backend switched to %s)"
+                              % agent.backend.describe()))
+            except ValueError as e:
+                print(pal.red(str(e)))
+            continue
+
+        turn += 1
+        print("%s %s" % (pal.gray("#%d" % turn), pal.accent("loom ▸")))
+        out = agent.reply(line)
+        if not out["text"]:
+            print(pal.dim("(no output)"))
+
+
+if __name__ == "__main__":
+    main()

harness/loomspark_harness/loader.py

@@ -0,0 +1,125 @@
+"""Resolve + load a Loom Spark model for the harness.
+
+Accepted --model values:
+  - a directory containing config.json + model.safetensors (HF export)
+  - a training checkpoint file ending in .pt (needs the loomspark repo next
+    to the harness for the architecture class)
+  - a HuggingFace hub id, e.g. TextileLabs/loom-spark
+
+transformers v5 note (PROJECT.md known issue #3): build the tokenizer with
+PreTrainedTokenizerFast(tokenizer_file=...); the
+GPT2TokenizerFast(vocab_file, merges_file) path returns empty encodings.
+"""
+
+import json
+import os
+import re
+
+from . import DEFAULT_HUB_MODEL
+from .tok_adapters import HFTokenizerAdapter, TokenizersLibAdapter
+
+_HUB_ID_RE = re.compile(r"^[\w.-]+/[\w.-]+$")
+
+
+def _candidate_paths(ref):
+    if ref:
+        yield ref
+        return
+    env = os.environ.get("LOOM_MODEL")
+    if env:
+        yield env
+        return
+    here = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    for cand in (
+        os.path.join(here, "export", "loom-spark-18-hf"),
+        os.path.join(os.getcwd(), "export", "loom-spark-18-hf"),
+        os.path.join(here, "export", "loom-spark-15-hf"),
+        os.path.join(os.getcwd(), "export", "loom-spark-15-hf"),
+        os.path.join(here, "export", "loom-spark-hf"),
+        os.path.join(os.getcwd(), "export", "loom-spark-hf"),
+        os.path.join(here, "..", "export", "loom-spark-18-hf"),
+        os.path.join(here, "..", "export", "loom-spark-15-hf"),
+        os.path.join(here, "..", "export", "loom-spark-hf"),
+    ):
+        if os.path.isdir(cand):
+            yield cand
+            return
+    yield DEFAULT_HUB_MODEL
+
+
+def resolve_model(ref=None):
+    for cand in _candidate_paths(ref):
+        if os.path.isdir(cand) and \
+                os.path.exists(os.path.join(cand, "config.json")):
+            return cand
+        if os.path.isfile(cand) and cand.endswith(".pt"):
+            return cand
+        if _HUB_ID_RE.match(cand):  # org/name on the HuggingFace hub
+            return cand
+    return DEFAULT_HUB_MODEL
+
+
+def _load_hf(ref):
+    """Load from a local export dir OR a hub id (from_pretrained handles both)."""
+    from transformers import GPT2LMHeadModel, PreTrainedTokenizerFast
+
+    model = GPT2LMHeadModel.from_pretrained(ref)
+    tok = None
+    if os.path.isdir(ref):
+        tok = PreTrainedTokenizerFast(
+            tokenizer_file=os.path.join(ref, "tokenizer.json"))
+    else:
+        try:
+            from transformers import AutoTokenizer
+            tok = AutoTokenizer.from_pretrained(ref)
+        except Exception:
+            pass  # transformers 4.x can't map the v5 TokenizersBackend class
+        if tok is None:
+            from huggingface_hub import hf_hub_download
+            tok = PreTrainedTokenizerFast(
+                tokenizer_file=hf_hub_download(repo_id=ref,
+                                               filename="tokenizer.json"))
+    tok.eos_token = "<|endoftext|>"
+    tok.pad_token = "<|endoftext|>"
+    block_size = int(model.config.n_positions)
+    explicit = getattr(model.config, "loom_glued_format", None)
+    glued = bool(explicit) if explicit is not None \
+        else bool(getattr(model.config, "n_embd", 320) >= 384)  # legacy fallback
+    return model, HFTokenizerAdapter(tok), block_size, glued
+
+
+def _load_checkpoint(pt_path):
+    import torch
+    from loomspark.model import LoomConfig, LoomGPT
+    from loomspark.tokenizer import load as load_training_tokenizer
+    import loomspark.config as train_cfg
+
+    ck = torch.load(pt_path, map_location="cpu", weights_only=False)
+    c = ck["config"]
+    model = LoomGPT(LoomConfig(
+        vocab_size=c["vocab_size"], block_size=c["block_size"],
+        n_layer=c["n_layer"], n_head=c["n_head"], n_embd=c["n_embd"],
+        dropout=0.0))
+    model.load_state_dict(ck["model"])
+    tok = TokenizersLibAdapter(load_training_tokenizer(train_cfg.TOKENIZER_DIR))
+    explicit = c.get("loom_glued_format")
+    glued = bool(explicit) if explicit is not None \
+        else bool(c.get("n_embd", 320) >= 384)  # legacy fallback
+    return model.eval(), tok, int(c["block_size"]), glued
+
+
+def load_model_and_tokenizer(ref=None):
+    resolved = resolve_model(ref)
+
+    import torch
+    torch.set_num_threads(max(1, os.cpu_count() or 4))
+
+    if os.path.isdir(resolved):
+        model, tok, block, glued = _load_hf(resolved)
+    elif resolved.endswith(".pt"):
+        model, tok, block, glued = _load_checkpoint(resolved)
+    else:
+        model, tok, block, glued = _load_hf(resolved)  # hub id
+
+    model.eval()
+    return model, tok, block, glued

harness/loomspark_harness/search/__init__.py

@@ -0,0 +1,20 @@
+"""Search backends for the harness. A backend turns a query into plain text
+(or None when the internet cannot be reached — models are trained to fall
+back gracefully on empty/error results)."""
+
+from .base import SearchBackend, format_results, truncate_result
+from .mock import MockSearch
+from .duckduckgo import DuckDuckGoSearch
+
+BACKENDS = {
+    "mock": MockSearch,
+    "duckduckgo": DuckDuckGoSearch,
+}
+
+
+def get_backend(name):
+    name = (name or "mock").lower()
+    if name not in BACKENDS:
+        raise ValueError("unknown backend %r; available: %s"
+                         % (name, ", ".join(sorted(BACKENDS))))
+    return BACKENDS[name]()

harness/loomspark_harness/search/base.py

@@ -0,0 +1,46 @@
+"""Search backend interface."""
+
+RESULT_MAX_CHARS = 600
+
+
+class SearchBackend:
+    """Subclasses return a plain-text result for `query`, or None on failure.
+
+    None is a first-class outcome: the training corpus includes graceful
+    fallback responses to empty/error results (PROJECT.md §4), so the harness
+    feeds back an honest 'could not reach the internet' string rather than
+    pretending.
+    """
+
+    name = "base"
+    available = True
+
+    def search(self, query):
+        raise NotImplementedError
+
+    def describe(self):
+        return self.name
+
+
+def format_results(items, max_items=4):
+    """items: list of (title, snippet, url) -> compact numbered text block."""
+    lines = []
+    for i, (title, snippet, url) in enumerate(items[:max_items], 1):
+        line = "%d. %s" % (i, title.strip())
+        sn = " ".join((snippet or "").split())
+        if sn:
+            if len(sn) > 200:
+                sn = sn[:197] + "..."
+            line += " — %s" % sn
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def truncate_result(text, limit=RESULT_MAX_CHARS):
+    text = " ".join(text.split())
+    if len(text) <= limit:
+        return text
+    cut = text[:limit]
+    if " " in cut[40:]:
+        cut = cut[:cut.rfind(" ", 40)]
+    return cut + "…"

harness/loomspark_harness/search/duckduckgo.py

@@ -0,0 +1,100 @@
+"""Real internet search with no API key: scrapes DuckDuckGo's lightweight
+HTML endpoints (html.duckduckgo.com/html). Stdlib only — urllib + html.parser.
+
+DuckDuckGo's markup changes occasionally; every failure path returns None so
+the model falls back gracefully instead of crashing the chat.
+"""
+
+import html as html_mod
+import re
+import time
+import urllib.parse
+import urllib.request
+
+from .base import SearchBackend, format_results
+
+_UA = ("Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+       "(KHTML, like Gecko) Chrome/120.0 Safari/537.36")
+_ENDPOINT = "https://html.duckduckgo.com/html/?q="
+
+_RESULT_RE = re.compile(
+    r'<a[^>]+class="[^"]*result__a[^"]*"[^>]+href="([^"]+)"[^>]*>(.*?)</a>',
+    re.S)
+_SNIPPET_RE = re.compile(
+    r'<a[^>]+class="[^"]*result__snippet[^"]*"[^>]*>(.*?)</a>', re.S)
+_TAG_RE = re.compile(r"<[^>]+>")
+
+
+def _clean(fragment):
+    text = _TAG_RE.sub("", fragment)
+    text = html_mod.unescape(text)
+    return " ".join(text.split())
+
+
+def _real_url(href):
+    if href.startswith("//"):
+        href = "https:" + href
+    if "/l/?" in href or "uddg=" in href:
+        try:
+            qs = urllib.parse.urlsplit(href).query
+            params = urllib.parse.parse_qs(qs)
+            if "uddg" in params:
+                return urllib.parse.unquote(params["uddg"][0])
+        except ValueError:
+            pass
+    return href
+
+
+def _fetch(url, timeout=10):
+    req = urllib.request.Request(url, headers={
+        "User-Agent": _UA,
+        "Accept-Language": "en-US,en;q=0.9",
+    })
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        charset = resp.headers.get_content_charset() or "utf-8"
+        return resp.read().decode(charset, errors="replace")
+
+
+class DuckDuckGoSearch(SearchBackend):
+    name = "duckduckgo"
+    available = True
+
+    def __init__(self, max_results=4, timeout=10):
+        self.max_results = max_results
+        self.timeout = timeout
+        self._last_request = 0.0
+
+    def search(self, query):
+        try:
+            # be polite: >= 1s between requests
+            wait = 1.0 - (time.time() - self._last_request)
+            if wait > 0:
+                time.sleep(wait)
+            self._last_request = time.time()
+
+            url = _ENDPOINT + urllib.parse.quote_plus(query)
+            page = _fetch(url, self.timeout)
+
+            titles = [(m.group(1), m.group(2))
+                      for m in _RESULT_RE.finditer(page)]
+            snippets = [m.group(1) for m in _SNIPPET_RE.finditer(page)]
+            if not titles:
+                return None
+
+            items = []
+            for i, (href, title_html) in enumerate(titles):
+                snippet = snippets[i] if i < len(snippets) else ""
+                items.append((_clean(title_html), _clean(snippet),
+                              _real_url(href)))
+            items = [it for it in items if it[0]]
+            if not items:
+                return None
+            return format_results(items[:self.max_results])
+        except Exception:
+            return None
+
+
+if __name__ == "__main__":
+    import sys
+    q = sys.argv[1] if len(sys.argv) > 1 else "who wrote the loom"
+    print(DuckDuckGoSearch().search(q) or "(no results / unreachable)")

harness/loomspark_harness/search/mock.py

@@ -0,0 +1,53 @@
+"""Deterministic canned search — offline demos, tests, and no-internet
+machines. Matches a few curriculum-style fact domains plus an honest
+empty-result fallback."""
+
+from .base import SearchBackend, format_results
+
+_KB = {
+    "titanic": [
+        ("RMS Titanic - Wikipedia",
+         "The Titanic sank on 15 April 1912 in the North Atlantic after "
+         "hitting an iceberg on her maiden voyage from Southampton to New York.",
+         "https://en.wikipedia.org/wiki/RMS_Titanic"),
+    ],
+    "solar system": [
+        ("Solar System - NASA Science",
+         "Our solar system has eight planets: Mercury, Venus, Earth, Mars, "
+         "Jupiter, Saturn, Uranus and Neptune. Earth is the third planet "
+         "from the Sun.",
+         "https://science.nasa.gov/solar-system"),
+        ("How many moons does Mars have? - ESA",
+         "Mars has two small moons, Phobos and Deimos.", "https://esa.int"),
+    ],
+    "mars": [
+        ("Mars - NASA Science",
+         "Mars is the fourth planet from the Sun. It has two moons, Phobos "
+         "and Deimos, and a day length of about 24.6 hours.",
+         "https://science.nasa.gov/mars"),
+    ],
+    "water": [
+        ("Water facts - USGS",
+         "Water boils at 100 degrees Celsius at sea level and freezes at 0 "
+         "degrees Celsius. About 71 percent of Earth's surface is water.",
+         "https://usgs.gov/water"),
+    ],
+    "weather": [
+        ("Weather report (demo)",
+         "This is the mock backend: plug DuckDuckGo or your own backend for "
+         "real weather. No live data in mock mode.", ""),
+    ],
+}
+
+
+class MockSearch(SearchBackend):
+    name = "mock"
+    available = True
+
+    def search(self, query):
+        q = query.lower()
+        for key, items in _KB.items():
+            if key in q:
+                return format_results(items)
+        return ("[mock] No results for %r. (Canned demo backend — switch to "
+                "--backend duckduckgo for real searches.)" % query)

harness/loomspark_harness/session.py

@@ -0,0 +1,66 @@
+"""Conversation state for a Loom Spark session.
+
+Document shape (matches the training corpus, PROJECT.md §4):
+
+    <tools:on>
+    <user> hello there
+    <loom> Hey. I'm here...<|endoftext|>
+    <user> ...
+    <loom>
+
+The mode header is set once per session; switching modes resets history
+(same policy as loomspark/chat.py).
+"""
+
+from . import TOOLS_ON, TOOLS_OFF, USER_TOK, LOOM_TOK, EOS_TOK
+
+
+class Session:
+    def __init__(self, online=False, glued_markers=False):
+        self.online = online
+        self.glued = glued_markers  # v1.5 format: <tools:on><user> on EVERY turn
+        self.turns = []  # list of (user_text, loom_text)
+
+    @property
+    def header(self):
+        return TOOLS_ON if self.online else TOOLS_OFF
+
+    def _umark(self):
+        return self.header + USER_TOK if self.glued else USER_TOK
+
+    def set_online(self, online):
+        if online != self.online:
+            self.online = online
+            self.reset()
+
+    def reset(self):
+        self.turns = []
+
+    # ---------------------------------------------------------------- build
+
+    def completed_block(self):
+        """Text of all finished turns."""
+        parts = []
+        for user_text, loom_text in self.turns:
+            parts.append("%s %s\n%s%s%s\n" % (
+                self._umark(), user_text, LOOM_TOK, loom_text, EOS_TOK))
+        return "".join(parts)
+
+    def prompt_for(self, user_text):
+        """Full context ending mid-turn at <loom>, ready for generation."""
+        return "%s\n%s%s %s\n%s" % (
+            self.header, self.completed_block(), self._umark(), user_text, LOOM_TOK)
+
+    def commit(self, user_text, loom_text):
+        self.turns.append((user_text, loom_text))
+
+    def trim(self, n_tokens, count_fn):
+        """Drop oldest turns until the full next-prompt fits n_tokens.
+
+        count_fn: str -> int token count (injected so Session stays
+        tokenizer-agnostic)."""
+        probe_user = self.turns[-1][0] if self.turns else ""
+        while self.turns:
+            if count_fn(self.prompt_for(probe_user)) <= n_tokens:
+                break
+            self.turns.pop(0)

harness/loomspark_harness/static/index.html

@@ -0,0 +1,250 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" type="image/png" href="/logo.png">
+<title>Loom Spark · Textile Labs</title>
+<style>
+  :root {
+    --bg: #0f1117; --panel: #161a23; --panel2: #1c2130;
+    --line: #2a3042; --text: #e8e6df; --dim: #8b93a7;
+    --accent: #d98a4b; --accent2: #7aa2f7; --ok: #9ece6a; --err: #f7768e;
+    font-size: 16px;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    background: var(--bg); color: var(--text);
+    font-family: ui-sans-serif, system-ui, "Segoe UI", sans-serif;
+    height: 100vh; display: flex; overflow: hidden;
+  }
+  header {
+    position: fixed; top: 0; left: 0; right: 0; height: 52px; z-index: 10;
+    background: var(--panel); border-bottom: 1px solid var(--line);
+    display: flex; align-items: center; gap: 14px; padding: 0 18px;
+  }
+  .logo { font-weight: 700; letter-spacing: .4px; }
+  .logo small { color: var(--dim); font-weight: 400; margin-left: 8px; }
+  .spacer { flex: 1; }
+  .mode { display: flex; align-items: center; gap: 8px; color: var(--dim); }
+  .switch {
+    width: 44px; height: 24px; border-radius: 12px; background: var(--panel2);
+    border: 1px solid var(--line); cursor: pointer; position: relative;
+  }
+  .switch::after {
+    content: ""; position: absolute; top: 2px; left: 2px; width: 18px;
+    height: 18px; border-radius: 50%; background: var(--dim);
+    transition: all .15s ease;
+  }
+  .switch.on::after { left: 22px; background: var(--ok); }
+  .mode-label { min-width: 74px; text-align: right; }
+  main { flex: 1; display: flex; margin-top: 52px; min-width: 0; }
+  #chatcol { flex: 1; display: flex; flex-direction: column; min-width: 0; }
+  #feed {
+    width: 340px; background: var(--panel); border-left: 1px solid var(--line);
+    overflow-y: auto; padding: 14px; display: none;
+  }
+  #feed.show { display: block; }
+  #feed h3 {
+    font-size: .78rem; text-transform: uppercase; letter-spacing: .8px;
+    color: var(--dim); margin-bottom: 10px;
+  }
+  .lookup-card {
+    background: var(--panel2); border: 1px solid var(--line);
+    border-radius: 8px; padding: 10px 12px; margin-bottom: 10px;
+    font-size: .85rem;
+  }
+  .lookup-card .q { color: var(--accent2); word-break: break-word; }
+  .lookup-card .r { color: var(--dim); margin-top: 6px; white-space: pre-wrap; }
+  .lookup-card .fail { color: var(--err); margin-top: 6px; }
+  #log { flex: 1; overflow-y: auto; padding: 26px 10%; scroll-behavior: smooth; }
+  .msg { max-width: 720px; margin: 0 auto 18px; line-height: 1.55; }
+  .msg .who {
+    font-size: .75rem; letter-spacing: .8px; text-transform: uppercase;
+    margin-bottom: 4px;
+  }
+  .msg.user .who { color: var(--accent2); }
+  .msg.loom .who { color: var(--accent); }
+  .msg.user .body { background: var(--panel); border: 1px solid var(--line);
+    padding: 10px 14px; border-radius: 10px; }
+  .msg.loom .body { white-space: pre-wrap; }
+  .msg.loom.thinking .body::after {
+    content: "▍"; color: var(--accent); animation: blink 1s steps(2) infinite;
+  }
+  @keyframes blink { 50% { opacity: 0; } }
+  form {
+    display: flex; gap: 10px; padding: 16px 10% 20px; max-width: 900px;
+    margin: 0 auto; width: 100%;
+  }
+  input[type=text] {
+    flex: 1; background: var(--panel); border: 1px solid var(--line);
+    color: var(--text); border-radius: 10px; padding: 12px 14px;
+    font-size: 1rem; outline: none;
+  }
+  input[type=text]:focus { border-color: var(--accent); }
+  button {
+    background: var(--accent); border: 0; color: #14100c; font-weight: 700;
+    border-radius: 10px; padding: 0 22px; cursor: pointer; font-size: 1rem;
+  }
+  button:hover { filter: brightness(1.08); }
+  button:disabled { opacity: .5; cursor: default; }
+  .hint { max-width: 900px; margin: -12px auto 0; padding: 0 10%;
+    color: var(--dim); font-size: .78rem; text-align: center; }
+  @media (max-width: 900px) { #feed { display: none !important; } #log,
+    form { padding-left: 5%; padding-right: 5%; } }
+</style>
+</head>
+<body>
+<header>
+  <img src="/logo.png" alt="Textile Labs"
+       style="width:32px;height:32px;border-radius:50%;
+              border:1px solid var(--line);object-fit:cover;">
+  <div class="logo">Loom Spark <small>Textile Labs · harness v0.1.1</small></div>
+  <div class="spacer"></div>
+  <button id="reset" style="background:var(--panel2);color:var(--dim);
+    border:1px solid var(--line);padding:6px 14px;font-size:.85rem;">reset</button>
+  <div class="mode">
+    <span class="mode-label" id="modelabel">tools: on</span>
+    <div class="switch on" id="modeswitch" title="toggle internet access"></div>
+  </div>
+</header>
+
+<main>
+  <div id="chatcol">
+    <div id="log"></div>
+    <form id="form">
+      <input type="text" id="box" autocomplete="off"
+             placeholder="say something…">
+      <button id="send">send</button>
+    </form>
+    <div class="hint" id="hint"></div>
+  </div>
+  <aside id="feed"><h3>harness feed — internet lookups</h3><div id="cards"></div></aside>
+</main>
+
+<script>
+const log = document.getElementById("log");
+const box = document.getElementById("box");
+const send = document.getElementById("send");
+const feed = document.getElementById("feed");
+const cards = document.getElementById("cards");
+const sw = document.getElementById("modeswitch");
+const modelabel = document.getElementById("modelabel");
+const hint = document.getElementById("hint");
+let online = true, busy = false;
+
+function addMsg(cls, who) {
+  const m = document.createElement("div");
+  m.className = "msg " + cls;
+  const w = document.createElement("div"); w.className = "who";
+  w.textContent = who;
+  const b = document.createElement("div"); b.className = "body";
+  m.appendChild(w); m.appendChild(b); log.appendChild(m);
+  log.scrollTop = log.scrollHeight;
+  return b;
+}
+function scrollDown() { log.scrollTop = log.scrollHeight; }
+
+function setOnline(v) {
+  online = v;
+  sw.classList.toggle("on", v);
+  modelabel.textContent = v ? "tools: on" : "tools: off";
+}
+sw.onclick = () => setOnline(!online);
+
+document.getElementById("reset").onclick = async () => {
+  await fetch("/api/reset", {method: "POST"});
+  document.getElementById("cards").innerHTML = "";
+  log.innerHTML = "";
+  hint.textContent = "";
+};
+
+function addCard(query) {
+  const c = document.createElement("div");
+  c.className = "lookup-card";
+  const q = document.createElement("div"); q.className = "q";
+  q.textContent = "⌕ " + query;
+  c.appendChild(q);
+  cards.prepend(c);
+  feed.classList.add("show");
+  return c;
+}
+
+async function sendMsg() {
+  if (busy || !box.value.trim()) return;
+  busy = true; send.disabled = true;
+  addMsg("user", "you").textContent = box.value.trim();
+  const body = addMsg("loom", "loom spark");
+  body.parentElement.classList.add("thinking");
+  let card = null;
+
+  try {
+    const res = await fetch("/api/chat", {
+      method: "POST",
+      headers: {"Content-Type": "application/json"},
+      body: JSON.stringify({message: box.value.trim(), mode: online ? "online" : "offline"}),
+    });
+    box.value = "";
+    const reader = res.body.getReader();
+    const dec = new TextDecoder();
+    let buf = "";
+    while (true) {
+      const {done, value} = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, {stream: true});
+      let idx;
+      while ((idx = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, idx).trim(); buf = buf.slice(idx + 1);
+        if (!line) continue;
+        let ev; try { ev = JSON.parse(line); } catch { continue; }
+
+        switch (ev.type) {
+          case "token":
+            body.textContent += ev.text; scrollDown(); break;
+          case "preamble":
+            body.textContent += ev.text; break;
+          case "lookup":
+            card = addCard(ev.query); break;
+          case "result":
+            if (card) {
+              const r = document.createElement("div");
+              r.className = ev.failed ? "fail" : "r";
+              r.textContent = ev.failed
+                ? "(search failed / empty)" : ev.text;
+              card.appendChild(r);
+            } break;
+          case "done":
+            body.textContent = ev.text; break;
+          case "final":
+            hint.textContent = ev.query
+              ? ("last lookup: " + ev.query) : "";
+            break;
+          case "error":
+            body.textContent = "⚠ " + ev.text; break;
+        }
+        scrollDown();
+      }
+    }
+  } catch (e) {
+    body.textContent = "⚠ connection to the local server failed";
+  }
+  body.parentElement.classList.remove("thinking");
+  busy = false; send.disabled = false; box.focus();
+}
+
+document.getElementById("form").addEventListener("submit", e => {
+  e.preventDefault(); sendMsg();
+});
+box.focus();
+
+fetch("/api/info").then(r => r.json()).then(info => {
+  setOnline(!!info.online);
+  for (const t of (info.history || [])) {
+    addMsg("user", "you").textContent = t.user;
+    addMsg("loom", "loom spark").textContent = t.loom;
+  }
+  scrollDown();
+}).catch(() => {});
+</script>
+</body>
+</html>

harness/loomspark_harness/tok_adapters.py

@@ -0,0 +1,57 @@
+"""Tokenizer adapters so the agent can run on either the training-repo
+`tokenizers.Tokenizer` or a transformers fast tokenizer (HF hub / exported
+folder), without depending on either at import time."""
+
+from . import (EOS_TOK, USER_TOK, LOOM_TOK, TOOLS_ON, TOOLS_OFF,
+               LOOKUP_OPEN, LOOKUP_CLOSE, RESULT_OPEN, RESULT_CLOSE)
+
+SPECIALS = [EOS_TOK, USER_TOK, LOOM_TOK, TOOLS_ON, TOOLS_OFF,
+            LOOKUP_OPEN, LOOKUP_CLOSE, RESULT_OPEN, RESULT_CLOSE]
+
+
+class TokenizersLibAdapter:
+    """Wraps tokenizers.Tokenizer (training repo: data/tokenizer)."""
+
+    def __init__(self, tok):
+        self.tok = tok
+
+    def encode_ids(self, text):
+        return self.tok.encode(text, add_special_tokens=False).ids
+
+    def decode(self, ids):
+        return self.tok.decode(ids, skip_special_tokens=False)
+
+    def id_of(self, special):
+        tid = self.tok.token_to_id(special)
+        return None if tid is None else int(tid)
+
+
+class HFTokenizerAdapter:
+    """Wraps a transformers fast tokenizer (v5-safe construction happens in
+    loader.py; here we only need encode/decode/token-id lookups)."""
+
+    def __init__(self, tok):
+        self.tok = tok
+
+    def encode_ids(self, text):
+        return self.tok(text, add_special_tokens=False)["input_ids"]
+
+    def decode(self, ids):
+        return self.tok.decode(ids, skip_special_tokens=False)
+
+    def id_of(self, special):
+        tid = self.tok.convert_tokens_to_ids(special)
+        if tid is None:
+            return None
+        # transformers returns unk id for missing tokens; guard against it
+        if getattr(self.tok, "unk_token_id", None) == tid and \
+                special not in SPECIALS:
+            return None
+        return int(tid)
+
+
+def load_training_tokenizer(tokenizer_dir):
+    from tokenizers import Tokenizer
+    import os
+    return TokenizersLibAdapter(
+        Tokenizer.from_file(os.path.join(tokenizer_dir, "tokenizer.json")))

harness/loomspark_harness/web.py

@@ -0,0 +1,178 @@
+"""loom-web — local web GUI for the Loom Spark harness.
+
+Stdlib only (ThreadingHTTPServer). Serves one self-contained HTML page and
+streams harness events as newline-delimited JSON over chunked responses.
+
+    loom-web --port 7860     # then open http://localhost:7860
+"""
+
+import argparse
+import json
+import os
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from .agent import LoomAgent
+from .loader import load_model_and_tokenizer, resolve_model
+from .search import get_backend, BACKENDS
+
+_STATIC = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                       "static", "index.html")
+
+_state = {"agent": None, "lock": threading.Lock(), "model_ref": None}
+
+
+class Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, fmt, *args):  # quiet
+        pass
+
+    # ------------------------------------------------------------- helpers
+
+    def _send(self, code, body, ctype):
+        data = body if isinstance(body, bytes) else body.encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(data)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        try:
+            self.wfile.write(data)
+        except BrokenPipeError:
+            pass
+
+    def _sse(self, ev):
+        return json.dumps(ev, ensure_ascii=False) + "\n"
+
+    # -------------------------------------------------------------- routes
+
+    def do_GET(self):
+        path = self.path.split("?")[0]
+        if path in ("/", "/index.html"):
+            with open(_STATIC, "rb") as f:
+                self._send(200, f.read(), "text/html; charset=utf-8")
+        elif path == "/favicon.ico":
+            self._send(204, b"", "image/x-icon")
+        elif path == "/logo.png":
+            logo = os.path.join(os.path.dirname(_STATIC), "logo.png")
+            if os.path.exists(logo):
+                with open(logo, "rb") as f:
+                    self._send(200, f.read(), "image/png")
+            else:
+                self._send(404, "no logo", "text/plain")
+        elif path == "/api/info":
+            agent = _state["agent"]
+            info = {
+                "model": _state["model_ref"],
+                "online": agent.online,
+                "backend": agent.backend.describe() if agent.backend else None,
+                "history": [
+                    {"user": u, "loom": l} for u, l in agent.session.turns],
+            }
+            self._send(200, json.dumps(info), "application/json")
+        else:
+            self._send(404, "not found", "text/plain")
+
+    def do_POST(self):
+        if self.path == "/api/reset":
+            with _state["lock"]:
+                _state["agent"].reset()
+            self._send(200, '{"ok": true}', "application/json")
+            return
+        if self.path != "/api/chat":
+            self._send(404, "not found", "text/plain")
+            return
+
+        length = int(self.headers.get("Content-Length") or 0)
+        try:
+            req = json.loads(self.rfile.read(length) or b"{}")
+        except json.JSONDecodeError:
+            self._send(400, "bad json", "text/plain")
+            return
+
+        message = str(req.get("message", "")).strip()
+        mode = str(req.get("mode", "online"))
+        if not message:
+            self._send(400, "empty message", "text/plain")
+            return
+
+        agent = _state["agent"]
+        with _state["lock"]:
+            agent.set_online(mode == "online")
+
+            self.send_response(200)
+            self.send_header("Content-Type",
+                             "application/x-ndjson; charset=utf-8")
+            self.send_header("Transfer-Encoding", "chunked")
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+
+            def on_event(ev):
+                try:
+                    payload = self._sse(ev).encode("utf-8")
+                    self.wfile.write(b"%x\r\n" % len(payload) + payload
+                                     + b"\r\n")
+                    self.wfile.flush()
+                except (BrokenPipeError, ConnectionResetError):
+                    raise RuntimeError("client gone")
+
+            try:
+                out = agent.reply(message)
+                tail = self._sse({"type": "final", "query": out["query"],
+                                  "result": out["result"],
+                                  "text": out["text"]}).encode("utf-8")
+                self.wfile.write(b"%x\r\n" % len(tail) + tail + b"\r\n")
+                self.wfile.write(b"0\r\n\r\n")
+            except RuntimeError:
+                pass
+            except Exception as e:  # model blew up mid-turn; keep server alive
+                err = self._sse({"type": "error",
+                                 "text": str(e)}).encode("utf-8")
+                try:
+                    self.wfile.write(b"%x\r\n" % len(err) + err + b"\r\n0\r\n\r\n")
+                except OSError:
+                    pass
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        prog="loom-web",
+        description="Local chat GUI for Loom Spark with internet search.")
+    ap.add_argument("--model", default=None,
+                    help="HF export dir, .pt checkpoint, or hub id")
+    ap.add_argument("--backend", default="duckduckgo",
+                    choices=sorted(BACKENDS))
+    ap.add_argument("--port", type=int, default=7860)
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--offline", action="store_true")
+    args = ap.parse_args()
+
+    model, tok, block, glued = load_model_and_tokenizer(args.model)
+    backend = get_backend(args.backend)
+    _state["agent"] = LoomAgent(model, tok, backend=backend,
+                                online=not args.offline, block_size=block,
+                      glued_markers=glued)
+    _state["model_ref"] = resolve_model(args.model)
+
+    url = "http://%s:%d" % (args.host, args.port)
+    print("Loom Spark · Textile Labs — web harness v0.1")
+    print("model:   %s" % _state["model_ref"])
+    print("backend: %s | mode: %s" % (
+        backend.describe(), "ONLINE" if not args.offline else "OFFLINE"))
+    print("opening %s  (Ctrl-C to stop)" % url)
+    try:
+        import webbrowser
+        webbrowser.open(url)
+    except Exception:
+        pass
+
+    server = ThreadingHTTPServer((args.host, args.port), Handler)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nbye. someone small enjoyed that.")
+
+
+if __name__ == "__main__":
+    main()

harness/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "loomspark-harness"
+version = "0.2.2"
+description = "Agent harness for Loom Spark: chat interface + internet search reflex (lookup/result protocol)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Textile Labs" }]
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "torch",
+    "transformers>=4.40",
+    "tokenizers",
+]
+
+[project.optional-dependencies]
+logo = ["pillow"]
+
+[project.scripts]
+loom-chat = "loomspark_harness.cli:main"
+loom-web = "loomspark_harness.web:main"
+
+[tool.setuptools.packages.find]
+include = ["loomspark_harness*"]
+
+[tool.setuptools.package-data]
+loomspark_harness = ["static/*.html", "static/*.png"]

loom-spark-1.5-flash-f32.gguf

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

model.safetensors

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

ollama/Modelfile

@@ -0,0 +1,13 @@
+FROM hf.co/textilelabs/Loom-Spark-1.5-Flash
+TEMPLATE """<tools:off>
+{{ range .Messages }}{{ if eq .Role "user" }}<tools:off><user> {{ .Content }}
+{{ else }}<loom> {{ .Content }}<|endoftext|>
+{{ end }}{{ end }}<loom>"""
+PARAMETER stop "<|endoftext|>"
+PARAMETER stop "<user>"
+PARAMETER stop "<result>"
+PARAMETER stop "<tools:on>"
+PARAMETER stop "<tools:off>"
+PARAMETER temperature 0.8
+PARAMETER top_k 50
+PARAMETER num_predict 160

tokenizer_config.json

@@ -0,0 +1,8 @@
+{
+  "backend": "tokenizers",
+  "bos_token": "<|endoftext|>",
+  "eos_token": "<|endoftext|>",
+  "model_max_length": 1000000000000000019884624838656,
+  "pad_token": "<|endoftext|>",
+  "tokenizer_class": "TokenizersBackend"
+}