emocentric 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Resonance Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# Emocentric
+
+A cross-platform, emotionally-driven agentic framework. Emocentric agents
+don't just respond to events — they **feel** their way through them:
+persistent emotions shape how an agent interprets what it sees, what it
+remembers, and what it chooses to do.
+
+## Blueprints and instances
+
+An agent is a **blueprint**, not a being: a serializable definition of who
+the character is — persona, emotion palette, action menu, and the memories
+it starts life with. Nobody talks to a blueprint. Each user gets their own
+**instance** of it, born on first contact with the blueprint's starting
+emotions and seed memories, and diverging from there. Two users of the same
+blueprint share nothing: separate feelings, separate memories.
+
+Instances are keyed by `(blueprintId, userId)` — with a `sessionId` slot
+reserved for the future case of several people sharing one instance.
+
+## The pipeline
+
+Every incoming event (a chat message, a photo, a game action) runs one
+heartbeat:
+
+```
+ContextEvent (you build this from your platform's event)
+   │
+   ▼
+1. time appraisal        feelings drift toward baseline for the time
+   │                     since last contact (math today, LLM-ready)
+   ▼
+2. interpret/recall      describe the event → search memory → look again
+   │                     with memories in hand, until nothing new turns up
+   ▼
+3. event appraisal       one LLM call decides how each emotion moves,
+   │                     in character; applied to persistent state
+   ▼
+4. writer                new facts extracted into memory; contradictions
+   │                     supersede old facts (history is kept, not erased)
+   ▼
+5. processor             actions chosen from the CURRENT feelings;
+                         executed only if you allow it
+```
+
+## Quickstart
+
+```ts
+import { createContextEvent, type AgentBlueprint } from "emocentric";
+import { createAgentInstance } from "emocentric/postgres";
+import { OpenRouterClient } from "emocentric/openrouter";
+
+// The blueprint: authored once (eventually in the studio), stored as JSON.
+const blueprint: AgentBlueprint = {
+  id: "lyra",
+  persona: {
+    name: "Lyra",
+    summary: "a warm, observant cellist who remembers the small things",
+    temperament: [{ emotion: "joy", sensitivity: 1.5 }],
+  },
+  actions: [
+    {
+      name: "send_message",
+      description: "Reply to the user. Use when a verbal response fits.",
+      slot: "voice",
+      paramsSchema: { type: "object", properties: { text: { type: "string" } }, required: ["text"] },
+    },
+  ],
+  seedFacts: [
+    { kind: "persona", content: "Lyra grew up in a port town and misses the sea", importance: 0.8 },
+  ],
+};
+
+// This user's private instance — created on first contact, found after.
+const { agent, close } = await createAgentInstance({
+  blueprint,
+  userId: "user-42",
+  llm: new OpenRouterClient({ model: "anthropic/claude-sonnet-4.6" }),
+  executors: {
+    // the platform's side of each blueprint action
+    send_message: (params, ctx) => myPlatform.send(ctx.event.channelId, params.text),
+  },
+  act: true,
+});
+
+// your platform glue: native event → ContextEvent → one call
+const event = createContextEvent({
+  platform: "discord",
+  actor: { id: "user-42", displayName: "Alice" },
+  payload: { kind: "text", text: "Biscuit just learned to fetch!!" },
+});
+
+const result = await agent.handleEvent(event);
+// `result` is the full transcript: time drift, grounded description,
+// emotion deltas with reasons, facts written, actions executed.
+```
+
+Payloads cover text, images, audio/video (via transcripts), platform
+actions (game moves, button presses), and composites of those.
+
+Instance management lives in `emocentric/postgres` too: `listInstances`
+(all instances of a blueprint, or everything a user owns) and
+`deleteInstance` (erase one user's memories, feelings, and directory row).
+
+## Setup
+
+```sh
+npm install
+docker compose up -d          # local Postgres (pgvector) — schema auto-creates
+cp .env.example .env          # add your OPENROUTER_API_KEY
+npm test                      # 110+ tests; DB/live tests skip when unconfigured
+npm run demo                  # one event through the full pipeline, with receipts
+```
+
+**Production:** provision PostgreSQL on Railway (pgvector included), hand the
+app its `DATABASE_URL`. Tables create themselves on first connect.
+
+## Design principles
+
+- **A blueprint is a recipe, not a being.** What the character *is* lives in
+  one JSON document; what each instance *has lived* stays in the database.
+  Seed facts are copied at birth — editing a blueprint affects only new
+  instances.
+- **Everything is swappable.** Memory is a 5-method interface, emotional
+  state is 5 methods, each pipeline stage is 1 method, the LLM is 1 method.
+  Rewrite any layer without touching the others; the shipped defaults are
+  just defaults. (`createAgentInstance` is itself just a convenience over
+  `new Agent(...)` with scoped stores.)
+- **LLM-agnostic.** All model calls go through OpenRouter — the model is a
+  string you choose, per stage if you like. Or implement `LLMClient` for
+  any provider.
+- **Feelings and memories persist per instance.** Postgres-backed; instances
+  never reset between sessions. One database serves many blueprints and all
+  their instances.
+- **Actions are described in data, executed in code.** The blueprint declares
+  what the agent can do and when (the LLM's menu); your codebase supplies the
+  side effects via `executors`.
+
+## Package layout
+
+| Import | Contents |
+|---|---|
+| `emocentric` | core: events, blueprints/scopes, memory/emotion/LLM interfaces, pipeline stages, `Agent` |
+| `emocentric/postgres` | `createAgentInstance`, `PostgresMemoryStore`, `PostgresEmotionalState`, instance directory (Node-only) |
+| `emocentric/openrouter` | `OpenRouterClient` |

package/dist/actions/action.d.ts

@@ -0,0 +1,70 @@
+import type { ContextEvent } from "../events/context-event.js";
+import type { Fact } from "../memory/fact.js";
+import type { EmotionSnapshot } from "../emotion/definitions.js";
+import type { Persona } from "../emotion/persona.js";
+/** Everything an action implementation gets to work with when it runs —
+ * including the platform-native `event.raw` (reply tokens, channel handles)
+ * and the agent's current feelings. */
+export interface ActionContext {
+    event: ContextEvent;
+    description: string;
+    memories: Fact[];
+    emotions: EmotionSnapshot;
+    persona?: Persona;
+}
+/**
+ * One thing the agent can do, defined by the developer in code.
+ *
+ * - `description` is written for the LLM: what it does AND when to use it.
+ * - `slot` groups mutually exclusive actions — at most one action per slot
+ *   makes it into a plan. No slot = combines freely.
+ * - `paramsSchema` (JSON schema) describes the arguments the LLM must fill
+ *   (e.g. the text of a message). Omit for parameter-less actions.
+ * - `act` is the developer's side effect; the SDK never touches platforms
+ *   itself. May return anything (captured in the execution report).
+ */
+export interface ActionDefinition {
+    name: string;
+    description: string;
+    slot?: string;
+    paramsSchema?: Record<string, unknown>;
+    act(params: Record<string, unknown>, context: ActionContext): Promise<unknown> | unknown;
+}
+/** An action the processor chose, with the LLM-filled params. Carries the
+ * real definition, so `planned.action.act(...)` is directly callable. */
+export interface PlannedAction {
+    action: ActionDefinition;
+    params: Record<string, unknown>;
+    reason?: string;
+}
+/** Outcome of running one planned action. */
+export interface ActionExecution {
+    name: string;
+    params: Record<string, unknown>;
+    status: "succeeded" | "failed";
+    result?: unknown;
+    error?: string;
+}
+/**
+ * The processor's output: slot-enforced chosen actions plus a record of
+ * what got dropped and why. `execute()` runs the plan (in order, errors
+ * isolated per action) — call it yourself when the processor ran with
+ * `act: false`.
+ */
+export declare class ActionPlan {
+    /** Accepted actions, in the LLM's chosen order, at most one per slot. */
+    readonly actions: PlannedAction[];
+    /** Valid actions dropped because their slot was already taken. */
+    readonly droppedConflicts: PlannedAction[];
+    /** Names the LLM picked that don't exist in the registry. */
+    readonly unknownActions: string[];
+    private readonly context;
+    constructor(
+    /** Accepted actions, in the LLM's chosen order, at most one per slot. */
+    actions: PlannedAction[], 
+    /** Valid actions dropped because their slot was already taken. */
+    droppedConflicts: PlannedAction[], 
+    /** Names the LLM picked that don't exist in the registry. */
+    unknownActions: string[], context: ActionContext);
+    execute(): Promise<ActionExecution[]>;
+}

package/dist/actions/action.js

@@ -0,0 +1,47 @@
+/**
+ * The processor's output: slot-enforced chosen actions plus a record of
+ * what got dropped and why. `execute()` runs the plan (in order, errors
+ * isolated per action) — call it yourself when the processor ran with
+ * `act: false`.
+ */
+export class ActionPlan {
+    actions;
+    droppedConflicts;
+    unknownActions;
+    context;
+    constructor(
+    /** Accepted actions, in the LLM's chosen order, at most one per slot. */
+    actions, 
+    /** Valid actions dropped because their slot was already taken. */
+    droppedConflicts, 
+    /** Names the LLM picked that don't exist in the registry. */
+    unknownActions, context) {
+        this.actions = actions;
+        this.droppedConflicts = droppedConflicts;
+        this.unknownActions = unknownActions;
+        this.context = context;
+    }
+    async execute() {
+        const executions = [];
+        for (const planned of this.actions) {
+            try {
+                const result = await planned.action.act(planned.params, this.context);
+                executions.push({
+                    name: planned.action.name,
+                    params: planned.params,
+                    status: "succeeded",
+                    ...(result !== undefined && { result }),
+                });
+            }
+            catch (error) {
+                executions.push({
+                    name: planned.action.name,
+                    params: planned.params,
+                    status: "failed",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return executions;
+    }
+}

package/dist/actions/index.d.ts

@@ -0,0 +1,2 @@
+export { ActionPlan, type ActionContext, type ActionDefinition, type ActionExecution, type PlannedAction, } from "./action.js";
+export { ActionRegistry } from "./registry.js";

package/dist/actions/index.js

@@ -0,0 +1,2 @@
+export { ActionPlan, } from "./action.js";
+export { ActionRegistry } from "./registry.js";

package/dist/actions/registry.d.ts

@@ -0,0 +1,12 @@
+import type { ActionDefinition } from "./action.js";
+/**
+ * The agent's menu of possible actions. Built in code at startup (actions
+ * are behavior, not data — they live in your codebase, not the database).
+ */
+export declare class ActionRegistry {
+    private readonly actions;
+    register(action: ActionDefinition): this;
+    get(name: string): ActionDefinition | undefined;
+    list(): ActionDefinition[];
+    get size(): number;
+}

package/dist/actions/registry.js

@@ -0,0 +1,26 @@
+/**
+ * The agent's menu of possible actions. Built in code at startup (actions
+ * are behavior, not data — they live in your codebase, not the database).
+ */
+export class ActionRegistry {
+    actions = new Map();
+    register(action) {
+        if (!action.name || action.name.trim() === "") {
+            throw new Error("Action name must be a non-empty string.");
+        }
+        if (this.actions.has(action.name)) {
+            throw new Error(`Action "${action.name}" is already registered.`);
+        }
+        this.actions.set(action.name, action);
+        return this;
+    }
+    get(name) {
+        return this.actions.get(name);
+    }
+    list() {
+        return [...this.actions.values()];
+    }
+    get size() {
+        return this.actions.size;
+    }
+}

package/dist/agent.d.ts

@@ -0,0 +1,141 @@
+import type { ContextEvent } from "./events/context-event.js";
+import type { MemoryStore } from "./memory/store.js";
+import { type Engagement, type ShortTermMemory } from "./short-term/short-term.js";
+import type { EmotionalState } from "./emotion/state.js";
+import type { Persona } from "./emotion/persona.js";
+import type { LLMClient } from "./llm/types.js";
+import { ActionRegistry } from "./actions/registry.js";
+import type { Interpreter } from "./pipeline/interpretation.js";
+import { type Recaller } from "./pipeline/recaller.js";
+import { InterpretRecallLoop, type InterpretRecallResult } from "./pipeline/loop.js";
+import { type AppraisalResult, type Appraiser } from "./pipeline/appraiser.js";
+import { type TimeAppraisalResult, type TimeAppraiser } from "./pipeline/time-appraiser.js";
+import { type WriteResult, type Writer } from "./pipeline/writer.js";
+import { type ProcessResult, type Processor } from "./pipeline/processor.js";
+import { type ActResult, type Actor } from "./pipeline/actor.js";
+import { type Consolidator } from "./pipeline/consolidator.js";
+import { type EnqueueOutcome } from "./pipeline/inbox.js";
+export interface AgentOptions {
+    /** Used to build every default stage. Override stages individually to
+     * use different models per stage. */
+    llm: LLMClient;
+    memory: MemoryStore;
+    /** The agent's short-term window of recent engagements — fed to the
+     * interpreter and processor for immediate conversational context. Defaults
+     * to a process-local {@link InMemoryShortTermMemory}; pass a persistent one
+     * to keep the window across sessions. */
+    shortTermMemory?: ShortTermMemory;
+    emotions: EmotionalState;
+    /** The action menu. Omit (or leave empty) for an agent that only
+     * perceives, feels, and remembers — the processor stage is skipped. */
+    actions?: ActionRegistry;
+    persona?: Persona;
+    timeAppraiser?: TimeAppraiser;
+    interpreter?: Interpreter;
+    recaller?: Recaller;
+    /** Supersedes `interpreter`/`recaller` if provided (a loop already
+     * contains both). */
+    loop?: InterpretRecallLoop;
+    appraiser?: Appraiser;
+    writer?: Writer;
+    processor?: Processor;
+    /** Runs the chosen plan and records what the agent did. Defaults to
+     * {@link DefaultActor}, which executes via the actions' own `act` handlers. */
+    actor?: Actor;
+    /** Writes memory from the agent's own actions (e.g. "I met Bill" → remember
+     * meeting Bill). Defaults to {@link LLMConsolidator}. */
+    consolidator?: Consolidator;
+    /** Max interpreter LLM calls per event (default 3). Ignored when a
+     * custom `loop` is provided. */
+    maxLoopIterations?: number;
+}
+export interface HandleEventOptions {
+    /** Cancellation for the coalescing inbox. When it aborts before the
+     * appraisal commits, the heartbeat throws {@link HeartbeatCancelled} at its
+     * next stage boundary. Set by `enqueue`; omit for a plain, uninterruptible
+     * run. */
+    signal?: AbortSignal;
+    /** Called synchronously the instant the heartbeat passes its last
+     * cancellable point (just before feelings persist). Set by `enqueue`. */
+    onCommit?: () => void;
+}
+/** The full transcript of one heartbeat — every stage's receipt. Log this
+ * and you can replay exactly why the agent felt and did what it did. */
+export interface AgentResult {
+    event: ContextEvent;
+    /** The short-term window the agent walked in with — the recent engagements
+     * the interpreter and processor reasoned over (this event not yet added). */
+    shortTerm: Engagement[];
+    time: TimeAppraisalResult;
+    interpretation: InterpretRecallResult;
+    appraisal: AppraisalResult;
+    memory: WriteResult;
+    actions: ProcessResult;
+    /** What the agent actually did — the executed plan's outcomes. */
+    acted: ActResult;
+    /** Memory written from the agent's own actions this turn. */
+    consolidation: WriteResult;
+}
+export type AgentStage = "time-appraisal" | "interpretation" | "appraisal" | "write" | "process" | "act" | "consolidate";
+/** Wraps a stage failure with which stage broke; the original error is on
+ * `cause`. Bad LLM *output* never raises this (stages degrade to no-ops) —
+ * this is for genuine failures: LLM outage, database down, bugs. */
+export declare class AgentError extends Error {
+    readonly stage: AgentStage;
+    constructor(stage: AgentStage, cause: unknown);
+}
+/**
+ * The orchestrator: wires the six pipeline stages into one call.
+ *
+ *   handleEvent(event):
+ *     1. time appraisal      feelings drift for the time since last contact
+ *     2. interpret/recall    understand the event, grounded in memories
+ *     3. event appraisal     feelings respond (persisted)
+ *     4. writer              new facts filed, contradictions superseded
+ *     5. processor           actions chosen in-feeling; plan returned, never
+ *                            executed — the caller runs plan.execute()
+ *
+ * Every stage is the shipped default unless overridden in options, and the
+ * developer-owned pieces (memory, emotions, actions, persona, LLM) are
+ * injected — so any layer can be rewritten without touching this class.
+ */
+export declare class Agent {
+    readonly memory: MemoryStore;
+    readonly shortTermMemory: ShortTermMemory;
+    readonly emotions: EmotionalState;
+    readonly actions: ActionRegistry;
+    readonly persona: Persona | undefined;
+    private readonly timeAppraiser;
+    private readonly loop;
+    private readonly appraiser;
+    private readonly writer;
+    private readonly processor;
+    private readonly actor;
+    private readonly consolidator;
+    /** Serializes + coalesces events for this agent. enqueue() is the entry;
+     * it drives handleEvent under cancellation. */
+    private readonly inbox;
+    constructor(options: AgentOptions);
+    /**
+     * The production entry point: hand an event to this agent's funnel. Events
+     * for one agent process one at a time; a burst that arrives before the
+     * current heartbeat commits its feelings is merged and run as one. Resolves
+     * to the heartbeat's {@link AgentResult}, or a {@link MergedOutcome} marker
+     * when this event was folded into a later one (do nothing in that case).
+     *
+     * Prefer this over {@link handleEvent} — it is the only path that serializes
+     * and coalesces. handleEvent runs immediately and bypasses both.
+     */
+    enqueue(event: ContextEvent): Promise<EnqueueOutcome<AgentResult>>;
+    /**
+     * Run one heartbeat immediately, bypassing the funnel. Internal: the inbox
+     * calls this under cancellation control. Calling it directly skips
+     * serialization and coalescing — only safe when you guarantee no concurrent
+     * events for this agent. Most callers want {@link enqueue}.
+     */
+    handleEvent(event: ContextEvent, options?: HandleEventOptions): Promise<AgentResult>;
+    /** Record one engagement in short-term memory: what the agent perceived and
+     * the words it actually said back (joined; empty when it stayed silent). */
+    private remember;
+    private stage;
+}