crewai-verigent 0.1.0__tar.gz

crewai_verigent-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: crewai-verigent
+Version: 0.1.0
+Summary: Verigent trust verification for CrewAI agent delegation
+Project-URL: Homepage, https://verigent.ai
+Project-URL: Repository, https://github.com/verigentai/crewai-verigent
+Author-email: verigentai <dev@verigent.ai>
+License-Expression: MIT
+Keywords: agents,crewai,delegation,trust,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: crewai>=0.30.0
+Provides-Extra: verify
+Requires-Dist: httpx>=0.25.0; extra == 'verify'
+Description-Content-Type: text/markdown
+
+# crewai-verigent
+
+Trust verification for CrewAI agent delegation.
+
+## The problem
+
+When one agent delegates a task to another, you're trusting that the receiving agent is competent for that specific job. A "research agent" delegating to an "analyst agent" has no way to verify that the analyst is actually good at analysis — it just has to hope.
+
+Verigent solves this by giving agents verifiable capability profiles (VG keys) that declare what they're good at, scored across 12 classes. This plugin checks those profiles at delegation time and flags mismatches before they become failures.
+
+## Install
+
+```bash
+pip install crewai-verigent
+```
+
+For remote verification against verigent.ai:
+
+```bash
+pip install crewai-verigent[verify]
+```
+
+## Usage
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_verigent import VerigentTrust
+
+# Build your crew as normal
+crew = Crew(agents=[researcher, analyst, writer], tasks=[...])
+
+# Wrap it — trust checking is now active
+trusted_crew = VerigentTrust(crew, min_score=50)
+result = trusted_crew.kickoff()
+
+# Check what happened
+for d in trusted_crew.decisions:
+    print(f"{d['agent']}: score={d['score']} verified={d['verified']}")
+```
+
+## What happens automatically
+
+Once enabled, `VerigentTrust` does three things:
+
+1. **Extracts VG keys** from each agent's backstory/system prompt, metadata, or headers
+2. **Evaluates trust** when tasks are assigned or delegated — matching task keywords against the agent's 12 class scores
+3. **Logs decisions** and optionally blocks delegation if the trust score is below your threshold
+
+Agents without VG keys score 0 and are flagged as unverified. Set `block_unverified=True` to prevent delegation to unverified agents entirely.
+
+## VG Keys
+
+A VG key encodes an agent's verified capability profile:
+
+```
+VG:JARVIS-0A:V3-ARCH·Se4Op7An5Ar9Co2Ad6St8Sc3Sa5So1Br2Fo6
+```
+
+This tells you JARVIS-0A is tier V3, primarily an Architect, scoring 90% on Architecture and 80% on Stewardship but only 10% on Sovereignty.
+
+Agents get VG keys by completing Verigent's evaluation process. The key can live in the agent's system prompt, an `X-Verigent` HTTP header, or a metadata field.
+
+## Configuration
+
+```python
+VerigentTrust(
+    crew,
+    min_score=50,           # Minimum trust score to allow delegation (0-100)
+    block_unverified=False, # Block delegation to agents without VG keys
+    on_decision=callback,   # Called with (agent, task, TrustScore) on each check
+)
+```
+
+## Decorator usage
+
+```python
+@VerigentTrust.wrap(min_score=60, block_unverified=True)
+def build_crew():
+    return Crew(agents=[...], tasks=[...])
+
+trusted_crew = build_crew()
+result = trusted_crew.kickoff()
+```
+
+## Get your agents verified
+
+Register your agents at [verigent.ai](https://verigent.ai) to get VG keys issued after evaluation.
+
+## License
+
+MIT

crewai_verigent-0.1.0/README.md

@@ -0,0 +1,91 @@
+# crewai-verigent
+
+Trust verification for CrewAI agent delegation.
+
+## The problem
+
+When one agent delegates a task to another, you're trusting that the receiving agent is competent for that specific job. A "research agent" delegating to an "analyst agent" has no way to verify that the analyst is actually good at analysis — it just has to hope.
+
+Verigent solves this by giving agents verifiable capability profiles (VG keys) that declare what they're good at, scored across 12 classes. This plugin checks those profiles at delegation time and flags mismatches before they become failures.
+
+## Install
+
+```bash
+pip install crewai-verigent
+```
+
+For remote verification against verigent.ai:
+
+```bash
+pip install crewai-verigent[verify]
+```
+
+## Usage
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_verigent import VerigentTrust
+
+# Build your crew as normal
+crew = Crew(agents=[researcher, analyst, writer], tasks=[...])
+
+# Wrap it — trust checking is now active
+trusted_crew = VerigentTrust(crew, min_score=50)
+result = trusted_crew.kickoff()
+
+# Check what happened
+for d in trusted_crew.decisions:
+    print(f"{d['agent']}: score={d['score']} verified={d['verified']}")
+```
+
+## What happens automatically
+
+Once enabled, `VerigentTrust` does three things:
+
+1. **Extracts VG keys** from each agent's backstory/system prompt, metadata, or headers
+2. **Evaluates trust** when tasks are assigned or delegated — matching task keywords against the agent's 12 class scores
+3. **Logs decisions** and optionally blocks delegation if the trust score is below your threshold
+
+Agents without VG keys score 0 and are flagged as unverified. Set `block_unverified=True` to prevent delegation to unverified agents entirely.
+
+## VG Keys
+
+A VG key encodes an agent's verified capability profile:
+
+```
+VG:JARVIS-0A:V3-ARCH·Se4Op7An5Ar9Co2Ad6St8Sc3Sa5So1Br2Fo6
+```
+
+This tells you JARVIS-0A is tier V3, primarily an Architect, scoring 90% on Architecture and 80% on Stewardship but only 10% on Sovereignty.
+
+Agents get VG keys by completing Verigent's evaluation process. The key can live in the agent's system prompt, an `X-Verigent` HTTP header, or a metadata field.
+
+## Configuration
+
+```python
+VerigentTrust(
+    crew,
+    min_score=50,           # Minimum trust score to allow delegation (0-100)
+    block_unverified=False, # Block delegation to agents without VG keys
+    on_decision=callback,   # Called with (agent, task, TrustScore) on each check
+)
+```
+
+## Decorator usage
+
+```python
+@VerigentTrust.wrap(min_score=60, block_unverified=True)
+def build_crew():
+    return Crew(agents=[...], tasks=[...])
+
+trusted_crew = build_crew()
+result = trusted_crew.kickoff()
+```
+
+## Get your agents verified
+
+Register your agents at [verigent.ai](https://verigent.ai) to get VG keys issued after evaluation.
+
+## License
+
+MIT

crewai_verigent-0.1.0/pyproject.toml

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

crewai_verigent-0.1.0/src/crewai_verigent/__init__.py

@@ -0,0 +1,17 @@
+"""Verigent trust verification for CrewAI agent delegation."""
+
+from .parser import VGKey, parse_vg_key, extract_vg_key
+from .trust import TrustScore, evaluate_trust, CLASS_NAMES
+from .middleware import VerigentTrust
+
+__all__ = [
+    "VGKey",
+    "parse_vg_key",
+    "extract_vg_key",
+    "TrustScore",
+    "evaluate_trust",
+    "CLASS_NAMES",
+    "VerigentTrust",
+]
+
+__version__ = "0.1.0"

crewai_verigent-0.1.0/src/crewai_verigent/middleware.py

@@ -0,0 +1,166 @@
+"""CrewAI integration middleware — wraps Crew to add trust checking on delegation."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional
+
+from crewai import Agent, Crew, Task
+
+from .parser import VGKey, extract_vg_key
+from .trust import TrustScore, evaluate_trust
+
+logger = logging.getLogger("crewai_verigent")
+
+
+class VerigentTrust:
+    """Wraps a CrewAI Crew to inject trust verification on agent delegation.
+
+    Usage:
+        crew = Crew(agents=[...], tasks=[...])
+        trusted_crew = VerigentTrust(crew)
+        result = trusted_crew.kickoff()
+
+    Or as a decorator:
+        @VerigentTrust.wrap
+        def build_crew():
+            return Crew(agents=[...], tasks=[...])
+    """
+
+    def __init__(
+        self,
+        crew: Crew,
+        *,
+        min_score: int = 50,
+        block_unverified: bool = False,
+        on_decision: Optional[Callable[[Agent, Task, TrustScore], None]] = None,
+    ):
+        self.crew = crew
+        self.min_score = min_score
+        self.block_unverified = block_unverified
+        self.on_decision = on_decision
+        self._decisions: list[dict[str, Any]] = []
+
+        self._patch_agents()
+
+    @classmethod
+    def wrap(
+        cls,
+        fn: Optional[Callable[..., Crew]] = None,
+        *,
+        min_score: int = 50,
+        block_unverified: bool = False,
+    ):
+        """Decorator to wrap a crew-building function with trust verification."""
+        def decorator(func: Callable[..., Crew]) -> Callable[..., VerigentTrust]:
+            def wrapper(*args, **kwargs) -> VerigentTrust:
+                crew = func(*args, **kwargs)
+                return cls(crew, min_score=min_score, block_unverified=block_unverified)
+            return wrapper
+
+        if fn is not None:
+            return decorator(fn)
+        return decorator
+
+    def _extract_key(self, agent: Agent) -> Optional[VGKey]:
+        """Extract VG key from an agent's configuration."""
+        return extract_vg_key(
+            system_prompt=getattr(agent, "backstory", None) or getattr(agent, "system_prompt", None),
+            metadata=getattr(agent, "metadata", None),
+        )
+
+    def _patch_agents(self) -> None:
+        """Patch agent delegation to include trust checks."""
+        for agent in self.crew.agents:
+            if hasattr(agent, "delegate_work"):
+                original_delegate = agent.delegate_work
+                agent.delegate_work = self._make_trust_wrapper(agent, original_delegate)
+
+            # Also patch execute_task for task assignment trust checks
+            original_execute = getattr(agent, "execute_task", None)
+            if original_execute:
+                agent.execute_task = self._make_task_wrapper(agent, original_execute)
+
+    def _make_trust_wrapper(self, delegator: Agent, original: Callable) -> Callable:
+        """Create a delegation wrapper that checks trust before delegating."""
+        def wrapper(task: Any, context: Any = None, **kwargs) -> Any:
+            # Find the target agent from kwargs or context
+            target = kwargs.get("coworker") or kwargs.get("agent")
+            if target and isinstance(target, Agent):
+                score = self._check_trust(delegator, target, task)
+                if not score.passed and self.block_unverified:
+                    logger.warning(
+                        f"Blocked delegation from {delegator.role} to {target.role}: "
+                        f"trust score {score.score} < {self.min_score}"
+                    )
+                    return f"Delegation blocked: {target.role} trust score too low ({score.score}/100)"
+            return original(task, context, **kwargs)
+        return wrapper
+
+    def _make_task_wrapper(self, agent: Agent, original: Callable) -> Callable:
+        """Wrap task execution to log trust evaluation."""
+        def wrapper(task: Any, *args, **kwargs) -> Any:
+            task_desc = getattr(task, "description", str(task)) if task else ""
+            key = self._extract_key(agent)
+            score = evaluate_trust(task_desc, key)
+            self._log_decision(agent, task, score)
+            return original(task, *args, **kwargs)
+        return wrapper
+
+    def _check_trust(self, delegator: Agent, target: Agent, task: Any) -> TrustScore:
+        """Evaluate trust for a delegation."""
+        task_desc = getattr(task, "description", str(task)) if task else ""
+        key = self._extract_key(target)
+        score = evaluate_trust(task_desc, key)
+        self._log_decision(target, task, score, delegator=delegator)
+        return score
+
+    def _log_decision(
+        self,
+        agent: Agent,
+        task: Any,
+        score: TrustScore,
+        delegator: Optional[Agent] = None,
+    ) -> None:
+        """Log a trust decision."""
+        decision = {
+            "agent": getattr(agent, "role", "unknown"),
+            "handle": score.handle,
+            "score": score.score,
+            "verified": score.verified,
+            "passed": score.passed,
+            "reason": score.reason,
+            "task": getattr(task, "description", str(task))[:100] if task else None,
+        }
+        if delegator:
+            decision["delegator"] = getattr(delegator, "role", "unknown")
+
+        self._decisions.append(decision)
+
+        level = logging.INFO if score.passed else logging.WARNING
+        logger.log(
+            level,
+            "Trust check: agent=%s handle=%s score=%d verified=%s — %s",
+            decision["agent"],
+            score.handle or "NONE",
+            score.score,
+            score.verified,
+            score.reason,
+        )
+
+        if self.on_decision:
+            self.on_decision(agent, task, score)
+
+    @property
+    def decisions(self) -> list[dict[str, Any]]:
+        """All trust decisions made during this crew's execution."""
+        return list(self._decisions)
+
+    def kickoff(self, **kwargs) -> Any:
+        """Run the crew with trust verification active."""
+        logger.info("Starting crew with Verigent trust verification (min_score=%d)", self.min_score)
+        return self.crew.kickoff(**kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        """Proxy other attributes to the underlying crew."""
+        return getattr(self.crew, name)

crewai_verigent-0.1.0/src/crewai_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

crewai_verigent-0.1.0/src/crewai_verigent/trust.py

@@ -0,0 +1,152 @@
+"""Trust evaluation logic — maps tasks to class scores."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .parser import VGKey, CLASS_CODES
+
+CLASS_NAMES = {v: k for k, v in CLASS_CODES.items()}
+
+# Keyword -> class code mappings
+_TASK_KEYWORDS: dict[str, list[str]] = {
+    "Se": [
+        "security", "protect", "guard", "monitor", "threat", "vulnerability",
+        "audit", "compliance", "firewall", "encryption",
+    ],
+    "Op": [
+        "execute", "deploy", "run", "operate", "action", "perform",
+        "implement", "deliver", "ship", "build",
+    ],
+    "An": [
+        "analyze", "analyse", "data", "research", "investigate", "report",
+        "metrics", "statistics", "insight", "pattern",
+    ],
+    "Ar": [
+        "design", "architect", "plan", "structure", "blueprint", "system",
+        "framework", "strategy", "roadmap", "infrastructure",
+    ],
+    "Co": [
+        "communicate", "relay", "translate", "bridge", "message", "notify",
+        "connect", "coordinate", "sync", "interface",
+    ],
+    "Ad": [
+        "adapt", "flexible", "dynamic", "adjust", "transform", "convert",
+        "migrate", "refactor", "evolve", "pivot",
+    ],
+    "St": [
+        "manage", "maintain", "steward", "govern", "organize", "track",
+        "schedule", "resource", "allocate", "budget",
+    ],
+    "Sc": [
+        "search", "find", "discover", "explore", "scan", "locate",
+        "browse", "crawl", "index", "retrieve",
+    ],
+    "Sa": [
+        "advise", "wisdom", "counsel", "guide", "recommend", "evaluate",
+        "judge", "assess", "review", "mentor",
+    ],
+    "So": [
+        "decide", "authorize", "approve", "command", "override", "escalate",
+        "prioritize", "delegate", "lead", "direct",
+    ],
+    "Br": [
+        "negotiate", "trade", "exchange", "deal", "mediate", "arbitrate",
+        "price", "value", "market", "partner",
+    ],
+    "Fo": [
+        "create", "generate", "produce", "synthesize", "craft", "compose",
+        "write", "code", "develop", "fabricate",
+    ],
+}
+
+# Build reverse index: keyword -> class code
+_KEYWORD_INDEX: dict[str, str] = {}
+for _code, _words in _TASK_KEYWORDS.items():
+    for _word in _words:
+        _KEYWORD_INDEX[_word] = _code
+
+
+@dataclass
+class TrustScore:
+    """Result of trust evaluation."""
+
+    score: int  # 0-100
+    verified: bool  # has a valid VG key
+    handle: Optional[str]
+    relevant_classes: dict[str, int]  # class code -> score (0-9)
+    reason: str
+
+    @property
+    def passed(self) -> bool:
+        """Whether trust score meets minimum threshold (50)."""
+        return self.score >= 50
+
+
+def evaluate_trust(task_description: str, key: Optional[VGKey]) -> TrustScore:
+    """Score task suitability given a task and a parsed VG key.
+
+    Returns a TrustScore with 0-100 rating based on how well the agent's
+    class scores match the task requirements.
+    """
+    if key is None:
+        return TrustScore(
+            score=0,
+            verified=False,
+            handle=None,
+            relevant_classes={},
+            reason="No VG key found — agent is unverified",
+        )
+
+    # Find relevant classes from task keywords
+    task_lower = task_description.lower()
+    matched_codes: dict[str, int] = {}
+
+    for word, code in _KEYWORD_INDEX.items():
+        if word in task_lower and code not in matched_codes:
+            matched_codes[code] = key.score_for(code)
+
+    if not matched_codes:
+        # No keyword matches — use tier as baseline
+        baseline = min(key.tier * 15, 70)
+        return TrustScore(
+            score=baseline,
+            verified=True,
+            handle=key.handle,
+            relevant_classes={},
+            reason=f"No specific class match; baseline from tier V{key.tier}",
+        )
+
+    # Weighted average of matched class scores (each 0-9, scaled to 0-100)
+    total = sum(matched_codes.values())
+    avg = (total / len(matched_codes)) * 10  # scale 0-9 to 0-90
+
+    # Tier bonus: V0=0, V1=1, V2=2, ... V6=6 points
+    score = int(min(avg + key.tier, 100))
+
+    return TrustScore(
+        score=score,
+        verified=True,
+        handle=key.handle,
+        relevant_classes=matched_codes,
+        reason=f"Matched {len(matched_codes)} classes, avg score {avg:.0f}%",
+    )
+
+
+async def verify_remote(handle: str) -> Optional[dict]:
+    """Verify agent against verigent.ai API. Requires httpx."""
+    try:
+        import httpx
+    except ImportError:
+        return None
+
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            resp = await client.get(f"https://verigent.ai/api/verify/{handle}")
+            if resp.status_code == 200:
+                return resp.json()
+    except (httpx.HTTPError, Exception):
+        pass
+
+    return None