feat: Add HTTP proxy registry writer, enhance OpenAPI schema resolution, and introduce an Enhancer protocol.

Author: tercel

CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2026-03-19
+
+### Added
+
+- `_deep_resolve_refs()` — recursive `$ref` resolution for nested OpenAPI schemas,
+  handling `allOf`/`anyOf`/`oneOf`, `items`, and `properties`. Depth-limited to 16
+  levels to prevent infinite recursion on circular references.
+- `Enhancer` protocol — pluggable interface for metadata enhancement, allowing
+  custom enhancers beyond the built-in `AIEnhancer`.
+- `HTTPProxyRegistryWriter` — registers scanned modules as HTTP proxy classes
+  that forward requests to a running web API. Supports path parameter substitution,
+  pluggable auth headers, and `2xx` success range (with `204` returning `{}`).
+  Requires optional `httpx` dependency (`pip install apcore-toolkit[http-proxy]`).
+- `get_writer("http-proxy", base_url=...)` — factory support for the new
+  HTTP proxy writer with `**kwargs` forwarding.
+- Expanded `__init__.py` public API: exports `Enhancer`, `HTTPProxyRegistryWriter`,
+  `WriteError`, `Verifier`, `VerifyResult`, verifier classes, serializer functions,
+  `resolve_ref`, `resolve_schema`, `extract_input_schema`, `extract_output_schema`,
+  and `run_verifier_chain`.
+
+### Fixed
+
+- `extract_output_schema()` — now recursively resolves all nested `$ref` pointers
+  (previously only handled the shallow case of array items with `$ref`).
+- `extract_input_schema()` — now recursively resolves `$ref` inside individual
+  properties after assembly.
+- `get_writer()` return type annotation now includes `HTTPProxyRegistryWriter`.
+
+### Tests
+
+- 272 tests (up from 260), all passing
+- Added `TestDeepResolveRefs` (8 tests): top-level ref, nested properties,
+  allOf/anyOf, array items, deeply nested refs, circular ref depth limit,
+  immutability guarantee
+- Added nested `$ref` tests for `extract_input_schema` and `extract_output_schema`
+- Added `test_http_proxy` for `get_writer("http-proxy")` factory
+
+---
+
 ## [0.2.0] - 2026-03-11
 
 ### Added

README.md

@@ -24,6 +24,8 @@ pip install apcore-toolkit
 | `YAMLWriter` | Generates `.binding.yaml` files for `apcore.BindingLoader` |
 | `PythonWriter` | Generates `@module`-decorated Python wrapper files |
 | `RegistryWriter` | Registers modules directly into an `apcore.Registry` |
+| `HTTPProxyRegistryWriter` | Registers HTTP proxy modules that forward requests to a running API |
+| `Enhancer` | Pluggable protocol for metadata enhancement |
 | `AIEnhancer` | SLM-based metadata enhancement for scanned modules |
 | `WriteResult` | Structured result type for all writer operations |
 | `WriteError` | Error class for I/O failures during write |

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-toolkit"
-version = "0.2.0"
+version = "0.3.0"
 description = "Shared scanner, schema extraction, and output toolkit for apcore framework adapters"
 requires-python = ">=3.11"
 readme = "README.md"
@@ -23,12 +23,13 @@ keywords = [
     "toolkit",
 ]
 dependencies = [
-    "apcore>=0.13.0",
+    "apcore>=0.13.1",
     "pydantic>=2.0",
     "PyYAML>=6.0",
 ]
 
 [project.optional-dependencies]
+http-proxy = ["httpx>=0.24"]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",

src/apcore_toolkit/__init__.py

@@ -5,16 +5,33 @@
 
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _get_version
-from apcore_toolkit.ai_enhancer import AIEnhancer
+from apcore_toolkit.ai_enhancer import AIEnhancer, Enhancer
 from apcore_toolkit.formatting import to_markdown
+from apcore_toolkit.openapi import (
+    extract_input_schema,
+    extract_output_schema,
+    resolve_ref,
+    resolve_schema,
+)
 from apcore_toolkit.output import get_writer
+from apcore_toolkit.output.errors import WriteError
 from apcore_toolkit.output.python_writer import PythonWriter
+from apcore_toolkit.output.http_proxy_writer import HTTPProxyRegistryWriter
 from apcore_toolkit.output.registry_writer import RegistryWriter
-from apcore_toolkit.output.types import WriteResult
+from apcore_toolkit.output.types import Verifier, VerifyResult, WriteResult
+from apcore_toolkit.output.verifiers import (
+    JSONVerifier,
+    MagicBytesVerifier,
+    RegistryVerifier,
+    SyntaxVerifier,
+    YAMLVerifier,
+    run_verifier_chain,
+)
 from apcore_toolkit.output.yaml_writer import YAMLWriter
 from apcore_toolkit.pydantic_utils import flatten_pydantic_params, resolve_target
 from apcore_toolkit.scanner import BaseScanner
 from apcore_toolkit.schema_utils import enrich_schema_descriptions
+from apcore_toolkit.serializers import annotations_to_dict, module_to_dict, modules_to_dicts
 from apcore_toolkit.types import ScannedModule
 
 try:
@@ -25,14 +42,32 @@
 __all__ = [
     "AIEnhancer",
     "BaseScanner",
+    "HTTPProxyRegistryWriter",
+    "Enhancer",
+    "JSONVerifier",
+    "MagicBytesVerifier",
     "PythonWriter",
+    "RegistryVerifier",
     "RegistryWriter",
     "ScannedModule",
+    "SyntaxVerifier",
+    "Verifier",
+    "VerifyResult",
+    "WriteError",
     "WriteResult",
+    "YAMLVerifier",
     "YAMLWriter",
+    "annotations_to_dict",
     "enrich_schema_descriptions",
+    "extract_input_schema",
+    "extract_output_schema",
     "flatten_pydantic_params",
     "get_writer",
+    "module_to_dict",
+    "modules_to_dicts",
+    "resolve_ref",
+    "resolve_schema",
     "resolve_target",
+    "run_verifier_chain",
     "to_markdown",
 ]

src/apcore_toolkit/ai_enhancer.py

@@ -14,7 +14,7 @@
 import logging
 import os
 from dataclasses import replace
-from typing import Any
+from typing import Any, Protocol
 
 from apcore import ModuleAnnotations
 
@@ -30,6 +30,16 @@
 _DEFAULT_ANNOTATIONS = ModuleAnnotations()
 
 
+class Enhancer(Protocol):
+    """Protocol for pluggable metadata enhancement.
+
+    Any class implementing this protocol can be used to fill metadata gaps
+    in scanned modules. See the AI Enhancement Guide for details.
+    """
+
+    def enhance(self, modules: list[ScannedModule]) -> list[ScannedModule]: ...
+
+
 class AIEnhancer:
     """Enhances ScannedModule metadata using a local SLM.
 

src/apcore_toolkit/openapi.py

@@ -48,6 +48,43 @@ def resolve_schema(
     return schema
 
 
+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.
+    """
+    if _depth > 16:
+        return schema
+
+    if "$ref" in schema:
+        resolved = resolve_ref(schema["$ref"], openapi_doc)
+        return _deep_resolve_refs(resolved, openapi_doc, _depth + 1)
+
+    result = dict(schema)
+
+    # Resolve inside allOf/anyOf/oneOf
+    for key in ("allOf", "anyOf", "oneOf"):
+        if key in result and isinstance(result[key], list):
+            result[key] = [_deep_resolve_refs(item, openapi_doc, _depth + 1) for item in result[key]]
+
+    # Resolve array items
+    if "items" in result and isinstance(result["items"], dict):
+        result["items"] = _deep_resolve_refs(result["items"], openapi_doc, _depth + 1)
+
+    # Resolve nested properties
+    if "properties" in result and isinstance(result["properties"], dict):
+        result["properties"] = {
+            k: _deep_resolve_refs(v, openapi_doc, _depth + 1) for k, v in result["properties"].items()
+        }
+
+    return result
+
+
 def extract_input_schema(
     operation: dict[str, Any],
     openapi_doc: dict[str, Any] | None = None,
@@ -90,6 +127,11 @@ def extract_input_schema(
         schema["properties"].update(body_schema.get("properties", {}))
         schema["required"].extend(body_schema.get("required", []))
 
+    # Recursively resolve $ref inside individual properties
+    if openapi_doc:
+        for prop_name, prop_schema in list(schema["properties"].items()):
+            schema["properties"][prop_name] = _deep_resolve_refs(prop_schema, openapi_doc)
+
     return schema
 
 
@@ -114,9 +156,9 @@ def extract_output_schema(
         if "schema" in json_content:
             schema: dict[str, Any] = json_content["schema"]
             schema = resolve_schema(schema, openapi_doc)
-            # Handle array with $ref items
-            if schema.get("type") == "array" and "$ref" in schema.get("items", {}):
-                schema["items"] = resolve_schema(schema["items"], openapi_doc)
+            # Recursively resolve all nested $ref pointers
+            if openapi_doc:
+                schema = _deep_resolve_refs(schema, openapi_doc)
             return schema
 
     return {"type": "object", "properties": {}}

src/apcore_toolkit/output/__init__.py

@@ -5,6 +5,11 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from apcore_toolkit.output.http_proxy_writer import HTTPProxyRegistryWriter
+
 from apcore_toolkit.output.errors import WriteError as WriteError
 from apcore_toolkit.output.python_writer import PythonWriter
 from apcore_toolkit.output.registry_writer import RegistryWriter
@@ -19,11 +24,16 @@
 from apcore_toolkit.output.yaml_writer import YAMLWriter
 
 
-def get_writer(output_format: str) -> YAMLWriter | PythonWriter | RegistryWriter:
+def get_writer(
+    output_format: str, **kwargs: Any
+) -> YAMLWriter | PythonWriter | RegistryWriter | HTTPProxyRegistryWriter:
     """Return a writer instance for the given output format.
 
     Args:
-        output_format: Output format name (``"yaml"``, ``"python"``, or ``"registry"``).
+        output_format: Output format name (``"yaml"``, ``"python"``,
+            ``"registry"``, or ``"http-proxy"``).
+        **kwargs: Passed to the writer constructor. For ``"http-proxy"``:
+            ``base_url``, ``auth_header_factory``, ``timeout``.
 
     Returns:
         A writer instance.
@@ -37,4 +47,8 @@ def get_writer(output_format: str) -> YAMLWriter | PythonWriter | RegistryWriter
         return PythonWriter()
     if output_format == "registry":
         return RegistryWriter()
+    if output_format == "http-proxy":
+        from apcore_toolkit.output.http_proxy_writer import HTTPProxyRegistryWriter
+
+        return HTTPProxyRegistryWriter(**kwargs)
     raise ValueError(f"Unknown output format: {output_format!r}")