tigen 0.2.1__py3-none-any.whl

tigen/ai/__init__.py

@@ -0,0 +1,10 @@
+import abc
+import functools
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ActionStep(abc.ABC):
+    @functools.cached_property
+    def name(self):
+        return self.__class__.__qualname__

tigen/ai/brain.py

@@ -0,0 +1,29 @@
+import abc
+import enum
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from tigen.ai import ActionStep
+from tigen.ai.context import BrainContext
+from tigen.ai.memory import Memory
+
+TGoal = TypeVar("TGoal", bound=enum.Enum)
+
+
+@dataclass(slots=True)
+class GoalSelector(abc.ABC, Generic[TGoal]):
+    @abc.abstractmethod
+    def select_goal(self, ctx: BrainContext) -> TGoal: ...
+
+
+@dataclass(slots=True)
+class Planner(abc.ABC, Generic[TGoal]):
+    @abc.abstractmethod
+    def make_plan(self, ctx: BrainContext, goal: str) -> list[ActionStep]: ...
+
+
+@dataclass(slots=True)
+class Brain(Generic[TGoal]):
+    goal_selector: GoalSelector[TGoal]
+    planner: Planner[TGoal]
+    memory: Memory

tigen/ai/context.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+from tigen.ai.memory import Memory, MemoryData
+
+
+@dataclass(slots=True, frozen=True)
+class BrainContext:
+    """
+    Context for the AI brain, providing necessary data for decision-making.
+    All "sensory" data is normalized to a range of 0.0 to 1.0.
+    This context is used by the AI engine to make decisions and plans.
+    """
+
+    simulation_time: int
+    eid: int
+    etype: str
+    memory_data: MemoryData
+    memory_engine: Memory

tigen/ai/memory.py

@@ -0,0 +1,230 @@
+import abc
+import enum
+import heapq
+import math
+import random
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+from typing import Any
+
+from tigen.common.math import Vector, cosine
+
+
+@dataclass(slots=True)
+class MemoryFact:
+    """
+    *uid* : unique and stable identifier
+    *t0*  : tick when the fact was first encoded
+    *value*: **opaque payload**  (Memory never inspects this)
+    *ctx* : optional context vector for similarity search
+    """
+
+    uid: str
+    tag: str
+    t0: int
+    value: Any
+    ctx: Vector | None = field(init=False, default=None)
+
+
+class MemoryType(str, enum.Enum):
+    PERFECT = "PERFECT"
+    IMPERFECT = "IMPERFECT"
+
+
+@dataclass(slots=True)
+class MemoryData:
+    ltm: dict[str, MemoryFact] = field(default_factory=dict[str, MemoryFact])
+    stm: list[MemoryFact] = field(default_factory=list[MemoryFact])
+    strength: dict[str, float] = field(default_factory=dict[str, float])
+    cue: dict[str, set[str]] = field(default_factory=dict[str, set[str]])
+    rng_state: int = field(default=0xDEADBEEF)  # splitmix state
+
+    def all(self) -> Iterator[MemoryFact]:
+        if self.stm:
+            yield from self.stm
+        if self.ltm.values():
+            yield from self.ltm.values()
+
+    def exists(self, uid: str) -> bool:
+        """Check if a fact with the given UID exists in either STM or LTM."""
+        return uid in self.ltm or any(fact.uid == uid for fact in self.stm)
+
+
+@dataclass(slots=True, frozen=True)
+class MemQuery:
+    fact_type: type[MemoryFact] | None = None
+    uid: str | None = None
+    where: Callable[[MemoryFact], bool] | None = None
+    ctx: Vector | None = None  # current context for activation boost
+    k: int = 5
+
+    @staticmethod
+    def tag_eq(tag: str) -> "MemQuery":
+        """Create a query for a specific tag."""
+        return MemQuery(where=lambda f: f.tag == tag)
+
+
+@dataclass(slots=True)
+class Memory(abc.ABC):
+    @abc.abstractmethod
+    def remember(self, md: MemoryData, fact: MemoryFact) -> None: ...
+
+    @abc.abstractmethod
+    def recall(self, md: MemoryData, q: MemQuery, now: int) -> list[MemoryFact]: ...
+
+    @abc.abstractmethod
+    def tick(self, md: MemoryData, dt: float, now: int) -> None: ...
+
+    @abc.abstractmethod
+    def forget(self, md: MemoryData, uid: str) -> None: ...
+
+
+# ———– PerfectMemory ————————————————————————————————————————
+class PerfectMemory(Memory):
+    def remember(self, md: MemoryData, fact: MemoryFact) -> None:
+        md.ltm[fact.uid] = fact
+
+    def recall(self, md: MemoryData, q: MemQuery, now: int) -> list[MemoryFact]:
+        cand = (fact for facts in (md.ltm.values(), md.stm) for fact in facts)
+        if q.where:
+            cand = filter(q.where, cand)
+        return list(cand)[: q.k]
+
+    def forget(self, md: MemoryData, uid: str) -> None:
+        """Forget a fact by UID."""
+        md.ltm.pop(uid, None)
+        md.stm = [f for f in md.stm if f.uid != uid]
+        for s in md.cue.values():
+            s.discard(uid)
+
+    def tick(self, md: MemoryData, dt: float, now: int) -> None:
+        # no‐op for perfect memory
+        return
+
+
+# ———– ImperfectMemory knobs & logic ——————————————————————————
+class ImperfectMemory(Memory):
+    ENCODE_NOISE_P = 0.10
+    STM_SPAN_TICKS = 300
+    INTERFERENCE_P = 0.40
+    DECAY_HALF_LIFE = 30_000
+    RETRIEVAL_NOISE_SD = 0.25
+
+    def remember(self, md: MemoryData, fact: MemoryFact) -> None:
+        rng = random.Random(md.rng_state)
+        if rng.random() < self.ENCODE_NOISE_P:
+            # fact = {**fact, "noisy": True}    # your distortion
+            ...
+        md.stm.append(fact)
+        md.rng_state = rng.getrandbits(64)
+
+    def tick(self, md: MemoryData, dt: float, now: int) -> None:
+        # STM → LTM + interference
+        while md.stm and now - md.stm[0].t0 >= self.STM_SPAN_TICKS:
+            f = md.stm.pop(0)
+            bucket = f.uid.split("-", 1)[0]
+            md.cue.setdefault(bucket, set()).add(f.uid)
+            md.ltm[f.uid] = f
+            md.strength[f.uid] = md.strength.get(f.uid, 0.01) + 1.0
+
+        # decay
+        k = 0.5 ** (dt / self.DECAY_HALF_LIFE)
+        dead: list[str] = []
+        for uid, s in md.strength.items():
+            s *= k
+            if s < 0.02:
+                dead.append(uid)
+            md.strength[uid] = s
+        for uid in dead:
+            md.ltm.pop(uid, None)
+            for s in md.cue.values():
+                s.discard(uid)
+
+    def recall(self, md: MemoryData, q: MemQuery, now: int) -> list[MemoryFact]:
+        rng = random.Random(md.rng_state)
+        result_heap: list[
+            tuple[float, MemoryFact]
+        ] = []  # Will store (-score, fact) pairs for min-heap behavior with max scores
+
+        # Process candidates from both LTM and STM without materializing full lists
+        def process_fact(f: MemoryFact):
+            if q.where and not q.where(f):
+                return
+
+            base = md.strength.get(f.uid, 0.01)
+            act = math.log(base / (now - f.t0 or 1e-9))
+            sim = 0.0
+            if q.ctx and f.ctx is not None:
+                sim = cosine(q.ctx, f.ctx)
+            noise = rng.gauss(0.0, self.RETRIEVAL_NOISE_SD)
+            score = act + sim + noise
+
+            # Use negative score for min-heap to function as max-heap
+            if len(result_heap) < q.k:
+                heapq.heappush(result_heap, (-score, f))
+            elif -score > result_heap[0][0]:
+                heapq.heappushpop(result_heap, (-score, f))
+
+        # Process long-term memory
+        for f in md.ltm.values():
+            process_fact(f)
+
+        # Process short-term memory
+        for f in md.stm:
+            process_fact(f)
+
+        md.rng_state = rng.getrandbits(64)
+
+        # Extract results in descending order of score
+        results = [f for _, f in sorted(result_heap, key=lambda x: x[0])]
+        return results
+
+    def forget(self, md: MemoryData, uid: str) -> None:
+        """Forget a fact by UID."""
+        md.ltm.pop(uid, None)
+        md.stm = [f for f in md.stm if f.uid != uid]
+        for s in md.cue.values():
+            s.discard(uid)
+        md.strength.pop(uid, None)
+
+
+# shared singleton instances
+_perfect_memory = PerfectMemory()
+_imperfect_memory = ImperfectMemory()
+
+
+def get_memory(memory_type: MemoryType) -> Memory:
+    if memory_type == MemoryType.PERFECT:
+        return _perfect_memory
+    return _imperfect_memory
+
+
+# ———– façade dispatchers ——————————————————————————————————————
+
+
+class MemWriter:
+    @staticmethod
+    def write(md: MemoryData, memory_type: str, fact: MemoryFact) -> None:
+        if memory_type == MemoryType.PERFECT:
+            _perfect_memory.remember(md, fact)
+        elif memory_type == MemoryType.IMPERFECT:
+            _imperfect_memory.remember(md, fact)
+
+
+class MemReader:
+    @staticmethod
+    def read(md: MemoryData, memory_type: str, q: MemQuery, now: int) -> list[MemoryFact]:
+        if memory_type == MemoryType.PERFECT:
+            return _perfect_memory.recall(md, q, now)
+        if memory_type == MemoryType.IMPERFECT:
+            return _imperfect_memory.recall(md, q, now)
+        return []  # empty list if memory type is unknown
+
+
+class MemHousekeeping:
+    @staticmethod
+    def tick(md: MemoryData, memory_type: str, dt: float, now: int) -> None:
+        if memory_type == MemoryType.PERFECT:
+            _perfect_memory.tick(md, dt, now)
+        else:
+            _imperfect_memory.tick(md, dt, now)

tigen/common/ds/generational.py

@@ -0,0 +1,266 @@
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import (
+    Generic,
+    TypeVar,
+    cast,
+)
+
+# --- Generic type declarations ---
+T = TypeVar("T")
+K = TypeVar("K")
+V = TypeVar("V")
+
+# A handle is a tuple: (index, generation)
+Handle = tuple[int, int]
+
+
+class IsolationLevel(Enum):
+    """
+    Enum controlling iteration mode.
+    NONE:       Live iteration (all modifications are visible).
+    ALLOW_DELETIONS: Fixed-range iteration—new insertions are ignored, deletions show as gaps.
+    FULL:       "Immutable" iteration: snapshot range is locked; new insertions are ignored;
+                    deletions in indices beyond the current iterator position are deferred.
+    """
+
+    NONE = 1
+    ALLOW_DELETIONS = 2
+    FULL = 3
+
+
+@dataclass(slots=True)
+class _ImmutableIterationContext(Generic[T]):
+    """
+    Per-iterator context for FULL mode. Records:
+      - snapshot_length: the container length at iterator creation.
+      - current_position: updated during iteration (the last index yielded).
+      - deferred: a dict mapping slot indices (within the snapshot) to the value
+                  that was present at the time of deletion.
+    """
+
+    snapshot_length: int
+    current_position: int = 0
+    deferred: dict[int, T] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class GenerationalContainer(Generic[T]):
+    """
+    A generic container that stores items in a list with per-slot generation counters.
+    Insertions reuse free slots (bumping the generation), and deletions mark a slot as None.
+
+    The smart_iter() method returns an iterator that obeys one of the three modes
+    as controlled by IsolationLevel.
+
+    For FULL mode, each iterator creates its own _ImmutableIterationContext,
+    and the container keeps a list of active contexts. In remove(), if a deletion occurs
+    at an index that is greater than the context’s current_position (and within its snapshot),
+    then the current (old) value is recorded in that context’s deferred buffer.
+    """
+
+    _items: list[T | None] = field(default_factory=list)
+    _generations: list[int] = field(default_factory=list)
+    _free_indices: list[int] = field(default_factory=list)
+    _immutable_contexts: list[_ImmutableIterationContext[T]] = field(default_factory=list)
+
+    def insert(self, item: T) -> Handle:
+        if self._free_indices:
+            idx = self._free_indices.pop()
+            self._items[idx] = item
+            self._generations[idx] += 1  # Invalidate any old handle.
+        else:
+            idx = len(self._items)
+            self._items.append(item)
+            self._generations.append(0)
+
+        return (idx, self._generations[idx])
+
+    def remove(self, handle: Handle) -> None:
+        idx, gen = handle
+        if idx >= len(self._items) or self._generations[idx] != gen:
+            raise ValueError("Invalid or stale handle")
+        if self._items[idx] is None:
+            raise ValueError("Item already deleted")
+        # For each active immutable context, only record deletion if the slot is within the snapshot
+        # and if the deletion index is beyond the current iteration position.
+        for ctx in self._immutable_contexts:
+            if ctx.current_position < idx < ctx.snapshot_length:
+                if self._items[idx] is not None and idx not in ctx.deferred:
+                    ctx.deferred[idx] = cast(T, self._items[idx])
+        self._items[idx] = None
+        self._free_indices.append(idx)
+
+    def get(self, handle: Handle) -> T | None:
+        idx, gen = handle
+        if idx >= len(self._items) or self._generations[idx] != gen:
+            return None
+        return self._items[idx]
+
+    def smart_iter(
+        self,
+        allowed_mutation: IsolationLevel = IsolationLevel.NONE,
+        skip_empty: bool = True,
+    ) -> Iterator[T | None]:
+        if allowed_mutation == IsolationLevel.NONE:
+            # Live iteration: yield items from the current list.
+            for item in self._items:
+                if skip_empty and item is None:
+                    continue
+                yield item
+        elif allowed_mutation == IsolationLevel.ALLOW_DELETIONS:
+            # Fixed-range iteration: snapshot the length and free-slot set.
+            snapshot_length = len(self._items)
+            frozen_free = {i for i, item in enumerate(self._items) if item is None}
+            for i in range(snapshot_length):
+                if i in frozen_free:
+                    continue
+                item = self._items[i]
+                if skip_empty and item is None:
+                    continue
+                yield item
+        elif allowed_mutation == IsolationLevel.FULL:
+            # Create a new immutable iteration context.
+            snapshot_length = len(self._items)
+            local_ctx = _ImmutableIterationContext[T](snapshot_length)
+            self._immutable_contexts.append(local_ctx)
+            try:
+                for i in range(snapshot_length):
+                    local_ctx.current_position = i  # Update current position.
+                    # If the live slot is None, try to fetch deferred value.
+                    item = self._items[i]
+                    if item is None and i in local_ctx.deferred:
+                        item = local_ctx.deferred[i]
+                    if skip_empty and item is None:
+                        continue
+                    yield item
+            finally:
+                if local_ctx in self._immutable_contexts:
+                    self._immutable_contexts.remove(local_ctx)
+        else:
+            raise ValueError("Unknown mutation allowance mode")
+
+    def __iter__(self) -> Iterator[T | None]:
+        # Default __iter__ uses NONE (live iteration).
+        return self.smart_iter(allowed_mutation=IsolationLevel.NONE)
+
+    def __len__(self) -> int:
+        # Return the number of used slots.
+        return len(self._items) - len(self._free_indices)
+
+
+@dataclass(slots=True, frozen=True)
+class Entry(Generic[K, V]):
+    key: K
+    value: V
+
+
+class GenerationalDict(Generic[K, V]):
+    __slots__ = ("_container", "_key_to_handle")
+    _container: GenerationalContainer[Entry[K, V]]
+    _key_to_handle: dict[K, Handle]
+    """
+    A dictionary that uses a GenerationalContainer to store Entry(key, value) objects.
+    It maintains a mapping from external keys to handles (for O(1) lookups). The smart_iter()
+    method delegates to the container`s smart_iter() to yield (key, value) pairs.
+    Default iteration value_over the dict yields keys using NONE mode.
+    """
+
+    def __init__(self) -> None:
+        self._container: GenerationalContainer[Entry[K, V]] = GenerationalContainer()
+        self._key_to_handle: dict[K, Handle] = {}
+
+    def __setitem__(self, key: K, value: V) -> None:
+        # To maintain correct generation, we remove the old entry if it exists, and then add the new one.
+        if key in self._key_to_handle:
+            existing = self._container.get(self._key_to_handle[key])
+            if existing is not None and value == existing:
+                # optimization: if the value is the same, do nothing.
+                return
+            self.delete(key)  # Remove old entry if it exists.
+        self.add(key, value)
+
+    def __getitem__(self, key: K) -> V:
+        try:
+            idx, gen = self._key_to_handle[key]  # O(1) hash-lookup
+            if self._container._generations[idx] == gen:  # generation still valid
+                entry = self._container._items[idx]
+                if entry is not None:  # slot not deleted
+                    return entry.value  # ➊ no extra calls
+        except (KeyError, IndexError):
+            pass  # fall through to slow path
+        # slow path keeps old invariants
+        raise KeyError(key)
+
+    def add(self, key: K, value: V) -> None:
+        entry = Entry(key, value)
+        handle = self._container.insert(entry)
+        self._key_to_handle[key] = handle
+
+    def delete(self, key: K) -> None:
+        handle = self._key_to_handle.pop(key, None)
+        if handle is not None:
+            self._container.remove(handle)
+
+    def get(self, key: K) -> V | None:
+        try:
+            return self[key]
+        except KeyError:
+            return None
+
+    def items(
+        self,
+        allowed_mutation: IsolationLevel = IsolationLevel.NONE,
+        skip_empty: bool = True,
+    ) -> Iterator[tuple[K, V]]:
+        for entry in self._container.smart_iter(allowed_mutation=allowed_mutation, skip_empty=skip_empty):
+            if entry is not None:
+                yield (entry.key, entry.value)
+
+    def keys(
+        self,
+        allowed_mutation: IsolationLevel = IsolationLevel.NONE,
+        skip_empty: bool = True,
+    ) -> Iterator[K]:
+        for entry in self.items(allowed_mutation=allowed_mutation, skip_empty=skip_empty):
+            yield entry[0]
+
+    def values(
+        self,
+        allowed_mutation: IsolationLevel = IsolationLevel.NONE,
+        skip_empty: bool = True,
+    ) -> Iterator[V]:
+        for entry in self.items(allowed_mutation=allowed_mutation, skip_empty=skip_empty):
+            yield entry[1]
+
+    def __iter__(self) -> Iterator[K]:
+        for key, _ in self.items(allowed_mutation=IsolationLevel.NONE, skip_empty=True):
+            yield key
+
+    def __len__(self) -> int:
+        return len(self._key_to_handle)
+
+    def __contains__(self, key: K) -> bool:
+        return key in self._key_to_handle
+
+
+class GenerationalDefaultDict(GenerationalDict[K, V]):
+    __slots__ = ("default_factory",)
+    """
+    A dictionary based on GenerationalDict that supports a default factory.
+    When a key is missing, the default_factory is called to provide a default value,
+    the value is inserted into the dictionary, and then returned.
+    """
+
+    def __init__(self, default_factory: Callable[[], V]) -> None:
+        super().__init__()
+        self.default_factory = default_factory
+
+    def __getitem__(self, key: K) -> V:
+        if key in self._key_to_handle:
+            return super().__getitem__(key)
+
+        default_value = self.default_factory()
+        self.__setitem__(key, default_value)
+        return default_value

tigen/common/ds/running_stats.py

@@ -0,0 +1,68 @@
+"""
+Utilities for maintaining online statistics with O(1) memory usage.
+"""
+
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from tigen.common.math import MovingAverageFunction, moving_average
+
+
+@dataclass(slots=True)
+class RunningMean:
+    """Maintains a running mean using constant memory."""
+
+    avg: MovingAverageFunction = field(default_factory=moving_average)
+
+    def add(self, value: float) -> None:
+        """Add a value to the running mean."""
+        self.avg(value)
+
+    def value(self) -> float:
+        """Get the current mean without modifying it."""
+        return self.avg.current()
+
+    def reset(self) -> None:
+        """Reset the mean calculation."""
+        self.avg.reset()
+
+
+@dataclass(slots=True)
+class RunningDistribution:
+    """
+    Incrementally maintains a probability distribution over categorical values.
+    Supports O(1) updates and probability queries.
+    """
+
+    counts: dict[str, int] = field(default_factory=lambda: defaultdict(int))
+    total: int = 0
+
+    def add(self, key: str, n: int = 1) -> None:
+        """
+        Record n occurrences of key.
+
+        :param key: Category to increment
+        :param n: Count to add (default: 1)
+        """
+        self.counts[key] += n
+        self.total += n
+
+    def prob(self, key: str) -> float:
+        """
+        Get P(key) = count(key) / total.
+        Returns 0.0 if no samples recorded.
+
+        :param key: Category to query
+        :return: Probability of this category
+        """
+        return self.counts[key] / self.total if self.total else 0.0
+
+    def keys(self) -> Iterable[str]:
+        """Get recorded categories."""
+        return self.counts.keys()
+
+    def reset(self) -> None:
+        """Clear all counts."""
+        self.counts.clear()
+        self.total = 0