ooples
diff --git a/‎.project-rules.md‎
Lines changed: 119 additions & 0 deletions b/‎.project-rules.md‎
Lines changed: 119 additions & 0 deletions
@@ -0,0 +1,119 @@
+# AiDotNet Project Rules
+
+This document contains critical coding standards and requirements for the AiDotNet project that must be followed at all times.
+
+## JSON Serialization Library
+
+**CRITICAL REQUIREMENT:**
+
+- ✅ **ALWAYS** use `Newtonsoft.Json` (Json.NET) for JSON serialization and deserialization
+- ❌ **NEVER** use `System.Text.Json`
+
+### Rationale
+
+- Newtonsoft.Json is compatible with older versions of .NET Framework
+- System.Text.Json is not compatible with .NET Framework and will break the library for users on older frameworks
+- This is a hard requirement for maintaining backward compatibility
+
+### Correct Usage Examples
+
+```csharp
+// ✅ CORRECT - Use Newtonsoft.Json
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+
+// Parse JSON
+var json = JObject.Parse(jsonString);
+
+// Access properties
+string value = json["propertyName"]?.ToString() ?? "";
+int count = json["count"]?.ToObject<int>() ?? 0;
+
+// Create JSON
+var obj = new JObject
+{
+    ["key"] = "value",
+    ["count"] = 42
+};
+string jsonString = obj.ToString(Formatting.None);
+```
+
+### Incorrect Usage Examples
+
+```csharp
+// ❌ WRONG - Do not use System.Text.Json
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+// ❌ WRONG - These will break .NET Framework compatibility
+using JsonDocument doc = JsonDocument.Parse(input);
+JsonElement root = doc.RootElement;
+var obj = new JsonObject { ["key"] = "value" };
+string json = obj.ToJsonString();
+```
+
+## Architectural Patterns
+
+### Constructor Injection Pattern
+
+- Properties in result classes (e.g., `PredictionModelResult`) should be **internal** with **private setters**
+- All configuration should be passed through constructors, not set via properties after construction
+- This prevents users from modifying result objects after they are created
+
+### Builder Pattern with Configuration Objects
+
+- Configure methods should take a **single configuration object** parameter
+- Do not use multiple individual parameters with defaults
+- Configuration objects should have sensible defaults
+
+Example:
+```csharp
+// ✅ CORRECT
+ConfigureAgentAssistance(AgentConfiguration<T> configuration)
+
+// ❌ WRONG
+ConfigureAgentAssistance(string? apiKey = null, LLMProvider provider = LLMProvider.OpenAI, ...)
+```
+
+### Required vs Optional Parameters
+
+- Required data (like input/output data for training) should be **non-nullable** with no defaults
+- Force users to explicitly provide required data
+- Use method overloads to separate different use cases
+
+Example:
+```csharp
+// ✅ CORRECT - Two overloads for different use cases
+BuildAsync()  // For meta-learning
+BuildAsync(TInput x, TOutput y)  // For regular training (required parameters)
+
+// ❌ WRONG - Nullable defaults that hide requirements
+BuildAsync(TInput? x = default, TOutput? y = default)
+```
+
+### Immutability Philosophy
+
+- Everything should be **internal** and only **methods** should be public
+- Users should not have the ability to edit anything in result objects
+- Properties should have private setters
+- All data should be passed through constructors
+
+## Adding New Features
+
+When adding new features, always:
+
+1. Use Newtonsoft.Json, not System.Text.Json
+2. Follow the constructor injection pattern
+3. Use configuration objects for Configure methods
+4. Make required parameters non-nullable
+5. Keep properties internal with private setters
+6. Only expose public methods, not public properties with setters
+
+## Enforcement
+
+These rules are enforced through:
+- Code reviews
+- This documentation
+- Reminders in AI coding sessions
+
+If you find code that violates these rules, it should be refactored to comply.