@polymorphism-tech/morph-spec 6.0.0 → 7.1.0

package/framework/standards/infrastructure/neon/neon-semantic-kernel.md

@@ -1,310 +0,0 @@
-# Neon Semantic Kernel Vector Store Standard
-
-> **Scope:** neon, dotnet-vsa
-> **Layer:** 2 (on keyword)
-> **Keywords:** semantic kernel, vector store, PostgresVectorStore, VectorStoreTextSearch, MAF
-> **Load When:** semantic kernel postgres vector keywords detected
-
-Stack: .NET VSA + Neon Serverless Postgres + Semantic Kernel
-
-## Core Rules
-
-- ALWAYS call `UseVector()` on `NpgsqlDataSourceBuilder` -- without it the vector store fails silently
-- ALWAYS use `AddPostgresVectorStore()` for DI registration -- handles datasource lifecycle
-- NEVER mix pgvector-dotnet `Vector` type with SK `ReadOnlyMemory<float>` -- SK uses its own mapping
-- ALWAYS annotate data model properties with `[VectorStoreKey]`, `[VectorStoreData]`, `[VectorStoreVector]`
-- Use `PostgresCollection<TKey, TRecord>` for typed collection access
-
-## NuGet Packages
-
-```bash
-dotnet add package Microsoft.SemanticKernel.Connectors.PgVector --prerelease
-dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI
-dotnet add package Npgsql
-```
-
-## PostgresVectorStore Initialization
-
-### Via Dependency Injection (Recommended)
-
-```csharp
-using Microsoft.Extensions.DependencyInjection;
-using Microsoft.SemanticKernel;
-using Npgsql;
-
-var builder = WebApplication.CreateBuilder(args);
-
-// Option 1: Connection string (UseVector applied automatically)
-builder.Services.AddPostgresVectorStore(
-    builder.Configuration.GetConnectionString("DefaultConnection")!);
-
-// Option 2: Manual NpgsqlDataSource (full control)
-builder.Services.AddSingleton<NpgsqlDataSource>(sp =>
-{
-    var dataSourceBuilder = new NpgsqlDataSourceBuilder(
-        builder.Configuration.GetConnectionString("DefaultConnection"));
-    dataSourceBuilder.UseVector();
-    return dataSourceBuilder.Build();
-});
-builder.Services.AddPostgresVectorStore();
-```
-
-### Direct Construction
-
-```csharp
-using Microsoft.SemanticKernel.Connectors.PgVector;
-using Npgsql;
-
-var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
-dataSourceBuilder.UseVector();
-var dataSource = dataSourceBuilder.Build();
-
-var vectorStore = new PostgresVectorStore(dataSource, ownsDataSource: true);
-```
-
-## Data Model Definition
-
-Annotate your record type with SK vector store attributes:
-
-```csharp
-using System;
-using Microsoft.Extensions.VectorData;
-
-public class KnowledgeEntry
-{
-    [VectorStoreKey(StorageName = "id")]
-    public Guid Id { get; set; }
-
-    [VectorStoreData(StorageName = "title")]
-    public string Title { get; set; } = string.Empty;
-
-    [VectorStoreData(StorageName = "content")]
-    public string Content { get; set; } = string.Empty;
-
-    [VectorStoreData(StorageName = "source")]
-    public string? Source { get; set; }
-
-    [VectorStoreData(StorageName = "created_at")]
-    public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
-
-    [VectorStoreVector(
-        Dimensions: 1536,
-        DistanceFunction = DistanceFunction.CosineDistance,
-        IndexKind = IndexKind.Hnsw,
-        StorageName = "embedding")]
-    public ReadOnlyMemory<float>? Embedding { get; set; }
-}
-```
-
-This maps to the following Postgres table (auto-created by `EnsureCollectionExistsAsync`):
-
-```sql
-CREATE TABLE IF NOT EXISTS public."knowledge_entries" (
-    "id" UUID PRIMARY KEY NOT NULL,
-    "title" TEXT,
-    "content" TEXT,
-    "source" TEXT,
-    "created_at" TIMESTAMPTZ,
-    "embedding" VECTOR(1536)
-);
-```
-
-## Collection Operations
-
-```csharp
-using Microsoft.SemanticKernel.Connectors.PgVector;
-
-// Get a typed collection
-var collection = vectorStore.GetCollection<Guid, KnowledgeEntry>("knowledge_entries");
-
-// Create table if it doesn't exist (includes HNSW index)
-await collection.EnsureCollectionExistsAsync();
-
-// Upsert a record
-var entry = new KnowledgeEntry
-{
-    Id = Guid.NewGuid(),
-    Title = "Neon Overview",
-    Content = "Neon is a serverless Postgres platform...",
-    Source = "docs",
-    Embedding = new ReadOnlyMemory<float>(embeddingVector)
-};
-await collection.UpsertAsync(entry);
-
-// Get by key
-var retrieved = await collection.GetAsync(entry.Id);
-
-// Delete
-await collection.DeleteAsync(entry.Id);
-```
-
-## Embedding Generation with OpenAI
-
-```csharp
-using Microsoft.SemanticKernel;
-using Microsoft.SemanticKernel.Connectors.OpenAI;
-using Microsoft.SemanticKernel.Embeddings;
-
-// Register embedding service
-builder.Services.AddOpenAITextEmbeddingGeneration(
-    modelId: "text-embedding-3-small",
-    apiKey: builder.Configuration["OpenAI:ApiKey"]!);
-
-// Generate embeddings
-public class EmbeddingService(ITextEmbeddingGenerationService embeddingService)
-{
-    public async Task<ReadOnlyMemory<float>> GenerateAsync(string text)
-    {
-        var embeddings = await embeddingService.GenerateEmbeddingsAsync([text]);
-        return embeddings[0];
-    }
-
-    public async Task<IList<ReadOnlyMemory<float>>> GenerateBatchAsync(IList<string> texts)
-    {
-        return await embeddingService.GenerateEmbeddingsAsync(texts);
-    }
-}
-```
-
-## VectorStoreTextSearch Usage
-
-`VectorStoreTextSearch<T>` provides a high-level search API that automatically generates embeddings for queries:
-
-```csharp
-using Microsoft.Extensions.VectorData;
-using Microsoft.SemanticKernel.Data;
-
-// Create text search from collection + embedding service
-var textSearch = new VectorStoreTextSearch<KnowledgeEntry>(
-    collection,
-    embeddingGenerationService);
-
-// Search with natural language
-var query = "How does Neon branching work?";
-KernelSearchResults<TextSearchResult> results = await textSearch.GetTextSearchResultsAsync(
-    query, new() { Top = 5, Skip = 0 });
-
-await foreach (TextSearchResult result in results.Results)
-{
-    Console.WriteLine($"Name:  {result.Name}");
-    Console.WriteLine($"Value: {result.Value}");
-    Console.WriteLine($"Link:  {result.Link}");
-}
-```
-
-### Use as Kernel Plugin (RAG in Prompts)
-
-```csharp
-using Microsoft.SemanticKernel;
-using Microsoft.SemanticKernel.Data;
-using Microsoft.SemanticKernel.PromptTemplates.Handlebars;
-
-var kernel = builder.Build();
-
-// Register text search as a plugin
-var searchPlugin = textSearch.CreateWithGetTextSearchResults("KnowledgeSearch");
-kernel.Plugins.Add(searchPlugin);
-
-// Use in prompt with automatic retrieval
-var promptTemplate = """
-    {{#with (KnowledgeSearch-GetTextSearchResults query)}}
-      {{#each this}}
-        Name: {{Name}}
-        Value: {{Value}}
-        ---
-      {{/each}}
-    {{/with}}
-
-    Based on the above context, answer: {{query}}
-    """;
-
-var function = KernelFunctionFactory.CreateFromPrompt(
-    new PromptTemplateConfig
-    {
-        Template = promptTemplate,
-        TemplateFormat = "handlebars"
-    },
-    new HandlebarsPromptTemplateFactory());
-
-var result = await kernel.InvokeAsync(function,
-    new KernelArguments { ["query"] = "How does Neon branching work?" });
-```
-
-## Integration with MAF Agents
-
-Use the vector store as a plugin for ChatCompletionAgent to give agents vector memory:
-
-```csharp
-using Microsoft.SemanticKernel;
-using Microsoft.SemanticKernel.Agents;
-using Microsoft.SemanticKernel.Data;
-
-// Build kernel with vector search plugin
-var kernelBuilder = Kernel.CreateBuilder();
-kernelBuilder.AddOpenAIChatCompletion("gpt-4o", apiKey);
-kernelBuilder.AddOpenAITextEmbeddingGeneration("text-embedding-3-small", apiKey);
-var kernel = kernelBuilder.Build();
-
-// Register vector search as a kernel plugin
-var searchPlugin = textSearch.CreateWithGetTextSearchResults("KnowledgeBase");
-kernel.Plugins.Add(searchPlugin);
-
-// Create agent with vector memory
-var agent = new ChatCompletionAgent
-{
-    Name = "KnowledgeAgent",
-    Instructions = """
-        You are a knowledge assistant. Use the KnowledgeBase plugin to search for
-        relevant information before answering questions. Always cite your sources.
-        """,
-    Kernel = kernel,
-    Arguments = new KernelArguments(
-        new OpenAIPromptExecutionSettings { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() })
-};
-
-// Agent automatically calls vector search when needed
-await foreach (var message in agent.InvokeAsync(chatHistory))
-{
-    Console.WriteLine(message.Content);
-}
-```
-
-## Service Registration Summary
-
-```csharp
-// Program.cs -- complete registration
-var builder = WebApplication.CreateBuilder(args);
-
-// 1. Vector store (Neon + pgvector)
-builder.Services.AddPostgresVectorStore(
-    builder.Configuration.GetConnectionString("DefaultConnection")!);
-
-// 2. Embedding generation
-builder.Services.AddOpenAITextEmbeddingGeneration(
-    modelId: "text-embedding-3-small",
-    apiKey: builder.Configuration["OpenAI:ApiKey"]!);
-
-// 3. Chat completion (for agents)
-builder.Services.AddOpenAIChatCompletion(
-    modelId: "gpt-4o",
-    apiKey: builder.Configuration["OpenAI:ApiKey"]!);
-
-// 4. Application services
-builder.Services.AddSingleton<EmbeddingService>();
-builder.Services.AddSingleton(sp =>
-{
-    var vectorStore = sp.GetRequiredService<PostgresVectorStore>();
-    return vectorStore.GetCollection<Guid, KnowledgeEntry>("knowledge_entries");
-});
-```
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| Missing `UseVector()` on data source | Always call `dataSourceBuilder.UseVector()` | Vector type mapping fails without it |
-| Using `float[]` for vector property | `ReadOnlyMemory<float>` with `[VectorStoreVector]` | SK connector expects its own vector types |
-| No `StorageName` on attributes | Set `StorageName` for snake_case columns | C# PascalCase won't match Postgres columns |
-| Creating collection without `EnsureCollectionExistsAsync` | Call before first upsert/search | Table and index won't exist |
-| Hardcoded embedding dimensions | Match `Dimensions` to your model (1536 for ada-002/3-small) | Mismatch causes insertion errors |
-| Using pgvector-dotnet `Vector` with SK | Use `ReadOnlyMemory<float>` | SK has its own type mapping layer |

package/framework/templates/integrations/semantic-kernel-neon.cs

@@ -1,125 +0,0 @@
-// ============================================================
-// SEMANTIC KERNEL + NEON PGVECTOR SETUP TEMPLATE
-// Generated by MORPH Framework
-// ============================================================
-
-using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.VectorData;
-using Microsoft.SemanticKernel;
-using Microsoft.SemanticKernel.Connectors.PgVector;
-using Microsoft.SemanticKernel.Connectors.OpenAI;
-using Microsoft.SemanticKernel.Embeddings;
-using Npgsql;
-
-#nullable disable
-
-namespace {{NAMESPACE}}.Infrastructure.AI;
-
-// ============================================================
-// 1. DATA MODEL — annotated for Semantic Kernel vector store
-// ============================================================
-
-public class KnowledgeEntry
-{
-    [VectorStoreKey(StorageName = "id")]
-    public Guid Id { get; set; }
-
-    [VectorStoreData(StorageName = "title")]
-    public string Title { get; set; } = string.Empty;
-
-    [VectorStoreData(StorageName = "content", IsFullTextSearchable = true)]
-    public string Content { get; set; } = string.Empty;
-
-    [VectorStoreData(StorageName = "source")]
-    public string? Source { get; set; }
-
-    [VectorStoreVector(Dimensions: 1536, DistanceFunction.CosineSimilarity, StorageName = "embedding")]
-    public ReadOnlyMemory<float> Embedding { get; set; }
-
-    [VectorStoreData(StorageName = "created_at")]
-    public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
-}
-
-// ============================================================
-// 2. SERVICE REGISTRATION — add to Program.cs
-// ============================================================
-
-public static class SemanticKernelExtensions
-{
-    public static IServiceCollection AddSemanticKernelWithNeon(
-        this IServiceCollection services,
-        string neonConnectionString,
-        string openAiApiKey,
-        string embeddingModel = "text-embedding-3-small")
-    {
-        // Neon PostgreSQL data source with pgvector
-        services.AddSingleton<NpgsqlDataSource>(sp =>
-        {
-            var builder = new NpgsqlDataSourceBuilder(neonConnectionString);
-            builder.UseVector();
-            return builder.Build();
-        });
-
-        // Semantic Kernel with OpenAI + Postgres vector store
-        services.AddKernel();
-
-        services.AddOpenAITextEmbeddingGeneration(embeddingModel, openAiApiKey);
-
-        services.AddPostgresVectorStore();
-
-        // VectorStoreTextSearch for natural language queries
-        services.AddSingleton<VectorStoreTextSearch<KnowledgeEntry>>(sp =>
-        {
-            var vectorStore = sp.GetRequiredService<IVectorStore>();
-            var collection = vectorStore.GetCollection<Guid, KnowledgeEntry>("knowledge_entries");
-            var embeddingGenerator = sp.GetRequiredService<ITextEmbeddingGenerationService>();
-
-            return new VectorStoreTextSearch<KnowledgeEntry>(
-                collection, embeddingGenerator);
-        });
-
-        return services;
-    }
-}
-
-// ============================================================
-// SETUP INSTRUCTIONS
-// ============================================================
-//
-// 1. Install NuGet packages:
-//
-//    dotnet add package Microsoft.SemanticKernel.Connectors.PgVector --prerelease
-//    dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI
-//    dotnet add package Npgsql
-//
-// 2. Add to Program.cs:
-//
-//    builder.Services.AddSemanticKernelWithNeon(
-//        builder.Configuration.GetConnectionString("DefaultConnection")!,
-//        builder.Configuration["OpenAI:ApiKey"]!);
-//
-// 3. Create the database table (Neon SQL):
-//
-//    CREATE EXTENSION IF NOT EXISTS vector;
-//    CREATE TABLE knowledge_entries (
-//        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-//        title TEXT NOT NULL,
-//        content TEXT NOT NULL,
-//        source TEXT,
-//        embedding vector(1536),
-//        created_at TIMESTAMPTZ DEFAULT now()
-//    );
-//    CREATE INDEX ON knowledge_entries USING hnsw (embedding vector_cosine_ops);
-//
-// 4. Use in a service or MAF agent:
-//
-//    public class SearchService(VectorStoreTextSearch<KnowledgeEntry> search)
-//    {
-//        public async Task<IReadOnlyList<KnowledgeEntry>> SearchAsync(string query)
-//        {
-//            var results = await search.SearchAsync(query, new() { Top = 5 });
-//            return await results.Results.Select(r => r.Record).ToListAsync();
-//        }
-//    }
-//
-// ============================================================