foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/search/external_search.py

@@ -0,0 +1,50 @@
+"""
+BaiduWebSearchPort —— 把已有的 foxclaw.core.web_search（百度 AI 搜索）
+包装成 HSR 的外部检索端口(ExternalSearchPort)，接入 Retriever。
+
+没有另起一套联网搜索实现：Foxclaw 已经在用百度 AI 搜索
+(foxclaw/core/web_search.py，Agent 的 `_web_augment` 也在用它)，
+这里只是把它的返回结果(answer + references)转成 RawEvidence，
+让 HSR 的证据融合/策略循环可以复用它，而不是绕开它另建一套。
+
+未配置 BAIDU_SEARCH_KEY 或网络不通时，底层 web_search.search_answer()
+本身就会静默返回空 dict，这里顺势返回空列表，不影响 HSR 主流程。
+"""
+from __future__ import annotations
+from ..core import web_search as _ws
+from .models import RawEvidence, SourceType
+
+
+class BaiduWebSearchPort:
+    name = "baidu_web_search"
+
+    def search(self, text: str, top_k: int = 5) -> list[RawEvidence]:
+        payload = _ws.search_answer(text)
+        if not payload:
+            return []
+
+        out: list[RawEvidence] = []
+
+        answer = payload.get("answer", "")
+        if answer:
+            out.append(RawEvidence(
+                id="baidu:answer",
+                fact=answer,
+                source=SourceType.WEB,
+                origin="baidu_ai_search",
+                confidence=0.65,
+            ))
+
+        for i, ref in enumerate(payload.get("references", [])[:top_k]):
+            snippet = ref.get("content", "") or ref.get("abstract", "")
+            if not snippet:
+                continue
+            out.append(RawEvidence(
+                id=f"baidu:ref:{i}",
+                fact=snippet,
+                source=SourceType.WEB,
+                origin=ref.get("url", "") or ref.get("web_anchor", ""),
+                confidence=0.55,
+            ))
+
+        return out

package/python/foxclaw/search/hkc_read_port.py

@@ -0,0 +1,60 @@
+"""
+HKCReadPort —— 把 foxclaw-hkc 的检索能力接入 HSR 的 knowledge_port。
+
+融合之后:HKC 是 Foxclaw 内部的一个模块，不是外挂的独立系统。
+Foxclaw 启动时会在同一个 Python 进程里直接装配 HKCContainer
+(`foxclaw/__init__.py` 里的 `_init_hkc()`)，这里只是拿 hkc_sdk 的
+DirectClient 包一层，调用的是同进程里的对象方法，不发 HTTP 请求、
+不需要单独起服务、不存在"服务没启动"这种降级场景。
+
+这一层只暴露 query()，没有 ingest_text()——写不写知识回 HKC
+不是 HSR 的职责范围，那是 foxclaw-hkc 自己的 KDE/KEE 摄入管线，
+或者未来 Runtime 层的决定。
+
+如果确实需要把 foxclaw-hkc 单独部署成另一个服务(比如给其它系统复用)，
+client 换成 hkc_sdk.connect(base_url=...) 返回的 HTTPClient 依然能用——
+DirectClient/HTTPClient 方法签名完全一致，这里的代码不用改一行。
+"""
+from __future__ import annotations
+import logging
+
+from .models import RawEvidence, SourceType
+
+logger = logging.getLogger(__name__)
+
+
+class HKCReadPort:
+    """只读查询 foxclaw-hkc。需要一个已经连好的 hkc_sdk 客户端
+    (DirectClient 或 HTTPClient，两者接口一致)；没有就永远返回空列表，
+    不影响 HSR 主流程——和整个项目的降级哲学一致(没配就跳过，不报错)。"""
+
+    def __init__(self, client=None):
+        self._client = client
+
+    @property
+    def available(self) -> bool:
+        return self._client is not None
+
+    def query(self, text: str, top_k: int = 5) -> list[RawEvidence]:
+        if self._client is None:
+            return []
+
+        try:
+            hits = self._client.search(text, mode="hybrid", top_k=top_k)
+        except Exception as e:
+            logger.info(f"[HKC] 搜索「{text}」失败({e})")
+            return []
+
+        out: list[RawEvidence] = []
+        for h in hits:
+            fact = (h.summary or h.name or "").strip()
+            if not fact:
+                continue
+            out.append(RawEvidence(
+                id=h.ku_id,
+                fact=fact,
+                source=SourceType.KNOWLEDGE,
+                origin=f"hkc:{h.ku_id}",
+                confidence=float(h.score) if h.score else 0.6,
+            ))
+        return out

package/python/foxclaw/search/internal_search.py

@@ -0,0 +1,71 @@
+"""
+Internal Search Engine —— HSR-I 路由的内部检索器
+
+串联 HMR(记忆)与 HKC(知识，在同一进程内直连，Foxclaw 启动时装配好后
+通过 knowledge_port 传进来)：
+
+    1. 若配置了 knowledge_port：先查它拿权威知识候选
+    2. 查 HMR 拿原始记忆，补充上下文 + 给①做溯源材料
+    3. 交叉关联：knowledge 候选如果能在 HMR 里找到对应记忆，
+       标记 grounded_by；找不到就做置信度惩罚（孤证）
+    4. 没配置 knowledge_port / 没查到候选时，自然退化为纯 HMR 检索
+
+knowledge_port 只需要实现 query(text, top_k) -> list[RawEvidence]，
+这里不关心它具体是 foxclaw-hkc、还是别的什么知识源。
+"""
+from __future__ import annotations
+from difflib import SequenceMatcher
+from .models import RawEvidence
+
+_GROUNDING_SIMILARITY = 0.5
+_UNGROUNDED_PENALTY = 0.15
+
+
+class InternalSearchEngine:
+    def __init__(self, memory_port=None, knowledge_port=None, agent_port=None):
+        self.memory_port = memory_port
+        self.knowledge_port = knowledge_port
+        self.agent_port = agent_port
+
+    @staticmethod
+    def _safe_query(port, text: str, top_k: int) -> list[RawEvidence]:
+        """【深审修复·内部源隔离】逐个内部源 try/except → [],与 external 端口的隔离对称:
+        任一内部源(知识/记忆/Agent)失败都只让该源返回空,**不掀翻整个 search**。
+        现有三端口虽各自兜异常,但此处防御式隔离让"接入不兜异常的自定义 port"也安全。"""
+        if port is None:
+            return []
+        try:
+            return port.query(text, top_k) or []
+        except Exception:
+            return []
+
+    def search(self, text: str, top_k: int = 5) -> list[RawEvidence]:
+        from foxclaw.core.tracing import span as _span
+        with _span("search.internal", top_k=top_k):
+            knowledge_hits = self._safe_query(self.knowledge_port, text, top_k)
+            memory_hits = self._safe_query(self.memory_port, text, top_k)
+            agent_hits = self._safe_query(self.agent_port, text, top_k)
+
+        if knowledge_hits:
+            knowledge_hits = self._cross_link(knowledge_hits, memory_hits + agent_hits)
+
+        return knowledge_hits + memory_hits + agent_hits
+
+    def _cross_link(self, knowledge_hits, memory_hits) -> list[RawEvidence]:
+        linked = []
+        for k in knowledge_hits:
+            trace = self._find_trace(k, memory_hits)
+            if trace:
+                k.grounded_by = trace.id
+            else:
+                k.confidence = max(0.0, k.confidence - _UNGROUNDED_PENALTY)
+            linked.append(k)
+        return linked
+
+    def _find_trace(self, knowledge: RawEvidence, memory_hits: list[RawEvidence]):
+        best, best_sim = None, 0.0
+        for m in memory_hits:
+            sim = SequenceMatcher(None, knowledge.fact, m.fact).ratio()
+            if sim >= _GROUNDING_SIMILARITY and sim > best_sim:
+                best, best_sim = m, sim
+        return best

package/python/foxclaw/search/models.py

@@ -0,0 +1,127 @@
+"""
+Foxclaw — Search 内核数据模型 (HSR)
+
+设计原则：这一层只产出"证据"，不做任何持久化决策。
+是否把搜索结果沉淀回 HMR、是否提交知识库(未来的 foxclaw-hkc)，
+由调用方(Agent / Runtime)决定，这里的数据结构都是只读产物。
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class RouteType(str, Enum):
+    INTERNAL = "HSR-I"
+    EXTERNAL = "HSR-E"
+    HYBRID = "HYBRID"
+
+
+class SourceType(str, Enum):
+    MEMORY = "memory"
+    KNOWLEDGE = "knowledge"
+    AGENT = "agent"
+    WEB = "web"
+
+
+@dataclass
+class SubQuery:
+    id: str
+    text: str
+    source_hint: Optional[SourceType] = None
+    depends_on: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SearchPlan:
+    route: RouteType
+    steps: list[SubQuery]
+    reasoning: str = ""
+
+
+@dataclass
+class RawEvidence:
+    id: str
+    fact: str
+    source: SourceType
+    origin: str
+    confidence: float = 0.5
+    raw: Any = None
+    grounded_by: Optional[str] = None
+
+
+@dataclass
+class EvidenceNode:
+    id: str
+    fact: str
+    source: SourceType
+    origin: str
+    confidence: float
+    grounded_by: Optional[str] = None
+
+
+@dataclass
+class EvidenceEdge:
+    src: str
+    dst: str
+    relation: str
+
+
+@dataclass
+class EvidenceGraph:
+    nodes: dict[str, EvidenceNode] = field(default_factory=dict)
+    edges: list[EvidenceEdge] = field(default_factory=list)
+
+    def add_node(self, node: EvidenceNode) -> None:
+        self.nodes[node.id] = node
+
+    def add_edge(self, edge: EvidenceEdge) -> None:
+        self.edges.append(edge)
+
+    def contradictions(self) -> list[EvidenceEdge]:
+        return [e for e in self.edges if e.relation == "contradicts"]
+
+    def to_dict(self) -> dict:
+        """给 API / ThoughtChain 用的精简序列化。"""
+        return {
+            "nodes": [
+                {
+                    "id": n.id, "fact": n.fact, "source": n.source.value,
+                    "origin": n.origin, "confidence": round(n.confidence, 2),
+                    "grounded_by": n.grounded_by,
+                }
+                for n in self.nodes.values()
+            ],
+            "edges": [
+                {"src": e.src, "dst": e.dst, "relation": e.relation}
+                for e in self.edges
+            ],
+        }
+
+
+@dataclass
+class StrategyDecision:
+    action: str
+    reason: str
+    next_steps: list[SubQuery] = field(default_factory=list)
+
+
+@dataclass
+class SearchResult:
+    """search() 的唯一返回值。到这里为止，Search 内核不再做任何事。"""
+    query: str
+    route: RouteType
+    graph: EvidenceGraph
+    iterations: int
+    confidence: float
+    trace: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "query": self.query,
+            "route": self.route.value,
+            "confidence": round(self.confidence, 2),
+            "iterations": self.iterations,
+            "graph": self.graph.to_dict(),
+            "trace": self.trace,
+        }

package/python/foxclaw/search/planner.py

@@ -0,0 +1,44 @@
+"""
+Query Planner —— 决定路由(HSR-I / HSR-E / HYBRID)，并把任务拆成多跳检索步骤。
+
+当前是规则实现(触发词 + 标点拆句)，接口(SearchPlan)保持稳定，
+未来要换成 LLM function-calling 结构化拆解时，只需替换这个文件内部实现，
+不影响 Retriever / EvidenceFusion / SearchStrategy。
+"""
+from __future__ import annotations
+from .models import SearchPlan, SubQuery, RouteType
+from ..planning import planner as P
+
+_MEMORY_HINTS = ("我之前", "我们讨论过", "上次", "记得", "history", "之前说")
+_HYBRID_HINTS = ("为什么", "对比", "分析", "综合", "评估")
+
+
+class QueryPlanner:
+    def route(self, query: str, context: dict | None = None) -> RouteType:
+        if any(h in query for h in _MEMORY_HINTS):
+            return RouteType.INTERNAL
+        if any(h in query for h in _HYBRID_HINTS):
+            return RouteType.HYBRID
+        return RouteType.EXTERNAL
+
+    def plan(self, query: str, context: dict | None = None) -> SearchPlan:
+        route = self.route(query, context)
+
+        if route == RouteType.INTERNAL:
+            steps = [SubQuery(id="s1", text=query)]
+        elif route == RouteType.EXTERNAL:
+            steps = self._decompose(query)
+        else:
+            steps = [SubQuery(id="s1", text=query), *self._decompose(query, offset=2)]
+
+        return SearchPlan(
+            route=route,
+            steps=steps,
+            reasoning=f"route={route.value}, steps={len(steps)}",
+        )
+
+    def _decompose(self, query: str, offset: int = 1) -> list[SubQuery]:
+        parts = P.split_on(query, P.LIST_SEPS)
+        if len(parts) <= 1:
+            parts = [query]
+        return [SubQuery(id=f"s{offset + i}", text=p) for i, p in enumerate(parts)]

package/python/foxclaw/search/retriever.py

@@ -0,0 +1,39 @@
+"""
+Retriever —— 内部检索(委托 InternalSearchEngine 串联 HMR/未来的 HKC)
+与外部检索(联网搜索，当前是百度 AI 搜索)的统一入口。
+"""
+from __future__ import annotations
+from .models import SubQuery, RawEvidence, RouteType
+from .internal_search import InternalSearchEngine
+
+
+class Retriever:
+    def __init__(
+        self,
+        memory_port=None,
+        knowledge_port=None,
+        external_ports: list | None = None,
+        internal_search: InternalSearchEngine | None = None,
+    ):
+        self.internal_search = internal_search or InternalSearchEngine(
+            memory_port=memory_port, knowledge_port=knowledge_port,
+        )
+        self.external_ports = external_ports or []
+
+    def retrieve(self, steps: list[SubQuery], route: RouteType) -> list[RawEvidence]:
+        results: list[RawEvidence] = []
+        for step in steps:
+            if route in (RouteType.INTERNAL, RouteType.HYBRID):
+                results += self.internal_search.search(step.text)
+            if route in (RouteType.EXTERNAL, RouteType.HYBRID):
+                results += self._retrieve_external(step)
+        return results
+
+    def _retrieve_external(self, step: SubQuery) -> list[RawEvidence]:
+        out: list[RawEvidence] = []
+        for port in self.external_ports:
+            try:
+                out += port.search(step.text)
+            except Exception:
+                continue
+        return out

package/python/foxclaw/search/runtime.py

@@ -0,0 +1,127 @@
+"""
+Foxclaw — Search: 认知搜索内核 (HSR)
+=======================================
+把"查内部记忆(HMR)"、"查内部知识(HKC)"和"查外部世界(联网搜索)"统一成
+一次 search() 调用，供五个 Agent 共享。和 Finance / Learning / Itinerary
+三个领域内核一样，遵循同一条边界：
+
+    内核只产出证据 / 建议，不越权替调用方做决策。
+    Finance 内核只建议、不动钱；Search 内核只给证据、不代替 Agent
+    决定"这次搜索结果值不值得写回 HMR"——那是 Agent 自己的事
+    (Agent 已经有 `_store_memory()`，Search 不需要再造一个)。
+
+HKC 融合说明：
+    HKC(foxclaw-hkc)现在是 Foxclaw 内部的一个模块，不是外挂的独立系统。
+    `foxclaw/__init__.py` 在启动时会在同一个 Python 进程里直接装配
+    HKCContainer，用 hkc_sdk.DirectClient 包成 HKCReadPort，再传进这里
+    的 knowledge_port——全程没有 HTTP、没有第二个服务、没有端口。
+    SearchRuntime 本身完全不关心 knowledge_port 具体是不是 HKC，
+    只要实现了 query(text, top_k) 就行，这条边界保持干净。
+"""
+from __future__ import annotations
+from typing import Optional
+
+from .models import SearchResult, RawEvidence, SourceType, RouteType
+from .planner import QueryPlanner
+from .internal_search import InternalSearchEngine
+from .external_search import BaiduWebSearchPort
+from .retriever import Retriever
+from .evidence import EvidenceFusion
+from .strategy import SearchStrategy
+
+
+class _HMRMemoryReadPort:
+    """把 HMRAdapter / MockHMR 的 recall() 适配成 InternalSearchEngine
+    需要的只读查询接口：query(text, top_k) -> list[RawEvidence]。
+
+    故意只暴露 query，不暴露 ingest——HSR 内部检索只读 HMR，
+    写不写记忆由 Agent 层的 `_store_memory()` 决定。"""
+
+    def __init__(self, hmr, agent_id: Optional[str]):
+        self.hmr = hmr
+        self.agent_id = agent_id
+
+    def query(self, text: str, top_k: int = 5) -> list[RawEvidence]:
+        try:
+            results = self.hmr.recall(query=text, agent_id=self.agent_id, top_k=top_k)
+        except Exception:
+            return []
+        out: list[RawEvidence] = []
+        for r in results or []:
+            content = r.get("content", "") or r.get("title", "")
+            if not content:
+                continue
+            conf = r.get("confidence", r.get("score", 0.6))
+            out.append(RawEvidence(
+                id=r.get("id", "") or f"hmr:{len(out)}",
+                fact=content,
+                source=SourceType.MEMORY,
+                origin=f"hmr:{r.get('id', '')}",
+                confidence=float(conf) if conf is not None else 0.6,
+            ))
+        return out
+
+
+class SearchRuntime:
+    """Foxclaw 的认知搜索内核。一次初始化，五个 Agent 共享调用
+    （与 self.hmr / self.hkc / self.router / self.token_meter 同级）。"""
+
+    def __init__(self, hmr=None, knowledge_port=None, agent_port=None,
+                 external_ports: list | None = None):
+        self.hmr = hmr
+        self.knowledge_port = knowledge_port
+        self.agent_port = agent_port
+        self.planner = QueryPlanner()
+        self.fusion = EvidenceFusion()
+        self.strategy = SearchStrategy()
+        self.external_ports = (
+            external_ports if external_ports is not None else [BaiduWebSearchPort()]
+        )
+
+    def search(self, query: str, agent_id: str | None = None, context: dict | None = None,
+               internal_only: bool = False) -> SearchResult:
+        """唯一公开入口。给定 query，返回 SearchResult，过程中不写任何持久化状态。
+
+        internal_only=True:只查内部(HMR记忆 + HKC知识 + Agent态势),跳过联网。
+        供 Agent 反向调用内部搜索作工具时用(双向连通的「Agent→搜索」方向)。"""
+        memory_port = _HMRMemoryReadPort(self.hmr, agent_id) if self.hmr else None
+        internal = InternalSearchEngine(
+            memory_port=memory_port, knowledge_port=self.knowledge_port,
+            agent_port=self.agent_port,
+        )
+        external_ports = [] if internal_only else self.external_ports
+        retriever = Retriever(internal_search=internal, external_ports=external_ports)
+
+        trace: list[str] = []
+        plan = self.planner.plan(query, context)
+        if internal_only and plan.route == RouteType.EXTERNAL:
+            plan.route = RouteType.INTERNAL
+            trace.append("[internal_only] 路由改写为 HSR-I(仅内部)")
+        trace.append(f"[plan] {plan.reasoning}")
+
+        raw = retriever.retrieve(plan.steps, plan.route)
+        graph = self.fusion.build(raw)
+        confidence = self.fusion.confidence(graph)
+
+        iteration = 0
+        while True:
+            decision = self.strategy.decide(graph, confidence, iteration, query)
+            trace.append(f"[loop {iteration}] {decision.action}: {decision.reason}")
+
+            if decision.action == "stop":
+                break
+
+            more = retriever.retrieve(decision.next_steps, plan.route)
+            if not more:
+                trace.append(f"[loop {iteration}] 无新证据，提前停止")
+                break
+
+            raw += more
+            graph = self.fusion.build(raw)
+            confidence = self.fusion.confidence(graph)
+            iteration += 1
+
+        return SearchResult(
+            query=query, route=plan.route, graph=graph,
+            iterations=iteration, confidence=confidence, trace=trace,
+        )

package/python/foxclaw/search/strategy.py

@@ -0,0 +1,44 @@
+"""
+Search Strategy —— 决定 continue / stop / switch_query / switch_source。
+纯函数式判断(无状态、无 IO)，可独立单测和演进。
+"""
+from __future__ import annotations
+from .models import EvidenceGraph, StrategyDecision, SubQuery
+
+_CONFIDENCE_STOP_THRESHOLD = 0.75
+_MAX_ITERATIONS = 3
+
+
+class SearchStrategy:
+    def decide(
+        self,
+        graph: EvidenceGraph,
+        confidence: float,
+        iteration: int,
+        original_query: str,
+    ) -> StrategyDecision:
+        if confidence >= _CONFIDENCE_STOP_THRESHOLD:
+            return StrategyDecision(action="stop", reason=f"置信度 {confidence:.2f} 已达标")
+
+        if iteration >= _MAX_ITERATIONS:
+            return StrategyDecision(action="stop", reason="达到最大迭代次数，防止无限循环")
+
+        if graph.contradictions():
+            return StrategyDecision(
+                action="switch_source",
+                reason="存在冲突证据，尝试切换更权威数据源",
+                next_steps=[SubQuery(id=f"retry{iteration}", text=original_query)],
+            )
+
+        if len(graph.nodes) < 2:
+            return StrategyDecision(
+                action="switch_query",
+                reason="证据不足，尝试改写查询",
+                next_steps=[SubQuery(id=f"rephrase{iteration}", text=original_query + " 详细信息")],
+            )
+
+        return StrategyDecision(
+            action="continue",
+            reason="证据尚可但置信度不足，继续补充检索",
+            next_steps=[SubQuery(id=f"more{iteration}", text=original_query)],
+        )