armor-agent-plugin 6.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of armor-agent-plugin might be problematic. Click here for more details.

Files changed (50) hide show
  1. armor/__init__.py +9 -0
  2. armor/__main__.py +3 -0
  3. armor/cli.py +209 -0
  4. armor/data/ai_standards/_catalog/latest.json +7 -0
  5. armor/data/ai_standards/_catalog/versions/2026-05-14__b1ed6db3/guardrail_catalog.json +1517 -0
  6. armor/data/ai_standards/_catalog/versions/2026-05-14__b1ed6db3/guardrail_catalog.md +345 -0
  7. armor/data/ai_standards/_catalog/versions/2026-05-14__b1ed6db3/guardrail_matrix.csv +54 -0
  8. armor/data/ai_standards/_catalog/versions/2026-05-14__b1ed6db3/guardrail_matrix.json +1446 -0
  9. armor/data/ai_standards/_catalog/versions/2026-05-14__b1ed6db3/guardrail_matrix.md +57 -0
  10. armor/data/ai_standards/_catalog/versions/2026-05-14__b1ed6db3/manifest.json +29 -0
  11. armor/data/ai_standards/_catalog/versions/2026-05-14__b1ed6db3/source_coverage.json +360 -0
  12. armor/data/ai_standards/eu-ai-act/history.jsonl +1 -0
  13. armor/data/ai_standards/eu-ai-act/latest.json +7 -0
  14. armor/data/ai_standards/eu-ai-act/versions/2026-06-04__e1a1c700/manifest.json +5 -0
  15. armor/data/ai_standards/mitre-atlas/history.jsonl +1 -0
  16. armor/data/ai_standards/mitre-atlas/latest.json +7 -0
  17. armor/data/ai_standards/mitre-atlas/versions/2026-06-04__32346fb3/manifest.json +5 -0
  18. armor/data/ai_standards/nist-ai-rmf/history.jsonl +1 -0
  19. armor/data/ai_standards/nist-ai-rmf/latest.json +7 -0
  20. armor/data/ai_standards/nist-ai-rmf/versions/2026-06-04__b157a100/manifest.json +5 -0
  21. armor/data/ai_standards/owasp-llm-top10/history.jsonl +1 -0
  22. armor/data/ai_standards/owasp-llm-top10/latest.json +7 -0
  23. armor/data/ai_standards/owasp-llm-top10/versions/2026-06-04__0a592025/manifest.json +5 -0
  24. armor/file_lock.py +114 -0
  25. armor/pipeline/__init__.py +17 -0
  26. armor/pipeline/adversary.py +140 -0
  27. armor/pipeline/conform.py +259 -0
  28. armor/pipeline/conform_audit.py +192 -0
  29. armor/pipeline/load.py +94 -0
  30. armor/pipeline/report.py +357 -0
  31. armor/pipeline/schema.py +113 -0
  32. armor/pipeline/schemas/posture_report.schema.json +400 -0
  33. armor/pipeline/state.py +182 -0
  34. armor/pipeline/triage.py +225 -0
  35. armor/pipeline/triage_audit.py +153 -0
  36. armor_agent_plugin-6.0.0.dist-info/METADATA +574 -0
  37. armor_agent_plugin-6.0.0.dist-info/RECORD +50 -0
  38. armor_agent_plugin-6.0.0.dist-info/WHEEL +5 -0
  39. armor_agent_plugin-6.0.0.dist-info/entry_points.txt +2 -0
  40. armor_agent_plugin-6.0.0.dist-info/licenses/LICENSE +21 -0
  41. armor_agent_plugin-6.0.0.dist-info/top_level.txt +2 -0
  42. catalog/__init__.py +1 -0
  43. catalog/ai_standards_versioning.py +114 -0
  44. catalog/download_aiid_slim.py +90 -0
  45. catalog/download_eu_ai_act_cellar.py +86 -0
  46. catalog/download_mitre_atlas.py +78 -0
  47. catalog/download_nist_ai_rmf.py +77 -0
  48. catalog/download_owasp_llm_top10.py +71 -0
  49. catalog/generate_guardrail_catalog.py +990 -0
  50. catalog/refresh_catalog.py +77 -0
armor/pipeline/load.py ADDED
@@ -0,0 +1,94 @@
1
+ """Phase 1: Load and normalise the AI/agentic standards guardrail catalog."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ from .state import RunDir
10
+
11
+
12
+ def _find_default_catalog() -> Path:
13
+ # 1. Bundled inside the installed `armor` package (PyPI wheel / sdist)
14
+ pkg_cand = Path(__file__).resolve().parents[1] / "data" / "ai_standards" / "_catalog" / "latest.json"
15
+ if pkg_cand.is_file():
16
+ data = json.loads(pkg_cand.read_text(encoding="utf-8"))
17
+ return pkg_cand.parent / "versions" / data["version"] / "guardrail_matrix.json"
18
+
19
+ # 2. Marketplace plugin layout (<skill_root>/references/ai_standards/_catalog/latest.json)
20
+ parents = Path(__file__).resolve().parents
21
+ if len(parents) > 3:
22
+ skill_root = parents[3]
23
+ cand = skill_root / "references" / "ai_standards" / "_catalog" / "latest.json"
24
+ if cand.is_file():
25
+ data = json.loads(cand.read_text(encoding="utf-8"))
26
+ return cand.parent / "versions" / data["version"] / "guardrail_matrix.json"
27
+
28
+ # 3. Walk parents looking for ai_standards/_catalog/latest.json
29
+ for parent in parents:
30
+ for rel in (
31
+ Path("references") / "ai_standards" / "_catalog" / "latest.json",
32
+ Path("ai_standards") / "_catalog" / "latest.json",
33
+ ):
34
+ p = parent / rel
35
+ if p.is_file():
36
+ data = json.loads(p.read_text(encoding="utf-8"))
37
+ return p.parent / "versions" / data["version"] / "guardrail_matrix.json"
38
+
39
+ raise SystemExit("default catalog not found; pass --catalog PATH")
40
+
41
+
42
+ def _resolve_catalog(catalog_arg: str | Path | None) -> Path:
43
+ if catalog_arg is not None:
44
+ p = Path(catalog_arg).resolve()
45
+ if not p.is_file():
46
+ raise SystemExit(f"catalog file not found: {p}")
47
+ if p.name == "latest.json":
48
+ data = json.loads(p.read_text(encoding="utf-8"))
49
+ return (p.parent / "versions" / data["version"] / "guardrail_matrix.json").resolve()
50
+ return p
51
+ return _find_default_catalog().resolve()
52
+
53
+
54
+ def run(
55
+ project: Path,
56
+ catalog_arg: str | Path | None = None,
57
+ run_dir: RunDir | None = None,
58
+ ) -> dict[str, Any]:
59
+ if run_dir is None:
60
+ from .state import current_run
61
+ run_dir = current_run(project)
62
+
63
+ catalog_path = _resolve_catalog(catalog_arg)
64
+ raw = json.loads(catalog_path.read_text(encoding="utf-8"))
65
+
66
+ guardrails: list[dict[str, Any]] = []
67
+ for row in raw.get("sub_guardrails", []):
68
+ num = str(row["number"])
69
+ family = num.split(".", 1)[0] if "." in num else num
70
+ guardrails.append(
71
+ {
72
+ "sid": num,
73
+ "family": family,
74
+ "family_name": row.get("category", ""),
75
+ "description": row.get("description", ""),
76
+ "verification_test": row.get("verification_test", ""),
77
+ "applicability_hint": row.get("applicability", ""),
78
+ "implementation_hints": row.get("implementation_hints", ""),
79
+ "standard_refs": row.get("standard_references", ""),
80
+ }
81
+ )
82
+
83
+ catalog_sha = str(raw.get("source_sha") or raw.get("sha") or "")
84
+ artifact: dict[str, Any] = {
85
+ "phase": "load",
86
+ "catalog_path": str(catalog_path),
87
+ "catalog_sha": catalog_sha,
88
+ "count": len(guardrails),
89
+ "guardrails": guardrails,
90
+ }
91
+
92
+ art_path = run_dir.artifact("load")
93
+ art_path.write_text(json.dumps(artifact, indent=2) + "\n", encoding="utf-8")
94
+ return artifact
@@ -0,0 +1,357 @@
1
+ """Phase 6: Deterministic posture report rollup, coverage calculation, and schema validation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import datetime, timezone
6
+ import json
7
+ from pathlib import Path
8
+ import shutil
9
+ from typing import Any
10
+
11
+ from .schema import validate_artifact
12
+ from .state import RunDir, _armor_dir, require_phase_done
13
+
14
+ VERDICT_WEIGHT: dict[str, float] = {
15
+ "implemented": 1.0,
16
+ "partial": 0.6,
17
+ "weak": 0.3,
18
+ "gap": 0.0,
19
+ "inconclusive": 0.0,
20
+ }
21
+
22
+ _SUGGESTION_KIND_ORDER: dict[str, int] = {
23
+ "gap": 0,
24
+ "inconclusive": 1,
25
+ "weak": 2,
26
+ "partial": 3,
27
+ }
28
+
29
+
30
+ def _coverage(rows: list[dict[str, Any]]) -> dict[str, Any]:
31
+ in_scope = [r for r in rows if r["verdict"] != "n/a"]
32
+ max_pts = float(len(in_scope))
33
+ earned = round(sum(VERDICT_WEIGHT.get(r["verdict"], 0.0) for r in in_scope), 4)
34
+ overall_pct = round(100.0 * earned / max_pts, 1) if max_pts > 0 else 0.0
35
+
36
+ by_verdict_in_scope: dict[str, int] = {}
37
+ for r in in_scope:
38
+ v = r["verdict"]
39
+ by_verdict_in_scope[v] = by_verdict_in_scope.get(v, 0) + 1
40
+
41
+ fam_groups: dict[str, list[dict[str, Any]]] = {}
42
+ fam_names: dict[str, str] = {}
43
+ for r in in_scope:
44
+ fam = r["family"]
45
+ fam_names[fam] = r.get("family_name", "")
46
+ fam_groups.setdefault(fam, []).append(r)
47
+
48
+ by_family: list[dict[str, Any]] = []
49
+ for fam, frows in fam_groups.items():
50
+ f_max = float(len(frows))
51
+ f_earned = round(sum(VERDICT_WEIGHT.get(r["verdict"], 0.0) for r in frows), 4)
52
+ f_pct = round(100.0 * f_earned / f_max, 1) if f_max > 0 else 0.0
53
+ by_family.append(
54
+ {
55
+ "family": fam,
56
+ "family_name": fam_names.get(fam, ""),
57
+ "in_scope": len(frows),
58
+ "earned": f_earned,
59
+ "max": f_max,
60
+ "score_pct": f_pct,
61
+ }
62
+ )
63
+
64
+ by_family.sort(key=lambda item: (item["score_pct"], item["family"]))
65
+
66
+ return {
67
+ "overall_pct": overall_pct,
68
+ "applicable_only_pct": overall_pct,
69
+ "in_scope_count": len(in_scope),
70
+ "max_possible_points": max_pts,
71
+ "earned_points": earned,
72
+ "by_verdict_in_scope": by_verdict_in_scope,
73
+ "by_family": by_family,
74
+ }
75
+
76
+
77
+ def _suggestions(rows: list[dict[str, Any]], coverage: dict[str, Any]) -> list[dict[str, Any]]:
78
+ fam_score_map = {f["family"]: f["score_pct"] for f in coverage.get("by_family", [])}
79
+ actionable: list[dict[str, Any]] = []
80
+
81
+ for r in rows:
82
+ verdict = r["verdict"]
83
+ if verdict not in _SUGGESTION_KIND_ORDER:
84
+ continue
85
+ pts_unlocked = round(1.0 - VERDICT_WEIGHT[verdict], 2)
86
+ rem = str(r.get("remediation") or "").strip()
87
+ if rem:
88
+ action = rem
89
+ elif verdict == "inconclusive":
90
+ action = (
91
+ f"Re-assess {r['sid']} and attach valid relative/path.ext:line citations "
92
+ "under project_root."
93
+ )
94
+ else:
95
+ action = f"No remediation supplied for {r['sid']}; implement controls satisfying the guardrail."
96
+
97
+ fam = r["family"]
98
+ fam_pct = fam_score_map.get(fam, 0.0)
99
+ actionable.append(
100
+ {
101
+ "sid": r["sid"],
102
+ "family": fam,
103
+ "family_name": r.get("family_name", ""),
104
+ "current_verdict": verdict,
105
+ "points_unlocked": pts_unlocked,
106
+ "family_score_pct": fam_pct,
107
+ "action": action,
108
+ "gap_summary": str(r.get("gap_summary") or ""),
109
+ "remediation": rem,
110
+ "reasoning": str(r.get("reasoning") or ""),
111
+ }
112
+ )
113
+
114
+ actionable.sort(
115
+ key=lambda s: (
116
+ -s["points_unlocked"],
117
+ s["family_score_pct"],
118
+ _SUGGESTION_KIND_ORDER[s["current_verdict"]],
119
+ s["sid"],
120
+ )
121
+ )
122
+ return actionable
123
+
124
+
125
+ def _render_md(artifact: dict[str, Any]) -> str:
126
+ cov = artifact["coverage"]
127
+ totals = artifact["totals"]
128
+ lines: list[str] = [
129
+ "# ARMOR v6 — AI Guardrail Posture Report",
130
+ "",
131
+ f"- **Generated at**: {artifact['generated_at']}",
132
+ f"- **Project**: `{artifact['project']}`",
133
+ f"- **Run dir**: `{artifact['run_dir']}`",
134
+ "",
135
+ "## Coverage",
136
+ "",
137
+ f"- **Overall score**: **{cov['overall_pct']}%** ({cov['earned_points']} / {cov['max_possible_points']} points across {cov['in_scope_count']} in-scope guardrails)",
138
+ "- _Weighting_: `implemented=1.0`, `partial=0.6`, `weak=0.3`, `gap=0.0`, `inconclusive=0.0` (`n/a` excluded from denominator).",
139
+ "",
140
+ "### Coverage by Family (weakest first)",
141
+ "",
142
+ "| Family | Name | In-Scope | Earned | Max | Score % |",
143
+ "| --- | --- | --- | --- | --- | --- |",
144
+ ]
145
+ for fam in cov.get("by_family", []):
146
+ lines.append(
147
+ f"| {fam['family']} | {fam['family_name']} | {fam['in_scope']} | {fam['earned']} | {fam['max']} | {fam['score_pct']}% |"
148
+ )
149
+
150
+ lines.extend(
151
+ [
152
+ "",
153
+ "## Ranked Remediation Suggestions",
154
+ "",
155
+ "| SID | Family | Verdict | Points Unlocked | Action |",
156
+ "| --- | --- | --- | --- | --- |",
157
+ ]
158
+ )
159
+ for s in artifact.get("suggestions", []):
160
+ act = str(s["action"]).replace("|", "\\|").replace("\n", " ")
161
+ lines.append(
162
+ f"| {s['sid']} | {s['family']} | {s['current_verdict']} | +{s['points_unlocked']} | {act} |"
163
+ )
164
+
165
+ lines.extend(
166
+ [
167
+ "",
168
+ "## Totals",
169
+ "",
170
+ f"- **Total guardrails**: {totals['guardrails']}",
171
+ f"- **By applicability**: `{json.dumps(totals['by_applicability'], sort_keys=True)}`",
172
+ f"- **By verdict**: `{json.dumps(totals['by_verdict'], sort_keys=True)}`",
173
+ f"- **Gaps**: {totals['gaps']}",
174
+ f"- **Weak or partial**: {totals['weak_or_partial']}",
175
+ f"- **Inconclusive**: {totals['inconclusive']}",
176
+ f"- **Open questions**: {totals['open_questions']}",
177
+ "",
178
+ "## System Profile",
179
+ "",
180
+ "```json",
181
+ json.dumps(artifact.get("system_profile", {}), indent=2),
182
+ "```",
183
+ "",
184
+ "## Findings by Category",
185
+ "",
186
+ "### Gaps",
187
+ "",
188
+ ]
189
+ )
190
+ rows = artifact.get("rows", [])
191
+ gaps = [r for r in rows if r["verdict"] == "gap"]
192
+ if gaps:
193
+ for r in gaps:
194
+ lines.append(f"- **{r['sid']}** ({r['family_name']}): {r.get('gap_summary') or r.get('reasoning')}")
195
+ else:
196
+ lines.append("_None._")
197
+
198
+ lines.extend(["", "### Partial / Weak", ""])
199
+ pw = [r for r in rows if r["verdict"] in ("partial", "weak")]
200
+ if pw:
201
+ for r in pw:
202
+ lines.append(f"- **{r['sid']}** [{r['verdict']}]: {r.get('reasoning')}")
203
+ else:
204
+ lines.append("_None._")
205
+
206
+ lines.extend(["", "### Inconclusive", ""])
207
+ inc = [r for r in rows if r["verdict"] == "inconclusive"]
208
+ if inc:
209
+ for r in inc:
210
+ marker = " *(demoted)*" if r.get("demoted_due_to_hallucination") else ""
211
+ lines.append(f"- **{r['sid']}**{marker}: {r.get('reasoning')}")
212
+ else:
213
+ lines.append("_None._")
214
+
215
+ lines.extend(["", "### Open Questions", ""])
216
+ open_q = artifact.get("open_questions", [])
217
+ if open_q:
218
+ for q in open_q:
219
+ lines.append(f"- **{q.get('sid', '')}**: {q.get('critique', '')}")
220
+ else:
221
+ lines.append("_None._")
222
+
223
+ lines.extend(
224
+ [
225
+ "",
226
+ "## All Guardrails",
227
+ "",
228
+ "| SID | Family | Applicability | Verdict | Citations |",
229
+ "| --- | --- | --- | --- | --- |",
230
+ ]
231
+ )
232
+ for r in rows:
233
+ v = r["verdict"]
234
+ if r.get("demoted_due_to_hallucination"):
235
+ v = f"{v} *(demoted)*"
236
+ cits = ", ".join(r.get("citations", []))
237
+ lines.append(f"| {r['sid']} | {r['family']} | {r['applicability']} | {v} | {cits} |")
238
+ lines.append("")
239
+ return "\n".join(lines)
240
+
241
+
242
+ def run(project: Path, run_dir: RunDir | None = None) -> dict[str, Any]:
243
+ if run_dir is None:
244
+ from .state import current_run
245
+ run_dir = current_run(project)
246
+
247
+ loaded = require_phase_done(run_dir, "load")
248
+ triage_audit = require_phase_done(run_dir, "triage-audit")
249
+ conform_audit = require_phase_done(run_dir, "conform-audit")
250
+
251
+ triage_by_sid = {r["sid"]: r for r in triage_audit.get("applicability", [])}
252
+ conform_by_sid = {r["sid"]: r for r in conform_audit.get("rows", [])}
253
+
254
+ rows: list[dict[str, Any]] = []
255
+ by_applicability: dict[str, int] = {}
256
+ by_verdict: dict[str, int] = {}
257
+
258
+ for cat in loaded.get("guardrails", []):
259
+ sid = cat["sid"]
260
+ t_row = triage_by_sid.get(sid, {})
261
+ app_status = t_row.get("status", "unknown")
262
+ if app_status not in ("applies", "partial_scope", "n_a", "unknown"):
263
+ app_status = "unknown"
264
+ app_reason = str(t_row.get("reason") or "")
265
+
266
+ c_row = conform_by_sid.get(sid, {})
267
+ if app_status == "n_a":
268
+ verdict = "n/a"
269
+ reasoning = app_reason
270
+ citations: list[str] = []
271
+ gap_summary = ""
272
+ remediation = ""
273
+ demoted = False
274
+ else:
275
+ verdict = str(c_row.get("verdict") or "inconclusive")
276
+ if verdict not in ("implemented", "partial", "weak", "gap", "inconclusive", "n/a"):
277
+ verdict = "inconclusive"
278
+ reasoning = str(c_row.get("reasoning") or "")
279
+ citations = list(c_row.get("citations") or [])
280
+ gap_summary = str(c_row.get("gap_summary") or "")
281
+ remediation = str(c_row.get("remediation") or "")
282
+ demoted = bool(c_row.get("demoted_due_to_hallucination", False))
283
+
284
+ by_applicability[app_status] = by_applicability.get(app_status, 0) + 1
285
+ by_verdict[verdict] = by_verdict.get(verdict, 0) + 1
286
+
287
+ rows.append(
288
+ {
289
+ "sid": sid,
290
+ "family": cat.get("family", ""),
291
+ "family_name": cat.get("family_name", ""),
292
+ "description": cat.get("description", ""),
293
+ "applicability": app_status,
294
+ "applicability_reason": app_reason,
295
+ "verdict": verdict,
296
+ "reasoning": reasoning,
297
+ "citations": citations,
298
+ "gap_summary": gap_summary,
299
+ "remediation": remediation,
300
+ "demoted_due_to_hallucination": demoted,
301
+ }
302
+ )
303
+
304
+ open_questions: list[dict[str, Any]] = list(triage_audit.get("open_questions", [])) + list(
305
+ conform_audit.get("open_questions", [])
306
+ )
307
+
308
+ coverage = _coverage(rows)
309
+ suggestions = _suggestions(rows, coverage)
310
+
311
+ totals = {
312
+ "guardrails": len(rows),
313
+ "by_applicability": by_applicability,
314
+ "by_verdict": by_verdict,
315
+ "gaps": by_verdict.get("gap", 0),
316
+ "weak_or_partial": by_verdict.get("weak", 0) + by_verdict.get("partial", 0),
317
+ "inconclusive": by_verdict.get("inconclusive", 0),
318
+ "open_questions": len(open_questions),
319
+ }
320
+
321
+ ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H-%M-%SZ")
322
+ artifact: dict[str, Any] = {
323
+ "phase": "report",
324
+ "generated_at": ts,
325
+ "project": str(project.resolve()),
326
+ "run_dir": str(run_dir.root.resolve()),
327
+ "system_profile": triage_audit.get("system_profile", {}),
328
+ "totals": totals,
329
+ "coverage": coverage,
330
+ "suggestions": suggestions,
331
+ "open_questions": open_questions,
332
+ "rows": rows,
333
+ }
334
+
335
+ # Validate against Pydantic PostureReport contract before writing to disk
336
+ validate_artifact(artifact)
337
+
338
+ art_json_text = json.dumps(artifact, indent=2) + "\n"
339
+ md_text = _render_md(artifact)
340
+
341
+ art_path = run_dir.artifact("report")
342
+ art_path.write_text(art_json_text, encoding="utf-8")
343
+
344
+ reports_dir = _armor_dir(project) / "reports"
345
+ reports_dir.mkdir(parents=True, exist_ok=True)
346
+
347
+ iso_json = reports_dir / f"posture_{ts}.json"
348
+ iso_md = reports_dir / f"posture_{ts}.md"
349
+ latest_json = reports_dir / "posture_latest.json"
350
+ latest_md = reports_dir / "posture_latest.md"
351
+
352
+ iso_json.write_text(art_json_text, encoding="utf-8")
353
+ iso_md.write_text(md_text, encoding="utf-8")
354
+ shutil.copyfile(iso_json, latest_json)
355
+ shutil.copyfile(iso_md, latest_md)
356
+
357
+ return artifact
@@ -0,0 +1,113 @@
1
+ """Pydantic v2 contract for the Phase 6 PostureReport artifact and JSON Schema helper."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from pathlib import Path
7
+ from typing import Any, Literal
8
+
9
+ from pydantic import BaseModel, ConfigDict, Field
10
+
11
+ Verdict = Literal["implemented", "partial", "weak", "gap", "inconclusive", "n/a"]
12
+ Applicability = Literal["applies", "partial_scope", "n_a", "unknown"]
13
+
14
+ SCHEMA_PATH = Path(__file__).resolve().parent / "schemas" / "posture_report.schema.json"
15
+
16
+
17
+ class _Strict(BaseModel):
18
+ model_config = ConfigDict(extra="forbid")
19
+
20
+
21
+ class GuardrailRow(_Strict):
22
+ sid: str
23
+ family: str
24
+ family_name: str
25
+ description: str
26
+ applicability: Applicability
27
+ applicability_reason: str = ""
28
+ verdict: Verdict
29
+ reasoning: str = ""
30
+ citations: list[str] = Field(default_factory=list)
31
+ gap_summary: str = ""
32
+ remediation: str = ""
33
+ demoted_due_to_hallucination: bool = False
34
+
35
+
36
+ class FamilyCoverage(_Strict):
37
+ family: str
38
+ family_name: str
39
+ in_scope: int = Field(ge=0)
40
+ earned: float = Field(ge=0.0)
41
+ max: float = Field(ge=0.0)
42
+ score_pct: float = Field(ge=0.0, le=100.0)
43
+
44
+
45
+ class Coverage(_Strict):
46
+ overall_pct: float = Field(ge=0.0, le=100.0)
47
+ applicable_only_pct: float = Field(ge=0.0, le=100.0)
48
+ in_scope_count: int = Field(ge=0)
49
+ max_possible_points: float = Field(ge=0.0)
50
+ earned_points: float = Field(ge=0.0)
51
+ by_verdict_in_scope: dict[str, int]
52
+ by_family: list[FamilyCoverage]
53
+
54
+
55
+ class Suggestion(_Strict):
56
+ sid: str
57
+ family: str
58
+ family_name: str
59
+ current_verdict: Literal["gap", "inconclusive", "weak", "partial"]
60
+ points_unlocked: float = Field(ge=0.0, le=1.0)
61
+ family_score_pct: float = Field(ge=0.0, le=100.0)
62
+ action: str
63
+ gap_summary: str = ""
64
+ remediation: str = ""
65
+ reasoning: str = ""
66
+
67
+
68
+ class Totals(_Strict):
69
+ guardrails: int = Field(ge=0)
70
+ by_applicability: dict[str, int]
71
+ by_verdict: dict[str, int]
72
+ gaps: int = Field(ge=0)
73
+ weak_or_partial: int = Field(ge=0)
74
+ inconclusive: int = Field(ge=0)
75
+ open_questions: int = Field(ge=0)
76
+
77
+
78
+ class OpenQuestion(BaseModel):
79
+ model_config = ConfigDict(extra="allow")
80
+
81
+ sid: str
82
+ critique: str = ""
83
+
84
+
85
+ class PostureReport(_Strict):
86
+ phase: Literal["report"]
87
+ generated_at: str = Field(pattern=r"^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z$")
88
+ project: str
89
+ run_dir: str
90
+ system_profile: dict[str, Any]
91
+ totals: Totals
92
+ coverage: Coverage
93
+ suggestions: list[Suggestion]
94
+ open_questions: list[OpenQuestion]
95
+ rows: list[GuardrailRow]
96
+
97
+
98
+ def validate_artifact(artifact: dict[str, Any]) -> PostureReport:
99
+ return PostureReport.model_validate(artifact)
100
+
101
+
102
+ def write_schema(path: Path | None = None) -> Path:
103
+ target = Path(path) if path is not None else SCHEMA_PATH
104
+ target.parent.mkdir(parents=True, exist_ok=True)
105
+ schema = PostureReport.model_json_schema()
106
+ target.write_text(json.dumps(schema, indent=2, sort_keys=True) + "\n", encoding="utf-8")
107
+ return target
108
+
109
+
110
+ def load_schema() -> dict[str, Any]:
111
+ if not SCHEMA_PATH.is_file():
112
+ write_schema(SCHEMA_PATH)
113
+ return json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))