chore: release version 0.5.0

- Renamed internal API methods to public: `_generate_input_model` and `_generate_output_model` to `generate_input_model` and `generate_output_model`.
- Updated parameter names for clarity: `format` to `output_format` in `context_logger`.
- Improved type annotations across various modules for better type safety.
- Refactored code to enhance quality and reduce duplication, including extraction of validation error handling.
- Added new async middleware methods for improved middleware management.
- Changed `Identity.roles` from a mutable list to an immutable tuple for memory safety.
- Ensured security by specifying encoding when opening YAML files.
- Updated documentation and tests to reflect changes in API and functionality.

Author: tercel

CHANGELOG.md

@@ -6,6 +6,46 @@ 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.5.0] - 2026-02-21
+
+### Changed
+
+#### API Naming
+- **decorator** - Renamed `_generate_input_model` / `_generate_output_model` to `generate_input_model` / `generate_output_model` as public API
+- **context_logger** - Renamed `format` parameter to `output_format` to avoid shadowing Python builtin
+- **registry** - Renamed `_write_lock` to `_lock` for clearer intent
+
+#### Type Annotations
+- **decorator** - Replaced bare `dict` with `dict[str, Any]` in `_normalize_result`, `annotations`, `metadata`, `_async_execute`, `_sync_execute`
+- **bindings** - Fixed `_build_model_from_json_schema` parameter type from `dict` to `dict[str, Any]`
+- **scanner** - Fixed `roots` parameter type from `list[dict]` to `list[dict[str, Any]]`
+- **metrics** - Fixed `snapshot` return type from `dict` to `dict[str, Any]`
+- **executor** - Removed redundant string-quoted forward references in `from_registry`; fixed `middlewares` parameter type to `list[Middleware] | None`
+
+#### Code Quality
+- **executor** - Extracted `_convert_validation_errors()` helper to eliminate 6 duplicated validation error conversion patterns
+- **executor** - Refactored `call_async()` and `stream()` to use new async middleware manager methods
+- **executor** - Removed internal `_execute_on_error_async` method (replaced by `MiddlewareManager.execute_on_error_async`)
+- **loader** - Use `self._resolver.clear_cache()` instead of accessing private `_file_cache` directly
+- **tracing** - Replaced `print()` with `sys.stdout.write()` in `StdoutExporter`
+- **acl / loader** - Changed hardcoded logger names to `logging.getLogger(__name__)`
+
+### Added
+
+#### Async Middleware
+- **MiddlewareManager** - Added `execute_before_async()`, `execute_after_async()`, `execute_on_error_async()` for proper async middleware dispatch with `inspect.iscoroutinefunction` detection
+- **RefResolver** - Added `clear_cache()` public method for cache management
+- **Executor** - Added `clear_async_cache()` public method
+
+### Fixed
+
+#### Memory Safety
+- **context** - Changed `Identity.roles` from mutable `list[str]` to immutable `tuple[str, ...]` in frozen dataclass
+
+#### Security
+- **acl** - Added explicit `encoding="utf-8"` to YAML file open
+
+
 ## [0.4.0] - 2026-02-20
 
 ### Added

README.md

@@ -116,7 +116,7 @@ src/apcore/
     acl.py               # Access control
     errors.py            # Error hierarchy
     module.py            # Module annotations & metadata
-    middleware/           # Middleware system
+    middleware/          # Middleware system
     observability/       # Tracing, metrics, logging
     registry/            # Module discovery & registration
     schema/              # Schema loading, validation, export

pyproject.toml

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

src/apcore/__init__.py

@@ -61,7 +61,7 @@
     TracingMiddleware,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     # Core

src/apcore/acl.py

@@ -57,7 +57,7 @@ def __init__(self, rules: list[ACLRule], default_effect: str = "deny") -> None:
         self._default_effect: str = default_effect
         self._yaml_path: str | None = None
         self.debug: bool = False
-        self._logger: logging.Logger = logging.getLogger("apcore.acl")
+        self._logger: logging.Logger = logging.getLogger(__name__)
         self._lock = threading.Lock()
 
     @classmethod
@@ -77,7 +77,7 @@ def load(cls, yaml_path: str) -> ACL:
         if not os.path.isfile(yaml_path):
             raise ConfigNotFoundError(config_path=yaml_path)
 
-        with open(yaml_path) as f:
+        with open(yaml_path, encoding="utf-8") as f:
             try:
                 data = yaml.safe_load(f)
             except yaml.YAMLError as e:

src/apcore/bindings.py

@@ -11,8 +11,8 @@
 
 from apcore.decorator import (
     FunctionModule,
-    _generate_input_model,
-    _generate_output_model,
+    generate_input_model,
+    generate_output_model,
 )
 from apcore.errors import (
     BindingCallableNotFoundError,
@@ -40,7 +40,7 @@
 _UNSUPPORTED_KEYS = {"oneOf", "anyOf", "allOf", "$ref", "format"}
 
 
-def _build_model_from_json_schema(schema: dict, model_name: str = "DynamicModel") -> type[BaseModel]:
+def _build_model_from_json_schema(schema: dict[str, Any], model_name: str = "DynamicModel") -> type[BaseModel]:
     """Build a Pydantic model from a simple JSON Schema dict."""
     # Check for unsupported top-level features
     if _UNSUPPORTED_KEYS & schema.keys():
@@ -174,8 +174,8 @@ def _create_module_from_binding(self, binding: dict, binding_file_dir: str) -> F
         # Determine schema mode
         if binding.get("auto_schema"):
             try:
-                input_schema = _generate_input_model(func)
-                output_schema = _generate_output_model(func)
+                input_schema = generate_input_model(func)
+                output_schema = generate_output_model(func)
             except (FuncMissingTypeHintError, FuncMissingReturnTypeError) as exc:
                 raise BindingSchemaMissingError(target=binding["target"]) from exc
         elif "input_schema" in binding or "output_schema" in binding:
@@ -204,8 +204,8 @@ def _create_module_from_binding(self, binding: dict, binding_file_dir: str) -> F
         else:
             # No schema mode specified, try auto_schema as default
             try:
-                input_schema = _generate_input_model(func)
-                output_schema = _generate_output_model(func)
+                input_schema = generate_input_model(func)
+                output_schema = generate_output_model(func)
             except (FuncMissingTypeHintError, FuncMissingReturnTypeError) as exc:
                 raise BindingSchemaMissingError(target=binding["target"]) from exc
 

src/apcore/context.py

@@ -15,7 +15,7 @@ class Identity:
 
     id: str
     type: str = "user"
-    roles: list[str] = field(default_factory=list)
+    roles: tuple[str, ...] = field(default_factory=tuple)
     attrs: dict[str, Any] = field(default_factory=dict)
 
 

src/apcore/decorator.py

@@ -13,7 +13,7 @@
 from apcore.errors import FuncMissingReturnTypeError, FuncMissingTypeHintError
 
 
-def _generate_input_model(func: Any) -> type[BaseModel]:
+def generate_input_model(func: Any) -> type[BaseModel]:
     """Convert a function's parameter signature into a dynamic Pydantic BaseModel.
 
     Skips self/cls, *args, **kwargs, and Context-typed parameters.
@@ -71,7 +71,7 @@ def _generate_input_model(func: Any) -> type[BaseModel]:
     return create_model("InputModel", **field_dict)
 
 
-def _generate_output_model(func: Any) -> type[BaseModel]:
+def generate_output_model(func: Any) -> type[BaseModel]:
     """Convert a function's return type annotation into a Pydantic BaseModel.
 
     - dict / dict[str, T] -> permissive model (extra="allow")
@@ -124,7 +124,7 @@ def _has_context_param(func: Any) -> tuple[bool, str | None]:
     return (False, None)
 
 
-def _normalize_result(result: Any) -> dict:
+def _normalize_result(result: Any) -> dict[str, Any]:
     """Normalize a function's return value to a dict for the executor pipeline."""
     if result is None:
         return {}
@@ -151,15 +151,15 @@ def __init__(
         documentation: str | None = None,
         tags: list[str] | None = None,
         version: str = "1.0.0",
-        annotations: dict | None = None,
-        metadata: dict | None = None,
+        annotations: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
         input_schema: type[BaseModel] | None = None,
         output_schema: type[BaseModel] | None = None,
     ) -> None:
         self._func = func
         self.module_id = module_id
-        self.input_schema = input_schema if input_schema is not None else _generate_input_model(func)
-        self.output_schema = output_schema if output_schema is not None else _generate_output_model(func)
+        self.input_schema = input_schema if input_schema is not None else generate_input_model(func)
+        self.output_schema = output_schema if output_schema is not None else generate_output_model(func)
 
         has_context, context_param_name = _has_context_param(func)
 
@@ -181,7 +181,7 @@ def __init__(
         # inspect.iscoroutinefunction returns the correct value.
         if inspect.iscoroutinefunction(func):
 
-            async def _async_execute(inputs: dict, context: Context) -> dict:
+            async def _async_execute(inputs: dict[str, Any], context: Context) -> dict[str, Any]:
                 call_kwargs = dict(inputs)
                 if has_context:
                     call_kwargs[context_param_name] = context
@@ -191,7 +191,7 @@ async def _async_execute(inputs: dict, context: Context) -> dict:
             self.execute = _async_execute
         else:
 
-            def _sync_execute(inputs: dict, context: Context) -> dict:
+            def _sync_execute(inputs: dict[str, Any], context: Context) -> dict[str, Any]:
                 call_kwargs = dict(inputs)
                 if has_context:
                     call_kwargs[context_param_name] = context
@@ -219,10 +219,10 @@ def module(
     id: str | None = None,  # noqa: A002
     description: str | None = None,
     documentation: str | None = None,
-    annotations: dict | None = None,
+    annotations: dict[str, Any] | None = None,
     tags: list[str] | None = None,
     version: str = "1.0.0",
-    metadata: dict | None = None,
+    metadata: dict[str, Any] | None = None,
     registry: Any = None,
 ) -> Any:
     """Wrap a Python function as an apcore module.