aocl 0.1.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.
- aocl/__init__.py +76 -0
- aocl/assess.py +225 -0
- aocl/ledger.py +344 -0
- aocl/model.py +318 -0
- aocl/realization.py +247 -0
- aocl-0.1.0.dist-info/METADATA +103 -0
- aocl-0.1.0.dist-info/RECORD +12 -0
- aocl-0.1.0.dist-info/WHEEL +5 -0
- aocl-0.1.0.dist-info/entry_points.txt +5 -0
- aocl-0.1.0.dist-info/licenses/LICENSE +202 -0
- aocl-0.1.0.dist-info/licenses/NOTICE +25 -0
- aocl-0.1.0.dist-info/top_level.txt +1 -0
aocl/__init__.py
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
"""aocl — Autonomous Operations & Closed Loops toolkit.
|
|
2
|
+
|
|
3
|
+
Formalizes the TechNE Hub "Autonomous Operations and Closed Loops" guide
|
|
4
|
+
(v1.2.0) as a versioned, tool-supported model: L1-L5 loop maturity assessment
|
|
5
|
+
across three vectors, the informative realization heuristic, loop velocity
|
|
6
|
+
taxonomy, and a CLAM-aligned loop modeler format.
|
|
7
|
+
|
|
8
|
+
The interlock in one line: Autonomous Operations cannot exist without Closed
|
|
9
|
+
Loops — loops translate intent into action, action into observation, and
|
|
10
|
+
observation into learning.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from aocl.assess import (
|
|
14
|
+
DECISION_MODELS,
|
|
15
|
+
FRONTIERS,
|
|
16
|
+
HITL,
|
|
17
|
+
LEVEL_NAMES,
|
|
18
|
+
RULESET_VERSION,
|
|
19
|
+
VECTORS,
|
|
20
|
+
VELOCITIES,
|
|
21
|
+
assess,
|
|
22
|
+
frontier,
|
|
23
|
+
gap_notes,
|
|
24
|
+
overall_level,
|
|
25
|
+
parse_vector_scores,
|
|
26
|
+
recommended_hitl,
|
|
27
|
+
recommended_model,
|
|
28
|
+
)
|
|
29
|
+
from aocl.realization import (
|
|
30
|
+
REFERENCE_POINTS,
|
|
31
|
+
assess_position,
|
|
32
|
+
complexity_from_components,
|
|
33
|
+
effort,
|
|
34
|
+
experience_from_components,
|
|
35
|
+
nearest_reference,
|
|
36
|
+
realize,
|
|
37
|
+
required_complexity,
|
|
38
|
+
required_experience,
|
|
39
|
+
sensitivity,
|
|
40
|
+
value_band,
|
|
41
|
+
value_exponential,
|
|
42
|
+
value_logarithmic,
|
|
43
|
+
)
|
|
44
|
+
|
|
45
|
+
__version__ = "0.1.0"
|
|
46
|
+
|
|
47
|
+
__all__ = [
|
|
48
|
+
"__version__",
|
|
49
|
+
"RULESET_VERSION",
|
|
50
|
+
"VECTORS",
|
|
51
|
+
"LEVEL_NAMES",
|
|
52
|
+
"FRONTIERS",
|
|
53
|
+
"HITL",
|
|
54
|
+
"DECISION_MODELS",
|
|
55
|
+
"VELOCITIES",
|
|
56
|
+
"parse_vector_scores",
|
|
57
|
+
"overall_level",
|
|
58
|
+
"frontier",
|
|
59
|
+
"recommended_model",
|
|
60
|
+
"recommended_hitl",
|
|
61
|
+
"gap_notes",
|
|
62
|
+
"assess",
|
|
63
|
+
"realize",
|
|
64
|
+
"effort",
|
|
65
|
+
"experience_from_components",
|
|
66
|
+
"complexity_from_components",
|
|
67
|
+
"sensitivity",
|
|
68
|
+
"required_complexity",
|
|
69
|
+
"required_experience",
|
|
70
|
+
"nearest_reference",
|
|
71
|
+
"value_band",
|
|
72
|
+
"value_logarithmic",
|
|
73
|
+
"value_exponential",
|
|
74
|
+
"assess_position",
|
|
75
|
+
"REFERENCE_POINTS",
|
|
76
|
+
]
|
aocl/assess.py
ADDED
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
"""AOCL loop maturity assessment engine (OODA/MAPE decision-model guidance).
|
|
2
|
+
|
|
3
|
+
Three vectors — Goal Decisioning (GD), Data Veracity (DV), Feedback Intelligence (FI) —
|
|
4
|
+
each scored L1..L5. The loop's overall level is the WEAKEST of the three vectors.
|
|
5
|
+
See model/levels.yaml and model/vectors.yaml for the harvested definitions.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import re
|
|
11
|
+
import sys
|
|
12
|
+
|
|
13
|
+
RULESET_VERSION = "1.0.0"
|
|
14
|
+
|
|
15
|
+
VECTORS = (("GD", "Goal Decisioning"), ("DV", "Data Veracity"), ("FI", "Feedback Intelligence"))
|
|
16
|
+
LEVEL_MIN, LEVEL_MAX = 1, 5
|
|
17
|
+
|
|
18
|
+
LEVEL_NAMES = {1: "Static", 2: "Reactive", 3: "Proactive", 4: "Predictive", 5: "Pre-emptive"}
|
|
19
|
+
|
|
20
|
+
# Frontier to the next level (doc §3.3); barrier notes in parentheses.
|
|
21
|
+
FRONTIERS = {
|
|
22
|
+
1: ("Automation Frontier", "instrumentation, orchestration, rule engines — barrier: organizational trust"),
|
|
23
|
+
2: ("Prediction Frontier", "data science capability, forecast models — barrier: data quality and feature engineering"),
|
|
24
|
+
3: ("Cognition Frontier", "AI/ML infrastructure, model governance, MLOps, explainability — barriers: AI talent scarcity, non-stationary environments"),
|
|
25
|
+
4: ("Autonomy Frontier", "experimentation infrastructure, digital twins, causal inference — barrier: delegating goal-setting to machines"),
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
DECISION_MODELS = ("OODA", "MAPE") # CUSTOM passes through for CLAM compatibility but is not advised here
|
|
29
|
+
VELOCITIES = ("fast", "tactical", "slow")
|
|
30
|
+
|
|
31
|
+
HITL = {1: "HITL", 2: "HITL", 3: "HOTL", 4: "HOTL", 5: "HOOTL"}
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def parse_vector_scores(values) -> dict:
|
|
35
|
+
"""Parse 3 integers (GD, DV, FI), each 1..5."""
|
|
36
|
+
if len(values) != len(VECTORS):
|
|
37
|
+
raise SystemExit(
|
|
38
|
+
f"error: expected exactly {len(VECTORS)} vector scores (GD DV FI), got {len(values)}\n"
|
|
39
|
+
"usage: aocl-score GD DV FI (each 1..5)"
|
|
40
|
+
)
|
|
41
|
+
scores = {}
|
|
42
|
+
for (code, _name), raw in zip(VECTORS, values):
|
|
43
|
+
if isinstance(raw, bool) or not isinstance(raw, (int, str)):
|
|
44
|
+
raise SystemExit(f"error: score for {code} must be an integer, got {raw!r}")
|
|
45
|
+
try:
|
|
46
|
+
score = int(raw)
|
|
47
|
+
except ValueError:
|
|
48
|
+
raise SystemExit(f"error: score for {code} must be an integer, got {raw!r}")
|
|
49
|
+
if not LEVEL_MIN <= score <= LEVEL_MAX:
|
|
50
|
+
raise SystemExit(f"error: score for {code} must be in {LEVEL_MIN}..{LEVEL_MAX}, got {score}")
|
|
51
|
+
scores[code] = score
|
|
52
|
+
return scores
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def overall_level(vector_scores: dict) -> int:
|
|
56
|
+
"""Weakest link across the three vectors."""
|
|
57
|
+
return min(vector_scores[v] for v, _ in VECTORS)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def frontier(level: int) -> tuple[str, str] | None:
|
|
61
|
+
"""(name, barrier note) for the frontier to the next level; None at L5."""
|
|
62
|
+
return FRONTIERS.get(level)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def recommended_model(level: int, velocity: str = "tactical") -> str:
|
|
66
|
+
"""(level x velocity) -> suggested decision model. L4-L5 fast loops keep the
|
|
67
|
+
deterministic MAPE skeleton; learning lives in the Slow Loops that parametrize them."""
|
|
68
|
+
if velocity not in VELOCITIES:
|
|
69
|
+
raise SystemExit(f"error: velocity must be one of {VELOCITIES}, got {velocity!r}")
|
|
70
|
+
if level <= 3:
|
|
71
|
+
return "MAPE"
|
|
72
|
+
return "OODA" if velocity in ("tactical", "slow") else "MAPE"
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def recommended_hitl(level: int) -> str:
|
|
76
|
+
return HITL[level]
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _recommended_move(level: int) -> str:
|
|
80
|
+
return {
|
|
81
|
+
1: "stabilize: automate thresholds to reach the Automation Frontier (reactive control)",
|
|
82
|
+
2: "predict: add trend analysis and forecasting to cross the Prediction Frontier",
|
|
83
|
+
3: "learn: introduce AI/ML strategy generation to cross the Cognition Frontier",
|
|
84
|
+
4: "delegate: extend autonomy toward goal-setting across the Autonomy Frontier",
|
|
85
|
+
5: "hold: govern at the strategic level; re-review on cadence",
|
|
86
|
+
}[level]
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def gap_notes(vector_scores: dict, current: int | None) -> list[str]:
|
|
90
|
+
"""Weakest-vector, frontier, and positioning notes."""
|
|
91
|
+
notes: list[str] = []
|
|
92
|
+
level = overall_level(vector_scores)
|
|
93
|
+
weakest_code, weakest_name = min(
|
|
94
|
+
((v, n) for v, n in VECTORS if vector_scores[v] == level),
|
|
95
|
+
key=lambda t: t[0],
|
|
96
|
+
)
|
|
97
|
+
laggards = [v for v, _ in VECTORS if vector_scores[v] == level]
|
|
98
|
+
if len(laggards) < len(VECTORS):
|
|
99
|
+
names = ", ".join(n for v, n in VECTORS if v in laggards)
|
|
100
|
+
notes.append(f"weakest link: {names} at L{level} — advance the lagging vector(s) before raising the overall level")
|
|
101
|
+
if level < LEVEL_MAX:
|
|
102
|
+
name, barrier = FRONTIERS[level]
|
|
103
|
+
notes.append(f"next: {name} — {barrier}")
|
|
104
|
+
if current is not None:
|
|
105
|
+
if current == 0:
|
|
106
|
+
notes.append("no formal loop in operation: nothing is delegated to the loop yet")
|
|
107
|
+
headroom = level - current
|
|
108
|
+
if headroom > 0:
|
|
109
|
+
notes.append(f"headroom: assessed level exceeds current operation by {headroom}; raise after clean review cycles")
|
|
110
|
+
elif headroom < 0:
|
|
111
|
+
notes.append(f"over-assessment: operating level exceeds assessed level by {-headroom}; reassess the vectors or step the operation down")
|
|
112
|
+
else:
|
|
113
|
+
notes.append("operating level matches assessment: hold and review")
|
|
114
|
+
return notes
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def assess(vector_scores: dict, current: int | None = None, velocity: str = "tactical") -> dict:
|
|
118
|
+
"""Return the assessment record (the CLI --json shape). Pass-through: the vector
|
|
119
|
+
scores are echoed exactly as issued; nothing here re-scores them."""
|
|
120
|
+
level = overall_level(vector_scores)
|
|
121
|
+
return {
|
|
122
|
+
"ruleset_version": RULESET_VERSION,
|
|
123
|
+
"vector_levels": {v: vector_scores[v] for v, _ in VECTORS},
|
|
124
|
+
"level": level,
|
|
125
|
+
"current_level": current,
|
|
126
|
+
"velocity": velocity,
|
|
127
|
+
"notes": gap_notes(vector_scores, current),
|
|
128
|
+
"frontier": frontier(level)[0] if level < LEVEL_MAX else None,
|
|
129
|
+
"recommended_decision_model": recommended_model(level, velocity),
|
|
130
|
+
"hitl": recommended_hitl(level),
|
|
131
|
+
"recommended_move": _recommended_move(level),
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def render(result: dict) -> str:
|
|
136
|
+
lines = [
|
|
137
|
+
"AOCL Loop Maturity Assessment",
|
|
138
|
+
f"Ruleset version: {result['ruleset_version']}",
|
|
139
|
+
]
|
|
140
|
+
levels = result["vector_levels"]
|
|
141
|
+
for code, name in VECTORS:
|
|
142
|
+
lines.append(f" {code} {name}: L{levels[code]}")
|
|
143
|
+
lines.append(f"Overall level: L{result['level']} — {LEVEL_NAMES[result['level']]}")
|
|
144
|
+
if result["frontier"]:
|
|
145
|
+
lines.append(f"Next frontier: {result['frontier']}")
|
|
146
|
+
lines.append(f"Recommended decision model: {result['recommended_decision_model']}")
|
|
147
|
+
lines.append(f"Human interaction model: {result['hitl']}")
|
|
148
|
+
lines.append(f"Recommended move: {result['recommended_move']}")
|
|
149
|
+
if result["notes"]:
|
|
150
|
+
lines.append("Notes:")
|
|
151
|
+
lines.extend(f" - {n}" for n in result["notes"])
|
|
152
|
+
return "\n".join(lines)
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def main(argv=None) -> int:
|
|
156
|
+
argv = list(sys.argv[1:] if argv is None else argv)
|
|
157
|
+
if "--self-test" in argv:
|
|
158
|
+
return _self_test()
|
|
159
|
+
velocity = "tactical"
|
|
160
|
+
if "--velocity" in argv:
|
|
161
|
+
i = argv.index("--velocity")
|
|
162
|
+
velocity = argv[i + 1]
|
|
163
|
+
del argv[i : i + 2]
|
|
164
|
+
as_json = "--json" in argv
|
|
165
|
+
if as_json:
|
|
166
|
+
argv.remove("--json")
|
|
167
|
+
current = None
|
|
168
|
+
if "--current" in argv:
|
|
169
|
+
i = argv.index("--current")
|
|
170
|
+
try:
|
|
171
|
+
current = int(argv[i + 1])
|
|
172
|
+
except (ValueError, IndexError):
|
|
173
|
+
raise SystemExit("error: --current must be an integer 1..5 (0 = no formal loop)")
|
|
174
|
+
if not 0 <= current <= 5:
|
|
175
|
+
raise SystemExit("error: --current must be an integer 1..5 (0 = no formal loop)")
|
|
176
|
+
del argv[i : i + 2]
|
|
177
|
+
scores = parse_vector_scores(argv)
|
|
178
|
+
result = assess(scores, current=current, velocity=velocity)
|
|
179
|
+
if as_json:
|
|
180
|
+
import json
|
|
181
|
+
|
|
182
|
+
print(json.dumps(result, indent=2))
|
|
183
|
+
else:
|
|
184
|
+
print(render(result))
|
|
185
|
+
return 0
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def _self_test() -> int:
|
|
189
|
+
assert overall_level({"GD": 3, "DV": 4, "FI": 2}) == 2
|
|
190
|
+
assert overall_level({"GD": 5, "DV": 5, "FI": 5}) == 5
|
|
191
|
+
assert recommended_model(2, "fast") == "MAPE"
|
|
192
|
+
assert recommended_model(4, "slow") == "OODA"
|
|
193
|
+
assert recommended_model(5, "fast") == "MAPE"
|
|
194
|
+
assert recommended_hitl(3) == "HOTL"
|
|
195
|
+
assert recommended_hitl(5) == "HOOTL"
|
|
196
|
+
assert frontier(5) is None and frontier(1)[0] == "Automation Frontier"
|
|
197
|
+
try:
|
|
198
|
+
parse_vector_scores([6, 3, 3])
|
|
199
|
+
raise AssertionError("expected rejection of out-of-range score")
|
|
200
|
+
except SystemExit:
|
|
201
|
+
pass
|
|
202
|
+
try:
|
|
203
|
+
recommended_model(3, "hyper")
|
|
204
|
+
raise AssertionError("expected rejection of bad velocity")
|
|
205
|
+
except SystemExit:
|
|
206
|
+
pass
|
|
207
|
+
r = assess({"GD": 3, "DV": 3, "FI": 3}, current=3)
|
|
208
|
+
assert r["level"] == 3 and r["recommended_decision_model"] == "MAPE"
|
|
209
|
+
# Cross-engine version parity: site/scoring.js must carry the same literal.
|
|
210
|
+
try:
|
|
211
|
+
import os
|
|
212
|
+
|
|
213
|
+
js = os.path.join(os.path.dirname(__file__), "..", "..", "site", "scoring.js")
|
|
214
|
+
with open(js, encoding="utf-8") as fh:
|
|
215
|
+
src = fh.read()
|
|
216
|
+
match = re.search(r'RULESET_VERSION\s*=\s*"([^"]+)"', src)
|
|
217
|
+
assert match and match.group(1) == RULESET_VERSION, "site/scoring.js RULESET_VERSION drift"
|
|
218
|
+
except FileNotFoundError:
|
|
219
|
+
pass # installed wheel/binary: JS not adjacent
|
|
220
|
+
print(f"self-test OK (ruleset {RULESET_VERSION})")
|
|
221
|
+
return 0
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
if __name__ == "__main__":
|
|
225
|
+
sys.exit(main())
|
aocl/ledger.py
ADDED
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
"""AOCL loop ledger: the registry of managed closed loops (schema 1).
|
|
2
|
+
|
|
3
|
+
Validates a loop-ledger YAML file and reports organizational health:
|
|
4
|
+
validity, guardrail hygiene (L3+ loops need guardrails), review staleness,
|
|
5
|
+
and vector/level consistency. Modeled on the autonomy-ledger pattern:
|
|
6
|
+
the file declares its format with a top-level `schema:` integer.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import datetime as _dt
|
|
12
|
+
import json
|
|
13
|
+
import re
|
|
14
|
+
import sys
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
|
|
17
|
+
try:
|
|
18
|
+
import yaml
|
|
19
|
+
except ImportError: # pragma: no cover
|
|
20
|
+
sys.exit("error: pyyaml is required for aocl-ledger (pip install pyyaml)")
|
|
21
|
+
|
|
22
|
+
RULESET_VERSION = "1.0.0"
|
|
23
|
+
SUPPORTED_SCHEMA_VERSION = 1
|
|
24
|
+
|
|
25
|
+
STATES = ("designed", "validated", "published", "active", "paused", "error", "retired")
|
|
26
|
+
VELOCITIES = ("fast", "tactical", "slow")
|
|
27
|
+
ENTITY_KINDS = ("process", "capability", "system", "function")
|
|
28
|
+
DECISION_MODELS = ("OODA", "MAPE", "CUSTOM") # CUSTOM passes through for CLAM compatibility
|
|
29
|
+
HITL_MODELS = ("HITL", "HOTL", "HOOTL")
|
|
30
|
+
HITL_BY_LEVEL = {1: "HITL", 2: "HITL", 3: "HOTL", 4: "HOTL", 5: "HOOTL"}
|
|
31
|
+
|
|
32
|
+
REQUIRED_FIELDS = (
|
|
33
|
+
"id", "entity", "entity_kind", "velocity", "level",
|
|
34
|
+
"decision_model", "owner", "state",
|
|
35
|
+
)
|
|
36
|
+
OPTIONAL_FIELDS = (
|
|
37
|
+
"vector_levels", "hitl", "guardrails", "budget_end_to_end",
|
|
38
|
+
"last_review", "review_cadence_days", "notes",
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
_BUDGETS = {
|
|
42
|
+
"fast": "< 100 ms",
|
|
43
|
+
"tactical": "< 10 min",
|
|
44
|
+
"slow": "< 7 days",
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _isodate(value) -> _dt.date | None:
|
|
49
|
+
if isinstance(value, _dt.date):
|
|
50
|
+
return value
|
|
51
|
+
if isinstance(value, str):
|
|
52
|
+
try:
|
|
53
|
+
return _dt.date.fromisoformat(value)
|
|
54
|
+
except ValueError:
|
|
55
|
+
return None
|
|
56
|
+
return None
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _validate_loop(raw, index: int) -> tuple[dict, list[str], list[str]]:
|
|
60
|
+
"""Returns (loop, errors, warnings)."""
|
|
61
|
+
problems: list[str] = []
|
|
62
|
+
warnings: list[str] = []
|
|
63
|
+
if not isinstance(raw, dict):
|
|
64
|
+
return {}, [f"loops[{index}] is not a mapping"], []
|
|
65
|
+
lid = raw.get("id")
|
|
66
|
+
label = f"loop {lid!r}" if isinstance(lid, str) and lid else f"loops[{index}]"
|
|
67
|
+
|
|
68
|
+
for name in REQUIRED_FIELDS:
|
|
69
|
+
if name not in raw:
|
|
70
|
+
problems.append(f"{label}: missing required field {name!r}")
|
|
71
|
+
if problems:
|
|
72
|
+
return raw, problems, warnings
|
|
73
|
+
|
|
74
|
+
if not re.match(r"^[a-z0-9][a-z0-9-]*$", str(lid)):
|
|
75
|
+
problems.append(f"{label}: id must be a lowercase slug")
|
|
76
|
+
if raw["entity_kind"] not in ENTITY_KINDS:
|
|
77
|
+
problems.append(f"{label}: entity_kind must be one of {ENTITY_KINDS}")
|
|
78
|
+
if raw["velocity"] not in VELOCITIES:
|
|
79
|
+
problems.append(f"{label}: velocity must be one of {VELOCITIES}")
|
|
80
|
+
if raw["decision_model"] not in DECISION_MODELS:
|
|
81
|
+
problems.append(f"{label}: decision_model must be one of {DECISION_MODELS}")
|
|
82
|
+
if raw["state"] not in STATES:
|
|
83
|
+
problems.append(f"{label}: state must be one of {STATES}")
|
|
84
|
+
if not isinstance(raw["owner"], str) or not raw["owner"].strip():
|
|
85
|
+
problems.append(f"{label}: owner must be a non-empty string")
|
|
86
|
+
|
|
87
|
+
level = raw["level"]
|
|
88
|
+
if not isinstance(level, int) or isinstance(level, bool) or not 1 <= level <= 5:
|
|
89
|
+
problems.append(f"{label}: level must be an integer 1..5, got {level!r}")
|
|
90
|
+
level = None
|
|
91
|
+
|
|
92
|
+
vlevels = raw.get("vector_levels")
|
|
93
|
+
if vlevels is not None:
|
|
94
|
+
if not isinstance(vlevels, dict) or set(vlevels) != {"GD", "DV", "FI"}:
|
|
95
|
+
problems.append(f"{label}: vector_levels must be a mapping with exactly GD, DV, FI")
|
|
96
|
+
else:
|
|
97
|
+
for code, val in vlevels.items():
|
|
98
|
+
if not isinstance(val, int) or isinstance(val, bool) or not 1 <= val <= 5:
|
|
99
|
+
problems.append(f"{label}: vector_levels.{code} must be an integer 1..5")
|
|
100
|
+
if all(isinstance(v, int) and not isinstance(v, bool) and 1 <= v <= 5 for v in vlevels.values()):
|
|
101
|
+
weakest = min(vlevels.values())
|
|
102
|
+
if level is not None and level != weakest:
|
|
103
|
+
problems.append(
|
|
104
|
+
f"{label}: level {level} inconsistent with weakest vector level {weakest} "
|
|
105
|
+
"(overall level = min of GD/DV/FI)"
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
hitl = raw.get("hitl")
|
|
109
|
+
if hitl is not None:
|
|
110
|
+
if hitl not in HITL_MODELS:
|
|
111
|
+
problems.append(f"{label}: hitl must be one of {HITL_MODELS}")
|
|
112
|
+
elif level is not None and hitl != HITL_BY_LEVEL[level]:
|
|
113
|
+
warnings.append(
|
|
114
|
+
f"{label}: hitl {hitl} differs from the level-{level} default "
|
|
115
|
+
f"{HITL_BY_LEVEL[level]} (permitted; recorded)"
|
|
116
|
+
)
|
|
117
|
+
|
|
118
|
+
guardrails = raw.get("guardrails", [])
|
|
119
|
+
if guardrails is None:
|
|
120
|
+
guardrails = []
|
|
121
|
+
if not isinstance(guardrails, list) or not all(isinstance(g, str) and g.strip() for g in guardrails):
|
|
122
|
+
problems.append(f"{label}: guardrails must be a list of non-empty strings")
|
|
123
|
+
elif level is not None and level >= 3 and not guardrails:
|
|
124
|
+
problems.append(
|
|
125
|
+
f"{label}: a loop at L{level} without guardrails is not AO-ready "
|
|
126
|
+
"(safety-envelope integrity, assumption 4)"
|
|
127
|
+
)
|
|
128
|
+
|
|
129
|
+
if raw["velocity"] == "fast" and not raw.get("budget_end_to_end"):
|
|
130
|
+
warnings.append(f"{label}: fast loop without a recorded end-to-end latency budget")
|
|
131
|
+
if raw.get("budget_end_to_end") and raw.get("budget_end_to_end") != _BUDGETS.get(raw["velocity"]) and raw.get("budget_end_to_end") != "custom":
|
|
132
|
+
warnings.append(
|
|
133
|
+
f"{label}: budget {raw['budget_end_to_end']!r} differs from the {raw['velocity']} "
|
|
134
|
+
f"reference budget {_BUDGETS[raw['velocity']]!r} (permitted; recorded)"
|
|
135
|
+
)
|
|
136
|
+
|
|
137
|
+
horizon_ok = True
|
|
138
|
+
if "last_review" in raw and raw["last_review"] is not None:
|
|
139
|
+
parsed = _isodate(raw["last_review"])
|
|
140
|
+
if parsed is None:
|
|
141
|
+
problems.append(f"{label}: last_review must be an ISO date, got {raw['last_review']!r}")
|
|
142
|
+
horizon_ok = False
|
|
143
|
+
cadence = raw.get("review_cadence_days", 90)
|
|
144
|
+
if not isinstance(cadence, int) or isinstance(cadence, bool) or cadence <= 0:
|
|
145
|
+
problems.append(f"{label}: review_cadence_days must be a positive integer")
|
|
146
|
+
|
|
147
|
+
unknown = set(raw) - set(REQUIRED_FIELDS) - set(OPTIONAL_FIELDS)
|
|
148
|
+
if unknown:
|
|
149
|
+
problems.append(f"{label}: unknown fields {sorted(unknown)} — ledger schema 1 does not define them")
|
|
150
|
+
|
|
151
|
+
_ = horizon_ok # staleness handled in health_report against --today
|
|
152
|
+
return raw, problems, warnings
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def load_ledger(path) -> dict:
|
|
156
|
+
path = Path(path)
|
|
157
|
+
with path.open(encoding="utf-8") as fh:
|
|
158
|
+
data = yaml.safe_load(fh)
|
|
159
|
+
if not isinstance(data, dict):
|
|
160
|
+
raise ValueError(f"{path}: ledger must be a YAML mapping with 'schema' and 'loops'")
|
|
161
|
+
|
|
162
|
+
schema = data.get("schema")
|
|
163
|
+
warnings: list[str] = []
|
|
164
|
+
if schema is None:
|
|
165
|
+
warnings.append("pre-versioning ledger: no 'schema' field — re-save with 'schema: 1'")
|
|
166
|
+
schema = None
|
|
167
|
+
elif not isinstance(schema, int) or isinstance(schema, bool):
|
|
168
|
+
raise ValueError(f"{path}: 'schema' must be an integer, got {schema!r}")
|
|
169
|
+
elif schema > SUPPORTED_SCHEMA_VERSION:
|
|
170
|
+
raise ValueError(
|
|
171
|
+
f"{path}: ledger schema {schema} is newer than supported schema "
|
|
172
|
+
f"{SUPPORTED_SCHEMA_VERSION} — fail-closed; update the tool"
|
|
173
|
+
)
|
|
174
|
+
elif schema < SUPPORTED_SCHEMA_VERSION:
|
|
175
|
+
warnings.append(f"ledger schema {schema} is older than supported {SUPPORTED_SCHEMA_VERSION}")
|
|
176
|
+
|
|
177
|
+
loops_raw = data.get("loops")
|
|
178
|
+
if not isinstance(loops_raw, list):
|
|
179
|
+
raise ValueError(f"{path}: top-level 'loops' must be a list")
|
|
180
|
+
|
|
181
|
+
loops, errors, loop_warnings = [], [], []
|
|
182
|
+
for i, raw in enumerate(loops_raw):
|
|
183
|
+
loop, problems, warns = _validate_loop(raw, i)
|
|
184
|
+
loops.append(loop)
|
|
185
|
+
errors.extend(problems)
|
|
186
|
+
loop_warnings.extend(warns)
|
|
187
|
+
|
|
188
|
+
ids = [l.get("id") for l in loops if isinstance(l, dict) and l.get("id")]
|
|
189
|
+
duplicates = sorted({i for i in ids if ids.count(i) > 1})
|
|
190
|
+
if duplicates:
|
|
191
|
+
errors.append(f"duplicate loop ids: {duplicates}")
|
|
192
|
+
|
|
193
|
+
return {
|
|
194
|
+
"schema_version": schema,
|
|
195
|
+
"loops": loops,
|
|
196
|
+
"errors": errors,
|
|
197
|
+
"warnings": warnings + loop_warnings,
|
|
198
|
+
"source": str(path),
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def health_report(ledger: dict, today: _dt.date | None = None) -> dict:
|
|
203
|
+
today = today or _dt.date.today()
|
|
204
|
+
loops = ledger["loops"]
|
|
205
|
+
active = [l for l in loops if l.get("state") == "active"]
|
|
206
|
+
by_level: dict[int, int] = {}
|
|
207
|
+
by_velocity: dict[str, int] = {}
|
|
208
|
+
for l in loops:
|
|
209
|
+
lv = l.get("level")
|
|
210
|
+
if isinstance(lv, int):
|
|
211
|
+
by_level[lv] = by_level.get(lv, 0) + 1
|
|
212
|
+
v = l.get("velocity")
|
|
213
|
+
if isinstance(v, str):
|
|
214
|
+
by_velocity[v] = by_velocity.get(v, 0) + 1
|
|
215
|
+
|
|
216
|
+
stale, unhygienic = [], 0
|
|
217
|
+
for l in loops:
|
|
218
|
+
problems = 0
|
|
219
|
+
cadence = l.get("review_cadence_days", 90)
|
|
220
|
+
last = _isodate(l.get("last_review")) if l.get("last_review") else None
|
|
221
|
+
if l.get("state") == "active":
|
|
222
|
+
if last is None:
|
|
223
|
+
stale.append({"id": l["id"], "reason": "active loop has never been reviewed"})
|
|
224
|
+
problems += 1
|
|
225
|
+
elif (today - last).days > cadence:
|
|
226
|
+
stale.append({
|
|
227
|
+
"id": l["id"],
|
|
228
|
+
"reason": f"last review {last} is {(today - last).days} days old (cadence {cadence})",
|
|
229
|
+
})
|
|
230
|
+
problems += 1
|
|
231
|
+
if l.get("level", 0) >= 3 and not l.get("guardrails"):
|
|
232
|
+
problems += 1
|
|
233
|
+
unhygienic += problems
|
|
234
|
+
|
|
235
|
+
coverage = 0.0
|
|
236
|
+
if loops:
|
|
237
|
+
complete = sum(
|
|
238
|
+
1 for l in loops
|
|
239
|
+
if all(l.get(f) not in (None, "") for f in REQUIRED_FIELDS)
|
|
240
|
+
and (l.get("level", 5) < 3 or bool(l.get("guardrails")))
|
|
241
|
+
)
|
|
242
|
+
coverage = complete / len(loops)
|
|
243
|
+
|
|
244
|
+
return {
|
|
245
|
+
"ruleset_version": RULESET_VERSION,
|
|
246
|
+
"schema_version": ledger["schema_version"],
|
|
247
|
+
"schema_warnings": ledger["warnings"],
|
|
248
|
+
"total_loops": len(loops),
|
|
249
|
+
"active": len(active),
|
|
250
|
+
"by_level": {f"L{k}": v for k, v in sorted(by_level.items())},
|
|
251
|
+
"by_velocity": {k: v for k, v in sorted(by_velocity.items())},
|
|
252
|
+
"validity_errors": ledger["errors"],
|
|
253
|
+
"stale_reviews": stale,
|
|
254
|
+
"unhygienic_count": unhygienic,
|
|
255
|
+
"coverage": round(coverage, 4),
|
|
256
|
+
"today": today.isoformat(),
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def render(report: dict) -> str:
|
|
261
|
+
lines = [
|
|
262
|
+
"AOCL Loop Ledger Health",
|
|
263
|
+
f"Ruleset version: {report['ruleset_version']}",
|
|
264
|
+
f"Loops: {report['total_loops']} total, {report['active']} active",
|
|
265
|
+
]
|
|
266
|
+
if report["by_level"]:
|
|
267
|
+
lines.append("By level: " + ", ".join(f"{k}: {v}" for k, v in report["by_level"].items()))
|
|
268
|
+
if report["by_velocity"]:
|
|
269
|
+
lines.append("By velocity: " + ", ".join(f"{k}: {v}" for k, v in report["by_velocity"].items()))
|
|
270
|
+
lines.append(f"Coverage (complete loops): {report['coverage']:.0%}")
|
|
271
|
+
for w in report["schema_warnings"]:
|
|
272
|
+
lines.append(f"warning: {w}")
|
|
273
|
+
for e in report["validity_errors"]:
|
|
274
|
+
lines.append(f"error: {e}")
|
|
275
|
+
for s in report["stale_reviews"]:
|
|
276
|
+
lines.append(f"stale: {s['id']} — {s['reason']}")
|
|
277
|
+
if report["unhygienic_count"]:
|
|
278
|
+
lines.append(f"hygiene findings: {report['unhygienic_count']}")
|
|
279
|
+
lines.append(f"(as of {report['today']})")
|
|
280
|
+
return "\n".join(lines)
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
def main(argv=None) -> int:
|
|
284
|
+
argv = list(sys.argv[1:] if argv is None else argv)
|
|
285
|
+
if "--self-test" in argv:
|
|
286
|
+
return _self_test()
|
|
287
|
+
as_json = "--json" in argv
|
|
288
|
+
argv = [a for a in argv if a != "--json"]
|
|
289
|
+
today = None
|
|
290
|
+
if "--today" in argv:
|
|
291
|
+
i = argv.index("--today")
|
|
292
|
+
today = _dt.date.fromisoformat(argv[i + 1])
|
|
293
|
+
del argv[i : i + 2]
|
|
294
|
+
if not argv:
|
|
295
|
+
print("usage: aocl-ledger <ledger.yaml> [--today YYYY-MM-DD] [--json] | --self-test")
|
|
296
|
+
return 2
|
|
297
|
+
try:
|
|
298
|
+
ledger = load_ledger(argv[0])
|
|
299
|
+
except (OSError, ValueError) as exc:
|
|
300
|
+
print(f"error: {exc}")
|
|
301
|
+
return 2
|
|
302
|
+
report = health_report(ledger, today)
|
|
303
|
+
print(json.dumps(report, indent=2) if as_json else render(report))
|
|
304
|
+
return 1 if (report["validity_errors"] or report["unhygienic_count"] or report["stale_reviews"]) else 0
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
def _self_test() -> int:
|
|
308
|
+
good = {
|
|
309
|
+
"id": "loop-a", "entity": "proc-1", "entity_kind": "process", "velocity": "fast",
|
|
310
|
+
"level": 3, "decision_model": "MAPE", "owner": "op-lead", "state": "active",
|
|
311
|
+
"guardrails": ["policy bounds enforced"], "budget_end_to_end": "< 100 ms",
|
|
312
|
+
"last_review": "2026-11-01", "review_cadence_days": 90,
|
|
313
|
+
}
|
|
314
|
+
loop, errors, warnings = _validate_loop(dict(good), 0)
|
|
315
|
+
assert not errors and not warnings, (errors, warnings)
|
|
316
|
+
# vector/level consistency:
|
|
317
|
+
bad = dict(good, level=5, vector_levels={"GD": 5, "DV": 5, "FI": 3})
|
|
318
|
+
_, errors, _ = _validate_loop(bad, 0)
|
|
319
|
+
assert any("inconsistent" in e for e in errors)
|
|
320
|
+
# L3 without guardrails is an error:
|
|
321
|
+
_, errors, _ = _validate_loop({k: v for k, v in good.items() if k != "guardrails"}, 0)
|
|
322
|
+
assert any("not AO-ready" in e for e in errors)
|
|
323
|
+
# hitl mismatch is a recorded warning, not an error:
|
|
324
|
+
_, errors, warnings = _validate_loop(dict(good, hitl="HOOTL"), 0)
|
|
325
|
+
assert not errors and any("differs from the level-3 default" in w for w in warnings)
|
|
326
|
+
# L1 without guardrails is fine:
|
|
327
|
+
l1 = dict(good, level=1, velocity="slow")
|
|
328
|
+
_, errors, _ = _validate_loop(l1, 0)
|
|
329
|
+
assert not errors
|
|
330
|
+
# unknown field rejected:
|
|
331
|
+
_, errors, _ = _validate_loop(dict(good, blended_score=9), 0)
|
|
332
|
+
assert any("unknown fields" in e for e in errors)
|
|
333
|
+
# report math with deterministic today:
|
|
334
|
+
ledger = {"schema_version": 1, "loops": [good], "errors": [], "warnings": [], "source": "t"}
|
|
335
|
+
report = health_report(ledger, today=_dt.date(2026, 12, 5)) # 34 days after review
|
|
336
|
+
assert report["stale_reviews"] == [] and report["coverage"] == 1.0
|
|
337
|
+
report = health_report(ledger, today=_dt.date(2027, 2, 1)) # 92 days after
|
|
338
|
+
assert len(report["stale_reviews"]) == 1
|
|
339
|
+
print(f"self-test OK (ruleset {RULESET_VERSION}, ledger schema {SUPPORTED_SCHEMA_VERSION})")
|
|
340
|
+
return 0
|
|
341
|
+
|
|
342
|
+
|
|
343
|
+
if __name__ == "__main__":
|
|
344
|
+
sys.exit(main())
|