theclassifier 0.1.0__py3-none-any.whl

theclassifier/__init__.py

@@ -0,0 +1,12 @@
+"""The Classifier: local inference and LoRA fine-tuning."""
+__version__ = "0.1.0"
+
+
+def __getattr__(name):
+    if name == "Classifier":
+        from .model import Classifier
+        return Classifier
+    if name == "finetune":
+        from .training import finetune
+        return finetune
+    raise AttributeError(name)

theclassifier/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+main()

theclassifier/checkpoints.py

@@ -0,0 +1,40 @@
+"""Cache-first checkpoint resolution. No model weights are bundled in the wheel."""
+import json
+import os
+from pathlib import Path
+from huggingface_hub import snapshot_download
+from huggingface_hub.errors import LocalEntryNotFoundError
+
+VERSIONS = ("general", "intent", "sentiment", "triage", "cause", "codify", "complaints", "stars")
+
+
+def validate_checkpoint(path):
+    path = Path(path)
+    required = [path / "adapter/adapter_config.json", path / "tokenizer/tokenizer_config.json"]
+    weights = any((path / "adapter" / name).is_file() for name in ("adapter_model.safetensors", "adapter_model.bin"))
+    if not weights or not all(p.is_file() for p in required) or not any((path / name).is_file() for name in ("head.safetensors", "head.pt")):
+        raise ValueError(f"Incomplete checkpoint at {path}: expected adapter/, tokenizer/ and head.safetensors or head.pt")
+    return path
+
+
+def resolve_checkpoint(version="general", *, checkpoint=None, model_repo=None, cache_dir=None, revision="main", offline=False):
+    if checkpoint is not None:
+        return validate_checkpoint(Path(checkpoint).expanduser())
+    if version not in VERSIONS:
+        raise ValueError(f"Unknown version {version!r}; choose {', '.join(VERSIONS)} or supply checkpoint=...")
+    repo = model_repo or os.environ.get("THECLASSIFIER_MODEL_REPO") or "TrueState/theclassifier"
+    options = dict(repo_id=repo, revision=revision, cache_dir=cache_dir,
+                   allow_patterns=[f"{version}/adapter/*", f"{version}/tokenizer/*", f"{version}/head.*", f"{version}/classifier.json"])
+    try:
+        root = snapshot_download(**options, local_files_only=True)
+        return validate_checkpoint(Path(root) / version)
+    except (LocalEntryNotFoundError, ValueError):
+        if offline:
+            raise FileNotFoundError(f"Version {version!r} is not fully cached; download it once before offline use") from None
+    root = snapshot_download(**options)
+    return validate_checkpoint(Path(root) / version)
+
+
+def checkpoint_model(path):
+    config = json.loads((Path(path) / "adapter/adapter_config.json").read_text())
+    return config["base_model_name_or_path"]

theclassifier/cli.py

@@ -0,0 +1,63 @@
+import argparse
+import json
+import os
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="theclassifier")
+    sub = parser.add_subparsers(dest="command", required=True)
+    for command in ("serve", "classify", "download", "finetune"):
+        p = sub.add_parser(command)
+        p.add_argument("--version", default="general" if command != "finetune" else None)
+        p.add_argument("--checkpoint")
+        p.add_argument("--model-repo", default=os.getenv("THECLASSIFIER_MODEL_REPO"))
+        p.add_argument("--cache-dir")
+        p.add_argument("--revision", default="main")
+        p.add_argument("--offline", action="store_true")
+        if command != "download":
+            p.add_argument("--device", default="auto")
+            p.add_argument("--max-length", type=int, default=2048)
+        if command == "serve":
+            p.add_argument("--host", default="127.0.0.1")
+            p.add_argument("--port", type=int, default=8090)
+        elif command == "classify":
+            p.add_argument("--text", required=True)
+            p.add_argument("--choices", nargs="+", required=True)
+            p.add_argument("--question", default="Which label fits?")
+        elif command == "finetune":
+            p.add_argument("--data", required=True)
+            p.add_argument("--output", required=True)
+            p.add_argument("--base-model", default="Qwen/Qwen3-1.7B-Base")
+            p.add_argument("--epochs", type=int, default=1)
+            p.add_argument("--rank", type=int, default=16)
+            p.add_argument("--alpha", type=int, default=16)
+            p.add_argument("--learning-rate", type=float, default=2e-4)
+            p.add_argument("--grad-accum", type=int, default=16)
+            p.add_argument("--max-steps", type=int)
+    args = vars(parser.parse_args(argv))
+    command = args.pop("command")
+    try:
+        if command == "download":
+            from .checkpoints import resolve_checkpoint
+            print(resolve_checkpoint(**args))
+        elif command == "finetune":
+            from .training import finetune
+            args["output_dir"] = args.pop("output")
+            print(json.dumps(finetune(**args), indent=2, default=str))
+        else:
+            from .model import Classifier
+            if command == "classify":
+                text, choices, question = args.pop("text"), args.pop("choices"), args.pop("question")
+                print(json.dumps(Classifier(**args).classify(text, choices=choices, question=question), indent=2))
+            else:
+                host, port = args.pop("host"), args.pop("port")
+                key = os.getenv("API_KEY")
+                if host not in {"localhost", "127.0.0.1", "::1"} and not key:
+                    parser.error("Set API_KEY before exposing the server outside localhost")
+                import uvicorn
+                from .server import create_app
+                uvicorn.run(create_app(Classifier(**args), api_key=key), host=host, port=port)
+    except (ValueError, FileNotFoundError) as exc:
+        parser.error(str(exc))
+    except ImportError as exc:
+        parser.error(f"Missing dependency: {exc}. For serving, install theclassifier[serve].")

theclassifier/model.py

@@ -0,0 +1,142 @@
+import json
+import threading
+import time
+from pathlib import Path
+import torch
+from torch import nn
+from transformers import AutoModel, AutoTokenizer
+from peft import PeftModel
+from safetensors.torch import load_file
+from .checkpoints import resolve_checkpoint, checkpoint_model
+from .prompt import pack_example
+from .schema import normalize
+
+
+def select_device(device="auto"):
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu") if device == "auto" else torch.device(device)
+    if device.type not in {"cpu", "cuda"}:
+        raise ValueError("Supported devices: auto, cpu, cuda, cuda:N")
+    if device.type == "cuda" and not torch.cuda.is_available():
+        raise ValueError("CUDA was requested but is unavailable. Install a CUDA-enabled PyTorch build or use device='cpu'.")
+    return device
+
+
+def select_dtype(device):
+    if device.type == "cuda":
+        with torch.cuda.device(device):
+            return torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float32
+    return torch.float32
+
+
+class Scorer(nn.Module):
+    def __init__(self, encoder):
+        super().__init__()
+        self.encoder = encoder
+        self.head = nn.Linear(encoder.config.hidden_size, 1)
+
+    def forward(self, input_ids, attention_mask):
+        hidden = self.encoder(input_ids=input_ids, attention_mask=attention_mask, use_cache=False).last_hidden_state
+        last = attention_mask.sum(dim=1) - 1
+        return self.head(hidden[torch.arange(len(hidden), device=hidden.device), last].float()).squeeze(-1)
+
+
+def load_head(path):
+    path = Path(path)
+    if (path / "head.safetensors").is_file():
+        return load_file(str(path / "head.safetensors"))
+    return torch.load(path / "head.pt", map_location="cpu", weights_only=True)
+
+
+class Classifier:
+    def __init__(self, version="general", *, checkpoint=None, model_repo=None, cache_dir=None,
+                 revision="main", offline=False, device="auto", max_length=2048, batch_size=8,
+                 base_model=None, attention="sdpa"):
+        if max_length < 2 or batch_size < 1:
+            raise ValueError("max_length must be >=2 and batch_size >=1")
+        if attention not in {"sdpa", "eager"}:
+            raise ValueError("attention must be sdpa or eager")
+        self.device = select_device(device)
+        self.options = dict(model_repo=model_repo, cache_dir=cache_dir, revision=revision, offline=offline)
+        path = resolve_checkpoint(version, checkpoint=checkpoint, **self.options)
+        self.base_model = base_model or checkpoint_model(path)
+        self.max_length, self.batch_size = max_length, batch_size
+        self.default_version = version
+        self.lock = threading.RLock()
+        self.tokenizers = {}
+        self.heads = {}
+        encoder = AutoModel.from_pretrained(self.base_model, dtype=select_dtype(self.device), attn_implementation=attention,
+                                           cache_dir=cache_dir, local_files_only=offline, trust_remote_code=False)
+        encoder = PeftModel.from_pretrained(encoder, path / "adapter", adapter_name=version, local_files_only=True)
+        self.model = Scorer(encoder).to(self.device)
+        self._store(version, path)
+        self.active = None
+        self.model.eval()
+
+    def _store(self, version, path):
+        head = load_head(path)
+        # Validate shape before a checkpoint is made available.
+        probe = nn.Linear(self.model.head.in_features, 1)
+        probe.load_state_dict(head)
+        tokenizer = AutoTokenizer.from_pretrained(path / "tokenizer", local_files_only=True, trust_remote_code=False)
+        if tokenizer.pad_token_id is None:
+            if tokenizer.eos_token_id is None:
+                raise ValueError("Checkpoint tokenizer requires a pad or EOS token")
+            tokenizer.pad_token = tokenizer.eos_token
+        tokenizer.padding_side = "right"
+        self.heads[version], self.tokenizers[version] = head, tokenizer
+
+    def load_adapter(self, version, checkpoint=None):
+        with self.lock:
+            if version in self.heads:
+                return self
+            path = resolve_checkpoint(version, checkpoint=checkpoint, **self.options)
+            expected = checkpoint_model(path)
+            first = self.model.encoder.peft_config[self.default_version].base_model_name_or_path
+            if expected != first:
+                raise ValueError("Adapter base model does not match the loaded backbone")
+            self._store(version, path)
+            try:
+                self.model.encoder.load_adapter(path / "adapter", adapter_name=version, is_trainable=False, local_files_only=True)
+            except Exception:
+                self.heads.pop(version, None); self.tokenizers.pop(version, None)
+                raise
+            self.active = None
+            self.model.eval()
+        return self
+
+    def _tokens(self, rows, tokenizer):
+        sequences = []
+        for text in rows:
+            ids = tokenizer.encode(text, add_special_tokens=True)
+            # Preserve the original checkpoint's first-token-plus-tail convention.
+            if len(ids) > self.max_length:
+                ids = ids[:1] + ids[-(self.max_length - 1):]
+            sequences.append({"input_ids": ids, "attention_mask": [1] * len(ids)})
+        return tokenizer.pad(sequences, padding=True, return_tensors="pt").to(self.device)
+
+    def classify(self, state, questions=None, *, choices=None, question="Which label fits?", version=None):
+        if questions is not None and choices is not None:
+            raise ValueError("Pass questions or choices, not both")
+        questions = normalize(state, questions if questions is not None else [{"question": question, "choices": choices}])
+        version = version or self.default_version
+        start = time.perf_counter()
+        with self.lock, torch.inference_mode():
+            self.load_adapter(version)
+            if self.active != version:
+                self.model.encoder.set_adapter(version)
+                self.model.head.load_state_dict(self.heads[version])
+                self.active = version
+            self.model.eval()
+            tokenizer = self.tokenizers[version]
+            results, tokens = [], 0
+            for item in questions:
+                rows = [pack_example(state, item["question"], c["choice"], item["guidance"], c["criteria"], item["choices"]) for c in item["choices"]]
+                chunks = []
+                for offset in range(0, len(rows), self.batch_size):
+                    batch = self._tokens(rows[offset:offset+self.batch_size], tokenizer)
+                    tokens += int(batch["attention_mask"].sum())
+                    chunks.append(self.model(batch["input_ids"], batch["attention_mask"]))
+                probabilities = torch.cat(chunks).float().softmax(dim=0).cpu().tolist()
+                detailed = sorted([{"choice": c["choice"], "score": round(p, 4)} for c,p in zip(item["choices"], probabilities)], key=lambda row: row["score"], reverse=True)
+                results.append({"question": item["question"], "selected": detailed[0], "detailed_results": detailed})
+            return {"results": results, "version": version, "input_tokens": tokens, "latency_ms": round((time.perf_counter()-start)*1000, 3)}

theclassifier/prompt.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+
+def pack_example(
+    state: str,
+    question: str,
+    choice: str,
+    guidance: str | None = None,
+    criteria: str | None = None,
+    choices: list[dict] | None = None,
+) -> str:
+    if not state.strip():
+        raise ValueError("state must not be empty")
+    if not question.strip():
+        raise ValueError("question must not be empty")
+    if not choice.strip():
+        raise ValueError("choice must not be empty")
+
+    menu = choices or [{"choice": choice, "criteria": criteria}]
+    parts = [f"<state>\n{state.strip()}", f"<question>\n{question.strip()}"]
+    if guidance and guidance.strip():
+        parts.append(f"<guidance>\n{guidance.strip()}")
+    parts.append(_choices_block(menu))
+    parts.append(f"<choice>\n{choice.strip()}")
+    return "\n".join(parts)
+
+
+def _choices_block(choices: list[dict]) -> str:
+    lines = ["<choices>"]
+    for item in choices:
+        name = str(item.get("choice") or "").strip()
+        if not name:
+            continue
+        criterion = item.get("criteria")
+        if criterion is not None and str(criterion).strip():
+            lines.append(f"- {name}: {str(criterion).strip()}")
+        else:
+            lines.append(f"- {name}")
+    if len(lines) == 1:
+        raise ValueError("choices must include at least one choice")
+    return "\n".join(lines)
+
+
+def humanize_label(label: str) -> str:
+    return label.replace("_", " ").replace("?", "").strip()

theclassifier/schema.py

@@ -0,0 +1,30 @@
+"""Input validation shared by inference, serving and training."""
+def normalize(state, questions):
+    if not isinstance(state, str) or not state.strip():
+        raise ValueError("state must be a non-empty string")
+    if not isinstance(questions, list) or not questions:
+        raise ValueError("questions must be a non-empty list")
+    normalized = []
+    for question in questions:
+        if not isinstance(question, dict) or not isinstance(question.get("question"), str) or not question["question"].strip():
+            raise ValueError("each question needs a non-empty question string")
+        raw = question.get("choices")
+        if not isinstance(raw, list) or not raw:
+            raise ValueError("each question needs at least one choice")
+        choices = []
+        for choice in raw:
+            if isinstance(choice, str):
+                choice = {"choice": choice}
+            if not isinstance(choice, dict) or not isinstance(choice.get("choice"), str) or not choice["choice"].strip():
+                raise ValueError("choices must be non-empty strings or objects with a choice string")
+            criteria = choice.get("criteria")
+            if criteria is not None and not isinstance(criteria, str):
+                raise ValueError("criteria must be a string")
+            choices.append({"choice": choice["choice"].strip(), "criteria": criteria})
+        if len({c["choice"] for c in choices}) != len(choices):
+            raise ValueError("choice names must be unique within each question")
+        guidance = question.get("guidance")
+        if guidance is not None and not isinstance(guidance, str):
+            raise ValueError("guidance must be a string")
+        normalized.append({"question": question["question"].strip(), "choices": choices, "guidance": guidance})
+    return normalized

theclassifier/server.py

@@ -0,0 +1,33 @@
+"""Standalone inference server; deliberately separate from hosted billing."""
+import hmac
+from typing import Any
+from fastapi import FastAPI, Header, HTTPException
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class ClassifyRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    state: str
+    questions: list[dict[str, Any]] = Field(min_length=1)
+    version: str | None = None
+
+
+def create_app(classifier, *, api_key=None):
+    app = FastAPI(title="The Classifier", version="0.1.0")
+
+    @app.get("/health")
+    def health():
+        return {"status": "ok"}
+
+    @app.post("/v1/classify")
+    def classify(body: ClassifyRequest, authorization: str | None = Header(default=None)):
+        if api_key and not hmac.compare_digest(authorization or "", f"Bearer {api_key}"):
+            raise HTTPException(status_code=401, detail="Invalid API key")
+        try:
+            return classifier.classify(body.state, body.questions, version=body.version)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        except (FileNotFoundError, OSError) as exc:
+            raise HTTPException(status_code=503, detail="Requested checkpoint is unavailable") from exc
+
+    return app

theclassifier/training.py

@@ -0,0 +1,120 @@
+"""Fine-tune LoRA adapters and a scalar head using menu cross-entropy."""
+import json
+import random
+from pathlib import Path
+import torch
+from transformers import AutoModel, AutoTokenizer
+from peft import LoraConfig, TaskType, get_peft_model, PeftModel
+from safetensors.torch import save_file
+from .model import Scorer, select_device, select_dtype, load_head
+from .checkpoints import resolve_checkpoint, checkpoint_model
+from .schema import normalize
+from .prompt import pack_example
+
+
+def read_examples(source):
+    if isinstance(source, (str, Path)):
+        with Path(source).open() as handle:
+            source = [json.loads(line) for line in handle if line.strip()]
+    examples = []
+    for index, row in enumerate(source):
+        if not isinstance(row, dict):
+            raise ValueError(f"Example {index}: expected an object")
+        state = row.get("state")
+        item = normalize(state, [{"question": row.get("question"), "choices": row.get("choices"), "guidance": row.get("guidance")}])[0]
+        answer = row.get("answer")
+        names = [c["choice"] for c in item["choices"]]
+        if len(names) < 2 or answer not in names:
+            raise ValueError(f"Example {index}: at least two choices and an answer matching one choice are required")
+        examples.append((state, item, names.index(answer)))
+    if not examples:
+        raise ValueError("Training data is empty")
+    return examples
+
+
+def finetune(data, output_dir, *, checkpoint=None, version=None, model_repo=None, cache_dir=None,
+             revision="main", offline=False, base_model="Qwen/Qwen3-1.7B-Base", device="auto",
+             epochs=1, learning_rate=2e-4, rank=16, alpha=16, dropout=0.05,
+             max_length=2048, grad_accum=16, seed=7, max_steps=None):
+    """Start fresh from a base model, or continue an adapter with checkpoint/version.
+
+    Data is JSONL or an iterable of {state, question, choices, answer} records.
+    Continuation starts a new optimizer; this is not exact optimizer-state resume.
+    """
+    if epochs < 1 or grad_accum < 1 or rank < 1 or alpha < 1 or learning_rate <= 0 or not 0 <= dropout < 1 or max_length < 2 or (max_steps is not None and max_steps < 1):
+        raise ValueError("Invalid training hyperparameters")
+    examples = read_examples(data)
+    output = Path(output_dir)
+    if output.exists() and any(output.iterdir()):
+        raise ValueError("output_dir must be empty; existing checkpoints are never overwritten")
+    torch.manual_seed(seed)
+    rng = random.Random(seed)
+    device = select_device(device)
+    initial = None
+    if checkpoint is not None or version is not None:
+        initial = resolve_checkpoint(version or "general", checkpoint=checkpoint, model_repo=model_repo,
+                                     cache_dir=cache_dir, revision=revision, offline=offline)
+        base_model = checkpoint_model(initial)
+    tokenizer = AutoTokenizer.from_pretrained(initial / "tokenizer" if initial else base_model, cache_dir=cache_dir, local_files_only=offline, trust_remote_code=False)
+    if tokenizer.pad_token_id is None:
+        if tokenizer.eos_token_id is None:
+            raise ValueError("Tokenizer needs an EOS or pad token")
+        tokenizer.pad_token = tokenizer.eos_token
+    tokenizer.padding_side = "right"
+    encoder = AutoModel.from_pretrained(base_model, dtype=select_dtype(device), attn_implementation="sdpa", cache_dir=cache_dir, local_files_only=offline, trust_remote_code=False)
+    if initial:
+        encoder = PeftModel.from_pretrained(encoder, initial / "adapter", is_trainable=True, local_files_only=True)
+    else:
+        config = LoraConfig(task_type=TaskType.FEATURE_EXTRACTION, r=rank, lora_alpha=alpha,
+                            lora_dropout=dropout, bias="none", target_modules=["q_proj", "v_proj"])
+        encoder = get_peft_model(encoder, config)
+    encoder.config.use_cache = False
+    encoder.gradient_checkpointing_enable(gradient_checkpointing_kwargs={"use_reentrant": False})
+    model = Scorer(encoder).to(device)
+    if initial:
+        model.head.load_state_dict(load_head(initial))
+    model.train()
+    parameters = [p for p in model.parameters() if p.requires_grad]
+    optimizer = torch.optim.AdamW(parameters, lr=learning_rate)
+    optimizer.zero_grad(set_to_none=True)
+    step, losses = 0, []
+    for epoch in range(epochs):
+        rng.shuffle(examples)
+        for offset in range(0, len(examples), grad_accum):
+            window = examples[offset:offset+grad_accum]
+            window_loss = 0.0
+            for state, item, target in window:
+                # Evaluate a whole choice menu together, preserving relative scores.
+                rows = []
+                for choice in item["choices"]:
+                    text = pack_example(state, item["question"], choice["choice"], item["guidance"], choice["criteria"], item["choices"])
+                    ids = tokenizer.encode(text, add_special_tokens=True)
+                    if len(ids) > max_length:
+                        ids = ids[:1] + ids[-(max_length-1):]
+                    rows.append({"input_ids": ids, "attention_mask": [1]*len(ids)})
+                batch = tokenizer.pad(rows, padding=True, return_tensors="pt").to(device)
+                logits = model(batch["input_ids"], batch["attention_mask"])
+                loss = torch.nn.functional.cross_entropy(logits.unsqueeze(0), torch.tensor([target], device=device))
+                (loss / len(window)).backward()
+                window_loss += float(loss.detach()) / len(window)
+            torch.nn.utils.clip_grad_norm_(parameters, 1.0)
+            optimizer.step()
+            optimizer.zero_grad(set_to_none=True)
+            step += 1
+            losses.append(window_loss)
+            if max_steps is not None and step >= max_steps:
+                break
+        if max_steps is not None and step >= max_steps:
+            break
+    output.mkdir(parents=True, exist_ok=True)
+    model.encoder.save_pretrained(output / "adapter", safe_serialization=True, save_embedding_layers=False)
+    tokenizer.save_pretrained(output / "tokenizer")
+    save_file({k:v.detach().cpu().contiguous() for k,v in model.head.state_dict().items()}, str(output / "head.safetensors"))
+    report = dict(base_model=base_model, steps=step, examples=len(examples), losses=losses, device=str(device),
+                  seed=seed, epochs=epochs, max_length=max_length, learning_rate=learning_rate,
+                  grad_accum=grad_accum, trainable_parameters=sum(p.numel() for p in parameters),
+                  initial_checkpoint=str(initial) if initial else None, objective="menu_cross_entropy",
+                  optimizer="AdamW", scheduler="constant", lora=model.encoder.peft_config["default"].to_dict())
+    (output / "training.json").write_text(json.dumps(report, indent=2, default=str)+"\n")
+    (output / "classifier.json").write_text(json.dumps({"max_length": max_length, "base_model": base_model})+"\n")
+    return report

theclassifier-0.1.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: theclassifier
+Version: 0.1.0
+Summary: Natural language classification on CPU and GPU, with domain adapters and LoRA fine-tuning
+Author: TrueState
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://theclassifier.ai
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch<3,>=2.6
+Requires-Dist: transformers<6,>=4.56
+Requires-Dist: peft<1,>=0.17
+Requires-Dist: accelerate<2,>=1
+Requires-Dist: huggingface-hub<2,>=0.34
+Requires-Dist: safetensors>=0.5
+Provides-Extra: serve
+Requires-Dist: fastapi<1,>=0.115; extra == "serve"
+Requires-Dist: uvicorn<1,>=0.30; extra == "serve"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# The Classifier
+
+A general-purpose natural language classifier with domain-specific LoRA adapters.
+Run locally on CPU or NVIDIA GPU, serve the same `/v1/classify` request format as
+the hosted service, or fine-tune an adapter on your own labelled examples.
+
+## Release status
+
+This is the initial 0.1.0 package. The configured model repository is
+`TrueState/theclassifier`. The checkpoints are staged privately; authenticate with
+Hugging Face and obtain repository access before using named-version downloads.
+A local checkpoint also works.
+Model weights are not included in the Python package. This code is Apache-2.0;
+checkpoint and dataset licences are separate.
+
+## Install
+
+From this checkout, until the PyPI release is published:
+
+```sh
+pip install './python[serve]'
+```
+
+After release:
+
+```sh
+pip install 'theclassifier[serve]'
+```
+
+Python 3.10+ is required. Install a PyTorch build suitable for your platform first
+if needed; CUDA support depends on that build and your NVIDIA driver. CPU uses
+float32; CUDA uses bfloat16 when supported, otherwise float32. No FlashAttention
+extension is required. `auto` selects CUDA when available and CPU otherwise.
+Apple MPS is not currently supported.
+
+## Classify locally
+
+```python
+from theclassifier import Classifier
+
+classifier = Classifier()  # general; downloads once, then uses the local cache
+result = classifier.classify(
+    'Please close my account.',
+    choices=['billing', 'cancellation', 'none'],
+    question='What is the customer asking for?',
+)
+print(result['results'][0]['selected'])
+```
+
+Use `Classifier(checkpoint='./checkpoints/general', device='cpu')` to load an
+existing local checkpoint. A checkpoint contains `adapter/`, `tokenizer/` and
+`head.safetensors` (or the existing `head.pt` format). The pretrained backbone is
+resolved from the adapter configuration. A local adapter can still require a
+backbone download if the backbone is not already cached.
+
+The full question format supports multiple decisions and optional criteria:
+
+```python
+result = classifier.classify(
+    'Please close my account.',
+    questions=[{
+        'question': 'What is the customer asking for?',
+        'choices': [
+            {'choice': 'cancellation', 'criteria': 'Requests to close an account.'},
+            {'choice': 'none', 'criteria': 'None of the other choices apply.'},
+        ],
+    }],
+    version='intent',
+)
+```
+
+Versions: `general`, `intent`, `sentiment`, `triage`, `cause`, `codify`,
+`complaints`, `stars`. Selecting a new version checks the Hugging Face cache,
+downloads missing files, then loads the adapter and its scoring head onto the
+shared backbone. Selection and inference are serialized to keep the adapter and
+head paired. A failed download raises an error; it never silently falls back to
+another model.
+
+```python
+classifier.load_adapter('custom', checkpoint='./checkpoints/my-adapter')
+result = classifier.classify('example', choices=['yes', 'no'], version='custom')
+```
+
+Use `model_repo=`, `revision=` and `cache_dir=` or the
+`THECLASSIFIER_MODEL_REPO` environment variable to override download settings.
+Pin `revision` to a commit for reproducibility. `offline=True` disables network
+loading, including the base model. Pre-download adapters with:
+
+```sh
+theclassifier download --version general
+theclassifier download --version intent
+```
+
+These commands download adapters and tokenizers; initialize the classifier once
+online to cache the backbone as well. The repository layout is
+`<version>/adapter/`, `<version>/tokenizer/`, `<version>/head.safetensors`.
+
+Default maximum input length is 2,048 tokens per candidate; longer inputs retain
+the first token and tail, matching the existing prompt format. Set `max_length`
+explicitly for longer records. `batch_size` controls inference candidate chunks.
+This initial portable runtime uses direct candidate scoring, not shared-prefix
+KV caching. It has not been benchmarked against the optimized production server.
+
+## Serve on CPU or GPU
+
+```sh
+theclassifier serve --checkpoint ./checkpoints/general --device cpu
+# On a CUDA machine:
+API_KEY=your-serving-key theclassifier serve --device cuda --host 0.0.0.0
+```
+
+Default binding is `127.0.0.1:8090`. Binding outside localhost requires `API_KEY`.
+Use one process per GPU; run behind a TLS proxy for remote clients. This standalone
+server provides inference and authentication, not the hosted service's billing,
+quotas or rate limiting. Set resource limits in your deployment.
+
+```sh
+curl http://127.0.0.1:8090/v1/classify \
+  -H 'Content-Type: application/json' \
+  -d '{"state":"Close my account","questions":[{"question":"Intent?","choices":[{"choice":"cancel"},{"choice":"none"}]}]}'
+```
+
+Include `Authorization: Bearer YOUR_KEY` when `API_KEY` is configured.
+Responses contain `results` (with `question`, `selected`, `detailed_results`),
+`version`, `input_tokens` and `latency_ms`.
+
+## Fine-tune with LoRA
+
+Each JSONL line is one complete choice menu, with an exact matching answer label:
+
+```json
+{"state":"Close my account","question":"Intent?","choices":[{"choice":"cancel","criteria":"Requests to close an account"},{"choice":"none"}],"answer":"cancel"}
+```
+
+```sh
+# Continue the general checkpoint to create a specialist:
+theclassifier finetune --version general --data train.jsonl \
+  --output checkpoints/my-adapter --device cuda
+
+# Train an adapter and scoring head from the base model:
+theclassifier finetune --base-model Qwen/Qwen3-1.7B-Base \
+  --data train.jsonl --output checkpoints/from-base --rank 16 --alpha 16
+```
+
+Or in Python:
+
+```python
+from theclassifier import finetune
+
+report = finetune(
+    'train.jsonl', 'checkpoints/my-adapter',
+    checkpoint='checkpoints/general', device='auto', epochs=1,
+    learning_rate=2e-4, grad_accum=16,
+)
+```
+
+Training freezes the backbone, learns LoRA updates to `q_proj` and `v_proj`, and
+trains a float32 scalar head using cross-entropy across each menu. Whole menus
+are processed together, gradients accumulate between menus, and gradient
+checkpointing reduces activation memory. Large choice menus may still require
+smaller input lengths or more memory. CPU training is supported but slow.
+
+New adapters default to rank 16, alpha 16 and dropout 0.05. Continuing an existing
+adapter preserves its LoRA configuration. A new AdamW optimizer is created with
+a constant learning rate; this is fine-tuning, not exact training-state resume.
+The optimizer configuration differs from the original research runs. Output
+folders must be empty. Saved files include the adapter, head, tokenizer,
+`classifier.json` and `training.json`. Keep evaluation data separate and evaluate
+before using a new checkpoint; the training loss is not a quality benchmark.
+
+## Development and release
+
+```sh
+cd python
+pip install -e '.[serve,dev]'
+pytest
+python -m build
+python -m twine check dist/*
+# With PyPI credentials configured locally:
+python -m twine upload dist/*
+```
+
+The tests build a tiny random Qwen model locally: no production weights, private
+data or external inference service is needed. All six tests passed on the NVIDIA
+workstation, including CUDA inference. Real v1.1 checkpoints were also smoke-tested
+on CUDA, and the general model was checked on CPU against the original scoring
+implementation. These checks establish execution compatibility, not accuracy.
+Publishing the package does not upload model weights. See `RELEASE.md` for the
+checkpoint and publication steps.

theclassifier-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+theclassifier/__init__.py,sha256=nRwlemZCjFjR0x9pMzmQP4CmSPRLHht1E8W5kTan9uM,321
+theclassifier/__main__.py,sha256=z3OQolCKD8rUd3pKYp_FISq2VctFhFl1mV-DVnaoNOM,29
+theclassifier/checkpoints.py,sha256=_1YCCfFTdKYKcY_nDvCKjLZdBO4TdxDQnhii4WSwInk,2144
+theclassifier/cli.py,sha256=k2Ok6joUDaw_EQAvMziJhv2g9GO97IY5GEBNBuEMn2w,3173
+theclassifier/model.py,sha256=-P73wjtcSz6j7CW5MOOR2rj1J0JPdJxREluBzyWqlpE,7240
+theclassifier/prompt.py,sha256=NDgd55hHrVLtA7l-tOZIdd9P43xSfb-1Z4KiDa05UMQ,1452
+theclassifier/schema.py,sha256=pFXfyLJnE2KnQwG62fcVjCEp94JzmAt77xAFxHoa-zs,1824
+theclassifier/server.py,sha256=I5WXANV9Mr7TTzj6eK_zmt_Jf2y2u6-0H7yLox6XRuw,1251
+theclassifier/training.py,sha256=naoG47rohHnExTKh-2Xix1pVni-cUYX0Ssfvv3d6Jeg,6950
+theclassifier-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+theclassifier-0.1.0.dist-info/METADATA,sha256=cJjIf8B1L35k7bQgWQt50yffIyEg6w7h1379Yo8aaYw,8270
+theclassifier-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+theclassifier-0.1.0.dist-info/entry_points.txt,sha256=DgP8Qe9vZ3ThSk2GZKG8rn_QClpkZtxUZvVDk_3rwTc,57
+theclassifier-0.1.0.dist-info/top_level.txt,sha256=3Gs26yaCztM7QB4sT0A_4INgG9njDqnsjl9sHDHSXCw,14
+theclassifier-0.1.0.dist-info/RECORD,,

theclassifier-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

theclassifier-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+theclassifier = theclassifier.cli:main

theclassifier-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

theclassifier-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+theclassifier