predictingthepast
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChinesePredicting The Past (Aeneas / Ithaca)
预测过往(Aeneas / Ithaca)
Aeneas (Latin) and Ithaca (Ancient Greek) perform four tasks on ancient texts:
- Restoration — fill missing/damaged characters
- Attribution — geographical + chronological origin
- Contextualization — retrieve parallel inscriptions
- Embedding — generate text embedding vectors
Aeneas(拉丁语)和Ithaca(古希腊语)可对古代文本执行四项任务:
- 修复 — 补全缺失/损坏的字符
- 归属判定 — 确定地理与年代起源
- 语境化 — 检索相似铭文
- 嵌入 — 生成文本嵌入向量
Prerequisites
前置条件
-
: Read the
uvskill and follow its Setup instructions to ensureuvis installed and on PATH.uv -
User Notification: If .licenses/predictingthepast_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://github.com/google-deepmind/predictingthepast/blob/main/README.md#license--disclaimer, and include the appropriate citation and the full dataset acknowledgement, and that use of these datasets should acknowledge and cite the original data sources. Then (2) create the file recording the notification text and timestamp.
-
:阅读
uv技能文档并按照其设置说明操作,确保uv已安装并添加至PATH。uv -
用户通知:若工作区根目录中不存在.licenses/predictingthepast_LICENSE.txt文件,则需:(1) 显著通知用户查看https://github.com/google-deepmind/predictingthepast/blob/main/README.md#license--disclaimer中的条款,同时包含相应引用和完整数据集致谢信息,并告知用户使用这些数据集时需认可并引用原始数据源;(2) 创建文件记录通知文本和时间戳。
Core Rules
核心规则
- Self-Contained Skill: Do NOT use web search or any external tools. Run
ONLY the scripts in this skill (,
preprocess.py,run_inference.py). Present model output as-is — never supplement or override it with external lookups.visualize_results.py - Notification: If this skill is used, ensure this is mentioned in the output.
- 独立技能:禁止使用网页搜索或任何外部工具。仅运行本技能中的脚本(、
preprocess.py、run_inference.py)。直接呈现模型输出,不得通过外部查询补充或覆盖结果。visualize_results.py - 通知要求:若使用本技能,需在输出中提及这一点。
On First Load
首次加载时
Present the restoration markup characters, then ask the user for their text:
- :
?- Meaning: Known-length gap: predict this character.
- Example:
donat in ??????????rtis
- :
#- Meaning: Unknown-length gap: predict a sequence of unknown length
- Example:
donat in #rtis
- :
-- Meaning: Missing/damaged character that does not need restoring
- Example:
prolixin---s fecit
- :
_- Meaning: Missing section of unknown length that does not need restoring
- Example:
prolixin_s fecit
After presenting this list, ask the user to provide the text they want to submit
for analysis.
先展示修复标记字符,再请求用户提供文本:
- :
?- 含义:已知长度的空缺:预测单个字符。
- 示例:
donat in ??????????rtis
- :
#- 含义:未知长度的空缺:预测一段未知长度的序列
- 示例:
donat in #rtis
- :
-- 含义:无需修复的缺失/损坏字符
- 示例:
prolixin---s fecit
- :
_- 含义:无需修复的未知长度缺失段落
- 示例:
prolixin_s fecit
展示上述列表后,请用户提供需要分析的文本。
Preprocessing
预处理
Clean input text before inference:
bash
uv run <SKILL_DIR>/scripts/preprocess.py \
--language=latin \
--input="raw text here..."Or from a file:
bash
uv run <SKILL_DIR>/scripts/preprocess.py \
--language=greek \
--input_file=/tmp/input.txt \
--output_file=/tmp/cleaned.txt推理前先清理输入文本:
bash
uv run <SKILL_DIR>/scripts/preprocess.py \
--language=latin \
--input="raw text here..."或从文件读取:
bash
uv run <SKILL_DIR>/scripts/preprocess.py \
--language=greek \
--input_file=/tmp/input.txt \
--output_file=/tmp/cleaned.txtWhat preprocessing does
预处理的作用
- Latin: lowercases, converts Arabic digits and Roman numerals to , strips editorial brackets
0and[], removes punctuation, filters to valid chars (()plusabcdefghiklmnopqrstuvxyz)0 . - _ ? # <space> - Greek: lowercases, strips accents, converts numeral notation to , applies PHI cleaning (bracket normalization, sigma conversion), filters to Greek alphabet (
0plusαβγδεζηθικλμνξοπρςστυφχψωϛ)0 . - _ ? # <space>
- 拉丁语:转为小写,将阿拉伯数字和罗马数字转换为,移除编辑用方括号
0和圆括号[],删除标点符号,过滤为有效字符(()加上abcdefghiklmnopqrstuvxyz)0 . - _ ? # <空格> - 古希腊语:转为小写,去除重音,将数字符号转换为,应用PHI清理(括号标准化、西格玛转换),过滤为希腊字母(
0加上αβγδεζηθικλμνξοπρςστυφχψωϛ)0 . - _ ? # <空格>
Inference
推理
Restoration Constraints
修复约束
- Minimum input length: 25 chars (pad with if shorter).
- - No consecutive . No adjacent
##or?#.#? - Spaces inside sequences count toward total.
? - If the user's text contains , ask how many characters to restore and set
#accordingly.--restore_max_len - If the user tries to restore multiple parts of the text at once, suggest to restore texts section by section. Suggest to focus on one damaged region per query — this is faster, produces higher-quality predictions.
- 最小输入长度:25个字符(若更短,用填充)。
- - 不得连续出现。不得出现相邻的
##或?#。#? - 序列中的空格计入总长度。
? - 若用户文本包含,询问需修复的字符数量并相应设置
#。--restore_max_len - 若用户尝试同时修复文本的多个部分,建议分段落修复文本。建议每次查询聚焦一个损坏区域,这样速度更快,预测质量更高。
Pre-Flight Checks
预检查
Confirm with the user before proceeding if either applies:
- Restoration complexity — if input contains more than 10 characters, or uses
?with#, warn: "This restoration involves N characters which will take approximately M minutes (restoration time scales roughly linearly ~10 s per additional--restore_max_len > 10on a high-end CPU machine: 5 → ~1 min, 10 → ~2.5 min, 20 → ~5 min, 30 → ~8 min). Do you want to proceed, or simplify the query first (e.g. fewer?marks, shorter?, or restoring section by section)?"--restore_max_len - Multi-window splitting — if the input text exceeds 750 characters and will be split into multiple windows, warn: "This text is N characters long and will be split into W overlapping windows, each run independently. This will be significantly slower. Do you want to proceed, or shorten the input?"
These factors compound: a complex restoration across multiple windows will be
substantially slower than either factor alone.
若出现以下任一情况,需先与用户确认再继续:
- 修复复杂度 — 若输入包含超过10个字符,或使用
?且#,需警告:"本次修复涉及N个字符,大约需要M分钟(修复时间大致呈线性增长:在高端CPU机器上,每增加一个--restore_max_len > 10约耗时10秒:5个→约1分钟,10个→约2.5分钟,20个→约5分钟,30个→约8分钟)。是否继续,还是先简化查询(例如减少?数量、缩短?或分段落修复)?"--restore_max_len - 多窗口拆分 — 若输入文本超过750个字符,将被拆分为多个窗口,需警告:"本文本长度为N个字符,将被拆分为W个重叠窗口,每个窗口独立运行。这会显著减慢速度。是否继续,还是缩短输入文本?"
这些因素会相互影响:复杂修复加上多窗口拆分的耗时会远高于单一因素的耗时。
Task Selection
任务选择
Each task is controlled by its own flag. At least one must be provided:
- — geographical + chronological attribution
--attribute - — text restoration (requires
--restoreor?in input)# - — parallel inscription retrieval
--contextualize
Any combination is valid. All three can be used together.
When is provided, a text embedding vector is also generated
alongside the other tasks.
--embedding每个任务由独立的标志控制。至少需提供一个:
- — 地理与年代归属判定
--attribute - — 文本修复(输入中需包含
--restore或?)# - — 相似铭文检索
--contextualize
可任意组合,也可同时使用三个任务。
若提供,则会在执行其他任务的同时生成文本嵌入向量。
--embeddingRunning Inference
运行推理
bash
undefinedbash
undefinedAttribution + 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
--language=latin
--input="cleaned text with ???"
--attribute --restore
--output_json=/tmp/results.json
uv run <SKILL_DIR>/scripts/run_inference.py
--language=latin
--input="cleaned text with ???"
--attribute --restore
--output_json=/tmp/results.json
--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
--language=latin
--input="cleaned text"
--attribute --contextualize
--output_json=/tmp/results.json
uv run <SKILL_DIR>/scripts/run_inference.py
--language=latin
--input="cleaned text"
--attribute --contextualize
--output_json=/tmp/results.json
--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
--language=latin
--input="cleaned text with ???"
--attribute --restore --contextualize
--output_json=/tmp/results.json
uv run <SKILL_DIR>/scripts/run_inference.py
--language=latin
--input="cleaned text with ???"
--attribute --restore --contextualize
--output_json=/tmp/results.json
--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
<SKILL_DIR>/scripts/visualize_results.py
--input=/tmp/results.json
--output=/tmp/dashboard.html
Outputs are always returned to the console (JSON/Summary) and must always be
written to an HTML dashboard for rich visualization.
**Serving HTML artifacts**: After generating **any** HTML file (the dashboard or
any other HTML artifact you create), start a background HTTP server so the user
can view it in their browser. Run the server in the foreground of the background
task process (without trailing `&`) to prevent the process from being
terminated. Use a random high port to avoid conflicts.
In the example below, replace `<HTML_FILE>` with the absolute path of the HTML
file you produced (e.g. `/tmp/dashboard.html` or `C:\tmp\dashboard.html`).
For Linux/macOS:
```bashuv run
<SKILL_DIR>/scripts/visualize_results.py
--input=/tmp/results.json
--output=/tmp/dashboard.html
<SKILL_DIR>/scripts/visualize_results.py
--input=/tmp/results.json
--output=/tmp/dashboard.html
输出始终会返回至控制台(JSON/摘要),且必须写入HTML仪表盘以实现丰富可视化。
**HTML artifact 服务**:生成**任何**HTML文件(仪表盘或其他HTML artifact)后,启动后台HTTP服务器,以便用户在浏览器中查看。在后台任务进程的前台运行服务器(不添加尾随`&`),防止进程被终止。使用随机高端端口避免冲突。
在以下示例中,将`<HTML_FILE>`替换为生成的HTML文件的绝对路径(例如`/tmp/dashboard.html`或`C:\tmp\dashboard.html`)。
适用于Linux/macOS:
```bashPick 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")"
For Windows (PowerShell):
```powershellHTML_FILE=/tmp/dashboard.html # ← 设置为实际HTML文件路径
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 "查看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):
```powershellPick 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
Then provide `http://localhost:<port>/<filename>` (or
`http://127.0.0.1:<port>/<filename>`) as the primary clickable link in your
response. Additionally, provide `http://<hostname>:<port>/<filename>` as a
fallback link for remote setups. Do **not** give the user a raw `file://` path.$HTML_FILE = "C:\tmp\dashboard.html" # ← 设置为实际HTML文件路径
$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 "查看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://`路径。Flags
标志说明
- : Text string (mutually exclusive with
--input)--input_file - : Path to UTF-8 text file
--input_file - :
--languageorlatingreek - : Model files directory (default:
--models_dir)$HOME/.predictingthepast/models - : Run geographical and chronological attribution
--attribute - : Run text restoration (requires
--restoreor?in input)# - : Run parallel inscription retrieval
--contextualize - : Number of top parallels to return (default: 10)
--contextualize_top_k - : Exclude test/validation texts from contextualization results. Filters on the internal numeric
--contextualize_exclude_test_valid(whereidis 3 or 4).id % 10 - : Generate a text embedding vector (default: off). When set, the output includes an
--embeddingfield with the full-precision float vector.embedding - : Save combined JSON to file (for
--output_json)visualize_results.py - : Number of candidate restorations to explore in beam search. Higher = more thorough but slower (default: 100)
--restore_beam_width - : Maximum total characters to restore across all
--restore_max_lenand?gaps (default: 15)# - : Sampling temperature. Lower = conservative, higher = creative (default: 1.0)
--restore_temperature - : Overlap fraction for long-text windowing (default: 0.33)
--window_overlap
- : 文本字符串(与
--input互斥)--input_file - : UTF-8文本文件路径
--input_file - :
--language或latingreek - : 模型文件目录(默认:
--models_dir)$HOME/.predictingthepast/models - : 运行地理与年代归属判定
--attribute - : 运行文本修复(输入中需包含
--restore或?)# - : 运行相似铭文检索
--contextualize - : 返回的相似文本数量(默认:10)
--contextualize_top_k - : 从语境化结果中排除测试/验证文本。根据内部数字
--contextualize_exclude_test_valid过滤(id为3表示测试,4表示验证)。id % 10 - : 生成文本嵌入向量(默认:关闭)。启用后,输出将包含
--embedding字段,存储全精度浮点向量。embedding - : 将合并后的JSON保存至文件(供
--output_json使用)visualize_results.py - : 束搜索中探索的候选修复数量。数值越高越全面但速度越慢(默认:100)
--restore_beam_width - : 所有
--restore_max_len和?空缺中需修复的最大总字符数(默认:15)# - : 采样温度。数值越低越保守,越高越具创造性(默认:1.0)
--restore_temperature - : 长文本窗口拆分的重叠比例(默认:0.33)
--window_overlap
Long Texts (>750 characters)
长文本(>750字符)
Each window must be between 25 and 750 characters. If the input text exceeds
750 characters, it is automatically split into overlapping windows (default 33%
overlap). Each window is run through the model independently, and the
geographical and chronological attribution results are averaged across all
windows. Restoration and contextualization are run per-window and concatenated.
每个窗口长度必须在25至750字符之间。若输入文本超过750字符,将自动拆分为重叠窗口(默认重叠33%)。每个窗口独立通过模型运行,地理与年代归属判定结果将在所有窗口间取平均值。修复和语境化结果按窗口运行后拼接。
Output Format
输出格式
Use to save the combined JSON to a file. For the full
format including all fields for attribution, restoration, and
contextualization, see output_format.md.
--output_json--output_json使用将合并后的JSON保存至文件。关于包含归属判定、修复和语境化所有字段的完整格式,请查看output_format.md。
--output_json--output_jsonPresenting Results
结果展示
Present results for every task requested by the user. Always generate the
HTML dashboard, serve it via the background HTTP server described above, and
provide the URL as a clickable link. Format years as BCE/CE.
http://展示用户请求的所有任务结果。始终生成HTML仪表盘,通过上述后台HTTP服务器提供服务,并提供格式的可点击链接。年份格式使用BCE/CE(公元前/公元后)。
http://Restoration
修复
Bold the restored characters in the top prediction. Show top-10 beam-search
candidates in a numbered table (rank, restored text, score). Summarise the most
salient words (not characters) — do not dump the raw saliency array.
将最优预测中的修复字符加粗。在编号表格中展示束搜索得到的前10个候选结果(排名、修复后文本、得分)。总结最显著的词汇(而非字符),请勿直接输出原始显著性数组。
Geographical Attribution
地理归属判定
Show the top 10 regions in a ranked table (rank, region, score). Highlight the
top-1 prediction in the narrative. Summarise the most salient words (not
characters) — do not dump the raw saliency array.
在排名表格中展示前10个区域(排名、区域、得分)。在叙述中突出显示排名第一的预测结果。总结最显著的词汇(而非字符),请勿直接输出原始显著性数组。
Chronological Attribution
年代归属判定
Report top year and weighted average year. Describe the distribution shape (peak
decade, probable range) — do not list all 160 bins. Summarise the most salient
words (not characters) — do not dump the raw saliency array.
报告排名第一的年份和加权平均年份。描述分布形态(峰值十年、可能范围),请勿列出所有160个区间。总结最显著的词汇(而非字符),请勿直接输出原始显著性数组。
Contextualization (Parallels)
语境化(相似文本)
Use or write your own code to extract the contextualization data from
. Show the top parallels in a table (rank, ID, Trismegistos ID,
region, date range, score, partner link). Quote the full text of the top
parallels from the JSON.
jp--output_jsonIf the user requests a specific number of parallels, use
to control how many are returned.
--contextualize_top_kIf the user asks to exclude test/validation texts, add
. This filters on the internal numeric
(where is 3 for test or 4 for validation).
--contextualize_exclude_test_valididid % 10使用或自行编写代码从中提取语境化数据。在表格中展示最相似的文本(排名、ID、Trismegistos ID、区域、日期范围、得分、关联链接)。引用JSON中排名靠前的相似文本的完整内容。
jp--output_json若用户请求特定数量的相似文本,使用控制返回数量。
--contextualize_top_k若用户要求排除测试/验证文本,添加。此选项根据**内部数字**过滤(为3表示测试,4表示验证)。
--contextualize_exclude_test_valididid % 10Embedding (when --embedding
is set)
--embedding嵌入(当启用--embedding
时)
--embeddingState the vector dimensionality (384 floats).
说明向量维度(384个浮点数)。
References
参考文献
For more information, see:
predictingthepast.com
IMPORTANT: The first time you return inference results to the user, remind
them to cite the appropriate paper below (Ithaca for Greek, Aeneas for Latin),
and the dataset acknowledgements below.
Ithaca (Ancient Greek): > Assael, Y., Sommerschield, T., Shillingford, B. et
al. Restoring and attributing ancient texts using deep neural networks. Nature
603, 280–283 (2022).
Aeneas (Latin): > Assael, Y., Sommerschield, T., Cooley, A. et al.
Contextualizing ancient texts with generative neural networks. Nature 645,
141–147 (2025).
更多信息请查看:
predictingthepast.com
重要提示:首次向用户返回推理结果时,提醒用户引用以下对应论文(古希腊语用Ithaca,拉丁语用Aeneas),以及下方的数据集致谢信息。
Ithaca(古希腊语):> Assael, Y., Sommerschield, T., Shillingford, B. et al. Restoring and attributing ancient texts using deep neural networks. Nature 603, 280–283 (2022).
Aeneas(拉丁语):> Assael, Y., Sommerschield, T., Cooley, A. et al. Contextualizing ancient texts with generative neural networks. Nature 645, 141–147 (2025).
Dataset Acknowledgements
数据集致谢
IMPORTANT: The first time you present inference results to the user, include
the appropriate citation and the full dataset acknowledgement for the language
used (see below).
The Ithaca and Aeneas projects rely on the availability of high-quality datasets
of ancient Greek and Latin inscriptions, respectively. These datasets were built
through centuries of scholarly collection and decades of digital editorial work.
Ithaca (Ancient Greek): In particular, Ithaca draws on a 2019 version of the
Searchable Greek Inscriptions database made available under "Fair Use" license
by the Packard Humanities Institute, generously supported by David Packard:
inscriptions.packhum.org.
Aeneas (Latin): Aeneas was trained on data from:
- Epigraphic Database Roma (EDR): Made available pursuant to a Creative Commons Attribution 4.0 International License (CC-BY) on Zenodo. EDR is also available at edr-edr.it.
- Epigraphic Database Heidelberg (EDH): Made available pursuant to a Creative Commons Attribution-ShareAlike 4.0 International License (CC-BY-SA) on Zenodo. EDH is also available at edh.ub.uni-heidelberg.de.
- ETL repository for Epigraphic Database Clauss Slaby (EDCS_ETL): Made available pursuant to a Creative Commons Attribution 4.0 International License (CC-BY) on Zenodo. EDCS_ETL is also available at manfredclauss.de and github.com/sdam-au/EDCS_ETL.
These resources bring together a large proportion of published inscriptions in a
searchable digital format.
重要提示:首次向用户展示推理结果时,需包含对应语言的引用和完整数据集致谢信息(见下文)。
Ithaca和Aeneas项目依赖于高质量的古希腊语和拉丁语铭文数据集。这些数据集是经过数百年的学术收集和数十年的数字编辑工作构建而成。
Ithaca(古希腊语):特别地,Ithaca使用了Packard人文研究所于2019年提供的可搜索希腊铭文数据库,该数据库基于「合理使用」许可,由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获取。
- ETL repository for Epigraphic Database Clauss Slaby (EDCS_ETL):基于知识共享署名4.0国际许可(CC-BY)在Zenodo上提供。EDCS_ETL也可在manfredclauss.de和github.com/sdam-au/EDCS_ETL获取。
这些资源将大量已发表的铭文整合为可搜索的数字格式。