{"id":26661578,"url":"https://github.com/lemniscate-world/neural","last_synced_at":"2025-04-11T17:32:59.196Z","repository":{"id":280281208,"uuid":"934613137","full_name":"Lemniscate-world/Neural","owner":"Lemniscate-world","description":"Neural is a domain-specific language (DSL) designed for defining, training, debugging, and deploying neural networks. With declarative syntax, cross-framework support, and built-in execution tracing (NeuralDbg), it simplifies deep learning development.","archived":false,"fork":false,"pushed_at":"2025-04-06T17:49:27.000Z","size":520785,"stargazers_count":9,"open_issues_count":186,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T18:20:30.650Z","etag":null,"topics":["automation","data-science","data-visualization","diagrams","dsl","hyperparameter-optimization","lark","llms","machine-learning","neural-architecture-search","neural-networks","neural-networks-and-deep-learning","neural-networks-from-scratch","nocode","onnx","pytorch","tensorflow","visual-programming-language","visualization"],"latest_commit_sha":null,"homepage":"https://lemniscate-world.github.io/Neural/","language":"HTML","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/Lemniscate-world.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"kuroio","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-02-18T05:52:39.000Z","updated_at":"2025-04-06T17:49:30.000Z","dependencies_parsed_at":"2025-04-06T18:30:16.573Z","dependency_job_id":null,"html_url":"https://github.com/Lemniscate-world/Neural","commit_stats":null,"previous_names":["lemniscate-sha-256/neural","lemniscate-world/neural"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lemniscate-world%2FNeural","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lemniscate-world%2FNeural/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lemniscate-world%2FNeural/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lemniscate-world%2FNeural/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lemniscate-world","download_url":"https://codeload.github.com/Lemniscate-world/Neural/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248450001,"owners_count":21105599,"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":["automation","data-science","data-visualization","diagrams","dsl","hyperparameter-optimization","lark","llms","machine-learning","neural-architecture-search","neural-networks","neural-networks-and-deep-learning","neural-networks-from-scratch","nocode","onnx","pytorch","tensorflow","visual-programming-language","visualization"],"created_at":"2025-03-25T13:24:05.526Z","updated_at":"2025-04-11T17:32:54.164Z","avatar_url":"https://github.com/Lemniscate-world.png","language":"HTML","funding_links":["https://ko-fi.com/kuroio"],"categories":[],"sub_categories":[],"readme":"\n  ![N](https://github.com/user-attachments/assets/f92005cc-7b1c-4020-aec6-0e6922c36b1b)\n\n\n  ⚠️ WARNING: Neural-dsl is a WIP DSL and debugger—bugs exist, feedback welcome!\n  This project is under active development and not yet production-ready!\n\n# Neural: A Neural Network Programming Language\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-green.svg)](https://www.python.org/)\n[![Discord](https://img.shields.io/badge/Chat-Discord-7289DA)](https://discord.gg/KFku4KvS)\n[![Pylint](https://github.com/Lemniscate-SHA-256/Neural/actions/workflows/pylint.yml/badge.svg?branch=main)](https://github.com/Lemniscate-SHA-256/Neural/actions/workflows/pylint.yml)\n[![Python package](https://github.com/Lemniscate-SHA-256/Neural/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/Lemniscate-SHA-256/Neural/actions/workflows/python-package.yml)\n[![CodeQL Advanced](https://github.com/Lemniscate-SHA-256/Neural/actions/workflows/codeql.yml/badge.svg)](https://github.com/Lemniscate-SHA-256/Neural/actions/workflows/codeql.yml)\n[![Tests](https://github.com/Lemniscate-SHA-256/Neural/actions/workflows/pytest.yml/badge.svg?branch=main)](https://github.com/Lemniscate-SHA-256/Neural/actions/workflows/pytest-to-issues.yml)\n[![Coverage](https://img.shields.io/codecov/c/github/Lemniscate-SHA-256/Neural)](https://codecov.io/gh/Lemniscate-SHA-256/Neural)\n![Dev.to blog](https://img.shields.io/badge/dev.to-0A0A0A?style=for-the-badge\u0026logo=dev.to\u0026logoColor=white)\n![Medium](https://img.shields.io/badge/Medium-12100E?style=for-the-badge\u0026logo=medium\u0026logoColor=white)\n![PyPi](https://img.shields.io/badge/pypi-%23ececec.svg?style=for-the-badge\u0026logo=pypi\u0026logoColor=1f73b7)\n\n\u003ca href=\"https://www.producthunt.com/posts/neural-2?embed=true\u0026utm_source=badge-featured\u0026utm_medium=badge\u0026utm_souce=badge-neural\u0026#0045;2\" target=\"_blank\"\u003e\u003cimg src=\"https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=945073\u0026theme=dark\u0026t=1742808173867\" alt=\"Neural - DSL\u0026#0032;for\u0026#0032;defining\u0026#0044;\u0026#0032;training\u0026#0044;\u0026#0032;debugging\u0026#0032;neural\u0026#0032;networks\u0026#0046; | Product Hunt\" style=\"width: 250px; height: 54px;\" width=\"250\" height=\"54\" /\u003e\u003c/a\u003e\n\n![design-01jmphv5f1-1740433387](https://github.com/user-attachments/assets/ecbcce19-73df-4696-ace2-69e32d02709f)\n\n## 🎯 Pain Points Solved\n\nNeural addresses deep learning challenges across **Criticality** (how essential) and **Impact Scope** (how transformative):\n\n| Criticality / Impact | Low Impact                  | Medium Impact                       | High Impact                         |\n|----------------------|-----------------------------|-------------------------------------|-------------------------------------|\n| **High**             |                             |                                     | - **Shape Mismatches**: Pre-runtime validation stops runtime errors.\u003cbr\u003e- **Debugging Complexity**: Real-time tracing \u0026 anomaly detection. |\n| **Medium**           |                             | - **Steep Learning Curve**: No-code GUI eases onboarding. | - **Framework Switching**: One-flag backend swaps.\u003cbr\u003e- **HPO Inconsistency**: Unified tuning across frameworks. |\n| **Low**              | - **Boilerplate**: Clean DSL syntax saves time. | - **Model Insight**: FLOPs \u0026 diagrams.\u003cbr\u003e- **Config Fragmentation**: Centralized setup. |                                     |\n\n### Why It Matters\n- **Core Value**: Fix critical blockers like shape errors and debugging woes with game-changing tools.  \n- **Strategic Edge**: Streamline framework switches and HPO for big wins.  \n- **User-Friendly**: Lower barriers and enhance workflows with practical features.\n\nNeural is a domain-specific language (DSL) designed for defining, training, debugging, and deploying neural networks whether via code, CLI, or a no-code interface. With **declarative syntax**, **cross-framework support**, and **built-in execution tracing (NeuralDbg)**, it simplifies deep learning development.\n\n## Feedback \n\nHelp us improve Neural DSL! Share your feedback: [Typeform link](https://form.typeform.com/to/xcibBdKD#name=xxxxx\u0026email=xxxxx\u0026phone_number=xxxxx\u0026user_id=xxxxx\u0026product_id=xxxxx\u0026auth_code=xxxxx).\n\n\n\n## 🚀 Features\n\n- **YAML-like Syntax**: Define models intuitively without framework boilerplate.\n- **Shape Propagation**: Catch dimension mismatches *before* runtime.\n  - ✅ Interactive shape flow diagrams included.\n- **Multi-Framework HPO**: Optimize hyperparameters for both PyTorch and TensorFlow with a single DSL config (#434).\n- **Multi-Backend Export**: Generate code for **TensorFlow**, **PyTorch**, or **ONNX**.\n- **Training Orchestration**: Configure optimizers, schedulers, and metrics in one place.\n- **Visual Debugging**: Render interactive 3D architecture diagrams.\n- **Extensible**: Add custom layers/losses via Python plugins.\n\n### **🛠 NeuralDbg: Built-in Neural Network Debugger**\nNeuralDbg provides **real-time execution tracing, profiling, and debugging**, allowing you to visualize and analyze deep learning models in action.\n\n✅ **Real-Time Execution Monitoring** – Track activations, gradients, memory usage, and FLOPs.  \n![test_trace_graph](https://github.com/user-attachments/assets/15b1edd2-2643-4587-9843-aa4697ed2e4b)\n![test_flops_memory_chart](https://github.com/user-attachments/assets/de1f6504-787b-4948-b543-fe3d2f8bfd74)\n![test_trace_graph_stacked](https://github.com/user-attachments/assets/529fc487-fb31-48ad-bb11-b0c64ab330ed)\n![test_trace_graph_heatmap](https://github.com/user-attachments/assets/debef7d5-9989-45da-ae91-7cef19aac2b0)\n![test_anomaly_chart](https://github.com/user-attachments/assets/b57d3142-6da8-4d57-94f0-486d1797e92c)\n![test_dead_neurons](https://github.com/user-attachments/assets/f4629b4f-2988-410e-8b49-3dde225f926f)\n![test_gradient_chart](https://github.com/user-attachments/assets/ca6b9f20-7dd8-4c72-9ee8-a3f35af6208b)\n\n\n✅ **Shape Propagation Debugging** – Visualize tensor transformations at each layer.  \n✅ **Gradient Flow Analysis** – Detect **vanishing \u0026 exploding gradients**.  \n✅ **Dead Neuron Detection** – Identify inactive neurons in deep networks.  \n✅ **Anomaly Detection** – Spot **NaNs, extreme activations, and weight explosions**.  \n✅ **Step Debugging Mode** – Pause execution and inspect tensors manually.\n\n\n## 📦 Installation\n\n# Clone the repository\ngit clone https://github.com/yourusername/neural.git\ncd neural\n\n# Create a virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate  # Linux/macOS\nvenv\\Scripts\\activate     # Windows\n\n# Install dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n```bash\npip install neural-dsl\n```\n\nsee v0.2.4 for bug fixes\n\n**Prerequisites**: Python 3.8+, pip\n\n## 🛠️ Quick Start\n\n### 1. Define a Model\n\nCreate `mnist.neural`:\n\n```yaml\nnetwork MNISTClassifier {\n  input: (28, 28, 1)  # Channels-last format\n  layers:\n    Conv2D(filters=32, kernel_size=(3,3), activation=\"relu\")\n    MaxPooling2D(pool_size=(2,2))\n    Flatten()\n    Dense(units=128, activation=\"relu\")\n    Dropout(rate=0.5)\n    Output(units=10, activation=\"softmax\")\n  \n  loss: \"sparse_categorical_crossentropy\"\n  optimizer: Adam(learning_rate=0.001)\n  metrics: [\"accuracy\"]\n  \n  train {\n    epochs: 15\n    batch_size: 64\n    validation_split: 0.2\n  }\n}\n```\n\n### 3. Run Or Compile The Model\n\n```bash\nneural run mnist.neural --backend tensorflow --output mnist_tf.py\n# Or for PyTorch:\nneural run mnist.neural --backend pytorch --output mnist_torch.py\n```\n\n### 4. Visualize Architecture\n\n```bash\nneural visualize mnist.neural --format png\n```\n\nThis will create architecture.png, shape_propagation.html, and tensor_flow.html for inspecting the network structure and shape propagation.\n\n![MNIST Architecture]()\n\n### 5. Debug with NeuralDbg\n\n```bash\nneural debug mnist.neural\n```\n\nOpen your browser to http://localhost:8050 to monitor execution traces, gradients, and anomalies interactively.\n\n### 6. Use The No-Code Interface\n\n```bash\nneural --no_code\n```\n\nOpen your browser to http://localhost:8051 to build and compile models via a graphical interface.\n\n---\n\n## **🛠 Debugging with NeuralDbg**\n\n### **🔹 1️⃣ Start Real-Time Execution Tracing**\n```bash\npython neural.py debug mnist.neural\n```\n**Features:**  \n✅ Layer-wise execution trace  \n✅ Memory \u0026 FLOP profiling  \n✅ Live performance monitoring  \n\n### **🔹 2️⃣ Analyze Gradient Flow**\n```bash\npython neural.py debug --gradients mnist.neural\n```\n🚀 **Detect vanishing/exploding gradients** with interactive charts.\n\n### **🔹 3️⃣ Identify Dead Neurons**\n```bash\npython neural.py debug --dead-neurons mnist.neural\n```\n🛠 **Find layers with inactive neurons (common in ReLU networks).**\n\n### **🔹 4️⃣ Detect Training Anomalies**\n```bash\npython neural.py debug --anomalies mnist.neural\n```\n🔥 **Flag NaNs, weight explosions, and extreme activations.**\n\n### **🔹 5️⃣ Step Debugging (Interactive Tensor Inspection)**\n```bash\npython neural.py debug --step mnist.neural\n```\n🔍 **Pause execution at any layer and inspect tensors manually.**\n\n---\n\n## 🌟 Why Neural?\n\n| Feature               | Neural      | Raw TensorFlow/PyTorch |\n|-----------------------|-------------|-------------------------|\n| Shape Validation      | ✅ Auto     | ❌ Manual               |\n| Framework Switching   | 1-line flag | Days of rewriting       |\n| Architecture Diagrams | Built-in    | Third-party tools       |\n| Training Config       | Unified     | Fragmented configs      |\n\n\n### **🔄 Cross-Framework Code Generation**  \n| Neural DSL          | TensorFlow Output          | PyTorch Output            |\n|---------------------|----------------------------|---------------------------|\n| `Conv2D(filters=32)`| `tf.keras.layers.Conv2D(32)`| `nn.Conv2d(in_channels, 32)` |\n| `Dense(units=128)`  | `tf.keras.layers.Dense(128)`| `nn.Linear(in_features, 128)`|\n\n## 🏆 Benchmarks  \n| Task                 | Neural | Baseline (TF/PyTorch) |  \n|----------------------|--------|-----------------------|  \n| MNIST Training       | 1.2x ⚡| 1.0x                  |  \n| Debugging Setup      | 5min 🕒| 2hr+                  |  \n\n## 📚 Documentation\n\n- [DSL Documentation](docs/dsl.md)\n\nExplore advanced features:\n- [Custom Layers Guide]()\n- [ONNX Export Tutorial]()\n- [Training Configuration]()\n- [NeuralDbg Debugging Features]()\n\n## 📚 Examples\n\nExplore common use cases in `examples/` with step-by-step guides in `docs/examples/`:\n- [MNIST Classifier Guide](docs/examples/mnist_guide.md)\n- [Sentiment Analysis Guide](docs/examples/sentiment_guide.md)\n- [Transformer for NLP Guide](docs/examples/transformer_guide.md)\n\n## 🕸Architecture Graphs (Zoom Alot For Some🫩)\n\n![classes](https://github.com/Lemniscate-SHA-256/Neural/blob/main/classes.png)\n![packages](https://github.com/Lemniscate-SHA-256/Neural/blob/main/packages.png)\n\n\n\n---\n\n\n## 🤝 Contributing\n\nWe welcome contributions! See our:\n- [Contributing Guidelines](CONTRIBUTING.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Roadmap](ROADMAP.md)\n\nTo set up a development environment:\n```bash\ngit clone https://github.com/yourusername/neural.git\ncd neural\npip install -r requirements-dev.txt  # Includes linter, formatter, etc.\npre-commit install  # Auto-format code on commit\n```\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=Lemniscate-world/Neural\u0026type=Timeline)](https://www.star-history.com/#Lemniscate-world/Neural\u0026Timeline)\n\n## Support\nPlease give us a star ⭐️ to increase our chances of getting into GitHub trends - the more attention we get, the higher our chances of actually making a difference.\nPlease share this project with your friends! Every share helps us reach more developers and grow our community. The more developers we reach, the more likely we are to build something truly revolutionary together. 🚀\n\n## 📬 Community\n\n- [Discord Server](https://discord.gg/KFku4KvS): Chat with developers\n- [Twitter @NLang4438](https://x.com/NLang4438): Updates \u0026 announcements\n\n![N (1)](https://github.com/user-attachments/assets/9edd42b3-dd23-4f4a-baad-422e690d687c)\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flemniscate-world%2Fneural","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flemniscate-world%2Fneural","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flemniscate-world%2Fneural/lists"}