全文搜尋(BM25)

fuzzy 做成對的字串相似度,``skill_library`` 做字母序的子字串比對,但兩者都無法依相關性對 文件語料*排名 —— 罕見的獨特詞與隨處可見的詞權重相同。本功能補上以倒排索引、用 Okapi **BM25* (或 TF-IDF)排名文件的搜尋,讓流程與 agent 不需資料庫即可搜尋日誌、爬取紀錄或知識片段。

純標準函式庫(math + collections + re);具決定性;不匯入 PySide6。

無頭 API

from je_auto_control import SearchIndex, search_documents

corpus = {
    "d1": "the quick brown fox jumps over the lazy dog",
    "d2": "a quick brown dog runs fast",
    "d3": "the database stores quick query results",
}

index = SearchIndex.build(corpus)          # 或 SearchIndex(); index.add(id, text)
for hit in index.search("quick dog", top_k=5):
    print(hit.doc_id, hit.score)

# 一次性便利函式
hits = search_documents(corpus, "database", mode="bm25")

SearchIndex.add / remove 以增量方式維護索引;``build`` 索引一個 {doc_id: text} 對映 (或 (id, text) 配對)。search 回傳排名後的 SearchHit(doc_id, score) 結果 —— 預設 為 BM25(k1=1.5、b=0.75),或 mode="tfidf"。評分採標準 Okapi 公式, IDF = ln(1 + (N − df + 0.5) / (df + 0.5)),因此罕見詞勝過常見詞、詞頻會飽和(k1)、長 文件被正規化下調(b)。可提供 stop_words 集合以濾除雜訊詞。結果具決定性(平手以 doc_id 決定)。

執行器命令

AC_search_documents 接受 docs``(``{doc_id: text} 對映或 JSON 字串)、query 與選用 的 top_k / mode,回傳 {hits: [{doc_id, score}]}。同一操作亦以 MCP 工具 ac_search_documents 以及 Script Builder 中 Data 分類下的命令提供。