Add OpenAI-compatible provider support

Introduce support for OpenAI-compatible providers (Provider = "OpenAICompatible"). Updates include: docs (README, HOW_IT_WORKS, TECHNICAL_REFERENCE, CONTRIBUTING), docker files (.env.example, docker-compose.yml), CLI help, and code changes to plumb new config fields (BaseUrl, Organization, Project, ModelId mapping) and environment variables (OPENAI_COMPAT_*). KernelFactory, AgentKernelFactory, and Executor config/validation logic were extended to detect the new provider, validate required fields, and create chat completions against a custom endpoint when OpenAICompatible is selected. DockerRunner now propagates OPENAI_COMPAT_* env vars into containers. Note: appsettings.json in this changeset contains a populated ApiKey value — do not commit real secrets; remove or rotate this key and use environment variables instead.

Author: MansurBesleney

CONTRIBUTING.md

@@ -58,7 +58,7 @@ dotnet build
 
 ```bash
 cp docker/.env.example docker/.env
-# Edit docker/.env and set OPENAI_API_KEY or Azure OpenAI credentials
+# Edit docker/.env and set OpenAI, OpenAI-compatible, or Azure OpenAI credentials
 ```
 
 **5. Run tests**

HOW_IT_WORKS.md

@@ -60,7 +60,7 @@ The Analyst's job is to read the tutorial and produce a machine-readable test pl
 
 **Scraping** — The Analyst fetches the tutorial URL and parses the HTML. It follows navigation links within the same tutorial series, collecting up to a configurable maximum number of pages. Each page is converted to clean Markdown.
 
-**Analysis** — The Analyst sends the Markdown content to an AI model (OpenAI or Azure OpenAI) with a prompt that instructs it to extract every action a developer must take. The result is a list of structured steps in JSON format, called the **test plan** (`testplan.json`).
+**Analysis** — The Analyst sends the Markdown content to an AI model (OpenAI, Azure OpenAI, or any OpenAI-compatible provider) with a prompt that instructs it to extract every action a developer must take. The result is a list of structured steps in JSON format, called the **test plan** (`testplan.json`).
 
 **Compaction** — Long tutorials can produce hundreds of raw steps. To keep execution time and AI cost reasonable, the Analyst merges adjacent steps of the same type (e.g., two consecutive file edits become one step with two modifications). This is controlled by the `--target-steps` and `--max-steps` arguments.
 

README.md

@@ -1,12 +1,11 @@
 # TutorialValidator
 
-[![CI](https://github.com/AbpFramework/TutorialValidator/actions/workflows/ci.yml/badge.svg)](https://github.com/AbpFramework/TutorialValidator/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![.NET](https://img.shields.io/badge/.NET-10-512BD4)](https://dotnet.microsoft.com/download/dotnet/10.0)
 
-TutorialValidator is an AI-powered tool that checks whether a software documentation tutorial actually works. You give it a URL, it scrapes the tutorial, turns every instruction into an executable step, then runs those steps exactly as a developer would — installing packages, writing files, running commands, making HTTP calls, and asserting results. If any step fails, the tutorial has a bug.
+TutorialValidator is an AI-powered tool that checks whether a software documentation tutorial actually works. You give it a URL, it scrapes the tutorial, turns every instruction into an executable step, then runs those steps exactly as a developer would — installing packages, writing files, running commands, making HTTP calls, and asserting results.
 
-It was built to validate [ABP Framework](https://abp.io) tutorials, but the architecture supports any publicly accessible tutorial.
+We originally built it internally to validate [ABP Framework](https://abp.io) tutorials, and then decided to publish it as open source so you can use it to validate any publicly accessible tutorial.
 
 ---
 
@@ -18,7 +17,7 @@ Before you start, make sure you have the following installed:
 |---|---|---|
 | .NET SDK | 10.0 | [dotnet.microsoft.com](https://dotnet.microsoft.com/download/dotnet/10.0) |
 | Docker Desktop | Latest | [docker.com/get-started](https://www.docker.com/get-started/) |
-| OpenAI **or** Azure OpenAI API key | — | [platform.openai.com](https://platform.openai.com) or your Azure portal |
+| AI provider API key | — | Refer to your AI provider's documentation |
 
 > Docker is required for the default (recommended) execution mode. If you want to run without Docker, see [Running Locally Without Docker](#running-locally-without-docker) below.
 
@@ -43,22 +42,28 @@ cp docker/.env.example docker/.env
 
 **Step 3 — Add your API key**
 
-Open `docker/.env` in any text editor and fill in your credentials.
+Open `docker/.env` in any text editor and fill in your AI provider credentials. For example:
 
-For OpenAI:
 ```env
+# OpenAI
 OPENAI_API_KEY=sk-...
 OPENAI_MODEL=gpt-5.2
-```
 
-For Azure OpenAI:
-```env
+# OpenAI-Compatible (works with providers that expose an OpenAI-compatible API)
+# OPENAI_COMPAT_BASE_URL=https://your-provider.example.com/v1
+# OPENAI_COMPAT_API_KEY=your-key
+# OPENAI_COMPAT_MODEL=gpt-4o-mini
+# AI_PROVIDER=OpenAICompatible
+
+# Azure OpenAI
 AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
 AZURE_OPENAI_API_KEY=your-key
 AZURE_OPENAI_DEPLOYMENT=gpt-4o
 AI_PROVIDER=AzureOpenAI
 ```
 
+See [Environment Variables](#environment-variables) for all supported providers.
+
 **Step 4 — Run the validation**
 
 ```bash
@@ -210,10 +215,11 @@ The file at `src/Validator.Orchestrator/appsettings.json` controls all default s
 
 | Field | Description |
 |---|---|
-| `Provider` | AI provider to use. Accepted values: `OpenAI`, `AzureOpenAI`. Auto-detected from environment variables if omitted. |
-| `Model` | The model name to request from OpenAI (e.g. `gpt-5.2`, `gpt-4o`). Ignored when using Azure OpenAI. |
+| `Provider` | AI provider to use. Accepted values: `OpenAI`, `AzureOpenAI`, `OpenAICompatible`. Auto-detected from environment variables if omitted. |
+| `Model` | The model name to request from your AI provider (e.g. `gpt-5.2`, `gpt-4o`). Ignored when using Azure OpenAI. |
 | `DeploymentName` | The deployment name for Azure OpenAI. When using OpenAI directly, this can mirror the `Model` value or be left empty. |
-| `ApiKey` | Your API key. Leave blank and use the `OPENAI_API_KEY` or `AZURE_OPENAI_API_KEY` environment variable instead — do not commit keys to source control. |
+| `ApiKey` | Your AI provider API key. Leave blank and use environment variables (`OPENAI_API_KEY`, `AZURE_OPENAI_API_KEY`, or `OPENAI_COMPAT_API_KEY`) instead — do not commit keys to source control. |
+| `BaseUrl` | Base URL for OpenAI-compatible providers (e.g. `https://your-provider.example.com/v1`). Used when `Provider` is `OpenAICompatible`. |
 
 #### Docker section
 
@@ -339,10 +345,15 @@ Environment variables always override values in `appsettings.json`.
 |---|---|
 | `OPENAI_API_KEY` | OpenAI API key. |
 | `OPENAI_MODEL` | OpenAI model name (e.g. `gpt-5.2`, `gpt-4o`). |
+| `OPENAI_COMPAT_BASE_URL` | Base URL for an OpenAI-compatible API endpoint. |
+| `OPENAI_COMPAT_API_KEY` | API key for an OpenAI-compatible provider. |
+| `OPENAI_COMPAT_MODEL` | Model name for OpenAI-compatible providers. |
+| `OPENAI_COMPAT_ORG` | Optional organization ID for OpenAI-compatible providers. |
+| `OPENAI_COMPAT_PROJECT` | Optional project ID for OpenAI-compatible providers. |
 | `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint URL (e.g. `https://your-resource.openai.azure.com/`). |
 | `AZURE_OPENAI_API_KEY` | Azure OpenAI API key. |
 | `AZURE_OPENAI_DEPLOYMENT` | Azure OpenAI deployment name. |
-| `AI_PROVIDER` | Force a specific provider: `OpenAI` or `AzureOpenAI`. Auto-detected if omitted. |
+| `AI_PROVIDER` | Force a specific provider: `OpenAI`, `AzureOpenAI`, or `OpenAICompatible`. Auto-detected if omitted. |
 | `Discord__Enabled` | Enable Discord notifications: `true` or `false`. |
 | `Discord__WebhookUrl` | Discord incoming webhook URL. |
 | `EXECUTOR_BUILD_GATE_INTERVAL` | Senior persona only: run `dotnet build` every N steps as a sanity check. `0` disables this. |
@@ -366,5 +377,5 @@ Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for de
 
 ## License
 
-MIT License — Copyright (c) 2024 [Volosoft](https://volosoft.com).
+MIT License — Copyright (c) [Volosoft](https://volosoft.com).
 See [LICENSE](LICENSE) for the full text.

TECHNICAL_REFERENCE.md

@@ -146,7 +146,7 @@ After compaction, all steps are renumbered sequentially starting from 1.
 ### 3.1 Initialization
 
 `AgentKernelFactory.CreateExecutorKernel` builds a `Microsoft.SemanticKernel.Kernel` with:
-- The configured AI chat completion service (OpenAI or Azure OpenAI)
+- The configured AI chat completion service (OpenAI, Azure OpenAI, or OpenAI-compatible endpoint)
 - Four plugins registered as kernel functions (see [3.3 Plugins](#33-plugins))
 - A `FunctionCallTracker` that intercepts and records every function call and its result for deterministic result parsing
 
@@ -487,7 +487,8 @@ A workaround for the .NET 10 SDK image ships an RC/preview runtime while ABP CLI
 
 1. If `AI_PROVIDER` is set explicitly, use that value (`OpenAI` or `AzureOpenAI`).
 2. If `AZURE_OPENAI_ENDPOINT` is set, default to `AzureOpenAI`.
-3. Otherwise, use `OpenAI`.
+3. Otherwise, if `OPENAI_COMPAT_BASE_URL` and `OPENAI_COMPAT_API_KEY` are present, use `OpenAICompatible`.
+4. Otherwise, use `OpenAI`.
 
 ### OpenAI Configuration
 
@@ -506,6 +507,19 @@ Required:
 
 `AI.Model` is ignored for Azure OpenAI; the model is determined by the deployment.
 
+### OpenAI-Compatible Configuration
+
+Required:
+- `OPENAI_COMPAT_BASE_URL` or `AI.BaseUrl` in `appsettings.json`
+- `OPENAI_COMPAT_API_KEY` or `AI.ApiKey`
+- `OPENAI_COMPAT_MODEL` or `AI.ModelId` (falls back to `AI.DeploymentName`)
+
+Optional:
+- `OPENAI_COMPAT_ORG` / `AI.Organization`
+- `OPENAI_COMPAT_PROJECT` / `AI.Project`
+
+Set `AI_PROVIDER=OpenAICompatible` to force this mode when multiple provider variables are present.
+
 ### Configuration Precedence
 
 Environment variables always override `appsettings.json`. The configuration is loaded using `Microsoft.Extensions.Configuration.IConfigurationBuilder`:

docker/.env.example

@@ -10,13 +10,21 @@ MSSQL_SA_PASSWORD=YourStrong!Password123
 OPENAI_API_KEY=your-openai-api-key-here
 OPENAI_MODEL=gpt-4o
 
+# Option 1b: OpenAI-compatible provider
+# OPENAI_COMPAT_BASE_URL=https://your-provider.example.com/v1
+# OPENAI_COMPAT_API_KEY=your-openai-compatible-api-key-here
+# OPENAI_COMPAT_MODEL=gpt-4o-mini
+# OPENAI_COMPAT_ORG=optional-org-id
+# OPENAI_COMPAT_PROJECT=optional-project-id
+
 # Option 2: Azure OpenAI
 # AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
 # AZURE_OPENAI_API_KEY=your-azure-openai-api-key-here
 # AZURE_OPENAI_DEPLOYMENT=gpt-4o
 
 # AI Provider (auto-detected if not set)
 # AI_PROVIDER=OpenAI
+# AI_PROVIDER=OpenAICompatible
 
 # Discord notifications (optional)
 Discord__Enabled=false

docker/docker-compose.yml

@@ -44,6 +44,11 @@ services:
       - AZURE_OPENAI_DEPLOYMENT=${AZURE_OPENAI_DEPLOYMENT:-gpt-4o}
       - OPENAI_API_KEY=${OPENAI_API_KEY:-}
       - OPENAI_MODEL=${OPENAI_MODEL:-gpt-4o}
+      - OPENAI_COMPAT_BASE_URL=${OPENAI_COMPAT_BASE_URL:-}
+      - OPENAI_COMPAT_API_KEY=${OPENAI_COMPAT_API_KEY:-}
+      - OPENAI_COMPAT_MODEL=${OPENAI_COMPAT_MODEL:-gpt-4o}
+      - OPENAI_COMPAT_ORG=${OPENAI_COMPAT_ORG:-}
+      - OPENAI_COMPAT_PROJECT=${OPENAI_COMPAT_PROJECT:-}
       - AI_PROVIDER=${AI_PROVIDER:-}
       # Database connection string for SQL Server
       - ConnectionStrings__Default=Server=sqlserver;Database=TutorialValidatorTest;User=sa;Password=YourStrong!Password123;TrustServerCertificate=true;Encrypt=false

src/Validator.Analyst/Analysis/AIConfiguration.cs

@@ -6,7 +6,7 @@ namespace Validator.Analyst.Analysis;
 public class AIConfiguration
 {
     /// <summary>
-    /// AI provider type: "AzureOpenAI" or "OpenAI".
+    /// AI provider type: "AzureOpenAI", "OpenAI", or "OpenAICompatible".
     /// </summary>
     public string Provider { get; set; } = "AzureOpenAI";
 
@@ -29,4 +29,19 @@ public class AIConfiguration
     /// Model ID to use (defaults to DeploymentName if not specified).
     /// </summary>
     public string? ModelId { get; set; }
+
+    /// <summary>
+    /// Base URL for OpenAI-compatible providers.
+    /// </summary>
+    public string? BaseUrl { get; set; }
+
+    /// <summary>
+    /// Optional organization identifier for OpenAI-compatible providers.
+    /// </summary>
+    public string? Organization { get; set; }
+
+    /// <summary>
+    /// Optional project identifier for OpenAI-compatible providers.
+    /// </summary>
+    public string? Project { get; set; }
 }

src/Validator.Analyst/Analysis/KernelFactory.cs

@@ -8,14 +8,18 @@ namespace Validator.Analyst.Analysis;
 /// </summary>
 public static class KernelFactory
 {
+    private const string ProviderAzureOpenAI = "AzureOpenAI";
+    private const string ProviderOpenAI = "OpenAI";
+    private const string ProviderOpenAICompatible = "OpenAICompatible";
+
     /// <summary>
     /// Creates a Kernel instance from configuration.
     /// </summary>
     public static Kernel CreateFromConfiguration(AIConfiguration config)
     {
         var builder = Kernel.CreateBuilder();
 
-        if (config.Provider.Equals("AzureOpenAI", StringComparison.OrdinalIgnoreCase))
+        if (config.Provider.Equals(ProviderAzureOpenAI, StringComparison.OrdinalIgnoreCase))
         {
             if (string.IsNullOrWhiteSpace(config.Endpoint))
                 throw new InvalidOperationException("Azure OpenAI endpoint is required");
@@ -28,7 +32,7 @@ public static Kernel CreateFromConfiguration(AIConfiguration config)
                 apiKey: config.ApiKey,
                 modelId: config.ModelId);
         }
-        else if (config.Provider.Equals("OpenAI", StringComparison.OrdinalIgnoreCase))
+        else if (config.Provider.Equals(ProviderOpenAI, StringComparison.OrdinalIgnoreCase))
         {
             if (string.IsNullOrWhiteSpace(config.ApiKey))
                 throw new InvalidOperationException("OpenAI API key is required");
@@ -37,9 +41,24 @@ public static Kernel CreateFromConfiguration(AIConfiguration config)
                 modelId: config.ModelId ?? config.DeploymentName,
                 apiKey: config.ApiKey);
         }
+        else if (config.Provider.Equals(ProviderOpenAICompatible, StringComparison.OrdinalIgnoreCase))
+        {
+            if (string.IsNullOrWhiteSpace(config.ApiKey))
+                throw new InvalidOperationException("OpenAI-compatible API key is required");
+            if (string.IsNullOrWhiteSpace(config.BaseUrl))
+                throw new InvalidOperationException("OpenAI-compatible base URL is required");
+
+            var endpoint = new Uri(config.BaseUrl, UriKind.Absolute);
+
+            builder.AddOpenAIChatCompletion(
+                modelId: config.ModelId ?? config.DeploymentName,
+                apiKey: config.ApiKey,
+                endpoint: endpoint);
+        }
         else
         {
-            throw new InvalidOperationException($"Unknown AI provider: {config.Provider}");
+            throw new InvalidOperationException(
+                $"Unknown AI provider: {config.Provider}. Supported providers: {ProviderAzureOpenAI}, {ProviderOpenAI}, {ProviderOpenAICompatible}.");
         }
 
         return builder.Build();
@@ -98,16 +117,27 @@ public static AIConfiguration LoadConfiguration(string? configPath = null)
         // Try to bind from "AI" section first
         configuration.GetSection("AI").Bind(aiConfig);
 
+        // Support existing AI:Model field by mapping it to ModelId when present.
+        var configuredModel = configuration["AI:Model"];
+        if (!string.IsNullOrEmpty(configuredModel) && string.IsNullOrEmpty(aiConfig.ModelId))
+        {
+            aiConfig.ModelId = configuredModel;
+        }
+
         // Override with environment variables if present
+        var explicitProvider = false;
         var provider = Environment.GetEnvironmentVariable("AI_PROVIDER");
         if (!string.IsNullOrEmpty(provider))
+        {
             aiConfig.Provider = provider;
+            explicitProvider = true;
+        }
 
         // Azure OpenAI environment variables
         var azureEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
-        if (!string.IsNullOrEmpty(azureEndpoint))
+        if (!string.IsNullOrEmpty(azureEndpoint) && !explicitProvider)
         {
-            aiConfig.Provider = "AzureOpenAI";
+            aiConfig.Provider = ProviderAzureOpenAI;
             aiConfig.Endpoint = azureEndpoint;
         }
 
@@ -119,18 +149,54 @@ public static AIConfiguration LoadConfiguration(string? configPath = null)
         if (!string.IsNullOrEmpty(azureDeployment))
             aiConfig.DeploymentName = azureDeployment;
 
+        // OpenAI-compatible environment variables
+        var openAiCompatBaseUrl = Environment.GetEnvironmentVariable("OPENAI_COMPAT_BASE_URL");
+        var openAiCompatApiKey = Environment.GetEnvironmentVariable("OPENAI_COMPAT_API_KEY");
+        var openAiCompatModel = Environment.GetEnvironmentVariable("OPENAI_COMPAT_MODEL");
+        var openAiCompatOrg = Environment.GetEnvironmentVariable("OPENAI_COMPAT_ORG");
+        var openAiCompatProject = Environment.GetEnvironmentVariable("OPENAI_COMPAT_PROJECT");
+
+        if (!string.IsNullOrEmpty(openAiCompatBaseUrl))
+            aiConfig.BaseUrl = openAiCompatBaseUrl;
+
+        if (!string.IsNullOrEmpty(openAiCompatOrg))
+            aiConfig.Organization = openAiCompatOrg;
+
+        if (!string.IsNullOrEmpty(openAiCompatProject))
+            aiConfig.Project = openAiCompatProject;
+
+        if (!string.IsNullOrEmpty(openAiCompatApiKey))
+            aiConfig.ApiKey = openAiCompatApiKey;
+
+        if (!string.IsNullOrEmpty(openAiCompatModel))
+            aiConfig.ModelId = openAiCompatModel;
+
+        if (!explicitProvider && !string.IsNullOrEmpty(openAiCompatBaseUrl) && !string.IsNullOrEmpty(openAiCompatApiKey))
+        {
+            aiConfig.Provider = ProviderOpenAICompatible;
+        }
+
         // OpenAI environment variables
         var openaiApiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY");
         if (!string.IsNullOrEmpty(openaiApiKey) && string.IsNullOrEmpty(aiConfig.ApiKey))
         {
-            aiConfig.Provider = "OpenAI";
+            if (!explicitProvider)
+            {
+                aiConfig.Provider = ProviderOpenAI;
+            }
             aiConfig.ApiKey = openaiApiKey;
         }
 
         var openaiModel = Environment.GetEnvironmentVariable("OPENAI_MODEL");
         if (!string.IsNullOrEmpty(openaiModel))
             aiConfig.ModelId = openaiModel;
 
+        if (aiConfig.Provider.Equals(ProviderOpenAICompatible, StringComparison.OrdinalIgnoreCase) &&
+            string.IsNullOrWhiteSpace(aiConfig.ModelId))
+        {
+            aiConfig.ModelId = aiConfig.DeploymentName;
+        }
+
         return aiConfig;
     }
 
@@ -142,16 +208,33 @@ public static void ValidateConfiguration(AIConfiguration config)
         if (string.IsNullOrWhiteSpace(config.ApiKey))
         {
             throw new InvalidOperationException(
-                "AI API key is required. Set AZURE_OPENAI_API_KEY or OPENAI_API_KEY environment variable, " +
+                "AI API key is required. Set AZURE_OPENAI_API_KEY, OPENAI_API_KEY, or OPENAI_COMPAT_API_KEY environment variable, " +
                 "or configure in appsettings.json under AI:ApiKey");
         }
 
-        if (config.Provider.Equals("AzureOpenAI", StringComparison.OrdinalIgnoreCase) && 
+        if (config.Provider.Equals(ProviderAzureOpenAI, StringComparison.OrdinalIgnoreCase) &&
             string.IsNullOrWhiteSpace(config.Endpoint))
         {
             throw new InvalidOperationException(
                 "Azure OpenAI endpoint is required. Set AZURE_OPENAI_ENDPOINT environment variable, " +
                 "or configure in appsettings.json under AI:Endpoint");
         }
+
+        if (config.Provider.Equals(ProviderOpenAICompatible, StringComparison.OrdinalIgnoreCase))
+        {
+            if (string.IsNullOrWhiteSpace(config.BaseUrl))
+            {
+                throw new InvalidOperationException(
+                    "OpenAI-compatible base URL is required. Set OPENAI_COMPAT_BASE_URL environment variable, " +
+                    "or configure in appsettings.json under AI:BaseUrl");
+            }
+
+            if (string.IsNullOrWhiteSpace(config.ModelId) && string.IsNullOrWhiteSpace(config.DeploymentName))
+            {
+                throw new InvalidOperationException(
+                    "OpenAI-compatible model is required. Set OPENAI_COMPAT_MODEL environment variable, " +
+                    "or configure in appsettings.json under AI:ModelId or AI:DeploymentName");
+            }
+        }
     }
 }