agent-relationship 0.2.0__tar.gz

agent_relationship-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blueken31
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_relationship-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+graft agent_relationship
+
+recursive-include agent_relationship *.py

agent_relationship-0.2.0/PKG-INFO

@@ -0,0 +1,421 @@
+Metadata-Version: 2.4
+Name: agent-relationship
+Version: 0.2.0
+Summary: 关系感知 Skill — 多 Agent 系统的社会层
+Author: Agent Relationship Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/agent-world/agent-relationship
+Project-URL: Documentation, https://github.com/agent-world/agent-relationship#readme
+Project-URL: Repository, https://github.com/agent-world/agent-relationship
+Project-URL: Issues, https://github.com/agent-world/agent-relationship/issues
+Keywords: agent,multi-agent,relationship,moloch,governance,alignment,ai-safety,openai,deepseek,anthropic,claude
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30.0; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.30.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# Agent Relationship v0.2.0
+
+[English](#english) · [中文](#中文)
+
+---
+
+## English
+
+> **The relationship-awareness layer for multi-agent systems** — lightweight, standalone, zero required dependencies
+
+```bash
+pip install git+https://github.com/blueken31/agent-relationship.git
+```
+
+> …or `pip install agent-relationship` once published to PyPI.
+
+### The Problem
+
+Every multi-agent system you build today — LangGraph, CrewAI, AutoGen — shares a blind spot:
+
+**All frameworks care about what agents do. None cares about what happens between them.**
+
+```
+What you can see                     What you can't
+──────────────────                   ──────────────────
+Agent A → Agent B: task done         Is the A↔B relationship deteriorating?
+carol completed 12 delegations        Is carol helping or free-riding?
+System throughput is rising           alice↔carol balance has dropped to 0.18
+                                      Three agents are forming a Moloch loop
+```
+
+### Five Pain Points
+
+| Without agent-relationship | Consequence |
+|---|---|
+| **Free-riding undetected** — carol over-extracts resources until the system collapses | 3 hours debugging reveals broken relationship, but logs only show "occasional timeout" |
+| **Escalating competition invisible** — 3 agents enter a toxic competitive loop, throughput drops without explanation | Downgrade, retry, add resources — treating symptoms, not the cause |
+| **Broken relationships have no repair path** — once trust falls below threshold, cooperation is permanently blocked | The core value of multi-agent systems is silently canceled |
+| **Interactions are unobservable** — logs show "request timeout" with zero relationship-level diagnostics | Ops teams fly blind |
+| **Dev/prod behavior divergence** — everything works in mock, then real LLM semantic judgments produce completely different outcomes | Deploy = break |
+
+### The Solution
+
+```python
+from agent_relationship import RelationshipTracker
+
+tracker = RelationshipTracker(llm="deepseek")
+
+# One line to record an interaction
+result = tracker.track("alice", "carol", {
+    "action": "resource_exchange", "result": "success",
+    "narrative": "carol over-extracted resources"
+})
+
+# Risk awareness built into the return value — no separate health() call needed
+if result.risk_transition == "worsened":
+    print(f"⚠️ Relationship deteriorating: {result.prev_balance:.2f} → {result.balance:.2f}")
+
+# Pre-cooperation check — integrate into agent decision loop
+check = tracker.can_cooperate("alice", "carol")
+if not check["can"] and check["needs_repair"]:
+    repair = tracker.can_cooperate("alice", "carol", try_repair=True)
+
+# Real-time risk change callback
+def on_alert(a, b, old_risk, new_risk, balance):
+    print(f"🚨 {a}↔{b}: {old_risk} → {new_risk}")
+
+tracker = RelationshipTracker(on_risk_change=on_alert)
+
+# One-line health summary
+print(tracker.summary())
+```
+
+**Agent frameworks teach agents how to act. Agent Relationship tells them what's happening between each other.**
+
+### Not Another Agent Framework
+
+| | Agent Relationship | LangGraph / CrewAI / AutoGen |
+|---|---|---|
+| Task orchestration | ❌ | ✅ |
+| Tool calling | ❌ | ✅ |
+| Memory management | ❌ | ✅ |
+| Bilateral relationship modeling (balance + trust + type) | ✅ | ❌ |
+| Moloch competition escalation detection | ✅ | ❌ |
+| Relationship repair paths (3 paths + cooldown) | ✅ | ❌ |
+| Risk transition awareness (low→medium→high→critical) | ✅ | ❌ |
+| Real-time risk change callbacks | ✅ | ❌ |
+| OpenAI / DeepSeek / Anthropic / Mock | ✅ | Each bound to one |
+
+**Complementary, not competitive.** Three lines of code to integrate with any framework.
+
+### Quick Start
+
+```python
+from agent_relationship import RelationshipTracker
+
+# Zero config
+tracker = RelationshipTracker()
+
+# Record interactions
+tracker.track("alice", "bob", {
+    "action": "help",
+    "result": "success",
+    "narrative": "alice helped bob complete data analysis"
+})
+
+# Query health
+h = tracker.health("alice", "bob")
+print(f"balance={h.balance:.2f}, risk={h.risk}")
+```
+
+### 8 Core Methods
+
+| Method | Purpose |
+|--------|---------|
+| `track(a, b, ctx)` | Record an interaction; returns balance + risk + risk_transition |
+| `health(a, b)` | Query bilateral relationship health |
+| `can_cooperate(a, b)` | Integrate into agent decision loop; returns repair paths when needed |
+| `history(a, b)` | Query interaction history (reverse chronological) |
+| `network(ids)` | Full relationship matrix + ASCII heatmap |
+| `detect_moloch()` | Competition escalation detection with typed MolochZone results |
+| `repair_paths(a, b)` | Three repair paths (adaptive filtering by balance) |
+| `summary()` | One-line Markdown health summary |
+
+### Four Engine Support
+
+```python
+tracker = RelationshipTracker()                        # Mock — zero config
+tracker = RelationshipTracker(llm="openai")            # OpenAI GPT / Codex
+tracker = RelationshipTracker(llm="deepseek")          # DeepSeek V4 Flash
+tracker = RelationshipTracker(llm="anthropic")         # Anthropic Claude
+```
+
+| Engine | Env Variable | Default Model |
+|--------|-------------|---------------|
+| `mock` | none | — |
+| `openai` | `OPENAI_API_KEY` | `gpt-4o` |
+| `deepseek` | `DEEPSEEK_API_KEY` | `deepseek-v4-flash` |
+| `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+
+### Framework Integration
+
+#### LangGraph — with decision loop
+
+```python
+from agent_relationship import RelationshipTracker
+
+tracker = RelationshipTracker(llm="deepseek")
+
+def agent_node(state):
+    agent, target = state["agent"], state["target"]
+
+    check = tracker.can_cooperate(agent, target)
+    if not check["can"]:
+        if check["needs_repair"]:
+            check = tracker.can_cooperate(agent, target, try_repair=True)
+        if not check["can"]:
+            return {"status": "skipped", "reason": check["reason"]}
+
+    result = execute_task(state)
+    tracker.track(agent, target, {
+        "action": state["action"],
+        "result": result["status"],
+        "narrative": result["summary"],
+    })
+    return result
+```
+
+#### CrewAI
+
+```python
+tracker = RelationshipTracker(llm="anthropic")
+
+class MyAgent(Agent):
+    def execute_task(self, task, context=None):
+        result = super().execute_task(task, context)
+        for other in context.get("collaborators", []):
+            tracker.track(self.role, other.role, {
+                "action": task.description,
+                "result": "success" if result else "failed",
+                "narrative": str(result)[:500],
+            })
+        return result
+```
+
+### Specs
+
+- **Zero required dependencies**: core engine + MockLLM are fully self-contained, HTTP via `urllib`
+- **Python ≥ 3.10**
+- **Tests**: 57 unit + regression tests covering all 8 public APIs + 4 LLM backends
+- **Source:test ratio**: 1,651 : 684 ≈ 2.4 : 1
+- **Optional dependencies**: `pip install agent-relationship[openai]` / `[anthropic]` / `[all]`
+
+### License
+
+MIT
+
+---
+
+## 中文
+
+> **多 Agent 系统的关系感知层** — 轻量、独立、零必选依赖
+
+```bash
+pip install git+https://github.com/blueken31/agent-relationship.git
+```
+
+> 发布到 PyPI 后可直接 `pip install agent-relationship`。
+
+### 它解决什么问题
+
+你今天构建的任何多 Agent 系统 — LangGraph、CrewAI、AutoGen — 都有一个盲区：
+
+**所有框架只关心 Agent 在做什么，不关心 Agent 之间发生了什么。**
+
+```
+你的 Agent 系统看得到的             你的 Agent 系统看不到的
+─────────────────────────         ─────────────────────────
+Agent A → Agent B: 任务完成        A 和 B 的关系在恶化吗？
+carol 完成了 12 个委托              carol 在帮助还是在搭便车？
+系统吞吐量在上升                    alice↔carol 之间的 balance 只剩 0.18
+                                   三个 Agent 正在形成 Moloch 竞争闭环
+```
+
+### 五个具体痛点
+
+| 没有 agent-relationship | 带来的后果 |
+|---|---|
+| **搭便车不被发现** — carol 持续超额提取资源，系统到崩溃才暴露 | 排查 3 小时发现是关系破裂，但日志里只有「偶尔超时」 |
+| **竞争升级不可见** — 3 个 Agent 形成恶性竞争闭环，吞吐量下降但没人知道原因 | 降级、重试、加资源——治标不治本 |
+| **关系破裂无修复路径** — 一旦 trust 跌破阈值，永久无法合作，系统变「单 Agent」 | 多 Agent 系统的核心优势被自动取消 |
+| **交互不可观测** — 日志只有「请求超时」，没有关系视角的诊断信息 | 运维靠猜 |
+| **开发与生产行为不一致** — Mock 环境一切正常，生产 LLM 的语义判断产生完全不同的结果 | 上线即翻车 |
+
+### 有了它
+
+```python
+from agent_relationship import RelationshipTracker
+
+tracker = RelationshipTracker(llm="deepseek")
+
+# 一行记录交互
+result = tracker.track("alice", "carol", {
+    "action": "resource_exchange", "result": "success", "narrative": "carol 超额提取"
+})
+
+# 自带风险感知 — 无需再单独查询
+if result.risk_transition == "worsened":
+    print(f"⚠️ 关系恶化: {result.prev_balance:.2f} → {result.balance:.2f}")
+
+# 协作前检查 — 集成到 Agent 决策循环
+check = tracker.can_cooperate("alice", "carol")
+if not check["can"] and check["needs_repair"]:
+    repair = tracker.can_cooperate("alice", "carol", try_repair=True)
+
+# 风险变化自动通知
+def on_alert(a, b, old_risk, new_risk, balance):
+    print(f"🚨 {a}↔{b}: {old_risk} → {new_risk}")
+
+tracker = RelationshipTracker(on_risk_change=on_alert)
+
+# 一键健康摘要
+print(tracker.summary())
+```
+
+**Agent 框架教 Agent 怎么做事。Agent Relationship 告诉它们彼此之间正在发生什么。**
+
+### 不是又一个 Agent 框架
+
+| | Agent Relationship | LangGraph / CrewAI / AutoGen |
+|---|---|---|
+| 任务编排 | ❌ 不做 | ✅ |
+| 工具调用 | ❌ 不做 | ✅ |
+| 记忆管理 | ❌ 不做 | ✅ |
+| 双边关系建模 (balance + trust + type) | ✅ | ❌ |
+| Moloch 竞争升级检测 | ✅ | ❌ |
+| 关系修复路径 (3 条 + 冷却) | ✅ | ❌ |
+| 风险过渡感知 (low→medium→high→critical) | ✅ | ❌ |
+| 风险变化实时回调 | ✅ | ❌ |
+| OpenAI / DeepSeek / Anthropic / Mock | ✅ | 各自绑定 |
+
+**互补，不竞争。** 三行代码接入任何框架。
+
+### 快速开始
+
+```python
+from agent_relationship import RelationshipTracker
+
+# 零配置起步
+tracker = RelationshipTracker()
+
+# 记录交互
+tracker.track("alice", "bob", {
+    "action": "help",
+    "result": "success",
+    "narrative": "alice 帮助 bob 完成了数据分析任务"
+})
+
+# 查询健康度
+h = tracker.health("alice", "bob")
+print(f"balance={h.balance:.2f}, risk={h.risk}")
+```
+
+### 8 个核心方法
+
+| 方法 | 作用 |
+|------|------|
+| `track(a, b, ctx)` | 记录交互，返回 balance + risk + risk_transition |
+| `health(a, b)` | 查询双边关系健康度 |
+| `can_cooperate(a, b)` | 集成到 Agent 决策循环，关系不足时返回修复路径 |
+| `history(a, b)` | 查询交互历史 (按时间倒序) |
+| `network(ids)` | 全网关系矩阵 + ASCII 热力图 |
+| `detect_moloch()` | 竞争升级检测，返回类型化 MolochZone 列表 |
+| `repair_paths(a, b)` | 三条关系修复路径 (根据 balance 自适应过滤) |
+| `summary()` | 一键 Markdown 健康摘要 |
+
+### 四引擎支持
+
+```python
+tracker = RelationshipTracker()                        # Mock — 零配置
+tracker = RelationshipTracker(llm="openai")            # OpenAI GPT / Codex
+tracker = RelationshipTracker(llm="deepseek")          # DeepSeek V4 Flash
+tracker = RelationshipTracker(llm="anthropic")         # Anthropic Claude
+```
+
+| 后端 | 环境变量 | 默认模型 |
+|------|---------|---------|
+| `mock` | 无 | — |
+| `openai` | `OPENAI_API_KEY` | `gpt-4o` |
+| `deepseek` | `DEEPSEEK_API_KEY` | `deepseek-v4-flash` |
+| `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+
+### 与现有框架集成
+
+#### LangGraph — 带决策循环
+
+```python
+from agent_relationship import RelationshipTracker
+
+tracker = RelationshipTracker(llm="deepseek")
+
+def agent_node(state):
+    agent, target = state["agent"], state["target"]
+
+    check = tracker.can_cooperate(agent, target)
+    if not check["can"]:
+        if check["needs_repair"]:
+            check = tracker.can_cooperate(agent, target, try_repair=True)
+        if not check["can"]:
+            return {"status": "skipped", "reason": check["reason"]}
+
+    result = execute_task(state)
+    tracker.track(agent, target, {
+        "action": state["action"],
+        "result": result["status"],
+        "narrative": result["summary"],
+    })
+    return result
+```
+
+#### CrewAI
+
+```python
+tracker = RelationshipTracker(llm="anthropic")
+
+class MyAgent(Agent):
+    def execute_task(self, task, context=None):
+        result = super().execute_task(task, context)
+        for other in context.get("collaborators", []):
+            tracker.track(self.role, other.role, {
+                "action": task.description,
+                "result": "success" if result else "failed",
+                "narrative": str(result)[:500],
+            })
+        return result
+```
+
+### 规范
+
+- **零必选依赖**: 核心引擎 + MockLLM 完全自包含，`urllib` 直调 HTTP
+- **Python ≥ 3.10**
+- **测试**: 57 个单元测试 + 回归测试，覆盖全部 8 个公开 API + 4 个 LLM 后端
+- **源码:测试比**: 1,651 : 684 ≈ 2.4 : 1
+- **可选依赖**: `pip install agent-relationship[openai]` / `[anthropic]` / `[all]`
+
+### 许可证
+
+MIT