feat: Introduce Module protocol and expose new schema and utility functions.

Author: tercel

README.md

@@ -24,6 +24,11 @@ Schema-driven module development framework for AI-perceivable interfaces.
 - **Async task management** -- Background module execution with status tracking, cancellation, and concurrency limiting
 - **W3C Trace Context** -- traceparent header injection/extraction for distributed tracing interop
 
+## Documentation
+
+For full documentation, including Quick Start guides for both Python and TypeScript, visit:
+**[https://aipartnerup.github.io/apcore/getting-started.html](https://aipartnerup.github.io/apcore/getting-started.html)**
+
 ## Requirements
 
 - Python >= 3.11

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apcore"
-version = "0.7.0"
+version = "0.7.1"
 description = "Schema-driven module development framework for AI-perceivable interfaces"
 readme = "README.md"
 requires-python = ">=3.11"

src/apcore/__init__.py

@@ -26,7 +26,7 @@
 from apcore.executor import Executor, redact_sensitive, REDACTED_VALUE
 
 # Module types
-from apcore.module import ModuleAnnotations, ModuleExample, ValidationResult
+from apcore.module import Module, ModuleAnnotations, ModuleExample, ValidationResult
 
 # Config
 from apcore.config import Config
@@ -92,6 +92,18 @@
 # Bindings
 from apcore.bindings import BindingLoader
 
+# Schema
+from apcore.schema import (
+    SchemaLoader as SchemaLoader,
+    SchemaValidator as SchemaValidator,
+    SchemaExporter as SchemaExporter,
+    RefResolver as RefResolver,
+    to_strict_schema as to_strict_schema,
+)
+
+# Utilities (pattern matching)
+from apcore.utils import match_pattern as match_pattern
+
 # Observability
 from apcore.observability import (
     ContextLogger,
@@ -109,7 +121,7 @@
 # Trace Context
 from apcore.trace_context import TraceContext, TraceParent
 
-__version__ = "0.7.0"
+__version__ = "0.7.1"
 
 __all__ = [
     # Core
@@ -128,6 +140,7 @@
     "AutoApproveHandler",
     "CallbackApprovalHandler",
     # Module types
+    "Module",
     "ModuleAnnotations",
     "ModuleExample",
     "ValidationResult",
@@ -200,7 +213,14 @@
     "TaskInfo",
     # Bindings
     "BindingLoader",
+    # Schema
+    "SchemaLoader",
+    "SchemaValidator",
+    "SchemaExporter",
+    "RefResolver",
+    "to_strict_schema",
     # Utilities
+    "match_pattern",
     "redact_sensitive",
     "REDACTED_VALUE",
     # Observability

src/apcore/module.py

@@ -1,12 +1,36 @@
-"""Module abstract base class and related data types."""
+"""Module protocol and related data types."""
 
 from __future__ import annotations
 
 from dataclasses import dataclass, field
 
-from typing import Any
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
-__all__ = ["ModuleAnnotations", "ModuleExample", "ValidationResult"]
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from apcore.context import Context
+
+__all__ = ["Module", "ModuleAnnotations", "ModuleExample", "ValidationResult"]
+
+
+@runtime_checkable
+class Module(Protocol):
+    """Protocol for apcore modules.
+
+    Any class with ``input_schema``, ``output_schema``, ``description``,
+    and an ``execute(inputs, context)`` method satisfies this protocol.
+    Inheriting from ``Module`` is optional but provides IDE autocompletion.
+
+    At runtime, ``@runtime_checkable`` only checks attribute existence.
+    Static type checkers (pyright) will verify the full signature.
+    """
+
+    input_schema: type[BaseModel]
+    output_schema: type[BaseModel]
+    description: str
+
+    def execute(self, inputs: dict[str, Any], context: Context) -> dict[str, Any]: ...
 
 
 @dataclass(frozen=True)

tests/test_public_api.py

@@ -37,6 +37,11 @@ def test_executor_importable(self):
 
     # -- Module types --
 
+    def test_module_importable(self):
+        from apcore import Module
+
+        assert Module is not None
+
     def test_module_annotations_importable(self):
         from apcore import ModuleAnnotations
 
@@ -327,6 +332,7 @@ class TestPublicAPIAll:
         "AutoApproveHandler",
         "CallbackApprovalHandler",
         # Module types
+        "Module",
         "ModuleAnnotations",
         "ModuleExample",
         "ValidationResult",
@@ -399,7 +405,14 @@ class TestPublicAPIAll:
         "TaskInfo",
         # Bindings
         "BindingLoader",
+        # Schema
+        "SchemaLoader",
+        "SchemaValidator",
+        "SchemaExporter",
+        "RefResolver",
+        "to_strict_schema",
         # Utilities
+        "match_pattern",
         "redact_sensitive",
         "REDACTED_VALUE",
         # Observability