Introduce trainer module and refactor public APIs and docs

[chaoming0625]

Summary

Testing

• pytest
• pre-commit run --all-files
• other (describe):

Checklist

• docs updated as needed
• changelog entry (if user-facing)
• linked issue: closes #

Notes

Summary by Sourcery

Introduce a high-level training framework and reorganize public APIs across core submodules.

New Features:

• Add a Trainer framework with Lightning-style modules, callbacks, loggers, data loaders, distributed strategies, checkpointing, and progress utilities for JAX/brainstate models.

Enhancements:

• Refine public APIs and exports for visualize, surrogate, quad, metric, input, optim, init, conn, and file submodules, providing richer user-facing docstrings and clearer, curated symbol lists.
• Simplify braintools top-level exports to expose trainer utilities and explicit spike encoder/operation functions while dropping the param subpackage from the public API.
• Improve file I/O abstractions by formalizing MATLAB loading and msgpack-based checkpoint helpers as the public file interface.

Documentation:

• Add extensive module-level documentation and usage examples for visualization, surrogate gradients, integration schemes, metrics, input generation, optimization, initialization, connectivity, file I/O, and the new training framework.

Tests:

• Add trainer module tests covering LightningModule, DataLoader, callbacks, loggers, distributed strategy selection, checkpointing helpers, and a simple end-to-end training loop.
• Update matfile tests to import the internal implementation module directly.

[sourcery-ai]

Sorry @chaoming0625, your pull request is larger than the review limit of 150000 diff characters

[chaoming0625]

@sourcery-ai title

[chaoming0625]

@sourcery-ai summary