本项目是论文 Explainable Innovation Engine: Dual-Tree Agent-RAG with Methods-as-Nodes and Verifiable Write-Back 的工程化可运行实现。系统以 methods-as-nodes 代替传统 text chunks,围绕两棵核心树展开:
Method Provenance Tree (T_M):表示方法的推导来源与父子依赖Clustering Abstraction Tree (T_C):表示方法在不同抽象层的聚类结构
在线推理时,系统执行以下闭环:
- 在
T_C上做分层漏斗检索Funnel Retrieval - 在
T_M上做加权祖先回溯Weighted Ancestor Backtracking - 由
Strategy Agent选择推理算子并合成候选创新 - 由
Verifier + Scorer验证、评分、剪枝 - 将保留的创新节点执行
Write-back写回知识库
本实现优先保证:
- 本地可运行
- 结构完整
- 模块可扩展
- 无需付费 API 也能跑通 demo
该仓库用于以下场景:
- 复现论文中的 Agent-RAG 双树架构
- 搭建研究原型或工程基线
- 在本地小规模语料上验证方法抽取、聚类、检索、创新生成流程
- 为未来接入真实 LLM、真实 embedding 模型、FAISS、形式化验证器提供稳定接口
- 多模态文档统一化解析
- 上下文保留式分段
- 方法抽取与关系抽取
- 方法去重与 canonicalization
- 构建
T_M - 构建
T_C - repository / tree 序列化保存
- 多层 Funnel Retrieval
- Weighted Ancestor Backtracking
- Strategy Agent 算子选择
- 候选创新合成
- Heuristic Verifier 验证
- Hybrid Deterministic Scorer 评分与剪枝
- 保留创新写回知识图结构
- 自动提出研究问题
- 运行若干轮自主演化
- 持久化演化历史日志
Input Documents
-> Multimodal Parser
-> Context-Preserving Segmenter
-> Method Extractor + Relation Extractor
-> Method Repository
-> T_M (Method Provenance Tree)
-> T_C (Clustering Abstraction Tree)
User Query
-> Funnel Retrieval on T_C
-> Weighted Ancestor Backtracking on T_M
-> Strategy Agent
-> Candidate Synthesizer
-> Verifier
-> Scorer
-> Pruning
-> Write-back
-> Final Answer + Trace + Evidence
- Python 3.11+
- 推荐使用虚拟环境
完整安装:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .如果不安装依赖,demo 仍然可以依靠 fallback 运行,但建议至少安装 requirements.txt。
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/demo.yaml demoPYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml build-index data/demo_docs/provenance_methods.txt data/demo_docs/strategy_methods.txt data/demo_docs/verification_notes.jsonPYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml query "How can we synthesize an explainable innovation pipeline for low-resource scientific corpora?"PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml inspect-tree tm
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml inspect-tree tcPYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml evolve --iterations 2作用:对输入文档执行离线构建,产出 repository、T_M、T_C 三类持久化文件。
命令:
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml build-index <doc1> <doc2> ...输入:
.txt.md.json.pdf
输出:
artifacts/.../repository.jsonartifacts/.../t_m.jsonartifacts/.../t_c.json
作用:加载已构建索引,执行完整在线推理流程。
命令:
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml query "your query"关闭写回:
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml query "your query" --no-write-back输出内容包括:
- 最终回答
final_answer - 创新摘要
innovation_summary - 推导链
derivation_chain - 证据
evidence - 分数明细
scores - trace 日志
trace
作用:导出树结构的 JSON-friendly 视图,便于后续画图或调试。
命令:
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml inspect-tree tm
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml inspect-tree tc作用:从当前 repository 中自动提出研究问题并执行多轮创新演化。
命令:
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml evolve --iterations 3输出:
- 每轮 query
- 保留候选
- 丢弃候选
- 演化日志 JSON
作用:从 demo 文档出发,完整执行 build + query + write-back。
命令:
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/demo.yaml demo输入文档通过 MultimodalParser 被转换为统一 Document schema。当前支持:
- 文本文件
- Markdown 文本
- JSON 结构化文档
- PDF 文本提取
ContextPreservingSegmenter 不是按固定窗口切段,而是:
- 若全文长度
<= L0,整篇保留为一个 segment - 若全文长度
> L0,尝试根据标题边界切分 - 若仍然过长,则按段落组装出多个 chunk
HeuristicMethodExtractor 使用确定性规则:
- 从标题和句子中识别方法名称候选
- 区分 prior methods 和 derived method
- 为每个方法生成 summary 与 keywords
HeuristicRelationExtractor 根据 cue words 给边打离散分:
- 强关系:5
- 中关系:4
- 弱关系:3
- 默认相关:2
并映射为连续权重:
w_ij = (r_ij - 1) / 4
MethodRepository 中每个方法会被 embedding,随后执行相似度比较:
sim(m_a, m_b) = cosine(v(m_a), v(m_b))
若超过 merge_threshold,则合并为 canonical method node,并保留:
- aliases
- 来源段落
- 来源文档
- provenance note
- incident edges
MethodProvenanceTree 负责:
- 为每个 target method 选择 primary parent
- 保留 supporting edges
- 防止 primary backbone 出现环
ClusteringAbstractionTree 负责:
- 对 method embeddings 做递归聚类
- 每层 cluster 数按论文公式递减
- 为每个 cluster 生成 summary
- 支持多 root cluster
FunnelRetriever 逐层从上到下做 cluster 选择:
k_t = max(1, ceil(k_1 * eta^(t-1)))
输出:
- selected clusters
- retrieved leaf methods
WeightedAncestorBacktracker 使用累积影响值:
I_d(m) = product(w_l(m) + eps)
满足:
I_d(m) >= taud <= m_max
则将祖先加入上下文集合。
StrategyAgent 从四个算子中选一个:
deductioninductionanalogyabduction
随后 HeuristicSynthesizer 生成多个创新候选,每个候选包含:
- 名称
- 摘要
- 父方法
- 父贡献权重
- 创新解释
- 适用边界
- 验证计划
HeuristicVerifier 检查:
- 是否重复命名
- parent 是否存在
- contribution 是否归一化
- summary / validation plan 是否足够完整
HybridDeterministicScorer 输出五维 rubric:
- Novelty
- Consistency / Explainability
- Verifiability
- Applicability
- Goal Alignment
WriteBackManager 将保留候选变为新的 MethodNode,并创建 parent edges,随后重新构建 T_M 和 T_C。
当前配置文件实际使用的是 JSON-compatible YAML,因此即使没有 PyYAML 也能用内置 json 回退解析。
paths.artifact_dir: 输出目录paths.repository_file: repository 序列化文件paths.provenance_tree_file:T_M序列化文件paths.abstraction_tree_file:T_C序列化文件providers.embedder.type:auto/hash/sentence-transformerproviders.embedder.dimension: hash embedding 维度ingestion.segment_length_threshold:L0ingestion.max_segment_length: 分段最大长度repository.merge_threshold: 方法合并阈值trees.abstraction_depth:T_C层数trees.k1: 第一层聚类数trees.k_min: 最后一层最小聚类数retrieval.top_k_start: 第 1 层漏斗预算retrieval.eta: 层间预算衰减系数retrieval.backtracking_tau: 祖先回溯影响阈值retrieval.backtracking_max_depth: 回溯深度上限scoring.threshold: 剪枝阈值strategy.candidate_count: 每次生成候选数evolution.max_iterations: 自主演化最大轮数
下面只列出需要人工维护或核心运行时相关的文件。__pycache__ 等自动生成目录不纳入维护说明。
- README.md
- 项目总说明与双语手册。
- requirements.txt
- 依赖清单,包含可选增强依赖,如
sentence-transformers、pypdf、scikit-learn。
- 依赖清单,包含可选增强依赖,如
- pyproject.toml
- 打包配置、脚本入口、可选依赖定义。
- .gitignore
- 忽略虚拟环境、缓存、构建产物、artifacts。
- configs/default.yaml
- 默认运行配置,适合常规 build/query/evolve。
- configs/demo.yaml
- 演示配置,优先使用 hash embedder,保证低依赖可跑通。
- data/demo_docs/provenance_methods.txt
- 关于 provenance、backtracking、retrieval 的示例文本。
- data/demo_docs/strategy_methods.txt
- 关于 strategy agent、repository、write-back 的示例文本。
- data/demo_docs/verification_notes.json
- JSON 结构化示例文档,覆盖 verifier、scorer、cluster tree、autonomous loop。
- src/agent_rag/init.py
- 包导出入口,暴露
InnovationEngine。
- 包导出入口,暴露
- src/agent_rag/schemas.py
- 定义所有核心 dataclass,包括
Document、MethodNode、MethodEdge、ClusterNode、InnovationCandidate、QueryResult等。
- 定义所有核心 dataclass,包括
- src/agent_rag/config.py
- 定义配置 dataclass,并负责从配置文件中加载
EngineConfig。
- 定义配置 dataclass,并负责从配置文件中加载
- src/agent_rag/utils/init.py
- 工具子包初始化文件。
- src/agent_rag/utils/logging_utils.py
- 日志配置工具。
- src/agent_rag/utils/text_utils.py
- 文本归一化、分句、关键词提取、heading 检测、稳定 ID 生成等通用文本工具。
- src/agent_rag/utils/math_utils.py
- 权重映射、向量归一化、余弦相似度、均值向量、累积影响计算等数学函数。
- src/agent_rag/providers/init.py
- provider 子包初始化文件。
- src/agent_rag/providers/llm_base.py
- LLM provider 抽象接口,定义
generate、summarize、judge。
- LLM provider 抽象接口,定义
- src/agent_rag/providers/llm_stub.py
- 无 API 的本地 stub LLM,实现确定性摘要与生成。
- src/agent_rag/providers/embedder_base.py
- embedding provider 抽象接口。
- src/agent_rag/providers/local_embedder.py
- 实现
HashingEmbedder和SentenceTransformerEmbedder,并提供自动 fallback 构造函数。
- 实现
- src/agent_rag/ingestion/init.py
- ingestion 子包初始化文件。
- src/agent_rag/ingestion/multimodal_parser.py
- 统一解析
.txt、.md、.json、.pdf为Document。
- 统一解析
- src/agent_rag/ingestion/segmenter.py
- 按标题边界与段落上下文进行切分,避免简单固定长度切块。
- src/agent_rag/extraction/init.py
- extraction 子包初始化文件。
- src/agent_rag/extraction/method_extractor.py
- 方法候选识别、derived/prior 区分、method node 构建。
- src/agent_rag/extraction/relation_extractor.py
- 从句子 cue 中抽取 prior -> derived 关系并打分。
- src/agent_rag/repository/init.py
- repository 子包初始化文件。
- src/agent_rag/repository/method_repository.py
- 核心知识库,负责方法去重、合并、alias 管理、边归一化、序列化。
- src/agent_rag/repository/provenance_graph.py
- repository 的图视图封装,提供 incoming/outgoing edge 查询。
- src/agent_rag/trees/init.py
- trees 子包初始化文件。
- src/agent_rag/trees/provenance_tree.py
- 构建并维护
Method Provenance Tree (T_M)。
- 构建并维护
- src/agent_rag/trees/abstraction_tree.py
- 构建并维护
Clustering Abstraction Tree (T_C)。
- 构建并维护
- src/agent_rag/trees/clustering.py
MiniBatchKMeans适配器,优先用 sklearn,缺失时回退到纯 Python 实现。
- src/agent_rag/trees/summarizer.py
- cluster summary 生成器,支持 heuristic 与 LLM-style 接口。
- src/agent_rag/retrieval/init.py
- retrieval 子包初始化文件。
- src/agent_rag/retrieval/funnel_retriever.py
- 在
T_C上执行 top-down funnel retrieval。
- 在
- src/agent_rag/retrieval/backtracking.py
- 在
T_M上执行 weighted ancestor backtracking。
- 在
- src/agent_rag/strategy/init.py
- strategy 子包初始化文件。
- src/agent_rag/strategy/operators.py
- 定义 reasoning operator library,包括 deduction、induction、analogy、abduction。
- src/agent_rag/strategy/strategy_agent.py
- 根据 query 与上下文选择最合适的推理算子。
- src/agent_rag/strategy/synthesizer.py
- 生成创新候选、父贡献、验证计划、创新解释等内容。
- src/agent_rag/verification/init.py
- verification 子包初始化文件。
- src/agent_rag/verification/verifier_base.py
- verifier 抽象接口。
- src/agent_rag/verification/heuristic_verifier.py
- 默认非形式化验证器,实现结构一致性与规则检查。
- src/agent_rag/verification/formal_stub.py
- 形式化验证器预留适配器 stub。
- src/agent_rag/scoring/init.py
- scoring 子包初始化文件。
- src/agent_rag/scoring/scorer.py
- 混合确定性评分器,实现五维 rubric、贡献深度自适应、剪枝逻辑。
- src/agent_rag/evolution/init.py
- evolution 子包初始化文件。
- src/agent_rag/evolution/writeback.py
- 将 retained innovation 写回 repository,并创建 parent edges。
- src/agent_rag/evolution/autonomous_loop.py
- 自动提出新 query 并执行多轮创新演化。
- src/agent_rag/engine/init.py
- engine 子包初始化文件。
- src/agent_rag/engine/innovation_engine.py
- 总编排器。负责 build、query、evolve、save/load、demo 执行。
- src/agent_rag/cli/init.py
- CLI 子包初始化文件。
- src/agent_rag/cli/main.py
- 命令行参数解析与子命令分发入口。
- tests/init.py
- 将
src注入测试路径。
- 将
- tests/test_segmentation.py
- 测试标题感知分段。
- tests/test_dedup.py
- 测试 method merge / dedup。
- tests/test_tree_build.py
- 测试 primary parent 选择和
T_C构建。
- 测试 primary parent 选择和
- tests/test_retrieval.py
- 测试 funnel retrieval。
- tests/test_backtracking.py
- 测试 weighted ancestor backtracking。
- tests/test_scoring.py
- 测试 weight mapping 与 pruning。
- tests/test_end_to_end.py
- 测试完整 build + query 流程。
artifacts/demo/repository.json- demo 运行后生成的方法仓库。
artifacts/demo/t_m.json- demo 运行后生成的
T_M。
- demo 运行后生成的
artifacts/demo/t_c.json- demo 运行后生成的
T_C。
- demo 运行后生成的
这些文件不是源码,但它们是 inspect/debug/visualization 的重要输入。
代码位置:
公式:
w_ij = (r_ij - 1) / 4
代码位置:
公式:
w_tilde_ij = w_ij / (sum_k w_kj + eps)
代码位置:
公式:
k_t = max(1, ceil(k_1 * eta^(t-1)))
代码位置:
公式:
I_d(m) = product_{l=1..d}(w_l(m) + eps)
代码位置:
公式:
d_i = d_min + floor(d_range * (w_tilde_i)^gamma)
query 和 demo 的 JSON 输出字段:
final_answer: 给用户的摘要回答innovation_summary: 每个候选创新的简表derivation_chain: 候选对应的父方法链evidence: 验证证据与评分说明scores: rubric 分数明细trace.selected_clusters: 每层选中的 clustertrace.retrieved_leaf_methods: 检索到的叶子方法trace.backtracked_ancestors: 加权祖先回溯轨迹trace.chosen_operator: 策略算子trace.candidate_scores: 候选的评分与验证结果trace.kept_candidates: 保留的候选trace.dropped_candidates: 剪掉的候选
运行测试:
PYTHONPATH=src python3 -m unittest discover -s tests -v当前覆盖点:
- segmentation
- weight mapping
- dedup merge
- primary parent selection
- abstraction tree build
- funnel retrieval
- weighted ancestor backtracking
- score threshold prune
- end-to-end pipeline
可以。系统会自动回退到 HashingEmbedder。
可以。系统会回退到纯 Python 版 MiniBatchKMeansAdapter。
不会。配置文件是 JSON-compatible YAML,加载器会自动尝试用 json 回退解析。
系统会依次尝试:
pypdfpdftotext- 二进制文本回退
如果 PDF 是扫描版,建议先 OCR。
这是工程化 fallback 版本,重点是保留论文结构与执行闭环,而不是复刻封闭模型效果。
本项目明确使用了若干工程近似:
- 方法抽取采用启发式规则,不依赖外部 LLM IE
- cluster summary 默认采用 heuristic summarizer
- verifier 默认不是形式化证明器
- write-back 默认采用 full rebuild 保证结构一致性
这些近似是为了保证:
- 可以离线运行
- 模块边界清晰
- 未来可替换为更强组件
如果你准备继续扩展这个项目,建议优先做以下几件事:
- 将
HeuristicMethodExtractor替换成真实 LLM IE provider - 将
StubLLMProvider替换为 OpenAI / Gemini / DeepSeek / local vLLM provider - 在 repository 中增加 ANN / FAISS 检索路径
- 对
T_C引入更稳定的增量更新策略 - 接入真实形式化验证器
- 增加更丰富的可视化层
返回顶部:Top
This repository is a runnable engineering implementation of the paper Explainable Innovation Engine: Dual-Tree Agent-RAG with Methods-as-Nodes and Verifiable Write-Back.
The system replaces chunk-based retrieval with methods-as-nodes and organizes knowledge through two trees:
Method Provenance Tree (T_M)Clustering Abstraction Tree (T_C)
At query time, the pipeline executes:
- hierarchical funnel retrieval on
T_C - weighted ancestor backtracking on
T_M - strategy-agent operator selection and innovation synthesis
- verification, scoring, and pruning
- write-back of retained innovations
The implementation prioritizes:
- local runnability
- architectural completeness
- clear modularity
- no mandatory paid API dependency
Use this repository to:
- reproduce the dual-tree Agent-RAG architecture from the paper
- build a research prototype or engineering baseline
- validate the methods-as-nodes pipeline on local corpora
- prepare a stable codebase for future LLM, embedding, FAISS, or formal-verifier integration
- multimodal normalization
- context-preserving segmentation
- method and relation extraction
- method deduplication and canonicalization
T_MconstructionT_Cconstruction- repository and tree serialization
- multi-level funnel retrieval
- weighted ancestor backtracking
- strategy operator selection
- candidate innovation synthesis
- heuristic verification
- deterministic rubric scoring and pruning
- write-back of retained candidates
- propose new research questions from graph gaps
- run multiple evolution rounds
- persist loop history
Input Documents
-> Multimodal Parser
-> Context-Preserving Segmenter
-> Method Extractor + Relation Extractor
-> Method Repository
-> T_M
-> T_C
User Query
-> Funnel Retrieval on T_C
-> Weighted Ancestor Backtracking on T_M
-> Strategy Agent
-> Candidate Synthesizer
-> Verifier
-> Scorer
-> Pruning
-> Write-back
-> Final Answer + Trace + Evidence
- Python 3.11+
- a virtual environment is recommended
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .The demo can still run with fallbacks even if some optional packages are unavailable.
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/demo.yaml demoPYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml build-index data/demo_docs/provenance_methods.txt data/demo_docs/strategy_methods.txt data/demo_docs/verification_notes.jsonPYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml query "How can we synthesize an explainable innovation pipeline for low-resource scientific corpora?"PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml inspect-tree tm
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml inspect-tree tcPYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml evolve --iterations 2Purpose: run the offline construction pipeline and persist the repository, T_M, and T_C.
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml build-index <doc1> <doc2> ...Supported inputs:
.txt.md.json.pdf
Outputs:
artifacts/.../repository.jsonartifacts/.../t_m.jsonartifacts/.../t_c.json
Purpose: load the built artifacts and execute the full online inference loop.
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml query "your query"Disable write-back:
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml query "your query" --no-write-backReturned fields include:
final_answerinnovation_summaryderivation_chainevidencescorestrace
Purpose: return a JSON-friendly view of either tree for visualization or debugging.
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml inspect-tree tm
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml inspect-tree tcPurpose: propose new research questions from the current graph and run multiple innovation rounds.
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml evolve --iterations 3Purpose: run build + query + write-back in one pass using the bundled demo data.
PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/demo.yaml demoMultimodalParser converts inputs into the shared Document schema. Current support includes:
- text files
- Markdown files
- structured JSON documents
- PDF text extraction
ContextPreservingSegmenter does not use blind fixed windows. Instead:
- if the document length
<= L0, keep it as one segment - if the document length
> L0, split by headings when possible - if sections are still too long, regroup by paragraphs
HeuristicMethodExtractor uses deterministic rules to:
- detect candidate method names
- separate prior methods from the derived method
- produce summaries and keywords for each method node
HeuristicRelationExtractor scores relations with cue words and maps them into continuous weights:
w_ij = (r_ij - 1) / 4
Inside MethodRepository, each method is embedded and compared with cosine similarity:
sim(m_a, m_b) = cosine(v(m_a), v(m_b))
If similarity exceeds the merge threshold, the nodes are merged while retaining:
- aliases
- source documents
- source segments
- provenance notes
- incident edges
MethodProvenanceTree:
- selects one primary parent per target method
- keeps supporting edges
- prevents cycles in the primary backbone
ClusteringAbstractionTree:
- recursively clusters method embeddings
- decreases cluster counts by layer according to the paper schedule
- generates a summary per cluster
- allows multiple top-level root clusters
FunnelRetriever performs top-down selection with the budget schedule:
k_t = max(1, ceil(k_1 * eta^(t-1)))
WeightedAncestorBacktracker uses cumulative influence:
I_d(m) = product(w_l(m) + eps)
Ancestors are included if:
I_d(m) >= taud <= m_max
StrategyAgent chooses one operator from:
deductioninductionanalogyabduction
Then HeuristicSynthesizer produces candidates with:
- name
- summary
- parent methods
- parent contribution weights
- novelty statement
- applicability boundaries
- validation plan
HeuristicVerifier checks:
- duplicate names
- missing parents
- contribution normalization
- summary and validation-plan completeness
HybridDeterministicScorer produces five rubric dimensions:
- Novelty
- Consistency / Explainability
- Verifiability
- Applicability
- Goal Alignment
WriteBackManager materializes retained candidates as new method nodes, creates parent edges, and rebuilds T_M and T_C.
Config files:
Important fields:
paths.artifact_dir: output directorypaths.repository_file: serialized repository pathpaths.provenance_tree_file: serializedT_Mpathpaths.abstraction_tree_file: serializedT_Cpathproviders.embedder.type:auto/hash/sentence-transformerproviders.embedder.dimension: hash embedding dimensioningestion.segment_length_threshold:L0ingestion.max_segment_length: upper bound for chunked sectionsrepository.merge_threshold: merge threshold for canonicalizationtrees.abstraction_depth: tree depth forT_Ctrees.k1: initial number of clusterstrees.k_min: lower bound of cluster countretrieval.top_k_start: initial funnel budgetretrieval.eta: budget decay factorretrieval.backtracking_tau: influence thresholdretrieval.backtracking_max_depth: max backtracking depthscoring.threshold: pruning thresholdstrategy.candidate_count: number of synthesized candidatesevolution.max_iterations: maximum autonomous rounds
This section covers the human-maintained and runtime-relevant files. Auto-generated cache directories are intentionally excluded.
- README.md
- bilingual project guide and usage manual.
- requirements.txt
- dependency list, including optional enhancement packages.
- pyproject.toml
- package metadata, script entrypoint, optional extras.
- .gitignore
- ignore rules for virtualenvs, caches, build outputs, and artifacts.
- configs/default.yaml
- default runtime configuration.
- configs/demo.yaml
- low-friction demo configuration with hash embeddings.
- data/demo_docs/provenance_methods.txt
- sample text about provenance, retrieval, and backtracking.
- data/demo_docs/strategy_methods.txt
- sample text about strategy, repository, and write-back.
- data/demo_docs/verification_notes.json
- structured demo data for verification, scoring, clustering, and evolution.
- src/agent_rag/init.py
- package-level export of
InnovationEngine.
- package-level export of
- src/agent_rag/schemas.py
- all core dataclasses such as
Document,MethodNode,MethodEdge,ClusterNode,InnovationCandidate, andQueryResult.
- all core dataclasses such as
- src/agent_rag/config.py
- config dataclasses and config loading logic.
- src/agent_rag/utils/init.py
- package init file.
- src/agent_rag/utils/logging_utils.py
- logger configuration helper.
- src/agent_rag/utils/text_utils.py
- whitespace normalization, sentence splitting, keyword extraction, heading detection, stable ids.
- src/agent_rag/utils/math_utils.py
- weight mapping, cosine similarity, normalization, mean vectors, cumulative influence.
- src/agent_rag/providers/init.py
- package init file.
- src/agent_rag/providers/llm_base.py
- abstract LLM provider interface.
- src/agent_rag/providers/llm_stub.py
- deterministic local fallback LLM.
- src/agent_rag/providers/embedder_base.py
- abstract embedding provider interface.
- src/agent_rag/providers/local_embedder.py
- hash embedder, sentence-transformer wrapper, and provider builder.
- src/agent_rag/ingestion/init.py
- package init file.
- src/agent_rag/ingestion/multimodal_parser.py
- normalizes
.txt,.md,.json, and.pdfintoDocumentobjects.
- normalizes
- src/agent_rag/ingestion/segmenter.py
- heading-aware and paragraph-aware segmentation logic.
- src/agent_rag/extraction/init.py
- package init file.
- src/agent_rag/extraction/method_extractor.py
- method candidate detection, prior/derived separation, method-node construction.
- src/agent_rag/extraction/relation_extractor.py
- relation scoring and edge creation.
- src/agent_rag/repository/init.py
- package init file.
- src/agent_rag/repository/method_repository.py
- canonical method store, deduplication, alias tracking, edge normalization, serialization.
- src/agent_rag/repository/provenance_graph.py
- graph view over repository methods and edges.
- src/agent_rag/trees/init.py
- package init file.
- src/agent_rag/trees/provenance_tree.py
- implementation of
T_M.
- implementation of
- src/agent_rag/trees/abstraction_tree.py
- implementation of
T_C.
- implementation of
- src/agent_rag/trees/clustering.py
- MiniBatchKMeans adapter with sklearn-first and pure-Python fallback behavior.
- src/agent_rag/trees/summarizer.py
- cluster summary generation.
- src/agent_rag/retrieval/init.py
- package init file.
- src/agent_rag/retrieval/funnel_retriever.py
- top-down funnel retrieval over
T_C.
- top-down funnel retrieval over
- src/agent_rag/retrieval/backtracking.py
- weighted ancestor backtracking over
T_M.
- weighted ancestor backtracking over
- src/agent_rag/strategy/init.py
- package init file.
- src/agent_rag/strategy/operators.py
- operator library with deduction, induction, analogy, and abduction.
- src/agent_rag/strategy/strategy_agent.py
- operator selection logic.
- src/agent_rag/strategy/synthesizer.py
- candidate synthesis, parent contributions, novelty and validation text generation.
- src/agent_rag/verification/init.py
- package init file.
- src/agent_rag/verification/verifier_base.py
- abstract verifier interface.
- src/agent_rag/verification/heuristic_verifier.py
- heuristic consistency checker.
- src/agent_rag/verification/formal_stub.py
- placeholder formal-verifier adapter.
- src/agent_rag/scoring/init.py
- package init file.
- src/agent_rag/scoring/scorer.py
- deterministic rubric scoring and pruning.
- src/agent_rag/evolution/init.py
- package init file.
- src/agent_rag/evolution/writeback.py
- materializes retained innovations and adds edges.
- src/agent_rag/evolution/autonomous_loop.py
- autonomous research-question proposal and iterative execution.
- src/agent_rag/engine/init.py
- package init file.
- src/agent_rag/engine/innovation_engine.py
- top-level orchestrator for build, query, evolve, save/load, and demo.
- src/agent_rag/cli/init.py
- package init file.
- src/agent_rag/cli/main.py
- CLI parser and command dispatcher.
- tests/init.py
- injects
srcinto the test path.
- injects
- tests/test_segmentation.py
- tests heading-aware segmentation.
- tests/test_dedup.py
- tests deduplication and merging.
- tests/test_tree_build.py
- tests primary-parent selection and abstraction-tree build.
- tests/test_retrieval.py
- tests funnel retrieval.
- tests/test_backtracking.py
- tests weighted ancestor backtracking.
- tests/test_scoring.py
- tests weight mapping and pruning.
- tests/test_end_to_end.py
- tests the end-to-end pipeline.
artifacts/demo/repository.json- serialized demo repository.
artifacts/demo/t_m.json- serialized demo provenance tree.
artifacts/demo/t_c.json- serialized demo abstraction tree.
Code:
Formula:
w_ij = (r_ij - 1) / 4
Code:
Formula:
w_tilde_ij = w_ij / (sum_k w_kj + eps)
Code:
Formula:
k_t = max(1, ceil(k_1 * eta^(t-1)))
Code:
Formula:
I_d(m) = product_{l=1..d}(w_l(m) + eps)
Code:
Formula:
d_i = d_min + floor(d_range * (w_tilde_i)^gamma)
query and demo return JSON with:
final_answer: concise user-facing answerinnovation_summary: compact summary for each candidatederivation_chain: parent chains per candidateevidence: verification evidence and score notesscores: rubric breakdownstrace.selected_clusters: selected clusters by leveltrace.retrieved_leaf_methods: retrieved leaf methodstrace.backtracked_ancestors: backtracking tracetrace.chosen_operator: selected reasoning operatortrace.candidate_scores: verification + score detailstrace.kept_candidates: retained candidatestrace.dropped_candidates: pruned candidates
Run the test suite:
PYTHONPATH=src python3 -m unittest discover -s tests -vCurrent coverage includes:
- segmentation
- weight mapping
- deduplication
- primary parent selection
- abstraction tree construction
- funnel retrieval
- weighted ancestor backtracking
- pruning threshold behavior
- end-to-end execution
Yes. It falls back to HashingEmbedder.
Yes. It falls back to the pure-Python MiniBatchKMeansAdapter.
The config files are JSON-compatible YAML, so the loader can fall back to json parsing.
The parser tries, in order:
pypdfpdftotext- raw binary-text fallback
For scanned PDFs, OCR is still recommended.
This codebase intentionally uses deterministic local fallbacks to preserve the architecture and execution loop, not to replicate closed-model performance.
This repository uses explicit engineering approximations:
- heuristic method extraction instead of closed-weight LLM IE
- heuristic cluster summaries when no LLM provider is connected
- heuristic verification instead of a full formal prover
- full tree rebuild after write-back for correctness and simplicity
These choices keep the repository:
- runnable offline
- structurally faithful to the paper
- easy to extend later
If you want to extend the project, the best next upgrades are:
- replace
HeuristicMethodExtractorwith an actual LLM-based extraction provider - replace
StubLLMProviderwith OpenAI, Gemini, DeepSeek, or a local vLLM backend - add FAISS or ANN retrieval paths inside the repository layer
- add incremental updates for
T_C - integrate a real formal verifier
- add a dedicated visualization frontend
Back to top: Top