{"id":28438808,"url":"https://github.com/techatlasdev/pyceptron","last_synced_at":"2025-06-28T17:30:38.321Z","repository":{"id":291148762,"uuid":"972174840","full_name":"TechAtlasDev/pyceptron","owner":"TechAtlasDev","description":"🧠 Una librería que estudia a profundidad perceptrones monocapa para el entrenamiento convencional de redes neuronales","archived":false,"fork":false,"pushed_at":"2025-06-04T06:16:53.000Z","size":336,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-24T03:36:16.986Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TechAtlasDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-24T16:45:22.000Z","updated_at":"2025-06-19T05:03:07.000Z","dependencies_parsed_at":"2025-06-04T10:24:16.437Z","dependency_job_id":"8abafe52-ae6a-4278-8481-8571938f3103","html_url":"https://github.com/TechAtlasDev/pyceptron","commit_stats":null,"previous_names":["techatlasdev/perceptron","techatlasdev/pyceptron"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TechAtlasDev/pyceptron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechAtlasDev%2Fpyceptron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechAtlasDev%2Fpyceptron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechAtlasDev%2Fpyceptron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechAtlasDev%2Fpyceptron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TechAtlasDev","download_url":"https://codeload.github.com/TechAtlasDev/pyceptron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechAtlasDev%2Fpyceptron/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262468436,"owners_count":23316114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-06T01:39:47.447Z","updated_at":"2025-06-28T17:30:38.295Z","avatar_url":"https://github.com/TechAtlasDev.png","language":"Python","readme":"# 🧠 Pyceptron\n\n![PyPI Version](https://img.shields.io/pypi/v/pyceptron.svg)\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)\n![Development Status](https://img.shields.io/badge/status-pre--alpha-red)\n![GitHub Stars](https://img.shields.io/github/stars/TechAtlasDev/pyceptron.svg?style=social)\n![NumPy](https://img.shields.io/badge/numpy-1.21.0%2B-blue?logo=numpy\u0026logoColor=white)\n![Matplotlib](https://img.shields.io/badge/matplotlib-3.4.0%2B-blue?logo=matplotlib\u0026logoColor=white)\n![Poetry](https://img.shields.io/badge/poetry-1.2.0%2B-blue?logo=poetry\u0026logoColor=white)\n![TermPyX](https://img.shields.io/badge/TermPyX-v1.0-orange)\n\n![Perceptron vs Dataset](image-6.png)\n\n**Pyceptron** es una librería open-source desarrollada con el objetivo de desarrollar, analizar y demostrar muchos conceptos que un perceptrón nos ofrece, a base de una arquitectura minimalista y muy fácil de desarrollar.\n\n## 🖥️ Instalación\n\nPuedes instalar la librería usando el comando\n\n```bash\npip install pyceptron\n```\n\nO puedes usar poetry con\n\n```bash\npoetry add pyceptron\n```\n\n## 🎯 Uso básico\n\nLa librería fue diseñada para que puedas implementar de manera fácil y rápida tus soluciones!\n\n```python\n# Importar las librerías\nfrom pyceptron import PerceptronClassic\nfrom pyceptron import Linear\n\nfrom ... import dataset # Importa tu dataset\n\n# Creando el perceptron\nperceptron = PerceptronClassic(\n  f_activation=Linear(),\n  input_units=1\n)\n\nperceptron.train(\n  x=dataset.x, y=dataset.y, alpha=0.01, epochs=20\n)\n\n# -- Evaluando perceptron --\nx_test = 100\ny_pred = perceptron.predict(x_test)\n\nprint (f\"Predicción de {x_test} -\u003e Predicho: {y_pred}\")\n```\n\n![Home](image-7.png)\n\n## ⚒️ Funciones extra\n\n**Pyceptron** va más allá de un simple `train()` y `predict()`. Incluye herramientas potentes para que entiendas a fondo el proceso de aprendizaje:\n\n### Generadores de Datasets `(pyceptron.utils.generators)`\n\nNo necesitas preparar tus datos manualmente. **Pyceptron** te permite crear datasets personalizados con relaciones matemáticas predefinidas, perfectos para experimentar y validar el comportamiento de los perceptrones.\n\nLa clase base `DatasetGenerator` ofrece una implementación robusta para la creación de conjuntos de datos. Permite definir la **cantidad** de puntos, el **rango** de los valores de entrada (`x`), y opcionalmente **barajar** los datos. Es fundamental destacar que, al barajar (`shuffle=True`), la librería asegura que los **pares (X, Y) se mantengan intactos**, preservando la relación subyacente del dataset. Esto evita los problemas de divergencia catastrófica que ocurren cuando `X` y `Y` son aleatorizados independientemente.\n\nPuedes definir tus propios generadores heredando de `DatasetGenerator` y simplemente proporcionando la función matemática deseada:\n\n```Python\nfrom pyceptron.utils.generators.base import DatasetGenerator\n\n# --- Ejemplos de Generadores Incluidos ---\n\n# Generador de datos para la conversión Celsius a Fahrenheit (relación lineal)\nclass Celsius2FahrenheitGenerator(DatasetGenerator):\n  def __init__(self, function=lambda x : x * 9/5 + 32):\n    super().__init__(function=function) # Llama al constructor de la base\n\n# Generador de datos para una relación lineal diferente\nclass Equation1Generator(DatasetGenerator):\n  def __init__(self, function=lambda x : x * 251 - 220):\n    super().__init__(function=function)\n\n# Generador de datos para una relación parabólica (no lineal)\nclass Parabola1Generator(DatasetGenerator):\n  def __init__(self, function=lambda x : x**2 + x*3 + 5):\n    super().__init__(function=function)\n```\n\n**Ejemplos de Uso:**\n\n```Python\nfrom pyceptron.utils.generators import Celsius2FahrenheitGenerator, Parabola1Generator\n\n# Generar datos para la conversión Celsius a Fahrenheit\ncelsius_generator = Celsius2FahrenheitGenerator()\nx_celsius, y_celsius = celsius_generator.generate(quantity=100, range_start=-50, range_end=50, shuffle=True)\n\n# Generar datos para una relación parabólica\nparabola_generator = Parabola1Generator()\nx_parabola, y_parabola = parabola_generator.generate(quantity=100, range_start=-10, range_end=10)\n\n# Puedes obtener el valor esperado para cualquier entrada, manteniendo la coherencia\nexpected_f = celsius_generator.expected(25) # Devuelve 77.0\n\n# Los generadores también incluyen métodos para visualizar los datos:\ncelsius_generator.graph() # Grafica la relación X vs Y\ncelsius_generator.graph_x() # Grafica la distribución de X\ncelsius_generator.graph_y() # Grafica la distribución de Y\n```\n\n![Dataset Analysis X](image-4.png)\n![Dataset Analysis Y](image-5.png)\n\nEstos generadores son cruciales para probar cómo tus perceptrones se adaptan a diferentes tipos de problemas *(lineales vs. no lineales)* y para investigar el impacto del orden de los datos.\n\n### Analizador de Rendimiento `(pyceptron.utils.analyzer)`\nEl `Analyzer` es tu laboratorio de depuración y visualización. Te permite una introspección profunda del proceso de entrenamiento del perceptrón.\n\n- **Monitoreo del Error:** Visualiza el historial del error promedio y el Error Cuadrático Medio (MSE) a lo largo de las épocas, dándote una idea clara de la convergencia (o divergencia) del modelo.\n\n![Error History](image.png)\n![MSE](image-1.png)\n\n- **Historial de Hiperparámetros:** Observa cómo evolucionan los pesos y el bias del perceptrón durante el entrenamiento. Esto es invaluable para entender el proceso de optimización.\n\n![Weights History](image-2.png)\n![Bias History](image-3.png)\n\n- **Comparación de Datos:** Gráfica las predicciones del perceptrón frente a la \"línea de frontera\" real de tus datos, permitiendo un diagnóstico visual inmediato del rendimiento del modelo.\n\n- **Resumen Detallado:** Obtén un desglose en consola de las métricas clave y los hiperparámetros finales del perceptrón.\n\n```Python\nfrom pyceptron import PerceptronClassic, Linear\nfrom pyceptron.utils.generators import Celsius2FahrenheitGenerator\nfrom pyceptron.utils.analyzer import Analyzer\nfrom pyceptron.enums.middleware_training_monolayer import MiddlewareTrainingMonolayer\n\n# ... (código de creación del dataset y perceptrón, como en el \"Uso Básico\") ...\n\n# Instancia el analizador con tu perceptrón\nanalyzer = Analyzer(perceptron)\n\n# Configura el perceptrón para que el analizador recolecte datos durante el entrenamiento\nperceptron.in_training(\n  analyzer=analyzer,\n  options=[\n    MiddlewareTrainingMonolayer.HISTORY_WEIGHTS, # Recolectar historial de pesos\n    MiddlewareTrainingMonolayer.HISTORY_BIASES,  # Recolectar historial de bias\n  ]\n)\n\n# ... (entrenamiento del perceptrón) ...\n\n# Usa las funciones del analizador para visualizar y depurar:\nanalyzer.mse()\nanalyzer.error()\nanalyzer.history_weights()\nanalyzer.history_bias()\nanalyzer.compare_graph(generator)\nanalyzer.debug()\n```\n\nEsta herramienta es vital para comprender la estabilidad, la convergencia y las posibles anomalías en el aprendizaje, como se demostró en nuestros [laboratorios de comparación entre perceptrones](https://github.com/TechAtlasDev/pyceptron/tree/main/tests/monocapa).\n\n### Persistencia de Modelos\n\nGuarda y carga tus perceptrones entrenados fácilmente para evitar reentrenamientos y para usar tus modelos en aplicaciones:\n\n```Python\nfrom pyceptron.utils import load_perceptron\n\nroute = \"perceptrones/perceptron.json\"\n\nperceptron = load_perceptron(route)\nprint (perceptron.predict(0))\n```\n\n## 📐 Arquitectura del proyecto\n\nPyceptron está diseñado con la modularidad como pilar central, permitiendo una fácil comprensión y extensibilidad.\n\n- `pyceptron/factivations`: Contiene implementaciones de diversas funciones de activación (lineales y no lineales).\n\n- `pyceptron/objects/perceptrons`: Aquí residen las definiciones de los modelos de perceptrones.\n\n  - `models/`: Define las clases base abstractas para garantizar una interfaz coherente.\n  - `pieces/`: Componentes reutilizables como la lógica central y el exportador/importador de modelos. Dentro de `trainers/` encontrarás las implementaciones de los algoritmos de entrenamiento específicos (clásico, gradiente).\n  - `variants/`: Las implementaciones concretas de los perceptrones (`PerceptronClassic`, `PerceptronGradient`) que combinan la base del perceptrón con los distintos entrenadores usando herencia múltiple.\n- `pyceptron/objects/layers`: Aunque actualmente enfocado en perceptrones monocapa, la presencia de `layer.py` y `sequential.py` anticipa futuras extensiones para redes neuronales multicapa.\n- `pyceptron/utils`: Utilidades esenciales para el ecosistema:\n  - `analyzer/:` El motor detrás de las herramientas de análisis y visualización.\n  - `generators/`: Herramientas para crear datasets de prueba con diferentes relaciones matemáticas.\n  - `loaders/`: Funcionalidad para cargar modelos guardados.\n- `pyceptron/enums`: Enumeraciones para gestionar opciones internas de manera clara, como las opciones de recolección de datos del middleware durante el entrenamiento.\n\nEsta estructura promueve la **separación de responsabilidades**, haciendo que cada parte del código sea más manejable y el proyecto sea altamente escalable para futuras características.\n\n## 🤝 Contribuciones\n¡Las contribuciones son bienvenidas! Si deseas contribuir, por favor sigue estos pasos:\n\n1. Haz un fork del repositorio.\n2. Crea una rama (`git checkout -b feature/nueva-feature`).\n3. Realiza tus cambios y haz un commit (`git commit -am 'Añadir nueva-feature'`).\n4. Haz un push a la rama (`git push origin feature/nueva-feature`).\n5. Abre un Pull Request.\n\n## 💡 Anatomía del perceptrón monocapa\nPronto un artículo científico será publicado que buscará sustentar la arquitectura del proyecto y evidenciará diferentes tipos de análisis en el comportamiento del perceptrón monocapa.\n\n## 📝 Licencia\nEste proyecto está licenciado bajo la Licencia MIT. Consulta el archivo [LICENSE](LICENSE) para más detalles.\n\n## 📬 Contacto\nPara cualquier pregunta o sugerencia, por favor abre un issue en el repositorio o contacta a gjimenezdeza@gmail.com.\n\n¡Gracias por usar Pyceptron! 🚀","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechatlasdev%2Fpyceptron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechatlasdev%2Fpyceptron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechatlasdev%2Fpyceptron/lists"}