Skip to content

conanxin/explainlens

BranchesTags

Repository files navigation

ExplainLens

Turn papers and complex texts into visual explainer cards and cartoon storyboards.

中文名：图解复杂内容的 AI 教学导演

Python License Status CI

当前版本: v0.3.0-alpha (development) 重要说明：默认不调用外部 AI API，不生成真实图片。 系统使用启发式规则提取概念、生成 SVG 占位图和 image prompts。 OpenAI provider 为 experimental 状态，需显式 opt-in（--allow-external-api + OPENAI_API_KEY）。 详见 v0.3.0-alpha Release Notes。

简介

ExplainLens 是一个开源工具，它像一位 AI 教学导演，能够：

  1. 解析论文、长文、技术文档等复杂内容
  2. 自动提取核心概念和关键论点
  3. 生成符合人类认知顺序的教学路径
  4. 为每个概念匹配生动的卡通视觉隐喻
  5. 生成图片提示词（可后续接入图像生成 API）
  6. 输出可视化 HTML 卡片预览

核心体验：复杂内容 → 8 张图解卡片

每张卡片包含：标题、简明解释、视觉隐喻、卡通画面描述、图片 prompt、takeaway、原文来源片段。

Demo Preview

ExplainLens demo preview

Run outputs/sample_run/cards.html to see 8 visual explainer cards in your browser. See docs/DEMO.md for the full demo guide.

See docs/GALLERY.md for the visual export gallery.

Demo

See docs/DEMO.md.

功能特性

  • 📖 文本解析 — 支持 .txt、.md 和 .pdf（可搜索 PDF）文件
  • 📄 PDF 输入 — Phase 2 支持搜索型 PDF，保留页码信息
  • 🔪 智能分块 — 按段落切分（txt/md）或页感知切分（PDF），保留字符偏移
  • 🔍 关键词分析 — 启发式提取核心问题、概念、方法、证据、局限
  • 🎓 教学路径 — 8 步固定教学计划
  • 🎨 卡通隐喻 — 迷宫、放大镜、侦探板、知识树等 8 种视觉隐喻
  • 🖼️ 图片 Prompt — 生成英文 prompt，适配 Stable Diffusion / DALL-E
  • 📄 多格式导出 — JSON / Markdown / HTML
  • 📎 Clickable Citations — 每个卡片的 source 区域可点击，跳转到页面底部的 Source Appendix
  • 📊 Source Index — source_index.json 记录 chunk/card/page 交叉引用
  • 🔌 Provider Interface — 可插拔分析后端（rule-based + mock-llm + local-fixture + local-http），不调用外部 API
  • 🧩 SVG 占位图 — 无外部 API 依赖，纯本地运行
  • 🌐 Local Web UI — 三栏 Codex 风格本地仪表盘，无需 CLI 命令

Local Web UI

ExplainLens includes a local Web UI (Codex-style 3-column dashboard) for interactive use without CLI commands.

Start the Web UI

python -m explainlens.web --host 127.0.0.1 --port 8765

Then open http://127.0.0.1:8765 in your browser.

Web UI Features

  • Left sidebar: Run history with status indicators
  • Center: New run form (input path, provider, image adapter, style)
  • Right: Live preview pane (cards.html with images)
  • Safety: openai/openai-image blocked by default
  • Chinese UI: Full Chinese localization

See docs/WEB_UI.md for full documentation.

安装

git clone https://github.com/conanxin/explainlens.git
cd explainlens
python -m venv .venv
source .venv/bin/activate   # Linux / macOS
# 或 .venv\Scripts\activate  # Windows
pip install -e ".[dev]"

快速开始

# 运行示例
python -m explainlens.cli analyze \
  --input examples/sample_article.txt \
  --output outputs/sample_run

# 或用安装后的 CLI 命令
explainlens analyze \
  --input examples/sample_article.txt \
  --output outputs/sample_run

然后用浏览器打开 outputs/sample_run/cards.html 预览结果。

ExplainLens 输出 source_index.json 文件，并在 cards.html 中提供可点击的 citations，点击即可跳转到页面底部的 Source Appendix。

快速开始（详细版）

详见 docs/QUICKSTART.md。

PDF 输入

ExplainLens Phase 2 支持从可搜索 PDF 中提取文本：

# 生成示例 PDF
python scripts/create_sample_pdf.py

# 分析 PDF
python -m explainlens.cli analyze \
  --input examples/sample_paper.pdf \
  --output outputs/pdf_demo

限制：

  • 不支持 OCR（扫描版 PDF 不受支持）
  • 目前不深度解析表格、公式和图形
  • 文本提取通过 PyMuPDF 完成，完全本地运行

Providers

ExplainLens supports provider-based analysis via the --provider flag, and a provider listing command:

# List all known providers (available + disabled)
python -m explainlens.cli providers

# Default: rule-based heuristic provider
python -m explainlens.cli analyze --input examples/sample_article.txt --output outputs/sample_run --provider rule-based

# Mock LLM: simulates future LLM output (no API calls)
python -m explainlens.cli analyze --input examples/sample_article.txt --output outputs/mock_run --provider mock-llm

# Local fixture: offline provider protocol test (no model, no HTTP)
python -m explainlens.cli analyze --input examples/sample_article.txt --output outputs/local_fixture_demo --provider local-fixture

# Debug: dump the provider prompt pack for inspection
python -m explainlens.cli analyze --input examples/sample_article.txt --output outputs/local_fixture_debug --provider local-fixture --dump-provider-prompt

# Local HTTP: fixture mode (offline, no HTTP call)
python -m explainlens.cli analyze --input examples/sample_article.txt --output outputs/local_http_fixture --provider local-http --local-http-protocol fixture

# Local HTTP: explicit local HTTP opt-in (requires --allow-local-http)
# python -m explainlens.cli analyze --input examples/sample_article.txt --output outputs/ollama_local --provider local-http --local-http-protocol ollama-chat --local-http-endpoint http://localhost:11434/api/chat --local-http-model llama3.2 --allow-local-http

Provider status:

Provider Status External API API key required
rule-based Available no no
mock-llm Available no no
local-fixture experimental no no
local-http experimental local loopback only no
openai experimental yes yes

All built-in providers run offline by default. The openai provider requires explicit opt-in. See docs/PROVIDERS.md for details.

Local providers

ExplainLens includes local provider diagnostics and endpoint validation:

# Run offline diagnostics (no network calls)
python -m explainlens.cli doctor

# Validate an endpoint (static check, no network)
python -m explainlens.cli validate-endpoint http://localhost:11434/api/chat

Configuration templates:

examples/configs/local-http-ollama.example.json
examples/configs/local-http-lmstudio.example.json
examples/configs/local-http-llamacpp.example.json

See docs/LOCAL_PROVIDERS.md for the full guide.

Image adapters

ExplainLens includes local image adapter scaffolding for generating card illustrations.

# Default: placeholder adapter (generates SVG images locally)
python -m explainlens.cli analyze \
  --input examples/sample_article.txt \
  --output outputs/image_demo \
  --image-adapter placeholder

# List available image adapters
python -m explainlens.cli image-adapters

# Skip image generation entirely
python -m explainlens.cli analyze \
  --input examples/sample_article.txt \
  --output outputs/no_image \
  --skip-images

Current image adapters:

Adapter Status External API API key required
placeholder available no no
fixture experimental no no
openai-image experimental yes yes (opt-in)

Real image generation is experimental — openai-image adapter requires --allow-external-images and OPENAI_API_KEY.

输出文件

运行后，输出目录包含：

文件 说明
source_pages.json 每页文本和偏移（仅 PDF）
source_chunks.json 原文分块结果
source_index.json 来源索引：chunk/page/card 交叉引用
concept_map.json 核心概念提取
teaching_plan.json 8 步教学计划
storyboard.json 卡通分镜脚本
image_prompts.json 图片生成提示词
cards.json 最终卡片数据
cards.md Markdown 格式卡片
cards.html 浏览器可预览的 HTML 卡片
image_jobs.json 图片生成任务列表
image_manifest.json 图片生成清单（含安全声明）
run_summary.json 运行摘要

运行测试

pip install -e ".[dev]"
python -m pytest

项目架构

explainlens/
├── src/explainlens/    # 核心源码
│   ├── parser.py       # 文档解析
│   ├── chunker.py      # 文本分块
│   ├── analyzer.py     # 关键词分析
│   ├── prompts.py      # 提示词模板
│   ├── planner.py      # 教学计划生成
│   ├── storyboard.py   # 卡通分镜生成
│   ├── renderer.py     # HTML 渲染
│   ├── exporters.py    # 多格式导出
│   ├── source_index.py # 来源索引与 citation
│   ├── schemas.py      # 数据模型
│   ├── cli.py          # CLI 入口
│   ├── images/         # 图片适配器接口
│   │   ├── base.py     # 抽象接口
│   │   ├── placeholder.py # 本地 SVG 占位图生成
│   │   ├── fixture.py  # 离线 fixture 适配器（CI/测试）
│   │   ├── registry.py # 图片适配器注册中心
│   │   ├── jobs.py     # image_jobs.json 生成
│   │   └── manifest.py # image_manifest.json 生成
│   └── providers/      # Provider 适配器接口
│       ├── base.py     # 抽象接口
│       ├── contract.py # 能力声明 + 输出校验
│       ├── registry.py # Provider 注册中心
│       ├── rule_based.py # 规则引擎 provider
│       ├── mock_llm.py # Mock LLM provider
│       ├── local_fixture.py # 离线本地 provider 协议测试
│       ├── local_http.py # 本地 HTTP provider (loopback-only)
│       ├── local_http_transport.py # 本地 HTTP 传输层
│       ├── openai_draft.py # OpenAI experimental provider
│       ├── openai_transport.py # OpenAI HTTP transport
│       ├── prompt_contract.py # 结构化 prompt 约定
│       ├── response_contract.py # 结构化 response 约定
│       └── fixture_transport.py # 离线传输层模拟
├── tests/              # 测试
├── examples/           # 示例输入
├── docs/               # 文档
├── scripts/            # 工具脚本
├── .github/            # GitHub Actions CI
└── outputs/            # 输出目录（gitignore）

路线图

详见 ROADMAP.md：

  • Phase 1 ✅ 本地文本 → 解释卡（v0.1.0-alpha）
  • Phase 2 ✅ PDF 解析（searchable PDF text extraction）
  • Phase 3 ✅ Provider 适配器接口（rule-based + mock-llm + local-fixture + local-http + openai）
  • Phase 3.1 ✅ Provider contract hardening
  • Phase 3.2A ✅ Offline local fixture provider protocol
  • Phase 3.2B ✅ Local HTTP provider (loopback-only, fail-closed)
  • Phase 3.2C ✅ Local provider UX polish (doctor, validate-endpoint, config templates)
  • Phase 3.3 ✅ OpenAI provider opt-in (experimental, fail-closed)
  • Phase 3.4 ✅ v0.2.0-alpha release hardening
  • Phase 4A 🔄 Image adapter interface (placeholder + fixture)
  • Phase 4 真实图片生成适配器
  • Phase 5 Web UI
  • Phase 6 长图/PPT/视频导出

当前限制

当前版本有以下已知限制：

  • 不支持扫描版 PDF — 无 OCR，仅支持搜索型 PDF
  • 不解析表格和公式 — PDF 中的表格、图形、数学符号不深度解析
  • OpenAI provider 为 experimental — 需显式 --allow-external-api opt-in
  • local-http provider 为 experimental — 仅允许 loopback 端点
  • 默认不调用外部 API — rule-based / mock-llm / local-fixture 完全离线
  • 不生成真实图片 — 输出 SVG 占位图和 image prompts，不接入 Stable Diffusion / DALL-E
  • Image adapter 仅本地 — placeholder/fixture adapter 均为纯本地 SVG，不调用外部图片 API
  • 无 Web UI — 仅命令行工具
  • 概念提取为启发式规则 — 不使用 LLM（默认 provider），质量取决于输入文本结构

常见问题

详见 docs/FAQ.md。

版本历史

贡献

欢迎贡献！请先阅读 CONTRIBUTING.md。

License

MIT License — 详见 LICENSE。

About

Turn papers and complex texts into visual explainer cards and cartoon storyboards.

Topics

visualization python nlp education ai storyboard papers cartoon explainer knowledge-tools

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages