predictingthepast

预测过去（Aeneas / Ithaca）

Aeneas（拉丁语）和 Ithaca（古希腊语）可对古代文本执行四项任务：

1. 文本修复 — 补全缺失或受损的字符
2. 归属判定 — 判定地理和年代来源
3. 语境化 — 检索平行铭文
4. 嵌入 — 生成文本嵌入向量

前置条件

1. uv：阅读 uv 技能，并按照其中的设置说明确保已安装 uv，且它位于 PATH 中。

2. 用户通知：如果工作区根目录中尚不存在 .licenses/predictingthepast_LICENSE.txt，则（1）醒目地提醒用户查看 https://github.com/google-deepmind/predictingthepast/blob/main/README.md#license--disclaimer 中的条款，并提供适当的引用和完整的数据集致谢，同时说明使用这些数据集时应致谢并引用原始数据来源。然后（2）创建文件，记录通知文本和时间戳。

核心规则

• 独立运行的技能：不得使用网页搜索或任何外部工具。仅运行此技能中的脚本（preprocess.py、run_inference.py、visualize_results.py）。按原样呈现模型输出，不得通过外部查询补充或覆盖输出。
• 通知：如果使用了此技能，确保在输出中提及这一点。

首次加载时

展示文本修复标记，然后询问用户要处理的文本：

• ?：
  • 含义：已知长度的缺失部分：预测这个字符。
  • 示例：donat in ??????????rtis
• #：
  • 含义：长度未知的缺失部分：预测一段长度未知的字符序列
  • 示例：donat in #rtis
• -：
  • 含义：缺失或受损的字符，但不需要修复
  • 示例：prolixin---s fecit
• _：
  • 含义：长度未知的缺失部分，但不需要修复
  • 示例：prolixin_s fecit

展示此列表后，询问用户提供要提交分析的文本。

预处理

推理前清理输入文本：

uv run <SKILL_DIR>/scripts/preprocess.py \
    --language=latin \
    --input="raw text here..."

或从文件读取：

uv run <SKILL_DIR>/scripts/preprocess.py \
    --language=greek \
    --input_file=/tmp/input.txt \
    --output_file=/tmp/cleaned.txt

预处理的内容

• 拉丁语：转换为小写，将阿拉伯数字和罗马数字转换为 0，去除编者括号 [] 和 ()，移除标点，将字符筛选为有效字符（abcdefghiklmnopqrstuvxyz 加上 0 . - _ ? # <space>）
• 希腊语：转换为小写，去除重音，将数字记号转换为 0，应用 PHI 清理（括号规范化、sigma 转换），将字符筛选为希腊字母（αβγδεζηθικλμνξοπρςστυφχψωϛ 加上 0 . - _ ? # <space>）

推理

文本修复约束

• 输入最小长度：25 个字符（如果更短，则用 - 补齐）。
• 不允许连续出现 ##。不允许相邻出现 ?# 或 #?。
• ? 序列中的空格计入总长度。
• 如果用户的文本中包含 #，询问需要修复多少个字符，并据此设置 --restore_max_len。
• 如果用户尝试一次修复文本中的多个部分，建议按段落逐一修复。建议每次查询聚焦于一个受损区域，这样速度更快，预测质量也更高。

运行前检查

如果以下任一情况适用，请先征得用户同意再继续：

1. 恢复复杂度 — 如果输入包含超过 10 个 ? 字符，或者使用 # 且 --restore_max_len > 10，请警告用户："此次恢复涉及 N 个字符，预计需要约 M 分钟（在高端 CPU 机器上，恢复时间大致随每个额外的 ? 线性增长，约为每个 ? 10 秒：5 → ~1 分钟，10 → ~2.5 分钟，20 → ~5 分钟，30 → ~8 分钟）。是否继续，还是先简化查询（例如减少 ? 标记、缩短 --restore_max_len，或逐段恢复）？"
2. 多窗口拆分 — 如果输入文本超过 750 个字符，并将拆分为多个窗口，请警告用户："此文本长 N 个字符，将拆分为 W 个有重叠的窗口，并分别运行。这会显著耗时。是否继续，还是缩短输入？"

这些因素会叠加：跨多个窗口进行复杂恢复，将比单独遇到其中任一因素耗时更多。

任务选择

每项任务都由其独立的标志控制。必须至少提供一个：

• --attribute — 地理和年代归属
• --restore — 文本恢复（输入中需要有 ? 或 #）
• --contextualize — 并行检索铭文

可以使用任意组合，也可以同时使用全部三项。

提供 --embedding 时，还会生成文本嵌入向量。

运行推理

# Attribution + Restoration (text with gaps)
uv run <SKILL_DIR>/scripts/run_inference.py \
    --language=latin \
    --input="cleaned text with ???" \
    --attribute --restore \
    --output_json=/tmp/results.json

# Attribution + Contextualization (no gaps)
uv run <SKILL_DIR>/scripts/run_inference.py \
    --language=latin \
    --input="cleaned text" \
    --attribute --contextualize \
    --output_json=/tmp/results.json

# All tasks
uv run <SKILL_DIR>/scripts/run_inference.py \
    --language=latin \
    --input="cleaned text with ???" \
    --attribute --restore --contextualize \
    --output_json=/tmp/results.json

# Generate dashboard
uv run \
    <SKILL_DIR>/scripts/visualize_results.py \
    --input=/tmp/results.json \
    --output=/tmp/dashboard.html

输出始终返回到控制台（JSON/摘要），并且必须始终写入 HTML 仪表板，以便进行丰富的可视化。

提供 HTML 工件：生成任何 HTML 文件（仪表板或创建的其他 HTML 工件）后，都要启动后台 HTTP 服务，以便用户在浏览器中查看。请在后台任务进程的前台运行服务（末尾不要加 &），以防进程被终止。使用随机的高位端口来避免冲突。

在以下示例中，将 <HTML_FILE> 替换为生成的 HTML 文件的绝对路径（例如 /tmp/dashboard.html 或 C:\tmp\dashboard.html）。

对于 Linux/macOS：

# Pick an unused port and start the server as a persistent process
HTML_FILE=/tmp/dashboard.html   # ← set to the actual HTML file path
PORT=$(export PATH="$HOME/.local/bin:$PATH" && uv run python -c "import socket; s=socket.socket(); s.bind(('',0)); print(s.getsockname()[1]); s.close()")
FILENAME=$(basename "$HTML_FILE")
echo "View URL: http://localhost:${PORT}/${FILENAME}"
export PATH="$HOME/.local/bin:$PATH" && uv run python -m http.server "$PORT" --bind 0.0.0.0 --directory "$(dirname "$HTML_FILE")"

对于 Windows（PowerShell）：

# Pick an unused port and start the server as a persistent process
$HTML_FILE = "C:\tmp\dashboard.html"   # ← set to the actual HTML file path
$PORT = & "$HOME\.local\bin\uv" run python -c "import socket; s=socket.socket(); s.bind(('',0)); print(s.getsockname()[1]); s.close()"
$FILENAME = Split-Path $HTML_FILE -Leaf
$DIRNAME = Split-Path $HTML_FILE -Parent
Write-Host "View URL: http://localhost:${PORT}/${FILENAME}"
& "$HOME\.local\bin\uv" run python -m http.server $PORT --bind 0.0.0.0 --directory $DIRNAME

然后在回复中提供 http://localhost:<port>/<filename>（或 http://127.0.0.1:<port>/<filename>）作为主要可点击链接。此外，还要提供 http://<hostname>:<port>/<filename> 作为远程环境下的备用链接。不要向用户提供原始的 file:// 路径。

标志

• --input：文本字符串（不能与 --input_file 同时使用）
• --input_file：UTF-8 文本文件的路径
• --language：latin 或 greek
• --models_dir：模型文件目录（默认值： $HOME/.predictingthepast/models）
• --attribute：运行地理和年代归属分析
• --restore：运行文本修复（输入中需要包含 ? 或 #）
• --contextualize：运行平行铭文检索
• --contextualize_top_k：返回的最相关平行文本数量（默认值：10）
• --contextualize_exclude_test_valid：从语境化结果中排除测试集／验证集文本。根据内部数值 id 进行筛选（其中 id % 10 为 3 或 4）。
• --embedding：生成文本嵌入向量（默认关闭）。启用后，输出会包含一个 embedding 字段，其中包含完整精度的浮点向量。
• --output_json：将合并后的 JSON 保存到文件（供 visualize_results.py 使用）
• --restore_beam_width：束搜索中要探索的候选修复结果数量。数值越大，搜索越全面但速度越慢（默认值：100）
• --restore_max_len：在所有 ? 和 # 缺口中修复的字符总数上限（默认值：15）
• --restore_temperature：采样温度。数值越低，结果越保守；数值越高，结果越有创意（默认值：1.0）
• --window_overlap：长文本分窗时的重叠比例（默认值： 0.33）

长文本（>750 个字符）

每个窗口必须在 25 到 750 个字符之间。如果输入文本超过 750 个字符，系统会自动将其拆分为相互重叠的窗口（默认重叠 33%）。每个窗口都会单独通过模型处理，地理和年代归属分析的结果会在所有窗口间取平均值。文本修复和语境化则逐窗口运行，之后再合并结果。

输出格式

使用 --output_json 将合并后的 JSON 保存到文件。有关 --output_json 的完整格式（包括归属分析、文本修复和语境化的所有字段），请参阅 output_format.md。

呈现结果

呈现用户要求的每一项任务的结果。始终生成 HTML 仪表板，通过上文所述的后台 HTTP 服务提供，并提供可点击的 http:// URL。年份格式使用 BCE/CE。

文本修复

将首选预测中修复的字符加粗。以编号表格展示束搜索的前 10 个候选结果（排名、修复后的文本、分数）。总结最显著的词语（而非字符）——不要直接输出原始显著性数组。

地理归属分析

以排名表格展示前 10 个地区（排名、地区、分数）。在叙述中突出显示排名第 1 的预测结果。总结最显著的词语（而非字符）——不要直接输出原始显著性数组。

年代归属分析

报告首选年份和加权平均年份。描述分布形状（峰值所在的十年、可能的范围）——不要列出全部 160 个区间。总结最显著的词语（而非字符）——不要直接输出原始显著性数组。

语境化（平行文本）

使用 jp 或编写自己的代码，从 --output_json 中提取语境化数据。以表格展示最相关的平行文本（排名、ID、Trismegistos ID、地区、日期范围、分数、partner 链接）。从 JSON 中引用最相关平行文本的完整内容。

如果用户要求特定数量的平行文本，请使用 --contextualize_top_k 控制返回数量。

如果用户要求排除测试集／验证集文本，请添加 --contextualize_exclude_test_valid。此选项根据内部数值 id 进行筛选（测试集的 id % 10 为 3，验证集的 id % 10 为 4）。

嵌入（启用 --embedding 时）

注明向量维度（384 个浮点数）。

参考资料

如需了解更多信息，请访问： predictingthepast.com

重要提示： 首次向用户返回推理结果时，请提醒他们引用下方相应的论文（希腊语引用 Ithaca，拉丁语引用 Aeneas）以及下方的数据集致谢。

Ithaca（古希腊语）：> Assael, Y., Sommerschield, T., Shillingford, B. 等。使用深度神经网络复原并归属古代文本。Nature 603，280–283（2022）。

Aeneas（拉丁语）：> Assael, Y., Sommerschield, T., Cooley, A. 等。 使用生成式神经网络为古代文本提供背景信息。Nature 645， 141–147（2025）。

数据集致谢

重要提示： 首次向用户展示推理结果时，请提供相应的引用，以及所用语言对应的完整数据集致谢（见下文）。

Ithaca 和 Aeneas 项目分别依托高质量的古希腊语和拉丁语铭文数据集。这些数据集历经数百年的学术整理和数十年的数字编辑工作而建成。

Ithaca（古希腊语）：具体而言，Ithaca 使用了 Searchable Greek Inscriptions 数据库的 2019 年版本。该版本由 Packard Humanities Institute 根据“合理使用”许可提供，并得到 David Packard 的慷慨支持： inscriptions.packhum.org。

Aeneas（拉丁语）：Aeneas 使用以下数据训练：

• Epigraphic Database Roma (EDR)：根据知识共享署名 4.0 国际许可（CC-BY）在 Zenodo 上提供。EDR 也可通过 edr-edr.it 获取。
• Epigraphic Database Heidelberg (EDH)：根据知识共享署名—相同方式共享 4.0 国际许可（CC-BY-SA） 在 Zenodo 上提供。EDH 也可通过 edh.ub.uni-heidelberg.de 获取。
• Epigraphic Database Clauss Slaby (EDCS_ETL) 的 ETL 仓库：根据知识共享署名 4.0 国际 许可（CC-BY）在 Zenodo 上提供。EDCS_ETL 也可通过 manfredclauss.de 和 github.com/sdam-au/EDCS_ETL 获取。

这些资源以可搜索的数字格式汇集了大量已发表的铭文。