secenvY 0.1.0__py3-none-any.whl

secenvY/__init__.py

@@ -0,0 +1,43 @@
+"""Android Security Analyzer Gymnasium Environment & Agent (SecEnv)."""
+
+import gymnasium as gym
+
+# Register standard AndroidSecurityEnv-v0 environment
+gym.register(
+    id="AndroidSecurityEnv-v0",
+    entry_point="secenvY.env.security_env:SecurityEnv",
+    max_episode_steps=100,
+)
+
+from secenvY.agents.dqn_agent import DuelingDQNAgent
+from secenvY.agents.networks import DuelingQNetwork
+from secenvY.agents.replay_buffer import PrioritizedReplayBuffer, UniformReplayBuffer
+from secenvY.env.security_env import SecurityEnv
+from secenvY.gateway.base import SystemGateway
+from secenvY.gateway.mock_gateway import MockSystemGateway
+from secenvY.gateway.websocket_gateway import WebSocketSystemGateway
+from secenvY.services.action_mapper import ActionMapper
+from secenvY.services.episode_policy import EpisodePolicy
+from secenvY.services.reward_calculator import RewardCalculator
+from secenvY.services.state_builder import StateBuilder
+from secenvY.services.state_encoder import StateEncoder
+from secenvY.services.state_validator import StateValidator
+from secenvY.services.tensor_converter import TensorConverter
+
+__all__ = [
+    "SecurityEnv",
+    "DuelingDQNAgent",
+    "DuelingQNetwork",
+    "PrioritizedReplayBuffer",
+    "UniformReplayBuffer",
+    "SystemGateway",
+    "MockSystemGateway",
+    "WebSocketSystemGateway",
+    "ActionMapper",
+    "StateBuilder",
+    "StateEncoder",
+    "StateValidator",
+    "TensorConverter",
+    "RewardCalculator",
+    "EpisodePolicy",
+]

secenvY/agents/__init__.py

@@ -0,0 +1,17 @@
+"""Dueling Double Deep Q-Network agent, neural network architectures, and replay buffers."""
+
+from secenvY.agents.dqn_agent import DuelingDQNAgent
+from secenvY.agents.networks import DuelingQNetwork
+from secenvY.agents.replay_buffer import (
+    PrioritizedReplayBuffer,
+    SumTree,
+    UniformReplayBuffer,
+)
+
+__all__ = [
+    "DuelingDQNAgent",
+    "DuelingQNetwork",
+    "PrioritizedReplayBuffer",
+    "UniformReplayBuffer",
+    "SumTree",
+]

secenvY/agents/dqn_agent.py

@@ -0,0 +1,225 @@
+"""Dueling Double Deep Q-Network (Dueling Double DQN) Agent with Prioritized Experience Replay."""
+
+from __future__ import annotations
+
+import os
+import random
+from typing import Any, Dict, List, Optional, Tuple, Union
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.optim as optim
+
+from secenvY.agents.networks import DuelingQNetwork
+from secenvY.agents.replay_buffer import PrioritizedReplayBuffer, UniformReplayBuffer
+
+
+class DuelingDQNAgent:
+    """Reinforcement Learning Agent implementing Dueling Double DQN with Prioritized Experience Replay (PER).
+
+    Args:
+        state_dim: Dimension of observation tensor (default: 117).
+        action_dim: Number of discrete actions (default: 8).
+        hidden_dim: Hidden dimension of backbone network (default: 256).
+        lr: Learning rate for Adam optimizer (default: 1e-4).
+        gamma: Discount factor for Bellman target (default: 0.99).
+        tau: Soft target network update coefficient (default: 0.005).
+        target_update_interval: Hard update interval if tau is 1.0 (default: 500).
+        buffer_capacity: Max transitions stored in experience replay (default: 100,000).
+        use_per: Whether to use Prioritized Experience Replay (default: True).
+        per_alpha: PER prioritization exponent (default: 0.6).
+        per_beta_start: Initial importance sampling exponent (default: 0.4).
+        max_grad_norm: Maximum gradient norm for clipping (default: 10.0).
+        device: Torch computing device (default: cpu / cuda if available).
+    """
+
+    def __init__(
+        self,
+        state_dim: int = 117,
+        action_dim: int = 8,
+        hidden_dim: int = 256,
+        lr: float = 1e-4,
+        gamma: float = 0.99,
+        tau: float = 0.005,
+        target_update_interval: int = 500,
+        buffer_capacity: int = 100_000,
+        use_per: bool = True,
+        per_alpha: float = 0.6,
+        per_beta_start: float = 0.4,
+        max_grad_norm: float = 10.0,
+        device: Optional[Union[str, torch.device]] = None,
+    ) -> None:
+        if device is None:
+            self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        else:
+            self.device = torch.device(device)
+
+        self.state_dim = state_dim
+        self.action_dim = action_dim
+        self.gamma = gamma
+        self.tau = tau
+        self.target_update_interval = target_update_interval
+        self.max_grad_norm = max_grad_norm
+        self.use_per = use_per
+
+        # Neural Networks: Online and Target Q-Networks
+        self.online_net = DuelingQNetwork(state_dim, action_dim, hidden_dim).to(self.device)
+        self.target_net = DuelingQNetwork(state_dim, action_dim, hidden_dim).to(self.device)
+        self.target_net.load_state_dict(self.online_net.state_dict())
+        self.target_net.eval()
+        for param in self.target_net.parameters():
+            param.requires_grad = False
+
+        # Optimizer and Huber Loss Criterion
+        self.optimizer = optim.Adam(self.online_net.parameters(), lr=lr, eps=1e-8)
+        self.criterion = nn.SmoothL1Loss(reduction="none")
+
+        # Replay Memory (PER or Uniform)
+        self.replay_buffer: Union[PrioritizedReplayBuffer, UniformReplayBuffer]
+        if use_per:
+            self.replay_buffer = PrioritizedReplayBuffer(
+                capacity=buffer_capacity,
+                alpha=per_alpha,
+                beta_start=per_beta_start,
+                device=self.device,
+            )
+        else:
+            self.replay_buffer = UniformReplayBuffer(
+                capacity=buffer_capacity,
+                device=self.device,
+            )
+
+        self.total_steps = 0
+        self.train_steps = 0
+
+    def select_action(
+        self,
+        state: np.ndarray | List[float],
+        epsilon: float = 0.0,
+        action_mask: Optional[Union[np.ndarray, List[bool]]] = None,
+    ) -> int:
+        """Select action using epsilon-greedy exploration policy with optional action masking.
+
+        Args:
+            state: State vector of shape (117,) or list of floats.
+            epsilon: Exploration probability in [0.0, 1.0].
+            action_mask: Optional boolean mask of shape (action_dim,) where True indicates valid action.
+
+        Returns:
+            Discrete action ID in range [0, action_dim - 1].
+        """
+        self.total_steps += 1
+
+        if action_mask is not None:
+            mask_arr = np.array(action_mask, dtype=bool)
+            valid_indices = np.where(mask_arr)[0]
+            if len(valid_indices) == 0:
+                valid_indices = np.arange(self.action_dim)
+        else:
+            valid_indices = np.arange(self.action_dim)
+
+        if random.random() < epsilon:
+            return int(random.choice(valid_indices))
+
+        state_tensor = torch.tensor(
+            np.array(state, dtype=np.float32),
+            device=self.device,
+            dtype=torch.float32,
+        ).unsqueeze(0)
+
+        self.online_net.eval()
+        with torch.no_grad():
+            q_values = self.online_net(state_tensor).squeeze(0)
+            if action_mask is not None:
+                mask_tensor = torch.tensor(mask_arr, device=self.device, dtype=torch.bool)
+                q_values[~mask_tensor] = -1e9
+            action = int(q_values.argmax(dim=-1).item())
+        self.online_net.train()
+
+        return action
+
+    def train_step(self, batch_size: int = 32) -> Optional[float]:
+        """Perform a single Double DQN training step over a batch from replay buffer.
+
+        Args:
+            batch_size: Number of transitions to sample.
+
+        Returns:
+            Computed scalar loss value, or None if buffer has insufficient transitions.
+        """
+        if len(self.replay_buffer) < batch_size:
+            return None
+
+        self.train_steps += 1
+
+        # 1. Sample batch
+        if self.use_per:
+            states, actions, rewards, next_states, dones, indices, weights = self.replay_buffer.sample(batch_size)  # type: ignore
+        else:
+            states, actions, rewards, next_states, dones = self.replay_buffer.sample(batch_size)  # type: ignore
+            weights = torch.ones_like(rewards)
+            indices = []
+
+        # 2. Compute current Q-values Q(s, a; θ)
+        current_q = self.online_net(states).gather(1, actions)
+
+        # 3. Double DQN Target: a* = argmax_{a'} Q(s', a'; θ), y = r + γ Q(s', a*; θ^-)
+        with torch.no_grad():
+            next_actions = self.online_net(next_states).argmax(dim=-1, keepdim=True)
+            target_q_next = self.target_net(next_states).gather(1, next_actions)
+            target_q = rewards + (1.0 - dones) * self.gamma * target_q_next
+
+        # 4. Compute TD Errors and Huber Loss
+        td_errors = (current_q - target_q).detach()
+        loss_elements = self.criterion(current_q, target_q)
+        loss = (loss_elements * weights).mean()
+
+        # 5. Backpropagation and Gradient Clipping
+        self.optimizer.zero_grad()
+        loss.backward()
+        if self.max_grad_norm > 0:
+            nn.utils.clip_grad_norm_(self.online_net.parameters(), max_norm=self.max_grad_norm)
+        self.optimizer.step()
+
+        # 6. Update PER priorities
+        if self.use_per and indices:
+            self.replay_buffer.update_priorities(indices, td_errors.abs())  # type: ignore
+
+        # 7. Update Target Network
+        self._update_target_network()
+
+        return float(loss.item())
+
+    def _update_target_network(self) -> None:
+        """Update target network parameters via Polyak soft update or periodic hard copy."""
+        if self.tau < 1.0:
+            # Soft Polyak update: θ^- ← τ θ + (1 - τ) θ^-
+            for target_param, online_param in zip(self.target_net.parameters(), self.online_net.parameters()):
+                target_param.data.copy_(self.tau * online_param.data + (1.0 - self.tau) * target_param.data)
+        else:
+            # Hard periodic update
+            if self.train_steps % self.target_update_interval == 0:
+                self.target_net.load_state_dict(self.online_net.state_dict())
+
+    def save_checkpoint(self, filepath: str) -> None:
+        """Save model and optimizer state to disk."""
+        os.makedirs(os.path.dirname(os.path.abspath(filepath)), exist_ok=True)
+        torch.save(
+            {
+                "online_net_state": self.online_net.state_dict(),
+                "target_net_state": self.target_net.state_dict(),
+                "optimizer_state": self.optimizer.state_dict(),
+                "total_steps": self.total_steps,
+                "train_steps": self.train_steps,
+            },
+            filepath,
+        )
+
+    def load_checkpoint(self, filepath: str) -> None:
+        """Load model and optimizer state from disk."""
+        checkpoint = torch.load(filepath, map_location=self.device)
+        self.online_net.load_state_dict(checkpoint["online_net_state"])
+        self.target_net.load_state_dict(checkpoint["target_net_state"])
+        self.optimizer.load_state_dict(checkpoint["optimizer_state"])
+        self.total_steps = checkpoint.get("total_steps", 0)
+        self.train_steps = checkpoint.get("train_steps", 0)

secenvY/agents/networks.py

@@ -0,0 +1,81 @@
+"""PyTorch neural network architectures for Dueling Deep Q-Networks."""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+
+class DuelingQNetwork(nn.Module):
+    """Dueling Deep Q-Network decomposing Q(s, a) into Value V(s) and Advantage A(s, a) streams.
+
+    Q(s, a) = V(s) + (A(s, a) - 1/|A| * sum_{a'} A(s, a'))
+
+    Args:
+        state_dim: Input observation space dimension (default: 117).
+        action_dim: Discrete action space size (default: 8).
+        hidden_dim: Number of hidden units in backbone layers (default: 256).
+    """
+
+    def __init__(
+        self,
+        state_dim: int = 117,
+        action_dim: int = 8,
+        hidden_dim: int = 256,
+    ) -> None:
+        super().__init__()
+        self.state_dim = state_dim
+        self.action_dim = action_dim
+
+        # Shared Feature Extractor Backbone
+        self.backbone = nn.Sequential(
+            nn.Linear(state_dim, hidden_dim),
+            nn.LayerNorm(hidden_dim),
+            nn.ReLU(),
+            nn.Linear(hidden_dim, hidden_dim),
+            nn.ReLU(),
+        )
+
+        # Value Stream: V(s) -> [B, 1]
+        self.value_stream = nn.Sequential(
+            nn.Linear(hidden_dim, hidden_dim // 2),
+            nn.ReLU(),
+            nn.Linear(hidden_dim // 2, 1),
+        )
+
+        # Advantage Stream: A(s, a) -> [B, action_dim]
+        self.advantage_stream = nn.Sequential(
+            nn.Linear(hidden_dim, hidden_dim // 2),
+            nn.ReLU(),
+            nn.Linear(hidden_dim // 2, action_dim),
+        )
+
+    def forward(self, state: torch.Tensor) -> torch.Tensor:
+        """Forward pass computing Q-values for all discrete actions.
+
+        Args:
+            state: Tensor of shape (batch_size, state_dim) or (state_dim,).
+
+        Returns:
+            Tensor of shape (batch_size, action_dim) containing Q-values.
+        """
+        if state.dim() == 1:
+            state = state.unsqueeze(0)
+
+        features = self.backbone(state)
+        value = self.value_stream(features)             # [B, 1]
+        advantage = self.advantage_stream(features)     # [B, action_dim]
+
+        # Aggregation: Q(s, a) = V(s) + (A(s, a) - mean(A(s, :)))
+        q_values = value + (advantage - advantage.mean(dim=-1, keepdim=True))
+        return q_values
+
+    def compute_value_and_advantage(self, state: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+        """Expose raw value and advantage streams for inspection and explainability."""
+        if state.dim() == 1:
+            state = state.unsqueeze(0)
+
+        features = self.backbone(state)
+        value = self.value_stream(features)
+        advantage = self.advantage_stream(features)
+        return value, advantage

secenvY/agents/replay_buffer.py

@@ -0,0 +1,205 @@
+"""Uniform and Prioritized Experience Replay buffers for RL agents."""
+
+from __future__ import annotations
+
+from collections import deque
+import random
+from typing import List, Optional, Tuple
+import numpy as np
+import torch
+
+
+class UniformReplayBuffer:
+    """Standard circular Experience Replay buffer sampling uniformly at random."""
+
+    def __init__(self, capacity: int = 100_000, device: Optional[torch.device] = None) -> None:
+        self.capacity = capacity
+        self.device = device or torch.device("cpu")
+        self.buffer: deque = deque(maxlen=capacity)
+
+    def push(
+        self,
+        state: np.ndarray | List[float],
+        action: int,
+        reward: float,
+        next_state: np.ndarray | List[float],
+        done: bool,
+    ) -> None:
+        """Add a transition tuple to the buffer."""
+        self.buffer.append((
+            np.array(state, dtype=np.float32),
+            int(action),
+            float(reward),
+            np.array(next_state, dtype=np.float32),
+            bool(done),
+        ))
+
+    def sample(self, batch_size: int) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+        """Sample a batch of transitions uniformly at random."""
+        transitions = random.sample(self.buffer, batch_size)
+        states, actions, rewards, next_states, dones = zip(*transitions)
+
+        return (
+            torch.tensor(np.array(states), dtype=torch.float32, device=self.device),
+            torch.tensor(actions, dtype=torch.long, device=self.device).unsqueeze(1),
+            torch.tensor(rewards, dtype=torch.float32, device=self.device).unsqueeze(1),
+            torch.tensor(np.array(next_states), dtype=torch.float32, device=self.device),
+            torch.tensor(dones, dtype=torch.float32, device=self.device).unsqueeze(1),
+        )
+
+    def __len__(self) -> int:
+        return len(self.buffer)
+
+
+class SumTree:
+    """Binary SumTree data structure for O(log N) prioritized sampling and priority updates."""
+
+    def __init__(self, capacity: int) -> None:
+        self.capacity = capacity
+        self.tree = np.zeros(2 * capacity - 1, dtype=np.float64)
+        self.data: List[Optional[Tuple[np.ndarray, int, float, np.ndarray, bool]]] = [None] * capacity
+        self.write_ptr = 0
+        self.n_entries = 0
+
+    def _propagate(self, idx: int, change: float) -> None:
+        parent = (idx - 1) // 2
+        self.tree[parent] += change
+        if parent != 0:
+            self._propagate(parent, change)
+
+    def _retrieve(self, idx: int, s: float) -> int:
+        left = 2 * idx + 1
+        right = left + 1
+
+        if left >= len(self.tree):
+            return idx
+
+        if s <= self.tree[left]:
+            return self._retrieve(left, s)
+        else:
+            return self._retrieve(right, s - self.tree[left])
+
+    @property
+    def total_priority(self) -> float:
+        return float(self.tree[0])
+
+    def add(self, priority: float, data: Tuple[np.ndarray, int, float, np.ndarray, bool]) -> None:
+        tree_idx = self.write_ptr + self.capacity - 1
+        self.data[self.write_ptr] = data
+        self.update(tree_idx, priority)
+
+        self.write_ptr = (self.write_ptr + 1) % self.capacity
+        if self.n_entries < self.capacity:
+            self.n_entries += 1
+
+    def update(self, tree_idx: int, priority: float) -> None:
+        change = priority - self.tree[tree_idx]
+        self.tree[tree_idx] = priority
+        if tree_idx != 0:
+            self._propagate(tree_idx, change)
+
+    def get_leaf(self, val: float) -> Tuple[int, float, Tuple[np.ndarray, int, float, np.ndarray, bool]]:
+        tree_idx = self._retrieve(0, val)
+        data_idx = tree_idx - self.capacity + 1
+        return tree_idx, float(self.tree[tree_idx]), self.data[data_idx]  # type: ignore
+
+
+class PrioritizedReplayBuffer:
+    """Prioritized Experience Replay (PER) buffer using SumTree for efficient sampling."""
+
+    def __init__(
+        self,
+        capacity: int = 100_000,
+        alpha: float = 0.6,
+        beta_start: float = 0.4,
+        beta_frames: int = 100_000,
+        eps: float = 1e-5,
+        device: Optional[torch.device] = None,
+    ) -> None:
+        self.tree = SumTree(capacity)
+        self.capacity = capacity
+        self.alpha = alpha
+        self.beta_start = beta_start
+        self.beta_frames = beta_frames
+        self.eps = eps
+        self.device = device or torch.device("cpu")
+        self.max_priority = 1.0
+        self.frame = 0
+
+    def _get_beta(self) -> float:
+        return min(1.0, self.beta_start + self.frame * (1.0 - self.beta_start) / max(1, self.beta_frames))
+
+    def push(
+        self,
+        state: np.ndarray | List[float],
+        action: int,
+        reward: float,
+        next_state: np.ndarray | List[float],
+        done: bool,
+    ) -> None:
+        """Add transition with maximal priority to ensure initial exploration."""
+        data = (
+            np.array(state, dtype=np.float32),
+            int(action),
+            float(reward),
+            np.array(next_state, dtype=np.float32),
+            bool(done),
+        )
+        priority = (self.max_priority + self.eps) ** self.alpha
+        self.tree.add(priority, data)
+
+    def sample(
+        self, batch_size: int
+    ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, List[int], torch.Tensor]:
+        """Sample a batch proportionally to priorities with Importance Sampling weights."""
+        self.frame += 1
+        beta = self._get_beta()
+
+        segment = self.tree.total_priority / batch_size
+        indices: List[int] = []
+        priorities: List[float] = []
+        transitions: List[Tuple[np.ndarray, int, float, np.ndarray, bool]] = []
+
+        for i in range(batch_size):
+            a = segment * i
+            b = segment * (i + 1)
+            s = random.uniform(a, b)
+            tree_idx, p, data = self.tree.get_leaf(s)
+
+            if data is None:
+                # Fallback for floating point boundary
+                tree_idx, p, data = self.tree.get_leaf(random.uniform(0, max(1e-5, self.tree.total_priority)))
+
+            indices.append(tree_idx)
+            priorities.append(max(self.eps, p))
+            transitions.append(data)
+
+        # Importance sampling weights: w_i = (N * P(i))^(-beta) / max(w)
+        probs = np.array(priorities) / max(1e-8, self.tree.total_priority)
+        weights = (len(self) * probs) ** (-beta)
+        weights = weights / weights.max()
+
+        states, actions, rewards, next_states, dones = zip(*transitions)
+
+        return (
+            torch.tensor(np.array(states), dtype=torch.float32, device=self.device),
+            torch.tensor(actions, dtype=torch.long, device=self.device).unsqueeze(1),
+            torch.tensor(rewards, dtype=torch.float32, device=self.device).unsqueeze(1),
+            torch.tensor(np.array(next_states), dtype=torch.float32, device=self.device),
+            torch.tensor(dones, dtype=torch.float32, device=self.device).unsqueeze(1),
+            indices,
+            torch.tensor(weights, dtype=torch.float32, device=self.device).unsqueeze(1),
+        )
+
+    def update_priorities(self, indices: List[int], td_errors: np.ndarray | torch.Tensor) -> None:
+        """Update transition priorities with new TD errors."""
+        if isinstance(td_errors, torch.Tensor):
+            td_errors = td_errors.detach().cpu().numpy().flatten()
+
+        for idx, error in zip(indices, td_errors):
+            p = float((abs(error) + self.eps) ** self.alpha)
+            self.tree.update(idx, p)
+            self.max_priority = max(self.max_priority, abs(error))
+
+    def __len__(self) -> int:
+        return self.tree.n_entries

secenvY/core/__init__.py

@@ -0,0 +1,109 @@
+"""Core schemas, vocabularies, and exception definitions for secenvY."""
+
+from secenvY.core.exceptions import (
+    EpisodeInactiveError,
+    GatewayError,
+    InvalidActionError,
+    SecurityEnvError,
+    SessionError,
+    StateValidationError,
+    ValidationError,
+)
+from secenvY.core.schemas import (
+    ActionCommand,
+    AndroidState,
+    AppMetadataState,
+    DynamicCryptoRuntimeState,
+    DynamicExportedIPCState,
+    DynamicLoggingState,
+    DynamicNetworkState,
+    DynamicStorageState,
+    DynamicUIState,
+    DynamicWebViewRuntimeState,
+    ExecutionResult,
+    ExplorationCoverageState,
+    MetaAction,
+    PermissionState,
+    RAGSecurityEvaluation,
+    RuntimeLifecycleState,
+    SecurityAnalysis,
+    Severity,
+    StaticAttackSurfaceState,
+    StaticCallGraphState,
+    StaticCryptoState,
+    StaticStorageState,
+    StaticWebViewState,
+    TransitionRecord,
+    VulnerabilityFlags,
+)
+from secenvY.core.vocabularies import (
+    ACTION_CATEGORIES,
+    ACTION_CATEGORIES_LIST,
+    ACTION_CATEGORIES_MAP,
+    CRITICAL_PERMISSIONS,
+    CRITICAL_PERMISSIONS_LIST,
+    CRITICAL_PERMISSIONS_MAP,
+    CRYPTO_ALGORITHMS_LIST,
+    CRYPTO_ALGORITHMS_MAP,
+    STATIC_CRYPTO_ALGORITHMS,
+    ActionCategory,
+    CriticalPermission,
+    CryptoAlgorithm,
+)
+
+__all__ = [
+    # Exceptions
+    "SecurityEnvError",
+    "StateValidationError",
+    "ValidationError",
+    "GatewayError",
+    "InvalidActionError",
+    "SessionError",
+    "EpisodeInactiveError",
+    # Vocabularies & Enums
+    "ActionCategory",
+    "MetaAction",
+    "CriticalPermission",
+    "CryptoAlgorithm",
+    "CRITICAL_PERMISSIONS",
+    "CRITICAL_PERMISSIONS_LIST",
+    "CRITICAL_PERMISSIONS_MAP",
+    "STATIC_CRYPTO_ALGORITHMS",
+    "CRYPTO_ALGORITHMS_LIST",
+    "CRYPTO_ALGORITHMS_MAP",
+    "ACTION_CATEGORIES",
+    "ACTION_CATEGORIES_LIST",
+    "ACTION_CATEGORIES_MAP",
+    # Canonical State Models
+    "AndroidState",
+    "AppMetadataState",
+    "PermissionState",
+    "StaticAttackSurfaceState",
+    "StaticStorageState",
+    "StaticCryptoState",
+    "StaticWebViewState",
+    "StaticCallGraphState",
+    "RuntimeLifecycleState",
+    "DynamicUIState",
+    "DynamicLoggingState",
+    "DynamicStorageState",
+    "DynamicCryptoRuntimeState",
+    "DynamicWebViewRuntimeState",
+    "DynamicNetworkState",
+    "DynamicExportedIPCState",
+    "ExplorationCoverageState",
+    "VulnerabilityFlags",
+    # Commands & Results
+    "ActionCommand",
+    "ExecutionResult",
+    "TransitionRecord",
+    # RAG Reasoner Schemas
+    "Severity",
+    "RAGSecurityEvaluation",
+    "SecurityAnalysis",
+    # Transitional Aliases
+    "ValidatedObservation",
+    "StaticAnalysisContext",
+    "UIContext",
+    "FridaRuntimeSinks",
+]