simasia 0.2.0__py3-none-any.whl

simasia/__init__.py

@@ -0,0 +1,24 @@
+"""Local tone classification utilities for LLM responses."""
+
+from .embeddings import EmbeddingModel, LocalEmbedder, OpenAIEmbedder
+from .generation import GenerationModel, OpenAIGenerator
+from .guard import SimasiaGuard
+from .storage import (
+    ArtifactStore,
+    FileArtifactStore,
+    deserialize_artifact,
+    serialize_artifact,
+)
+
+__all__ = [
+    "SimasiaGuard",
+    "OpenAIEmbedder",
+    "LocalEmbedder",
+    "EmbeddingModel",
+    "OpenAIGenerator",
+    "GenerationModel",
+    "ArtifactStore",
+    "FileArtifactStore",
+    "serialize_artifact",
+    "deserialize_artifact",
+]

simasia/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simasia/cli.py

@@ -0,0 +1,57 @@
+"""Command-line entry point: ``simasia train`` / ``simasia score``.
+
+Loads keys from ``.env`` / ``.env.local`` (if present), reads ``simasia.toml``,
+and runs the requested command.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from .config import build_guard, load_config, load_dotenv, run_training
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="simasia", description="Brand tone guardrail.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    train = sub.add_parser("train", help="Train a brand model from the config file.")
+    train.add_argument("--config", default="simasia.toml")
+
+    score = sub.add_parser("score", help="Score one response against a trained brand.")
+    score.add_argument("--config", default="simasia.toml")
+    score.add_argument("text", help="The response text to score.")
+
+    explain = sub.add_parser(
+        "explain", help="Score a response and show the closest on/off-brand samples."
+    )
+    explain.add_argument("--config", default="simasia.toml")
+    explain.add_argument("text", help="The response text to explain.")
+
+    args = parser.parse_args(argv)
+
+    # Make keys in a local .env available before we build any backend.
+    load_dotenv(".env")
+    load_dotenv(".env.local")
+
+    config = load_config(args.config)
+
+    if args.command == "train":
+        accuracy = run_training(config)
+        print(f"Trained brand '{config['brand']['id']}'. Training accuracy: {accuracy:.3f}")
+    elif args.command == "score":
+        guard = build_guard(config)
+        print(f"{guard.evaluate_response(args.text):.3f}")
+    elif args.command == "explain":
+        guard = build_guard(config)
+        result = guard.explain(args.text)
+        on = result["closest_on_brand"]
+        off = result["closest_off_brand"]
+        print(f"score:   {result['score']:.3f} ({result['verdict']})")
+        print(f"on-brand  (sim {on['similarity']:.2f}): {on['text']}")
+        print(f"off-brand (sim {off['similarity']:.2f}): {off['text']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simasia/config.py

@@ -0,0 +1,111 @@
+"""Config-file driven setup: build a guard and run training from ``simasia.toml``.
+
+Secrets stay in the environment (``EMBEDDING_KEY`` / ``GENERATION_KEY``, which a
+``.env`` file can supply); the TOML file holds only non-secret settings, so it is
+safe to commit.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+try:  # stdlib on 3.11+, backport on 3.10
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - version dependent
+    import tomli as tomllib
+
+from .embeddings import LocalEmbedder, OpenAIEmbedder
+from .generation import OpenAIGenerator
+from .guard import SimasiaGuard
+
+
+def load_dotenv(path: str | os.PathLike[str]) -> None:
+    """Load simple ``KEY=VALUE`` lines from a .env file into the environment.
+
+    Existing environment variables win, so a real shell export is never clobbered.
+    """
+    path = Path(path)
+    if not path.exists():
+        return
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+def load_config(path: str | os.PathLike[str]) -> dict:
+    """Parse a ``simasia.toml`` config file into a dict."""
+    with open(path, "rb") as handle:
+        return tomllib.load(handle)
+
+
+def build_guard(config: dict) -> SimasiaGuard:
+    """Construct a :class:`SimasiaGuard` from a parsed config dict."""
+    brand_id = config["brand"]["id"]
+
+    embed_cfg = config.get("embedding", {})
+    provider = embed_cfg.get("provider", "openai")
+    if provider == "openai":
+        embedder = OpenAIEmbedder(
+            model=embed_cfg.get("model", OpenAIEmbedder.DEFAULT_MODEL),
+            api_key=embed_cfg.get("api_key"),
+            dimensions=embed_cfg.get("dimensions"),
+        )
+    elif provider == "local":
+        embedder = LocalEmbedder(
+            model_name=embed_cfg.get("model", LocalEmbedder.DEFAULT_MODEL_NAME)
+        )
+    else:
+        raise ValueError(f"Unknown embedding provider: {provider!r} (use 'openai' or 'local').")
+
+    # Only build a generator when configured; otherwise the guard makes a default
+    # one lazily, and only if on-brand-only training actually needs it.
+    gen_cfg = config.get("generation")
+    generator = (
+        OpenAIGenerator(
+            model=gen_cfg.get("model", OpenAIGenerator.DEFAULT_MODEL),
+            api_key=gen_cfg.get("api_key"),
+        )
+        if gen_cfg
+        else None
+    )
+
+    storage_dir = config.get("storage", {}).get("dir", ".")
+    return SimasiaGuard(
+        brand_id,
+        artifact_dir=storage_dir,
+        embedding_model=embedder,
+        generator=generator,
+    )
+
+
+def resolve_side(training: dict, side: str) -> str | list[str] | None:
+    """Resolve one training side to raw text or a URL list.
+
+    Accepts ``<side>_text`` (inline), ``<side>_file`` (path to a .txt), or
+    ``<side>_urls`` (list). Returns ``None`` when the side is not configured.
+    """
+    if f"{side}_urls" in training:
+        return list(training[f"{side}_urls"])
+    if f"{side}_file" in training:
+        return Path(training[f"{side}_file"]).read_text(encoding="utf-8")
+    if f"{side}_text" in training:
+        return training[f"{side}_text"]
+    return None
+
+
+def run_training(config: dict) -> float:
+    """Build a guard from config and train it. Returns training accuracy."""
+    guard = build_guard(config)
+    training = config["training"]
+
+    on_brand = resolve_side(training, "on_brand")
+    if on_brand is None:
+        raise ValueError(
+            "config [training] needs on_brand_text, on_brand_file, or on_brand_urls."
+        )
+    off_brand = resolve_side(training, "off_brand")
+    return guard.train(on_brand, off_brand)

simasia/embeddings.py

@@ -0,0 +1,98 @@
+"""Pluggable embedding backends for Simasia.
+
+A backend is anything satisfying :class:`EmbeddingModel` — an object with an
+``encode(list[str]) -> np.ndarray`` method.  ``OpenAIEmbedder`` is the default
+used by :class:`~simasia.guard.SimasiaGuard`; ``LocalEmbedder`` keeps the
+original offline sentence-transformer path available for consumers who install
+the ``local`` extra.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Protocol
+
+import numpy as np
+
+
+class EmbeddingModel(Protocol):
+    """Minimal interface required from an embedding backend."""
+
+    def encode(self, sentences: list[str], **kwargs: object) -> np.ndarray: ...
+
+
+class OpenAIEmbedder:
+    """Embed text with an OpenAI embedding model (default backend).
+
+    The API key is read from the ``EMBEDDING_KEY`` environment variable unless
+    passed explicitly.  ``dimensions`` is forwarded to the API to shorten the
+    output vector when the model supports it (``text-embedding-3-*`` do).
+    A pre-built ``client`` may be injected for testing.
+    """
+
+    DEFAULT_MODEL = "text-embedding-3-small"
+
+    def __init__(
+        self,
+        model: str = DEFAULT_MODEL,
+        api_key: str | None = None,
+        dimensions: int | None = None,
+        client: object | None = None,
+    ) -> None:
+        self.model = model
+        self.dimensions = dimensions
+        if client is None:
+            api_key = api_key or os.environ.get("EMBEDDING_KEY")
+            if not api_key:
+                raise ValueError(
+                    "No OpenAI API key found. Set the EMBEDDING_KEY environment "
+                    "variable or pass api_key=..."
+                )
+            try:
+                from openai import OpenAI
+            except ImportError as exc:  # pragma: no cover - import guard
+                raise ImportError(
+                    "OpenAIEmbedder requires the 'openai' package. "
+                    "Install it with: pip install simasia[openai]"
+                ) from exc
+            client = OpenAI(api_key=api_key)
+        self._client = client
+
+    def encode(self, sentences: list[str], **_kwargs: object) -> np.ndarray:
+        request: dict[str, object] = {"model": self.model, "input": list(sentences)}
+        if self.dimensions is not None:
+            request["dimensions"] = self.dimensions
+        response = self._client.embeddings.create(**request)
+        return np.asarray([item.embedding for item in response.data], dtype=np.float32)
+
+
+class LocalEmbedder:
+    """Embed text with a local, frozen sentence-transformer (offline backend).
+
+    Defaults to ``BAAI/bge-small-en-v1.5`` loaded strictly from the local cache,
+    so training and inference run on CPU without network access.  Pass a
+    pre-loaded ``model`` to reuse a cached instance or to inject a fake.
+    """
+
+    DEFAULT_MODEL_NAME = "BAAI/bge-small-en-v1.5"
+
+    def __init__(
+        self,
+        model_name: str = DEFAULT_MODEL_NAME,
+        local_files_only: bool = True,
+        model: object | None = None,
+    ) -> None:
+        if model is None:
+            try:
+                from sentence_transformers import SentenceTransformer
+            except ImportError as exc:  # pragma: no cover - import guard
+                raise ImportError(
+                    "LocalEmbedder requires the 'sentence-transformers' package. "
+                    "Install it with: pip install simasia[local]"
+                ) from exc
+            model = SentenceTransformer(model_name, local_files_only=local_files_only)
+        self._model = model
+
+    def encode(self, sentences: list[str], **_kwargs: object) -> np.ndarray:
+        embeddings = self._model.encode(list(sentences), convert_to_numpy=True)
+        return np.asarray(embeddings, dtype=np.float32)

simasia/generation.py

@@ -0,0 +1,68 @@
+"""Pluggable text-generation backend for Simasia.
+
+Used at training time to turn each on-brand chunk into an off-brand "opposite"
+sample, so a brand can be calibrated from on-brand text alone.  A backend is
+anything with a ``generate(prompt) -> str`` method; ``OpenAIGenerator`` is the
+default.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Protocol
+
+
+class GenerationModel(Protocol):
+    """Minimal interface required from a generation backend."""
+
+    def generate(self, prompt: str) -> str: ...
+
+
+class OpenAIGenerator:
+    """Generate text with an OpenAI chat model (default backend).
+
+    The API key is read from ``GENERATION_KEY``, falling back to ``EMBEDDING_KEY``,
+    unless passed explicitly.  ``model`` defaults to a small, cheap model since the
+    opposite-example step is meant to be lightweight.  A pre-built ``client`` may
+    be injected for testing.
+    """
+
+    DEFAULT_MODEL = "gpt-4o-mini"
+
+    def __init__(
+        self,
+        model: str = DEFAULT_MODEL,
+        api_key: str | None = None,
+        temperature: float = 0.7,
+        client: object | None = None,
+    ) -> None:
+        self.model = model
+        self.temperature = temperature
+        if client is None:
+            api_key = (
+                api_key
+                or os.environ.get("GENERATION_KEY")
+                or os.environ.get("EMBEDDING_KEY")
+            )
+            if not api_key:
+                raise ValueError(
+                    "No OpenAI API key found. Set GENERATION_KEY (or EMBEDDING_KEY) "
+                    "or pass api_key=..."
+                )
+            try:
+                from openai import OpenAI
+            except ImportError as exc:  # pragma: no cover - import guard
+                raise ImportError(
+                    "OpenAIGenerator requires the 'openai' package. "
+                    "Install it with: pip install simasia[openai]"
+                ) from exc
+            client = OpenAI(api_key=api_key)
+        self._client = client
+
+    def generate(self, prompt: str) -> str:
+        response = self._client.chat.completions.create(
+            model=self.model,
+            messages=[{"role": "user", "content": prompt}],
+            temperature=self.temperature,
+        )
+        return (response.choices[0].message.content or "").strip()

simasia/guard.py

@@ -0,0 +1,357 @@
+"""The embedding-plus-classification pipeline used by Simasia."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+from sklearn.linear_model import LogisticRegression
+
+from .embeddings import EmbeddingModel, OpenAIEmbedder
+from .generation import GenerationModel, OpenAIGenerator
+from .sources import build_corpus, fetch_url_text
+from .storage import ArtifactStore, FileArtifactStore
+
+ARTIFACT_FORMAT = "simasia-head/2"
+
+OPPOSITE_PROMPT = (
+    "Rewrite the text below so it has the OPPOSITE tone and voice, while keeping a "
+    "similar topic and length. Return only the rewritten text, with no preamble.\n\n"
+    "Text: {chunk}"
+)
+
+
+class SimasiaGuard:
+    """Classify short LLM responses as matching a brand's tone or not.
+
+    The embedding backend is frozen and pluggable (OpenAI by default; see
+    :mod:`simasia.embeddings`); only the small per-brand logistic-regression
+    head is fitted.  The persisted artifact
+    (``simasia_<brand_id>_head.joblib``) also stores the training chunks and
+    their embeddings so :meth:`explain` can ground a verdict in the brand's own
+    on-brand and off-brand samples.
+    """
+
+    def __init__(
+        self,
+        brand_id: str,
+        artifact_dir: str | os.PathLike[str] = ".",
+        embedding_model: EmbeddingModel | None = None,
+        store: ArtifactStore | None = None,
+        generator: GenerationModel | None = None,
+    ) -> None:
+        """Initialize a guard for ``brand_id``.
+
+        ``embedding_model`` defaults to :class:`~simasia.embeddings.OpenAIEmbedder`
+        (``text-embedding-3-small``, key from the ``EMBEDDING_KEY`` environment
+        variable).  Pass any object implementing ``encode`` to choose a different
+        model, supply your own key/dimensions, or run fully offline via
+        :class:`~simasia.embeddings.LocalEmbedder`.
+
+        ``store`` decides where the trained artifact lives.  It defaults to
+        :class:`~simasia.storage.FileArtifactStore` writing under ``artifact_dir``;
+        pass a custom :class:`~simasia.storage.ArtifactStore` to use a database or
+        object store instead.
+        """
+        if not brand_id or not brand_id.strip():
+            raise ValueError("brand_id must be a non-empty string")
+
+        self.brand_id = brand_id
+        self.store: ArtifactStore = store or FileArtifactStore(artifact_dir)
+        self.embedding_model: EmbeddingModel = embedding_model or OpenAIEmbedder()
+        # Created lazily only if opposite generation is actually needed.
+        self.generator: GenerationModel | None = generator
+        self.classifier: LogisticRegression | None = None
+        self.on_chunks: list[str] | None = None
+        self.on_embeddings: np.ndarray | None = None
+        self.off_chunks: list[str] | None = None
+        self.off_embeddings: np.ndarray | None = None
+
+    def _chunk_text(self, raw_text: str, sentences_per_chunk: int = 2) -> list[str]:
+        """Return overlapping sentence windows suitable for tone training.
+
+        A chunk is retained only when the complete window has at least four words.
+        This avoids discarding useful short sentences when they form a meaningful
+        two-sentence sample with their neighbour.
+        """
+        if sentences_per_chunk < 1:
+            raise ValueError("sentences_per_chunk must be at least 1")
+        if not isinstance(raw_text, str):
+            raise TypeError("raw_text must be a string")
+
+        cleaned = re.sub(r"\s+", " ", raw_text).strip()
+        if not cleaned:
+            return []
+        sentences = [
+            sentence.strip()
+            for sentence in re.split(r"(?<=[.!?])\s+", cleaned)
+            if sentence.strip()
+        ]
+
+        return [
+            " ".join(sentences[index : index + sentences_per_chunk])
+            for index in range(len(sentences) - sentences_per_chunk + 1)
+            if len(" ".join(sentences[index : index + sentences_per_chunk]).split()) >= 4
+        ]
+
+    def train(
+        self,
+        on_brand: str | Path | list[str],
+        off_brand: str | Path | list[str] | None = None,
+    ) -> float:
+        """Train the brand model (the main training entry point).
+
+        Each side accepts raw text (``str``), a file path (``pathlib.Path``, read
+        as text), or a list of URLs (``list[str]``). If ``off_brand`` is omitted, an
+        off-brand opposite is generated for each on-brand chunk with the generation
+        backend (see :meth:`calibrate_from_on_brand`). Returns training accuracy.
+        """
+        if off_brand is None:
+            return self.calibrate_from_on_brand(on_brand)
+        return self.calibrate_weights(self._to_corpus(on_brand), self._to_corpus(off_brand))
+
+    def calibrate_from_on_brand(self, on_brand: str | Path | list[str]) -> float:
+        """Train from on-brand text alone, generating each off-brand opposite.
+
+        The on-brand corpus (raw text, a file path, or a list of URLs) is chunked,
+        and the generation backend rewrites each chunk into an off-brand opposite.
+        Both sets are then embedded, labelled, and fitted like any other run.
+        """
+        on_chunks = self._chunk_text(self._to_corpus(on_brand))
+        if not on_chunks:
+            raise ValueError("Training input contains insufficient sentences to extract tone.")
+        off_chunks = self._generate_opposites(on_chunks)
+        return self._fit(on_chunks, off_chunks)
+
+    @staticmethod
+    def _to_corpus(source: str | Path | list[str]) -> str:
+        """Resolve a training source to raw text.
+
+        ``Path`` is read as a text file, ``list``/``tuple`` is fetched as URLs, and
+        ``str`` is used as-is (raw text — never treated as a path, to avoid guessing).
+        """
+        if isinstance(source, Path):
+            return source.read_text(encoding="utf-8")
+        if isinstance(source, (list, tuple)):
+            return build_corpus(list(source))
+        if isinstance(source, str):
+            return source
+        raise TypeError(
+            "Training source must be str (raw text), pathlib.Path (a file), or "
+            "list[str] (URLs)."
+        )
+
+    def _generate_opposites(self, on_chunks: list[str]) -> list[str]:
+        """Rewrite each on-brand chunk into an off-brand opposite via the LLM."""
+        if self.generator is None:
+            self.generator = OpenAIGenerator()
+        opposites: list[str] = []
+        for chunk in on_chunks:
+            opposite = self.generator.generate(OPPOSITE_PROMPT.format(chunk=chunk)).strip()
+            if not opposite:
+                raise ValueError("Generation backend returned an empty opposite example.")
+            opposites.append(opposite)
+        return opposites
+
+    def calibrate_from_urls(
+        self,
+        on_brand_urls: list[str],
+        off_brand_urls: list[str],
+        fetcher: Callable[[str], str] = fetch_url_text,
+    ) -> float:
+        """Train from URLs: fetch and extract each page, then calibrate.
+
+        Every on-brand URL's extracted text is concatenated into one corpus, and
+        likewise for off-brand, before the usual chunking and fitting.  ``fetcher``
+        is injectable for testing or for supplying pre-fetched content.
+        """
+        on_brand_raw = build_corpus(on_brand_urls, fetcher=fetcher)
+        off_brand_raw = build_corpus(off_brand_urls, fetcher=fetcher)
+        return self.calibrate_weights(on_brand_raw, off_brand_raw)
+
+    def calibrate_weights(self, on_brand_raw: str, off_brand_raw: str) -> float:
+        """Fit and persist the brand-specific logistic-regression head.
+
+        On-brand and off-brand corpora are chunked independently and labelled
+        1/0; the counts need not match.  The chunks and their embeddings are
+        persisted alongside the head so verdicts can be explained against real
+        samples.  Returns training accuracy.
+        """
+        on_chunks = self._chunk_text(on_brand_raw)
+        off_chunks = self._chunk_text(off_brand_raw)
+        if not on_chunks or not off_chunks:
+            raise ValueError("Training inputs contain insufficient sentences to extract tone.")
+        return self._fit(on_chunks, off_chunks)
+
+    def _fit(self, on_chunks: list[str], off_chunks: list[str]) -> float:
+        """Embed labelled chunks, fit the head, persist the artifact, return accuracy."""
+        text_samples = on_chunks + off_chunks
+        labels = np.concatenate(
+            (np.ones(len(on_chunks), dtype=np.int64), np.zeros(len(off_chunks), dtype=np.int64))
+        )
+        embeddings = self._encode(text_samples)
+
+        self.classifier = LogisticRegression(class_weight="balanced", max_iter=1000)
+        self.classifier.fit(embeddings, labels)
+
+        self.on_chunks = on_chunks
+        self.off_chunks = off_chunks
+        self.on_embeddings = embeddings[: len(on_chunks)]
+        self.off_embeddings = embeddings[len(on_chunks) :]
+
+        self.store.save(
+            self.brand_id,
+            {
+                "format": ARTIFACT_FORMAT,
+                "classifier": self.classifier,
+                "on_chunks": self.on_chunks,
+                "off_chunks": self.off_chunks,
+                "on_embeddings": self.on_embeddings,
+                "off_embeddings": self.off_embeddings,
+            },
+        )
+        return float(self.classifier.score(embeddings, labels))
+
+    def evaluate_response(self, llm_generated_text: str) -> float:
+        """Return the probability that a live response is on-brand."""
+        text = self._validate_response(llm_generated_text)
+        self._load_artifact()
+        embedding = self._encode([text])
+        return self._on_brand_probability(embedding)
+
+    def explain(self, llm_generated_text: str) -> dict[str, object]:
+        """Score a response and ground the verdict in the brand's own samples.
+
+        Returns the on-brand probability plus the nearest on-brand and off-brand
+        training chunks (by cosine similarity) — the concrete text the response
+        reads most and least like. No generative model is involved.
+        """
+        text = self._validate_response(llm_generated_text)
+        self._load_artifact()
+        if self.on_embeddings is None or self.off_embeddings is None:
+            raise ValueError(
+                f"Artifact for brand '{self.brand_id}' has no stored exemplars. "
+                "Retrain with calibrate_weights/calibrate_from_urls to enable explain()."
+            )
+
+        embedding = self._encode([text])
+        score = self._on_brand_probability(embedding)
+        query = embedding[0]
+        return {
+            "score": score,
+            "verdict": "on-brand" if score >= 0.5 else "off-brand",
+            "closest_on_brand": self._nearest(query, self.on_embeddings, self.on_chunks),
+            "closest_off_brand": self._nearest(query, self.off_embeddings, self.off_chunks),
+        }
+
+    def refine(
+        self,
+        generate: Callable[[str | None], str],
+        threshold: float = 0.7,
+        max_attempts: int = 4,
+    ) -> dict[str, object]:
+        """Regenerate a response until it scores on-brand, using explain feedback.
+
+        ``generate(feedback)`` is your LLM call: on the first attempt ``feedback``
+        is ``None``; after a low score it receives a plain-text hint built from the
+        nearest off-brand and on-brand samples. Stops as soon as a response reaches
+        ``threshold``; otherwise returns the best attempt after ``max_attempts``.
+
+        Returns ``{"text", "score", "passed", "attempts"}``.
+        """
+        if not callable(generate):
+            raise TypeError("generate must be callable")
+        if max_attempts < 1:
+            raise ValueError("max_attempts must be at least 1")
+
+        best: dict[str, object] | None = None
+        feedback: str | None = None
+        for attempt in range(1, max_attempts + 1):
+            text = generate(feedback)
+            result = self.explain(text)
+            score = float(result["score"])
+            if best is None or score > float(best["score"]):
+                best = {"text": text, "score": score}
+            if score >= threshold:
+                return {**best, "passed": True, "attempts": attempt}
+            feedback = self._build_feedback(result)
+
+        return {**best, "passed": False, "attempts": max_attempts}
+
+    @staticmethod
+    def _build_feedback(result: dict[str, object]) -> str:
+        """Turn an explain() result into a hint for the next generation."""
+        off = result["closest_off_brand"]["text"]
+        on = result["closest_on_brand"]["text"]
+        return (
+            f"That response scored {float(result['score']):.2f} on-brand (too low). "
+            f'It sounds too much like this off-brand sample: "{off}". '
+            f'Rewrite it to sound more like this on-brand sample: "{on}".'
+        )
+
+    def _nearest(
+        self, query: np.ndarray, matrix: np.ndarray, chunks: list[str]
+    ) -> dict[str, object]:
+        """Return the chunk in ``matrix`` most similar to ``query``."""
+        similarities = self._cosine_similarity(query, matrix)
+        best = int(np.argmax(similarities))
+        return {"text": chunks[best], "similarity": float(similarities[best])}
+
+    @staticmethod
+    def _cosine_similarity(query: np.ndarray, matrix: np.ndarray) -> np.ndarray:
+        """Cosine similarity between one vector and each row of ``matrix``."""
+        query_norm = query / (np.linalg.norm(query) + 1e-12)
+        matrix_norm = matrix / (np.linalg.norm(matrix, axis=1, keepdims=True) + 1e-12)
+        return matrix_norm @ query_norm
+
+    def _on_brand_probability(self, embedding: np.ndarray) -> float:
+        """Probability of the on-brand class for an already-encoded sample."""
+        assert self.classifier is not None  # set by _load_artifact
+        probabilities = self.classifier.predict_proba(embedding)
+        on_brand_index = int(np.where(self.classifier.classes_ == 1)[0][0])
+        return float(probabilities[0, on_brand_index])
+
+    @staticmethod
+    def _validate_response(llm_generated_text: str) -> str:
+        if not isinstance(llm_generated_text, str) or not llm_generated_text.strip():
+            raise ValueError("llm_generated_text must be a non-empty string")
+        return llm_generated_text
+
+    def _load_artifact(self) -> None:
+        """Load the persisted head (and exemplars, if present) once per process.
+
+        Supports both the current dict artifact and legacy files that stored a
+        bare ``LogisticRegression``; legacy files load without exemplars.
+        """
+        if self.classifier is not None:
+            return
+        loaded = self.store.load(self.brand_id)
+        if loaded is None:
+            raise FileNotFoundError(
+                f"No trained artifact for brand '{self.brand_id}'. Call "
+                "calibrate_weights or calibrate_from_urls first."
+            )
+        if isinstance(loaded, dict):
+            self.classifier = loaded["classifier"]
+            self.on_chunks = loaded.get("on_chunks")
+            self.off_chunks = loaded.get("off_chunks")
+            self.on_embeddings = loaded.get("on_embeddings")
+            self.off_embeddings = loaded.get("off_embeddings")
+        else:  # legacy: bare classifier, no exemplars
+            self.classifier = loaded
+
+    def _encode(self, text_samples: list[str]) -> np.ndarray:
+        """Embed text and validate the returned sample matrix.
+
+        The embedding dimension is model-dependent and no longer fixed; sklearn
+        enforces train/inference consistency, so we only check the matrix shape.
+        """
+        embeddings = np.asarray(
+            self.embedding_model.encode(text_samples, convert_to_numpy=True), dtype=np.float32
+        )
+        if embeddings.ndim != 2 or embeddings.shape[0] != len(text_samples):
+            raise ValueError("Embedding model returned an invalid sample matrix.")
+        return embeddings

simasia/sources.py

@@ -0,0 +1,52 @@
+"""Turn training URLs into a single text corpus.
+
+Fetching a page is easy; extracting *clean* prose (no nav, cookie banners,
+footers, or ads) is the hard part, so this delegates both steps to
+``trafilatura`` rather than hand-rolling an HTML reader.  Each URL's extracted
+article text is concatenated into one corpus, which the guard then chunks
+normally — a page's content is raw material, never a single chunk.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+CORPUS_SEPARATOR = "\n\n"
+
+
+def fetch_url_text(url: str) -> str:
+    """Download ``url`` and return its main article text.
+
+    Raises ``ValueError`` when the page cannot be downloaded or yields no
+    extractable content, so a dead link never silently contributes an empty
+    sample to training.
+    """
+    try:
+        import trafilatura
+    except ImportError as exc:  # pragma: no cover - import guard
+        raise ImportError(
+            "URL training requires the 'trafilatura' package. "
+            "Install it with: pip install simasia[urls]"
+        ) from exc
+
+    downloaded = trafilatura.fetch_url(url)
+    if downloaded is None:
+        raise ValueError(f"Could not download URL: {url!r}")
+    text = trafilatura.extract(downloaded)
+    if not text or not text.strip():
+        raise ValueError(f"No extractable text content at URL: {url!r}")
+    return text.strip()
+
+
+def build_corpus(
+    urls: list[str],
+    fetcher: Callable[[str], str] = fetch_url_text,
+) -> str:
+    """Fetch every URL and join the results into one corpus string.
+
+    ``fetcher`` is injectable so callers can supply cached content or a stub in
+    tests without network access.
+    """
+    if not urls:
+        raise ValueError("At least one URL is required.")
+    return CORPUS_SEPARATOR.join(fetcher(url) for url in urls)

simasia/storage.py

@@ -0,0 +1,60 @@
+"""Where a brand's trained artifact is saved and loaded.
+
+The guard talks to this seam instead of touching the filesystem directly, so a
+database or object-store backend is a drop-in later: implement the three
+``ArtifactStore`` methods and pass it to :class:`~simasia.guard.SimasiaGuard`.
+``FileArtifactStore`` is the default and keeps the original on-disk behaviour.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+from pathlib import Path
+from typing import Protocol
+
+import joblib
+
+
+class ArtifactStore(Protocol):
+    """Reads and writes one artifact per brand."""
+
+    def save(self, brand_id: str, artifact: object) -> None: ...
+    def load(self, brand_id: str) -> object | None: ...
+    def exists(self, brand_id: str) -> bool: ...
+
+
+def serialize_artifact(artifact: object) -> bytes:
+    """Turn an artifact into bytes for storing in a DB blob (or anywhere)."""
+    buffer = io.BytesIO()
+    joblib.dump(artifact, buffer)
+    return buffer.getvalue()
+
+
+def deserialize_artifact(blob: bytes) -> object:
+    """Rebuild an artifact from bytes produced by :func:`serialize_artifact`."""
+    return joblib.load(io.BytesIO(blob))
+
+
+class FileArtifactStore:
+    """Save each brand's artifact as ``simasia_<brand_id>_head.joblib``."""
+
+    def __init__(self, artifact_dir: str | os.PathLike[str] = ".") -> None:
+        self.artifact_dir = Path(artifact_dir)
+
+    def path_for(self, brand_id: str) -> Path:
+        return self.artifact_dir / f"simasia_{brand_id}_head.joblib"
+
+    def save(self, brand_id: str, artifact: object) -> None:
+        path = self.path_for(brand_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        joblib.dump(artifact, path)
+
+    def load(self, brand_id: str) -> object | None:
+        path = self.path_for(brand_id)
+        if not path.exists():
+            return None
+        return joblib.load(path)
+
+    def exists(self, brand_id: str) -> bool:
+        return self.path_for(brand_id).exists()

simasia-0.2.0.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: simasia
+Version: 0.2.0
+Summary: Per-brand tone guardrail for LLM responses via pluggable embeddings and a small logistic-regression head.
+Author-email: Armstrong Olusoji <armstrongolusoji9@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Armstrong2035/simasia
+Project-URL: Repository, https://github.com/Armstrong2035/simasia
+Project-URL: Changelog, https://github.com/Armstrong2035/simasia/blob/main/CHANGELOG.md
+Keywords: llm,brand-voice,tone,guardrail,embeddings,classification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: joblib>=1.3.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: tomli>=2.0.0; python_version < "3.11"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: local
+Requires-Dist: sentence-transformers>=3.0.0; extra == "local"
+Provides-Extra: urls
+Requires-Dist: trafilatura>=1.6.0; extra == "urls"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Dynamic: license-file
+
+# Simasia Tone Guardrail
+
+Simasia scores how closely an LLM response matches a brand's tone of voice. It
+pairs a **frozen, pluggable embedding backend** with a small per-brand
+`LogisticRegression` head. The fitted head is stored in
+`simasia_<brand_id>_head.joblib`, **along with the training chunks and their
+embeddings** — these let `explain()` ground a verdict in the brand's own samples.
+(If your training text is sensitive, note that it is written into that artifact.)
+
+Version history is in [CHANGELOG.md](CHANGELOG.md).
+
+## Quick start
+
+Two methods: **`train`** once per brand, then **`refine`** in your response pipeline.
+
+```python
+from simasia import SimasiaGuard
+
+guard = SimasiaGuard(brand_id="fintech_core")   # key from EMBEDDING_KEY
+
+# 1. Train once from ON-BRAND text only. For each on-brand chunk, a lightweight
+#    LLM writes an off-brand opposite to train against (key: GENERATION_KEY, or
+#    it falls back to EMBEDDING_KEY). Pass URLs instead of text if you prefer.
+guard.train(on_brand="We build automated investment tools. They work fast.")
+
+# Or supply both sides yourself and skip the LLM step entirely:
+# guard.train(on_brand="...", off_brand="...")
+
+# 2. Wire into the pipeline: keep regenerating until the reply is on-brand.
+def generate(feedback):
+    prompt = "Reply to the customer about their late transfer."
+    if feedback:                 # a hint from the previous low-scoring attempt
+        prompt += "\n\n" + feedback
+    return my_llm(prompt)        # your LLM call
+
+result = guard.refine(generate, threshold=0.7, max_attempts=4)
+print(result)  # {"text": "...", "score": 0.82, "passed": True, "attempts": 2}
+```
+
+## Config-file usage (no code)
+
+Prefer not to write Python? Configure once, then run one command.
+
+1. `pip install "simasia[openai]"`
+2. Copy `.env.example` → `.env.local`, add your key (`EMBEDDING_KEY=...`). It's gitignored — keys never go in the committed config.
+3. Copy `simasia.example.toml` → `simasia.toml`, set your brand and training source.
+4. Train, then score:
+
+```bash
+simasia train                       # reads simasia.toml + .env.local
+simasia score "Hey! Quick heads up about your transfer."
+simasia explain "Kindly be advised your request is under review."
+```
+
+`simasia train --config path/to/other.toml` points at a different config.
+
+## Install
+
+The package is parametric — install only the backend you want:
+
+```bash
+pip install .[openai]          # default backend: OpenAI text-embedding-3-small
+pip install .[urls]            # train from URLs (fetch + clean-text extraction)
+pip install .[local]           # offline backend: frozen sentence-transformer, CPU
+pip install .[openai,urls,test]  # a typical dev setup
+```
+
+`requirements.txt` is a quick-start shortcut for the OpenAI + URLs combination.
+
+## Choosing an embedding backend
+
+The backend is any object with an `encode(list[str]) -> np.ndarray` method
+(`EmbeddingModel`). The default is OpenAI, with the API key read from the
+`EMBEDDING_KEY` environment variable:
+
+```python
+from simasia import SimasiaGuard, OpenAIEmbedder, LocalEmbedder
+
+# Default: OpenAIEmbedder(), key from EMBEDDING_KEY
+guard = SimasiaGuard(brand_id="fintech_core")
+
+# Pick a model / shorten the vector / pass a key explicitly
+guard = SimasiaGuard(
+    brand_id="fintech_core",
+    embedding_model=OpenAIEmbedder(model="text-embedding-3-small", dimensions=512),
+)
+
+# Fully offline (no network, CPU) — requires the `local` extra and a cached model
+guard = SimasiaGuard(brand_id="fintech_core", embedding_model=LocalEmbedder())
+```
+
+## Training
+
+`train(on_brand, off_brand=None)` is the one entry point. Each side accepts three
+source types, and you can mix them:
+
+```python
+guard.train("We build automated investment tools. They work fast.")  # str  -> raw text
+guard.train(Path("brand_voice.txt"))                                 # Path -> read file
+guard.train(["https://brand.example/voice", "https://brand.example/blog"])  # list -> URLs
+```
+
+A `str` is always raw text (never guessed as a path); use `Path` for a file. URLs
+are fetched and reduced to clean article text, then all on-brand pages are
+concatenated into one corpus (same for off-brand) before chunking.
+
+**On-brand only (opposites generated).** Omit `off_brand` and a lightweight LLM
+writes an off-brand opposite for each on-brand chunk (key: `GENERATION_KEY`, or it
+falls back to `EMBEDDING_KEY`):
+
+```python
+guard.train(on_brand="We build automated investment tools. They work fast.")
+```
+
+**Both sides supplied (no LLM).** Pass both to skip generation entirely:
+
+```python
+guard.train(
+    on_brand="We build automated investment tools. They work fast.",
+    off_brand="Our enterprise architecture processes asset allocations. "
+              "Systems experience transactional delay cycles.",
+)
+```
+
+The lower-level `calibrate_weights` (raw text) and `calibrate_from_urls` (URLs)
+methods remain available if you want to call them directly.
+
+## Scoring live responses
+
+```python
+score = guard.evaluate_response("Hey! Let's get your account squared away right now.")
+print(score)  # probability in [0, 1] that the text is on-brand
+```
+
+## Explaining a verdict
+
+`explain()` returns the score plus the nearest on-brand and off-brand training
+chunks — the concrete text the response reads most and least like. No generative
+model is involved; the "reason" is retrieved from the brand's own samples.
+
+```python
+result = guard.explain("Kindly be advised your request is under review.")
+# {
+#   "score": 0.21,
+#   "verdict": "off-brand",
+#   "closest_on_brand":  {"text": "We build automated tools...", "similarity": 0.44},
+#   "closest_off_brand": {"text": "Systems experience delay cycles.", "similarity": 0.73},
+# }
+```
+
+## Steering a response on-brand
+
+`refine()` keeps asking your LLM for a response until it scores on-brand. You pass
+a `generate(feedback)` function; the first call gets `feedback=None`, and after a
+low score it gets a plain-text hint built from the nearest off/on-brand samples.
+
+```python
+def generate(feedback):
+    prompt = "Reply to the customer."
+    if feedback:
+        prompt += "\n\n" + feedback   # explain()-based hint
+    return my_llm(prompt)
+
+result = guard.refine(generate, threshold=0.7, max_attempts=4)
+# {"text": "...", "score": 0.82, "passed": True, "attempts": 2}
+```
+
+## Where the artifact is stored
+
+By default the artifact is a file (`FileArtifactStore`). For production (many
+servers, containers, serverless) put it in shared storage instead — your own
+database or an S3/GCS bucket. Implement `ArtifactStore` (`save`, `load`,
+`exists`) and pass it in; nothing in the guard changes.
+
+Use `serialize_artifact` / `deserialize_artifact` so your store only handles
+bytes. Example against any DB (shown with SQLite):
+
+```python
+import sqlite3
+from simasia import SimasiaGuard, serialize_artifact, deserialize_artifact
+
+class SQLiteStore:
+    def __init__(self, conn):
+        self.conn = conn
+        conn.execute("CREATE TABLE IF NOT EXISTS simasia (brand TEXT PRIMARY KEY, blob BLOB)")
+
+    def save(self, brand_id, artifact):
+        self.conn.execute(
+            "REPLACE INTO simasia (brand, blob) VALUES (?, ?)",
+            (brand_id, serialize_artifact(artifact)),
+        )
+        self.conn.commit()
+
+    def load(self, brand_id):
+        row = self.conn.execute(
+            "SELECT blob FROM simasia WHERE brand = ?", (brand_id,)
+        ).fetchone()
+        return deserialize_artifact(row[0]) if row else None
+
+    def exists(self, brand_id):
+        return self.conn.execute(
+            "SELECT 1 FROM simasia WHERE brand = ?", (brand_id,)
+        ).fetchone() is not None
+
+guard = SimasiaGuard(brand_id="fintech_core", store=SQLiteStore(sqlite3.connect("brands.db")))
+```

simasia-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+simasia/__init__.py,sha256=KfucTbTHknLm-j4gjsx0wfu0NizDYYj72fV4HL1y1yk,584
+simasia/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+simasia/cli.py,sha256=BdeNq2sA_0qavrKjeSjNh401hwPlA3f5uVpsXc8_RNE,2108
+simasia/config.py,sha256=vusGbduWJw9hXFE5qoYJkxt-c2GMKQ-7c6q8UjIvPn0,3826
+simasia/embeddings.py,sha256=j0caLtv2EnvEoDLq-Wob3S8kXPB5UcUn6MpklC9O9-A,3752
+simasia/generation.py,sha256=obagUYRDw0FeFHPlMRiFKzpxs0fhOC11n7yJZ__GkOM,2312
+simasia/guard.py,sha256=SpxmhB3641mguMGhEeQCR4S7rqm_siK86Cnvz2KUY-Q,15905
+simasia/sources.py,sha256=ZzSoHaPoijASYaD3yzEGDvergIbCQVJFXeyExxeKVOM,1801
+simasia/storage.py,sha256=3kamnWJs_bpC343I824fEYxhpqSrlwTL2OscLzihSB4,1954
+simasia-0.2.0.dist-info/licenses/LICENSE,sha256=7BxXjkZsF8T3LbDpuLSWkVk2t37M2Q9fZFjcVCXBmLU,1074
+simasia-0.2.0.dist-info/METADATA,sha256=FXki6-TlQllqOUrguHQ3MdPsHypcmFXvXG-bu_Vub84,9356
+simasia-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+simasia-0.2.0.dist-info/entry_points.txt,sha256=4aSQpn3TyMEXo5YKznHD0-vw844c0FOv2XqBluxzByU,45
+simasia-0.2.0.dist-info/top_level.txt,sha256=e6v7s5eLYDIFWV9ksnrlGkhT1esBb-i7UXqwiaP7RD4,8
+simasia-0.2.0.dist-info/RECORD,,

simasia-0.2.0.dist-info/WHEEL

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

simasia-0.2.0.dist-info/entry_points.txt

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

simasia-0.2.0.dist-info/licenses/LICENSE

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

simasia-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simasia