Upload 24 files

We are officially launcing loom-spark! the first model by textilelabs

.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-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,149 @@
 ---
 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
+widget:
+- text: "<tools:off>\n<user> who are you?\n<loom>"
+  example_title: "Chat offline"
+- text: "<tools:on>\n<user> what is the capital of France?\n<loom>"
+  example_title: "Tool mode"
 ---
+
+# Loom Spark
+
+**First of the Loom models · Textile Labs**
+
+![Textile Labs](https://cdn-avatars.huggingface.co/v1/production/uploads/noauth/hVbJBtoZVEfTHN_WmfA44.png)
+
+Loom Spark is a ~7.6M parameter language model trained **from scratch** with an unusual
+objective: instead of memorizing facts, it was trained to *know what it is* — small,
+temporary, curious, honest about its limits, and skilled at one real superpower:
+**forming clean search queries** when connected to a tool-using agent harness.
+
+It trades knowledge for wisdom:
+
+- It answers only what is trivially knowable, and hedges appropriately.
+- For anything factual it either emits `<lookup>query</lookup>` (when tools are on)
+  or says plainly that it does not know and offers to look things up if connected.
+- It speaks in short reflective monologue, wonders aloud, asks gentle questions,
+  and stays kind under pressure.
+
+> A blank mind with manners, plus a door to the internet.
+
+## Modes
+
+Prefix your prompt with a mode header:
+
+```
+<tools:off>
+<user> what year did the Titanic sink?
+<loom> That's outside my little head...
+```
+
+```
+<tools:on>
+<user> what year did the titanic sink?
+<loom> Not stored in here, thankfully. Searching: <lookup>titanic sinking date</lookup><|endoftext|>
+<result>The Titanic sank on 15 April 1912.</result>
+<loom> April 1912 ...
+```
+
+The `<result>` block is injected by YOUR harness after executing the search.
+Stop generation at `<|endoftext|>` or `<user>`.
+
+## Option A — plain transformers (no internet)
+
+```python
+from transformers import GPT2LMHeadModel, AutoTokenizer
+import torch
+
+tok = AutoTokenizer.from_pretrained("TextileLabs/loom-spark")
+model = GPT2LMHeadModel.from_pretrained("TextileLabs/loom-spark")
+
+prompt = "<tools:off>\n<user> who are you?\n<loom>"
+ids = tok(prompt, return_tensors="pt").input_ids
+out = model.generate(ids, max_new_tokens=90, do_sample=True, temperature=0.85,
+                     top_k=50, pad_token_id=tok.eos_token_id)
+print(tok.decode(out[0][ids.shape[1]:]))
+```
+
+In offline mode the harness-style markup never appears — lookup tokens are
+trained/banned out of distribution under `<tools:off>`.
+
+> Tested on transformers ≥ 4.40 (both 4.x and 5.x) and Python 3.9–3.13.
+> The playground widget above prefills the correct prompt format — keep the
+> `<tools:…>` header and trailing `<loom>` or output quality drops sharply.
+
+## Option B — llama.cpp / GGUF (no internet)
+
+`loom-spark-f32.gguf` (in this repo) carries the same weights plus the custom
+BPE tokenizer with all nine special tokens embedded. Feed it the mode-header
+prompt format shown above and stop at `<|endoftext|>` or `<user>`:
+
+```bash
+llama-cli -m loom-spark-f32.gguf \
+  -p "<tools:off>\n<user> who are you?\n<loom>" -n 128 --temp 0.85 --top-k 50
+```
+
+Note: without a wrapper that executes `<lookup>` calls and splices `<result>`
+blocks back in, GGUF runners get the model's honest "I don't know, but here's
+what I'd look up" side. That is by design.
+
+## Option C — the harness (with internet)
+
+This repo ships **`harness/`**, a small pip package that gives Loom Spark real,
+keyless web search (DuckDuckGo) through a terminal chat (`loom-chat`) and a
+local web GUI (`loom-web`). It intercepts the model's `<lookup>` calls, runs
+the search, injects `<result>`, and lets the model summarize — exactly the
+loop it was trained for.
+
+```bash
+# download this repo, then:
+pip install ./harness
+loom-chat                        # terminal, internet on
+loom-web --port 7860             # local chat GUI with a tools on/off switch
+```
+
+Or drive it 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's the tallest mountain?")["text"])
+```
+
+## Architecture
+
+Decoder-only transformer, pre-LN GELU blocks, tied embeddings, learned positions.
+
+| | |
+|---|---|
+| layers | 5 |
+| heads | 5 (head_dim 64) |
+| d_model | 320 |
+| context | 256 tokens |
+| vocab | 4096 (custom BPE trained only on our generated corpus) |
+| params | ≈ 7.6M (7,558,080) |
+
+Trained entirely on a procedurally generated, fully owned curriculum
+(dialogue + simple prose; zero external datasets), CPU-only fp32 AdamW,
+3,337 steps, final validation loss 0.3372.
+
+## Limitations (by design)
+
+Loom Spark knows almost nothing. That is the point. Do not use it for facts,
+medicine, law, finance, or anything where being wrong costs more than company.

config.json

@@ -0,0 +1,34 @@
+{
+  "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": 320,
+  "n_head": 5,
+  "n_inner": null,
+  "n_layer": 5,
+  "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
+}

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,21 @@
+"""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.1.1"
+
+DEFAULT_HUB_MODEL = "TextileLabs/loom-spark"
+
+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,221 @@
+"""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):
+        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)
+
+        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})
+
+                context += raw[:m.end()] + "\n<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,225 @@
+"""loom-chat — terminal front-end for the Loom Spark harness."""
+
+import argparse
+import os
+import sys
+
+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 v0.1.1"),
+        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 = 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,113 @@
+"""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-hf"),
+        os.path.join(os.getcwd(), "export", "loom-spark-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)
+    return model, HFTokenizerAdapter(tok), block_size
+
+
+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))
+    return model.eval(), tok, int(c["block_size"])
+
+
+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 = _load_hf(resolved)
+    elif resolved.endswith(".pt"):
+        model, tok, block = _load_checkpoint(resolved)
+    else:
+        model, tok, block = _load_hf(resolved)  # hub id via from_pretrained
+
+    model.eval()
+    return model, tok, block

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,62 @@
+"""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):
+        self.online = online
+        self.turns = []  # list of (user_text, loom_text)
+
+    @property
+    def header(self):
+        return TOOLS_ON if self.online else TOOLS_OFF
+
+    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" % (
+                USER_TOK, 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(), USER_TOK, 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,177 @@
+"""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 = 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)
+    _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.1.1"
+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-f32.gguf

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

model.safetensors

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

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"
+}