recruitertriage 0.1.0__tar.gz

recruitertriage-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.gradio/
+flagged/

recruitertriage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mukunda Rao Katta
+
+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.

recruitertriage-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: recruitertriage
+Version: 0.1.0
+Summary: Triage recruiter outreach with a small (<1B) language model. Built for the HuggingFace Build Small Hackathon.
+Project-URL: Homepage, https://github.com/MukundaKatta/recruitertriage
+Project-URL: Source, https://github.com/MukundaKatta/recruitertriage
+Project-URL: Issues, https://github.com/MukundaKatta/recruitertriage/issues
+Author-email: Mukunda Rao Katta <mukunda.vjcs6@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,huggingface,inbox,llm,recruiter,small-models,smollm,triage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: smollm
+Requires-Dist: accelerate>=0.30; extra == 'smollm'
+Requires-Dist: torch>=2.2; extra == 'smollm'
+Requires-Dist: transformers>=4.44; extra == 'smollm'
+Provides-Extra: space
+Requires-Dist: accelerate>=0.30; extra == 'space'
+Requires-Dist: gradio>=4.40; extra == 'space'
+Requires-Dist: torch>=2.2; extra == 'space'
+Requires-Dist: transformers>=4.44; extra == 'space'
+Description-Content-Type: text/markdown
+
+# recruitertriage
+
+Triage recruiter outreach with a small (<1B) language model. Built
+for the [HuggingFace Build Small Hackathon][bs].
+
+[bs]: https://huggingface.co/Build-Small-Hackathon
+
+The default backend is
+[SmolLM2-360M-Instruct](https://huggingface.co/HuggingFaceTB/SmolLM2-360M-Instruct).
+It fits on a free HF Space CPU and still gets useful triage signal.
+You can swap in any callable LM (a fine-tune, Qwen-0.5B, a
+heuristic, anything that maps `prompt -> string`).
+
+## Install
+
+```bash
+pip install recruitertriage              # core only (zero heavy deps)
+pip install "recruitertriage[smollm]"    # + SmolLM2 / transformers
+pip install "recruitertriage[space]"     # + Gradio for the Space UI
+```
+
+Python 3.10+.
+
+## What it does
+
+Each piece of recruiter outreach gets bucketed into one of five labels:
+
+| label        | meaning                                              |
+|--------------|------------------------------------------------------|
+| `interview`  | looks like a real fit, schedule a call               |
+| `needs_info` | interesting but missing role/comp/level              |
+| `reject`     | clearly off (wrong stack, wrong level)               |
+| `spam`       | not a real role (vendor sales, lead-gen, scam)       |
+| `unsure`     | low confidence — falls through to a human            |
+
+Each `Decision` carries a label, a confidence (0..1), a one-line
+reason, an optional suggested reply, and the raw signals the model
+saw.
+
+## Usage
+
+```python
+from recruitertriage import triage, HeuristicLLM
+
+# Zero-dep fallback (good for tests/CI):
+d = triage(
+    subject="Staff ML Engineer @ AcmeAI",
+    body="Hi - we're hiring a Staff ML Engineer. Comp 250-320k...",
+    llm=HeuristicLLM(),
+)
+print(d.label, d.confidence, d.suggested_reply)
+
+# Real small-model backend (requires the `smollm` extra):
+from recruitertriage.smollm import make_smollm
+llm = make_smollm("HuggingFaceTB/SmolLM2-360M-Instruct")
+d = triage(subject="...", body="...", llm=llm)
+```
+
+`triage()` only cares that `llm` is `Callable[[str], str]`, so any
+small instruction-tuned LM works. The core parser is tolerant of
+small-model JSON quirks (code fences, prose around the object, etc.).
+
+## HuggingFace Space
+
+The `space/` directory is the deployable Gradio app:
+
+```bash
+pip install "recruitertriage[space]"
+python space/app.py
+```
+
+To publish:
+
+1. `hf login`
+2. Create a new Gradio Space (CPU basic is enough)
+3. Push the contents of `space/` as the Space root
+
+## Demo
+
+```bash
+python examples/demo.py             # uses HeuristicLLM
+python examples/demo.py --smollm    # uses SmolLM2-360M-Instruct
+```
+
+## Companion libraries
+
+`recruitertriage` slots into the @mukundakatta agent-stack:
+
+- [agentleash](https://github.com/MukundaKatta/agentleash) — USD/call budget cap + tool-arg gate
+- [birddog](https://github.com/MukundaKatta/birddog) — audited Bright Data egress for scraping agents
+- [agentvet](https://github.com/MukundaKatta/agentvet) — tool-arg validation with retry hints
+- [agentsnap](https://github.com/MukundaKatta/agentsnap) — snapshot tests for agent traces
+
+## License
+
+MIT

recruitertriage-0.1.0/README.md

@@ -0,0 +1,96 @@
+# recruitertriage
+
+Triage recruiter outreach with a small (<1B) language model. Built
+for the [HuggingFace Build Small Hackathon][bs].
+
+[bs]: https://huggingface.co/Build-Small-Hackathon
+
+The default backend is
+[SmolLM2-360M-Instruct](https://huggingface.co/HuggingFaceTB/SmolLM2-360M-Instruct).
+It fits on a free HF Space CPU and still gets useful triage signal.
+You can swap in any callable LM (a fine-tune, Qwen-0.5B, a
+heuristic, anything that maps `prompt -> string`).
+
+## Install
+
+```bash
+pip install recruitertriage              # core only (zero heavy deps)
+pip install "recruitertriage[smollm]"    # + SmolLM2 / transformers
+pip install "recruitertriage[space]"     # + Gradio for the Space UI
+```
+
+Python 3.10+.
+
+## What it does
+
+Each piece of recruiter outreach gets bucketed into one of five labels:
+
+| label        | meaning                                              |
+|--------------|------------------------------------------------------|
+| `interview`  | looks like a real fit, schedule a call               |
+| `needs_info` | interesting but missing role/comp/level              |
+| `reject`     | clearly off (wrong stack, wrong level)               |
+| `spam`       | not a real role (vendor sales, lead-gen, scam)       |
+| `unsure`     | low confidence — falls through to a human            |
+
+Each `Decision` carries a label, a confidence (0..1), a one-line
+reason, an optional suggested reply, and the raw signals the model
+saw.
+
+## Usage
+
+```python
+from recruitertriage import triage, HeuristicLLM
+
+# Zero-dep fallback (good for tests/CI):
+d = triage(
+    subject="Staff ML Engineer @ AcmeAI",
+    body="Hi - we're hiring a Staff ML Engineer. Comp 250-320k...",
+    llm=HeuristicLLM(),
+)
+print(d.label, d.confidence, d.suggested_reply)
+
+# Real small-model backend (requires the `smollm` extra):
+from recruitertriage.smollm import make_smollm
+llm = make_smollm("HuggingFaceTB/SmolLM2-360M-Instruct")
+d = triage(subject="...", body="...", llm=llm)
+```
+
+`triage()` only cares that `llm` is `Callable[[str], str]`, so any
+small instruction-tuned LM works. The core parser is tolerant of
+small-model JSON quirks (code fences, prose around the object, etc.).
+
+## HuggingFace Space
+
+The `space/` directory is the deployable Gradio app:
+
+```bash
+pip install "recruitertriage[space]"
+python space/app.py
+```
+
+To publish:
+
+1. `hf login`
+2. Create a new Gradio Space (CPU basic is enough)
+3. Push the contents of `space/` as the Space root
+
+## Demo
+
+```bash
+python examples/demo.py             # uses HeuristicLLM
+python examples/demo.py --smollm    # uses SmolLM2-360M-Instruct
+```
+
+## Companion libraries
+
+`recruitertriage` slots into the @mukundakatta agent-stack:
+
+- [agentleash](https://github.com/MukundaKatta/agentleash) — USD/call budget cap + tool-arg gate
+- [birddog](https://github.com/MukundaKatta/birddog) — audited Bright Data egress for scraping agents
+- [agentvet](https://github.com/MukundaKatta/agentvet) — tool-arg validation with retry hints
+- [agentsnap](https://github.com/MukundaKatta/agentsnap) — snapshot tests for agent traces
+
+## License
+
+MIT

recruitertriage-0.1.0/examples/demo.py

@@ -0,0 +1,72 @@
+"""Run recruitertriage against a handful of canned emails.
+
+By default uses the zero-dep HeuristicLLM so this script works in CI
+and on machines without transformers/torch installed.
+
+Pass --smollm to use SmolLM2-360M-Instruct (requires
+`pip install "recruitertriage[smollm]"`).
+
+    python examples/demo.py
+    python examples/demo.py --smollm
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from recruitertriage import HeuristicLLM, triage
+
+
+SAMPLES = [
+    (
+        "Staff ML Engineer @ AcmeAI",
+        "Hi Mukunda - we're hiring a Staff ML Engineer to lead agents. "
+        "Comp band 250-320k base + equity. Remote PT/PST friendly. "
+        "Are you open to a 15-min chat next week?",
+    ),
+    (
+        "Java backend role",
+        "Hello, we are sourcing for a Java backend developer at a "
+        "Fortune 100 bank. Onsite Charlotte. Interested?",
+    ),
+    (
+        "Lead gen partnership",
+        "Hi, our agency can send you 50 verified candidate emails per week. "
+        "Buy emails, save time. Reply YES for pricing.",
+    ),
+    (
+        "Quick chat",
+        "Hey - saw your GitHub. Could you send your resume if you're "
+        "open to a chat? Let me know if interested!",
+    ),
+]
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--smollm", action="store_true",
+                    help="Use SmolLM2-360M-Instruct (heavy import).")
+    args = ap.parse_args()
+
+    if args.smollm:
+        from recruitertriage.smollm import make_smollm
+        llm = make_smollm()
+        backend = "SmolLM2-360M-Instruct"
+    else:
+        llm = HeuristicLLM()
+        backend = "HeuristicLLM (zero-dep fallback)"
+
+    print(f"backend: {backend}\n")
+
+    for i, (subj, body) in enumerate(SAMPLES, 1):
+        d = triage(subject=subj, body=body, llm=llm)
+        print(f"[{i}] {subj}")
+        print(f"    label={d.label.value:<11} conf={d.confidence:.2f}  reason={d.reason}")
+        if d.suggested_reply:
+            print(f"    reply: {d.suggested_reply}")
+        print()
+
+
+if __name__ == "__main__":
+    main()

recruitertriage-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "recruitertriage"
+version = "0.1.0"
+description = "Triage recruiter outreach with a small (<1B) language model. Built for the HuggingFace Build Small Hackathon."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Mukunda Rao Katta", email = "mukunda.vjcs6@gmail.com" }]
+keywords = [
+  "ai",
+  "llm",
+  "small-models",
+  "huggingface",
+  "smollm",
+  "recruiter",
+  "inbox",
+  "triage",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+# Core lib has NO heavy deps; you bring your own callable LM.
+# The HF model integration lives in the [smollm] extra.
+dependencies = []
+
+[project.optional-dependencies]
+smollm = ["transformers>=4.44", "torch>=2.2", "accelerate>=0.30"]
+space  = ["gradio>=4.40", "transformers>=4.44", "torch>=2.2", "accelerate>=0.30"]
+dev    = ["pytest>=8.0", "ruff>=0.4"]
+
+[project.urls]
+Homepage = "https://github.com/MukundaKatta/recruitertriage"
+Source   = "https://github.com/MukundaKatta/recruitertriage"
+Issues   = "https://github.com/MukundaKatta/recruitertriage/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/recruitertriage"]

recruitertriage-0.1.0/space/app.py

@@ -0,0 +1,118 @@
+"""Gradio Space for recruitertriage on HuggingFace.
+
+Built for the HuggingFace Build Small Hackathon. Uses
+HuggingFaceTB/SmolLM2-360M-Instruct (under 1B params) as the underlying
+language model. Fits on a free CPU Space.
+
+To deploy:
+
+    1. `huggingface-cli login` (or use `hf` CLI)
+    2. Create a new Space (Gradio SDK, CPU basic)
+    3. Push this `space/` directory as the Space root.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+# Make the local src/ importable when running the Space directly from
+# this directory (the published Space pins recruitertriage as a normal
+# pip dep via requirements.txt instead).
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_SRC = os.path.normpath(os.path.join(_HERE, "..", "src"))
+if os.path.isdir(_SRC) and _SRC not in sys.path:
+    sys.path.insert(0, _SRC)
+
+import gradio as gr
+
+from recruitertriage import HeuristicLLM, triage
+
+
+# Lazily build the SmolLM2 model so the Space starts fast and only
+# pays the model-load cost on first request.
+_smollm_cache = {"fn": None}
+
+
+def _get_llm(backend: str):
+    if backend == "heuristic":
+        return HeuristicLLM()
+    if _smollm_cache["fn"] is None:
+        from recruitertriage.smollm import make_smollm
+        _smollm_cache["fn"] = make_smollm()
+    return _smollm_cache["fn"]
+
+
+LABEL_EMOJI = {
+    "interview": "yes",
+    "needs_info": "ask",
+    "reject": "no",
+    "spam": "block",
+    "unsure": "shrug",
+}
+
+
+def _do_triage(subject: str, body: str, backend: str):
+    if not subject.strip() and not body.strip():
+        return "Paste a recruiter email above.", "", ""
+
+    llm = _get_llm(backend)
+    d = triage(subject=subject, body=body, llm=llm)
+    badge = f"{LABEL_EMOJI.get(d.label.value, '?')} {d.label.value} ({d.confidence:.0%})"
+    detail = f"**Reason:** {d.reason}\n\n**Signals:** {json.dumps(d.signals)}"
+    reply = d.suggested_reply or "_(no suggested reply)_"
+    return badge, detail, reply
+
+
+SAMPLES = [
+    [
+        "Staff ML Engineer @ AcmeAI",
+        "Hi - we're hiring a Staff ML Engineer to lead agents. "
+        "Comp band 250-320k base + equity. Remote PT/PST friendly. "
+        "Are you open to a 15-min chat next week?",
+    ],
+    [
+        "Quick question",
+        "Hey, would you be open to a chat? Send your resume if "
+        "interested!",
+    ],
+    [
+        "Lead gen partnership",
+        "Hi, our agency can send you 50 verified candidate emails per "
+        "week. Buy emails, save time. Reply YES for pricing.",
+    ],
+]
+
+
+with gr.Blocks(title="recruitertriage", theme="soft") as demo:
+    gr.Markdown(
+        "# recruitertriage\n"
+        "Triage recruiter outreach with a small (<1B) language model. "
+        "Built for the HuggingFace Build Small Hackathon. "
+        "Backed by [SmolLM2-360M-Instruct]"
+        "(https://huggingface.co/HuggingFaceTB/SmolLM2-360M-Instruct)."
+    )
+
+    with gr.Row():
+        with gr.Column():
+            subject = gr.Textbox(label="Subject", lines=1)
+            body = gr.Textbox(label="Body", lines=10)
+            backend = gr.Radio(
+                ["smollm", "heuristic"],
+                value="smollm",
+                label="Backend",
+                info="smollm = SmolLM2-360M-Instruct.  heuristic = zero-dep keyword fallback (instant).",
+            )
+            run = gr.Button("Triage", variant="primary")
+        with gr.Column():
+            label = gr.Markdown(label="Decision")
+            detail = gr.Markdown(label="Detail")
+            reply = gr.Textbox(label="Suggested reply", lines=4)
+
+    run.click(_do_triage, [subject, body, backend], [label, detail, reply])
+    gr.Examples(examples=SAMPLES, inputs=[subject, body])
+
+
+if __name__ == "__main__":
+    demo.launch()

recruitertriage-0.1.0/space/requirements.txt

@@ -0,0 +1,5 @@
+recruitertriage>=0.1.0
+gradio>=4.40
+transformers>=4.44
+torch>=2.2
+accelerate>=0.30

recruitertriage-0.1.0/src/recruitertriage/__init__.py

@@ -0,0 +1,41 @@
+"""recruitertriage - triage recruiter outreach with a small (<1B) LM.
+
+A tiny, dependency-light core. Bring your own callable language model
+(SmolLM2, Qwen-0.5B, your own fine-tune, or even a heuristic).
+
+Example:
+
+    from recruitertriage import triage, Decision
+
+    def my_llm(prompt: str) -> str:
+        # call SmolLM2-360M, return raw text
+        ...
+
+    result: Decision = triage(
+        subject="Senior ML role at Acme",
+        body="Hi! Are you open to a quick chat about a Senior MLE role...",
+        llm=my_llm,
+    )
+    print(result.label, result.confidence, result.reason)
+
+For the HuggingFace Build Small Hackathon entry, see `space/app.py`
+for a Gradio UI bundled with SmolLM2-360M-Instruct.
+"""
+
+from __future__ import annotations
+
+from .core import (
+    Decision,
+    HeuristicLLM,
+    Label,
+    triage,
+)
+
+__all__ = [
+    "Decision",
+    "HeuristicLLM",
+    "Label",
+    "triage",
+]
+
+__version__ = "0.1.0"

recruitertriage-0.1.0/src/recruitertriage/core.py

@@ -0,0 +1,253 @@
+"""Core triage logic. No heavy deps — bring your own LM."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable, Iterable
+
+
+# ---- decision shape -------------------------------------------------------
+
+
+class Label(str, Enum):
+    """Five buckets a recruiter outreach can fall into.
+
+    `interview`  - looks like a strong fit, schedule a call
+    `needs_info` - interesting but missing key details (role, comp, location)
+    `reject`     - clearly off (wrong stack, mass blast, sketchy)
+    `spam`       - not a real role / vendor pitch / sales
+    `unsure`     - the model couldn't decide; fall through to human
+    """
+
+    interview = "interview"
+    needs_info = "needs_info"
+    reject = "reject"
+    spam = "spam"
+    unsure = "unsure"
+
+
+@dataclass
+class Decision:
+    label: Label
+    confidence: float  # 0..1
+    reason: str
+    suggested_reply: str | None = None
+    signals: dict[str, object] = field(default_factory=dict)
+
+
+LLM = Callable[[str], str]
+"""A callable language model: takes a prompt string, returns raw text."""
+
+
+# ---- prompt ---------------------------------------------------------------
+
+
+_SYSTEM = (
+    "You triage recruiter outreach. Pick exactly one label from: "
+    "interview, needs_info, reject, spam, unsure. "
+    "Return JSON ONLY with keys: label, confidence (0..1), reason (one short line), "
+    "suggested_reply (1-3 sentences, plain, no AI phrases). "
+    "If the email is vendor sales, pitch, or unrelated to a job role, return spam. "
+    "If it lacks role title or comp range AND looks legit, return needs_info. "
+    "If the stack/level is clearly wrong, return reject. "
+    "If it looks like a real job match, return interview."
+)
+
+
+def _build_prompt(subject: str, body: str, hints: dict[str, object] | None) -> str:
+    hints_block = ""
+    if hints:
+        hints_block = "\n\nUser hints:\n" + "\n".join(
+            f"- {k}: {v}" for k, v in hints.items()
+        )
+    return (
+        f"{_SYSTEM}\n\n"
+        f"Subject: {subject}\n\n"
+        f"Body:\n{body}{hints_block}\n\n"
+        f"JSON:"
+    )
+
+
+# ---- parsing --------------------------------------------------------------
+
+
+_JSON_RE = re.compile(r"\{.*?\}", re.DOTALL)
+
+
+def _parse_llm_json(raw: str) -> dict | None:
+    """Pull the first JSON object out of a model's free-form text.
+
+    Small models love to wrap things in prose, code fences, or extra
+    commentary. Find the first {...} block and try to parse it."""
+    # try whole-string first (well-behaved model)
+    raw = raw.strip()
+    try:
+        return json.loads(raw)
+    except Exception:
+        pass
+    m = _JSON_RE.search(raw)
+    if not m:
+        return None
+    try:
+        return json.loads(m.group(0))
+    except Exception:
+        return None
+
+
+def _coerce_decision(obj: dict | None) -> Decision:
+    if not isinstance(obj, dict):
+        return Decision(Label.unsure, 0.0, "model output unparseable")
+
+    label_raw = str(obj.get("label", "")).strip().lower()
+    try:
+        label = Label(label_raw)
+    except ValueError:
+        label = Label.unsure
+
+    try:
+        conf = float(obj.get("confidence", 0.0))
+    except (TypeError, ValueError):
+        conf = 0.0
+    conf = max(0.0, min(1.0, conf))
+
+    reason = str(obj.get("reason", "")).strip() or "no reason"
+    reply = obj.get("suggested_reply")
+    if reply is not None:
+        reply = str(reply).strip() or None
+
+    return Decision(label, conf, reason, suggested_reply=reply)
+
+
+# ---- public entry ---------------------------------------------------------
+
+
+def triage(
+    *,
+    subject: str,
+    body: str,
+    llm: LLM,
+    hints: dict[str, object] | None = None,
+) -> Decision:
+    """Triage one piece of recruiter outreach.
+
+    Pass any callable that maps prompt-string -> raw-string output.
+    Small models (SmolLM2, Qwen-0.5B, etc.) are the target."""
+    prompt = _build_prompt(subject=subject, body=body, hints=hints)
+    raw = llm(prompt)
+    parsed = _parse_llm_json(raw)
+    decision = _coerce_decision(parsed)
+    decision.signals["prompt_chars"] = len(prompt)
+    decision.signals["raw_chars"] = len(raw)
+    return decision
+
+
+# ---- offline / heuristic fallback LM --------------------------------------
+
+
+_INTERVIEW_HINTS = (
+    "principal",
+    "staff",
+    "senior",
+    "lead",
+    "ml engineer",
+    "machine learning",
+    "ai engineer",
+    "applied scientist",
+    "research engineer",
+)
+
+_REJECT_HINTS = (
+    "java",
+    ".net",
+    "salesforce admin",
+    "qa manual",
+    "support engineer",
+    "tier 1 support",
+)
+
+_SPAM_HINTS = (
+    "purchase order",
+    "lead gen",
+    "we have leads",
+    "guaranteed candidates",
+    "buy emails",
+    "outsource your hiring",
+    "verified bitcoin",
+    "crypto investment",
+)
+
+_INFO_HINTS = (
+    "more info",
+    "let me know if interested",
+    "send your resume",
+    "open to a chat",
+)
+
+
+class HeuristicLLM:
+    """Zero-dep fallback 'model'. Pattern-matches on keywords and emits
+    a JSON-shaped string so the core pipeline still works without
+    transformers/torch installed. Good for tests, CI, and offline demos.
+
+    Don't ship this to prod. Plug in SmolLM2 or similar for real runs."""
+
+    def __call__(self, prompt: str) -> str:
+        body = prompt.lower()
+
+        if any(s in body for s in _SPAM_HINTS):
+            return json.dumps({
+                "label": "spam",
+                "confidence": 0.85,
+                "reason": "matched spam keyword",
+                "suggested_reply": None,
+            })
+        if any(s in body for s in _REJECT_HINTS):
+            return json.dumps({
+                "label": "reject",
+                "confidence": 0.78,
+                "reason": "stack/level mismatch",
+                "suggested_reply": (
+                    "Thanks for reaching out. Not the right fit for me right now."
+                ),
+            })
+        if any(s in body for s in _INTERVIEW_HINTS):
+            return json.dumps({
+                "label": "interview",
+                "confidence": 0.72,
+                "reason": "title/level looks like a fit",
+                "suggested_reply": (
+                    "Thanks, this looks interesting. Could you share the role "
+                    "level, comp band, and location?"
+                ),
+            })
+        if any(s in body for s in _INFO_HINTS):
+            return json.dumps({
+                "label": "needs_info",
+                "confidence": 0.6,
+                "reason": "no role title or details given",
+                "suggested_reply": (
+                    "Happy to chat. Could you share the company, role title, "
+                    "and comp band first?"
+                ),
+            })
+        return json.dumps({
+            "label": "unsure",
+            "confidence": 0.3,
+            "reason": "no clear signals",
+        })
+
+
+# ---- batch helpers --------------------------------------------------------
+
+
+def triage_batch(
+    emails: Iterable[tuple[str, str]],
+    *,
+    llm: LLM,
+    hints: dict[str, object] | None = None,
+) -> list[Decision]:
+    """Triage a list of (subject, body) tuples. Pure convenience."""
+    return [triage(subject=s, body=b, llm=llm, hints=hints) for s, b in emails]

recruitertriage-0.1.0/src/recruitertriage/smollm.py

@@ -0,0 +1,76 @@
+"""SmolLM2 (HuggingFaceTB/SmolLM2-360M-Instruct) integration.
+
+Lives behind an extra: `pip install "recruitertriage[smollm]"`.
+
+The default model is small enough to run on a laptop CPU; for the
+HuggingFace Build Small Hackathon we explicitly target sub-1B
+parameter models. Pass any other instruction-tuned causal LM by name."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def make_smollm(
+    model_id: str = "HuggingFaceTB/SmolLM2-360M-Instruct",
+    *,
+    device: str | None = None,
+    max_new_tokens: int = 220,
+    temperature: float = 0.2,
+):
+    """Build a callable LM around a HuggingFace causal model.
+
+    Returns a function `(prompt: str) -> str` that you can pass straight
+    into `recruitertriage.triage(..., llm=...)`."""
+    try:
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+    except Exception as e:  # pragma: no cover - import guard
+        raise RuntimeError(
+            'recruitertriage[smollm] extras are required for SmolLM2. '
+            'Install with: pip install "recruitertriage[smollm]"'
+        ) from e
+
+    if device is None:
+        if torch.cuda.is_available():
+            device = "cuda"
+        elif getattr(torch.backends, "mps", None) and torch.backends.mps.is_available():
+            device = "mps"
+        else:
+            device = "cpu"
+
+    tok = AutoTokenizer.from_pretrained(model_id)
+    model = AutoModelForCausalLM.from_pretrained(model_id).to(device)
+    model.eval()
+
+    def _call(prompt: str) -> str:
+        # SmolLM2-Instruct expects a chat template; the prompt becomes
+        # a single user message. We deliberately keep the system message
+        # baked into `prompt` so callers can swap models without breaking
+        # the template.
+        messages = [{"role": "user", "content": prompt}]
+        rendered = tok.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True
+        )
+        inputs: dict[str, Any] = tok(rendered, return_tensors="pt").to(device)
+        with torch_no_grad():
+            out = model.generate(
+                **inputs,
+                max_new_tokens=max_new_tokens,
+                do_sample=temperature > 0,
+                temperature=temperature,
+                pad_token_id=tok.eos_token_id,
+            )
+        # only decode the newly-generated tokens
+        new = out[0, inputs["input_ids"].shape[1]:]
+        return tok.decode(new, skip_special_tokens=True).strip()
+
+    return _call
+
+
+def torch_no_grad():
+    """Lazy torch.no_grad() so importing this module is cheap when torch
+    isn't installed (the make_smollm call above already imported it)."""
+    import torch  # noqa: PLC0415
+
+    return torch.no_grad()

recruitertriage-0.1.0/tests/test_core.py

@@ -0,0 +1,141 @@
+"""Tests for recruitertriage core triage logic.
+
+These tests don't need transformers/torch — they exercise the
+heuristic LM and the JSON parser directly."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from recruitertriage import Decision, HeuristicLLM, Label, triage
+from recruitertriage.core import _coerce_decision, _parse_llm_json, triage_batch
+
+
+# ---- _parse_llm_json ------------------------------------------------------
+
+
+def test_parse_clean_json():
+    obj = _parse_llm_json('{"label":"interview","confidence":0.8}')
+    assert obj == {"label": "interview", "confidence": 0.8}
+
+
+def test_parse_json_buried_in_prose():
+    raw = 'Sure! Here is the result:\n```json\n{"label":"reject"}\n```\nHope that helps!'
+    obj = _parse_llm_json(raw)
+    assert obj == {"label": "reject"}
+
+
+def test_parse_garbage_returns_none():
+    assert _parse_llm_json("totally not json") is None
+
+
+# ---- _coerce_decision -----------------------------------------------------
+
+
+def test_coerce_unknown_label_falls_back_to_unsure():
+    d = _coerce_decision({"label": "yolo", "confidence": 0.9, "reason": "x"})
+    assert d.label is Label.unsure
+
+
+def test_coerce_clamps_confidence():
+    d = _coerce_decision({"label": "interview", "confidence": 5.0, "reason": "x"})
+    assert d.confidence == 1.0
+    d2 = _coerce_decision({"label": "interview", "confidence": -1.0, "reason": "x"})
+    assert d2.confidence == 0.0
+
+
+def test_coerce_none_returns_unsure():
+    d = _coerce_decision(None)
+    assert d.label is Label.unsure
+    assert d.confidence == 0.0
+
+
+# ---- HeuristicLLM end-to-end ---------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "subject,body,expected",
+    [
+        # spam
+        (
+            "We have leads",
+            "We sell verified bitcoin investment opportunities to your team.",
+            Label.spam,
+        ),
+        # reject (stack mismatch)
+        (
+            "Java backend role at BankCorp",
+            "Hi, we're hiring a Java developer for our trading platform.",
+            Label.reject,
+        ),
+        # interview (clear fit)
+        (
+            "Staff ML Engineer at AcmeAI",
+            "Looking for a Staff ML Engineer to lead our agents team. "
+            "Comp 250-320k base + equity.",
+            Label.interview,
+        ),
+        # needs_info (vague but legit)
+        (
+            "Quick question",
+            "Hey, would you be open to a chat? Send your resume "
+            "if interested!",
+            Label.needs_info,
+        ),
+    ],
+)
+def test_heuristic_llm_round_trip(subject: str, body: str, expected: Label):
+    d = triage(subject=subject, body=body, llm=HeuristicLLM())
+    assert d.label is expected
+    assert 0.0 <= d.confidence <= 1.0
+    assert d.reason
+
+
+def test_unsure_when_no_signals():
+    d = triage(
+        subject="Hello",
+        body="Hi, just saying hi.",
+        llm=HeuristicLLM(),
+    )
+    assert d.label is Label.unsure
+
+
+# ---- BYO-LLM contract -----------------------------------------------------
+
+
+def test_byo_llm_callable_works():
+    def fake_llm(prompt: str) -> str:
+        return json.dumps({
+            "label": "interview",
+            "confidence": 0.91,
+            "reason": "test fixture",
+            "suggested_reply": "thanks, send details",
+        })
+
+    d = triage(subject="hi", body="hi", llm=fake_llm)
+    assert d.label is Label.interview
+    assert d.confidence == pytest.approx(0.91)
+    assert d.suggested_reply == "thanks, send details"
+
+
+def test_signals_captured():
+    d = triage(subject="x", body="y", llm=HeuristicLLM())
+    assert "prompt_chars" in d.signals
+    assert "raw_chars" in d.signals
+    assert isinstance(d.signals["prompt_chars"], int)
+
+
+# ---- batch ---------------------------------------------------------------
+
+
+def test_triage_batch():
+    pairs = [
+        ("Staff MLE role", "Senior Machine Learning Engineer at AcmeAI"),
+        ("Java dev", "We need a Java backend dev"),
+    ]
+    results = triage_batch(pairs, llm=HeuristicLLM())
+    assert len(results) == 2
+    assert results[0].label is Label.interview
+    assert results[1].label is Label.reject