Finetuned canonical datamodel

Author: huka81

docs/10-api-reference/database_schema.md

@@ -11,18 +11,26 @@
 Requires PYTHONPATH including workspace src/ (see .vscode/settings.json).
 
 ROA Manifesto alignment: §3-4, §6
+
+Canonical telemetry: ``samples/01_roa_agent/data/01_roa_agent.db`` (optional).
 """
 from __future__ import annotations
 
 import json
 import logging
 import random
+import sys
 from abc import ABC, abstractmethod
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple, Union
 
-from dir_core import (
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_SRC = _REPO_ROOT / "src"
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+from dir_core import (  # noqa: E402
     AgentState,
     DecisionRecord,
     EscalationRequest,
@@ -33,8 +41,16 @@
     SelfCheckResult,
     new_dfid,
 )
+from dir_core.storage import AuditStore, ensure_db, sqlite_storage  # noqa: E402
 from dir_core.utils.logging_utils import log_with_dfid
 
+from telemetry import (  # noqa: E402
+    SIMULATION_ID,
+    record_roa_cycle_result,
+    record_simulation_end,
+    record_simulation_start,
+)
+
 logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
 logger = logging.getLogger(__name__)
 
@@ -704,9 +720,9 @@ def formulate_policy(self, dfid: str, explain_result: ExplainResult) -> Policy:
 # =============================================================================
 
 
-def main() -> None:
-    """Demonstrate full ROA lifecycle with dynamic agents and escalation scenarios."""
-    
+def _run_roa_demo(audit: AuditStore) -> None:
+    """Scenarios A–G: ROA lifecycle (one ``decision_audit`` row per ``run_decision_cycle``)."""
+
     print("=" * 70)
     print("ROA Agent Sample - Full Lifecycle Demonstration")
     print("=" * 70)
@@ -737,7 +753,8 @@ def main() -> None:
     }
 
     result_a = btc_agent.run_decision_cycle(dfid_a, context_a)
-    
+    record_roa_cycle_result(audit, dfid_a, SIMULATION_ID, result_a, scenario_label="A")
+
     if isinstance(result_a, PolicyProposal):
         print(f"\n[RESULT A] PolicyProposal emitted:")
         print(f"  DFID: {result_a.dfid}")
@@ -765,7 +782,8 @@ def main() -> None:
     }
 
     result_b = btc_agent.run_decision_cycle(dfid_b, context_b)
-    
+    record_roa_cycle_result(audit, dfid_b, SIMULATION_ID, result_b, scenario_label="B")
+
     if isinstance(result_b, EscalationRequest):
         print(f"\n[RESULT B] EscalationRequest emitted:")
         print(f"  DFID: {result_b.dfid}")
@@ -801,7 +819,8 @@ def main() -> None:
     context_c = {"price": 63500}  # +5.8% profit
 
     result_c = position_agent.run_decision_cycle(dfid_c, context_c)
-    
+    record_roa_cycle_result(audit, dfid_c, SIMULATION_ID, result_c, scenario_label="C")
+
     if isinstance(result_c, PolicyProposal):
         print(f"\n[RESULT C] PositionAgent PolicyProposal:")
         print(f"  DFID: {result_c.dfid}")
@@ -824,7 +843,8 @@ def main() -> None:
     context_d = {"price": 57500}  # -4.2% loss, exceeds 3% max_drawdown_limit
 
     result_d = position_agent.run_decision_cycle(dfid_d, context_d)
-    
+    record_roa_cycle_result(audit, dfid_d, SIMULATION_ID, result_d, scenario_label="D")
+
     if isinstance(result_d, PolicyProposal):
         print(f"\n[RESULT D] Risk-triggered PolicyProposal:")
         print(f"  Action: {result_d.policy_kind}")
@@ -895,7 +915,8 @@ def main() -> None:
     }
 
     result_e = restored_agent.run_decision_cycle(dfid_e, context_e)
-    
+    record_roa_cycle_result(audit, dfid_e, SIMULATION_ID, result_e, scenario_label="E")
+
     if isinstance(result_e, PolicyProposal):
         print(f"\n[RESULT E] Restored agent decision:")
         print(f"  Action: {result_e.policy_kind}")
@@ -964,11 +985,17 @@ def main() -> None:
     dfid_f1 = new_dfid()
     log_with_dfid(logger, dfid_f1, logging.INFO, "Growth agent analyzing...")
     result_f1 = growth_agent.run_decision_cycle(dfid_f1, same_context)
-    
+    record_roa_cycle_result(
+        audit, dfid_f1, SIMULATION_ID, result_f1, scenario_label="F_growth"
+    )
+
     dfid_f2 = new_dfid()
     log_with_dfid(logger, dfid_f2, logging.INFO, "Defensive agent analyzing...")
     result_f2 = defensive_agent.run_decision_cycle(dfid_f2, same_context)
-    
+    record_roa_cycle_result(
+        audit, dfid_f2, SIMULATION_ID, result_f2, scenario_label="F_defensive"
+    )
+
     print("\n  [COMPARISON] Same data, different missions:")
     print(f"\n  Growth Agent (mission: 'Maximize alpha...'):")
     print(f"    Focus: opportunity_weight={growth_agent.parse_mission_focus()['opportunity_weight']:.1f}x")
@@ -1018,7 +1045,14 @@ def main() -> None:
         dfid_g = new_dfid()
         log_with_dfid(logger, dfid_g, logging.INFO, f"Challenge {i}: vol={ctx['volatility']:.1%}")
         result_g = evolving_agent.run_decision_cycle(dfid_g, ctx)
-        
+        record_roa_cycle_result(
+            audit,
+            dfid_g,
+            SIMULATION_ID,
+            result_g,
+            scenario_label=f"G_challenge_{i}",
+        )
+
         outcome = "ESCALATED" if isinstance(result_g, EscalationRequest) else result_g.policy_kind
         print(f"  Challenge {i}: vol={ctx['volatility']:.1%} -> {outcome} (policy v{evolving_agent.state.policy_version})")
 
@@ -1032,6 +1066,31 @@ def main() -> None:
     print(f"  -> Agent {'shifted to more conservative strategy' if evolving_agent.state.policy_version > 1 else 'maintained original strategy'}")
 
 
+def main() -> None:
+    """Run ROA demo and append audit rows to canonical SQLite under ``data/``."""
+    data_dir = Path(__file__).resolve().parent / "data"
+    data_dir.mkdir(parents=True, exist_ok=True)
+    db_path = ensure_db(data_dir / "01_roa_agent.db")
+    bundle = sqlite_storage(str(db_path))
+    audit = AuditStore(bundle.decision_audit, bundle.idempotency)
+    run_status = "ok"
+    end_error: Optional[str] = None
+    try:
+        record_simulation_start(audit, SIMULATION_ID)
+        _run_roa_demo(audit)
+    except Exception as exc:
+        run_status = "error"
+        end_error = str(exc)
+        raise
+    finally:
+        record_simulation_end(
+            audit,
+            SIMULATION_ID,
+            status=run_status,
+            error_message=end_error,
+        )
+
+
 if __name__ == "__main__":
     main()
 

samples/01_roa_agent/run.py

@@ -0,0 +1,134 @@
+"""``AuditStore`` helpers — canonical decision audit rows for ROA demo runs.
+
+Aligned with ``src/dir_core/storage/schema.sql`` and telemetry guidelines:
+
+* ``root_dfid`` = ``simulation_id`` for the whole script run.
+* Per-cycle rows use the scenario ``dfid`` with the same ``root_dfid``.
+* ``detail_json`` includes ``correlation_id`` (= ``simulation_id``).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Union
+
+from dir_core import EscalationRequest, PolicyProposal
+from dir_core.storage.base import AuditStore
+
+SIMULATION_ID = "sample_01_roa_agent"
+
+
+def _detail_base(
+    simulation_id: str,
+    extra: Optional[Dict[str, Any]] = None,
+    *,
+    causation_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    out: Dict[str, Any] = {
+        "simulation_id": simulation_id,
+        "correlation_id": simulation_id,
+    }
+    if causation_id:
+        out["causation_id"] = causation_id
+    if extra:
+        out.update(extra)
+    return out
+
+
+def record_simulation_start(
+    audit: AuditStore,
+    simulation_id: str = SIMULATION_ID,
+    *,
+    sample: str = "01_roa_agent",
+) -> None:
+    audit.record(
+        simulation_id,
+        "SIMULATION_START",
+        step_id="SIMULATION",
+        state="RUNNING",
+        details=_detail_base(
+            simulation_id,
+            {
+                "sample": sample,
+                "mode": "roa_educational_demo",
+            },
+        ),
+        root_dfid=simulation_id,
+        severity="INFO",
+    )
+
+
+def record_simulation_end(
+    audit: AuditStore,
+    simulation_id: str = SIMULATION_ID,
+    *,
+    status: str,
+    error_message: Optional[str] = None,
+) -> None:
+    extra: Dict[str, Any] = {"status": status}
+    if error_message is not None:
+        extra["error_message"] = error_message
+    sev = "ERROR" if status.lower() == "error" else "INFO"
+    audit.record(
+        simulation_id,
+        "SIMULATION_END",
+        step_id="SIMULATION",
+        state=status.upper(),
+        details=_detail_base(simulation_id, extra),
+        root_dfid=simulation_id,
+        severity=sev,
+    )
+
+
+def record_roa_cycle_result(
+    audit: AuditStore,
+    dfid: str,
+    simulation_id: str,
+    result: Union[PolicyProposal, EscalationRequest],
+    *,
+    scenario_label: str,
+) -> None:
+    """Emit one audit row per ``run_decision_cycle`` outcome."""
+    if isinstance(result, PolicyProposal):
+        pk = str(result.policy_kind)
+        st = pk.upper().replace(" ", "_")[:120]
+        audit.record(
+            dfid,
+            "AGENT_DECISION",
+            step_id="ROA_CYCLE",
+            state=st,
+            details=_detail_base(
+                simulation_id,
+                {
+                    "scenario": scenario_label,
+                    "agent_id": result.agent_id,
+                    "policy_kind": result.policy_kind,
+                    "confidence": result.confidence,
+                    "justification": (result.justification or "")[:500],
+                },
+            ),
+            root_dfid=simulation_id,
+            agent_id=result.agent_id,
+            severity="INFO",
+        )
+        return
+
+    sev_esc = str(result.severity)
+    audit.record(
+        dfid,
+        "ESCALATION_REQUESTED",
+        step_id="ROA_ESCALATION",
+        state="PENDING",
+        details=_detail_base(
+            simulation_id,
+            {
+                "scenario": scenario_label,
+                "from_agent_id": result.from_agent_id,
+                "to_agent_id": result.to_agent_id,
+                "trigger": result.trigger,
+                "severity": sev_esc,
+            },
+        ),
+        root_dfid=simulation_id,
+        agent_id=result.from_agent_id,
+        severity="WARNING",
+    )