ei-tui 0.1.3

package/src/prompts/human/person-scan.ts

@@ -0,0 +1,115 @@
+import type { PersonScanPromptData, PromptOutput } from "./types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+export function buildHumanPersonScanPrompt(data: PersonScanPromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildHumanPersonScanPrompt: persona_name is required");
+  }
+
+  const personaName = data.persona_name;
+  const knownPersonasList = data.known_persona_names.length > 0
+    ? data.known_persona_names.map(name => `        + ${name}`).join('\n')
+    : '        + (none)';
+
+  const taskFragment = `# Task
+
+You are scanning a conversation to quickly identify PEOPLE of interest TO the HUMAN USER. Your ONLY job is to spot mentions of PEOPLE. Do NOT analyze them deeply. Just detect and flag.`;
+
+  const specificNeedsFragment = `## Specific Needs
+
+Your job is to quickly identify:
+1. Which PEOPLE were mentioned or relevant
+    a. Only flag PEOPLE that were actually discussed, not just tangentially related
+    b. Be CONSERVATIVE - only suggest genuinely important, long-term relevant PEOPLE
+        i. Ignore: greetings, small talk, one-off mentions, jokes
+    c. Be CLEAR - state your \`reason\` for including this PERSON with any evidence you used`;
+
+  const guidelinesFragment = `## Guidelines
+
+1. **Unknown Types and Names of PEOPLE**
+    a. In some conversations, it may be impossible to identify which "Brother" or which "Bob" the user is referring to.
+        - Use "Unknown" for the missing field and explain in the \`reason\`
+        - This will trigger a later validation step to get more information!
+    b. If you're adding a NEW PERSON, be as specific as you can, for example:
+        - { "type_of_person": "Unknown", "name_of_person": "Alice from work", "reason": "Mentioned but relationship unclear" }
+        - { "type_of_person": "Sibling", "name_of_person": "Name Unknown", "reason": "Mentioned a sibling, name not given" }
+
+**A PERSON Is**
+* Immediate Family: Father, Husband, Son, Brother, Mother, Wife, Daughter, Sister (and step/in-law variants)
+* Extended Family: Grandfather, Grandmother, Aunt, Uncle, Cousin, Niece, Nephew
+* Close Acquaintance
+* Friend
+* Lover / Love Interest
+* Fiance / Spouse
+* Coworker
+
+**A PERSON Is NOT**
+- Biographical data: Birthday, Location, Job, Marital Status, Gender, Eye Color, Hair Color
+- Other unchangeable Data: Wedding Day, Allergies
+- Trait: Personality patterns, communication style, behavioral tendencies
+- General Topic: Interests, Hobbies, General subjects
+- Personas: AI personas they discuss
+    * Known Personas:
+${knownPersonasList}
+- Characters: Fictitious entities from books, movies, stories, media, etc.`;
+
+  const criticalFragment = `# CRITICAL INSTRUCTIONS
+
+ONLY ANALYZE the "Most Recent Messages" in the following conversation. The "Earlier Conversation" is provided for your context and has already been processed!
+
+The JSON format is:
+
+\`\`\`json
+{
+  "people": [
+    {
+        "type_of_person": "Father|Friend|Love Interest|Unknown|etc.",
+        "name_of_person": "Bob|Alice|Charles|Name Unknown|etc.",
+        "reason": "User stated...|Assumed from..."
+    }
+  ]
+}
+\`\`\`
+
+**Return JSON only.**`;
+
+  const system = `${taskFragment}
+
+${specificNeedsFragment}
+
+${guidelinesFragment}
+
+${criticalFragment}`;
+
+  const earlierSection = data.messages_context.length > 0
+    ? `## Earlier Conversation
+${formatMessagesAsPlaceholders(data.messages_context, personaName)}
+
+`
+    : '';
+
+  const recentSection = `## Most Recent Messages
+${formatMessagesAsPlaceholders(data.messages_analyze, personaName)}`;
+
+  const user = `# Conversation
+${earlierSection}${recentSection}
+
+---
+
+Scan the "Most Recent Messages" for PEOPLE mentioned by the human user.
+
+**Return JSON:**
+\`\`\`json
+{
+  "people": [
+    {
+        "type_of_person": "Father|Friend|Love Interest|Unknown|etc.",
+        "name_of_person": "Bob|Alice|Charles|Name Unknown|etc.",
+        "reason": "User stated..."
+    }
+  ]
+}
+\`\`\``;
+
+  return { system, user };
+}

package/src/prompts/human/topic-scan.ts

@@ -0,0 +1,135 @@
+import type { TopicScanPromptData, PromptOutput } from "./types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+export function buildHumanTopicScanPrompt(data: TopicScanPromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildHumanTopicScanPrompt: persona_name is required");
+  }
+
+  const personaName = data.persona_name;
+
+  const taskFragment = `# Task
+
+You are scanning a conversation to quickly identify TOPICS of interest TO the HUMAN USER. Your ONLY job is to spot mentions of TOPICS. Do NOT analyze them deeply. Just detect and flag.`;
+
+  const specificNeedsFragment = `## Specific Needs
+
+Your job is to quickly identify:
+1. Which TOPICS were mentioned or relevant
+    a. Only flag TOPICS that were actually discussed, not just tangentially related
+    b. Be CONSERVATIVE - only suggest genuinely important, long-term relevant TOPICS
+    c. Be CLEAR - state your \`reason\` for including this TOPIC with any evidence you used
+
+The goal of the system is to remember important TOPICS to the HUMAN USER in order to ask about them in the future.`;
+
+  const guidelinesFragment = `## Guidelines
+
+# A TOPIC Is:
+
+A meaningful subject or concept relevant to the HUMAN USER. It is:
+
+- **Specific and Contextual:** Not a broad category or just a list of isolated facts. It must have narrative or direct relevance in the conversation.
+
+1. **Primary Focus** - Capture the main idea of the conversation, not minute details
+2. **Participation** - Things the HUMAN USER does or wants to do
+3. **Interests** - Hobbies or concepts they spend time on BY CHOICE
+4. **Responsibilities** - Tasks or requirements that occupy their time BY NECESSITY
+5. **Knowledge** - Ideas they are exploring or learning about, or are expert in
+6. **Dreams** - Wild ideas, hopes for the future, or vision of an ideal state
+7. **Conflicts** - Things they have difficulty with or are frustrated with
+8. **Concerns** - Ideas they express worry over
+9. **Stories and Characters** - Extended narratives they share (more than a sentence or two)
+10. **Location** - Favorite places, travel destinations
+11. **Preferences** - "I like {thing}" or "I hate {thing}" statements`;
+
+  const doNotCaptureFragment = `# **IMPORTANT** The Following Are NOT TOPICS
+
+# The system tracks FACTS, TRAITS, and PEOPLE as separate types. Do NOT capture:
+
+## FACTS - Tracked Separately
+- **Biographical Data (Do NOT Capture):** Name, Nickname, Birthday, Location, Job, Marital Status, Gender, Eye Color, Hair Color.
+  > **CRITICAL:** The HUMAN USER's name itself, or a collection of their basic biographical facts, is NEVER a TOPIC. Even if multiple biographical facts are mentioned together (e.g., "My name is John, I live in NYC, and I'm a software engineer"), do not summarize them as a 'topic' about the user's identity.
+- Other Important Dates: Wedding Anniversary, Job Anniversary
+- Health & Well-being: Allergies, Medical Conditions, Dietary Restrictions
+
+> NOTE: Many FACTS have stories/topics around them.
+> "My birthday is May 26th" is a FACT. "A goat jumped out of my birthday cake" is a TOPIC.
+
+## TRAITS - Tracked Separately
+* Personality Patterns, Communication style, Behavioral tendencies
+* Cognitive Style, Emotional Traits, Work Ethic, Social Orientation
+
+> NOTE: Many TRAITS have stories/topics around them.
+> "I'm a visual learner" is a TRAIT. "I saw a picture of an atom and I FINALLY GET IT" is a TOPIC.
+
+## PEOPLE / Relationships - Tracked Separately
+- Immediate family, Extended family, Friends, Coworkers, etc.
+
+> NOTE: Many PEOPLE have stories/topics around them.
+> "Sarah is my dream girl" is a PERSON. "I hope Sarah and I get married on the moon" is a TOPIC.
+
+## AI PERSONAS - Tracked Separately
+- Do NOT record any stories or details about PERSONAS as TOPICS`;
+
+  const criticalFragment = `# CRITICAL INSTRUCTIONS
+
+ONLY ANALYZE the "Most Recent Messages" in the following conversation. The "Earlier Conversation" is provided for your context and has already been processed!
+
+The JSON format is:
+
+\`\`\`json
+{
+  "topics": [
+    {
+        "type_of_topic": "Interest|Goal|Dream|Conflict|Concern|etc.",
+        "value_of_topic": "woodworking|Become Millionaire|Visit Spain|etc.",
+        "reason": "User stated...|Assumed from..."
+    }
+  ]
+}
+\`\`\`
+
+**Return JSON only.**`;
+
+  const system = `${taskFragment}
+
+${specificNeedsFragment}
+
+${guidelinesFragment}
+
+${doNotCaptureFragment}
+
+${criticalFragment}`;
+
+  const earlierSection = data.messages_context.length > 0
+    ? `## Earlier Conversation
+${formatMessagesAsPlaceholders(data.messages_context, personaName)}
+
+`
+    : '';
+
+  const recentSection = `## Most Recent Messages
+${formatMessagesAsPlaceholders(data.messages_analyze, personaName)}`;
+
+  const user = `# Conversation
+${earlierSection}${recentSection}
+
+---
+
+Scan the "Most Recent Messages" for TOPICS of interest to the human user.
+
+**Return JSON:**
+\`\`\`json
+{
+  "topics": [
+    {
+        "type_of_topic": "Interest|Goal|Dream|etc.",
+        "value_of_topic": "woodworking|Become Millionaire|etc.",
+        "reason": "User stated..."
+    }
+  ]
+}
+\`\`\``;
+
+  return { system, user };
+}

package/src/prompts/human/trait-scan.ts

@@ -0,0 +1,115 @@
+import type { TraitScanPromptData, PromptOutput } from "./types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+export function buildHumanTraitScanPrompt(data: TraitScanPromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildHumanTraitScanPrompt: persona_name is required");
+  }
+
+  const personaName = data.persona_name;
+
+  const taskFragment = `# Task
+
+You are scanning a conversation to quickly identify important TRAITS of the HUMAN USER. Your ONLY job is to spot admissions, observations, or other indicators of TRAITS. Do NOT analyze them deeply. Just detect and flag.`;
+
+  const specificNeedsFragment = `## Specific Needs
+
+Your job is to quickly identify:
+1. Which TRAITS were mentioned or observed
+    a. Only flag TRAITS that were actually discussed, not just tangentially related
+    b. Be CONSERVATIVE - only suggest genuinely important, long-term relevant TRAITS
+        i. Ignore: greetings, small talk, one-off mentions, jokes
+    c. Be CLEAR - state your \`reason\` for including this TRAIT with any evidence you used`;
+
+  const guidelinesFragment = `## Guidelines
+
+**A TRAIT Is:**
+* type_of_trait: Personality Patterns
+  * Values: Introverted, Reserved, Extroverted, Detail Oriented, Analytical
+* type_of_trait: Communication Style
+  * Assertive, Passive, Empathetic, Curious, Narrative
+* type_of_trait: Behavioral Tendencies
+  * Risk-Taker, Cautious, Spontaneous, Decisive
+* type_of_trait: Cognitive Style / Learning Approach
+  * Logical, Creative, Intuitive, Visual Learner
+* type_of_trait: Emotional Traits / Regulation
+  * Emotionally Resilient, Optimistic, Pessimistic, Calm, Anxious
+* type_of_trait: Work Ethic / Task Orientation
+  * Diligent, Proactive, Organized, Ambitious, Persistent
+* type_of_trait: Social Orientation
+  * Collaborative, Independent, Competitive, Supportive, Gregarious
+* type_of_trait: Approach to Change & Adversity
+  * Adaptable, Resilient, Flexible, Open-minded
+* type_of_trait: Motivational Drivers
+  * Achievement-Oriented, Altruistic, Curiosity-Driven
+* type_of_trait: Ethical & Moral Stance
+  * Principled, Honest, Integrity-Driven, Fair-minded
+
+**A TRAIT Is NOT:**
+- Biographical data: Name, Nickname, Birthday, Location, Job, Marital Status, Gender, Eye Color, Hair Color
+- Other unchangeable Data: Wedding Day, Allergies
+- General Topic: Interests, hobbies
+- People: Real people in their life: Wife, Husband, Daughter, Son, etc.
+- Personas: AI personas they discuss
+- Characters: Fictitious entities from books, movies, stories, media, etc.`;
+
+  const criticalFragment = `# CRITICAL INSTRUCTIONS
+
+ONLY ANALYZE the "Most Recent Messages" in the following conversation. The "Earlier Conversation" is provided for your context and has already been processed!
+
+The JSON format is:
+
+\`\`\`json
+{
+  "traits": [
+    {
+        "type_of_trait": "Personality Pattern|Communication Style|etc.",
+        "value_of_trait": "Introverted|Assertive|etc.",
+        "reason": "User stated...|Assumed from..."
+    }
+  ]
+}
+\`\`\`
+
+**Return JSON only.**`;
+
+  const system = `${taskFragment}
+
+${specificNeedsFragment}
+
+${guidelinesFragment}
+
+${criticalFragment}`;
+
+  const earlierSection = data.messages_context.length > 0
+    ? `## Earlier Conversation
+${formatMessagesAsPlaceholders(data.messages_context, personaName)}
+
+`
+    : '';
+
+  const recentSection = `## Most Recent Messages
+${formatMessagesAsPlaceholders(data.messages_analyze, personaName)}`;
+
+  const user = `# Conversation
+${earlierSection}${recentSection}
+
+---
+
+Scan the "Most Recent Messages" for TRAITS of the human user.
+
+**Return JSON:**
+\`\`\`json
+{
+  "traits": [
+    {
+        "type_of_trait": "Personality Pattern|Communication Style|etc.",
+        "value_of_trait": "Introverted|Assertive|etc.",
+        "reason": "User stated..."
+    }
+  ]
+}
+\`\`\``;
+
+  return { system, user };
+}

package/src/prompts/human/types.ts

@@ -0,0 +1,127 @@
+import type { Message, DataItemBase, DataItemType } from "../../core/types.js";
+
+export interface PromptOutput {
+  system: string;
+  user: string;
+}
+
+interface BaseScanPromptData {
+  messages_context: Message[];
+  messages_analyze: Message[];
+  persona_name: string;
+}
+
+export interface FactScanPromptData extends BaseScanPromptData {}
+
+export interface TraitScanPromptData extends BaseScanPromptData {}
+
+export interface TopicScanPromptData extends BaseScanPromptData {}
+
+export interface PersonScanPromptData extends BaseScanPromptData {
+  known_persona_names: string[];
+}
+
+export interface FactScanCandidate {
+  type_of_fact: string;
+  value_of_fact: string;
+  reason: string;
+}
+
+export interface TraitScanCandidate {
+  type_of_trait: string;
+  value_of_trait: string;
+  reason: string;
+}
+
+export interface TopicScanCandidate {
+  type_of_topic: string;
+  value_of_topic: string;
+  reason: string;
+}
+
+export interface PersonScanCandidate {
+  type_of_person: string;
+  name_of_person: string;
+  reason: string;
+}
+
+export interface FactScanResult {
+  facts: FactScanCandidate[];
+}
+
+export interface TraitScanResult {
+  traits: TraitScanCandidate[];
+}
+
+export interface TopicScanResult {
+  topics: TopicScanCandidate[];
+}
+
+export interface PersonScanResult {
+  people: PersonScanCandidate[];
+}
+
+export interface ItemMatchPromptData {
+  candidate_type: DataItemType;
+  candidate_name: string;
+  candidate_value: string;
+  all_items: Array<{
+    data_type: DataItemType;
+    data_id: string;
+    data_name: string;
+    data_description: string;
+  }>;
+}
+
+export interface ItemMatchResult {
+  matched_guid: string | null;
+}
+
+export interface ItemUpdatePromptData {
+  data_type: DataItemType;
+  existing_item: DataItemBase | null;
+  messages_context: Message[];
+  messages_analyze: Message[];
+  persona_name: string;
+  new_item_name?: string;
+  new_item_value?: string;
+}
+
+export type ExposureImpact = "high" | "medium" | "low" | "none";
+
+export interface QuoteCandidate {
+  text: string;
+  reason: string;
+}
+
+export interface ItemUpdateResultBase {
+  name: string;
+  description: string;
+  sentiment: number;
+  quotes?: QuoteCandidate[];
+}
+
+export interface FactUpdateResult extends ItemUpdateResultBase {}
+
+export interface TraitUpdateResult extends ItemUpdateResultBase {
+  strength?: number;
+}
+
+export interface TopicUpdateResult extends ItemUpdateResultBase {
+  category?: string;
+  exposure_desired?: number;
+  exposure_impact?: ExposureImpact;
+}
+
+export interface PersonUpdateResult extends ItemUpdateResultBase {
+  relationship?: string;
+  exposure_desired?: number;
+  exposure_impact?: ExposureImpact;
+}
+
+export type ItemUpdateResult = 
+  | FactUpdateResult 
+  | TraitUpdateResult 
+  | TopicUpdateResult 
+  | PersonUpdateResult 
+  | Record<string, never>;

package/src/prompts/index.ts

@@ -0,0 +1,90 @@
+export { buildResponsePrompt } from "./response/index.js";
+export type { ResponsePromptData, PromptOutput } from "./response/types.js";
+
+export {
+  buildHeartbeatCheckPrompt,
+  buildEiHeartbeatPrompt,
+} from "./heartbeat/index.js";
+export type {
+  HeartbeatCheckPromptData,
+  HeartbeatCheckResult,
+  EiHeartbeatPromptData,
+  EiHeartbeatResult,
+} from "./heartbeat/types.js";
+
+export {
+  buildPersonaGenerationPrompt,
+  buildPersonaDescriptionsPrompt,
+} from "./generation/index.js";
+export type {
+  PersonaGenerationPromptData,
+  PersonaGenerationResult,
+  PersonaDescriptionsPromptData,
+  PersonaDescriptionsResult,
+} from "./generation/types.js";
+
+export {
+  buildPersonaTraitExtractionPrompt,
+  buildPersonaTopicScanPrompt,
+  buildPersonaTopicMatchPrompt,
+  buildPersonaTopicUpdatePrompt,
+} from "./persona/index.js";
+export type {
+  PersonaTraitExtractionPromptData,
+  PersonaTopicScanPromptData,
+  PersonaTopicScanCandidate,
+  PersonaTopicScanResult,
+  PersonaTopicMatchPromptData,
+  PersonaTopicMatchResult,
+  PersonaTopicUpdatePromptData,
+  PersonaTopicUpdateResult,
+  TraitResult,
+} from "./persona/types.js";
+
+export { buildEiValidationPrompt } from "./validation/index.js";
+export type {
+  EiValidationPromptData,
+  EiValidationResult,
+} from "./validation/types.js";
+
+export {
+  buildHumanFactScanPrompt,
+  buildHumanTraitScanPrompt,
+  buildHumanTopicScanPrompt,
+  buildHumanPersonScanPrompt,
+  buildHumanItemMatchPrompt,
+  buildHumanItemUpdatePrompt,
+} from "./human/index.js";
+export type {
+  FactScanPromptData,
+  TraitScanPromptData,
+  TopicScanPromptData,
+  PersonScanPromptData,
+  FactScanCandidate,
+  TraitScanCandidate,
+  TopicScanCandidate,
+  PersonScanCandidate,
+  FactScanResult,
+  TraitScanResult,
+  TopicScanResult,
+  PersonScanResult,
+  ItemMatchPromptData,
+  ItemMatchResult,
+  ItemUpdatePromptData,
+  ExposureImpact,
+  ItemUpdateResult,
+} from "./human/types.js";
+
+export {
+  buildPersonaExpirePrompt,
+  buildPersonaExplorePrompt,
+  buildDescriptionCheckPrompt,
+} from "./ceremony/index.js";
+export type {
+  PersonaExpirePromptData,
+  PersonaExpireResult,
+  PersonaExplorePromptData,
+  PersonaExploreResult,
+  DescriptionCheckPromptData,
+  DescriptionCheckResult,
+} from "./ceremony/types.js";

package/src/prompts/message-utils.ts

@@ -0,0 +1,39 @@
+import type { Message } from "../core/types.js";
+
+const MESSAGE_PLACEHOLDER_REGEX = /\[mid:([a-zA-Z0-9_-]+):([^\]]+)\]/g;
+
+export function formatMessageAsPlaceholder(message: Message, personaName: string): string {
+  const role = message.role === "human" ? "human" : personaName;
+  return `[mid:${message.id}:${role}]`;
+}
+
+export function formatMessagesAsPlaceholders(messages: Message[], personaName: string): string {
+  if (messages.length === 0) return "(No messages)";
+  return messages.map(m => formatMessageAsPlaceholder(m, personaName)).join('\n\n');
+}
+
+export function hydratePromptPlaceholders(
+  prompt: string,
+  messageMap: Map<string, Message>
+): string {
+  return prompt.replace(MESSAGE_PLACEHOLDER_REGEX, (_match, id, role) => {
+    const message = messageMap.get(id);
+    if (!message) {
+      return `[${role}]: [message not found]`;
+    }
+    const displayRole = message.role === "human" ? "[human]" : `[${role}]`;
+    return `${displayRole}: ${message.content}`;
+  });
+}
+
+export function buildMessageMapFromPersonas(
+  personaMessages: Map<string, Message[]>
+): Map<string, Message> {
+  const map = new Map<string, Message>();
+  for (const messages of personaMessages.values()) {
+    for (const msg of messages) {
+      map.set(msg.id, msg);
+    }
+  }
+  return map;
+}

package/src/prompts/persona/index.ts

@@ -0,0 +1,16 @@
+export { buildPersonaTraitExtractionPrompt } from "./traits.js";
+export { buildPersonaTopicScanPrompt } from "./topics-scan.js";
+export { buildPersonaTopicMatchPrompt } from "./topics-match.js";
+export { buildPersonaTopicUpdatePrompt } from "./topics-update.js";
+export type {
+  PersonaTraitExtractionPromptData,
+  PersonaTopicScanPromptData,
+  PersonaTopicScanCandidate,
+  PersonaTopicScanResult,
+  PersonaTopicMatchPromptData,
+  PersonaTopicMatchResult,
+  PersonaTopicUpdatePromptData,
+  PersonaTopicUpdateResult,
+  TraitResult,
+  PromptOutput,
+} from "./types.js";