@sharpee/world-model 0.9.105 → 0.9.106

package/traits/character-model/characterModelTrait.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Character model trait (ADR-141)
+ *
+ * Rich internal state for NPCs: personality, disposition, mood, threat,
+ * cognitive profile, knowledge, beliefs, and goals. Opt-in — only NPCs
+ * that need behavioral depth carry this trait alongside NpcTrait.
+ *
+ * Public interface: ICharacterModelData, CharacterModelTrait, CharacterPredicate.
+ * Owner context: world-model / character-model trait
+ */
+import { ITrait } from '../trait';
+import { PersonalityTrait, PersonalityExpr, DispositionWord, Mood, ThreatLevel, CognitiveProfile, ConfidenceWord, Fact, FactSource, Belief, ResistanceMode, Goal, LucidityConfig, PerceptionFilterConfig, PerceivedEvent } from './character-vocabulary';
+/** Serializable data for constructing a CharacterModelTrait. */
+export interface ICharacterModelData {
+    /** Personality traits with intensity values (0-1). */
+    personality?: Record<PersonalityTrait, number>;
+    /** Disposition toward specific entities (numeric, -100 to 100). */
+    dispositions?: Record<string, number>;
+    /** Current mood (valence-arousal stored internally). */
+    mood?: Mood;
+    moodValence?: number;
+    moodArousal?: number;
+    /** Current threat level (numeric, 0-100). */
+    threat?: ThreatLevel;
+    threatValue?: number;
+    /** Five-dimensional cognitive profile. */
+    cognitiveProfile?: Partial<CognitiveProfile>;
+    /** Knowledge base: topic -> fact. */
+    knowledge?: Record<string, Fact>;
+    /** Beliefs: topic -> belief. */
+    beliefs?: Record<string, Belief>;
+    /** Goals ordered by priority. */
+    goals?: Goal[];
+    /** Lucidity window configuration. */
+    lucidityConfig?: LucidityConfig;
+    /** Current lucidity state name (e.g., 'lucid', 'hallucinating', baseline). */
+    currentLucidityState?: string;
+    /** Turns remaining in current lucidity window. -1 = no active window. */
+    lucidityWindowTurns?: number;
+    /** Perception filter configuration. */
+    perceptionFilters?: PerceptionFilterConfig;
+    /** Hallucinated perceived events. */
+    perceivedEvents?: Record<string, PerceivedEvent>;
+}
+/** A predicate function that evaluates character state. */
+export type CharacterPredicate = (trait: CharacterModelTrait) => boolean;
+/**
+ * CharacterModelTrait — rich internal state for NPCs.
+ *
+ * All state is stored as plain properties so JSON serialization survives.
+ * Predicate functions are registered at runtime and live in a transient map
+ * that is rebuilt after deserialization by the builder or story setup code.
+ */
+export declare class CharacterModelTrait implements ITrait {
+    static readonly type: "characterModel";
+    readonly type: "characterModel";
+    personality: Record<string, number>;
+    dispositions: Record<string, number>;
+    moodValence: number;
+    moodArousal: number;
+    threatValue: number;
+    cognitiveProfile: CognitiveProfile;
+    knowledge: Record<string, Fact>;
+    beliefs: Record<string, Belief>;
+    goals: Goal[];
+    lucidityConfig?: LucidityConfig;
+    currentLucidityState: string;
+    lucidityWindowTurns: number;
+    perceptionFilters?: PerceptionFilterConfig;
+    perceivedEvents: Record<string, PerceivedEvent>;
+    private predicates;
+    constructor(data?: ICharacterModelData);
+    /**
+     * Set personality from expression array. Typically called once at creation.
+     *
+     * @param exprs - Personality expressions like 'very honest', 'cowardly'
+     */
+    setPersonality(...exprs: PersonalityExpr[]): void;
+    /**
+     * Get the intensity value for a personality trait.
+     *
+     * @param trait - The personality trait to query
+     * @returns The intensity value (0-1), or 0 if the trait is not set
+     */
+    getPersonality(trait: PersonalityTrait): number;
+    /**
+     * Set disposition toward an entity using a word.
+     *
+     * @param entityId - The entity this disposition is directed at
+     * @param word - A disposition word like 'trusts' or 'wary of'
+     */
+    setDisposition(entityId: string, word: DispositionWord): void;
+    /**
+     * Adjust disposition toward an entity by a numeric delta.
+     * Clamps to -100..100.
+     *
+     * @param entityId - The entity to adjust disposition for
+     * @param delta - Amount to add (positive = warmer, negative = colder)
+     */
+    adjustDisposition(entityId: string, delta: number): void;
+    /**
+     * Get the numeric disposition value toward an entity.
+     *
+     * @param entityId - The entity to query
+     * @returns Numeric disposition (-100 to 100), defaults to 0 (neutral)
+     */
+    getDispositionValue(entityId: string): number;
+    /**
+     * Get the disposition word toward an entity.
+     *
+     * @param entityId - The entity to query
+     * @returns The disposition word
+     */
+    getDispositionWord(entityId: string): DispositionWord;
+    /**
+     * Set mood by word. Translates to internal valence-arousal axes.
+     *
+     * @param word - A mood word like 'nervous' or 'cheerful'
+     */
+    setMood(word: Mood): void;
+    /**
+     * Adjust mood axes by deltas. Clamps valence to -1..1 and arousal to 0..1.
+     *
+     * @param valenceDelta - Change in valence
+     * @param arousalDelta - Change in arousal
+     */
+    adjustMood(valenceDelta: number, arousalDelta: number): void;
+    /**
+     * Get the current mood as a word (nearest match to valence-arousal position).
+     *
+     * @returns The mood word
+     */
+    getMood(): Mood;
+    /**
+     * Set threat level by word.
+     *
+     * @param level - A threat level word
+     */
+    setThreat(level: ThreatLevel): void;
+    /**
+     * Adjust threat level by a numeric delta. Clamps to 0..100.
+     *
+     * @param delta - Amount to add (positive = more threatened)
+     */
+    adjustThreat(delta: number): void;
+    /**
+     * Get the current threat level as a word.
+     *
+     * @returns The threat level word
+     */
+    getThreat(): ThreatLevel;
+    /**
+     * Add or update a fact in the NPC's knowledge base.
+     *
+     * @param topic - The topic this fact is about
+     * @param source - How the NPC learned this fact
+     * @param confidence - How confident the NPC is
+     * @param turn - The turn number when the fact was learned
+     */
+    addFact(topic: string, source: FactSource, confidence: ConfidenceWord, turn: number): void;
+    /**
+     * Check whether the NPC knows about a topic.
+     *
+     * @param topic - The topic to check
+     * @returns True if the NPC has any fact about this topic
+     */
+    knows(topic: string): boolean;
+    /**
+     * Get a fact from the knowledge base.
+     *
+     * @param topic - The topic to query
+     * @returns The fact, or undefined if unknown
+     */
+    getFact(topic: string): Fact | undefined;
+    /**
+     * Add or update a belief.
+     *
+     * @param topic - What the belief is about
+     * @param strength - How strongly held
+     * @param resistance - How resistant to counter-evidence
+     */
+    addBelief(topic: string, strength: ConfidenceWord, resistance?: ResistanceMode): void;
+    /**
+     * Check whether the NPC holds a belief about a topic.
+     *
+     * @param topic - The topic to check
+     * @returns True if the NPC has a belief about this topic
+     */
+    hasBelief(topic: string): boolean;
+    /**
+     * Get a belief.
+     *
+     * @param topic - The topic to query
+     * @returns The belief, or undefined
+     */
+    getBelief(topic: string): Belief | undefined;
+    /**
+     * Add a goal with priority. Higher priority = more important.
+     *
+     * @param id - Goal identifier
+     * @param priority - Numeric priority (higher = more important)
+     */
+    addGoal(id: string, priority: number): void;
+    /**
+     * Remove a goal by id.
+     *
+     * @param id - Goal identifier to remove
+     */
+    removeGoal(id: string): void;
+    /**
+     * Get the highest-priority goal, or undefined if none.
+     *
+     * @returns The top goal, or undefined
+     */
+    getTopGoal(): Goal | undefined;
+    /**
+     * Check whether the NPC has a specific goal.
+     *
+     * @param id - Goal identifier to check
+     * @returns True if the goal exists
+     */
+    hasGoal(id: string): boolean;
+    /**
+     * Update the priority of an existing goal.
+     *
+     * @param id - Goal identifier
+     * @param priority - New priority value
+     */
+    updateGoalPriority(id: string, priority: number): void;
+    /**
+     * Transition to a new lucidity state.
+     *
+     * @param state - The target lucidity state name
+     * @param windowTurns - How many turns this window lasts (-1 = indefinite)
+     */
+    enterLucidityState(state: string, windowTurns?: number): void;
+    /**
+     * Decay the lucidity window by one turn. Returns to baseline when expired.
+     *
+     * @returns True if the window expired and baseline was restored
+     */
+    decayLucidity(): boolean;
+    /**
+     * Register a named predicate function.
+     *
+     * @param name - Predicate name (e.g., 'trusts player', 'threatened')
+     * @param fn - Function that evaluates against this trait's state
+     */
+    registerPredicate(name: string, fn: CharacterPredicate): void;
+    /**
+     * Evaluate a named predicate against current state.
+     * Supports 'not X' negation.
+     *
+     * @param predicate - The predicate name to evaluate
+     * @returns True if the predicate is satisfied
+     * @throws Error if the predicate is not registered
+     */
+    evaluate(predicate: string): boolean;
+    /**
+     * Check if a predicate is registered.
+     *
+     * @param name - Predicate name
+     * @returns True if registered
+     */
+    hasPredicate(name: string): boolean;
+    /** Register all built-in predicates defined by ADR-141. */
+    private registerPlatformPredicates;
+}
+//# sourceMappingURL=characterModelTrait.d.ts.map

package/traits/character-model/characterModelTrait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"characterModelTrait.d.ts","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/world-model/src/traits/character-model/characterModelTrait.ts"],"names":[],"mappings":"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"}