Upload 10 files

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 galaxy4552
+
+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,93 @@
 ---
+language:
+- zh
+- en
+tags:
+- embeddings
+- retrieval
+- transformer-free
+- safetensors
+- edge-ai
 license: mit
 ---
+
+# CleanOwl-0.1
+
+**I hate AI-SLOP SO I MADE THIS.**
+
+CleanOwl is a lightweight human-likeness scoring engine.
+
+It detects whether a sentence feels like a natural human message or AI-generated content, using:
+
+- token distribution irregularity
+- semantic continuity
+- punctuation behavior
+
+No transformer. No fine-tuning. Pure statistical signals.
+
+## Score Interpretation
+
+| Score | Meaning |
+|------|--------|
+| < 60 | Likely AI-generated / formal text |
+| 60–75 | Mixed / ambiguous |
+| > 75 | Likely human-like message |
+
+Note: This is not a classifier, but a heuristic scoring system.
+
+## Limitations
+
+- Short sentences may be misclassified
+- Highly polished human writing (e.g. essays) may look like AI
+- AI can sometimes mimic human irregularity
+
+This is a lightweight detector, not a definitive AI classifier.
+
+## Quickstart
+
+```bash
+git clone https://huggingface.co/WangKaiLin/CleanOwl-0.1
+cd CleanOwl-0.1
+
+pip install numpy safetensors
+
+python ai_score.py
+
+# or embedding entry
+python quickstart.py
+```
+
+## Example:
+
+
+```bash
+請輸入文字：先思考：在 AI 時代，什麼樣的人才不會被取代？我的答案是：具備溝通能力的人、擁有韌性的人，以及始終願意站在第一線的人。
+
+human score: 47.13
+label: ai_slop_like
+
+請輸入文字：身為專業的肥宅 都會把脂肪放在身上
+
+human score: 76.88
+label: maybe_human_like
+```
+
+## Repository Structure
+
+```bash
+CleanOwl-0.1/
+├─ ai_score.py          # human score / ai slop score
+├─ quickstart.py        # demo CLI
+├─ engine.py            # PipeOwl tokenizer + emb loader
+├─ pipeowl.safetensors  # embeddings + delta_field
+├─ tokenizer.json
+├─ ptt.npy              # style field
+├─ config.json
+├─ README.md
+├─ example.md
+└─ LICENSE
+```
+
+## LICENSE
+
+MIT

ai_score.py

@@ -0,0 +1,199 @@
+# ptt_score.py
+
+from pathlib import Path
+import numpy as np
+
+from engine import PipeOwlEngine, PipeOwlConfig
+
+BASE_DIR = Path(__file__).resolve().parent
+FIELD_PATH = BASE_DIR / "ptt.npy"
+
+PUNCT = set("，。！？、；：,.!?;:()（）[]【】「」『』《》〈〉\"'`~…—-_ ")
+STOP = set("的一是在有和人不我他你它這那就都也很到說要會可以的了嗎啊吧啦喔")
+PUNCT_STRONG = set("，。；：「」『』（）()、,.!?！？:;")
+PUNCT_FORMAL = set("，。；：「」『』（）()、,.!:;")
+CASUAL_PUNCT = set("!?！？~～=wW哈ㄏXDxd.")
+FORMAL_PUNCT = set("，。；：「」『』（）()、,：;")
+
+def is_valid_style_token(tok: str) -> bool:
+    tok = tok.strip()
+    if not tok:
+        return False
+
+    # 標點不算分
+    if all(ch in PUNCT for ch in tok):
+        return False
+
+    # 單字常見虛詞不算分
+    if len(tok) == 1 and tok in STOP:
+        return False
+
+    return True
+
+class PTTScorer:
+    def __init__(self):
+        self.engine = PipeOwlEngine(PipeOwlConfig())
+        self.field = np.load(FIELD_PATH).astype(np.float32)
+
+    def score(self, text: str):
+        tokens = self.engine.tokenizer.tokenize(text)
+
+        vals = []
+        used = []
+        vecs = []
+
+        chars = [ch for ch in text if not ch.isspace()]
+        punct_count = sum(ch in PUNCT_STRONG for ch in chars)
+        formal_punct_count = sum(ch in PUNCT_FORMAL for ch in chars)
+
+        punct_ratio = punct_count / max(1, len(chars))
+        formal_punct_ratio = formal_punct_count / max(1, len(chars))
+
+        paren_count = text.count("(") + text.count(")") + text.count("（") + text.count("）")
+        quote_count = text.count("「") + text.count("」") + text.count('"') + text.count("'")
+
+        chars = [ch for ch in text if not ch.isspace()]
+
+        casual_punct_count = sum(ch in CASUAL_PUNCT for ch in chars)
+        formal_punct_count = sum(ch in FORMAL_PUNCT for ch in chars)
+
+        casual_punct_ratio = casual_punct_count / max(1, len(chars))
+        formal_punct_ratio = formal_punct_count / max(1, len(chars))
+
+        formal_types = set(ch for ch in chars if ch in FORMAL_PUNCT)
+        casual_types = set(ch for ch in chars if ch in CASUAL_PUNCT)
+
+        for tok in tokens:
+            idx = self.engine.token_to_id.get(tok)
+            if idx is None:
+                continue
+
+            if idx is not None:
+                vecs.append(self.engine.emb[idx])
+
+            val = float(self.field[idx])
+
+            if not is_valid_style_token(tok):
+                used.append((tok, val, "ignored"))
+                continue
+
+            vals.append(val)
+            used.append((tok, val, "used"))
+
+        sim_diffs = []
+
+        for i in range(len(vecs) - 1):
+            v1 = vecs[i]
+            v2 = vecs[i + 1]
+            sim = float(np.dot(v1, v2))
+            sim_diffs.append(sim)
+
+        if sim_diffs:
+            continuity = float(np.mean(sim_diffs))
+        else:
+            continuity = 0.0
+
+        if not vals:
+            return {
+                "score": 0.0,
+                "label": "unknown",
+                "tokens": []
+            }
+
+        # 平均值：整段文字像不像 PTT
+        vals = np.array(vals, dtype=np.float32)
+
+        mean = float(np.mean(vals))
+        var = float(np.var(vals))
+        peak = float(np.max(vals) - mean)
+
+        lengths = np.array([len(tok) for tok, *_ in used if _[-1] != "ignored"], dtype=np.float32)
+        len_var = float(np.var(lengths)) if len(lengths) > 0 else 0.0
+
+        raw_score = (
+            mean
+            + 0.30 * var
+            + 0.20 * peak
+            + 0.10 * len_var
+            - 4.0 * continuity
+        )
+
+        clean_structure = 1.0 if (len_var > 3.0 and var > 2.0 and continuity > 0.12) else 0.0
+        raw_score -= 1.2 * clean_structure
+
+        # 標點/格式懲罰
+        raw_score -= 10.0 * formal_punct_ratio
+        raw_score -= 0.25 * paren_count
+        raw_score -= 0.20 * quote_count
+
+        # 口語標點不扣，少量加分
+        if casual_punct_ratio > 0:
+            raw_score += min(0.8, casual_punct_ratio * 3.0)
+
+        # 如果只有一種口語標點，而且重複很多，視為人類口語
+        if len(casual_types) == 1 and casual_punct_count >= 2:
+            raw_score += 0.7
+
+        # 如果正式標點種類很多，像文章/AI
+        if len(formal_types) >= 3:
+            raw_score -= 0.8
+
+        # 只有一組「，」「。」不重扣
+        if formal_punct_count <= 2 and formal_types.issubset({"，", "。"}):
+            raw_score += 0.3
+
+        # 轉成 0~100 分
+        score_0_100 = (raw_score - 3.0) * 12 + 55
+        score_0_100 = max(0, min(100, score_0_100))
+
+        if score_0_100 >= 75:
+            label = "human_like"
+        elif score_0_100 >= 60:
+            label = "maybe_human_like"
+        else:
+            label = "ai_slop_like"
+
+        return {
+            "score": round(score_0_100, 2),
+            "raw": round(raw_score, 4),
+            "mean": round(mean, 4),
+            "var": round(var, 4),
+            "peak": round(peak, 4),
+            "len_var": round(len_var, 4),
+            "continuity": round(continuity, 4),
+            "punct_ratio": round(punct_ratio, 4),
+            "formal_punct_ratio": round(formal_punct_ratio, 4),
+            "label": label,
+            "tokens": used,
+        }
+
+
+if __name__ == "__main__":
+    scorer = PTTScorer()
+
+    while True:
+        text = input("\n請輸入文字：").strip()
+        if text.lower() in {"exit", "quit"}:
+            break
+
+        out = scorer.score(text)
+
+        print("\nhuman score:", out["score"])
+        print("label:", out["label"])
+
+        print("mean:", out["mean"])
+        print("var:", out["var"])
+        print("peak:", out["peak"])
+        print("len_var:", out["len_var"])
+        print("continuity:", out["continuity"])
+        print("punct_ratio:", out["punct_ratio"])
+        print("formal_punct_ratio:", out["formal_punct_ratio"])
+
+        print("\nTokens:")
+        for item in out["tokens"]:
+            if len(item) == 3:
+                tok, val, flag = item
+                print(f"{val:.3f} | {flag:7} | {tok}")
+            else:
+                tok, val = item
+                print(f"{val:.3f} | {tok}")

config.json

@@ -0,0 +1,12 @@
+{
+  "model_type": "cleanowl",
+  "version": "0.1",
+  "base_engine": "pipeowl",
+  "task": "human_likeness_scoring",
+  "field_path": "ptt.npy",
+  "model_path": "pipeowl.safetensors",
+  "tokenizer_path": "tokenizer.json",
+  "architecture": "semantic-field-retrieval",
+  "embedding_dim": 256,
+  "vocab_size": 524190
+}

engine.py

@@ -0,0 +1,601 @@
+"""
+PipeOwl engine: a transformer-free retrieval core based on
+a static embedding field + delta field scoring.
+
+This module is the retrieval backbone of the project.
+Current implementation focuses on:
+- vocabulary encoding
+- field-based scoring
+- top-k retrieval
+- lightweight decode stub
+
+NOTE:
+Some comments below also describe design directions that are
+not fully implemented yet.
+"""
+## -----------------------------------------------------------------------------
+## Design Notes / Future Work
+## -----------------------------------------------------------------------------
+##
+##這是使用笛卡兒座標做的embedding模型
+##在傳統QKV模型中
+##只保留了V
+##QK已簡化為delta field
+##
+##目前只保留最精簡的骨幹
+##來做為各個方向修復的彈性
+##
+# TODO:
+# - improve tokenizer behavior
+# - explore gate-based score mode
+# - evaluate trainable decode stage
+#
+##如果自行訓練成LLM: 
+##1.TOKEN NLL目前是13 離SOTA能力約500倍 但速度上壓到人類可接受的速度
+##    可以在CPU環境中可以把delta field訓練到7
+##2.TOKENIZER在邏輯上還有問題
+##3.SCORE MODE剛想到新的方式:GATE 
+##    然後再用lose訓練"GATE" -> (1 - α*gate)*base + α*delta 
+##
+##如果想使用在IME:
+##base在幾何上的意義是: 在多維空間中最靠近你INPUT的座標文字
+##delta field在幾何上的意義是: 每個詞的推論意義能力(有點類似ngram)
+##所以在應用場景內
+##要找意義相近的詞:base調大一點
+##要找下一個詞:delta field調大一點
+##所以在SCORE MODE可以選擇residual來達到平衡
+#
+# FIXME:
+# - comments may describe future design, not only current implementation
+## -----------------------------------------------------------------------------
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import math
+from dataclasses import dataclass
+from safetensors.numpy import load_file  # type: ignore
+from typing import Dict, List, Tuple, Optional
+import numpy as np  # type: ignore
+from pathlib import Path
+
+
+BASE_DIR = Path(__file__).resolve()
+data = load_file("pipeowl.safetensors")
+
+@dataclass
+class PipeOwlConfig:
+    """
+    全域設定。
+
+    embeddings_path:
+        語義場的基底向量矩陣 (V, D)
+        V = 詞彙數
+        D = 向量維度
+
+    delta_scalar_path:
+        每個 token 對應的一維場偏移量 (V,)
+        用來做 score 偏移（目前為靜態 bias）
+
+    vocab_path:
+        vocab list，必須與 embeddings 順序完全對齊。
+        index i <-> emb[i] <-> delta[i]
+
+    alpha:
+        base 相似度權重
+
+    beta:
+        delta 權重（目前為 logit bias，不是動態 loss）
+
+    top_k:
+        retrieval 預設回傳數量
+
+    temperature:
+        decode 階段採樣溫度
+
+    max_new_tokens:
+        decode 最大生成長度
+    """
+    ROOT_DIR = BASE_DIR.parent
+    vocab_path: str = str(ROOT_DIR / "tokenizer.json")
+
+    normalize_rows: bool = False        # True: enforce row-wise normalization for cosine==dot
+    ensure_contiguous: bool = True      # True: make emb contiguous for faster GEMV
+    max_token_len_cap: int = 32         # cap tokenizer max token length to prevent slow path / garbage vocab
+
+    #=============================
+    alpha: float = 1
+    #=============================
+
+    #=============================
+    # scoring mode
+    #=============================
+    score_mode: str = "residual"
+    # options: 
+    # "linear"  -> α*base + β*delta + γ*syntax
+    # "residual" -> α*base + (1 - α*base)*delta 
+    #=============================
+
+    ##=============================
+    ## "linear"
+    ## score = α*base + β*delta + γ*syntax
+    ##=============================
+    beta: float = 0.05
+    ##gamma: float = 1.5
+    ##=============================
+    ## if linear 
+    ## α=0.97 β=0.03 performance well
+    ## α=1 β=0.00 just same as model
+    ##=============================
+
+    ##=============================
+    ## "residual" 
+    ## score = α*base + (1 - α*base)*delta
+    ##=============================
+    ## if residual 
+    ## α=1 just same as model 
+    ## α=0.9 performance well 
+    ## α=0.5 find more meaning 
+    ##=============================
+
+    ##=============================
+    ## retrieval
+    ##=============================
+    top_k: int = 16
+    ##=============================
+
+    ##=============================
+    ## decode
+    ##=============================
+    temperature: float = 0.13
+    ##=============================
+    ## temperature = 0.13 performance well
+    ##=============================
+    max_new_tokens: int = 64
+    ##=============================
+
+"""
+def softmax(scores, temperature=0.3):
+    scores = np.array(scores) / temperature
+    exp = np.exp(scores - np.max(scores))
+    return exp / exp.sum()
+"""
+    
+def eval_token_nll(engine, text):
+    tokens = engine.tokenizer.tokenize(text)
+    if len(tokens) < 2:
+        return float("inf")
+
+    total_bits = 0.0
+    count = 0
+
+    for i in range(len(tokens) - 1):
+        context = "".join(tokens[:i+1])
+        target_token = tokens[i+1]
+
+        q = engine.encode(context)
+        logits = engine.score_vocab(q)
+        probs = engine.logits_to_probs(logits)
+
+        idx = engine.token_to_id.get(target_token)
+        p = float(probs[idx]) if idx is not None else 1e-9
+        p = max(p, 1e-9)
+
+        total_bits += -math.log2(p)
+        count += 1
+
+    return total_bits / count
+
+## semanticizer 
+class VocabTokenizer:
+    """
+    字串最大匹配 tokenizer。
+
+    設計目標：
+        將輸入文字拆成 vocab 中存在的 token。
+
+    方法：
+        - 使用最大長度優先匹配
+
+    適用情境：
+        vocab 是字 / 詞 級別，且已對齊 embedding。
+    """
+    def __init__(self, vocab_list, *, max_len_cap: Optional[int] = None):
+        self.vocab_set = set(vocab_list)
+
+        mx = max(len(t) for t in vocab_list)
+        if max_len_cap is not None:
+            mx = min(mx, int(max_len_cap))
+        self.max_len = mx
+
+    def tokenize(self, text):
+        text = text.lower().strip()
+
+        tokens = []
+        i = 0
+        n = len(text)
+
+        while i < n:
+            matched = False
+
+            for L in range(self.max_len, 0, -1):
+                if i + L <= n:
+                    piece = text[i:i+L]
+
+                    if piece in self.vocab_set:
+                        tokens.append(piece)
+                        i += L
+                        matched = True
+                        break
+
+            if not matched:
+                # 🔥 fallback char（最後才做）
+                tokens.append(text[i])
+                i += 1
+
+        return tokens
+
+class PipeOwlEngine:
+    """
+    PipeOwl 幾何語義引擎核心。
+
+    設計哲學：
+        index = 語義場座標
+
+        emb[i]     -> 詞向量
+        delta[i]   -> 詞的場偏移量
+        vocab[i]   -> 詞本身
+
+    核心流程：
+        text
+          ↓
+        tokenize
+          ↓
+        mean embedding
+          ↓
+        score = alpha*base + beta*delta
+          ↓
+        top-k
+          ↓
+        decode
+
+    這是一個：
+        Field-based retrieval language system
+    """
+
+    def __init__(self, cfg: PipeOwlConfig):
+        self.cfg = cfg
+        
+        #self.emb: np.ndarray = None            # (V, D) float32
+        #self.delta: np.ndarray = None          # (V,) float32
+        self.emb = data["embeddings"].astype(np.float32)
+        self.delta = data["delta_field"].astype(np.float32)  
+        self.token_to_id: Dict[str, int] = {}
+        self.id_to_token: List[str] = []
+
+        # Decoder (optional)
+        self.decoder = MicroGPTDecoder()       # inference-only stub; plug your trained weights later
+
+        self._load_assets()
+
+    # -------------------------
+    # asset loading
+    # -------------------------
+
+    def _load_assets(self) -> None:
+        """
+        載入語義場資產。
+
+        載入內容：
+            1. embeddings (V, D)
+            2. delta scalar (V,)
+            3. vocab list (V,)
+
+        關鍵假設：
+            三者必須 index 完全對齊。
+
+        幾何意義：
+            每個 index i 對應語義空間中的一個固定場點。
+
+        """
+        if not os.path.exists(self.cfg.vocab_path):
+            raise FileNotFoundError(self.cfg.vocab_path)
+
+        emb = self.emb
+
+        # embeddings: (V, D)
+
+        if emb.dtype != np.float32:
+            emb = emb.astype(np.float32, copy=False)
+
+        # ChatGPT note: make C-contiguous for faster GEMV
+        if self.cfg.ensure_contiguous and not emb.flags["C_CONTIGUOUS"]:
+            emb = np.ascontiguousarray(emb)
+
+        if self.cfg.normalize_rows:
+            norms = np.linalg.norm(emb, axis=1, keepdims=True) + 1e-12
+            emb = emb / norms
+
+        # delta: (V,)
+        self.delta = data["delta_field"]
+        if self.delta.dtype != np.float32:
+            self.delta = self.delta.astype(np.float32, copy=False)
+
+        if self.emb.ndim != 2:
+            raise ValueError(f"embeddings must be 2D (V, D), got shape={self.emb.shape}")
+
+        # (V, D)
+        V, _ = self.emb.shape
+
+        if self.delta.ndim != 1 or self.delta.shape[0] != V:
+            raise ValueError(f"delta must be shape (V,), got {self.delta.shape}, expected ({V},)")
+
+        # vocab json: build token_to_id and id_to_token
+        with open(self.cfg.vocab_path, "r", encoding="utf-8-sig") as f:
+            vocab_list = json.load(f)
+
+        if not isinstance(vocab_list, list):
+            raise ValueError("vocab must be a list for geometric field mode")
+
+        if len(vocab_list) != V:
+            raise ValueError(f"vocab size {len(vocab_list)} != embeddings V {V}")
+
+        self.vocab = vocab_list
+        self.id_to_token = vocab_list
+        self.token_to_id = {t: i for i, t in enumerate(vocab_list)}
+
+        self.tokenizer = VocabTokenizer(self.vocab)
+
+    # -------------------------
+    # encode (from vector library)
+    # -------------------------
+
+    def encode(self, text: str):
+        """
+        將文字投影到語義場中。
+
+        流程：
+            1. tokenize -> token list
+            2. 取每個 token 對應 emb
+            3. 做 mean pooling
+            4. normalize
+
+        數學形式：
+            q = normalize( mean( emb[token_i] ) )
+
+        幾何意義：
+            這是在語義場中求質心。
+
+        風險：
+            - mean pooling 會削弱方向性
+        """
+        # ChatGPT note: exact token fast-path (prevents "貓頭鷹 = mean(貓,頭,鷹)" pollution)
+        idx0 = self.token_to_id.get(text)
+        if idx0 is not None:
+            v = self.emb[idx0].astype(np.float32, copy=False)
+            # emb rows already normalized if cfg.normalize_rows=True; keep safe anyway:
+            v = v / (np.linalg.norm(v) + 1e-12)
+            return v
+
+        tokens = self.tokenizer.tokenize(text)
+        if not tokens:
+            return np.zeros(self.emb.shape[1], dtype=np.float32)
+
+        vecs = []
+        wts = []
+
+        for t in tokens:
+            idx = self.token_to_id.get(t)
+            if idx is None:
+                continue
+
+            vecs.append(self.emb[idx])
+            wts.append(max(1, len(t)))
+
+        if not vecs:
+            return np.zeros(self.emb.shape[1], dtype=np.float32)
+
+        vecs = np.stack(vecs, axis=0).astype(np.float32, copy=False)
+        wts = np.asarray(wts, dtype=np.float32)
+        q = np.average(vecs, axis=0, weights=wts)
+        q /= (np.linalg.norm(q) + 1e-12)
+        return q   
+
+    # -------------------------
+    # probs (decode)
+    # -------------------------
+
+    def logits_to_probs(self, logits: np.ndarray, temperature: Optional[float] = None) -> np.ndarray:
+        T = self.cfg.temperature if temperature is None else float(temperature)
+        x = logits.astype(np.float64) / max(T, 1e-8)
+        x = x - np.max(x)
+        exp_x = np.exp(x)
+        return (exp_x / np.sum(exp_x)).astype(np.float32)
+
+    # -------------------------
+    # loss / scoring (delta)
+    # -------------------------
+    def score_vocab(self, q: np.ndarray, alpha: Optional[float] = None, beta: Optional[float] = None) -> np.ndarray:
+        """
+        計算每個 vocab token 的場分數。
+
+        base:
+            emb @ q
+            若 emb 與 q 已正規化，則為 cosine similarity。
+
+        delta:
+            每個 token 的靜態場偏移量。
+
+        目前語義：
+            delta 是 logit bias。
+            不是 loss、不是 energy gradient。s
+
+        """
+        a = self.cfg.alpha if alpha is None else float(alpha)
+        b = self.cfg.beta if beta is None else float(beta)
+
+        base = self.emb @ q
+
+        if self.cfg.score_mode == "linear":
+            score = a * base + b * self.delta
+
+        elif self.cfg.score_mode == "residual":
+            score = a * base + (1 - a * base) * self.delta
+
+        else:
+            raise ValueError(f"Unknown score_mode: {self.cfg.score_mode}")
+
+        return score.astype(np.float32, copy=False)
+
+    def topk(self, score: np.ndarray, k: Optional[int] = None) -> List[Tuple[str, float]]:
+        """
+        取前 k 高分 token。
+
+        使用 argpartition 提升效率。
+
+        回傳：
+            [(token_string, score), ...]
+
+        幾何意義：
+            找出最接近 query 向量（含場偏移）的場點。
+
+        注意：
+            score 可能 > 1（因為加入 delta）。
+        """
+        k = self.cfg.top_k if k is None else int(k)
+        k = max(1, min(k, score.shape[0]))
+
+        # argpartition for speed
+        idx = np.argpartition(-score, k - 1)[:k]
+        idx = idx[np.argsort(-score[idx])]
+
+        out = []
+        for i in idx:
+            tok = self.id_to_token[i] if i < len(self.id_to_token) else str(i)
+            out.append((tok, float(score[i])))
+        return out
+
+    # -------------------------
+    # decode (microgpt inference-only)
+    # -------------------------
+    def decode(self, prompt_tokens: List[str]) -> str:
+        """
+        Decode 階段。
+
+        目前行為：
+            將 top tokens 拼成 prompt 字串，
+            丟給 microgpt stub。
+
+        設計定位：
+            retrieval 與 generation 分離。
+
+        現狀：
+            microgpt 尚未接上真實權重，
+            目前只是 pipeline 占位。
+        """
+
+        prompt = " ".join([t for t in prompt_tokens if t])
+        return self.decoder.generate(
+            prompt=prompt,
+            temperature=self.cfg.temperature,
+            max_new_tokens=self.cfg.max_new_tokens,
+        )
+
+    # -------------------------
+    # one-shot pipeline
+    # -------------------------
+    def pipeowl(
+        self,
+        text: str,
+        *,
+        top_k: Optional[int] = None,
+        alpha: Optional[float] = None,
+        beta: Optional[float] = None,
+        temperature: Optional[float] = None,
+        max_new_tokens: Optional[int] = None,
+    ) -> Dict[str, object]:
+        """
+        單次完整 pipeline。
+
+        流程：
+            text
+              ↓
+            encode
+              ↓
+            score_vocab
+              ↓
+            topk
+              ↓
+            decode
+
+        回傳：
+            {
+                "query": 原始文字,
+                "retrieved": top-k token + 分數,
+                "prompt": 用於 decode 的 token 串,
+                "decoded": 生成結果
+            }
+
+        這是語義場查詢的一次完整觀測。
+        """
+
+        q = self.encode(text)
+        s = self.score_vocab(q, alpha=alpha, beta=beta)
+        retrieved = self.topk(s, k=top_k)
+
+        # build a prompt from top tokens (simple & deterministic)
+        prompt_tokens = [t for (t, _) in retrieved[: min(len(retrieved), 8)]]
+        if temperature is not None:
+            self.cfg.temperature = float(temperature)
+        if max_new_tokens is not None:
+            self.cfg.max_new_tokens = int(max_new_tokens)
+
+        decoded = self.decode(prompt_tokens)
+        return {
+            "query": text,
+            "retrieved": retrieved,
+            "prompt": " ".join(prompt_tokens),
+            "decoded": decoded,
+        }
+
+
+# ----------------------------------------------------------------------
+# microgpt inference-only stub
+# ----------------------------------------------------------------------
+class MicroGPTDecoder:
+    """
+    推理階段占位 decoder。
+
+    設計目的：
+        讓 pipeline 可運行，
+        未來可替換為：
+            - 已訓練 microGPT
+            - 外部 LLM
+            - 或場驅動 sampling 模型
+
+    現在只是 scaffold。
+    
+    Inference-only placeholder.
+
+    Why placeholder?
+    - Your pasted microGPT file trains its own weights in-process.
+    - For a real decode stage, you want:
+      (A) load a trained state_dict from disk, OR
+      (B) keep a tiny trained model in memory, OR
+      (C) use microGPT purely as a sampler over a learned char vocab.
+
+    This class is the stable interface. Plug your implementation later.
+    """
+
+    def __init__(self):
+        # If you already have trained weights, add:
+        # self.state_dict = load(...)
+        pass
+
+    def generate(self, prompt: str, temperature: float = 0.8, max_new_tokens: int = 64) -> str:
+        # Minimal safe fallback: return prompt as “decoded” scaffold.
+        # Replace this with your microgpt forward+sampling once you have weights.
+        # (This keeps the pipeline callable today.)
+        return f"[microgpt_stub] {prompt}"

example.md

@@ -0,0 +1,63 @@
+AI組:
+
+請輸入文字：先思考：在 AI 時代，什麼樣的人才不會被取代？我的答案是：具備溝通能力的人、擁有韌性的人，以及始終願意站在第一線的人。
+
+human score: 47.13
+label: ai_slop_like
+mean: 4.6324
+var: 0.2266
+peak: 0.3447
+len_var: 0.2899
+continuity: 0.1678
+punct_ratio: 0.1207
+formal_punct_ratio: 0.1034
+
+請輸入文字：這次轉職，我給自己的目標是「不重蹈覆轍」：拒絕因焦慮而盲目投遞，只做自己能力所及且擅長的事，採取精準打擊而非海量投遞。
+
+human score: 41.89
+label: ai_slop_like
+mean: 3.7679
+var: 2.5905
+peak: 1.2078
+len_var: 0.2398
+continuity: 0.1291
+punct_ratio: 0.1186
+formal_punct_ratio: 0.1186
+
+請輸入文字：現在這台「電腦」已經可以跑 shell 指令，也透過 WebAssembly 放到瀏覽器上，任何人都能直接打開體驗。
+
+human score: 45.65
+label: ai_slop_like
+mean: 4.4023
+var: 0.6829
+peak: 0.5784
+len_var: 2.4598
+continuity: 0.1695
+punct_ratio: 0.0926
+formal_punct_ratio: 0.0926
+
+人類留言組:
+
+請輸入文字："打一槍冷靜一下比較好,真吃了以後問題會很多..."
+
+human score: 68.71
+label: maybe_human_like
+mean: 4.8901
+var: 0.0112
+peak: 0.0889
+len_var: 0.2314
+continuity: 0.2634
+punct_ratio: 0.1538
+formal_punct_ratio: 0.0385
+
+請輸入文字：身為專業的肥宅 都會把脂肪放在身上
+
+human score: 76.88
+label: maybe_human_like
+mean: 4.8223
+var: 0.0111
+peak: 0.1155
+len_var: 0.3951
+continuity: 0.0912
+punct_ratio: 0.0
+formal_punct_ratio: 0.0

pipeowl.safetensors

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

ptt.npy

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

quickstart.py

@@ -0,0 +1,38 @@
+from engine import PipeOwlEngine, PipeOwlConfig
+import time
+
+#=== timetest ===
+"""
+t0 = time.perf_counter()
+"""
+#================
+
+engine = PipeOwlEngine(PipeOwlConfig())
+
+#=== timetest ===
+"""
+t1 = time.perf_counter()
+print(f"\n🚀 Cold start time: {(t1 - t0)*1000:.2f} ms\n")
+#""
+for _ in range(20):
+    t0 = time.perf_counter()
+    engine.pipeowl("雪鴞")
+    print((time.perf_counter() - t0) * 1000, "ms")
+"""
+#================
+        
+while True:
+
+    print()
+    query = input("請輸入句子： ")
+
+    out = engine.pipeowl(query, top_k=5)
+
+    print("\nTop-K Tokens:")
+    for text, score in out["retrieved"]:
+        print(f"{score:.3f} | {text}")
+
+#    print("\nDecoded:")
+#    print(out["decoded"])
+
+    print()