Source code for simvx.core.ai.sensor

"""Sensors: turn world / context state into percepts on a Blackboard.

A `Sensor` reads the current `AIContext` (the agent, the world, the
blackboard) and writes what it perceives back onto the blackboard. A
`Perception` runs a list of sensors each tick. Both classical and LLM brains
share this perception layer, so swapping deciders never touches sensing.
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from .brain import AIContext




class Sensor(ABC):
    """Reads the context and writes percepts to ``ctx.blackboard``."""



    @abstractmethod
    def sense(self, ctx: AIContext) -> None: ...






class Perception:
    """An ordered collection of sensors run together each tick."""

    def __init__(self, sensors: list[Sensor] | tuple[Sensor, ...] = ()) -> None:
        self.sensors: list[Sensor] = list(sensors)



    def add(self, sensor: Sensor) -> Sensor:
        self.sensors.append(sensor)
        return sensor




    def sense(self, ctx: AIContext) -> None:
        for sensor in self.sensors:
            sensor.sense(ctx)