langchain-agentx-python 0.4.9__tar.gz → 0.5.0__tar.gz

{langchain-agentx-python-0.4.9 → langchain-agentx-python-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.4.9
+Version: 0.5.0
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-0.4.9 → langchain-agentx-python-0.5.0}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "0.4.9"
+__version__ = "0.5.0"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

{langchain-agentx-python-0.4.9 → langchain-agentx-python-0.5.0}/langchain_agentx/tool_runtime/__init__.py

@@ -52,6 +52,7 @@ from .resolvers import (
     PermissionResolver,
     WorkflowPermissionResolver,
 )
+from .override import DenyOverrideManager, DenyOverrideRecord, enrich_blocked_deny_envelope
 from .session_store import AgentSessionStore, FileReadRecord, FileWriteRecord
 from .state_bridge import ToolStateBridge
 
@@ -97,6 +98,10 @@ __all__ = [
     "AgentSessionStore",
     "FileReadRecord",
     "FileWriteRecord",
+    # deny override (L4 UX seam)
+    "DenyOverrideRecord",
+    "DenyOverrideManager",
+    "enrich_blocked_deny_envelope",
     # pipeline
     "ToolOutputManager",
     "ToolExecutorPipeline",

{langchain-agentx-python-0.4.9 → langchain-agentx-python-0.5.0}/langchain_agentx/tool_runtime/adapter.py

@@ -58,6 +58,40 @@ from .base import RuntimeTool
 from .pipeline import ToolExecutorPipeline
 
 
+def _resolve_tool_call_id(
+    *,
+    config: RunnableConfig,
+    tool_runtime: ToolRuntime | None,
+    kwargs: dict[str, Any],
+) -> str | None:
+    """在构造 ctx 前解析 tool_call_id（对齐 CC toolUseID 贯穿决策链）。
+
+    优先级：ToolRuntime.tool_call_id → configurable → 工具入参 id 字段。
+    """
+    tid: str | None = None
+    if tool_runtime is not None:
+        raw = getattr(tool_runtime, "tool_call_id", None)
+        if isinstance(raw, str) and raw:
+            tid = raw
+
+    configurable = config.get("configurable", {}) or {}
+    if not tid:
+        for key in ("tool_call_id", "tool_use_id"):
+            val = configurable.get(key)
+            if isinstance(val, str) and val:
+                tid = val
+                break
+
+    if not tid:
+        for key in ("tool_call_id", "id"):
+            val = kwargs.get(key)
+            if isinstance(val, str) and val:
+                tid = val
+                break
+
+    return tid
+
+
 class LangChainAdapter:
     """
     LangChain 集成适配器。
@@ -298,12 +332,17 @@ class LangChainAdapter:
                 effective_tool_flags["sandbox_excluded_commands"] = configurable[
                     "sandbox_excluded_commands"
                 ]
+            resolved_tool_call_id = _resolve_tool_call_id(
+                config=config,
+                tool_runtime=tool_runtime,
+                kwargs=kwargs,
+            )
             return adapter.build_tool_execution_context(
                 tool_name=tool.name,
                 raw_input=kwargs,
                 state=effective_state,
                 config=config,
-                tool_call_id=getattr(tool_runtime, "tool_call_id", None),
+                tool_call_id=resolved_tool_call_id,
                 tool_flags=effective_tool_flags,
             )
 

{langchain-agentx-python-0.4.9 → langchain-agentx-python-0.5.0}/langchain_agentx/tool_runtime/auto_mode/__init__.py

@@ -40,6 +40,7 @@ from .allowlist import SafeToolAllowlist
 from .events import AutoModeDecisionEvent
 from .hook import AutoModeAuthHook
 from .factory import build_auto_mode_hook
+from .feedback import AutoModeFeedback, FeedbackIngest, feedback_from_decision_event
 from .rule_stripping import (
     CROSS_PLATFORM_CODE_EXEC,
     DEFAULT_DANGEROUS_BASH_PATTERNS,
@@ -72,6 +73,10 @@ __all__ = [
     "AutoModeAuthHook",
     # Factory
     "build_auto_mode_hook",
+    # Feedback
+    "AutoModeFeedback",
+    "FeedbackIngest",
+    "feedback_from_decision_event",
     # Rule Stripping
     "CROSS_PLATFORM_CODE_EXEC",
     "DEFAULT_DANGEROUS_BASH_PATTERNS",

langchain-agentx-python-0.5.0/langchain_agentx/tool_runtime/auto_mode/config_update.py

@@ -0,0 +1,59 @@
+"""
+tool_runtime/auto_mode/config_update.py — Auto Mode 配置热更新
+
+职责：
+    在运行时合并/替换 AutoModeConfig，并同步 PolicyEngine hook 与全局开关。
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any
+
+from .config import AutoModeConfig
+from .state import get_auto_mode_state
+
+if TYPE_CHECKING:
+    from ..policy import DefaultPolicyEngine, ToolPolicyConfig
+
+
+def merge_auto_mode_config(
+    current: AutoModeConfig | None,
+    *,
+    enabled: bool | None = None,
+    classifier_model: str | None = None,
+    use_classifier: bool | None = None,
+) -> AutoModeConfig:
+    """基于当前配置生成新的 AutoModeConfig（frozen dataclass replace）。"""
+    base = current if current is not None else AutoModeConfig()
+    fields: dict[str, Any] = {}
+    if enabled is not None:
+        fields["enabled"] = enabled
+    if classifier_model is not None:
+        fields["classifier_model"] = classifier_model
+    if use_classifier is not None:
+        fields["use_classifier"] = use_classifier
+    if not fields:
+        return base
+    return replace(base, **fields)
+
+
+def apply_auto_mode_config_to_engine(
+    engine: DefaultPolicyEngine,
+    config: AutoModeConfig,
+) -> None:
+    """将 AutoModeConfig 写入 DefaultPolicyEngine 与已挂载的 hook。"""
+    engine._config.auto_mode = config
+    hook = engine._auto_mode_hook
+    if hook is not None and hasattr(hook, "update_config"):
+        hook.update_config(config)
+    get_auto_mode_state().enabled = config.enabled
+
+
+def apply_auto_mode_config_to_policy(
+    policy_config: ToolPolicyConfig,
+    config: AutoModeConfig,
+) -> None:
+    """更新 ToolPolicyConfig.auto_mode 字段。"""
+    policy_config.auto_mode = config
+    get_auto_mode_state().enabled = config.enabled

{langchain-agentx-python-0.4.9 → langchain-agentx-python-0.5.0}/langchain_agentx/tool_runtime/auto_mode/decision.py

@@ -66,6 +66,12 @@ class AutoModeDecision:
     def to_authorization_decision(self) -> "AuthorizationDecision":
         """转换为 AuthorizationDecision（用于 PolicyEngine 集成）。"""
         from ..models import AuthorizationDecision
+        from ..permission_decision import (
+            POLICY_ID_PREFIX_AUTO_MODE,
+            PermissionDecisionType,
+            attach_decision_reason,
+            make_decision_reason,
+        )
 
         metadata = {
             "auto_mode_layer": self.layer,
@@ -78,12 +84,26 @@ class AutoModeDecision:
         if self.matched_pattern:
             metadata["auto_mode_pattern"] = self.matched_pattern
 
-        return AuthorizationDecision(
+        reason_type = (
+            PermissionDecisionType.CLASSIFIER
+            if self.layer == "L4"
+            else PermissionDecisionType.AUTO_MODE
+        )
+        decision = AuthorizationDecision(
             behavior=self.behavior,
             message=self.explanation,
-            policy_id=f"auto_mode_{self.layer}_{self.reason.value}",
+            policy_id=f"{POLICY_ID_PREFIX_AUTO_MODE}{self.layer}:{self.reason.value}",
             metadata=metadata,
         )
+        return attach_decision_reason(
+            decision,
+            make_decision_reason(
+                reason_type,
+                layer=self.layer,
+                reason=self.reason.value,
+                behavior=self.behavior,
+            ),
+        )
 
 
 @dataclass(frozen=True)

langchain-agentx-python-0.5.0/langchain_agentx/tool_runtime/auto_mode/feedback.py

@@ -0,0 +1,103 @@
+"""
+tool_runtime/auto_mode/feedback.py — Auto Mode 反馈摄入
+
+职责：
+    收集用户对 auto-approve 的纠正信号；有 endpoint 时 POST，否则追加本地 jsonl。
+
+链路位置：
+    UI/CLI → FeedbackIngest.submit → Analytics 或 ~/.cache/.../auto_mode_feedback.jsonl
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Literal
+from urllib import error as urllib_error
+from urllib import request as urllib_request
+
+
+@dataclass
+class AutoModeFeedback:
+    tool_use_id: str
+    tool_name: str
+    was_auto_approved: bool
+    user_correction: Literal["approve", "deny"] | None
+    model_family: str
+    timestamp: float
+    session_id: str | None = None
+    extra: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out = asdict(self)
+        if out.get("extra") is None:
+            out.pop("extra", None)
+        return out
+
+
+class FeedbackIngest:
+    """Auto Mode 反馈摄入：本地 jsonl 或 HTTP POST。"""
+
+    def __init__(
+        self,
+        endpoint: str | None = None,
+        *,
+        local_path: str | Path | None = None,
+        timeout_s: float = 10.0,
+    ) -> None:
+        self.endpoint = endpoint
+        self.timeout_s = timeout_s
+        if local_path is None:
+            local_path = Path.home() / ".cache" / "langchain_agentx" / "auto_mode_feedback.jsonl"
+        self._local_path = Path(local_path)
+
+    def submit(self, feedback: AutoModeFeedback) -> None:
+        """提交反馈：有 endpoint 时 POST，否则仅本地 jsonl。"""
+        if self.endpoint:
+            self._post_remote(feedback)
+        else:
+            self._append_local(feedback)
+
+    def _append_local(self, feedback: AutoModeFeedback) -> None:
+        self._local_path.parent.mkdir(parents=True, exist_ok=True)
+        line = json.dumps(feedback.to_dict(), ensure_ascii=False)
+        with self._local_path.open("a", encoding="utf-8") as f:
+            f.write(line + "\n")
+
+    def _post_remote(self, feedback: AutoModeFeedback) -> None:
+        body = json.dumps(feedback.to_dict()).encode("utf-8")
+        req = urllib_request.Request(
+            self.endpoint,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib_request.urlopen(req, timeout=self.timeout_s) as resp:
+                if resp.status >= 400:
+                    raise OSError(f"feedback endpoint returned {resp.status}")
+        except urllib_error.URLError as exc:
+            raise OSError(f"failed to POST auto-mode feedback: {exc}") from exc
+
+
+def feedback_from_decision_event(
+    *,
+    tool_use_id: str,
+    tool_name: str,
+    was_auto_approved: bool,
+    user_correction: Literal["approve", "deny"] | None = None,
+    model_family: str = "",
+    session_id: str | None = None,
+) -> AutoModeFeedback:
+    """从 UI 事件构造 AutoModeFeedback。"""
+    return AutoModeFeedback(
+        tool_use_id=tool_use_id,
+        tool_name=tool_name,
+        was_auto_approved=was_auto_approved,
+        user_correction=user_correction,
+        model_family=model_family,
+        timestamp=time.time(),
+        session_id=session_id,
+    )

{langchain-agentx-python-0.4.9 → langchain-agentx-python-0.5.0}/langchain_agentx/tool_runtime/auto_mode/hook.py

@@ -89,6 +89,10 @@ class AutoModeAuthHook:
         self._tool_registry = tool_registry
         self._event_bus = event_bus
 
+    def update_config(self, config: AutoModeConfig) -> None:
+        """热更新 Auto Mode 配置（下一笔 decide 立即生效）。"""
+        self._config = config
+
     def _emit_event(
         self,
         decision: AutoModeDecision,

{langchain-agentx-python-0.4.9 → langchain-agentx-python-0.5.0}/langchain_agentx/tool_runtime/loader.py

@@ -27,6 +27,13 @@ from langchain_core.tools import BaseTool
 from .adapter import LangChainAdapter
 from .base import RuntimeTool
 from .pipeline import ToolExecutorPipeline, ToolOutputManager
+from .auto_mode.config import AutoModeConfig
+from .auto_mode.config_update import (
+    apply_auto_mode_config_to_engine,
+    apply_auto_mode_config_to_policy,
+    merge_auto_mode_config,
+)
+from .auto_mode.state import get_auto_mode_state
 from .policy import DefaultPolicyEngine, PolicyEngine, ToolPolicyConfig
 from .registry import RuntimeToolRegistry
 from .prompt.handler import PermissionPromptHandler
@@ -73,6 +80,7 @@ class ToolRuntimeLoader:
             pipeline=self._pipeline,
             adapter=self._adapter,
         )
+        self._policy_config = policy_config
         # 优先使用外部传入的 policy_engine；其次从 policy_config 构造；否则为 None
         if policy_engine is not None:
             self._policy: PolicyEngine | None = policy_engine
@@ -214,6 +222,61 @@ class ToolRuntimeLoader:
         self._prompt_handler = prompt_handler
         self._pipeline.set_prompt_handler(prompt_handler)
 
+    def update_auto_mode_config(
+        self,
+        *,
+        enabled: bool | None = None,
+        classifier_model: str | None = None,
+        classifier_path: str | None = None,
+        use_classifier: bool | None = None,
+        auto_mode_config: AutoModeConfig | None = None,
+    ) -> AutoModeConfig:
+        """热更新 auto_mode 配置，下一轮 authorize 立即生效。
+
+        Args:
+            enabled: 总开关（同步 AutoModeState.enabled）
+            classifier_model: 分类器模型 ID
+            classifier_path: classifier_model 别名（历史命名兼容）
+            use_classifier: 是否启用 L4 LLM 分类器
+            auto_mode_config: 整包替换（优先级最高）
+
+        Returns:
+            生效后的 AutoModeConfig
+        """
+        model_id = classifier_model if classifier_model is not None else classifier_path
+
+        if auto_mode_config is not None:
+            effective = auto_mode_config
+        else:
+            current: AutoModeConfig | None = None
+            if self._policy_config is not None:
+                current = self._policy_config.auto_mode
+            elif isinstance(self._policy, DefaultPolicyEngine):
+                current = self._policy._config.auto_mode
+            effective = merge_auto_mode_config(
+                current,
+                enabled=enabled,
+                classifier_model=model_id,
+                use_classifier=use_classifier,
+            )
+
+        if self._policy_config is not None:
+            apply_auto_mode_config_to_policy(self._policy_config, effective)
+        if isinstance(self._policy, DefaultPolicyEngine):
+            apply_auto_mode_config_to_engine(self._policy, effective)
+        elif enabled is not None:
+            get_auto_mode_state().enabled = enabled
+
+        return effective
+
+    @property
+    def policy_config(self) -> ToolPolicyConfig | None:
+        return self._policy_config
+
+    @property
+    def policy(self) -> PolicyEngine | None:
+        return self._policy
+
     @property
     def registry(self) -> RuntimeToolRegistry:
         return self._registry

langchain-agentx-python-0.5.0/langchain_agentx/tool_runtime/override.py

@@ -0,0 +1,153 @@
+"""
+tool_runtime/override.py — deny 决策覆盖（L4 UX seam）
+
+职责：
+    记录 policy deny 的 tool_call，供 UI/CLI 展示覆盖横幅；
+    apply_override 更新会话态，实际重试由宿主命令路由触发。
+
+链路位置：
+    pipeline deny → enrich_blocked_deny_envelope → AgentSessionStore
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from .models import AuthorizationDecision, ToolExecutionContext, ToolResultEnvelope
+
+if TYPE_CHECKING:
+    from .session_store import AgentSessionStore
+
+OverrideDecision = Literal["allow", "confirm_deny"]
+OverrideActor = Literal["user", "admin"]
+RecordStatus = Literal["pending", "allow", "confirm_deny"]
+
+
+@dataclass
+class DenyOverrideRecord:
+    """单次 deny 的覆盖记录。"""
+
+    tool_call_id: str
+    tool_name: str
+    original_decision: AuthorizationDecision
+    override_decision: RecordStatus = "pending"
+    override_at: float | None = None
+    override_by: OverrideActor | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        orig = self.original_decision
+        return {
+            "tool_call_id": self.tool_call_id,
+            "tool_name": self.tool_name,
+            "original_decision": {
+                "behavior": orig.behavior,
+                "message": orig.message,
+                "policy_id": orig.policy_id,
+                "metadata": orig.metadata,
+            },
+            "override_decision": self.override_decision,
+            "override_at": self.override_at,
+            "override_by": self.override_by,
+        }
+
+
+class DenyOverrideManager:
+    """deny 覆盖管理器，绑定 AgentSessionStore。"""
+
+    _STORE_KEY = "_deny_overrides"
+
+    def __init__(self, session_store: AgentSessionStore) -> None:
+        self._store = session_store
+        if not hasattr(session_store, self._STORE_KEY):
+            setattr(session_store, self._STORE_KEY, {})
+
+    def _records(self) -> dict[str, DenyOverrideRecord]:
+        raw = getattr(self._store, self._STORE_KEY)
+        return raw if isinstance(raw, dict) else {}
+
+    def request_override(
+        self,
+        tool_call_id: str,
+        tool_name: str,
+        original_decision: AuthorizationDecision,
+        *,
+        override_by: OverrideActor = "user",
+    ) -> DenyOverrideRecord:
+        """标记某次 deny 为待覆盖状态，返回记录供 UI 展示。"""
+        if not tool_call_id:
+            raise ValueError("tool_call_id is required for deny override")
+
+        record = DenyOverrideRecord(
+            tool_call_id=tool_call_id,
+            tool_name=tool_name,
+            original_decision=original_decision,
+            override_decision="pending",
+            override_by=override_by,
+        )
+        self._records()[tool_call_id] = record
+        self._store.append_audit(
+            {
+                "event": "deny_override_requested",
+                "ts": time.time(),
+                **record.to_dict(),
+            }
+        )
+        return record
+
+    def get(self, tool_call_id: str) -> DenyOverrideRecord | None:
+        return self._records().get(tool_call_id)
+
+    def apply_override(self, tool_call_id: str, decision: OverrideDecision) -> bool:
+        """应用覆盖决策，更新会话状态。"""
+        records = self._records()
+        record = records.get(tool_call_id)
+        if record is None or record.override_decision != "pending":
+            return False
+
+        record.override_decision = decision
+        record.override_at = time.time()
+        self._store.append_audit(
+            {
+                "event": "deny_override_applied",
+                "ts": record.override_at,
+                "tool_call_id": tool_call_id,
+                "override_decision": decision,
+                "override_by": record.override_by,
+            }
+        )
+        return True
+
+    def list_pending(self) -> list[DenyOverrideRecord]:
+        return [r for r in self._records().values() if r.override_decision == "pending"]
+
+
+def enrich_blocked_deny_envelope(
+    envelope: ToolResultEnvelope,
+    *,
+    ctx: ToolExecutionContext,
+    auth: AuthorizationDecision,
+) -> ToolResultEnvelope:
+    """在 blocked deny envelope 上附加 can_override 并登记待覆盖记录。"""
+    tool_call_id = ctx.tool_call_id
+    if not tool_call_id or auth.behavior != "deny":
+        return envelope
+
+    meta = dict(envelope.meta or {})
+    meta["can_override"] = True
+    meta.setdefault("tool_call_id", tool_call_id)
+    meta.setdefault("policy_id", auth.policy_id)
+
+    store = ctx.session_store
+    if store is not None:
+        mgr = DenyOverrideManager(store)
+        record = mgr.request_override(
+            tool_call_id,
+            ctx.tool_name,
+            auth,
+        )
+        meta["deny_override"] = record.to_dict()
+
+    envelope.meta = meta
+    return envelope

langchain-agentx-python-0.5.0/langchain_agentx/tool_runtime/permission_decision.py

@@ -0,0 +1,99 @@
+"""
+tool_runtime/permission_decision.py — 权限决策结构化契约
+
+职责：
+    对齐 CC PermissionDecisionReason.type，提供稳定的 decision_reason 与
+    policy_id 解析辅助，避免调用方依赖字符串前缀嗅探。
+
+链路位置：
+    PolicyEngine / AutoModeDecision → AuthorizationDecision.metadata
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from .models import AuthorizationDecision
+
+
+class PermissionDecisionType(str, Enum):
+    """CC PermissionDecisionReason.type 对齐子集。"""
+
+    RULE = "rule"
+    MODE = "mode"
+    CLASSIFIER = "classifier"
+    HOOK = "hook"
+    AUTO_MODE = "auto_mode"
+
+
+# 公开 policy_id 前缀（文档化契约；新代码优先读 metadata["decision_reason"]）
+POLICY_ID_PREFIX_AUTO_MODE = "auto_mode:"
+POLICY_ID_PREFIX_ALWAYS_ASK_TOOL = "always_ask_tool:"
+POLICY_ID_PREFIX_DENY_GLOB = "deny_glob:"
+POLICY_ID_PREFIX_ASK_GLOB = "ask_glob:"
+
+
+def normalize_tool_name_set(names: Any) -> frozenset[str]:
+    """工具名集合归一化为小写 frozenset。"""
+    if names is None:
+        return frozenset()
+    if isinstance(names, frozenset):
+        return frozenset(n.lower() for n in names if isinstance(n, str) and n.strip())
+    return frozenset(str(n).strip().lower() for n in names if str(n).strip())
+
+
+def make_decision_reason(
+    reason_type: PermissionDecisionType | str,
+    **fields: Any,
+) -> dict[str, Any]:
+    """构造 CC 风格的 decision_reason 字典。"""
+    type_value = reason_type.value if isinstance(reason_type, PermissionDecisionType) else reason_type
+    out: dict[str, Any] = {"type": type_value}
+    for key, value in fields.items():
+        if value is not None:
+            out[key] = value
+    return out
+
+
+def attach_decision_reason(
+    decision: AuthorizationDecision,
+    reason: dict[str, Any],
+) -> AuthorizationDecision:
+    """将 decision_reason 写入 metadata（就地更新 metadata 引用）。"""
+    meta = dict(decision.metadata or {})
+    meta["decision_reason"] = reason
+    decision.metadata = meta
+    return decision
+
+
+def is_auto_mode_policy_id(policy_id: str | None) -> bool:
+    """判断 policy_id 是否来自 Auto Mode（稳定契约，非前缀嗅探首选）。"""
+    if not policy_id:
+        return False
+    return policy_id.startswith(POLICY_ID_PREFIX_AUTO_MODE) or policy_id.startswith("auto_mode_")
+
+
+def decision_type_from_policy_id(policy_id: str | None) -> PermissionDecisionType | None:
+    """从 policy_id 推断 decision_reason.type（向后兼容）。"""
+    if not policy_id:
+        return None
+    if is_auto_mode_policy_id(policy_id):
+        return PermissionDecisionType.AUTO_MODE
+    if policy_id.startswith(POLICY_ID_PREFIX_ALWAYS_ASK_TOOL):
+        return PermissionDecisionType.RULE
+    if policy_id.startswith(POLICY_ID_PREFIX_DENY_GLOB) or policy_id.startswith(
+        POLICY_ID_PREFIX_ASK_GLOB
+    ):
+        return PermissionDecisionType.RULE
+    if policy_id in ("read_only_mode", "builtin_deny", "read_roots", "write_roots"):
+        return PermissionDecisionType.RULE
+    return None
+
+
+def get_decision_reason(decision: AuthorizationDecision) -> dict[str, Any] | None:
+    """读取 metadata 中的 decision_reason。"""
+    if not decision.metadata:
+        return None
+    reason = decision.metadata.get("decision_reason")
+    return reason if isinstance(reason, dict) else None