.NET AI and Machine Learning

Pick the right technology first, then deliver only what the task asks for. If the task asks for a plan, comparison, or architecture (or says "do not write code"), produce that — do not scaffold, build, or run code unprompted.

Step 1: Classify the task (decision tree)

State which branch applies and why, then choose that technology.

| Task type | Technology | Why | |-----------|-----------|-----| | Structured/tabular: classification, regression, clustering, anomaly detection, recommendation | ML.NET (Microsoft.ML) | Deterministic (fixed seed), no cloud dependency, purpose-built | | NL understanding, generation, summarization, reasoning (single prompt → response, no tools) | LLM via Microsoft.Extensions.AI (IChatClient) | Language capability, no orchestration needed | | Agentic: multi-step tool/function calling, agent loops, multi-agent | Microsoft Agent Framework (Microsoft.Agents.AI) on Microsoft.Extensions.AI | Needs orchestration, tool dispatch, iteration control IChatClient lacks | | GitHub Copilot extensions / custom dev-workflow agents | GitHub Copilot SDK (GitHub.Copilot.SDK) | Integrates with the Copilot agent runtime | | Run a pre-trained/custom model in production | ONNX Runtime (Microsoft.ML.OnnxRuntime) | Hardware-accelerated, format-agnostic inference | | Local/offline LLM inference | OllamaSharp (Ollama models) | Privacy-sensitive, air-gapped, cost-constrained | | Semantic search, RAG, embedding storage | Microsoft.Extensions.VectorData.Abstractions (MEVD) + a provider (Azure AI Search, Milvus, MongoDB, pgvector, Pinecone, Qdrant, Redis, SQL) | Provider-agnostic vector search | | Ingest, chunk, load documents into a vector store | Microsoft.Extensions.AI.DataIngestion (preview) + MEVD | Parses, chunks, embeds, upserts | | Both structured predictions AND NL reasoning | Hybrid: ML.NET scoring + LLM reasoning layer | ML.NET is reproducible; LLM adds explanation |

Critical rule: Do NOT use an LLM for tasks ML.NET handles well (tabular classification, regression, clustering) — LLMs are slower, costlier, and non-deterministic for these.

Step 1b: Pick the library layer

| Layer | Library | Use when | |-------|---------|----------| | Abstraction | Microsoft.Extensions.AI (MEAI) | Always the foundation. Use IChatClient directly for prompt-response and simple, bounded function invocation. | | Provider SDK | Azure.AI.OpenAI / OpenAI / Azure.AI.Inference / OllamaSharp | Concrete provider behind MEAI via AddChatClient. | | Orchestration | Microsoft.Agents.AI (prerelease) | Multi-step tool use, durable agent loops, and multi-agent workflows. | | Copilot | GitHub.Copilot.SDK | Building Copilot-platform extensions only. |

Rules: start with MEAI; put the provider behind it via AddChatClient (don't call the provider in business logic); use Microsoft.Agents.AI for multi-step or durable agent workflows rather than hand-rolling an agent loop; never mix a raw HttpClient-to-OpenAI call with MEAI in the same workflow. Do not use Accord.NET (archived). For new projects, prefer MEAI and Agent Framework unless existing Semantic Kernel features or investments are a requirement. Register AI/ML services via DI; load secrets from user-secrets / env / Key Vault — never hardcode keys.

Step 2: Cover the branch essentials, then decide depth

Every answer — plan or implementation — must address the guardrails for the selected branch:

• ML.NET — new MLContext(seed: …) (reproducible); TrainTestSplit + evaluate on the held-out set; report real metrics (MicroAccuracy/MacroAccuracy/LogLoss, AUC/F1, or RMSE/R²); serve with PredictionEnginePool<TIn,TOut> (never a singleton PredictionEngine).
• LLM (MEAI) — depend on IChatClient registered via AddChatClient (provider behind it); set Temperature and MaxOutputTokens in ChatOptions; add retry/timeout (RetryingChatClient/Polly); pin a dated model; load keys from user-secrets / env / Key Vault — never hardcode an sk-… key; validate non-deterministic output against a schema with a fallback.
• Agentic (Agent Framework) — orchestrate with Microsoft.Agents.AI on IChatClient (never a hand-rolled loop); set MaximumIterations and a token/cost ceiling; define each tool with a clear schema (AIFunctionFactory.Create); log each step (never raw sensitive content).
• RAG / embeddings — semantic chunking (not fixed-size); IEmbeddingGenerator and cache the embeddings (don't re-embed per query); store/query with Microsoft.Extensions.VectorData.Abstractions (MEVD) + the provider the user asked for (e.g. pgvector); filter by a minimum similarity score; keep source attribution for each answer. Honor the UI/storage the user specified; use only real, existing NuGet packages.

Then choose depth:

• Plan / comparison / architecture only (or "do not write code"): answer from this file alone using the essentials above. Do NOT open a reference — the branch essentials here are sufficient for a selection or plan. For RAG plans, cover chat, ingestion/chunking, embeddings, vector storage, source attribution, and the requested UI/storage.
• Writing implementation code: read the matching reference(s) for packages and implementation guidance (read only the selected branch; for Hybrid, read both Classic ML.NET and LLM):
  • Classic ML.NET → references/classic-ml.md
  • LLM integration (MEAI) → references/llm.md
  • Agentic (Agent Framework) → references/agentic.md
  • RAG / embeddings / ingestion → references/rag.md
  • GitHub Copilot extensions → references/copilot.md
  • ONNX Runtime inference → references/onnx.md
  • Local/offline LLM with Ollama → references/ollama.md

Validation

• [ ] Selection follows the decision tree — no LLM for tasks ML.NET handles
• [ ] Only what was asked is produced (plan-only requests get a plan, not code)
• [ ] AI/ML services registered via DI; config via IOptions<T>; keys from secure sources
• [ ] Branch guardrails (Step 2 essentials, plus the reference when implementing) are satisfied
• [ ] After implementing, build and run existing tests

Anti-Patterns to Reject

| Anti-pattern | Redirect | |-------------|----------| | LLM for tabular classification | Use ML.NET — faster, cheaper, deterministic | | LLM calls without retry/timeout | Add RetryingChatClient or Polly retry | | API keys in committed appsettings.json | user-secrets / env / Key Vault | | Accord.NET, or defaulting to Semantic Kernel without a requirement | ML.NET; prefer MEAI + Microsoft.Agents.AI for new work | | Hand-rolled multi-step tool loops with IChatClient | Microsoft.Agents.AI (MaximumIterations, tool dispatch) | | Agent Framework for a single prompt→response | IChatClient directly | | Raw HttpClient/OpenAI SDK in business logic alongside MEAI | one abstraction layer; depend on IChatClient | | PredictionEngine singleton in ASP.NET Core | PredictionEnginePool<TIn,TOut> (not thread-safe) | | RAG without chunking or relevance filtering | semantic chunking + minimum similarity score | | Building custom neural nets in .NET from scratch | pre-trained via ONNX Runtime or an LLM API |