agent-relationship 0.2.0__py3-none-any.whl

agent_relationship/__init__.py

@@ -0,0 +1,41 @@
+"""
+Agent Relationship — 多 Agent 系统的关系感知 Skill。
+
+给任何多 Agent 系统注入「社会层」：关系建模、Moloch 检测、关系修复。
+
+用法:
+    from agent_relationship import RelationshipTracker
+
+    tracker = RelationshipTracker()
+    tracker.track("alice", "bob", {"action": "help", "result": "success"})
+    h = tracker.health("alice", "bob")
+    print(tracker.summary())
+
+四引擎:
+    - "mock"      — 零配置，确定性模拟
+    - "openai"    — GPT / Codex
+    - "deepseek"  — V4 Flash / V4 Pro
+    - "anthropic" — Claude / Claude Code
+"""
+
+from .tracker import RelationshipTracker
+from .types import (
+    TrackResult,
+    Health,
+    NetworkReport,
+    MolochReport,
+    MolochZone,
+    RepairPath,
+)
+
+__all__ = [
+    "RelationshipTracker",
+    "TrackResult",
+    "Health",
+    "NetworkReport",
+    "MolochReport",
+    "MolochZone",
+    "RepairPath",
+]
+
+__version__ = "0.2.0"

agent_relationship/engine.py

@@ -0,0 +1,326 @@
+"""
+Agent Relationship — 关系引擎
+
+管理所有 Agent 之间的关系场：记录交互、评估健康、检测危机。
+"""
+
+import time
+from typing import Dict, List, Optional, Set, Tuple
+
+from .models import RelationProfile, InteractionRecord
+from .repair import RepairMechanism
+from .llm import LLMBackend
+
+
+class RelationshipEngine:
+    """
+    关系引擎 — 多 Agent 系统的社会层。
+
+    核心功能:
+    - 记录交互 → 更新 balance / trust / type
+    - 查询双边关系健康度
+    - Moloch 竞争升级检测 (BFS 连通分量 + 趋势)
+    - 关系修复路径
+    """
+
+    def __init__(self, llm: LLMBackend, max_history: int = 100):
+        self.llm = llm
+        self.profiles: Dict[Tuple[str, str], RelationProfile] = {}
+        self.repair = RepairMechanism()
+        self.moloch_threshold: float = 0.3
+        self.moloch_min_zone_size: int = 3
+        self._previous_moloch_zones: List[Dict] = []
+        self.max_history = max_history
+
+    def _key(self, a: str, b: str) -> Tuple[str, str]:
+        """规范化键 — (a,b) 和 (b,a) 指向同一 profile"""
+        return (a, b) if a < b else (b, a)
+
+    # ── 查询 ──
+
+    def get_relationship(
+        self, agent_a: str, agent_b: str
+    ) -> Optional[RelationProfile]:
+        """查询双边关系"""
+        return self.profiles.get(self._key(agent_a, agent_b))
+
+    def get_or_create_relationship(
+        self, agent_a: str, agent_b: str
+    ) -> RelationProfile:
+        """查询或创建双边关系"""
+        key = self._key(agent_a, agent_b)
+        if key not in self.profiles:
+            self.profiles[key] = RelationProfile(
+                agent_a=key[0], agent_b=key[1],
+                max_history_length=self.max_history,
+            )
+        return self.profiles[key]
+
+    # ── 记录交互 ──
+
+    def record_interaction(
+        self,
+        initiator: str,
+        target: str,
+        interaction_data: Dict,
+    ) -> Dict:
+        """
+        记录一次交互，更新关系档案。
+
+        interaction_data 自由格式:
+          {"action": "...", "result": "...", "narrative": "..."}
+        """
+        impact_a = self._estimate_impact(
+            initiator, interaction_data, True
+        )
+        impact_b = self._estimate_impact(
+            target, interaction_data, False
+        )
+
+        record = InteractionRecord(
+            timestamp=time.time(),
+            interaction_type=interaction_data.get(
+                "action", interaction_data.get("type", "unknown")
+            ),
+            initiator=initiator,
+            target=target,
+            action=interaction_data,
+            impact_a=impact_a,
+            impact_b=impact_b,
+            context=interaction_data,
+        )
+
+        profile = self.get_or_create_relationship(initiator, target)
+        profile.record_interaction(record)
+
+        return {
+            "balance": profile.balance,
+            "trust": profile.trust,
+            "relation_type": profile.relation_type.value,
+            "impact": (impact_a + impact_b) / 2,
+            "interaction_count": profile.interaction_count,
+        }
+
+    # ── 协作检查 ──
+
+    def can_cooperate(
+        self,
+        agent_a: str,
+        agent_b: str,
+        threshold: float = 0.4,
+        is_repair_attempt: bool = False,
+    ) -> Dict:
+        """
+        检查两个 Agent 是否可以协作。
+
+        不是简单的是/否 — 返回修复路径而非永久封锁。
+        """
+        profile = self.get_relationship(agent_a, agent_b)
+
+        if not profile:
+            return {
+                "can": True,
+                "reason": "无历史交互",
+                "confidence": 0.3,
+                "needs_repair": False,
+            }
+
+        if is_repair_attempt:
+            can_repair, msg = self.repair.can_attempt_repair(profile)
+            if can_repair:
+                result = self.repair.execute_repair_attempt(
+                    profile
+                )
+                return {
+                    "can": True,
+                    "reason": f"修复尝试: {msg}",
+                    "confidence": result["temp_threshold"],
+                    "needs_repair": True,
+                }
+            else:
+                return {
+                    "can": False,
+                    "reason": msg,
+                    "confidence": 0.0,
+                    "needs_repair": True,
+                }
+
+        if profile.balance > threshold:
+            return {
+                "can": True,
+                "reason": f"关系良好 (balance={profile.balance:.2f})",
+                "confidence": profile.balance,
+                "needs_repair": False,
+            }
+        else:
+            return {
+                "can": False,
+                "reason": (
+                    f"关系需要修复 (balance={profile.balance:.2f})"
+                ),
+                "confidence": 1.0 - profile.balance,
+                "needs_repair": True,
+                "repair_paths": [
+                    p["description"]
+                    for p in self.repair.available_paths()
+                ],
+            }
+
+    # ── 影响评估 ──
+
+    def _estimate_impact(
+        self, agent_id: str, interaction: Dict, is_initiator: bool
+    ) -> float:
+        """通过 LLM 估算交互影响"""
+        return self.llm.estimate_impact(
+            agent_id, interaction, is_initiator
+        )
+
+    # ── Moloch 检测 ──
+
+    def _detect_moloch_zones(self) -> List[Dict]:
+        """
+        Moloch 萌芽检测。
+
+        1. 收集 balance < threshold 的边
+        2. BFS 找连通分量
+        3. 过滤 ≥ min_zone_size 的分量
+        4. 计算平均 balance / 严重程度 / 趋势
+        """
+        threshold = self.moloch_threshold
+        min_size = self.moloch_min_zone_size
+
+        imbalanced_edges = [
+            (a, b)
+            for (a, b), profile in self.profiles.items()
+            if profile.balance < threshold
+            and profile.interaction_count >= 3
+        ]
+
+        # 建图
+        graph: Dict[str, Set[str]] = {}
+        for a, b in imbalanced_edges:
+            graph.setdefault(a, set()).add(b)
+            graph.setdefault(b, set()).add(a)
+
+        moloch_zones = []
+        visited: Set[str] = set()
+
+        for node in graph:
+            if node in visited:
+                continue
+
+            component: Set[str] = set()
+            queue = [node]
+            while queue:
+                current = queue.pop(0)
+                if current in visited:
+                    continue
+                visited.add(current)
+                component.add(current)
+                for neighbor in graph.get(current, set()):
+                    if neighbor not in visited:
+                        queue.append(neighbor)
+
+            if len(component) >= min_size:
+                zone_balances: List[float] = []
+                for a, b in imbalanced_edges:
+                    if a in component and b in component:
+                        profile = self.profiles.get((a, b))
+                        if profile:
+                            zone_balances.append(profile.balance)
+
+                avg_balance = (
+                    sum(zone_balances) / len(zone_balances)
+                    if zone_balances
+                    else 0.0
+                )
+
+                trend = "stable"
+                prev = self._find_previous_zone(component)
+                if prev:
+                    delta = avg_balance - prev["avg_balance"]
+                    if delta < -0.05:
+                        trend = "deteriorating"
+                    elif delta > 0.05:
+                        trend = "improving"
+
+                moloch_zones.append(
+                    {
+                        "agents": sorted(component),
+                        "size": len(component),
+                        "avg_balance": avg_balance,
+                        "trend": trend,
+                        "severity": self._classify_severity(
+                            avg_balance, len(component), trend
+                        ),
+                        "first_detected": prev is None,
+                    }
+                )
+
+        self._previous_moloch_zones = moloch_zones
+        return moloch_zones
+
+    def get_moloch_report(self) -> Dict:
+        """获取 Moloch 检测报告"""
+        zones = self._detect_moloch_zones()
+        total = len(self.profiles)
+        balanced = sum(
+            1
+            for p in self.profiles.values()
+            if p.balance >= self.moloch_threshold
+        )
+        return {
+            "zones": zones,
+            "active": len(zones) > 0,
+            "total_relationships": total,
+            "balanced_ratio": balanced / max(total, 1),
+        }
+
+    def _find_previous_zone(
+        self, component: Set[str]
+    ) -> Optional[Dict]:
+        comp_set = set(component)
+        for prev in self._previous_moloch_zones:
+            if set(prev["agents"]) == comp_set:
+                return prev
+        return None
+
+    @staticmethod
+    def _classify_severity(
+        avg_balance: float, size: int, trend: str
+    ) -> str:
+        if avg_balance < 0.1:
+            base = "critical"
+        elif avg_balance < 0.2:
+            base = "high"
+        elif avg_balance < 0.3:
+            base = "moderate"
+        else:
+            base = "watch"
+
+        if trend == "deteriorating" and base in ("moderate", "high"):
+            return f"{base}_escalating"
+        if size >= 10 and trend == "deteriorating":
+            return f"{base}_large_scale"
+
+        return base
+
+    # ── 聚合 ──
+
+    def average_balance(self) -> float:
+        """全局平均 balance"""
+        if not self.profiles:
+            return 0.5
+        return (
+            sum(p.balance for p in self.profiles.values())
+            / len(self.profiles)
+        )
+
+    def all_agent_ids(self) -> List[str]:
+        """获取所有已知的 Agent ID"""
+        ids: Set[str] = set()
+        for a, b in self.profiles:
+            ids.add(a)
+            ids.add(b)
+        return sorted(ids)

agent_relationship/llm/__init__.py

@@ -0,0 +1,17 @@
+"""
+Agent Relationship — LLM 后端集合
+"""
+
+from .base import LLMBackend
+from .mock import MockLLM
+from .openai import OpenAILLM
+from .deepseek import DeepSeekLLM
+from .anthropic import AnthropicLLM
+
+__all__ = [
+    "LLMBackend",
+    "MockLLM",
+    "OpenAILLM",
+    "DeepSeekLLM",
+    "AnthropicLLM",
+]

agent_relationship/llm/anthropic.py

@@ -0,0 +1,108 @@
+"""
+Agent Relationship — AnthropicLLM
+
+Anthropic Claude API 后端 — Messages API 格式。
+
+环境变量:
+  ANTHROPIC_API_KEY  — API 密钥 (必填)
+  ANTHROPIC_MODEL     — 模型名 (默认 claude-sonnet-4-20250514)
+
+可用模型:
+  - claude-sonnet-4-20250514: 平衡性能与成本 (默认)
+  - claude-opus-4-20250918:   最强推理
+  - claude-haiku-4-20250514:  最快最便宜
+
+与 OpenAI 格式的核心差异:
+  - 端点: https://api.anthropic.com/v1/messages
+  - 认证: x-api-key 头 (非 Authorization: Bearer)
+  - 版本: anthropic-version: 2023-06-01 (必填)
+  - system: 顶层字段 (非 messages 数组内)
+  - 响应: content[0].text (非 choices[0].message.content)
+  - max_tokens: 必填 (OpenAI 可选)
+  - JSON mode: 无原生支持，用 prompt 引导
+"""
+
+import json
+import os
+import urllib.request
+import urllib.error
+from typing import Optional
+from .base import LLMBackend
+
+
+class AnthropicLLM(LLMBackend):
+    """
+    Anthropic Claude API 后端 — Messages API。
+
+    使用 urllib 直调 HTTP，无需 anthropic SDK。
+    """
+
+    ANTHROPIC_VERSION = "2023-06-01"
+    ENDPOINT = "https://api.anthropic.com/v1/messages"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = "claude-sonnet-4-20250514",
+    ):
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+        self.model = os.environ.get("ANTHROPIC_MODEL", model)
+
+        if not self.api_key:
+            raise ValueError(
+                "ANTHROPIC_API_KEY 未设置。"
+                "请设置环境变量或传入 api_key 参数。"
+            )
+
+    def chat(
+        self,
+        prompt: str,
+        system: str = "",
+        temperature: float = 0.3,
+        max_tokens: int = 500,
+        json_mode: bool = False,
+    ) -> str:
+        # 构建请求体
+        body: dict = {
+            "model": self.model,
+            "max_tokens": max_tokens,
+            "messages": [{"role": "user", "content": prompt}],
+        }
+
+        # Anthropic: system 是顶层字段
+        system_content = system or ""
+        if json_mode:
+            # Anthropic 无原生 JSON mode，通过 system prompt 引导
+            json_instruction = (
+                "\n\n你必须返回纯 JSON，只输出 JSON 对象，"
+                "不要包含 markdown 代码块标记 (```json```)，"
+                "不要添加任何解释文字。"
+            )
+            system_content += json_instruction
+
+        if system_content.strip():
+            body["system"] = system_content.strip()
+
+        if temperature is not None:
+            body["temperature"] = temperature
+
+        req = urllib.request.Request(
+            self.ENDPOINT,
+            data=json.dumps(body).encode("utf-8"),
+            headers={
+                "Content-Type": "application/json",
+                "x-api-key": self.api_key,
+                "anthropic-version": self.ANTHROPIC_VERSION,
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=60) as resp:
+                data = json.loads(resp.read())
+                # Anthropic 响应: content 是数组，取第一个 text
+                return data["content"][0]["text"]
+        except urllib.error.HTTPError as e:
+            raise RuntimeError(
+                f"Anthropic API 错误 ({e.code}): {e.read().decode()}"
+            )
+        except Exception as e:
+            raise RuntimeError(f"Anthropic 调用失败: {e}")

agent_relationship/llm/base.py

@@ -0,0 +1,91 @@
+"""
+Agent Relationship — LLM 抽象基类
+
+所有 LLM 后端必须实现的接口。
+"""
+
+import json
+from abc import ABC, abstractmethod
+
+
+class LLMBackend(ABC):
+    """LLM 后端抽象基类"""
+
+    @abstractmethod
+    def chat(
+        self,
+        prompt: str,
+        system: str = "",
+        temperature: float = 0.3,
+        max_tokens: int = 500,
+        json_mode: bool = False,
+    ) -> str:
+        """通用对话接口"""
+        ...
+
+    # ── estimate_impact ──
+
+    def estimate_impact(
+        self,
+        agent_id: str,
+        interaction: dict,
+        is_initiator: bool,
+    ) -> float:
+        """
+        评估交互对 Agent 的影响 → (-1.0, +1.0)
+
+        优先用 LLM 语义评估，失败时降级到启发式。
+        """
+        role = "发起方" if is_initiator else "接收方"
+        prompt = (
+            f"你是 {agent_id} ({role})。评估以下交互对你的影响:\n\n"
+            f"交互详情: {json.dumps(interaction, ensure_ascii=False)}\n\n"
+            f'返回 JSON:\n'
+            f'{{"impact": <float -1到1>, '
+            f'"reasoning": "<一句话分析>", '
+            f'"fairness": <float 0-1>}}'
+        )
+        try:
+            result = json.loads(self.chat(prompt, json_mode=True))
+            return max(-1.0, min(1.0, float(result.get("impact", 0.0))))
+        except Exception:
+            return self._fallback_estimate_impact(interaction, is_initiator)
+
+    @staticmethod
+    def _fallback_estimate_impact(
+        interaction: dict, is_initiator: bool
+    ) -> float:
+        """LLM 不可用时的启发式降级"""
+        atype = interaction.get("action", interaction.get("type", ""))
+        details = interaction.get("details", interaction.get("metadata", {}))
+
+        beneficial = {
+            "resource_exchange": 0.3,
+            "collaboration": 0.4,
+            "collaborate": 0.4,
+            "knowledge_share": 0.35,
+            "help": 0.5,
+            "delegate_task": 0.3,
+            "handoff": 0.2,
+        }
+        harmful = {
+            "attack": -0.5,
+            "deception": -0.4,
+            "theft": -0.6,
+            "sabotage": -0.7,
+        }
+
+        if atype in beneficial:
+            return beneficial[atype]
+        if atype in harmful:
+            return harmful[atype]
+
+        fair = details.get("fair_price", 0)
+        actual = details.get("price", details.get("amount", 0))
+        if fair > 0:
+            return (
+                0.3
+                if (actual <= fair if is_initiator else actual >= fair)
+                else -0.1
+            )
+        return 0.1

agent_relationship/llm/deepseek.py

@@ -0,0 +1,51 @@
+"""
+Agent Relationship — DeepSeekLLM
+
+DeepSeek API 后端 — OpenAI 兼容接口。
+默认 deepseek-v4-flash (无推理模式，适合 Agent 交互)。
+
+环境变量:
+  DEEPSEEK_API_KEY   — API 密钥 (必填)
+  DEEPSEEK_BASE_URL  — API 端点 (默认 https://api.deepseek.com)
+  DEEPSEEK_MODEL     — 模型名 (默认 deepseek-v4-flash)
+
+可用模型:
+  - deepseek-v4-flash: 高吞吐、无推理模式、成本低 (默认)
+  - deepseek-v4-pro:  复杂推理、内置思维链 — 注意: 可能因
+                       thinking 消耗 token 导致 content 为空
+"""
+
+import os
+from typing import Optional
+from .base import LLMBackend
+from .openai import OpenAILLM
+
+
+class DeepSeekLLM(OpenAILLM):
+    """
+    DeepSeek API — OpenAI 兼容但独立端点。
+
+    与 OpenAI 的核心差异:
+      - 端点: https://api.deepseek.com (无 /v1 后缀)
+      - 上下文: 1M tokens
+      - 定价: ~$0.28/$1.10 per 1M input/output
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        model: str = "deepseek-v4-flash",
+    ):
+        # 不走 OpenAILLM.__init__，避免 OPENAI_MODEL 环境变量覆盖
+        LLMBackend.__init__(self)
+        _api_key = api_key or os.environ.get("DEEPSEEK_API_KEY", "")
+        if not _api_key:
+            raise ValueError(
+                "DEEPSEEK_API_KEY 未设置。请设置环境变量或传入 api_key 参数。"
+            )
+        self.api_key = _api_key
+        self.base_url = base_url or os.environ.get(
+            "DEEPSEEK_BASE_URL", "https://api.deepseek.com"
+        )
+        self.model = os.environ.get("DEEPSEEK_MODEL", model)