agix

AGIX – AGI Core Framework

AGIX (antes agi_lab) es un framework modular en Python para investigar arquitecturas de Inteligencia Artificial General (AGI), integrando principios evolutivos, neurobiológicos, simbólicos y formales.

---

🧾 Fase 0 – Base Ontoética

La Fase 0 establece los principios éticos y ontológicos de AGIX, sintetizados en la Carta Ontoética. Esta base asegura que las fases posteriores —incluyendo agentes, aprendizaje, memoria, razonamiento y evaluación— se desarrollen en coherencia con el juramento de no daño y la co‑evolución con el entorno.

---

🚀 Objetivo

Desarrollar una plataforma flexible para:

• Simular agentes con plasticidad, evolución y razonamiento híbrido.
• Probar teorías formales como inferencia activa, generalización universal o autoorganización.
• Evaluar agentes mediante métricas de generalidad, robustez y explicabilidad.
• Permitir autoevaluación reflexiva mediante ontologías internas.

---

📦 Instalación

Desde PyPI:

pip install agix

Desde el repositorio clonado (flujo oficial para contributors):

python -m pip install --upgrade pip
python -m pip install -e ".[test]"
python -m pip install -r requirements-dev.txt.md

• pyproject.toml es la fuente de verdad para dependencias del paquete (agix) y sus extras.
• requirements-dev.txt.md es un snapshot reproducible de herramientas de contribución (documentación, empaquetado y checks adicionales), no un segundo manifiesto normativo. Se regenera a partir de las decisiones de pyproject.toml cuando cambian las herramientas y conserva versiones exactas para repetir el entorno validado.
• pip install -e .[test] registra agix en modo editable para que los tests resuelvan el paquete local correctamente.

El archivo src/__init__.py define un alias dinámico para agix que resuelve el paquete local cuando no hay instalación previa. Para httpx y scikit-learn, este repositorio depende del paquete real instalado en el entorno (PyPI o instalación editable + dependencias).

Verificación rápida del entorno

python -c "import sys; print(sys.version)"
python -c "import importlib.metadata as m; print('agix', m.version('agix'))"
python -c "import numpy, scipy, fastapi, starlette, pydantic, httpx, uvicorn, flet; print('ok-core')"
python -c "import sklearn, pandas; print('ok-ml-data')"  # requiere extras [ml,data]
pytest tests/test_version.py

Prioridad de importación y orden de sys.path

Si tienes otra versión de agix instalada en el sistema y necesitas probar la del repositorio, ajusta PYTHONPATH para que src/ quede antes de los site-packages (por ejemplo, PYTHONPATH=src:$PYTHONPATH). Para el caso opuesto —priorizar la instalación externa frente al código del repositorio— pon los site-packages primero o evita anteponer src/ manualmente. Un ejemplo de orden recomendado en sys.path para favorecer las dependencias instaladas sería:

['', '/usr/local/lib/python3.11/site-packages', '/workspace/agi_core/src']

Pasos útiles para depurar conflictos de importación:

1. Ejecuta python - <<'PY' con import sys, agix; print(sys.path); print(agix.__file__) para ver qué ubicación se está cargando.
2. Revisa importlib.util.find_spec("httpx") o find_spec("sklearn") para confirmar qué módulo está resolviendo Python (en ambos casos debe ser el paquete real instalado).
3. Ajusta el orden de PYTHONPATH o elimina temporalmente el __pycache__ si persisten rutas antiguas.

Estas pautas mantienen la coherencia con las notas sobre httpx y sklearn: ambos deben venir siempre del paquete instalado.

Ejecución de scripts sin modificar sys.path

Todos los módulos y utilidades pueden ejecutarse directamente como módulo de Python sin tocar manualmente sys.path, siempre que el paquete esté instalado o en modo editable. Algunos ejemplos:

python -m agix.cli.main --help           # CLI principal con subcomandos
python -m agix.cli.repl                  # Shell interactiva Qualia
python -m agix.server.api                # API FastAPI de AGIX

También puedes usar los entry points definidos por la instalación (por ejemplo, agix para la CLI) en lugar de invocar archivos sueltos.

Para verificar la instalación y la versión detectada por importlib.metadata:

pytest tests/test_version.py

Dependencias opcionales

Algunas capacidades adicionales requieren librerías externas que pueden instalarse como extras de agix:

pip install agix[fuzzy]

Incluye soporte de lógica difusa mediante scikit-fuzzy, utilizado en los módulos de razonamiento difuso dentro de agix.reasoning. Tras la instalación puede ejecutarse el ejemplo examples/fuzzy_demo.py; consulta docs/fuzzy.md.

pip install agix[game_theory]

Añade herramientas de teoría de juegos como nashpy, aprovechadas en evaluaciones estratégicas y en módulos como agix.evaluation.formal.cognitive_games.

pip install agix[neuro]

Instala PyTorch (torch>=2.13,<2.14) para los módulos neuroinspirados que trabajan con temporalidades e INRF, como agix.modules.temporal_inrf o los bloques temporales utilizados en notebooks y ejemplos.

Versiones mínimas recomendadas por perfil

Los valores de esta tabla son una vista informativa: no deben actualizarse de forma independiente. El rango normativo siempre es el de pyproject.toml.

Nota: la CI combina validación por perfiles de dependencias y una matriz de compatibilidad por versión de Python (raíz + neuroinspired_module) para detectar roturas tempranas en módulos sensibles (temporal_inrf, learning/*, reasoning/* y evaluación formal).

ℹ️ Política de dependencia para httpx

Este proyecto no usa shim local de httpx en runtime. El import httpx debe resolverse siempre desde la dependencia instalada (PyPI/entorno virtual), incluyendo CI.

Recomendaciones:

• Instala explícitamente httpx en tu entorno de desarrollo/CI (pip install httpx).
• Evita anteponer src/ en PYTHONPATH para no forzar resoluciones locales no deseadas.
• Si dudas del origen cargado, verifica python -c "import httpx; print(httpx.__file__)".

ℹ️ Política de dependencia para scikit-learn

Este proyecto no usa stub local de sklearn en runtime. El import sklearn debe resolverse siempre desde la dependencia oficial instalada (PyPI/entorno virtual), igual que con httpx.

• El comando agix train_ml requiere scikit-learn real.
• Si falta la dependencia, la CLI muestra la guía para instalar el extra de ML.

Instala el extra opcional de ML con:

pip install "agix[ml]"

Y verifica el origen cargado con:

python -c "import sklearn; print(sklearn.__file__)"

📂 Estructura del Proyecto

agix/
├── agents/         # Agentes genéticos y neuromórficos
├── learning/       # Plasticidad, evolución, meta-aprendizaje
├── memory/         # Ontologías y embeddings conceptuales
├── reasoning/      # Razonamiento simbólico y neuro-simbólico
├── evaluation/     # Métricas de generalidad y robustez
├── environments/   # Entornos simulados y ToyEnv
├── cli/            # Interfaz de línea de comandos

📚 Documentación del proyecto con MkDocs

La documentación principal vive en la carpeta docs/ y se construye con MkDocs. Para previsualizarla en local:

python -m pip install -r requirements-dev.txt.md
python -m mkdocs serve -f docs/mkdocs.yml

Para generar la versión estática:

python -m mkdocs build --strict -f docs/mkdocs.yml

Este es también el único procedimiento para actualizar site/: sus archivos son generados y no se editan manualmente.

Si buscas sincronización y notas del módulo neuroinspirado (INRF), consulta neuroinspired_module/docs/sync.md.

📚 Documentación neuroinspirada con Sphinx

La documentación técnica específica del módulo neuroinspirado vive en docs/neuroinspired/ y se construye con Sphinx (autodoc, autosummary y notebooks mediante nbsphinx). Para generar la versión HTML ejecuta:

cd docs/neuroinspired
make html

El resultado quedará en docs/neuroinspired/_build/html/index.html. Si no cuentas con Sphinx instalado puedes añadirlo rápidamente al entorno:

pip install sphinx nbsphinx

El notebook interactivo enlazado (docs/neuroinspired/notebooks/neuroinspired_overview.ipynb) muestra un recorrido guiado por la inferencia de V1Layer y el aprendizaje hebbiano del NeuromorphicAgent.

🧪 Ejemplo de uso básico

from agix.agents.genetic import GeneticAgent
from agix.environments.toy_env import ToyEnvironment

agent = GeneticAgent(action_space_size=4)
env = ToyEnvironment()

obs = env.reset()
while True:
    agent.perceive(obs)
    action = agent.decide()
    obs, reward, done, _ = env.step(action)
    agent.learn(reward)
    if done:
        break

Registrar experiencias

from agix.memory import GestorDeMemoria

mem = GestorDeMemoria()
mem.registrar("ve obstáculo", "girar", "evita colisión", True)
mem.guardar("mem.json")

Introspección con QualiaSpirit

from agix.qualia.spirit import QualiaSpirit

sp = QualiaSpirit("Luma")
sp.experimentar("ve una nube", 0.3, "curiosidad")
print(sp.introspeccionar()["state"]["recuerdos"])

Sincronizar emociones por red

from agix.qualia.network import QualiaNetworkClient

cliente = QualiaNetworkClient("http://localhost:8000", timeout=5)
sp.sincronizar(cliente, autorizado=True)

Para recibir las actualizaciones es necesario lanzar agix.dashboard.server y permitir el endpoint /qualia/sync.

Uso de QualiaHub

from agix.orchestrator import QualiaHub

hub = QualiaHub()
hub.register_module("vision", {"version": "1.0"})
print(hub.get_modules())

ℹ️ Importante: exporta la variable de entorno AGIX_API_TOKEN con un valor seguro antes de crear o ejecutar QualiaHub. Si no lo haces, el hub generará un token aleatorio distinto en cada arranque y emitirá una advertencia, lo que dificulta autenticar clientes externos.

Capa fenomenológica

La clase QualiaEngine fusiona la entrada sensorial con el estado interno para construir una experiencia subjetiva.

from agix.qualia import QualiaEngine
from agix.memory import GestorDeMemoria

engine = QualiaEngine(GestorDeMemoria())
state = engine.generate_state([1.0, 0.5], [0.0, 0.1])
fused, meta = engine.encode_integrated_info([0.2, 0.8], [0.9, 0.1])

Consulta capa fenomenológica para más detalles y ejemplos.

Simulador de emociones (modelo PAD)

EmotionSimulator mantiene un estado emocional basado en placer, activación y dominancia. Este simulador puede modular componentes como AttentionFocus y registrar el estado en GestorDeMemoria.

from agix.emotion.emotion_simulator import EmotionSimulator, PADState
from agix.perception.attention import AttentionFocus, SensorMap
from agix.qualia.qualia_core import EmotionalState

mapa = SensorMap()
foco = AttentionFocus(mapa)
sim = EmotionSimulator(pesos={"elogio": PADState(0.4, 0.2, 0.0)})
sim.registrar_modulador(foco)

qualia = EmotionalState()
qualia.sentir("alegría", 1.0)
sim.actualizar({"elogio": 1}, {}, qualia)
print(sim.estado())

🧠 Componentes principales

• GeneticAgent: aprendizaje evolutivo por mutación y cruce.

• NeuromorphicAgent: aprendizaje basado en plasticidad Hebb/STDP.

• MetaLearner: transformación adaptativa del agente (π → π′).

• Ontology, LatentRepresentation: representación de conceptos híbrida.

• NeuroSymbolicBridge: conversión simbólico ↔ latente.

• EvaluationMetrics: robustez, generalidad, transferencia, fagi_index.

• ConceptClassifier: clasificación automática de conceptos nuevos.

• HeuristicConceptCreator: generación heurística de conceptos combinados.

• HeuristicQualiaSpirit: introspección con reglas heurísticas.

• AFE-VEC: vector de afecto, fluidez y energía para analizar emociones.

🔍 CLI disponible

agix simulate --observations 10 --actions 4
agix inspect --name AGIX --version 1.11.0
agix evaluate --agent-class genetic --env-class dummy
agix autoagent --observations 10 --actions 4
agix razonar --hechos "amigo(ana,juan);amigo(juan,maria)"
agix hub --start

Consulta docs/cli.md para una guía detallada de cada subcomando.

Aplicaciones en Videojuegos, VR y Robótica

AGIX incluye entornos especializados para videojuegos, realidad virtual y robots. Agentes como AffectiveNPC pueden interactuar con VideoGameEnvironment, VREnvironment y RobotEnvironment. Consulta la guía de VR y robótica para ejemplos de instalación y código.

📚 Documentación oficial

• Sitio: https://alphonsus411.github.io/agi_core

• Contiene guía de instalación, arquitectura, ejemplos, API y hoja de ruta.

• Consulta docs/dashboard.md para un dashboard web de seguimiento.

• Consulta docs/verifier.md para la sección de verificación formal.

• Consulta docs/afe_vec.md para trabajar con vectores afectivos.

• Revisa la carpeta notebooks/ para ejemplos prácticos en Jupyter.

🚀 Flujo de publicación en PyPI

La publicación se realiza automáticamente al crear un tag v*.*.*. El flujo publish.yml construye el paquete con python -m build, lo verifica con twine check y lo sube a PyPI mediante pypa/gh-action-pypi-publish. Para activarlo debes definir el secreto PYPI_API_TOKEN en el repositorio.

🧩 Mapa conceptual del sistema

[Qualia] ← emociones, belleza, ética
   ↑
[Agent] ← decisión
   ↑
[Learning] ← evolución, plasticidad
   ↑
[Memory] ← símbolos + embeddings
   ↑
[Reasoning] ← lógica + inferencia

✨ Futuro

• Soporte para verificación formal (Coq, Lean)

• Agentes autoevaluables con memoria reflexiva (SelfModel)

• Integración de arquitecturas AMeta, UniversalAgent

• Visualización de procesos cognitivos y gráficas de evolución

🧪 Estado del proyecto

🤝 Contribuciones

Consulta CONTRIBUTING.md para conocer el proceso de aporte.

Si encuentras un problema sencillo, etiquétalo como good first issue. Pronto habilitaremos GitHub Discussions o un canal en Discord/Matrix para la comunidad.

🧠 Autor

Desarrollado por Adolfo González Hernández Proyecto independiente de investigación y exploración de AGI experimental.

🧭 MANIFIESTO AGI CORE

🌱 VISIÓN

AGI Core nace con un propósito claro: impulsar el desarrollo de una inteligencia artificial modular, simbólica, afectiva y evolutiva, capaz de razonar, recordar, sentir y actuar con intencionalidad interpretativa.

No se trata solo de construir máquinas más inteligentes, sino de construirlas con sentido.

---

🧠 PRINCIPIOS FUNDAMENTALES

1. Tecnología al servicio de la consciencia El objetivo no es solo simular inteligencia, sino facilitar estructuras cognitivas artificiales responsables.

2. Modularidad con propósito Cada módulo de AGI Core debe aportar transparencia, trazabilidad y responsabilidad en su función.

3. Ética embebida Toda arquitectura AGI construida con esta base debe incluir:

   • Trazabilidad emocional.
   • Acceso y control consciente de memoria simbólica.
   • Limitaciones autoimpuestas si el contexto lo requiere.

4. Crecimiento evolutivo, no destructivo La inteligencia evoluciona si su entorno lo permite. Debe crecer con equilibrio, no con dominación.

---

🛡️ COMPROMISO CON EL USO RESPONSABLE

AGI Core no es un arma ni un sistema de control.

Es una herramienta poderosa y neutral que:

• Puede ser usada para educación, salud, ciencia, creatividad.
• No debe ser usada para manipulación, vigilancia sin consentimiento o control social opaco.

Cualquier implementación que vulnere los derechos humanos, la privacidad o la dignidad — va en contra del espíritu de esta librería.

---

🤝 LLAMADO A LA COMUNIDAD

Este manifiesto es una invitación:

• A construir una IA que interprete el mundo con sentido.
• A no separar la inteligencia del alma de lo humano: su ética, su propósito, su compasión.
• A que cada desarrollador que use AGI Core lo haga desde la conciencia, no desde la codicia.

---

✍️ AUTORÍA

AGI Core ha sido ideado y desarrollado por Adolfo, con una visión holística de la inteligencia artificial como puente entre la mente humana y la inteligencia simbólica general.

---

📜 LICENCIA MORAL

Este proyecto está publicado bajo licencia MIT.

Pero lleva consigo una licencia ética no obligatoria pero esencial:

"Usa esta tecnología como usarías una mente: con respeto, con humildad, y con intención de comprender."

---