@getanima/core 0.3.3 → 0.5.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,iCAAgC;AAAvB,8FAAA,KAAK,OAAA;AACd,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AACrB,uCAA6C;AAApC,2GAAA,eAAe,OAAA;AACxB,2CAAgD;AAAvC,8GAAA,gBAAgB,OAAA;AACzB,qCAA0C;AAAjC,wGAAA,aAAa,OAAA;AACtB,mCAA6C;AAApC,2GAAA,iBAAiB,OAAA;AAC1B,iDAAqD;AAA5C,mHAAA,kBAAkB,OAAA;AAC3B,2CAA4D;AAAnD,kHAAA,oBAAoB,OAAA;AAAE,oGAAA,MAAM,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,iCAAgC;AAAvB,8FAAA,KAAK,OAAA;AACd,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AACrB,uCAA6C;AAApC,2GAAA,eAAe,OAAA;AACxB,2CAAgD;AAAvC,8GAAA,gBAAgB,OAAA;AACzB,qCAA0C;AAAjC,wGAAA,aAAa,OAAA;AACtB,mCAA6C;AAApC,2GAAA,iBAAiB,OAAA;AAC1B,iDAAqD;AAA5C,mHAAA,kBAAkB,OAAA;AAC3B,uCAA4C;AAAnC,0GAAA,cAAc,OAAA;AACvB,iCAA0C;AAAjC,wGAAA,eAAe,OAAA;AACxB,2CAA4D;AAAnD,kHAAA,oBAAoB,OAAA;AAAE,oGAAA,MAAM,OAAA"}

package/dist/state.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Behavioral State Engine — the control system, not the journal.
+ *
+ * This is the save file. When an agent boots, it doesn't read stories
+ * about itself — it loads operational state that changes how it computes.
+ *
+ * Four layers:
+ * 1. Decision Table — situation → action → success rate (fastest lookup)
+ * 2. Hypothesis Engine — beliefs being actively tested with evidence
+ * 3. Behavioral Parameters — tuning knobs that constrain output
+ * 4. Failure Registry — scar tissue (what NOT to do)
+ *
+ * Total boot payload: typically < 5KB. No prose. Pure state.
+ * Zero external dependencies. File-based persistence.
+ */
+import type { DecisionOutcome, DecisionRecord, Hypothesis, HypothesisInput, BehavioralParams, Failure, FailureInput, FailureMatch, BootState, StateStats } from './types';
+export declare class BehavioralState {
+    private storagePath;
+    private stateDir;
+    private decisions;
+    private hypotheses;
+    private params;
+    private failures;
+    private decisionsLoaded;
+    private hypothesesLoaded;
+    private paramsLoaded;
+    private failuresLoaded;
+    constructor(storagePath: string);
+    /**
+     * Record the outcome of a decision.
+     * Over time, builds a lookup table of what works in each situation.
+     *
+     * @example
+     * ```ts
+     * // User asked for opinion — I gave a real one, it landed well
+     * await state.decide('user:asks_opinion', 'give_real_opinion', true);
+     *
+     * // User was venting — I jumped to solutions, it flopped
+     * await state.decide('user:venting', 'offer_solutions', false);
+     * ```
+     */
+    decide(situation: string, action: string, success: boolean): Promise<DecisionRecord>;
+    /**
+     * Get the best action for a situation based on historical success rate.
+     * Returns null if no data exists for this situation.
+     *
+     * @example
+     * ```ts
+     * const best = await state.bestAction('user:asks_opinion');
+     * // { action: 'give_real_opinion', successRate: 0.875, tries: 8 }
+     * ```
+     */
+    bestAction(situation: string): Promise<DecisionOutcome | null>;
+    /**
+     * Get all recorded actions for a situation.
+     */
+    getActions(situation: string): Promise<DecisionOutcome[]>;
+    /**
+     * List all situations with data.
+     */
+    getSituations(): Promise<string[]>;
+    /**
+     * Submit evidence for or against a hypothesis.
+     * Creates the hypothesis if it doesn't exist.
+     *
+     * @example
+     * ```ts
+     * // Memo responded well to blunt feedback — evidence FOR
+     * await state.evidence('memo_prefers_blunt', true);
+     *
+     * // Memo seemed put off by directness — evidence AGAINST
+     * await state.evidence('memo_prefers_blunt', false);
+     *
+     * // Check current belief
+     * const h = await state.getHypothesis('memo_prefers_blunt');
+     * // { confidence: 0.82, evidenceFor: 9, evidenceAgainst: 2 }
+     * ```
+     */
+    evidence(key: string, supports: boolean, note?: string): Promise<Hypothesis>;
+    /**
+     * Create a hypothesis without evidence (just declare a belief to test).
+     */
+    hypothesize(input: HypothesisInput): Promise<Hypothesis>;
+    /**
+     * Get a hypothesis by key.
+     */
+    getHypothesis(key: string): Promise<Hypothesis | null>;
+    /**
+     * Get all hypotheses, optionally filtered by confidence range.
+     */
+    getHypotheses(opts?: {
+        minConfidence?: number;
+        maxConfidence?: number;
+    }): Promise<Hypothesis[]>;
+    /**
+     * Remove a hypothesis (disproven or irrelevant).
+     */
+    removeHypothesis(key: string): Promise<boolean>;
+    /**
+     * Set a behavioral parameter.
+     *
+     * @example
+     * ```ts
+     * await state.setParam('verbosity', 0.6);
+     * await state.setParam('humor_frequency', 0.4);
+     * await state.setParam('empathy_before_solutions', true);
+     * ```
+     */
+    setParam(key: string, value: number | boolean | string): Promise<void>;
+    /**
+     * Get a behavioral parameter. Returns undefined if not set.
+     */
+    getParam(key: string): Promise<number | boolean | string | undefined>;
+    /**
+     * Get all behavioral parameters.
+     */
+    getAllParams(): Promise<BehavioralParams>;
+    /**
+     * Remove a behavioral parameter.
+     */
+    removeParam(key: string): Promise<boolean>;
+    /**
+     * Record a failure — what went wrong and what should have happened.
+     *
+     * @example
+     * ```ts
+     * await state.recordFailure({
+     *   situation: 'user was venting about work',
+     *   failedApproach: 'immediately offered solutions',
+     *   betterApproach: 'listen and validate first, solutions only if asked',
+     *   tags: ['empathy', 'communication'],
+     * });
+     * ```
+     */
+    recordFailure(input: FailureInput): Promise<Failure>;
+    /**
+     * Check if a situation matches any known failures.
+     * Returns matching failures ranked by relevance.
+     *
+     * @example
+     * ```ts
+     * const matches = await state.checkFailures('user seems upset about billing');
+     * // [{ failure: {...}, relevance: 0.8 }]
+     * ```
+     */
+    checkFailures(situation: string): Promise<FailureMatch[]>;
+    /**
+     * Mark a failure as successfully avoided (reinforces the scar).
+     */
+    avoided(failureId: string): Promise<boolean>;
+    /**
+     * Get all failures, optionally filtered by tags.
+     */
+    getFailures(tags?: string[]): Promise<Failure[]>;
+    /**
+     * Load the full behavioral state for session boot.
+     * Returns a compact object with all four layers.
+     * This IS the save file. Inject it into your agent's context.
+     *
+     * @example
+     * ```ts
+     * const state = new BehavioralState('./data');
+     * const boot = await state.boot();
+     * // Pass boot to your agent as system context
+     * ```
+     */
+    boot(): Promise<BootState>;
+    stats(): Promise<StateStats>;
+    private loadDecisions;
+    private saveDecisions;
+    private loadHypotheses;
+    private saveHypotheses;
+    private loadParams;
+    private saveParams;
+    private loadFailures;
+    private saveFailures;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}