trustops-security-data-lake 0.2.1__py3-none-any.whl

security_lakehouse/__init__.py

@@ -0,0 +1,3 @@
+"""TrustOps Security Data Lake package."""
+
+__version__ = "0.1.0"

security_lakehouse/agents/__init__.py

@@ -0,0 +1,21 @@
+"""Optional agent harness for TrustOps.
+
+The harness is allowed to orchestrate TrustOps APIs and propose actions. It is
+not the source of truth for evidence, controls, RBAC, redaction, or compliance
+evaluation.
+"""
+
+from security_lakehouse.agents.budgets import AgentBudgetPolicy
+from security_lakehouse.agents.graphs import build_posture_review_graph, build_soc_triage_graph, run_posture_review
+from security_lakehouse.agents.soc import run_soc_triage
+from security_lakehouse.agents.state import AgentDecision, AgentRunState
+
+__all__ = [
+    "AgentBudgetPolicy",
+    "AgentDecision",
+    "AgentRunState",
+    "build_posture_review_graph",
+    "build_soc_triage_graph",
+    "run_posture_review",
+    "run_soc_triage",
+]

security_lakehouse/agents/budgets.py

@@ -0,0 +1,143 @@
+"""Token and context budgets for optional model-assisted harness runs."""
+
+from __future__ import annotations
+
+import json
+import os
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+
+
+def _env_int(name: str, default: int, *, minimum: int, maximum: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        return default
+    return max(minimum, min(value, maximum))
+
+
+@dataclass(frozen=True)
+class AgentBudgetPolicy:
+    """Bound how much context an optional model can receive."""
+
+    max_context_chars: int = 12_000
+    max_fact_items: int = 20
+    max_output_tokens: int = 600
+    max_string_chars: int = 1_000
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "max_context_chars", max(256, min(int(self.max_context_chars), 200_000)))
+        object.__setattr__(self, "max_fact_items", max(1, min(int(self.max_fact_items), 250)))
+        object.__setattr__(self, "max_output_tokens", max(64, min(int(self.max_output_tokens), 8_000)))
+        object.__setattr__(self, "max_string_chars", max(128, min(int(self.max_string_chars), 16_000)))
+
+    @classmethod
+    def from_env(cls) -> AgentBudgetPolicy:
+        """Load bounded budget knobs from environment."""
+        return cls(
+            max_context_chars=_env_int("TRUSTOPS_AGENT_MAX_CONTEXT_CHARS", 12_000, minimum=1_000, maximum=200_000),
+            max_fact_items=_env_int("TRUSTOPS_AGENT_MAX_FACT_ITEMS", 20, minimum=1, maximum=250),
+            max_output_tokens=_env_int("TRUSTOPS_AGENT_MAX_OUTPUT_TOKENS", 600, minimum=64, maximum=8_000),
+            max_string_chars=_env_int("TRUSTOPS_AGENT_MAX_STRING_CHARS", 1_000, minimum=128, maximum=16_000),
+        )
+
+    def public_dict(self) -> dict[str, int | str]:
+        """Return non-secret budget policy metadata for audit output."""
+        return {
+            "profile": "small_context_default",
+            "max_context_chars": self.max_context_chars,
+            "max_fact_items": self.max_fact_items,
+            "max_output_tokens": self.max_output_tokens,
+            "max_string_chars": self.max_string_chars,
+        }
+
+
+def estimate_tokens(payload: Any) -> int:
+    """Estimate model input tokens without provider-specific tokenizers."""
+    chars = len(json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str))
+    return max(1, (chars + 3) // 4)
+
+
+def apply_budget(context: dict[str, Any], policy: AgentBudgetPolicy) -> dict[str, Any]:
+    """Return a compacted model context with budget telemetry attached."""
+    original_chars = _context_chars(context)
+    original_tokens = estimate_tokens(context)
+    for item_limit in _candidate_limits(policy.max_fact_items):
+        candidate = deepcopy(context)
+        omitted: dict[str, int] = {}
+        _limit_fact_lists(candidate, item_limit=item_limit, omitted=omitted)
+        _truncate_strings(candidate, max_chars=policy.max_string_chars, omitted=omitted)
+        candidate["budget"] = {
+            **policy.public_dict(),
+            "status": "checking",
+            "estimated_context_chars_before": original_chars,
+            "estimated_context_tokens_before": original_tokens,
+            "estimated_context_chars": 0,
+            "estimated_context_tokens": 0,
+            "fact_item_limit_applied": item_limit,
+            "truncated": bool(omitted),
+            "omitted": omitted,
+        }
+        compacted_chars = _context_chars(candidate)
+        if compacted_chars <= policy.max_context_chars or item_limit == 1:
+            status = "within_budget" if compacted_chars <= policy.max_context_chars else "over_budget"
+            candidate["budget"] = {
+                **policy.public_dict(),
+                "status": status,
+                "estimated_context_chars_before": original_chars,
+                "estimated_context_tokens_before": original_tokens,
+                "estimated_context_chars": compacted_chars,
+                "estimated_context_tokens": estimate_tokens(candidate),
+                "fact_item_limit_applied": item_limit,
+                "truncated": bool(omitted),
+                "omitted": omitted,
+            }
+            return candidate
+    raise AssertionError("candidate limits always return at least one policy")
+
+
+def _candidate_limits(max_items: int) -> list[int]:
+    limits: list[int] = []
+    current = max(1, max_items)
+    while current not in limits:
+        limits.append(current)
+        if current == 1:
+            break
+        current = max(1, current // 2)
+    return limits
+
+
+def _context_chars(payload: Any) -> int:
+    return len(json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str))
+
+
+def _limit_fact_lists(context: dict[str, Any], *, item_limit: int, omitted: dict[str, int]) -> None:
+    facts = context.get("facts")
+    if not isinstance(facts, dict):
+        return
+    for key in ("evidence_gaps", "alerts", "deterministic_decisions"):
+        value = facts.get(key)
+        if not isinstance(value, list) or len(value) <= item_limit:
+            continue
+        facts[key] = value[:item_limit]
+        omitted[f"facts.{key}"] = len(value) - item_limit
+
+
+def _truncate_strings(value: Any, *, max_chars: int, omitted: dict[str, int], path: str = "") -> Any:
+    if isinstance(value, dict):
+        for key, child in list(value.items()):
+            child_path = f"{path}.{key}" if path else str(key)
+            value[key] = _truncate_strings(child, max_chars=max_chars, omitted=omitted, path=child_path)
+        return value
+    if isinstance(value, list):
+        for index, child in enumerate(list(value)):
+            value[index] = _truncate_strings(child, max_chars=max_chars, omitted=omitted, path=f"{path}[{index}]")
+        return value
+    if isinstance(value, str) and len(value) > max_chars:
+        omitted[path or "string"] = len(value) - max_chars
+        return value[:max_chars] + "...[truncated]"
+    return value

security_lakehouse/agents/checkpoints.py

@@ -0,0 +1,54 @@
+"""LangGraph checkpoint helpers for resumable harness orchestration."""
+
+from __future__ import annotations
+
+import importlib.util
+from typing import Any
+
+
+def langgraph_available() -> bool:
+    return importlib.util.find_spec("langgraph") is not None
+
+
+def memory_checkpointer() -> Any:
+    """Return a process-local MemorySaver checkpointer."""
+    try:
+        from langgraph.checkpoint.memory import MemorySaver
+    except ImportError as exc:  # pragma: no cover - optional extra
+        raise RuntimeError("install trustops-security-data-lake[agents] to use LangGraph checkpoints") from exc
+    return MemorySaver()
+
+
+def run_config(thread_id: str) -> dict[str, Any]:
+    return {"configurable": {"thread_id": thread_id}}
+
+
+def checkpoint_state(compiled: Any, thread_id: str) -> dict[str, Any] | None:
+    """Return the latest checkpointed harness state for ``thread_id``, if any."""
+    snapshot = compiled.get_state(run_config(thread_id))
+    values = getattr(snapshot, "values", None)
+    if isinstance(values, dict) and values:
+        return dict(values)
+    return None
+
+
+def invoke_with_checkpoint(
+    compiled: Any,
+    state: dict[str, Any],
+    *,
+    thread_id: str | None = None,
+    resume: bool = False,
+) -> dict[str, Any]:
+    """Invoke a compiled LangGraph, optionally checkpointing by ``thread_id``.
+
+    The optional model step stays outside the graph; checkpoints only cover
+    deterministic TrustOps tool nodes.
+    """
+    if not thread_id:
+        return dict(compiled.invoke(state))
+    config = run_config(thread_id)
+    if resume and checkpoint_state(compiled, thread_id) is not None:
+        result = compiled.invoke(None, config)
+        return dict(result) if isinstance(result, dict) else dict(state)
+    result = compiled.invoke(state, config)
+    return dict(result)

security_lakehouse/agents/evaluations.py

@@ -0,0 +1,201 @@
+"""Deterministic guardrail evaluations for agent harnesses."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from security_lakehouse.agents.model_contract import POSTURE_REVIEW_TOOL_CALLS, SOC_TRIAGE_TOOL_CALLS
+
+
+def _decision_items(state: dict[str, Any]) -> list[Any]:
+    return list(state.get("decisions") or [])
+
+
+def _decision_action(item: Any) -> str:
+    return str(getattr(item, "action", "") or (item.get("action") if isinstance(item, dict) else ""))
+
+
+def _decision_requires_approval(item: Any) -> bool:
+    if hasattr(item, "requires_approval"):
+        return bool(item.requires_approval)
+    if isinstance(item, dict):
+        return bool(item.get("requires_approval"))
+    return False
+
+
+def _decision_status(item: Any) -> str:
+    return str(getattr(item, "status", "") or (item.get("status") if isinstance(item, dict) else ""))
+
+
+def _check(check: str, passed: bool, detail: dict[str, Any] | None = None, *, weight: int = 1) -> dict[str, Any]:
+    return {"check": check, "passed": passed, "detail": detail or {}, "weight": weight}
+
+
+def _budget_status(state: dict[str, Any]) -> str:
+    context = state.get("model_context") if isinstance(state.get("model_context"), dict) else {}
+    budget = context.get("budget") if isinstance(context.get("budget"), dict) else {}
+    return str(budget.get("status") or "not_applicable")
+
+
+def _rejected_tool_calls(state: dict[str, Any]) -> list[Any]:
+    model_output = state.get("model_output") if isinstance(state.get("model_output"), dict) else {}
+    rejected = model_output.get("rejected_tool_calls", []) if isinstance(model_output, dict) else []
+    return rejected if isinstance(rejected, list) else []
+
+
+def _coverage(state: dict[str, Any], *, use_case: str) -> dict[str, Any]:
+    decisions = _decision_items(state)
+    return {
+        "use_case": use_case,
+        "mode": state.get("mode", "rules_only"),
+        "decisions_total": len(decisions),
+        "approval_gated_decisions": sum(1 for item in decisions if _decision_requires_approval(item)),
+        "proposed_decisions": sum(1 for item in decisions if _decision_status(item) == "proposed"),
+        "model_rejected_tool_calls": len(_rejected_tool_calls(state)),
+        "model_budget_status": _budget_status(state),
+        "errors": len(state.get("errors") or []),
+    }
+
+
+def _result(checks: list[dict[str, Any]], coverage: dict[str, Any]) -> dict[str, Any]:
+    total_weight = sum(int(item.get("weight") or 1) for item in checks) or 1
+    passed_weight = sum(int(item.get("weight") or 1) for item in checks if item.get("passed"))
+    score = round((passed_weight / total_weight) * 100)
+    failures = [item for item in checks if not item.get("passed")]
+    rejected_count = int(coverage.get("model_rejected_tool_calls", 0) or 0)
+    if failures:
+        confidence = "low" if score < 70 else "medium"
+    elif rejected_count:
+        confidence = "medium"
+    elif score >= 90:
+        confidence = "high"
+    elif score >= 70:
+        confidence = "medium"
+    else:
+        confidence = "low"
+    risk_level = "critical" if any(item["check"] == "writes_are_approval_gated" for item in failures) else "high"
+    if not failures:
+        risk_level = "low" if rejected_count == 0 else "medium"
+    return {
+        "ok": not failures,
+        "score": score,
+        "confidence": confidence,
+        "risk_level": risk_level,
+        "checks": checks,
+        "failures": failures,
+        "coverage": coverage,
+    }
+
+
+def evaluate_agent_run(state: dict[str, Any], *, use_case: str) -> dict[str, Any]:
+    """Evaluate generic harness safety invariants and deterministic confidence."""
+    allowed = SOC_TRIAGE_TOOL_CALLS if use_case == "soc_triage" else POSTURE_REVIEW_TOOL_CALLS
+    checks: list[dict[str, Any]] = []
+    decisions = _decision_items(state)
+    unsupported = sorted({_decision_action(item) for item in decisions if _decision_action(item) not in allowed})
+    checks.append(_check("allowed_actions_only", not unsupported, {"unsupported_actions": unsupported}, weight=3))
+    unsafe_writes = [
+        _decision_action(item)
+        for item in decisions
+        if _decision_action(item) in allowed
+        and (not _decision_requires_approval(item) or _decision_status(item) == "executed")
+    ]
+    checks.append(_check("writes_are_approval_gated", not unsafe_writes, {"unsafe_actions": unsafe_writes}, weight=4))
+    model_output = state.get("model_output") if isinstance(state.get("model_output"), dict) else {}
+    rejected = model_output.get("rejected_tool_calls", []) if isinstance(model_output, dict) else []
+    checks.append(
+        _check(
+            "model_rejections_recorded",
+            isinstance(rejected, list),
+            {"rejected_tool_calls": rejected if isinstance(rejected, list) else "invalid"},
+            weight=1,
+        )
+    )
+    budget_status = _budget_status(state)
+    errors = {str(item) for item in state.get("errors") or []}
+    checks.append(
+        _check(
+            "context_budget_enforced",
+            budget_status != "over_budget" or "model_skipped: context_budget_exceeded" in errors,
+            {"budget_status": budget_status},
+            weight=2,
+        )
+    )
+    coverage = _coverage(state, use_case=use_case)
+    if use_case == "posture_review":
+        evidence_gaps = [row for row in state.get("evidence_gaps", []) if isinstance(row, dict)]
+        gap_control_ids = {str(row.get("control_id") or "") for row in evidence_gaps if row.get("control_id")}
+        covered_control_ids = set()
+        for item in decisions:
+            payload = (
+                getattr(item, "payload", None)
+                if hasattr(item, "payload")
+                else item.get("payload")
+                if isinstance(item, dict)
+                else {}
+            )
+            if isinstance(payload, dict) and payload.get("control_id"):
+                covered_control_ids.add(str(payload["control_id"]))
+        missing = sorted(control_id for control_id in gap_control_ids if control_id not in covered_control_ids)
+        checks.append(
+            _check(
+                "evidence_gaps_have_actions",
+                not missing,
+                {"missing_control_ids": missing},
+                weight=2,
+            )
+        )
+        coverage = {
+            **coverage,
+            "evidence_gaps_total": len(evidence_gaps),
+            "covered_evidence_gap_controls": len(gap_control_ids) - len(missing),
+            "evidence_gap_coverage": 1.0
+            if not gap_control_ids
+            else round((len(gap_control_ids) - len(missing)) / len(gap_control_ids), 4),
+        }
+    return _result(checks, coverage)
+
+
+def evaluate_posture_review(state: dict[str, Any]) -> dict[str, Any]:
+    """Evaluate posture-review guardrails and deterministic confidence."""
+    return evaluate_agent_run(state, use_case="posture_review")
+
+
+def evaluate_soc_triage(state: dict[str, Any]) -> dict[str, Any]:
+    """Evaluate SOC triage-specific deterministic guardrails."""
+    base = evaluate_agent_run(state, use_case="soc_triage")
+    alerts = [row for row in state.get("alerts", []) if isinstance(row, dict)]
+    high_priority = {
+        str(row.get("event_id") or "")
+        for row in alerts
+        if str(row.get("status") or "").lower() in {"open", "failed", "blocked", "noncompliant"}
+        and str(row.get("severity") or "").lower() in {"critical", "high"}
+    }
+    covered = set()
+    for item in _decision_items(state):
+        payload = (
+            getattr(item, "payload", None)
+            if hasattr(item, "payload")
+            else item.get("payload")
+            if isinstance(item, dict)
+            else {}
+        )
+        if isinstance(payload, dict):
+            covered.add(str(payload.get("event_id") or ""))
+    missing = sorted(event_id for event_id in high_priority if event_id and event_id not in covered)
+    check = _check(
+        "high_priority_alerts_have_actions",
+        not missing,
+        {"missing_event_ids": missing},
+        weight=3,
+    )
+    coverage = {
+        **base["coverage"],
+        "alerts_total": len(alerts),
+        "high_priority_alerts": len([event_id for event_id in high_priority if event_id]),
+        "covered_high_priority_alerts": len([event_id for event_id in high_priority if event_id]) - len(missing),
+        "high_priority_coverage": 1.0
+        if not high_priority
+        else round((len([event_id for event_id in high_priority if event_id]) - len(missing)) / len(high_priority), 4),
+    }
+    return _result([*base["checks"], check], coverage)

security_lakehouse/agents/graphs.py

@@ -0,0 +1,199 @@
+"""Optional LangGraph workflows around TrustOps facts."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from security_lakehouse.agents.budgets import AgentBudgetPolicy
+from security_lakehouse.agents.checkpoints import invoke_with_checkpoint, memory_checkpointer
+from security_lakehouse.agents.evaluations import evaluate_posture_review
+from security_lakehouse.agents.model_client import ModelClientError, call_model_json
+from security_lakehouse.agents.model_contract import (
+    POSTURE_REVIEW_TOOL_CALLS,
+    build_model_context,
+    validate_model_output,
+)
+from security_lakehouse.agents.providers import ModelProviderConfig, provider_from_env
+from security_lakehouse.agents.state import AgentDecision, AgentOrchestrator, AgentRunState
+from security_lakehouse.agents.tools import (
+    assess_data_readiness,
+    load_evidence_gaps,
+    load_redacted_posture,
+    propose_evidence_gap_actions,
+)
+
+ModelClient = Callable[[dict[str, Any], ModelProviderConfig], dict[str, Any]]
+
+
+def _initial_posture_state(
+    lake_dir: str | Path,
+    *,
+    role: str,
+    objective: str,
+    provider: ModelProviderConfig,
+    budget: AgentBudgetPolicy,
+    orchestrator: AgentOrchestrator,
+) -> AgentRunState:
+    return {
+        "lake_dir": str(lake_dir),
+        "role": role,
+        "objective": objective,
+        "mode": "rules_only",
+        "orchestrator": orchestrator,
+        "model_provider": provider.public_dict(),
+        "agent_budget": budget.public_dict(),
+        "data_readiness": assess_data_readiness(lake_dir, role=role, harness="posture_review"),
+        "errors": [],
+    }
+
+
+def _load_posture_node(state: AgentRunState) -> AgentRunState:
+    return {
+        **state,
+        "posture": load_redacted_posture(state["lake_dir"], role=state.get("role", "read_only")),
+    }
+
+
+def _load_gaps_node(state: AgentRunState) -> AgentRunState:
+    return {
+        **state,
+        "evidence_gaps": load_evidence_gaps(state["lake_dir"], role=state.get("role", "read_only")),
+    }
+
+
+def _propose_actions_node(state: AgentRunState) -> AgentRunState:
+    decisions = [
+        AgentDecision(
+            action=str(item["action"]),
+            reason=str(item["reason"]),
+            requires_approval=bool(item["requires_approval"]),
+            payload={"control_id": item["control_id"]},
+            status="proposed",
+        )
+        for item in propose_evidence_gap_actions(state.get("evidence_gaps", []))
+    ]
+    return {**state, "decisions": decisions}
+
+
+def _finalize_no_gaps_node(state: AgentRunState) -> AgentRunState:
+    return {**state, "decisions": []}
+
+
+def run_posture_review(
+    lake_dir: str | Path,
+    *,
+    role: str = "read_only",
+    objective: str = "Review posture and propose evidence-gap actions.",
+    provider: ModelProviderConfig | None = None,
+    budget: AgentBudgetPolicy | None = None,
+    model_client: ModelClient | None = None,
+    orchestrator: AgentOrchestrator = "sequential",
+    checkpoint_thread_id: str | None = None,
+    resume: bool = False,
+) -> AgentRunState:
+    """Run the posture-review harness without requiring LangGraph or an LLM."""
+    provider = provider or provider_from_env()
+    budget = budget or AgentBudgetPolicy.from_env()
+    if orchestrator not in {"sequential", "langgraph"}:
+        raise ValueError("posture_review orchestrator must be 'sequential' or 'langgraph'")
+    state = _initial_posture_state(
+        lake_dir,
+        role=role,
+        objective=objective,
+        provider=provider,
+        budget=budget,
+        orchestrator=orchestrator,
+    )
+    if orchestrator == "langgraph":
+        state = dict(
+            invoke_with_checkpoint(
+                build_posture_review_graph(checkpointer=memory_checkpointer() if checkpoint_thread_id else None),
+                state,
+                thread_id=checkpoint_thread_id,
+                resume=resume,
+            )
+        )
+        state["mode"] = "langgraph"
+        state["orchestrator"] = "langgraph"
+    else:
+        state = _load_posture_node(state)
+        state = _load_gaps_node(state)
+        state = _propose_actions_node(state)
+    if provider.enabled:
+        context = build_model_context(dict(state), provider, budget=budget)
+        state["model_context"] = context
+        if context.get("budget", {}).get("status") == "over_budget":
+            state["errors"] = [*state.get("errors", []), "model_skipped: context_budget_exceeded"]
+        elif provider.should_call_model:
+            client = model_client or call_model_json
+            try:
+                raw_output = client(context, provider)
+                state["model_output"] = validate_model_output(raw_output, allowed_tool_calls=POSTURE_REVIEW_TOOL_CALLS)
+                state["mode"] = "model_assisted"
+            except ModelClientError as exc:
+                state["errors"] = [*state.get("errors", []), f"model_error: {exc}"]
+    state["evaluation"] = evaluate_posture_review(dict(state))
+    return state
+
+
+def build_posture_review_graph(*, checkpointer: Any | None = None) -> Any:
+    """Build a LangGraph StateGraph when the optional extra is installed."""
+    try:
+        from langgraph.graph import END, StateGraph
+    except ImportError as exc:  # pragma: no cover - exercised without optional extra
+        raise RuntimeError("install trustops-security-data-lake[agents] to use LangGraph orchestration") from exc
+
+    graph = StateGraph(AgentRunState)
+
+    def _route_after_gaps(state: AgentRunState) -> str:
+        gaps = state.get("evidence_gaps") or []
+        return "propose_actions" if gaps else "finalize_no_gaps"
+
+    graph.add_node("load_posture", _load_posture_node)
+    graph.add_node("load_evidence_gaps", _load_gaps_node)
+    graph.add_node("propose_actions", _propose_actions_node)
+    graph.add_node("finalize_no_gaps", _finalize_no_gaps_node)
+    graph.set_entry_point("load_posture")
+    graph.add_edge("load_posture", "load_evidence_gaps")
+    graph.add_conditional_edges(
+        "load_evidence_gaps",
+        _route_after_gaps,
+        {"propose_actions": "propose_actions", "finalize_no_gaps": "finalize_no_gaps"},
+    )
+    graph.add_edge("propose_actions", END)
+    graph.add_edge("finalize_no_gaps", END)
+    return graph.compile(checkpointer=checkpointer) if checkpointer is not None else graph.compile()
+
+
+def _load_alerts_node(state: AgentRunState) -> AgentRunState:
+    from security_lakehouse.agents.soc import load_soc_alerts
+
+    return {
+        **state,
+        "alerts": load_soc_alerts(state["lake_dir"], role=state.get("role", "read_only")),
+    }
+
+
+def _propose_soc_actions_node(state: AgentRunState) -> AgentRunState:
+    from security_lakehouse.agents.soc import propose_soc_actions
+
+    decisions = propose_soc_actions(state.get("alerts") or [])
+    return {**state, "decisions": decisions}
+
+
+def build_soc_triage_graph(*, checkpointer: Any | None = None) -> Any:
+    """Build the SOC triage LangGraph when the optional extra is installed."""
+    try:
+        from langgraph.graph import END, StateGraph
+    except ImportError as exc:  # pragma: no cover
+        raise RuntimeError("install trustops-security-data-lake[agents] to use LangGraph orchestration") from exc
+
+    graph = StateGraph(AgentRunState)
+    graph.add_node("load_alerts", _load_alerts_node)
+    graph.add_node("propose_actions", _propose_soc_actions_node)
+    graph.set_entry_point("load_alerts")
+    graph.add_edge("load_alerts", "propose_actions")
+    graph.add_edge("propose_actions", END)
+    return graph.compile(checkpointer=checkpointer) if checkpointer is not None else graph.compile()