hoomanjs 1.0.0

package/src/core/memory/ltm/utils.ts

@@ -0,0 +1,218 @@
+import type { Where } from "chromadb";
+import type {
+  LongTermMemoryScope,
+  Memory,
+  MemorySource,
+  MemoryStatus,
+  MemoryType,
+} from "./types.ts";
+
+export const DEFAULT_HALF_LIFE_MS = 1000 * 60 * 60 * 24 * 30;
+export const DEFAULT_REINFORCEMENT_STEP = 0.1;
+export const DEFAULT_DEDUPE_THRESHOLD = 0.92;
+const DEFAULT_SEARCH_LIMIT = 5;
+const MAX_SEARCH_LIMIT = 20;
+
+export type ChromaMemoryMetadata = {
+  userId: string;
+  type: MemoryType;
+  status: MemoryStatus;
+  importance: number;
+  strength: number;
+  accessCount: number;
+  confidence: number | null;
+  createdAt: number;
+  updatedAt: number | null;
+  lastAccessedAt: number | null;
+  version: number;
+  source: MemorySource;
+  /** Omitted when empty: Chroma rejects `[]` for list metadata values. */
+  tags?: string[];
+  entities?: string[];
+  relatedTo?: string[];
+  supersededBy: string | null;
+};
+
+export function clampSearchLimit(limit?: number): number {
+  const value = Math.trunc(limit ?? DEFAULT_SEARCH_LIMIT);
+  return Math.min(Math.max(value, 1), MAX_SEARCH_LIMIT);
+}
+
+export function clampUnitInterval(value: number, fallback: number): number {
+  if (!Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.min(1, Math.max(0, value));
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (Array.isArray(value)) {
+    return value.filter((item): item is string => typeof item === "string");
+  }
+  if (typeof value === "string" && value.length > 0) {
+    return [value];
+  }
+  return undefined;
+}
+
+function normalizeText(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function similarity(left: string, right: string): number {
+  const a = normalizeText(left);
+  const b = normalizeText(right);
+  if (!a || !b) {
+    return 0;
+  }
+  if (a === b) {
+    return 1;
+  }
+
+  const shorter = a.length <= b.length ? a : b;
+  const longer = a.length > b.length ? a : b;
+  const containment = longer.includes(shorter)
+    ? shorter.length / longer.length
+    : 0;
+
+  const tokensA = new Set(a.split(" "));
+  const tokensB = new Set(b.split(" "));
+  let intersection = 0;
+  for (const token of tokensA) {
+    if (tokensB.has(token)) {
+      intersection += 1;
+    }
+  }
+  const union = new Set([...tokensA, ...tokensB]).size;
+  const jaccard = union === 0 ? 0 : intersection / union;
+
+  return Math.max(containment, jaccard);
+}
+
+export function getEffectiveStrength(
+  metadata: Pick<
+    Memory["metadata"],
+    "createdAt" | "lastAccessedAt" | "strength"
+  >,
+  halfLifeMs: number,
+): number {
+  const reference = metadata.lastAccessedAt ?? metadata.createdAt;
+  const age = Math.max(0, Date.now() - reference);
+  return metadata.strength * Math.exp(-age / halfLifeMs);
+}
+
+export function toChromaMetadata(memory: Memory): ChromaMemoryMetadata {
+  const tags = (memory.metadata.tags ?? []).filter((t) => t.length > 0);
+  const entities = (memory.metadata.entities ?? []).filter((t) => t.length > 0);
+  const relatedTo = (memory.metadata.relatedTo ?? []).filter(
+    (t) => t.length > 0,
+  );
+
+  const meta: ChromaMemoryMetadata = {
+    userId: memory.userId,
+    type: memory.type,
+    status: memory.status,
+    importance: memory.metadata.importance,
+    strength: memory.metadata.strength,
+    accessCount: memory.metadata.accessCount,
+    confidence: memory.metadata.confidence ?? null,
+    createdAt: memory.metadata.createdAt,
+    updatedAt: memory.metadata.updatedAt ?? null,
+    lastAccessedAt: memory.metadata.lastAccessedAt ?? null,
+    version: memory.metadata.version,
+    source: memory.metadata.source,
+    supersededBy: memory.metadata.supersededBy ?? null,
+  };
+
+  if (tags.length > 0) {
+    meta.tags = tags;
+  }
+  if (entities.length > 0) {
+    meta.entities = entities;
+  }
+  if (relatedTo.length > 0) {
+    meta.relatedTo = relatedTo;
+  }
+
+  return meta;
+}
+
+export function toMemory(
+  id: string,
+  content: string,
+  metadata: ChromaMemoryMetadata | null | undefined,
+): Memory {
+  const createdAt = Number(metadata?.createdAt ?? Date.now());
+  return {
+    id,
+    userId: metadata?.userId ?? "",
+    type: (metadata?.type ?? "semantic") as MemoryType,
+    status: (metadata?.status ?? "active") as MemoryStatus,
+    content,
+    metadata: {
+      createdAt,
+      updatedAt: metadata?.updatedAt ?? undefined,
+      lastAccessedAt: metadata?.lastAccessedAt ?? undefined,
+      importance: clampUnitInterval(Number(metadata?.importance ?? 0.7), 0.7),
+      strength: Number(metadata?.strength ?? 0.5),
+      confidence:
+        metadata?.confidence == null
+          ? undefined
+          : clampUnitInterval(Number(metadata.confidence), 1),
+      accessCount: Number(metadata?.accessCount ?? 0),
+      version: Number(metadata?.version ?? 1),
+      source: (metadata?.source ?? "assistant") as MemorySource,
+      tags: asStringArray(metadata?.tags),
+      entities: asStringArray(metadata?.entities),
+      supersededBy: metadata?.supersededBy ?? undefined,
+      relatedTo: asStringArray(metadata?.relatedTo),
+    },
+  };
+}
+
+export function buildWhere(
+  scope: LongTermMemoryScope,
+  options?: {
+    status?: MemoryStatus;
+    includeArchived?: boolean;
+    types?: MemoryType[];
+  },
+): Where {
+  // Chroma v3: top-level `where` must have exactly one key (field predicate or $and/$or).
+  const parts: Where[] = [{ userId: scope.userId } as Where];
+
+  const statusFilter = options?.includeArchived
+    ? options.status
+    : (options?.status ?? "active");
+
+  if (statusFilter !== undefined) {
+    parts.push({ status: statusFilter } as Where);
+  }
+
+  if (options?.types?.length) {
+    parts.push({ type: { $in: options.types } } as Where);
+  }
+
+  if (parts.length === 1) {
+    return parts[0]!;
+  }
+
+  return { $and: parts } as Where;
+}
+
+export function chromaClientArgsFromUrl(urlString: string): {
+  host: string;
+  port?: number;
+  ssl: boolean;
+} {
+  const url = new URL(urlString);
+  return {
+    host: url.hostname,
+    port: url.port ? Number(url.port) : undefined,
+    ssl: url.protocol === "https:",
+  };
+}

package/src/core/memory/stm/index.ts

@@ -0,0 +1,17 @@
+import { Agent, SummarizingConversationManager } from "@strands-agents/sdk";
+import { SessionManager, FileStorage } from "@strands-agents/sdk";
+import { sessionsPath } from "../../utils/paths";
+
+export function create(sessionId: string) {
+  const sessionManager = new SessionManager({
+    sessionId,
+    storage: { snapshot: new FileStorage(sessionsPath()) },
+  });
+
+  const conversationManager = new SummarizingConversationManager({
+    summaryRatio: 0.5,
+    preserveRecentMessages: 5,
+  });
+
+  return { sessionManager, conversationManager };
+}

package/src/core/models/anthropic.ts

@@ -0,0 +1,53 @@
+import { anthropic, createAnthropic } from "@ai-sdk/anthropic";
+import { VercelModel } from "@strands-agents/sdk/models/vercel";
+import type { AnthropicProviderSettings } from "@ai-sdk/anthropic";
+import type { VercelModelConfig } from "@strands-agents/sdk/models/vercel";
+import { omit, pick } from "lodash";
+
+const PROVIDER_SETTINGS_KEYS = [
+  "apiKey",
+  "authToken",
+  "baseURL",
+  "headers",
+] as const;
+
+function pickProviderSettings(
+  params: Record<string, unknown>,
+): AnthropicProviderSettings {
+  const picked = pick(params, [...PROVIDER_SETTINGS_KEYS]) as Record<
+    string,
+    unknown
+  >;
+  const unset = Object.keys(picked).filter((k) => picked[k] === undefined);
+  return omit(picked, unset) as AnthropicProviderSettings;
+}
+
+function pickVercelModelConfig(
+  params: Record<string, unknown>,
+): Partial<VercelModelConfig> {
+  return omit(params, [
+    ...PROVIDER_SETTINGS_KEYS,
+  ]) as Partial<VercelModelConfig>;
+}
+
+/**
+ * Anthropic via AI SDK + Strands {@link VercelModel}.
+ *
+ * - **`config.llm.model`**: model id passed to `anthropic(...)` (e.g. `claude-sonnet-4-20250514`).
+ * - **`params`**: Settings {@link AnthropicProviderSettings} (`apiKey`, `authToken`, `baseURL`, …).
+ *   If none are set, the default provider is used (`ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` from env).
+ * - Any other `params` keys are forwarded as {@link VercelModelConfig} (e.g. `temperature`, `maxTokens`).
+ */
+export function create(
+  model: string,
+  params: Record<string, unknown> = {},
+): VercelModel {
+  const settings = pickProviderSettings(params);
+  const provider =
+    Object.keys(settings).length > 0 ? createAnthropic(settings) : anthropic;
+  const config = pickVercelModelConfig(params);
+  return new VercelModel({
+    provider: provider(model),
+    ...config,
+  });
+}

package/src/core/models/bedrock.ts

@@ -0,0 +1,54 @@
+import type { BedrockRuntimeClientConfig } from "@aws-sdk/client-bedrock-runtime";
+import { BedrockModel } from "@strands-agents/sdk/models/bedrock";
+import type { BedrockModelOptions } from "@strands-agents/sdk";
+
+/**
+ * Params map from `config.llm.params` into {@link BedrockModel} options.
+ *
+ * - **`region`**: AWS region (default `us-west-2`).
+ * - **`clientConfig`**: passed to the Bedrock Runtime client (credentials, profile, etc.).
+ *   See AWS SDK v3 docs for credential options.
+ * - **`apiKey`**: optional Bedrock API key auth (bearer), if used instead of SigV4.
+ * - Any other keys are forwarded as Bedrock model config (e.g. `maxTokens`, `temperature`,
+ *   `stream`, `cacheConfig`).
+ *
+ * `config.llm.model` is always used as `modelId`.
+ */
+export type BedrockLlmParams = Omit<
+  BedrockModelOptions,
+  "modelId" | "region" | "clientConfig" | "apiKey"
+> & {
+  region?: string;
+  clientConfig?: BedrockRuntimeClientConfig;
+  apiKey?: string;
+};
+
+const TOP_LEVEL_KEYS = new Set(["region", "clientConfig", "apiKey", "modelId"]);
+
+export function create(
+  model: string,
+  params: Record<string, unknown> = {},
+): BedrockModel {
+  const p = params as Record<string, unknown>;
+  const region =
+    typeof p.region === "string" && p.region.length > 0
+      ? p.region
+      : "us-west-2";
+  const clientConfig = p.clientConfig as BedrockRuntimeClientConfig | undefined;
+  const apiKey = typeof p.apiKey === "string" ? p.apiKey : undefined;
+
+  const modelOptions: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(p)) {
+    if (!TOP_LEVEL_KEYS.has(key)) {
+      modelOptions[key] = value;
+    }
+  }
+
+  return new BedrockModel({
+    modelId: model,
+    region,
+    ...(clientConfig ? { clientConfig } : {}),
+    ...(apiKey !== undefined ? { apiKey } : {}),
+    ...modelOptions,
+  } as BedrockModelOptions);
+}

package/src/core/models/google.ts

@@ -0,0 +1,51 @@
+import { GoogleModel } from "@strands-agents/sdk/models/google";
+import type { GoogleModelOptions } from "@strands-agents/sdk/models/google";
+import { omit, pick } from "lodash";
+
+/**
+ * Keys passed to {@link GoogleModel} alongside `modelId` / `params`.
+ * Generation options (`temperature`, `maxOutputTokens`, …) belong in `params`
+ * (see Gemini [GenerationConfig](https://ai.google.dev/api/generate-content#generationconfig)).
+ */
+const TOP_LEVEL_KEYS = [
+  "apiKey",
+  "client",
+  "clientConfig",
+  "builtInTools",
+] as const;
+
+function omitUndefined(
+  record: Record<string, unknown>,
+): Record<string, unknown> {
+  const unset = Object.keys(record).filter((k) => record[k] === undefined);
+  return omit(record, unset);
+}
+
+/**
+ * Google Gemini via Strands {@link GoogleModel} (`@google/genai` under the hood).
+ *
+ * - **`config.llm.model`**: Gemini id (e.g. `gemini-2.5-flash`).
+ * - **`params`**: Optional `apiKey` (defaults to `GEMINI_API_KEY`), or `client` / `clientConfig`
+ *   for a custom Google GenAI client. Any other keys are sent as `params` to the API
+ *   (`temperature`, `maxOutputTokens`, `topP`, `topK`, …).
+ */
+export function create(
+  model: string,
+  params: Record<string, unknown> = {},
+): GoogleModel {
+  const top = omitUndefined(
+    pick(params, [...TOP_LEVEL_KEYS]) as Record<string, unknown>,
+  ) as Pick<
+    GoogleModelOptions,
+    "apiKey" | "client" | "clientConfig" | "builtInTools"
+  >;
+  const filtered = omitUndefined(
+    omit(params, [...TOP_LEVEL_KEYS]) as Record<string, unknown>,
+  );
+
+  return new GoogleModel({
+    modelId: model,
+    ...top,
+    ...(Object.keys(filtered).length > 0 ? { params: filtered } : {}),
+  } as GoogleModelOptions);
+}

package/src/core/models/index.ts

@@ -0,0 +1,16 @@
+import type { Model, BaseModelConfig } from "@strands-agents/sdk";
+
+export type ModelProvider = {
+  create: (
+    model: string,
+    params: Record<string, any>,
+  ) => Model<BaseModelConfig>;
+};
+
+export const modelProviders: Record<string, () => Promise<ModelProvider>> = {
+  anthropic: () => import("./anthropic.ts"),
+  bedrock: () => import("./bedrock.ts"),
+  google: () => import("./google.ts"),
+  ollama: () => import("./ollama/index.ts"),
+  openai: () => import("./openai.ts"),
+};

package/src/core/models/ollama/index.ts

@@ -0,0 +1,13 @@
+import type { OllamaModelConfig } from "./strands-ollama.ts";
+import { StrandsOllamaModel } from "./strands-ollama.ts";
+
+/** Strands {@link Model} backed by local (or remote) Ollama via `ollama` JS. */
+export function create(
+  model: string,
+  params: Record<string, any>,
+): StrandsOllamaModel {
+  return new StrandsOllamaModel({
+    modelId: model,
+    ...(params as Omit<OllamaModelConfig, "modelId">),
+  });
+}