alpha-engine-lib 0.41.0__tar.gz → 0.43.0__tar.gz

{alpha_engine_lib-0.41.0 → alpha_engine_lib-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.41.0
+Version: 0.43.0
 Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary

{alpha_engine_lib-0.41.0 → alpha_engine_lib-0.43.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "alpha-engine-lib"
-version = "0.41.0"
+version = "0.43.0"
 description = "Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README."
 readme = "README.md"
 # EC2 still runs Python 3.9 on the always-on micro instance (boto3 drops

{alpha_engine_lib-0.41.0 → alpha_engine_lib-0.43.0}/src/alpha_engine_lib/__init__.py

@@ -1,3 +1,3 @@
 """alpha-engine-lib — shared utilities for Alpha Engine modules."""
 
-__version__ = "0.41.0"
+__version__ = "0.43.0"

{alpha_engine_lib-0.41.0 → alpha_engine_lib-0.43.0}/src/alpha_engine_lib/agent_schemas.py

@@ -50,10 +50,19 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 # ── Literals ─────────────────────────────────────────────────────────────
 
 
-RegimeLiteral = Literal["bull", "neutral", "bear", "caution"]
+RegimeLiteral = Literal["bull", "neutral", "bear"]
 """Macro market regime — output of the macro_economist agent and the
 macro critic. Drives sector_modifiers downstream and the executor's
-graduated drawdown gate."""
+graduated drawdown gate.
+
+3-class Ang-Bekaert taxonomy. The legacy 4th value ``"caution"`` was
+retired in v0.42.0 (plan: caution-regime-retirement-260528.md): the
+rule-based caution override at the macro-agent layer double-counted
+signals already weighted into the continuous ``regime_intensity_z``
+META_FEATURE. Portfolio-protective drawdown state is now a separate
+axis (``drawdown_tier: Literal["risk_on","caution","risk_off"]``)
+emitted by the predictor's drawdown leg; consumers compose the two
+axes via most-protective override at decision time."""
 
 
 CIORawDecisionLiteral = Literal["ADVANCE", "REJECT", "NO_ADVANCE_DEADLOCK"]

{alpha_engine_lib-0.41.0 → alpha_engine_lib-0.43.0}/src/alpha_engine_lib/transparency.py

@@ -64,7 +64,13 @@ class CheckResult:
 
     row_id: str
     cadence: str
-    status: str  # "ok" | "fail" | "not_yet_effective" | "error"
+    # "ok" | "fail" | "degraded" | "not_yet_effective" | "error"
+    # "degraded" = non-fatal: either a diagnostic row (non_fatal: true, e.g.
+    # pipeline_execution success_rate — observability, not a gate) or a present
+    # artifact carrying a benign producer status (non_fatal_statuses, e.g.
+    # no_recent_sf_run = no upstream data this cycle, not a missing diagnostic).
+    # Degraded does NOT count as a failure: no SNS alert, exit 0, CW value 1.0.
+    status: str
     detail: str
     effective_date: str
     artifact: str | None = None
@@ -157,13 +163,16 @@ def _check_row(
 
     sub: list[str] = []
     artifact_hint: str | None = None
+    degraded_detail: str | None = None
     for src in row["sources"]:
         try:
-            ok, detail, artifact = _check_source(
+            ok, detail, artifact, status_hint = _check_source(
                 src, today, s3_client, cloudwatch_client
             )
         except Exception as exc:  # pragma: no cover — defensive
-            ok, detail, artifact = False, f"checker error: {exc!r}", None
+            ok, detail, artifact, status_hint = (
+                False, f"checker error: {exc!r}", None, None
+            )
         if artifact and artifact_hint is None:
             artifact_hint = artifact
         if ok:
@@ -175,8 +184,28 @@ def _check_row(
                 effective_date=str(eff),
                 artifact=artifact_hint,
             )
+        if status_hint == "degraded" and degraded_detail is None:
+            degraded_detail = detail
         sub.append(detail)
 
+    # All sources failed. Classify non-fatal degradation vs hard fail:
+    #  - row-level ``non_fatal: true`` → diagnostic/observability row demoted
+    #    from a gate (Phase 1c: pipeline_execution success_rate).
+    #  - any source signalled "degraded" → present artifact carrying a benign
+    #    producer status (Phase 1a: e.g. no_recent_sf_run = no upstream data
+    #    this cycle, not a missing diagnostic).
+    # Either way the cycle isn't "broken" — surface it without failing the gate.
+    if row.get("non_fatal") or degraded_detail is not None:
+        return CheckResult(
+            row_id=row["id"],
+            cadence=row["cadence"],
+            status="degraded",
+            detail=degraded_detail or "; ".join(sub),
+            effective_date=str(eff),
+            artifact=artifact_hint,
+            sub_failures=sub,
+        )
+
     return CheckResult(
         row_id=row["id"],
         cadence=row["cadence"],
@@ -198,12 +227,22 @@ def _check_source(
     today: date,
     s3_client: Any,
     cloudwatch_client: Any,
-) -> tuple[bool, str, str | None]:
+) -> tuple[bool, str, str | None, str | None]:
+    """Run a source handler, normalized to ``(ok, detail, artifact, status_hint)``.
+
+    Handlers may return a 3-tuple (the common case) or a 4-tuple whose 4th
+    element is a ``status_hint`` ("degraded") used to mark a non-fatal
+    non-pass. Normalizing here keeps handlers that don't care unchanged.
+    """
     kind = src["kind"]
     handler = _SOURCE_HANDLERS.get(kind)
     if handler is None:
-        return False, f"unsupported source kind: {kind}", None
-    return handler(src, today, s3_client, cloudwatch_client)
+        return False, f"unsupported source kind: {kind}", None, None
+    result = handler(src, today, s3_client, cloudwatch_client)
+    if len(result) == 4:
+        return result
+    ok, detail, artifact = result
+    return ok, detail, artifact, None
 
 
 def _resolve_key(src: dict, today: date) -> tuple[str, str]:
@@ -293,7 +332,7 @@ def _resolve_and_age(
 
 def _check_s3_json(
     src: dict, today: date, s3_client: Any, _cw: Any
-) -> tuple[bool, str, str | None]:
+) -> tuple[bool, str, str | None] | tuple[bool, str, str | None, str | None]:
     bucket = src.get("bucket", DEFAULT_BUCKET)
     key, age, status = _resolve_and_age(src, today, s3_client)
     if key is None:
@@ -322,6 +361,22 @@ def _check_s3_json(
     except Exception as exc:
         return False, f"json parse error on s3://{bucket}/{key}: {exc!r}", key
 
+    # Phase 1a: a present artifact carrying a benign producer status is a
+    # legitimate cycle state (no upstream data), NOT a missing diagnostic and
+    # NOT a hard failure. Short-circuit BEFORE evaluating asserts so we don't
+    # report a misleading "coverage 0% < 99". Always-emit (producer side) is
+    # what makes this distinguishable from absence.
+    non_fatal_statuses = src.get("non_fatal_statuses", [])
+    prod_status = payload.get("status") if isinstance(payload, dict) else None
+    if non_fatal_statuses and prod_status in non_fatal_statuses:
+        return (
+            False,
+            f"degraded: producer status='{prod_status}' — no upstream data "
+            f"this cycle (s3://{bucket}/{key})",
+            key,
+            "degraded",
+        )
+
     failures: list[str] = []
     for required in src.get("assert_keys_present", []):
         if required not in payload:
@@ -636,8 +691,9 @@ def emit_cloudwatch_metrics(results: list[CheckResult], cloudwatch_client: Any =
 
     metric_data = []
     for r in results:
-        # 1 = ok or not_yet_effective (counts as healthy), 0 = fail
-        value = 1.0 if r.status in ("ok", "not_yet_effective") else 0.0
+        # 1 = ok / not_yet_effective / degraded (all non-failing), 0 = fail.
+        # Degraded is non-fatal so it must not trip the SubstrateRowOK alarm.
+        value = 1.0 if r.status in ("ok", "not_yet_effective", "degraded") else 0.0
         metric_data.append({
             "MetricName": "SubstrateRowOK",
             "Dimensions": [{"Name": "RowID", "Value": r.row_id}],
@@ -646,10 +702,12 @@ def emit_cloudwatch_metrics(results: list[CheckResult], cloudwatch_client: Any =
         })
     n_ok = sum(1 for r in results if r.status == "ok")
     n_fail = sum(1 for r in results if r.status == "fail")
+    n_degraded = sum(1 for r in results if r.status == "degraded")
     n_pending = sum(1 for r in results if r.status == "not_yet_effective")
     metric_data.extend([
         {"MetricName": "SubstrateChecksOK", "Value": float(n_ok), "Unit": "Count"},
         {"MetricName": "SubstrateChecksFailed", "Value": float(n_fail), "Unit": "Count"},
+        {"MetricName": "SubstrateChecksDegraded", "Value": float(n_degraded), "Unit": "Count"},
         {"MetricName": "SubstrateChecksPending", "Value": float(n_pending), "Unit": "Count"},
     ])
 
@@ -664,15 +722,22 @@ def format_report(results: list[CheckResult]) -> str:
     lines = ["Substrate Health Report", "=" * 50]
     n_ok = sum(1 for r in results if r.status == "ok")
     n_fail = sum(1 for r in results if r.status == "fail")
+    n_degraded = sum(1 for r in results if r.status == "degraded")
     n_pending = sum(1 for r in results if r.status == "not_yet_effective")
     n_total = len(results)
-    pct = (100.0 * n_ok / max(1, n_total - n_pending)) if n_total > n_pending else 0.0
+    # Gating denominator excludes pending (not yet effective) AND degraded
+    # (non-fatal, can't be scored pass/fail this cycle).
+    n_gating = n_total - n_pending - n_degraded
+    pct = (100.0 * n_ok / n_gating) if n_gating > 0 else 100.0
     lines.append(
-        f"OK: {n_ok}  Failed: {n_fail}  Pending: {n_pending}  "
-        f"({pct:.1f}% of effective rows passing)"
+        f"OK: {n_ok}  Failed: {n_fail}  Degraded: {n_degraded}  "
+        f"Pending: {n_pending}  ({pct:.1f}% of gating rows passing)"
     )
     lines.append("")
-    icon = {"ok": "OK ", "fail": "FAIL", "not_yet_effective": "PEND", "error": "ERR "}
+    icon = {
+        "ok": "OK ", "fail": "FAIL", "degraded": "DEGR",
+        "not_yet_effective": "PEND", "error": "ERR ",
+    }
     for r in results:
         lines.append(f"  [{icon.get(r.status, '?')}] {r.row_id:30s} {r.detail}")
     failures = [r for r in results if r.status == "fail"]
@@ -681,6 +746,12 @@ def format_report(results: list[CheckResult]) -> str:
         lines.append("ACTIONS NEEDED:")
         for r in failures:
             lines.append(f"  - {r.row_id}: {r.detail}")
+    degraded = [r for r in results if r.status == "degraded"]
+    if degraded:
+        lines.append("")
+        lines.append("DEGRADED (non-fatal — observability, no action gate):")
+        for r in degraded:
+            lines.append(f"  - {r.row_id}: {r.detail}")
     return "\n".join(lines)
 
 

{alpha_engine_lib-0.41.0 → alpha_engine_lib-0.43.0}/src/alpha_engine_lib/transparency_inventory.yaml

@@ -24,9 +24,23 @@ inventory:
   - id: pipeline_execution
     cadence: weekly
     effective_date: 2026-04-01
+    # non_fatal (Phase 1c, 2026-05-29): raw CloudWatch SF success_rate is a
+    # FIRST-PASS / OPERATOR-TOIL diagnostic, NOT a health gate. On a young,
+    # recovery-stitched system a cycle that needs N executions (1 scheduled
+    # fail + recovery reruns) to produce a complete, valid artifact set is a
+    # healthy cycle with an efficiency cost — counting every manual recovery /
+    # smoke / postfix run against a 99% SLA produces false alarms (Sat 40% /
+    # weekday 71% on 2026-05-29, both already-recovered incidents). Cycle
+    # health is judged by the per-artifact deliverable rows below (the
+    # asset-based / data-contract gate); this row stays for visibility but a
+    # low success_rate degrades, it does not fail. See
+    # private-docs/artifact-completion-monitoring-design-260529.md (Move 1) +
+    # feedback_judge_recovery_sf_by_artifact_union_not_execution_status.
+    non_fatal: true
     description: >-
-      SF success rate ≥ 99% across Saturday + weekday + EOD pipelines,
-      with per-stage durations recorded.
+      First-pass SF success rate across Saturday + weekday + EOD pipelines
+      (operator-toil diagnostic, NOT a gate — recovery-stitched cycles are
+      healthy; deliverable rows below are authoritative).
     sources:
       - kind: cloudwatch
         namespace: AWS/States
@@ -64,6 +78,17 @@ inventory:
         # The most recent date's artifact is the authoritative one.
         key_pattern: backtest/{date}/decision_capture_coverage.json
         max_age_days: 8
+        # non_fatal_statuses (Phase 1a, 2026-05-29): the backtester always
+        # emits this artifact now (alpha-engine-backtester #265), so absence
+        # means the diagnostic never ran (a real failure), while a present
+        # artifact with status=no_recent_sf_run means the upstream Saturday SF
+        # produced no agent captures this cycle (research failed / recovery
+        # was predictor-only) — a legitimate recovery-stitched state, not a
+        # coverage regression. Degrade rather than fail; a genuinely dead
+        # research pipeline is caught independently by the research_signals
+        # freshness row. See artifact-completion-monitoring-design-260529.md.
+        non_fatal_statuses:
+          - no_recent_sf_run
         assert:
           - path: coverage_pct
             op: gte

{alpha_engine_lib-0.41.0 → alpha_engine_lib-0.43.0}/src/alpha_engine_lib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.41.0
+Version: 0.43.0
 Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary

{alpha_engine_lib-0.41.0 → alpha_engine_lib-0.43.0}/tests/test_agent_schemas.py

@@ -325,6 +325,33 @@ class TestMacroEconomistRawOutput:
         with pytest.raises(ValidationError):
             MacroEconomistRawOutput(market_regime="exuberant")
 
+    def test_regime_literal_is_3class_caution_rejected(self):
+        # v0.42.0 retired "caution" from the macro market_regime taxonomy
+        # per caution-regime-retirement-260528.md. The 3-class Ang-Bekaert
+        # taxonomy (bull/neutral/bear) is the institutional baseline; the
+        # rule-based caution override at the macro-agent layer was double-
+        # counted by the continuous regime_intensity_z META_FEATURE.
+        # Portfolio-protective hysteresis (risk_on/caution/risk_off) is a
+        # separate axis emitted by the predictor drawdown leg.
+        from alpha_engine_lib.agent_schemas import (
+            MacroCriticOutput,
+            MacroEconomistRawOutput,
+        )
+
+        with pytest.raises(ValidationError):
+            MacroEconomistRawOutput(market_regime="caution")
+        with pytest.raises(ValidationError):
+            MacroCriticOutput(
+                action="revise", critique="elevated stress", suggested_regime="caution",
+            )
+
+    def test_regime_literal_accepts_all_3_classes(self):
+        from alpha_engine_lib.agent_schemas import MacroEconomistRawOutput
+
+        for regime in ("bull", "neutral", "bear"):
+            out = MacroEconomistRawOutput(market_regime=regime)
+            assert out.market_regime == regime
+
 
 class TestMacroCriticOutput:
     def test_accept_action(self):

{alpha_engine_lib-0.41.0 → alpha_engine_lib-0.43.0}/tests/test_transparency.py

@@ -955,3 +955,112 @@ def test_format_report_lists_actions_for_failed_rows():
     out = format_report(results)
     assert "ACTIONS NEEDED" in out
     assert "b: missing column" in out
+
+
+# ---------------------------------------------------------------------------
+# Phase 1 — degraded (non-fatal) status: non_fatal_statuses + non_fatal row
+# ---------------------------------------------------------------------------
+
+
+def _s3_json_row(extra_src=None):
+    src = {
+        "kind": "s3_json",
+        "bucket": "b",
+        "key": "k.json",
+        "max_age_days": 4,
+        "assert": [{"path": "coverage_pct", "op": "gte", "value": 99}],
+    }
+    if extra_src:
+        src.update(extra_src)
+    return {
+        "version": 1,
+        "inventory": [{
+            "id": "agent_decisions", "cadence": "daily",
+            "effective_date": "2026-01-01", "description": "x",
+            "sources": [src],
+        }],
+    }
+
+
+def test_s3_json_non_fatal_status_degrades_not_fails():
+    """A present artifact carrying a benign producer status (no_recent_sf_run)
+    degrades — it is NOT a coverage failure and NOT a missing diagnostic."""
+    inv = _s3_json_row({"non_fatal_statuses": ["no_recent_sf_run"]})
+    s3 = StubS3()
+    s3.put("b", "k.json", json.dumps(
+        {"status": "no_recent_sf_run", "coverage_pct": 0.0}).encode())
+    res = check_inventory("daily", today=date(2026, 6, 1), inventory=inv, s3_client=s3)
+    assert res[0].status == "degraded"
+    assert "no_recent_sf_run" in res[0].detail
+
+
+def test_s3_json_non_fatal_status_ok_passes_normally():
+    """status=ok + coverage passing → ok (non_fatal_statuses doesn't interfere)."""
+    inv = _s3_json_row({"non_fatal_statuses": ["no_recent_sf_run"]})
+    s3 = StubS3()
+    s3.put("b", "k.json", json.dumps(
+        {"status": "ok", "coverage_pct": 100.0}).encode())
+    res = check_inventory("daily", today=date(2026, 6, 1), inventory=inv, s3_client=s3)
+    assert res[0].status == "ok"
+
+
+def test_s3_json_status_not_in_non_fatal_set_still_fails():
+    """A failing status NOT in non_fatal_statuses (here: low coverage) still
+    fails — only the listed benign statuses degrade."""
+    inv = _s3_json_row({"non_fatal_statuses": ["no_recent_sf_run"]})
+    s3 = StubS3()
+    s3.put("b", "k.json", json.dumps(
+        {"status": "ok", "coverage_pct": 50.0}).encode())
+    res = check_inventory("daily", today=date(2026, 6, 1), inventory=inv, s3_client=s3)
+    assert res[0].status == "fail"
+
+
+def test_missing_artifact_still_fails_even_with_non_fatal_statuses():
+    """Absence is a real failure: always-emit (producer) means a missing
+    object = diagnostic never ran, distinct from a benign present status."""
+    inv = _s3_json_row({"non_fatal_statuses": ["no_recent_sf_run"]})
+    s3 = StubS3()  # nothing put
+    res = check_inventory("daily", today=date(2026, 6, 1), inventory=inv, s3_client=s3)
+    assert res[0].status == "fail"
+
+
+def test_row_non_fatal_degrades_on_source_failure():
+    """A row marked non_fatal: true degrades instead of failing when its
+    source fails (Phase 1c: pipeline_execution success_rate is a diagnostic)."""
+    inv = _s3_json_row()
+    inv["inventory"][0]["non_fatal"] = True
+    inv["inventory"][0]["id"] = "pipeline_execution"
+    s3 = StubS3()
+    s3.put("b", "k.json", json.dumps({"coverage_pct": 10.0}).encode())
+    res = check_inventory("daily", today=date(2026, 6, 1), inventory=inv, s3_client=s3)
+    assert res[0].status == "degraded"
+
+
+def test_format_report_separates_degraded_from_actions():
+    from alpha_engine_lib.transparency import CheckResult, format_report
+    results = [
+        CheckResult("ok_row", "daily", "ok", "fine", "2026-01-01"),
+        CheckResult("bad_row", "daily", "fail", "broke", "2026-01-01"),
+        CheckResult("degr_row", "daily", "degraded", "no upstream data", "2026-01-01"),
+    ]
+    report = format_report(results)
+    assert "Degraded: 1" in report
+    assert "[DEGR] degr_row" in report
+    # degraded must NOT appear under ACTIONS NEEDED
+    actions = report.split("ACTIONS NEEDED:")[1].split("DEGRADED")[0]
+    assert "degr_row" not in actions
+    assert "bad_row" in actions
+    assert "DEGRADED (non-fatal" in report
+
+
+def test_real_inventory_pipeline_execution_is_non_fatal():
+    inv = load_inventory()
+    row = next(r for r in inv["inventory"] if r["id"] == "pipeline_execution")
+    assert row.get("non_fatal") is True
+
+
+def test_real_inventory_agent_decisions_degrades_on_no_recent_sf_run():
+    inv = load_inventory()
+    row = next(r for r in inv["inventory"] if r["id"] == "agent_decisions")
+    src = next(s for s in row["sources"] if s["kind"] == "s3_json")
+    assert "no_recent_sf_run" in src.get("non_fatal_statuses", [])