@manta-eu/client 0.1.9 → 0.2.0

package/src/shared/duration.ts

@@ -0,0 +1,61 @@
+import { isPresent } from "@manta-eu/lib/present";
+import type { Duration } from "iso8601-duration";
+import { parse, toSeconds } from "iso8601-duration";
+
+export function parseDuration(isoDuration: string): Duration | null {
+  try {
+    return parse(isoDuration);
+  } catch {
+    return null;
+  }
+}
+
+export function formatDuration(isoDuration: string): string {
+  const duration = parseDuration(isoDuration);
+  if (!duration) return isoDuration;
+
+  const parts = [];
+
+  if (duration.days) parts.push(`${duration.days}d`);
+  if (duration.hours) parts.push(`${duration.hours}h`);
+  if (duration.minutes) parts.push(`${duration.minutes}m`);
+  if (duration.seconds) parts.push(`${duration.seconds}s`);
+
+  return isPresent(parts) ? parts.join(" ") : "0m";
+}
+
+export function durationToSeconds(isoDuration: string): number | null {
+  const duration = parseDuration(isoDuration);
+  if (!duration) return null;
+
+  return toSeconds(duration);
+}
+
+export function formatDurationSmart(isoDuration: string): string {
+  const duration = parseDuration(isoDuration);
+  if (!duration) return isoDuration;
+
+  const totalSeconds = toSeconds(duration);
+
+  if (totalSeconds < 60) {
+    return `${Math.round(totalSeconds)}s`;
+  }
+
+  if (totalSeconds < 3600) {
+    const minutes = Math.round(totalSeconds / 60);
+    return `${minutes}m`;
+  }
+
+  if (totalSeconds < 86400) {
+    const hours = Math.floor(totalSeconds / 3600);
+    const remainingMinutes = Math.round((totalSeconds % 3600) / 60);
+    return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
+  }
+
+  const days = Math.floor(totalSeconds / 86400);
+  const remainingHours = Math.floor((totalSeconds % 86400) / 3600);
+  if (remainingHours > 0) {
+    return `${days}d ${remainingHours}h`;
+  }
+  return `${days}d`;
+}

package/src/shared/email.ts

@@ -0,0 +1,54 @@
+import { nco, nmo } from "@manta-eu/ldo/namespaces";
+import { isPresent } from "@manta-eu/lib/present";
+import { ExecuteAgentActionAdditionDocument, type GQLExecuteAgentActionAdditionMutation } from "../generated/graphql";
+
+export type EmailGraphql = (document: string, variables: Record<string, unknown>) => Promise<unknown>;
+
+export type RealmEmailTerms = { emailMessageShape: string; renderedFrom: string };
+
+export type RenderedEmail = {
+  subjectIri: string;
+  from: string;
+  to: string;
+  subject: string;
+  renderedFrom: string;
+};
+
+export type EmailStart = { ok: true; plan: string } | { ok: false; error: string };
+
+function renderedEmailAddition(terms: RealmEmailTerms, email: RenderedEmail) {
+  return {
+    subjectIri: email.subjectIri,
+    rdfType: nmo.Email,
+    actionShape: terms.emailMessageShape,
+    properties: {
+      "@id": email.subjectIri,
+      "@type": nmo.Email,
+      [nmo.messageFrom]: { "@type": nco.EmailAddress, [nco.emailAddress]: email.from },
+      [nmo.emailTo]: { "@type": nco.EmailAddress, [nco.emailAddress]: email.to },
+      [nmo.messageSubject]: email.subject,
+      [nmo.contentMimeType]: "text/html",
+      [terms.renderedFrom]: { "@id": email.renderedFrom },
+    },
+  };
+}
+
+export async function startRenderedEmail(
+  graphql: EmailGraphql,
+  terms: RealmEmailTerms,
+  email: RenderedEmail,
+): Promise<EmailStart> {
+  try {
+    const data = (await graphql(ExecuteAgentActionAdditionDocument, {
+      input: renderedEmailAddition(terms, email),
+    })) as GQLExecuteAgentActionAdditionMutation | undefined;
+    const addition = data?.executeActionAddition;
+
+    if (addition?.success === true && isPresent(addition.namedGraphIri)) {
+      return { ok: true, plan: addition.namedGraphIri };
+    }
+    return { ok: false, error: addition?.error ?? "The email action did not start" };
+  } catch (cause) {
+    return { ok: false, error: cause instanceof Error ? cause.message : String(cause) };
+  }
+}

package/src/shared/entity-set.ts

@@ -0,0 +1,33 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { detailViewTypes, lensViewTypes } from "@manta-eu/rdf-lib/detail-view-types";
+import { groupBy, toPairs } from "ramda";
+import { getJsonLdGraph, getNodeId, getNodeTypes, type JsonLdGraphDocument } from "../types/jsonld";
+import { expandPrefix } from "./rdf-namespaces";
+
+export const selfFetchingTypes = detailViewTypes.map(expandPrefix);
+
+export const displayFactTypes = lensViewTypes.map(expandPrefix);
+
+export function entityTypesByIri(graph: JsonLdGraphDocument) {
+  const typesByIri = new Map<string, string[]>();
+
+  for (const node of getJsonLdGraph(graph)) {
+    const id = getNodeId(node);
+    if (id === undefined) continue;
+    typesByIri.set(expandPrefix(id), getNodeTypes(node).map(expandPrefix));
+  }
+
+  return typesByIri;
+}
+
+export type EntityTypeGroup = { typeIris: string[]; iris: string[] };
+
+export function groupEntitiesByType(entityIris: readonly string[], typesByIri: Map<string, string[]>) {
+  const typeKey = (iri: string) => [...(typesByIri.get(expandPrefix(iri)) ?? [])].sort().join("|");
+
+  return toPairs(groupBy(typeKey, entityIris)).map(([key, iris = []]) => ({
+    key,
+    typeIris: isPresent(key) ? key.split("|") : [],
+    iris,
+  }));
+}

package/src/shared/error-utils.ts

@@ -0,0 +1,79 @@
+// hono owns this union. A hand-written copy drifts, and `Exclude<number, ...>` does not narrow.
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+export type ErrorInfo = {
+  message: string;
+  description?: string;
+};
+
+export type HttpError = Error & { status: ContentfulStatusCode };
+
+export function createHttpError(message: string, status: ContentfulStatusCode): HttpError {
+  const err = new Error(message) as HttpError;
+  err.status = status;
+  return err;
+}
+
+export function isHttpError(e: unknown): e is HttpError {
+  return e instanceof Error && typeof (e as HttpError).status === "number";
+}
+
+function isNetworkError(error: unknown): boolean {
+  return (
+    error instanceof TypeError &&
+    (error.message.includes("fetch") || error.message.includes("network") || error.message.includes("Failed to fetch"))
+  );
+}
+
+function isGraphQLError(error: unknown): error is { message: string; graphQLErrors?: unknown[] } {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    (("graphQLErrors" in error && Array.isArray(error.graphQLErrors)) || "networkError" in error)
+  );
+}
+
+export function serializeError(error: unknown) {
+  if (error instanceof Error) return { name: error.name, message: error.message, stack: error.stack };
+
+  return { value: String(error) };
+}
+
+export function parseError(error: unknown, defaultMessage: string): ErrorInfo {
+  if (error instanceof Error) {
+    if (isNetworkError(error)) {
+      return {
+        message: defaultMessage,
+        description: "Network error. Please check your connection and try again.",
+      };
+    }
+
+    return {
+      message: defaultMessage,
+      description: error.message,
+    };
+  }
+
+  if (isGraphQLError(error) && error.graphQLErrors && Array.isArray(error.graphQLErrors)) {
+    const firstError = error.graphQLErrors[0];
+    if (typeof firstError === "object" && firstError && "message" in firstError) {
+      return {
+        message: defaultMessage,
+        description: String(firstError.message),
+      };
+    }
+  }
+
+  if (typeof error === "string") {
+    return {
+      message: defaultMessage,
+      description: error,
+    };
+  }
+
+  return {
+    message: defaultMessage,
+    description: "An unexpected error occurred",
+  };
+}

package/src/shared/explorer-paths.ts

@@ -0,0 +1,9 @@
+// The URL shape of the data explorer. The server redirects into these paths and the app routes
+// them, so both sides must read one definition.
+export const explorerPath = "/data";
+
+export const entitySegment = "entity";
+
+export function entityPath(iri: string): string {
+  return `${explorerPath}/${entitySegment}/${encodeURIComponent(iri)}`;
+}

package/src/shared/fileIri.ts

@@ -0,0 +1,25 @@
+export const fileIriScheme = "s3";
+
+const fileIriPattern = /^s3:\/\/([^/]+)\/(.+)$/;
+
+export function buildFileIri(input: { bucket: string; key: string }) {
+  return `${fileIriScheme}://${input.bucket}/${input.key}`;
+}
+
+export function isFileIri(iri: string) {
+  return fileIriPattern.test(iri);
+}
+
+export function validateFileIri(iri: string) {
+  if (!isFileIri(iri)) {
+    throw new Error(`Invalid file IRI: expected ${fileIriScheme}://<bucket>/<key> - got "${iri}"`);
+  }
+}
+
+export function parseFileIri(iri: string) {
+  validateFileIri(iri);
+
+  const [, bucket = "", storageKey = ""] = fileIriPattern.exec(iri) ?? [];
+
+  return { bucket, storageKey };
+}

package/src/shared/index.ts

@@ -0,0 +1,31 @@
+import type { UIMessage } from "ai";
+import type { OperatorAllowedModel } from "./model";
+import type { PageContext } from "./page-context";
+
+// Approval string to be shared across frontend and backend
+export const APPROVAL = {
+  YES: "Yes, confirmed.",
+  NO: "No, denied.",
+} as const;
+
+export type AssistantResponseState = "in-progress" | "finished" | "failed" | "aborted";
+
+export type ChatUIMessage = UIMessage<{
+  createdAt: string;
+  userId?: string;
+  datastoreId?: string;
+  totalTokens?: number;
+  finishReason?: string;
+  responseState?: AssistantResponseState;
+  isTask?: boolean;
+  traceId?: string;
+  pageContext?: PageContext;
+  model?: OperatorAllowedModel;
+}>;
+
+/** A blank chat, which `/` stops being once an app gives its datastores a home page. */
+export const newChatPath = "/chat";
+
+export function chatIdToPath(id: string) {
+  return `/chat/${encodeURIComponent(id)}`;
+}

package/src/shared/inferal-stream.ts

@@ -0,0 +1,2 @@
+// Inferal caps a stream name at 64 characters, and the server spends 17 of them on the "ds-<hash>:" prefix.
+export const inferalStreamNameMaxLength = 47;

package/src/shared/live-context.ts

@@ -0,0 +1,15 @@
+// :now[:Clock] is MAX(schema:dateModified) over ingested platform data, not real time, and is unbound on an
+// empty datastore - every reader of :LiveContext_Chat has to apply memory dates itself, against NOW().
+export const liveContextMemoryDateFilter = `FILTER NOT EXISTS {
+        ?entity a :Memory .
+        {
+          ?entity :memoryTrustedUntil ?horizon .
+          FILTER(?horizon <= NOW())
+        } UNION {
+          ?entity :memoryValidUntil ?expiry .
+          FILTER(?expiry <= NOW())
+        } UNION {
+          ?entity :memoryValidFrom ?validFrom .
+          FILTER(?validFrom > NOW())
+        }
+      }`;

package/src/shared/maintenance-schedule.ts

@@ -0,0 +1,47 @@
+import { msPerDay } from "./memory-dates";
+
+export const maintenanceTickMinutes = 30;
+
+export const compactionPeriodHours = 24;
+
+export function ticksInPeriod(periodHours: number): number {
+  return Math.max(1, Math.round((periodHours * 60) / maintenanceTickMinutes));
+}
+
+// This is FNV-1a, kept synchronous because this file ships to the browser without node:crypto.
+export function stableSlot(key: string, slots: number): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < key.length; i++) {
+    hash ^= key.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash % slots;
+}
+
+export function sampledByKey(key: string, rate: number): boolean {
+  if (rate <= 0) return false;
+  if (rate >= 1) return true;
+
+  // 0x100000000 is 2^32, the hash's full range, so dividing by it maps the hash to a fraction in [0, 1).
+  return stableSlot(key, 0x100000000) / 0x100000000 < rate;
+}
+
+export function currentTick(now: Date, periodHours: number): number {
+  return Math.floor(now.getTime() / (maintenanceTickMinutes * 60_000)) % ticksInPeriod(periodHours);
+}
+
+export function isDueThisTick(key: string, now: Date, periodHours: number): boolean {
+  const slots = ticksInPeriod(periodHours);
+  return stableSlot(key, slots) === currentTick(now, periodHours);
+}
+
+export function dueThisTick(keys: readonly string[], now: Date, periodHours: number): string[] {
+  return keys.filter((key) => isDueThisTick(key, now, periodHours));
+}
+
+export const redundancySweepDayBuckets = 7;
+
+export function isDueOnDay(key: string, now: Date, buckets: number = redundancySweepDayBuckets): boolean {
+  const day = Math.floor(now.getTime() / msPerDay) % buckets;
+  return stableSlot(key, buckets) === day;
+}

package/src/shared/memory-citation-sampling.ts

@@ -0,0 +1,26 @@
+import { sampledByKey } from "./maintenance-schedule";
+
+// citeMemories under-counts memories that work by suppressing an answer; treat as diagnostic, not a score.
+export const memoryCitationSampleRate = 0.1;
+
+export function shouldRequestCitations(seed: string, rate: number = memoryCitationSampleRate): boolean {
+  return sampledByKey(seed, rate);
+}
+
+export type CitationRequestTurn = {
+  hasPersonalPreload: boolean;
+  hasSharedSections: boolean;
+  seed: string;
+};
+
+export type CitationDecision =
+  | { requested: false; reason: "none" }
+  | { requested: true; reason: "personal" | "sampled" };
+
+export function citationDecisionForTurn(turn: CitationRequestTurn, rate?: number): CitationDecision {
+  if (turn.hasPersonalPreload) return { requested: true, reason: "personal" };
+  if (turn.hasSharedSections && shouldRequestCitations(turn.seed, rate)) {
+    return { requested: true, reason: "sampled" };
+  }
+  return { requested: false, reason: "none" };
+}

package/src/shared/memory-confidence.ts

@@ -0,0 +1,8 @@
+import { clamp } from "ramda";
+
+export const unreviewedMemoryConfidence = 0.7;
+
+export function normalizeConfidence(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(clamp(0, 1, value) * 100) / 100;
+}

package/src/shared/memory-consolidation-limits.ts

@@ -0,0 +1,9 @@
+export const consolidationChunkSize = 12;
+
+export const consolidationMaxChunks = 12;
+
+export const consolidationCandidateLimit = consolidationChunkSize * consolidationMaxChunks;
+
+export const consolidationSeedBatchSize = 8;
+
+export const consolidationJudgeBatchSize = 4;

package/src/shared/memory-dates.ts

@@ -0,0 +1,7 @@
+export const msPerDay = 24 * 60 * 60 * 1000;
+
+export function parseMemoryDate(value: Date | string | null | undefined): Date | null {
+  if (!value) return null;
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}

package/src/shared/memory-decay.ts

@@ -0,0 +1,70 @@
+import { msPerDay, parseMemoryDate } from "./memory-dates";
+
+export const personalMemoryScope = "user";
+
+export type MemoryDecayCandidate = {
+  scope?: string | null;
+  memoryUseCount?: number | null;
+  memoryCiteCount?: number | null;
+  memoryLastUsedAt?: Date | string | null;
+};
+
+export const preloadedUseWeight = 1;
+
+export const citedUseWeight = 0;
+
+export type UseWeights = { preloaded?: number; cited?: number };
+
+export function weightedUseCount(memory: MemoryDecayCandidate, weights?: UseWeights): number {
+  const preloaded = Math.max(memory.memoryUseCount ?? 0, 0) * (weights?.preloaded ?? preloadedUseWeight);
+  const cited = Math.max(memory.memoryCiteCount ?? 0, 0) * (weights?.cited ?? citedUseWeight);
+  return preloaded + cited;
+}
+
+export const decayUseCountCap = 20;
+
+export const decayHalfLifeDays = 7;
+
+export const decayDemotionThreshold = 0.5;
+
+export const decayHoldOutDays = 30;
+
+export function usageWeight(
+  useCount: number | null | undefined,
+  lastUsedAt: Date | string | null | undefined,
+  now: Date = new Date(),
+): number {
+  const uses = Math.min(Math.max(useCount ?? 0, 0), decayUseCountCap);
+  if (uses === 0) return 0;
+
+  const lastUsed = parseMemoryDate(lastUsedAt);
+  if (!lastUsed) return uses;
+
+  const days = Math.max((now.getTime() - lastUsed.getTime()) / msPerDay, 0);
+  return uses * Math.pow(0.5, days / decayHalfLifeDays);
+}
+
+export function coldOnsetDays(useCount: number): number {
+  // Floor at the demotion threshold, not 1: a fractional weighted count is already below it at day 0,
+  // so clamping to 1 would report an onset the decay curve never had.
+  const uses = Math.min(Math.max(useCount, decayDemotionThreshold), decayUseCountCap);
+  return decayHalfLifeDays * Math.log2(uses / decayDemotionThreshold);
+}
+
+export function shouldDemoteOnUsage(
+  memory: MemoryDecayCandidate,
+  now: Date = new Date(),
+  weights?: UseWeights,
+): boolean {
+  if (memory.scope !== personalMemoryScope) return false;
+
+  const uses = weightedUseCount(memory, weights);
+  if (uses <= 0) return false;
+  if (usageWeight(uses, memory.memoryLastUsedAt, now) >= decayDemotionThreshold) return false;
+
+  const lastUsed = parseMemoryDate(memory.memoryLastUsedAt);
+  if (!lastUsed) return false;
+
+  const daysSinceUse = (now.getTime() - lastUsed.getTime()) / msPerDay;
+  return daysSinceUse < coldOnsetDays(uses) + decayHoldOutDays;
+}

package/src/shared/memory-diversity.ts

@@ -0,0 +1,55 @@
+export const memoryRedundancyThreshold = 0.6;
+
+export const memoryDiversityCandidateMultiplier = 3;
+
+export type DiversityCandidate = {
+  label?: string | null;
+  description?: string | null;
+};
+
+const tokenPattern = /[a-z0-9]+/g;
+
+const minimumTokenLength = 3;
+
+export function memoryTokens(memory: DiversityCandidate): Set<string> {
+  const text = `${memory.label ?? ""} ${memory.description ?? ""}`.toLowerCase();
+  const tokens = text.match(tokenPattern) ?? [];
+  return new Set(tokens.filter((t) => t.length >= minimumTokenLength));
+}
+
+export function jaccardSimilarity(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 || b.size === 0) return 0;
+  let shared = 0;
+  for (const token of a) if (b.has(token)) shared += 1;
+  const union = a.size + b.size - shared;
+  return union === 0 ? 0 : shared / union;
+}
+
+export function selectDiverseMemories<T extends DiversityCandidate>(
+  candidates: readonly T[],
+  limit: number,
+  threshold: number = memoryRedundancyThreshold,
+): T[] {
+  if (limit <= 0) return [];
+  if (candidates.length <= limit) return [...candidates];
+
+  const tokens = candidates.map(memoryTokens);
+  const taken: number[] = [];
+  const skipped: number[] = [];
+
+  for (let i = 0; i < candidates.length && taken.length < limit; i += 1) {
+    const redundant = taken.some((j) => jaccardSimilarity(tokens[i] ?? new Set(), tokens[j] ?? new Set()) >= threshold);
+    if (redundant) skipped.push(i);
+    else taken.push(i);
+  }
+
+  for (const i of skipped) {
+    if (taken.length >= limit) break;
+    taken.push(i);
+  }
+
+  return taken
+    .sort((a, b) => a - b)
+    .map((i) => candidates[i])
+    .filter((memory): memory is T => memory !== undefined);
+}

package/src/shared/memory-entity-recall.ts

@@ -0,0 +1,26 @@
+export const entityHopLimit = 8;
+
+export const entityLabelMatchLimit = 6;
+
+export type EntityHopCandidate = { aboutEntityIris?: readonly string[] | null };
+
+export function collectAboutEntities(
+  memories: readonly EntityHopCandidate[],
+  limit: number = entityHopLimit,
+): string[] {
+  const seen = new Set<string>();
+
+  for (const memory of memories) {
+    for (const iri of memory.aboutEntityIris ?? []) {
+      if (seen.size >= limit) return [...seen];
+      seen.add(iri);
+    }
+  }
+
+  return [...seen];
+}
+
+export function withoutEntities(entityIris: readonly string[], exclude: readonly string[]): string[] {
+  const excluded = new Set(exclude);
+  return entityIris.filter((iri) => !excluded.has(iri));
+}

package/src/shared/memory-importance.ts

@@ -0,0 +1,12 @@
+import { clamp } from "ramda";
+import { maxImportanceForVolatility } from "./memory-volatility";
+
+export const defaultMemoryImportance = 3;
+
+export function clampImportance(value: number): number {
+  return clamp(1, 5, Math.round(value));
+}
+
+export function clampImportanceForVolatility(value: number, volatility: unknown): number {
+  return Math.min(clampImportance(value), maxImportanceForVolatility(volatility));
+}