feat: model metadata attributes & source generator infrastructure (#956)

[ooples]

Summary

• Closes Annotate all ~700 model classes with metadata attributes #958: Annotate all concrete IFullModel implementations (~2100+ classes) with metadata attributes (ModelDomain, ModelCategory, ModelTask, ModelComplexity, ModelInput, ModelPaper).
• Closes Validation Generator: enforce model metadata attributes and documentation #959: Add ModelMetadataValidationGenerator — a Roslyn incremental source generator that auto-discovers all concrete IFullModel implementations via AllInterfaces chain traversal and emits AIDN001/010-012/020 diagnostics for missing attributes and documentation.
• Closes Registry Generator: auto-generate ModelMetadataRegistry from attributes #960: Add ModelRegistryGenerator — a Roslyn incremental source generator that auto-generates a static ModelMetadataRegistry class at compile time with zero runtime reflection. Includes query methods (GetByDomain, GetByCategory, GetByTask, GetByComplexity, GetByTypeName, GetByClassName).
• Closes Annotate Diffusion models with metadata attributes (~343 models) #967: Annotate all Diffusion models (~343 classes) across TextToImage, Video, FastGeneration, ImageEditing, Control, Distillation, ThreeD, Audio, SuperResolution, StyleTransfer, VAE, Panorama, VirtualTryOn, MotionGeneration, and Alignment subdirectories.
• Closes Annotate Vision-Language models with metadata attributes (~166 models) #968: Annotate all Vision-Language models (~170 classes) across InstructionTuned, Encoders, Generative, Document, Grounding, Foundational, VideoLanguage, Unified, and remaining subdirectories.
• Closes Annotate Computer Vision models with metadata attributes (~106 models) #973: Annotate all Computer Vision models (~99 classes) across Segmentation, Detection, OCR, and Tracking subdirectories.

Non-model directories clarified

• Annotate Federated Learning models with metadata attributes (~159 models) #969 (FederatedLearning) and Annotate RAG models with metadata attributes (~116 models) #972 (RAG) — These directories contain strategy/utility/infrastructure classes (aggregation strategies, chunking strategies, retrievers, etc.) that do NOT implement IFullModel. Model metadata attributes were removed from these 299 non-model classes. These issues should be closed as "not applicable" since there are no model classes to annotate.

Also included (partial coverage of other issues)

• Create model metadata attributes and enums, remove ModelType enum #957 (partial): Attributes and enums created. ModelType enum removal deferred to follow-up.
• Additional annotations across Audio, NeuralNetworks, Finance, Classification, Regression, Clustering, TimeSeries, AnomalyDetection, CausalDiscovery, CausalInference, SurvivalAnalysis, ActiveLearning, AdversarialRobustness, SelfSupervisedLearning, Safety, SpeechRecognition, TextToSpeech, Video, and Agents directories.

Key Design Decisions

• Fully automated model discovery: Both generators use Roslyn's AllInterfaces to recursively walk the entire inheritance chain from any class back to IFullModel<,,>. No hardcoded list of base types.
• net471 compatible: Generated registry uses constructors (not init accessors) for .NET Framework compatibility.
• Only annotate IFullModel implementations: Model metadata attributes are reserved for concrete classes that implement IFullModel. Strategy, utility, and infrastructure classes do not get annotations.
• Multiple attributes: Models spanning multiple domains/categories/tasks have multiple [ModelDomain], [ModelCategory], and [ModelTask] attributes (e.g., VisionLanguage models have both Vision and Language domains).

Remaining Work (follow-up issues)

• Create model metadata attributes and enums, remove ModelType enum #957 remainder — Remove ModelType enum (deferred until annotations provide replacement)
• Documentation Generator: auto-generate beginner-friendly model catalog and guides #961 — Documentation Generator
• feat: Discovery API Generator - strongly-typed model query methods #962 — Discovery API Generator
• feat: Compatibility Matrix Generator - model/optimizer/loss function compatibility #963 — Compatibility Matrix Generator
• feat: Test Scaffold Generator - warn on untested models, generate skeleton tests #964 — Test Scaffold Generator

Test plan

• dotnet build src/AiDotNet.csproj --framework net10.0 -c Release — 0 errors
• dotnet build src/AiDotNet.csproj --framework net471 -c Release — 0 errors
• Generator discovers concrete IFullModel implementations
• No null-forgiving operators used anywhere
• All IFullModel implementations have required attributes
• Non-model classes (strategies, utilities) do NOT have model attributes

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aidotnet_website	Ready	Preview, Comment	Mar 13, 2026 5:40pm
aidotnet-playground-api	Ready	Preview, Comment	Mar 13, 2026 5:40pm

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Extensive updates across causal discovery algorithms (Bayesian, constraint-based, score-based, deep/continuous/time-series) introduce NOTEARS-based acyclicity, multivariate OLS weight estimation, stricter validations, and configuration handling. A new ModelRegistryGenerator is added. Broad metadata attributes decorate many models (vision, diffusion, anomaly detection, etc.). Several algorithms gain seeded RNG, thresholds, and constructor/option handling.

Changes

Cohort / File(s)	Summary
Source Generator src/AiDotNet.Generators/ModelRegistryGenerator.cs	Added ModelRegistryGenerator with Initialize; simplified XML-doc whitespace normalization.
Bayesian Causal Discovery src/CausalDiscovery/Bayesian/BCDNetsAlgorithm.cs, .../BayesDAGAlgorithm.cs, .../OrderMCMCAlgorithm.cs, .../IterativeMCMCAlgorithm.cs, .../PartitionMCMCAlgorithm.cs	Integrated NOTEARS h(P)=tr(exp(P∘P))−d with Taylor exp; new acyclicity gradients and augmented Lagrangian updates; multivariate OLS in OrderMCMC; safety default NumSamples.
Constraint-Based Causal Discovery src/CausalDiscovery/ConstraintBased/CDNODAlgorithm.cs, .../CPCAlgorithm.cs, .../FastIAMBAlgorithm.cs, .../IAMBAlgorithm.cs, .../RFCIAlgorithm.cs, .../FCIAlgorithm.cs	Expanded Meek rules and collider semantics; edge inclusion logic tweaks; argument validation in RFCI; added metadata attributes to FCI (declarative).
Score-Based Causal Discovery src/CausalDiscovery/ScoreBased/BOSSAlgorithm.cs, .../ExactSearchAlgorithm.cs, .../GRaSPAlgorithm.cs, .../K2Algorithm.cs	Shifted to joint multivariate OLS for edge weights; localized parent updates; added small-system solvers; BOSS uses variance-based init and stable reordering.
Continuous Optimization Causal src/CausalDiscovery/ContinuousOptimization/CORLAlgorithm.cs, .../MCSLAlgorithm.cs, .../NOTEARSLowRank.cs, .../NOTEARSSobolev.cs, .../NoCurlAlgorithm.cs	Input validation and seeded RNG; configurable ranks/iterations/penalties; implemented NoCurl workflow; consistent tau usage; Sobolev seeding.
Deep Causal Discovery src/CausalDiscovery/DeepLearning/*Algorithm.cs, src/CausalDiscovery/DeepLearning/DeepCausalBase.cs	Adopted NOTEARS acyclicity and gradients; expanded backprop paths; asymmetric/source-target embeddings; standardized hidden units; edge threshold moved to DeepCausalBase; seeded RNG in some models.
Hybrid Causal Discovery src/CausalDiscovery/Hybrid/GFCIAlgorithm.cs, .../H2PCAlgorithm.cs, .../PCNOTEARSAlgorithm.cs, .../RSMAX2Algorithm.cs, .../MMHCAlgorithm.cs	Multivariate partial correlation via OLS; proximal update + DAG enforcement; multi-predictor residualization; metadata attributes for MMHC.
Functional Causal Discovery src/CausalDiscovery/Functional/CCDrAlgorithm.cs, .../IGCIAlgorithm.cs, .../RCDAlgorithm.cs	Configurable MCP concavity; tie-aware uniformization; MI computation replaced with entropy-based estimator; stricter input validation.
Information-Theoretic Causal src/CausalDiscovery/InformationTheoretic/KraskovMIAlgorithm.cs, .../OCSEAlgorithm.cs, .../TransferEntropyAlgorithm.cs	Constructor and data validations; undirected MI emission; robust KSG counts; centered regress-out in OCSE; TE uses MaxLag and throws on invalid inputs.
Time-Series Causal Discovery src/CausalDiscovery/TimeSeries/*Algorithm.cs	New thresholds and validations (CCM, LPCMCI, TSFCI, NeuralGranger); NTSNOTEARS adopts joint W/A optimization and new aggregation; TiMINo returns (hsic,beta) and uses beta for weights; DYNOTEARS metadata added.
Causal Base Utilities src/CausalDiscovery/CausalDiscoveryBase.cs	Dimension checks in MatMul/MatVecMul; Engine visibility tightened to private protected.
Anomaly Detection (Metadata) src/AnomalyDetection/*/*.cs	Added ModelDomain/Category/Task/Complexity/Input/Paper attributes; no logic changes.
Computer Vision OCR/Segmentation (Metadata) src/ComputerVision/OCR/.../*.cs, src/ComputerVision/Segmentation/*/*.cs	Added extensive model metadata attributes across OCR and segmentation families; no functional edits.
Diffusion Suite (Metadata) src/Diffusion/**/*.*	Widespread addition of model metadata attributes across diffusion models, conditioning, control, guidance, distillation, fast generation, audio, and utilities; a few classes add GetOptions; no behavioral changes otherwise.
Selector (Metadata) src/CausalDiscovery/CausalDiscoverySelector.cs	Added multiple model metadata attributes to selector class.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~180 minutes

Possibly related issues

• Annotate Diffusion models with metadata attributes (~343 models) #967 — Broad addition of model metadata attributes matches the extensive attribute decorations in this PR.
• Epic: Model Metadata Attributes & Source Generator Infrastructure #956 — New ModelRegistryGenerator and attributes align with the source-generator-based model registry effort.
• Validation Generator: enforce model metadata attributes and documentation #959 — XML-doc normalization in ModelRegistryGenerator relates to validation of documentation during generation.
• Create model metadata attributes and enums, remove ModelType enum #957 — Generator integration to discover/register model attributes directly supports this attribute rollout.
• Registry Generator: auto-generate ModelMetadataRegistry from attributes #960 — Auto-generating ModelMetadataRegistry from attributes/XML docs is impacted by the new generator and cleaned XML.
• feat: Discovery API Generator - strongly-typed model query methods #962 — Changes in the generator affect discovery API generation that consumes model attributes and docs.

Possibly related PRs

• feat: annotate model classes with metadata attributes (#958) #984 — Adds model metadata attributes broadly; complements this PR’s generator and attribute processing changes.

Suggested labels

feature

Poem

Graphs learn to dance with cycles kept at bay,
OLS hums in chorus, weights find their way.
Seeds set the dice, rules whisper “Meek.”
Metadata stars light models we seek.
From vision to diffusion—big bang today! 🌌✨

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/model-domain-attributes

[Copilot]

Pull request overview

This PR introduces the foundational “model metadata” surface area (enums + attributes) and adds Roslyn incremental source generators to (a) validate metadata presence/documentation and (b) generate a compile-time model metadata registry intended to avoid runtime reflection.

Changes:

• Added ModelDomain/Category/Task/Complexity enums with XML docs and corresponding attribute types (Model*Attribute, plus ModelInputAttribute and ModelPaperAttribute).
• Added two incremental generators: ModelMetadataValidationGenerator (AIDN diagnostics) and ModelRegistryGenerator (emits ModelMetadataRegistry.g.cs).
• Updated AiDotNet.csproj to suppress AIDN diagnostics via NoWarn until model annotations land; added analyzer release tracking files to the generator project.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/Enums/ModelDomain.cs	New domain enum with beginner-friendly XML docs.
src/Enums/ModelCategory.cs	New category enum with XML docs.
src/Enums/ModelTask.cs	New task enum with XML docs.
src/Enums/ModelComplexity.cs	New complexity enum with XML docs.
src/Attributes/ModelDomainAttribute.cs	New attribute for domain tagging.
src/Attributes/ModelCategoryAttribute.cs	New attribute for single category tagging.
src/Attributes/ModelTaskAttribute.cs	New multi-use attribute for task tagging.
src/Attributes/ModelComplexityAttribute.cs	New attribute for complexity tagging.
src/Attributes/ModelInputAttribute.cs	New attribute for input/output type declaration.
src/Attributes/ModelPaperAttribute.cs	New attribute for paper references.
src/AiDotNet.Generators/ModelMetadataValidationGenerator.cs	Generator emitting AIDN diagnostics for missing metadata/docs/URLs.
src/AiDotNet.Generators/ModelRegistryGenerator.cs	Generator emitting ModelMetadataRegistry from discovered model symbols/attributes.
src/AiDotNet.Generators/AnalyzerReleases.Shipped.md	Analyzer release tracking scaffold.
src/AiDotNet.Generators/AnalyzerReleases.Unshipped.md	Records newly introduced AIDN rules.
src/AiDotNet.Generators/AiDotNet.Generators.csproj	Adds analyzer release tracking files as AdditionalFiles.
src/AiDotNet.csproj	Suppresses AIDN diagnostics via NoWarn in Debug/Release.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 7

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/AiDotNet.csproj`:
- Around line 26-27: The project currently suppresses analyzer IDs via the
NoWarn MSBuild property (NoWarn contains
AIDN001;AIDN010;AIDN011;AIDN012;AIDN020), which hides them entirely; change
those IDs from NoWarn into WarningsNotAsErrors so they remain visible as
warnings while not being elevated to errors when TreatWarningsAsErrors is true;
update both PropertyGroup entries (the Debug and Release groups that contain
NoWarn) to remove the AIDN IDs from NoWarn and add them to WarningsNotAsErrors,
ensuring the analyzer IDs are preserved exactly
(AIDN001;AIDN010;AIDN011;AIDN012;AIDN020).

In `@src/AiDotNet.Generators/ModelMetadataValidationGenerator.cs`:
- Around line 175-183: The loop in ModelMetadataValidationGenerator is
validating the same INamedTypeSymbol multiple times because Collect() returns
one entry per partial declaration; deduplicate candidates before calling
ValidateRequiredAttributes/ValidatePaperUrls/ValidateXmlDocumentation by
creating a HashSet using SymbolEqualityComparer.Default (or the same seen logic
used in ModelRegistryGenerator) and only iterate over unique modelClass symbols
so each model emits diagnostics once.
- Around line 276-288: The generator currently only treats presence of
"<example>" in xmlDoc as a usage example, causing false positives when authors
use a "<code>" block inside "<remarks>"; update the check in
ModelMetadataValidationGenerator so it reports MissingExample only when neither
an "<example>" tag nor a "<remarks>" tag containing a "<code>" tag is present
(i.e., change the condition that references xmlDoc and the MissingExample
diagnostic to allow xmlDoc.Contains("<example>") OR
(xmlDoc.Contains("<remarks>") && xmlDoc.Contains("<code>"))); keep the same
context.ReportDiagnostic call and location/className parameters.

In `@src/AiDotNet.Generators/ModelRegistryGenerator.cs`:
- Around line 277-290: ExtractXmlElement is currently cleaning XML before
isolating the BeginnerGuide portion, causing nested tags like </b> or </para> to
be removed and preventing correct detection of the beginner-only boundaries;
update the logic in ExtractXmlElement (and the code handling BeginnerGuide
extraction) to first slice the raw xml to isolate the "For Beginners" section
(searching for the raw markers like "For Beginners" and the closing tags inside
the uncleaned substring) and only call CleanXmlText once on that final sliced
text (remove intermediate CleanXmlText calls that strip tags before you locate
end markers). Ensure you reference the ExtractXmlElement method and the
BeginnerGuide extraction code path so the slicing happens on the original xml
and cleaning happens once after isolation.
- Around line 494-556: BuildLookups has a race because it only checks _byDomain
and assigns the dictionaries without synchronization; fix by making BuildLookups
atomic using a private static readonly object _lookupsLock and wrapping the
method body in lock(_lookupsLock) so the null check and assignment of _byDomain,
_byCategory, _byTask, _byComplexity, and _byTypeName happen under the same lock
(or alternatively check all fields and only return if all are non-null); update
BuildLookups to use this lock and ensure the fields are either all set together
inside the lock or _byDomain is assigned last if you choose the assign-order
approach.
- Around line 394-406: Change the generated accessibility of the generator
plumbing types from public to internal so they are not part of the public API:
replace public with internal for the ModelPaperEntry type (and its constructor
and any generated member accessors like Title, Url, Year, Authors), and do the
same for ModelMetadataEntry and ModelMetadataRegistry (including constructors,
properties and any IReadOnlyList/ backing-array exposures) so the entire
AiDotNet.Generated surface is internal-only rather than public.

In `@src/Attributes/ModelInputAttribute.cs`:
- Around line 38-42: The ModelInputAttribute constructor currently assigns
InputType and OutputType without null checks; add defensive validation in the
ModelInputAttribute(Type inputType, Type outputType) constructor to throw
ArgumentNullException for null inputType or outputType (use
ArgumentNullException.ThrowIfNull(inputType/ outputType) when targeting modern
.NET, or the classic inputType ?? throw new
ArgumentNullException(nameof(inputType)) pattern if ThrowIfNull isn't available)
so InputType and OutputType are never set to null.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 67d7a93f-4484-4914-99bb-f16ab9436411

📥 Commits

Reviewing files that changed from the base of the PR and between cfa9bd1 and 7b51f2f.

📒 Files selected for processing (16)

• src/AiDotNet.Generators/AiDotNet.Generators.csproj
• src/AiDotNet.Generators/AnalyzerReleases.Shipped.md
• src/AiDotNet.Generators/AnalyzerReleases.Unshipped.md
• src/AiDotNet.Generators/ModelMetadataValidationGenerator.cs
• src/AiDotNet.Generators/ModelRegistryGenerator.cs
• src/AiDotNet.csproj
• src/Attributes/ModelCategoryAttribute.cs
• src/Attributes/ModelComplexityAttribute.cs
• src/Attributes/ModelDomainAttribute.cs
• src/Attributes/ModelInputAttribute.cs
• src/Attributes/ModelPaperAttribute.cs
• src/Attributes/ModelTaskAttribute.cs
• src/Enums/ModelCategory.cs
• src/Enums/ModelComplexity.cs
• src/Enums/ModelDomain.cs
• src/Enums/ModelTask.cs

[Copilot]

Pull request overview

Copilot reviewed 251 out of 251 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.