firefly-judgment 0.1.0__py3-none-any.whl

firefly/__init__.py

@@ -0,0 +1,6 @@
+"""萤 (Firefly) —— 可嵌入 Agent Harness 的自成长判断系统。
+
+P0 核心包：协议 / 萤核 / 节点 / 工具图谱 / 总线 / SDK / 边车。
+"""
+
+__version__ = "0.1.0"

firefly/bootstrap.py

@@ -0,0 +1,38 @@
+"""一键装配萤总线：P0 路由/守门双节点；swarm_nodes=True 时加 P2 萤群五节点。"""
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from .bus import DecisionCache, Fallback, FireflyBus
+from .nodes import (
+    GateNode,
+    GuardPolicy,
+    LoopNode,
+    MemoryNode,
+    MetaNode,
+    RouterNode,
+    ScheduleNode,
+    VerifyNode,
+)
+
+
+def build_bus(
+    llm_decider: Optional[Callable] = None,
+    user_decider: Optional[Callable] = None,
+    cache_ttl_seconds: float = 5.0,
+    gate_policy: Optional[GuardPolicy] = None,
+    swarm_nodes: bool = False,
+) -> FireflyBus:
+    bus = FireflyBus(
+        cache=DecisionCache(ttl_seconds=cache_ttl_seconds),
+        fallback=Fallback(llm_decider=llm_decider, user_decider=user_decider),
+    )
+    bus.register_node(RouterNode())
+    bus.register_node(GateNode(policy=gate_policy))
+    if swarm_nodes:
+        bus.register_node(VerifyNode())
+        bus.register_node(LoopNode())
+        bus.register_node(ScheduleNode())
+        bus.register_node(MemoryNode())
+        bus.register_node(MetaNode())
+    return bus

firefly/bus/__init__.py

@@ -0,0 +1,17 @@
+"""萤总线层：路由 / 缓存 / 回退 / 审计 / 指标。"""
+from .audit import AuditLog
+from .bus import (
+    FireflyBus,
+    FireflyError,
+    NodeNotFound,
+    ProtocolViolation,
+)
+from .cache import DecisionCache
+from .fallback import Fallback, FallbackDecision
+from .metrics import Metrics
+
+__all__ = [
+    "FireflyBus", "FireflyError", "NodeNotFound", "ProtocolViolation",
+    "DecisionCache", "Fallback", "FallbackDecision",
+    "AuditLog", "Metrics",
+]

firefly/bus/audit.py

@@ -0,0 +1,90 @@
+"""决策审计日志（方案 5.6 / 9.1：审计日志不可篡改）。
+
+每条日志包含前一条哈希，形成 SHA-256 哈希链；可导出 JSONL 并随时验链。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+from typing import Dict, List, Optional
+
+from ..protocol.models import DecisionLogEntry
+
+
+class AuditLog:
+    def __init__(self) -> None:
+        self._entries: Dict[str, DecisionLogEntry] = {}
+        self._order: List[str] = []
+        self._prev_hash: Optional[str] = None
+        self._lock = threading.RLock()
+
+    def append(self, entry: DecisionLogEntry) -> DecisionLogEntry:
+        with self._lock:
+            entry.prev_hash = self._prev_hash
+            entry.entry_hash = self._hash(entry)
+            self._entries[entry.trace_id] = entry
+            self._order.append(entry.trace_id)
+            self._prev_hash = entry.entry_hash
+            return entry
+
+    def get(self, trace_id: str) -> Optional[DecisionLogEntry]:
+        with self._lock:
+            return self._entries.get(trace_id)
+
+    def list(self, limit: Optional[int] = None) -> List[DecisionLogEntry]:
+        with self._lock:
+            ids = self._order if limit is None else self._order[-limit:]
+            return [self._entries[t] for t in ids]
+
+    def attach_feedback(self, trace_id: str, feedback, outcome: str) -> Optional[DecisionLogEntry]:
+        with self._lock:
+            if trace_id not in self._entries:
+                return None
+            entry = self._entries[trace_id]
+            entry.outcome = outcome
+            entry.feedback = feedback.to_dict() if hasattr(feedback, "to_dict") else feedback
+            # 反馈使日志条目定版：重算该条及其后续条目的哈希链
+            self._rehash_from(self._order.index(trace_id))
+            return entry
+
+    def _rehash_from(self, start: int) -> None:
+        prev = self._entries[self._order[start - 1]].entry_hash if start > 0 else None
+        for i in range(start, len(self._order)):
+            entry = self._entries[self._order[i]]
+            entry.prev_hash = prev
+            entry.entry_hash = self._hash(entry)
+            prev = entry.entry_hash
+        self._prev_hash = prev
+
+    def verify_chain(self) -> bool:
+        with self._lock:
+            prev: Optional[str] = None
+            for trace_id in self._order:
+                entry = self._entries[trace_id]
+                if entry.prev_hash != prev:
+                    return False
+                if entry.entry_hash != self._hash(entry):
+                    return False
+                prev = entry.entry_hash
+            return True
+
+    @staticmethod
+    def _hash(entry: DecisionLogEntry) -> str:
+        body = {
+            "trace_id": entry.trace_id,
+            "request": entry.request,
+            "response": entry.response,
+            "node_version": entry.node_version,
+            "outcome": entry.outcome,
+            "feedback": entry.feedback,
+            "timestamp": entry.timestamp,
+            "prev_hash": entry.prev_hash,
+        }
+        canonical = json.dumps(body, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+    def save_jsonl(self, path: str) -> None:
+        with self._lock, open(path, "w", encoding="utf-8") as f:
+            for trace_id in self._order:
+                f.write(json.dumps(self._entries[trace_id].to_dict(), ensure_ascii=False) + "\n")

firefly/bus/bus.py

@@ -0,0 +1,249 @@
+"""萤总线 FireflyBus（方案 5.3 / 6.2）。
+
+职责：节点注册与路由、短缓存、软超时与回退、决策审计（哈希链）、
+反馈驱动的在线学习、工具图谱变更、指标采集。
+``federate`` / ``bid`` 属于 v0.2 能力，在 P0 显式留口。
+"""
+from __future__ import annotations
+
+import copy
+import logging
+import threading
+from typing import Any, Dict, Optional, Union
+
+from ..graph.tool_graph import ToolGraph
+from ..nodes.base import FireflyNode
+from ..protocol.models import (
+    DecisionLogEntry,
+    DecisionRequest,
+    DecisionResponse,
+    Feedback,
+    GraphDelta,
+    ToolSpec,
+)
+from ..protocol.schemas import validate_message
+from ..protocol.version import PROTOCOL_VERSION
+from .audit import AuditLog
+from .cache import DecisionCache
+from .fallback import Fallback
+from .metrics import Metrics
+
+BASE_DECISION_COST = 1e-5
+PER_OPTION_COST = 1e-6
+LLM_FALLBACK_COST = 1e-3
+logger = logging.getLogger("firefly.bus")
+
+
+class FireflyError(Exception):
+    """萤总线错误基类。"""
+
+
+class ProtocolViolation(FireflyError):
+    """消息违反协议 Schema。"""
+
+
+class NodeNotFound(FireflyError):
+    """请求的萤节点未注册。"""
+
+
+class FireflyBus:
+    def __init__(
+        self,
+        graph: Optional[ToolGraph] = None,
+        cache: Optional[DecisionCache] = None,
+        audit: Optional[AuditLog] = None,
+        metrics: Optional[Metrics] = None,
+        fallback: Optional[Fallback] = None,
+    ) -> None:
+        self.graph = graph or ToolGraph()
+        self.cache = cache or DecisionCache()
+        self.audit = audit or AuditLog()
+        self.metrics = metrics or Metrics()
+        self.fallback = fallback or Fallback()
+        self._nodes: Dict[str, FireflyNode] = {}
+        self._decision_listeners = []
+        self._feedback_listeners = []
+        self._lock = threading.RLock()
+
+    def add_decision_listener(self, listener) -> None:
+        """listener(DecisionRequest, DecisionResponse)，异常被隔离不影响决策。"""
+        self._decision_listeners.append(listener)
+
+    def add_feedback_listener(self, listener) -> None:
+        """listener(DecisionRequest, DecisionResponse, Feedback)。"""
+        self._feedback_listeners.append(listener)
+
+    # ------------------------------------------------------------------ #
+    # 节点与图谱
+    # ------------------------------------------------------------------ #
+    def register_node(self, node: FireflyNode, name: Optional[str] = None) -> FireflyNode:
+        with self._lock:
+            if node.graph is None:
+                node.graph = self.graph
+            key = name or node.node_type
+            self._nodes[key] = node
+            return node
+
+    def get_node(self, name: str) -> Optional[FireflyNode]:
+        return self._nodes.get(name)
+
+    def list_nodes(self) -> List[str]:
+        with self._lock:
+            return list(self._nodes.keys())
+
+    def register_tool(self, spec: Union[ToolSpec, Dict[str, Any]]) -> ToolSpec:
+        spec = spec if isinstance(spec, ToolSpec) else ToolSpec.from_dict(spec)
+        return self.graph.upsert_tool(spec)
+
+    def update_graph(self, delta: Union[GraphDelta, Dict[str, Any]]) -> None:
+        delta = delta if isinstance(delta, GraphDelta) else GraphDelta.from_dict(delta)
+        self.graph.apply_delta(delta)
+
+    # ------------------------------------------------------------------ #
+    # 决策
+    # ------------------------------------------------------------------ #
+    def decide(self, request: Union[DecisionRequest, Dict[str, Any]]) -> DecisionResponse:
+        if isinstance(request, dict):
+            # 裸边车客户端可省略协议版本，按当前版本补全后再做 schema 校验
+            payload = {"protocol_version": PROTOCOL_VERSION, **request}
+            errors = validate_message("decision_request", payload)
+            if errors:
+                raise ProtocolViolation("DecisionRequest 校验失败: " + "; ".join(errors))
+            request = DecisionRequest.from_dict(payload)
+        else:
+            errors = validate_message("decision_request", request.to_dict())
+            if errors:
+                raise ProtocolViolation("DecisionRequest 校验失败: " + "; ".join(errors))
+
+        node = self._nodes.get(request.node)
+        if node is None:
+            raise NodeNotFound(f"未注册的萤节点: {request.node}")
+
+        cache_key = self._cache_key(request)
+        cached = self.cache.get(cache_key)
+        if cached is not None:
+            response = copy.deepcopy(cached)
+            response.trace_id = request.trace_id
+            response.latency_ms = 0.0
+            response.extra["cache_hit"] = True
+            cache_hit = True
+        else:
+            response = node.decide(request)
+            cache_hit = False
+            self._apply_fallback_and_limits(request, response, node)
+            response_errors = validate_message("decision_response", response.to_dict())
+            if response_errors:
+                raise ProtocolViolation("DecisionResponse 校验失败: " + "; ".join(response_errors))
+            if not response.fallback_used:
+                self.cache.set(cache_key, response)
+
+        self.audit.append(
+            DecisionLogEntry(
+                trace_id=request.trace_id,
+                request=request.to_dict(),
+                response=response.to_dict(),
+                node_version=response.version,
+            )
+        )
+        self.metrics.record_decision(
+            request.node, response.latency_ms, response.fallback_used, cache_hit
+        )
+        for listener in list(self._decision_listeners):
+            try:
+                listener(request, response)
+            except Exception:  # noqa: BLE001
+                logger.exception("决策监听器执行异常")
+        return response
+
+    def feedback(
+        self,
+        trace_id: str,
+        feedback: Union[Feedback, Dict[str, Any], str],
+        corrected_choice: Any = None,
+        extra: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """结果回流：触发节点在线学习并闭环审计日志（方案 7.4）。"""
+        if isinstance(feedback, str):
+            feedback = Feedback(
+                outcome=feedback,
+                corrected_choice=corrected_choice,
+                extra=extra or {},
+            )
+        elif not isinstance(feedback, Feedback):
+            feedback = Feedback.from_dict(feedback)
+        entry = self.audit.get(trace_id)
+        if entry is None:
+            raise KeyError(f"找不到 trace_id 对应的决策日志: {trace_id}")
+
+        request = DecisionRequest.from_dict(entry.request)
+        response = DecisionResponse.from_dict(entry.response)
+        node = self._nodes.get(response.node)
+        if node is not None:
+            node.handle_feedback(request, response, feedback)
+
+        self.audit.attach_feedback(trace_id, feedback, feedback.outcome)
+        self.metrics.record_feedback(response.node, feedback.outcome, response.confidence)
+        self.cache.clear()  # 学习发生后旧缓存失效
+        for listener in list(self._feedback_listeners):
+            try:
+                listener(request, response, feedback)
+            except Exception:  # noqa: BLE001
+                logger.exception("反馈监听器执行异常")
+
+    # ------------------------------------------------------------------ #
+    # v0.2 能力留口
+    # ------------------------------------------------------------------ #
+    def federate(self, request: Any) -> Any:
+        raise NotImplementedError("联邦萤群为 v0.2（L3）能力，P0 暂未启用")
+
+    def bid(self, task: Any) -> Any:
+        raise NotImplementedError("判断市场为 v0.2（L4）能力，P0 暂未启用")
+
+    # ------------------------------------------------------------------ #
+    # 内部
+    # ------------------------------------------------------------------ #
+    def _apply_fallback_and_limits(
+        self, request: DecisionRequest, response: DecisionResponse, node: FireflyNode
+    ) -> None:
+        policy = request.constraints.fallback
+        timed_out = response.latency_ms > request.constraints.timeout_ms
+
+        decision = None
+        if timed_out and policy and policy.mode != "none":
+            decision = self.fallback.dispatch(policy.mode, request, response, node)
+            response.rationale = (response.rationale or "") + "；决策超过超时预算，触发强制回退"
+        else:
+            decision = self.fallback.resolve(request, response, node)
+
+        if decision is not None and decision.mode != "none":
+            response.choice = decision.choice
+            response.fallback_used = True
+            response.fallback_mode = decision.mode
+            response.rationale = f"回退决策（{decision.mode}）" + (
+                f"：{response.rationale}" if response.rationale else ""
+            )
+
+        mode = response.fallback_mode
+        if mode == "llm":
+            response.cost = LLM_FALLBACK_COST
+        else:
+            response.cost = round(
+                BASE_DECISION_COST + PER_OPTION_COST * len(request.options), 8
+            )
+
+    @staticmethod
+    def _as_request(request: Union[DecisionRequest, Dict[str, Any]]) -> DecisionRequest:
+        if isinstance(request, DecisionRequest):
+            return request
+        return DecisionRequest.from_dict(request)
+
+    @staticmethod
+    def _cache_key(request: DecisionRequest) -> str:
+        payload = {
+            "state": request.state.to_dict(),
+            "options": [o.to_dict() for o in request.options],
+            "constraints": request.constraints.to_dict(),
+            "explain": request.explain,
+            "counterfactual": request.counterfactual,
+        }
+        return DecisionCache.make_key(request.node, payload)

firefly/bus/cache.py

@@ -0,0 +1,55 @@
+"""决策短 TTL 缓存（方案 5.3：请求路由、缓存、批处理）。
+
+决策会随在线学习快速变化，因此缓存只用于极短时间内的相同请求去重。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+import time
+from typing import Any, Dict, Optional, Tuple
+
+
+class DecisionCache:
+    def __init__(self, ttl_seconds: float = 5.0, maxsize: int = 1024) -> None:
+        self.ttl_seconds = ttl_seconds
+        self.maxsize = maxsize
+        self._store: Dict[str, Tuple[float, Any]] = {}
+        self._lock = threading.Lock()
+
+    @staticmethod
+    def make_key(node: str, payload: Dict[str, Any]) -> str:
+        canonical = json.dumps(
+            {"node": node, "payload": payload},
+            ensure_ascii=False, sort_keys=True, separators=(",", ":"),
+            default=str,
+        )
+        return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+    def get(self, key: str) -> Optional[Any]:
+        if self.ttl_seconds <= 0:
+            return None
+        with self._lock:
+            item = self._store.get(key)
+            if item is None:
+                return None
+            expires_at, value = item
+            if time.time() > expires_at:
+                self._store.pop(key, None)
+                return None
+            return value
+
+    def set(self, key: str, value: Any) -> None:
+        if self.ttl_seconds <= 0:
+            return
+        with self._lock:
+            if len(self._store) >= self.maxsize:
+                # 简单淘汰最早写入的一个键
+                oldest = min(self._store.items(), key=lambda kv: kv[1][0])[0]
+                self._store.pop(oldest, None)
+            self._store[key] = (time.time() + self.ttl_seconds, value)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._store.clear()

firefly/bus/fallback.py

@@ -0,0 +1,106 @@
+"""回退器 Fallback（方案 6.4）。
+
+触发规则：
+1. 萤置信度低于阈值 → 回退到约束指定模式（llm / user / explore / deny）；
+2. 高风险任务且置信度不足 → 优先人类；
+3. 元认知检测到“状态信息不足” → 回退；
+4. 守门硬规则裁决（带 certificate，如 block）永不回退 —— 安全不能被 LLM 覆盖。
+
+LLM/用户的判断结果在总线收到反馈后作为教师信号回流训练（方案 6.4/7.4）。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from ..nodes.base import FireflyNode
+from ..protocol.models import DecisionRequest, DecisionResponse
+
+# (request, firefly_response) -> 选项 id
+Decider = Callable[[DecisionRequest, DecisionResponse], Any]
+
+
+@dataclass
+class FallbackDecision:
+    mode: str
+    choice: Any = None
+
+
+class Fallback:
+    def __init__(
+        self,
+        llm_decider: Optional[Decider] = None,
+        user_decider: Optional[Decider] = None,
+        high_risk_threshold: float = 0.8,
+    ) -> None:
+        self.llm_decider = llm_decider
+        self.user_decider = user_decider
+        self.high_risk_threshold = high_risk_threshold
+
+    def resolve(
+        self,
+        request: DecisionRequest,
+        response: DecisionResponse,
+        node: FireflyNode,
+    ) -> Optional[FallbackDecision]:
+        policy = request.constraints.fallback
+        mode = policy.mode if policy else "llm"
+        threshold = policy.threshold if policy else 0.6
+        if mode == "none":
+            return None
+
+        # 安全硬规则裁决不可回退（方案 9.1）
+        if response.certificate:
+            return None
+
+        trigger: Optional[str] = None
+        if response.confidence < threshold:
+            trigger = mode
+        elif request.state.risk == "high" and response.confidence < self.high_risk_threshold:
+            trigger = "user"
+        elif response.meta_cognition and any(
+            "状态信息不足" in unknown for unknown in response.meta_cognition.known_unknowns
+        ):
+            trigger = mode
+        if trigger is None:
+            return None
+
+        return self.dispatch(trigger, request, response, node)
+
+    def dispatch(
+        self,
+        mode: str,
+        request: DecisionRequest,
+        response: DecisionResponse,
+        node: FireflyNode,
+    ) -> FallbackDecision:
+        """按指定模式强制执行一次回退（用于决策超时等场景）。"""
+        if mode == "none":
+            return FallbackDecision("none", response.choice)
+        return self._dispatch(mode, request, response, node)
+
+    def _dispatch(
+        self,
+        mode: str,
+        request: DecisionRequest,
+        response: DecisionResponse,
+        node: FireflyNode,
+    ) -> FallbackDecision:
+        if mode == "llm":
+            if self.llm_decider is not None:
+                return FallbackDecision("llm", self.llm_decider(request, response))
+            mode = "explore"  # 未配置 LLM 时降级为探索
+        if mode == "user":
+            if self.user_decider is not None:
+                return FallbackDecision("user", self.user_decider(request, response))
+            if self.llm_decider is not None:
+                return FallbackDecision("llm", self.llm_decider(request, response))
+            mode = "deny"
+        if mode == "explore":
+            # 使用节点自身的决策空间（如过滤/守门的固定动作集）
+            return FallbackDecision("explore", node.explore_option(
+                request, node.prepare_options(request)
+            ))
+        if mode == "deny":
+            return FallbackDecision("deny", None)
+        return FallbackDecision(mode, None)

firefly/bus/metrics.py

@@ -0,0 +1,67 @@
+"""可观测指标（方案 9.3）。
+
+记录 decision_count / latency_p50,p95 / fallback_rate / cache_hit /
+feedback_outcome 等，按节点维度聚合。
+"""
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from typing import Dict, List
+
+
+class Metrics:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._counters: Dict[str, Dict[str, int]] = defaultdict(lambda: defaultdict(int))
+        self._latencies: Dict[str, List[float]] = defaultdict(list)
+        self._confidences: Dict[str, List[int]] = defaultdict(list)  # (confidence*100, outcome)
+
+    def record_decision(
+        self, node: str, latency_ms: float, fallback_used: bool, cache_hit: bool
+    ) -> None:
+        with self._lock:
+            c = self._counters[node]
+            c["decision_count"] += 1
+            if fallback_used:
+                c["fallback_count"] += 1
+            if cache_hit:
+                c["cache_hit_count"] += 1
+            self._latencies[node].append(latency_ms)
+
+    def record_feedback(self, node: str, outcome: str, confidence: float) -> None:
+        with self._lock:
+            self._counters[node][f"feedback_{outcome}"] += 1
+            self._confidences[node].append(
+                (round(confidence, 2), 1 if outcome == "success" else 0)
+            )
+            self._confidences[node] = self._confidences[node][-500:]
+
+    def snapshot(self) -> Dict[str, Dict[str, object]]:
+        with self._lock:
+            result: Dict[str, Dict[str, object]] = {}
+            for node, counters in self._counters.items():
+                count = counters.get("decision_count", 0)
+                latencies = sorted(self._latencies.get(node, []))
+                result[node] = {
+                    "decision_count": count,
+                    "fallback_count": counters.get("fallback_count", 0),
+                    "fallback_rate": round(
+                        counters.get("fallback_count", 0) / count, 4
+                    ) if count else 0.0,
+                    "cache_hit_count": counters.get("cache_hit_count", 0),
+                    "latency_p50_ms": _percentile(latencies, 50),
+                    "latency_p95_ms": _percentile(latencies, 95),
+                    "feedback": {
+                        k.replace("feedback_", ""): v
+                        for k, v in counters.items() if k.startswith("feedback_")
+                    },
+                }
+            return result
+
+
+def _percentile(sorted_values: List[float], pct: int) -> float:
+    if not sorted_values:
+        return 0.0
+    index = min(len(sorted_values) - 1, int(len(sorted_values) * pct / 100))
+    return round(sorted_values[index], 3)

firefly/core/__init__.py

@@ -0,0 +1,13 @@
+"""萤核层：编码、打分、校准、因果/元认知头。"""
+from .calibrator import TemperatureCalibrator, expected_calibration_error
+from .encoder import OptionEncoder, StateEncoder, l2_normalize, tokenize
+from .firefly_core import FireflyCore
+from .heads import CounterfactualHead, MetaCognitionHead
+from .scorer import BilinearScorer, ScoredResult, softmax
+
+__all__ = [
+    "FireflyCore", "BilinearScorer", "ScoredResult", "softmax",
+    "StateEncoder", "OptionEncoder", "tokenize", "l2_normalize",
+    "TemperatureCalibrator", "expected_calibration_error",
+    "CounterfactualHead", "MetaCognitionHead",
+]