@bluefly/openstandardagents 0.2.9 → 0.3.0

package/dist/services/runtime/azure.adapter.d.ts

@@ -0,0 +1,389 @@
+/**
+ * Azure OpenAI Runtime Adapter
+ * Runs OSSA agents using Azure OpenAI's function calling API with streaming and tool support
+ *
+ * This adapter extends the OpenAI SDK with Azure-specific configuration:
+ * - Custom endpoint URLs (Azure OpenAI resource endpoints)
+ * - API version headers (Azure requires explicit API versioning)
+ * - Deployment names (Azure uses deployment names instead of model names)
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const manifest: OssaManifest = {
+ *   apiVersion: 'v0.3.0',
+ *   kind: 'Agent',
+ *   metadata: { name: 'my-agent' },
+ *   spec: { role: 'Assistant' },
+ *   extensions: {
+ *     azure: {
+ *       endpoint: 'https://my-resource.openai.azure.com',
+ *       deployment: 'gpt-4o-mini',
+ *       api_version: '2024-02-15-preview'
+ *     }
+ *   }
+ * };
+ *
+ * const adapter = new AzureAdapter(manifest);
+ * adapter.initialize();
+ * const response = await adapter.chat('Hello!');
+ * ```
+ */
+import OpenAI from 'openai';
+import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+/**
+ * OSSA Agent manifest structure
+ * Supports Azure-specific configuration via extensions.azure
+ */
+export interface OssaManifest {
+    apiVersion: string;
+    kind: string;
+    metadata: {
+        name: string;
+        version?: string;
+        description?: string;
+    };
+    spec: {
+        role: string;
+        llm?: {
+            provider: string;
+            model: string;
+            temperature?: number;
+            maxTokens?: number;
+        };
+        tools?: Array<{
+            type: string;
+            name?: string;
+            capabilities?: string[];
+            config?: Record<string, unknown>;
+        }>;
+    };
+    extensions?: {
+        azure?: {
+            /** Azure OpenAI endpoint URL (e.g., https://my-resource.openai.azure.com) */
+            endpoint?: string;
+            /** Azure deployment name (replaces model name in Azure) */
+            deployment?: string;
+            /** Azure API version (default: 2024-02-15-preview) */
+            api_version?: string;
+            /** System instructions (overrides spec.role if provided) */
+            instructions?: string;
+            /** Temperature setting (overrides spec.llm.temperature if provided) */
+            temperature?: number;
+            /** Max tokens (overrides spec.llm.maxTokens if provided) */
+            max_tokens?: number;
+            /** Tool mapping for Azure function calling */
+            tools_mapping?: Array<{
+                ossa_capability: string;
+                azure_tool_name?: string;
+                description?: string;
+                parameters?: Record<string, unknown>;
+            }>;
+        };
+        [key: string]: unknown;
+    };
+}
+/**
+ * Runtime options for chat execution
+ */
+export interface RunOptions {
+    /** Enable verbose logging of tool calls and responses */
+    verbose?: boolean;
+    /** Maximum conversation turns before stopping (default: 10) */
+    maxTurns?: number;
+}
+/**
+ * Tool definition with optional handler
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    handler?: (args: Record<string, unknown>) => Promise<string>;
+}
+/**
+ * Azure OpenAI Runtime Adapter
+ *
+ * This adapter bridges OSSA agent manifests to Azure OpenAI's API, handling:
+ * - Azure-specific authentication and endpoint configuration
+ * - Deployment name mapping (Azure uses deployments instead of model names)
+ * - API version headers required by Azure
+ * - Function calling and tool execution
+ * - Multi-turn conversations with tool support
+ *
+ * Configuration Priority (highest to lowest):
+ * 1. extensions.azure.* (Azure-specific settings)
+ * 2. spec.llm.* (Generic LLM settings)
+ * 3. Hard-coded defaults
+ */
+export declare class AzureAdapter {
+    private client;
+    private manifest;
+    private tools;
+    private messages;
+    private deployment;
+    /**
+     * Creates a new Azure OpenAI adapter instance
+     *
+     * @param manifest - OSSA agent manifest with Azure configuration in extensions.azure
+     * @param apiKey - Azure OpenAI API key (optional, falls back to AZURE_OPENAI_API_KEY env var)
+     *
+     * @throws {Error} If Azure endpoint or deployment name is not configured
+     *
+     * @example
+     * ```typescript
+     * const adapter = new AzureAdapter(manifest, process.env.AZURE_OPENAI_API_KEY);
+     * ```
+     */
+    constructor(manifest: OssaManifest, apiKey?: string);
+    /**
+     * Get the Azure deployment name from manifest
+     *
+     * Deployment names in Azure OpenAI are distinct from model names and must be
+     * configured in the Azure portal. They map to specific model versions.
+     *
+     * Priority:
+     * 1. extensions.azure.deployment (Azure-specific)
+     * 2. spec.llm.model (Generic LLM config, treated as deployment name)
+     * 3. Default: 'gpt-4o-mini' (must exist as deployment in Azure)
+     *
+     * @returns Azure deployment name
+     *
+     * @private
+     */
+    private getDeployment;
+    /**
+     * Get system prompt from manifest
+     *
+     * The system prompt defines the agent's role and behavior. Azure OpenAI uses
+     * the same system message format as standard OpenAI.
+     *
+     * Priority:
+     * 1. extensions.azure.instructions (Azure-specific instructions)
+     * 2. spec.role (Generic role definition)
+     *
+     * @returns System prompt text
+     *
+     * @private
+     */
+    private getSystemPrompt;
+    /**
+     * Get temperature setting for response generation
+     *
+     * Temperature controls randomness in responses (0.0 = deterministic, 2.0 = very random).
+     * Azure OpenAI supports the same temperature range as OpenAI.
+     *
+     * Priority:
+     * 1. extensions.azure.temperature
+     * 2. spec.llm.temperature
+     * 3. Default: 0.7
+     *
+     * @returns Temperature value (0.0 to 2.0)
+     *
+     * @private
+     */
+    private getTemperature;
+    /**
+     * Get max tokens setting for response generation
+     *
+     * Max tokens limits the length of generated responses. Azure OpenAI has the
+     * same token limits as OpenAI (varies by model).
+     *
+     * Priority:
+     * 1. extensions.azure.max_tokens
+     * 2. spec.llm.maxTokens
+     * 3. Default: undefined (uses model's default)
+     *
+     * @returns Max tokens value or undefined
+     *
+     * @private
+     */
+    private getMaxTokens;
+    /**
+     * Convert OSSA tools to OpenAI function calling format
+     *
+     * This method transforms OSSA tool definitions into Azure OpenAI's function calling
+     * schema. Azure uses the same function calling format as OpenAI.
+     *
+     * Tool sources (in priority order):
+     * 1. extensions.azure.tools_mapping - Azure-specific tool definitions
+     * 2. spec.tools - Generic OSSA tool definitions
+     *
+     * @returns Array of OpenAI ChatCompletionTool objects
+     *
+     * @private
+     */
+    private getAzureTools;
+    /**
+     * Register a tool handler for runtime execution
+     *
+     * Tool handlers are async functions that execute when the LLM calls a tool.
+     * They receive parsed arguments and return string results.
+     *
+     * @param name - Tool name (must match a tool defined in manifest)
+     * @param handler - Async function that executes the tool
+     *
+     * @example
+     * ```typescript
+     * adapter.registerToolHandler('get_weather', async (args) => {
+     *   const { location } = args;
+     *   const weather = await fetchWeather(location);
+     *   return JSON.stringify(weather);
+     * });
+     * ```
+     */
+    registerToolHandler(name: string, handler: (args: Record<string, unknown>) => Promise<string>): void;
+    /**
+     * Execute a tool call from the LLM
+     *
+     * This internal method handles tool execution during conversation turns.
+     * It looks up the registered handler and invokes it with the provided arguments.
+     *
+     * @param name - Tool name
+     * @param args - Parsed tool arguments from LLM
+     * @returns Tool execution result as string
+     *
+     * @private
+     */
+    private executeTool;
+    /**
+     * Initialize the conversation
+     *
+     * Sets up the conversation history with the system prompt. Must be called
+     * before the first chat() call.
+     *
+     * @example
+     * ```typescript
+     * adapter.initialize();
+     * const response = await adapter.chat('Hello!');
+     * ```
+     */
+    initialize(): void;
+    /**
+     * Send a message and get a response
+     *
+     * This is the main method for interacting with the Azure OpenAI agent. It handles:
+     * - Adding user messages to conversation history
+     * - Calling Azure OpenAI API with proper authentication and headers
+     * - Executing tool calls requested by the LLM
+     * - Multi-turn conversations with tool results
+     * - Automatic retry until final text response or max turns reached
+     *
+     * The method automatically handles the tool execution loop:
+     * 1. Send messages to Azure OpenAI
+     * 2. If LLM requests tool calls, execute them
+     * 3. Send tool results back to LLM
+     * 4. Repeat until LLM provides final text response
+     *
+     * @param userMessage - The user's message text
+     * @param options - Optional runtime configuration
+     * @returns Final text response from the LLM
+     *
+     * @throws {Error} If Azure API call fails
+     *
+     * @example Basic usage
+     * ```typescript
+     * const response = await adapter.chat('What is the weather in Paris?');
+     * console.log(response);
+     * ```
+     *
+     * @example With verbose logging
+     * ```typescript
+     * const response = await adapter.chat('Calculate 2+2', { verbose: true });
+     * // Logs: [Calling 1 tool(s)...]
+     * // Logs:   → calculate({"expression":"2+2"})
+     * // Logs:   ← 4
+     * ```
+     */
+    chat(userMessage: string, options?: RunOptions): Promise<string>;
+    /**
+     * Get agent information
+     *
+     * Returns metadata about the configured agent including deployment name,
+     * available tools, and provider identifier.
+     *
+     * @returns Object containing agent name, deployment, tools array, and provider
+     *
+     * @example
+     * ```typescript
+     * const info = adapter.getAgentInfo();
+     * console.log(`Agent: ${info.name}`);
+     * console.log(`Deployment: ${info.deployment}`);
+     * console.log(`Tools: ${info.tools.join(', ')}`);
+     * console.log(`Provider: ${info.provider}`); // 'azure'
+     * ```
+     */
+    getAgentInfo(): {
+        name: string;
+        deployment: string;
+        tools: string[];
+        provider: string;
+    };
+    /**
+     * Get conversation history
+     *
+     * Returns the full conversation history including system messages, user messages,
+     * assistant responses, and tool calls/results. Useful for debugging or saving
+     * conversation state.
+     *
+     * @returns Array of conversation messages
+     *
+     * @example
+     * ```typescript
+     * const history = adapter.getConversationHistory();
+     * console.log(`Messages: ${history.length}`);
+     * ```
+     */
+    getConversationHistory(): ChatCompletionMessageParam[];
+    /**
+     * Clear conversation history
+     *
+     * Resets the conversation to initial state (only system message remains).
+     * Call this to start a fresh conversation without recreating the adapter.
+     *
+     * @example
+     * ```typescript
+     * adapter.clearHistory();
+     * adapter.initialize(); // Re-add system prompt
+     * ```
+     */
+    clearHistory(): void;
+    /**
+     * Get available tools
+     *
+     * Returns all registered tool definitions including their schemas and handlers.
+     *
+     * @returns Array of tool definitions
+     *
+     * @example
+     * ```typescript
+     * const tools = adapter.getTools();
+     * for (const tool of tools) {
+     *   console.log(`${tool.name}: ${tool.description}`);
+     * }
+     * ```
+     */
+    getTools(): ToolDefinition[];
+    /**
+     * Get the OpenAI client instance
+     *
+     * Provides direct access to the underlying OpenAI SDK client configured for Azure.
+     * Use this for advanced scenarios not covered by the adapter API.
+     *
+     * @returns Configured OpenAI client instance
+     *
+     * @example Advanced usage with streaming
+     * ```typescript
+     * const client = adapter.getClient();
+     * const stream = await client.chat.completions.create({
+     *   model: adapter.getAgentInfo().deployment,
+     *   messages: adapter.getConversationHistory(),
+     *   stream: true,
+     * });
+     * for await (const chunk of stream) {
+     *   process.stdout.write(chunk.choices[0]?.delta?.content || '');
+     * }
+     * ```
+     */
+    getClient(): OpenAI;
+}
+//# sourceMappingURL=azure.adapter.d.ts.map

package/dist/services/runtime/azure.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"azure.adapter.d.ts","sourceRoot":"","sources":["../../../src/services/runtime/azure.adapter.ts"],"names":[],"mappings":"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"}