apcore-toolkit 0.4.0__tar.gz → 0.4.2__tar.gz

{apcore_toolkit-0.4.0 → apcore_toolkit-0.4.2}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.1] - 2026-03-25
+
+### Added
+
+- **`deep_resolve_refs()`** — public API for recursive `$ref` resolution in OpenAPI schemas (previously internal `_deep_resolve_refs`). Resolves nested `allOf`/`anyOf`/`oneOf`, `items`, and `properties`. Depth-limited to 16 levels.
+
+### Fixed
+
+- README: apcore dependency version updated from `>= 0.13.1` to `>= 0.14.0` (matches pyproject.toml).
+- README: Core Modules table now lists all public API functions (added 10 missing entries).
+
 ## [0.4.0] - 2026-03-23
 
 ### Added

{apcore_toolkit-0.4.0 → apcore_toolkit-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apcore-toolkit
-Version: 0.4.0
+Version: 0.4.2
 Summary: Shared scanner, schema extraction, and output toolkit for apcore framework adapters
 Project-URL: Homepage, https://aiperceivable.com
 Project-URL: Repository, https://github.com/aiperceivable/apcore-toolkit-python
@@ -10,7 +10,7 @@ Author-email: aiperceivable <tercel.yi@gmail.com>
 License-Expression: Apache-2.0
 Keywords: apcore,mcp,openapi,pydantic,scanner,schema,toolkit,yaml
 Requires-Python: >=3.11
-Requires-Dist: apcore>=0.13.1
+Requires-Dist: apcore>=0.18.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
@@ -69,6 +69,15 @@ pip install apcore-toolkit
 | `get_writer` | Factory function for writer instances |
 | `DisplayResolver` | Sparse binding.yaml display overlay — resolves surface-facing alias, description, guidance, tags into `metadata["display"]` (§5.13) |
 | `ConventionScanner` | Scans a `commands/` directory of plain Python files for public functions and converts them to `ScannedModule` instances with schema inferred from type annotations (§5.14) |
+| `extract_input_schema` | Merges OpenAPI query, path, and request body params into a single JSON Schema |
+| `extract_output_schema` | Extracts response schema from OpenAPI operation objects |
+| `resolve_ref` | Resolves a single internal `$ref` JSON pointer |
+| `resolve_schema` | Resolves a top-level `$ref` in a schema |
+| `deep_resolve_refs` | Recursively resolves all `$ref` pointers, depth-limited to 16 levels |
+| `annotations_to_dict` | Converts `ModuleAnnotations` to a plain dict |
+| `module_to_dict` | Converts a `ScannedModule` to a dict for JSON/YAML serialization |
+| `modules_to_dicts` | Batch version of `module_to_dict` |
+| `run_verifier_chain` | Runs multiple verifiers in sequence, stopping on first failure |
 
 ## Usage
 
@@ -240,7 +249,7 @@ Input and output schemas are inferred from PEP 484 type annotations. Use `includ
 ## Requirements
 
 - Python >= 3.11
-- apcore >= 0.13.1
+- apcore >= 0.14.0
 - pydantic >= 2.0
 - PyYAML >= 6.0
 

{apcore_toolkit-0.4.0 → apcore_toolkit-0.4.2}/README.md

@@ -43,6 +43,15 @@ pip install apcore-toolkit
 | `get_writer` | Factory function for writer instances |
 | `DisplayResolver` | Sparse binding.yaml display overlay — resolves surface-facing alias, description, guidance, tags into `metadata["display"]` (§5.13) |
 | `ConventionScanner` | Scans a `commands/` directory of plain Python files for public functions and converts them to `ScannedModule` instances with schema inferred from type annotations (§5.14) |
+| `extract_input_schema` | Merges OpenAPI query, path, and request body params into a single JSON Schema |
+| `extract_output_schema` | Extracts response schema from OpenAPI operation objects |
+| `resolve_ref` | Resolves a single internal `$ref` JSON pointer |
+| `resolve_schema` | Resolves a top-level `$ref` in a schema |
+| `deep_resolve_refs` | Recursively resolves all `$ref` pointers, depth-limited to 16 levels |
+| `annotations_to_dict` | Converts `ModuleAnnotations` to a plain dict |
+| `module_to_dict` | Converts a `ScannedModule` to a dict for JSON/YAML serialization |
+| `modules_to_dicts` | Batch version of `module_to_dict` |
+| `run_verifier_chain` | Runs multiple verifiers in sequence, stopping on first failure |
 
 ## Usage
 
@@ -214,7 +223,7 @@ Input and output schemas are inferred from PEP 484 type annotations. Use `includ
 ## Requirements
 
 - Python >= 3.11
-- apcore >= 0.13.1
+- apcore >= 0.14.0
 - pydantic >= 2.0
 - PyYAML >= 6.0
 

{apcore_toolkit-0.4.0 → apcore_toolkit-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-toolkit"
-version = "0.4.0"
+version = "0.4.2"
 description = "Shared scanner, schema extraction, and output toolkit for apcore framework adapters"
 requires-python = ">=3.11"
 readme = "README.md"
@@ -23,7 +23,7 @@ keywords = [
     "toolkit",
 ]
 dependencies = [
-    "apcore>=0.13.1",
+    "apcore>=0.18.0",
     "pydantic>=2.0",
     "PyYAML>=6.0",
 ]

{apcore_toolkit-0.4.0 → apcore_toolkit-0.4.2}/src/apcore_toolkit/__init__.py

@@ -9,6 +9,7 @@ from apcore_toolkit.ai_enhancer import AIEnhancer, Enhancer
 from apcore_toolkit.display import DisplayResolver
 from apcore_toolkit.formatting import to_markdown
 from apcore_toolkit.openapi import (
+    deep_resolve_refs,
     extract_input_schema,
     extract_output_schema,
     resolve_ref,
@@ -62,6 +63,7 @@ __all__ = [
     "YAMLVerifier",
     "YAMLWriter",
     "annotations_to_dict",
+    "deep_resolve_refs",
     "enrich_schema_descriptions",
     "extract_input_schema",
     "extract_output_schema",

{apcore_toolkit-0.4.0 → apcore_toolkit-0.4.2}/src/apcore_toolkit/ai_enhancer.py

@@ -10,13 +10,16 @@ metadata dict for auditability.
 
 from __future__ import annotations
 
+import dataclasses
 import json
 import logging
 import os
+import types
+import typing
 from dataclasses import replace
-from typing import Any, Protocol
+from typing import Any, Callable, Protocol
 
-from apcore import ModuleAnnotations
+from apcore import DEFAULT_ANNOTATIONS, ModuleAnnotations
 
 from apcore_toolkit.types import ScannedModule
 
@@ -27,7 +30,53 @@ _DEFAULT_MODEL = "qwen:0.6b"
 _DEFAULT_THRESHOLD = 0.7
 _DEFAULT_BATCH_SIZE = 5
 _DEFAULT_TIMEOUT = 30
-_DEFAULT_ANNOTATIONS = ModuleAnnotations()
+
+
+# SLM must never write to ModuleAnnotations.extra: it is reserved for adapter
+# extensions and is not user-facing semantic content.
+_SLM_EXCLUDED_ANNOTATION_FIELDS = frozenset({"extra"})
+
+
+def _build_annotation_field_validators() -> dict[str, Callable[[Any], bool]]:
+    """Derive per-field type validators from ``ModuleAnnotations`` at import time.
+
+    Introspecting the dataclass instead of hardcoding a whitelist ensures that
+    when apcore adds new annotation fields the AI Enhancer automatically picks
+    them up (still subject to confidence gating). ``extra`` is excluded so the
+    SLM cannot inject arbitrary keys via that escape hatch.
+
+    The order of ``isinstance`` checks matters: ``bool`` is a subclass of
+    ``int`` in Python, so a boolean must not be silently accepted as an int
+    field.
+    """
+    hints = typing.get_type_hints(ModuleAnnotations)
+    validators: dict[str, Callable[[Any], bool]] = {}
+    for field in dataclasses.fields(ModuleAnnotations):
+        if field.name in _SLM_EXCLUDED_ANNOTATION_FIELDS:
+            continue
+        hint = hints.get(field.name)
+        origin = typing.get_origin(hint)
+        # Strip Optional[X] / X | None — SLM returns concrete values, not None.
+        # PEP 604 (X | None) yields types.UnionType; typing.Optional yields typing.Union.
+        if origin is typing.Union or origin is types.UnionType:
+            args = [a for a in typing.get_args(hint) if a is not type(None)]
+            if len(args) == 1:
+                hint = args[0]
+                origin = typing.get_origin(hint)
+        if hint is bool:
+            validators[field.name] = lambda v: isinstance(v, bool)
+        elif hint is int:
+            validators[field.name] = lambda v: isinstance(v, int) and not isinstance(v, bool)
+        elif hint is str:
+            validators[field.name] = lambda v: isinstance(v, str)
+        elif origin in (list, tuple):
+            validators[field.name] = lambda v: isinstance(v, list)
+        else:
+            logger.debug("AIEnhancer: skipping ModuleAnnotations field %r with unsupported type %r", field.name, hint)
+    return validators
+
+
+_ANNOTATION_FIELD_VALIDATORS = _build_annotation_field_validators()
 
 
 class Enhancer(Protocol):
@@ -152,7 +201,7 @@ class AIEnhancer:
             gaps.append("description")
         if not module.documentation:
             gaps.append("documentation")
-        if module.annotations is None or module.annotations == _DEFAULT_ANNOTATIONS:
+        if module.annotations is None or module.annotations == DEFAULT_ANNOTATIONS:
             gaps.append("annotations")
         if not module.input_schema.get("properties"):
             gaps.append("input_schema")
@@ -186,65 +235,26 @@ class AIEnhancer:
             else:
                 warnings.append(f"Low confidence ({doc_conf:.2f}) for documentation — skipped. Review manually.")
 
-        # Apply annotations if above threshold
+        # Apply annotations if above threshold. Field set is derived from
+        # ModuleAnnotations at import time, so adding new fields upstream
+        # automatically widens what the SLM may populate (extra excluded).
         if "annotations" in gaps and "annotations" in parsed and isinstance(parsed["annotations"], dict):
             ann_data = parsed["annotations"]
             ann_conf = parsed.get("confidence", {})
             accepted: dict[str, Any] = {}
-            _BOOL_FIELDS = (
-                "readonly",
-                "destructive",
-                "idempotent",
-                "requires_approval",
-                "open_world",
-                "streaming",
-                "cacheable",
-                "paginated",
-            )
-            for field in _BOOL_FIELDS:
-                if field in ann_data and isinstance(ann_data[field], bool):
-                    field_conf = ann_conf.get(f"annotations.{field}", ann_conf.get(field, 0.0))
-                    confidence[f"annotations.{field}"] = field_conf
-                    if field_conf >= self.threshold:
-                        accepted[field] = ann_data[field]
-                    else:
-                        warnings.append(
-                            f"Low confidence ({field_conf:.2f}) for annotations.{field} — skipped. Review manually."
-                        )
-            # Handle non-boolean annotation fields
-            _INT_FIELDS = ("cache_ttl",)
-            for field in _INT_FIELDS:
-                if field in ann_data and isinstance(ann_data[field], int):
-                    field_conf = ann_conf.get(f"annotations.{field}", ann_conf.get(field, 0.0))
-                    confidence[f"annotations.{field}"] = field_conf
-                    if field_conf >= self.threshold:
-                        accepted[field] = ann_data[field]
-                    else:
-                        warnings.append(
-                            f"Low confidence ({field_conf:.2f}) for annotations.{field} — skipped. Review manually."
-                        )
-            _STR_FIELDS = ("pagination_style",)
-            for field in _STR_FIELDS:
-                if field in ann_data and isinstance(ann_data[field], str):
-                    field_conf = ann_conf.get(f"annotations.{field}", ann_conf.get(field, 0.0))
-                    confidence[f"annotations.{field}"] = field_conf
-                    if field_conf >= self.threshold:
-                        accepted[field] = ann_data[field]
-                    else:
-                        warnings.append(
-                            f"Low confidence ({field_conf:.2f}) for annotations.{field} — skipped. Review manually."
-                        )
-            if "cache_key_fields" in ann_data and isinstance(ann_data["cache_key_fields"], list):
-                field_conf = ann_conf.get("annotations.cache_key_fields", ann_conf.get("cache_key_fields", 0.0))
-                confidence["annotations.cache_key_fields"] = field_conf
+            for field_name, validate in _ANNOTATION_FIELD_VALIDATORS.items():
+                if field_name not in ann_data or not validate(ann_data[field_name]):
+                    continue
+                field_conf = ann_conf.get(f"annotations.{field_name}", ann_conf.get(field_name, 0.0))
+                confidence[f"annotations.{field_name}"] = field_conf
                 if field_conf >= self.threshold:
-                    accepted["cache_key_fields"] = ann_data["cache_key_fields"]
+                    accepted[field_name] = ann_data[field_name]
                 else:
                     warnings.append(
-                        f"Low confidence ({field_conf:.2f}) for annotations.cache_key_fields — skipped. Review manually."
+                        f"Low confidence ({field_conf:.2f}) for annotations.{field_name} — skipped. Review manually."
                     )
             if accepted:
-                base = module.annotations or ModuleAnnotations()
+                base = module.annotations or DEFAULT_ANNOTATIONS
                 updates["annotations"] = replace(base, **accepted)
 
         # Apply input_schema if above threshold

{apcore_toolkit-0.4.0 → apcore_toolkit-0.4.2}/src/apcore_toolkit/openapi.py

@@ -85,6 +85,27 @@ def _deep_resolve_refs(
     return result
 
 
+def deep_resolve_refs(
+    schema: dict[str, Any],
+    openapi_doc: dict[str, Any],
+    depth: int = 0,
+) -> dict[str, Any]:
+    """Recursively resolve all ``$ref`` pointers in a schema.
+
+    Handles nested ``$ref``, ``allOf``, ``anyOf``, ``oneOf``, and ``items``.
+    Depth-limited to 16 levels to prevent infinite recursion on circular refs.
+
+    Args:
+        schema: A JSON Schema dict (possibly containing ``$ref`` pointers).
+        openapi_doc: The full OpenAPI document dict.
+        depth: Current recursion depth (callers should not set this).
+
+    Returns:
+        A new schema dict with all ``$ref`` pointers resolved.
+    """
+    return _deep_resolve_refs(schema, openapi_doc, depth)
+
+
 def extract_input_schema(
     operation: dict[str, Any],
     openapi_doc: dict[str, Any] | None = None,

{apcore_toolkit-0.4.0 → apcore_toolkit-0.4.2}/src/apcore_toolkit/output/http_proxy_writer.py

@@ -29,7 +29,7 @@ import re
 from collections.abc import Callable
 from typing import Any
 
-from apcore import ModuleAnnotations, Registry
+from apcore import DEFAULT_ANNOTATIONS, Registry
 from apcore_toolkit.output.types import WriteResult
 from apcore_toolkit.types import ScannedModule
 
@@ -104,7 +104,7 @@ class HTTPProxyRegistryWriter:
         auth_factory = self._auth_header_factory
         timeout = self._timeout
 
-        annotations = mod.annotations or ModuleAnnotations()
+        annotations = mod.annotations or DEFAULT_ANNOTATIONS
 
         # Raw dict schemas are auto-wrapped by Registry._ensure_schema_adapter
         # (apcore >= 0.13.1) during register(), so no manual wrapping needed.
@@ -152,11 +152,13 @@ class HTTPProxyRegistryWriter:
                     return resp.json()  # type: ignore[no-any-return]
 
                 error_msg = _extract_error_message(resp)
+                from apcore import ErrorCodes
                 from apcore.errors import ModuleError
 
                 raise ModuleError(
-                    code=f"HTTP_{resp.status_code}",
-                    message=error_msg,
+                    code=ErrorCodes.MODULE_EXECUTE_ERROR,
+                    message=f"HTTP {resp.status_code}: {error_msg}",
+                    details={"http_status": resp.status_code},
                 )
 
         ProxyModule.__name__ = mod.module_id.replace(".", "_")

{apcore_toolkit-0.4.0 → apcore_toolkit-0.4.2}/src/apcore_toolkit/scanner.py

@@ -12,7 +12,7 @@ from abc import ABC, abstractmethod
 from dataclasses import replace
 from typing import Any
 
-from apcore import ModuleAnnotations, parse_docstring
+from apcore import DEFAULT_ANNOTATIONS, ModuleAnnotations, parse_docstring
 from apcore_toolkit.types import ScannedModule
 
 
@@ -97,12 +97,12 @@ class BaseScanner(ABC):
         """
         method_upper = method.upper()
         if method_upper == "GET":
-            return ModuleAnnotations(readonly=True, cacheable=True)
+            return replace(DEFAULT_ANNOTATIONS, readonly=True, cacheable=True)
         elif method_upper == "DELETE":
-            return ModuleAnnotations(destructive=True)
+            return replace(DEFAULT_ANNOTATIONS, destructive=True)
         elif method_upper == "PUT":
-            return ModuleAnnotations(idempotent=True)
-        return ModuleAnnotations()
+            return replace(DEFAULT_ANNOTATIONS, idempotent=True)
+        return DEFAULT_ANNOTATIONS
 
     def deduplicate_ids(self, modules: list[ScannedModule]) -> list[ScannedModule]:
         """Resolve duplicate module IDs by appending _2, _3, etc.

{apcore_toolkit-0.4.0 → apcore_toolkit-0.4.2}/tests/test_openapi.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from apcore_toolkit.openapi import (
     _deep_resolve_refs,
+    deep_resolve_refs,
     extract_input_schema,
     extract_output_schema,
     resolve_ref,
@@ -168,6 +169,101 @@ class TestDeepResolveRefs:
         assert OPENAPI_DOC["components"]["schemas"]["Address"]["properties"] == original_props
 
 
+class TestDeepResolveRefsPublic:
+    """Tests for the public deep_resolve_refs wrapper."""
+
+    def test_top_level_ref(self) -> None:
+        schema = {"$ref": "#/components/schemas/User"}
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result["type"] == "object"
+        assert "id" in result["properties"]
+        assert "name" in result["properties"]
+
+    def test_nested_ref_in_properties(self) -> None:
+        schema = {
+            "type": "object",
+            "properties": {
+                "address": {"$ref": "#/components/schemas/Address"},
+            },
+        }
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result["properties"]["address"]["type"] == "object"
+        assert "street" in result["properties"]["address"]["properties"]
+
+    def test_ref_in_allof(self) -> None:
+        schema = {
+            "allOf": [
+                {"$ref": "#/components/schemas/User"},
+                {"type": "object", "properties": {"extra": {"type": "boolean"}}},
+            ]
+        }
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result["allOf"][0]["type"] == "object"
+        assert "id" in result["allOf"][0]["properties"]
+
+    def test_ref_in_anyof(self) -> None:
+        schema = {
+            "anyOf": [
+                {"$ref": "#/components/schemas/User"},
+                {"$ref": "#/components/schemas/Address"},
+            ]
+        }
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert "name" in result["anyOf"][0]["properties"]
+        assert "street" in result["anyOf"][1]["properties"]
+
+    def test_ref_in_oneof(self) -> None:
+        schema = {
+            "oneOf": [
+                {"$ref": "#/components/schemas/User"},
+                {"$ref": "#/components/schemas/Address"},
+            ]
+        }
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result["oneOf"][0]["type"] == "object"
+        assert "name" in result["oneOf"][0]["properties"]
+        assert "city" in result["oneOf"][1]["properties"]
+
+    def test_ref_in_array_items(self) -> None:
+        schema = {"type": "array", "items": {"$ref": "#/components/schemas/User"}}
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result["items"]["type"] == "object"
+        assert "id" in result["items"]["properties"]
+
+    def test_deeply_nested_ref(self) -> None:
+        result = deep_resolve_refs({"$ref": "#/components/schemas/UserWithAddress"}, OPENAPI_DOC)
+        assert result["properties"]["address"]["type"] == "object"
+        assert "street" in result["properties"]["address"]["properties"]
+
+    def test_circular_ref_depth_limit(self) -> None:
+        result = deep_resolve_refs({"$ref": "#/components/schemas/SelfRef"}, OPENAPI_DOC)
+        assert result["type"] == "object"
+        assert "child" in result["properties"]
+
+    def test_no_mutation_of_original(self) -> None:
+        original_address = OPENAPI_DOC["components"]["schemas"]["Address"]
+        original_props = dict(original_address.get("properties", {}))
+        deep_resolve_refs({"$ref": "#/components/schemas/UserWithAddress"}, OPENAPI_DOC)
+        assert OPENAPI_DOC["components"]["schemas"]["Address"]["properties"] == original_props
+
+    def test_custom_depth_parameter(self) -> None:
+        """Passing depth=17 should short-circuit immediately."""
+        schema = {"$ref": "#/components/schemas/User"}
+        result = deep_resolve_refs(schema, OPENAPI_DOC, depth=17)
+        # Should return the unresolved schema since depth > 16
+        assert "$ref" in result
+
+    def test_plain_schema_no_refs(self) -> None:
+        schema = {"type": "string", "description": "A simple string"}
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result == {"type": "string", "description": "A simple string"}
+
+    def test_importable_from_package(self) -> None:
+        from apcore_toolkit import deep_resolve_refs as public_fn
+
+        assert callable(public_fn)
+
+
 class TestExtractInputSchema:
     def test_query_and_path_params(self) -> None:
         operation = {