import * as aiplatform from "@distilled.cloud/gcp/aiplatform_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { GcpEnvironment } from "../Environment.ts";
import { createInternalLabels, hasAlchemyLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import { listLocations } from "./names.ts";
import { resourceNameFromOperation, waitForOperation } from "./operations.ts";
import { listAlchemyReasoningEngines } from "./ReasoningEngine.ts";
import {
AiPlatformNotResolved,
AiPlatformStillExists,
collectPages,
encodeDescription,
hasDescriptionOwnership,
jsonEqual,
lastSegment,
locationParent,
normalizeLocation,
parentBefore,
parseDescription,
parseResourceName,
toPhysicalId,
} from "./shared.ts";
const COLLECTION = "memories";
export type MemoryMetadataValue = {
boolValue?: boolean;
doubleValue?: number;
stringValue?: string;
timestampValue?: string;
};
export type ReasoningEnginesMemoryProps = {
/**
* Parent Reasoning Engine. Full name
* `projects/{project}/locations/{location}/reasoningEngines/{engine}`
* or the engine id (combined with `location`). Immutable — changing it
* replaces the memory.
*/
reasoningEngine: string;
/**
* Vertex AI location. Used when `reasoningEngine` is a bare id.
* Immutable. @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
*/
location?: string;
/**
* Memory id. If omitted, a unique RFC1035 name is generated. Immutable
* — changing it replaces the memory.
*/
memoryId?: string;
/**
* Isolation scope. Required and immutable. Values cannot contain `*`.
*/
scope: Record<string, string>;
/**
* Semantic fact extracted from source content.
*/
fact?: string;
/**
* Display name.
*/
displayName?: string;
/**
* Human-readable description. Memory has no labels field, so Alchemy
* ownership is stored in a `[alchemy …]` prefix for `list` / nuke.
*/
description?: string;
/**
* User-provided metadata (not generated by Memory Bank).
*/
metadata?: Record<string, MemoryMetadataValue>;
/**
* TTL for this memory (e.g. `"86400s"`). Input only.
*/
ttl?: string;
/**
* Absolute expire time (RFC3339).
*/
expireTime?: string;
};
export type ReasoningEnginesMemory = Resource<
"GCP.AIPlatform.ReasoningEnginesMemory",
ReasoningEnginesMemoryProps,
{
/** Full resource name. */
name: string;
/** Memory id (last path segment). */
memoryId: string;
/** Parent Reasoning Engine resource name. */
reasoningEngine: string;
/** Project id. */
project: string;
/** Location id. */
location: string;
/** Isolation scope. */
scope: aiplatform.StringMap;
/** Semantic fact. */
fact: string | undefined;
/** Display name. */
displayName: string | undefined;
/** User description with the Alchemy ownership prefix stripped. */
description: string | undefined;
/** RFC3339 expire time. */
expireTime: string | undefined;
/** RFC3339 creation timestamp. */
createTime: string | undefined;
/** RFC3339 last-update timestamp. */
updateTime: string | undefined;
},
never,
Providers
>;
/**
* A Vertex AI Reasoning Engine memory — scoped semantic knowledge used
* by an Agent Engine Memory Bank.
*
* Memory has no labels, so Alchemy stamps ownership into the
* description. Changing `memoryId`, `reasoningEngine`, `location`, or
* `scope` replaces the memory. Fact, description, and metadata update in
* place.
*
* ### Creating a Memory
* **Example:** User-scoped fact
* ```typescript
* const memory = yield* GCP.AIPlatform.ReasoningEnginesMemory("Pref", {
* reasoningEngine: engine.name,
* scope: { user_id: "user-123" },
* fact: "the user prefers concise answers",
* });
* ```
*
* @resource
* @category AIPlatform
*/
export const ReasoningEnginesMemory = Resource<ReasoningEnginesMemory>(
"GCP.AIPlatform.ReasoningEnginesMemory",
);
export class ReasoningEnginesMemoryNotResolved extends Data.TaggedError(
"GCP.AIPlatform.ReasoningEnginesMemoryNotResolved",
)<{
resourceName: string;
}> {}
const engineNameOf = (project: string, location: string, reasoningEngine: string) =>
reasoningEngine.includes("/")
? reasoningEngine
: `${locationParent(project, location)}/reasoningEngines/${reasoningEngine}`;
const resourceName = (parent: string, memoryId: string) => `${parent}/${COLLECTION}/${memoryId}`;
const toAttrs = (memory: aiplatform.GoogleCloudAiplatformV1Memory, project: string) => {
const name = memory.name ?? "";
const parsed = parseResourceName(name, COLLECTION);
const description = parseDescription(memory.description);
return {
name,
memoryId: parsed.id,
reasoningEngine: parentBefore(name, COLLECTION),
project: parsed.project || project,
location: parsed.location,
scope: memory.scope ?? {},
fact: memory.fact,
displayName: memory.displayName,
description: description.description,
expireTime: memory.expireTime,
createTime: memory.createTime,
updateTime: memory.updateTime,
};
};
const getByName = (name: string) =>
aiplatform
.getProjectsLocationsReasoningEnginesMemories({ name })
.pipe(Effect.catchTag("NotFound", () => Effect.undefined));
const waitUntilExists = (name: string) =>
getByName(name).pipe(
Effect.filterOrFail(
(memory): memory is aiplatform.GoogleCloudAiplatformV1Memory => memory !== undefined,
() => new AiPlatformNotResolved({ resourceName: name }),
),
Effect.retry({
while: (error) => error._tag === "GCP.AIPlatform.NotResolved",
times: 8,
schedule: Schedule.spaced("2 seconds"),
}),
);
const waitUntilGone = (name: string) =>
getByName(name).pipe(
Effect.filterOrFail(
(memory) => memory === undefined,
() => new AiPlatformStillExists({ resourceName: name }),
),
Effect.asVoid,
Effect.retry({
while: (error) => error._tag === "GCP.AIPlatform.StillExists",
times: 10,
schedule: Schedule.spaced("2 seconds"),
}),
);
const listMemories = (parent: string) =>
collectPages(
aiplatform.listProjectsLocationsReasoningEnginesMemories.pages({
parent,
pageSize: 100,
}),
).pipe(
Effect.map((pages) => pages.flatMap((page) => page.memories ?? [])),
Effect.catchTag("NotFound", () =>
Effect.succeed<aiplatform.GoogleCloudAiplatformV1Memory[]>([]),
),
);
export const ReasoningEnginesMemoryProvider = () =>
Provider.succeed(ReasoningEnginesMemory, {
stables: ["name", "memoryId", "reasoningEngine", "project", "location", "createTime"],
diff: Effect.fn(function* ({ news, olds, output }) {
const env = yield* GcpEnvironment.current;
if (!isResolved(news)) return undefined;
const previousId = olds?.memoryId ?? output?.memoryId;
const nextId = news.memoryId ?? previousId;
const previousParent = lastSegment(olds?.reasoningEngine ?? output?.reasoningEngine ?? "");
const nextParent = lastSegment(news.reasoningEngine);
const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
const nextLocation = normalizeLocation(news.location ?? output?.location, env.region);
const scopeChanged = olds !== undefined && !jsonEqual(news.scope, olds.scope);
const replace =
(previousId !== undefined && nextId !== undefined && nextId !== previousId) ||
(previousParent.length > 0 && previousParent !== nextParent) ||
previousLocation !== nextLocation ||
scopeChanged;
if (!replace) return undefined;
return {
action: "replace" as const,
deleteFirst:
previousLocation === nextLocation &&
previousParent === nextParent &&
previousId !== undefined &&
nextId === previousId,
};
}),
read: Effect.fn(function* ({ id, olds, output }) {
const env = yield* GcpEnvironment.current;
const location = normalizeLocation(olds?.location ?? output?.location, env.region);
const engine = olds?.reasoningEngine ?? output?.reasoningEngine;
// A create interrupted before its engine resolved has nothing to find.
if (output?.name === undefined && typeof engine !== "string") {
return undefined;
}
const parent = engineNameOf(env.project, location, engine ?? "");
const memoryId = yield* toPhysicalId(id, olds?.memoryId, output?.memoryId);
const name = output?.name ?? resourceName(parent, memoryId);
const existing = yield* getByName(name);
if (existing === undefined) return undefined;
const attrs = toAttrs(existing, env.project);
const parsed = parseDescription(existing.description);
return (yield* hasAlchemyLabels(id, parsed.labels)) ? attrs : Unowned(attrs);
}),
list: () =>
Effect.gen(function* () {
const env = yield* GcpEnvironment.current;
const engines = (yield* Effect.forEach(listLocations(env.region), (location) =>
listAlchemyReasoningEngines(env.project, location),
)).flat();
const memories = yield* Effect.forEach(
engines,
(engine) =>
engine.name
? listMemories(engine.name)
: Effect.succeed<aiplatform.GoogleCloudAiplatformV1Memory[]>([]),
{ concurrency: 4 },
);
return memories
.flat()
.filter((memory) => hasDescriptionOwnership(memory.description))
.map((memory) => toAttrs(memory, env.project));
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const env = yield* GcpEnvironment.current;
const location = normalizeLocation(news.location ?? output?.location, env.region);
const parent = engineNameOf(env.project, location, news.reasoningEngine);
const memoryId = yield* toPhysicalId(id, news.memoryId, output?.memoryId);
const name = resourceName(parent, memoryId);
const internal = yield* createInternalLabels(id);
const stampedDescription = encodeDescription(internal, news.description);
let current = yield* getByName(output?.name ?? name);
if (current === undefined) {
const created = yield* aiplatform
.createProjectsLocationsReasoningEnginesMemories({
parent,
memoryId,
body: {
scope: news.scope,
fact: news.fact,
displayName: news.displayName,
description: stampedDescription,
metadata: news.metadata,
ttl: news.ttl,
expireTime: news.expireTime,
},
})
.pipe(Effect.catchTag("Conflict", () => Effect.undefined));
if (created !== undefined) {
yield* waitForOperation(created, { alreadyExistsOk: true });
}
const createdName = resourceNameFromOperation(created ?? {}) ?? output?.name ?? name;
current = yield* waitUntilExists(createdName);
}
if (current === undefined || current.name === undefined) {
return yield* new ReasoningEnginesMemoryNotResolved({ resourceName: name });
}
const observedName = current.name;
const observed = parseDescription(current.description);
const factChanged = (current.fact ?? "") !== (news.fact ?? "");
const displayChanged = (current.displayName ?? "") !== (news.displayName ?? "");
const descriptionChanged = (observed.description ?? "") !== (news.description ?? "");
const metadataChanged = !jsonEqual(current.metadata, news.metadata);
if (factChanged || displayChanged || descriptionChanged || metadataChanged) {
const updateMask = [
factChanged ? "fact" : undefined,
displayChanged ? "display_name" : undefined,
descriptionChanged ? "description" : undefined,
metadataChanged ? "metadata" : undefined,
].filter((field): field is string => field !== undefined);
const patched = yield* aiplatform.patchProjectsLocationsReasoningEnginesMemories({
name: observedName,
updateMask: updateMask.join(","),
body: {
name: observedName,
fact: news.fact,
displayName: news.displayName,
description: stampedDescription,
metadata: news.metadata,
},
});
yield* waitForOperation(patched);
current = yield* getByName(observedName);
}
if (current === undefined) {
return yield* new ReasoningEnginesMemoryNotResolved({
resourceName: observedName,
});
}
return toAttrs(current, env.project);
}),
delete: Effect.fn(function* ({ output }) {
const operation = yield* aiplatform
.deleteProjectsLocationsReasoningEnginesMemories({
name: output.name,
})
.pipe(Effect.catchTag("NotFound", () => Effect.undefined));
if (operation !== undefined) {
yield* waitForOperation(operation, { notFoundOk: true });
}
yield* waitUntilGone(output.name);
}),
});