@polymorphism-tech/morph-spec 4.7.1 → 4.7.2

package/.morph/framework/standards/data/vector-search/azure-ai-search.md

@@ -0,0 +1,121 @@
+# Data Standard: Azure AI Search (Vector Search)
+
+## Overview
+Azure AI Search provides vector and hybrid search for RAG (Retrieval-Augmented Generation) patterns.
+
+## Index Design
+```csharp
+// Define index with vector field
+var index = new SearchIndex("documents-index")
+{
+    Fields =
+    [
+        new SimpleField("id", SearchFieldDataType.String) { IsKey = true },
+        new SearchableField("content") { AnalyzerName = "pt.microsoft" },
+        new SearchableField("title") { AnalyzerName = "pt.microsoft" },
+        new SimpleField("sourceUrl", SearchFieldDataType.String) { IsFilterable = true },
+        new SimpleField("category", SearchFieldDataType.String) { IsFilterable = true, IsFacetable = true },
+        new VectorSearchField("contentVector", dimensions: 1536, vectorSearchProfileName: "hnsw-profile")
+    ],
+    VectorSearch = new VectorSearch
+    {
+        Profiles = { new VectorSearchProfile("hnsw-profile", "hnsw-config") },
+        Algorithms = { new HnswAlgorithmConfiguration("hnsw-config") }
+    }
+};
+await indexClient.CreateOrUpdateIndexAsync(index);
+```
+
+## Embedding Generation
+```csharp
+public class EmbeddingService : IEmbeddingService
+{
+    private readonly OpenAIClient _client;
+    private const string EmbeddingModel = "text-embedding-ada-002"; // 1536 dimensions
+
+    public async Task<float[]> GenerateEmbeddingAsync(string text)
+    {
+        // Truncate to model limit
+        var truncated = text.Length > 8192 ? text[..8192] : text;
+
+        var response = await _client.GetEmbeddingsAsync(
+            new EmbeddingsOptions(EmbeddingModel, [truncated]));
+
+        return response.Value.Data[0].Embedding.ToArray();
+    }
+
+    public async Task<IReadOnlyList<float[]>> GenerateBatchEmbeddingsAsync(IReadOnlyList<string> texts)
+    {
+        var response = await _client.GetEmbeddingsAsync(
+            new EmbeddingsOptions(EmbeddingModel, texts));
+        return response.Value.Data.Select(d => d.Embedding.ToArray()).ToList();
+    }
+}
+```
+
+## Document Indexing
+```csharp
+public class DocumentIndexer
+{
+    public async Task IndexDocumentAsync(Document doc)
+    {
+        var embedding = await _embeddingService.GenerateEmbeddingAsync(doc.Content);
+
+        var searchDoc = new SearchDocument
+        {
+            ["id"] = doc.Id.ToString(),
+            ["content"] = doc.Content,
+            ["title"] = doc.Title,
+            ["sourceUrl"] = doc.SourceUrl,
+            ["category"] = doc.Category,
+            ["contentVector"] = embedding
+        };
+
+        await _searchClient.MergeOrUploadDocumentsAsync([searchDoc]);
+    }
+}
+```
+
+## Hybrid Search (Vector + Keyword)
+```csharp
+public async Task<IReadOnlyList<SearchResult>> SearchAsync(string query, string? category = null)
+{
+    var queryEmbedding = await _embeddingService.GenerateEmbeddingAsync(query);
+
+    var options = new SearchOptions
+    {
+        Filter = category != null ? $"category eq '{category}'" : null,
+        Size = 10,
+        VectorSearch = new VectorSearchOptions
+        {
+            Queries =
+            {
+                new VectorizedQuery(queryEmbedding)
+                {
+                    Fields = { "contentVector" },
+                    KNearestNeighborsCount = 50
+                }
+            }
+        },
+        QueryType = SearchQueryType.Semantic,
+        SemanticSearch = new SemanticSearchOptions
+        {
+            SemanticConfigurationName = "my-semantic-config",
+            QueryCaption = new QueryCaption(QueryCaptionType.Extractive)
+        }
+    };
+
+    var response = await _searchClient.SearchAsync<SearchDocument>(query, options);
+    return await response.Value.GetResultsAsync().Select(r => new SearchResult(
+        r.Document["id"].ToString()!,
+        r.Document["content"].ToString()!,
+        r.Score ?? 0
+    )).ToListAsync();
+}
+```
+
+## Cost Optimization
+- Index only necessary fields (cost per GB/month)
+- Use semantic ranking sparingly (higher cost per query)
+- Cache frequent query embeddings (embeddings are stable for same text)
+- Batch indexing for large document sets (avoid per-document API calls)

package/.morph/framework/standards/data/vector-search/rag-chunking.md

@@ -0,0 +1,104 @@
+# Data Standard: RAG Chunking Strategies
+
+## Overview
+Chunking splits documents into segments for embedding. Chunk quality directly impacts RAG answer quality.
+
+## Chunking Strategies
+
+### 1. Fixed-Size (Baseline)
+```csharp
+public IEnumerable<Chunk> FixedSizeChunk(string text, int size = 512, int overlap = 50)
+{
+    for (int i = 0; i < text.Length; i += size - overlap)
+    {
+        yield return new Chunk
+        {
+            Content = text[i..Math.Min(i + size, text.Length)],
+            StartIndex = i,
+            EndIndex = Math.Min(i + size, text.Length)
+        };
+    }
+}
+```
+
+### 2. Sentence-Aware (Recommended for prose)
+```csharp
+public IEnumerable<Chunk> SentenceChunk(string text, int maxTokens = 256)
+{
+    var sentences = SplitSentences(text);
+    var current = new StringBuilder();
+    var tokenCount = 0;
+
+    foreach (var sentence in sentences)
+    {
+        var sentenceTokens = EstimateTokens(sentence);
+        if (tokenCount + sentenceTokens > maxTokens && current.Length > 0)
+        {
+            yield return new Chunk { Content = current.ToString().Trim() };
+            current.Clear();
+            tokenCount = 0;
+        }
+        current.Append(sentence).Append(' ');
+        tokenCount += sentenceTokens;
+    }
+
+    if (current.Length > 0)
+        yield return new Chunk { Content = current.ToString().Trim() };
+}
+```
+
+### 3. Semantic (Best quality, higher cost)
+Split at semantic boundaries (paragraphs, headers, sections) rather than character count.
+
+```csharp
+public IEnumerable<Chunk> SemanticChunk(string markdown)
+{
+    // Split at markdown headers
+    var sections = Regex.Split(markdown, @"(?=^#{1,3} )", RegexOptions.Multiline);
+    foreach (var section in sections.Where(s => s.Trim().Length > 0))
+        yield return new Chunk { Content = section.Trim() };
+}
+```
+
+## Token Estimation
+```csharp
+// Rough estimate: 1 token ≈ 4 characters (English), ≈ 3 characters (Portuguese)
+private static int EstimateTokens(string text) => text.Length / 4;
+
+// More accurate: use tiktoken (if available)
+// var encoder = TiktokenSharp.TikToken.EncodingForModel("gpt-4");
+// return encoder.Encode(text).Count;
+```
+
+## Chunk Metadata
+Always store metadata with chunks for filtering and citation:
+```csharp
+public record Chunk
+{
+    public string Content { get; init; } = "";
+    public string DocumentId { get; init; } = "";
+    public string DocumentTitle { get; init; } = "";
+    public string SourceUrl { get; init; } = "";
+    public int ChunkIndex { get; init; }
+    public int StartCharIndex { get; init; }
+    public string Section { get; init; } = ""; // H1/H2 header this belongs to
+    public DateTime IndexedAt { get; init; } = DateTime.UtcNow;
+}
+```
+
+## Strategy Selection Guide
+| Document Type | Strategy | Chunk Size |
+|---------------|----------|------------|
+| Legal documents | Sentence-aware | 256 tokens |
+| Technical docs | Semantic (headers) | Variable |
+| Q&A pairs | Keep as-is | Whole Q+A |
+| Code files | Function-boundary | Whole function |
+| News articles | Paragraph | 512 tokens |
+
+## Quality Checklist
+- [ ] Chunks overlap by 10-20% to avoid cutting context at boundaries
+- [ ] Minimum chunk size: 50 tokens (avoid noisy small chunks)
+- [ ] Maximum chunk size: 512 tokens for ada-002 (8192 token model limit)
+- [ ] Metadata preserved and searchable
+- [ ] Source URL included for citation
+- [ ] Re-index when document changes (detect via content hash)

package/.morph/framework/standards/frontend/blazor/design-checklist.md

@@ -0,0 +1,222 @@
+# Blazor Design Phase Checklist
+
+> **Scope:** blazor-azure
+> **Layer:** 2 (on keyword)
+> **Keywords:** blazor, design, checklist, phase, architecture
+> **Load When:** design phase for blazor features
+
+Use this checklist during FASE 2 (DESIGN) for features involving Blazor Server
+
+---
+
+## 1. State and Session Management
+
+### State Persistence
+
+- [ ] **How will critical state be persisted?**
+  - [ ] Database (recommended for important data)
+  - [ ] Distributed cache (Redis, SQL Distributed Cache)
+  - [ ] Cookie (only for identification, not data)
+  - [ ] LocalStorage via JS Interop (only for non-critical preferences)
+
+- [ ] **SessionState has `LoadFrom(entity)` method?**
+  - Allows reloading state from persisted source
+  - See [state.md](./state.md)
+
+- [ ] **`IsLoaded` property exists to avoid unnecessary reloads?**
+
+- [ ] **SessionId middleware is configured?**
+  - HttpOnly cookie with session identifier
+  - Injected into HttpContext.Items for component access
+
+### Page Validation
+
+- [ ] **All pages in flow reload state in `OnInitializedAsync`?**
+  ```csharp
+  if (!Session.IsLoaded)
+  {
+      var entity = await Repository.GetBySessionIdAsync(sessionId);
+      Session.LoadFrom(entity);
+  }
+  ```
+
+- [ ] **What happens if user accesses middle page directly?**
+  - Redirect to start?
+  - Load partial state?
+  - Show friendly error?
+
+---
+
+## 2. EF Core Concurrency
+
+### Background Operations
+
+- [ ] **Will any service be called via `Task.Run`?**
+  - If YES: Use `IDbContextFactory<T>`
+  - See [ef-core.md](../../backend/database/ef-core.md)
+
+- [ ] **Will any service be called in background job (Hangfire, Timer)?**
+  - If YES: Use `IDbContextFactory<T>` or Repository Factory pattern
+
+- [ ] **Will multiple operations happen concurrently in same component?**
+  - If YES: Each operation needs isolated DbContext
+
+---
+
+## 3. File Upload
+
+- [ ] **Will feature handle file uploads?**
+  - [ ] Max file size defined?
+  - [ ] Allowed file types/extensions specified?
+  - [ ] Files read once and bytes stored?
+  - [ ] Upload progress indicator planned?
+
+- [ ] **Where will files be stored?**
+  - [ ] Azure Blob Storage (recommended)
+  - [ ] Local file system (not scalable)
+  - [ ] Database as byte[] (only for small files < 1MB)
+
+---
+
+## 4. JavaScript Interop
+
+- [ ] **Will feature use JavaScript?**
+  - [ ] JS calls in `OnAfterRenderAsync`, not `OnInitializedAsync`?
+  - [ ] `firstRender` check to prevent duplicate calls?
+  - [ ] JS file location planned (wwwroot/js/)?
+
+- [ ] **Will feature need external JS libraries?**
+  - [ ] Library loaded via CDN or npm?
+  - [ ] Initialization strategy planned?
+
+---
+
+## 5. Navigation and Routing
+
+- [ ] **How many pages in the feature?**
+  - Single page?
+  - Multi-page flow?
+  - Modal/dialog-based?
+
+- [ ] **Will users need to navigate back/forward?**
+  - [ ] State persisted before navigation?
+  - [ ] Browser back button handled correctly?
+
+- [ ] **Are there deep links?**
+  - [ ] Each page can load state from URL/DB?
+  - [ ] Invalid state handled gracefully?
+
+---
+
+## 6. Real-time Updates
+
+- [ ] **Will feature need real-time updates?**
+  - SignalR circuit is already available
+  - Update strategy planned?
+
+- [ ] **Will updates come from background jobs?**
+  - [ ] Notification mechanism planned?
+  - [ ] UI refresh strategy defined?
+
+---
+
+## 7. Performance
+
+- [ ] **Expected data volume?**
+  - Pagination needed for lists > 100 items?
+  - Lazy loading for large datasets?
+
+- [ ] **Heavy computations planned?**
+  - [ ] Run in background (Task.Run with factory)?
+  - [ ] Cache results?
+
+- [ ] **Large components/forms?**
+  - [ ] Split into smaller components?
+  - [ ] Lazy rendering planned?
+
+---
+
+## 8. Error Handling
+
+- [ ] **What errors might occur?**
+  - Database errors?
+  - Network errors?
+  - Validation errors?
+  - Permission errors?
+
+- [ ] **Error display strategy?**
+  - [ ] Toast notifications?
+  - [ ] Inline validation messages?
+  - [ ] Error page redirect?
+
+- [ ] **Retry strategy for transient errors?**
+
+---
+
+## 9. Security
+
+- [ ] **Authentication required?**
+  - [ ] `[Authorize]` attribute on pages?
+  - [ ] Login redirect configured?
+
+- [ ] **Authorization rules?**
+  - Role-based?
+  - Policy-based?
+  - Resource-based?
+
+- [ ] **Input validation?**
+  - [ ] Client-side (Blazor validation)?
+  - [ ] Server-side (service layer)?
+  - [ ] Both?
+
+- [ ] **Sensitive data?**
+  - [ ] Not stored in SessionState?
+  - [ ] Not logged?
+  - [ ] Encrypted in database?
+
+---
+
+## 10. UI/UX
+
+- [ ] **Loading states?**
+  - Spinners for async operations?
+  - Skeleton loaders for data?
+  - Disabled buttons during saves?
+
+- [ ] **Success feedback?**
+  - Toast messages?
+  - Inline success indicators?
+  - Redirect to confirmation page?
+
+- [ ] **Responsive design?**
+  - Mobile layout planned?
+  - Breakpoints defined?
+
+---
+
+## Quick Design Decisions
+
+Before implementing, answer these:
+
+| Question | Answer Required |
+|----------|----------------|
+| **State:** Where is critical state stored? | Database / Cache / Cookie |
+| **Files:** Where are uploads stored? | Azure Blob / Database / FileSystem |
+| **Navigation:** Single page or multi-page? | Single / Multi / Modal |
+| **JS:** Is JavaScript needed? | Yes / No |
+| **Auth:** Authentication required? | Yes / No |
+| **Background:** Any background operations? | Yes (use factory) / No |
+| **Real-time:** Real-time updates needed? | Yes / No |
+
+---
+
+## Related Standards
+
+- [state.md](./state.md) - Session state patterns
+- [lifecycle.md](./lifecycle.md) - Component lifecycle
+- [pitfalls.md](./pitfalls.md) - Common mistakes
+- [ef-core.md](../../backend/database/ef-core.md) - DbContext concurrency
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*