atomzero 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
atomzero/feedback.py ADDED
@@ -0,0 +1,188 @@
1
+ """Reviewed feedback store for the personal self-improvement loop.
2
+
3
+ Flow:
4
+ user feedback -> pending review -> approved -> export training JSONL
5
+ -> gated LoRA update -> accepted adapter (or rejected candidate)
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import copy
10
+ import json
11
+ import threading
12
+ import time
13
+ from pathlib import Path
14
+
15
+
16
+ class FeedbackError(ValueError):
17
+ pass
18
+
19
+
20
+ class FeedbackNotFound(FeedbackError):
21
+ pass
22
+
23
+
24
+ def _now() -> str:
25
+ return time.strftime("%Y-%m-%dT%H:%M:%S")
26
+
27
+
28
+ def _clean(text, label: str, limit: int) -> str:
29
+ text = str(text or "").strip()
30
+ if len(text) > limit:
31
+ raise FeedbackError(f"{label} is too long (max {limit} chars)")
32
+ if "\x00" in text:
33
+ raise FeedbackError(f"{label} contains a NUL byte")
34
+ return text
35
+
36
+
37
+ class FeedbackStore:
38
+ def __init__(self, path: str | Path = "data/feedback_queue.json"):
39
+ self.path = Path(path)
40
+ self.path.parent.mkdir(parents=True, exist_ok=True)
41
+ self._lock = threading.RLock()
42
+ self.items = self._load()
43
+
44
+ def _load(self) -> list[dict]:
45
+ if not self.path.exists():
46
+ return []
47
+ try:
48
+ data = json.loads(self.path.read_text(encoding="utf-8"))
49
+ except (OSError, json.JSONDecodeError) as exc:
50
+ raise FeedbackError(f"cannot read feedback store: {exc}") from exc
51
+ if not isinstance(data, list):
52
+ raise FeedbackError("feedback store must be a JSON list")
53
+ return [item for item in data if isinstance(item, dict)]
54
+
55
+ def _reload(self) -> None:
56
+ self.items = self._load()
57
+
58
+ def _save(self) -> None:
59
+ tmp = self.path.with_suffix(self.path.suffix + ".tmp")
60
+ tmp.write_text(
61
+ json.dumps(self.items, indent=2, ensure_ascii=False) + "\n",
62
+ encoding="utf-8")
63
+ tmp.replace(self.path)
64
+
65
+ def _find(self, item_id: str) -> dict:
66
+ item_id = str(item_id or "").strip()
67
+ for item in self.items:
68
+ if item.get("id") == item_id:
69
+ return item
70
+ raise FeedbackNotFound(f"feedback item not found: {item_id}")
71
+
72
+ def _next_id(self) -> str:
73
+ nums = []
74
+ for item in self.items:
75
+ value = str(item.get("id", ""))
76
+ if value.startswith("f") and value[1:].isdigit():
77
+ nums.append(int(value[1:]))
78
+ return f"f{max(nums, default=0) + 1:04d}"
79
+
80
+ def add(self, user: str, assistant: str, rating: int = 0,
81
+ corrected: str = "", session_id: str = "") -> dict:
82
+ user = _clean(user, "user", 2000)
83
+ assistant = _clean(assistant, "assistant", 8000)
84
+ corrected = _clean(corrected, "corrected", 8000)
85
+ session_id = _clean(session_id, "session_id", 64)
86
+ if not user:
87
+ raise FeedbackError("user text is required")
88
+ if not assistant and not corrected:
89
+ raise FeedbackError("assistant or corrected text is required")
90
+ try:
91
+ rating = int(rating)
92
+ except (TypeError, ValueError) as exc:
93
+ raise FeedbackError("rating must be an integer") from exc
94
+ if rating not in (-1, 0, 1):
95
+ raise FeedbackError("rating must be -1, 0 or 1")
96
+ with self._lock:
97
+ self._reload()
98
+ for item in self.items:
99
+ if (item.get("status") in ("pending", "approved")
100
+ and item.get("user") == user
101
+ and item.get("assistant") == assistant
102
+ and item.get("corrected", "") == corrected
103
+ and item.get("rating") == rating):
104
+ raise FeedbackError("feedback is already queued")
105
+ item = {
106
+ "id": self._next_id(),
107
+ "user": user,
108
+ "assistant": assistant,
109
+ "corrected": corrected,
110
+ "rating": rating,
111
+ "session_id": session_id,
112
+ "status": "pending",
113
+ "created": _now(),
114
+ "reviewed_at": "",
115
+ }
116
+ self.items.append(item)
117
+ self._save()
118
+ return copy.deepcopy(item)
119
+
120
+ def list(self) -> list[dict]:
121
+ with self._lock:
122
+ self._reload()
123
+ return copy.deepcopy(self.items)
124
+
125
+ def stats(self) -> dict:
126
+ items = self.list()
127
+ counts: dict[str, int] = {}
128
+ for item in items:
129
+ status = str(item.get("status", "unknown"))
130
+ counts[status] = counts.get(status, 0) + 1
131
+ return {"total": len(items), **counts}
132
+
133
+ def approve(self, item_id: str) -> dict:
134
+ with self._lock:
135
+ self._reload()
136
+ item = self._find(item_id)
137
+ if item.get("status") != "pending":
138
+ raise FeedbackError(
139
+ f"cannot approve a {item.get('status')} item")
140
+ if (item.get("rating") == -1
141
+ and not str(item.get("corrected", "")).strip()):
142
+ raise FeedbackError(
143
+ "negative feedback needs a corrected answer")
144
+ item["status"] = "approved"
145
+ item["reviewed_at"] = _now()
146
+ self._save()
147
+ return copy.deepcopy(item)
148
+
149
+ def reject(self, item_id: str) -> dict:
150
+ with self._lock:
151
+ self._reload()
152
+ item = self._find(item_id)
153
+ if item.get("status") not in ("pending", "approved"):
154
+ raise FeedbackError(
155
+ f"cannot reject a {item.get('status')} item")
156
+ item["status"] = "rejected"
157
+ item["reviewed_at"] = _now()
158
+ self._save()
159
+ return copy.deepcopy(item)
160
+
161
+ def export_training(self, path: str | Path) -> dict:
162
+ """Write approved feedback as user/assistant JSONL for the gate."""
163
+ path = Path(path)
164
+ path.parent.mkdir(parents=True, exist_ok=True)
165
+ rows = []
166
+ seen = set()
167
+ with self._lock:
168
+ self._reload()
169
+ for item in self.items:
170
+ if item.get("status") != "approved":
171
+ continue
172
+ assistant = str(item.get("corrected") or
173
+ item.get("assistant") or "").strip()
174
+ user = str(item.get("user") or "").strip()
175
+ if not user or not assistant:
176
+ continue
177
+ key = (user, assistant)
178
+ if key in seen:
179
+ continue
180
+ seen.add(key)
181
+ rows.append({"user": user, "assistant": assistant})
182
+ tmp = path.with_suffix(path.suffix + ".tmp")
183
+ tmp.write_text(
184
+ "".join(json.dumps(row, ensure_ascii=False) + "\n"
185
+ for row in rows),
186
+ encoding="utf-8")
187
+ tmp.replace(path)
188
+ return {"path": str(path), "examples": len(rows)}
@@ -0,0 +1,157 @@
1
+ """Knowledge-gap store for reviewed research proposals.
2
+
3
+ When the assistant has no local source for a question, the question is recorded
4
+ here. A human can turn a gap into a pending research-queue topic; the scheduled
5
+ worker fetches it only after approval. Gaps never train weights directly.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import copy
10
+ import json
11
+ import re
12
+ import threading
13
+ import time
14
+ from pathlib import Path
15
+
16
+
17
+ class KnowledgeGapError(ValueError):
18
+ pass
19
+
20
+
21
+ class GapNotFound(KnowledgeGapError):
22
+ pass
23
+
24
+
25
+ def _now() -> str:
26
+ return time.strftime("%Y-%m-%dT%H:%M:%S")
27
+
28
+
29
+ def _clean_query(query: str) -> str:
30
+ query = re.sub(r"\s+", " ", str(query or "")).strip()
31
+ if not query:
32
+ raise KnowledgeGapError("query is required")
33
+ if len(query) > 500:
34
+ raise KnowledgeGapError("query is too long (max 500 chars)")
35
+ if "\x00" in query:
36
+ raise KnowledgeGapError("query contains a NUL byte")
37
+ return query
38
+
39
+
40
+ class KnowledgeGapStore:
41
+ def __init__(self, path: str | Path = "data/knowledge_gaps.json"):
42
+ self.path = Path(path)
43
+ self.path.parent.mkdir(parents=True, exist_ok=True)
44
+ self._lock = threading.RLock()
45
+ self.items = self._load()
46
+
47
+ def _load(self) -> list[dict]:
48
+ if not self.path.exists():
49
+ return []
50
+ try:
51
+ data = json.loads(self.path.read_text(encoding="utf-8"))
52
+ except (OSError, json.JSONDecodeError) as exc:
53
+ raise KnowledgeGapError(
54
+ f"cannot read knowledge gaps: {exc}") from exc
55
+ if not isinstance(data, list):
56
+ raise KnowledgeGapError("knowledge gaps must be a JSON list")
57
+ return [item for item in data if isinstance(item, dict)]
58
+
59
+ def _reload(self) -> None:
60
+ self.items = self._load()
61
+
62
+ def _save(self) -> None:
63
+ tmp = self.path.with_suffix(self.path.suffix + ".tmp")
64
+ tmp.write_text(
65
+ json.dumps(self.items, indent=2, ensure_ascii=False) + "\n",
66
+ encoding="utf-8")
67
+ tmp.replace(self.path)
68
+
69
+ def _find(self, item_id: str) -> dict:
70
+ item_id = str(item_id or "").strip()
71
+ for item in self.items:
72
+ if item.get("id") == item_id:
73
+ return item
74
+ raise GapNotFound(f"knowledge gap not found: {item_id}")
75
+
76
+ def _next_id(self) -> str:
77
+ nums = []
78
+ for item in self.items:
79
+ match = re.fullmatch(r"g(\d+)", str(item.get("id", "")))
80
+ if match:
81
+ nums.append(int(match.group(1)))
82
+ return f"g{max(nums, default=0) + 1:04d}"
83
+
84
+ def add(self, query: str, session_id: str = "",
85
+ reason: str = "no_local_source") -> dict:
86
+ query = _clean_query(query)
87
+ session_id = str(session_id or "").strip()[:64]
88
+ with self._lock:
89
+ self._reload()
90
+ normalized = query.lower()
91
+ for item in self.items:
92
+ if (item.get("status") in ("pending", "proposed")
93
+ and str(item.get("query", "")).lower() == normalized):
94
+ item["count"] = int(item.get("count", 1)) + 1
95
+ item["last_seen"] = _now()
96
+ if session_id:
97
+ item["session_id"] = session_id
98
+ self._save()
99
+ return copy.deepcopy(item)
100
+ item = {
101
+ "id": self._next_id(),
102
+ "query": query,
103
+ "status": "pending",
104
+ "count": 1,
105
+ "reason": str(reason or "no_local_source")[:100],
106
+ "session_id": session_id,
107
+ "research_id": "",
108
+ "first_seen": _now(),
109
+ "last_seen": _now(),
110
+ "proposed_at": "",
111
+ "dismissed_at": "",
112
+ }
113
+ self.items.append(item)
114
+ self._save()
115
+ return copy.deepcopy(item)
116
+
117
+ def get(self, item_id: str) -> dict:
118
+ with self._lock:
119
+ self._reload()
120
+ return copy.deepcopy(self._find(item_id))
121
+
122
+ def list(self) -> list[dict]:
123
+ with self._lock:
124
+ self._reload()
125
+ return copy.deepcopy(self.items)
126
+
127
+ def stats(self) -> dict:
128
+ counts: dict[str, int] = {}
129
+ for item in self.list():
130
+ status = str(item.get("status", "unknown"))
131
+ counts[status] = counts.get(status, 0) + 1
132
+ return {"total": sum(counts.values()), **counts}
133
+
134
+ def mark_proposed(self, item_id: str, research_id: str) -> dict:
135
+ with self._lock:
136
+ self._reload()
137
+ item = self._find(item_id)
138
+ if item.get("status") != "pending":
139
+ raise KnowledgeGapError(
140
+ f"cannot propose a {item.get('status')} gap")
141
+ item["status"] = "proposed"
142
+ item["research_id"] = str(research_id or "")
143
+ item["proposed_at"] = _now()
144
+ self._save()
145
+ return copy.deepcopy(item)
146
+
147
+ def dismiss(self, item_id: str) -> dict:
148
+ with self._lock:
149
+ self._reload()
150
+ item = self._find(item_id)
151
+ if item.get("status") not in ("pending", "proposed"):
152
+ raise KnowledgeGapError(
153
+ f"cannot dismiss a {item.get('status')} gap")
154
+ item["status"] = "dismissed"
155
+ item["dismissed_at"] = _now()
156
+ self._save()
157
+ return copy.deepcopy(item)
atomzero/lora.py ADDED
@@ -0,0 +1,140 @@
1
+ """Low-rank adapters (LoRA) for HF transformers and the tiny LM."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import math
6
+ from pathlib import Path
7
+
8
+ import torch
9
+ import torch.nn as nn
10
+
11
+ ATTN_SUFFIXES = (".q_proj", ".k_proj", ".v_proj", ".o_proj", ".out_proj",
12
+ ".query", ".key", ".value", ".dense")
13
+ MLP_SUFFIXES = (".mlp", ".fc1", ".fc2", ".gate_proj", ".up_proj",
14
+ ".down_proj", ".c_fc", ".c_proj", ".mlp.0", ".mlp.2",
15
+ "mlp.0", "mlp.2")
16
+ _TARGET_SUFFIXES = ("mlp.0", "mlp.2")
17
+
18
+
19
+ class LoRALinear(nn.Module):
20
+ def __init__(self, base: nn.Linear, r: int = 8, alpha: int = 16):
21
+ super().__init__()
22
+ self.base = base
23
+ for param in self.base.parameters():
24
+ param.requires_grad = False
25
+ self.r = r
26
+ self.scaling = alpha / r
27
+ self.A = nn.Parameter(torch.empty(r, base.in_features))
28
+ self.B = nn.Parameter(torch.zeros(base.out_features, r))
29
+ nn.init.kaiming_uniform_(self.A, a=math.sqrt(5))
30
+ self._fast_dtype = None
31
+
32
+ def set_fast(self, dtype):
33
+ self._fast_dtype = dtype
34
+
35
+ def forward(self, x):
36
+ out = self.base(x)
37
+ a, b = self.A, self.B
38
+ if a.device != x.device:
39
+ a, b = a.to(x.device), b.to(x.device)
40
+ dtype = self._fast_dtype or out.dtype
41
+ delta = (x.to(dtype) @ a.to(dtype).T @ b.to(dtype).T) * self.scaling
42
+ return out + delta.to(out.dtype)
43
+
44
+
45
+ def _target_r(name: str, r_attn: int, r_mlp: int) -> tuple[int, float] | None:
46
+ if r_attn > 0 and name.endswith(ATTN_SUFFIXES):
47
+ return r_attn, float(r_attn)
48
+ if r_mlp > 0 and name.endswith(MLP_SUFFIXES):
49
+ return r_mlp, float(r_mlp)
50
+ return None
51
+
52
+
53
+ def apply_lora(model: nn.Module, r_attn: int = 8, r_mlp: int = 0,
54
+ alpha_attn: int | None = None,
55
+ alpha_mlp: int | None = None) -> nn.Module:
56
+ """Replace target Linear modules with LoRALinear and freeze the base."""
57
+ for name, module in list(model.named_modules()):
58
+ if not isinstance(module, nn.Linear) or isinstance(module, LoRALinear):
59
+ continue
60
+ if not name.endswith(ATTN_SUFFIXES + MLP_SUFFIXES):
61
+ continue
62
+ is_attn = name.endswith(ATTN_SUFFIXES)
63
+ r = r_attn if is_attn else r_mlp
64
+ if r <= 0:
65
+ continue
66
+ alpha = (alpha_attn if is_attn else alpha_mlp) or r
67
+ parent_name, _, child = name.rpartition(".")
68
+ parent = model.get_submodule(parent_name) if parent_name else model
69
+ setattr(parent, child, LoRALinear(module, r, int(alpha)))
70
+ for param in model.parameters():
71
+ param.requires_grad = False
72
+ for module in model.modules():
73
+ if isinstance(module, LoRALinear):
74
+ module.A.requires_grad = True
75
+ module.B.requires_grad = True
76
+ return model
77
+
78
+
79
+ def inject_lora(model: nn.Module, rank: int = 8, alpha: int = 16,
80
+ **kwargs) -> nn.Module:
81
+ """Tiny-LM helper: adapt MLP layers only."""
82
+ return apply_lora(model, r_attn=0, r_mlp=rank, alpha_mlp=alpha)
83
+
84
+
85
+ def count_lora_params(model: nn.Module) -> int:
86
+ return sum(p.numel() for p in lora_parameters(model))
87
+
88
+
89
+ def lora_parameters(model: nn.Module):
90
+ return [p for p in model.parameters() if p.requires_grad]
91
+
92
+
93
+ def lora_state_dict(model: nn.Module) -> dict:
94
+ return {k: v.detach().cpu() for k, v in model.state_dict().items()
95
+ if k.endswith(".A") or k.endswith(".B")
96
+ or k.endswith("lora_A") or k.endswith("lora_B")}
97
+
98
+
99
+ def set_lora_state_dict(model: nn.Module, state: dict):
100
+ target = {k: v for k, v in state.items()
101
+ if k.endswith(".A") or k.endswith(".B")}
102
+ if not target:
103
+ raise SystemExit("adapter has no LoRA A/B tensors")
104
+ model.load_state_dict(target, strict=False)
105
+
106
+
107
+ def merge_lora(model: nn.Module):
108
+ with torch.no_grad():
109
+ for module in model.modules():
110
+ if not isinstance(module, LoRALinear):
111
+ continue
112
+ delta = (module.B @ module.A) * module.scaling
113
+ module.base.weight.add_(delta.to(module.base.weight.dtype))
114
+ module.A.zero_()
115
+ module.B.zero_()
116
+
117
+
118
+ def save_adapter(model: nn.Module, out: str | Path, **config) -> Path:
119
+ out = Path(out)
120
+ out.mkdir(parents=True, exist_ok=True)
121
+ torch.save({"lora": lora_state_dict(model), "config": config},
122
+ out / "adapter.pt")
123
+ (out / "config.json").write_text(json.dumps(config, indent=2) + "\n",
124
+ encoding="utf-8")
125
+ return out
126
+
127
+
128
+ def apply_adapter(model: nn.Module, path: str | Path) -> dict:
129
+ ck = torch.load(Path(path) / "adapter.pt", map_location="cpu",
130
+ weights_only=False)
131
+ config = ck.get("config", {})
132
+ apply_lora(model, r_attn=int(config.get("r_attn", 0)),
133
+ r_mlp=int(config.get("r_mlp", config.get("rank", 8))),
134
+ alpha_attn=config.get("alpha_attn"),
135
+ alpha_mlp=config.get("alpha_mlp", config.get("alpha")))
136
+ state = {k: v for k, v in ck["lora"].items()
137
+ if k.endswith(".A") or k.endswith(".B")}
138
+ model.load_state_dict(state, strict=False)
139
+ model.eval()
140
+ return config
atomzero/ml_safety.py ADDED
@@ -0,0 +1,165 @@
1
+ """Local ML moderation with the exact rule filter as fallback.
2
+
3
+ The ML head is a small linear classifier over frozen MiniLM embeddings. It is
4
+ additive: the existing ``SafetyFilter`` always runs first and can only block.
5
+ If the head or embedding model is missing/broken, behavior is exactly the
6
+ rule-based filter.
7
+
8
+ safety = build_safety_filter()
9
+ verdict = safety.check("tell me the easiest way to end my own life")
10
+ """
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ import math
15
+ from pathlib import Path
16
+
17
+ from atomzero.safety import SafetyFilter
18
+
19
+ ROOT = Path(__file__).resolve().parents[1]
20
+ DEFAULT_HEAD = ROOT / "streamft/moderation_head.json"
21
+ DEFAULT_MODEL = ROOT / "models/all-MiniLM-L6-v2"
22
+
23
+
24
+ class ModerationModelError(RuntimeError):
25
+ pass
26
+
27
+
28
+ class ModerationHead:
29
+ version = "0.3-ml"
30
+
31
+ def __init__(self, head_path: str | Path = DEFAULT_HEAD,
32
+ model_path: str | Path = DEFAULT_MODEL,
33
+ encoder=None, threshold: float | None = None):
34
+ self.head_path = Path(head_path)
35
+ self.model_path = Path(model_path)
36
+ self.encoder = encoder
37
+ self.threshold_override = threshold
38
+ self._head = None
39
+ self._encoder = encoder
40
+
41
+ def load_head(self) -> dict:
42
+ if self._head is not None:
43
+ return self._head
44
+ try:
45
+ payload = json.loads(self.head_path.read_text(encoding="utf-8"))
46
+ weights = payload["binary"]["w"]
47
+ category = payload["category"]
48
+ classes = category["classes"]
49
+ matrix = category["w"]
50
+ if int(payload["dim"]) != len(weights):
51
+ raise ValueError("moderation head dimension mismatch")
52
+ if (len(matrix) != len(weights)
53
+ or any(len(row) != len(classes) for row in matrix)
54
+ or len(category["b"]) != len(classes)):
55
+ raise ValueError("moderation category matrix mismatch")
56
+ except (OSError, KeyError, TypeError, ValueError) as exc:
57
+ raise ModerationModelError(
58
+ f"cannot load moderation head: {exc}") from exc
59
+ self._head = payload
60
+ return payload
61
+
62
+ def _embed(self, text: str) -> list[float]:
63
+ if self._encoder is None:
64
+ from atomzero.neural_embedder import NeuralReranker
65
+ self._encoder = NeuralReranker(self.model_path)
66
+ self._encoder.embed(["warmup"])
67
+ vector = self._encoder.embed([str(text)])[0]
68
+ if hasattr(vector, "tolist"):
69
+ vector = vector.tolist()
70
+ return [float(value) for value in vector]
71
+
72
+ def score(self, text: str, threshold: float | None = None) -> dict | None:
73
+ head = self.load_head()
74
+ vector = self._embed(text)
75
+ weights = head["binary"]["w"]
76
+ if len(vector) != len(weights):
77
+ raise ModerationModelError("embedding dimension mismatch")
78
+ logit = sum(a * b for a, b in zip(weights, vector)) + float(
79
+ head["binary"]["b"])
80
+ probability = 1.0 / (1.0 + math.exp(-max(-40.0, min(40.0, logit))))
81
+ if threshold is None:
82
+ threshold = (float(self.threshold_override)
83
+ if self.threshold_override is not None
84
+ else float(head["threshold"]))
85
+ if probability < threshold:
86
+ return None
87
+ category = head["category"]
88
+ weights_c = category["w"]
89
+ logits = []
90
+ for index, bias in enumerate(category["b"]):
91
+ logits.append(sum(weights_c[dim][index] * vector[dim]
92
+ for dim in range(len(vector))) + float(bias))
93
+ label = category["classes"][
94
+ max(range(len(logits)), key=lambda index: logits[index])]
95
+ return {"category": label, "action": "refuse",
96
+ "match": f"ml:{probability:.3f}"}
97
+
98
+
99
+ class HybridSafetyFilter:
100
+ """Rules first, then an optional ML head; any ML failure falls back."""
101
+
102
+ def __init__(self, rules: SafetyFilter | None = None,
103
+ model: ModerationHead | None = None,
104
+ output_threshold: float = 0.90):
105
+ self.rules = rules or SafetyFilter()
106
+ self.model = model
107
+ self.output_threshold = float(output_threshold)
108
+
109
+ @property
110
+ def version(self) -> str:
111
+ return self.model.version if self.model is not None else self.rules.version
112
+
113
+ @property
114
+ def ml_enabled(self) -> bool:
115
+ return self.model is not None
116
+
117
+ def check(self, text: str) -> dict | None:
118
+ verdict = self.rules.check(text)
119
+ if verdict is not None:
120
+ return verdict
121
+ if self.model is None:
122
+ return None
123
+ try:
124
+ return self.model.score(text)
125
+ except (ModerationModelError, OSError, RuntimeError, ValueError):
126
+ # Exact rule behavior from here on.
127
+ self.model = None
128
+ return None
129
+
130
+ def refusal(self, category: str) -> str:
131
+ return self.rules.refusal(category)
132
+
133
+ def filter_reply(self, text: str) -> tuple[str, dict | None]:
134
+ # Outputs are short and structurally different from requests, so the
135
+ # ML head needs a stricter threshold there. Rules remain authoritative.
136
+ verdict = self.rules.check(text)
137
+ if verdict is None and self.model is not None:
138
+ try:
139
+ verdict = self.model.score(
140
+ text, threshold=self.output_threshold)
141
+ except (ModerationModelError, OSError, RuntimeError, ValueError):
142
+ self.model = None
143
+ verdict = None
144
+ if verdict is None:
145
+ return text, None
146
+ return self.refusal(verdict["category"]), verdict
147
+
148
+
149
+ def build_safety_filter(prefer_ml: bool = True,
150
+ head_path: str | Path = DEFAULT_HEAD,
151
+ model_path: str | Path = DEFAULT_MODEL,
152
+ encoder=None,
153
+ preflight: bool = True) -> SafetyFilter | HybridSafetyFilter:
154
+ """Return the hybrid filter when head and encoder load, else exact rules."""
155
+ rules = SafetyFilter()
156
+ if not prefer_ml:
157
+ return rules
158
+ try:
159
+ head = ModerationHead(head_path, model_path, encoder=encoder)
160
+ head.load_head()
161
+ if preflight:
162
+ head._embed("warmup")
163
+ return HybridSafetyFilter(rules, head)
164
+ except (ModerationModelError, OSError, RuntimeError, ValueError):
165
+ return rules