simz 0.1.0__tar.gz

simz-0.1.0/.gitignore

@@ -0,0 +1,175 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc
+dist/

simz-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: simz
+Version: 0.1.0
+Summary: A lightweight ECS-based simulation engine
+Project-URL: Repository, https://github.com/danield137/projectzero
+Author-email: Daniel Dror <danield137@gmail.com>
+License: Copyright (c) [Daniel Dror;danield137@gmail.com]
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for non-commercial, non-profit purposes only.
+        Commercial use, including but not limited to use by for-profit organizations or individuals for business purposes, is not permitted without obtaining a separate commercial license from the copyright holder.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY...
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment :: Simulation
+Requires-Python: >=3.10
+Requires-Dist: numpy>=2.2.4
+Requires-Dist: termcolor>=2.5.0
+Description-Content-Type: text/markdown
+
+# sim
+
+A lightweight ECS (Entity Component System) based simulation engine.
+
+## Features
+
+- **ECS Core** — Entity-Component-System architecture with generational IDs and efficient queries
+- **AI Module** — Brain/context/memory abstractions for agent behavior
+- **Common Utilities** — Math helpers, logging, data structures (generational containers, running stats)
+- **Configurable** — Runtime configuration for simulation parameters
+
+## Installation
+
+```bash
+pip install simz
+```
+
+## Quick Start
+
+```python
+from sim.ecs.core import ECS
+from sim.ecs.component import Component
+from sim.ecs.system import System
+
+# Define components
+class Position(Component):
+    def __init__(self, x: float, y: float):
+        self.x = x
+        self.y = y
+
+# Create ECS and entities
+ecs = ECS()
+ecs.create_entity("player", [Position(0, 0)])
+```
+
+## License
+
+Non-commercial use only. See [LICENSE](LICENSE) for details.

simz-0.1.0/README.md

@@ -0,0 +1,38 @@
+# sim
+
+A lightweight ECS (Entity Component System) based simulation engine.
+
+## Features
+
+- **ECS Core** — Entity-Component-System architecture with generational IDs and efficient queries
+- **AI Module** — Brain/context/memory abstractions for agent behavior
+- **Common Utilities** — Math helpers, logging, data structures (generational containers, running stats)
+- **Configurable** — Runtime configuration for simulation parameters
+
+## Installation
+
+```bash
+pip install simz
+```
+
+## Quick Start
+
+```python
+from sim.ecs.core import ECS
+from sim.ecs.component import Component
+from sim.ecs.system import System
+
+# Define components
+class Position(Component):
+    def __init__(self, x: float, y: float):
+        self.x = x
+        self.y = y
+
+# Create ECS and entities
+ecs = ECS()
+ecs.create_entity("player", [Position(0, 0)])
+```
+
+## License
+
+Non-commercial use only. See [LICENSE](LICENSE) for details.

simz-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "simz"
+version = "0.1.0"
+description = "A lightweight ECS-based simulation engine"
+authors = [
+    {name = "Daniel Dror", email = "danield137@gmail.com"},
+]
+dependencies = [
+    "numpy>=2.2.4",
+    "termcolor>=2.5.0",
+]
+requires-python = ">=3.10"
+readme = "README.md"
+license = {text = """
+Copyright (c) [Daniel Dror;danield137@gmail.com]
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for non-commercial, non-profit purposes only.
+Commercial use, including but not limited to use by for-profit organizations or individuals for business purposes, is not permitted without obtaining a separate commercial license from the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY...
+"""}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Games/Entertainment :: Simulation",
+]
+
+[project.urls]
+Repository = "https://github.com/danield137/projectzero"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sim"]

simz-0.1.0/src/sim/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__

simz-0.1.0/src/sim/ai/brain.py

@@ -0,0 +1,29 @@
+import abc
+import enum
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from sim.ai import ActionStep
+from sim.ai.context import BrainContext
+from sim.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

simz-0.1.0/src/sim/ai/context.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+from sim.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

simz-0.1.0/src/sim/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 sim.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)