Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/automated-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,14 @@ The **Auto-merge** check decides, after an hour with every check green. Adding t
| **changes** any other value, such as a name, colour, trait or link | Merges unless the AI review raises a 🔴 error on it, like new data. |
| **deletes**, renames or removes anything, or changes an `id`, `uuid` or `slicer_ids` | Always needs a maintainer. |

It never auto-merges claimed brands (their representative signs off), or sustainability data. The full checklist (E1–E22) is in [`ofd/automerge/eligibility.py`](../ofd/automerge/eligibility.py) and on each PR's Auto-merge check.
It never auto-merges claimed brands (their representative signs off), sustainability data or mechanical data. The full checklist (E1–E22) is in [`ofd/automerge/eligibility.py`](../ofd/automerge/eligibility.py) and on each PR's Auto-merge check.

## Sustainability data

Sustainability figures feed CO2 calculations, so the `Sustainability sources` status fails closed. Every figure must be on its source, verbatim, and confirmed by the AI review. See [the manual](manual.md#-sustainability-data).

Mechanical values (`mechanical` on filaments) go through the same status: each one must be on its data sheet, verbatim, and confirmed by the AI review. See [the manual](manual.md#-mechanical-data).

A maintainer who has checked a figure by hand can add the `sustainability-verified` label. A later push that touches sustainability data removes the label again.

A PR that changes the rules themselves (the schemas, `ofd/review/sustainability.py`, this workflow) needs a maintainer's eyes. That requirement is already met when a maintainer opened the PR.
Expand Down
53 changes: 53 additions & 0 deletions docs/manual.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,7 @@ A filament represents a **product line** (e.g. "Silk PLA", "Glow PLA"), **not a
- Lifecycle: `discontinued` (boolean)
- Slicer integration: `slicer_ids` (PrusaSlicer / BambuStudio / OrcaSlicer / Cura native IDs) and `slicer_settings` (per-slicer profile names, IDs, and temperature overrides)
- Sustainability: `sustainability` — sourced recycled / bio-based content, carbon footprints and relative claims. See [🌱 Sustainability data](#-sustainability-data); every figure needs a source.
- Mechanical data: `mechanical` — sourced tensile, flexural, impact and heat deflection values from the data sheet, per print direction. See [🔩 Mechanical data](#-mechanical-data); every value needs a source.

## 🎨 Adding a Variant
A variant represents a single colour or finish of a filament.
Expand Down Expand Up @@ -253,6 +254,58 @@ Sustainability figures are used to calculate the CO₂ footprint of prints, and

Checked a brand and found nothing? Record that in [`docs/sustainability-sources.md`](sustainability-sources.md). A negative result is useful too.

## 🔩 Mechanical data
Data sheets give stiffness, strength, impact and heat values, often **per print direction**: a part is weaker across its layers than along them. `mechanical` keeps those values with their source, so CAD, simulation and slicer tools can use them.

### The rules
1. **Copy, never compute.** Enter each value in the unit the sheet uses: a sheet in psi stays in psi, and `3.86 GPa` is never entered as `3860 MPa`. Never average, convert or estimate.
2. **Every entry needs a source**: `source_url`, `source_quote` and `retrieved`, as for [sustainability data](#-sustainability-data). The quote is the sheet's row, verbatim, and must contain the value (and `plus_minus`, if set). `5.85` matches `5,85`. In `MPa`, `psi`, `ksi` and `J/m`, where values of 1000 and up are common, `7250` also matches `7,250`; in other units a comma is a decimal comma, so `2,350 GPa` is `2.35`.
3. **Primary sources first**: the brand's own data sheet (TDS) or product page. Mark a retailer copy `source_type: "secondary"`.
4. **One entry per value**: one for X-Y, one for Z, one for dry and one for conditioned. If the sheet gives a range or a footnote, quote it and explain it in `notes`.
5. **No generic values in `data/`.** Typical values for a material type (PLA, PETG...) are not a brand's data.

`ofd validate` checks the sources, the value in the quote, dates in the future and that the unit fits the property (errors). It warns about a print direction on moulded bars and about repeated entries (same property, direction, condition, standard, unit and specimen).

On a pull request, the `Sustainability sources` check also checks every new or changed mechanical value against its source, and a PR that touches mechanical data never merges automatically. See [automated review](automated-review.md#sustainability-data).

### Where it goes
`mechanical` is an array on `filament.json`. Variants don't override it: a data sheet covers the product line.

```json
"mechanical": [
{
"property": "tensile_modulus", "direction": "XY",
"value": 3860, "plus_minus": 230, "unit": "MPa",
"standard": "ISO 527", "condition": "dry",
"specimen": {"process": "printed", "infill_percent": 100, "print_temperature": 290,
"conditioning": "annealed and dried at 80 °C for 12 h"},
"source_type": "primary",
"source_url": "https://store.bblcdn.com/7166b20bc68f4c87b32c972b856eeb4b.pdf",
"source_quote": "Young's Modulus (X-Y) ISO 527, GB/T 1040 3860 ± 230 MPa",
"retrieved": "2026-11-08"
}
]
```

The sheet's Z row (`2180 ± 130 MPa`) is a second entry with `"direction": "Z"` and its own quote.

### Field guide
| Field | Values | Meaning |
|---|---|---|
| `property` | `tensile_modulus`, `tensile_strength`, `yield_strength`, `elongation_at_break`, `flexural_modulus`, `flexural_strength`, `impact_strength`, `impact_strength_notched`, `heat_deflection_045`, `heat_deflection_18`, `vicat_softening` | What was measured. `heat_deflection_045` / `_18` are HDT at 0.45 / 1.8 MPa. Young's modulus is `tensile_modulus` |
| `direction` | `XY`, `XZ`, `Z`, `unknown` | `XY`: bars printed flat (along the layers). `XZ`: on edge. `Z`: upright (across the layers). `unknown` when the sheet gives none, and for moulded bars |
| `value`, `plus_minus` | numbers | As written. `plus_minus` is the "±" spread, or `null` |
| `unit` | `MPa`, `GPa`, `psi`, `ksi`, `%`, `kJ/m2`, `J/m`, `ft-lb/in`, `°C`, `°F` | Must fit the property: moduli and strengths in `MPa`, `GPa`, `psi` or `ksi`; elongation in `%`; impact in `kJ/m2` (ISO 179 / 180), `J/m` or `ft-lb/in` (ASTM D256); heat in `°C` or `°F` |
| `standard` | free text or `null` | **Only** when the sheet names one, e.g. "ISO 527" or "ASTM D638" |
| `condition` | `dry`, `conditioned` | Moisture state at test time, when the sheet gives it (common for nylons) |
| `specimen` | object | How the bars were made: `process` (`printed`, `moulded`, `unknown`), `printer`, `nozzle_diameter`, `layer_height`, `infill_percent`, `perimeters`, `raster_angle`, `print_temperature`, `bed_temperature`, `chamber_temperature`, `print_speed`, `conditioning` (e.g. "annealed at 80 °C for 12 h"). Leave out what the sheet doesn't say |

### Valid sources
- ✅ The brand's technical data sheet (TDS) or product page
- ✅ A retailer copy of the brand's sheet, **only** when the original is gone (`source_type: "secondary"`)
- ❌ Your own test results, or values from a review or forum
- ❌ Values you converted, averaged or read off a chart

## 🏪 Adding a Store
Stores are referenced by `purchase_links[].store_id` and live under `/stores`.

Expand Down
4 changes: 3 additions & 1 deletion ofd/automerge/eligibility.py
Original file line number Diff line number Diff line change
Expand Up @@ -286,7 +286,9 @@ def check(id_: str, ok: bool, detail: str) -> None:
check(
"E15",
not touched and gate_green,
"no sustainability data, gate green" if not touched else "touches sustainability data",
"no sustainability or mechanical data, gate green"
if not touched
else "touches sustainability or mechanical data",
)
ai_errors = [f for f in model.get("findings") or [] if f.get("severity") == "error"]
blocked = (NEW in kinds or JUDGED in kinds) and ai_errors
Expand Down
1 change: 1 addition & 0 deletions ofd/builder/exporters/csv_exporter.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@
"enclosure",
"discontinued",
"sustainability",
"mechanical",
],
"variant": [
"id",
Expand Down
3 changes: 2 additions & 1 deletion ofd/builder/exporters/sqlite_exporter.py
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,8 @@
safety_sheet_url TEXT,
discontinued INTEGER NOT NULL DEFAULT 0,
slicer_settings TEXT, -- JSON
sustainability TEXT -- JSON (see schemas/sustainability_schema.json)
sustainability TEXT, -- JSON (see schemas/sustainability_schema.json)
mechanical TEXT -- JSON (see schemas/mechanical_schema.json)
);
CREATE INDEX IF NOT EXISTS ix_filament_brand ON filament(brand_id);
CREATE INDEX IF NOT EXISTS ix_filament_material ON filament(material_id);
Expand Down
6 changes: 6 additions & 0 deletions ofd/review/guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,12 @@ and sustainability traits (`recycled`, `biodegradable`, `bio_based`, compostable
added without a source. Set `sustainability.verdict` to `ok` only when every entry is
`ok`. Never propose sustainability values in `enrichments`; only check what the PR has.

Mechanical values (`/mechanical/<i>` on a filament, manual section "Mechanical data")
are checked the same way and listed in the same section: fetch the data sheet, and
return `ok` only if the quote is on it and the value, `plus_minus` and `unit` are as
printed, for the `direction` (X-Y, Z...) and `condition` the entry names. Units are
never converted. Never propose mechanical values in `enrichments`.

## Proof mode: the contributor's values

The context may list "Values to prove": values this PR sets that a script can check.
Expand Down
4 changes: 4 additions & 0 deletions ofd/review/suggest.py
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,10 @@ def build_suggestions(enrichments: list[dict], changes: list[ChangedFile]) -> Ou
):
outcome.rejected.append((enrichment, "sustainability data is never suggested"))
continue
# Mechanical values are copied from the data sheet with a quote, never guessed.
if pointer == "/mechanical" or pointer.startswith("/mechanical/"):
outcome.rejected.append((enrichment, "mechanical data is never suggested"))
continue
grouped.setdefault(enrichment["path"], []).append(enrichment)

key_order = build_key_order_map(SCHEMAS_DIR)
Expand Down
66 changes: 55 additions & 11 deletions ofd/review/sustainability.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@
sustainability data and changes to the sustainability rules themselves all fail it.
Only a maintainer's ``sustainability-verified`` label overrides it, and the review
workflow drops that label again on every push that touches sustainability data.

Mechanical values (``mechanical`` on filaments) are sourced the same way, from the
brand's data sheet, so the gate checks them too: the quote must be on the sheet and
hold the value and its ``±`` as written.
"""

import json
Expand All @@ -31,6 +35,7 @@

from ofd.enrich.verify import Fetcher, Page, as_sites, normalize, number_in, site_name
from ofd.review.gitdata import ChangedFile, TreeReader
from ofd.validation.data_quality import GROUPED_UNITS, MECHANICAL_VALUES, _number_pattern

STATUS_CONTEXT = "Sustainability sources"
OVERRIDE_LABEL = "sustainability-verified"
Expand Down Expand Up @@ -58,6 +63,7 @@
# to look at it.
RULE_PATHS = (
"schemas/sustainability_schema.json",
"schemas/mechanical_schema.json",
"schemas/material_defaults_schema.json",
"reference/",
"ofd/review/sustainability.py",
Expand Down Expand Up @@ -94,9 +100,33 @@ def to_dict(self) -> dict:
return asdict(self)


def is_sourced_pointer(pointer: str) -> bool:
"""A JSON pointer into sourced data: sustainability, container_details or mechanical."""
return (
"sustainability" in pointer
or "container_details" in pointer
or pointer == "/mechanical"
or pointer.startswith("/mechanical/")
)


def _value_fields(section: str) -> tuple[str, ...]:
if section == "container_details":
return CONTAINER_VALUES
if section == "mechanical":
return MECHANICAL_VALUES
return SECTIONS[section]


def entries_in(doc, kind: str) -> list[tuple[str, str, dict]]:
"""``(pointer, section, entry)`` for every sourced entry in one document."""
found: list[tuple[str, str, dict]] = []
if kind == "filament" and isinstance(doc, dict) and isinstance(doc.get("mechanical"), list):
found += [
(f"/mechanical/{i}", "mechanical", item)
for i, item in enumerate(doc["mechanical"])
if isinstance(item, dict)
]
if kind in ("filament", "variant") and isinstance(doc, dict):
block = doc.get("sustainability")
if isinstance(block, dict):
Expand Down Expand Up @@ -198,8 +228,12 @@ def _fragments(quote: str) -> list[str]:
return [f.strip() for f in re.split(r"…|\.\.\.|\[\.\.\.\]", normalize(quote)) if f.strip()]


def check_quote(quote: str, values: list, page: Page) -> list[str]:
"""Errors for a quote that isn't on ``page`` the way the entry uses it."""
def check_quote(quote: str, values: list, page: Page, number_in=number_in) -> list[str]:
"""Errors for a quote that isn't on ``page`` the way the entry uses it.

``number_in(value, text)`` finds a value in a quote fragment; mechanical entries pass
the validator's matcher, which knows the thousands their unit groups (7,250 psi).
"""
fragments = _fragments(quote)
if not fragments:
return ["source_quote is empty"]
Expand Down Expand Up @@ -234,12 +268,9 @@ def verify_entry(entry: Entry, fetcher: Fetcher, brand_site) -> None:
data = entry.data
url = data.get("source_url") or ""
quote = data.get("source_quote") or ""
value_fields = (
CONTAINER_VALUES if entry.section == "container_details" else SECTIONS[entry.section]
)
values = [
data[f]
for f in value_fields
for f in _value_fields(entry.section)
if isinstance(data.get(f), (int, float)) and not isinstance(data.get(f), bool)
]

Expand Down Expand Up @@ -271,7 +302,13 @@ def verify_entry(entry: Entry, fetcher: Fetcher, brand_site) -> None:
f"and add the `{OVERRIDE_LABEL}` label if it is right"
)
return
entry.errors += check_quote(quote, values, page)
if entry.section == "mechanical":
grouped = data.get("unit") in GROUPED_UNITS
entry.errors += check_quote(
quote, values, page, lambda v, text: bool(_number_pattern(v, grouped).search(text))
)
else:
entry.errors += check_quote(quote, values, page)
q = normalize(quote)

# Details that, when given, must come from the source (rule 1: never invent).
Expand Down Expand Up @@ -444,9 +481,7 @@ def model_problems(touch: Touch, model: dict | None) -> list[str]:
problems.append(f"AI: {verdict.get('summary') or verdict.get('verdict')}")
for finding in model.get("findings") or []:
pointer = finding.get("pointer") or ""
if finding.get("severity") == "error" and (
"sustainability" in pointer or "container_details" in pointer
):
if finding.get("severity") == "error" and is_sourced_pointer(pointer):
problems.append(f"AI: `{finding.get('path')}` `{pointer}`: {finding.get('message')}")
return problems

Expand All @@ -457,7 +492,9 @@ def gate(touch: Touch, model: dict | None, override: str | None = None) -> dict:
for entry in touch.entries:
failures += [f"`{entry.path}` `{entry.pointer}`: {e}" for e in entry.errors]
failures += [
f"`{e.path}` `{e.pointer}`: sustainability data removed; a maintainer must confirm"
f"`{e.path}` `{e.pointer}`: "
f"{'mechanical' if e.section == 'mechanical' else 'sustainability'} data removed; "
"a maintainer must confirm"
for e in touch.removed
]
failures += [
Expand Down Expand Up @@ -501,6 +538,13 @@ def context_section(touch: Touch) -> str:
"using exactly the path and pointer shown. Fetch each source_url yourself.",
"",
]
if any(e.section == "mechanical" for e in touch.entries + touch.removed):
lines += [
"Entries under `/mechanical/` are values from the brand's data sheet. The same "
"rules apply: the quote is on the sheet, and the value, its `±` and unit are as "
"printed there, for the print direction and conditions the entry names.",
"",
]
for entry in touch.entries:
lines.append(f"### `{entry.path}` `{entry.pointer}` ({entry.status})")
lines.append(f"```json\n{json.dumps(entry.data, indent=2, ensure_ascii=False)}\n```")
Expand Down
7 changes: 4 additions & 3 deletions ofd/review/triage.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
from ofd.review.checks import ENRICHABLE
from ofd.review.gitdata import ChangedFile
from ofd.review.jsonlines import resolve
from ofd.review.sustainability import is_sourced_pointer

# A finding that only asks someone else to do the checking.
_ASKS_TO_CHECK = re.compile(
Expand Down Expand Up @@ -68,9 +69,9 @@ def _about_empty_field(finding: dict, change: ChangedFile | None) -> bool:
def drop_reason(finding: dict, change: ChangedFile | None) -> str | None:
"""Why a model finding shouldn't be posted, or None to keep it."""
pointer = finding.get("pointer") or ""
# Evidence-backed findings are judged by a script, and sustainability findings
# feed the gate: neither is ever dropped here.
if finding.get("evidence") or "sustainability" in pointer or "container_details" in pointer:
# Evidence-backed findings are judged by a script, and sustainability and mechanical
# findings feed the gate: neither is ever dropped here.
if finding.get("evidence") or is_sourced_pointer(pointer):
return None
message = finding.get("message") or ""
if _TRACKING.search(message):
Expand Down
19 changes: 19 additions & 0 deletions ofd/scripts/style_data.py
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,7 @@ def sanitize_data(data: Any, schema_name: str) -> tuple[Any, list[str]]:
- sizes: default sizes[].diameter from 0 to 1.75; sanitize nested
purchase_links and container_details dicts.
- filament/variant: sanitize the sourced entries inside ``sustainability``.
- filament: sanitize each sourced entry in ``mechanical``.
"""
changes: list[str] = []

Expand Down Expand Up @@ -285,6 +286,7 @@ def sanitize_data(data: Any, schema_name: str) -> tuple[Any, list[str]]:

_sanitize_dict(data, changes)
_sanitize_sustainability(data.get("sustainability"), changes)
_sanitize_mechanical(data.get("mechanical"), changes)
return data, changes

return data, changes
Expand All @@ -303,6 +305,23 @@ def _sanitize_sustainability(sustainability: Any, changes: list[str]) -> None:
_sanitize_dict(item, changes, f"sustainability.{section}[{i}]")


def _sanitize_mechanical(mechanical: Any, changes: list[str]) -> None:
Comment thread
percosys marked this conversation as resolved.
Resolved
"""Sanitize each sourced entry in a filament's ``mechanical`` array."""
if not isinstance(mechanical, list):
return
for i, item in enumerate(mechanical):
if not isinstance(item, dict):
continue
_sanitize_dict(item, changes, f"mechanical[{i}]")
specimen = item.get("specimen")
if isinstance(specimen, dict):
_sanitize_dict(specimen, changes, f"mechanical[{i}].specimen")
# Every specimen field is optional: an empty one says nothing.
for key in [k for k, v in specimen.items() if v == ""]:
del specimen[key]
changes.append(f"mechanical[{i}].specimen.{key}: removed empty string")


def _sanitize_dict(data: dict[str, Any], changes: list[str], prefix: str = "") -> None:
"""Sanitize string fields in a dict in-place."""
dot = f"{prefix}." if prefix else ""
Expand Down
Loading
Loading