luar 0.2.0__py3-none-any.whl

luar/__init__.py

@@ -0,0 +1,16 @@
+"""LUAR - Local Utility for Automated Reviews."""
+from .engine import DEFAULT_THRESHOLD, Result, classify, run_file
+from .questions import Question, QuestionError, load_questions, parse_questions
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "DEFAULT_THRESHOLD",
+    "Question",
+    "QuestionError",
+    "Result",
+    "classify",
+    "load_questions",
+    "parse_questions",
+    "run_file",
+]

luar/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

luar/app.py

@@ -0,0 +1,256 @@
+"""Web interface (Gradio). Runs on 127.0.0.1 only: files never leave the machine."""
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+import gradio as gr
+import pandas as pd
+
+from .backends.laya_backend import LayaBackend, pick_checkpoint
+from .backends.lmstudio_backend import LMStudioBackend, LMStudioError
+from .engine import DEFAULT_THRESHOLD, EXPECTED_PREFIX, REVIEW_COL, classify, save_result
+from .questions import EXPERIMENTAL_TYPES, QuestionError, dump_questions, load_questions, parse_questions
+from .report import render_summary
+from .tables import read_table
+
+EXAMPLES = Path(__file__).resolve().parents[2] / "examples"
+QUESTION_HEADERS = ["id", "type", "question", "options"]
+PREVIEW_ROWS = 8
+_backends: dict[str, LayaBackend] = {}  # loaded models, reused between runs
+
+INTRO = """
+# 🌙 LUAR
+**Local Utility for Automated Reviews.** Drop a spreadsheet, say what you want to know about each row,
+and get a copy with the answers plus a summary. Everything runs on this computer.
+"""
+
+QUESTION_HELP = """
+**Question types:** `choice` picks one option · `noul` answers yes/no · `score` places the row on an
+ordered scale (*experimental*: the least reliable type in our tests).
+**Options:** separate with `;` and optionally add a description after `:`, e.g.
+`delivery: shipping, delays; product: defects, quality`. Up to 20 options; `noul` takes none.
+Add a column named `expected_<id>` to your file to measure accuracy on rows you already know.
+"""
+
+
+def _questions_to_rows(questions) -> list[list[str]]:
+    rows = []
+    for q in questions:
+        opts = "; ".join(f"{k}: {v}" if v else k for k, v in q.options.items())
+        rows.append([q.id, q.type, q.question, opts])
+    return rows
+
+
+def _rows_to_questions(table) -> list:
+    df = table if isinstance(table, pd.DataFrame) else pd.DataFrame(table, columns=QUESTION_HEADERS)
+    data = []
+    for _, r in df.iterrows():
+        values = ["" if pd.isna(v) else str(v).strip() for v in r.tolist()[:4]]
+        if not any(values):
+            continue
+        qid, qtype, text, opts = values
+        data.append({"id": qid, "type": qtype.lower(), "question": text, "options": opts})
+    return parse_questions(data)
+
+
+def on_file(file):
+    if file is None:
+        return gr.update(choices=[], value=[]), None, "", None
+    try:
+        df, info = read_table(file)
+    except Exception as e:  # unreadable file: tell the user, keep the UI alive
+        raise gr.Error(f"Could not read this file: {e}") from e
+    # expected_* columns hold known answers: never offer them as model input
+    readable = [c for c in df.columns if not str(c).startswith(EXPECTED_PREFIX)]
+    # suggest the column with the longest text on average
+    lengths = {c: df[c].astype(str).str.len().mean() for c in readable}
+    best = max(lengths, key=lengths.get) if lengths else None
+    detail = f"separator `{info.sep}`, {info.encoding}" if info.kind == "csv" else f"sheet `{info.sheet}`"
+    status = f"**{Path(file).name}**: {len(df)} rows, {len(df.columns)} columns ({detail})."
+    return (
+        gr.update(choices=readable, value=[best] if best else []),
+        df.head(PREVIEW_ROWS),
+        status,
+        file,
+    )
+
+
+def on_load_questions(file):
+    if file is None:
+        return gr.update()
+    try:
+        return _questions_to_rows(load_questions(file))
+    except (QuestionError, json.JSONDecodeError) as e:
+        raise gr.Error(str(e)) from e
+
+
+def on_save_questions(table):
+    try:
+        questions = _rows_to_questions(table)
+    except QuestionError as e:
+        raise gr.Error(str(e)) from e
+    path = Path(tempfile.mkdtemp(prefix="luar_")) / "questions.json"
+    path.write_text(dump_questions(questions), encoding="utf-8")
+    return path
+
+
+EXAMPLE_SETS = {
+    "English reviews": ("reviews.csv", "reviews_questions.json"),
+    "English reviews: severity (score)": ("reviews.csv", "reviews_severity_question.json"),
+    "Avaliações em português": ("avaliacoes.csv", "avaliacoes_perguntas.json"),
+}
+
+
+def on_example(name):
+    data, questions = EXAMPLE_SETS[name]
+    rows = _questions_to_rows(load_questions(EXAMPLES / questions))
+    return str(EXAMPLES / data), rows
+
+
+def _backend(checkpoint: str, texts: list[str], questions) -> LayaBackend:
+    resolved = pick_checkpoint(texts, questions) if checkpoint == "auto" else checkpoint
+    if resolved not in _backends:
+        _backends[resolved] = LayaBackend(checkpoint=resolved)
+    backend = _backends[resolved]
+    backend.name = f"laya ({resolved}{', chosen automatically' if checkpoint == 'auto' else ''})"
+    return backend
+
+
+def on_engine(engine):
+    is_laya = engine == "Laya"
+    return gr.update(visible=is_laya), gr.update(visible=not is_laya), gr.update(visible=not is_laya)
+
+
+def on_refresh_models():
+    """List the LLMs LM Studio can serve (loaded or downloaded)."""
+    try:
+        models = LMStudioBackend().list_models()
+    except LMStudioError as e:
+        raise gr.Error(str(e)) from e
+    if not models:
+        raise gr.Error("LM Studio has no model available; load one (e.g. `lms load qwen3.5-4b`).")
+    return gr.update(choices=models, value=models[0])
+
+
+def on_run(file, columns, table, threshold, engine, checkpoint, lms_model, progress=gr.Progress()):
+    if not file:
+        raise gr.Error("Drop a CSV or XLSX file first.")
+    if not columns:
+        raise gr.Error("Choose at least one column to read.")
+    try:
+        questions = _rows_to_questions(table)
+    except QuestionError as e:
+        raise gr.Error(str(e)) from e
+    if any(q.type in EXPERIMENTAL_TYPES for q in questions):
+        gr.Warning("`score` questions are experimental: check those answers by hand.")
+
+    df, info = read_table(file)
+    texts = df[columns].astype(str).agg(" ".join, axis=1).tolist()
+    if engine == "Laya":
+        progress(0, desc="Loading the model (the first run downloads it)…")
+        backend = _backend(checkpoint, texts, questions)
+    else:
+        progress(0, desc="Asking LM Studio…")
+        backend = LMStudioBackend(model=lms_model or None)
+    try:
+        result = classify(
+            df, columns, questions, backend, threshold,
+            progress=lambda done, total: progress(done / total, desc=f"{done}/{total} rows"),
+        )
+    except (ValueError, LMStudioError) as e:
+        raise gr.Error(str(e)) from e
+    # uploads live in a temp folder; write the outputs to a fresh one
+    save_result(result, info, out_dir=tempfile.mkdtemp(prefix="luar_"))
+    flagged = (result.table[REVIEW_COL] == "yes").sum()
+    gr.Info(f"Done: {len(result.table)} rows, {flagged} to review.")
+    return result.table, render_summary(result), [str(result.table_path), str(result.summary_path)]
+
+
+def build() -> gr.Blocks:
+    with gr.Blocks(title="LUAR") as demo:
+        gr.Markdown(INTRO)
+        source = gr.State()
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("### 1. Spreadsheet")
+                upload = gr.File(label="CSV or XLSX", file_types=[".csv", ".xlsx", ".xlsm", ".txt"])
+                status = gr.Markdown()
+                columns = gr.CheckboxGroup(label="Column(s) the model should read", choices=[])
+                example = gr.Dropdown(
+                    list(EXAMPLE_SETS), label="…or try an example", value=None,
+                    visible=EXAMPLES.exists(),  # examples ship with the repo, not the wheel
+                )
+            with gr.Column(scale=2):
+                gr.Markdown("### Preview")
+                preview = gr.Dataframe(interactive=False, max_height=260, wrap=True)
+
+        gr.Markdown("### 2. What do you want to know about each row?")
+        questions = gr.Dataframe(
+            headers=QUESTION_HEADERS,
+            datatype=["str", "str", "str", "str"],
+            value=[["", "choice", "", ""]],
+            interactive=True,
+            row_count=(1, "dynamic"),
+            column_count=(4, "fixed"),
+            wrap=True,
+            column_widths=["12%", "10%", "38%", "40%"],
+        )
+        gr.Markdown(QUESTION_HELP)
+        with gr.Row():
+            q_upload = gr.File(label="Load questions (.json)", file_types=[".json"], scale=1)
+            q_save = gr.Button("Save questions as .json", scale=0)
+            q_file = gr.File(label="Questions file", interactive=False, scale=1)
+
+        gr.Markdown("### 3. Run")
+        with gr.Row():
+            threshold = gr.Slider(
+                0.5, 0.95, value=DEFAULT_THRESHOLD, step=0.05, label="Confidence threshold",
+                info="Answers below it mark the row as needs_review",
+            )
+            engine = gr.Radio(
+                ["Laya", "LM Studio"], value="Laya", label="Engine",
+                info="Laya: fast, built for decisions · LM Studio: a local LLM, slower, often more accurate",
+            )
+            checkpoint = gr.Dropdown(
+                ["auto", "multilingual", "english"], value="auto", label="Laya model variant",
+                info="auto: English files use the English model, others the multilingual one",
+            )
+            lms_model = gr.Dropdown(
+                [], label="LM Studio model", visible=False, allow_custom_value=True,
+                info="Empty: the first model LM Studio has loaded",
+            )
+            lms_refresh = gr.Button("List LM Studio models", visible=False, scale=0)
+        run = gr.Button("Run", variant="primary")
+
+        gr.Markdown("### Result")
+        downloads = gr.File(label="Download (result copy + summary)", file_count="multiple", interactive=False)
+        with gr.Tabs():
+            with gr.Tab("Summary"):
+                summary = gr.Markdown()
+            with gr.Tab("Table"):
+                result = gr.Dataframe(interactive=False, max_height=420, wrap=True)
+
+        upload.change(on_file, upload, [columns, preview, status, source])
+        example.change(on_example, example, [upload, questions])
+        q_upload.change(on_load_questions, q_upload, questions)
+        q_save.click(on_save_questions, questions, q_file)
+        engine.change(on_engine, engine, [checkpoint, lms_model, lms_refresh])
+        lms_refresh.click(on_refresh_models, None, lms_model)
+        run.click(
+            on_run, [source, columns, questions, threshold, engine, checkpoint, lms_model],
+            [result, summary, downloads],
+        )
+    return demo
+
+
+def launch(port: int = 7860, share: bool = False, open_browser: bool = True) -> None:
+    build().launch(
+        server_name="127.0.0.1", server_port=port, share=share, inbrowser=open_browser,
+        theme=gr.themes.Soft(primary_hue="indigo", secondary_hue="slate"),
+    )
+
+
+if __name__ == "__main__":
+    launch()

luar/backends/__init__.py

@@ -0,0 +1,17 @@
+from .base import Answer, Backend, Progress
+from .laya_backend import LayaBackend
+from .lmstudio_backend import LMStudioBackend, LMStudioError
+
+ENGINES = ("laya", "lmstudio")
+
+
+def make_backend(engine: str = "laya", **options) -> Backend:
+    """Build an engine by name. Laya takes checkpoint/device; LM Studio takes model/base_url/api_key."""
+    if engine == "laya":
+        return LayaBackend(**options)
+    if engine == "lmstudio":
+        return LMStudioBackend(**options)
+    raise ValueError(f"Unknown engine {engine!r}; use one of {', '.join(ENGINES)}.")
+
+
+__all__ = ["Answer", "Backend", "ENGINES", "LayaBackend", "LMStudioBackend", "LMStudioError", "Progress", "make_backend"]

luar/backends/base.py

@@ -0,0 +1,29 @@
+"""The "socket" every decision engine plugs into."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Protocol
+
+from ..questions import Question
+
+
+@dataclass
+class Answer:
+    value: str | None        # chosen label; "yes"/"no" for noul; None if the engine gave nothing
+    confidence: float | None  # 0..1, how sure the engine is about `value`
+
+
+Progress = Callable[[int, int], None]
+
+
+class Backend(Protocol):
+    name: str
+
+    def decide(
+        self,
+        texts: list[str],
+        questions: list[Question],
+        progress: Progress | None = None,
+    ) -> list[dict[str, Answer]]:
+        """Return one {question_id: Answer} per text, in the same order."""
+        ...

luar/backends/laya_backend.py

@@ -0,0 +1,96 @@
+"""Laya backend: local Jev-style decision model (https://huggingface.co/convaiinnovations/laya)."""
+from __future__ import annotations
+
+from ..questions import Question
+from .base import Answer, Progress
+
+CHECKPOINTS = {
+    "auto": None,                    # picks english or multilingual from the file's language
+    "multilingual": "multilingual",  # best tested option for non-English text
+    "english": None,                 # clearly better than multilingual on English text
+    "typed-decisions": "typed-decisions",
+}
+ENGLISH_SHARE = 0.8
+LANGUAGE_SAMPLE = 200
+
+
+def pick_checkpoint(texts: list[str], questions: list[Question]) -> str:
+    """"english" when the questions and at least 80% of the (sampled) rows are English."""
+    import laya
+
+    sample = texts[:LANGUAGE_SAMPLE] + [q.question for q in questions]
+    decided = [d for d in map(laya.detect_language, sample) if not d["language_undecided"]]
+    if not decided:
+        return "multilingual"
+    english = sum(d["is_english"] for d in decided) / len(decided)
+    return "english" if english >= ENGLISH_SHARE else "multilingual"
+
+
+def extract_answer(raw: dict | None, qtype: str) -> Answer:
+    """Normalize one Laya answer (package 0.3.x format):
+      choice -> {"choice": "x", "answer_confidence": p}
+      score  -> {"legend": {"0": "low", ...}, "probabilities": {"0": p, ...}}
+      noul   -> {"noul": P(yes)}"""
+    if not isinstance(raw, dict):
+        return Answer(None, None)
+    if qtype == "noul":
+        p = float(raw["noul"])
+        return Answer("yes" if p >= 0.5 else "no", max(p, 1 - p))
+    if qtype == "score":
+        probs = raw["probabilities"]
+        k = max(probs, key=probs.get)
+        return Answer(raw["legend"][k], float(probs[k]))
+    conf = raw.get("answer_confidence", raw.get("confidence"))
+    return Answer(raw.get("choice"), None if conf is None else float(conf))
+
+
+class LayaBackend:
+    def __init__(
+        self,
+        checkpoint: str = "auto",
+        device: str | None = None,
+        repo: str = "convaiinnovations/laya",
+        batch_size: int = 16,
+    ):
+        if checkpoint not in CHECKPOINTS:
+            raise ValueError(f"Unknown checkpoint {checkpoint!r}; use one of {', '.join(CHECKPOINTS)}.")
+        self.checkpoint = checkpoint
+        self.device = device
+        self.repo = repo
+        self.batch_size = batch_size
+        self.name = f"laya ({checkpoint})"
+        self._agent = None
+
+    def _load(self, texts: list[str], questions: list[Question]):
+        if self.checkpoint == "auto":
+            self.checkpoint = pick_checkpoint(texts, questions)
+            self.name = f"laya ({self.checkpoint}, chosen automatically)"
+        if self._agent is None:
+            import laya  # heavy import (torch); only when actually needed
+
+            kwargs = {}
+            if self.device:
+                kwargs["device"] = self.device
+            if CHECKPOINTS[self.checkpoint]:
+                kwargs["subfolder"] = CHECKPOINTS[self.checkpoint]
+            self._agent = laya.load(self.repo, **kwargs)
+        return self._agent
+
+    def decide(
+        self,
+        texts: list[str],
+        questions: list[Question],
+        progress: Progress | None = None,
+    ) -> list[dict[str, Answer]]:
+        agent = self._load(texts, questions)
+        laya_questions = {q.id: q.to_laya() for q in questions}
+        results: list[dict[str, Answer]] = []
+        for start in range(0, len(texts), self.batch_size):
+            chunk = texts[start:start + self.batch_size]
+            raws = agent.predict_batch(chunk, laya_questions, batch_size=self.batch_size)
+            for raw in raws:
+                answers = raw.get("answers", raw) if isinstance(raw, dict) else {}
+                results.append({q.id: extract_answer(answers.get(q.id), q.type) for q in questions})
+            if progress:
+                progress(len(results), len(texts))
+        return results

luar/backends/lmstudio_backend.py

@@ -0,0 +1,163 @@
+"""LM Studio backend: a local LLM behind LM Studio's OpenAI-compatible server.
+
+Each option gets a letter (A, B, C…) and the model answers with one token. The
+probability the model puts on each letter (logprobs) is the confidence, so it is a
+real probability, not a number the model writes about itself."""
+from __future__ import annotations
+
+import json
+import math
+import os
+import string
+import urllib.error
+import urllib.request
+
+from ..questions import Question
+from .base import Answer, Progress
+
+DEFAULT_URL = "http://localhost:1234/v1"
+URL_ENV = "LUAR_LMSTUDIO_URL"
+KEY_ENV = "LMSTUDIO_API_KEY"
+LETTERS = string.ascii_uppercase  # questions are limited to 20 options
+TOP_LOGPROBS = 20
+
+SYSTEM_PROMPT = (
+    "You label text. Read the text, then answer the question by choosing exactly one option. "
+    "Reply with the letter of that option only."
+)
+
+
+class LMStudioError(RuntimeError):
+    """The LM Studio server could not be used (not running, no model, auth…)."""
+
+
+def option_labels(q: Question) -> list[tuple[str, str]]:
+    """[(label, description)] in the order shown to the model."""
+    if q.type == "noul":
+        return [("yes", ""), ("no", "")]
+    return list(q.options.items())
+
+
+def build_prompt(text: str, q: Question) -> str:
+    # The row text comes first so LM Studio can reuse its prompt cache across the
+    # questions of the same row.
+    lines = [f"Text:\n{text}", "", f"Question: {q.question}"]
+    for letter, (label, desc) in zip(LETTERS, option_labels(q)):
+        lines.append(f"{letter}) {label}: {desc}" if desc else f"{letter}) {label}")
+    lines.append("Answer:")
+    return "\n".join(lines)
+
+
+def letter_probabilities(top_logprobs: list[dict], n_options: int) -> dict[str, float]:
+    """Probability per option letter, renormalized over the valid letters only.
+    Tokens like " B" or "b" count for B."""
+    valid = LETTERS[:n_options]
+    probs = dict.fromkeys(valid, 0.0)
+    for item in top_logprobs:
+        tok = item["token"].strip().upper()
+        if tok in probs:
+            probs[tok] += math.exp(item["logprob"])
+    total = sum(probs.values())
+    return {k: v / total for k, v in probs.items()} if total else {}
+
+
+def answer_from_probs(probs: dict[str, float], q: Question) -> Answer:
+    if not probs:
+        return Answer(None, None)
+    best = max(probs, key=probs.get)
+    label = option_labels(q)[LETTERS.index(best)][0]
+    return Answer(label, probs[best])
+
+
+class LMStudioBackend:
+    def __init__(
+        self,
+        model: str | None = None,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float = 300,
+    ):
+        self.base_url = (base_url or os.environ.get(URL_ENV) or DEFAULT_URL).rstrip("/")
+        self.api_key = api_key if api_key is not None else os.environ.get(KEY_ENV)
+        self.model = model
+        self.timeout = timeout
+        self.name = f"lmstudio ({model or 'loaded model'})"
+
+    def _request(self, path: str, body: dict | None = None, root: str | None = None) -> dict:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        data = None if body is None else json.dumps(body).encode()
+        req = urllib.request.Request((root or self.base_url) + path, data=data, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.load(resp)
+        except urllib.error.HTTPError as e:
+            if e.code in (401, 403):
+                raise LMStudioError(
+                    f"LM Studio refused the request ({e.code}). If the server requires an API key, "
+                    f"set the {KEY_ENV} environment variable."
+                ) from e
+            detail = e.read().decode(errors="replace")[:300]
+            raise LMStudioError(f"LM Studio returned {e.code}: {detail}") from e
+        except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+            raise LMStudioError(
+                f"Could not reach LM Studio at {self.base_url}. Start the server "
+                "(`lms server start`, or Developer > Start Server) and load a model."
+            ) from e
+
+    def list_models(self) -> list[str]:
+        """Models the server can use, loaded ones first; embedding models left out.
+        Uses LM Studio's own /api/v0/models (which says what is loaded) when available."""
+        root = self.base_url[:-3] if self.base_url.endswith("/v1") else self.base_url
+        try:
+            data = self._request("/api/v0/models", root=root).get("data", [])
+        except LMStudioError:
+            data = self._request("/models").get("data", [])
+        usable = [m for m in data if m.get("type") != "embeddings" and "embed" not in m["id"].lower()]
+        usable.sort(key=lambda m: m.get("state") != "loaded")  # stable: keeps server order otherwise
+        return [m["id"] for m in usable]
+
+    def resolve_model(self) -> str:
+        if not self.model:
+            models = self.list_models()
+            if not models:
+                raise LMStudioError("No model is available in LM Studio; load one (e.g. `lms load qwen3.5-4b`).")
+            self.model = models[0]
+            self.name = f"lmstudio ({self.model})"
+        return self.model
+
+    def ask(self, text: str, q: Question) -> Answer:
+        body = {
+            "model": self.resolve_model(),
+            "messages": [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": build_prompt(text, q)},
+            ],
+            "max_tokens": 1,
+            "temperature": 0,
+            "logprobs": True,
+            "top_logprobs": TOP_LOGPROBS,
+            "reasoning_effort": "none",  # answer directly, no "thinking" tokens
+        }
+        resp = self._request("/chat/completions", body)
+        try:
+            top = resp["choices"][0]["logprobs"]["content"][0]["top_logprobs"]
+        except (KeyError, IndexError, TypeError) as e:
+            raise LMStudioError(
+                "LM Studio did not return token probabilities (logprobs); update LM Studio."
+            ) from e
+        return answer_from_probs(letter_probabilities(top, len(option_labels(q))), q)
+
+    def decide(
+        self,
+        texts: list[str],
+        questions: list[Question],
+        progress: Progress | None = None,
+    ) -> list[dict[str, Answer]]:
+        results = []
+        for i, text in enumerate(texts):
+            results.append({q.id: self.ask(text, q) for q in questions})
+            if progress:
+                progress(i + 1, len(texts))
+        return results