neuralt-work 0.1.0__tar.gz

neuralt_work-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aquilesinho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neuralt_work-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: neuralt-work
+Version: 0.1.0
+Summary: A lightweight neural-network learning library for Python.
+Author: Aquilesinho
+License: MIT License
+        
+        Copyright (c) 2026 Aquilesinho
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Dynamic: license-file
+
+# NeuraltWork
+
+NeuraltWork is a Python neural-network learning library.
+
+## Installation
+
+```bash
+pip install neuralt-work
+```
+
+## Import
+
+```python
+import neuraltwork as nn
+```
+
+## Status
+
+This project is in early development. Its API and behavior may change between releases.
+
+## License
+
+This project is distributed under the MIT License. See [LICENSE](LICENSE).

neuralt_work-0.1.0/README.md

@@ -0,0 +1,23 @@
+# NeuraltWork
+
+NeuraltWork is a Python neural-network learning library.
+
+## Installation
+
+```bash
+pip install neuralt-work
+```
+
+## Import
+
+```python
+import neuraltwork as nn
+```
+
+## Status
+
+This project is in early development. Its API and behavior may change between releases.
+
+## License
+
+This project is distributed under the MIT License. See [LICENSE](LICENSE).

neuralt_work-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neuralt-work"
+version = "0.1.0"
+description = "A lightweight neural-network learning library for Python."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Aquilesinho" }
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "numpy>=1.24"
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

neuralt_work-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

neuralt_work-0.1.0/src/neuralt_work.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: neuralt-work
+Version: 0.1.0
+Summary: A lightweight neural-network learning library for Python.
+Author: Aquilesinho
+License: MIT License
+        
+        Copyright (c) 2026 Aquilesinho
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Dynamic: license-file
+
+# NeuraltWork
+
+NeuraltWork is a Python neural-network learning library.
+
+## Installation
+
+```bash
+pip install neuralt-work
+```
+
+## Import
+
+```python
+import neuraltwork as nn
+```
+
+## Status
+
+This project is in early development. Its API and behavior may change between releases.
+
+## License
+
+This project is distributed under the MIT License. See [LICENSE](LICENSE).

neuralt_work-0.1.0/src/neuralt_work.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/neuralt_work.egg-info/PKG-INFO
+src/neuralt_work.egg-info/SOURCES.txt
+src/neuralt_work.egg-info/dependency_links.txt
+src/neuralt_work.egg-info/requires.txt
+src/neuralt_work.egg-info/top_level.txt
+src/neuraltwork/__init__.py
+src/neuraltwork/main.py

neuralt_work-0.1.0/src/neuralt_work.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

neuralt_work-0.1.0/src/neuralt_work.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy>=1.24

neuralt_work-0.1.0/src/neuralt_work.egg-info/top_level.txt

@@ -0,0 +1 @@
+neuraltwork

neuralt_work-0.1.0/src/neuraltwork/__init__.py

@@ -0,0 +1 @@
+from .main import *

neuralt_work-0.1.0/src/neuraltwork/main.py

@@ -0,0 +1,717 @@
+import os
+os.environ["OPENBLAS_NUM_THREADS"] = "1"
+os.environ["OMP_NUM_THREADS"] = "1"
+os.environ["MKL_NUM_THREADS"] = "1"
+import pickle
+import random
+import time
+from collections import deque
+import numpy as np
+
+
+ACAO_ESPERAR = 0
+ACAO_PRIMEIRA_FUNCAO = 1
+
+_ENTRADAS_BASE = 4
+_MAX_MEMORIA = 50000
+_LOTE = 32
+_FREQUENCIA_APRENDIZADO = 64
+_FREQUENCIA_DECISAO = 4
+
+
+class _RedeNeural:
+    def __init__(self, entradas=_ENTRADAS_BASE, ocultas1=64, ocultas2=64, saidas=2):
+        self.W1 = np.random.randn(entradas, ocultas1).astype(np.float32) * np.sqrt(2.0 / entradas)
+        self.b1 = np.zeros(ocultas1, dtype=np.float32)
+        self.W2 = np.random.randn(ocultas1, ocultas2).astype(np.float32) * np.sqrt(2.0 / ocultas1)
+        self.b2 = np.zeros(ocultas2, dtype=np.float32)
+        self.W3 = np.random.randn(ocultas2, saidas).astype(np.float32) * np.sqrt(2.0 / ocultas2)
+        self.b3 = np.zeros(saidas, dtype=np.float32)
+        self.m = [np.zeros_like(p) for p in self.parametros()]
+        self.v = [np.zeros_like(p) for p in self.parametros()]
+        self.passos_adam = 0
+
+    def parametros(self):
+        return [self.W1, self.b1, self.W2, self.b2, self.W3, self.b3]
+
+    def prever(self, estados):
+        estados = np.asarray(estados, dtype=np.float32)
+        a1 = np.maximum(0, estados @ self.W1 + self.b1)
+        a2 = np.maximum(0, a1 @ self.W2 + self.b2)
+        return a2 @ self.W3 + self.b3
+
+    def treinar(self, estados, acoes, alvos):
+        estados = np.asarray(estados, dtype=np.float32)
+        acoes = np.asarray(acoes, dtype=np.int64)
+        alvos = np.asarray(alvos, dtype=np.float32)
+
+        z1 = estados @ self.W1 + self.b1
+        a1 = np.maximum(0, z1)
+        z2 = a1 @ self.W2 + self.b2
+        a2 = np.maximum(0, z2)
+        saida = a2 @ self.W3 + self.b3
+
+        quantidade = len(estados)
+        delta3 = np.zeros_like(saida)
+        delta3[np.arange(quantidade), acoes] = (
+            2.0 * (saida[np.arange(quantidade), acoes] - alvos) / quantidade
+        )
+
+        grad_W3 = a2.T @ delta3
+        grad_b3 = np.sum(delta3, axis=0)
+        delta2 = (delta3 @ self.W3.T) * (z2 > 0)
+        grad_W2 = a1.T @ delta2
+        grad_b2 = np.sum(delta2, axis=0)
+        delta1 = (delta2 @ self.W2.T) * (z1 > 0)
+        grad_W1 = estados.T @ delta1
+        grad_b1 = np.sum(delta1, axis=0)
+
+        gradientes = [grad_W1, grad_b1, grad_W2, grad_b2, grad_W3, grad_b3]
+        self.passos_adam += 1
+        beta1 = 0.9
+        beta2 = 0.999
+        taxa = 0.0005
+        epsilon = 1e-8
+
+        for i, (parametro, gradiente) in enumerate(zip(self.parametros(), gradientes)):
+            self.m[i] = beta1 * self.m[i] + (1.0 - beta1) * gradiente
+            self.v[i] = beta2 * self.v[i] + (1.0 - beta2) * (gradiente ** 2)
+            m_corrigido = self.m[i] / (1.0 - beta1 ** self.passos_adam)
+            v_corrigido = self.v[i] / (1.0 - beta2 ** self.passos_adam)
+            parametro -= taxa * m_corrigido / (np.sqrt(v_corrigido) + epsilon)
+
+    def copiar_pesos(self, outra):
+        for destino, origem in zip(self.parametros(), outra.parametros()):
+            destino[:] = origem
+
+
+class _AgenteDQN:
+    def __init__(self, quantidade_acoes, caminho, entradas):
+        self.rede = _RedeNeural(entradas=entradas, saidas=quantidade_acoes)
+        self.rede_alvo = _RedeNeural(entradas=entradas, saidas=quantidade_acoes)
+        self.rede_alvo.copiar_pesos(self.rede)
+        self.memoria = deque(maxlen=_MAX_MEMORIA)
+        self.memoria_melhor = deque(maxlen=_MAX_MEMORIA)
+        self.experiencias_episodio = deque(maxlen=_MAX_MEMORIA)
+        self.gamma = 0.99
+        self.epsilon = 1.0
+        self.epsilon_minimo = 0.05
+        self.epsilon_decay = 0.9995
+        self.lote = _LOTE
+        self.passos = 0
+        self.caminho = caminho
+        self.carregar()
+
+    def escolher_acao(self, estado):
+        if random.random() < self.epsilon:
+            return random.randrange(self.rede.W3.shape[1])
+        return int(np.argmax(self.rede.prever([estado])[0]))
+
+    def guardar(self, estado, acao, recompensa, proximo, terminou):
+        experiencia = (
+            np.asarray(estado, dtype=np.float32),
+            int(acao),
+            float(recompensa),
+            np.asarray(proximo, dtype=np.float32),
+            bool(terminou)
+        )
+        self.memoria.append(experiencia)
+        self.experiencias_episodio.append(experiencia)
+
+    def aprender(self):
+        total = len(self.memoria) + len(self.memoria_melhor)
+        if total < self.lote:
+            return
+
+        qtd_atual = min(16, len(self.memoria))
+        qtd_melhor = min(16, len(self.memoria_melhor))
+        faltam = self.lote - qtd_atual - qtd_melhor
+
+        if faltam > 0:
+            extra = min(faltam, len(self.memoria) - qtd_atual)
+            qtd_atual += extra
+            faltam -= extra
+        if faltam > 0:
+            qtd_melhor += min(faltam, len(self.memoria_melhor) - qtd_melhor)
+
+        amostra = []
+        if qtd_atual:
+            amostra.extend(random.sample(list(self.memoria), qtd_atual))
+        if qtd_melhor:
+            amostra.extend(random.sample(list(self.memoria_melhor), qtd_melhor))
+        if len(amostra) < self.lote:
+            return
+
+        estados = np.asarray([item[0] for item in amostra], dtype=np.float32)
+        acoes = np.asarray([item[1] for item in amostra], dtype=np.int64)
+        recompensas = np.asarray([item[2] for item in amostra], dtype=np.float32)
+        proximos = np.asarray([item[3] for item in amostra], dtype=np.float32)
+        terminou = np.asarray([item[4] for item in amostra], dtype=np.float32)
+
+        futuros = np.max(self.rede_alvo.prever(proximos), axis=1)
+        alvos = recompensas + self.gamma * futuros * (1.0 - terminou)
+        self.rede.treinar(estados, acoes, alvos)
+
+        self.passos += 1
+        if self.passos % 500 == 0:
+            self.rede_alvo.copiar_pesos(self.rede)
+
+        self.epsilon = max(self.epsilon_minimo, self.epsilon * self.epsilon_decay)
+
+    def encerrar_episodio(self):
+        if self.experiencias_episodio:
+            self.memoria_melhor = deque(self.experiencias_episodio, maxlen=_MAX_MEMORIA)
+        self.experiencias_episodio = deque(maxlen=_MAX_MEMORIA)
+
+    def salvar(self):
+        dados = {
+            "versao": 3,
+            "acoes": self.rede.W3.shape[1],
+            "entradas": self.rede.W1.shape[0],
+            "pesos_rede": [p.copy() for p in self.rede.parametros()],
+            "pesos_alvo": [p.copy() for p in self.rede_alvo.parametros()],
+            "memoria": list(self.memoria),
+            "memoria_melhor": list(self.memoria_melhor),
+            "epsilon": self.epsilon,
+            "passos": self.passos,
+            "adam_m": [v.copy() for v in self.rede.m],
+            "adam_v": [v.copy() for v in self.rede.v],
+            "adam_passos": self.rede.passos_adam
+        }
+        temporario = self.caminho + "." + str(os.getpid()) + ".tmp"
+        try:
+            with open(temporario, "wb") as arquivo:
+                pickle.dump(dados, arquivo, protocol=pickle.HIGHEST_PROTOCOL)
+            for tentativa in range(5):
+                try:
+                    os.replace(temporario, self.caminho)
+                    return
+                except PermissionError:
+                    if tentativa == 4:
+                        raise
+                    time.sleep(0.3)
+        except Exception as erro:
+            print("neuralnetwork: erro ao salvar:", erro)
+        finally:
+            if os.path.exists(temporario):
+                try:
+                    os.remove(temporario)
+                except OSError:
+                    pass
+
+    def carregar(self):
+        if not os.path.exists(self.caminho):
+            return
+        try:
+            with open(self.caminho, "rb") as arquivo:
+                dados = pickle.load(arquivo)
+            if (dados.get("versao") != 3 or
+                    dados.get("acoes") != self.rede.W3.shape[1] or
+                    dados.get("entradas") != self.rede.W1.shape[0]):
+                print("neuralnetwork: memória incompatível; iniciando do zero.")
+                return
+            for atual, salvo in zip(self.rede.parametros(), dados["pesos_rede"]):
+                if atual.shape == salvo.shape:
+                    atual[:] = salvo
+            for atual, salvo in zip(self.rede_alvo.parametros(), dados["pesos_alvo"]):
+                if atual.shape == salvo.shape:
+                    atual[:] = salvo
+            self.memoria.extend(dados.get("memoria", []))
+            self.memoria_melhor.extend(dados.get("memoria_melhor", []))
+            self.epsilon = float(dados.get("epsilon", 1.0))
+            self.passos = int(dados.get("passos", 0))
+            self.rede.m = [v.copy() for v in dados.get("adam_m", self.rede.m)]
+            self.rede.v = [v.copy() for v in dados.get("adam_v", self.rede.v)]
+            self.rede.passos_adam = int(dados.get("adam_passos", 0))
+            print("neuralnetwork: memória carregada.")
+        except Exception as erro:
+            print("neuralnetwork: não foi possível carregar a memória:", erro)
+
+
+_player_pos = None
+_player_size = None
+_player_velocity_y = 0.0
+_obstaculos = []
+_obsnot = []
+_paredes = []
+_quantidades_observacao = None
+_funcoes = []
+_recompensa_atual = 1.0
+_estado_anterior = None
+_acao_anterior = None
+_contador_atualizacoes = 0
+_agente = None
+_total_tentativas = 0
+_melhor_recompensa = 0.0
+_pasta = os.path.dirname(os.path.abspath(__file__))
+_caminho_memoria = os.path.join(_pasta, "neuralnetwork_memory.pkl")
+
+
+def player(posicao, tamanho, velocity_y=0.0):
+    """Atualiza a posição e o tamanho do jogador. Chame a cada frame."""
+    global _player_pos, _player_size, _player_velocity_y
+    _player_pos = tuple(posicao)
+    _player_size = tuple(tamanho)
+    _player_velocity_y = float(velocity_y)
+
+
+def _validar_hitboxes(lista, nome):
+    """Valida listas no formato [((x, y), (largura, altura)), ...]."""
+    if not isinstance(lista, (list, tuple)):
+        raise TypeError("nn." + nome + " espera uma lista ou tupla.")
+
+    resultado = []
+    for item in lista:
+        try:
+            posicao, tamanho = item
+            if len(posicao) != 2 or len(tamanho) != 2:
+                raise ValueError
+            x = float(posicao[0])
+            y = float(posicao[1])
+            largura = float(tamanho[0])
+            altura = float(tamanho[1])
+            if largura < 0 or altura < 0:
+                raise ValueError
+        except (TypeError, ValueError, IndexError):
+            raise ValueError(
+                "Item inválido em nn." + nome + ". Use [((x, y), (largura, altura)), ...]."
+            )
+        resultado.append((x, y, largura, altura))
+    return resultado
+
+
+def obstacles(lista):
+    """Define TODOS os obstáculos que podem matar o jogador."""
+    global _obstaculos
+    _obstaculos = sorted(_validar_hitboxes(lista, "obstacles"), key=lambda item: item[0])
+
+
+def obsnot(lista):
+    """Define objetos de efeito incerto; a IA aprende pelo resultado das tentativas."""
+    global _obsnot
+    _obsnot = sorted(_validar_hitboxes(lista, "obsnot"), key=lambda item: item[0])
+
+
+def wall(lista):
+    """Define hitboxes de paredes/limites que não matam o jogador."""
+    global _paredes
+    _paredes = sorted(_validar_hitboxes(lista, "wall"), key=lambda item: item[0])
+
+
+def functions(lista):
+    """Define ações. A ação 0 é sempre esperar; lista[0] vira ação 1."""
+    global _funcoes, _agente, _estado_anterior, _acao_anterior
+    if not isinstance(lista, (list, tuple)):
+        raise TypeError("nn.functions espera uma lista ou tupla de funções.")
+    if not lista:
+        raise ValueError("nn.functions precisa de pelo menos uma função.")
+    if not all(callable(funcao) for funcao in lista):
+        raise TypeError("Todos os itens de nn.functions precisam ser funções.")
+    mudou = len(_funcoes) != len(lista)
+    _funcoes = list(lista)
+    if mudou:
+        _agente = None
+        _estado_anterior = None
+        _acao_anterior = None
+
+
+def reward(pontos):
+    """Define a recompensa do passo atual. Ex.: nn.reward(points)."""
+    global _recompensa_atual
+    _recompensa_atual = float(pontos)
+
+
+def _obter_estado():
+    global _quantidades_observacao
+
+    if _player_pos is None or _player_size is None:
+        raise RuntimeError("Chame nn.player(posicao, tamanho) antes de nn.update().")
+
+    px, py = _player_pos
+    largura, altura = _player_size
+    quantidades = (len(_obstaculos), len(_obsnot), len(_paredes))
+
+    # A quantidade de hitboxes precisa permanecer estável para manter
+    # o mesmo tamanho de entrada da rede durante o treinamento.
+    if _quantidades_observacao is None:
+        _quantidades_observacao = quantidades
+    elif quantidades != _quantidades_observacao:
+        raise RuntimeError(
+            "A quantidade de hitboxes mudou depois do início da IA. "
+            "Passe todos os itens de cada categoria em todos os frames, "
+            "mesmo os que estão longe da tela."
+        )
+
+    estado = [
+        max(-1.0, min(1.0, py / 600.0)),
+        max(-1.0, min(1.0, _player_velocity_y / 900.0)),
+        max(0.0, min(1.0, largura / 300.0)),
+        max(0.0, min(1.0, altura / 300.0))
+    ]
+
+    # Cada hitbox é incluída. A ordem por X deixa a observação consistente.
+    # As três categorias ficam separadas para a rede aprender suas diferenças.
+    for grupo in (_obstaculos, _obsnot, _paredes):
+        for x, y, w, h in grupo:
+            estado.extend([
+                max(-10.0, min(10.0, (x - px) / 1050.0)),
+                max(-10.0, min(10.0, (y - py) / 600.0)),
+                max(0.0, min(10.0, w / 300.0)),
+                max(0.0, min(10.0, h / 300.0))
+            ])
+
+    return np.asarray(estado, dtype=np.float32)
+
+
+def _garantir_agente(entradas):
+    global _agente
+    if not _funcoes:
+        raise RuntimeError("Configure as ações com nn.functions([...]) antes de nn.update().")
+    if _agente is None:
+        _agente = _AgenteDQN(len(_funcoes) + 1, _caminho_memoria, entradas)
+
+
+def update():
+    """Executa uma decisão da IA. Chame uma vez por passo de jogo/física.
+
+    Retorna True após executar a decisão da IA.
+    """
+    global _estado_anterior, _acao_anterior, _recompensa_atual
+    global _contador_atualizacoes
+    if _player_pos is None or _player_size is None:
+        raise RuntimeError("Chame nn.player(posicao, tamanho) antes de nn.update().")
+
+    estado = _obter_estado()
+    _garantir_agente(len(estado))
+    _contador_atualizacoes += 1
+    if _estado_anterior is not None and _acao_anterior is not None:
+        _agente.guardar(_estado_anterior, _acao_anterior, _recompensa_atual, estado, False)
+        if _contador_atualizacoes % _FREQUENCIA_APRENDIZADO == 0:
+            _agente.aprender()
+
+    acao = _agente.escolher_acao(estado)
+    if acao > 0:
+        _funcoes[acao - 1]()
+
+    _estado_anterior = estado
+    _acao_anterior = acao
+    _recompensa_atual = 1.0
+    return True
+
+
+def reset():
+    """Encerra a tentativa atual; preserva os pesos e o aprendizado."""
+    global _estado_anterior, _acao_anterior, _recompensa_atual
+    global _total_tentativas, _melhor_recompensa
+
+    if _agente is not None and _estado_anterior is not None and _acao_anterior is not None:
+        proximo = _obter_estado() if _player_pos is not None else _estado_anterior
+        recompensa_final = _recompensa_atual
+        _agente.guardar(_estado_anterior, _acao_anterior, recompensa_final, proximo, True)
+        _agente.aprender()
+        if _agente.experiencias_episodio:
+            soma = sum(item[2] for item in _agente.experiencias_episodio)
+            if soma > _melhor_recompensa:
+                _melhor_recompensa = soma
+                _agente.encerrar_episodio()
+            else:
+                _agente.experiencias_episodio = deque(maxlen=_MAX_MEMORIA)
+        _total_tentativas += 1
+        if _total_tentativas % 10 == 0:
+            _agente.salvar()
+
+    _estado_anterior = None
+    _acao_anterior = None
+    _recompensa_atual = 1.0
+    
+
+def save():
+    """Salva a rede e as memórias manualmente."""
+    if _agente is not None:
+        _agente.salvar()
+
+
+def stats():
+    """Retorna informações úteis: epsilon, tentativas e tamanhos das memórias."""
+    if _agente is None:
+        return {
+            "epsilon": 1.0,
+            "tentativas": _total_tentativas,
+            "memoria": 0,
+            "memoria_melhor": 0
+        }
+    return {
+        "epsilon": _agente.epsilon,
+        "tentativas": _total_tentativas,
+        "memoria": len(_agente.memoria),
+        "memoria_melhor": len(_agente.memoria_melhor)
+    }
+
+# ================= MODO POPULACAO ================= #
+# nn.players([...]) ativa o modo de varias IAs. Cada item:
+# (posicao, tamanho, velocidade_y, viva)
+_QUANTIDADE_JOGADORES = 100
+_modo_populacao = False
+_jogadores = []
+_agentes_populacao = []
+_recompensas_populacao = []
+_pontuacoes_populacao = []
+_mortos_anteriores = []
+_ticks_populacao = 0
+_recompensas_acumuladas = [0.0] * 100
+_geracao = 1
+_melhor_indice = 0
+_melhor_pontuacao_geral = float("-inf")
+_caminho_melhor_populacao = os.path.join(_pasta, "neuralnetwork_best_population.pkl")
+
+
+def _novo_agente_populacao(indice, copiar_de=None):
+    caminho = os.path.join(_pasta, "population_agent_" + str(indice) + ".pkl")
+    agente = _AgenteDQN(len(_funcoes) + 1, caminho, _entradas_populacao)
+    if copiar_de is not None:
+        # Na primeira geracao, copiar_de pode ser uma _RedeNeural
+        # carregada do arquivo da melhor populacao. Nas seguintes,
+        # pode ser um _AgenteDQN completo.
+        if isinstance(copiar_de, _AgenteDQN):
+            rede_origem = copiar_de.rede
+            epsilon_origem = copiar_de.epsilon
+        else:
+            rede_origem = copiar_de
+            epsilon_origem = 1.0
+
+        agente.rede.copiar_pesos(rede_origem)
+        agente.rede_alvo.copiar_pesos(rede_origem)
+        agente.epsilon = max(0.25, epsilon_origem)
+        agente.memoria.clear()
+        agente.memoria_melhor.clear()
+        agente.experiencias_episodio.clear()
+    return agente
+
+
+def players(lista):
+    """Atualiza os 100 jogadores: [(pos, tamanho, velocidade_y, viva), ...]."""
+    global _modo_populacao, _jogadores, _agentes_populacao
+    global _recompensas_populacao, _pontuacoes_populacao, _mortos_anteriores
+    global _entradas_populacao
+    if not isinstance(lista, (list, tuple)) or not lista:
+        raise ValueError("nn.players espera uma lista de jogadores.")
+    if len(lista) != _QUANTIDADE_JOGADORES:
+        raise ValueError("nn.players precisa receber exatamente 100 jogadores.")
+    normalizados = []
+    for item in lista:
+        if len(item) == 3:
+            pos, tamanho, velocidade = item
+            viva = True
+        elif len(item) == 4:
+            pos, tamanho, velocidade, viva = item
+        else:
+            raise ValueError("Cada jogador deve ser (pos, tamanho, velocidade, viva).")
+        normalizados.append((tuple(pos), tuple(tamanho), float(velocidade), bool(viva)))
+    _modo_populacao = True
+    _jogadores = normalizados
+    if not _agentes_populacao:
+        # A dimensão é calculada com a mesma observação usada no modo individual.
+        global _player_pos, _player_size, _player_velocity_y
+        _player_pos, _player_size, _player_velocity_y = normalizados[0][:3]
+        estado = _obter_estado()
+        _entradas_populacao = len(estado)
+        melhor = None
+        if os.path.exists(_caminho_melhor_populacao):
+            try:
+                with open(_caminho_melhor_populacao, "rb") as arquivo:
+                    dados = pickle.load(arquivo)
+                melhor = _RedeNeural(entradas=_entradas_populacao, saidas=len(_funcoes) + 1)
+                for atual, salvo in zip(melhor.parametros(), dados["pesos"]):
+                    if atual.shape == salvo.shape:
+                        atual[:] = salvo
+            except Exception:
+                melhor = None
+        _agentes_populacao = [_novo_agente_populacao(i, melhor) for i in range(100)]
+        _recompensas_populacao = [0.0] * 100
+        _pontuacoes_populacao = [0.0] * 100
+        _mortos_anteriores = [False] * 100
+
+
+def reward(pontos):
+    """No modo players, recebe uma lista de 100 recompensas individuais."""
+    global _recompensa_atual, _recompensas_populacao
+    if _modo_populacao:
+        if not isinstance(pontos, (list, tuple)) or len(pontos) != 100:
+            raise ValueError("No modo nn.players, nn.reward precisa receber 100 valores.")
+        _recompensas_populacao = [float(v) for v in pontos]
+    else:
+        _recompensa_atual = float(pontos)
+
+
+def _processar_jogador(argumentos):
+    """Processa uma IA sequencialmente, sem criar threads concorrentes."""
+    i, estado = argumentos
+    jogador = _jogadores[i]
+    agente = _agentes_populacao[i]
+    recompensa = _recompensas_populacao[i]
+    _pontuacoes_populacao[i] += recompensa
+
+    if not jogador[3]:
+        if not _mortos_anteriores[i] and agente.experiencias_episodio:
+            ultimo = agente.experiencias_episodio[-1]
+            agente.guardar(ultimo[3], ultimo[1], recompensa, ultimo[3], True)
+            agente.aprender()
+            agente.encerrar_episodio()
+        _mortos_anteriores[i] = True
+        return i
+
+    _mortos_anteriores[i] = False
+    if not hasattr(agente, "estado_anterior"):
+        agente.estado_anterior = None
+        agente.acao_anterior = None
+        agente.contador = 0
+
+    if agente.estado_anterior is not None:
+        agente.guardar(agente.estado_anterior, agente.acao_anterior, recompensa, estado, False)
+        agente.contador += 1
+        if agente.contador % _FREQUENCIA_APRENDIZADO == 0:
+            agente.aprender()
+
+    acao = agente.escolher_acao(estado)
+    if acao > 0:
+        _funcoes[acao - 1](i)
+    agente.estado_anterior = estado
+    agente.acao_anterior = acao
+    return i
+
+
+def update():
+    """Atualiza a população; decisões e treinamento são espaçados para aliviar a CPU."""
+    global _player_pos, _player_size, _player_velocity_y, _melhor_indice
+    global _ticks_populacao, _recompensas_acumuladas, _recompensas_populacao
+    if not _modo_populacao:
+        return _update_individual_original()
+    if len(_jogadores) != _QUANTIDADE_JOGADORES or len(_agentes_populacao) != _QUANTIDADE_JOGADORES:
+        raise RuntimeError("Chame nn.players() com 100 jogadores antes de nn.update().")
+
+    _ticks_populacao += 1
+    for i, valor in enumerate(_recompensas_populacao):
+        _recompensas_acumuladas[i] += valor
+
+    # A física continua a cada passo, mas a IA só recalcula estados e ações
+    # a cada 4 passos (30 decisões/s em vez de 120). Mortes são processadas já.
+    houve_morte = any(not item[3] and not _mortos_anteriores[i]
+                      for i, item in enumerate(_jogadores))
+    if _ticks_populacao % _FREQUENCIA_DECISAO != 0 and not houve_morte:
+        return True
+
+    _recompensas_populacao = _recompensas_acumuladas
+    _recompensas_acumuladas = [0.0] * _QUANTIDADE_JOGADORES
+
+    # Monta os estados das 100 IAs em lote. As hitboxes são compartilhadas;
+    # NumPy calcula as distâncias relativas sem repetir loops Python gigantes.
+    quantidades = (len(_obstaculos), len(_obsnot), len(_paredes))
+    if _quantidades_observacao is not None and quantidades != _quantidades_observacao:
+        raise RuntimeError("A quantidade de hitboxes mudou depois do início da IA.")
+
+    jogadores_np = np.asarray([
+        [item[0][0], item[0][1], item[2], item[1][0], item[1][1]]
+        for item in _jogadores
+    ], dtype=np.float32)
+    estados_np = np.empty((100, _entradas_populacao), dtype=np.float32)
+    estados_np[:, 0] = np.clip(jogadores_np[:, 1] / 600.0, -1.0, 1.0)
+    estados_np[:, 1] = np.clip(jogadores_np[:, 2] / 900.0, -1.0, 1.0)
+    estados_np[:, 2] = np.clip(jogadores_np[:, 3] / 300.0, 0.0, 1.0)
+    estados_np[:, 3] = np.clip(jogadores_np[:, 4] / 300.0, 0.0, 1.0)
+
+    deslocamento = 4
+    for grupo in (_obstaculos, _obsnot, _paredes):
+        if grupo:
+            hitboxes = np.asarray(grupo, dtype=np.float32)
+            quantidade = len(hitboxes)
+            bloco = np.empty((100, quantidade, 4), dtype=np.float32)
+            bloco[:, :, 0] = np.clip((hitboxes[None, :, 0] - jogadores_np[:, None, 0]) / 1050.0, -10.0, 10.0)
+            bloco[:, :, 1] = np.clip((hitboxes[None, :, 1] - jogadores_np[:, None, 1]) / 600.0, -10.0, 10.0)
+            bloco[:, :, 2] = np.clip(hitboxes[None, :, 2] / 300.0, 0.0, 10.0)
+            bloco[:, :, 3] = np.clip(hitboxes[None, :, 3] / 300.0, 0.0, 10.0)
+            estados_np[:, deslocamento:deslocamento + quantidade * 4] = bloco.reshape(100, quantidade * 4)
+            deslocamento += quantidade * 4
+
+    for i in range(100):
+        _processar_jogador((i, estados_np[i]))
+
+    vivos = [i for i, item in enumerate(_jogadores) if item[3]]
+    if vivos:
+        _melhor_indice = max(vivos, key=lambda i: _pontuacoes_populacao[i])
+    return True
+
+
+def _update_individual_original():
+    global _estado_anterior, _acao_anterior, _recompensa_atual, _contador_atualizacoes
+    if _player_pos is None or _player_size is None:
+        raise RuntimeError("Chame nn.player(posicao, tamanho) antes de nn.update().")
+    estado = _obter_estado()
+    _garantir_agente(len(estado))
+    _contador_atualizacoes += 1
+    if _estado_anterior is not None and _acao_anterior is not None:
+        _agente.guardar(_estado_anterior, _acao_anterior, _recompensa_atual, estado, False)
+        if _contador_atualizacoes % _FREQUENCIA_APRENDIZADO == 0:
+            _agente.aprender()
+    acao = _agente.escolher_acao(estado)
+    if acao > 0:
+        _funcoes[acao - 1]()
+    _estado_anterior, _acao_anterior = estado, acao
+    _recompensa_atual = 1.0
+    return True
+
+
+def reset():
+    """No modo populacao, inicia nova geracao a partir da melhor IA."""
+    global _estado_anterior, _acao_anterior, _recompensa_atual
+    global _total_tentativas, _melhor_recompensa, _geracao
+    global _agentes_populacao, _pontuacoes_populacao, _mortos_anteriores
+    global _melhor_pontuacao_geral, _ticks_populacao, _recompensas_acumuladas
+    if not _modo_populacao:
+        return _reset_individual_original()
+    if any(item[3] for item in _jogadores):
+        return
+    melhor_i = max(range(100), key=lambda i: _pontuacoes_populacao[i])
+    melhor = _agentes_populacao[melhor_i]
+    pontuacao = _pontuacoes_populacao[melhor_i]
+    if pontuacao > _melhor_pontuacao_geral:
+        _melhor_pontuacao_geral = pontuacao
+        try:
+            with open(_caminho_melhor_populacao, "wb") as arquivo:
+                pickle.dump({"pesos": [p.copy() for p in melhor.rede.parametros()]}, arquivo, protocol=pickle.HIGHEST_PROTOCOL)
+        except Exception as erro:
+            print("neuralnetwork: erro ao salvar melhor populacao:", erro)
+    _agentes_populacao = [_novo_agente_populacao(i, melhor) for i in range(100)]
+    _pontuacoes_populacao = [0.0] * 100
+    _mortos_anteriores = [False] * 100
+    _recompensas_populacao = [0.0] * 100
+    _recompensas_acumuladas = [0.0] * 100
+    _ticks_populacao = 0
+    _geracao += 1
+    _total_tentativas += 100
+
+
+def _reset_individual_original():
+    global _estado_anterior, _acao_anterior, _recompensa_atual
+    global _total_tentativas, _melhor_recompensa
+    if _agente is not None and _estado_anterior is not None and _acao_anterior is not None:
+        proximo = _obter_estado() if _player_pos is not None else _estado_anterior
+        _agente.guardar(_estado_anterior, _acao_anterior, _recompensa_atual, proximo, True)
+        _agente.aprender()
+        if _agente.experiencias_episodio:
+            soma = sum(item[2] for item in _agente.experiencias_episodio)
+            if soma > _melhor_recompensa:
+                _melhor_recompensa = soma
+                _agente.encerrar_episodio()
+            else:
+                _agente.experiencias_episodio = deque(maxlen=_MAX_MEMORIA)
+        _total_tentativas += 1
+        if _total_tentativas % 10 == 0:
+            _agente.salvar()
+    _estado_anterior = None
+    _acao_anterior = None
+    _recompensa_atual = 1.0
+
+
+def population_stats():
+    return {"geracao": _geracao, "vivas": sum(1 for p in _jogadores if p[3]),
+            "melhor_indice": _melhor_indice, "melhor_pontuacao": max(_pontuacoes_populacao) if _pontuacoes_populacao else 0}