simasia 0.2.0__tar.gz

simasia-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,206 @@
+# 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/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simasia"
+version = "0.2.0"
+description = "Per-brand tone guardrail for LLM responses via pluggable embeddings and a small logistic-regression head."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Armstrong Olusoji", email = "armstrongolusoji9@gmail.com" }]
+keywords = ["llm", "brand-voice", "tone", "guardrail", "embeddings", "classification"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "scikit-learn>=1.3.0",
+    "joblib>=1.3.0",
+    "numpy>=1.24.0",
+    "tomli>=2.0.0; python_version < '3.11'",
+]
+
+[project.scripts]
+simasia = "simasia.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Armstrong2035/simasia"
+Repository = "https://github.com/Armstrong2035/simasia"
+Changelog = "https://github.com/Armstrong2035/simasia/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+# Default embedding backend (OpenAI, text-embedding-3-small).
+openai = ["openai>=1.0.0"]
+# Offline embedding backend (frozen sentence-transformer, CPU).
+local = ["sentence-transformers>=3.0.0"]
+# URL-based training data (fetch + clean-text extraction).
+urls = ["trafilatura>=1.6.0"]
+# Everything needed to run the tests.
+test = ["pytest>=7.0.0"]
+
+[tool.setuptools.packages.find]
+include = ["simasia*"]

simasia-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simasia-0.2.0/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-0.2.0/simasia/__main__.py

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

simasia-0.2.0/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())