Skip to content

About

This is the code for the paper "Explainable Innovation Engine: Dual-Tree Agent-RAG with Methods-as-Nodes and Verifiable Write-Back"

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Explainable Innovation Engine: Dual-Tree Agent-RAG

Language / 语言切换: 中文 | English


中文说明

1. 项目概述

本项目是论文 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):表示方法在不同抽象层的聚类结构

在线推理时,系统执行以下闭环:

  1. 在 T_C 上做分层漏斗检索 Funnel Retrieval
  2. 在 T_M 上做加权祖先回溯 Weighted Ancestor Backtracking
  3. 由 Strategy Agent 选择推理算子并合成候选创新
  4. 由 Verifier + Scorer 验证、评分、剪枝
  5. 将保留的创新节点执行 Write-back 写回知识库

本实现优先保证:

  • 本地可运行
  • 结构完整
  • 模块可扩展
  • 无需付费 API 也能跑通 demo

2. 项目目标

该仓库用于以下场景:

  • 复现论文中的 Agent-RAG 双树架构
  • 搭建研究原型或工程基线
  • 在本地小规模语料上验证方法抽取、聚类、检索、创新生成流程
  • 为未来接入真实 LLM、真实 embedding 模型、FAISS、形式化验证器提供稳定接口

3. 核心能力

3.1 离线构建能力

  • 多模态文档统一化解析
  • 上下文保留式分段
  • 方法抽取与关系抽取
  • 方法去重与 canonicalization
  • 构建 T_M
  • 构建 T_C
  • repository / tree 序列化保存

3.2 在线推理能力

  • 多层 Funnel Retrieval
  • Weighted Ancestor Backtracking
  • Strategy Agent 算子选择
  • 候选创新合成
  • Heuristic Verifier 验证
  • Hybrid Deterministic Scorer 评分与剪枝
  • 保留创新写回知识图结构

3.3 演化能力

  • 自动提出研究问题
  • 运行若干轮自主演化
  • 持久化演化历史日志

4. 系统架构总览

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

5. 快速开始

5.1 环境要求

  • Python 3.11+
  • 推荐使用虚拟环境

5.2 安装方式

完整安装:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

如果不安装依赖,demo 仍然可以依靠 fallback 运行,但建议至少安装 requirements.txt。

5.3 一条命令跑 demo

PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/demo.yaml demo

5.4 构建索引

PYTHONPATH=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.json

5.5 运行查询

PYTHONPATH=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?"

5.6 查看树结构

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

5.7 运行自主演化

PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml evolve --iterations 2

6. 命令行使用手册

6.1 build-index

作用:对输入文档执行离线构建,产出 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.json
  • artifacts/.../t_m.json
  • artifacts/.../t_c.json

6.2 query

作用:加载已构建索引,执行完整在线推理流程。

命令:

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

6.3 inspect-tree

作用:导出树结构的 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

6.4 evolve

作用:从当前 repository 中自动提出研究问题并执行多轮创新演化。

命令:

PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml evolve --iterations 3

输出:

  • 每轮 query
  • 保留候选
  • 丢弃候选
  • 演化日志 JSON

6.5 demo

作用:从 demo 文档出发,完整执行 build + query + write-back。

命令:

PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/demo.yaml demo

7. 运行流程详解

7.1 输入阶段

输入文档通过 MultimodalParser 被转换为统一 Document schema。当前支持:

  • 文本文件
  • Markdown 文本
  • JSON 结构化文档
  • PDF 文本提取

7.2 分段阶段

ContextPreservingSegmenter 不是按固定窗口切段,而是:

  • 若全文长度 <= L0,整篇保留为一个 segment
  • 若全文长度 > L0,尝试根据标题边界切分
  • 若仍然过长,则按段落组装出多个 chunk

7.3 方法抽取阶段

HeuristicMethodExtractor 使用确定性规则:

  • 从标题和句子中识别方法名称候选
  • 区分 prior methods 和 derived method
  • 为每个方法生成 summary 与 keywords

7.4 关系抽取阶段

HeuristicRelationExtractor 根据 cue words 给边打离散分:

  • 强关系:5
  • 中关系:4
  • 弱关系:3
  • 默认相关:2

并映射为连续权重:

w_ij = (r_ij - 1) / 4

7.5 去重与规范化阶段

MethodRepository 中每个方法会被 embedding,随后执行相似度比较:

sim(m_a, m_b) = cosine(v(m_a), v(m_b))

若超过 merge_threshold,则合并为 canonical method node,并保留:

  • aliases
  • 来源段落
  • 来源文档
  • provenance note
  • incident edges

7.6 构建 T_M

MethodProvenanceTree 负责:

  • 为每个 target method 选择 primary parent
  • 保留 supporting edges
  • 防止 primary backbone 出现环

7.7 构建 T_C

ClusteringAbstractionTree 负责:

  • 对 method embeddings 做递归聚类
  • 每层 cluster 数按论文公式递减
  • 为每个 cluster 生成 summary
  • 支持多 root cluster

7.8 在线检索

FunnelRetriever 逐层从上到下做 cluster 选择:

k_t = max(1, ceil(k_1 * eta^(t-1)))

输出:

  • selected clusters
  • retrieved leaf methods

7.9 加权祖先回溯

WeightedAncestorBacktracker 使用累积影响值:

I_d(m) = product(w_l(m) + eps)

满足:

  • I_d(m) >= tau
  • d <= m_max

则将祖先加入上下文集合。

7.10 策略生成

StrategyAgent 从四个算子中选一个:

  • deduction
  • induction
  • analogy
  • abduction

随后 HeuristicSynthesizer 生成多个创新候选,每个候选包含:

  • 名称
  • 摘要
  • 父方法
  • 父贡献权重
  • 创新解释
  • 适用边界
  • 验证计划

7.11 验证与评分

HeuristicVerifier 检查:

  • 是否重复命名
  • parent 是否存在
  • contribution 是否归一化
  • summary / validation plan 是否足够完整

HybridDeterministicScorer 输出五维 rubric:

  • Novelty
  • Consistency / Explainability
  • Verifiability
  • Applicability
  • Goal Alignment

7.12 写回

WriteBackManager 将保留候选变为新的 MethodNode,并创建 parent edges,随后重新构建 T_M 和 T_C。

8. 配置手册

8.1 配置文件

当前配置文件实际使用的是 JSON-compatible YAML,因此即使没有 PyYAML 也能用内置 json 回退解析。

8.2 关键参数说明

  • 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-transformer
  • providers.embedder.dimension: hash embedding 维度
  • ingestion.segment_length_threshold: L0
  • ingestion.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: 自主演化最大轮数

9. 文件级详细说明

下面只列出需要人工维护或核心运行时相关的文件。__pycache__ 等自动生成目录不纳入维护说明。

9.1 根目录文件

  • README.md
    • 项目总说明与双语手册。
  • requirements.txt
    • 依赖清单,包含可选增强依赖,如 sentence-transformers、pypdf、scikit-learn。
  • pyproject.toml
    • 打包配置、脚本入口、可选依赖定义。
  • .gitignore
    • 忽略虚拟环境、缓存、构建产物、artifacts。

9.2 配置文件

9.3 示例数据文件

9.4 包入口与全局 schema

9.5 utils/

9.6 providers/

9.7 ingestion/

9.8 extraction/

9.9 repository/

9.10 trees/

9.11 retrieval/

9.12 strategy/

9.13 verification/

9.14 scoring/

9.15 evolution/

9.16 engine/

9.17 cli/

9.18 测试文件

9.19 运行时生成文件

  • artifacts/demo/repository.json
    • demo 运行后生成的方法仓库。
  • artifacts/demo/t_m.json
    • demo 运行后生成的 T_M。
  • artifacts/demo/t_c.json
    • demo 运行后生成的 T_C。

这些文件不是源码,但它们是 inspect/debug/visualization 的重要输入。

10. 论文公式与代码映射

10.1 边权映射

代码位置:

公式:

w_ij = (r_ij - 1) / 4

10.2 归一化权重

代码位置:

公式:

w_tilde_ij = w_ij / (sum_k w_kj + eps)

10.3 Funnel Retrieval 预算衰减

代码位置:

公式:

k_t = max(1, ceil(k_1 * eta^(t-1)))

10.4 Weighted Ancestor Backtracking

代码位置:

公式:

I_d(m) = product_{l=1..d}(w_l(m) + eps)

10.5 Contribution-driven ancestor depth

代码位置:

公式:

d_i = d_min + floor(d_range * (w_tilde_i)^gamma)

11. 输出结果说明

query 和 demo 的 JSON 输出字段:

  • final_answer: 给用户的摘要回答
  • innovation_summary: 每个候选创新的简表
  • derivation_chain: 候选对应的父方法链
  • evidence: 验证证据与评分说明
  • scores: rubric 分数明细
  • trace.selected_clusters: 每层选中的 cluster
  • trace.retrieved_leaf_methods: 检索到的叶子方法
  • trace.backtracked_ancestors: 加权祖先回溯轨迹
  • trace.chosen_operator: 策略算子
  • trace.candidate_scores: 候选的评分与验证结果
  • trace.kept_candidates: 保留的候选
  • trace.dropped_candidates: 剪掉的候选

12. 测试与验证

运行测试:

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

13. 常见问题

13.1 没有安装 sentence-transformers 能不能跑?

可以。系统会自动回退到 HashingEmbedder。

13.2 没有安装 scikit-learn 能不能跑?

可以。系统会回退到纯 Python 版 MiniBatchKMeansAdapter。

13.3 yaml 没装会不会报错?

不会。配置文件是 JSON-compatible YAML,加载器会自动尝试用 json 回退解析。

13.4 PDF 解析失败怎么办?

系统会依次尝试:

  • pypdf
  • pdftotext
  • 二进制文本回退

如果 PDF 是扫描版,建议先 OCR。

13.5 为什么生成结果和论文展示不同?

这是工程化 fallback 版本,重点是保留论文结构与执行闭环,而不是复刻封闭模型效果。

14. Paper-to-Code Approximation

本项目明确使用了若干工程近似:

  • 方法抽取采用启发式规则,不依赖外部 LLM IE
  • cluster summary 默认采用 heuristic summarizer
  • verifier 默认不是形式化证明器
  • write-back 默认采用 full rebuild 保证结构一致性

这些近似是为了保证:

  • 可以离线运行
  • 模块边界清晰
  • 未来可替换为更强组件

15. 开发建议

如果你准备继续扩展这个项目,建议优先做以下几件事:

  1. 将 HeuristicMethodExtractor 替换成真实 LLM IE provider
  2. 将 StubLLMProvider 替换为 OpenAI / Gemini / DeepSeek / local vLLM provider
  3. 在 repository 中增加 ANN / FAISS 检索路径
  4. 对 T_C 引入更稳定的增量更新策略
  5. 接入真实形式化验证器
  6. 增加更丰富的可视化层

返回顶部:Top


English Guide

1. Overview

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:

  1. hierarchical funnel retrieval on T_C
  2. weighted ancestor backtracking on T_M
  3. strategy-agent operator selection and innovation synthesis
  4. verification, scoring, and pruning
  5. write-back of retained innovations

The implementation prioritizes:

  • local runnability
  • architectural completeness
  • clear modularity
  • no mandatory paid API dependency

2. What the Project Is For

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

3. Main Capabilities

3.1 Offline construction

  • multimodal normalization
  • context-preserving segmentation
  • method and relation extraction
  • method deduplication and canonicalization
  • T_M construction
  • T_C construction
  • repository and tree serialization

3.2 Online inference

  • 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

3.3 Autonomous evolution

  • propose new research questions from graph gaps
  • run multiple evolution rounds
  • persist loop history

4. Architecture at a Glance

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

5. Quick Start

5.1 Requirements

  • Python 3.11+
  • a virtual environment is recommended

5.2 Installation

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.

5.3 Run the demo in one command

PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/demo.yaml demo

5.4 Build an index

PYTHONPATH=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.json

5.5 Run a query

PYTHONPATH=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?"

5.6 Inspect the trees

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

5.7 Run autonomous evolution

PYTHONPATH=src python3 -m agent_rag.cli.main --config configs/default.yaml evolve --iterations 2

6. CLI Manual

6.1 build-index

Purpose: 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.json
  • artifacts/.../t_m.json
  • artifacts/.../t_c.json

6.2 query

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-back

Returned fields include:

  • final_answer
  • innovation_summary
  • derivation_chain
  • evidence
  • scores
  • trace

6.3 inspect-tree

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 tc

6.4 evolve

Purpose: 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 3

6.5 demo

Purpose: 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 demo

7. Pipeline Walkthrough

7.1 Input normalization

MultimodalParser converts inputs into the shared Document schema. Current support includes:

  • text files
  • Markdown files
  • structured JSON documents
  • PDF text extraction

7.2 Segmentation

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

7.3 Method extraction

HeuristicMethodExtractor uses deterministic rules to:

  • detect candidate method names
  • separate prior methods from the derived method
  • produce summaries and keywords for each method node

7.4 Relation extraction

HeuristicRelationExtractor scores relations with cue words and maps them into continuous weights:

w_ij = (r_ij - 1) / 4

7.5 Deduplication and canonicalization

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

7.6 Building T_M

MethodProvenanceTree:

  • selects one primary parent per target method
  • keeps supporting edges
  • prevents cycles in the primary backbone

7.7 Building T_C

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

7.8 Funnel retrieval

FunnelRetriever performs top-down selection with the budget schedule:

k_t = max(1, ceil(k_1 * eta^(t-1)))

7.9 Weighted ancestor backtracking

WeightedAncestorBacktracker uses cumulative influence:

I_d(m) = product(w_l(m) + eps)

Ancestors are included if:

  • I_d(m) >= tau
  • d <= m_max

7.10 Strategy synthesis

StrategyAgent chooses one operator from:

  • deduction
  • induction
  • analogy
  • abduction

Then HeuristicSynthesizer produces candidates with:

  • name
  • summary
  • parent methods
  • parent contribution weights
  • novelty statement
  • applicability boundaries
  • validation plan

7.11 Verification and scoring

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

7.12 Write-back

WriteBackManager materializes retained candidates as new method nodes, creates parent edges, and rebuilds T_M and T_C.

8. Configuration Manual

Config files:

Important fields:

  • paths.artifact_dir: output directory
  • paths.repository_file: serialized repository path
  • paths.provenance_tree_file: serialized T_M path
  • paths.abstraction_tree_file: serialized T_C path
  • providers.embedder.type: auto / hash / sentence-transformer
  • providers.embedder.dimension: hash embedding dimension
  • ingestion.segment_length_threshold: L0
  • ingestion.max_segment_length: upper bound for chunked sections
  • repository.merge_threshold: merge threshold for canonicalization
  • trees.abstraction_depth: tree depth for T_C
  • trees.k1: initial number of clusters
  • trees.k_min: lower bound of cluster count
  • retrieval.top_k_start: initial funnel budget
  • retrieval.eta: budget decay factor
  • retrieval.backtracking_tau: influence threshold
  • retrieval.backtracking_max_depth: max backtracking depth
  • scoring.threshold: pruning threshold
  • strategy.candidate_count: number of synthesized candidates
  • evolution.max_iterations: maximum autonomous rounds

9. File-by-File Reference

This section covers the human-maintained and runtime-relevant files. Auto-generated cache directories are intentionally excluded.

9.1 Root files

  • 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.

9.2 Config files

9.3 Demo data files

9.4 Package entry and shared schema files

9.5 utils/

9.6 providers/

9.7 ingestion/

9.8 extraction/

9.9 repository/

9.10 trees/

9.11 retrieval/

9.12 strategy/

9.13 verification/

9.14 scoring/

9.15 evolution/

9.16 engine/

9.17 cli/

9.18 Test files

9.19 Runtime-generated files

  • 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.

10. Formula-to-Code Mapping

10.1 Edge weight mapping

Code:

Formula:

w_ij = (r_ij - 1) / 4

10.2 Normalized weights

Code:

Formula:

w_tilde_ij = w_ij / (sum_k w_kj + eps)

10.3 Funnel budget schedule

Code:

Formula:

k_t = max(1, ceil(k_1 * eta^(t-1)))

10.4 Weighted ancestor backtracking

Code:

Formula:

I_d(m) = product_{l=1..d}(w_l(m) + eps)

10.5 Contribution-driven ancestor depth

Code:

Formula:

d_i = d_min + floor(d_range * (w_tilde_i)^gamma)

11. Output Schema Explanation

query and demo return JSON with:

  • final_answer: concise user-facing answer
  • innovation_summary: compact summary for each candidate
  • derivation_chain: parent chains per candidate
  • evidence: verification evidence and score notes
  • scores: rubric breakdowns
  • trace.selected_clusters: selected clusters by level
  • trace.retrieved_leaf_methods: retrieved leaf methods
  • trace.backtracked_ancestors: backtracking trace
  • trace.chosen_operator: selected reasoning operator
  • trace.candidate_scores: verification + score details
  • trace.kept_candidates: retained candidates
  • trace.dropped_candidates: pruned candidates

12. Tests

Run the test suite:

PYTHONPATH=src python3 -m unittest discover -s tests -v

Current coverage includes:

  • segmentation
  • weight mapping
  • deduplication
  • primary parent selection
  • abstraction tree construction
  • funnel retrieval
  • weighted ancestor backtracking
  • pruning threshold behavior
  • end-to-end execution

13. FAQ

13.1 Can the project run without sentence-transformers?

Yes. It falls back to HashingEmbedder.

13.2 Can it run without scikit-learn?

Yes. It falls back to the pure-Python MiniBatchKMeansAdapter.

13.3 What if yaml is not installed?

The config files are JSON-compatible YAML, so the loader can fall back to json parsing.

13.4 What if PDF parsing fails?

The parser tries, in order:

  • pypdf
  • pdftotext
  • raw binary-text fallback

For scanned PDFs, OCR is still recommended.

13.5 Why are the generated results not identical to a paper demo?

This codebase intentionally uses deterministic local fallbacks to preserve the architecture and execution loop, not to replicate closed-model performance.

14. Paper-to-Code Approximation

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

15. Suggested Next Steps

If you want to extend the project, the best next upgrades are:

  1. replace HeuristicMethodExtractor with an actual LLM-based extraction provider
  2. replace StubLLMProvider with OpenAI, Gemini, DeepSeek, or a local vLLM backend
  3. add FAISS or ANN retrieval paths inside the repository layer
  4. add incremental updates for T_C
  5. integrate a real formal verifier
  6. add a dedicated visualization frontend

Back to top: Top

About

This is the code for the paper "Explainable Innovation Engine: Dual-Tree Agent-RAG with Methods-as-Nodes and Verifiable Write-Back"

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages