sicilahval: from Ottoman biographies to reusable data

I built sicilahval while working with Sicill-i Ahvâl personnel biographies. Researchers repeatedly turn similar accounts into spreadsheets. Each project has to decide how to represent appointments, schooling, dates, pay changes and later additions. This package and companion skill provide a shared starting point while retaining the source wording.

The assistant reads and structures the biography; Python prepares, checks and exports it. You can use the skill in Codex or Claude Code, with Turkish or English review notes. No separate model API key or web-search service is needed for local files.

1. 1. SourceFile, text segments and locations
2. 2. ReadingAssistant or researcher structures the account
3. 3. ChecksQuotes, references and declared coverage
4. 4. DataLinked CSV, JSON and SQLite

Install

Use Python 3.10 or later. This command installs version 0.1.6 from GitHub, including the optional text-PDF reader.

python -m pip install \
  "sicilahval[pdf] @ git+https://github.com/kansoy/ottoman-personnel-tools.git@v0.1.6"

Use it in Codex or Claude Code

Install the skill for your assistant, then reload or rescan skills if your client requires it. The host needs file access and Python execution.

sicilahval install-skill --target codex --scope user
# For Claude Code:
sicilahval install-skill --target claude --scope user

Codex

Use $sicilahval to extract every complete biography and addition
from this file. Preserve native dates, payment components, source
quotations and uncertainty. Return CSV and SQLite with an English
review summary.

Claude Code

/sicilahval Extract every complete biography and addition from
this file. Preserve native dates, payment components, source
quotations and uncertainty. Return CSV and SQLite with an English
review summary.

Ask for a Turkish review summary instead if preferred. Quotations and names keep their source spelling; table field names remain stable. An uploadable standalone skill ZIP is also available for compatible hosts.

Use it from Python

First prepare a document. This writes tagged text, source metadata and a record template into a new directory.

from sicilahval import prepare_source

prepare_source("records.docx", "work", language="en")

Reading step: the assistant or researcher now reads work/source.txt, follows the schema and fills work/records.json using the template. The preparation function does not extract the biography’s meaning.

Then validate and export the completed reading:

from sicilahval import validate_records, export_records

report = validate_records("work/records.json", "work/source.json")
if not report["valid"]:
    raise ValueError(report["errors"])

export_records("work/records.json", "work/source.json", "data")

Use language="tr" for Turkish notes. Output includes 11 linked CSV tables, the full JSON reading and sicilahval.sqlite. Personal and family details, education, languages, events, native dates, payment components, legal statements, corrections and uncertainty have a place in the format.

A real example: a raise is not a salary

The same record explicitly reports conversion to Islam and the name Mahmut Süreyya on 4 Rebiülevvel AH 1306. The linked event retains the original wording and paired native dates; his earlier religion remains unspecified because this passage does not state it. The change applies at that exact day boundary; the later religion and name are not assigned to earlier periods or the whole of AH 1306.

Değişiklik 4 Rebiülevvel 1306 (Hicrî) gününe bağlıdır; sonraki din ve ad, önceki dönemlere veya Hicrî 1306 yılının tamamına atanmaz.

A second example, Zenop Tangaryan, retains conflicting birth-year statements rather than silently choosing one. Run the reviewed examples locally:

sicilahval demo --out manuk-demo --language en
sicilahval demo --out zenop-demo --language tr

The demo exports the included reviewed readings. It does not make a new model call.

What it saves—and what still needs judgement

The reusable work is the structure: a consistent reading protocol, quotations linked to source locations, distinct dates and pay components, explicit uncertainty, and reproducible exports. That makes it easier to check a collaborator’s reading and reuse records across projects. A web search connector would help locate material; it would not replace these steps.

TXT, Markdown, DOCX, text PDF, HTML, common RTF and ODT are supported. Scans and images need a separately checked transcription or OCR process. Unknown pay stays distinct from zero, an allegation from a conviction, and an inferred reading from a direct statement.

The validation notes report 43 software tests and checks on the two real examples. The date checks now correctly read forms such as “yirmi beşine” (25) and “on sekizine” (18), as well as a year joined to a month name (“Zilhicce1299”). These do not establish general extraction accuracy. Quotes can match even when their interpretation is wrong. Historical judgement and review remain necessary; place/job codes, identity merging, calendar conversion and person-year panels are separate research decisions.

Code, methods and citation

The software is open source under Apache-2.0. Start with the repository or the three-page methods note in your preferred language.

Kansoy, Fatih (2026). sicilahval: Evidence-linked extraction of Ottoman personnel records. Version 0.1.6. Citation metadata. Cite the historical source separately.

Reference: Sarıyıldız, Gülden (2009). “Sicill-i Ahvâl Defterleri.” TDV İslâm Ansiklopedisi, 37, 134–136.

Contact: kansoy@gmail.com · fatih.ai

Share cards: English PNG · Türkçe PNG