adp-hypervisor 0.1.0.dev0__py3-none-any.whl

adp_hypervisor/__init__.py

@@ -0,0 +1,28 @@
+# Copyright 2026 Datastrato, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""ADP Hypervisor - Agentic Data Protocol Python Implementation."""
+
+__all__ = ["ADPServer"]
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import to avoid circular dependency with backends."""
+    if name == "ADPServer":
+        from adp_hypervisor.server import ADPServer
+
+        return ADPServer
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

adp_hypervisor/__main__.py

@@ -0,0 +1,289 @@
+# Copyright 2026 Datastrato, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+ADP Hypervisor CLI entry point.
+
+Starts the ADP server with the given configuration directory,
+log level, and transport type.
+
+Usage::
+
+    python -m adp_hypervisor --config /path/to/manifests
+    python -m adp_hypervisor --config /path/to/manifests --log-level DEBUG
+    python -m adp_hypervisor --config /path/to/manifests --transport stdio
+"""
+
+import argparse
+import asyncio
+import logging
+import logging.config
+import logging.handlers
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from adp_hypervisor.manifest.yaml_provider import YamlManifestProvider
+from adp_hypervisor.policy import UserRoleConfig, YamlRoleResolver
+from adp_hypervisor.server import ADPServer
+from adp_hypervisor.transport.stdio import StdioTransport
+
+logger = logging.getLogger(__name__)
+
+_VALID_LOG_LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
+_VALID_TRANSPORTS = ("stdio", "http")
+
+# Built-in default logging config, matches conf/logging_conf.yaml.template.
+# Used when no logging_conf.yaml is present in the config directory.
+_DEFAULT_LOGGING_CONFIG: dict[str, Any] = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "standard": {
+            "format": "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+            "datefmt": "%Y-%m-%dT%H:%M:%S",
+        }
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "standard",
+            "stream": "ext://sys.stderr",
+        },
+        "file_handler": {
+            "class": "logging.handlers.RotatingFileHandler",
+            "formatter": "standard",
+            "filename": "./hypervisor-logs/hypervisor.log",
+            "maxBytes": 10485760,
+            "backupCount": 5,
+            "encoding": "utf-8",
+        },
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["console", "file_handler"],
+    },
+}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="adp_hypervisor",
+        description="ADP Hypervisor - Agentic Data Protocol server",
+    )
+    parser.add_argument(
+        "--config",
+        required=True,
+        help="Path to the manifest directory containing physical.yaml, "
+        "semantic.yaml, and policy.yaml",
+    )
+    parser.add_argument(
+        "--log-level",
+        default=None,
+        choices=_VALID_LOG_LEVELS,
+        help="Override the root logging level (default: level from logging_conf.yaml or INFO)",
+    )
+    parser.add_argument(
+        "--transport",
+        default="stdio",
+        choices=_VALID_TRANSPORTS,
+        help="Transport type (default: stdio)",
+    )
+    return parser
+
+
+def _load_logging_config(config_dir: Path) -> dict[str, Any]:
+    """Load logging configuration from config_dir/logging_conf.yaml.
+
+    Falls back to the built-in default when the file is absent.
+
+    Args:
+        config_dir: The runtime config directory.
+
+    Returns:
+        A dict suitable for logging.config.dictConfig.
+    """
+    logging_conf_path = config_dir / "logging_conf.yaml"
+    if logging_conf_path.exists():
+        try:
+            raw = yaml.safe_load(logging_conf_path.read_text(encoding="utf-8"))
+            if isinstance(raw, dict):
+                return raw
+            print(
+                f"Warning: {logging_conf_path} is not a YAML mapping (got {type(raw).__name__}), "
+                "using built-in logging defaults.",
+                file=sys.stderr,
+            )
+        except (yaml.YAMLError, OSError):
+            print(
+                f"Warning: failed to parse {logging_conf_path}, using built-in logging defaults.",
+                file=sys.stderr,
+            )
+    return _DEFAULT_LOGGING_CONFIG
+
+
+def _ensure_log_directories(config: dict[str, Any]) -> None:
+    """Create parent directories for all file-based log handlers.
+
+    Scans every handler in the config dict, resolves the parent directory
+    for any handler that has a ``filename`` key, and creates it if missing.
+    Emits a startup notice to stderr for each resolved log file path.
+
+    Args:
+        config: The logging config dict (as passed to dictConfig).
+    """
+    handlers = config.get("handlers", {})
+    for _name, handler_cfg in handlers.items():
+        filename = handler_cfg.get("filename")
+        if not filename:
+            continue
+        log_path = Path(filename).resolve()
+        log_dir = log_path.parent
+        log_dir.mkdir(parents=True, exist_ok=True)
+        print(
+            f"ADP Hypervisor: logging to file {log_path}",
+            file=sys.stderr,
+        )
+
+
+def _configure_logging(config_dir: Path, level_override: str | None) -> None:
+    """Load and apply logging configuration.
+
+    Reads logging_conf.yaml from config_dir (falls back to built-in defaults),
+    ensures all file-handler directories exist, then applies the config via
+    dictConfig. Overrides the root log level when --log-level is provided.
+
+    Args:
+        config_dir: The runtime config directory.
+        level_override: Optional log level string (e.g. "DEBUG") from --log-level.
+    """
+    config = _load_logging_config(config_dir)
+
+    if level_override is not None:
+        config.setdefault("root", {})["level"] = level_override
+
+    _ensure_log_directories(config)
+    logging.config.dictConfig(config)
+
+
+def _create_yaml_provider(config_dir: Path) -> YamlManifestProvider:
+    """Create a YAML manifest provider from a config directory.
+
+    Args:
+        config_dir: Path to the directory containing physical.yaml,
+            semantic.yaml, and policy.yaml manifest files.
+
+    Returns:
+        A configured YamlManifestProvider instance.
+
+    Raises:
+        FileNotFoundError: If required manifest files are missing.
+    """
+    physical_path = config_dir / "physical.yaml"
+    semantic_path = config_dir / "semantic.yaml"
+    policy_path = config_dir / "policy.yaml"
+
+    for path in (physical_path, semantic_path):
+        if not path.exists():
+            raise FileNotFoundError(f"Manifest file not found: {path}")
+
+    # Accept a missing policy file gracefully — ACCESS enforcement uses
+    # closed-by-default semantics, so an empty policy file simply denies all.
+    if not policy_path.exists():
+        try:
+            policy_path.write_text("version: '1.0.0'\n", encoding="utf-8")
+        except OSError as exc:
+            raise FileNotFoundError(
+                f"Policy manifest not found at {policy_path} and could not be created. "
+                "Ensure the config directory is writable or provide a policy.yaml file."
+            ) from exc
+
+    return YamlManifestProvider(
+        physical_path=physical_path,
+        semantic_path=semantic_path,
+        policy_path=policy_path,
+    )
+
+
+def _create_role_resolver(config_dir: Path) -> YamlRoleResolver:
+    """Create a role resolver from a config directory.
+
+    Loads the user-to-role mapping from ``users.yaml`` in the config
+    directory. If the file does not exist, returns a resolver with
+    default configuration.
+
+    Args:
+        config_dir: Path to the directory containing users.yaml.
+
+    Returns:
+        A configured YamlRoleResolver instance.
+    """
+    users_path = config_dir / "users.yaml"
+    if not users_path.exists():
+        logger.info("No users.yaml found in %s, using default role config", config_dir)
+        return YamlRoleResolver(UserRoleConfig())
+
+    import yaml
+
+    try:
+        raw = yaml.safe_load(users_path.read_text(encoding="utf-8"))
+        config = UserRoleConfig.model_validate(raw or {})
+    except (yaml.YAMLError, ValueError) as exc:
+        logger.error("Failed to load %s, using default role config: %s", users_path, exc)
+        return YamlRoleResolver(UserRoleConfig())
+
+    logger.info(
+        "Loaded user-role config: %d users, default_role=%r",
+        len(config.users),
+        config.default_role,
+    )
+    return YamlRoleResolver(config)
+
+
+def main(args: list[str] | None = None) -> None:
+    """Parse arguments and run the ADP server.
+
+    Args:
+        args: Command-line arguments. Defaults to sys.argv[1:].
+    """
+    parser = _build_parser()
+    parsed = parser.parse_args(args)
+
+    config_dir = Path(parsed.config)
+    _configure_logging(config_dir, parsed.log_level)
+
+    if parsed.transport == "http":
+        logger.error("HTTP transport is not yet implemented")
+        sys.exit(1)
+
+    transport = StdioTransport()
+    provider = _create_yaml_provider(config_dir)
+    role_resolver = _create_role_resolver(config_dir)
+    server = ADPServer(manifest_provider=provider, transport=transport, role_resolver=role_resolver)
+
+    logger.info(
+        "Starting ADP Hypervisor: config=%s, transport=%s, log_level=%s",
+        parsed.config,
+        parsed.transport,
+        parsed.log_level or "from config",
+    )
+
+    asyncio.run(server.run())
+
+
+if __name__ == "__main__":
+    main()

adp_hypervisor/handlers/__init__.py

@@ -0,0 +1,35 @@
+# Copyright 2026 Datastrato, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""ADP Request Handlers."""
+
+from adp_hypervisor.handlers.base import Handler
+from adp_hypervisor.handlers.describe import DescribeHandler
+from adp_hypervisor.handlers.discover import DiscoverHandler
+from adp_hypervisor.handlers.execute import ExecuteHandler
+from adp_hypervisor.handlers.initialize import InitializeHandler
+from adp_hypervisor.handlers.ping import PingHandler
+from adp_hypervisor.handlers.validate import ValidateHandler
+
+__all__ = [
+    # Base
+    "Handler",
+    # Handlers
+    "DescribeHandler",
+    "DiscoverHandler",
+    "ExecuteHandler",
+    "InitializeHandler",
+    "PingHandler",
+    "ValidateHandler",
+]

adp_hypervisor/handlers/base.py

@@ -0,0 +1,45 @@
+# Copyright 2026 Datastrato, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Handler abstract base class.
+
+Defines the abstract interface that all ADP request handlers must implement.
+Each handler processes a specific JSON-RPC method (e.g., adp.initialize, adp.ping).
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class Handler(ABC):
+    """Handler abstract base class for processing ADP requests."""
+
+    @property
+    @abstractmethod
+    def method(self) -> str:
+        """Return the JSON-RPC method name this handler processes."""
+
+    @abstractmethod
+    async def handle(self, params: dict[str, Any]) -> BaseModel:
+        """Process a request and return the result.
+
+        Args:
+            params: The JSON-RPC request parameters.
+
+        Returns:
+            A Pydantic model representing the response.
+        """

adp_hypervisor/handlers/describe.py

@@ -0,0 +1,286 @@
+# Copyright 2026 Datastrato, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Describe Handler.
+
+Implements the adp.describe method which returns the UsageContract
+(field definitions and capabilities) for a specific resource and intent class.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+from adp_hypervisor.handlers.base import Handler
+from adp_hypervisor.policy.enforcer import PolicyEnforcer
+from adp_hypervisor.protocol.errors import InvalidParamsError, ResourceNotFoundError
+from adp_hypervisor.protocol.types import (
+    Capabilities,
+    DescribeRequestParams,
+    DescribeResult,
+    Field,
+    FieldType,
+    IntentClass,
+    MutableCapability,
+    PredicateCapability,
+    PredicateOperator,
+    PredicateUsage,
+    ProjectionCapability,
+    UsageContract,
+)
+
+if TYPE_CHECKING:
+    from adp_hypervisor.manifest.index import ManifestIndex
+
+logger = logging.getLogger(__name__)
+
+# Operator mapping by FieldType
+# Operator Sets (Reusable groups of operators)
+_BASIC_OPS = [
+    PredicateOperator.EQ,
+    PredicateOperator.NEQ,
+]
+
+_ORDERING_OPS = [
+    PredicateOperator.GT,
+    PredicateOperator.LT,
+    PredicateOperator.GTE,
+    PredicateOperator.LTE,
+]
+
+_MATCHING_OPS = [
+    PredicateOperator.LIKE,
+    PredicateOperator.ILIKE,
+    PredicateOperator.CONTAINS,
+]
+
+_SET_OPS = [
+    PredicateOperator.IN,
+]
+
+# Combined Operator Groups
+_NUMERIC_OPS = _BASIC_OPS + _ORDERING_OPS + _SET_OPS
+_TEXT_OPS = _NUMERIC_OPS + _MATCHING_OPS
+_CONTAINER_OPS = _BASIC_OPS + [PredicateOperator.CONTAINS]
+_VECTOR_OPS = [PredicateOperator.SIMILAR]
+
+
+# Field Type Categories
+_TEXT_TYPES = {
+    FieldType.STRING,
+    FieldType.DATE,
+    FieldType.TIMESTAMP,
+}
+
+_NUMERIC_TYPES = {
+    FieldType.INTEGER,
+    FieldType.FLOAT,
+}
+
+_BASIC_TYPES = {
+    FieldType.BOOLEAN,
+}
+
+_CONTAINER_TYPES = {
+    FieldType.JSON,
+    FieldType.BLOB,
+}
+
+_VECTOR_TYPES = {
+    FieldType.VECTOR,
+}
+
+
+# Dynamic Operator Mapping Construction
+_OPERATORS_BY_FIELD_TYPE: dict[FieldType, list[PredicateOperator]] = {}
+
+
+def _register_operators(field_types: set[FieldType], operators: list[PredicateOperator]) -> None:
+    for field_type in field_types:
+        _OPERATORS_BY_FIELD_TYPE[field_type] = operators
+
+
+_register_operators(_TEXT_TYPES, _TEXT_OPS)
+_register_operators(_NUMERIC_TYPES, _NUMERIC_OPS)
+_register_operators(_BASIC_TYPES, _BASIC_OPS)
+_register_operators(_CONTAINER_TYPES, _CONTAINER_OPS)
+_register_operators(_VECTOR_TYPES, _VECTOR_OPS)
+
+
+def _get_operators_for_field(field_type: FieldType | None) -> list[PredicateOperator]:
+    """Return allowed predicate operators for a given field type."""
+    if field_type is None:
+        return [PredicateOperator.EQ]
+    return list(_OPERATORS_BY_FIELD_TYPE.get(field_type, [PredicateOperator.EQ]))
+
+
+def _get_mandatory_field_ids(manifest_index: ManifestIndex, resource_id: str) -> set[str]:
+    """Get field IDs that have MANDATORY_FILTER policy rules."""
+
+    policies = manifest_index.get_mandatory_filter_policies(resource_id)
+    return {p.field_id for p in policies}
+
+
+def _build_read_capabilities(fields: list[Field], mandatory_field_ids: set[str]) -> Capabilities:
+    """Build capabilities for READ intent classes (LOOKUP, QUERY)."""
+    predicates = [
+        PredicateCapability(
+            field_id=f.field_id,
+            usage=(
+                PredicateUsage.REQUIRED
+                if f.field_id in mandatory_field_ids
+                else PredicateUsage.OPTIONAL
+            ),
+            operators=_get_operators_for_field(f.type),
+        )
+        for f in fields
+    ]
+    projections = [ProjectionCapability(field_id=f.field_id) for f in fields]
+    return Capabilities(predicates=predicates, projections=projections)
+
+
+def _build_write_capabilities(fields: list[Field]) -> Capabilities:
+    """Build capabilities for WRITE intent classes (INGEST, REVISE)."""
+    mutables = [MutableCapability(field_id=f.field_id) for f in fields]
+    return Capabilities(mutables=mutables)
+
+
+def _is_read_intent(intent_class: IntentClass) -> bool:
+    return intent_class in (IntentClass.LOOKUP, IntentClass.QUERY)
+
+
+class DescribeHandler(Handler):
+    """Handler for the adp.describe method.
+
+    Returns the UsageContract (field definitions and capabilities) for a
+    specific resource and intent class. Capabilities are auto-derived from
+    the resource's field types and policy rules.
+    """
+
+    def __init__(self, manifest_index: ManifestIndex, policy_enforcer: PolicyEnforcer) -> None:
+        """Initialize the handler.
+
+        Args:
+            manifest_index: The manifest index to look up resources and policies.
+            policy_enforcer: The policy enforcer to check access.
+        """
+        self._manifest_index = manifest_index
+        self._policy_enforcer = policy_enforcer
+
+    @property
+    def method(self) -> str:
+        """Return the JSON-RPC method name this handler processes."""
+        return "adp.describe"
+
+    async def handle(self, params: dict[str, Any]) -> BaseModel:
+        """Process a describe request.
+
+        Args:
+            params: The JSON-RPC request parameters.
+
+        Returns:
+            A DescribeResult with the usage contract for the requested resource.
+
+        Raises:
+            InvalidParamsError: If the intent class is invalid or unsupported.
+            ResourceNotFoundError: If the resource does not exist.
+        """
+        request = DescribeRequestParams.model_validate(params)
+
+        role = self._policy_enforcer.resolve_role(params)
+
+        self._validate_intent_class(request.intent_class)
+
+        resource = self._manifest_index.get_resource(request.resource_id, version=request.version)
+        if resource is None:
+            raise ResourceNotFoundError(
+                f"Resource not found: {request.resource_id!r}"
+                + (f" version={request.version}" if request.version is not None else "")
+            )
+
+        self._validate_resource_supports_intent(
+            request.resource_id, request.intent_class, resource.intent_classes
+        )
+
+        self._policy_enforcer.check_access(request.resource_id, role, request.intent_class)
+
+        fields = self._extract_fields(resource)
+        capabilities = self._build_capabilities(fields, request.intent_class, request.resource_id)
+
+        logger.info(
+            "Describe: resource=%s, version=%s, intent_class=%s, fields=%d",
+            request.resource_id,
+            resource.version,
+            request.intent_class,
+            len(fields),
+        )
+
+        return DescribeResult(
+            resource_id=request.resource_id,
+            version=resource.version or 1,
+            intent_class=request.intent_class,
+            usage_contract=UsageContract(fields=fields, capabilities=capabilities),
+        )
+
+    def _validate_intent_class(self, intent_class: IntentClass) -> None:
+        if intent_class == IntentClass.WILDCARD:
+            raise InvalidParamsError(
+                "WILDCARD intent class is not allowed in describe requests. "
+                "Please specify a concrete intent class (LOOKUP, QUERY, INGEST, REVISE)."
+            )
+
+    def _validate_resource_supports_intent(
+        self,
+        resource_id: str,
+        intent_class: IntentClass,
+        resource_intent_classes: list[IntentClass],
+    ) -> None:
+        if not resource_intent_classes:
+            raise InvalidParamsError(
+                f"Resource {resource_id!r} does not declare any supported intent classes. "
+                "Use adp.discover to find resources supporting your intent class."
+            )
+        if (
+            intent_class not in resource_intent_classes
+            and IntentClass.WILDCARD not in resource_intent_classes
+        ):
+            supported = ", ".join(ic.value for ic in resource_intent_classes)
+            raise InvalidParamsError(
+                f"Resource {resource_id!r} does not support intent class {intent_class.value}. "
+                f"Supported intent classes: {supported}. "
+                "Use adp.discover to find resources supporting your intent class."
+            )
+
+    def _extract_fields(self, resource: Any) -> list[Field]:
+        """Extract fields from the resource's source definition."""
+        if resource.source_definition.fields:
+            return list(resource.source_definition.fields)
+        return []
+
+    def _build_capabilities(
+        self,
+        fields: list[Field],
+        intent_class: IntentClass,
+        resource_id: str,
+    ) -> Capabilities:
+        if _is_read_intent(intent_class):
+            # TODO: enforce policy rules once the policy spec is finalized.
+            # Use _get_mandatory_field_ids(self._manifest_index, resource_id) to
+            # derive REQUIRED predicates from MandatoryFilterRule entries.
+            return _build_read_capabilities(fields, mandatory_field_ids=set())
+        return _build_write_capabilities(fields)