NIR-Hub: storing neuromorphic models online using NIR

[stevenabreu7]

Feature: NIR Hub

This PR presents a mock example for a new "NIR Hub" feature to the NIR project. The NIR Hub provides a centralized platform where researchers and developers can:

1. Upload their NIR models with metadata like tags and framework compatibility
2. Download models created by others
3. Search for models by tags, framework origin, or compatible platforms

This creates a "model zoo" for neuromorphic computing similar to PyTorch Hub or HuggingFace Hub, but specifically for cross-framework neuromorphic model sharing.

What's Included

Core Components

• Client Library (nir/hub/client.py): with upload and download
• Version Compatibility (nir/hub/version.py)
• Local Hub Server (mock) (nir/hub/server.py): REST API for model storage and retrieval, search, etc.
• Command-Line Interface (nir/hub/cli.py)

Documentation and Examples

• User Documentation (docs/source/hub.md)
• Example Code (examples/hub/)
• Tests (tests/test_hub.py)

Usage Examples

Starting a Hub Server

uv sync
uv run -m nir.hub.cli server --debug --port 8080

Uploading a Model

import nir

fname = "paper/03_rnn/braille_noDelay_bias_zero.nir"
graph = nir.read(fname)
print(f"Uploading model with nodes: {graph.nodes.keys()}")
response = nir.hub.upload(
    graph=graph,
    model_name="braille-rnn",
    description="no-delay, bias, zero",
    tags=["tactile", "classification"],
    framework_origin="snntorch",
    compatible_platforms=["norse", "nengo"],
    hub_url="http://localhost:8080",
)
print(f"Uploaded model: {response.status_code} ({response.reason})")
print(f"\nResponse:\n{response.json()}")

Downloading a Model

import nir

graph = nir.hub.download(
    model_id_or_name="braille-rnn",
    hub_url="http://localhost:8080",
)
print(f"Downloaded model with nodes: {graph.nodes.keys()}")

Searching models with the CLI

$ uv run -m nir.hub.cli search --url http://localhost:8818

Example output:

2025-04-10 18:59:45,794 - nir.hub.server - INFO - Loaded 2 models from index
Found 2 model(s):
ID: ec65f9f1-22c8-467d-83d3-0762ecc9011d
Name: braille-rnn
Description: no delay, bias, zero
Tags: demo
NIR Version: 1.0.5.dev30+g7b4a1b5.d20250410
---
ID: df702cb1-fd9f-4fff-97e1-02cc3b9a49a5
Name: braille-rnn
Description: no delay, bias, zero
Tags: demo
NIR Version: 1.0.5.dev30+g7b4a1b5.d20250410
---

Implementation Notes

• The hub server uses a simple file-based storage system
• Models are stored in HDF5 format with accompanying JSON metadata
• The server maintains a persistent index of available models
• The client library handles version compatibility checking
• Basic testing on upload/download/search functionality and CLI

Database Schema

See ./nir/hub/HUB_DATABASE.md:

erDiagram
    User ||--o{ Model : uploads
    User ||--o{ Vote : casts
    Model ||--o{ Vote : receives
    Model ||--o{ Version : has
    Model ||--o{ Tag : tagged_with
    Model ||--o{ Platform : compatible_with
    Model ||--o{ File : contains
    
    User {
        string id PK
        string username
        string email
        string name
        string organization
        string website
        string bio
        string avatar_url
        datetime created_at
        datetime last_login
        boolean is_admin
    }
    
    Model {
        string id PK
        string model_name
        string description
        string user_id FK
        string nir_version
        string framework_origin
        datetime created_at
        datetime updated_at
        int download_count
        int upvote_count
        int downvote_count
    }
    
    Version {
        string id PK
        string model_id FK
        string version_number
        string changelog
        datetime released_at
        string nir_version
    }
    
    File {
        string id PK
        string model_id FK
        string filename
        string filetype
        string description
        int size_bytes
        string content
        string path
    }
    
    Vote {
        string id PK
        string user_id FK
        string model_id FK
        boolean is_upvote
        datetime created_at
    }
    
    Tag {
        string id PK
        string name
    }
    
    ModelTag {
        string model_id FK
        string tag_id FK
    }
    
    Platform {
        string id PK
        string name
    }
    
    ModelPlatform {
        string model_id FK
        string platform_id FK
        boolean verified_compatible
    }

Loading

TODOs:

• remove flask dependency (needed only for the mock server which will not be released)
• host a real NIR Hub server - could use firebase or supabase?
• dedicated frontend with search, etc.
• add authentication for uploads
• match model naming with HuggingFace convention (org_or_user/model_id)
• allow adding documentation, examples and citations for uploaded models (e.g. with a LICENSE and README)

Things to think about:

• do we want to verify models somehow? E.g. verify they are valid, verify claimed compatibilities, etc.
• do we want to have model versioning?
• could we visualize models on the hub frontend? e.g. using mermaid or nengo
• with access to real neuromorphic hardware, we could also verify performance and efficiency metrics for models! (long shot..)

[DylanMuir]

Wow, you really slammed this one out fast! :)