sharada 0.1.0.dev0__py3-none-any.whl

sharada/__init__.py

@@ -0,0 +1,31 @@
+"""Sharada — typed decisions from text in one forward pass.
+
+    from sharada import DecisionModel
+
+    model = DecisionModel.from_pretrained("LenaBarretta/sharada-base")
+    d = model.decide("My card hasn't arrived yet",
+                     "Which team should handle this?",
+                     ["billing", "technical", "sales"])
+    d.answer, d.confidence
+
+The model reads the text, the question and every option in one pass and returns a probability for each
+option. Every option is a branch of the sequence starting at the same position, so their order cannot
+change the answer; an option reads the text, the question and itself, so its score does not depend on
+which other options are offered.
+"""
+
+from .calibrate import calibrate, check_passport, fit_temperature, save_passport
+from .data import Example, Request
+from .evaluate import calibration_error, evaluate, latency, risk_coverage
+from .layout import Limits
+from .model import Config, Decision, DecisionModel
+from .policy import Action, Policy, escalation_budget
+from .train import fit
+
+__all__ = [
+    "DecisionModel", "Config", "Decision", "Request", "Example", "Limits",
+    "fit", "calibrate", "fit_temperature", "save_passport", "check_passport",
+    "evaluate", "calibration_error", "risk_coverage", "latency",
+    "Policy", "Action", "escalation_budget",
+]
+__version__ = "0.1.0.dev0"

sharada/calibrate.py

@@ -0,0 +1,115 @@
+"""Calibration, and the passport that says where it holds.
+
+A model is not calibrated in general; it is calibrated on a distribution, and it goes stale when the
+traffic moves. So fitting a temperature also writes a passport: what it was fitted on, how far off the
+probabilities were, and what should make you fit it again.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import math
+import pathlib
+
+from .data import Example
+
+VALID_DAYS = 90
+
+
+def _negative_log_likelihood(log_probabilities: list[list[float]], labels: list[int], temperature: float) -> float:
+    total = 0.0
+    for row, label in zip(log_probabilities, labels):
+        scaled = [v / temperature for v in row]
+        top = max(scaled)
+        total += -(scaled[label] - (top + math.log(sum(math.exp(v - top) for v in scaled))))
+    return total / len(labels)
+
+
+def fit_temperature(probabilities: list[list[float]], labels: list[int],
+                    grid: tuple[float, float, int] = (0.25, 8.0, 61)) -> float:
+    """One number per task: divide the scores by it. Chosen to minimise the log loss on held-out
+    answers, which is what a temperature can honestly be chosen on."""
+    low, high, steps = grid
+    log_probabilities = [[math.log(max(p, 1e-12)) for p in row] for row in probabilities]
+    candidates = [math.exp(math.log(low) + (math.log(high) - math.log(low)) * i / (steps - 1)) for i in range(steps)]
+    return min(candidates, key=lambda t: _negative_log_likelihood(log_probabilities, labels, t))
+
+
+def fingerprint(model, examples: list[Example]) -> dict:
+    """What the examples looked like, so a later drift is visible."""
+    out: dict[str, dict] = {}
+    for task in sorted({e.task for e in examples}):
+        subset = [e for e in examples if e.task == task]
+        lengths = sorted(len(model.layout(e.text, e.question, e.options).ids) for e in subset)
+        counts: dict[str, int] = {}
+        for e in subset:
+            counts[e.options[e.label]] = counts.get(e.options[e.label], 0) + 1
+        out[task] = {"n": len(subset), "options": subset[0].options,
+                     "median_tokens": lengths[len(lengths) // 2],
+                     "answers": counts}
+    return out
+
+
+def calibrate(model, examples: list[Example], batch_size: int = 32, valid_days: int = VALID_DAYS) -> dict:
+    """Fit one temperature per task on these examples and return the passport. The temperatures are
+    stored on the model, so `decide` uses them from then on."""
+    from .evaluate import evaluate
+
+    raw = model.probabilities(examples, batch_size=batch_size, calibrated=False)
+    for task in sorted({e.task for e in examples}):
+        index = [i for i, e in enumerate(examples) if e.task == task]
+        model.config.temperatures[task] = fit_temperature([raw[i] for i in index],
+                                                          [examples[i].label for i in index])
+    measured = evaluate(model, examples, batch_size=batch_size, calibrated=True)
+    today = dt.date.today()
+    return {
+        "created": today.isoformat(),
+        "valid_until": (today + dt.timedelta(days=valid_days)).isoformat(),
+        "encoder": model.config.encoder,
+        "examples": len(examples),
+        "temperatures": dict(model.config.temperatures),
+        "fingerprint": fingerprint(model, examples),
+        "calibration_error": measured["calibration_error"],
+        "calibration_error_interval": measured["calibration_error_interval"],
+        "accuracy": measured["accuracy"],
+        "reliability": measured["reliability"],
+        "risk_coverage": measured["risk_coverage"],
+        "recalibrate_if": {
+            "after": "valid_until",
+            "options_change": True,
+            "median_tokens_shift": 0.5,       # half as long, or twice as long
+        },
+    }
+
+
+def save_passport(passport: dict, path: str | pathlib.Path) -> pathlib.Path:
+    path = pathlib.Path(path)
+    path.write_text(json.dumps(passport, indent=1))
+    return path
+
+
+def check_passport(passport: dict, examples: list[Example] | None = None, model=None,
+                   today: dt.date | None = None) -> list[str]:
+    """What is wrong with trusting these probabilities today. An empty list means nothing found —
+    run it in the deployment pipeline and fail the build on anything it returns."""
+    today = today or dt.date.today()
+    problems = []
+    if today.isoformat() > passport["valid_until"]:
+        problems.append(f"the calibration expired on {passport['valid_until']}; fit it again on recent answers")
+    if passport["examples"] < 200:
+        problems.append(f"fitted on {passport['examples']} answers — the interval on the calibration error is wide")
+    if examples and model:
+        now = fingerprint(model, examples)
+        for task, then in passport["fingerprint"].items():
+            if task not in now:
+                continue
+            if now[task]["options"] != then["options"]:
+                problems.append(f"{task}: the options have changed since the calibration")
+            ratio = now[task]["median_tokens"] / max(then["median_tokens"], 1)
+            if ratio < 0.5 or ratio > 2:
+                problems.append(f"{task}: texts are now {ratio:.1f}× the length they were calibrated on")
+        for task in now:
+            if task not in passport["fingerprint"]:
+                problems.append(f"{task}: never calibrated — its probabilities are raw")
+    return problems

sharada/data.py

@@ -0,0 +1,105 @@
+"""Requests, examples and batches."""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+
+import torch
+
+from .layout import FIRST_OPTION, Laid, Layout
+
+KINDS = ("choice", "scale", "binary")       # unordered labels, an ordered scale, yes or no
+
+
+@dataclass
+class Request:
+    """One question about one text."""
+
+    text: str
+    question: str
+    options: list[str]
+    kind: str = "choice"
+    task: str = "task"                       # a name, so temperatures can be fitted per task
+
+    def __post_init__(self):
+        if self.kind not in KINDS:
+            raise ValueError(f"kind must be one of {KINDS}, got {self.kind!r}")
+
+
+@dataclass
+class Example(Request):
+    """A request whose answer is known: `label` is the index of the right option."""
+
+    label: int = 0
+
+    def __post_init__(self):
+        super().__post_init__()
+        if not 0 <= self.label < len(self.options):
+            raise ValueError(f"label {self.label} is outside the {len(self.options)} options")
+
+
+@dataclass
+class Batch:
+    ids: torch.Tensor
+    positions: torch.Tensor
+    segments: torch.Tensor
+    present: torch.Tensor                    # [batch, options] — which option slots are real
+    kinds: torch.Tensor
+    n_options: torch.Tensor
+    labels: torch.Tensor | None = None
+    tasks: list[str] = field(default_factory=list)
+    width: int = 0                           # the widest number of options in this batch
+
+    def to(self, device) -> "Batch":
+        move = lambda v: v.to(device) if torch.is_tensor(v) else v
+        return Batch(move(self.ids), move(self.positions), move(self.segments), move(self.present),
+                     move(self.kinds), move(self.n_options), move(self.labels), self.tasks, self.width)
+
+
+def collate(laid: list[Laid], requests: list[Request], pad_id: int) -> Batch:
+    length = max(len(l) for l in laid)
+    width = max(l.n_options for l in laid)
+    n = len(laid)
+    ids = torch.full((n, length), pad_id, dtype=torch.long)
+    positions = torch.zeros((n, length), dtype=torch.long)
+    segments = torch.full((n, length), -1, dtype=torch.long)
+    for i, l in enumerate(laid):
+        k = len(l)
+        ids[i, :k] = torch.tensor(l.ids)
+        positions[i, :k] = torch.tensor(l.positions)
+        segments[i, :k] = torch.tensor(l.segments)
+    counts = torch.tensor([l.n_options for l in laid])
+    labels = None
+    if all(isinstance(r, Example) for r in requests):
+        labels = torch.tensor([r.label for r in requests])
+    return Batch(ids=ids, positions=positions, segments=segments,
+                 present=torch.arange(width)[None] < counts[:, None],
+                 kinds=torch.tensor([KINDS.index(r.kind) for r in requests]),
+                 n_options=counts, labels=labels, tasks=[r.task for r in requests], width=width)
+
+
+def batches(requests: list[Request], layout: Layout, batch_size: int, pad_id: int,
+            shuffle: bool = False, seed: int = 0):
+    """Mini-batches. When shuffling, requests of similar length travel together, so a batch of short
+    questions is not padded out to the length of one with sixty options."""
+    order = list(range(len(requests)))
+    laid = [layout(r.text, r.question, r.options) for r in requests]
+    if shuffle:
+        rng = random.Random(seed)
+        rng.shuffle(order)
+        window = batch_size * 50
+        order = [j for w in range(0, len(order), window)
+                 for j in sorted(order[w:w + window], key=lambda j: len(laid[j]))]
+    chunks = [order[i:i + batch_size] for i in range(0, len(order), batch_size)]
+    if shuffle:
+        random.Random(seed + 1).shuffle(chunks)
+    for chunk in chunks:
+        yield chunk, collate([laid[j] for j in chunk], [requests[j] for j in chunk], pad_id)
+
+
+def option_mass(segments: torch.Tensor, states: torch.Tensor, width: int) -> torch.Tensor:
+    """Mean of each option's own final token states -> [batch, options, hidden]."""
+    index = FIRST_OPTION + torch.arange(width, device=states.device)
+    member = (segments[:, :, None] == index[None, None, :]).to(states.dtype)
+    return torch.einsum("blk,bld->bkd", member, states) / member.sum(1).clamp(min=1)[..., None]

sharada/evaluate.py

@@ -0,0 +1,105 @@
+"""Measuring a decision model: the answer, the stated number, and the whole distribution."""
+
+from __future__ import annotations
+
+import math
+import random
+import time
+
+from .data import Example
+
+
+def _bands(confidence: list[float], n: int) -> list[int]:
+    return [min(int(c * n), n - 1) for c in confidence]
+
+
+def calibration_error(confidence: list[float], correct: list[int], bands: int = 15) -> float:
+    """The average gap between the probability stated and how often it turns out right, over equal
+    bands, weighted by how many answers fall in each. Zero means this estimate finds no gap — on a
+    finite sample that is not proof of none."""
+    index = _bands(confidence, bands)
+    total = 0.0
+    for b in range(bands):
+        inside = [i for i, j in enumerate(index) if j == b]
+        if inside:
+            said = sum(confidence[i] for i in inside) / len(inside)
+            was = sum(correct[i] for i in inside) / len(inside)
+            total += len(inside) / len(confidence) * abs(said - was)
+    return total
+
+
+def calibration_interval(confidence: list[float], correct: list[int], bands: int = 15,
+                         draws: int = 200, seed: int = 0) -> tuple[float, float]:
+    """A bootstrap interval for the calibration error — on a few hundred answers it is wide, and
+    saying so is the point."""
+    rng = random.Random(seed)
+    n = len(confidence)
+    values = []
+    for _ in range(draws):
+        pick = [rng.randrange(n) for _ in range(n)]
+        values.append(calibration_error([confidence[i] for i in pick], [correct[i] for i in pick], bands))
+    values.sort()
+    return values[int(0.025 * draws)], values[int(0.975 * draws) - 1]
+
+
+def reliability_curve(confidence: list[float], correct: list[int], bands: int = 10) -> list[dict]:
+    index = _bands(confidence, bands)
+    curve = []
+    for b in range(bands):
+        inside = [i for i, j in enumerate(index) if j == b]
+        curve.append({"from": b / bands, "n": len(inside),
+                      "stated": sum(confidence[i] for i in inside) / len(inside) if inside else None,
+                      "observed": sum(correct[i] for i in inside) / len(inside) if inside else None})
+    return curve
+
+
+def risk_coverage(confidence: list[float], correct: list[int], steps: int = 20) -> list[dict]:
+    """Answer only where the model is surest: what accuracy, at what share of the traffic."""
+    order = sorted(range(len(confidence)), key=lambda i: -confidence[i])
+    out = []
+    for k in range(1, steps + 1):
+        take = max(1, round(len(order) * k / steps))
+        kept = [correct[i] for i in order[:take]]
+        out.append({"coverage": take / len(order), "accuracy": sum(kept) / len(kept),
+                    "threshold": confidence[order[take - 1]]})
+    return out
+
+
+def evaluate(model, examples: list[Example], batch_size: int = 32, calibrated: bool = True) -> dict:
+    """Everything above, on one set of labelled examples."""
+    probabilities = model.probabilities(examples, batch_size=batch_size, calibrated=calibrated)
+    confidence, correct, true_p, squared = [], [], [], []
+    for p, e in zip(probabilities, examples):
+        best = max(range(len(p)), key=p.__getitem__)
+        confidence.append(p[best])
+        correct.append(int(best == e.label))
+        true_p.append(p[e.label])
+        squared.append(sum((q - (1.0 if i == e.label else 0.0)) ** 2 for i, q in enumerate(p)))
+    low, high = calibration_interval(confidence, correct)
+    return {"n": len(examples),
+            "accuracy": sum(correct) / len(correct),
+            "mean_confidence": sum(confidence) / len(confidence),
+            "calibration_error": calibration_error(confidence, correct),
+            "calibration_error_interval": [low, high],
+            "log_loss": sum(-math.log(max(p, 1e-9)) for p in true_p) / len(true_p),
+            "brier": sum(squared) / len(squared),
+            "reliability": reliability_curve(confidence, correct),
+            "risk_coverage": risk_coverage(confidence, correct)}
+
+
+def latency(model, request, batch_size: int = 1, repeats: int = 20) -> dict:
+    """Milliseconds per call and per question, as the model is loaded right now."""
+    import torch
+
+    requests = [request] * batch_size
+    for _ in range(3):
+        model.probabilities(requests, batch_size=batch_size)
+    if next(model.parameters()).is_cuda:
+        torch.cuda.synchronize()
+    start = time.time()
+    for _ in range(repeats):
+        model.probabilities(requests, batch_size=batch_size)
+    if next(model.parameters()).is_cuda:
+        torch.cuda.synchronize()
+    per_call = (time.time() - start) / repeats * 1e3
+    return {"batch": batch_size, "ms_per_call": per_call, "ms_per_question": per_call / batch_size}

sharada/layout.py

@@ -0,0 +1,78 @@
+"""One request, laid out as one sequence.
+
+    position:  0     1 … n      n+1    n+2 … m     m+1  │ m+2 …         │ m+2 …
+    token:     [CLS] the text   [SEP]  question    [SEP]│ option 0 [SEP] │ option 1 [SEP]
+
+Every option is a branch of its own and every branch starts at the same position, the one right after
+the question. The encoder's positions are rotary, so to it no option is earlier or later than another:
+the order of the options cannot change their scores. `masking.who_reads_whom` then decides who may read
+whom; together the two give the properties the model is built on.
+"""
+
+from __future__ import annotations
+
+import functools
+from dataclasses import dataclass, field
+
+TEXT = 0
+QUESTION = 1
+FIRST_OPTION = 2        # option i has segment FIRST_OPTION + i
+
+
+@dataclass(frozen=True)
+class Limits:
+    """How many tokens each part of a request may use."""
+
+    text: int = 256
+    question: int = 48
+    option: int = 12
+
+    def as_dict(self) -> dict:
+        return {"text": self.text, "question": self.question, "option": self.option}
+
+
+@dataclass
+class Laid:
+    """A request turned into token ids, position ids and one segment per token."""
+
+    ids: list[int]
+    positions: list[int]
+    segments: list[int]
+    n_options: int
+    option_start: int = field(default=0)
+
+    def __len__(self) -> int:
+        return len(self.ids)
+
+
+class Layout:
+    """Lays requests out for one tokenizer. Token ids of repeated strings — option names, instructions,
+    the same text asked about twice — are cached, which is most of the cost of preparing a batch."""
+
+    def __init__(self, tokenizer, limits: Limits | None = None):
+        self.tokenizer = tokenizer
+        self.limits = limits or Limits()
+        self._ids = functools.lru_cache(maxsize=100_000)(self._encode)
+
+    def _encode(self, text: str) -> tuple[int, ...]:
+        return tuple(self.tokenizer(text, add_special_tokens=False)["input_ids"])
+
+    def __call__(self, text: str, question: str, options: list[str]) -> Laid:
+        if len(options) < 2:
+            raise ValueError("a decision needs at least two options")
+        cls_id, sep_id = self.tokenizer.cls_token_id, self.tokenizer.sep_token_id
+        body = list(self._ids(text))[: self.limits.text]
+        ask = list(self._ids(question))[: self.limits.question]
+
+        ids = [cls_id] + body + [sep_id] + ask + [sep_id]
+        segments = [TEXT] * (len(body) + 2) + [QUESTION] * (len(ask) + 1)
+        positions = list(range(len(ids)))
+
+        start = len(ids)
+        for i, option in enumerate(options):
+            tokens = list(self._ids(" " + option))[: self.limits.option] + [sep_id]
+            ids += tokens
+            segments += [FIRST_OPTION + i] * len(tokens)
+            positions += range(start, start + len(tokens))      # every option restarts here
+        return Laid(ids=ids, positions=positions, segments=segments, n_options=len(options),
+                    option_start=start)

sharada/masking.py

@@ -0,0 +1,48 @@
+"""Who reads whom.
+
+The text reads only the text, so its states do not depend on the question or the options — a text asked
+several questions could be read once. The question reads the text and itself. An option reads the text,
+the question and its own tokens, and nothing else: with seventy-seven options on offer, each one still
+sees only the message and itself, and its score does not depend on which other options came along.
+
+`read_each_other=True` keeps the other behaviour — options that also read one another — which is what
+this model was first trained with. On label sets of a few options it costs nothing; on seventy-seven it
+cost thirty points of accuracy, which is why it is not the default.
+
+The encoder's local-attention layers only look a fixed distance away, and the distance is measured in
+positions, so an option sees the end of the question the same way wherever it sits in the sequence.
+"""
+
+from __future__ import annotations
+
+import torch
+
+from .layout import QUESTION, TEXT
+
+
+def who_reads_whom(segments: torch.Tensor, positions: torch.Tensor, local_reach: int,
+                   read_each_other: bool = False) -> tuple[torch.Tensor, torch.Tensor]:
+    """-> two [batch, length, length] boolean masks: for the global layers and for the local ones.
+    True at (i, j) means query token i may read key token j."""
+    q, k = segments[:, :, None], segments[:, None, :]
+    real = k >= 0                                     # padding is not a key
+    context = (k == TEXT) | (k == QUESTION)
+    options_see = real if read_each_other else (context | (k == q))
+    full = torch.where(q == TEXT, k == TEXT, torch.where(q == QUESTION, context, options_see)) & real
+    full = full | torch.eye(segments.size(1), dtype=torch.bool, device=segments.device)[None]
+    near = (positions[:, :, None] - positions[:, None, :]).abs() <= local_reach
+    return full, full & near
+
+
+def encoder_masks(segments: torch.Tensor, positions: torch.Tensor, local_reach: int,
+                  attn_implementation: str, dtype: torch.dtype, read_each_other: bool = False) -> dict:
+    """The masks in the form the encoder expects: booleans for fused attention, an additive float mask
+    for the plain implementation."""
+    out = {}
+    names = ("full_attention", "sliding_attention")
+    for name, allowed in zip(names, who_reads_whom(segments, positions, local_reach, read_each_other)):
+        mask = allowed[:, None]
+        if attn_implementation == "eager":
+            mask = torch.zeros(mask.shape, dtype=dtype, device=mask.device).masked_fill(~mask, torch.finfo(dtype).min)
+        out[name] = mask
+    return out

sharada/model.py

@@ -0,0 +1,167 @@
+"""The decision model: an encoder, a small read-out, one number per option."""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from dataclasses import asdict, dataclass, field
+
+import torch
+import torch.nn as nn
+
+from .data import Batch, Example, Request, batches, collate, option_mass
+from .layout import Laid, Layout, Limits
+
+DEFAULT_ENCODER = "answerdotai/ModernBERT-base"
+
+
+@dataclass
+class Config:
+    encoder: str = DEFAULT_ENCODER
+    limits: dict = field(default_factory=lambda: Limits().as_dict())
+    local_reach: int | None = None          # taken from the encoder when left out
+    read_each_other: bool = False           # options reading one another; off by default, see masking.py
+    temperatures: dict = field(default_factory=dict)    # per task, fitted by `calibrate`
+    version: int = 1
+
+
+@dataclass
+class Decision:
+    """What the model answers, and how sure it says it is."""
+
+    answer: str
+    index: int
+    probabilities: dict[str, float]
+    confidence: float
+
+    def __repr__(self) -> str:
+        return f"Decision({self.answer!r}, confidence={self.confidence:.3f})"
+
+
+class DecisionModel(nn.Module):
+    def __init__(self, config: Config | None = None, tokenizer=None, encoder=None):
+        super().__init__()
+        from transformers import AutoModel, AutoTokenizer
+
+        self.config = config or Config()
+        self.tokenizer = tokenizer or AutoTokenizer.from_pretrained(self.config.encoder)
+        self.attn = "eager" if not torch.cuda.is_available() else "sdpa"
+        self.encoder = encoder or AutoModel.from_pretrained(self.config.encoder, attn_implementation=self.attn)
+        hidden = self.encoder.config.hidden_size
+        self.read = nn.Sequential(nn.Linear(2 * hidden, hidden), nn.GELU(), nn.LayerNorm(hidden),
+                                  nn.Linear(hidden, 1))
+        if self.config.local_reach is None:
+            self.config.local_reach = getattr(self.encoder.config, "local_attention", 128) // 2
+        self.layout = Layout(self.tokenizer, Limits(**self.config.limits))
+
+    # ── the forward pass ──────────────────────────────────────────────────────────────────────
+    def forward(self, batch: Batch) -> torch.Tensor:
+        """-> [batch, options] scores; options that do not exist cannot win."""
+        from .masking import encoder_masks
+
+        dtype = self.encoder.embeddings.tok_embeddings.weight.dtype
+        masks = encoder_masks(batch.segments, batch.positions, self.config.local_reach,
+                              self.attn, dtype, self.config.read_each_other)
+        states = self.encoder(input_ids=batch.ids, position_ids=batch.positions,
+                              attention_mask=masks).last_hidden_state
+        options = option_mass(batch.segments, states, batch.width)
+        summary = states[:, :1].expand(-1, batch.width, -1)
+        scores = self.read(torch.cat([options, options * summary], -1)).squeeze(-1).float()
+        return scores.masked_fill(~batch.present, -1e4)
+
+    # ── asking it things ──────────────────────────────────────────────────────────────────────
+    @torch.no_grad()
+    def probabilities(self, requests: list[Request], batch_size: int = 32,
+                      calibrated: bool = True) -> list[list[float]]:
+        """One distribution over the options of each request, in the order they were given."""
+        self.eval()
+        device = next(self.parameters()).device
+        out: list[list[float]] = [[] for _ in requests]
+        for chunk, batch in batches(requests, self.layout, batch_size, self.tokenizer.pad_token_id):
+            scores = self(batch.to(device))
+            for row, j in enumerate(chunk):
+                k = int(batch.n_options[row])
+                z = scores[row, :k].float().cpu()
+                if calibrated:
+                    z = z / self.temperature_for(requests[j])
+                out[j] = torch.softmax(z, -1).tolist()
+        return out
+
+    def decide(self, text: str, question: str, options: list[str], kind: str = "choice",
+               task: str = "task", calibrated: bool = True) -> Decision:
+        """One decision, start to finish."""
+        request = Request(text=text, question=question, options=options, kind=kind, task=task)
+        return self.decide_many([request], calibrated=calibrated)[0]
+
+    def decide_many(self, requests: list[Request], batch_size: int = 32,
+                    calibrated: bool = True) -> list[Decision]:
+        decisions = []
+        for request, probabilities in zip(requests, self.probabilities(requests, batch_size, calibrated)):
+            best = max(range(len(probabilities)), key=probabilities.__getitem__)
+            decisions.append(Decision(answer=request.options[best], index=best,
+                                      probabilities=dict(zip(request.options, probabilities)),
+                                      confidence=probabilities[best]))
+        return decisions
+
+    def temperature_for(self, request: Request) -> float:
+        return float(self.config.temperatures.get(request.task, 1.0))
+
+    # ── saving and loading ────────────────────────────────────────────────────────────────────
+    def save(self, path: str | pathlib.Path) -> pathlib.Path:
+        from safetensors.torch import save_file
+
+        path = pathlib.Path(path)
+        path.mkdir(parents=True, exist_ok=True)
+        save_file({k: v.contiguous() for k, v in self.state_dict().items()}, path / "model.safetensors")
+        (path / "config.json").write_text(json.dumps(asdict(self.config), indent=1))
+        self.tokenizer.save_pretrained(path)
+        return path
+
+    @classmethod
+    def from_pretrained(cls, path: str | pathlib.Path, device: str | None = None) -> "DecisionModel":
+        """A local directory saved by `save`, or a model id on the Hub."""
+        from safetensors.torch import load_file
+        from transformers import AutoConfig, AutoModel, AutoTokenizer
+
+        local = pathlib.Path(path)
+        if not local.is_dir():
+            from huggingface_hub import snapshot_download
+
+            local = pathlib.Path(snapshot_download(str(path)))
+        config = Config(**json.loads((local / "config.json").read_text()))
+        tokenizer = AutoTokenizer.from_pretrained(local)
+        attn = "eager" if not torch.cuda.is_available() else "sdpa"
+        encoder = AutoModel.from_config(AutoConfig.from_pretrained(config.encoder), attn_implementation=attn)
+        model = cls(config=config, tokenizer=tokenizer, encoder=encoder)
+        model.load_state_dict(load_file(local / "model.safetensors"))
+        return model.to(device or ("cuda" if torch.cuda.is_available() else "cpu"))
+
+    def push_to_hub(self, repo_id: str, private: bool = False) -> str:
+        """Upload to the Hub. The token comes from the environment; this never asks for one."""
+        import tempfile
+
+        from huggingface_hub import HfApi
+
+        api = HfApi()
+        api.create_repo(repo_id, private=private, exist_ok=True)
+        with tempfile.TemporaryDirectory() as tmp:
+            self.save(tmp)
+            api.upload_folder(folder_path=tmp, repo_id=repo_id)
+        return f"https://huggingface.co/{repo_id}"
+
+    # ── training lives in train.py, calibration in calibrate.py ───────────────────────────────
+    def fit(self, examples: list[Example], **kwargs):
+        from .train import fit
+
+        return fit(self, examples, **kwargs)
+
+    def calibrate(self, examples: list[Example], **kwargs):
+        from .calibrate import calibrate
+
+        return calibrate(self, examples, **kwargs)
+
+
+def encode_one(model: DecisionModel, request: Request) -> tuple[Laid, Batch]:
+    """Handy in tests: one request, laid out and collated."""
+    laid = model.layout(request.text, request.question, request.options)
+    return laid, collate([laid], [request], model.tokenizer.pad_token_id)

sharada/policy.py

@@ -0,0 +1,100 @@
+"""What to do with 0.94.
+
+A probability is not a decision. The decision depends on what each mistake costs and on what it costs
+to hand the case to a person or to a bigger model. Give those costs and the rule is arithmetic: take the
+action with the smallest expected loss, and abstain when abstaining costs less than any of them.
+
+    policy = Policy(options=["approve", "reject"],
+                    costs={("fraud", "approve"): 10_000, ("clean", "reject"): 100},
+                    escalate=30)
+    policy.act(decision.probabilities)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+ESCALATE = "escalate"
+
+
+@dataclass
+class Action:
+    kind: str                      # "answer" or "escalate"
+    answer: str | None
+    expected_loss: float
+    margin: float                  # how much better than the next best course of action
+
+    def __repr__(self) -> str:
+        what = self.answer if self.kind == "answer" else "escalate"
+        return f"Action({what!r}, expected_loss={self.expected_loss:.2f})"
+
+
+@dataclass
+class Policy:
+    """Costs are given per (true option, chosen option) pair; anything not named costs `wrong` when the
+    answer is wrong and nothing when it is right."""
+
+    options: list[str]
+    costs: dict[tuple[str, str], float] = field(default_factory=dict)
+    wrong: float = 1.0
+    escalate: float | None = None
+
+    def loss(self, true_option: str, chosen: str) -> float:
+        if true_option == chosen:
+            return float(self.costs.get((true_option, chosen), 0.0))
+        return float(self.costs.get((true_option, chosen), self.wrong))
+
+    def expected_losses(self, probabilities: dict[str, float]) -> dict[str, float]:
+        """What each course of action is expected to cost, under the model's own probabilities."""
+        out = {chosen: sum(p * self.loss(true_option, chosen) for true_option, p in probabilities.items())
+               for chosen in self.options}
+        if self.escalate is not None:
+            out[ESCALATE] = float(self.escalate)
+        return out
+
+    def act(self, probabilities: dict[str, float]) -> Action:
+        losses = self.expected_losses(probabilities)
+        ranked = sorted(losses.items(), key=lambda kv: kv[1])
+        (best, loss), (_, second) = ranked[0], ranked[1]
+        if best == ESCALATE:
+            return Action(kind=ESCALATE, answer=None, expected_loss=loss, margin=second - loss)
+        return Action(kind="answer", answer=best, expected_loss=loss, margin=second - loss)
+
+    # ── choosing how much to take on ──────────────────────────────────────────────────────────
+    def coverage(self, probabilities: list[dict[str, float]]) -> float:
+        """The share of these requests the model would answer itself."""
+        answered = sum(1 for p in probabilities if self.act(p).kind == "answer")
+        return answered / len(probabilities)
+
+    def realised_loss(self, probabilities: list[dict[str, float]], truths: list[str]) -> dict:
+        """What this policy would actually have cost on labelled data — the number to compare policies
+        on, and the one that goes wrong when the probabilities are not honest."""
+        total, answered, mistakes = 0.0, 0, 0
+        for p, truth in zip(probabilities, truths):
+            action = self.act(p)
+            if action.kind == ESCALATE:
+                total += float(self.escalate or 0.0)
+                continue
+            answered += 1
+            total += self.loss(truth, action.answer)
+            mistakes += action.answer != truth
+        n = len(truths)
+        return {"loss_per_request": total / n, "coverage": answered / n,
+                "accuracy_when_answering": (answered - mistakes) / answered if answered else float("nan")}
+
+
+def escalation_budget(policy: Policy, probabilities: list[dict[str, float]], budget: float) -> Policy:
+    """Escalating everything the model is unsure about only works while there is someone to escalate to.
+    Given a budget — the share of requests that may be handed over — this returns the policy that keeps
+    to it: the cost of escalating is raised until few enough cases are worth escalating."""
+    if policy.escalate is None:
+        raise ValueError("this policy never escalates; give it an `escalate` cost first")
+    low, high = 0.0, max(policy.wrong, policy.escalate) * 100
+    for _ in range(40):
+        middle = (low + high) / 2
+        trial = Policy(policy.options, policy.costs, policy.wrong, middle)
+        if 1 - trial.coverage(probabilities) > budget:
+            low = middle            # too many escalations: make escalating dearer
+        else:
+            high = middle
+    return Policy(policy.options, policy.costs, policy.wrong, high)

sharada/train.py

@@ -0,0 +1,125 @@
+"""Fine-tuning on your own labelled examples.
+
+Three lines should get you a usable model:
+
+    model = DecisionModel.from_pretrained("LenaBarretta/sharada-base")
+    report = model.fit(examples)
+    model.save("my-router")
+
+`fit` holds a part of the examples out, trains on the rest, stops when the held-out log loss stops
+improving, then fits one temperature per task on that same held-out part and writes a calibration
+passport. What comes back is a report of what it did and how well it ended up.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+import time
+from dataclasses import dataclass
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from .data import Example, batches
+
+
+@dataclass
+class Report:
+    examples: int
+    held_out: int
+    epochs: float
+    minutes: float
+    accuracy: float
+    log_loss: float
+    calibration_error: float
+    temperatures: dict
+    passport: dict
+
+    def __repr__(self) -> str:
+        return (f"Report({self.examples} examples, accuracy {self.accuracy:.3f}, "
+                f"log loss {self.log_loss:.3f}, calibration error {self.calibration_error:.3f})")
+
+
+def brier_loss(scores: torch.Tensor, batch) -> torch.Tensor:
+    """The squared error over all options; for a scale, over the cumulative distribution."""
+    probabilities = torch.softmax(scores, -1) * batch.present
+    truth = F.one_hot(batch.labels, scores.size(-1)).to(probabilities.dtype) * batch.present
+    flat = ((probabilities - truth) ** 2 * batch.present).sum(-1)
+    ranked = (((probabilities.cumsum(-1) - truth.cumsum(-1)) ** 2) * batch.present).sum(-1) / (batch.n_options - 1).clamp(min=1)
+    return torch.where(batch.kinds == 1, ranked, flat).mean()
+
+
+def fit(model, examples: list[Example], *, val_split: float = 0.2, max_epochs: int = 10,
+        batch_size: int = 16, lr: float = 2e-5, patience: int = 2, loss: str = "cross_entropy",
+        freeze_encoder: bool = False, seed: int = 0, device: str | None = None,
+        progress: bool = True) -> Report:
+    if len(examples) < 20:
+        raise ValueError("fine-tuning needs at least 20 examples; below that, use the model as it is")
+    device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+    model.to(device)
+
+    rng = random.Random(seed)
+    order = list(range(len(examples)))
+    rng.shuffle(order)
+    cut = max(10, int(len(examples) * val_split))
+    held_out = [examples[i] for i in order[:cut]]
+    training = [examples[i] for i in order[cut:]]
+
+    for parameter in model.encoder.parameters():
+        parameter.requires_grad = not freeze_encoder
+    trainable = [p for p in model.parameters() if p.requires_grad]
+    optimizer = torch.optim.AdamW(trainable, lr=lr, weight_decay=0.01)
+    steps = max_epochs * math.ceil(len(training) / batch_size)
+    schedule = torch.optim.lr_scheduler.OneCycleLR(optimizer, max_lr=lr, total_steps=steps + 1, pct_start=0.1)
+    scaler = torch.amp.GradScaler("cuda", enabled=device.startswith("cuda"))
+    loss_fn = brier_loss if loss == "brier" else None
+
+    best, best_state, waited, start, epochs_done = math.inf, None, 0, time.time(), 0
+    for epoch in range(max_epochs):
+        model.train()
+        for _, batch in batches(training, model.layout, batch_size, model.tokenizer.pad_token_id,
+                                shuffle=True, seed=seed + epoch):
+            batch = batch.to(device)
+            with torch.amp.autocast("cuda", dtype=torch.float16, enabled=device.startswith("cuda")):
+                scores = model(batch)
+                step_loss = loss_fn(scores, batch) if loss_fn else F.cross_entropy(scores, batch.labels)
+            optimizer.zero_grad(set_to_none=True)
+            scaler.scale(step_loss).backward()
+            scaler.unscale_(optimizer)
+            nn.utils.clip_grad_norm_(trainable, 1.0)
+            scaler.step(optimizer)
+            scaler.update()
+            schedule.step()
+        epochs_done = epoch + 1
+
+        current = _log_loss(model, held_out, batch_size)
+        if progress:
+            print(f"epoch {epochs_done}: held-out log loss {current:.4f}", flush=True)
+        if current < best - 1e-4:
+            best, waited = current, 0
+            best_state = {k: v.detach().cpu().clone() for k, v in model.state_dict().items()}
+        else:
+            waited += 1
+            if waited >= patience:
+                break
+    if best_state is not None:
+        model.load_state_dict(best_state)
+        model.to(device)
+
+    from .calibrate import calibrate
+
+    passport = calibrate(model, held_out, batch_size=batch_size)
+    from .evaluate import evaluate
+
+    scores = evaluate(model, held_out, batch_size=batch_size)
+    return Report(examples=len(examples), held_out=len(held_out), epochs=epochs_done,
+                  minutes=(time.time() - start) / 60, accuracy=scores["accuracy"],
+                  log_loss=scores["log_loss"], calibration_error=scores["calibration_error"],
+                  temperatures=dict(model.config.temperatures), passport=passport)
+
+
+def _log_loss(model, examples: list[Example], batch_size: int) -> float:
+    probabilities = model.probabilities(examples, batch_size=batch_size, calibrated=False)
+    return float(sum(-math.log(max(p[e.label], 1e-9)) for p, e in zip(probabilities, examples)) / len(examples))

sharada-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.5
+Name: sharada
+Version: 0.1.0.dev0
+Summary: Typed decisions from text in one forward pass — options in the request, calibrated probabilities, easy to fine-tune.
+Project-URL: Homepage, https://github.com/LenaBarretta/sharada
+Project-URL: Article, https://lenatriestounderstand.com/notes/llm/024-rlcr/
+Author: Lena Barretta
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: calibration,decision-making,text-classification,uncertainty,zero-shot-classification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: huggingface-hub>=0.26
+Requires-Dist: safetensors>=0.4
+Requires-Dist: torch>=2.2
+Requires-Dist: transformers==5.12.1
+Provides-Extra: train
+Requires-Dist: datasets>=4; extra == 'train'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/logo.png" alt="Sharada" width="200">
+</p>
+
+<h1 align="center">Sharada</h1>
+
+<p align="center">
+  <em>Typed decisions about text in one forward pass — options in the request, calibrated probabilities out.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/LenaBarretta/sharada/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="Apache 2.0"></a>
+  <a href="https://huggingface.co/LenaBarretta/sharada-base"><img src="https://img.shields.io/badge/%F0%9F%A4%97-sharada--base-yellow" alt="sharada-base on the Hub"></a>
+  <a href="https://lenatriestounderstand.com/notes/llm/024-rlcr/"><img src="https://img.shields.io/badge/write--up-lenatriestounderstand-ff69b4" alt="the write-up"></a>
+</p>
+
+A small encoder that makes **typed decisions about text in one forward pass**: the options come with the
+request, and what comes back is a probability for each of them. Nothing is generated, nothing is parsed,
+and the same model answers a question it has never seen because the labels are part of the input rather
+than part of the weights.
+
+```python
+from sharada import DecisionModel
+
+model = DecisionModel.from_pretrained("LenaBarretta/sharada-base")
+
+d = model.decide(
+    text="My card still hasn't arrived and I ordered it two weeks ago.",
+    question="Which team should handle this?",
+    options=["billing", "card delivery", "technical support", "account closure"],
+)
+
+d.answer          # 'card delivery'
+d.confidence      # 0.86
+d.probabilities   # {'billing': 0.07, 'card delivery': 0.86, ...}
+```
+
+Three kinds of question are typed, so the model knows what the options mean:
+
+| kind | the options are | example |
+| --- | --- | --- |
+| `choice` | unordered labels | which team, which topic, which intent |
+| `scale` | ordered steps | severity 1–5, how positive, how urgent |
+| `binary` | yes or no | is this spam, does this need a human |
+
+```python
+from sharada import Request
+
+model.decide_many([
+    Request(text=review, question="How positive is this review?",
+            options=["very negative", "negative", "neutral", "positive", "very positive"],
+            kind="scale", task="review-tone"),
+    Request(text=review, question="Does this mention a refund?",
+            options=["no", "yes"], kind="binary", task="refund-flag"),
+])
+```
+
+## Install
+
+```bash
+pip install git+https://github.com/LenaBarretta/sharada
+```
+
+Python 3.10+, `torch` and `transformers`; CPU is enough to run it.
+
+## Models
+
+| model | encoder | parameters | what it is for |
+| --- | --- | --- | --- |
+| `LenaBarretta/sharada-base` | ModernBERT-base | 150M | the default; fine-tune this one |
+| `LenaBarretta/sharada-large` | ModernBERT-large | 400M | a few points better, ~2.5× the time |
+
+Accuracy and calibration per label set are in each model card, measured on label sets the model was
+**not** trained on as well as on the ones it was.
+
+## Three things the architecture guarantees
+
+The request is laid out as one sequence — text, question, then every option as a parallel branch — and a
+mask decides who may read whom. Both are in [`layout.py`](sharada/layout.py) and
+[`masking.py`](sharada/masking.py), and they buy three properties that hold by construction, not because
+training got them approximately right:
+
+1. **The order of the options cannot matter.** Every option branch starts at the same position id, and
+   the encoder's positions are rotary, so no option is earlier or later than another. Reshuffle them and
+   the probabilities follow their options exactly.
+2. **An option's score does not depend on which other options are offered.** An option reads the text,
+   the question and itself, nothing else. Drop two options from a list of four and the remaining two keep
+   their scores to the last bit — so the probabilities are a renormalisation, and a long list of options
+   does not make each one noisier.
+3. **The text is read once.** Text tokens read only text tokens, so their states do not depend on the
+   question. Ten questions about one document are ten cheap read-outs over one encoding of it.
+
+These are the tests in [`tests/test_model.py`](tests/test_model.py), checked on an untrained model.
+
+## Fine-tune it on your own labels
+
+This is what the package is built around: a few hundred labelled examples and a few minutes.
+
+```python
+from sharada import DecisionModel, Example
+
+examples = [
+    Example(text="the invoice is wrong again", question="Which team should handle this?",
+            options=["billing", "technical", "sales"], label=0, task="routing"),
+    ...
+]
+
+model = DecisionModel.from_pretrained("LenaBarretta/sharada-base")
+report = model.fit(examples)        # holds out 20%, stops when held-out log loss stops improving
+model.save("my-router")
+
+report        # Report(820 examples, accuracy 0.914, log loss 0.287, calibration error 0.031)
+```
+
+`fit` keeps a part of the examples out, trains on the rest, early-stops, then fits one temperature per
+task on the held-out part and writes a calibration passport. Useful arguments:
+
+| argument | default | |
+| --- | --- | --- |
+| `loss` | `"cross_entropy"` | `"brier"` scores the whole distribution, not just the right option |
+| `freeze_encoder` | `False` | train the read-out only: seconds, and enough for a few hundred examples |
+| `batch_size`, `lr`, `max_epochs`, `patience` | `16`, `2e-5`, `10`, `2` | |
+
+Mixing several tasks in one `fit` is the normal case — give each one its own `task` name and each gets
+its own temperature. See [`examples/finetune_your_own.py`](examples/finetune_your_own.py), which trains
+on a CSV.
+
+## The number next to the answer is supposed to be true
+
+`0.86` should mean right about 86% of the time. That is a property of a distribution, not of a model, so
+it is fitted and it expires:
+
+```python
+from sharada import check_passport, save_passport
+
+passport = model.calibrate(recent_examples)     # one temperature per task
+save_passport(passport, "passport.json")
+
+check_passport(passport, recent_examples, model)
+# ['the calibration expired on 2026-04-01; fit it again on recent answers',
+#  'routing: the options have changed since the calibration']
+```
+
+`check_passport` returns an empty list when it finds nothing wrong — run it in the deployment pipeline
+and fail the build on anything it returns. `evaluate` gives accuracy, log loss, Brier, expected
+calibration error with a bootstrap interval, a reliability curve and a risk–coverage curve.
+
+## What to do with 0.86
+
+A probability is not a decision. `Policy` turns one into the action that costs the least, including
+handing the request to a person:
+
+```python
+from sharada import Policy, escalation_budget
+
+policy = Policy(options=["approve", "reject"],
+                costs={("fraud", "approve"): 10_000, ("clean", "reject"): 100},
+                escalate=30)
+
+policy.act({"fraud": 0.1, "clean": 0.9})     # Action('answer', 'reject', expected_loss=90.0)
+policy.act({"fraud": 0.5, "clean": 0.5})     # Action('escalate', ...)
+
+# a person can look at 5% of the traffic, no more:
+policy = escalation_budget(policy, probabilities, budget=0.05)
+```
+
+## Train the base models yourself
+
+[`training/`](training) has the whole run: a mix of public label sets in
+[`sources.py`](training/sources.py) — intents, topics, sentiment, toxicity, spam, entailment, review
+scores — each one presented with several question phrasings, shuffled options and sampled option
+subsets, so the model learns to read the options rather than their positions. Some label sets are held
+out of training entirely and only measured, which is where the zero-shot numbers come from.
+
+```bash
+python training/run.py --encoder answerdotai/ModernBERT-base --out runs/base
+```
+
+It checkpoints every few hundred steps and resumes from the checkpoint if it finds one, which is what
+makes it survive a Kaggle session; [`training/kaggle.ipynb`](training/kaggle.ipynb) is the notebook
+wrapper. One free T4: about an hour for base, about three for large.
+
+## What it will not do
+
+- **It does not generate.** No free-form answers, no extraction, no reasoning out loud. Options or
+  nothing.
+- **256 tokens of text** by default (`Limits`), with 48 for the question and 12 per option. Longer
+  documents need chunking or a larger limit, and the limit costs quadratic attention.
+- **English.** The encoder is English-only; a multilingual encoder drops in, but the published
+  checkpoints are not trained for it.
+- **It is small.** Where a frontier model knows a fact that is not in the text, it wins. This answers
+  questions about the text in front of it.
+
+## Where it came from
+
+The design, the experiments behind it and what each training signal did are written up in
+[RLCR from Scratch](https://lenatriestounderstand.com/notes/llm/024-rlcr/), with a runnable lab.
+
+Apache 2.0.

sharada-0.1.0.dev0.dist-info/RECORD

@@ -0,0 +1,13 @@
+sharada/__init__.py,sha256=kqs7sBkdNMppeKdGznxvz9jMdiWoMvUNz5yox7OQLj8,1358
+sharada/calibrate.py,sha256=htaw-6roSaSf50RrrsW6DMZFcQAk4re-RX_goieBStM,5425
+sharada/data.py,sha256=Ow5gKtU571DxXDCRcexGPz10ligmV9MSR3MF8A543G0,4170
+sharada/evaluate.py,sha256=GJEiK-MGQxeM74t9F0SGU21oaBrU6VQcJX8tdFgKqz0,4725
+sharada/layout.py,sha256=I0_L1RCZfo26r06cIHic8A0FgTnb1AGTseZIfAiBMwg,2962
+sharada/masking.py,sha256=HG1xSUhUj0DRswzrZ4IU8AOIGuxWR3gF1jYFEtGm8kM,2625
+sharada/model.py,sha256=2xj0BfzXjgxHnD6jZVXJhQlPq5kQSnAQ9tivqELCVMo,8307
+sharada/policy.py,sha256=FbP-cIf5LeF0NfLNTSRy8mcfDzjCqQ49xypIWTyEfy0,4829
+sharada/train.py,sha256=ftGiOQv8rPTRVBBhhKlSaYVfvpt1inOn6ek_cAFgdmI,5283
+sharada-0.1.0.dev0.dist-info/METADATA,sha256=ZUBbEwQ7gJe7EfelwLKFAQRNIGc8fJGwdzl6qDMY528,9821
+sharada-0.1.0.dev0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+sharada-0.1.0.dev0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+sharada-0.1.0.dev0.dist-info/RECORD,,

sharada-0.1.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

sharada-0.1.0.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 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.