paigent 0.1.0__py3-none-any.whl

pai/__init__.py

@@ -0,0 +1,37 @@
+"""PAI — Proactive AI Framework (主動式 AI 框架)
+
+感知 (Triggers) → 決策 (Brain) → 治理 (Policy) → 行動 (Actions) → 記憶/回饋 (Memory)
+"""
+from .core import PAIAgent, Event, Intent, AutonomyLevel
+from .triggers import IntervalTrigger, ScheduleTrigger, FileWatchTrigger, ThresholdTrigger
+from .brain import RuleBrain, LLMBrain, Rule
+from .policy import ProactivityPolicy
+from .actions import ConsoleNotifier, WebhookNotifier, CallbackAction
+from .memory import Memory
+from .protocol import PAI_PROTOCOL_VERSION, build_record, to_json, save_pai, load_pai
+from .paifile import PaiWriter, PaiReader, pack_agent, load_agent, bake_adapter_into_pai
+from .finetune import (
+    AdapterStore, EvalGate, SelfFinetuneManager,
+    EchoBackend, LlamaFinetuneBackend, LlamaFactoryBackend, export_preference_dataset,
+)
+from .omni_brain import MiniCPMoBrain, DuplexOmniLoop
+from .loader import load_runtime
+from .learning import ReflectiveMemory, HashingEmbedder, EmbeddingClient
+
+__version__ = "0.1.0"
+__author__ = "vito1317 <service@vito1317.com>"
+
+__all__ = [
+    "PAIAgent", "Event", "Intent", "AutonomyLevel",
+    "IntervalTrigger", "ScheduleTrigger", "FileWatchTrigger", "ThresholdTrigger",
+    "RuleBrain", "LLMBrain", "Rule",
+    "ProactivityPolicy",
+    "ConsoleNotifier", "WebhookNotifier", "CallbackAction",
+    "Memory",
+    "PAI_PROTOCOL_VERSION", "build_record", "to_json", "save_pai", "load_pai",
+    "PaiWriter", "PaiReader", "pack_agent", "load_agent", "load_runtime",
+    "ReflectiveMemory", "HashingEmbedder", "EmbeddingClient",
+    "bake_adapter_into_pai", "AdapterStore", "EvalGate", "SelfFinetuneManager",
+    "EchoBackend", "LlamaFinetuneBackend", "LlamaFactoryBackend", "export_preference_dataset",
+    "MiniCPMoBrain", "DuplexOmniLoop",
+]

pai/__main__.py

@@ -0,0 +1,52 @@
+"""PAI CLI：
+    python3 -m pai info  <agent.pai>          顯示 .pai 檔內容
+    python3 -m pai run   <agent.pai> [秒數]   載入並運行 agent
+"""
+import json
+import logging
+import sys
+
+
+def main():
+    if len(sys.argv) < 3 or sys.argv[1] not in ("info", "run"):
+        print(__doc__)
+        sys.exit(1)
+    cmd, path = sys.argv[1], sys.argv[2]
+
+    if cmd == "info":
+        from .paifile import PaiReader, load_agent
+        r = PaiReader(path)
+        print(json.dumps({**load_agent(path)["manifest"], **r.info()},
+                         ensure_ascii=False, indent=2))
+        return
+
+    logging.basicConfig(level=logging.INFO,
+                        format="%(asctime)s %(levelname)s %(message)s")
+    duration = float(sys.argv[3]) if len(sys.argv) > 3 else None
+    from .loader import load_runtime
+
+    def confirm(intent):
+        ans = input(f"\n❓ [PAI 請求確認] {intent.rationale} (y/N): ").strip().lower()
+        return ans == "y"
+
+    # CLI 模式下未注入的 handler/metric 一律以 stub 代替（不執行真動作）
+    class _StubHandlers(dict):
+        def get(self, key, default=None):
+            if key not in self:
+                self[key] = lambda intent, _k=key: print(
+                    f"   ⚙️ [stub] handler '{_k}' 未注入，僅示意執行：{intent.params}")
+            return self[key]
+
+    class _StubMetrics(dict):
+        def get(self, key, default=None):
+            if key not in self:
+                self[key] = lambda: 0.0
+            return self[key]
+
+    agent = load_runtime(path, handlers=_StubHandlers(),
+                         metrics=_StubMetrics(), confirm_handler=confirm)
+    agent.run(duration=duration)
+
+
+if __name__ == "__main__":
+    main()

pai/actions.py

@@ -0,0 +1,47 @@
+"""行動層：可被 Intent 觸發的動作。"""
+from __future__ import annotations
+
+import json
+from typing import Callable
+
+from .core import Intent
+
+
+class ConsoleNotifier:
+    """把通知印到終端（開發/示範用）。"""
+
+    def execute(self, intent: Intent):
+        params = intent.params
+        title = params.get("title", intent.action)
+        body = params.get("body", intent.rationale)
+        print(f"\n🔔 [PAI 通知] {title}\n   {body}")
+        return {"notified": True}
+
+
+class WebhookNotifier:
+    """POST JSON 到任意 webhook（Slack/Discord/自建服務）。"""
+
+    def __init__(self, url: str):
+        self.url = url
+
+    def execute(self, intent: Intent):
+        import urllib.request
+        data = json.dumps({
+            "title": intent.params.get("title", intent.action),
+            "body": intent.params.get("body", intent.rationale),
+            "intent": intent.to_dict(),
+        }, ensure_ascii=False).encode()
+        req = urllib.request.Request(
+            self.url, data=data, headers={"content-type": "application/json"})
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            return {"status": resp.status}
+
+
+class CallbackAction:
+    """把任意 Python 函式包成動作。"""
+
+    def __init__(self, fn: Callable[[Intent], object]):
+        self.fn = fn
+
+    def execute(self, intent: Intent):
+        return self.fn(intent)

pai/brain.py

@@ -0,0 +1,137 @@
+"""決策層：把 Event + 記憶上下文 轉成 0..n 個 Intent。
+
+兩種腦：
+- RuleBrain：純規則，零依賴、可離線運行，適合確定性場景與 LLM 的安全後備。
+- LLMBrain：呼叫 LLM（預設 Anthropic API）做開放式判斷，輸出結構化 JSON 意圖。
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+from .core import AutonomyLevel, Event, Intent
+
+logger = logging.getLogger("pai.brain")
+
+
+@dataclass
+class Rule:
+    """單條規則：match(event, context) → 可選 Intent。"""
+    name: str
+    match: Callable[[Event, dict], Optional[Intent]]
+
+
+class RuleBrain:
+    def __init__(self, rules: Optional[list[Rule]] = None):
+        self.rules = rules or []
+
+    def add_rule(self, rule: Rule) -> "RuleBrain":
+        self.rules.append(rule)
+        return self
+
+    def decide(self, event: Event, context: dict) -> list[Intent]:
+        intents = []
+        for rule in self.rules:
+            try:
+                intent = rule.match(event, context)
+                if intent is not None:
+                    intents.append(intent)
+            except Exception:  # noqa: BLE001
+                logger.exception("Rule '%s' raised", rule.name)
+        return intents
+
+
+_LLM_SYSTEM_PROMPT = """\
+You are the decision engine of a proactive AI agent.
+Given an event and context, decide whether the agent should act proactively.
+
+Respond ONLY with a JSON array (possibly empty) of intents:
+[{"action": "<one of the available actions>",
+  "params": {},
+  "confidence": 0.0-1.0,
+  "urgency": 0.0-1.0,
+  "rationale": "<short reason, same language as the user>",
+  "requested_level": 0|1|2|3}]
+
+Levels: 0=observe only, 1=suggest/notify, 2=ask for confirmation, 3=act autonomously.
+Be conservative: prefer lower levels unless confidence is high and risk is low.
+Return [] when no proactive behavior is warranted (most events deserve []).
+"""
+
+
+class LLMBrain:
+    """以 LLM 為決策核心。失敗時自動退回 fallback（通常是 RuleBrain）。"""
+
+    def __init__(self, available_actions: list[str],
+                 model: str = "claude-sonnet-4-6",
+                 api_key: Optional[str] = None,
+                 fallback: Optional[RuleBrain] = None,
+                 user_profile: str = ""):
+        self.available_actions = available_actions
+        self.model = model
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        self.fallback = fallback
+        self.user_profile = user_profile
+
+    def decide(self, event: Event, context: dict) -> list[Intent]:
+        try:
+            return self._decide_llm(event, context)
+        except Exception:  # noqa: BLE001
+            logger.exception("LLM decision failed; using fallback")
+            if self.fallback:
+                return self.fallback.decide(event, context)
+            return []
+
+    def _decide_llm(self, event: Event, context: dict) -> list[Intent]:
+        import urllib.request
+
+        if not self.api_key:
+            raise RuntimeError("ANTHROPIC_API_KEY not set")
+
+        user_msg = json.dumps({
+            "event": event.to_dict(),
+            "context": context,
+            "available_actions": self.available_actions,
+            "user_profile": self.user_profile,
+        }, ensure_ascii=False)
+
+        req = urllib.request.Request(
+            "https://api.anthropic.com/v1/messages",
+            data=json.dumps({
+                "model": self.model,
+                "max_tokens": 1024,
+                "system": _LLM_SYSTEM_PROMPT,
+                "messages": [{"role": "user", "content": user_msg}],
+            }).encode(),
+            headers={
+                "content-type": "application/json",
+                "x-api-key": self.api_key,
+                "anthropic-version": "2023-06-01",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            data = json.loads(resp.read())
+        text = "".join(b.get("text", "") for b in data.get("content", []))
+        return self._parse(text)
+
+    def _parse(self, text: str) -> list[Intent]:
+        start, end = text.find("["), text.rfind("]")
+        if start == -1 or end == -1:
+            return []
+        items = json.loads(text[start:end + 1])
+        intents = []
+        for it in items:
+            if it.get("action") not in self.available_actions:
+                continue
+            intents.append(Intent(
+                action=it["action"],
+                params=it.get("params", {}),
+                confidence=float(it.get("confidence", 0.5)),
+                urgency=float(it.get("urgency", 0.5)),
+                rationale=it.get("rationale", ""),
+                requested_level=AutonomyLevel(int(it.get("requested_level", 1))),
+            ))
+        return intents

pai/core.py

@@ -0,0 +1,202 @@
+"""PAI 核心：事件模型、意圖模型、自主等級與主動行為迴圈。"""
+from __future__ import annotations
+
+import logging
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import IntEnum
+from typing import Any, Callable, Optional
+
+logger = logging.getLogger("pai")
+
+
+class AutonomyLevel(IntEnum):
+    """自主等級：決定 PAI 對一個意圖「可以主動到什麼程度」。
+
+    OBSERVE: 只記錄，不打擾
+    SUGGEST: 主動通知/建議，但不執行
+    ASK:     請求使用者確認後執行
+    ACT:     直接自動執行（高信心、低風險時）
+    """
+    OBSERVE = 0
+    SUGGEST = 1
+    ASK = 2
+    ACT = 3
+
+
+@dataclass
+class Event:
+    """感知層產生的標準事件格式。"""
+    source: str                       # 觸發器名稱
+    kind: str                         # 事件類型，如 "schedule.tick", "file.changed"
+    payload: dict = field(default_factory=dict)
+    ts: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id, "source": self.source, "kind": self.kind,
+            "payload": self.payload, "ts": self.ts.isoformat(),
+        }
+
+
+def _event_summary(event: "Event") -> str:
+    """把事件壓成一行文字，供記憶檢索使用。"""
+    payload = " ".join(f"{k}={v}" for k, v in event.payload.items())
+    return f"{event.kind} from {event.source}: {payload}".strip()
+
+
+@dataclass
+class Intent:
+    """決策層輸出的標準意圖格式。"""
+    action: str                       # 想執行的動作名稱
+    params: dict = field(default_factory=dict)
+    confidence: float = 0.5           # 0~1，決策信心
+    urgency: float = 0.5              # 0~1，緊急程度
+    rationale: str = ""               # 決策理由（可解釋性）
+    requested_level: AutonomyLevel = AutonomyLevel.SUGGEST
+    event_id: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "action": self.action, "params": self.params,
+            "confidence": self.confidence, "urgency": self.urgency,
+            "rationale": self.rationale,
+            "requested_level": int(self.requested_level),
+            "event_id": self.event_id,
+        }
+
+
+class PAIAgent:
+    """主動式 AI 代理：把觸發器、決策腦、治理政策、行動與記憶組裝成迴圈。"""
+
+    def __init__(self, name: str, brain, policy, memory, actions: dict[str, Any],
+                 confirm_handler: Optional[Callable[[Intent], bool]] = None,
+                 reflective=None):
+        self.name = name
+        self.brain = brain
+        self.policy = policy
+        self.memory = memory
+        self.actions = actions            # {action_name: Action 實例}
+        self.reflective = reflective      # ReflectiveMemory（記憶式即時學習，選用）
+        self.triggers: list = []
+        self.confirm_handler = confirm_handler or (lambda intent: False)
+        self._stop = threading.Event()
+
+    # ---- 組裝 ----
+    def add_trigger(self, trigger) -> "PAIAgent":
+        self.triggers.append(trigger)
+        return self
+
+    # ---- 主迴圈 ----
+    def run(self, duration: Optional[float] = None, poll_interval: float = 0.5):
+        """啟動主動行為迴圈。duration=None 表示持續運行。"""
+        logger.info("[%s] PAI agent started (%d triggers)", self.name, len(self.triggers))
+        start = time.time()
+        try:
+            while not self._stop.is_set():
+                for trigger in self.triggers:
+                    for event in trigger.poll():
+                        self._handle_event(event)
+                if duration is not None and time.time() - start >= duration:
+                    break
+                time.sleep(poll_interval)
+        finally:
+            logger.info("[%s] PAI agent stopped", self.name)
+
+    def stop(self):
+        self._stop.set()
+
+    # ---- 單一事件的完整生命週期 ----
+    def _handle_event(self, event: Event):
+        self.memory.record_event(event)
+        context = self.memory.build_context(event)
+
+        # 記憶式即時學習：把相似情境的回饋教訓注入決策上下文
+        if self.reflective is not None:
+            lessons = self.reflective.lessons_for(_event_summary(event))
+            if lessons:
+                context["lessons_from_feedback"] = lessons
+
+        intents = self.brain.decide(event, context)
+        for intent in intents:
+            intent.event_id = event.id
+            self._dispatch(intent, event)
+
+    def _dispatch(self, intent: Intent, event: Event):
+        from .protocol import build_record
+
+        context = self.memory.build_context(event)
+        granted = self.policy.gate(intent, self.memory)
+        cost = self.policy.last_interruption_cost
+        self.memory.record_intent(intent, granted=int(granted))
+
+        execution = {"actions_taken": [], "status": "not_executed"}
+        feedback = "pending"
+
+        if granted == AutonomyLevel.OBSERVE:
+            logger.debug("OBSERVE only: %s (%s)", intent.action, intent.rationale)
+            execution["status"] = "observed"
+
+        elif granted == AutonomyLevel.SUGGEST:
+            notifier = self.actions.get("__notify__")
+            if notifier:
+                notifier.execute(Intent(
+                    action="__notify__",
+                    params={"title": f"建議：{intent.action}",
+                            "body": intent.rationale, "intent": intent.to_dict()},
+                    confidence=intent.confidence, urgency=intent.urgency,
+                ))
+            self.memory.record_outcome(intent, status="suggested")
+            execution["status"] = "suggested"
+
+        else:  # ASK 或 ACT
+            action = self.actions.get(intent.action)
+            if action is None:
+                logger.warning("No action registered for intent '%s'", intent.action)
+                execution["status"] = "no_action_registered"
+            else:
+                approved = True
+                if granted == AutonomyLevel.ASK:
+                    approved = self.confirm_handler(intent)
+                    if not approved:
+                        self.memory.record_outcome(intent, status="declined")
+                        self.memory.record_feedback(intent, positive=False)
+                        execution["status"] = "declined"
+                        feedback = "rejected"
+                        self._learn(event, intent, "rejected")
+                if approved:
+                    try:
+                        result = action.execute(intent)
+                        self.memory.record_outcome(intent, status="executed", result=result)
+                        execution["actions_taken"].append(
+                            {"tool": intent.action, "status": "ok", "result": str(result)})
+                        execution["status"] = "executed"
+                        logger.info("Executed '%s' (confidence=%.2f): %s",
+                                    intent.action, intent.confidence, intent.rationale)
+                    except Exception as exc:  # noqa: BLE001
+                        self.memory.record_outcome(intent, status="failed", result=str(exc))
+                        execution["status"] = "failed"
+                        logger.exception("Action '%s' failed", intent.action)
+
+        # ACT 成功且使用者沒有否決 → 視為一次正向經驗
+        if execution["status"] == "executed" and granted == AutonomyLevel.ACT:
+            self._learn(event, intent, "accepted")
+
+        # 產生並保存 PAI Protocol 標準紀錄
+        record = build_record(event, context, intent, granted, cost,
+                              execution=execution, user_feedback=feedback)
+        self.memory.record_protocol(record)
+
+    # ---- 記憶式學習：對外的回饋 API ----
+    def record_user_feedback(self, event: Event, intent: Intent, feedback: str):
+        """外部 UI 收到使用者回饋（accepted/rejected/modified/ignored）時呼叫。"""
+        self._learn(event, intent, feedback)
+
+    def _learn(self, event: Event, intent: Intent, feedback: str):
+        if self.reflective is not None:
+            self.reflective.add_experience(
+                _event_summary(event), intent.action, intent.rationale, feedback)