One YAML File for a Town Archive's Condition Calls

Description and use

A single YAML model was created to classify items in a small archive, eliminating inconsistencies across separate notebooks and providing a unified set of rules for assessing condition, digitization, and risk.

Problem

Multiple notebooks for a town archive disagreed on how to classify items, leading to inconsistent treatment, digitization, and risk decisions.

Outcome

Consistent, rule‑driven classification of archive items, a 50% treatment rate, seven items flagged for digitization, two pull risks, and a clear, reproducible workflow.

Workflow

• Define fact grain as Item
• Define dimensions: Collection, Location, Format
• Define properties: condition_score, digitized, pull_count, note
• Define metrics/judgments: NeedsTreatment, Stable, DigitizeNext, PullRisk
• Write rules in YAML with clear boundaries (e.g., score <=2 for treatment)
• Load YAML with PyYAML and validate with ontology.py
• Bind items to dimensions with bind.py
• Score items with metrics.py
• Generate report via build_report in main.py
• Expose report through FastAPI GET /api/brief
• Render chart with Matplotlib
• Run tests with pytest to ensure rule boundaries and error handling

Evidence

I kept three notebooks for a fake town archive and they would not agree on a single object.

Source

The semantic model is schema/archive.yaml. The fact grain is Item.

Source

Python main.py prints that table. FastAPI serves the same build_report function.

Source