diff --git a/docs/ai/chat.md b/docs/ai/chat.md index 26d77fde..d708ceaa 100644 --- a/docs/ai/chat.md +++ b/docs/ai/chat.md @@ -2,6 +2,8 @@ sidebar_label: Chat Endpoint --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Chat Endpoint @@ -171,7 +173,10 @@ Chat maintains server-side conversation history per user and datasource. This en ## Server-Side Implementation -The Chat endpoint is automatically registered when you configure Reveal AI in your ASP.NET Core application: +The Chat endpoints are registered automatically when you configure Reveal AI in your application. No additional controller, route, or servlet wiring is required — both POST and DELETE endpoints are ready as soon as the AI services are added. + + + ```csharp title="Program.cs" using Reveal.Sdk; @@ -179,10 +184,8 @@ using Reveal.Sdk.AI; var builder = WebApplication.CreateBuilder(args); -// Add Reveal SDK builder.Services.AddControllers().AddReveal(revealBuilder => { - // Configure datasource provider revealBuilder.AddDataSourceProvider(); }); @@ -190,17 +193,75 @@ builder.Services.AddControllers().AddReveal(revealBuilder => builder.Services.AddRevealAI() .AddOpenAI(options => { - options.ApiKey = builder.Configuration["OpenAI:ApiKey"]; - options.ModelId = "gpt-4.1"; - }); + options.ApiKey = builder.Configuration["RevealAI:OpenAI:ApiKey"]; + options.Model = "gpt-4.1"; + }) + .UseMetadataCatalogFile("config/catalog.json"); var app = builder.Build(); - app.MapControllers(); app.Run(); ``` -No additional controller or routing configuration is needed. Both POST and DELETE endpoints are ready to use once you call `AddRevealAI()`. + + + + +```javascript title="server.js" +const reveal = require('reveal-sdk-node'); +const revealAI = require('reveal-sdk-node-ai'); +const express = require('express'); +const path = require('path'); + +const aiSettings = { + openai: { + ApiKey: process.env.OPENAI_API_KEY, + Model: 'gpt-4.1' + } +}; + +const revealOptions = { + dataSourceProvider: dataSourceProvider, + plugins: [ + revealAI.withOptions({ + defaultProvider: 'openai', + settings: aiSettings, + metadataCatalogFile: path.resolve(__dirname, 'Reveal', 'Metadata', 'catalog.json') + }) + ] +}; + +const app = express(); +app.use('/', reveal(revealOptions)); +app.listen(5111); +``` + + + + + +```java title="Application.java" +Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", System.getenv("OPENAI_API_KEY"), + "Model", "gpt-4.1")); + +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "openai", + Path.of("src", "main", "resources", "Reveal", "Metadata", "catalog.json") + .toAbsolutePath().normalize().toString(), + null, + null, + Map.of("settings", aiSettings)); + +IRevealServer revealServer = new RevealServerBuilder() + .setDataSourceProvider(dataSourceProvider) + .addPlugin(RevealAIPlugin.withOptions(aiPluginOptions)) + .build(); +``` + + + ## Metadata Configuration diff --git a/docs/ai/getting-started-html.md b/docs/ai/getting-started-html.md index 242decaa..de02cb3d 100644 --- a/docs/ai/getting-started-html.md +++ b/docs/ai/getting-started-html.md @@ -24,6 +24,12 @@ Before you begin, ensure you meet the [System Requirements](system-requirements. 2. [Reveal SDK AI Server](install-server-sdk.md) installed 3. **LLM Provider API Key** from [OpenAI](https://platform.openai.com/api-keys), [Anthropic](https://platform.anthropic.com/account/keys), or [Google Cloud](https://cloud.google.com/vertex-ai) +:::info Other server platforms + +This guide uses ASP.NET Core for the server. The Reveal SDK AI Server is also available for **Node.js** and **Java** — see [Install Server SDK](install-server-sdk.md) for the equivalent installation and configuration steps. The HTML/JavaScript client below is identical regardless of which server you choose. + +::: + ## Step 1: Create the ASP.NET Core Server ### 1.1 Create a New ASP.NET Core Web API Project diff --git a/docs/ai/install-server-sdk.md b/docs/ai/install-server-sdk.md index d036edc0..8600f909 100644 --- a/docs/ai/install-server-sdk.md +++ b/docs/ai/install-server-sdk.md @@ -2,35 +2,39 @@ sidebar_label: Install Server SDK --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Installing the AI Server SDK The Reveal SDK AI Server provides the backend services needed to power AI features in your applications. It integrates with LLM providers and manages AI operations like insight generation, dashboard creation, and conversational analytics. +The AI Server SDK ships for **ASP.NET Core**, **Node.js**, and **Java**. The setup steps map one-to-one across platforms — install the AI package, configure an LLM provider, point at a metadata catalog, and run. + ## Prerequisites Before installing the AI Server SDK, ensure you have: 1. The base [Reveal SDK Server](/web/install-server-sdk) installed and configured -2. .NET 8.0 or higher +2. The platform runtime for your project: + - **ASP.NET Core**: .NET 8.0 or higher + - **Node.js**: Node.js 16 or higher + - **Java**: Java 17 or higher and Maven 3.6 or higher 3. Access to at least one LLM provider (OpenAI, Anthropic, Google, etc.) 4. LLM provider API keys configured -## Installation Methods - -### ASP.NET Core - -The AI Server SDK for ASP.NET Core is distributed as a NuGet package. - -#### Step 1: Install the NuGet Package +## Step 1: Install the AI Package -Right-click your Solution or Project and select **Manage NuGet Packages** for Solution. + + -![](../web/images/getting-started-nuget-packages-manage.jpg) +The AI Server SDK for ASP.NET Core is distributed as a NuGet package. Right-click your Solution or Project and select **Manage NuGet Packages**, then install **Reveal.Sdk.AI.AspNetCore**. -In the package manager dialog, open the **Browse** tab and install the **Reveal.Sdk.AI.AspNetCore** NuGet package into your project. +Or using the .NET CLI: -**Package Name:** `Reveal.Sdk.AI.AspNetCore` +```bash +dotnet add package Reveal.Sdk.AI.AspNetCore +``` Or using the Package Manager Console: @@ -38,17 +42,60 @@ Or using the Package Manager Console: Install-Package Reveal.Sdk.AI.AspNetCore ``` -Or using the .NET CLI: + + + + +Install the **reveal-sdk-node-ai** npm package: + +```bash npm2yarn +npm install reveal-sdk-node-ai +``` + + + + + +Add the Reveal Maven repositories and the **reveal-sdk-ai** dependency to your `pom.xml`: + +```xml title="pom.xml" + + + reveal.public + https://maven.revealbi.io/repository/public + + + reveal.snapshots + https://maven.revealbi.io/repository/snapshots + + + + + + io.revealbi + reveal-sdk-ai + 1.0.6-SNAPSHOT + + +``` + +Then run: ```bash -dotnet add package Reveal.Sdk.AI.AspNetCore +mvn install ``` -#### Step 2: Configure Services + + + +## Step 2: Register the AI Services + +The AI SDK extends the base Reveal SDK, so you need both configured. Register the AI services where you wire up Reveal in your application. -Open and modify the `Program.cs` file to add the AI services. The AI SDK extends the base Reveal SDK, so you need both configured: + + -```csharp +```csharp title="Program.cs" using Reveal.Sdk; using Reveal.Sdk.AI; @@ -61,20 +108,78 @@ builder.Services.AddControllers().AddReveal(); builder.Services.AddRevealAI(); var app = builder.Build(); +app.MapControllers(); app.Run(); ``` -#### Step 3: Install and Configure an LLM Provider + + + -Each LLM provider is distributed as a separate NuGet package. Install the package for your chosen provider and register it after `AddRevealAI()`. +Add `revealAI.withOptions(...)` to the `plugins` array of your Reveal options: -For example, to use OpenAI: +```javascript title="server.js" +const reveal = require('reveal-sdk-node'); +const revealAI = require('reveal-sdk-node-ai'); +const express = require('express'); + +const revealOptions = { + plugins: [ + revealAI.withOptions({ + defaultProvider: 'openai', + settings: { /* configured in the next step */ } + }) + ] +}; + +const app = express(); +app.use('/', reveal(revealOptions)); +app.listen(5111); +``` + + + + + +Build a `RevealAIPluginOptions` and add `RevealAIPlugin.withOptions(...)` via `RevealServerBuilder.addPlugin(...)`: + +```java title="Application.java" +import io.revealbi.ai.RevealAIPlugin; +import io.revealbi.ai.RevealAIPluginOptions; +import io.revealbi.core.IRevealServer; +import io.revealbi.core.RevealServerBuilder; + +import java.util.Map; + +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "openai", + /* metadataCatalogFile */ "config/catalog.json", + /* metadataManager */ null, + /* contextManager */ null, + /* additionalOptions */ Map.of("settings", /* configured in the next step */ Map.of())); + +IRevealServer revealServer = new RevealServerBuilder() + .addPlugin(RevealAIPlugin.withOptions(aiPluginOptions)) + .build(); +``` + + + + +## Step 3: Install and Configure an LLM Provider + +Configure the LLM provider you want to use. Each provider topic ([OpenAI](providers-openai.md), [Azure OpenAI](providers-azure-openai.md), [Anthropic](providers-anthropic.md), [Google Gemini](providers-google-gemini.md)) has full setup details — what follows is the OpenAI quickstart. + + + + +Install the provider NuGet package and chain `.AddOpenAI(...)` after `AddRevealAI()`: ```bash dotnet add package Reveal.Sdk.AI.OpenAI ``` -```csharp +```csharp title="Program.cs" builder.Services.AddRevealAI() .AddOpenAI(options => { @@ -82,14 +187,61 @@ builder.Services.AddRevealAI() }); ``` -For detailed setup instructions for each provider, see the [Providers](/ai/providers-overview) section: + + + + +For Node.js, the provider packages are bundled with `reveal-sdk-node-ai` — no extra install is needed. Pass provider settings via the `settings` option using lowercase provider keys: + +```javascript title="server.js" +const aiSettings = { + openai: { + ApiKey: process.env.OPENAI_API_KEY, + Model: 'gpt-4.1' + } +}; + +const revealOptions = { + plugins: [ + revealAI.withOptions({ + defaultProvider: 'openai', + settings: aiSettings + }) + ] +}; +``` + + + + + +For Java, the provider implementations are bundled with `reveal-sdk-ai` — no extra dependency is needed. Pass provider settings via the `additionalOptions` map using lowercase provider keys: + +```java title="Application.java" +Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", System.getenv("OPENAI_API_KEY"), + "Model", "gpt-4.1")); + +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "openai", + "src/main/resources/Reveal/Metadata/catalog.json", + null, + null, + Map.of("settings", aiSettings)); +``` + + + -| Provider | NuGet Package | Guide | -|----------|--------------|-------| -| OpenAI | `Reveal.Sdk.AI.OpenAI` | [Setup guide](/ai/providers-openai) | -| Azure OpenAI | `Reveal.Sdk.AI.AzureOpenAI` | [Setup guide](/ai/providers-azure-openai) | -| Anthropic | `Reveal.Sdk.AI.Anthropic` | [Setup guide](/ai/providers-anthropic) | -| Google Gemini | `Reveal.Sdk.AI.Google` | [Setup guide](/ai/providers-google-gemini) | +Available built-in providers: + +| Provider | ASP.NET NuGet | Node.js / Java key | Guide | +|----------|--------------|--------------------|-------| +| OpenAI | `Reveal.Sdk.AI.OpenAI` | `openai` | [Setup guide](/ai/providers-openai) | +| Azure OpenAI | `Reveal.Sdk.AI.AzureOpenAI` | `azure-openai` | [Setup guide](/ai/providers-azure-openai) | +| Anthropic | `Reveal.Sdk.AI.Anthropic` | `anthropic` | [Setup guide](/ai/providers-anthropic) | +| Google Gemini | `Reveal.Sdk.AI.Google` | `google` | [Setup guide](/ai/providers-google-gemini) | :::danger Never Commit API Keys @@ -97,9 +249,9 @@ Never commit API keys to source control. Always use environment variables, User ::: -#### Step 4: Install and Configure a Metadata Provider +## Step 4: Install and Configure a Metadata Provider -The metadata catalog can be loaded from a JSON file on disk or from a completely custom provider (e.g., database-backed). For the built-in file provider, you can simply set it up like so (minimal example): +The metadata catalog tells the AI which datasources exist. It can be loaded from a JSON file on disk or from a custom provider (e.g., database-backed). For the built-in file provider, point the AI builder at a JSON catalog. **1. Create a catalog file:** @@ -108,7 +260,7 @@ The metadata catalog can be loaded from a JSON file on disk or from a completely "Datasources": [ { "Id": "NorthwindDB", - "Provider": "SQLServer", + "Provider": "SQLServer" } ] } @@ -116,16 +268,53 @@ The metadata catalog can be loaded from a JSON file on disk or from a completely **2. Point the builder at the file:** + + + ```csharp title="Program.cs" builder.Services.AddRevealAI() .UseMetadataCatalogFile("config/catalog.json"); ``` + + + + +```javascript title="server.js" +const path = require('path'); + +revealAI.withOptions({ + defaultProvider: 'openai', + settings: aiSettings, + metadataCatalogFile: path.resolve(__dirname, 'config', 'catalog.json') +}); +``` + + + + + +```java title="Application.java" +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "openai", + Path.of("src", "main", "resources", "Reveal", "Metadata", "catalog.json") + .toAbsolutePath().normalize().toString(), + null, + null, + Map.of("settings", aiSettings)); +``` + + + + Both absolute and relative paths are supported. Relative paths are resolved against the application's current working directory. -#### Complete Example +## Complete Example + +Here's a complete server with the AI features configured end-to-end. -Here's a complete `Program.cs` with AI features configured: + + ```csharp title="Program.cs" using Reveal.Sdk; @@ -170,41 +359,160 @@ app.MapControllers(); app.Run(); ``` -### Node.js (Coming Soon) + + + + +```javascript title="server.js" +const reveal = require('reveal-sdk-node'); +const revealAI = require('reveal-sdk-node-ai'); +const express = require('express'); +const cors = require('cors'); +const path = require('path'); +const os = require('os'); + +const aiSettings = { + openai: { + ApiKey: process.env.OPENAI_API_KEY, + Model: 'gpt-4.1' + } +}; + +const revealOptions = { + plugins: [ + revealAI.withOptions({ + defaultProvider: 'openai', + settings: aiSettings, + metadataCatalogFile: path.resolve(__dirname, 'Reveal', 'Metadata', 'catalog.json'), + metadataManager: { + outputPath: path.resolve(os.homedir(), 'AImetadata'), + } + }) + ] +}; + +const app = express(); +app.use(cors()); +app.use('/', reveal(revealOptions)); + +const PORT = parseInt(process.env.PORT || '5111', 10); +app.listen(PORT, () => { + console.log(`Reveal AI server running on http://localhost:${PORT}`); +}); +``` + + -Node.js support for the AI Server SDK is under development and will be available in a future release. + -For now, ASP.NET Core is the recommended server platform for AI features. +```java title="Application.java" +package com.example; -### Java (Coming Soon) +import io.revealbi.ai.RevealAIPlugin; +import io.revealbi.ai.RevealAIPluginOptions; +import io.revealbi.core.IRevealServer; +import io.revealbi.core.RevealServerBuilder; +import io.revealbi.servlet.RevealEngineServlet; +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; +import org.springframework.boot.web.servlet.ServletRegistrationBean; +import org.springframework.context.annotation.Bean; -Java support for the AI Server SDK is under development and will be available in a future release. +import java.nio.file.Path; +import java.util.Map; -For now, ASP.NET Core is the recommended server platform for AI features. +@SpringBootApplication +public class Application { + public static void main(String[] args) { + SpringApplication.run(Application.class, args); + } + + @Bean + public IRevealServer revealServer() { + Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", System.getenv("OPENAI_API_KEY"), + "Model", "gpt-4.1")); + + RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "openai", + Path.of("src", "main", "resources", "Reveal", "Metadata", "catalog.json") + .toAbsolutePath().normalize().toString(), + new RevealAIPluginOptions.MetadataManagerOptions( + Path.of(System.getProperty("user.home"), "AImetadata").toString()), + null, + Map.of("settings", aiSettings)); + + return new RevealServerBuilder() + .addPlugin(RevealAIPlugin.withOptions(aiPluginOptions)) + .build(); + } + + @Bean + ServletRegistrationBean revealServlet(IRevealServer revealServer) { + ServletRegistrationBean registration = + new ServletRegistrationBean<>(new RevealEngineServlet(revealServer), "/*"); + registration.setAsyncSupported(true); + registration.setLoadOnStartup(1); + return registration; + } +} +``` + + + ## Verify Installation -After installation, verify the AI SDK is properly configured: +After installation, verify the AI SDK is properly configured. ### Step 1: Run Your Application + + + ```bash dotnet run ``` -### Step 2: Check AI Endpoints + + + + +```bash +node server.js +``` -The AI SDK adds several endpoints under `/api/reveal/ai/`: + -Test the providers endpoint: + ```bash -curl http://localhost:5000/api/reveal/ai/providers +mvn spring-boot:run ``` -Expected response: + + + +### Step 2: Check AI Endpoints + +The AI SDK adds endpoints under `/api/reveal/ai/`. Test the metadata status endpoint: + +```bash +curl http://localhost:5111/api/reveal/ai/metadata/status +``` + +Expected response once the system is ready: + ```json { - "providers": ["openai", "anthropic"] + "status": "Completed", + "isInitialized": true } ``` + +:::info Get the Code + +A complete multi-platform sample is available on [GitHub](https://github.com/RevealBi/sdk-samples-ai), with `aspnet/`, `node/`, and `java/` sub-folders for each server platform. + +::: diff --git a/docs/ai/metadata-catalog.md b/docs/ai/metadata-catalog.md index 8716a6bc..385a417f 100644 --- a/docs/ai/metadata-catalog.md +++ b/docs/ai/metadata-catalog.md @@ -2,6 +2,8 @@ sidebar_label: Metadata Catalog --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Metadata Catalog @@ -162,16 +164,60 @@ Store the catalog in a standalone JSON file. This is the simplest approach and i **2. Point the builder at the file:** + + + ```csharp title="Program.cs" builder.Services.AddRevealAI() .UseMetadataCatalogFile("config/catalog.json") .AddOpenAI(); ``` + + + + +Pass the catalog path via the `metadataCatalogFile` option of the AI plugin: + +```javascript title="server.js" +const path = require('path'); + +revealAI.withOptions({ + defaultProvider: 'openai', + settings: aiSettings, + metadataCatalogFile: path.resolve(__dirname, 'config', 'catalog.json') +}); +``` + + + + + +Pass the catalog path as the second argument to `RevealAIPluginOptions`: + +```java title="Application.java" +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "openai", + Path.of("src", "main", "resources", "Reveal", "Metadata", "catalog.json") + .toAbsolutePath().normalize().toString(), + null, + null, + Map.of("settings", aiSettings)); +``` + + + + Both absolute and relative paths are supported. Relative paths are resolved against the application's current working directory. ### Option 2: Custom Provider +:::info ASP.NET Core only + +The `IMetadataCatalogProvider` extension point is currently available on **ASP.NET Core** only. Node.js and Java applications must use the JSON file approach described above. + +::: + Implement `IMetadataCatalogProvider` to load datasource definitions from any source — a database, an API, a key vault, or anything else. **1. Implement the interface:** @@ -220,6 +266,9 @@ Your provider class is resolved through dependency injection, so you can inject The **Metadata Manager** controls where generated metadata files are written on disk. These files are ephemeral — they are generated automatically and can be regenerated at any time. + + + ```json title="appsettings.json" { "RevealAI": { @@ -230,6 +279,41 @@ The **Metadata Manager** controls where generated metadata files are written on } ``` + + + + +```javascript title="server.js" +const path = require('path'); +const os = require('os'); + +revealAI.withOptions({ + defaultProvider: 'openai', + settings: aiSettings, + metadataCatalogFile: 'config/catalog.json', + metadataManager: { + outputPath: path.resolve(os.homedir(), 'AImetadata') + } +}); +``` + + + + + +```java title="Application.java" +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "openai", + "config/catalog.json", + new RevealAIPluginOptions.MetadataManagerOptions( + Path.of(System.getProperty("user.home"), "AImetadata").toString()), + null, + Map.of("settings", aiSettings)); +``` + + + + | Property | Type | Required | Description | |----------|------|----------|-------------| | `OutputPath` | string | No | Directory where generated metadata files are stored. Defaults to `{user-home}/reveal/ai/metadata`. | @@ -240,6 +324,12 @@ The **Metadata Manager** controls where generated metadata files are written on The **Metadata Service** controls *when* metadata is generated. You can trigger generation at application startup, on a recurring schedule, or both. +:::info ASP.NET Core only + +Scheduled metadata generation via `MetadataService` is currently available on **ASP.NET Core** only. On Node.js and Java, metadata is generated on demand when the AI plugin needs it. + +::: + ```json title="appsettings.json" { "RevealAI": { @@ -260,7 +350,7 @@ The **Metadata Service** controls *when* metadata is generated. You can trigger ## Complete Configuration Example -Here is a complete example showing a catalog file, `appsettings.json` for the manager and service options, and the `Program.cs` setup: +Here is a complete example showing the catalog file, configuration, and server registration for each platform: ```json title="config/catalog.json" { @@ -297,6 +387,9 @@ Here is a complete example showing a catalog file, `appsettings.json` for the ma } ``` + + + ```json title="appsettings.json" { "RevealAI": { @@ -319,3 +412,64 @@ builder.Services.AddRevealAI() .UseMetadataCatalogFile("config/catalog.json") .AddOpenAI(); ``` + + + + + +```javascript title="server.js" +const reveal = require('reveal-sdk-node'); +const revealAI = require('reveal-sdk-node-ai'); +const express = require('express'); +const path = require('path'); + +const aiSettings = { + openai: { + ApiKey: process.env.OPENAI_API_KEY, + Model: 'gpt-4.1' + } +}; + +const revealOptions = { + plugins: [ + revealAI.withOptions({ + defaultProvider: 'openai', + settings: aiSettings, + metadataCatalogFile: path.resolve(__dirname, 'config', 'catalog.json'), + metadataManager: { + outputPath: path.resolve('D:', 'metadata', 'output') + } + }) + ] +}; + +const app = express(); +app.use('/', reveal(revealOptions)); +app.listen(5111); +``` + + + + + +```java title="Application.java" +Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", System.getenv("OPENAI_API_KEY"), + "Model", "gpt-4.1")); + +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "openai", + Path.of("config", "catalog.json").toAbsolutePath().normalize().toString(), + new RevealAIPluginOptions.MetadataManagerOptions( + Path.of("D:", "metadata", "output").toString()), + null, + Map.of("settings", aiSettings)); + +IRevealServer revealServer = new RevealServerBuilder() + .addPlugin(RevealAIPlugin.withOptions(aiPluginOptions)) + .build(); +``` + + + diff --git a/docs/ai/overview.md b/docs/ai/overview.md index f9dc22b4..4b6a597c 100644 --- a/docs/ai/overview.md +++ b/docs/ai/overview.md @@ -78,9 +78,9 @@ The client SDK runs in your web application and provides: - Built-in streaming support via Server-Sent Events (SSE) - Request cancellation and error handling -### Server SDK (ASP.NET Core) +### Server SDK (ASP.NET Core, Node.js, Java) -The server SDK handles: +The server SDK runs on ASP.NET Core, Node.js, and Java, and handles: - LLM provider integration (OpenAI, Anthropic, Google, etc.) - Datasource metadata generation and caching diff --git a/docs/ai/providers-anthropic.md b/docs/ai/providers-anthropic.md index 6b60f0b7..b6fb0c16 100644 --- a/docs/ai/providers-anthropic.md +++ b/docs/ai/providers-anthropic.md @@ -2,6 +2,8 @@ sidebar_label: Anthropic --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Anthropic Provider @@ -9,19 +11,52 @@ The Anthropic provider integrates Reveal SDK AI with Anthropic's Claude models, ## Installation + + + Install the Anthropic provider NuGet package: ```bash dotnet add package Reveal.Sdk.AI.Anthropic ``` + + + + +The Anthropic provider is bundled with `reveal-sdk-node-ai` — no extra package is required: + +```bash npm2yarn +npm install reveal-sdk-node-ai +``` + + + + + +The Anthropic provider is bundled with `reveal-sdk-ai` — no extra dependency is required beyond the base AI artifact: + +```xml title="pom.xml" + + io.revealbi + reveal-sdk-ai + 1.0.6-SNAPSHOT + +``` + + + + ## Configuration ### Basic Setup + + + Add the Anthropic provider in your `Program.cs`: -```csharp +```csharp title="Program.cs" using Reveal.Sdk; using Reveal.Sdk.AI; @@ -40,7 +75,76 @@ app.MapControllers(); app.Run(); ``` -### Using appsettings.json + + + + +Pass Anthropic settings under the `anthropic` key in the `settings` object: + +```javascript title="server.js" +const reveal = require('reveal-sdk-node'); +const revealAI = require('reveal-sdk-node-ai'); +const express = require('express'); + +const aiSettings = { + anthropic: { + ApiKey: process.env.ANTHROPIC_API_KEY, + Model: 'claude-sonnet-4-5' + } +}; + +const revealOptions = { + plugins: [ + revealAI.withOptions({ + defaultProvider: 'anthropic', + settings: aiSettings + }) + ] +}; + +const app = express(); +app.use('/', reveal(revealOptions)); +app.listen(5111); +``` + + + + + +Pass Anthropic settings under the `anthropic` key in the `settings` map and register the plugin: + +```java title="Application.java" +import io.revealbi.ai.RevealAIPlugin; +import io.revealbi.ai.RevealAIPluginOptions; +import io.revealbi.core.IRevealServer; +import io.revealbi.core.RevealServerBuilder; + +import java.util.Map; + +Map aiSettings = Map.of( + "anthropic", Map.of( + "ApiKey", System.getenv("ANTHROPIC_API_KEY"), + "Model", "claude-sonnet-4-5")); + +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "anthropic", + "config/catalog.json", + null, + null, + Map.of("settings", aiSettings)); + +IRevealServer revealServer = new RevealServerBuilder() + .addPlugin(RevealAIPlugin.withOptions(aiPluginOptions)) + .build(); +``` + + + + +### Using a Configuration File + + + The provider automatically binds to the `RevealAI:Anthropic` configuration section: @@ -63,8 +167,43 @@ builder.Services.AddRevealAI() .AddAnthropic(); ``` + + + + +Node.js does not bind to `appsettings.json`. Load your settings from environment variables, a secrets manager, or a local config file and pass them inline: + +```javascript title="server.js" +const aiSettings = { + anthropic: { + ApiKey: process.env.ANTHROPIC_API_KEY, + Model: 'claude-opus-4-1', + MaxTokens: 4096 + } +}; +``` + + + + + +Java does not bind to `appsettings.json`. Load your settings from environment variables, a secrets manager, or a local config file and pass them inline: + +```java title="Application.java" +Map aiSettings = Map.of( + "anthropic", Map.of( + "ApiKey", System.getenv("ANTHROPIC_API_KEY"), + "Model", "claude-opus-4-1", + "MaxTokens", 4096)); +``` + + + + ## Options +The same option names are used across all server platforms — ASP.NET sets them on the strongly-typed `options` object, Node.js and Java set them as keys in the `anthropic` settings map. + | Property | Type | Default | Description | |----------|------|---------|-------------| | `ApiKey` | `string` | `""` | **Required.** Your Anthropic API key. | @@ -81,6 +220,9 @@ Anthropic offers several Claude models. Here are some commonly used options: | `claude-sonnet-4-5` | Balanced performance and speed | | `claude-haiku-3-5` | Fastest and most cost-effective | + + + ```csharp builder.Services.AddRevealAI() .AddAnthropic(options => @@ -91,6 +233,35 @@ builder.Services.AddRevealAI() }); ``` + + + + +```javascript +const aiSettings = { + anthropic: { + ApiKey: process.env.ANTHROPIC_API_KEY, + Model: 'claude-sonnet-4-5', + MaxTokens: 8192 + } +}; +``` + + + + + +```java +Map aiSettings = Map.of( + "anthropic", Map.of( + "ApiKey", System.getenv("ANTHROPIC_API_KEY"), + "Model", "claude-sonnet-4-5", + "MaxTokens", 8192)); +``` + + + + ## Getting an API Key 1. Create an account at [console.anthropic.com](https://console.anthropic.com) diff --git a/docs/ai/providers-azure-openai.md b/docs/ai/providers-azure-openai.md index 77d2242d..a38291b5 100644 --- a/docs/ai/providers-azure-openai.md +++ b/docs/ai/providers-azure-openai.md @@ -2,6 +2,8 @@ sidebar_label: Azure OpenAI --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Azure OpenAI Provider @@ -9,19 +11,52 @@ The Azure OpenAI provider integrates Reveal SDK AI with Azure's OpenAI Service, ## Installation + + + Install the Azure OpenAI provider NuGet package: ```bash dotnet add package Reveal.Sdk.AI.AzureOpenAI ``` + + + + +The Azure OpenAI provider is bundled with `reveal-sdk-node-ai` — no extra package is required: + +```bash npm2yarn +npm install reveal-sdk-node-ai +``` + + + + + +The Azure OpenAI provider is bundled with `reveal-sdk-ai` — no extra dependency is required beyond the base AI artifact: + +```xml title="pom.xml" + + io.revealbi + reveal-sdk-ai + 1.0.6-SNAPSHOT + +``` + + + + ## Configuration ### Basic Setup + + + Add the Azure OpenAI provider in your `Program.cs`: -```csharp +```csharp title="Program.cs" using Reveal.Sdk; using Reveal.Sdk.AI; @@ -42,7 +77,78 @@ app.MapControllers(); app.Run(); ``` -### Using appsettings.json + + + + +Pass Azure OpenAI settings under the `azure-openai` key in the `settings` object: + +```javascript title="server.js" +const reveal = require('reveal-sdk-node'); +const revealAI = require('reveal-sdk-node-ai'); +const express = require('express'); + +const aiSettings = { + 'azure-openai': { + ApiKey: process.env.AZURE_OPENAI_API_KEY, + Endpoint: 'https://your-resource-name.openai.azure.com/', + DeploymentName: 'gpt-4o' + } +}; + +const revealOptions = { + plugins: [ + revealAI.withOptions({ + defaultProvider: 'azure-openai', + settings: aiSettings + }) + ] +}; + +const app = express(); +app.use('/', reveal(revealOptions)); +app.listen(5111); +``` + + + + + +Pass Azure OpenAI settings under the `azure-openai` key in the `settings` map and register the plugin: + +```java title="Application.java" +import io.revealbi.ai.RevealAIPlugin; +import io.revealbi.ai.RevealAIPluginOptions; +import io.revealbi.core.IRevealServer; +import io.revealbi.core.RevealServerBuilder; + +import java.util.Map; + +Map aiSettings = Map.of( + "azure-openai", Map.of( + "ApiKey", System.getenv("AZURE_OPENAI_API_KEY"), + "Endpoint", "https://your-resource-name.openai.azure.com/", + "DeploymentName", "gpt-4o")); + +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "azure-openai", + "config/catalog.json", + null, + null, + Map.of("settings", aiSettings)); + +IRevealServer revealServer = new RevealServerBuilder() + .addPlugin(RevealAIPlugin.withOptions(aiPluginOptions)) + .build(); +``` + + + + +### Using a Configuration File + + + The provider automatically binds to the `RevealAI:AzureOpenAI` configuration section: @@ -67,8 +173,47 @@ builder.Services.AddRevealAI() .AddAzureOpenAI(); ``` + + + + +Node.js does not bind to `appsettings.json`. Load your settings from environment variables, a secrets manager, or a local config file and pass them inline: + +```javascript title="server.js" +const aiSettings = { + 'azure-openai': { + ApiKey: process.env.AZURE_OPENAI_API_KEY, + Endpoint: 'https://your-resource-name.openai.azure.com/', + DeploymentName: 'gpt-4o', + Temperature: 0.0, + MaxTokens: 4096 + } +}; +``` + + + + + +Java does not bind to `appsettings.json`. Load your settings from environment variables, a secrets manager, or a local config file and pass them inline: + +```java title="Application.java" +Map aiSettings = Map.of( + "azure-openai", Map.of( + "ApiKey", System.getenv("AZURE_OPENAI_API_KEY"), + "Endpoint", "https://your-resource-name.openai.azure.com/", + "DeploymentName", "gpt-4o", + "Temperature", 0.0, + "MaxTokens", 4096)); +``` + + + + ## Options +The same option names are used across all server platforms — ASP.NET sets them on the strongly-typed `options` object, Node.js and Java set them as keys in the `azure-openai` settings map. + | Property | Type | Default | Description | |----------|------|---------|-------------| | `ApiKey` | `string` | `""` | **Required.** Your Azure OpenAI API key. | @@ -97,6 +242,9 @@ Like the OpenAI provider, the Azure OpenAI provider automatically detects reason - Temperature is disabled for reasoning models - Reasoning effort can be configured + + + ```csharp builder.Services.AddRevealAI() .AddAzureOpenAI(options => @@ -108,6 +256,37 @@ builder.Services.AddRevealAI() }); ``` + + + + +```javascript +const aiSettings = { + 'azure-openai': { + ApiKey: process.env.AZURE_OPENAI_API_KEY, + Endpoint: 'https://your-resource.openai.azure.com/', + DeploymentName: 'o3', + ReasoningEffort: 'Medium' + } +}; +``` + + + + + +```java +Map aiSettings = Map.of( + "azure-openai", Map.of( + "ApiKey", System.getenv("AZURE_OPENAI_API_KEY"), + "Endpoint", "https://your-resource.openai.azure.com/", + "DeploymentName", "o3", + "ReasoningEffort", "Medium")); +``` + + + + :::danger Never Commit API Keys Never commit API keys to source control. Always use environment variables, User Secrets, or a secure key management service. diff --git a/docs/ai/providers-building-custom.md b/docs/ai/providers-building-custom.md index 39a7ff5b..82e029bb 100644 --- a/docs/ai/providers-building-custom.md +++ b/docs/ai/providers-building-custom.md @@ -7,6 +7,12 @@ sidebar_label: Building a Custom Provider If you need to integrate with an LLM service that isn't supported out of the box, you can create a custom provider by implementing the `IAIProvider` interface and registering it with the SDK. +:::info ASP.NET Core only + +Custom providers built against the `IAIProvider` interface are currently supported on **ASP.NET Core** only. Node.js and Java applications must use one of the built-in providers — if your target service exposes an OpenAI-compatible API, use the [Custom Endpoints](providers-custom-endpoints.md) approach with the OpenAI provider. + +::: + ## Step 1: Create the Provider Class Implement the `IAIProvider` interface: diff --git a/docs/ai/providers-custom-endpoints.md b/docs/ai/providers-custom-endpoints.md index be668f95..2379fc36 100644 --- a/docs/ai/providers-custom-endpoints.md +++ b/docs/ai/providers-custom-endpoints.md @@ -2,6 +2,8 @@ sidebar_label: Custom Endpoints --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Custom Endpoints @@ -11,7 +13,10 @@ You can use the OpenAI provider with any OpenAI-compatible API endpoint. This is Set the `Endpoint` option on the OpenAI provider to point to your custom API: -```csharp + + + +```csharp title="Program.cs" builder.Services.AddRevealAI() .AddOpenAI(options => { @@ -35,12 +40,49 @@ Or using `appsettings.json`: } ``` + + + + +```javascript title="server.js" +const aiSettings = { + openai: { + ApiKey: 'your-api-key', + Endpoint: 'https://your-custom-endpoint.com/v1', + Model: 'your-model-name' + } +}; + +revealAI.withOptions({ + defaultProvider: 'openai', + settings: aiSettings +}); +``` + + + + + +```java title="Application.java" +Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", "your-api-key", + "Endpoint", "https://your-custom-endpoint.com/v1", + "Model", "your-model-name")); +``` + + + + ## Common Use Cases ### Local Model Servers Tools like [Ollama](https://ollama.ai), [LM Studio](https://lmstudio.ai), and [vLLM](https://github.com/vllm-project/vllm) expose OpenAI-compatible APIs that can be used directly: + + + ```csharp // Ollama example builder.Services.AddRevealAI() @@ -52,10 +94,44 @@ builder.Services.AddRevealAI() }); ``` + + + + +```javascript +// Ollama example +const aiSettings = { + openai: { + ApiKey: 'ollama', // Ollama doesn't require a real key + Endpoint: 'http://localhost:11434/v1', + Model: 'llama3' + } +}; +``` + + + + + +```java +// Ollama example +Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", "ollama", // Ollama doesn't require a real key + "Endpoint", "http://localhost:11434/v1", + "Model", "llama3")); +``` + + + + ### Third-Party Providers Many AI providers offer OpenAI-compatible endpoints: + + + ```csharp builder.Services.AddRevealAI() .AddOpenAI(options => @@ -66,6 +142,35 @@ builder.Services.AddRevealAI() }); ``` + + + + +```javascript +const aiSettings = { + openai: { + ApiKey: 'your-provider-api-key', + Endpoint: 'https://api.provider.com/v1', + Model: 'provider-model-name' + } +}; +``` + + + + + +```java +Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", "your-provider-api-key", + "Endpoint", "https://api.provider.com/v1", + "Model", "provider-model-name")); +``` + + + + ## Limitations When using custom endpoints, be aware of: diff --git a/docs/ai/providers-google-gemini.md b/docs/ai/providers-google-gemini.md index 61fab2c9..99b26369 100644 --- a/docs/ai/providers-google-gemini.md +++ b/docs/ai/providers-google-gemini.md @@ -2,6 +2,8 @@ sidebar_label: Google Gemini --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Google Gemini Provider @@ -9,19 +11,52 @@ The Google Gemini provider integrates Reveal SDK AI with Google Cloud's Vertex A ## Installation + + + Install the Google provider NuGet package: ```bash dotnet add package Reveal.Sdk.AI.Google ``` + + + + +The Google provider is bundled with `reveal-sdk-node-ai` — no extra package is required: + +```bash npm2yarn +npm install reveal-sdk-node-ai +``` + + + + + +The Google provider is bundled with `reveal-sdk-ai` — no extra dependency is required beyond the base AI artifact: + +```xml title="pom.xml" + + io.revealbi + reveal-sdk-ai + 1.0.6-SNAPSHOT + +``` + + + + ## Configuration ### Basic Setup + + + Add the Google Gemini provider in your `Program.cs`: -```csharp +```csharp title="Program.cs" using Reveal.Sdk; using Reveal.Sdk.AI; @@ -41,7 +76,76 @@ app.MapControllers(); app.Run(); ``` -### Using appsettings.json + + + + +Pass Google settings under the `google` key in the `settings` object: + +```javascript title="server.js" +const reveal = require('reveal-sdk-node'); +const revealAI = require('reveal-sdk-node-ai'); +const express = require('express'); + +const aiSettings = { + google: { + ProjectId: process.env.GCP_PROJECT_ID, + CredentialsPath: '/path/to/credentials.json' + } +}; + +const revealOptions = { + plugins: [ + revealAI.withOptions({ + defaultProvider: 'google', + settings: aiSettings + }) + ] +}; + +const app = express(); +app.use('/', reveal(revealOptions)); +app.listen(5111); +``` + + + + + +Pass Google settings under the `google` key in the `settings` map and register the plugin: + +```java title="Application.java" +import io.revealbi.ai.RevealAIPlugin; +import io.revealbi.ai.RevealAIPluginOptions; +import io.revealbi.core.IRevealServer; +import io.revealbi.core.RevealServerBuilder; + +import java.util.Map; + +Map aiSettings = Map.of( + "google", Map.of( + "ProjectId", System.getenv("GCP_PROJECT_ID"), + "CredentialsPath", "/path/to/credentials.json")); + +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "google", + "config/catalog.json", + null, + null, + Map.of("settings", aiSettings)); + +IRevealServer revealServer = new RevealServerBuilder() + .addPlugin(RevealAIPlugin.withOptions(aiPluginOptions)) + .build(); +``` + + + + +### Using a Configuration File + + + The provider automatically binds to the `RevealAI:Google` configuration section: @@ -65,8 +169,45 @@ builder.Services.AddRevealAI() .AddGoogle(); ``` + + + + +Node.js does not bind to `appsettings.json`. Load your settings from environment variables, a secrets manager, or a local config file and pass them inline: + +```javascript title="server.js" +const aiSettings = { + google: { + ProjectId: process.env.GCP_PROJECT_ID, + CredentialsPath: '/path/to/credentials.json', + Location: 'us-central1', + Model: 'gemini-2.5-pro' + } +}; +``` + + + + + +Java does not bind to `appsettings.json`. Load your settings from environment variables, a secrets manager, or a local config file and pass them inline: + +```java title="Application.java" +Map aiSettings = Map.of( + "google", Map.of( + "ProjectId", System.getenv("GCP_PROJECT_ID"), + "CredentialsPath", "/path/to/credentials.json", + "Location", "us-central1", + "Model", "gemini-2.5-pro")); +``` + + + + ## Options +The same option names are used across all server platforms — ASP.NET sets them on the strongly-typed `options` object, Node.js and Java set them as keys in the `google` settings map. + | Property | Type | Default | Description | |----------|------|---------|-------------| | `ProjectId` | `string` | `""` | **Required.** Your Google Cloud project ID. | @@ -107,6 +248,9 @@ The provider sets the `GOOGLE_APPLICATION_CREDENTIALS` environment variable auto | `gemini-2.5-flash` | Fast and efficient for most tasks | | `gemini-2.0-flash` | Previous generation fast model | + + + ```csharp builder.Services.AddRevealAI() .AddGoogle(options => @@ -118,6 +262,37 @@ builder.Services.AddRevealAI() }); ``` + + + + +```javascript +const aiSettings = { + google: { + ProjectId: 'your-project-id', + CredentialsPath: '/path/to/credentials.json', + Model: 'gemini-2.5-flash', + Location: 'us-east1' + } +}; +``` + + + + + +```java +Map aiSettings = Map.of( + "google", Map.of( + "ProjectId", "your-project-id", + "CredentialsPath", "/path/to/credentials.json", + "Model", "gemini-2.5-flash", + "Location", "us-east1")); +``` + + + + ## Regions The `Location` option determines which Google Cloud region processes your requests. Common options include: diff --git a/docs/ai/providers-openai.md b/docs/ai/providers-openai.md index 0aa980f0..5365bdf8 100644 --- a/docs/ai/providers-openai.md +++ b/docs/ai/providers-openai.md @@ -2,6 +2,8 @@ sidebar_label: OpenAI --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # OpenAI Provider @@ -9,19 +11,52 @@ The OpenAI provider integrates Reveal SDK AI with OpenAI's chat completion API, ## Installation + + + Install the OpenAI provider NuGet package: ```bash dotnet add package Reveal.Sdk.AI.OpenAI ``` + + + + +The OpenAI provider is bundled with `reveal-sdk-node-ai` — no extra package is required: + +```bash npm2yarn +npm install reveal-sdk-node-ai +``` + + + + + +The OpenAI provider is bundled with `reveal-sdk-ai` — no extra dependency is required beyond the base AI artifact: + +```xml title="pom.xml" + + io.revealbi + reveal-sdk-ai + 1.0.6-SNAPSHOT + +``` + + + + ## Configuration ### Basic Setup + + + Add the OpenAI provider in your `Program.cs`: -```csharp +```csharp title="Program.cs" using Reveal.Sdk; using Reveal.Sdk.AI; @@ -40,7 +75,76 @@ app.MapControllers(); app.Run(); ``` -### Using appsettings.json + + + + +Pass OpenAI settings under the `openai` key in the `settings` object: + +```javascript title="server.js" +const reveal = require('reveal-sdk-node'); +const revealAI = require('reveal-sdk-node-ai'); +const express = require('express'); + +const aiSettings = { + openai: { + ApiKey: process.env.OPENAI_API_KEY, + Model: 'gpt-4.1' + } +}; + +const revealOptions = { + plugins: [ + revealAI.withOptions({ + defaultProvider: 'openai', + settings: aiSettings + }) + ] +}; + +const app = express(); +app.use('/', reveal(revealOptions)); +app.listen(5111); +``` + + + + + +Pass OpenAI settings under the `openai` key in the `settings` map and register the plugin: + +```java title="Application.java" +import io.revealbi.ai.RevealAIPlugin; +import io.revealbi.ai.RevealAIPluginOptions; +import io.revealbi.core.IRevealServer; +import io.revealbi.core.RevealServerBuilder; + +import java.util.Map; + +Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", System.getenv("OPENAI_API_KEY"), + "Model", "gpt-4.1")); + +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "openai", + "config/catalog.json", + null, + null, + Map.of("settings", aiSettings)); + +IRevealServer revealServer = new RevealServerBuilder() + .addPlugin(RevealAIPlugin.withOptions(aiPluginOptions)) + .build(); +``` + + + + +### Using a Configuration File + + + The provider automatically binds to the `RevealAI:OpenAI` configuration section: @@ -64,8 +168,50 @@ builder.Services.AddRevealAI() .AddOpenAI(); ``` + + + + +Node.js does not bind to `appsettings.json`. Load your settings from environment variables, a secrets manager, or a local config file and pass them inline: + +```javascript title="server.js" +const aiSettings = { + openai: { + ApiKey: process.env.OPENAI_API_KEY, + Model: 'gpt-4.1', + Temperature: 0.0, + MaxTokens: 4096 + } +}; + +revealAI.withOptions({ + defaultProvider: 'openai', + settings: aiSettings +}); +``` + + + + + +Java does not bind to `appsettings.json`. Load your settings from environment variables, a secrets manager, or a local config file and pass them inline: + +```java title="Application.java" +Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", System.getenv("OPENAI_API_KEY"), + "Model", "gpt-4.1", + "Temperature", 0.0, + "MaxTokens", 4096)); +``` + + + + ## Options +The same option names are used across all server platforms — ASP.NET sets them on the strongly-typed `options` object, Node.js and Java set them as keys in the `openai` settings map. + | Property | Type | Default | Description | |----------|------|---------|-------------| | `ApiKey` | `string` | `""` | **Required.** Your OpenAI API key. | @@ -83,6 +229,9 @@ The provider automatically detects reasoning models (o1, o3, o4, gpt-5) and adju - Temperature is disabled for reasoning models - Reasoning effort can be configured via the `ReasoningEffort` option + + + ```csharp builder.Services.AddRevealAI() .AddOpenAI(options => @@ -93,9 +242,41 @@ builder.Services.AddRevealAI() }); ``` + + + + +```javascript +const aiSettings = { + openai: { + ApiKey: process.env.OPENAI_API_KEY, + Model: 'o3', + ReasoningEffort: 'Medium' + } +}; +``` + + + + + +```java +Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", System.getenv("OPENAI_API_KEY"), + "Model", "o3", + "ReasoningEffort", "Medium")); +``` + + + + ## Custom Endpoints -If you are using an OpenAI-compatible API (such as a local model server), you can specify a custom endpoint: +If you are using an OpenAI-compatible API (such as a local model server), specify a custom endpoint: + + + ```csharp builder.Services.AddRevealAI() @@ -107,6 +288,35 @@ builder.Services.AddRevealAI() }); ``` + + + + +```javascript +const aiSettings = { + openai: { + ApiKey: 'your-api-key', + Endpoint: 'https://your-custom-endpoint.com/v1', + Model: 'your-model-name' + } +}; +``` + + + + + +```java +Map aiSettings = Map.of( + "openai", Map.of( + "ApiKey", "your-api-key", + "Endpoint", "https://your-custom-endpoint.com/v1", + "Model", "your-model-name")); +``` + + + + :::danger Never Commit API Keys Never commit API keys to source control. Always use environment variables, User Secrets, or a secure key management service. diff --git a/docs/ai/providers-overview.md b/docs/ai/providers-overview.md index 274ff651..9fad8cc7 100644 --- a/docs/ai/providers-overview.md +++ b/docs/ai/providers-overview.md @@ -2,27 +2,34 @@ sidebar_label: Overview --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # AI Providers Overview -Reveal SDK AI uses a provider-based architecture that lets you integrate with different large language model (LLM) services. Each provider is distributed as a separate NuGet package, so you only install what you need. +Reveal SDK AI uses a provider-based architecture that lets you integrate with different large language model (LLM) services. The same set of providers is available on **ASP.NET Core**, **Node.js**, and **Java** — only the registration syntax differs. ## Available Providers -| Provider | NuGet Package | Extension Method | -|----------|--------------|-----------------| -| [OpenAI](providers-openai.md) | `Reveal.Sdk.AI.OpenAI` | `.AddOpenAI()` | -| [Azure OpenAI](providers-azure-openai.md) | `Reveal.Sdk.AI.AzureOpenAI` | `.AddAzureOpenAI()` | -| [Anthropic](providers-anthropic.md) | `Reveal.Sdk.AI.Anthropic` | `.AddAnthropic()` | -| [Google Gemini](providers-google-gemini.md) | `Reveal.Sdk.AI.Google` | `.AddGoogle()` | +| Provider | ASP.NET NuGet | Node.js / Java key | Extension Method (ASP.NET) | +|----------|--------------|--------------------|----------------------------| +| [OpenAI](providers-openai.md) | `Reveal.Sdk.AI.OpenAI` | `openai` | `.AddOpenAI()` | +| [Azure OpenAI](providers-azure-openai.md) | `Reveal.Sdk.AI.AzureOpenAI` | `azure-openai` | `.AddAzureOpenAI()` | +| [Anthropic](providers-anthropic.md) | `Reveal.Sdk.AI.Anthropic` | `anthropic` | `.AddAnthropic()` | +| [Google Gemini](providers-google-gemini.md) | `Reveal.Sdk.AI.Google` | `google` | `.AddGoogle()` | + +For ASP.NET Core, each provider is a separate NuGet package — install only the ones you need. For Node.js (`reveal-sdk-node-ai`) and Java (`reveal-sdk-ai`), the provider implementations are bundled in the main AI package. ## How Providers Work -All providers implement the `IAIProvider` interface and are registered through the `IRevealAIBuilder` fluent API. The SDK uses dependency injection with keyed services, allowing you to register multiple providers simultaneously. +All providers implement a common provider interface and are registered with the AI runtime. The SDK supports registering multiple providers simultaneously and resolves the appropriate one based on the request or a configured default. ### Registering Providers -Providers are added by chaining extension methods after `AddRevealAI()`: + + + +Chain extension methods after `AddRevealAI()`: ```csharp builder.Services.AddRevealAI() @@ -36,9 +43,50 @@ builder.Services.AddRevealAI() }); ``` + + + + +Pass each provider's settings under its lowercase key in the `settings` object: + +```javascript +revealAI.withOptions({ + defaultProvider: 'openai', + settings: { + openai: { ApiKey: 'your-api-key' }, + anthropic: { ApiKey: 'your-api-key' } + } +}); +``` + + + + + +Pass each provider's settings under its lowercase key in the `settings` map: + +```java +Map aiSettings = Map.of( + "openai", Map.of("ApiKey", "your-api-key"), + "anthropic", Map.of("ApiKey", "your-api-key")); + +RevealAIPluginOptions aiPluginOptions = new RevealAIPluginOptions( + "openai", + "config/catalog.json", + null, + null, + Map.of("settings", aiSettings)); +``` + + + + ### Default Provider -The SDK uses a default provider when no specific provider is requested. You can configure this in `appsettings.json`: +The SDK uses a default provider when no specific provider is requested. Available provider keys: `openai`, `azure-openai`, `anthropic`, `google`. + + + ```json title="appsettings.json" { @@ -48,11 +96,37 @@ The SDK uses a default provider when no specific provider is requested. You can } ``` -Available provider keys: `openai`, `azure-openai`, `anthropic`, `google`. + + + + +```javascript +revealAI.withOptions({ + defaultProvider: 'openai', + settings: { /* ... */ } +}); +``` + + + + + +The default provider is the first argument to the `RevealAIPluginOptions` constructor: + +```java +new RevealAIPluginOptions( + "openai", // defaultProvider + /* catalog file */ "config/catalog.json", + null, null, + Map.of("settings", aiSettings)); +``` + + + ### Configuration Binding -All providers support configuration binding from `appsettings.json` under the `RevealAI` section. Options set in code take precedence over configuration file values: +For ASP.NET Core, all providers support configuration binding from `appsettings.json` under the `RevealAI` section. Options set in code take precedence over configuration file values: ```json title="appsettings.json" { @@ -69,6 +143,8 @@ All providers support configuration binding from `appsettings.json` under the `R } ``` +For Node.js and Java, load your settings from environment variables, a secrets manager, or a local config file and pass them inline at startup. + ### Multiple Providers You can register multiple providers and the SDK will resolve the appropriate one based on the request. This is useful for scenarios such as: @@ -77,6 +153,9 @@ You can register multiple providers and the SDK will resolve the appropriate one - Providing fallback options - Cost optimization by routing simpler tasks to less expensive models + + + ```csharp builder.Services.AddRevealAI() .AddOpenAI() // Registered as "openai" @@ -84,6 +163,35 @@ builder.Services.AddRevealAI() .AddGoogle(); // Registered as "google" ``` + + + + +```javascript +revealAI.withOptions({ + defaultProvider: 'openai', + settings: { + openai: { ApiKey: process.env.OPENAI_API_KEY }, + anthropic: { ApiKey: process.env.ANTHROPIC_API_KEY }, + google: { ProjectId: process.env.GCP_PROJECT_ID } + } +}); +``` + + + + + +```java +Map aiSettings = Map.of( + "openai", Map.of("ApiKey", System.getenv("OPENAI_API_KEY")), + "anthropic", Map.of("ApiKey", System.getenv("ANTHROPIC_API_KEY")), + "google", Map.of("ProjectId", System.getenv("GCP_PROJECT_ID"))); +``` + + + + ## Custom Providers -If you need to integrate with an LLM service that isn't supported out of the box, you can [build a custom provider](providers-building-custom.md). +If you need to integrate with an LLM service that isn't supported out of the box, you can [build a custom provider](providers-building-custom.md). Custom providers are currently supported on ASP.NET Core only. diff --git a/docs/ai/system-requirements.md b/docs/ai/system-requirements.md index eb7bbe1c..835c6c8c 100644 --- a/docs/ai/system-requirements.md +++ b/docs/ai/system-requirements.md @@ -34,9 +34,24 @@ While the client SDK works with vanilla JavaScript, it integrates seamlessly wit ## Server SDK Requirements +The AI Server SDK runs on ASP.NET Core, Node.js, and Java. + ### ASP.NET Core -- ASP.NET 8.0 or higher +- .NET 8.0 or higher +- `Reveal.Sdk.AspNetCore` 1.8.4 or higher + +### Node.js (Preview) + +- Node.js 16 or higher +- `reveal-sdk-node` 2.0.0 or higher + +### Java (Preview) + +- Java 17 or higher +- Maven 3.6 or higher +- `io.revealbi:reveal-sdk-servlet` 2.0.0 or higher (or the Spring Boot equivalent) +- A Jakarta EE 9 compliant servlet container (e.g., Tomcat 10+, Jetty 12+) ## Reveal SDK Base Requirements @@ -44,7 +59,7 @@ Reveal SDK AI extends the base Reveal SDK, so you must also meet the standard Re - Valid Reveal SDK license - Reveal SDK Web (JavaScript) package -- Reveal.Sdk.AspNetCore package (compatible version) +- The base Reveal Server SDK package for your platform (`Reveal.Sdk.AspNetCore`, `reveal-sdk-node`, or `io.revealbi:reveal-sdk-servlet`) ### TypeScript Support