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

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

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] - 2026-03-23
+
+### Added
+
+- **`DisplayResolver`** (`apcore_toolkit.display`) — sparse binding.yaml display overlay (§5.13). Merges per-surface presentation fields (alias, description, guidance, tags, documentation) into `ScannedModule.metadata["display"]` for downstream CLI/MCP/A2A surfaces.
+  - Resolution chain per field: surface-specific override > `display` default > binding-level field > scanner value.
+  - `resolve(modules, *, binding_path=..., binding_data=...)` — accepts pre-parsed dict or a path to a `.binding.yaml` file / directory of `*.binding.yaml` files. `binding_data` takes precedence over `binding_path`.
+  - MCP alias auto-sanitization: replaces characters outside `[a-zA-Z0-9_-]` with `_`; prepends `_` if result starts with a digit.
+  - MCP alias hard limit: raises `ValueError` if sanitized alias exceeds 64 characters.
+  - CLI alias validation: warns and falls back to `display.alias` when user-explicitly-set alias does not match `^[a-z][a-z0-9_-]*$` (module_id fallback always accepted without warning).
+  - `suggested_alias` in `ScannedModule.metadata` (emitted by `simplify_ids=True` scanner) used as fallback when no `display.alias` is set.
+  - Match-count logging: `INFO` for match count, `WARNING` when binding map loaded but zero modules matched.
+- **`DisplayResolver` public export** — available as `from apcore_toolkit.display import DisplayResolver` and `from apcore_toolkit import DisplayResolver`.
+
+### Tests
+
+- 30 new tests in `tests/test_display_resolver.py` covering: no-binding fallthrough, alias-only overlay, surface-specific overrides, MCP sanitization, MCP 64-char limit, `suggested_alias` fallback, sparse overlay (10 modules / 1 binding), tags resolution, `binding_path` file and directory loading, guidance chain, CLI invalid alias warning and fallback, `binding_data` vs `binding_path` precedence.
+
+### Added (Convention Module Discovery — §5.14)
+
+- **`ConventionScanner`** — scans a `commands/` directory of plain Python files for public functions and converts them to `ScannedModule` instances with schema inferred from type annotations.
+  - Module ID: `{file_prefix}.{function_name}` with `MODULE_PREFIX` override.
+  - Description from first line of docstring (`"(no description)"` fallback).
+  - `input_schema` / `output_schema` inferred from PEP 484 type hints.
+  - `CLI_GROUP` and `TAGS` module-level constants stored in metadata.
+  - `include` / `exclude` regex filters on module IDs.
+- **`ConventionScanner` public export** — available as `from apcore_toolkit import ConventionScanner`.
+
+### Tests (Convention Module Discovery)
+
+- 15 new tests in `tests/test_convention_scanner.py`.
+
+---
+## [0.3.1] - 2026-03-22
+
+### Changed
+- Rebrand: aipartnerup → aiperceivable
+
 ## [0.3.0] - 2026-03-19
 
 ### Added

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

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: apcore-toolkit
-Version: 0.3.0
+Version: 0.4.0
 Summary: Shared scanner, schema extraction, and output toolkit for apcore framework adapters
-Project-URL: Homepage, https://aipartnerup.com
-Project-URL: Repository, https://github.com/aipartnerup/apcore-toolkit-python
-Project-URL: Documentation, https://github.com/aipartnerup/apcore-toolkit-python#readme
-Project-URL: Issues, https://github.com/aipartnerup/apcore-toolkit-python/issues
-Author-email: aipartnerup <tercel.yi@gmail.com>
+Project-URL: Homepage, https://aiperceivable.com
+Project-URL: Repository, https://github.com/aiperceivable/apcore-toolkit-python
+Project-URL: Documentation, https://github.com/aiperceivable/apcore-toolkit-python#readme
+Project-URL: Issues, https://github.com/aiperceivable/apcore-toolkit-python/issues
+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
@@ -25,12 +25,12 @@ Requires-Dist: httpx>=0.24; extra == 'http-proxy'
 Description-Content-Type: text/markdown
 
 <div align="center">
-  <img src="https://raw.githubusercontent.com/aipartnerup/apcore-toolkit/main/apcore-toolkit-logo.svg" alt="apcore-toolkit logo" width="200"/>
+  <img src="https://raw.githubusercontent.com/aiperceivable/apcore-toolkit/main/apcore-toolkit-logo.svg" alt="apcore-toolkit logo" width="200"/>
 </div>
 
 # apcore-toolkit-python
 
-Python implementation of the [apcore-toolkit](https://github.com/aipartnerup/apcore-toolkit).
+Python implementation of the [apcore-toolkit](https://github.com/aiperceivable/apcore-toolkit).
 
 Extracts ~1,400 lines of duplicated framework-agnostic logic from `django-apcore` and `flask-apcore` into a standalone Python package.
 
@@ -67,6 +67,8 @@ pip install apcore-toolkit
 | `resolve_target` | Resolves "module.path:function_name" to callable |
 | `enrich_schema_descriptions` | Merges descriptions into JSON Schema properties |
 | `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) |
 
 ## Usage
 
@@ -162,16 +164,89 @@ from apcore_toolkit import to_markdown
 md = to_markdown({"name": "Alice", "role": "admin"}, title="User Info")
 ```
 
+### Display Overlay (§5.13)
+
+`DisplayResolver` applies a sparse `binding.yaml` display overlay to a list of `ScannedModule` instances, populating `metadata["display"]` with surface-facing presentation fields (alias, description, guidance, tags) for CLI, MCP, and A2A surfaces.
+
+```python
+from apcore_toolkit.display import DisplayResolver
+
+resolver = DisplayResolver()
+
+# Apply overlay from a directory of *.binding.yaml files
+modules = resolver.resolve(scanned_modules, binding_path="bindings/")
+
+# Or from a pre-parsed dict
+modules = resolver.resolve(
+    scanned_modules,
+    binding_data={
+        "bindings": [
+            {
+                "module_id": "product.get",
+                "display": {
+                    "alias": "product-get",
+                    "description": "Get a product by ID",
+                    "cli": {"alias": "get-product"},
+                    "mcp": {"alias": "get_product"},
+                },
+            }
+        ]
+    },
+)
+
+# Resolved fields are in metadata["display"]
+mod = modules[0]
+print(mod.metadata["display"]["cli"]["alias"])   # "get-product"
+print(mod.metadata["display"]["mcp"]["alias"])   # "get_product"
+print(mod.metadata["display"]["a2a"]["alias"])   # "product-get"
+```
+
+**Resolution chain** (per field): surface-specific override > `display` default > binding-level field > scanner value.
+
+**MCP alias constraints**: automatically sanitized (non-`[a-zA-Z0-9_-]` chars replaced with `_`; leading digit prefixed with `_`); raises `ValueError` if result exceeds 64 characters.
+
+**CLI alias validation**: warns and falls back to `display.alias` when a user-explicitly-set alias does not match `^[a-z][a-z0-9_-]*$`.
+
+### Convention Module Discovery (§5.14)
+
+`ConventionScanner` scans a directory of plain Python files for public functions and converts them to `ScannedModule` instances. No decorators, no base classes, no imports from apcore -- just functions with type hints.
+
+```python
+from apcore_toolkit import ConventionScanner
+
+scanner = ConventionScanner()
+modules = scanner.scan(commands_dir="commands/")
+
+# Each public function becomes a module:
+#   commands/deploy.py  ->  deploy.deploy
+#   commands/deploy.py  ->  deploy.rollback  (if rollback() exists)
+```
+
+Module-level constants customize behavior:
+
+```python
+# commands/deploy.py
+MODULE_PREFIX = "ops"       # override file-based prefix -> ops.deploy
+CLI_GROUP = "operations"    # group hint for CLI surface
+TAGS = ["infra", "deploy"]  # tags stored in metadata
+
+def deploy(env: str, tag: str = "latest") -> dict:
+    """Deploy the app to the given environment."""
+    return {"status": "deployed", "env": env}
+```
+
+Input and output schemas are inferred from PEP 484 type annotations. Use `include` / `exclude` regex filters to control which module IDs are registered.
+
 ## Requirements
 
 - Python >= 3.11
-- apcore >= 0.13.0
+- apcore >= 0.13.1
 - pydantic >= 2.0
 - PyYAML >= 6.0
 
 ## Documentation
 
-Full documentation is available at [https://github.com/aipartnerup/apcore-toolkit](https://github.com/aipartnerup/apcore-toolkit).
+Full documentation is available at [https://github.com/aiperceivable/apcore-toolkit](https://github.com/aiperceivable/apcore-toolkit).
 
 ## License
 

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

@@ -1,10 +1,10 @@
 <div align="center">
-  <img src="https://raw.githubusercontent.com/aipartnerup/apcore-toolkit/main/apcore-toolkit-logo.svg" alt="apcore-toolkit logo" width="200"/>
+  <img src="https://raw.githubusercontent.com/aiperceivable/apcore-toolkit/main/apcore-toolkit-logo.svg" alt="apcore-toolkit logo" width="200"/>
 </div>
 
 # apcore-toolkit-python
 
-Python implementation of the [apcore-toolkit](https://github.com/aipartnerup/apcore-toolkit).
+Python implementation of the [apcore-toolkit](https://github.com/aiperceivable/apcore-toolkit).
 
 Extracts ~1,400 lines of duplicated framework-agnostic logic from `django-apcore` and `flask-apcore` into a standalone Python package.
 
@@ -41,6 +41,8 @@ pip install apcore-toolkit
 | `resolve_target` | Resolves "module.path:function_name" to callable |
 | `enrich_schema_descriptions` | Merges descriptions into JSON Schema properties |
 | `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) |
 
 ## Usage
 
@@ -136,16 +138,89 @@ from apcore_toolkit import to_markdown
 md = to_markdown({"name": "Alice", "role": "admin"}, title="User Info")
 ```
 
+### Display Overlay (§5.13)
+
+`DisplayResolver` applies a sparse `binding.yaml` display overlay to a list of `ScannedModule` instances, populating `metadata["display"]` with surface-facing presentation fields (alias, description, guidance, tags) for CLI, MCP, and A2A surfaces.
+
+```python
+from apcore_toolkit.display import DisplayResolver
+
+resolver = DisplayResolver()
+
+# Apply overlay from a directory of *.binding.yaml files
+modules = resolver.resolve(scanned_modules, binding_path="bindings/")
+
+# Or from a pre-parsed dict
+modules = resolver.resolve(
+    scanned_modules,
+    binding_data={
+        "bindings": [
+            {
+                "module_id": "product.get",
+                "display": {
+                    "alias": "product-get",
+                    "description": "Get a product by ID",
+                    "cli": {"alias": "get-product"},
+                    "mcp": {"alias": "get_product"},
+                },
+            }
+        ]
+    },
+)
+
+# Resolved fields are in metadata["display"]
+mod = modules[0]
+print(mod.metadata["display"]["cli"]["alias"])   # "get-product"
+print(mod.metadata["display"]["mcp"]["alias"])   # "get_product"
+print(mod.metadata["display"]["a2a"]["alias"])   # "product-get"
+```
+
+**Resolution chain** (per field): surface-specific override > `display` default > binding-level field > scanner value.
+
+**MCP alias constraints**: automatically sanitized (non-`[a-zA-Z0-9_-]` chars replaced with `_`; leading digit prefixed with `_`); raises `ValueError` if result exceeds 64 characters.
+
+**CLI alias validation**: warns and falls back to `display.alias` when a user-explicitly-set alias does not match `^[a-z][a-z0-9_-]*$`.
+
+### Convention Module Discovery (§5.14)
+
+`ConventionScanner` scans a directory of plain Python files for public functions and converts them to `ScannedModule` instances. No decorators, no base classes, no imports from apcore -- just functions with type hints.
+
+```python
+from apcore_toolkit import ConventionScanner
+
+scanner = ConventionScanner()
+modules = scanner.scan(commands_dir="commands/")
+
+# Each public function becomes a module:
+#   commands/deploy.py  ->  deploy.deploy
+#   commands/deploy.py  ->  deploy.rollback  (if rollback() exists)
+```
+
+Module-level constants customize behavior:
+
+```python
+# commands/deploy.py
+MODULE_PREFIX = "ops"       # override file-based prefix -> ops.deploy
+CLI_GROUP = "operations"    # group hint for CLI surface
+TAGS = ["infra", "deploy"]  # tags stored in metadata
+
+def deploy(env: str, tag: str = "latest") -> dict:
+    """Deploy the app to the given environment."""
+    return {"status": "deployed", "env": env}
+```
+
+Input and output schemas are inferred from PEP 484 type annotations. Use `include` / `exclude` regex filters to control which module IDs are registered.
+
 ## Requirements
 
 - Python >= 3.11
-- apcore >= 0.13.0
+- apcore >= 0.13.1
 - pydantic >= 2.0
 - PyYAML >= 6.0
 
 ## Documentation
 
-Full documentation is available at [https://github.com/aipartnerup/apcore-toolkit](https://github.com/aipartnerup/apcore-toolkit).
+Full documentation is available at [https://github.com/aiperceivable/apcore-toolkit](https://github.com/aiperceivable/apcore-toolkit).
 
 ## License
 

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

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-toolkit"
-version = "0.3.0"
+version = "0.4.0"
 description = "Shared scanner, schema extraction, and output toolkit for apcore framework adapters"
 requires-python = ">=3.11"
 readme = "README.md"
 license = "Apache-2.0"
 authors = [
-    { name = "aipartnerup", email = "tercel.yi@gmail.com" },
+    { name = "aiperceivable", email = "tercel.yi@gmail.com" },
 ]
 keywords = [
     "apcore",
@@ -40,10 +40,10 @@ dev = [
 ]
 
 [project.urls]
-Homepage = "https://aipartnerup.com"
-Repository = "https://github.com/aipartnerup/apcore-toolkit-python"
-Documentation = "https://github.com/aipartnerup/apcore-toolkit-python#readme"
-Issues = "https://github.com/aipartnerup/apcore-toolkit-python/issues"
+Homepage = "https://aiperceivable.com"
+Repository = "https://github.com/aiperceivable/apcore-toolkit-python"
+Documentation = "https://github.com/aiperceivable/apcore-toolkit-python#readme"
+Issues = "https://github.com/aiperceivable/apcore-toolkit-python/issues"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/apcore_toolkit"]

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

@@ -6,6 +6,7 @@ Public API re-exports for convenient access to core types and utilities.
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _get_version
 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 (
     extract_input_schema,
@@ -29,6 +30,7 @@ from apcore_toolkit.output.verifiers import (
 )
 from apcore_toolkit.output.yaml_writer import YAMLWriter
 from apcore_toolkit.pydantic_utils import flatten_pydantic_params, resolve_target
+from apcore_toolkit.convention_scanner import ConventionScanner
 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
@@ -41,7 +43,9 @@ except PackageNotFoundError:
 
 __all__ = [
     "AIEnhancer",
+    "DisplayResolver",
     "BaseScanner",
+    "ConventionScanner",
     "HTTPProxyRegistryWriter",
     "Enhancer",
     "JSONVerifier",

apcore_toolkit-0.4.0/src/apcore_toolkit/convention_scanner.py

@@ -0,0 +1,215 @@
+"""Convention Module Scanner — discovers plain functions as apcore modules (§5.14)."""
+
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import logging
+import re
+import sys
+from pathlib import Path
+from typing import Any, get_type_hints
+
+from apcore_toolkit.types import ScannedModule
+
+logger = logging.getLogger("apcore_toolkit")
+
+# Type hint → JSON Schema mapping (subset of §5.11.5)
+_TYPE_MAP: dict[type, dict[str, Any]] = {
+    str: {"type": "string"},
+    int: {"type": "integer"},
+    float: {"type": "number"},
+    bool: {"type": "boolean"},
+    list: {"type": "array"},
+    dict: {"type": "object"},
+}
+
+
+class ConventionScanner:
+    """Scan a directory of plain Python files for public functions.
+
+    Converts each discovered function into a ScannedModule with
+    schema inferred from type annotations and description from docstrings.
+
+    Usage::
+
+        scanner = ConventionScanner()
+        modules = scanner.scan("commands/")
+    """
+
+    def scan(
+        self,
+        commands_dir: str | Path,
+        *,
+        include: str | None = None,
+        exclude: str | None = None,
+    ) -> list[ScannedModule]:
+        """Scan a commands directory for convention modules.
+
+        Args:
+            commands_dir: Path to the commands directory.
+            include: Regex pattern to include module IDs.
+            exclude: Regex pattern to exclude module IDs.
+
+        Returns:
+            List of ScannedModule instances.
+        """
+        commands_path = Path(commands_dir)
+        if not commands_path.is_dir():
+            logger.warning("ConventionScanner: commands directory not found: %s", commands_path)
+            return []
+
+        modules: list[ScannedModule] = []
+        for py_file in sorted(commands_path.rglob("*.py")):
+            if py_file.name.startswith("_"):
+                continue
+            try:
+                file_modules = self._scan_file(py_file, commands_path)
+                modules.extend(file_modules)
+            except Exception as exc:
+                logger.warning("ConventionScanner: failed to scan %s: %s", py_file, exc)
+
+        # Apply include/exclude filters
+        if include:
+            pattern = re.compile(include)
+            modules = [m for m in modules if pattern.search(m.module_id)]
+        if exclude:
+            pattern = re.compile(exclude)
+            modules = [m for m in modules if not pattern.search(m.module_id)]
+
+        logger.info("ConventionScanner: discovered %d modules from %s", len(modules), commands_path)
+        return modules
+
+    def _scan_file(self, py_file: Path, base_dir: Path) -> list[ScannedModule]:
+        """Scan a single Python file for public functions."""
+        # Derive prefix from relative path
+        rel = py_file.relative_to(base_dir)
+        parts = list(rel.with_suffix("").parts)
+        file_prefix = ".".join(parts)
+
+        # Load the module
+        spec = importlib.util.spec_from_file_location(f"_convention_{file_prefix}", py_file)
+        if spec is None or spec.loader is None:
+            return []
+
+        mod = importlib.util.module_from_spec(spec)
+        # Add parent directory to sys.path temporarily for imports
+        parent = str(py_file.parent)
+        added_path = parent not in sys.path
+        if added_path:
+            sys.path.insert(0, parent)
+        try:
+            spec.loader.exec_module(mod)
+        finally:
+            if added_path and parent in sys.path:
+                sys.path.remove(parent)
+
+        # Read module-level constants
+        module_prefix = getattr(mod, "MODULE_PREFIX", None)
+        cli_group = getattr(mod, "CLI_GROUP", None)
+        file_tags = getattr(mod, "TAGS", None) or []
+
+        prefix = module_prefix if isinstance(module_prefix, str) else file_prefix
+
+        # Discover public functions
+        results: list[ScannedModule] = []
+        for name, obj in inspect.getmembers(mod, inspect.isfunction):
+            # Skip private functions and imported functions
+            if name.startswith("_"):
+                continue
+            if getattr(obj, "__module__", None) != mod.__name__:
+                continue
+
+            module_id = f"{prefix}.{name}"
+            description = self._extract_description(obj)
+            input_schema = self._build_input_schema(obj)
+            output_schema = self._build_output_schema(obj)
+
+            metadata: dict[str, Any] = {}
+            if isinstance(cli_group, str):
+                metadata.setdefault("display", {}).setdefault("cli", {})["group"] = cli_group
+
+            results.append(
+                ScannedModule(
+                    module_id=module_id,
+                    description=description,
+                    input_schema=input_schema,
+                    output_schema=output_schema,
+                    tags=list(file_tags),
+                    target=f"{py_file}:{name}",
+                    metadata=metadata,
+                )
+            )
+
+        return results
+
+    def _extract_description(self, func: Any) -> str:
+        """Extract first line of docstring as description."""
+        doc = inspect.getdoc(func)
+        if not doc:
+            return "(no description)"
+        return doc.split("\n")[0].strip()
+
+    def _build_input_schema(self, func: Any) -> dict[str, Any]:
+        """Build JSON Schema from function parameter type hints."""
+        try:
+            hints = get_type_hints(func)
+        except Exception:
+            hints = {}
+
+        sig = inspect.signature(func)
+        properties: dict[str, Any] = {}
+        required: list[str] = []
+
+        for param_name, param in sig.parameters.items():
+            if param_name in ("self", "cls", "ctx", "context"):
+                continue
+
+            type_hint = hints.get(param_name)
+            prop = self._type_to_schema(type_hint)
+
+            if param.default is inspect.Parameter.empty:
+                required.append(param_name)
+            else:
+                if param.default is not None:
+                    prop["default"] = param.default
+
+            properties[param_name] = prop
+
+        schema: dict[str, Any] = {"type": "object", "properties": properties}
+        if required:
+            schema["required"] = required
+        return schema
+
+    def _build_output_schema(self, func: Any) -> dict[str, Any]:
+        """Build output schema from return type hint."""
+        try:
+            hints = get_type_hints(func)
+        except Exception:
+            return {}
+
+        ret = hints.get("return")
+        if ret is None or ret is type(None):
+            return {}
+        return self._type_to_schema(ret)
+
+    def _type_to_schema(self, type_hint: Any) -> dict[str, Any]:
+        """Convert a Python type hint to JSON Schema."""
+        if type_hint is None:
+            return {"type": "string"}
+
+        # Direct type mapping
+        if type_hint in _TYPE_MAP:
+            return dict(_TYPE_MAP[type_hint])
+
+        # Handle Optional[X] / X | None
+        origin = getattr(type_hint, "__origin__", None)
+        args = getattr(type_hint, "__args__", None)
+
+        if origin is list and args:
+            return {"type": "array", "items": self._type_to_schema(args[0])}
+        if origin is dict:
+            return {"type": "object"}
+
+        # Fallback
+        return {"type": "string"}

apcore_toolkit-0.4.0/src/apcore_toolkit/display/__init__.py

@@ -0,0 +1,10 @@
+"""Display overlay resolver for surface-facing presentation.
+
+Implements §5.13 of the apcore PROTOCOL_SPEC: sparse binding.yaml display
+section that controls how modules appear in CLI, MCP, and A2A surfaces
+without changing the canonical module_id.
+"""
+
+from apcore_toolkit.display.resolver import DisplayResolver
+
+__all__ = ["DisplayResolver"]