classone 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.
@@ -0,0 +1,334 @@
1
+ """Training and calibration loop for ClassOne System One decision models.
2
+
3
+ Implements:
4
+ - Parameter-Efficient Fine-Tuning (LoRA via PEFT)
5
+ - Multi-task RLCD training step with proper scoring rules (Brier + Log-Loss)
6
+ - Memory-efficient per-item gradient accumulation
7
+ - Temperature scaling calibration for optimal epistemic confidence
8
+ - Model checkpoint saving and loading (including LoRA adapters)
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import os
14
+ from dataclasses import dataclass
15
+ from typing import Any
16
+
17
+ import torch
18
+ from peft import LoraConfig, PeftModel, get_peft_model
19
+
20
+ from classone.modeling.loss import RLCDLoss
21
+ from classone.modeling.modeling_classone import ClassOneModel
22
+ from classone.schemas import Question
23
+ from classone.tokenizer import ClassOnePromptBuilder
24
+
25
+
26
+ @dataclass
27
+ class TrainingItem:
28
+ """A single training instance pairing input state, questions, and ground-truth targets."""
29
+
30
+ state: str | dict[str, Any] | list[Any]
31
+ questions: dict[str, Question]
32
+ targets: dict[str, int | float | str]
33
+
34
+
35
+ class ClassOneTrainer:
36
+ """Trainer executing Reinforcement Learning for Calibrated Decisions (RLCD)."""
37
+
38
+ def __init__(
39
+ self,
40
+ model: ClassOneModel,
41
+ prompt_builder: ClassOnePromptBuilder,
42
+ loss_fn: RLCDLoss | None = None,
43
+ lr: float = 1e-4,
44
+ weight_decay: float = 0.01,
45
+ device: str | torch.device | None = None,
46
+ ):
47
+ self.model = model
48
+ self.prompt_builder = prompt_builder
49
+ self.loss_fn = loss_fn or RLCDLoss(brier_weight=0.5, log_weight=1.0)
50
+ self.lr = lr
51
+ self.weight_decay = weight_decay
52
+ self.device = torch.device(device) if device else self.model.device
53
+ self.model.to(self.device)
54
+
55
+ # Initialize optimizer for decision heads and trainable backbone parameters
56
+ trainable_params = [p for p in self.model.parameters() if p.requires_grad]
57
+ self.optimizer = torch.optim.AdamW(trainable_params, lr=self.lr, weight_decay=self.weight_decay)
58
+
59
+ def enable_lora(
60
+ self,
61
+ r: int = 16,
62
+ lora_alpha: int = 32,
63
+ lora_dropout: float = 0.05,
64
+ target_modules: list[str] | None = None,
65
+ ):
66
+ """Attaches LoRA adapters to the transformer backbone, keeping heads trainable."""
67
+ if target_modules is None:
68
+ # Common attention and MLP projection layers in Gemma / modern LLMs
69
+ target_candidates = [
70
+ "q_proj",
71
+ "k_proj",
72
+ "v_proj",
73
+ "o_proj",
74
+ "gate_proj",
75
+ "up_proj",
76
+ "down_proj",
77
+ ]
78
+ if hasattr(self.model.backbone, "language_model"):
79
+ # Multi-modal architectures like Gemma 4: target linear projections in language_model
80
+ target_modules = r".*language_model.*(q_proj|o_proj|gate_proj|up_proj|down_proj).*"
81
+ else:
82
+ # Filter to candidates that actually exist as Linear in the backbone
83
+ existing_modules = {
84
+ name.split(".")[-1]
85
+ for name, mod in self.model.backbone.named_modules()
86
+ if isinstance(mod, torch.nn.Linear)
87
+ }
88
+ matched = [m for m in target_candidates if m in existing_modules]
89
+ target_modules = matched if matched else target_candidates
90
+
91
+ lora_config = LoraConfig(
92
+ r=r,
93
+ lora_alpha=lora_alpha,
94
+ lora_dropout=lora_dropout,
95
+ target_modules=target_modules,
96
+ bias="none",
97
+ )
98
+
99
+ # Apply LoRA to the backbone
100
+ self.model.backbone = get_peft_model(self.model.backbone, lora_config)
101
+
102
+ # Ensure decision heads remain trainable
103
+ for head in [
104
+ self.model.noul_head,
105
+ self.model.choice_head,
106
+ self.model.score_head,
107
+ ]:
108
+ for param in head.parameters():
109
+ param.requires_grad = True
110
+
111
+ # Re-initialize optimizer with updated trainable parameters preserving initial lr & decay
112
+ trainable_params = [p for p in self.model.parameters() if p.requires_grad]
113
+ self.optimizer = torch.optim.AdamW(trainable_params, lr=self.lr, weight_decay=self.weight_decay)
114
+
115
+ def train_step(self, batch: list[TrainingItem]) -> dict[str, float]:
116
+ """Executes a single gradient update across a batch of multi-task items with per-item accumulation."""
117
+ self.model.train()
118
+ self.optimizer.zero_grad()
119
+
120
+ # Count total valid questions in batch first for correct gradient normalization
121
+ total_valid_questions = 0
122
+ packed_batch = []
123
+ for item in batch:
124
+ packed = self.prompt_builder.pack(state=item.state, questions=item.questions)
125
+ packed_batch.append((item, packed))
126
+ for q_id in item.targets:
127
+ if q_id in packed.questions:
128
+ total_valid_questions += 1
129
+
130
+ if total_valid_questions == 0:
131
+ return {"loss": 0.0, "questions": 0}
132
+
133
+ accumulated_loss_val = 0.0
134
+
135
+ for item, packed in packed_batch:
136
+ input_ids = packed.input_ids.to(self.device)
137
+ attention_mask = packed.attention_mask.to(self.device)
138
+
139
+ hidden_states = self.model.extract_hidden_states(input_ids=input_ids, attention_mask=attention_mask)
140
+ seq_hidden = hidden_states[0]
141
+ head_dtype = next(self.model.noul_head.parameters()).dtype
142
+ if seq_hidden.dtype != head_dtype:
143
+ seq_hidden = seq_hidden.to(head_dtype)
144
+
145
+ item_loss = torch.tensor(0.0, device=self.device)
146
+ item_question_count = 0
147
+
148
+ for q_id, target in item.targets.items():
149
+ if q_id not in packed.questions:
150
+ continue
151
+
152
+ span = packed.questions[q_id]
153
+
154
+ if span.question_type == "noul":
155
+ h_query = seq_hidden[span.query_token_idx]
156
+ prob = self.model.noul_head(h_query)
157
+ target_tensor = torch.tensor([float(target)], device=self.device, dtype=torch.float32)
158
+ q_loss = self.loss_fn.forward_binary(prob, target_tensor)
159
+ item_loss = item_loss + q_loss
160
+ item_question_count += 1
161
+
162
+ elif span.question_type == "choice":
163
+ h_query = seq_hidden[span.query_token_idx]
164
+ h_opts = torch.stack([seq_hidden[idx] for idx in span.option_token_indices])
165
+ probs = self.model.choice_head(h_query, h_opts) # [num_options]
166
+
167
+ # Target index resolution
168
+ if isinstance(target, str):
169
+ target_idx = span.option_keys.index(target) if target in span.option_keys else 0
170
+ else:
171
+ target_idx = int(target)
172
+
173
+ target_tensor = torch.tensor([target_idx], device=self.device, dtype=torch.long)
174
+ q_loss = self.loss_fn.forward_multiclass(probs.unsqueeze(0), target_tensor)
175
+ item_loss = item_loss + q_loss
176
+ item_question_count += 1
177
+
178
+ elif span.question_type == "score":
179
+ h_query = seq_hidden[span.query_token_idx]
180
+ h_levels = torch.stack([seq_hidden[idx] for idx in span.option_token_indices])
181
+ _, probs = self.model.score_head(h_query, h_levels)
182
+
183
+ # Robust score target parsing (supports numeric index, string level number, or rubric text)
184
+ if isinstance(target, (int, float)):
185
+ target_idx = max(0, min(len(span.option_keys) - 1, int(target) - 1))
186
+ elif str(target) in span.option_keys:
187
+ target_idx = span.option_keys.index(str(target))
188
+ else:
189
+ target_idx = 0
190
+
191
+ target_tensor = torch.tensor([target_idx], device=self.device, dtype=torch.long)
192
+ q_loss = self.loss_fn.forward_multiclass(probs.unsqueeze(0), target_tensor)
193
+ item_loss = item_loss + q_loss
194
+ item_question_count += 1
195
+
196
+ if item_question_count > 0:
197
+ scaled_loss = item_loss / total_valid_questions
198
+ scaled_loss.backward()
199
+ accumulated_loss_val += float(item_loss.item())
200
+
201
+ torch.nn.utils.clip_grad_norm_(self.model.parameters(), max_norm=1.0)
202
+ self.optimizer.step()
203
+
204
+ return {
205
+ "loss": accumulated_loss_val / total_valid_questions,
206
+ "questions": total_valid_questions,
207
+ }
208
+
209
+ def calibrate_temperature(
210
+ self,
211
+ val_data: list[TrainingItem],
212
+ lr: float = 0.05,
213
+ max_epochs: int = 20,
214
+ ) -> dict[str, float]:
215
+ """Calibrates head temperatures via validation loss optimization to minimize ECE."""
216
+ self.model.eval()
217
+
218
+ # Cache original parameter requires_grad states to prevent unfreezing the backbone
219
+ original_grad_states = {name: p.requires_grad for name, p in self.model.named_parameters()}
220
+
221
+ for p in self.model.parameters():
222
+ p.requires_grad = False
223
+
224
+ # Optimize the raw temperature parameters
225
+ self.model.noul_head.temperature_raw.requires_grad = True
226
+ self.model.choice_head.temperature_raw.requires_grad = True
227
+ self.model.score_head.choice_evaluator.temperature_raw.requires_grad = True
228
+
229
+ temp_optimizer = torch.optim.Adam(
230
+ [
231
+ self.model.noul_head.temperature_raw,
232
+ self.model.choice_head.temperature_raw,
233
+ self.model.score_head.choice_evaluator.temperature_raw,
234
+ ],
235
+ lr=lr,
236
+ )
237
+
238
+ for _ in range(max_epochs):
239
+ temp_optimizer.zero_grad()
240
+ calib_loss = torch.tensor(0.0, device=self.device)
241
+ count = 0
242
+
243
+ for item in val_data:
244
+ packed = self.prompt_builder.pack(item.state, item.questions)
245
+ with torch.no_grad():
246
+ hidden_states = self.model.extract_hidden_states(
247
+ packed.input_ids.to(self.device),
248
+ packed.attention_mask.to(self.device),
249
+ )
250
+ seq_hidden = hidden_states[0]
251
+
252
+ for q_id, target in item.targets.items():
253
+ if q_id not in packed.questions:
254
+ continue
255
+ span = packed.questions[q_id]
256
+ if span.question_type == "noul":
257
+ h_query = seq_hidden[span.query_token_idx]
258
+ prob = self.model.noul_head(h_query)
259
+ t = torch.tensor([float(target)], device=self.device)
260
+ calib_loss = calib_loss + self.loss_fn.forward_binary(prob, t)
261
+ count += 1
262
+ elif span.question_type == "choice":
263
+ h_query = seq_hidden[span.query_token_idx]
264
+ h_opts = torch.stack([seq_hidden[idx] for idx in span.option_token_indices])
265
+ probs = self.model.choice_head(h_query, h_opts)
266
+ t_idx = (
267
+ span.option_keys.index(target)
268
+ if (isinstance(target, str) and target in span.option_keys)
269
+ else int(target)
270
+ )
271
+ t = torch.tensor([t_idx], device=self.device)
272
+ calib_loss = calib_loss + self.loss_fn.forward_multiclass(probs.unsqueeze(0), t)
273
+ count += 1
274
+ elif span.question_type == "score":
275
+ h_query = seq_hidden[span.query_token_idx]
276
+ h_levels = torch.stack([seq_hidden[idx] for idx in span.option_token_indices])
277
+ _, probs = self.model.score_head(h_query, h_levels)
278
+ if isinstance(target, (int, float)):
279
+ t_idx = max(0, min(len(span.option_keys) - 1, int(target) - 1))
280
+ elif str(target) in span.option_keys:
281
+ t_idx = span.option_keys.index(str(target))
282
+ else:
283
+ t_idx = 0
284
+ t = torch.tensor([t_idx], device=self.device)
285
+ calib_loss = calib_loss + self.loss_fn.forward_multiclass(probs.unsqueeze(0), t)
286
+ count += 1
287
+
288
+ if count > 0:
289
+ (calib_loss / count).backward()
290
+ temp_optimizer.step()
291
+
292
+ # Accurately restore original gradient states
293
+ for name, p in self.model.named_parameters():
294
+ p.requires_grad = original_grad_states[name]
295
+
296
+ return {
297
+ "noul_temp": float(self.model.noul_head.temperature.item()),
298
+ "choice_temp": float(self.model.choice_head.temperature.item()),
299
+ "score_temp": float(self.model.score_head.temperature.item()),
300
+ }
301
+
302
+ def save_checkpoint(self, output_dir: str):
303
+ """Saves model weights, decision heads, and configuration to directory."""
304
+ os.makedirs(output_dir, exist_ok=True)
305
+ checkpoint_path = os.path.join(output_dir, "classone_heads.pt")
306
+ torch.save(
307
+ {
308
+ "noul_head": self.model.noul_head.state_dict(),
309
+ "choice_head": self.model.choice_head.state_dict(),
310
+ "score_head": self.model.score_head.state_dict(),
311
+ "config": self.model.config.to_dict(),
312
+ },
313
+ checkpoint_path,
314
+ )
315
+
316
+ # If LoRA was attached, save adapters
317
+ if hasattr(self.model.backbone, "save_pretrained"):
318
+ lora_dir = os.path.join(output_dir, "lora_backbone")
319
+ self.model.backbone.save_pretrained(lora_dir)
320
+
321
+ def load_checkpoint(self, checkpoint_dir: str):
322
+ """Loads decision heads and optional LoRA adapters from directory."""
323
+ checkpoint_path = os.path.join(checkpoint_dir, "classone_heads.pt")
324
+ data = torch.load(checkpoint_path, map_location=self.device)
325
+ self.model.noul_head.load_state_dict(data["noul_head"])
326
+ self.model.choice_head.load_state_dict(data["choice_head"])
327
+ self.model.score_head.load_state_dict(data["score_head"])
328
+
329
+ lora_dir = os.path.join(checkpoint_dir, "lora_backbone")
330
+ if os.path.exists(lora_dir):
331
+ if isinstance(self.model.backbone, PeftModel):
332
+ self.model.backbone.load_adapter(lora_dir, adapter_name="default")
333
+ else:
334
+ self.model.backbone = PeftModel.from_pretrained(self.model.backbone, lora_dir)
@@ -0,0 +1,152 @@
1
+ Metadata-Version: 2.4
2
+ Name: classone
3
+ Version: 0.1.0
4
+ Summary: Open-source System 1 decision model architecture built on Gemma 4 E2B
5
+ Author: Thiago
6
+ Project-URL: Homepage, https://github.com/devops-thiago/class-one
7
+ Project-URL: Repository, https://github.com/devops-thiago/class-one
8
+ Project-URL: Issues, https://github.com/devops-thiago/class-one/issues
9
+ Requires-Python: >=3.10
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Requires-Dist: pydantic>=2.5.0
13
+ Requires-Dist: fastapi>=0.110.0
14
+ Requires-Dist: uvicorn>=0.28.0
15
+ Requires-Dist: torch>=2.2.0
16
+ Requires-Dist: transformers>=4.40.0
17
+ Requires-Dist: peft>=0.10.0
18
+ Requires-Dist: accelerate>=0.21.0
19
+ Requires-Dist: numpy>=1.26.0
20
+ Provides-Extra: dev
21
+ Requires-Dist: pytest>=8.0.0; extra == "dev"
22
+ Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
23
+ Requires-Dist: httpx>=0.27.0; extra == "dev"
24
+ Dynamic: license-file
25
+
26
+ # ClassOne: System 1 Decision Model Architecture
27
+
28
+ [![CI](https://github.com/devops-thiago/class-one/actions/workflows/ci.yml/badge.svg)](https://github.com/devops-thiago/class-one/actions/workflows/ci.yml)
29
+ [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
30
+
31
+ **ClassOne** is an open-source **System 1 decision model architecture** built on Google's **Gemma 4 E2B** (Effective 2B). It provides rapid, non-autoregressive, schema-constrained decision execution for classification, routing, verification, and scoring in a single forward pass.
32
+
33
+ Inspired by Daniel Kahneman's cognitive framework in *Thinking, Fast and Slow* and modern proper scoring rules (Brier, 1950; Gneiting & Raftery, 2007).
34
+
35
+ ---
36
+
37
+ ## Key Features
38
+
39
+ - **System 1 Architecture:** Non-autoregressive decision model. Skips open-ended token generation entirely.
40
+ - **Single-Pass Parallel Evaluation:** Evaluates multiple typed questions (`Noul`, `Choice`, `Score`) simultaneously in a single forward pass over unstructured state (<10ms on MPS, <50ms on edge GPU).
41
+ - **Zero Structural Hallucinations:** Constrained by design to valid schema outputs.
42
+ - **Calibrated Probabilities (RLCD):** Trained and scored using Strictly Proper Scoring Rules (normalized Brier score + Negative Log-Likelihood) to penalize overconfidence.
43
+ - **Dual API Endpoints:** Exposes `POST /v1/decide` and `POST /v1/classone` for schema-out decision queries.
44
+ - **Python Client SDK:** Idiomatic synchronous and asynchronous client library (`from classone import ClassOneClient`).
45
+
46
+ ---
47
+
48
+ ## Quickstart
49
+
50
+ ### 1. Installation
51
+
52
+ ```bash
53
+ git clone https://github.com/devops-thiago/class-one.git
54
+ cd class-one
55
+ python3 -m venv .venv
56
+ source .venv/bin/activate
57
+ pip install -e ".[dev]"
58
+ ```
59
+
60
+ ### 2. Run Test Suite
61
+
62
+ ```bash
63
+ pytest tests/
64
+ ```
65
+
66
+ ### 3. Start the API Server
67
+
68
+ ```bash
69
+ uvicorn classone.server.app:app --host 0.0.0.0 --port 8000
70
+ ```
71
+
72
+ ### 4. Query via HTTP
73
+
74
+ ```bash
75
+ curl -X POST http://localhost:8000/v1/classone \
76
+ -H "Content-Type: application/json" \
77
+ -d '{
78
+ "model": "class-one-gemma-4-e2b",
79
+ "state": {
80
+ "message": "I was double billed for my subscription."
81
+ },
82
+ "questions": {
83
+ "refund": {
84
+ "type": "noul",
85
+ "instructions": "Is customer asking for a refund?"
86
+ },
87
+ "routing": {
88
+ "type": "choice",
89
+ "instructions": "Which department?",
90
+ "criteria": {
91
+ "billing": "Charges and payouts",
92
+ "technical": "App bugs and crashes"
93
+ }
94
+ },
95
+ "urgency": {
96
+ "type": "score",
97
+ "instructions": "Ticket urgency",
98
+ "criteria": ["low", "normal", "critical"]
99
+ }
100
+ }
101
+ }'
102
+ ```
103
+
104
+ ### 5. Python SDK Usage
105
+
106
+ ```python
107
+ from classone import ClassOneClient, Choice, Noul, Score
108
+
109
+ with ClassOneClient(base_url="http://localhost:8000") as client:
110
+ response = client.decide(
111
+ state="Customer account was locked after three incorrect attempts.",
112
+ questions={
113
+ "urgent": Noul(instructions="Is this an urgent security event?"),
114
+ "action": Choice(
115
+ instructions="Action required:",
116
+ criteria={"unlock": "Send unlock link", "escalate": "Escalate to SecOps"}
117
+ ),
118
+ "severity": Score(
119
+ instructions="Assess severity:",
120
+ criteria=["low", "medium", "critical"]
121
+ ),
122
+ }
123
+ )
124
+
125
+ print("Urgent P(true):", response.nouls["urgent"].noul)
126
+ print("Action Choice:", response.choices["action"].choice)
127
+ print("Severity Score:", response.scores["severity"].score)
128
+ ```
129
+
130
+ ---
131
+
132
+ ## CLI Utilities
133
+
134
+ ```bash
135
+ # Run single-pass decision inference on Gemma:
136
+ python scripts/run_classone.py --model google/gemma-2-2b-it --device auto
137
+
138
+ # Benchmark latency vs traditional autoregressive LLMs:
139
+ python scripts/benchmark_latency.py --iterations 30
140
+ ```
141
+
142
+ ---
143
+
144
+ ## Reference
145
+ - **Architecture:** [`ARCHITECTURE.md`](ARCHITECTURE.md)
146
+
147
+ ---
148
+
149
+ ## Legal & Attribution Notices
150
+
151
+ - Gemma is a trademark of Google LLC.
152
+ - Gemma is provided under and subject to the Gemma Terms of Use found at [ai.google.dev/gemma/terms](https://ai.google.dev/gemma/terms).
@@ -0,0 +1,19 @@
1
+ classone/__init__.py,sha256=BSx0zBUGowfEerQHF7TkPndq_LhKJi253keQqcLEybE,946
2
+ classone/schemas.py,sha256=-5HF_7qd5rtfIT35oX84V-OtXZQzG-z4Kjfo-bYKXs0,4772
3
+ classone/sdk.py,sha256=4K36swYNoZqBs5swA7fNWQdysvpY_D6DOSpDvMClLAQ,9175
4
+ classone/tokenizer.py,sha256=48UwCCkrfWf2bcQOGAmzsLuOMkyeyUHFrfHwmSNt2eA,8934
5
+ classone/data/__init__.py,sha256=bjihtSdKTSHa1HMtA7BYxSBUUooyOepG2RoVwaia0Lo,59
6
+ classone/data/dataset.py,sha256=OUZCq462401e_QTB6BwAqYJHKp0QdgGsj_wPX49ThtY,5872
7
+ classone/modeling/__init__.py,sha256=LO6sXtlyhmUDDw2nfG9DNZI2ZnK2jelCBlLn50OsJYI,602
8
+ classone/modeling/configuration_classone.py,sha256=6Uar_wx18QA0b-K3TQ-5Vpl7doH8IdGQMlz_L2j1H1s,888
9
+ classone/modeling/loss.py,sha256=JgLbEk5qM2cWVgdbnrJhUTb0QZDOIf2b1T7ZkxlOTiw,5179
10
+ classone/modeling/modeling_classone.py,sha256=dh9-YYqAyk6D22As-GtgC6szI1kUi3gbiCdNlwtBo3g,14570
11
+ classone/server/__init__.py,sha256=LtKXoT433HDnQr1DKUjF1w6VRXzxYbfdZaciaXoOqpc,59
12
+ classone/server/app.py,sha256=DjuuQMhvK4oVaD5KYqv6BakELlGjyivCjTSJLkVgsmk,4823
13
+ classone/train/__init__.py,sha256=QS2y0m_NTKQTC-mQ7vJq0qrsXLryq18KAsTsd0RTNg4,68
14
+ classone/train/trainer.py,sha256=8_evIaQFVx0zMNKHb8SD6FMpxOlYsKyI672QoT37yuM,14730
15
+ classone-0.1.0.dist-info/licenses/LICENSE,sha256=q98xkcVqv2MBnqAZMdiu6CFK9IMhkRIujktsOWkGC30,10714
16
+ classone-0.1.0.dist-info/METADATA,sha256=x01oiIcMy_hy3F3mfZ9EIzGt7Pe6oLzOAoi6ZoUlGEc,4990
17
+ classone-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
18
+ classone-0.1.0.dist-info/top_level.txt,sha256=t_HVdyFrhFXWfhIkWiF1OxgjnXL6LggFW6oDbnWc7jo,9
19
+ classone-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+