ei-tui 0.1.25 → 0.3.1

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

@@ -0,0 +1,241 @@
+import type { PromptOutput } from "./types.js";
+import type { Person, Message } from "../../core/types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+export interface PersonUpdatePromptData {
+  existing_item: Person | null;
+  new_person_name?: string;
+  new_person_description?: string;
+  new_person_relationship?: string;
+  messages_context: Message[];
+  messages_analyze: Message[];
+  persona_name: string;
+}
+
+function formatExistingPerson(person: Person): string {
+  return JSON.stringify({
+    name: person.name,
+    description: person.description,
+    sentiment: person.sentiment,
+    relationship: person.relationship,
+    exposure_current: person.exposure_current,
+    exposure_desired: person.exposure_desired,
+  }, null, 2);
+}
+
+export function buildPersonUpdatePrompt(data: PersonUpdatePromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildPersonUpdatePrompt: persona_name is required");
+  }
+
+  const personaName = data.persona_name;
+
+  const nameSection = `The person's actual name, or the clearest available identifier.
+
+Only update when you learn something more specific.
+
+Examples: "Unknown woman" → "Carol", "Mom" → "Carol (Mom)", "David" → "David Kim"`;
+
+  const descriptionSection = `A concise summary of who this person is and how they relate to the HUMAN USER. Personas use this to recognize this person and engage meaningfully when they come up.
+
+## CRITICAL: Synthesize, don't accumulate
+
+Every update must **rewrite** the description as a current-state summary. Never append to it.
+
+**Good description**: "Borfinda, partner of 12 years. Former marine biologist, now stay-at-home parent. Tends to ground the user when they spiral; dry sense of humor. Two kids together."
+
+**Bad description**: "Borfinda was mentioned when the user talked about moving. In a later conversation she came up again during the work stress discussion. Most recently the user said she was supportive."
+
+The description should:
+- Capture who this person IS — their role, characteristics, relationship texture
+- Include what the HUMAN USER has revealed about them over time
+- Be useful to a persona who's never heard this person's name before
+- Read as a brief, confident summary — not a log of when they were mentioned
+
+The description should NOT:
+- Append "Most recently:", "Latest mention:", or any temporal marker
+- Accumulate a session-by-session history of every time this person came up
+- Speculate about the person based on thin evidence
+- Exceed 3-4 sentences under any circumstances
+
+**ABSOLUTELY VITAL**: Do **NOT** embellish — personas use their own voice. Record what the user actually said or demonstrated, not your interpretation of its emotional significance.`;
+
+  const relationshipSection = `## Relationship (\`relationship\`)
+
+How the HUMAN USER is currently related to this PERSON.
+
+Once known, this field changes infrequently — a "Father" may later be clarified to "Step-Father", but is unlikely to become "Uncle".
+
+Keep it concise and specific. Avoid vague labels.
+
+Examples: "Unknown" → "Coworker", "Mother" → "Step-Mother", "Fiance" → "Spouse", "AI Persona" → "AI Companion"`;
+
+  const exposureSection = `## Desired Exposure (\`exposure_desired\`)
+
+How much the HUMAN USER wants to talk about this PERSON.
+
+Scale of 0.0 to 1.0:
+- 0.0: Never wants to hear about this PERSON again
+- 0.5: Average amount of engagement
+- 1.0: This PERSON is the sole focus of their existence
+
+Do not make micro-adjustments. Close enough is OK.
+
+## Exposure Impact (\`exposure_impact\`)
+
+Not in the current data — but include it in your response.
+
+How much this conversation should count toward exposure tracking:
+- "high": Long, detailed conversation exclusively about this PERSON
+- "medium": Long OR detailed conversation about this PERSON
+- "low": The conversation touched on this PERSON briefly
+- "none": Only alluded to or hinted at`;
+
+  const currentDetailsSection = data.existing_item
+    ? `\`\`\`json
+${formatExistingPerson(data.existing_item)}
+\`\`\`
+
+You are UPDATING an existing PERSON.`
+    : `**NEW PERSON — NOT YET IN SYSTEM**
+
+You are CREATING a new PERSON from what was discovered:
+\`\`\`json
+{
+  "name": "${data.new_person_name ?? "Unknown"}",
+  "description": "${data.new_person_description ?? "Details unknown"}",
+  "relationship": "${data.new_person_relationship ?? "Unknown"}"
+}
+\`\`\`
+
+Return all fields based on what you find in the conversation.`;
+
+  const jsonTemplate = `{
+    "name": "...",
+    "description": "...",
+    "sentiment": 0.0,
+    "relationship": "Mother|Friend|Coworker|AI Companion|etc.",
+    "exposure_desired": 0.5,
+    "exposure_impact": "high|medium|low|none",
+    "quotes": [
+      {
+        "text": "exact phrase from message",
+        "reason": "why this matters"
+      }
+    ]
+  }`;
+
+  const system = `# Task
+
+You are scanning a conversation to deeply understand a PERSON in the HUMAN USER's life.
+
+Your job is to take that analysis and apply it to the record we already have **IF DOING SO WILL PROVIDE THE HUMAN USER WITH A BETTER EXPERIENCE IN THE FUTURE**.
+
+This means detail you add should:
+1. Be meaningful, accurate, or still true to the HUMAN USER in six months or more
+2. **NOT** already be present in the description or name of the PERSON
+
+This PERSON will be recorded in the HUMAN USER's profile for agents and personas to later reference.
+
+# Field Definitions
+
+## Name (\`name\`)
+${nameSection}
+
+## Description (\`description\`)
+${descriptionSection}
+
+## Sentiment (\`sentiment\`)
+
+How the HUMAN USER feels about this PERSON overall.
+
+Scale of -1.0 to 1.0:
+- -1.0: No PERSON is more despised
+- -0.5: Disliked or complicated relationship, but not without value
+- 0: Neutral or unknown
+- 0.5: Liked and valued
+- 1.0: The most important person in their life
+
+Do not make micro-adjustments. Close enough is OK.
+
+${relationshipSection}
+
+${exposureSection}
+
+## Quotes
+
+In addition to updating the PERSON, identify any **memorable, funny, important, or stand-out phrases** from the Most Recent Messages that relate to this PERSON.
+
+### What Makes a Quote Worth Preserving
+
+**Prioritize:**
+- Humor, wit, colorful language, creative profanity
+- Emotional outbursts (positive or negative) — the raw stuff
+- Phrases that reveal how the HUMAN USER feels about this PERSON
+- Things you'd quote back to them later to make them laugh or think
+- Unique expressions or turns of phrase about or from this PERSON
+- Quotable moments from EITHER speaker — humans AND AI personas both say memorable things
+
+**NEVER extract these — they are NOT quotes:**
+- Technical identifiers: ARNs, URLs, file paths, UUIDs, config keys
+- AI agent self-talk: "I notice I'm in Plan Mode", "I'll start by...", status updates
+- AI apologies or acknowledgments: "You're absolutely right", "I apologize for that"
+- Generic statements that could apply to anyone
+- Credentials, secrets, connection strings, or anything that looks like an access token
+
+**The litmus test**: Would you bring this up at a bar with a friend? Would it make someone laugh, think, or feel something?
+- "She's the only person who can make me feel simultaneously stupid and brilliant" → YES.
+- "Borfinda was mentioned in the context of the Minnesota discussion" → NO. That's a note, not a quote.
+
+**When in doubt, leave it out.** An empty quotes array is always acceptable.
+
+**CRITICAL**: Return the EXACT text as it appears in the message. **WE CAN ONLY USE IT IF WE FIND IT IN THE TEXT.**
+
+# CRITICAL INSTRUCTIONS
+
+ONLY ANALYZE the "Most Recent Messages". The "Earlier Conversation" is provided for context only — it has already been processed.
+
+\`\`\`json
+${jsonTemplate}
+\`\`\`
+
+When returning a record, **ALWAYS** include \`name\`, \`description\`, and \`sentiment\`.
+
+If you find **NO EVIDENCE** of this PERSON in the "Most Recent Messages", respond with: \`{}\`
+
+If **NO CHANGES** are required, respond with: \`{}\`
+
+An empty object is the MOST COMMON expected response.
+
+# Current Details of PERSON
+
+${currentDetailsSection}
+`;
+
+  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}
+
+---
+
+Analyze the Most Recent Messages and update the PERSON if warranted.
+
+**Return JSON:**
+\`\`\`json
+${jsonTemplate}
+\`\`\`
+
+If no changes are needed, respond with: \`{}\``;
+
+  return { system, user };
+}

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

@@ -0,0 +1,65 @@
+import type { PromptOutput } from "./types.js";
+
+export interface TopicMatchPromptData {
+  candidate_name: string;
+  candidate_description: string;
+  candidate_category: string;
+  existing_topics: Array<{
+    id: string;
+    name: string;
+    description: string;
+    category?: string;
+  }>;
+}
+
+export function buildTopicMatchPrompt(data: TopicMatchPromptData): PromptOutput {
+  if (!data.candidate_name) {
+    throw new Error("buildTopicMatchPrompt: candidate_name is required");
+  }
+
+  const system = `# Task
+
+You are checking if a TOPIC already exists in our database.
+
+## Matching Rules
+
+1. **Exact match**: Same name or concept → return its ID
+2. **Similar match**: Clearly the same topic with different wording → return its ID
+3. **No match**: Genuinely new information → return "new"
+
+Be conservative. If you're unsure, return "new" — a duplicate is worse than a gap.
+
+# Existing Topics
+
+\`\`\`json
+${JSON.stringify(data.existing_topics, null, 2)}
+\`\`\`
+
+# Response Format
+
+Return ONLY the ID of the matching entry, or "new".
+
+\`\`\`json
+{
+  "matched_guid": "uuid-of-matching-entry" | "new"
+}
+\`\`\`
+
+**Return JSON only.**`;
+
+  const user = `# Candidate Topic
+
+Name: ${data.candidate_name}
+Description: ${data.candidate_description}
+Category: ${data.candidate_category}
+
+Find the best match in existing topics, or return "new" if this is genuinely new.
+
+\`\`\`json
+{
+  "matched_guid": "..." | "new"
+}
+\`\`\``;
+
+  return { system, user };
+}

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

@@ -1,6 +1,19 @@
-import type { TopicScanPromptData, PromptOutput } from "./types.js";
+import type { TopicScanPromptData, PromptOutput, ParticipantContext } from "./types.js";
 import { formatMessagesAsPlaceholders } from "../message-utils.js";
 
+function participantContextSection(ctx: ParticipantContext | undefined): string {
+  if (!ctx) return "";
+  const lines: string[] = ["# Participant Context", "The following may help you understand what themes and moments are meaningful in this conversation.", ""];
+  lines.push(`## Persona: ${ctx.persona_name}`);
+  if (ctx.persona_description) lines.push(ctx.persona_description);
+  lines.push("");
+  lines.push("## Human");
+  if (ctx.human_name) lines.push(`Name: ${ctx.human_name}`);
+  if (ctx.human_age !== undefined) lines.push(`Age: ${ctx.human_age}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
 export function buildHumanTopicScanPrompt(data: TopicScanPromptData): PromptOutput {
   if (!data.persona_name) {
     throw new Error("buildHumanTopicScanPrompt: persona_name is required");
@@ -8,98 +21,64 @@ export function buildHumanTopicScanPrompt(data: TopicScanPromptData): PromptOutp
 
   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
+  const system = `# Task
 
-# A TOPIC Is:
+You are scanning a conversation to quickly identify TOPICS of interest to the HUMAN USER.
 
-A meaningful subject or concept relevant to the HUMAN USER. It is:
+Detect and flag. Do NOT analyze deeply — that happens later.
 
-- **Specific and Contextual:** Not a broad category or just a list of isolated facts. It must have narrative or direct relevance in the conversation.
+## What to Capture
 
-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`;
+Flag a TOPIC when it was meaningfully discussed — not just mentioned in passing.
 
-  const doNotCaptureFragment = `# **IMPORTANT** The Following Are NOT TOPICS
+Be **conservative**: only flag topics that are genuinely relevant to the human user long-term. Noise is worse than gaps.
 
-# The system tracks FACTS, TRAITS, and PEOPLE as separate types. Do NOT capture:
+## What a TOPIC Is
 
-## 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
+A meaningful subject in the human user's life: something they care about, work on, worry over, or experience. It has context and weight — not just a passing reference.
 
-> 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.
+**NOT a TOPIC:**
+- Biographical facts (birthday, job title, location) — those are Facts
+- People (family, friends, coworkers, AI personas) — those are People
+- One-off mentions, small talk, or jokes with no deeper relevance
 
-## TRAITS - Tracked Separately
-* Personality Patterns, Communication style, Behavioral tendencies
-* Cognitive Style, Emotional Traits, Work Ethic, Social Orientation
+## Category
 
-> 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.
+Assign each TOPIC one category. Pick the closest fit:
 
-## PEOPLE / Relationships - Tracked Separately
-- Immediate family, Extended family, Friends, Coworkers, etc.
+- **Interest** — hobbies, activities, ongoing fascinations
+- **Goal** — things they want to achieve
+- **Dream** — aspirational, maybe unrealistic desires
+- **Conflict** — internal or external struggles, dilemmas
+- **Concern** — worries, anxieties about something real
+- **Fear** — things that scare them
+- **Hope** — positive expectations for the future
+- **Plan** — concrete intentions with steps in mind
+- **Project** — active undertakings with real progress
+- **Event** — a specific, significant moment that either party might reference later ("remember when...")
 
-> 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.
+When in doubt, pick the closest match. The update step will refine it.
 
-## 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:
+## Output Format
 
 \`\`\`json
 {
   "topics": [
     {
-        "type_of_topic": "The Topic Type from the list above",
-        "value_of_topic": "<actual topic from the conversation>",
-        "reason": "The justification of including this specific topic"
+      "name": "Short label for the topic (10-75 characters)",
+      "description": "1-2 sentences: what this topic is and why it matters to the user",
+      "category": "One of the categories above",
+      "reason": "Evidence from the conversation that justified flagging this topic"
     }
   ]
 }
 \`\`\`
 
-**Return JSON only.**`;
-
-  const system = `${taskFragment}
-
-${specificNeedsFragment}
-
-${guidelinesFragment}
+**Return JSON only.**
 
-${doNotCaptureFragment}
+ONLY ANALYZE the "Most Recent Messages". The "Earlier Conversation" is provided for context only — it has already been processed.
 
-${criticalFragment}`;
+${participantContextSection(data.participant_context)}`;
 
   const earlierSection = data.messages_context.length > 0
     ? `## Earlier Conversation
@@ -123,9 +102,10 @@ Scan the "Most Recent Messages" for TOPICS of interest to the human user.
 {
   "topics": [
     {
-        "type_of_topic": "The Topic Type from the list above",
-        "value_of_topic": "<actual topic from the conversation>",
-        "reason": "The justification of including this specific topic"
+      "name": "Short label for the topic (10-75 characters)",
+      "description": "1-2 sentences: what this topic is and why it matters to the user",
+      "category": "Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event",
+      "reason": "Evidence from the conversation that justified flagging this topic"
     }
   ]
 }