Epic: Model Metadata Attributes & Source Generator Infrastructure

[ooples]

Epic: Model Metadata Attributes & Source Generator Infrastructure

Problem

When building wizard/catalog UIs that need to categorize models by application domain (Healthcare, Robotics, Graph Neural Networks, Multimodal), the only metadata available from AiDotNet is the algorithm category via the ModelType enum (~280 entries, wildly outdated, doesn't cover the ~700+ models in the library).

Algorithm categories don't map cleanly to application domains:

• SurvivalAnalysis models can be used for drug discovery (Healthcare) OR general survival prediction
• ReinforcementLearning models can be for robotics control OR game playing
• NeuralNetwork includes graph neural networks, standard feedforward nets, and many other architectures
• VisionModel + LanguageModel together = Multimodal, but that relationship isn't expressed

Currently the only option is fragile string matching on class names, which is unreliable and not production-ready.

---

Decisions Made

1. Use attributes (not a registry) - attributes are the source of truth, applied directly to each concrete model class
2. No inheritance from base classes - every concrete model must be explicitly annotated
3. Clean replacement of ModelType enum - no backward compatibility needed (no downstream consumers use it)
4. 6 core attributes agreed upon (see below)
5. Source generators will validate, collect, and document all model metadata at compile time
6. All ~700 models must be annotated in a single PR per child issue
7. Beginner-friendly documentation is mandatory for every model and enforced by generators

---

6 Model Attributes

1. [ModelDomain(ModelDomain.Vision)] - Application Domain

What field/industry/area the model is applicable to. AllowMultiple = true.

Enum values:
General, Vision, Language, Audio, Video, Multimodal, Healthcare, Finance, Science, Robotics, GraphAnalysis, ThreeD, Tabular, TimeSeries, Generative, ReinforcementLearning, Causal

2. [ModelCategory(ModelCategory.NeuralNetwork)] - Algorithm Family

Replaces the ModelType enum. What kind of algorithm this is.

Enum values:
NeuralNetwork, Regression, Classifier, Clustering, GAN, Diffusion, Transformer, ReinforcementLearningAgent, GaussianProcess, Ensemble, Bayesian, SurvivalModel, CausalModel, TimeSeriesModel, Autoencoder, RecurrentNetwork, ConvolutionalNetwork, GraphNetwork, EmbeddingModel, FoundationModel, MetaLearning, TabularModel, SyntheticDataGenerator, PhysicsInformed, NeuralOperator, Agent

3. [ModelTask(ModelTask.Classification)] - What It Does

The actual task the model performs. AllowMultiple = true.

Enum values:
Classification, Regression, Generation, Segmentation, Detection, Embedding, Translation, Forecasting, Clustering, Denoising, SuperResolution, StyleTransfer, Inpainting, SpeechRecognition, TextToSpeech, SourceSeparation, AnomalyDetection, Recommendation, Ranking, DepthEstimation, OpticalFlow, Tracking, ActionRecognition, ImageEditing, TextToImage, TextToVideo, ThreeDGeneration, MotionGeneration, SurvivalAnalysis, CausalInference, Synthesis, FeatureExtraction, Restoration, Compression, FrameInterpolation

4. [ModelComplexity(ModelComplexity.High)] - Compute Requirements

Helps users understand resource needs.

Enum values:
Low, Medium, High, VeryHigh

5. [ModelInput(typeof(Tensor<>))] - Expected Input Type

Declares I/O types for discoverability without instantiation.

6. [ModelPaper("Attention Is All You Need", "https://arxiv.org/abs/1706.03762")] - Academic Reference

Paper name and URL for documentation and credibility.

---

Source Generator Infrastructure

A. Validation Generator

• Required attributes: Compile error if any concrete model class is missing [ModelDomain], [ModelCategory], [ModelTask], [ModelComplexity], [ModelInput]
• XML doc enforcement: Warning if model class is missing <summary>, <remarks> with For Beginners content, <example> usage blocks
• Public method docs: Warning if public methods lack XML doc and <param> docs
• Paper URL validation: Warning if [ModelPaper] URL is not well-formed (must start with https://)
• Domain/Task consistency: Warning if domain and task don't logically match (e.g., Vision domain with no vision-related task)

B. Registry Generator

Auto-generate a static ModelMetadataRegistry class at compile time. No reflection needed at runtime - source generator emits all metadata statically.

C. Documentation Generator

• Generate beginner-friendly markdown catalog grouped by domain, category, and task
• For each model emit: name, one-line description, complexity badge, domains, tasks, paper link, and "When to use this" blurb
• Generate a "Model Selection Guide" decision tree: "I want to do X task in Y domain" -> options sorted by complexity
• Generate comparison tables within each domain
• Generate quick-start code snippets from <example> blocks

Every model's documentation must answer:

• What is this? (plain English, no jargon)
• When should I use it? (use cases)
• When should I NOT use it? (anti-patterns, better alternatives)
• How complex is it? (maps to ModelComplexity)
• What paper introduced it? (academic credibility)
• Minimal working example (copy-paste code)

D. Model Discovery API Generator

Generate strongly-typed query methods with full IntelliSense support for model discovery by domain and task.

E. Compatibility Matrix Generator

Scan which models work with which optimizers, loss functions, and preprocessors based on generic constraints and interface implementations. Generate a compatibility reference.

F. Test Scaffold Generator

For any model class without a corresponding test class, emit a warning or optionally generate skeleton test files with basic instantiation and forward/backward smoke tests.

---

Model Inventory (~700+ models)

Approximate counts by area:

• NeuralNetworks (root): ~100 (CNNs, RNNs, GANs, Transformers, Language Models, etc.)
• NeuralNetworks/Tabular: ~15 architectures x 4 variants each
• NeuralNetworks/SyntheticData: ~30 generators
• Regression: ~55 models
• Classification: ~40+ classifiers
• TimeSeries: ~30 models
• Audio: ~120+ models across 18 subdirectories
• Video: ~100+ models across 15 subdirectories
• Diffusion: ~200+ models across 18 subdirectories
• ReinforcementLearning/Agents: ~50 agents
• Finance: ~30+ models
• GaussianProcesses: ~12 models
• CausalInference: ~7 models
• SurvivalAnalysis: ~6 models
• PhysicsInformed: ~15 models
• ComputerVision: ~5 trackers
• Agents: ~4

---

Child Issues

#	Issue	Description	Status	Dependencies
1	#957	Create model metadata attributes and enums, remove ModelType enum	Not started	None
2	#958	Annotate all ~700 model classes with metadata attributes	Not started	#957
3	#959	Validation Generator: enforce attributes and documentation	Not started	#957
4	#960	Registry Generator: auto-generate ModelMetadataRegistry	Not started	#957, #958
5	#961	Documentation Generator: beginner-friendly model catalog	Not started	#957, #958
6	#962	Discovery API Generator: strongly-typed model query methods	Not started	#957, #958
7	#963	Compatibility Matrix Generator: model/optimizer/loss compatibility	Not started	#957, #958, #960
8	#964	Test Scaffold Generator: warn on untested models	Not started	#957, #958

Suggested execution order: #957 → #958 → #959 + #960 (parallel) → #961 + #962 + #963 + #964 (parallel)

Branch

feat/model-domain-attributes

[ooples]

PR tracking

Open PRs covering this Epic:

• PR feat: remove ModelType enum, add 4 source generators (#957 #961-#964) #986 — Core infrastructure: source generators, ModelType removal, AIDN diagnostics (Closes Create model metadata attributes and enums, remove ModelType enum #957, Documentation Generator: auto-generate beginner-friendly model catalog and guides #961, feat: Discovery API Generator - strongly-typed model query methods #962, feat: Compatibility Matrix Generator - model/optimizer/loss function compatibility #963, feat: Test Scaffold Generator - warn on untested models, generate skeleton tests #964)
• PR fix: restrict optimizer defaults and add missing category rules for AIDN030 #997 — Fix optimizer defaults for all model categories, AIDN030 -> 0 errors (Fixes Fix optimizer defaults for 558 models flagged by AIDN030 #992)
• PR feat: comprehensive model integration tests with mathematical invariants #998 — Comprehensive integration tests (Fixes Comprehensive integration tests for all model classes (AIDN040) #990)

Remaining sub-issues not yet covered by PRs:

• Annotate RAG models with metadata attributes (~116 models) #972 — Annotate RAG models (~116 models)
• Annotate Federated Learning models with metadata attributes (~159 models) #969 — Annotate Federated Learning models (~159 models)

Related issues created from PR #986 work:

• Comprehensive integration tests for all model classes (AIDN040) #990 — Integration tests for ~750 models (AIDN040)
• Fix optimizer defaults for 558 models flagged by AIDN030 #992 — Optimizer defaults for models flagged by AIDN030