Update core/resource.py

core/resource.py

@@ -4,12 +4,10 @@ core.resource
 
 Generic resource representation for WorldSmithAI.
 
-This module defines the Resource runtime object used by the simulation engine.
 Resources are domain-agnostic quantities that agents and behaviors may observe,
 consume, regenerate, exchange, transform, or produce.
 
-Examples of resources include:
-
+Examples:
     - food
     - grass
     - water
@@ -23,26 +21,6 @@ Examples of resources include:
 
 The Resource class does not know what any resource type means. Domain semantics
 are supplied by the DSL, behaviors, policies, and world rules.
-
-Minimal usage example
----------------------
-
-    resource = Resource(
-        id="food_patch_1",
-        type="food",
-        amount=10.0,
-        position=[2.0, 3.0],
-        metadata={
-            "capacity": 20.0,
-            "regeneration_rate": 1.5,
-        },
-    )
-
-    depletion = resource.deplete(3.0)
-    print(depletion.new_amount)
-
-    regeneration = resource.regenerate()
-    print(regeneration.new_amount)
 """
 
 from __future__ import annotations
@@ -58,42 +36,13 @@ from numpy.typing import NDArray
 
 logger = logging.getLogger(__name__)
 
-PositionInput: TypeAlias = Sequence[float] | NDArray[np.float64]
+PositionInput: TypeAlias = Sequence[float] | NDArray[np.float64] | None
 ResourceOperation: TypeAlias = Literal["deplete", "regenerate", "set_amount"]
 
 
 @dataclass(frozen=True, slots=True)
 class ResourceOperationResult:
-    """
-    Structured result of a resource operation.
-
-    Attributes
-    ----------
-    resource_id:
-        Unique id of the affected resource.
-    resource_type:
-        Domain-level resource type string.
-    operation:
-        Operation name, such as ``"deplete"`` or ``"regenerate"``.
-    requested_amount:
-        Amount requested by the caller.
-    actual_delta:
-        Signed change applied to the resource amount.
-        Regeneration produces a positive delta.
-        Depletion produces a negative delta.
-    previous_amount:
-        Resource amount before the operation.
-    new_amount:
-        Resource amount after the operation.
-    success:
-        Whether the operation completed successfully.
-    partial:
-        Whether the operation applied less than the requested amount.
-    message:
-        Human-readable operation summary.
-    metadata:
-        Additional structured operation metadata.
-    """
+    """Structured result of a resource operation."""
 
     resource_id: str
     resource_type: str
@@ -108,16 +57,8 @@ class ResourceOperationResult:
     metadata: Mapping[str, Any] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
-        """
-        Validate operation result fields.
-
-        Raises
-        ------
-        ValueError
-            If any numeric field is non-finite or invalid.
-        TypeError
-            If metadata is not a mapping.
-        """
+        """Validate operation result fields."""
+
         numeric_fields = {
             "requested_amount": self.requested_amount,
             "actual_delta": self.actual_delta,
@@ -148,14 +89,8 @@ class ResourceOperationResult:
         object.__setattr__(self, "metadata", dict(self.metadata))
 
     def to_dict(self) -> dict[str, Any]:
-        """
-        Convert the operation result into a JSON-friendly dictionary.
-
-        Returns
-        -------
-        dict[str, Any]
-            Serializable operation result.
-        """
+        """Convert the operation result into a JSON-friendly dictionary."""
+
         return {
             "resource_id": self.resource_id,
             "resource_type": self.resource_type,
@@ -173,113 +108,82 @@ class ResourceOperationResult:
 
 @dataclass(slots=True)
 class Resource:
-    """
-    Generic domain-agnostic world resource.
-
-    A resource stores a finite non-negative quantity at a numeric position.
-    Its semantic meaning is entirely defined by the DSL and behaviors.
-
-    Attributes
-    ----------
-    id:
-        Unique resource identifier.
-    type:
-        Domain-level resource type string, such as ``"food"``, ``"money"``,
-        ``"knowledge"``, or ``"mana"``.
-    amount:
-        Current non-negative resource quantity.
-    position:
-        Numeric position vector. The engine does not assume 2D only.
-    metadata:
-        Optional structured metadata. Common optional keys may include
-        ``"capacity"``, ``"regeneration_rate"``, ``"owner_id"``, ``"tags"``,
-        or domain-specific configuration.
+    """Generic domain-agnostic world resource.
+
+    Runtime compatibility:
+        - ``position`` is always normalized to a NumPy array.
+        - ``regeneration_rate`` and ``max_amount`` are accepted directly because
+          WorldFactory may pass or attach them.
+        - ``max_amount`` is mirrored into metadata as both ``max_amount`` and
+          ``capacity`` for compatibility with older code.
     """
 
     id: str
     type: str
     amount: float
-    position: PositionInput
+    position: PositionInput = None
     metadata: dict[str, Any] = field(default_factory=dict)
+    regeneration_rate: float = 0.0
+    max_amount: float | None = None
+    dsl_spec: Any | None = None
 
     def __post_init__(self) -> None:
-        """
-        Validate and normalize resource fields.
-
-        Raises
-        ------
-        ValueError
-            If id, type, amount, or position are invalid.
-        TypeError
-            If metadata has invalid type or non-string keys.
-        """
+        """Validate and normalize resource fields."""
+
         if not isinstance(self.id, str) or not self.id.strip():
             raise ValueError("Resource.id must be a non-empty string.")
 
         if not isinstance(self.type, str) or not self.type.strip():
             raise ValueError("Resource.type must be a non-empty string.")
 
+        if not isinstance(self.metadata, Mapping):
+            raise TypeError("Resource.metadata must be a mapping.")
+
         self.id = self.id.strip()
         self.type = self.type.strip()
         self.amount = self._normalize_non_negative_float(self.amount, "amount")
         self.position = self._normalize_position(self.position)
 
-        if not isinstance(self.metadata, Mapping):
-            raise TypeError("Resource.metadata must be a mapping.")
-
         self.metadata = dict(self.metadata)
         self._validate_string_keys(self.metadata, "metadata")
 
-        capacity = self.capacity
-        if capacity is not None and self.amount > capacity:
+        self.regeneration_rate = self._resolve_regeneration_rate(self.regeneration_rate)
+        self.max_amount = self._resolve_max_amount(self.max_amount)
+
+        self.metadata.setdefault("regeneration_rate", self.regeneration_rate)
+
+        if self.max_amount is not None:
+            self.metadata.setdefault("max_amount", self.max_amount)
+            self.metadata.setdefault("capacity", self.max_amount)
+
+        if self.capacity is not None and self.amount > self.capacity:
             logger.warning(
-                "Resource amount exceeds metadata capacity: resource_id=%s "
-                "amount=%s capacity=%s",
+                "Resource amount exceeds capacity: resource_id=%s amount=%s capacity=%s",
                 self.id,
                 self.amount,
-                capacity,
+                self.capacity,
             )
 
     @property
     def capacity(self) -> float | None:
-        """
-        Optional maximum amount for this resource.
-
-        The value is read from ``metadata["capacity"]`` when present.
+        """Optional maximum amount for this resource."""
 
-        Returns
-        -------
-        float | None
-            Non-negative finite capacity, or None if no capacity is configured.
-        """
-        return self._read_optional_metadata_float("capacity")
+        if self.max_amount is not None:
+            return self.max_amount
 
-    @property
-    def regeneration_rate(self) -> float:
-        """
-        Optional default regeneration amount per resource update.
-
-        The value is read from ``metadata["regeneration_rate"]`` when present.
-        Missing values default to ``0.0``.
+        for key in ("capacity", "max_amount"):
+            if key in self.metadata and self.metadata[key] is not None:
+                return self._normalize_non_negative_float(
+                    self.metadata[key],
+                    f"metadata['{key}']",
+                )
 
-        Returns
-        -------
-        float
-            Non-negative finite regeneration amount.
-        """
-        rate = self._read_optional_metadata_float("regeneration_rate")
-        return 0.0 if rate is None else rate
+        return None
 
     @property
     def is_empty(self) -> bool:
-        """
-        Return whether this resource has no available quantity.
-
-        Returns
-        -------
-        bool
-            True if amount is zero, otherwise False.
-        """
+        """Return whether this resource has no available quantity."""
+
         return self.amount <= 0.0
 
     def regenerate(
@@ -289,31 +193,8 @@ class Resource:
         capacity: float | None = None,
         metadata: Mapping[str, Any] | None = None,
     ) -> ResourceOperationResult:
-        """
-        Increase the resource amount.
-
-        If ``amount`` is omitted, the method uses ``metadata["regeneration_rate"]``
-        when available, otherwise ``0.0``.
-
-        If ``capacity`` is omitted, the method uses ``metadata["capacity"]`` when
-        available. If no capacity exists, the resource may grow without an upper
-        bound.
-
-        Parameters
-        ----------
-        amount:
-            Non-negative amount to regenerate. Defaults to the configured
-            regeneration rate.
-        capacity:
-            Optional non-negative maximum resource amount for this operation.
-        metadata:
-            Additional metadata attached to the operation result.
-
-        Returns
-        -------
-        ResourceOperationResult
-            Structured result of the regeneration operation.
-        """
+        """Increase the resource amount."""
+
         requested_amount = (
             self.regeneration_rate
             if amount is None
@@ -376,29 +257,8 @@ class Resource:
         allow_partial: bool = True,
         metadata: Mapping[str, Any] | None = None,
     ) -> ResourceOperationResult:
-        """
-        Decrease the resource amount.
-
-        Parameters
-        ----------
-        amount:
-            Non-negative amount requested for depletion.
-        allow_partial:
-            Whether to allow depleting the remaining available amount when the
-            requested amount exceeds the current amount.
-        metadata:
-            Additional metadata attached to the operation result.
-
-        Returns
-        -------
-        ResourceOperationResult
-            Structured result of the depletion operation.
-
-        Raises
-        ------
-        TypeError
-            If ``allow_partial`` is not a boolean.
-        """
+        """Decrease the resource amount."""
+
         requested_amount = self._normalize_non_negative_float(amount, "amount")
 
         if not isinstance(allow_partial, bool):
@@ -458,26 +318,8 @@ class Resource:
         *,
         metadata: Mapping[str, Any] | None = None,
     ) -> ResourceOperationResult:
-        """
-        Set the resource amount directly.
-
-        This method is useful for world events, scripted interventions, tests,
-        and world factory initialization corrections. Behaviors should usually
-        prefer ``deplete()`` or ``regenerate()`` so operation semantics remain
-        explicit.
-
-        Parameters
-        ----------
-        amount:
-            New non-negative finite resource amount.
-        metadata:
-            Additional metadata attached to the operation result.
-
-        Returns
-        -------
-        ResourceOperationResult
-            Structured result of the set operation.
-        """
+        """Set the resource amount directly."""
+
         normalized_amount = self._normalize_non_negative_float(amount, "amount")
         previous_amount = self.amount
         self.amount = normalized_amount
@@ -494,40 +336,13 @@ class Resource:
         )
 
     def set_position(self, position: PositionInput) -> None:
-        """
-        Set the resource position.
-
-        Parameters
-        ----------
-        position:
-            New numeric position vector.
-
-        Raises
-        ------
-        ValueError
-            If the position is invalid.
-        """
+        """Set the resource position."""
+
         self.position = self._normalize_position(position)
 
     def distance_to(self, position: PositionInput) -> float:
-        """
-        Compute Euclidean distance from this resource to a position.
-
-        Parameters
-        ----------
-        position:
-            Numeric position vector.
-
-        Returns
-        -------
-        float
-            Euclidean distance.
-
-        Raises
-        ------
-        ValueError
-            If dimensionality does not match.
-        """
+        """Compute Euclidean distance from this resource to a position."""
+
         other_position = self._normalize_position(position)
 
         if self.position.shape != other_position.shape:
@@ -540,37 +355,35 @@ class Resource:
         return float(np.linalg.norm(self.position - other_position))
 
     def snapshot(self) -> dict[str, Any]:
-        """
-        Return a JSON-friendly snapshot of this resource.
-
-        Returns
-        -------
-        dict[str, Any]
-            Serializable resource snapshot.
-        """
+        """Return a JSON-friendly snapshot of this resource."""
+
         return {
             "id": self.id,
             "type": self.type,
             "amount": self.amount,
             "position": self.position.tolist(),
+            "regeneration_rate": self.regeneration_rate,
+            "max_amount": self.max_amount,
             "metadata": deepcopy(self.metadata),
         }
 
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-friendly dictionary representation."""
+
+        return self.snapshot()
+
     def copy(self) -> Resource:
-        """
-        Return a deep copy of this resource.
-
-        Returns
-        -------
-        Resource
-            Independent copy of this resource.
-        """
+        """Return a deep copy of this resource."""
+
         return Resource(
             id=self.id,
             type=self.type,
             amount=self.amount,
             position=self.position.copy(),
             metadata=deepcopy(self.metadata),
+            regeneration_rate=self.regeneration_rate,
+            max_amount=self.max_amount,
+            dsl_spec=self.dsl_spec,
         )
 
     def _operation_result(
@@ -585,33 +398,8 @@ class Resource:
         message: str,
         metadata: Mapping[str, Any] | None,
     ) -> ResourceOperationResult:
-        """
-        Build a normalized resource operation result.
-
-        Parameters
-        ----------
-        operation:
-            Operation name.
-        requested_amount:
-            Requested non-negative amount.
-        previous_amount:
-            Amount before the operation.
-        new_amount:
-            Amount after the operation.
-        success:
-            Whether the operation succeeded.
-        partial:
-            Whether less than the requested amount was applied.
-        message:
-            Human-readable operation summary.
-        metadata:
-            Additional result metadata.
-
-        Returns
-        -------
-        ResourceOperationResult
-            Structured operation result.
-        """
+        """Build a normalized resource operation result."""
+
         if metadata is not None and not isinstance(metadata, Mapping):
             raise TypeError("metadata must be a mapping when provided.")
 
@@ -630,77 +418,50 @@ class Resource:
         )
 
     def _resolve_capacity(self, capacity: float | None) -> float | None:
-        """
-        Resolve operation-specific or metadata-defined capacity.
-
-        Parameters
-        ----------
-        capacity:
-            Explicit capacity override.
-
-        Returns
-        -------
-        float | None
-            Non-negative finite capacity, or None.
-        """
+        """Resolve operation-specific or resource-defined capacity."""
+
         if capacity is not None:
             return self._normalize_non_negative_float(capacity, "capacity")
 
         return self.capacity
 
-    def _read_optional_metadata_float(self, key: str) -> float | None:
-        """
-        Read an optional non-negative float from resource metadata.
-
-        Parameters
-        ----------
-        key:
-            Metadata key.
-
-        Returns
-        -------
-        float | None
-            Normalized non-negative float, or None.
-
-        Raises
-        ------
-        TypeError
-            If key is invalid.
-        ValueError
-            If the metadata value is not a finite non-negative number.
-        """
-        if not isinstance(key, str) or not key:
-            raise TypeError("metadata key must be a non-empty string.")
-
-        if key not in self.metadata or self.metadata[key] is None:
-            return None
-
-        return self._normalize_non_negative_float(
-            self.metadata[key],
-            f"metadata['{key}']",
-        )
+    def _resolve_regeneration_rate(self, value: Any) -> float:
+        """Resolve regeneration rate from explicit value or metadata."""
+
+        if value is not None and float(value) != 0.0:
+            return self._normalize_non_negative_float(value, "regeneration_rate")
+
+        if "regeneration_rate" in self.metadata and self.metadata["regeneration_rate"] is not None:
+            return self._normalize_non_negative_float(
+                self.metadata["regeneration_rate"],
+                "metadata['regeneration_rate']",
+            )
+
+        return self._normalize_non_negative_float(value or 0.0, "regeneration_rate")
+
+    def _resolve_max_amount(self, value: Any) -> float | None:
+        """Resolve max amount from explicit value or metadata aliases."""
+
+        if value is not None:
+            return self._normalize_non_negative_float(value, "max_amount")
+
+        for key in ("max_amount", "capacity"):
+            if key in self.metadata and self.metadata[key] is not None:
+                return self._normalize_non_negative_float(
+                    self.metadata[key],
+                    f"metadata['{key}']",
+                )
+
+        return None
 
     @staticmethod
     def _normalize_position(position: PositionInput) -> NDArray[np.float64]:
-        """
-        Normalize a position input into a one-dimensional numpy float array.
-
-        Parameters
-        ----------
-        position:
-            Sequence or numpy array representing a position.
-
-        Returns
-        -------
-        NDArray[np.float64]
-            Normalized position vector.
-
-        Raises
-        ------
-        ValueError
-            If the position is empty, non-finite, or not one-dimensional.
-        """
-        normalized = np.asarray(position, dtype=np.float64)
+        """Normalize a position input into a one-dimensional numpy float array."""
+
+        if position is None:
+            return np.zeros(2, dtype=np.float64)
+
+        normalized = np.asarray(position, dtype=np.float64).reshape(-1)
 
         if normalized.ndim != 1:
             raise ValueError("Resource.position must be a one-dimensional vector.")
@@ -711,32 +472,12 @@ class Resource:
         if not np.all(np.isfinite(normalized)):
             raise ValueError("Resource.position must contain only finite values.")
 
-        return normalized
+        return normalized.astype(np.float64, copy=True)
 
     @staticmethod
     def _normalize_non_negative_float(value: Any, label: str) -> float:
-        """
-        Normalize a value into a finite non-negative float.
-
-        Parameters
-        ----------
-        value:
-            Candidate numeric value.
-        label:
-            Human-readable value label used in error messages.
-
-        Returns
-        -------
-        float
-            Normalized non-negative float.
-
-        Raises
-        ------
-        TypeError
-            If value is not numeric.
-        ValueError
-            If value is negative or non-finite.
-        """
+        """Normalize a value into a finite non-negative float."""
+
         if isinstance(value, bool) or not isinstance(value, Real):
             raise TypeError(f"{label} must be a real number.")
 
@@ -752,21 +493,8 @@ class Resource:
 
     @staticmethod
     def _validate_string_keys(mapping: Mapping[str, Any], label: str) -> None:
-        """
-        Validate that all mapping keys are strings.
-
-        Parameters
-        ----------
-        mapping:
-            Mapping to validate.
-        label:
-            Human-readable mapping label used in error messages.
-
-        Raises
-        ------
-        TypeError
-            If any mapping key is not a string.
-        """
+        """Validate that all mapping keys are strings."""
+
         for key in mapping:
             if not isinstance(key, str):
                 raise TypeError(f"Resource.{label} keys must be strings.")