feat: Implement simplify_ids in OpenAPIScanner for shorter module IDs, supported by new helper methods and get_scanner kwargs.

Author: tercel

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] - 2026-03-18
+
+### Added
+- **`simplify_ids` option for `OpenAPIScanner`** -- when enabled, generates clean module IDs using only the function name instead of the full FastAPI operationId. For example, `product.get_product_product__product_id_.get` becomes `product.get_product.get`. Defaults to `False` for backward compatibility.
+- **`_extract_func_name()` static method** -- reverses FastAPI's `generate_unique_id()` transformation to recover the original Python function name from an operationId. Handles path parameters, nested paths, and hyphens correctly.
+- **`_strip_method_suffix()` static method** -- minimal default simplification that removes only the trailing `_{method}` from operationIds.
+- **`get_scanner()` now accepts `**kwargs`** -- keyword arguments are forwarded to the scanner constructor, enabling `get_scanner("openapi", simplify_ids=True)`.
+- **5 new tests** for `simplify_ids` behavior -- covers shortened IDs, function name extraction, no duplicates, default mode preserving path info, and factory kwarg passthrough.
+
+### Changed
+- `_generate_module_id()` refactored -- uses `_extract_func_name()` when `simplify_ids=True`, or `_strip_method_suffix()` when `False`. Extracted common prefix logic to reduce duplication.
+- Module docstring in `openapi.py` updated to document both ID generation modes.
+
 ## [0.1.0] - 2026-03-18
 
 ### Added

README.md

@@ -8,6 +8,7 @@ FastAPI integration for [apcore](https://github.com/aipartnerup/apcore-python) (
 - **Annotation inference** -- `GET` -> readonly+cacheable, `DELETE` -> destructive, `PUT` -> idempotent
 - **Pydantic schema extraction** -- input/output schemas extracted from Pydantic models and OpenAPI spec
 - **Two scanner backends** -- OpenAPI-based (accurate) and native route inspection (fast)
+- **Simplified module IDs** -- `simplify_ids=True` extracts clean function names from FastAPI operationIds
 - **`@module` decorator** -- define standalone AI-callable modules with full schema enforcement
 - **YAML binding** -- zero-code module definitions via external `.binding.yaml` files
 - **MCP server** -- stdio, streamable-http, and SSE transports via `fastapi-apcore serve`
@@ -380,15 +381,22 @@ Two scanner backends are available:
 ```python
 from fastapi_apcore import get_scanner
 
-# OpenAPI scanner (default)
+# OpenAPI scanner (default) -- full operationId-based IDs
 scanner = get_scanner("openapi")
 modules = scanner.scan(app)
 
+# OpenAPI scanner with simplified IDs (recommended for CLI)
+scanner = get_scanner("openapi", simplify_ids=True)
+modules = scanner.scan(app)
+# product.get_product_product__product_id_.get → product.get_product.get
+
 # Native scanner
 scanner = get_scanner("native")
 modules = scanner.scan(app, include=r"users\.", exclude=r"\.delete$")
 ```
 
+The `simplify_ids` option extracts the original Python function name from FastAPI's auto-generated operationId, producing much shorter and more readable module IDs. It defaults to `False` for backward compatibility.
+
 ## Project Structure
 
 ```

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-apcore"
-version = "0.1.0"
+version = "0.2.0"
 description = "FastAPI integration for apcore AI-Perceivable Core — exposes FastAPI routes as apcore modules with auto-discovery, schema extraction from Pydantic models, and OpenAPI-based scanning."
 requires-python = ">=3.11"
 readme = "README.md"

src/fastapi_apcore/scanners/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from fastapi_apcore.scanners.native import NativeFastAPIScanner
 from fastapi_apcore.scanners.openapi import OpenAPIScanner
@@ -16,12 +16,14 @@
 }
 
 
-def get_scanner(source: str = "openapi") -> BaseScanner:
+def get_scanner(source: str = "openapi", **kwargs: Any) -> BaseScanner:
     """Instantiate a scanner by source name.
 
     Args:
         source: Scanner type — 'native' for route inspection,
                 'openapi' for OpenAPI schema-based scanning (default).
+        **kwargs: Passed to the scanner constructor.
+                  For 'openapi': ``simplify_ids=True`` generates simplified IDs.
 
     Returns:
         A BaseScanner subclass instance.
@@ -33,4 +35,4 @@ def get_scanner(source: str = "openapi") -> BaseScanner:
     if scanner_cls is None:
         valid = ", ".join(sorted(_SCANNER_REGISTRY))
         raise ValueError(f"Unknown scanner source '{source}'. Valid sources: {valid}")
-    return scanner_cls()
+    return scanner_cls(**kwargs)

src/fastapi_apcore/scanners/openapi.py

@@ -4,7 +4,9 @@
 This is the most accurate scanner since FastAPI's OpenAPI generation
 handles all edge cases (Depends, File, Form, etc.).
 
-Module ID format: {tag}.{operation_id}.{method}
+Module ID format:
+  Default:        {tag}.{operationId_without_method}.{method}
+  simplify_ids:   {tag}.{func_name}.{method}
 """
 
 from __future__ import annotations
@@ -34,6 +36,17 @@ class OpenAPIScanner(BaseScanner):
     - Response models with $ref
     """
 
+    def __init__(self, *, simplify_ids: bool = False) -> None:
+        """Initialize the OpenAPI scanner.
+
+        Args:
+            simplify_ids: When True, generate simplified module IDs using only
+                the function name (e.g. ``product.get_product.get``).
+                When False (default), use the full FastAPI operationId
+                (e.g. ``product.get_product_product__product_id_.get``).
+        """
+        self._simplify_ids = simplify_ids
+
     def scan(
         self,
         app: FastAPI,
@@ -108,39 +121,72 @@ def get_source_name(self) -> str:
         return "openapi-fastapi"
 
     def _generate_module_id(self, operation: dict[str, Any], path: str, method: str) -> str:
-        """Generate module_id from tags + operation_id + method.
+        """Generate module_id from tags + function_name + method.
+
+        When ``simplify_ids=True`` (set in constructor), extracts the clean
+        function name from FastAPI's operationId::
 
-        Format: {tag}.{operation_id}.{method}
-        Falls back to path-based ID if no tags.
+            GET /product/{product_id}  → product.get_product.get
+            POST /task/create          → task.create_task.post
+
+        When ``simplify_ids=False`` (default), uses the raw operationId
+        with only the trailing method stripped::
+
+            GET /product/{product_id}  → product.get_product_product__product_id_.get
         """
         operation_id: str = operation.get("operationId", "unknown")
         tags = operation.get("tags", [])
 
-        # Clean operation_id: FastAPI generates e.g. "create_task_task_create_post"
-        # We use the simpler function name portion
-        func_name = self._simplify_operation_id(operation_id)
+        if self._simplify_ids:
+            func_name = self._extract_func_name(operation_id, path, method)
+        else:
+            func_name = self._strip_method_suffix(operation_id, method)
 
         if tags:
             prefix = str(tags[0]).lower().replace(" ", "_")
-            module_id = f"{prefix}.{func_name}.{method.lower()}"
         else:
             path_parts = [p for p in path.strip("/").split("/") if not p.startswith("{")]
             prefix = ".".join(path_parts) if path_parts else "root"
-            module_id = f"{prefix}.{func_name}.{method.lower()}"
 
+        module_id = f"{prefix}.{func_name}.{method.lower()}"
         return re.sub(r"[^a-zA-Z0-9._]", "_", module_id)
 
-    def _simplify_operation_id(self, operation_id: str) -> str:
-        """Simplify FastAPI's auto-generated operation IDs.
+    @staticmethod
+    def _strip_method_suffix(operation_id: str, method: str) -> str:
+        """Strip the trailing ``_{method}`` from an operationId.
+
+        This is the default (non-short) simplification — removes only the
+        HTTP method suffix while preserving the full path information.
+        """
+        suffix = f"_{method.lower()}"
+        if operation_id.endswith(suffix):
+            return operation_id[: -len(suffix)]
+        return operation_id
+
+    @staticmethod
+    def _extract_func_name(operation_id: str, path: str, method: str) -> str:
+        """Extract the original function name from a FastAPI operationId.
+
+        FastAPI generates operationId as::
+
+            re.sub(r"\\W", "_", f"{func_name}{path}") + "_{method}"
 
-        FastAPI generates IDs like 'create_task_task_create_post'.
-        We strip the trailing path+method suffix to get the function name.
+        This method reverses that transformation to recover ``func_name``.
         """
-        # FastAPI pattern: {func_name}_{path_part}_{path_part}_{method}
-        # Try to extract just the function name by removing the suffix
-        parts = operation_id.rsplit("_", 1)
-        if len(parts) == 2 and parts[1] in ("get", "post", "put", "delete", "patch"):
-            return parts[0]
+        method_lower = method.lower()
+
+        # Reconstruct the path suffix exactly as FastAPI generates it:
+        # every non-word character (\W) in the path becomes "_"
+        path_suffix = re.sub(r"\W", "_", path)
+        expected_suffix = f"{path_suffix}_{method_lower}"
+
+        if operation_id.endswith(expected_suffix):
+            return operation_id[: -len(expected_suffix)].rstrip("_")
+
+        # Fallback: strip trailing _{method}
+        if operation_id.endswith(f"_{method_lower}"):
+            return operation_id[: -(len(method_lower) + 1)]
+
         return operation_id
 
     def _build_view_map(self, app: FastAPI) -> dict[str, str]:

tests/test_scanner.py

@@ -215,6 +215,59 @@ def test_metadata_has_source(self, app: FastAPI) -> None:
             assert "operation_id" in m.metadata
 
 
+# -- OpenAPIScanner simplify_ids --------------------------------------------
+
+
+class TestOpenAPIScannerSimplifyIds:
+    def test_simplified_ids_are_shorter(self, app: FastAPI) -> None:
+        default = OpenAPIScanner()
+        simplified = OpenAPIScanner(simplify_ids=True)
+
+        default_modules = default.scan(app)
+        simplified_modules = simplified.scan(app)
+
+        assert len(default_modules) == len(simplified_modules)
+        for d, s in zip(default_modules, simplified_modules):
+            assert len(s.module_id) <= len(d.module_id)
+
+    def test_simplified_ids_use_func_name(self, app: FastAPI) -> None:
+        scanner = OpenAPIScanner(simplify_ids=True)
+        modules = scanner.scan(app)
+        ids = {m.module_id for m in modules}
+
+        # Should contain clean function-name based IDs
+        assert "items.list_items.get" in ids
+        assert "items.create_item.post" in ids
+        assert "items.get_item.get" in ids
+        assert "items.delete_item.delete" in ids
+
+    def test_default_ids_contain_path_info(self, app: FastAPI) -> None:
+        scanner = OpenAPIScanner(simplify_ids=False)
+        modules = scanner.scan(app)
+        ids = {m.module_id for m in modules}
+
+        # Default IDs should contain path fragments (longer)
+        get_detail = next(mid for mid in ids if "get_item" in mid and mid.endswith(".get"))
+        assert "item_id" in get_detail  # path param info preserved
+
+    def test_simplify_ids_no_duplicates(self, app: FastAPI) -> None:
+        scanner = OpenAPIScanner(simplify_ids=True)
+        modules = scanner.scan(app)
+        ids = [m.module_id for m in modules]
+
+        assert len(ids) == len(set(ids)), f"Duplicate IDs found: {ids}"
+
+    def test_factory_passes_simplify_ids(self, app: FastAPI) -> None:
+        from fastapi_apcore.scanners import get_scanner
+
+        scanner = get_scanner("openapi", simplify_ids=True)
+        modules = scanner.scan(app)
+
+        # Verify simplified IDs (no path fragments like __item_id__)
+        for m in modules:
+            assert "__" not in m.module_id, f"Unsimplified ID: {m.module_id}"
+
+
 # -- get_scanner factory -----------------------------------------------------