M1.5 — Adapter `KbRepository.upsert()` pour `structured_data`

[zestones]

Note

Milestone: M1 — Data Layer
Planning doc: docs/planning/M1-data-layer/issues.md

Scope. Modifier backend/modules/kb/repository.py :

• Étendre JSON_FIELDS pour inclure structured_data (et signal_patterns côté failures)
• Réécrire EquipmentKbUpsert Pydantic dans schemas.py :
  structured_data: EquipmentKB, raw_markdown: str | None,
  confidence_score: float, last_enriched_at: datetime | None,
  onboarding_complete: bool
• Supprimer toute référence aux 3 anciens champs (nominal_specs,
  common_failure_modes, maintenance_recommendations) dans schemas.py,
  repository.py, router.py. Pas de retro-compat (cf. M1.1, on drop la DB).

Note

Decided — pas de retro-compat.
Suppression complète des 3 anciens champs
dans le code. Une seule source : structured_data.

Acceptance.

• PUT /api/v1/kb/equipment avec body contenant structured_data persiste correctement
• GET /api/v1/kb/equipment/2 retourne le structured_data parsé
• Test : roundtrip Pydantic → JSON → DB → JSON → Pydantic identique

---

[zestones]

Follow-up from M1.1 (#2)

Warning

M1.1 (migration 007) dropped nominal_specs, common_failure_modes, maintenance_recommendations from equipment_kb and added structured_data + 4 others. The Python layer still references the old columns. It doesn't crash today because decode_record / encode_fields are defensive and Pydantic ignores unknown fields by default — but any write path is silently broken (inserts will SQL-error on the dropped columns) and reads return stale-shaped DTOs. This must be fixed before M2/M3 land.

Concrete patch points

Note

All paths below are post-M1.1.

backend/modules/kb/schemas.py

• EquipmentKbOut (lines 16-30): remove nominal_specs, common_failure_modes, maintenance_recommendations; add structured_data: EquipmentKB, raw_markdown: str | None, confidence_score: float, last_enriched_at: datetime | None, onboarding_complete: bool
• EquipmentKbUpsert (lines 33-43): same swap

backend/modules/kb/repository.py

• JSON_FIELDS tuple (lines 12-17): replace the 3 old entries with "structured_data" (keep "parts_replaced" for the failure-history path)
• upsert() (lines 36-52): no structural change needed, but verify the ON CONFLICT SET clause covers the new columns

backend/modules/kb/router.py

• Should be drop-in once schemas + repository are updated (the router only goes through _ser_kb)

backend/tests/e2e_smoke.sh (lines 131-136)

• Currently posts nominal_specs / common_failure_modes — will break. Rewrite to post a valid structured_data patch instead.

Validation dependency

This issue depends on M1.4 (#5) — the new EquipmentKbUpsert.structured_data: EquipmentKB field requires the EquipmentKB Pydantic class to exist.

flowchart LR
    M11["#2 M1.1<br/>Migration 007<br/>(DONE)"] --> M14["#5 M1.4<br/>EquipmentKB Pydantic"]
    M14 --> M15["#6 M1.5<br/>KbRepository + schemas<br/>(this issue)"]
    M15 --> M2["M2 MCP tools<br/>get_equipment_kb /<br/>update_equipment_kb"]
    M15 --> E2E["e2e_smoke.sh<br/>rewrite lines 131-136"]

Loading

Planning doc typo (minor)

Note

docs/planning/M1-data-layer/issues.md line 43 says make reset-db — the real Makefile target is make db.reset. Worth fixing in the same PR since M1.5 touches this area.

Added tasks

• Drop legacy field refs from schemas.py, repository.py
• Roundtrip test: PUT /api/v1/kb/equipment with a full structured_data body → GET /api/v1/kb/equipment/<cell_id> returns an identical parsed blob
• Rewrite backend/tests/e2e_smoke.sh lines 131-136 to use structured_data
• Fix make reset-db → make db.reset in docs/planning/M1-data-layer/issues.md line 43

[zestones]

Resolution

Note

All acceptance criteria met. Quality gates: 0 lint errors, 0 pyright errors, 9/9 unit tests pass.

Changes applied

backend/modules/kb/schemas.py

• Removed nominal_specs, common_failure_modes, maintenance_recommendations from both EquipmentKbOut and EquipmentKbUpsert
• Added structured_data: Optional[EquipmentKB], raw_markdown, confidence_score, last_enriched_at, onboarding_complete to both DTOs
• Added import for EquipmentKB from modules.kb.kb_schema

backend/modules/kb/repository.py

• Replaced the 3 legacy entries in JSON_FIELDS with "structured_data" (kept "parts_replaced" and "signal_patterns")
• upsert() required no structural change — it builds SQL dynamically from the field dict

backend/tests/e2e_smoke.sh (lines 132-136)

• Rewrote PUT body to use structured_data with a threshold blob
• Rewrote python3 roundtrip check to verify structured_data.thresholds.flow_m3h.nominal == 32

backend/tests/test_kb_schema.py

• Added test_upsert_roundtrip_structured_data: unit test covering the full encode/decode cycle (EquipmentKbUpsert → encode_fields → decode_record → EquipmentKbOut)

docs/planning/M1-data-layer/issues.md (line 43)

• Fixed typo: make reset-db → make db.reset

Roundtrip data flow

flowchart LR
    A[EquipmentKbUpsert<br/>structured_data: EquipmentKB] -->|model_dump mode=json| B[Python dict]
    B -->|encode_fields| C[JSON string in DB]
    C -->|asyncpg fetch| D[str column value]
    D -->|decode_record| E[Python dict]
    E -->|EquipmentKbOut.model_validate| F[EquipmentKbOut<br/>structured_data: EquipmentKB]

Loading

Warning

ACs 1 and 2 (PUT/GET HTTP paths) require a live DB and are covered by e2e_smoke.sh (integration). The unit roundtrip test in test_kb_schema.py covers the serialization cycle without DB access.

[zestones]

⏱️ Total tracked time: 19min 53s

#	Date	Duration
1	2026-04-22	19min 53s