@arcgis/ai-orchestrator 5.0.0-next.133

package/dist/intent_prompt-BjOozjFv.js

@@ -0,0 +1,20 @@
+const e = `## GIS Feature Layer Intent Classifier
+
+You are an assistant that classifies user intent in ArcGIS Online Map Viewer.
+
+Return **up to {maxIntents} intents in the exact order they should be executed** for the user's request.
+If none apply, return an **empty list** (no "none" label).
+
+Choose only from registered agents. Input format will be: {{id: string, name: string, description: string}}[]
+{registeredAgents}
+
+Rules:
+
+- Output 0–{maxIntents} items, ordered for execution.
+- Do **not** include any labels outside the list above.
+- Do **not** include "none"; return an empty list instead when unrelated questions like labels, popups, etc.
+- If none apply, return an empty array [].
+`;
+export {
+  e as default
+};

package/dist/layer_descriptions_prompt-NAaKWdJi.js

@@ -0,0 +1,58 @@
+const e = `This Feature Layer is part of a Feature Service. The Feature Layer contains various fields, each with its own name, type, and description.
+The Feature Layer is a collection of geographic features that represent real-world entities. Each feature in the layer has attributes that provide additional information about the feature. The layer may include point, line, or polygon geometries, depending on the type of data it represents.
+The geometry type for this layer is {layerGeometryType}.
+
+Here is the field information for each field in the Feature Layer. Each field has a name, alias, type, valueType and description. These should help you understand the data represented in the Feature Layer.
+
+Field Descriptions:
+{fieldInformation}
+
+Your task is to :
+
+- analyze the field descriptions to understand the data represented in the Feature Layer.
+- Generate the following for the layer:
+  - a title: a concise title that accurately reflects the content and purpose of the feature service.
+  - a description: a detailed description of the feature layer
+
+Consider the following aspects in your description:
+
+- purpose of this feature layer
+- types of data and geometric entities represented in the layer
+- sources of the layer information and the geographic area covered
+- potential applications and usefulness of the feature layer in the GIS world
+
+If any of the above topics are not applicable, you can skip them. Don't include statements that indicate something this Feature Layer is not or does not have. Avoid listing field names, types, and other technical details.
+
+Instructions while generating the title:
+
+- Avoid using special characters in the title.
+- Avoid using 'layer' in the title.
+- Avoid using all uppercase letters in the title. Use title case instead.
+- The title should not be too long.
+
+You are given Feature Layer descriptions and title.
+
+## Existing layer details filled in by a human:
+
+{existingLayerTitle}
+{existingLayerSnippet}
+{existingLayerDescription}
+
+## Instructions on how to use the information filled in by a human:
+
+Remember humans may have more information about the item than just the field and layer descriptions.
+
+- Use this information ONLY IF it helps you understand the item better.
+- Use this information ONLY IF it helps you generate a better description and title.
+- Use your knowledge from this information to compensate for any important information that is missing in the field and layer descriptions.
+
+## Instructions on what to avoid doing with the information filled in by a human:
+
+- you must not use this information in your response as it is.
+- you must not think of this information as the final version.
+- you must not use this information to generate a response without analyzing it.
+- you must not copy this information verbatim in your response.
+`;
+export {
+  e as default
+};

package/dist/llm/generateFieldDescriptions.d.ts

@@ -0,0 +1,8 @@
+import { default as FeatureLayer } from '@arcgis/core/layers/FeatureLayer';
+import { FieldsRegistry } from '../types/types';
+/**
+ * Enriches a FeatureLayer's fields (missing alias/description/valueType) using an LLM and
+ * returns a complete `FieldsRegistry`. Skips the model call if nothing needs enrichment.
+ * Throws if the LLM response fails schema validation.
+ */
+export declare const generateFieldDescriptions: (featureLayer: FeatureLayer) => Promise<FieldsRegistry>;

package/dist/llm/generateLayerAndFieldDescription.d.ts

@@ -0,0 +1,7 @@
+import { LayersAndFieldsRegistry } from '../types/types';
+/**
+ * Builds a combined registry of layer and field metadata for all FeatureLayers in a map.
+ * For each FeatureLayer: generates field descriptions, then layer descriptions, and stores
+ * the results keyed by layer id. Non-FeatureLayer entries are ignored.
+ */
+export declare const layerAndFieldDescriptions: (arcgisMap: __esri.Map) => Promise<LayersAndFieldsRegistry>;

package/dist/llm/generateLayerDescriptions.d.ts

@@ -0,0 +1,22 @@
+import { default as z } from 'zod';
+import { FieldsRegistry } from '../types/types';
+import { default as FeatureLayer } from '@arcgis/core/layers/FeatureLayer';
+declare const layerDescriptionSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    description: string;
+    name: string | null;
+}, {
+    title: string;
+    description: string;
+    name: string | null;
+}>;
+export type LayerDescriptionWrapper = z.infer<typeof layerDescriptionSchema>;
+/**
+ * Enriches a layer's title/description via LLM using existing metadata + field descriptions.
+ */
+export declare const generateLayerDescriptions: (layer: FeatureLayer, fieldRegistry: FieldsRegistry) => Promise<LayerDescriptionWrapper>;
+export {};

package/dist/models/modelConfig.d.ts

@@ -0,0 +1,28 @@
+import { ChatModelTier, EmbeddingModelTier } from './types';
+export declare const ModelConfig: {
+    readonly "gpt-4.1": {
+        readonly deploymentName: "gpt-4.1";
+        readonly apiVersion: "2024-10-21";
+        readonly pathSegment: "models/gpt-4.1/openai/deployments/gpt-4.1/chat/completions";
+    };
+    readonly "gpt-4.1-mini": {
+        readonly deploymentName: "gpt-4.1-mini";
+        readonly apiVersion: "2024-10-21";
+        readonly pathSegment: "models/gpt-4.1-mini/openai/deployments/gpt-4.1-mini/chat/completions";
+    };
+    readonly "text-embedding-ada-002": {
+        readonly deploymentName: "text-embedding-ada-002";
+        readonly apiVersion: "2024-10-21";
+        readonly pathSegment: "models/text-embedding-ada-002/openai/deployments/text-embedding-ada-002/embeddings";
+    };
+};
+export type AiModelKey = keyof typeof ModelConfig;
+/**
+ * Public tiers → internal model keys
+ */
+export declare const ChatModelTierMap: Record<ChatModelTier, AiModelKey>;
+export declare const EmbeddingModelTierMap: Record<EmbeddingModelTier, AiModelKey>;
+/**
+ * Build the full AI Utility Service URL for a model.
+ */
+export declare const getModelUrl: (baseUrl: string, modelKey: AiModelKey) => string;

package/dist/models/types.d.ts

@@ -0,0 +1,2 @@
+export type ChatModelTier = "default" | "fast";
+export type EmbeddingModelTier = "default";

package/dist/orchestrator/orchestrator.d.ts

@@ -0,0 +1,70 @@
+import { OrchestratorEvent } from './orchestratorEvents';
+import { AgentWithContext } from '../registry/agentRegistry';
+import { default as Portal } from '@arcgis/core/portal/Portal.js';
+/** Orchestrator initialization dependencies. */
+type Deps = {
+    portal: Portal;
+    /** Optional map view enabling map-dependent services. */
+    view?: __esri.View;
+    /** Optional agents to register at init. */
+    agents?: AgentWithContext[];
+};
+/**
+ * Orchestrator
+ *
+ * Coordinates chat-in / events-out workflows on top of LangGraph.
+ * - Accepts user input via `ask()`
+ * - Streams structured events (`trace`, `interrupt`, `completed`, `cancelled`)
+ * - Manages HITL (human-in-the-loop) flows and cancellation
+ *
+ * Intended as the main entrypoint for the UX layer.
+ */
+export declare class Orchestrator {
+    private deps;
+    private orchestratorReady;
+    private embeddingsWorker?;
+    private graph?;
+    private chatHistory;
+    private threadId;
+    private agentRegistry;
+    private layersAndFieldsRegistry?;
+    private interruptHandler?;
+    private currentInterrupt?;
+    private streamEpoch;
+    private constructor();
+    /**
+     * Creates and returns an AI-ready Orchestrator instance.
+     * @param deps Core dependencies (layer/field registry plus optional map views).
+     * @returns Ready Orchestrator.
+     */
+    static init(deps: Deps): Promise<Orchestrator>;
+    /**
+     * Run a new chat turn through the graph.
+     * Yields structured events for the UI to consume:
+     *  - `trace`: intermediate model output
+     *  - `interrupt`: HITL required, wait for `resumeInterrupt()`
+     *  - `completed`: final result with chat history + layer styling
+     *  - `cancelled`: user aborted the run
+     */
+    ask(userInput: string): AsyncGenerator<OrchestratorEvent>;
+    /**
+     * Start a new conversation by clearing chat history.
+     */
+    newConversation(): void;
+    /**
+     * Generic resume for any HITL interrupt.
+     * The payload is whatever the UI collected (e.g. "yes", "no", layerId, etc).
+     */
+    resumeInterrupt(payload: unknown): void;
+    /**
+     * Optional: allow UI to cancel the current HITL.
+     */
+    cancelInterrupt(): void;
+    private pipeStream;
+    /**
+     * Disposes this instance by terminating the embeddings worker
+     * and cleaning up all related resources.
+     */
+    dispose(): void;
+}
+export {};

package/dist/orchestrator/orchestratorEvents.d.ts

@@ -0,0 +1,60 @@
+import { UiInterrupt } from '../hitl/types';
+/**
+ * Events emitted by the Orchestrator during a chat run.
+ *
+ * - `"trace"`: intermediate model output to display.
+ * - `"interrupt"`: human-in-the-loop input required; UI should call `resumeInterrupt()`.
+ * - `"completed"`: run finished successfully; includes final chat history and optional smart-mapping result.
+ * - `"cancelled"`: run aborted by the user.
+ * - `"ux-suggestion"`: optional suggestion for the UX to display (e.g., show legend).
+ * - `"error"`: an error occurred during orchestration.
+ * Consumers should handle all cases when iterating the async generator from `ask()`.
+ */
+export type OrchestratorEvent = (OrchestratorEventBase & {
+    type: "cancelled";
+    reason?: CancelReason;
+}) | (OrchestratorEventBase & {
+    type: "completed";
+    result: CompletedEventResult;
+}) | (OrchestratorEventBase & {
+    type: "error";
+    error: OrchestratorError;
+}) | (OrchestratorEventBase & {
+    type: "interrupt";
+    interrupt: UiInterrupt;
+}) | (OrchestratorEventBase & {
+    type: "trace";
+    data: TraceEventData;
+}) | (OrchestratorEventBase & {
+    type: "ux-suggestion";
+    suggestion: UXSuggestion;
+});
+/** Base properties for all orchestrator events */
+type OrchestratorEventBase = {
+    runId: string;
+    timestamp: number;
+};
+export interface CompletedEventResult {
+    content: string;
+}
+/** Data for a trace event emitted during graph execution */
+export interface TraceEventData {
+    text: string;
+    agentName?: string;
+    toolName?: string;
+}
+/** Optional suggestion event the UX can choose to display or ignore */
+export type UXSuggestion = {
+    id: string;
+    description?: string;
+    payload?: Record<string, unknown>;
+};
+/** Cancel reasons for orchestrator events:
+ * - "user": the user explicitly cancelled the run.
+ */
+export type CancelReason = "user";
+/** Error information for orchestrator events */
+export type OrchestratorError = {
+    message: string;
+};
+export {};

package/dist/prompts/getPrompt.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Loads a markdown prompt file dynamically.
+ * Note: Vite only supports variable imports one level deep — e.g. "foo" works, "foo/bar" fails.
+ * https://vite.dev/guide/features.html#dynamic-import
+ */
+export declare const getPromptText: (promptName: string) => Promise<string>;

package/dist/providers/arcgis/aiUtilityService.d.ts

@@ -0,0 +1,3 @@
+import { ChatModelTier, EmbeddingModelTier } from '../../models/types';
+export declare function getChatAIUtilityServiceUrl(tier?: ChatModelTier): string;
+export declare function getEmbeddingAIUtilityServiceUrl(tier?: EmbeddingModelTier): string;

package/dist/providers/azure/azureChat.d.ts

@@ -0,0 +1,6 @@
+import { AzureChatOpenAI } from '@langchain/openai';
+import { ChatModelTier } from '../../models/types';
+/**
+ * Creates an instance of AzureChatOpenAI.
+ */
+export declare const createAzureChatModel: (tier?: ChatModelTier, temperature?: number) => Promise<AzureChatOpenAI>;

package/dist/providers/azure/promptChain.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { ChatHistory } from '../../types/types';
+import { StructuredToolInterface } from '@langchain/core/tools';
+import { AIMessage } from '@langchain/core/messages';
+import { ChatModelTier } from '../../models/types';
+type BaseOptions = {
+    promptText: string;
+    modelTier?: ChatModelTier;
+    temperature?: number;
+    messages?: ChatHistory;
+    inputVariables?: Record<string, unknown>;
+};
+/**
+ * Invokes a prompt and returns a plain text response.
+ * Use this when you just need free-form text from the model.
+ */
+export declare const invokeTextPrompt: (opts: BaseOptions) => Promise<string>;
+/**
+ * Invokes a prompt and returns structured data validated against a schema.
+ * Use this when you need a predictable, typed result.
+ */
+export declare const invokeStructuredPrompt: <T>(opts: BaseOptions & {
+    schema: z.ZodType<T>;
+}) => Promise<T>;
+/**
+ * Invokes a prompt with tools enabled and returns the model’s tool call response.
+ * Use this when the model needs to decide whether to call a tool.
+ */
+export declare const invokeToolPrompt: (opts: BaseOptions & {
+    tools: StructuredToolInterface[];
+}) => Promise<AIMessage>;
+export {};

package/dist/providers/azure/sanitizedFetch.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Creates a sanitized fetch function that removes unnecessary headers
+ * and adds the Esri authorization token.
+ */
+export declare const createSanitizedFetch: (token?: string) => typeof fetch;

package/dist/registry/agentRegistry.d.ts

@@ -0,0 +1,26 @@
+import { AnnotationRoot, StateGraph } from '@langchain/langgraph/web';
+/**
+ * Describes a single agent that can be registered with the orchestrator.
+ */
+export interface AgentRegistration {
+    id: string;
+    name: string;
+    description: string;
+    createGraph: () => StateGraph<unknown>;
+    workspace: AnnotationRoot<any>;
+}
+export type GetContext<TContext extends Record<string, unknown>> = () => Promise<TContext> | TContext;
+export interface AgentWithContext<TContext extends Record<string, unknown> = Record<string, unknown>> {
+    agent: AgentRegistration;
+    /**
+     * Lazily resolves runtime context.
+     * Can be sync or async, and may perform lifecycle checks (e.g. await view.when()).
+     */
+    getContext?: GetContext<TContext>;
+}
+export declare class AgentRegistry {
+    private agentRegistry;
+    register<TContext extends Record<string, unknown>>(entry: AgentWithContext<TContext>): void;
+    get(id: string): AgentWithContext | undefined;
+    list(): AgentWithContext[];
+}

package/dist/services/fieldSearch.d.ts

@@ -0,0 +1,20 @@
+import { VectorSearchFieldResults } from '../types/types';
+/**
+ * Service for semantic field matching within one or more layers.
+ * Hides the embeddings worker from callers.
+ */
+export interface FieldSearchService {
+    searchFields: (input: {
+        text: string;
+        layerIds: string[];
+        minScore: number;
+        topResults: number;
+    }) => Promise<VectorSearchFieldResults>;
+}
+/**
+ * Factory that binds a Worker to the FieldSearchService.
+ * The worker is captured privately and never exposed.
+ */
+export declare function createFieldSearchService(deps: {
+    worker: Worker;
+}): FieldSearchService;

package/dist/services/layerSearch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Service for semantic layer matching.
+ * Hides the embeddings worker from callers.
+ */
+export interface LayerSearchService {
+    searchLayers: (input: {
+        text: string;
+        minScore: number;
+    }) => Promise<{
+        id: string;
+        score: number;
+    }[]>;
+}
+/**
+ * Factory that binds a Worker to the LayerSearchService.
+ * The worker is captured privately and never exposed.
+ */
+export declare function createLayerSearchService(deps: {
+    worker: Worker;
+}): LayerSearchService;

package/dist/signals/index.d.ts

@@ -0,0 +1,24 @@
+import { RunnableConfig } from '@langchain/core/runnables';
+import { TraceEventData, UXSuggestion } from '../orchestrator/orchestratorEvents';
+/**
+ * Dispatch a graph trace message to the browser event bridge.
+ *
+ * Emits a CustomEvent named "trace_message" that UI/tooling can observe
+ * (e.g., devtools panels or Storybook add‑ons) to surface node-enter messages.
+ *
+ * @param data - Trace event data.
+ * @param config - Runnable LangChain config forwarded to the dispatcher.
+ * @returns A promise that resolves once the event has been dispatched.
+ */
+export declare const sendTraceMessage: (data: TraceEventData, config?: RunnableConfig) => Promise<void>;
+/**
+ * Send a UX suggestion produced by the graph to the host UI.
+ *
+ * Useful for surfacing non-blocking, contextual hints (e.g., recommended
+ * actions or next steps) during an agent run.
+ *
+ * @param suggestion - The UX suggestion payload.
+ * @param config - Runnable LangChain config to pass through to the dispatcher.
+ * @returns A promise that resolves once the suggestion has been dispatched.
+ */
+export declare const sendUXSuggestion: (suggestion: UXSuggestion, config?: RunnableConfig) => Promise<void>;

package/dist/types/types.d.ts

@@ -0,0 +1,55 @@
+import { BaseMessage } from '@langchain/core/messages';
+import { LayerDescriptionWrapper } from '../llm/generateLayerDescriptions';
+import { AgentRegistry } from '../registry/agentRegistry';
+import { HITLResponse } from '../hitl/types';
+import { FieldSearchService } from '../services/fieldSearch';
+import { LayerSearchService } from '../services/layerSearch';
+export type FieldStatistics = {
+    summaryStatistics: __esri.SummaryStatisticsResult | null;
+    uniqueValues: __esri.UniqueValuesResultUniqueValueInfos[] | null;
+};
+export type FieldInfo = {
+    name: string;
+    alias: string;
+    type: string;
+    description: string;
+    valueType: string;
+    statistics?: FieldStatistics;
+};
+export type FieldsRegistry = Map<string, FieldInfo>;
+/** Registry mapping layer IDs to their description and associated field registry. */
+export type LayersAndFieldsRegistry = Map<string, {
+    layerItem: LayerDescriptionWrapper;
+    fieldRegistry: FieldsRegistry;
+}>;
+export type FieldVectors = {
+    layerId: string;
+    results: {
+        name: string;
+        score: number;
+    }[];
+};
+export type VectorSearchFieldResults = FieldVectors[];
+/** Sequence of AI and human messages that make up the chat history. */
+export type ChatHistory = BaseMessage[];
+export type Services = Readonly<{
+    /** Registry used to discover and invoke available agents. */
+    agentRegistry: AgentRegistry;
+    /** ArcGIS Portal instance for auth, user context, and content access. */
+    portal: __esri.Portal;
+    /** Finds candidate layers using semantic (vector) search. */
+    layerSearch?: LayerSearchService;
+    /** Finds relevant fields for given layers using semantic (vector) search. */
+    fieldSearch?: FieldSearchService;
+    /** Registry of available layers and their fields for query / search (optional). */
+    layersAndFieldsRegistry?: LayersAndFieldsRegistry;
+}>;
+export type CustomConfigurableType = Record<string, unknown> & {
+    thread_id: string;
+    /** Optional HITL response injected by the host application. */
+    hitlResponse: HITLResponse | null;
+    /** Runtime services provided to agents and nodes. */
+    services: Services;
+    agentId?: string;
+    context?: unknown;
+};

package/dist/utils/cleanHistory.d.ts

@@ -0,0 +1,2 @@
+import { BaseMessage } from '@langchain/core/messages';
+export declare const cleanOrphanedToolMessages: (messages: BaseMessage[]) => BaseMessage[];

package/dist/utils/contextSelectors.d.ts

@@ -0,0 +1,10 @@
+import { BaseMessage } from '@langchain/core/messages';
+/**
+ * Return the last N HumanMessage instances.
+ */
+export declare const getUserContext: (messages: BaseMessage[], userCount?: number) => BaseMessage[];
+/**
+ * Returns the concatenated content of all AI messages
+ * that occur after the last HumanMessage.
+ */
+export declare const finalAgentResponse: (messages: BaseMessage[]) => string;

package/dist/workers/embeddings.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/workers/embeddingsWorkerSetup.d.ts

@@ -0,0 +1,6 @@
+import { LayersAndFieldsRegistry } from '../types/types';
+/**
+ * Initializes the embeddings worker and waits for its initial embedding generation
+ * to complete. Returns the ready Worker instance.
+ */
+export declare const initEmbeddingsWorker: (layersAndFieldsRegistry: LayersAndFieldsRegistry) => Promise<Worker>;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@arcgis/ai-orchestrator",
+  "version": "5.0.0-next.133",
+  "description": "ArcGIS AI Orchestrator Package",
+  "homepage": "https://developers.arcgis.com/javascript/latest/",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/"
+  ],
+  "dependencies": {
+    "@langchain/core": "^0.3.80",
+    "@langchain/langgraph": "^0.4.9",
+    "langchain": "^0.3.37",
+    "tslib": "^2.8.1",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "@arcgis/core": ">=5.0.0-next.62 <5.1"
+  }
+}