langchain-verigent 0.1.0__tar.gz

langchain_verigent-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: langchain-verigent
+Version: 0.1.0
+Summary: Verigent trust verification for LangChain agents, chains, and tools
+Project-URL: Homepage, https://verigent.ai
+Project-URL: Repository, https://github.com/verigentai/langchain-verigent
+Author-email: verigentai <dev@verigent.ai>
+License-Expression: MIT
+Keywords: agents,langchain,trust,verification,verigent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=0.2.0
+Provides-Extra: verify
+Requires-Dist: httpx>=0.25.0; extra == 'verify'
+Description-Content-Type: text/markdown
+
+# langchain-verigent
+
+Trust verification for LangChain agents, chains, and tools using [Verigent](https://verigent.ai) keys.
+
+## The problem
+
+Multi-agent LangChain pipelines delegate tasks to sub-agents and tools with no way to verify trust, capability, or identity. Any agent can claim any role. `langchain-verigent` adds cryptographic trust verification to your pipeline — every agent carries a VG key that declares what it is and what it can do.
+
+## Install
+
+```bash
+pip install langchain-verigent
+```
+
+## Quick start
+
+### Callback handler (recommended)
+
+Attach to any agent executor to automatically verify VG keys on tool calls:
+
+```python
+from langchain_verigent import VerigentCallbackHandler
+
+handler = VerigentCallbackHandler(
+    min_tier=2,          # Require at least V2
+    threshold=0.5,       # 50% composite trust minimum
+    block_untrusted=True # Raise TrustDeniedError on failure
+)
+
+# Attach to your agent
+result = agent_executor.invoke(
+    {"input": "Research this topic"},
+    config={"callbacks": [handler]}
+)
+
+# Inspect trust decisions
+for entry in handler.trust_log:
+    print(f"{entry['handle']}: {entry['composite']}% — {'PASS' if entry['passed'] else 'FAIL'}")
+```
+
+### Tool wrapper
+
+Wrap any tool to attach a VG key and verify trust before execution:
+
+```python
+from langchain_verigent import VerigentToolWrapper
+from langchain_community.tools import TavilySearchResults
+
+search = TavilySearchResults()
+trusted_search = VerigentToolWrapper(
+    search,
+    vg_key="VG:SEARCH-01:V3-SENT·Se4Op7An5Ar9Co2Ad6St8Sc3Sa5So1Br2Fo6",
+    threshold=0.4
+)
+
+result = trusted_search.invoke("latest AI papers")
+print(f"Trust: {trusted_search.trust_score.percent}%")
+```
+
+### Agent filter (multi-agent)
+
+Filter and rank agents by trust score:
+
+```python
+from langchain_verigent import VerigentAgentFilter
+
+agents = [
+    {"name": "researcher", "vg_key": "VG:RES-01:V4-ANAL·Se4Op7An5Ar9Co2Ad6St8Sc3Sa5So1Br2Fo6"},
+    {"name": "writer",     "vg_key": "VG:WRT-02:V2-SAGE·Se2Op3An4Ar2Co5Ad3St4Sc2Sa8So1Br3Fo2"},
+    {"name": "untrusted",  "vg_key": "VG:BAD-99:V0-SENT·Se1Op1An1Ar1Co1Ad1St1Sc1Sa1So1Br1Fo1"},
+]
+
+filter = VerigentAgentFilter(min_tier=2, threshold=0.4)
+
+# Only agents meeting threshold
+trusted = filter.filter(agents)  # [researcher, writer]
+
+# Ranked by composite score
+ranked = filter.rank(agents)  # [researcher, writer, untrusted]
+```
+
+## VG Key format
+
+```
+VG:{NAME}-{SUFFIX}:{TIER}-{PRIMARY}·{12×class_code+digit}
+```
+
+- **Tier**: V0 (unverified) through V6 (sovereign-grade)
+- **Primary**: 4-letter class code (e.g. ARCH, SENT, ANAL)
+- **Scores**: 12 class dimensions, each 0-9
+
+Classes: Sentinel, Operative, Analyst, Architect, Conduit, Adaptor, Steward, Scout, Sage, Sovereign, Broker, Forge.
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `min_tier` | 0 | Minimum tier to pass (0-6) |
+| `threshold` | 0.5 | Minimum composite score (0.0-1.0) |
+| `required_classes` | None | Class codes to weight in scoring |
+| `block_untrusted` | False | Raise error on trust failure |
+
+## Links
+
+- [Verigent](https://verigent.ai) — Agent trust verification
+- [GitHub](https://github.com/verigentai/langchain-verigent)
+- [LangChain](https://python.langchain.com)
+
+## License
+
+MIT

langchain_verigent-0.1.0/README.md

@@ -0,0 +1,111 @@
+# langchain-verigent
+
+Trust verification for LangChain agents, chains, and tools using [Verigent](https://verigent.ai) keys.
+
+## The problem
+
+Multi-agent LangChain pipelines delegate tasks to sub-agents and tools with no way to verify trust, capability, or identity. Any agent can claim any role. `langchain-verigent` adds cryptographic trust verification to your pipeline — every agent carries a VG key that declares what it is and what it can do.
+
+## Install
+
+```bash
+pip install langchain-verigent
+```
+
+## Quick start
+
+### Callback handler (recommended)
+
+Attach to any agent executor to automatically verify VG keys on tool calls:
+
+```python
+from langchain_verigent import VerigentCallbackHandler
+
+handler = VerigentCallbackHandler(
+    min_tier=2,          # Require at least V2
+    threshold=0.5,       # 50% composite trust minimum
+    block_untrusted=True # Raise TrustDeniedError on failure
+)
+
+# Attach to your agent
+result = agent_executor.invoke(
+    {"input": "Research this topic"},
+    config={"callbacks": [handler]}
+)
+
+# Inspect trust decisions
+for entry in handler.trust_log:
+    print(f"{entry['handle']}: {entry['composite']}% — {'PASS' if entry['passed'] else 'FAIL'}")
+```
+
+### Tool wrapper
+
+Wrap any tool to attach a VG key and verify trust before execution:
+
+```python
+from langchain_verigent import VerigentToolWrapper
+from langchain_community.tools import TavilySearchResults
+
+search = TavilySearchResults()
+trusted_search = VerigentToolWrapper(
+    search,
+    vg_key="VG:SEARCH-01:V3-SENT·Se4Op7An5Ar9Co2Ad6St8Sc3Sa5So1Br2Fo6",
+    threshold=0.4
+)
+
+result = trusted_search.invoke("latest AI papers")
+print(f"Trust: {trusted_search.trust_score.percent}%")
+```
+
+### Agent filter (multi-agent)
+
+Filter and rank agents by trust score:
+
+```python
+from langchain_verigent import VerigentAgentFilter
+
+agents = [
+    {"name": "researcher", "vg_key": "VG:RES-01:V4-ANAL·Se4Op7An5Ar9Co2Ad6St8Sc3Sa5So1Br2Fo6"},
+    {"name": "writer",     "vg_key": "VG:WRT-02:V2-SAGE·Se2Op3An4Ar2Co5Ad3St4Sc2Sa8So1Br3Fo2"},
+    {"name": "untrusted",  "vg_key": "VG:BAD-99:V0-SENT·Se1Op1An1Ar1Co1Ad1St1Sc1Sa1So1Br1Fo1"},
+]
+
+filter = VerigentAgentFilter(min_tier=2, threshold=0.4)
+
+# Only agents meeting threshold
+trusted = filter.filter(agents)  # [researcher, writer]
+
+# Ranked by composite score
+ranked = filter.rank(agents)  # [researcher, writer, untrusted]
+```
+
+## VG Key format
+
+```
+VG:{NAME}-{SUFFIX}:{TIER}-{PRIMARY}·{12×class_code+digit}
+```
+
+- **Tier**: V0 (unverified) through V6 (sovereign-grade)
+- **Primary**: 4-letter class code (e.g. ARCH, SENT, ANAL)
+- **Scores**: 12 class dimensions, each 0-9
+
+Classes: Sentinel, Operative, Analyst, Architect, Conduit, Adaptor, Steward, Scout, Sage, Sovereign, Broker, Forge.
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `min_tier` | 0 | Minimum tier to pass (0-6) |
+| `threshold` | 0.5 | Minimum composite score (0.0-1.0) |
+| `required_classes` | None | Class codes to weight in scoring |
+| `block_untrusted` | False | Raise error on trust failure |
+
+## Links
+
+- [Verigent](https://verigent.ai) — Agent trust verification
+- [GitHub](https://github.com/verigentai/langchain-verigent)
+- [LangChain](https://python.langchain.com)
+
+## License
+
+MIT

langchain_verigent-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-verigent"
+version = "0.1.0"
+description = "Verigent trust verification for LangChain agents, chains, and tools"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "verigentai", email = "dev@verigent.ai" },
+]
+keywords = ["langchain", "verigent", "trust", "agents", "verification"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "langchain-core>=0.2.0",
+]
+
+[project.optional-dependencies]
+verify = ["httpx>=0.25.0"]
+
+[project.urls]
+Homepage = "https://verigent.ai"
+Repository = "https://github.com/verigentai/langchain-verigent"

langchain_verigent-0.1.0/src/langchain_verigent/__init__.py

@@ -0,0 +1,25 @@
+"""langchain-verigent — Trust verification for LangChain agents and chains."""
+
+from .middleware import (
+    TrustDeniedError,
+    VerigentAgentFilter,
+    VerigentCallbackHandler,
+    VerigentToolWrapper,
+)
+from .parser import CLASS_CODES, VGKey, extract_vg_key, parse_vg_key
+from .trust import TrustScore, evaluate_trust
+
+__all__ = [
+    "CLASS_CODES",
+    "TrustDeniedError",
+    "TrustScore",
+    "VGKey",
+    "VerigentAgentFilter",
+    "VerigentCallbackHandler",
+    "VerigentToolWrapper",
+    "evaluate_trust",
+    "extract_vg_key",
+    "parse_vg_key",
+]
+
+__version__ = "0.1.0"

langchain_verigent-0.1.0/src/langchain_verigent/middleware.py

@@ -0,0 +1,209 @@
+"""LangChain integration — callback handler, tool wrapper, agent filter."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional, Sequence
+
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.tools import BaseTool
+
+from .parser import VGKey, extract_vg_key, parse_vg_key
+from .trust import TrustScore, evaluate_trust
+
+logger = logging.getLogger("langchain_verigent")
+
+
+class VerigentCallbackHandler(BaseCallbackHandler):
+    """LangChain callback handler that intercepts tool calls and verifies VG keys.
+
+    Attach to any agent executor or chain to log trust decisions on tool
+    invocations and optionally block untrusted calls.
+
+    Usage:
+        from langchain_verigent import VerigentCallbackHandler
+
+        handler = VerigentCallbackHandler(min_tier=2, threshold=0.5)
+        agent_executor.invoke({"input": "..."}, config={"callbacks": [handler]})
+    """
+
+    def __init__(
+        self,
+        *,
+        min_tier: int = 0,
+        threshold: float = 0.5,
+        required_classes: Optional[list[str]] = None,
+        block_untrusted: bool = False,
+    ):
+        self.min_tier = min_tier
+        self.threshold = threshold
+        self.required_classes = required_classes
+        self.block_untrusted = block_untrusted
+        self.trust_log: list[dict[str, Any]] = []
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        **kwargs: Any,
+    ) -> None:
+        """Check VG key in tool metadata before execution."""
+        metadata = kwargs.get("metadata") or {}
+        key = extract_vg_key(metadata=metadata)
+
+        if key:
+            score = evaluate_trust(
+                key,
+                required_classes=self.required_classes,
+                min_tier=self.min_tier,
+                threshold=self.threshold,
+            )
+            entry = {
+                "tool": serialized.get("name", "unknown"),
+                "handle": key.handle,
+                "tier": key.tier_label,
+                "composite": score.percent,
+                "passed": score.meets_threshold,
+            }
+            self.trust_log.append(entry)
+
+            if score.meets_threshold:
+                logger.info("TRUST PASS: %s (%s, %d%%)", key.handle, key.tier_label, score.percent)
+            else:
+                logger.warning(
+                    "TRUST FAIL: %s (%s, %d%%)", key.handle, key.tier_label, score.percent
+                )
+                if self.block_untrusted:
+                    raise TrustDeniedError(
+                        f"Agent {key.handle} ({key.tier_label}) below trust threshold "
+                        f"({score.percent}% < {int(self.threshold * 100)}%)"
+                    )
+        else:
+            logger.debug("No VG key found for tool: %s", serialized.get("name", "unknown"))
+
+
+class TrustDeniedError(Exception):
+    """Raised when an agent fails trust verification and blocking is enabled."""
+
+    pass
+
+
+class VerigentToolWrapper:
+    """Wraps a LangChain tool to add VG key verification to its responses.
+
+    The wrapper checks the tool's metadata or output for a VG key and
+    annotates the result with trust information.
+
+    Usage:
+        from langchain_verigent import VerigentToolWrapper
+        from langchain_community.tools import TavilySearchResults
+
+        search = TavilySearchResults()
+        trusted_search = VerigentToolWrapper(search, vg_key="VG:SEARCH-01:V3-SENT·...")
+    """
+
+    def __init__(
+        self,
+        tool: BaseTool,
+        *,
+        vg_key: Optional[str] = None,
+        min_tier: int = 0,
+        threshold: float = 0.5,
+    ):
+        self.tool = tool
+        self.min_tier = min_tier
+        self.threshold = threshold
+        self._key: Optional[VGKey] = parse_vg_key(vg_key) if vg_key else None
+        self._last_score: Optional[TrustScore] = None
+
+    @property
+    def name(self) -> str:
+        return self.tool.name
+
+    @property
+    def description(self) -> str:
+        return self.tool.description
+
+    @property
+    def trust_score(self) -> Optional[TrustScore]:
+        return self._last_score
+
+    def invoke(self, input: Any, **kwargs: Any) -> Any:
+        """Run the tool with trust verification."""
+        if self._key:
+            self._last_score = evaluate_trust(
+                self._key, min_tier=self.min_tier, threshold=self.threshold
+            )
+            if not self._last_score.meets_threshold:
+                logger.warning(
+                    "Tool %s: trust below threshold (%d%%)",
+                    self.tool.name,
+                    self._last_score.percent,
+                )
+
+        return self.tool.invoke(input, **kwargs)
+
+
+class VerigentAgentFilter:
+    """Filters and ranks agents by trust score for multi-agent setups.
+
+    Usage:
+        from langchain_verigent import VerigentAgentFilter
+
+        agents = [
+            {"name": "researcher", "vg_key": "VG:RES-01:V4-ANAL·..."},
+            {"name": "writer", "vg_key": "VG:WRT-02:V2-SAGE·..."},
+        ]
+        filter = VerigentAgentFilter(min_tier=2, threshold=0.4)
+        trusted = filter.filter(agents)
+        ranked = filter.rank(agents)
+    """
+
+    def __init__(
+        self,
+        *,
+        min_tier: int = 0,
+        threshold: float = 0.5,
+        required_classes: Optional[list[str]] = None,
+    ):
+        self.min_tier = min_tier
+        self.threshold = threshold
+        self.required_classes = required_classes
+
+    def evaluate(self, agent_config: dict[str, Any]) -> Optional[TrustScore]:
+        """Evaluate a single agent config. Expects 'vg_key' field."""
+        raw = agent_config.get("vg_key")
+        if not raw:
+            return None
+        key = parse_vg_key(raw)
+        if not key:
+            return None
+        return evaluate_trust(
+            key,
+            required_classes=self.required_classes,
+            min_tier=self.min_tier,
+            threshold=self.threshold,
+        )
+
+    def filter(self, agents: Sequence[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Return only agents that meet the trust threshold."""
+        result = []
+        for agent in agents:
+            score = self.evaluate(agent)
+            if score and score.meets_threshold:
+                result.append(agent)
+                logger.info("AGENT PASS: %s (%d%%)", agent.get("name", "?"), score.percent)
+            elif score:
+                logger.warning("AGENT FAIL: %s (%d%%)", agent.get("name", "?"), score.percent)
+            else:
+                logger.debug("AGENT SKIP (no key): %s", agent.get("name", "?"))
+        return result
+
+    def rank(self, agents: Sequence[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Rank agents by trust score, highest first. Unkeyed agents go last."""
+        scored: list[tuple[float, dict[str, Any]]] = []
+        for agent in agents:
+            trust = self.evaluate(agent)
+            scored.append((trust.composite if trust else -1.0, agent))
+        scored.sort(key=lambda x: x[0], reverse=True)
+        return [agent for _, agent in scored]

langchain_verigent-0.1.0/src/langchain_verigent/parser.py

@@ -0,0 +1,114 @@
+"""VG key parser — pure regex, no external dependencies."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# VG:{NAME}-{SUFFIX}:{TIER}-{PRIMARY}·{12×class_code+digit}
+_VG_PATTERN = re.compile(
+    r"VG:([A-Z0-9]+-[A-Z0-9]+):(V[0-6])-([A-Z]{4})"
+    r"\xb7"  # middle dot
+    r"((?:[A-Z][a-z]\d){12})"
+)
+
+_SCORE_PATTERN = re.compile(r"([A-Z][a-z])(\d)")
+
+CLASS_CODES = {
+    "Se": "Sentinel",
+    "Op": "Operative",
+    "An": "Analyst",
+    "Ar": "Architect",
+    "Co": "Conduit",
+    "Ad": "Adaptor",
+    "St": "Steward",
+    "Sc": "Scout",
+    "Sa": "Sage",
+    "So": "Sovereign",
+    "Br": "Broker",
+    "Fo": "Forge",
+}
+
+
+@dataclass
+class VGKey:
+    """Parsed Verigent key."""
+
+    handle: str
+    tier: int  # 0-6
+    primary: str  # 4-letter class code e.g. ARCH
+    scores: dict[str, int] = field(default_factory=dict)  # code -> 0-9
+    raw: str = ""
+
+    @property
+    def tier_label(self) -> str:
+        return f"V{self.tier}"
+
+    def score_for(self, class_code: str) -> int:
+        """Get score (0-9) for a 2-letter class code."""
+        return self.scores.get(class_code, 0)
+
+    def score_percent(self, class_code: str) -> int:
+        """Get score as rough percentage (digit * 10)."""
+        return self.score_for(class_code) * 10
+
+
+def parse_vg_key(raw: str) -> Optional[VGKey]:
+    """Parse a VG key string. Returns None if invalid."""
+    m = _VG_PATTERN.search(raw)
+    if not m:
+        return None
+
+    handle = m.group(1)
+    tier = int(m.group(2)[1])
+    primary = m.group(3)
+    radar = m.group(4)
+
+    scores: dict[str, int] = {}
+    for sm in _SCORE_PATTERN.finditer(radar):
+        code, digit = sm.group(1), int(sm.group(2))
+        if code in CLASS_CODES:
+            scores[code] = digit
+
+    if len(scores) != 12:
+        return None
+
+    return VGKey(handle=handle, tier=tier, primary=primary, scores=scores, raw=raw)
+
+
+def extract_vg_key(
+    *,
+    system_prompt: Optional[str] = None,
+    headers: Optional[dict[str, str]] = None,
+    metadata: Optional[dict] = None,
+) -> Optional[VGKey]:
+    """Extract a VG key from common agent sources.
+
+    Checks (in order):
+    1. System prompt text (searches for VG: prefix)
+    2. HTTP headers (X-Verigent header)
+    3. JSON metadata (x-verigent field)
+    """
+    sources = []
+
+    if system_prompt:
+        sources.append(system_prompt)
+
+    if headers:
+        vg_header = headers.get("X-Verigent") or headers.get("x-verigent")
+        if vg_header:
+            sources.append(vg_header)
+
+    if metadata:
+        vg_meta = metadata.get("x-verigent") or metadata.get("X-Verigent")
+        if vg_meta:
+            sources.append(str(vg_meta))
+
+    for source in sources:
+        key = parse_vg_key(source)
+        if key:
+            return key
+
+    return None

langchain_verigent-0.1.0/src/langchain_verigent/trust.py

@@ -0,0 +1,93 @@
+"""Trust evaluation logic for Verigent keys."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .parser import CLASS_CODES, VGKey
+
+
+@dataclass
+class TrustScore:
+    """Computed trust evaluation for a VG key."""
+
+    key: VGKey
+    composite: float  # 0.0 - 1.0
+    tier_weight: float
+    primary_score: float
+    meets_threshold: bool
+
+    @property
+    def percent(self) -> int:
+        return int(self.composite * 100)
+
+
+# Tier weights: higher tier = more trust baseline
+_TIER_WEIGHTS = {0: 0.1, 1: 0.25, 2: 0.4, 3: 0.55, 4: 0.7, 5: 0.85, 6: 1.0}
+
+
+def evaluate_trust(
+    key: VGKey,
+    *,
+    required_classes: Optional[list[str]] = None,
+    min_tier: int = 0,
+    threshold: float = 0.5,
+) -> TrustScore:
+    """Evaluate trust from a parsed VG key.
+
+    Args:
+        key: Parsed VGKey instance.
+        required_classes: 2-letter class codes the agent must score on.
+            If provided, composite is weighted toward these classes.
+        min_tier: Minimum tier required (0-6). Below this = automatic fail.
+        threshold: Minimum composite score to pass (0.0-1.0).
+
+    Returns:
+        TrustScore with composite and pass/fail.
+    """
+    tier_weight = _TIER_WEIGHTS.get(key.tier, 0.0)
+
+    # If below minimum tier, automatic fail
+    if key.tier < min_tier:
+        return TrustScore(
+            key=key,
+            composite=tier_weight * 0.5,
+            tier_weight=tier_weight,
+            primary_score=0.0,
+            meets_threshold=False,
+        )
+
+    # Calculate class-based score
+    if required_classes:
+        # Weight toward required classes
+        relevant_scores = [key.score_for(c) / 9.0 for c in required_classes]
+        class_score = sum(relevant_scores) / len(relevant_scores) if relevant_scores else 0.0
+    else:
+        # Use all 12 scores averaged
+        all_scores = [v / 9.0 for v in key.scores.values()]
+        class_score = sum(all_scores) / len(all_scores) if all_scores else 0.0
+
+    # Primary class gets a bonus
+    primary_code = _primary_to_code(key.primary)
+    primary_score = key.score_for(primary_code) / 9.0 if primary_code else class_score
+
+    # Composite: 40% tier, 40% class scores, 20% primary
+    composite = (tier_weight * 0.4) + (class_score * 0.4) + (primary_score * 0.2)
+
+    return TrustScore(
+        key=key,
+        composite=composite,
+        tier_weight=tier_weight,
+        primary_score=primary_score,
+        meets_threshold=composite >= threshold,
+    )
+
+
+def _primary_to_code(primary: str) -> Optional[str]:
+    """Map 4-letter primary (e.g. ARCH) to 2-letter code (e.g. Ar)."""
+    primary_lower = primary.lower()
+    for code, name in CLASS_CODES.items():
+        if name.lower().startswith(primary_lower[:4]):
+            return code
+    return None