fewshot-guided

A modular retrieval-augmented pipeline for materials property prediction from tabular data. It builds prompts from similar training samples, calls an LLM for predictions, and saves structured results for analysis.

English | 中文说明

Table of Contents

• Features
• Project Structure
• Setup (Deployment)
• Usage
• Customization
• 中文说明

Features

• Modular RAG pipeline with data processing, retrieval, prompting, calling, parsing, and saving stages.
• Provider abstraction for multiple LLM backends (Ricardo, DeepSeek, Gemini, TheAPI, LemonAPI).
• Configurable prompt templates and target properties.
• Local embedding support (Sentence-Transformers) with TF-IDF fallback.
• Reproducible outputs saved to disk (inputs, outputs, metrics, configs).

Project Structure

• core_modules/: Pipeline implementation.
• datasets/: Example datasets (CSV).
• prompt_templates/: JSON prompt templates.
• EmbeddingModel/: Local embedding models (optional).
• output/: Generated runs and artifacts.

Setup (Deployment)

1) Create a Python environment

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1

2) Install dependencies

pip install pandas numpy scikit-learn sentence-transformers litellm python-dotenv

Notes:

• At least one embedding backend is required: sentence-transformers (preferred) or scikit-learn (TF-IDF fallback).
• If you plan to download embedding models, you may also need transformers and huggingface-hub.

3) Configure LLM credentials

Create or edit .env:

LLM_PROVIDER=gemini
LLM_MODEL=gemini-2.5-flash
GEMINI_API_KEY=your_api_key_here

See docs/llm_config.md for provider-specific options and model lists.

4) (Optional) Download local embedding models

python EmbeddingModel/download_bert_models.py

Usage

Run the default pipeline:

python run_refactored.py

Outputs are written to output/<run_name>/, including:

• config.json, train_set.csv, test_set.csv
• predictions.csv, prediction_details.json
• inputs/ (prompts) and outputs/ (raw model responses)

Customization

• Update run_refactored.py to change input data, target columns, templates, or output folder.
• Or build a config with core_modules.config.create_default_config and pass it to RAGPipeline.
• Shared template modes are registered in core_modules.pipeline.shared_batch_profiles; the built-in modes are with_analysis, lite_analysis, and no_analysis.

Paper Package

To build the Ti/Kilig prompt-condition comparison package used for paper drafting:

python scripts/build_ti_kilig_prompt_paper_package.py

This creates a standalone workspace at paper_from_data/ti_kilig_prompt_tradeoff_study/ with:

• input/raw/ti_kilig_prompt_metrics_primary.csv
• input/spec/data_spec.md
• processed comparison tables under data/processed/
• paper-ready figures under figures/
• result notes under manuscript/ and validation notes under qa/

---

中文说明

这是一个用于材料属性预测的模块化检索增强流程（RAG）。系统从训练样本中检索相似记录，构建提示词并调用大模型生成预测结果，随后将结果结构化保存，便于分析。

目录

• 功能特点
• 项目结构
• 部署与环境配置
• 使用方法
• 自定义

功能特点

• 模块化流水线：数据处理、检索、提示构建、模型调用、解析与保存。
• 支持多种 LLM 提供方（Ricardo、DeepSeek、Gemini）。
• 支持配置化提示模板与目标属性。
• 本地向量检索（Sentence-Transformers），并提供 TF-IDF 兜底方案。
• 输出可复现，结果与配置均保存到磁盘。

项目结构

• core_modules/: 主要流程实现。
• datasets/: 示例数据集（CSV）。
• prompt_templates/: 提示模板（JSON）。
• EmbeddingModel/: 本地向量模型（可选）。
• output/: 运行结果输出目录。

部署与环境配置

1) 创建 Python 环境

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1

2) 安装依赖

pip install pandas numpy scikit-learn sentence-transformers litellm python-dotenv

说明：

• 至少需要一种向量检索后端：sentence-transformers（推荐）或 scikit-learn（TF-IDF 兜底）。
• 如需下载嵌入模型，可能还需安装 transformers 与 huggingface-hub。

3) 配置 LLM 凭证

在 .env 中设置：

LLM_PROVIDER=gemini
LLM_MODEL=gemini-2.5-flash
GEMINI_API_KEY=your_api_key_here

更多配置见 docs/llm_config.md。

4) （可选）下载本地向量模型

python EmbeddingModel/download_bert_models.py

使用方法

运行默认流程：

python run_refactored.py

输出位于 output/<run_name>/，包括：

• config.json、train_set.csv、test_set.csv
• predictions.csv、prediction_details.json
• inputs/（提示词）与 outputs/（模型原始回复）

自定义

• 直接修改 run_refactored.py（输入数据、目标列、模板、输出路径）。
• 或使用 core_modules.config.create_default_config 构建配置并传入 RAGPipeline。
• 共享模板模式统一注册在 core_modules.pipeline.shared_batch_profiles，内置模式包括 with_analysis、lite_analysis 和 no_analysis。

论文数据包

如需生成 Ti/Kilig 三种 prompt condition 的论文比较数据包，可运行：

python scripts/build_ti_kilig_prompt_paper_package.py

脚本会在 paper_from_data/ti_kilig_prompt_tradeoff_study/ 下生成独立工作区，包含：

• input/raw/ti_kilig_prompt_metrics_primary.csv
• input/spec/data_spec.md
• data/processed/ 中的整理后数据表
• figures/ 中的论文图表
• manuscript/ 中的结果摘要和 qa/ 中的验证报告