koan-ai-integration

sylin-org's avatarfrom sylin-org

Chat endpoints, embeddings, RAG workflows, vector search

⭐2stars🔀1forks📁View on GitHub🕐Updated Nov 11, 2025
[Developer Tools]

When & Why to Use This Skill

The Koan AI Integration skill empowers developers to seamlessly embed advanced AI capabilities into their software architecture. It provides a comprehensive framework for managing chat endpoints, generating and storing vector embeddings directly on data entities, and orchestrating complex RAG (Retrieval-Augmented Generation) workflows. By supporting multiple providers like OpenAI and Ollama alongside vector databases like Weaviate, it simplifies the implementation of semantic search and AI-enriched data patterns for modern applications.

Use Cases

  • Building context-aware AI chatbots: Utilize RAG workflows to provide accurate answers based on private knowledge bases or document repositories.
  • Implementing semantic search: Enable high-precision search functionality in product catalogs or content platforms using vector embeddings and Weaviate integration.
  • AI-enriched data modeling: Automatically generate and store embeddings for entity fields to facilitate intelligent data retrieval and similarity matching.
  • Multi-provider AI orchestration: Configure primary and fallback AI models (e.g., OpenAI to Ollama) to ensure high availability and cost-optimization for chat services.
namekoan-ai-integration
descriptionChat endpoints, embeddings, RAG workflows, vector search

Koan AI Integration

Core Principle

AI capabilities integrate seamlessly with entity patterns. Store embeddings on entities, use vector repositories for search, and leverage standard Entity patterns for AI-enriched data.

Quick Reference

Chat Endpoints

public class ChatController : ControllerBase
{
    private readonly IAi _ai;

    [HttpPost]
    public async Task<IActionResult> Chat(
        [FromBody] ChatRequest request,
        CancellationToken ct)
    {
        var response = await _ai.ChatAsync(new AiChatRequest
        {
            Model = "gpt-4",
            Messages = request.Messages,
            SystemPrompt = "You are a helpful assistant.",
            Temperature = 0.7
        }, ct);

        return Ok(new { message = response.Content, usage = response.Usage });
    }
}

Entity with Embeddings

[DataAdapter("weaviate")] // Force vector database
public class ProductSearch : Entity<ProductSearch>
{
    public string ProductId { get; set; } = "";
    public string Description { get; set; } = "";

    [VectorField]
    public float[] DescriptionEmbedding { get; set; } = Array.Empty<float>();

    // Semantic search
    public static async Task<List<ProductSearch>> SimilarTo(
        string query,
        CancellationToken ct = default)
    {
        return await Vector<ProductSearch>.SearchAsync(query, limit: 10, ct);
    }
}

RAG Workflow

public class KnowledgeBaseService
{
    private readonly IAi _ai;

    public async Task<string> AnswerQuestion(string question, CancellationToken ct)
    {
        // 1. Find relevant documents via vector search
        var relevantDocs = await KnowledgeDocument.SimilarTo(question, ct);

        // 2. Build context from documents
        var context = string.Join("\n\n", relevantDocs.Select(d => d.Content));

        // 3. Query AI with context
        var response = await _ai.ChatAsync(new AiChatRequest
        {
            Model = "gpt-4",
            SystemPrompt = $"Answer based on this context:\n\n{context}",
            Messages = new[] { new AiMessage { Role = "user", Content = question } }
        }, ct);

        return response.Content;
    }
}

Configuration

{
  "Koan": {
    "AI": {
      "Providers": {
        "Primary": {
          "Type": "OpenAI",
          "ApiKey": "{OPENAI_API_KEY}",
          "Model": "gpt-4"
        },
        "Fallback": {
          "Type": "Ollama",
          "BaseUrl": "http://localhost:11434",
          "Model": "llama2"
        }
      }
    },
    "Data": {
      "Sources": {
        "Vectors": {
          "Adapter": "weaviate",
          "ConnectionString": "http://localhost:8080"
        }
      }
    }
  }
}

When This Skill Applies

  • ✅ Integrating AI features
  • ✅ Semantic search
  • ✅ Chat interfaces
  • ✅ Embeddings generation
  • ✅ RAG workflows
  • ✅ AI-enriched entities

Reference Documentation

  • Full Guide: docs/guides/ai-integration.md
  • Vector How-To: docs/guides/ai-vector-howto.md
  • Sample: samples/S5.Recs/ (AI recommendation engine)
  • Sample: samples/S16.PantryPal/ (Vision AI integration)