feat: Add support for defining module input/output schemas using plain dictionaries and fix related executor/registry crashes.

Author: tercel

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.13.1] - 2026-03-19
+
+### Added
+- **Dict schema support** — Modules can now define `input_schema` / `output_schema` as plain JSON Schema dicts instead of Pydantic model classes. A `_DictSchemaAdapter` transparently wraps dict schemas at registration time so all internal code paths (executor, schema exporter, `get_definition`) work without changes.
+
+### Fixed
+- **`get_definition()` crash on dict schemas** — Previously called `.model_json_schema()` on dict objects, causing `AttributeError`
+- **Executor crash on dict schemas** — `call()`, `call_async()`, and `stream()` all called `.model_validate()` on dict objects
+
+### Improved
+- **File header docstrings** — Enhanced docstrings for `errors.py`, `executor.py`, and `version.py`
+
+---
+
 ## [0.13.0] - 2026-03-12
 
 ### Added

README.md

@@ -15,7 +15,7 @@ A schema-enforced module standard for the AI-Perceivable era.
 
 ## Features
 
-- **Schema-driven modules** -- Define input/output contracts using Pydantic models with automatic validation
+- **Schema-driven modules** -- Define input/output contracts using Pydantic models (with automatic validation) or plain JSON Schema dicts
 - **Execution Pipeline** -- Context creation, safety checks, ACL enforcement, approval gate, validation, middleware chains, and execution with timeout support
 - **`@module` decorator** -- Turn plain functions into fully schema-aware modules with zero boilerplate
 - **YAML bindings** -- Register modules declaratively without modifying source code
@@ -184,6 +184,30 @@ result = client.call("greet", {"name": "Alice"})
 # {"message": "Hello, Alice!"}
 ```
 
+### Alternative: Define schemas with plain dicts
+
+If you prefer not to use Pydantic, pass raw JSON Schema dicts directly:
+
+```python
+from apcore import APCore
+
+client = APCore()
+
+class WeatherModule:
+    input_schema = {"type": "object", "properties": {"city": {"type": "string"}}}
+    output_schema = {"type": "object", "properties": {"temp": {"type": "number"}}}
+    description = "Get current temperature"
+
+    def execute(self, inputs: dict, context=None) -> dict:
+        return {"temp": 22.5}
+
+client.register("weather", WeatherModule())
+result = client.call("weather", {"city": "Tokyo"})
+# {"temp": 22.5}
+```
+
+> **Note:** Dict schemas skip Pydantic input validation. Use Pydantic models when you need automatic type coercion and validation, or validate inside `execute()`.
+
 ### Add middleware
 
 ```python

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apcore"
-version = "0.13.0"
+version = "0.13.1"
 description = "Schema-driven module standard for AI-perceivable interfaces"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -62,7 +62,7 @@ dev = [
     "ruff>=0.1.0",
     "mypy>=1.0",
     "aiohttp>=3.9",
-    "apdev[dev]>=0.2.0",
+    "apdev[dev]>=0.2.3",
 ]
 
 [tool.setuptools.packages.find]

src/apcore/errors.py

@@ -1,4 +1,10 @@
-"""Error hierarchy for apcore."""
+"""Error hierarchy for apcore.
+
+Defines ModuleError (the base for all apcore errors), standard ErrorCodes,
+and specialized subclasses (ACLDeniedError, SchemaValidationError, etc.).
+Each error carries optional AI guidance fields (retryable, ai_guidance,
+user_fixable, suggestion) to enable Self-Healing agents.
+"""
 
 from __future__ import annotations
 

src/apcore/executor.py

@@ -1,4 +1,9 @@
-"""Executor and related utilities for apcore."""
+"""Executor — the module execution engine for apcore.
+
+Resolves a module by ID, validates inputs against its schema, enforces ACL
+and approval policies, runs the middleware chain, and returns the result.
+Supports sync, async, and streaming execution modes.
+"""
 
 from __future__ import annotations
 

src/apcore/registry/registry.py

@@ -32,6 +32,43 @@
 
 logger = logging.getLogger(__name__)
 
+
+class _DictSchemaAdapter:
+    """Adapts a plain JSON Schema dict to the Pydantic model class interface.
+
+    Allows modules that define ``input_schema`` / ``output_schema`` as raw
+    dicts to work transparently with the executor, schema exporter, and any
+    other code that calls ``model_validate``, ``model_json_schema``, or
+    ``model_rebuild`` on a schema object.
+
+    Note: ``model_validate`` is a pass-through — no JSON Schema validation is
+    performed.  Adding real validation would require a ``jsonschema`` dependency
+    which is not currently declared.  Modules that need strict input checking
+    should use Pydantic model classes or validate inside ``execute()``.
+    """
+
+    def __init__(self, schema: dict[str, Any]) -> None:
+        self._schema = schema
+
+    def model_json_schema(self) -> dict[str, Any]:
+        return self._schema
+
+    def model_validate(self, data: Any) -> Any:
+        """Pass-through: returns *data* unchanged (no validation)."""
+        return data
+
+    def model_rebuild(self) -> None:
+        pass
+
+
+def _ensure_schema_adapter(module: Any) -> None:
+    """Wrap raw dict schemas on *module* with ``_DictSchemaAdapter`` in-place."""
+    for attr in ("input_schema", "output_schema"):
+        value = getattr(module, attr, None)
+        if isinstance(value, dict):
+            setattr(module, attr, _DictSchemaAdapter(value))
+
+
 REGISTRY_EVENTS: dict[str, str] = {
     "REGISTER": "register",
     "UNREGISTER": "unregister",
@@ -400,6 +437,8 @@ def register(
         if len(module_id) > MAX_MODULE_ID_LENGTH:
             raise InvalidInputError(f"Module ID exceeds maximum length of {MAX_MODULE_ID_LENGTH}: {len(module_id)}")
 
+        _ensure_schema_adapter(module)
+
         effective_version = version or getattr(module, "version", None) or "0.0.0"
 
         is_versioned = version is not None
@@ -974,6 +1013,7 @@ def register_internal(self, module_id: str, module: Any) -> None:
 
         Used by sys modules that use the reserved 'system.' prefix.
         """
+        _ensure_schema_adapter(module)
         with self._lock:
             self._modules[module_id] = module
             self._lowercase_map[module_id.lower()] = module_id

src/apcore/version.py

@@ -1,4 +1,8 @@
-"""Version negotiation (Algorithm A14)."""
+"""Version negotiation (Algorithm A14).
+
+Compares caller-requested semver ranges against a module's declared version
+and selects the best compatible match, enabling safe multi-version coexistence.
+"""
 
 from __future__ import annotations
 

tests/registry/test_registry.py

@@ -394,6 +394,44 @@ def test_nonexistent_returns_none(self) -> None:
         reg = Registry()
         assert reg.get_definition("missing") is None
 
+    def test_dict_schema(self) -> None:
+        """get_definition() works when input_schema / output_schema are plain dicts."""
+
+        class DictSchemaModule:
+            description = "Module with dict schemas"
+            input_schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+            output_schema = {"type": "object", "properties": {"ok": {"type": "boolean"}}}
+            version = "1.0.0"
+            tags: list[str] = []
+
+            def execute(self, inputs: dict, context: object = None) -> dict:
+                return {"ok": True}
+
+        reg = Registry()
+        reg.register("dict.mod", DictSchemaModule())
+        defn = reg.get_definition("dict.mod")
+        assert defn is not None
+        assert defn.input_schema == {"type": "object", "properties": {"name": {"type": "string"}}}
+        assert defn.output_schema == {"type": "object", "properties": {"ok": {"type": "boolean"}}}
+
+    def test_no_schema(self) -> None:
+        """get_definition() returns empty dict when module has no schema."""
+
+        class NoSchemaModule:
+            description = "Module without schemas"
+            version = "1.0.0"
+            tags: list[str] = []
+
+            def execute(self, inputs: dict, context: object = None) -> dict:
+                return {}
+
+        reg = Registry()
+        reg.register("no.typed", NoSchemaModule())
+        defn = reg.get_definition("no.typed")
+        assert defn is not None
+        assert defn.input_schema == {}
+        assert defn.output_schema == {}
+
 
 # ===== Event Callbacks =====
 

tests/test_executor.py

@@ -451,6 +451,41 @@ def test_none_inputs_treated_as_empty(self) -> None:
         assert result == {"result": "ok"}
         assert mod.execute_calls[0][0] == {}
 
+    def test_dict_schema_call(self) -> None:
+        """call() works when module schemas are plain dicts (not Pydantic models)."""
+
+        class DictSchemaModule:
+            description = "Dict schema module"
+            input_schema = {"type": "object", "properties": {"x": {"type": "integer"}}}
+            output_schema = {"type": "object", "properties": {"y": {"type": "integer"}}}
+            version = "1.0.0"
+            tags: list[str] = []
+
+            def execute(self, inputs: dict[str, Any], context: Any) -> dict[str, Any]:
+                return {"y": inputs.get("x", 0) + 1}
+
+        ex = _make_executor(module=DictSchemaModule())
+        result = ex.call("test.module", {"x": 5})
+        assert result == {"y": 6}
+
+    @pytest.mark.asyncio
+    async def test_dict_schema_call_async(self) -> None:
+        """call_async() works when module schemas are plain dicts."""
+
+        class DictSchemaModule:
+            description = "Dict schema module"
+            input_schema = {"type": "object", "properties": {"x": {"type": "integer"}}}
+            output_schema = {"type": "object", "properties": {"y": {"type": "integer"}}}
+            version = "1.0.0"
+            tags: list[str] = []
+
+            async def execute(self, inputs: dict[str, Any], context: Any) -> dict[str, Any]:
+                return {"y": inputs.get("x", 0) + 1}
+
+        ex = _make_executor(module=DictSchemaModule())
+        result = await ex.call_async("test.module", {"x": 5})
+        assert result == {"y": 6}
+
 
 # === validate() Tests ===