Strengthen message/tool validation and standardize ToolFunctionSchema APIs (#109)

* Fix: full message validator

* feat(core): add module docstring, runtime check for optimized mode, and refactor agent tool types

* Refactor: message validating

* Feat: did_you_mean hint

Author: JohnRichard4096

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "amrita_core"
-version = "0.10.3"
+version = "0.10.4"
 description = "High performance, flexible, lightweight agent framework."
 readme = "README.md"
 requires-python = ">=3.10,<3.15"

src/amrita_core/__init__.py

@@ -1,3 +1,48 @@
+"""AmritaCore — A lightweight Agent runtime.
+
+AmritaCore is a lightweight Agent runtime built on top of AmritaSense, providing
+native async streaming, tool integration, event hooks, and memory management.
+This module is the unified entry point for the AmritaCore library, organized
+by functional domain:
+
+Core Components
+    - **Config**: AmritaConfig, get_config, set_config
+    - **Preset Management**: PresetManager, PresetReport, ModelPreset, ModelConfig
+    - **Chat Management**: ChatManager, ChatObject, ChatObjectMeta, SuspendEnum
+    - **Agent Strategy**: AgentStrategy, AgentRuntime, create_agent
+
+Type System
+    - **Message**: BaseModel, UniResponse, UniResponseUsage
+    - **Tools**: ToolCall, ToolResult, ToolFunctionSchema, FunctionDefinitionSchema,
+      FunctionParametersSchema, FunctionPropertySchema, ToolContext, ToolData
+    - **Content**: TextContent, Function, MemoryModel
+
+Backends & Contexts
+    - **Backends**: AbilityBackend, MemoryBackend, LegacyBackend, BackendSlots
+    - **Contexts**: AbilityContext, StateContext
+
+Event Hooks
+    - **Events**: CompletionEvent, PreCompletionEvent, EventTypeEnum
+    - **Registration**: on_completion, on_event, on_precompletion
+
+Tool System
+    - **Management**: ToolsManager, on_tools, simple_tool
+    - **MCP**: mcp
+
+Chat API
+    - call_completion, tools_caller, text_generator, get_last_response, get_tokens
+
+Initialization
+    - load_amrita(): Full initialization with built-in components and MCP clients
+    - minimal_init(): Minimal initialization
+
+Note: AmritaCore must NOT be run in Python optimized mode (-O / --optimize).
+"""
+
+if not __debug__:  # fast-fail in optimized mode
+    raise RuntimeError(
+        "AmritaCore is running in optimized mode, which will affect functionality. Please run without -O or --optimize flag."
+    )
 from amrita_sense.logging import debug_log, logger
 from amrita_sense.streaming import SuspendObjectStream
 

src/amrita_core/base/adapter.py

@@ -8,6 +8,7 @@
 from amrita_sense.logging import logger
 
 from amrita_core.config import AmritaConfig, get_config
+from amrita_core.utils import _did_you_mean_hint
 
 from ..tools.models import ToolChoice, ToolFunctionSchema
 from ..types import EmbeddingChunk, ModelPreset, ToolCall, UniResponse
@@ -120,7 +121,8 @@ def safe_get_adapter(self, protocol: str) -> type[ModelAdapter] | None:
     def get_adapter(self, protocol: str) -> type[ModelAdapter]:
         """Get adapter"""
         if protocol not in self._adapter_class:
-            raise ValueError(f"No adapter found for protocol {protocol}")
+            hint = _did_you_mean_hint(protocol, list(self._adapter_class.keys()))
+            raise ValueError(f"No adapter found for protocol '{protocol}'.{hint}")
         return self._adapter_class[protocol]
 
     def register_adapter(self, adapter: type[ModelAdapter]):

src/amrita_core/base/tokenizer.py

@@ -3,6 +3,8 @@
 
 from amrita_sense.logging import logger
 
+from amrita_core.utils import _did_you_mean_hint
+
 
 class BaseTokenizer(ABC):
     __override__: bool = False  # Whether to allow overriding existing tokenizers
@@ -89,7 +91,8 @@ def safe_get_tokenizer(self, tok_type: str) -> type[BaseTokenizer] | None:
     def get_tokenizer(self, tok_type: str) -> type[BaseTokenizer]:
         """Get tokenizer"""
         if tok_type not in self._tokenizer_class:
-            raise ValueError(f"No tokenizer found for tok_type {tok_type}")
+            hint = _did_you_mean_hint(tok_type, list(self._tokenizer_class.keys()))
+            raise ValueError(f"No tokenizer found for tok_type '{tok_type}'.{hint}")
         return self._tokenizer_class[tok_type]
 
     def register_tokenizer(self, tokenizer: type[BaseTokenizer]):

src/amrita_core/builtins/agent.py

@@ -19,6 +19,7 @@
     get_last_response,
     tools_caller,
 )
+from amrita_core.tools.models import ToolFunctionSchema
 from amrita_core.types import (
     CONTENT_LIST_TYPE_ITEM,
     Function,
@@ -56,6 +57,13 @@
 )
 
 
+def _resolve_tool_name(tool: ToolFunctionSchema | dict) -> str:
+    """Resolve the function name from a tool schema (object or dict form)."""
+    if isinstance(tool, dict):
+        return tool.get("function", {}).get("name", "")
+    return tool.function.name
+
+
 class BaseReActAgentStrategy(AgentStrategy, ABC):
     """
     Abstract base class for ReAct agent strategies with common execution logic.
@@ -93,7 +101,7 @@ class BaseReActAgentStrategy(AgentStrategy, ABC):
 
     agent_last_step: str | None = None
     call_count = 1
-    tools: list[Any]
+    tools: list[ToolFunctionSchema]
     origin_msg: str = ""
     origin_instruction: str = ""
     reasoning_pc = 0
@@ -112,8 +120,8 @@ def __init__(self, ctx: StrategyContext):
         self.origin_instruction = self.chat_object.train.content
         config = self.chat_object.config
         if config.builtin.tool_calling_mode == "agent":
-            self.tools.append(STOP_TOOL.model_dump())
-        self.tools.extend(self.tools_manager.tools_meta_dict().values())
+            self.tools.append(STOP_TOOL)
+        self.tools.extend(self.tools_manager.tools_meta().values())
         #  Initialize reasoning enhancement state
         self._predicted_tools = []
         self.origin_msg: str = (
@@ -131,8 +139,8 @@ async def _generate_reasoning_content(
     ) -> UniResponse[str, None]:
         tools = [
             {
-                "name": tool["function"]["name"],
-                "description": tool["function"]["description"],
+                "name": tool.function.name,
+                "description": tool.function.description,
             }
             for tool in self.tools
         ]
@@ -362,7 +370,7 @@ async def _run_reflection(
 
             tool_response = await tools_caller(
                 msg_list,
-                [REFLECTION_TOOL.model_dump()],
+                [REFLECTION_TOOL],
                 tool_choice=REFLECTION_TOOL,
                 preset=self.ctx.chat_object.preset,
             )
@@ -421,7 +429,7 @@ async def _run_reflection(
 
     async def _generate_reasoning_msg(
         self,
-        tools_ctx: list[dict[str, Any]],
+        tools_ctx: list[ToolFunctionSchema],
         /,
         then: Callable[
             [
@@ -447,7 +455,7 @@ async def _generate_reasoning_msg(
         ]
         tool_response: UniResponse[None, list[ToolCall] | None] = await tools_caller(
             reasoning_trigger_msg,
-            [REASONING_TOOL.model_dump(), *tools_ctx],
+            [REASONING_TOOL, *tools_ctx],
             tool_choice=REASONING_TOOL,
             preset=self.ctx.chat_object.preset,
         )
@@ -840,7 +848,9 @@ async def _handle_tool_error_common(
         Returns:
             Error message string
         """
-        logger.error(f"Function {function_name} execution failed: {err}")
+        logger.opt(exception=err, colors=True).error(
+            f"Function {function_name} execution failed: {err}"
+        )
         config = self.chat_object.config
         if (
             config.builtin.tool_calling_mode == "agent"
@@ -886,6 +896,7 @@ def get_category(
     ) -> Literal["workflow"]:
         return "workflow"
 
+
 class HybridReActAgentStrategy(BaseReActAgentStrategy):
     """**Hybrid ReAct Agent Strategy optimized for Mixture of Experts (MoE) architecture models.**
 
@@ -1087,7 +1098,7 @@ async def single_execute(
             return False
         tools = self.tools.copy()
         if config.builtin.agent_thought_mode.startswith("reasoning"):
-            tools.append(REASONING_TOOL.model_dump())
+            tools.append(REASONING_TOOL)
 
         if (
             self._predicted_tools
@@ -1096,15 +1107,16 @@ async def single_execute(
             and config.builtin.react_config.reasoning_aware_tools
         ):
             prioritized = [
-                t for t in tools if t["function"]["name"] in self._predicted_tools
+                t for t in tools if _resolve_tool_name(t) in self._predicted_tools
             ]
             others = [
-                t for t in tools if t["function"]["name"] not in self._predicted_tools
+                t for t in tools if _resolve_tool_name(t) not in self._predicted_tools
             ]
             tools = prioritized + others
             logger.debug(
-                f"Reasoning-aware tools: {[t['function']['name'] for t in prioritized]} "
-                f"ahead of {len(others)} others"
+                f"Reasoning-aware tools:"
+                f" {[_resolve_tool_name(t) for t in prioritized]}"
+                f" ahead of {len(others)} others"
             )
 
         response_msg: UniResponse[None, list[ToolCall] | None] = await tools_caller(
@@ -1320,7 +1332,7 @@ async def single_execute(
             return False
         tools = self.tools.copy()
         if config.builtin.agent_thought_mode.startswith("reasoning"):
-            tools.append(REASONING_TOOL.model_dump())
+            tools.append(REASONING_TOOL)
 
         if (
             self._predicted_tools
@@ -1329,15 +1341,16 @@ async def single_execute(
             and config.builtin.react_config.reasoning_aware_tools
         ):
             prioritized = [
-                t for t in tools if t["function"]["name"] in self._predicted_tools
+                t for t in tools if _resolve_tool_name(t) in self._predicted_tools
             ]
             others = [
-                t for t in tools if t["function"]["name"] not in self._predicted_tools
+                t for t in tools if _resolve_tool_name(t) not in self._predicted_tools
             ]
             tools = prioritized + others
             logger.debug(
-                f"Reasoning-aware tools: {[t['function']['name'] for t in prioritized]} "
-                f"ahead of {len(others)} others"
+                f"Reasoning-aware tools:"
+                f" {[_resolve_tool_name(t) for t in prioritized]}"
+                f" ahead of {len(others)} others"
             )
 
         response_msg: UniResponse[None, list[ToolCall] | None] = await tools_caller(

src/amrita_core/builtins/tools.py

@@ -73,6 +73,7 @@
             },
             required=[
                 "summary",
+                "last_step",
             ],
         ),
     ),