@breadstone/archipel-platform-intelligence

Intelligence infrastructure for NestJS — capability registry, text generation, and provider loaders for OpenAI, Anthropic, Google, and Grok.

Features

• Multi-provider — OpenAI, Anthropic, Google (Gemini), and Grok via @ai-sdk/*
• Capability registry — Register and discover provider capabilities at startup
• Text generation — Unified IntelligenceTextGenerator with timeout, retry, and backoff
• Eager validation — Missing API keys or unsupported providers caught at module init
• Tree-shakable — Provider loaders in separate sub-exports to avoid bundling unused SDKs
• Health checks — IntelligenceHealthIndicator for readiness probes (separate /health subpath)

⚠️ Environment Variables

| Variable | Required | Default | Description | | -------------------------------- | -------- | ------- | ----------------------------- | | INTELLIGENCE_MODEL | no | - | AI model identifier | | INTELLIGENCE_TEMPERATURE | no | 0.7 | AI model sampling temperature | | INTELLIGENCE_TOP_P | no | 1 | AI model top-p value | | INTELLIGENCE_MAX_OUTPUT_TOKENS | no | 1024 | Max generated output tokens | | OPENAI_API_KEY | no | - | OpenAI / Grok API key | | ANTHROPIC_API_KEY | no | - | Anthropic API key | | GOOGLE_GENERATIVE_AI_API_KEY | no | - | Google Gemini API key |

Quick Start

import { IntelligenceModule } from '@breadstone/archipel-platform-intelligence';

@Module({
  imports: [IntelligenceModule],
})
export class AppModule {}

Import Options

// Main import (module, text generator, capability registry)
import { IntelligenceModule, IntelligenceTextGenerator } from '@breadstone/archipel-platform-intelligence';

// Provider-specific loaders (tree-shakable sub-exports)
import { loadOpenAILanguageModel } from '@breadstone/archipel-platform-intelligence/openai';
import { loadAnthropicLanguageModel } from '@breadstone/archipel-platform-intelligence/anthropic';
import { loadGoogleLanguageModel } from '@breadstone/archipel-platform-intelligence/google';

// Health indicator (optional)
import { IntelligenceHealthIndicator } from '@breadstone/archipel-platform-intelligence/health';

Error Handling

| Error Class | Code | When Thrown | | -------------------------------- | ---------------------------- | ------------------------------------------------------------------ | | IntelligenceProviderError | INTELLIGENCE_PROVIDER | Provider SDK failures during text generation | | IntelligenceValidationError | INTELLIGENCE_VALIDATION | Invalid generation parameters (temperature, topP, maxOutputTokens) | | IntelligenceConfigurationError | INTELLIGENCE_CONFIGURATION | Unsupported provider, missing API key, or missing SDK package |

Resource Limits

| Limit | Value | Description | | ------------------------- | ---------- | ----------------------------------------------------- | | Text generation timeout | 30 seconds | LLM requests aborted after 30s (configurable) | | Max retries | 2 | Failed calls retried with exponential backoff (1s–4s) | | Capability registry cap | 500 | Max registered capabilities; excess silently ignored | | Default max output tokens | 1,024 | Maximum generated tokens per request |

Lifecycle

• Startup (OnModuleInit): IntelligenceTextGenerator and IntelligenceCapabilityRegistrar validate provider configuration eagerly. Missing API keys or unsupported providers are caught before the first request.

Peer Dependencies

| Package | Required | Notes | | --------------------------------------------- | -------- | ----------------------------- | | @breadstone/archipel-platform-configuration | Yes | Typed config key support | | @nestjs/common | Yes | NestJS core | | ai | Yes | Vercel AI SDK core | | @ai-sdk/openai | No | Required for OpenAI / Grok | | @ai-sdk/anthropic | No | Required for Anthropic | | @ai-sdk/google | No | Required for Google Gemini | | @breadstone/archipel-platform-health | No | Required for health indicator | | @nestjs/terminus | No | Required for health indicator |

Documentation

📖 Package Docs: .docs/packages/platform-intelligence/index.md

Development

# Build
yarn nx build platform-intelligence

# Test
yarn nx test platform-intelligence

# Lint
yarn nx lint platform-intelligence