trooth 0.2.0__tar.gz → 0.4.0__tar.gz

{trooth-0.2.0 → trooth-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trooth
-Version: 0.2.0
+Version: 0.4.0
 Summary: Read a company's Semanto signed copy and check it: signatures, keys, DNS binding, page proofs and the public log.
 Author: Trooth, LLC
 License-Expression: Apache-2.0
@@ -94,6 +94,12 @@ from trooth import SemantoSource
 acme = SemantoSource("acme.com", on_event=lambda e: print(e["event"], e["detail"]))
 a = acme.answer(question="How much is the Starter plan?")
 print(a["status"], a["text"])
+
+r = acme.reply(question=user_question, draft=model_text)  # built by code; the draft is discarded
+show(r["text"])
+
+r = acme.respond(question=user_question, draft=model_text)  # follows the company's answer mode
+show(r["text"])  # Audit mode also returns r["audit"]: supported, differs, marked, not_in_record or not_checked
 ```
 
 It loads `/.well-known/trooth.semanto` and the company's keys from the company's site, checks the file once for each new body, reads the site again at most every 15 minutes, and answers fact IDs and plain questions in process with the same matcher as Trooth's service (`trooth_semanto_verify.answer`, compared case by case with `verifier/test-vectors/answer-v1`). When Trooth's API cannot be reached it keeps answering from the last version that checked out and logs `trooth_api_unreachable`; a new version that does not check out is refused and the last good one stays in use. A fact marked changed since signing or expired returns its mark and no value.

{trooth-0.2.0 → trooth-0.4.0}/README.md

@@ -64,6 +64,12 @@ from trooth import SemantoSource
 acme = SemantoSource("acme.com", on_event=lambda e: print(e["event"], e["detail"]))
 a = acme.answer(question="How much is the Starter plan?")
 print(a["status"], a["text"])
+
+r = acme.reply(question=user_question, draft=model_text)  # built by code; the draft is discarded
+show(r["text"])
+
+r = acme.respond(question=user_question, draft=model_text)  # follows the company's answer mode
+show(r["text"])  # Audit mode also returns r["audit"]: supported, differs, marked, not_in_record or not_checked
 ```
 
 It loads `/.well-known/trooth.semanto` and the company's keys from the company's site, checks the file once for each new body, reads the site again at most every 15 minutes, and answers fact IDs and plain questions in process with the same matcher as Trooth's service (`trooth_semanto_verify.answer`, compared case by case with `verifier/test-vectors/answer-v1`). When Trooth's API cannot be reached it keeps answering from the last version that checked out and logs `trooth_api_unreachable`; a new version that does not check out is refused and the last good one stays in use. A fact marked changed since signing or expired returns its mark and no value.

{trooth-0.2.0 → trooth-0.4.0}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trooth"
-version = "0.2.0"
+version = "0.4.0"
 description = "Read a company's Semanto signed copy and check it: signatures, keys, DNS binding, page proofs and the public log."
 readme = "README.md"
 requires-python = ">=3.11"

{trooth-0.2.0 → trooth-0.4.0}/trooth/__init__.py

@@ -14,5 +14,5 @@ kits). Framework integrations are optional extras: trooth[langchain], trooth[lla
 from trooth_semanto_verify.client import SemantoClient
 from trooth_semanto_verify.source import SemantoSource
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 __all__ = ["SemantoClient", "SemantoSource", "__version__"]

{trooth-0.2.0 → trooth-0.4.0}/trooth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trooth
-Version: 0.2.0
+Version: 0.4.0
 Summary: Read a company's Semanto signed copy and check it: signatures, keys, DNS binding, page proofs and the public log.
 Author: Trooth, LLC
 License-Expression: Apache-2.0
@@ -94,6 +94,12 @@ from trooth import SemantoSource
 acme = SemantoSource("acme.com", on_event=lambda e: print(e["event"], e["detail"]))
 a = acme.answer(question="How much is the Starter plan?")
 print(a["status"], a["text"])
+
+r = acme.reply(question=user_question, draft=model_text)  # built by code; the draft is discarded
+show(r["text"])
+
+r = acme.respond(question=user_question, draft=model_text)  # follows the company's answer mode
+show(r["text"])  # Audit mode also returns r["audit"]: supported, differs, marked, not_in_record or not_checked
 ```
 
 It loads `/.well-known/trooth.semanto` and the company's keys from the company's site, checks the file once for each new body, reads the site again at most every 15 minutes, and answers fact IDs and plain questions in process with the same matcher as Trooth's service (`trooth_semanto_verify.answer`, compared case by case with `verifier/test-vectors/answer-v1`). When Trooth's API cannot be reached it keeps answering from the last version that checked out and logs `trooth_api_unreachable`; a new version that does not check out is refused and the last good one stays in use. A fact marked changed since signing or expired returns its mark and no value.

{trooth-0.2.0 → trooth-0.4.0}/trooth_semanto_verify/__init__.py

@@ -91,4 +91,4 @@ __all__ = [
     "version_id",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

{trooth-0.2.0 → trooth-0.4.0}/trooth_semanto_verify/answer.py

@@ -170,3 +170,20 @@ def answer(file: dict, company: dict, fact_id: Optional[str] = None, question: O
     lines = [MARK_WORDS[mark]] if mark else [f["statement"], *([f"Conditions: {'; '.join(f['conditions'])}."] if f.get("conditions") else [])]
     lines.append(f"Check: {check}")
     return {**base, "status": "answer", "matched_by": by, "facts": [_as_answered(f, mark)], "text": "\n".join(lines[:3])}
+
+
+def assemble_reply(a: dict, draft: Optional[str] = None) -> dict:
+    """What the customer is shown, built by code from an answer; a model's own wording is never part of it.
+
+    For a value answer the first line is the signed sentence exactly as signed, then its conditions if any, then the day
+    it was signed and the check link. A marked fact shows its mark instead of a value. Candidates, the not-published
+    reply and not_read show the answer's own fixed line. `draft` (what a model wrote) is accepted and discarded:
+    `discarded` says whether one was given."""
+    discarded = isinstance(draft, str) and len(draft) > 0
+    signed_on = str(a["signed_at"])[:10] if a.get("signed_at") else None
+    f = a["facts"][0] if a["status"] == "answer" else None
+    if not f:
+        return {"status": a["status"], "fact_id": None, "statement": None, "signed_on": signed_on, "check": a.get("check"), "text": a["text"], "discarded": discarded}
+    tail = f"{f'Signed on {signed_on}. ' if signed_on else ''}Check: {a['check']}"
+    lines = [MARK_WORDS[f["mark"]], tail] if f["mark"] else [f["statement"], *([f"Conditions: {'; '.join(f['conditions'])}."] if f["conditions"] else []), tail]
+    return {"status": a["status"], "fact_id": f["fact_id"], "statement": f["statement"], "signed_on": signed_on, "check": a["check"], "text": "\n".join(lines), "discarded": discarded}

{trooth-0.2.0 → trooth-0.4.0}/trooth_semanto_verify/source.py

@@ -22,18 +22,21 @@ from __future__ import annotations
 
 import json
 import threading
+import unicodedata
 import time
 import urllib.parse
 from datetime import datetime, timezone
 from typing import Any, Callable, Dict, List, Optional
 
 from .answer import answer as _answer
-from .answer import fact_marks
+from .answer import MARK_WORDS, assemble_reply, fact_marks
 from .client import Fetch, urllib_fetch
 from .verify import verify_semanto
 
 TROOTH_API = "https://api.trooth.co"
 MAX_REFRESH_SECONDS = 900
+# The answer modes a company chooses on trooth.co.
+ANSWER_MODES = ("checked", "source_only", "audit")
 
 
 class SemantoSource:
@@ -58,6 +61,9 @@ class SemantoSource:
         self.checks = 0
         self._body: Optional[str] = None
         self._lock = threading.Lock()
+        self._mode: Optional[dict] = None
+        self._mode_read_at: Optional[float] = None
+        self._mode_fresh = False
 
     def _log(self, event: str, detail: str) -> None:
         e = {"at": datetime.fromtimestamp(self.now(), timezone.utc).isoformat().replace("+00:00", "Z"), "event": event, "detail": detail}
@@ -152,3 +158,59 @@ class SemantoSource:
             return {"object": "semanto.answer", "status": "not_read", "matched_by": None, "company": {"trooth_id": None, "name": None, "domain": self.domain},
                     "version": None, "facts": [], "text": f"No signed record of {self.domain} could be read and checked yet."}
         return _answer(self.file, self.company, fact_id=fact_id, question=question, marks=self.marks(), check_base=f"{self.api_base}/public/semanto")
+
+    def reply(self, fact_id: Optional[str] = None, question: Optional[str] = None, draft: Optional[str] = None) -> dict:
+        """The reply a chatbot shows for a question: built by code from the signed record, with the model's draft discarded."""
+        return assemble_reply(self.answer(fact_id=fact_id, question=question), draft)
+
+    def answer_mode(self) -> dict:
+        """The company's answer mode, read from Trooth and kept between reads. When it has never been read (Trooth's API
+        unreachable from the start), Checked is used: the strictest mode, so nothing unchecked is shown."""
+        self.ensure_fresh()
+        if self.file and (self._mode_read_at is None or self.now() - self._mode_read_at >= self.refresh_seconds):
+            tid = urllib.parse.quote(self.file["header"]["trooth_id"], safe="")
+            try:
+                m = self._json(f"{self.api_base}/public/semanto/{tid}/answer-mode")
+                if m.get("mode") in ANSWER_MODES:
+                    self._mode = {"mode": m["mode"], "generated_sentences": m.get("generated_sentences") is True}
+                self._mode_fresh = True
+            except Exception as e:  # noqa: BLE001
+                self._mode_fresh = False
+                self._log("trooth_api_unreachable", f"The answer mode could not be read ({e}); {self._mode['mode'] + ' stays in force' if self._mode else 'Checked is used until it can be read'}.")
+            self._mode_read_at = self.now()
+        if self._mode:
+            return {**self._mode, "source": "trooth" if self._mode_fresh else "last_read"}
+        return {"mode": "checked", "generated_sentences": False, "source": "fail_closed"}
+
+    def respond(self, question: Optional[str] = None, draft: str = "", fact_id: Optional[str] = None, mode: Optional[str] = None) -> dict:
+        """The reply a chatbot sends, in the company's answer mode (or `mode` when given). checked: built by code from the
+        signed record, the draft discarded. source_only: the draft as written, nothing checked. audit: the draft as
+        written, checked right after; the result is in "audit" and in an "audit" event."""
+        m = mode if mode in ANSWER_MODES else self.answer_mode()["mode"]
+        if m == "checked":
+            return {"mode": m, **self.reply(fact_id=fact_id, question=question, draft=draft)}
+        if m == "source_only":
+            return {"mode": m, "status": "unchecked", "text": draft}
+        result = audit_draft(self.answer(fact_id=fact_id, question=question), draft, self.file)
+        self._log("audit", f"{result['result']}: {question or fact_id or ''}".strip())
+        return {"mode": m, "status": "unchecked", "text": draft, "audit": result}
+
+
+def audit_draft(a: dict, draft: str, file: Optional[dict] = None) -> dict:
+    """Audit mode's check of a sent draft against the answer for the same question: "supported" when the draft carries the
+    signed sentence or its value, "differs" when a single signed fact answers and the draft carries neither (the signed
+    sentence comes with it), "marked" for a fact marked changed or expired, "not_in_record" when the record holds nothing
+    for it, and "not_checked" for candidates or no version."""
+    if a["status"] != "answer":
+        return {"result": "not_in_record" if a["status"] == "not_published" else "not_checked", "fact_id": None, "statement": None}
+    f = a["facts"][0]
+    if f["mark"]:
+        return {"result": "marked", "fact_id": f["fact_id"], "statement": None, "words": MARK_WORDS[f["mark"]]}
+    norm = lambda s: " ".join(unicodedata.normalize("NFKC", str(s).lower()).split())  # noqa: E731
+    d = norm(draft)
+    raw = next((x for x in (file or {}).get("facts", []) if x["id"] == f["fact_id"]), None) or {}
+    typed = f.get("typed") or raw.get("typed") or {}
+    value = typed.get("value") if typed.get("value") is not None else raw.get("value")
+    values = [str(x) for x in (value if isinstance(value, list) else [] if value is None else [value])]
+    supported = norm(f["statement"]) in d or (len(values) > 0 and all(norm(v) in d for v in values))
+    return {"result": "supported" if supported else "differs", "fact_id": f["fact_id"], "statement": f["statement"]}