"""Minimal CatOpt bridge scaffolding for NovaPlan.

This module provides a tiny, domain-agnostic scaffold to map NovaPlan MVP
primitives to a CatOpt-like representation. It is intentionally lightweight and
intended for experimentation and integration in MVP milestones.

- Object: canonical local problem representation (LocalProblem).
- Morphism: exchange vectors such as SharedVariables and PlanDelta with versioning.
- Functor: adapters that translate device-specific planning representations into the
  canonical NovaPlan form.

Note: This is a stubbed scaffold and not a full implementation. Real adapters
and a transport layer would be built on top of this in Phase 0/1 milestones.
"""
from __future__ import annotations

from typing import Dict, Any
from nova_plan.planner import LocalProblem
from nova_plan.contracts import PlanDelta


class Object:
    """A canonical representation of a local problem object in CatOpt terms."""

    def __init__(self, problem: LocalProblem):
        self.problem = problem

    def to_dict(self) -> Dict[str, Any]:
        return {
            "agent_id": self.problem.id,
            "variables": self.problem.variables,
            "constraints": self.problem.constraints,
        }


class Morphism:
    """Represents an exchange signal between agents (e.g., shared variable delta)."""

    def __init__(self, delta: Dict[str, float], source: str, target: str, version: int = 1):
        self.delta = delta
        self.source = source
        self.target = target
        self.version = version

    def to_json(self) -> str:
        import json
        return json.dumps({
            "delta": self.delta,
            "source": self.source,
            "target": self.target,
            "version": self.version,
        })


class Functor:
    """Adapter/translator between device-specific planning representations and NovaPlan."""

    def __init__(self, name: str):
        self.name = name

    def adapt(self, device_representation: Any) -> LocalProblem:
        """Translate a device-specific representation into a LocalProblem.

        This is a no-op placeholder in this MVP scaffold. Implementations would
        depend on the device vocabularies and the canonical NovaPlan schema.
        """
        raise NotImplementedError("Adapter not implemented yet in MVP scaffold")


def protocol_example(local: LocalProblem) -> str:
    """Return a small, human-readable protocol example for debugging."""
    obj = Object(local)
    return f"CatOpt Protocol Example: agent={obj.to_dict().get('agent_id')}"


__all__ = ["Object", "Morphism", "Functor", "protocol_example", "validate_contracts"]


def validate_contracts(obj: Object, morphism: Morphism) -> bool:
    """Validate basic contract compatibility between Object and Morphism.

    Ensures that the delta keys carried by the Morphism are a subset of the
    Object's local variables. This is a lightweight guard to catch obvious
    contract mismatches early in the MVP bridge.
    """
    obj_vars = set(obj.to_dict().get("variables", {}).keys())
    delta_keys = set(morphism.delta.keys())
    return delta_keys.issubset(obj_vars)


def to_object(local: LocalProblem) -> Object:
    """Convenience helper: convert a LocalProblem into its canonical Object form."""
    return Object(local)


def to_morphism(delta: Dict[str, float], source: str, target: str, version: int = 1) -> Morphism:
    """Convenience helper: produce a Morphism carrying an optimization delta."""
    return Morphism(delta=delta, source=source, target=target, version=version)


def bridge_example(local: LocalProblem, source: str = "rover", target: str = "habitat") -> Dict[str, Any]:
    """Create a tiny bridge example: Object + Morphism for a given delta.

    Returns a simple dictionary combining both representations for easy testing
    and experimentation in MVP pilots.
    """
    obj = Object(local)
    # small, illustrative delta: take current local variables as delta snapshot
    delta = {k: v for k, v in local.variables.items()}
    morph = Morphism(delta=delta, source=source, target=target, version=1)
    return {
        "object": obj.to_dict(),
        "morphism": morph.to_json(),
    }