sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Dialogflow/ AgentsIntent.ts

import * as dialogflow from "@distilled.cloud/gcp/dialogflow_v3";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { GcpEnvironment } from "../Environment.ts";
import {
  createInternalLabels,
  diffLabels,
  hasAlchemyLabels,
  stripInternalLabels,
  toLabels,
} from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import {
  collectionParent,
  DEFAULT_LOCATION,
  encodeOwnership,
  encodeOwnershipLine,
  expandAgent,
  fingerprint,
  hasOwnershipMarker,
  lastSegment,
  locationOf,
  namedAgents,
  normalizeLocation,
  ownedByAlchemy,
  parentOf,
  parseOwnership,
  projectOf,
  sameText,
  toResourceId,
  updateMaskOf,
  retryQuota,
} from "./internal.ts";

export type IntentTrainingPhrasePart = {
  /** Parameter id this part annotates. */
  parameterId?: string;
  /** Text of this part. */
  text?: string;
};

export type IntentTrainingPhrase = {
  /** Ordered parts that concatenate to the phrase. */
  parts?: IntentTrainingPhrasePart[];
  /** Training phrase id. Output only when omitted. */
  id?: string;
  /** How many times this phrase is repeated during training. */
  repeatCount?: number;
};

export type IntentParameter = {
  /** Unique parameter id. */
  id?: string;
  /** Entity type (`projects/-/locations/-/agents/-/entityTypes/sys.date`). */
  entityType?: string;
  /** Redact the parameter in logs. */
  redact?: boolean;
  /** Whether the parameter is a list. */
  isList?: boolean;
};

export type AgentsIntentProps = {
  /**
   * Parent agent resource name
   * `projects/{project}/locations/{location}/agents/{agent}`.
   * Immutable — changing it replaces the intent.
   */
  agent: string;
  /**
   * Intent id (the `{intent}` segment). Server-assigned when omitted.
   * Immutable — changing it replaces the intent.
   */
  intentId?: string;
  /**
   * Location used when `agent` is an id rather than a resource name.
   * Immutable — changing it replaces the intent.
   * @default "global"
   */
  location?: string;
  /**
   * Human-readable name unique within the agent. Alchemy stamps
   * ownership into this field and strips it from attributes.
   */
  displayName?: string;
  /**
   * User labels. Alchemy ownership labels are merged in automatically.
   */
  labels?: Record<string, string>;
  /** Training phrases. */
  trainingPhrases?: IntentTrainingPhrase[];
  /** Intent parameters. */
  parameters?: IntentParameter[];
  /**
   * Matching priority. Higher values match first. `0` or negative
   * disables the intent.
   */
  priority?: number;
  /**
   * Whether this is the fallback intent.
   * @default false
   */
  isFallback?: boolean;
  /**
   * Human-readable description. Alchemy also stamps ownership here so
   * `list` / nuke can find the intent if labels are stripped.
   */
  description?: string;
  /** DTMF pattern associated with this intent. */
  dtmfPattern?: string;
  /** Language code for training phrases. */
  languageCode?: string;
};

export type AgentsIntent = Resource<
  "GCP.Dialogflow.AgentsIntent",
  AgentsIntentProps,
  {
    /** Full resource name `.../agents/{agent}/intents/{intent}`. */
    name: string;
    /** Intent id (last path segment). */
    intentId: string;
    /** Parent agent resource name. */
    agent: string;
    /** Location id. */
    location: string;
    /** Project id. */
    project: string;
    /** User display name with the Alchemy ownership prefix stripped. */
    displayName: string | undefined;
    /** User labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
    /** Training phrases. */
    trainingPhrases: IntentTrainingPhrase[] | undefined;
    /** Intent parameters. */
    parameters: IntentParameter[] | undefined;
    /** Matching priority. */
    priority: number | undefined;
    /** Whether this is the fallback intent. */
    isFallback: boolean;
    /** User description with the Alchemy ownership prefix stripped. */
    description: string | undefined;
    /** DTMF pattern. */
    dtmfPattern: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Dialogflow CX intent (training phrases plus parameters).
 *
 * Alchemy ownership is stored in labels, `displayName`, and
 * `description` so `list` / nuke can find the intent. Parent agent and
 * id are immutable. Display name, labels, training phrases, parameters,
 * priority, fallback flag, description, and DTMF pattern update in
 * place.
 *
 * ### Creating an Intent
 * **Example:** Greeting intent
 * ```typescript
 * const intent = yield* GCP.Dialogflow.AgentsIntent("Hello", {
 *   agent: agentName,
 *   displayName: "hello",
 *   trainingPhrases: [
 *     { parts: [{ text: "hello" }], repeatCount: 1 },
 *     { parts: [{ text: "hi there" }], repeatCount: 1 },
 *   ],
 *   labels: { env: "test" },
 * });
 * ```
 *
 * ### Updating an Intent
 * Change props on the same logical id; the engine keeps the physical id.
 *
 * **Example:** Add a training phrase
 * ```typescript
 * const intent = yield* GCP.Dialogflow.AgentsIntent("Hello", {
 *   agent: agentName,
 *   displayName: "hello",
 *   trainingPhrases: [
 *     { parts: [{ text: "hello" }], repeatCount: 1 },
 *     { parts: [{ text: "good morning" }], repeatCount: 1 },
 *   ],
 *   labels: { env: "prod" },
 * });
 * ```
 *
 * @resource
 * @category Dialogflow
 */
export const AgentsIntent = Resource<AgentsIntent>("GCP.Dialogflow.AgentsIntent");

export class AgentsIntentNotResolved extends Data.TaggedError(
  "GCP.Dialogflow.AgentsIntentNotResolved",
)<{
  resourceName: string;
}> {}

const resourceName = (agent: string, intentId: string) => `${agent}/intents/${intentId}`;

const userLabels = (
  labels: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalLabels(tagRecord(labels));

const phrasesOf = (
  phrases: dialogflow.GoogleCloudDialogflowCxV3IntentTrainingPhraseList | undefined,
): IntentTrainingPhrase[] | undefined => {
  if (phrases === undefined) return undefined;
  return phrases.map((phrase) => ({
    parts: phrase.parts?.map((part) => ({
      parameterId: part.parameterId,
      text: part.text,
    })),
    repeatCount: phrase.repeatCount,
  }));
};

const parametersOf = (
  parameters: dialogflow.GoogleCloudDialogflowCxV3IntentParameterList | undefined,
): IntentParameter[] | undefined => {
  if (parameters === undefined) return undefined;
  return parameters.map((parameter) => ({
    id: parameter.id,
    entityType: parameter.entityType,
    redact: parameter.redact,
    isList: parameter.isList,
  }));
};

const toAttrs = (
  intent: dialogflow.GoogleCloudDialogflowCxV3Intent,
  project: string,
  agentHint?: string,
) => {
  const name = intent.name ?? "";
  return {
    name,
    intentId: lastSegment(name),
    agent: name.includes("/intents/")
      ? collectionParent(name, "agents")
      : (agentHint ?? parentOf(name)),
    location: locationOf(name),
    project: projectOf(name) || project,
    displayName: parseOwnership(intent.displayName).text,
    labels: userLabels(intent.labels),
    trainingPhrases: phrasesOf(intent.trainingPhrases),
    parameters: parametersOf(intent.parameters),
    priority: intent.priority,
    isFallback: intent.isFallback === true,
    description: parseOwnership(intent.description).text,
    dtmfPattern: intent.dtmfPattern,
  };
};

const getByName = (name: string) =>
  name.length === 0
    ? Effect.undefined
    : dialogflow
        .getProjectsLocationsAgentsIntents({ name })
        .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const isOwnedIntent = (intent: dialogflow.GoogleCloudDialogflowCxV3Intent) =>
  hasOwnershipMarker(intent.displayName) ||
  hasOwnershipMarker(intent.description) ||
  Object.keys(intent.labels ?? {}).some((key) => key.startsWith("alchemy-"));

const listAt = (parent: string, project: string) =>
  dialogflow.listProjectsLocationsAgentsIntents
    .pages({ parent, pageSize: 100, intentView: "INTENT_VIEW_FULL" })
    .pipe(
      Stream.flatMap((page) => Stream.fromIterable(page.intents ?? [])),
      Stream.filter(isOwnedIntent),
      Stream.map((intent) => toAttrs(intent, project, parent)),
      Stream.runCollect,
      Effect.map((chunk) => Array.from(chunk)),
      Effect.catchTag("NotFound", () => Effect.succeed([])),
    );

const findByDisplayName = (parent: string, displayName: string) =>
  dialogflow.listProjectsLocationsAgentsIntents
    .pages({ parent, pageSize: 100, intentView: "INTENT_VIEW_PARTIAL" })
    .pipe(
      Stream.flatMap((page) => Stream.fromIterable(page.intents ?? [])),
      Stream.filter((intent) => intent.displayName === displayName),
      Stream.runHead,
      Effect.map((option) => (option._tag === "Some" ? option.value : undefined)),
      Effect.catchTag("NotFound", () => Effect.undefined),
    );

export const AgentsIntentProvider = () =>
  Provider.succeed(AgentsIntent, {
    stables: ["name", "intentId", "agent", "location", "project"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousAgent = olds?.agent ?? output?.agent;
      if (previousAgent !== undefined && news.agent !== previousAgent) {
        return { action: "replace" as const, deleteFirst: false };
      }
      const previousId = olds?.intentId ?? output?.intentId;
      if (previousId !== undefined && news.intentId !== undefined && news.intentId !== previousId) {
        return { action: "replace" as const, deleteFirst: false };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const location = normalizeLocation(olds?.location ?? output?.location);
      const agent = olds?.agent ? expandAgent(olds.agent, env.project, location) : output?.agent;
      const intentId = yield* toResourceId(id, olds?.intentId, output?.intentId);
      const name = output?.name ?? (agent !== undefined ? resourceName(agent, intentId) : "");
      let existing = yield* getByName(name);
      if (existing === undefined && agent !== undefined) {
        const ownership = yield* createInternalLabels(id);
        existing = yield* findByDisplayName(
          agent,
          encodeOwnershipLine(ownership, olds?.displayName),
        );
      }
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project, agent);
      const labeled = yield* hasAlchemyLabels(id, tagRecord(existing.labels));
      const named = yield* ownedByAlchemy(id, existing.displayName);
      const described = yield* ownedByAlchemy(id, existing.description);
      return labeled || named || described ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const agents = yield* namedAgents(env.project);
        const pages = yield* Effect.forEach(agents, (agent) => listAt(agent.name, env.project), {
          concurrency: 4,
        });
        return pages.flat();
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const location = normalizeLocation(news.location ?? output?.location ?? DEFAULT_LOCATION);
      const agent = expandAgent(news.agent, env.project, location);
      const intentId = yield* toResourceId(id, news.intentId, output?.intentId);
      const name = output?.name ?? resourceName(agent, intentId);
      const ownership = yield* createInternalLabels(id);
      const displayName = encodeOwnershipLine(ownership, news.displayName);
      const description = encodeOwnership(ownership, news.description);
      const desiredLabels = {
        ...toLabels(news.labels),
        ...ownership,
      };
      const isFallback = news.isFallback === true;
      const body: dialogflow.GoogleCloudDialogflowCxV3Intent = {
        displayName,
        labels: desiredLabels,
        trainingPhrases: news.trainingPhrases,
        parameters: news.parameters,
        priority: news.priority,
        isFallback,
        description,
        dtmfPattern: news.dtmfPattern,
      };

      let current = yield* getByName(output?.name ?? name);
      if (current === undefined) {
        current = yield* findByDisplayName(agent, displayName);
      }

      if (current === undefined) {
        const created = yield* dialogflow
          .createProjectsLocationsAgentsIntents({
            parent: agent,
            languageCode: news.languageCode,
            body,
          })
          .pipe(Effect.catchTag("Conflict", () => findByDisplayName(agent, displayName)));
        current = created ?? undefined;
      }

      if (current === undefined) {
        return yield* new AgentsIntentNotResolved({ resourceName: name });
      }

      const currentName = current.name ?? name;
      const displayChanged = (current.displayName ?? "") !== displayName;
      const observedLabels = tagRecord(current.labels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      const labelsChanged = upsert.length > 0 || removed.length > 0;
      const phrasesChanged =
        fingerprint(phrasesOf(current.trainingPhrases)) !== fingerprint(news.trainingPhrases);
      const parametersChanged =
        fingerprint(parametersOf(current.parameters)) !== fingerprint(news.parameters);
      const priorityChanged = (current.priority ?? 0) !== (news.priority ?? 0);
      const fallbackChanged = (current.isFallback === true) !== isFallback;
      const descriptionChanged = (current.description ?? "") !== description;
      const dtmfChanged = !sameText(current.dtmfPattern, news.dtmfPattern);

      if (
        displayChanged ||
        labelsChanged ||
        phrasesChanged ||
        parametersChanged ||
        priorityChanged ||
        fallbackChanged ||
        descriptionChanged ||
        dtmfChanged
      ) {
        current = yield* dialogflow.patchProjectsLocationsAgentsIntents({
          name: currentName,
          languageCode: news.languageCode,
          updateMask: updateMaskOf(
            displayChanged ? "display_name" : undefined,
            labelsChanged ? "labels" : undefined,
            phrasesChanged ? "training_phrases" : undefined,
            parametersChanged ? "parameters" : undefined,
            priorityChanged ? "priority" : undefined,
            fallbackChanged ? "is_fallback" : undefined,
            descriptionChanged ? "description" : undefined,
            dtmfChanged ? "dtmf_pattern" : undefined,
          ),
          body: { ...body, name: currentName },
        });
      }

      return toAttrs(current, env.project, agent);
    }, retryQuota),

    delete: Effect.fn(function* ({ output }) {
      yield* dialogflow
        .deleteProjectsLocationsAgentsIntents({ name: output.name })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }, retryQuota),
  });