@qearlyao/familiar 0.1.0

package/dist/memory/tools.js

@@ -0,0 +1,205 @@
+import { Type } from "typebox";
+import { retrieveMemory } from "./index/retrieval.js";
+const DEFAULT_RECALL_LIMIT = 8;
+const MAX_TEXT_PREVIEW_CHARS = 700;
+const MAX_CONTEXT_LABEL_CHARS = 120;
+const MAX_SOURCE_LABEL_CHARS = 160;
+const MEMORY_SCOPE_CORPORA = {
+    diary: ["diary_chunk"],
+    factual: ["atomic_fact", "lcm_record", "lcm_summary"],
+    all: undefined,
+};
+const memoryRecallSchema = Type.Object({
+    query: Type.String({ description: "Natural-language memory search query." }),
+    scope: Type.Optional(Type.Union([Type.Literal("diary"), Type.Literal("factual"), Type.Literal("all")], {
+        default: "all",
+        description: "all searches every memory corpus; diary searches long-term diary memory; factual searches facts and conversation memory.",
+    })),
+    mode: Type.Optional(Type.Union([Type.Literal("lexical"), Type.Literal("semantic"), Type.Literal("hybrid")], {
+        default: "hybrid",
+        description: "hybrid uses lexical and semantic recall; lexical and semantic restrict to one mode.",
+    })),
+    before: Type.Optional(Type.String({
+        description: "Only recall chunks whose metadata.timestamp or createdAt is at or before this ISO 8601 time.",
+    })),
+    after: Type.Optional(Type.String({
+        description: "Only recall chunks whose metadata.timestamp or createdAt is at or after this ISO 8601 time.",
+    })),
+    limit: Type.Optional(Type.Number({
+        default: DEFAULT_RECALL_LIMIT,
+        minimum: 1,
+        maximum: 20,
+    })),
+}, { additionalProperties: false });
+const memoryOpenSchema = Type.Object({
+    id: Type.Number({
+        description: "Memory chunk id returned by memory_recall.",
+        minimum: 1,
+    }),
+}, { additionalProperties: false });
+export function createMemoryTools(deps) {
+    return [makeMemoryRecallTool(deps), makeMemoryOpenTool(deps)];
+}
+function makeMemoryRecallTool(deps) {
+    return {
+        name: "memory_recall",
+        label: "Memory Recall",
+        description: "search memory for diary, fact, or conversation chunks. returns previews and ids; use memory_open for full text and source details.",
+        parameters: memoryRecallSchema,
+        async execute(_toolCallId, input, signal) {
+            const query = input.query.trim();
+            if (!query)
+                throw new Error("memory_recall query is required.");
+            const scope = input.scope ?? "all";
+            const mode = input.mode ?? "hybrid";
+            const limit = clampLimit(input.limit);
+            assertIsoTime(input.before, "before");
+            assertIsoTime(input.after, "after");
+            const hits = await retrieveMemory({
+                query,
+                store: deps.store,
+                embeddingProvider: deps.embeddingProvider,
+                scope: { corpora: MEMORY_SCOPE_CORPORA[scope], before: input.before, after: input.after },
+                limit,
+                useLexical: mode !== "semantic",
+                useSemantic: mode !== "lexical",
+                signal,
+            });
+            return {
+                content: [{ type: "text", text: formatRecallResults(hits) }],
+                details: {
+                    query,
+                    scope,
+                    mode,
+                    limit,
+                    resultCount: hits.length,
+                    ids: hits.map((hit) => hit.id),
+                },
+            };
+        },
+    };
+}
+function makeMemoryOpenTool(deps) {
+    return {
+        name: "memory_open",
+        label: "Memory Open",
+        description: "open one stored memory chunk by id. returns the full text plus source details.",
+        parameters: memoryOpenSchema,
+        async execute(_toolCallId, input) {
+            const id = Math.trunc(input.id);
+            if (!Number.isInteger(input.id) || id < 1)
+                throw new Error("memory_open id must be a positive integer.");
+            const chunk = deps.store.getChunk(id);
+            if (!chunk) {
+                return {
+                    content: [{ type: "text", text: `No memory chunk found for id ${id}.` }],
+                    details: { id, found: false },
+                };
+            }
+            return {
+                content: [{ type: "text", text: formatOpenChunk(chunk) }],
+                details: {
+                    id,
+                    found: true,
+                    corpus: chunk.corpus,
+                    sourceId: chunk.sourceId,
+                    sourceRef: chunk.sourceRef,
+                    chunkIndex: chunk.chunkIndex,
+                    sources: chunk.sources,
+                },
+            };
+        },
+    };
+}
+function clampLimit(value) {
+    if (value === undefined)
+        return DEFAULT_RECALL_LIMIT;
+    if (!Number.isInteger(value) || value < 1)
+        throw new Error("memory_recall limit must be a positive integer.");
+    return Math.min(value, 20);
+}
+function assertIsoTime(value, name) {
+    if (value === undefined)
+        return;
+    if (!Number.isFinite(Date.parse(value)))
+        throw new Error(`memory_recall ${name} must be an ISO 8601 timestamp.`);
+}
+function formatRecallResults(hits) {
+    if (hits.length === 0)
+        return "No matching memories found.";
+    return hits.map((hit, index) => formatRecallHit(hit, index + 1)).join("\n\n");
+}
+function formatRecallHit(hit, ordinal) {
+    const chunk = hit.chunk;
+    const lines = [
+        `${ordinal}. id=${hit.id} type=${memoryTypeLabel(chunk)} score=${hit.score.toFixed(4)}`,
+        ...compactContextLines(chunk),
+        `preview: ${previewText(chunk.snippet || chunk.text, MAX_TEXT_PREVIEW_CHARS)}`,
+    ];
+    return lines.join("\n");
+}
+function formatOpenChunk(chunk) {
+    const lines = [
+        `id=${chunk.id} type=${memoryTypeLabel(chunk)}`,
+        ...compactContextLines(chunk),
+        ...openSourceLines(chunk),
+        `stored=${formatUnixTimestamp(chunk.createdAt)} updated=${formatUnixTimestamp(chunk.updatedAt)}`,
+        "",
+        chunk.text,
+    ];
+    return lines.join("\n");
+}
+function memoryTypeLabel(chunk) {
+    if (chunk.corpus === "diary_chunk")
+        return "diary";
+    if (chunk.corpus === "lcm_record")
+        return "conversation";
+    if (chunk.corpus === "lcm_summary")
+        return "conversation_summary";
+    if (chunk.corpus === "atomic_fact")
+        return "fact";
+    return chunk.corpus;
+}
+function compactContextLines(chunk) {
+    const lines = [];
+    const happenedAt = metadataString(chunk.metadata, "happenedAt") ?? metadataString(chunk.metadata, "timestamp");
+    const date = metadataString(chunk.metadata, "date");
+    const heading = metadataString(chunk.metadata, "heading");
+    if (happenedAt)
+        lines.push(`when=${happenedAt}`);
+    else if (date)
+        lines.push(`when=${date}`);
+    if (heading)
+        lines.push(`title=${previewText(heading, MAX_CONTEXT_LABEL_CHARS)}`);
+    return lines;
+}
+function openSourceLines(chunk) {
+    const sources = chunk.sources.length > 0
+        ? chunk.sources
+        : [{ sourceId: chunk.sourceId, sourceRef: chunk.sourceRef, chunkIndex: chunk.chunkIndex }];
+    const labels = sources
+        .map((source) => source.sourceRef ?? source.sourceId)
+        .filter((value) => !!value)
+        .map((value) => previewText(value, MAX_SOURCE_LABEL_CHARS));
+    return labels.length ? [`sources=${Array.from(new Set(labels)).join("; ")}`] : [];
+}
+function metadataString(metadata, key) {
+    const value = metadata?.[key];
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function previewText(text, maxLength) {
+    const normalized = text.replaceAll(/\s+/g, " ").trim();
+    if (normalized.length <= maxLength)
+        return normalized;
+    return `${normalized.slice(0, maxLength - 3).trimEnd()}...`;
+}
+function formatUnixTimestamp(value) {
+    const milliseconds = value < 10_000_000_000 ? value * 1000 : value;
+    return new Date(milliseconds).toISOString();
+}
+export const __memoryToolsTest = {
+    formatUnixTimestamp,
+    formatOpenChunk,
+    formatRecallResults,
+    previewText,
+};

package/dist/models.js

@@ -0,0 +1,165 @@
+import { clampThinkingLevel, findEnvKeys, getEnvApiKey, getModels, getProviders, } from "@earendil-works/pi-ai";
+const PROVIDER_DEFAULTS = {
+    anthropic: {
+        api: "anthropic-messages",
+        baseUrl: "https://api.anthropic.com",
+    },
+    google: {
+        api: "google-generative-ai",
+        baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+    },
+    "google-vertex": {
+        api: "google-vertex",
+        baseUrl: "https://{location}-aiplatform.googleapis.com",
+    },
+    openai: {
+        api: "openai-responses",
+        baseUrl: "https://api.openai.com/v1",
+    },
+    groq: {
+        api: "openai-completions",
+        baseUrl: "https://api.groq.com/openai/v1",
+    },
+};
+export function parseModelRef(value) {
+    const trimmed = value.trim();
+    const separator = trimmed.indexOf("/");
+    if (separator <= 0 || separator === trimmed.length - 1)
+        return undefined;
+    const provider = trimmed.slice(0, separator).trim();
+    const id = trimmed.slice(separator + 1).trim();
+    if (!provider || !id)
+        return undefined;
+    return { provider, id, key: `${provider}/${id}` };
+}
+function findBuiltInModel(ref) {
+    if (!getProviders().includes(ref.provider))
+        return undefined;
+    const models = getModels(ref.provider);
+    return models.find((model) => model.id === ref.id);
+}
+function createFallbackModel(ref) {
+    const defaults = PROVIDER_DEFAULTS[ref.provider];
+    if (!defaults) {
+        throw new Error(`Unsupported model provider: ${ref.provider}`);
+    }
+    return {
+        id: ref.id,
+        name: ref.id,
+        api: defaults.api,
+        provider: ref.provider,
+        baseUrl: defaults.baseUrl,
+        reasoning: true,
+        input: ["text", "image"],
+        cost: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+        },
+        contextWindow: 200000,
+        maxTokens: 8192,
+    };
+}
+function applyConfiguredBaseUrl(config, model) {
+    const baseUrl = config.models.baseUrls[`${model.provider}/${model.id}`] ?? config.models.baseUrls[model.provider];
+    return baseUrl ? { ...model, baseUrl } : model;
+}
+export function resolveModel(ref, config) {
+    const model = findBuiltInModel(ref) ?? createFallbackModel(ref);
+    return config ? applyConfiguredBaseUrl(config, model) : model;
+}
+export function createConfiguredModel(config) {
+    const ref = parseModelRef(config.agent.model);
+    if (!ref)
+        throw new Error(`Invalid agent.model: ${config.agent.model}`);
+    if (config.agent.api && config.agent.modelId && config.agent.baseUrl) {
+        return applyConfiguredBaseUrl(config, {
+            id: config.agent.modelId,
+            name: config.agent.modelId,
+            api: config.agent.api,
+            provider: config.agent.provider,
+            baseUrl: config.agent.baseUrl,
+            reasoning: true,
+            input: ["text", "image"],
+            cost: {
+                input: 0,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+            },
+            contextWindow: 200000,
+            maxTokens: 8192,
+        });
+    }
+    return resolveModel(ref, config);
+}
+export function resolveModelApiKey(config, model) {
+    const configuredEnv = config.models.apiKeyEnvs[`${model.provider}/${model.id}`] ??
+        config.models.apiKeyEnvs[model.provider] ??
+        (model.provider === config.agent.provider ? config.agent.apiKeyEnv : undefined);
+    if (configuredEnv)
+        return process.env[configuredEnv];
+    return getEnvApiKey(model.provider);
+}
+export function requiresExplicitApiKey(config, model) {
+    if (model.provider === "google-vertex")
+        return false;
+    return resolveModelApiKey(config, model) === undefined;
+}
+function hasVertexAdcEnvironment() {
+    const project = process.env.GOOGLE_CLOUD_PROJECT?.trim() || process.env.GCLOUD_PROJECT?.trim();
+    const location = process.env.GOOGLE_CLOUD_LOCATION?.trim();
+    return !!project && !!location;
+}
+export function modelCanAuthenticate(config, model) {
+    if (model.provider === "google-vertex")
+        return resolveModelApiKey(config, model) !== undefined || hasVertexAdcEnvironment();
+    return !requiresExplicitApiKey(config, model);
+}
+export function assertModelCanAuthenticate(config, model) {
+    if (model.provider === "google-vertex") {
+        if (resolveModelApiKey(config, model) !== undefined || hasVertexAdcEnvironment())
+            return;
+        throw new Error(`Missing Vertex auth for ${model.provider}/${model.id}: ${describeModelAuth(config, model)}`);
+    }
+    if (requiresExplicitApiKey(config, model)) {
+        throw new Error(`Missing API key for ${model.provider}/${model.id}: ${describeModelAuth(config, model)}`);
+    }
+}
+export function describeModelAuth(config, model) {
+    const configuredEnv = config.models.apiKeyEnvs[`${model.provider}/${model.id}`] ??
+        config.models.apiKeyEnvs[model.provider] ??
+        (model.provider === config.agent.provider ? config.agent.apiKeyEnv : undefined);
+    if (configuredEnv)
+        return configuredEnv;
+    if (model.provider === "google-vertex") {
+        return "set GOOGLE_CLOUD_API_KEY, or use Vertex ADC with GOOGLE_CLOUD_PROJECT/GCLOUD_PROJECT and GOOGLE_CLOUD_LOCATION";
+    }
+    const envKeys = findEnvKeys(model.provider);
+    if (envKeys?.length)
+        return envKeys.join(", ");
+    return "no matching API key environment variable found";
+}
+export function isAllowedModel(config, ref) {
+    return config.models.allow.length === 0 || config.models.allow.includes(ref.key);
+}
+export function formatAllowedModels(config) {
+    return config.models.allow.length > 0 ? config.models.allow.join("\n") : "(no allowlist configured)";
+}
+export function clampConfiguredThinkingLevel(model, level) {
+    if (level === "off")
+        return "off";
+    return clampThinkingLevel(model, level);
+}
+export function isThinkingLevel(value) {
+    return (value === "off" ||
+        value === "minimal" ||
+        value === "low" ||
+        value === "medium" ||
+        value === "high" ||
+        value === "xhigh");
+}
+export function supportedThinkingLevels(model) {
+    return model.reasoning ? ["off", "minimal", "low", "medium", "high", "xhigh"] : ["off"];
+}

package/dist/persona.js

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises";
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function readOptionalPersonaFile(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return null;
+        throw error;
+    }
+}
+export async function loadPersona(config) {
+    const [soul, user, memory, inner] = await Promise.all([
+        readFile(config.persona.soul, "utf8"),
+        readFile(config.persona.user, "utf8"),
+        readFile(config.persona.memory, "utf8"),
+        readOptionalPersonaFile(config.persona.inner),
+    ]);
+    return { soul, user, memory, inner };
+}
+function renderSystemPromptFile(file) {
+    return `<file name="${file.name}">
+${file.contents.trim()}
+</file>`;
+}
+export function buildSystemPrompt(persona, skillsBlock = "") {
+    const files = [
+        { name: "SOUL.md", contents: persona.soul },
+        { name: "USER.md", contents: persona.user },
+        { name: "MEMORY.md", contents: persona.memory },
+        ...(persona.inner !== null ? [{ name: "INNER.md", contents: persona.inner }] : []),
+    ];
+    const renderedFiles = files.map(renderSystemPromptFile).join("\n\n");
+    const renderedSkillsBlock = skillsBlock.trim() ? `\n\n${skillsBlock.trim()}` : "";
+    return `<system-reminder>
+${renderedFiles}
+
+<note_to_self>
+you can edit MEMORY.md when something about her is worth keeping.
+output [[FAMILIAR_SILENT]] if there's nothing worth saying — quiet's a real choice.
+</note_to_self>
+${renderedSkillsBlock}
+</system-reminder>`;
+}
+const NAME_FIELD_RE = /^\s*[-*]?\s*\*\*Name:\*\*\s*(.+?)\s*$/im;
+export function parsePersonaName(soul, fallback = "Familiar") {
+    const match = soul.match(NAME_FIELD_RE);
+    if (!match)
+        return fallback;
+    return match[1].replace(/^["'`*_]+|["'`*_]+$/g, "").trim() || fallback;
+}