open-reflection-protocol 0.3.0__py3-none-any.whl

orp/cli.py

@@ -0,0 +1,366 @@
+"""ORP CLI — 命令行界面"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+from orp.schema import (
+    ExperienceRecord, TimelineEvent, EventKind, LessonStatus,
+    CounterfactualReplay, EvalArtifact, DeliveryStrategy,
+)
+from orp.storage import ORPStorage
+from orp.experience import ExperienceBuilder, Redactor, EvidenceLinker
+from orp.capture import capture_command, capture_git_diff, capture_trace_context
+from orp.reflect import ReflectionAnalyzer, Challenger
+from orp.replay import CounterfactualReplayer
+from orp.compiler import ExperienceCompiler
+from orp.lessons import LessonStore
+from orp.conflicts import ConflictDefender
+from orp.delivery import DeliveryRouter
+from orp.effects import EffectEvaluator
+from orp.rollback import RollbackManager
+from orp.training import TrainingPipeline
+from orp.mcp_server import MCPServer
+from orp.export import ExportEngine
+from orp.viewer import HTMLReporter
+
+
+def cmd_wrap(args):
+    """orp wrap -- python agent.py"""
+    goal = args.goal or " ".join(args.command[:3])
+    with capture_trace_context(goal) as ctx:
+        result = capture_command(args.command, timeout=args.timeout)
+        ctx.set_outcome("success" if result["success"] else "failed", result)
+    
+    events = ctx.get_events()
+    events.append(TimelineEvent(
+        kind="outcome",
+        content="Exit code: " + str(result.get("exit_code", -1)),
+        source="system",
+    ))
+    builder = ExperienceBuilder()
+    record = builder.from_events(events, goal=goal)
+    record.outcome.status = "success" if result.get("success", False) else "failed"
+    
+    storage = ORPStorage()
+    storage.save_experience(record)
+    print("Experience recorded: " + record.experience_id)
+    print("  Outcome: " + record.outcome.status)
+
+
+def cmd_inspect(args):
+    """orp inspect [id]"""
+    storage = ORPStorage()
+    if args.id == "latest":
+        exps = storage.list_experiences(limit=1)
+        if not exps:
+            print("No experiences found")
+            return
+        exp = exps[0]
+    else:
+        exp = storage.get_experience(args.id)
+        if not exp:
+            print("Experience not found: " + args.id)
+            return
+    
+    print()
+    print("Experience: " + exp.experience_id)
+    print("  Agent:    " + exp.agent.get("id", "?"))
+    print("  Model:    " + exp.agent.get("model", "?"))
+    print("  Goal:     " + exp.task.get("goal", "?"))
+    print("  Outcome:  " + exp.outcome.status)
+    print("  Timeline: " + str(len(exp.timeline)) + " events")
+    print()
+    print("Events:")
+    for evt in exp.timeline:
+        markers = {"observation": "\u25cf", "claim": "\u25b3", "action": "\u25b6",
+                   "feedback": "\u25a0", "outcome": "\u25c6", "decision": "\u25c8"}
+        marker = markers.get(evt.kind.value, "\u25cb")
+        print("  " + marker + " [" + evt.kind.value + "] " + evt.content[:120])
+
+
+def cmd_learn(args):
+    """orp learn [id]"""
+    storage = ORPStorage()
+    if args.id == "latest":
+        exps = storage.list_experiences(limit=1)
+        if not exps:
+            print("No experiences to learn from")
+            return
+        exp = exps[0]
+    else:
+        exp = storage.get_experience(args.id)
+        if not exp:
+            print("Experience not found: " + args.id)
+            return
+    
+    print("Learning from: " + exp.experience_id)
+    
+    analyzer = ReflectionAnalyzer()
+    reflection = analyzer.analyze(exp)
+    exp.reflection = reflection
+    print("  Diagnosis: " + (reflection.diagnosis or "none"))
+    
+    challenger = Challenger()
+    challenged = challenger.challenge(exp)
+    if challenged:
+        print("  Claims challenged: " + str(len(challenged)))
+        for c in challenged:
+            print("    " + c["issue"] + ": " + c["content"][:80])
+    
+    compiler = ExperienceCompiler()
+    artifacts = compiler.compile(exp)
+    
+    for lesson in artifacts.get("lessons", []):
+        storage.save_lesson(lesson)
+        print("  Lesson: " + lesson.lesson_id[:12] + "... " + lesson.recommendation[:80])
+    for eval_ in artifacts.get("evals", []):
+        storage.save_eval(eval_)
+        print("  Eval:   " + eval_.eval_id[:12] + "... " + eval_.command)
+    
+    storage.save_experience(exp)
+    print("  Done.")
+
+
+def cmd_replay(args):
+    """orp replay <id>"""
+    storage = ORPStorage()
+    exp = storage.get_experience(args.id)
+    if not exp:
+        print("Experience not found: " + args.id)
+        return
+    replayer = CounterfactualReplayer()
+    replay = replayer.replay(
+        experience_id=exp.experience_id,
+        original="original",
+        alternative=args.strategy or "Review trace and write tests first",
+    )
+    storage.save_replay(replay)
+    print("Replay: " + replay.replay_id[:12] + "...")
+    print("  Mode:   " + replay.verification_mode)
+    print("  Result: " + replay.result.get("status", "unknown"))
+
+
+def cmd_lessons(args):
+    """orp lessons <subcommand>"""
+    storage = ORPStorage()
+    store = LessonStore(storage)
+    
+    if args.subcommand == "list":
+        status = LessonStatus(args.status) if args.status else None
+        lessons = storage.list_lessons(status=status)
+        for l in lessons:
+            rid = l.lesson_id[:16] + "..."
+            print(rid + " " + l.status.value + " " + l.recommendation[:60])
+    
+    elif args.subcommand == "validate":
+        issues = store.validate_lesson(args.id)
+        if not issues:
+            print("Lesson " + args.id + ": valid")
+        else:
+            print("Lesson " + args.id + ": issues")
+            for i in issues:
+                print("  - " + i)
+    
+    elif args.subcommand == "conflicts":
+        defender = ConflictDefender(storage)
+        reviewed = defender.auto_review_conflicts()
+        if reviewed:
+            print("Lessons moved to under_review: " + str(reviewed))
+        else:
+            print("No conflicts found")
+    
+    elif args.subcommand == "rollback":
+        manager = RollbackManager(storage)
+        rollback = manager.rollback(args.id, args.reason or "Manual rollback")
+        if rollback:
+            print("Lesson " + args.id + ": " + rollback.previous_status.value + " -> " + rollback.new_status.value)
+        else:
+            print("Lesson not found: " + args.id)
+    
+    elif args.subcommand == "deliver":
+        lesson = storage.get_lesson(args.id)
+        if not lesson:
+            print("Lesson not found: " + args.id)
+            return
+        strategy = DeliveryStrategy(args.strategy) if args.strategy else DeliveryStrategy.PROMPT_CONTEXT
+        router = DeliveryRouter(storage)
+        delivery = router.deliver(lesson, "cli", strategy=strategy, context=args.context)
+        print("Delivered: " + delivery.delivery_id[:12] + "... via " + delivery.strategy.value)
+
+
+def cmd_effects(args):
+    """orp effects evaluate <id>"""
+    storage = ORPStorage()
+    evaluator = EffectEvaluator(storage)
+    
+    if args.id == "all":
+        evals = evaluator.auto_evaluate_all()
+        print("Evaluated " + str(len(evals)) + " lessons")
+        for e in evals:
+            print("  " + e.lesson_id[:12] + "... -> " + e.decision)
+    else:
+        lesson = storage.get_lesson(args.id)
+        if not lesson:
+            print("Lesson not found: " + args.id)
+            return
+        evaluation = evaluator.evaluate_matched_baseline(lesson)
+        storage.save_lesson_evaluation(evaluation)
+        print("Evaluation: " + evaluation.evaluation_id[:12] + "...")
+        print("  Method:   " + evaluation.method.value)
+        print("  Decision: " + evaluation.decision)
+
+
+def cmd_training(args):
+    """orp training <subcommand>"""
+    storage = ORPStorage()
+    pipeline = TrainingPipeline(storage)
+    
+    if args.subcommand == "candidates":
+        candidates = storage.list_training_candidates()
+        if not candidates:
+            print("No training candidates")
+            return
+        for c in candidates:
+            print(c.candidate_id[:16] + "... " + c.format.value + " " + c.status.value)
+    
+    elif args.subcommand == "export":
+        exported = pipeline.export_approved()
+        if not exported:
+            print("No approved candidates to export")
+            return
+        print("Exporting " + str(len(exported)) + " approved candidates")
+        for e in exported:
+            print("  " + e["candidate_id"][:12] + "...")
+
+
+def cmd_mcp(args):
+    """orp mcp-server"""
+    server = MCPServer(transport=args.transport)
+    if args.transport == "stdio":
+        print("Starting ORP MCP Server (stdio)...", file=sys.stderr)
+        server.run_stdio()
+    else:
+        print("Transport " + args.transport + " not yet implemented")
+
+
+def cmd_report(args):
+    """orp report"""
+    storage = ORPStorage()
+    reporter = HTMLReporter(storage)
+    path = reporter.write_report(args.output or "orp_report.html")
+    print("Report written to " + path)
+    if args.open:
+        import subprocess
+        try:
+            subprocess.Popen(["start", path], shell=True)
+        except Exception:
+            pass
+
+
+def cmd_diff(args):
+    """orp diff <id1> <id2>"""
+    storage = ORPStorage()
+    a = storage.get_experience(args.id1)
+    b = storage.get_experience(args.id2)
+    if not a or not b:
+        print("One or both experiences not found")
+        return
+    
+    a_actions = len([e for e in a.timeline if e.kind == EventKind.ACTION])
+    b_actions = len([e for e in b.timeline if e.kind == EventKind.ACTION])
+    a_claims = len([e for e in a.timeline if e.kind == EventKind.CLAIM])
+    b_claims = len([e for e in b.timeline if e.kind == EventKind.CLAIM])
+    a_evidence = sum(len(e.evidence_refs) for e in a.timeline)
+    b_evidence = sum(len(e.evidence_refs) for e in b.timeline)
+    
+    print("Metric                          Before              After")
+    print("-" * 60)
+    print("Task success                    " + a.outcome.status.ljust(20) + b.outcome.status)
+    print("Tool calls                      " + str(a_actions).ljust(20) + str(b_actions))
+    print("Claims                          " + str(a_claims).ljust(20) + str(b_claims))
+    print("Evidence refs                   " + str(a_evidence).ljust(20) + str(b_evidence))
+
+
+def cmd_export(args):
+    """orp export [id]"""
+    storage = ORPStorage()
+    engine = ExportEngine(storage)
+    content = engine.to_json(args.id)
+    if content:
+        print(content[:2000])
+    else:
+        print("Experience not found: " + args.id)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="ORP — Open Reflection Protocol CLI")
+    sub = parser.add_subparsers(dest="command")
+    
+    p = sub.add_parser("wrap", help="Wrap an agent with ORP")
+    p.add_argument("command", nargs="+")
+    p.add_argument("--goal")
+    p.add_argument("--timeout", type=int, default=300)
+    p.set_defaults(func=cmd_wrap)
+    
+    p = sub.add_parser("inspect", help="Inspect an experience")
+    p.add_argument("id", default="latest", nargs="?")
+    p.set_defaults(func=cmd_inspect)
+    
+    p = sub.add_parser("learn", help="Generate lessons from an experience")
+    p.add_argument("id", default="latest", nargs="?")
+    p.set_defaults(func=cmd_learn)
+    
+    p = sub.add_parser("replay", help="Counterfactual replay")
+    p.add_argument("id")
+    p.add_argument("--strategy")
+    p.set_defaults(func=cmd_replay)
+    
+    p = sub.add_parser("lessons", help="Manage lessons")
+    p.add_argument("subcommand", choices=["list", "validate", "conflicts", "rollback", "deliver"])
+    p.add_argument("id", nargs="?", default="")
+    p.add_argument("--status")
+    p.add_argument("--strategy")
+    p.add_argument("--reason")
+    p.add_argument("--context")
+    p.set_defaults(func=cmd_lessons)
+    
+    p = sub.add_parser("effects", help="Evaluate lesson effects")
+    p.add_argument("subcommand", choices=["evaluate"])
+    p.add_argument("id")
+    p.set_defaults(func=cmd_effects)
+    
+    p = sub.add_parser("training", help="Training candidates")
+    p.add_argument("subcommand", choices=["candidates", "export"])
+    p.set_defaults(func=cmd_training)
+    
+    p = sub.add_parser("mcp-server", help="Start MCP lesson server")
+    p.add_argument("--transport", default="stdio", choices=["stdio", "http"])
+    p.set_defaults(func=cmd_mcp)
+    
+    p = sub.add_parser("report", help="Generate HTML report")
+    p.add_argument("--output", default="orp_report.html")
+    p.add_argument("--open", action="store_true")
+    p.set_defaults(func=cmd_report)
+    
+    p = sub.add_parser("diff", help="Compare two experiences")
+    p.add_argument("id1")
+    p.add_argument("id2")
+    p.set_defaults(func=cmd_diff)
+    
+    p = sub.add_parser("export", help="Export an experience")
+    p.add_argument("id", default="latest", nargs="?")
+    p.set_defaults(func=cmd_export)
+    
+    args = parser.parse_args()
+    if hasattr(args, "func"):
+        args.func(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

orp/compiler.py

@@ -0,0 +1,124 @@
+"""Experience Compiler — 将候选经验编译为可执行资产"""
+
+from typing import Any, Optional
+
+from orp.schema import (
+    ExperienceRecord, Lesson, EvalArtifact,
+    EventKind, LessonStatus,
+)
+from orp.reflect import Challenger, ReflectionAnalyzer
+
+
+class ExperienceCompiler:
+    """经验编译器 — 诊断 → Lesson / Eval / Guardrail 候选"""
+
+    def compile(self, record: ExperienceRecord) -> dict[str, list[Any]]:
+        """编译 ExperienceRecord 生成可执行资产"""
+        lessons: list[Lesson] = []
+        evals: list[EvalArtifact] = []
+        guardrails: list[dict[str, Any]] = []
+
+        # 如果任务失败，生成 Lesson 候选
+        if record.outcome.status in ("failed", "partial"):
+            lesson = self._generate_lesson(record)
+            if lesson:
+                lessons.append(lesson)
+
+        # 生成回归 Eval
+        eval_artifact = self._generate_eval(record)
+        if eval_artifact:
+            evals.append(eval_artifact)
+
+        # 检查重复动作模式
+        guardrail = self._check_repeated_patterns(record)
+        if guardrail:
+            guardrails.append(guardrail)
+
+        # 更新 record 的 artifacts 引用
+        record.artifacts = {
+            "lessons": [l.lesson_id for l in lessons],
+            "evals": [e.eval_id for e in evals],
+            "guardrails": [g.get("id", "") for g in guardrails],
+        }
+
+        return {"lessons": lessons, "evals": evals, "guardrails": guardrails}
+
+    def _generate_lesson(self, record: ExperienceRecord) -> Optional[Lesson]:
+        """从失败的运行生成 Lesson 候选"""
+        challenger = Challenger()
+        challenged = challenger.challenge(record)
+        
+        # 从被挑战的声明中提取建议
+        recommendations = set()
+        for c in challenged:
+            content = c.get("content", "")
+            if "fix" in content.lower() or "complete" in content.lower():
+                recommendations.add("Verify fixes with before/after tests")
+            if "test" in content.lower():
+                recommendations.add("Run all tests after changes, not just affected ones")
+
+        if not recommendations:
+            if record.outcome.status == "failed":
+                recommendations.add("Review full timeline before drawing conclusions")
+            else:
+                return None
+
+        task_goal = record.task.get("goal", "")
+        task_domain = record.task.get("domain", "coding")
+
+        return Lesson(
+            trigger={
+                "domain": task_domain,
+                "conditions": [task_goal[:200]] if task_goal else [],
+            },
+            recommendation="; ".join(sorted(recommendations)),
+            provenance={"experience_ids": [record.experience_id]},
+            scope={"task_domains": [task_domain], "frameworks": [],
+                   "agent_versions": [record.agent.get("version", "")] if record.agent.get("version") else []},
+            status=LessonStatus.CANDIDATE,
+        )
+
+    def _generate_eval(self, record: ExperienceRecord) -> Optional[EvalArtifact]:
+        """从失败的运行生成回归 Eval"""
+        error_events = [
+            e for e in record.timeline
+            if e.kind == EventKind.OBSERVATION
+            and any(w in e.content.lower() for w in ["error", "fail", "exception", "exit code", "traceback"])
+        ]
+        if not error_events and record.outcome.status != "failed":
+            return None
+
+        # 生成 pytest 测试
+        test_content = self._make_pytest_eval(record)
+        return EvalArtifact(
+            origin_experience=record.experience_id,
+            runner="pytest",
+            command="pytest -q",
+            expected={"exit_code": 0},
+            generated_by="orp-compiler",
+        )
+
+
+    def _check_repeated_patterns(self, record):
+        """检查重复的无效动作模式"""
+        actions = [e for e in record.timeline if e.kind == EventKind.ACTION]
+        contents = [a.content for a in actions]
+        from collections import Counter
+        duplicates = {k: v for k, v in Counter(contents).items() if v > 2}
+        if duplicates:
+            return {
+                "id": "guard_" + record.experience_id[:8],
+                "type": "repeated_action",
+                "pattern": "Repeated action " + str(max(duplicates, key=duplicates.get)) + " " + str(max(duplicates.values())) + " times",
+                "source_experience": record.experience_id,
+            }
+        return None
+
+    def _make_pytest_eval(self, record: ExperienceRecord) -> str:
+        """生成一个基本的 pytest 回归测试"""
+        task_goal = record.task.get("goal", "unknown")
+        return (
+            f"ORP-generated regression test\n"
+            f"Source: {record.experience_id}\n"
+            f"Goal: {task_goal}\n"
+        )

orp/conflicts.py

@@ -0,0 +1,62 @@
+"""Conflict Defender — Lesson 作用域与冲突检测"""
+
+from typing import Optional
+
+from orp.schema import Lesson, LessonStatus, check_lesson_conflict
+from orp.storage import ORPStorage
+
+
+class ConflictDefender:
+    """冲突防御 — 激活 Lesson 前执行检查"""
+
+    def __init__(self, storage: Optional[ORPStorage] = None):
+        self._storage = storage or ORPStorage()
+
+    def check_new_lesson(self, new_lesson: Lesson) -> list[dict[str, str]]:
+        """检查新 Lesson 与现有 active Lesson 的冲突"""
+        conflicts = []
+        active = self._storage.list_lessons(status=LessonStatus.ACTIVE)
+        for existing in active:
+            if existing.lesson_id == new_lesson.lesson_id:
+                continue
+            if check_lesson_conflict(new_lesson, existing):
+                if self._are_contradictory(new_lesson.recommendation, existing.recommendation):
+                    conflicts.append({
+                        "type": "contradiction",
+                        "existing_id": existing.lesson_id,
+                        "existing": existing.recommendation[:100],
+                        "new": new_lesson.recommendation[:100],
+                    })
+        return conflicts
+
+    def _are_contradictory(self, a: str, b: str) -> bool:
+        """检查两条建议是否语义相反（简单启发式）"""
+        a_lower = a.lower()
+        b_lower = b.lower()
+        # 检查是否有反义词对
+        opposites = [
+            ("always", "never"),
+            ("must", "must not"),
+            ("do", "don't"),
+            ("before", "after"),
+            ("first", "last"),
+        ]
+        for a_word, b_word in opposites:
+            has_a = a_word in a_lower
+            has_b = b_word in b_lower
+            if has_a and has_b:
+                return True
+        return False
+
+    def auto_review_conflicts(self) -> list[str]:
+        """自动将所有冲突的 Lesson 标记为 under_review"""
+        reviewed: list[str] = []
+        active = self._storage.list_lessons(status=LessonStatus.ACTIVE)
+        for a in active:
+            for b in active:
+                if a.lesson_id >= b.lesson_id:
+                    continue
+                if check_lesson_conflict(a, b) and self._are_contradictory(a.recommendation, b.recommendation):
+                    self._storage.update_lesson_status(b.lesson_id, LessonStatus.UNDER_REVIEW)
+                    reviewed.append(b.lesson_id)
+        return reviewed

orp/delivery.py

@@ -0,0 +1,110 @@
+"""Delivery Router — 将 Lesson 交付给 Agent"""
+
+from typing import Any, Optional
+
+from orp.schema import (
+    Lesson, LessonDelivery, DeliveryStrategy,
+)
+from orp.storage import ORPStorage
+
+
+class DeliveryRouter:
+    """Lesson 交付路由 — 支持多种交付策略"""
+
+    def __init__(self, storage: Optional[ORPStorage] = None):
+        self._storage = storage or ORPStorage()
+
+    def deliver(self, lesson: Lesson, experience_id: str,
+                strategy: DeliveryStrategy = DeliveryStrategy.MCP_TOOL,
+                context: Optional[str] = None) -> LessonDelivery:
+        """交付 Lesson 并记录"""
+        delivery = LessonDelivery(
+            lesson_id=lesson.lesson_id,
+            experience_id=experience_id,
+            strategy=strategy,
+            delivery_context=context,
+        )
+        # 如果策略需要写入文件，同步执行
+        if strategy == DeliveryStrategy.POLICY_FILE:
+            self._write_policy_file(lesson)
+        elif strategy == DeliveryStrategy.PROMPT_CONTEXT:
+            delivery.acknowledged = True  # 假设注入成功
+        
+        self._storage.save_delivery(delivery)
+        
+        # 更新 Lesson 指标
+        lesson.metrics["delivered"] = lesson.metrics.get("delivered", 0) + 1
+        self._storage.save_lesson(lesson)
+        
+        return delivery
+
+    def acknowledge(self, lesson_id: str, delivery_id: str) -> None:
+        """记录 Agent 已确认接收到 Lesson"""
+        # In a real implementation, this would update the delivery record
+        # For now, we update metrics on the lesson
+        lesson = self._storage.get_lesson(lesson_id)
+        if lesson:
+            lesson.metrics["acknowledged"] = lesson.metrics.get("acknowledged", 0) + 1
+            self._storage.save_lesson(lesson)
+
+    def report_outcome(self, lesson_id: str, outcome: str,
+                       evidence_refs: Optional[list[str]] = None) -> None:
+        """记录 Lesson 应用后的实际结果"""
+        lesson = self._storage.get_lesson(lesson_id)
+        if not lesson:
+            return
+        lesson.metrics["applied"] = lesson.metrics.get("applied", 0) + 1
+        if outcome in ("success", "improved", "passed"):
+            lesson.metrics["successful_after_apply"] = lesson.metrics.get("successful_after_apply", 0) + 1
+        self._storage.save_lesson(lesson)
+
+    def _write_policy_file(self, lesson: Lesson) -> None:
+        """将 Lesson 写入 AGENTS.md 等策略文件"""
+        import os
+        try:
+            agents_path = os.path.join(os.getcwd(), "AGENTS.md")
+            comment = f"\n<!-- ORP Lesson: {lesson.lesson_id} -->\n- {lesson.recommendation}\n<!-- END ORP Lesson -->\n"
+            if os.path.exists(agents_path):
+                with open(agents_path, "a") as f:
+                    f.write(comment)
+        except (IOError, PermissionError):
+            pass
+
+    def get_mcp_tools(self) -> list[dict[str, Any]]:
+        """返回 MCP Server 的工具定义"""
+        return [
+            {
+                "name": "orp_retrieve_lessons",
+                "description": "Retrieve relevant lessons for a task",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "task": {"type": "string", "description": "Task description"},
+                        "limit": {"type": "integer", "default": 3},
+                        "domain": {"type": "string", "optional": True},
+                    },
+                },
+            },
+            {
+                "name": "orp_acknowledge_lesson",
+                "description": "Acknowledge a delivered lesson",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "lesson_id": {"type": "string"},
+                    },
+                },
+            },
+            {
+                "name": "orp_report_outcome",
+                "description": "Report the outcome of applying a lesson",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "lesson_id": {"type": "string"},
+                        "outcome": {"type": "string", "enum": ["success", "failed", "improved", "worse"]},
+                        "evidence_refs": {"type": "array", "items": {"type": "string"}},
+                    },
+                },
+            },
+        ]