@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

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

@@ -1,121 +0,0 @@
-# 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

@@ -1,104 +0,0 @@
-# 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

@@ -1,222 +0,0 @@
-# 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*