agent.tools.rag
===============

.. py:module:: agent.tools.rag

.. autoapi-nested-parse::

   RAG 检索引擎：BM25 全文检索。

   扫描 docs/*.md + README.md，按 ## 标题切块后建立 BM25 索引。
   分词策略：中文用 jieba 分词，英文按空白拆分。



Attributes
----------

.. autoapisummary::

   agent.tools.rag._PROJECT_ROOT
   agent.tools.rag._DOC_DIR
   agent.tools.rag._STOP_WORDS
   agent.tools.rag._engine


Classes
-------

.. autoapisummary::

   agent.tools.rag.RagEngine


Functions
---------

.. autoapisummary::

   agent.tools.rag._tokenize
   agent.tools.rag.search_rag


Module Contents
---------------

.. py:data:: _PROJECT_ROOT
   :value: b'.'


.. py:data:: _DOC_DIR

.. py:data:: _STOP_WORDS

.. py:function:: _tokenize(text: str) -> list[str]

   中英文混合分词：中文用 jieba，英文按空白分割，过滤停用词。


.. py:class:: RagEngine

   零依赖 BM25 检索引擎，惰性初始化。


   .. py:attribute:: _docs
      :type:  list[dict]
      :value: []



   .. py:attribute:: _avgdl
      :value: 0.0



   .. py:attribute:: _idf
      :type:  dict[str, float]


   .. py:attribute:: _initialized
      :value: False



   .. py:method:: init() -> None

      惰性初始化：扫描文档 → 切块 → 建立 BM25 索引。幂等，多次调用仅执行一次。



   .. py:method:: _load_docs() -> None

      扫描 docs/*.md + README.md，按 ## 标题切块后存入 self._docs。



   .. py:method:: _build_index() -> None

      计算文档平均长度 + 每个词的 IDF，供 BM25 打分使用。



   .. py:method:: _bm25_score(q_tokens: list[str]) -> list[tuple[float, dict]]

      计算 BM25 分数（k1=1.5, b=0.75），返回 (分数, 文档) 列表，按分数降序排列。



   .. py:method:: search(query: str, k: int = 3) -> list[dict]

      BM25 检索，返回 top-k 条结果。低分时自动提取关键词重试。



.. py:data:: _engine

.. py:function:: search_rag(query: str, k: int = 3) -> list[dict]

   全局接口：检索 RAG 文档库，惰性初始化。

   Args:
       query: 用户查询文本。
       k: 返回 top-k 条结果，默认 3。

   Returns:
       list[dict]: 每项含 score/source/heading/text，按 BM25 分数降序。