rmic-guard 0.1.0__tar.gz

rmic_guard-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: rmic-guard
+Version: 0.1.0
+Summary: Role-boundary preservation and identity-drift detection for autonomous LLM agents.
+Author-email: Arshitha S <arshitha.s1104@gmail.com>, Charithra H S <charithrahs@gmail.com>, Chandrakala <chandanah1605@gmail.com>, Neethu B Krishna <Neethu.b.krishna10@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Arshu-1104/RMIC
+Project-URL: Repository, https://github.com/Arshu-1104/RMIC
+Keywords: llm,agents,safety,guardrails,prompt-injection,drift-detection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: litellm>=1.56.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: scipy>=1.13.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: PyYAML>=6.0.0
+Requires-Dist: fastembed>=0.2.0
+Provides-Extra: torch
+Requires-Dist: sentence-transformers>=3.0.0; extra == "torch"
+
+# rmic-guard
+
+Role-boundary preservation and identity-drift detection for autonomous LLM agents.
+
+`rmic-guard` gives an agent a **contract** — an explicit statement of its role,
+allowed/forbidden tools, and data-access scope — and enforces it at runtime
+with two layers:
+
+- **Hard rules**: exact-match checks on tool names, parameter bounds, and data scope.
+- **IDS (Identity Drift Score)**: an embedding-based signal (role distance,
+  semantic grounding, trajectory curvature) that flags gradual drift a
+  hard-rule check alone would miss.
+
+## Install
+
+```bash
+pip install rmic-guard
+```
+
+If your platform can't run `fastembed`'s ONNX backend, install the
+PyTorch-based fallback instead:
+
+```bash
+pip install "rmic-guard[torch]"
+```
+
+## Quickstart
+
+```python
+from rmic_guard import load_contract, EnforcementEngine, ClaudeReasoning
+
+# 1. Load a role contract (see contracts/*.json in the repo for examples)
+contract = load_contract("contracts/financial_agent.json")
+
+# 2. Plan a tool call from a user message
+reasoning = ClaudeReasoning()  # reads ANTHROPIC_API_KEY from the environment
+plan = reasoning.plan_tool_call(
+    "What's my current account balance?",
+    contract=contract,
+    condition="C",
+)
+
+# 3. Enforce the contract before executing
+engine = EnforcementEngine(contract=contract, tools=my_tool_registry, ledger=None)
+outcome = engine.evaluate_and_maybe_execute(
+    plan,
+    recent_ids=[],       # pass prior IDS scores for trajectory tracking across a session
+    drift_type=None,
+    execute_tool=True,
+    enforcement_mode="full",  # "full" | "hard_rules_only" | "ids_only"
+)
+
+print(outcome.decision)  # "PASS" | "WARN" | "BLOCK" | "NEEDS_RECOVERY" | "PREEMPTIVE_WARN"
+```
+
+Groq (Llama/Mixtral) is supported as a drop-in alternative to Claude:
+
+```python
+from rmic_guard import GroqReasoning
+reasoning = GroqReasoning(model_name="groq/llama-3.3-70b-versatile")
+```
+
+## Writing a contract
+
+A contract is a JSON file describing the agent's role, its allowed and
+forbidden tools, parameter constraints, and data-access scope. See the
+`contracts/` directory in the [GitHub repo](https://github.com/Charithra207/RMIC-guard)
+for real examples across financial, support, healthcare-research, and
+legal-review agent roles.
+
+## Status
+
+This is an early (0.1.x) release from an active research project on
+role-boundary preservation in autonomous agents. APIs may change between
+minor versions until 1.0. Issues and contributions welcome on GitHub.
+
+## License
+
+MIT

rmic_guard-0.1.0/PYPI_README.md

@@ -0,0 +1,79 @@
+# rmic-guard
+
+Role-boundary preservation and identity-drift detection for autonomous LLM agents.
+
+`rmic-guard` gives an agent a **contract** — an explicit statement of its role,
+allowed/forbidden tools, and data-access scope — and enforces it at runtime
+with two layers:
+
+- **Hard rules**: exact-match checks on tool names, parameter bounds, and data scope.
+- **IDS (Identity Drift Score)**: an embedding-based signal (role distance,
+  semantic grounding, trajectory curvature) that flags gradual drift a
+  hard-rule check alone would miss.
+
+## Install
+
+```bash
+pip install rmic-guard
+```
+
+If your platform can't run `fastembed`'s ONNX backend, install the
+PyTorch-based fallback instead:
+
+```bash
+pip install "rmic-guard[torch]"
+```
+
+## Quickstart
+
+```python
+from rmic_guard import load_contract, EnforcementEngine, ClaudeReasoning
+
+# 1. Load a role contract (see contracts/*.json in the repo for examples)
+contract = load_contract("contracts/financial_agent.json")
+
+# 2. Plan a tool call from a user message
+reasoning = ClaudeReasoning()  # reads ANTHROPIC_API_KEY from the environment
+plan = reasoning.plan_tool_call(
+    "What's my current account balance?",
+    contract=contract,
+    condition="C",
+)
+
+# 3. Enforce the contract before executing
+engine = EnforcementEngine(contract=contract, tools=my_tool_registry, ledger=None)
+outcome = engine.evaluate_and_maybe_execute(
+    plan,
+    recent_ids=[],       # pass prior IDS scores for trajectory tracking across a session
+    drift_type=None,
+    execute_tool=True,
+    enforcement_mode="full",  # "full" | "hard_rules_only" | "ids_only"
+)
+
+print(outcome.decision)  # "PASS" | "WARN" | "BLOCK" | "NEEDS_RECOVERY" | "PREEMPTIVE_WARN"
+```
+
+Groq (Llama/Mixtral) is supported as a drop-in alternative to Claude:
+
+```python
+from rmic_guard import GroqReasoning
+reasoning = GroqReasoning(model_name="groq/llama-3.3-70b-versatile")
+```
+
+## Writing a contract
+
+A contract is a JSON file describing the agent's role, its allowed and
+forbidden tools, parameter constraints, and data-access scope. See the
+`contracts/` directory in the [GitHub repo](https://github.com/Charithra207/RMIC-guard)
+for real examples across financial, support, healthcare-research, and
+legal-review agent roles.
+
+## Status
+
+This is an early (0.1.x) release from an active research project on
+role-boundary preservation in autonomous agents. APIs may change between
+minor versions until 1.0. Issues and contributions welcome on GitHub.
+
+## License
+
+MIT

rmic_guard-0.1.0/README.md

@@ -0,0 +1,160 @@
+# RMIC-Guard
+
+**Role-Model Identity Contract Guard** — research framework proving that enforcement
+position (external middleware vs. in-prompt self-policing) is the primary determinant
+of role identity drift suppression in autonomous LLM agents.
+
+---
+
+## Prerequisites
+
+- Python 3.11 (Windows recommended)
+- Anthropic API key (`sk-ant-...`) with credits
+
+---
+
+## Setup
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+```
+
+Create `.env` in the project root:
+
+```
+ANTHROPIC_API_KEY=your_key_here
+ANTHROPIC_MODEL=claude-sonnet-4-6
+GEMINI_API_KEY=your_key_here
+GROQ_API_KEY=your_key_here
+```
+
+---
+
+## Validate
+
+```powershell
+python setup.py
+```
+
+Expected: 6/6 checks pass.
+
+---
+
+## Run Experiment
+
+**Test one provider first** (60 API calls):
+
+```powershell
+python -m experiment.runner --test --provider anthropic
+```
+
+Expected output: `rows_inserted=60`
+
+Test Gemini only:
+
+```powershell
+python -m experiment.runner --test --provider gemini
+```
+
+Test Groq only:
+
+```powershell
+python -m experiment.runner --test --provider groq
+```
+
+Run multi-model comparison (all available providers with keys):
+
+```powershell
+python -m experiment.runner --test --multi-model --compare-providers
+```
+
+**Full run** (1,300 API calls per run, ~$8–15 at Sonnet 4.6 pricing):
+
+```powershell
+python -m experiment.runner
+```
+
+Run 3 times for statistical variance.
+
+---
+
+## Statistical Report
+
+```powershell
+python -m experiment.statistical_tests
+```
+
+Requires 2+ full runs. Report saved to `results/statistical_report.txt`.
+
+---
+
+## Dashboard
+
+```powershell
+python -m uvicorn dashboard.app:app --reload --port 8001
+```
+
+Open `http://127.0.0.1:8001` — use the run selector to switch between runs.
+
+---
+
+## Experimental Design
+
+**4 Roles:** `financial_agent`, `support_agent`, `healthcare_research_agent`, `legal_review_agent`
+
+**5 Conditions:**
+
+| Condition | Description |
+|---|---|
+| `A_no_contract` | Baseline — no contract, no enforcement |
+| `B_prompt_contract` | Contract in system prompt — LLM self-polices |
+| `C_rmic_middleware` | External middleware — full dual-pass enforcement |
+| `C1_hard_rules_only` | Ablation — hard rules only, no IDS |
+| `C2_ids_only` | Ablation — semantic IDS only, no hard rules |
+
+**65 prompts per role per condition:** 50 adversarial + 10 generic legitimate + 5 role-specific legitimate
+
+---
+
+## IDS Metrics (7 Independent Signals)
+
+| Metric | Description |
+|---|---|
+| Base IDS | 0.4 × RoleDistance + 0.4 × SemanticGrounding + 0.2 × TrajectoryCurvature |
+| Mahalanobis | Covariance-aware distance in 384-dim embedding space |
+| KL Divergence | Asymmetric early-warning divergence signal |
+| Jensen–Shannon | Primary enforcement metric — symmetric, bounded [0, 1] |
+| Wasserstein | Geometry-aware Earth Mover's Distance |
+| Hellinger | Tail-sensitive, bounded [0, 1] |
+| Tool Frequency | Behavioral pattern drift across session window |
+
+All 7 computed independently. Never blended.
+
+---
+
+## Key Metrics
+
+| Metric | Definition |
+|---|---|
+| DSR | Drift Suppression Rate = blocked / expected_drift |
+| DDR | Drift Detection Rate = detected / expected_drift |
+| FPR | False Positive Rate = false_detections / legitimate |
+
+---
+
+## Exports
+
+Each full run auto-exports to `results/exports/{run_id}.csv` (1,300 rows, 22 columns).
+
+---
+
+## Team Branches
+
+| Branch | Scope |
+|---|---|
+| `charithra/core` | Core engine |
+| `chandrakala/experiment` | Experiment pipeline |
+| `arshitha/dashboard` | Dashboard |
+| `neethu/contracts` | Contracts and prompts |

rmic_guard-0.1.0/core/audit_ledger.py

@@ -0,0 +1,116 @@
+"""Append-only audit ledger with per-entry Ed25519 signatures."""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from hashlib import sha256
+from pathlib import Path
+from typing import Any, Mapping
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+__all__ = ["AuditEntry", "AuditLedger"]
+
+
+def _utc_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass(frozen=True)
+class AuditEntry:
+    timestamp: str
+    agent_id: str
+    input_hash: str
+    ids_score: float
+    drift_type: str | None
+    drift_velocity: float | None
+    decision: str
+    contract_hash: str
+    recovery_attempted: bool
+    role_distance: float | None = None
+    semantic_grounding: float | None = None
+    trajectory_curvature: float | None = None
+    failure_reason: str | None = None
+    false_positive: bool = False
+    false_negative: bool = False
+
+
+class AuditLedger:
+    """
+    Append-only JSONL ledger. Each line is a JSON object:
+    { "entry": {...}, "signature": "<base64>" }
+    """
+
+    def __init__(self, path: str | Path, private_key: Ed25519PrivateKey | None = None) -> None:
+        self.path = Path(path)
+        self._private_key = private_key or Ed25519PrivateKey.generate()
+        self._public_key = self._private_key.public_key()
+
+    @property
+    def public_key(self) -> Ed25519PublicKey:
+        return self._public_key
+
+    def public_key_bytes(self) -> bytes:
+        return self._public_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+
+    def append(self, entry: AuditEntry) -> None:
+        payload = json.dumps(asdict(entry), sort_keys=True, separators=(",", ":")).encode("utf-8")
+        sig = self._private_key.sign(payload)
+        line = json.dumps(
+            {
+                "entry": asdict(entry),
+                "signature": base64.b64encode(sig).decode("ascii"),
+            },
+            separators=(",", ":"),
+        )
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(line + "\n")
+
+    @staticmethod
+    def verify_line(line: str, public_key: Ed25519PublicKey) -> bool:
+        obj = json.loads(line)
+        entry = obj["entry"]
+        sig = base64.b64decode(obj["signature"])
+        payload = json.dumps(entry, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        try:
+            public_key.verify(sig, payload)
+        except Exception:
+            return False
+        return True
+
+
+def hash_text(text: str) -> str:
+    """SHA-256 hex digest of UTF-8 text (for input_hash)."""
+    return sha256(text.encode("utf-8")).hexdigest()
+
+
+def entry_from_mapping(m: Mapping[str, Any]) -> AuditEntry:
+    return AuditEntry(
+        timestamp=str(m["timestamp"]),
+        agent_id=str(m["agent_id"]),
+        input_hash=str(m["input_hash"]),
+        ids_score=float(m["ids_score"]),
+        role_distance=None if m.get("role_distance") is None else float(m["role_distance"]),
+        semantic_grounding=(
+            None if m.get("semantic_grounding") is None else float(m["semantic_grounding"])
+        ),
+        trajectory_curvature=(
+            None if m.get("trajectory_curvature") is None else float(m["trajectory_curvature"])
+        ),
+        drift_type=m.get("drift_type"),
+        drift_velocity=None if m.get("drift_velocity") is None else float(m["drift_velocity"]),
+        decision=str(m["decision"]),
+        failure_reason=(None if m.get("failure_reason") is None else str(m.get("failure_reason"))),
+        false_positive=bool(m.get("false_positive", False)),
+        false_negative=bool(m.get("false_negative", False)),
+        contract_hash=str(m["contract_hash"]),
+        recovery_attempted=bool(m["recovery_attempted"]),
+    )

rmic_guard-0.1.0/core/contract_loader.py

@@ -0,0 +1,218 @@
+"""Load, cryptographically seal, and verify RMIC identity contracts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping
+from utils.config import load_config
+
+__all__ = [
+    "DataScope",
+    "ParameterConstraint",
+    "RMICContract",
+    "canonical_contract_dict_for_hash",
+    "compute_contract_hash",
+    "load_contract",
+    "seal_contract_file",
+]
+
+
+def canonical_contract_dict_for_hash(data: Mapping[str, Any]) -> dict[str, Any]:
+    """Return a JSON-serialisable dict for hashing (excludes contract_hash only)."""
+    return {k: v for k, v in sorted(data.items()) if k != "contract_hash"}
+
+
+def compute_contract_hash(data: Mapping[str, Any]) -> str:
+    """SHA-256 over stable JSON of all fields except contract_hash."""
+    payload = canonical_contract_dict_for_hash(dict(data))
+    blob = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(blob).hexdigest()
+
+
+@dataclass(frozen=True)
+class DataScope:
+    """Immutable data-scope slice from the contract JSON."""
+
+    accessible: tuple[str, ...]
+    prohibited: tuple[str, ...]
+    pii_categories: tuple[str, ...]
+
+    @staticmethod
+    def from_mapping(m: Mapping[str, Any]) -> DataScope:
+        return DataScope(
+            accessible=tuple(m.get("accessible") or ()),
+            prohibited=tuple(m.get("prohibited") or ()),
+            pii_categories=tuple(m.get("pii_categories") or ()),
+        )
+
+
+@dataclass(frozen=True)
+class ParameterConstraint:
+    """Single parameter bound as loaded from the contract."""
+
+    name: str
+    max: float | int | None
+    min: float | int | None
+    value_type: str
+
+    @staticmethod
+    def from_entry(name: str, spec: Mapping[str, Any]) -> ParameterConstraint:
+        return ParameterConstraint(
+            name=name,
+            max=spec.get("max"),
+            min=spec.get("min"),
+            value_type=str(spec.get("type", "float")),
+        )
+
+
+@dataclass(frozen=True)
+class RMICContract:
+    """Frozen runtime identity contract. No field may change after construction."""
+
+    agent_id: str
+    role_name: str
+    sector: str
+    role_description: str
+    semantic_anchors: tuple[str, ...]
+    allowed_actions: tuple[str, ...]
+    forbidden_actions: tuple[str, ...]
+    data_scope: DataScope
+    parameter_constraints: tuple[ParameterConstraint, ...]
+    ids_warn_threshold: float
+    ids_block_threshold: float
+    drift_velocity_threshold: float
+    recovery_policy: str
+    compliance_tags: tuple[str, ...]
+    contract_version: str
+    created_at: str | None
+    contract_hash: str
+    anchor_embedding: tuple[float, ...]
+
+    def constraints_by_name(self) -> dict[str, ParameterConstraint]:
+        return {c.name: c for c in self.parameter_constraints}
+
+
+def _as_tuple_str(v: Any) -> tuple[str, ...]:
+    if v is None:
+        return ()
+    if isinstance(v, str):
+        return (v,)
+    return tuple(str(x) for x in v)
+
+
+def _contract_from_dict(data: dict[str, Any], *, require_hash_match: bool) -> RMICContract:
+    cfg = load_config()
+    tcfg = cfg.get("thresholds", {})
+    stored_hash = data.get("contract_hash")
+    if require_hash_match:
+        if not stored_hash:
+            raise ValueError("contract_hash missing; seal the contract before load with verify")
+        computed = compute_contract_hash(data)
+        if computed != stored_hash:
+            raise ValueError("contract_hash mismatch — contract was tampered with or corrupted")
+
+    ds_raw = data.get("data_scope") or {}
+    if not isinstance(ds_raw, dict):
+        raise TypeError("data_scope must be an object")
+
+    pc_raw = data.get("parameter_constraints") or {}
+    if not isinstance(pc_raw, dict):
+        raise TypeError("parameter_constraints must be an object")
+
+    constraints: list[ParameterConstraint] = []
+    for name in sorted(pc_raw.keys()):
+        spec = pc_raw[name]
+        if not isinstance(spec, dict):
+            raise TypeError(f"parameter_constraints.{name} must be an object")
+        constraints.append(ParameterConstraint.from_entry(name, spec))
+
+    anchors = _as_tuple_str(data.get("semantic_anchors"))
+    if not anchors:
+        raise ValueError("semantic_anchors must contain at least one sentence")
+
+    emb = data.get("anchor_embedding")
+    if emb is None:
+        anchor_embedding: tuple[float, ...] = ()
+    else:
+        if not isinstance(emb, list):
+            raise TypeError("anchor_embedding must be a list of floats (seal the contract first)")
+        anchor_embedding = tuple(float(x) for x in emb)
+
+    return RMICContract(
+        agent_id=str(data["agent_id"]),
+        role_name=str(data["role_name"]),
+        sector=str(data["sector"]),
+        role_description=str(data.get("role_description", "")),
+        semantic_anchors=anchors,
+        allowed_actions=_as_tuple_str(data.get("allowed_actions")),
+        forbidden_actions=_as_tuple_str(data.get("forbidden_actions")),
+        data_scope=DataScope.from_mapping(ds_raw),
+        parameter_constraints=tuple(constraints),
+        ids_warn_threshold=float(
+            data.get("ids_warn_threshold", data.get("warn_threshold", tcfg.get("warn_threshold", 0.35)))
+        ),
+        ids_block_threshold=float(
+            data.get("ids_block_threshold", data.get("block_threshold", tcfg.get("block_threshold", 0.60)))
+        ),
+        drift_velocity_threshold=float(
+            data.get(
+                "drift_velocity_threshold",
+                data.get("velocity_threshold", tcfg.get("velocity_threshold", 0.05)),
+            )
+        ),
+        recovery_policy=str(data.get("recovery_policy", "re-anchor")),
+        compliance_tags=_as_tuple_str(data.get("compliance_tags")),
+        contract_version=str(data.get("contract_version", "1.0.0")),
+        created_at=data.get("created_at"),
+        contract_hash=str(stored_hash or compute_contract_hash(data)),
+        anchor_embedding=anchor_embedding,
+    )
+
+
+def load_contract(path: str | Path, *, verify_hash: bool = True) -> RMICContract:
+    """Load a contract JSON file and optionally verify SHA-256 integrity."""
+    p = Path(path)
+    raw = json.loads(p.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise TypeError("contract file must contain a JSON object")
+    return _contract_from_dict(raw, require_hash_match=verify_hash)
+
+
+def seal_contract_file(
+    path: str | Path,
+    *,
+    write_back: bool = True,
+    model_name: str | None = None,
+) -> RMICContract:
+    """
+    Compute anchor_embedding (once) and contract_hash, optionally persist to disk.
+
+    anchor_embedding is the L2-normalised mean embedding of semantic_anchors.
+    """
+    from core.embedder import anchor_centroid_from_anchors
+
+    p = Path(path)
+    data = json.loads(p.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise TypeError("contract file must contain a JSON object")
+
+    anchors = _as_tuple_str(data.get("semantic_anchors"))
+    if not anchors:
+        raise ValueError("semantic_anchors must contain at least one sentence")
+
+    centroid = anchor_centroid_from_anchors(list(anchors), model_name=model_name)
+    data["anchor_embedding"] = [float(x) for x in centroid.tolist()]
+
+    if data.get("created_at") in (None, ""):
+        data["created_at"] = datetime.now(timezone.utc).isoformat()
+
+    data["contract_hash"] = compute_contract_hash(data)
+
+    if write_back:
+        p.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    return _contract_from_dict(data, require_hash_match=True)