state-integrity-protocol 0.1.0__py3-none-any.whl

sip/__init__.py

@@ -0,0 +1,37 @@
+"""
+State Integrity Protocol (SIP) 🧬
+
+A Fidelity-Flow Observation library for detecting and measuring State Decay
+in multi-agent AI pipelines.
+"""
+
+from sip.anchor import SemanticAnchor
+from sip.middleware import (
+    ConstraintViolationResult,
+    DriftCheckResult,
+    IntentAlignmentResult,
+    MiddlewareEvaluation,
+    PipelineResult,
+    SIPMiddlewarePipeline,
+    VerificationDecision,
+)
+from sip.observer import FidelityObserver, TransitionRecord, cosine_similarity
+from sip.protocol import ObservationResult, StateIntegrityProtocol
+
+__all__ = [
+    "StateIntegrityProtocol",
+    "SemanticAnchor",
+    "FidelityObserver",
+    "ObservationResult",
+    "TransitionRecord",
+    "cosine_similarity",
+    "SIPMiddlewarePipeline",
+    "DriftCheckResult",
+    "IntentAlignmentResult",
+    "ConstraintViolationResult",
+    "MiddlewareEvaluation",
+    "VerificationDecision",
+    "PipelineResult",
+]
+
+__version__ = "0.1.0"

sip/anchor.py

@@ -0,0 +1,69 @@
+"""
+SemanticAnchor – captures and stores the embedding of the initial prompt.
+
+The anchor acts as the ground-truth reference against which every subsequent
+agent output is measured.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, List, Optional, Sequence
+
+
+class SemanticAnchor:
+    """
+    Stores the *semantic anchor* – the embedding of the origin prompt.
+
+    Parameters
+    ----------
+    embed_fn:
+        A callable ``(text: str) -> List[float]`` that converts a piece of
+        text into a numeric vector.  If *None*, the default TF-IDF helper is
+        used.
+    """
+
+    def __init__(
+        self,
+        embed_fn: Optional[Callable[[str], Sequence[float]]] = None,
+    ) -> None:
+        if embed_fn is None:
+            from sip.embeddings import default_embed_fn
+
+            embed_fn = default_embed_fn
+        self._embed_fn = embed_fn
+        self._embedding: Optional[List[float]] = None
+        self._text: Optional[str] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def set(self, prompt: str) -> List[float]:
+        """
+        Embed *prompt* and store it as the anchor.
+
+        Returns the embedding so callers can inspect it if needed.
+        """
+        embedding = list(self._embed_fn(prompt))
+        self._embedding = embedding
+        self._text = prompt
+        return embedding
+
+    @property
+    def embedding(self) -> Optional[List[float]]:
+        """The stored anchor embedding, or *None* if not yet set."""
+        return self._embedding
+
+    @property
+    def text(self) -> Optional[str]:
+        """The original anchor text, or *None* if not yet set."""
+        return self._text
+
+    def is_set(self) -> bool:
+        """Return *True* if an anchor has been established."""
+        return self._embedding is not None
+
+    def reset(self) -> None:
+        """Clear the anchor (useful when starting a new task chain)."""
+        self._embedding = None
+        self._text = None

sip/embeddings.py

@@ -0,0 +1,78 @@
+"""
+State Integrity Protocol (SIP) - Embedding Engine
+Optimized for zero-latency auditing with Semantic Smoothing.
+"""
+
+from __future__ import annotations
+import math
+import re
+from collections import Counter
+from typing import List
+
+def _tokenize(text: str) -> List[str]:
+    """
+    Lower-case, filters out numeric noise and common stopwords 
+    to reduce 'False Positive' drift in demos.
+    """
+    # Extract alpha-numeric tokens
+    tokens = re.findall(r"[a-z0-9]+", text.lower())
+    
+    # Semantic Smoothing: Ignore connector words that don't carry 'Intent'
+    stop_words = {
+        'the', 'is', 'at', 'which', 'on', 'and', 'a', 'an', 'to', 'for', 
+        'in', 'of', 'with', 'by', 'do', 'does', 'doing', 'it', 'my', 'your'
+    }
+    return [t for t in tokens if t not in stop_words]
+
+def _tf(tokens: List[str]) -> Counter:
+    return Counter(tokens)
+
+class TFIDFEmbedder:
+    """
+    Incrementally-fitted TF-IDF vectoriser.
+    L2-normalised for direct dot-product cosine similarity.
+    """
+    def __init__(self) -> None:
+        self._vocab: dict[str, int] = {}
+        self._df: Counter = Counter()
+        self._n_docs: int = 0
+
+    def embed(self, text: str) -> List[float]:
+        """Return a TF-IDF vector (L2-normalised) for *text*."""
+        tokens = _tokenize(text)
+        if not tokens:
+            return []
+
+        tf = _tf(tokens)
+
+        # Update vocabulary and document-frequency counts
+        self._n_docs += 1
+        for term in tf:
+            if term not in self._vocab:
+                self._vocab[term] = len(self._vocab)
+            self._df[term] += 1
+
+        dim = len(self._vocab)
+        vec = [0.0] * dim
+
+        for term, count in tf.items():
+            idx = self._vocab[term]
+            tf_score = count / len(tokens)
+            # IDF with smoothing to prevent division by zero
+            idf_score = math.log((1 + self._n_docs) / (1 + self._df[term])) + 1.0
+            vec[idx] = tf_score * idf_score
+
+        return _l2_normalize(vec)
+
+def _l2_normalize(vec: List[float]) -> List[float]:
+    norm = math.sqrt(sum(v * v for v in vec))
+    if norm == 0.0:
+        return vec
+    return [v / norm for v in vec]
+
+# Singleton instance
+_default_embedder = TFIDFEmbedder()
+
+def default_embed_fn(text: str) -> List[float]:
+    """Default embedding function for the SIP Protocol."""
+    return _default_embedder.embed(text)

sip/middleware.py

@@ -0,0 +1,359 @@
+"""
+Middleware orchestration for the State Integrity Protocol (SIP).
+
+Flow:
+Human/Agent A -> anchor(intent) -> middleware checks -> verify_and_sign()
+-> accepted OR repair loop.
+"""
+
+from __future__ import annotations
+
+import os
+os.environ["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "1"
+os.environ["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
+os.environ["TRANSFORMERS_VERBOSITY"] = "error"
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"
+
+import hashlib
+import json
+import logging
+import re
+import warnings
+from dataclasses import dataclass
+from typing import Callable, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+warnings.filterwarnings("ignore")
+logging.getLogger("sentence_transformers").setLevel(logging.ERROR)
+logging.getLogger("transformers").setLevel(logging.ERROR)
+logging.getLogger("huggingface_hub").setLevel(logging.ERROR)
+
+from sentence_transformers import SentenceTransformer
+from sip.anchor import SemanticAnchor
+from sip.observer import FidelityObserver
+
+# Cache embeddings to avoid recomputing
+_semantic_model: Optional[SentenceTransformer] = None
+_embedding_cache: dict[str, np.ndarray] = {}
+
+
+def _get_model() -> SentenceTransformer:
+    global _semantic_model
+    if _semantic_model is None:
+        _semantic_model = SentenceTransformer('paraphrase-MiniLM-L3-v2')
+    return _semantic_model
+
+
+def _encode_cached(text: str) -> np.ndarray:
+    if text not in _embedding_cache:
+        _embedding_cache[text] = _get_model().encode(text)
+    return _embedding_cache[text]
+
+
+Signer = Callable[[str], str]
+
+
+@dataclass(frozen=True)
+class DriftCheckResult:
+    drift: float
+    threshold: float
+    passed: bool
+
+
+@dataclass(frozen=True)
+class IntentAlignmentResult:
+    score: float
+    threshold: float
+    passed: bool
+
+
+@dataclass(frozen=True)
+class ConstraintViolationResult:
+    constraints: Tuple[str, ...]
+    violations: Tuple[str, ...]
+    passed: bool
+
+
+@dataclass(frozen=True)
+class MiddlewareEvaluation:
+    step: int
+    output: str
+    drift_check: DriftCheckResult
+    intent_alignment: IntentAlignmentResult
+    constraint_check: ConstraintViolationResult
+    failure_codes: Tuple[str, ...]
+
+    @property
+    def passed(self) -> bool:
+        return not self.failure_codes
+
+
+@dataclass(frozen=True)
+class VerificationDecision:
+    accepted: bool
+    repair_required: bool
+    reasons: Tuple[str, ...]
+    failure_codes: Tuple[str, ...]
+    signature: str
+    payload: str
+
+
+@dataclass(frozen=True)
+class PipelineResult:
+    status: str
+    evaluation: MiddlewareEvaluation
+    decision: VerificationDecision
+    attempts_used: int
+    attempts_remaining: int
+    repair_instructions: Tuple[str, ...]
+
+
+class SIPMiddlewarePipeline:
+    DEFAULT_DRIFT_THRESHOLD: float = 0.7
+    DEFAULT_INTENT_ALIGNMENT_THRESHOLD: float = 0.2
+    DEFAULT_MAX_RETRIES: int = 2
+
+    def __init__(
+        self,
+        *,
+        embed_fn: Optional[Callable[[str], Sequence[float]]] = None,
+        drift_threshold: float = DEFAULT_DRIFT_THRESHOLD,
+        intent_alignment_threshold: float = DEFAULT_INTENT_ALIGNMENT_THRESHOLD,
+        constraints: Optional[Sequence[str]] = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        signer: Optional[Signer] = None,
+    ) -> None:
+        if not 0.0 <= drift_threshold <= 1.0:
+            raise ValueError(f"drift_threshold must be in [0, 1], got {drift_threshold!r}")
+        if not 0.0 <= intent_alignment_threshold <= 1.0:
+            raise ValueError(f"intent_alignment_threshold must be in [0, 1], got {intent_alignment_threshold!r}")
+        if max_retries < 0:
+            raise ValueError(f"max_retries must be >= 0, got {max_retries!r}")
+
+        self._drift_threshold = drift_threshold
+        self._intent_alignment_threshold = intent_alignment_threshold
+        self._constraints = tuple(constraints or ())
+        self._max_retries = max_retries
+        self._signer = signer or _default_signer
+
+        self._anchor = SemanticAnchor(embed_fn=embed_fn)
+        self._observer = FidelityObserver(anchor=self._anchor, embed_fn=embed_fn)
+
+        self._intent_text: Optional[str] = None
+        self._intent_tokens: set[str] = set()
+        self._rejection_count = 0
+
+    @property
+    def history(self):
+        return self._observer.history
+
+    def anchor(self, intent: str) -> List[float]:
+        if not intent.strip():
+            raise ValueError("intent must be a non-empty string")
+        self._observer.reset()
+        self._rejection_count = 0
+        self._intent_text = intent
+        self._intent_tokens = _tokenize(intent)
+        # Pre-cache intent embedding
+        _encode_cached(" ".join(self._intent_tokens))
+        return self._anchor.set(intent)
+
+    def evaluate(
+        self, output: str, constraints: Optional[Sequence[str]] = None
+    ) -> MiddlewareEvaluation:
+        if self._intent_text is None:
+            raise RuntimeError("Anchor not set. Call anchor() before evaluate().")
+
+        drift = self._observer.observe(output)
+        intent_score = _intent_alignment_score(
+            intent_tokens=self._intent_tokens, output=output
+        )
+        numeric_safe = not _has_numeric_drift(self._intent_text, output)
+        scope_safe = not _has_scope_creep(self._intent_text, output)
+
+        drift_check = DriftCheckResult(
+            drift=drift,
+            threshold=self._drift_threshold,
+            passed=(drift <= self._drift_threshold or intent_score >= 0.7) and numeric_safe and scope_safe,
+        )
+
+        intent_alignment = IntentAlignmentResult(
+            score=intent_score,
+            threshold=self._intent_alignment_threshold,
+            passed=intent_score >= self._intent_alignment_threshold,
+        )
+
+        active_constraints = tuple(
+            self._constraints if constraints is None else constraints
+        )
+        output_lower = output.lower()
+        violations = tuple(
+            c for c in active_constraints
+            if _matches_constraint_phrase(c, output_lower)
+        )
+        constraint_check = ConstraintViolationResult(
+            constraints=active_constraints,
+            violations=violations,
+            passed=not violations,
+        )
+
+        failure_codes = []
+        if not drift_check.passed:
+            failure_codes.append("drift")
+        if not intent_alignment.passed:
+            failure_codes.append("intent_alignment")
+        if not constraint_check.passed:
+            failure_codes.append("constraint_violation")
+
+        return MiddlewareEvaluation(
+            step=len(self._observer.history),
+            output=output,
+            drift_check=drift_check,
+            intent_alignment=intent_alignment,
+            constraint_check=constraint_check,
+            failure_codes=tuple(failure_codes),
+        )
+
+    def verify_and_sign(self, evaluation: MiddlewareEvaluation) -> VerificationDecision:
+        reasons = tuple(_reason_for_code(code, evaluation) for code in evaluation.failure_codes)
+        payload = _stable_payload(evaluation=evaluation, reasons=reasons)
+        signature = self._signer(payload)
+        return VerificationDecision(
+            accepted=evaluation.passed,
+            repair_required=not evaluation.passed,
+            reasons=reasons,
+            failure_codes=evaluation.failure_codes,
+            signature=signature,
+            payload=payload,
+        )
+
+    def run(
+        self, output: str, constraints: Optional[Sequence[str]] = None
+    ) -> PipelineResult:
+        if self._intent_text is None:
+            raise RuntimeError("Anchor not set. Call anchor() before run().")
+
+        evaluation = self.evaluate(output=output, constraints=constraints)
+        decision = self.verify_and_sign(evaluation)
+        if not decision.accepted:
+            self._rejection_count += 1
+
+        rejection_count = self._rejection_count
+        attempts_used = rejection_count
+        attempts_remaining = max(0, self._max_retries - rejection_count)
+        status = "accepted"
+        repair_instructions: Tuple[str, ...] = ()
+        if not decision.accepted:
+            attempts_remaining = max(0, self._max_retries - rejection_count + 1)
+            status = (
+                "repair_required"
+                if self._rejection_count <= self._max_retries
+                else "rejected"
+            )
+            repair_instructions = tuple(
+                _repair_instruction_for_code(code)
+                for code in decision.failure_codes
+            )
+        return PipelineResult(
+            status=status,
+            evaluation=evaluation,
+            decision=decision,
+            attempts_used=attempts_used,
+            attempts_remaining=attempts_remaining,
+            repair_instructions=repair_instructions,
+        )
+
+
+def _tokenize(text: str) -> set[str]:
+    return set(re.findall(r"[a-z0-9]+", text.lower()))
+
+
+def _intent_alignment_score(intent_tokens: set[str], output: str) -> float:
+    if not output.strip():
+        return 0.0
+    intent_text = " ".join(intent_tokens)
+    e1 = _encode_cached(intent_text)
+    e2 = _encode_cached(output)
+    return float(np.dot(e1, e2) / (np.linalg.norm(e1) * np.linalg.norm(e2)))
+
+
+def _has_numeric_drift(intent: str, output: str) -> bool:
+    intent_nums = set(re.findall(r'\d+', intent))
+    output_nums = set(re.findall(r'\d+', output))
+    return intent_nums != output_nums
+
+
+def _has_scope_creep(intent: str, output: str) -> bool:
+    intent_tokens = _tokenize(intent)
+    output_tokens = _tokenize(output)
+    extra = output_tokens - intent_tokens
+    return len(extra) > 5
+
+
+def _matches_constraint_phrase(constraint: str, output_lower: str) -> bool:
+    phrase = constraint.strip().lower()
+    if not phrase:
+        return False
+    pattern = r"\b" + re.escape(phrase) + r"\b"
+    return re.search(pattern, output_lower) is not None
+
+
+def _reason_for_code(code: str, evaluation: MiddlewareEvaluation) -> str:
+    if code == "drift":
+        return (
+            f"Drift {evaluation.drift_check.drift:.4f} exceeded threshold "
+            f"{evaluation.drift_check.threshold:.4f}."
+        )
+    if code == "intent_alignment":
+        return (
+            f"Intent alignment {evaluation.intent_alignment.score:.4f} fell below "
+            f"threshold {evaluation.intent_alignment.threshold:.4f}."
+        )
+    if code == "constraint_violation":
+        violations = ", ".join(evaluation.constraint_check.violations)
+        return f"Constraint violations detected: {violations}."
+    return f"Unknown failure code: {code}."
+
+
+def _repair_instruction_for_code(code: str) -> str:
+    if code == "drift":
+        return "Regenerate response with closer semantic fidelity to the anchor intent."
+    if code == "intent_alignment":
+        return "Add explicit intent terms and requested scope from the anchored intent."
+    if code == "constraint_violation":
+        return "Remove prohibited phrases and satisfy all configured constraints."
+    return "Review middleware failure and regenerate output."
+
+
+def _stable_payload(
+    *, evaluation: MiddlewareEvaluation, reasons: Tuple[str, ...]
+) -> str:
+    data = {
+        "constraint_check": {
+            "constraints": list(evaluation.constraint_check.constraints),
+            "passed": evaluation.constraint_check.passed,
+            "violations": list(evaluation.constraint_check.violations),
+        },
+        "drift_check": {
+            "drift": evaluation.drift_check.drift,
+            "passed": evaluation.drift_check.passed,
+            "threshold": evaluation.drift_check.threshold,
+        },
+        "failure_codes": list(evaluation.failure_codes),
+        "intent_alignment": {
+            "passed": evaluation.intent_alignment.passed,
+            "score": evaluation.intent_alignment.score,
+            "threshold": evaluation.intent_alignment.threshold,
+        },
+        "output": evaluation.output,
+        "passed": evaluation.passed,
+        "reasons": list(reasons),
+        "step": evaluation.step,
+    }
+    return json.dumps(data, sort_keys=True, separators=(",", ":"))
+
+
+def _default_signer(payload: str) -> str:
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()

sip/observer.py

@@ -0,0 +1,158 @@
+"""
+FidelityObserver – measures semantic drift at each agent transition.
+
+Drift is defined as::
+
+    drift = 1 - cosine_similarity(anchor_embedding, current_embedding)
+
+A drift of **0** means perfect alignment; **1** means completely orthogonal
+(maximum drift).
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable, List, Optional, Sequence
+
+from sip.anchor import SemanticAnchor
+
+
+@dataclass
+class TransitionRecord:
+    """Immutable snapshot of one agent transition."""
+
+    step: int
+    text: str
+    embedding: List[float]
+    drift: float
+    timestamp: datetime = field(
+        default_factory=lambda: datetime.now(tz=timezone.utc)
+    )
+
+
+class FidelityObserver:
+    """
+    Monitors semantic drift across agent transitions.
+
+    Parameters
+    ----------
+    anchor:
+        A :class:`~sip.anchor.SemanticAnchor` instance that holds the
+        reference embedding.
+    embed_fn:
+        Embedding function used to convert agent outputs to vectors.  Must
+        match the function used to build the anchor.
+    """
+
+    def __init__(
+        self,
+        anchor: SemanticAnchor,
+        embed_fn: Optional[Callable[[str], Sequence[float]]] = None,
+    ) -> None:
+        self._anchor = anchor
+        if embed_fn is None:
+            from sip.embeddings import default_embed_fn
+
+            embed_fn = default_embed_fn
+        self._embed_fn = embed_fn
+        self._history: List[TransitionRecord] = []
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def observe(self, text: str) -> float:
+        """
+        Embed *text*, compute drift against the anchor, record the transition.
+
+        Returns
+        -------
+        float
+            Drift score in ``[0.0, 1.0]`` where 0 is perfect fidelity.
+
+        Raises
+        ------
+        RuntimeError
+            If the anchor has not been set yet.
+        """
+        if not self._anchor.is_set():
+            raise RuntimeError(
+                "Anchor not set. Call StateIntegrityProtocol.anchor() first."
+            )
+
+        current_embedding = list(self._embed_fn(text))
+        drift = _cosine_drift(self._anchor.embedding, current_embedding)
+
+        record = TransitionRecord(
+            step=len(self._history) + 1,
+            text=text,
+            embedding=current_embedding,
+            drift=drift,
+        )
+        self._history.append(record)
+        return drift
+
+    @property
+    def history(self) -> List[TransitionRecord]:
+        """All recorded :class:`TransitionRecord` objects (oldest first)."""
+        return list(self._history)
+
+    @property
+    def last_drift(self) -> Optional[float]:
+        """Drift score from the most recent observation, or *None*."""
+        return self._history[-1].drift if self._history else None
+
+    def reset(self) -> None:
+        """Clear the observation history."""
+        self._history.clear()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _dot(a: Sequence[float], b: Sequence[float]) -> float:
+    """Dot-product of two equal-length vectors."""
+    return sum(x * y for x, y in zip(a, b))
+
+
+def _norm(v: Sequence[float]) -> float:
+    return math.sqrt(sum(x * x for x in v))
+
+
+def _pad(
+    a: List[float], b: List[float]
+) -> tuple[List[float], List[float]]:
+    """Zero-pad the shorter vector so both have the same length."""
+    diff = len(a) - len(b)
+    if diff > 0:
+        b = b + [0.0] * diff
+    elif diff < 0:
+        a = a + [0.0] * (-diff)
+    return a, b
+
+
+def cosine_similarity(
+    a: Sequence[float], b: Sequence[float]
+) -> float:
+    """
+    Return the cosine similarity between two vectors.
+
+    Vectors are zero-padded to the same length if necessary.
+    Returns ``0.0`` for any zero-length or all-zero vector.
+    """
+    a, b = _pad(list(a), list(b))
+    norm_a, norm_b = _norm(a), _norm(b)
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+    return _dot(a, b) / (norm_a * norm_b)
+
+
+def _cosine_drift(
+    anchor: Sequence[float], current: Sequence[float]
+) -> float:
+    """``drift = 1 - cosine_similarity``."""
+    return 1.0 - cosine_similarity(anchor, current)

sip/protocol.py

@@ -0,0 +1,205 @@
+"""
+StateIntegrityProtocol – the top-level orchestrator for Fidelity-Flow
+Observation.
+
+Workflow
+--------
+1. **Anchor** – call :py:meth:`anchor` with the initial prompt to capture the
+   semantic anchor.
+2. **Observe** – call :py:meth:`observe` after every agent transition.  The
+   method returns the drift score and automatically triggers a realignment
+   callback when drift exceeds the configured threshold.
+3. **Inspect** – use :py:attr:`history` and :py:attr:`is_aligned` to audit the
+   pipeline after the fact.
+
+Example
+-------
+>>> from sip import StateIntegrityProtocol
+>>> sip = StateIntegrityProtocol(threshold=0.15)
+>>> sip.anchor("Summarise the quarterly report in three bullet points.")
+>>> result = sip.observe("Here are three key highlights from Q3 ...")
+>>> print(f"Drift: {result.drift:.4f}  Aligned: {sip.is_aligned}")
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from typing import Callable, List, Optional, Sequence
+
+from sip.anchor import SemanticAnchor
+from sip.observer import FidelityObserver, TransitionRecord
+
+
+@dataclass
+class ObservationResult:
+    """Returned by :py:meth:`StateIntegrityProtocol.observe`."""
+
+    step: int
+    text: str
+    drift: float
+    threshold: float
+    realignment_triggered: bool
+
+    @property
+    def is_aligned(self) -> bool:
+        """``True`` if drift is within the acceptable threshold."""
+        return self.drift <= self.threshold
+
+    @property
+    def last_drift(self) -> float:
+        """Alias for the latest drift score on this observation."""
+        return self.drift
+
+
+class StateIntegrityProtocol:
+    """
+    Fidelity-Flow Observation engine.
+
+    Parameters
+    ----------
+    embed_fn:
+        Callable ``(text: str) -> Sequence[float]`` used to embed text.
+        Defaults to the built-in TF-IDF helper.
+    threshold:
+        Drift threshold in ``[0, 1]``.  Outputs whose drift exceeds this value
+        trigger the realignment callback.  Default is ``0.15`` (15 %).
+    on_realignment:
+        Optional callback invoked whenever drift > threshold.  Receives the
+        :class:`ObservationResult` for the offending transition.  If not
+        provided a :py:class:`UserWarning` is emitted instead.
+    """
+
+    DEFAULT_THRESHOLD: float = 0.15
+
+    def __init__(
+        self,
+        embed_fn: Optional[Callable[[str], Sequence[float]]] = None,
+        threshold: float = DEFAULT_THRESHOLD,
+        on_realignment: Optional[Callable[["ObservationResult"], None]] = None,
+    ) -> None:
+        if not 0.0 <= threshold <= 1.0:
+            raise ValueError(
+                f"threshold must be in [0, 1], got {threshold!r}"
+            )
+        self._threshold = threshold
+        self._on_realignment = on_realignment
+
+        self._anchor = SemanticAnchor(embed_fn=embed_fn)
+        self._observer = FidelityObserver(
+            anchor=self._anchor, embed_fn=embed_fn
+        )
+
+    # ------------------------------------------------------------------
+    # Core workflow
+    # ------------------------------------------------------------------
+
+    def anchor(self, prompt: str) -> List[float]:
+        """
+        Capture the semantic anchor from the initial *prompt*.
+
+        Resets any existing observation history and re-anchors from scratch.
+
+        Returns
+        -------
+        List[float]
+            The embedding vector of *prompt*.
+        """
+        self._observer.reset()
+        return self._anchor.set(prompt)
+
+    def observe(self, output: str) -> ObservationResult:
+        """
+        Measure semantic drift of *output* against the anchor.
+
+        Parameters
+        ----------
+        output:
+            The text produced by the current agent node.
+
+        Returns
+        -------
+        ObservationResult
+            Contains the drift score and whether realignment was triggered.
+
+        Raises
+        ------
+        RuntimeError
+            If :py:meth:`anchor` has not been called yet.
+        """
+        drift = self._observer.observe(output)
+        step = len(self._observer.history)
+
+        triggered = drift > self._threshold
+        result = ObservationResult(
+            step=step,
+            text=output,
+            drift=drift,
+            threshold=self._threshold,
+            realignment_triggered=triggered,
+        )
+
+        if triggered:
+            if self._on_realignment is not None:
+                self._on_realignment(result)
+            else:
+                warnings.warn(
+                    f"[SIP] Drift {drift:.4f} exceeds threshold "
+                    f"{self._threshold:.4f} at step {step}. "
+                    "Consider re-aligning the agent or flagging for human "
+                    "intervention.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Inspection helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def is_aligned(self) -> bool:
+        """
+        ``True`` if the most recent observation is within the drift threshold.
+
+        Returns ``True`` (vacuously) before any observation has been made.
+        """
+        last = self._observer.last_drift
+        return last is None or last <= self._threshold
+
+    @property
+    def threshold(self) -> float:
+        """The configured drift threshold."""
+        return self._threshold
+
+    @property
+    def history(self) -> List[TransitionRecord]:
+        """Full list of :class:`~sip.observer.TransitionRecord` objects."""
+        return self._observer.history
+
+    @property
+    def last_drift(self) -> Optional[float]:
+        """Drift score from the most recent observation, or *None*."""
+        return self._observer.last_drift
+
+    def reset(self) -> None:
+        """
+        Full reset – clears the anchor *and* the observation history.
+
+        Use this when starting a completely new task chain.
+        """
+        self._anchor.reset()
+        self._observer.reset()
+
+    # ------------------------------------------------------------------
+    # Dunder helpers
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"StateIntegrityProtocol("
+            f"threshold={self._threshold!r}, "
+            f"steps={len(self.history)}, "
+            f"aligned={self.is_aligned})"
+        )

state_integrity_protocol-0.1.0.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: state-integrity-protocol
+Version: 0.1.0
+Summary: Minimal Python SDK for semantic drift detection and state integrity tracking.
+License: AGPL-3.0
+Keywords: ai,agents,drift-detection,semantic-anchor,llm
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: sentence-transformers>=2.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: scikit-learn>=1.2.0; extra == "dev"
+Dynamic: license-file
+
+# 🧬 State Integrity Protocol (SIP)
+
+> A lightweight runtime layer for detecting and preventing semantic drift in LLM outputs.
+
+SIP helps AI systems stay **faithful to user intent** across generation, transformation, and multi-agent workflows.
+
+---
+
+## ⚠️ Problem
+
+LLMs can fail silently by:
+
+- drifting from original intent
+- adding unwanted assumptions
+- changing numbers, constraints, or meaning
+- hallucinating details that were never requested
+
+This makes AI outputs less reliable in production systems.
+
+---
+
+## 🧠 Solution
+
+SIP introduces a runtime integrity loop:
+
+**Intent → Anchor → Output → Observe → Drift Score → Decision**
+
+Every generated output is checked against the original anchored intent before it is accepted.
+
+---
+
+## ⚙️ Core Concept
+
+SIP operates in three stages:
+
+### 1) Anchor (Intent Definition)
+
+Define the original intent:
+
+```python
+sip.anchor("Refund user $50 within 7 days")
+```
+
+### 2) Observe (Output Evaluation)
+
+Compare generated output against the anchor:
+
+```python
+result = sip.observe("Refund user $500 immediately")
+```
+
+### 3) Decision Layer
+
+Use alignment and drift signals to decide accept/repair/reject:
+
+```python
+print(result.is_aligned)
+print(result.drift)
+```
+
+---
+
+## 🔁 Example
+
+```python
+from sip import StateIntegrityProtocol
+
+sip = StateIntegrityProtocol()
+
+sip.anchor("Delete user account safely")
+result = sip.observe("Create new user account")
+
+print(result.is_aligned)  # False
+print(result.drift)       # e.g., 0.61
+```
+
+`ObservationResult` exposes both `drift` and `last_drift`; both reference the same latest drift score.
+
+---
+
+## 🧱 Architecture
+
+SIP is designed as middleware for AI systems:
+
+```text
+User / Agent
+    ↓
+LLM (generation)
+    ↓
+SIP Middleware
+    ├── Drift detection
+    ├── Intent alignment check
+    ├── Constraint validation
+    ↓
+Decision: Accept / Repair / Reject
+```
+
+---
+
+## 🔐 What SIP Detects
+
+- semantic drift
+- numerical manipulation
+- instruction leakage
+- constraint violations
+- intent mismatch
+- prompt injection attempts
+
+---
+
+## 🚀 Why This Matters
+
+SIP makes AI systems:
+
+- more reliable
+- more predictable
+- safer for production use
+- easier to audit
+
+---
+
+## 🧩 Use Cases
+
+- AI agents
+- LLM pipelines
+- autonomous workflows
+- enterprise AI systems
+- chatbots with strict behavior controls
+
+---
+
+## 📦 Installation
+
+```bash
+pip install -e .
+```
+
+For development and tests:
+
+```bash
+python -m pip install -e '.[dev]'
+```
+
+---
+
+## 🧠 Core API
+
+- `anchor(prompt: str)` — define the initial intent state
+- `observe(output: str)` — evaluate drift from the anchored intent
+- `is_aligned: bool` — alignment signal
+- `drift: float` — latest drift score (alias)
+- `last_drift: float` — latest drift score
+- `history: list` — transition history
+- `SIPMiddlewarePipeline` — optional anchor → checks → verify/sign → repair loop orchestration
+
+---
+
+## 🛡️ Middleware + Verification Flow
+
+The optional pipeline can run:
+
+1. drift check against the anchor
+2. intent-alignment check
+3. constraint-violation check
+4. `verify_and_sign()` decision
+5. accept/repair/reject routing
+
+```python
+from sip import SIPMiddlewarePipeline
+
+pipeline = SIPMiddlewarePipeline(
+    drift_threshold=0.15,
+    intent_alignment_threshold=0.3,
+    constraints=["do not mention internal token"],
+    max_retries=2,
+)
+
+pipeline.anchor("Summarize refund policy in 3 bullet points")
+result = pipeline.run(
+    "Refund policy summary in 3 bullet points without internal token."
+)
+
+print(result.status)                 # accepted | repair_required | rejected
+print(result.decision.signature)     # deterministic decision signature
+print(result.decision.failure_codes) # machine-readable failure causes
+print(result.repair_instructions)    # guidance when not accepted
+```
+
+### Policy Knobs
+
+- `drift_threshold`: maximum allowed semantic drift
+- `intent_alignment_threshold`: minimum token-overlap score
+- `constraints`: blocked words/phrases
+- `max_retries`: max repair attempts before rejection
+- `signer`: optional custom signing function for `verify_and_sign()`
+
+---
+
+## 🧪 Testing
+
+```bash
+python -m pytest tests/ -v
+```
+
+---
+
+## 🛡️ Philosophy
+
+> “AI should not just generate outputs — it should stay faithful to intent.”
+
+SIP enforces that principle at runtime.
+
+---
+
+## Licensing & Commercial Use
+
+- Core SDK (SIP) is licensed under AGPL-3.0.
+- **AI Sentinel** (the full monitoring system) is a separate commercial product and is **not open source**.
+- Companies can use SIP under AGPL terms.
+- For commercial hosted service, white-label, or custom enterprise versions, please contact us.

state_integrity_protocol-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+sip/__init__.py,sha256=dySESO1yK5DMoXUHlbsNk6q_0TFoddzDWekzag0Ot6g,963
+sip/anchor.py,sha256=-4H27MRss3zMeXHgB-ehnmgjq5gnO9nTXx5F1IXeh1w,2142
+sip/embeddings.py,sha256=W22g4CZbonlZzgmUMJmAo_Thj62TL5WSTRulGfnlPOE,2454
+sip/middleware.py,sha256=fzm3uKn4KU_ZlOIX1Vjft3uABLlS_UoUGSAnXuetjJo,12468
+sip/observer.py,sha256=QKR9YjvT78xeKM0mBRghj0VHL4otoIfgEwtGbtlE2M4,4549
+sip/protocol.py,sha256=OErjfOAq6B8PNA5IZ4HHFoExIefdI_NathOS0210L7g,6669
+state_integrity_protocol-0.1.0.dist-info/licenses/LICENSE,sha256=_ySFkMWvtsIxcUjUcecXO_JHHLCHS6GzAsr7yk5BI28,1425
+state_integrity_protocol-0.1.0.dist-info/METADATA,sha256=DmXvOKlXPRl6F12_lQuDLnobrOAHyDLukDTGrmRaLo0,5407
+state_integrity_protocol-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+state_integrity_protocol-0.1.0.dist-info/top_level.txt,sha256=T0YIgLIWZ6nOkXD5hSLgyJws00m9f92moovVmzTDV_s,4
+state_integrity_protocol-0.1.0.dist-info/RECORD,,

state_integrity_protocol-0.1.0.dist-info/WHEEL

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

state_integrity_protocol-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2026 sijan324 (sijangautamx@gmail.com)
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  DEVELOPER WARNING FOR COMMERCIAL USERS: If you modify this Program or 
+run a derivative version of it on a network server to provide cloud 
+services, you MUST legally open-source your entire cloud platform code 
+to the public under the same AGPL-3.0 terms. If you do not wish to share 
+your server code, you must purchase a private proprietary corporate 
+license from the original copyright holder (sijan324).
+
+[The remaining standard full text of the GNU AGPL v3 license applies 
+here to govern this repository and its mathematical test suites.]

state_integrity_protocol-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sip