N-Orca: A Markdown-based DSL for Declaring, Validating, and Visualizing Neural Network Architectures

N-Orca is a Markdown-based domain-specific language (DSL) designed to help developers and LLMs declare neural network architectures in plain text. Its core features include automatic shape consistency validation, generation of visual charts, and compilation into executable PyTorch code. The project aims to unify five key needs of architecture design—writing, reading, visualization, validation, and execution—into a single Markdown file, addressing the fragmentation of architecture descriptions in traditional deep learning workflows.

In deep learning development, neural network architecture definitions are often scattered across design documents, code, and verbal communications. This fragmentation leads to information inconsistencies, understanding biases, and high communication costs. N-Orca was created to solve this problem by leveraging Markdown (a format familiar to both developers and AI) as a unified carrier for architecture descriptions, bridging the gap between human-readable documentation and executable code.

N-Orca follows a design philosophy of 'one file, five abilities':

• Write: Using pure Markdown (LLMs can reliably generate GitHub-style tables and titles).
• Read: Chapter titles as navigation (each ## is a landmark, one line per layer).
• Visualize: Compile to Mermaid flowcharts (renderable in any Markdown reader).
• Explain: Structured error codes (e.g., SHAPE_MISMATCH, UNREACHABLE_LAYER) with repair suggestions.
• Execute: Compile to PyTorch nn.Module (only after shape matching is verified).

An example Transformer block definition in N-Orca includes sections for hyperparameters, tensors, layer definitions, data flow, and invariants (e.g., output shape constraints).

N-Orca's validation system performs five stages of static checks before code execution:

1. Naming Check: Ensures valid layer references, unique input/output layers, no duplicate layer names.
2. Structure Check: Verifies the architecture is a directed acyclic graph (DAG), all layers are reachable from input and can reach output.
3. Shape Check: Validates input shapes match operation rules and declared shapes.
4. Resource Check: Compares parameters, depth, output shape against invariants.
5. Operation Coverage Check: Ensures layers use existing operators (unknown ops generate warnings and become nn.Identity() placeholders).

Example error: SHAPE_MISMATCH for an Add layer with mismatched input shapes.

N-Orca provides a complete CLI toolchain:

• Verify: Check architecture validity (n-orca verify).
• Compile: Generate Mermaid charts or PyTorch code (n-orca compile).
• Info: View architecture details (parameters, depth).

It integrates with HuggingFace Hub (download model configs) and supports MCP servers. Installation options:

• Core: pip install n-orca
• With PyTorch: pip install "n-orca[torch]"
• All features: pip install "n-orca[all]"
• Source: Clone from GitHub and install with pip install -e ".[all]".

N-Orca is in active development. Ongoing work includes:

1. Temporal World Model Support: Add support for sequential/recurrent world models for economic SAE state transfer and window feature recovery.
2. Cosmos MoT World Models: Implement Mixture of Transformers dual-tower architecture with joint attention and diffusion time-step world model builders, supporting physical AI, multimodality, and diffusion bases.

These features expand N-Orca to handle more complex architecture patterns beyond static layer stacking.

N-Orca represents a paradigm shift: separating architecture description from code using a declarative approach. Key advantages:

• Human-AI Collaboration: Markdown allows non-technical users to understand and participate in design.
• LLM-Friendly: Structured text is easier for AI to generate/modify than Python code.
• Early Validation: Catches shape mismatches and other errors before training.
• Built-in Visualization: Architecture charts are auto-generated, not事后补充.

Trade-off: Less suitable for highly dynamic architectures (e.g., conditional computation). Recommendation: Try N-Orca if you want transparent, verifiable architecture design.