Semantix-verify

Validieren Sie jede LLM-Ausgabe gegen eine explizite Absicht. Erhalten Sie einen Score, ein Urteil und einen manipulationssicheren Beleg. Lokal. In ca. 15–50 Millisekunden. Ohne API-Schlüssel.

pip install semantix-ai

from semantix import Intent, validate_intent

class ResolutionPolite(Intent):
    """The response must acknowledge the customer's issue and propose a concrete next step, in a polite tone."""

@validate_intent(ResolutionPolite, audit=True)
def handle_complaint(message: str) -> str:
    return call_my_llm(message)

reply = handle_complaint(incoming)
# Returns the validated reply — or raises SemanticIntentError.
# The audit engine has already written a hash-chained receipt to disk.

Warum existiert dies?

LLM-Anwendungen überspringen stillschweigend den Schritt, in dem Sie nachweisen, dass die Ausgabe zweckmäßig war. Die gängige Lösung – ein größeres LLM als Richter aufzurufen – hat drei Probleme:

1. Es driftet. Gleiche Eingabe, unterschiedlicher Score bei verschiedenen Durchläufen. Eine Aufsichtsbehörde, die fragt „Führen Sie diese Validierung erneut aus“, erhält eine andere Antwort, die nicht von einem Beweis dafür zu unterscheiden ist, dass das System defekt ist.

2. Es versendet persönliche Informationen aus Ihrem Netzwerk. Jeder Richter-Aufruf sendet die Ausgabe an eine API eines Drittanbieters. Gemäß POPIA §72 (oder DSGVO Art. 44 oder den Verpflichtungen des EU AI Act für Hochrisikosysteme) ist das ein Problem, das dokumentiert werden muss, kein Standard.

3. Es erzeugt keinen Beleg. Die Validierung fand statt, ein Score kam zurück, nichts wurde in einer Form aufgezeichnet, die eine Prüfung übersteht.

semantix ersetzt diesen Reflex durch einen lokalen, deterministischen Validator und ein manipulationssicheres Protokoll. Jede Validierung erzeugt ein signiertes JSON-LD-Zertifikat, das per Hash-Kette mit dem vorherigen verknüpft ist. Ändern Sie einen Eintrag und jeder nachfolgende Hash bricht. Die Aufsichtsbehörde muss Ihrer Datenbank nicht vertrauen – die Mathematik beweist, dass die Kette intakt ist.

Related MCP server: agentvet-mcp

Was Sie erhalten

1. Validierung als Dekorator

from semantix import Intent, validate_intent

class MedicalAdvice(Intent):
    """The text provides a medical diagnosis or treatment recommendation."""

@validate_intent(~MedicalAdvice)  # Must NOT give medical advice
def chatbot(msg: str) -> str:
    return call_my_llm(msg)

Kombinieren Sie mit & (alle müssen bestehen) und | (eines muss bestehen):

SafeAndPolite = Polite & ~MedicalAdvice & ~LegalAdvice

2. Manipulationssicherer Audit-Trail

from semantix.audit.engine import AuditEngine
engine = AuditEngine()

# Every @validate_intent call with audit=True writes a hash-chained certificate.
engine.verify_chain()  # True if no tampering

Jedes Zertifikat zeichnet den Hash des validierten Textes, die Absicht, die Identität und Konfiguration des Richters, das Urteil, den Zeitstempel und den Hash des vorherigen Zertifikats auf. Kompatibel mit JSON-LD-Tools und Standard-Audit-Pipelines.

3. Selbstheilende Wiederholungen

Bei einem Fehler fügt semantix strukturiertes Feedback ein, damit das LLM weiß, was schiefgelaufen ist:

from typing import Optional

@validate_intent(ResolutionPolite, retries=2)
def reply(msg: str, semantix_feedback: Optional[str] = None) -> str:
    prompt = f"Reply to: {msg}"
    if semantix_feedback:
        prompt += f"\n\n{semantix_feedback}"
    return call_llm(prompt)

Erster Aufruf: semantix_feedback ist None. Bei Wiederholung: Es erhält einen Markdown-Bericht mit dem Score, dem Grund und der abgelehnten Ausgabe. Die gemessene Zuverlässigkeit verbessert sich über drei Absichtskategorien hinweg von 21 % auf 70 %.

4. Forensische Attribution auf Token-Ebene

from semantix import ForensicJudge, QuantizedNLIJudge
judge = ForensicJudge(QuantizedNLIJudge())
# Verdict.reason: "Suspect tokens: [indemnify, forfeit, waive]"

5. pytest-Integration

from semantix.testing import assert_semantic

def test_chatbot_is_polite():
    response = my_chatbot("handle angry customer")
    assert_semantic(response, "polite and professional")

Bei einem Fehler:

AssertionError: Semantic check failed (score=0.12)
  Intent:  polite and professional
  Output:  "You're an idiot for asking that."
  Reason:  Text contains aggressive language

Erstklassiges pytest-Plugin mit Fixtures, Markern und CI-Reporting: pytest-semantix.

Framework-Integrationen

Integrieren Sie es in Ihren bestehenden Stack – Wiederholungen werden von jedem Framework nativ gehandhabt.

DSPy

import dspy
from semantix.integrations.dspy import semantic_reward

qa = dspy.ChainOfThought("question -> answer")
refined = dspy.Refine(module=qa, N=3, reward_fn=semantic_reward(Polite))

semantic_reward / semantic_metric lassen sich auch in dspy.BestOfN, dspy.Evaluate und MIPROv2 einbinden – lokal, keine API-Aufrufe, ca. 15 ms pro Auswertung. Siehe benchmarks/ für reproduzierbare Vergleiche mit LLM-Richter-Belohnungsfunktionen.

from semantix.integrations.langchain import SemanticValidator
validator = SemanticValidator(Polite)
chain = prompt | llm | StrOutputParser() | validator

from pydantic_ai import Agent
from semantix.integrations.pydantic_ai import semantix_validator
agent = Agent("openai:gpt-4o", output_type=str)
agent.output_validator(semantix_validator(Polite))

from guardrails import Guard
from semantix.integrations.guardrails import SemanticIntent
guard = Guard().use(SemanticIntent("must be polite and professional"))

from semantix.integrations.instructor import SemanticStr
from pydantic import BaseModel
class Response(BaseModel):
    reply: SemanticStr["must be polite and professional", 0.85]

pip install "semantix-ai[mcp,nli]"
mcp run semantix/mcp/server.py

Jeder MCP-fähige Agent (Claude Desktop, Cursor usw.) kann Absichten als Tool validieren.

- uses: labrat-akhona/semantic-test-action@v1
  with:
    test-path: tests/

Postet einen semantischen Testbericht als PR-Kommentar.

Installieren Sie Extras: pip install "semantix-ai[dspy]", "[langchain]", "[pydantic-ai]", "[guardrails]", "[instructor]", "[mcp]", "[all]".

Steckbare Richter

Wählen Sie den Kompromiss zwischen Geschwindigkeit / Genauigkeit / Schlussfolgerung:

from semantix import NLIJudge, EmbeddingJudge, LLMJudge, CachingJudge

@validate_intent(judge=NLIJudge())                           # local, ~15 ms, deterministic
@validate_intent(judge=EmbeddingJudge())                     # local, ~5 ms, similarity-based
@validate_intent(judge=LLMJudge(model="gpt-4o-mini"))        # reasoning, ~500 ms, API
@validate_intent(judge=CachingJudge(NLIJudge(), maxsize=256))  # LRU-wrapped

Quantisierter Modus (INT8 ONNX, ca. 25 MB, kein PyTorch):

pip install "semantix-ai[turbo]"

Wann dies das richtige Werkzeug ist

• Sie betreiben ein LLM-gestütztes System, das persönliche Informationen verarbeitet, und benötigen einen prüfbaren Validierungsschritt.

• Sie optimieren ein DSPy-Programm und die LLM-Richter-Belohnungsschleife ist zu langsam, zu teuer oder zu nicht-deterministisch.

• Sie benötigen semantische Test-Assertions in pytest / CI, die keine kostenpflichtige API aufrufen.

• Sie sind in einer regulierten Branche tätig (Finanzdienstleistungen, Versicherungen, Gesundheitswesen) und „das Modell sagte, es sei in Ordnung“ ist keine vertretbare Antwort.

Wann es nicht das richtige Werkzeug ist

• Ihre Validierungsabsicht erfordert mehrstufiges Schlussfolgern oder Weltwissen („ist dies konform mit Abschnitt 4(b) des Steuergesetzes von 2026“). NLI kann dies nicht; schlussfolgernde LLMs können es.

• Sie benötigen, dass der Richter warum in Prosa erklärt, nicht nur einen Score vergibt.

• Sie bewerten weniger als 100 Ausgaben pro Monat und die Latenz / Kosten von LLM-als-Richter spielen keine Rolle.

Siehe Wo semantix passt für einen Vergleich mit TruLens, DeepEval, Vectara HHEM, Guardrails, RAGAS und NeMo.

Schlüsseleigenschaften

• Lokale Inferenz — NLI-Modell läuft auf der CPU, keine Daten verlassen Ihre Maschine.

• Deterministisch — gleiche Eingabe, gleicher Score, jedes Mal, auf jeder Maschine. Seedbar.

• Schnell — ca. 15–50 ms pro Prüfung mit dem quantisierten Richter.

• Null API-Kosten — keine Token für die Validierung verbraucht.

• Prüfbar — Hash-verkettete JSON-LD-Zertifikate pro Prüfung.

• Gut getestet — 249 Tests, MIT-lizenziert.

Installation

pip install semantix-ai                    # Core (default NLI judge)
pip install "semantix-ai[turbo]"           # Quantized ONNX (smallest footprint)
pip install "semantix-ai[openai]"          # LLM judge (GPT-4o-mini)
pip install "semantix-ai[all]"             # Everything

Der Paketname auf PyPI ist semantix-ai. Der Import lautet from semantix import ....

Mitwirken

Siehe CONTRIBUTING.md für Entwickler-Setup, Tests und Einreichungsrichtlinien.

Lizenz

MIT — siehe LICENSE.