nwm-rl 1.0.0__tar.gz

nwm_rl-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 NWM Research Team
+
+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.

nwm_rl-1.0.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: nwm-rl
+Version: 1.0.0
+Summary: Negative Weight Mapping - A Reinforcement Learning framework using persistent potential fields
+Author: CusterMustOfficial
+License: MIT
+Project-URL: Homepage, https://github.com/nwm-research/nwm
+Project-URL: Documentation, https://github.com/nwm-research/nwm#readme
+Keywords: reinforcement-learning,machine-learning,ai,potential-field,exploration
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: gymnasium>=0.26.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Provides-Extra: full
+Requires-Dist: matplotlib>=3.5.0; extra == "full"
+Requires-Dist: torch>=2.0.0; extra == "full"
+Dynamic: license-file
+
+# NWM - Negative Weight Mapping
+
+**Apprendimento per Esclusione** - Un framework che guida l'esplorazione e la stabilita  utilizzando memorie persistenti di fallimento e successo.
+
+## Cos'e NWM?
+
+Il **Negative Weight Mapping** trasforma l'esperienza passata in un **Campo di Forza Potenziale**. L'agente naviga lo spazio degli stati reagendo a:
+
+- **Forze Attrattive** - Successi passati che guidano verso azioni ottimali
+- **Forze Repulsive** - Fallimenti passati che allontanano da azioni pericolose
+
+### Caratteristiche Principali
+
+| Feature                        | Descrizione                                             |
+| ------------------------------ | ------------------------------------------------------- |
+| **Dynamic Smart Lock**   | Protegge automaticamente le memorie di alta qualita     |
+| **Adaptive Exploration** | Riduce l'esplorazione quando trova strategie vincenti   |
+| **Persistent Memory**    | I centroidi evolvono con "stiffness" progressiva        |
+| **Fear & Greed**         | Evita le azioni pericolose prima di cercare il guadagno |
+
+## Installazione
+
+```bash
+cd PYTHONLIB
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import gymnasium as gym
+from nwm import NWM
+
+# Crea ambiente e agente
+env = gym.make("CartPole-v1")
+agent = NWM(
+    state_dim=env.observation_space.shape[0],
+    num_actions=env.action_space.n
+)
+
+# Training loop
+for episode in range(100):
+    state, _ = env.reset()
+    done = False
+  
+    while not done:
+        action = agent.select_action(state)
+        next_state, reward, terminated, truncated, _ = env.step(action)
+        done = terminated or truncated
+        agent.step(state, action, reward, next_state, done)
+        state = next_state
+  
+    print(f"Episode {episode + 1}: Best = {agent.best_reward:.0f}")
+```
+
+## API Reference
+
+### NWM
+
+```python
+from nwm import NWM, NWMConfig
+
+# Con configurazione personalizzata
+config = NWMConfig(
+    max_centroids=500,      # Massimo numero di centroidi
+    warmup_episodes=50,     # Episodi di pura esplorazione
+    exploration_rate=1.0,   # Tasso iniziale di esplorazione
+    exploration_decay=0.99, # Decay dell'esplorazione
+    min_exploration=0.05,   # Esplorazione minima
+)
+
+agent = NWM(state_dim=4, num_actions=2, config=config)
+
+# Metodi principali
+action = agent.select_action(state, training=True)
+agent.step(state, action, reward, next_state, done)
+stats = agent.get_stats()
+
+# Save/Load
+agent.save("agent.pkl")
+agent = NWM.load("agent.pkl")
+```
+
+### NWMConfig
+
+| Parametro             | Default | Descrizione                            |
+| --------------------- | ------- | -------------------------------------- |
+| `max_centroids`     | 500     | Numero massimo di centroidi in memoria |
+| `warmup_episodes`   | 50      | Episodi di warmup prima del learning   |
+| `exploration_rate`  | 1.0     | Tasso iniziale di esplorazione         |
+| `exploration_decay` | 0.99    | Fattore di decay                       |
+| `min_exploration`   | 0.05    | Esplorazione minima                    |
+| `merge_threshold`   | 0.3     | Soglia per il merge dei centroidi      |
+| `distance_cutoff`   | 2.5     | Distanza massima di influenza          |
+
+## Struttura del Package
+
+```
+PYTHONLIB/
+├── nwm/                    # Package principale
+│   ├── agents/             # Implementazioni agenti
+│   ├── core/               # Componenti core (centroid, potential_field)
+│   └── utils/              # Utilities (config)
+├── examples/               # Esempi di utilizzo
+└── tests/                  # Test suite
+```
+
+## Esempi
+
+```bash
+# Quick start
+python examples/quickstart.py
+
+# Training completo
+python examples/cartpole_training.py --episodes 500
+
+# Demo visuale
+python examples/cartpole_training.py --demo
+```
+
+---
+
+**Versione**: 1.0.0
+**Licenza**: MIT
+**Autore**: CusterMustOfficial

nwm_rl-1.0.0/README.md

@@ -0,0 +1,125 @@
+# NWM - Negative Weight Mapping
+
+**Apprendimento per Esclusione** - Un framework che guida l'esplorazione e la stabilita  utilizzando memorie persistenti di fallimento e successo.
+
+## Cos'e NWM?
+
+Il **Negative Weight Mapping** trasforma l'esperienza passata in un **Campo di Forza Potenziale**. L'agente naviga lo spazio degli stati reagendo a:
+
+- **Forze Attrattive** - Successi passati che guidano verso azioni ottimali
+- **Forze Repulsive** - Fallimenti passati che allontanano da azioni pericolose
+
+### Caratteristiche Principali
+
+| Feature                        | Descrizione                                             |
+| ------------------------------ | ------------------------------------------------------- |
+| **Dynamic Smart Lock**   | Protegge automaticamente le memorie di alta qualita     |
+| **Adaptive Exploration** | Riduce l'esplorazione quando trova strategie vincenti   |
+| **Persistent Memory**    | I centroidi evolvono con "stiffness" progressiva        |
+| **Fear & Greed**         | Evita le azioni pericolose prima di cercare il guadagno |
+
+## Installazione
+
+```bash
+cd PYTHONLIB
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import gymnasium as gym
+from nwm import NWM
+
+# Crea ambiente e agente
+env = gym.make("CartPole-v1")
+agent = NWM(
+    state_dim=env.observation_space.shape[0],
+    num_actions=env.action_space.n
+)
+
+# Training loop
+for episode in range(100):
+    state, _ = env.reset()
+    done = False
+  
+    while not done:
+        action = agent.select_action(state)
+        next_state, reward, terminated, truncated, _ = env.step(action)
+        done = terminated or truncated
+        agent.step(state, action, reward, next_state, done)
+        state = next_state
+  
+    print(f"Episode {episode + 1}: Best = {agent.best_reward:.0f}")
+```
+
+## API Reference
+
+### NWM
+
+```python
+from nwm import NWM, NWMConfig
+
+# Con configurazione personalizzata
+config = NWMConfig(
+    max_centroids=500,      # Massimo numero di centroidi
+    warmup_episodes=50,     # Episodi di pura esplorazione
+    exploration_rate=1.0,   # Tasso iniziale di esplorazione
+    exploration_decay=0.99, # Decay dell'esplorazione
+    min_exploration=0.05,   # Esplorazione minima
+)
+
+agent = NWM(state_dim=4, num_actions=2, config=config)
+
+# Metodi principali
+action = agent.select_action(state, training=True)
+agent.step(state, action, reward, next_state, done)
+stats = agent.get_stats()
+
+# Save/Load
+agent.save("agent.pkl")
+agent = NWM.load("agent.pkl")
+```
+
+### NWMConfig
+
+| Parametro             | Default | Descrizione                            |
+| --------------------- | ------- | -------------------------------------- |
+| `max_centroids`     | 500     | Numero massimo di centroidi in memoria |
+| `warmup_episodes`   | 50      | Episodi di warmup prima del learning   |
+| `exploration_rate`  | 1.0     | Tasso iniziale di esplorazione         |
+| `exploration_decay` | 0.99    | Fattore di decay                       |
+| `min_exploration`   | 0.05    | Esplorazione minima                    |
+| `merge_threshold`   | 0.3     | Soglia per il merge dei centroidi      |
+| `distance_cutoff`   | 2.5     | Distanza massima di influenza          |
+
+## Struttura del Package
+
+```
+PYTHONLIB/
+├── nwm/                    # Package principale
+│   ├── agents/             # Implementazioni agenti
+│   ├── core/               # Componenti core (centroid, potential_field)
+│   └── utils/              # Utilities (config)
+├── examples/               # Esempi di utilizzo
+└── tests/                  # Test suite
+```
+
+## Esempi
+
+```bash
+# Quick start
+python examples/quickstart.py
+
+# Training completo
+python examples/cartpole_training.py --episodes 500
+
+# Demo visuale
+python examples/cartpole_training.py --demo
+```
+
+---
+
+**Versione**: 1.0.0
+**Licenza**: MIT
+**Autore**: CusterMustOfficial

nwm_rl-1.0.0/nwm/__init__.py

@@ -0,0 +1,45 @@
+"""
+NWM - Negative Weight Mapping
+=============================
+
+A Reinforcement Learning framework that uses persistent potential fields
+to guide agent exploration through attractive (success) and repulsive (failure) forces.
+
+Quick Start
+-----------
+>>> import gymnasium as gym
+>>> from nwm import NWM, NWMConfig
+>>>
+>>> env = gym.make("CartPole-v1")
+>>> agent = NWM(
+...     state_dim=env.observation_space.shape[0],
+...     num_actions=env.action_space.n
+... )
+>>>
+>>> state, _ = env.reset()
+>>> action = agent.select_action(state)
+>>> next_state, reward, done, truncated, _ = env.step(action)
+>>> agent.step(state, action, reward, next_state, done or truncated)
+
+Main Components
+---------------
+- NWM: The main RL agent using potential fields
+- NWMConfig: Configuration dataclass for agent parameters
+- PersistentCentroid: Memory unit storing state-action experiences
+- PersistentPotentialField: Spatial memory structure with force calculations
+"""
+
+__version__ = "1.0.0"
+__author__ = "CusterMustOfficial"
+
+from nwm.agents.nwm_agent import NWMAgent as NWM
+from nwm.core.centroid import PersistentCentroid
+from nwm.core.potential_field import PersistentPotentialField
+from nwm.utils.config import NWMConfig
+
+__all__ = [
+    "NWM",
+    "NWMConfig",
+    "PersistentCentroid",
+    "PersistentPotentialField",
+]

nwm_rl-1.0.0/nwm/agents/__init__.py

@@ -0,0 +1,5 @@
+"""Agent implementations for NWM framework."""
+
+from nwm.agents.nwm_agent import NWMAgent
+
+__all__ = ["NWMAgent"]