Metadata-Version: 2.4
Name: instinto
Version: 0.2.0
Summary: Red neuronal zero-deps para videojuegos: neuroevolucion, imitacion, JIT por codegen y save de una linea.
Author: esraderey
License: MIT
Project-URL: Homepage, https://github.com/ElEscribanoSilente/instinto
Keywords: neural-network,neuroevolution,gamedev,zero-dependencies,genetic-algorithm
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# instinto

[![CI](https://github.com/ElEscribanoSilente/instinto/actions/workflows/ci.yml/badge.svg)](https://github.com/ElEscribanoSilente/instinto/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/instinto)](https://pypi.org/project/instinto/)
[![Python](https://img.shields.io/pypi/pyversions/instinto)](https://pypi.org/project/instinto/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Red neuronal **zero-deps** para videojuegos. Un archivo, solo stdlib.

- **`Brain`** — MLP denso con pesos planos. `think()` / `act()`.
- **Neuroevolución** — `Population` con elitismo, torneo y **sigma autoadaptativo**
  (regla 1/5 de Rechenberg): explora fuerte al inicio, refina solo al final.
- **Imitación** — `learn()` con backprop (SGD + momentum). Graba al jugador, entrena al NPC.
- **JIT por codegen** — `compile()` genera el forward desenrollado vía `exec`:
  **3–6× más rápido**, ~120k inferencias/seg en CPython puro.
- **Save de una línea** — `save()` → float16 + zlib + base85. Un cerebro 2-6-2
  son ~116 chars: pégalo en el JSON de tu partida guardada.
- **Determinista** — misma seed, misma evolución. Replays reproducibles.

## Instalar

```
pip install instinto        # o copia instinto.py a tu proyecto
```

## 60 segundos

```python
from instinto import Brain, Population

# inferencia
npc = Brain(n_in=4, hidden=[8], n_out=3, out="softmax", seed=42)
accion = npc.act([dx, dy, vida, peligro], explore=0.05)   # 0|1|2

# neuroevolución: el fitness ES tu juego
pop = Population(60, n_in=4, hidden=[8], n_out=3, out="softmax", seed=7)
for gen in range(100):
    for brain in pop:
        brain.fitness = jugar_partida(brain)     # tu función
    stats = pop.evolve()                          # {'gen','best','mean','sigma'}
mejor = pop.best

# imitación: aprende del jugador
datos = [(estado, accion_del_jugador), ...]       # índice de clase si softmax
npc.learn(datos, epochs=300, lr=0.5)

# producción
mejor.compile()                                   # JIT (se invalida solo al mutar)
blob = mejor.save()                               # str de una línea
npc2 = Brain.load(blob)
```

## Demo

```
python demo_caza.py    # agentes evolucionan a cazar comida, render ASCII
```

## API

| | |
|---|---|
| `Brain(n_in, hidden, n_out, act, out, seed)` | acts: `tanh sigmoid relu linear` (+`softmax` en salida) |
| `.think(x) -> list` / `.act(x, explore) -> int` | inferencia / argmax con ε-greedy |
| `.learn(samples, epochs, lr, momentum, batch, reset)` | backprop; devuelve loss (½·MSE o CE) |
| `.mutate(rate, power)` / `.cross(other)` / `.clone()` | operadores evolutivos |
| `.compile()` / `.save(compact)` / `Brain.load(s)` | JIT / persistencia |
| `Population(size, ..., elite, tournament, mut_rate, sigma, noisy_fitness)` | iterable de Brains |
| `.evolve() -> stats` / `.best` | siguiente generación / hall of fame |

Sin numpy. Sin configs. Sin clases que heredar. Python ≥ 3.8.
