emocentric 0.1.0

package/dist/memory/openai-embedder.d.ts

@@ -0,0 +1,50 @@
+import type { Embedder } from "./store.js";
+export interface OpenAIEmbedderOptions {
+    /** API key. Defaults to process.env.OPENAI_API_KEY. */
+    apiKey?: string;
+    /** Embedding model. Default "text-embedding-3-small". */
+    model?: string;
+    /** Output dimensions. Default 1536 (text-embedding-3-small's native size).
+     * text-embedding-3-* models support shrinking this (e.g. 512) for smaller,
+     * faster vectors at a small quality cost. MUST match the DB column. */
+    dimensions?: number;
+    /** API base URL. Default OpenAI; point it at any OpenAI-compatible
+     * embeddings endpoint (Together, Azure, a local proxy, …). */
+    baseUrl?: string;
+    /** Cosine-relevance floor for recall: results scoring below this on a text
+     * query are dropped as "no real match". Default 0.3 — tune for precision vs
+     * recall. (text-embedding-3 puts genuine matches well above this and
+     * unrelated text below ~0.25, so without a floor every query returns a full
+     * page of low-relevance noise.) */
+    minRelevance?: number;
+    /** Per-attempt request timeout in ms. Default 30_000. */
+    timeoutMs?: number;
+    /** Max retries on transient failures — HTTP 429, HTTP 5xx, and
+     * network/timeout errors. Other 4xx fail fast. Default 2 (up to 3 attempts). */
+    maxRetries?: number;
+    /** Base backoff in ms between retries; doubles each attempt with full jitter,
+     * capped at 8s, and overridden by a server `Retry-After` header. Default 500. */
+    retryBackoffMs?: number;
+}
+/**
+ * Semantic embedder backed by an OpenAI(-compatible) embeddings API. Just an
+ * HTTPS call — no native dependency, so it bundles cleanly everywhere (no
+ * webpack/Next config needed, unlike a local model). Far better recall than a
+ * lexical word-hashing embedder. Needs an API key; cost is tiny (text-embedding-3-small
+ * is ~$0.02 per million tokens). After switching an existing store to this,
+ * run `store.reembedAll({ confirm: true })` once.
+ */
+export declare class OpenAIEmbedder implements Embedder {
+    readonly dimensions: number;
+    readonly minRelevance: number;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryBackoffMs;
+    constructor(options?: OpenAIEmbedderOptions);
+    embed(texts: string[]): Promise<number[][]>;
+    /** Exponential backoff with full jitter, capped at 8s. */
+    private backoffMs;
+}

package/dist/memory/openai-embedder.js

@@ -0,0 +1,124 @@
+/**
+ * Semantic embedder backed by an OpenAI(-compatible) embeddings API. Just an
+ * HTTPS call — no native dependency, so it bundles cleanly everywhere (no
+ * webpack/Next config needed, unlike a local model). Far better recall than a
+ * lexical word-hashing embedder. Needs an API key; cost is tiny (text-embedding-3-small
+ * is ~$0.02 per million tokens). After switching an existing store to this,
+ * run `store.reembedAll({ confirm: true })` once.
+ */
+export class OpenAIEmbedder {
+    dimensions;
+    minRelevance;
+    apiKey;
+    model;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    retryBackoffMs;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error("OpenAIEmbedder needs an `apiKey` (or the OPENAI_API_KEY env var).");
+        }
+        this.apiKey = apiKey;
+        this.model = options.model ?? "text-embedding-3-small";
+        this.dimensions = options.dimensions ?? 1536;
+        this.minRelevance = options.minRelevance ?? 0.3;
+        this.baseUrl = (options.baseUrl ?? "https://api.openai.com/v1").replace(/\/$/, "");
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.retryBackoffMs = options.retryBackoffMs ?? 500;
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const payload = JSON.stringify({
+            model: this.model,
+            input: texts,
+            dimensions: this.dimensions,
+        });
+        // Retry transient failures (429, 5xx, network/timeout) with jittered
+        // backoff; fatal failures (other 4xx) and success return immediately.
+        for (let attempt = 0;; attempt++) {
+            let response;
+            let transientError;
+            let retryAfterMs;
+            try {
+                response = await fetch(`${this.baseUrl}/embeddings`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        authorization: `Bearer ${this.apiKey}`,
+                    },
+                    body: payload,
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+            }
+            catch (error) {
+                // Network failure or AbortSignal timeout — transient, retry.
+                transientError = new Error(`OpenAIEmbedder request failed (network error or >${this.timeoutMs}ms timeout): ` +
+                    (error?.message ?? String(error)), { cause: error });
+            }
+            if (response) {
+                if (response.ok) {
+                    const body = (await response.json());
+                    const data = body.data;
+                    if (!Array.isArray(data) || data.length !== texts.length) {
+                        throw new Error(`OpenAIEmbedder: expected ${texts.length} embedding(s) but got ` +
+                            `${Array.isArray(data) ? data.length : "none"} from "${this.model}".`);
+                    }
+                    // The API preserves input order, but sort by `index` to be safe.
+                    const vectors = data
+                        .slice()
+                        .sort((a, b) => a.index - b.index)
+                        .map((d) => d.embedding);
+                    // Verify the returned length matches what we sized the DB column to.
+                    // OpenRouter forwards the `dimensions` param provider-dependently, so
+                    // some models return their native length instead — catch that here
+                    // with a clear message rather than a cryptic pgvector insert error.
+                    for (const vector of vectors) {
+                        if (!Array.isArray(vector) || vector.length !== this.dimensions) {
+                            throw new Error(`OpenAIEmbedder: model "${this.model}" returned a ` +
+                                `${Array.isArray(vector) ? vector.length : "non-array"}-length ` +
+                                `vector but ${this.dimensions} dimensions were requested. The ` +
+                                "model/provider likely doesn't honor the `dimensions` parameter — " +
+                                "set the embedder's `dimensions` to the model's native size (and " +
+                                "reembedAll if a store already exists).");
+                        }
+                    }
+                    return vectors;
+                }
+                const detail = await response.text().catch(() => "");
+                const error = new Error(`OpenAIEmbedder request failed (${response.status} ${response.statusText}): ${detail.slice(0, 300)}`);
+                // 429 (rate limit) and 5xx are transient; other 4xx won't succeed on retry.
+                if (response.status !== 429 && response.status < 500)
+                    throw error;
+                transientError = error;
+                retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+            }
+            if (attempt >= this.maxRetries)
+                throw transientError;
+            await delay(retryAfterMs ?? this.backoffMs(attempt));
+        }
+    }
+    /** Exponential backoff with full jitter, capped at 8s. */
+    backoffMs(attempt) {
+        const base = this.retryBackoffMs * 2 ** attempt;
+        return Math.random() * Math.min(base, 8_000);
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Parse a `Retry-After` header (delta-seconds or HTTP-date) → ms, capped at 20s. */
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.min(Math.max(0, seconds) * 1000, 20_000);
+    const date = Date.parse(value);
+    if (!Number.isNaN(date))
+        return Math.min(Math.max(0, date - Date.now()), 20_000);
+    return undefined;
+}

package/dist/memory/scoring.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared ranking logic so every MemoryStore implementation orders results
+ * the same way. Final score blends three signals:
+ *
+ *   score = w.relevance * relevance     (how well the fact matches the query)
+ *         + w.importance * importance   (how much the fact matters)
+ *         + w.recency * recency         (exponential decay by age)
+ *
+ * Relevance comes from the store's search (vector cosine similarity);
+ * importance is stored on the fact; recency is computed here with a
+ * configurable half-life.
+ */
+export interface ScoringWeights {
+    relevance: number;
+    importance: number;
+    recency: number;
+    /** Age at which the recency signal halves. */
+    recencyHalfLifeDays: number;
+}
+export declare const DEFAULT_SCORING_WEIGHTS: ScoringWeights;
+/** 1.0 for a brand-new fact, 0.5 after one half-life, → 0 over time. */
+export declare function recencyScore(createdAt: string, halfLifeDays: number, now?: number): number;
+export declare function blendScore(relevance: number, importance: number, createdAt: string, weights?: ScoringWeights, now?: number): number;
+export declare function clamp01(n: number): number;

package/dist/memory/scoring.js

@@ -0,0 +1,20 @@
+export const DEFAULT_SCORING_WEIGHTS = {
+    relevance: 0.65,
+    importance: 0.2,
+    recency: 0.15,
+    recencyHalfLifeDays: 30,
+};
+const MS_PER_DAY = 86_400_000;
+/** 1.0 for a brand-new fact, 0.5 after one half-life, → 0 over time. */
+export function recencyScore(createdAt, halfLifeDays, now = Date.now()) {
+    const ageMs = Math.max(0, now - Date.parse(createdAt));
+    return Math.pow(0.5, ageMs / (halfLifeDays * MS_PER_DAY));
+}
+export function blendScore(relevance, importance, createdAt, weights = DEFAULT_SCORING_WEIGHTS, now = Date.now()) {
+    return (weights.relevance * clamp01(relevance) +
+        weights.importance * clamp01(importance) +
+        weights.recency * recencyScore(createdAt, weights.recencyHalfLifeDays, now));
+}
+export function clamp01(n) {
+    return n < 0 ? 0 : n > 1 ? 1 : n;
+}

package/dist/memory/store.d.ts

@@ -0,0 +1,79 @@
+import type { Fact, FactInput, FactKind, FactPatch } from "./fact.js";
+/** A retrieval request, usually built by the recaller from the
+ * interpreter's description of the payload. */
+export interface MemoryQuery {
+    /** Free-text search query. When empty, stores rank purely by
+     * importance + recency (useful for "what's been on my mind lately"). */
+    text: string;
+    /** Restrict to these kinds. Omit for all kinds. */
+    kinds?: FactKind[];
+    /** Restrict to facts about this subject (e.g. the current actor). */
+    subjectId?: string;
+    /** Max results. Omit to let the store's retrieval strategy decide; the
+     * default Postgres store returns every text match above its relevance floor
+     * and only applies a default cap to no-text browse queries. */
+    limit?: number;
+    /** Drop results whose blended score is below this (0..1). */
+    minScore?: number;
+    /** Drop results whose raw search relevance (cosine) is below this. Overrides
+     * the store and embedder defaults. Only affects text queries. */
+    minRelevance?: number;
+    /** Include facts that have been superseded. Defaults to false. */
+    includeSuperseded?: boolean;
+}
+/** A fetch result: the fact plus how it ranked. */
+export interface ScoredFact {
+    fact: Fact;
+    /** Blended score (relevance + importance + recency), 0..1. */
+    score: number;
+    /** Pure search relevance before blending, 0..1. */
+    relevance: number;
+}
+/**
+ * The persistence boundary of the SDK — the ONLY surface the rest of the
+ * framework uses to touch memory. The recaller calls `fetch`, the writer
+ * calls `add`/`update`; nothing else reaches into storage. Rewriting the
+ * entire memory backend (different database, different retrieval strategy,
+ * a remote service) means implementing these five methods and handing the
+ * new store to the agent — no other code changes.
+ *
+ * Implementations must:
+ * - exclude superseded facts from fetch unless asked otherwise
+ * - return fetch results ordered by descending score
+ * - treat the store as scoped to one agent (multi-tenant backends take the
+ *   agent id at construction time, not per call)
+ */
+export interface MemoryStore {
+    /** Persist new facts. Generates ids/timestamps when absent and returns
+     * the stored facts. */
+    add(facts: FactInput[]): Promise<Fact[]>;
+    /** Search memory. This is the recaller's primitive. */
+    fetch(query: MemoryQuery): Promise<ScoredFact[]>;
+    /** Look up one fact by id, superseded or not. */
+    get(id: string): Promise<Fact | null>;
+    /** Patch a fact (the writer uses this to mark facts superseded).
+     * Returns the updated fact, or null if the id doesn't exist. */
+    update(id: string, patch: FactPatch): Promise<Fact | null>;
+    /** Permanently remove a fact. Returns whether it existed. */
+    delete(id: string): Promise<boolean>;
+    /** Release connections/resources, for stores that own any. */
+    close?(): Promise<void>;
+}
+/**
+ * Turns text into fixed-length vectors for similarity search. Swappable: the
+ * SDK defaults to OpenAIEmbedder (an API embedder); plug in another (e.g. a
+ * local model, or a different provider) by implementing these two members.
+ */
+export interface Embedder {
+    /** Vector length this embedder produces — used to size DB columns. */
+    readonly dimensions: number;
+    /** Recommended cosine-relevance floor for this embedder: results scoring
+     * below it on a text query are treated as "no real match" and dropped. A
+     * lexical embedder scores 0 on no overlap (floor 0 is enough); a semantic
+     * embedder scores a small positive value even for unrelated text, so it
+     * needs a positive floor to avoid returning noise. Optional — omitted is
+     * treated as 0 (drop only ≤ 0). The store and per-query options override it. */
+    readonly minRelevance?: number;
+    /** Embed a batch of texts, one vector per text, same order. */
+    embed(texts: string[]): Promise<number[][]>;
+}

package/dist/memory/store.js

@@ -0,0 +1 @@
+export {};

package/dist/openrouter/client.d.ts

@@ -0,0 +1,27 @@
+import type { LLMClient, LLMRequest, LLMResponse } from "../llm/types.js";
+export interface OpenRouterClientOptions {
+    /** Model id on OpenRouter, e.g. "anthropic/claude-sonnet-4.6",
+     * "openai/gpt-5.2", "google/gemini-3-pro" — the developer's choice. */
+    model: string;
+    /** Defaults to process.env.OPENROUTER_API_KEY. */
+    apiKey?: string;
+    /** Default 4096. */
+    defaultMaxTokens?: number;
+    baseUrl?: string;
+    /** Optional OpenRouter attribution headers (shown on their dashboard). */
+    appUrl?: string;
+    appName?: string;
+    /** Abort requests after this many ms. Default 120_000. */
+    timeoutMs?: number;
+}
+/**
+ * LLMClient backed by OpenRouter's OpenAI-compatible chat completions API.
+ * One client = one model; run several models by creating several clients.
+ * Plain fetch, no SDK dependency, works in any runtime with `fetch`.
+ */
+export declare class OpenRouterClient implements LLMClient {
+    private readonly options;
+    private readonly apiKey;
+    constructor(options: OpenRouterClientOptions);
+    complete(request: LLMRequest): Promise<LLMResponse>;
+}

package/dist/openrouter/client.js

@@ -0,0 +1,118 @@
+/**
+ * LLMClient backed by OpenRouter's OpenAI-compatible chat completions API.
+ * One client = one model; run several models by creating several clients.
+ * Plain fetch, no SDK dependency, works in any runtime with `fetch`.
+ */
+export class OpenRouterClient {
+    options;
+    apiKey;
+    constructor(options) {
+        const apiKey = options.apiKey ?? process.env.OPENROUTER_API_KEY;
+        if (!apiKey) {
+            throw new Error("OpenRouterClient needs an apiKey (or OPENROUTER_API_KEY env var).");
+        }
+        this.apiKey = apiKey;
+        this.options = {
+            defaultMaxTokens: 4096,
+            baseUrl: "https://openrouter.ai/api/v1",
+            timeoutMs: 120_000,
+            ...options,
+        };
+    }
+    async complete(request) {
+        const messages = [];
+        if (request.system) {
+            messages.push({ role: "system", content: request.system });
+        }
+        for (const message of request.messages) {
+            messages.push({
+                role: message.role,
+                content: message.content.map(toOpenAIContent),
+            });
+        }
+        const body = {
+            model: this.options.model,
+            max_tokens: request.maxTokens ?? this.options.defaultMaxTokens,
+            messages,
+        };
+        if (request.jsonSchema) {
+            body.response_format = {
+                type: "json_schema",
+                json_schema: {
+                    name: request.jsonSchema.name,
+                    strict: true,
+                    schema: request.jsonSchema.schema,
+                },
+            };
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+        };
+        if (this.options.appUrl)
+            headers["HTTP-Referer"] = this.options.appUrl;
+        if (this.options.appName)
+            headers["X-Title"] = this.options.appName;
+        const response = await fetch(`${this.options.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.options.timeoutMs),
+        });
+        const payload = (await response.json().catch(() => ({})));
+        if (!response.ok) {
+            throw new Error(`OpenRouter request failed (${response.status} ${response.statusText}): ` +
+                (payload.error?.message ?? "no error detail"));
+        }
+        const choice = payload.choices?.[0];
+        const content = choice?.message?.content;
+        const text = typeof content === "string"
+            ? content
+            : Array.isArray(content)
+                ? content
+                    .filter((part) => part.type === "text" || part.text !== undefined)
+                    .map((part) => part.text ?? "")
+                    .join("")
+                : "";
+        // Empty transport output is a failure, not a "calm" response — surface
+        // it loudly with whatever diagnostics the provider gave us, instead of
+        // letting an empty string cascade into silent no-ops downstream.
+        if (text.trim() === "") {
+            const reasoningLen = typeof choice?.message?.reasoning === "string"
+                ? choice.message.reasoning.length
+                : 0;
+            throw new Error(`OpenRouter returned an empty completion (model ${this.options.model}, ` +
+                `finish_reason: ${choice?.finish_reason ?? "?"} / ${choice?.native_finish_reason ?? "?"}, ` +
+                `reasoning chars: ${reasoningLen}). ` +
+                "If finish_reason is 'length', raise maxTokens; if reasoning consumed the budget, " +
+                "disable/limit reasoning for this model or pick a non-reasoning model.");
+        }
+        return { text };
+    }
+}
+function toOpenAIContent(content) {
+    if (content.type === "text") {
+        return { type: "text", text: content.text };
+    }
+    return { type: "image_url", image_url: { url: mediaToUrl(content.source) } };
+}
+function mediaToUrl(source) {
+    switch (source.type) {
+        case "url":
+            return source.url;
+        case "base64":
+            return `data:${source.mimeType};base64,${source.data}`;
+        case "bytes":
+            return `data:${source.mimeType};base64,${bytesToBase64(source.data)}`;
+    }
+}
+function bytesToBase64(bytes) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes).toString("base64");
+    }
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary);
+}

package/dist/openrouter/index.d.ts

@@ -0,0 +1 @@
+export { OpenRouterClient, type OpenRouterClientOptions } from "./client.js";

package/dist/openrouter/index.js

@@ -0,0 +1 @@
+export { OpenRouterClient } from "./client.js";

package/dist/pipeline/actor.d.ts

@@ -0,0 +1,31 @@
+import type { ActionExecution, ActionPlan } from "../actions/action.js";
+/** Input to the act stage: the plan the processor chose. */
+export interface ActInput {
+    plan: ActionPlan;
+}
+/**
+ * A receipt of what the agent actually did — one entry per executed action,
+ * carrying whatever that action returned (e.g. the message text actually
+ * sent). This is the record the consolidation stage reads to remember the
+ * agent's own actions.
+ */
+export interface ActResult {
+    executions: ActionExecution[];
+}
+/**
+ * Carries out a chosen plan and records what happened. One method — swap in a
+ * dry-run actor (records intentions, no side effects), a rate-limited actor,
+ * etc., and the rest of the SDK is unchanged.
+ */
+export interface Actor {
+    act(input: ActInput): Promise<ActResult>;
+}
+/**
+ * Default actor: runs the plan's actions in order (via each action's
+ * developer-supplied `act`), isolating per-action errors, and returns the
+ * executions. The SDK names no execution model — the action implementations
+ * the developer registered do the work and bring their own.
+ */
+export declare class DefaultActor implements Actor {
+    act(input: ActInput): Promise<ActResult>;
+}

package/dist/pipeline/actor.js

@@ -0,0 +1,11 @@
+/**
+ * Default actor: runs the plan's actions in order (via each action's
+ * developer-supplied `act`), isolating per-action errors, and returns the
+ * executions. The SDK names no execution model — the action implementations
+ * the developer registered do the work and bring their own.
+ */
+export class DefaultActor {
+    async act(input) {
+        return { executions: await input.plan.execute() };
+    }
+}

package/dist/pipeline/appraiser.d.ts

@@ -0,0 +1,55 @@
+import type { ContextEvent } from "../events/context-event.js";
+import type { Fact } from "../memory/fact.js";
+import type { EmotionDelta, EmotionSnapshot } from "../emotion/definitions.js";
+import type { Persona } from "../emotion/persona.js";
+import { type EmotionalState } from "../emotion/state.js";
+import type { LLMClient } from "../llm/types.js";
+export interface AppraisalInput {
+    event: ContextEvent;
+    /** The interpret/recall loop's final, memory-grounded description. */
+    description: string;
+    /** The memories that grounded it (pass `result.memories.map(m => m.fact)`). */
+    memories: Fact[];
+    state: EmotionalState;
+    /** Summary + dispositions go into the prompt so judgment is in character. */
+    persona?: Persona;
+    /** Default true. False = dry run: deltas + projected `after`, state untouched. */
+    apply?: boolean;
+}
+export interface AppraisalResult {
+    /** Raw appraised deltas (-1..+1, pre-sensitivity), unknown emotions dropped. */
+    deltas: EmotionDelta[];
+    before: EmotionSnapshot;
+    /** Real new state when applied; projected state on a dry run. */
+    after: EmotionSnapshot;
+    applied: boolean;
+}
+/**
+ * Decides how an event moves the agent's feelings. One method — implement
+ * it differently (rules, appraisal theory, a fine-tuned model) and the rest
+ * of the SDK keeps working.
+ */
+export interface Appraiser {
+    appraise(input: AppraisalInput): Promise<AppraisalResult>;
+}
+export interface LLMAppraiserOptions {
+    llm: LLMClient;
+    maxTokens?: number;
+}
+/**
+ * Default appraiser: one LLM call that reads the persona (summary +
+ * dispositions), every emotion's description and current value, the event
+ * description, and the recalled memories — and returns per-emotion deltas
+ * with reasons.
+ */
+export declare class LLMAppraiser implements Appraiser {
+    private readonly options;
+    constructor(options: LLMAppraiserOptions);
+    appraise(input: AppraisalInput): Promise<AppraisalResult>;
+    private systemPrompt;
+    private userPrompt;
+}
+/** Tolerant parse of appraisal output: extracts JSON from prose, drops
+ * deltas for emotions outside the palette, clamps deltas to [-1, 1].
+ * Unparseable output yields an empty delta list (a calm non-reaction). */
+export declare function parseDeltas(text: string, knownEmotions: ReadonlySet<string>): EmotionDelta[];