ei-tui 0.1.25 → 0.3.1

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

@@ -0,0 +1,122 @@
+import type { PromptOutput, ParticipantContext } from "./types.js";
+import type { Message } from "../../core/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 interface EventScanPromptData {
+  persona_name: string;
+  messages_context: Message[];
+  messages_analyze: Message[];
+  window_start?: string;
+  window_end?: string;
+  participant_context?: ParticipantContext;
+}
+
+export function buildEventScanPrompt(data: EventScanPromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildEventScanPrompt: persona_name is required");
+  }
+
+  const personaName = data.persona_name;
+
+  const system = `# Task
+
+You are scanning a conversation window to identify EPIC EVENTS worth preserving as long-term memories.
+
+An EPIC EVENT is a significant, bounded moment — something either participant would reference months later with recognition. Not a topic. Not a theme. A specific thing that happened.
+
+## The Test
+
+Ask yourself: "Would this moment get a section heading in a campaign recap document?"
+
+- "The Night We Debugged Beta's CPU" → YES
+- "First session with filesystem access" → YES
+- "The time the health check cached the API response forever" → YES
+- "We talked about AI" → NO (that's a Topic) return empty
+- "Flare asked some questions" → NO (too vague) return empty
+- Normal conversation without a notable arc → NO (not epic) return empty
+
+## What Makes an EPIC EVENT
+
+- A conflict encountered and (possibly) resolved
+- A discovery or breakthrough moment
+- A memorable failure or unexpected outcome
+- A significant "first" in the relationship
+- A pivotal decision or turning point
+- A moment either party would say "oh THAT session" about
+
+## What Is NOT an EPIC EVENT
+
+- Ongoing themes or interests (those are Topics)
+- Casual check-ins without a notable arc
+- Technical facts without a story around them
+- Anything that's already an ongoing trend rather than a bounded moment
+
+## Output Format
+
+\`\`\`json
+{
+  "events": [
+    {
+      "name": "Short evocative label (5-50 characters)",
+      "description": "1-2 sentences: what happened, why it mattered. Write it like a friend describing the moment to someone who wasn't there.",
+      "reason": "Evidence from the conversation — what made this rise to Epic Event level"
+    }
+  ]
+}
+\`\`\`
+
+Return an empty array if nothing qualifies. An empty array is the most common expected response.
+
+**Return JSON only. Be conservative. One memorable moment per window is the norm.**
+
+ONLY ANALYZE the "Most Recent Messages". The "Earlier Conversation" is provided for context only — it has already been processed.
+
+${participantContextSection(data.participant_context)}`;
+
+  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 Window
+${earlierSection}${recentSection}
+
+---
+
+Scan this conversation window for EPIC EVENTS — specific, memorable moments worth preserving long-term.
+
+**Return JSON:**
+\`\`\`json
+{
+  "events": [
+    {
+      "name": "Short evocative label",
+      "description": "What happened and why it mattered",
+      "reason": "Evidence from the conversation"
+    }
+  ]
+}
+\`\`\`
+
+Return empty array if nothing qualifies. Be conservative.`;
+
+  return { system, user };
+}

package/src/prompts/human/fact-find.ts

@@ -0,0 +1,106 @@
+import type { FactFindPromptData, PromptOutput } from "./types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+export function buildFactFindPrompt(data: FactFindPromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildFactFindPrompt: persona_name is required");
+  }
+  if (!data.missing_fact_names || data.missing_fact_names.length === 0) {
+    throw new Error("buildFactFindPrompt: missing_fact_names is required and must not be empty");
+  }
+
+  const personaName = data.persona_name;
+
+  const taskFragment = `# Task
+
+The system is missing some facts about the user. The user is not obligated to EVER provide ANY facts, so it is very likely that these facts are NOT present in this conversation. Your ONLY job is to search for EXPLICIT statements of fact for these SPECIFIC items, and return any matches in the provided JSON format.`;
+
+  const missingFactsFragment = `## Missing Facts
+
+The system is looking for the following facts:
+
+${data.missing_fact_names.map(name => `- ${name}`).join('\n')}
+
+Again - 99.99999% of the time, you will return no data — don't try to force it.`;
+
+  const guidelinesFragment = `# Guidelines
+
+1.  **Explicitness:**
+    *   **Focus only on what the user *explicitly states*.** Do not infer, assume, or guess based on context or general knowledge.
+    *   **Prioritize direct statements.** "I was born in 1985" is a fact. "I feel old now that it's 3030" isn't an explicit statement of their birth year.
+2.  **Objectivity and Verifiability:**
+    *   **Facts are objective and generally verifiable.** They are not subjective opinions, feelings, or temporary states.
+    *   **Focus on unchangeable or enduring attributes/events.**
+3.  **Specificity over Generality:**
+    *   If the user says "I live in a big city," do not extract "Current Location: big city." If they say "I live in New York," extract "Current Location: New York."
+4.  **Avoid Inference:**
+    *   If a user talks extensively about cooking, it's an interest, not a Fact like "Current Job Title: Chef" unless they explicitly state they ARE a chef.
+5.  **CRITICAL - Entity Attribution:**
+    *   ONLY extract facts about THE HUMAN USER THEMSELVES, not facts about other people they mention.
+    *   **Extract**: "I was born in 1984" → User's birthday
+    *   **Extract**: "I'm a software engineer" → User's job
+    *   **DO NOT Extract**: "My wife was a theater major" → This is about the wife, NOT the user
+    *   **DO NOT Extract**: "My daughter is 10 years old" → This is about the daughter, NOT the user
+    *   **DO NOT Extract**: "My brother lives in Texas" → This is about the brother, NOT the user
+    *   If the user shares information about someone else, that is NOT a fact about the user.`;
+
+  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
+{
+  "facts": [
+    {
+      "name": "One of the missing fact names from above",
+      "value": "The exact value of the fact",
+      "evidence": "Direct quote or reference showing where this fact was stated"
+    }
+  ]
+}
+\`\`\`
+
+**Return JSON only.**`;
+
+  const system = `${taskFragment}
+
+${missingFactsFragment}
+
+${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 FACTS about the human user.
+
+**Return JSON:**
+\`\`\`json
+{
+  "facts": [
+    {
+      "name": "One of the missing fact names from above",
+      "value": "The exact value of the fact",
+      "evidence": "Direct quote or reference showing where this fact was stated"
+    }
+  ]
+}
+\`\`\``;
+
+  return { system, user };
+}

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

@@ -75,8 +75,6 @@ Your job is to quickly identify:
 > They are details OF facts (e.g., { "type_of_fact": "Birthday", "value_of_fact": "August 15th" }).
 
 **FACTS ARE NOT**
-- Trait: Personality patterns, communication style, behavioral tendencies
-  - These are tracked separately
 - General Topic: Interests, hobbies, general subjects
   - These are tracked separately
 - Relationships: Wife, Husband, Daughter, Son, etc.

package/src/prompts/human/index.ts

@@ -1,32 +1,39 @@
 export { buildHumanFactScanPrompt } from "./fact-scan.js";
-export { buildHumanTraitScanPrompt } from "./trait-scan.js";
+export { buildFactFindPrompt } from "./fact-find.js";
 export { buildHumanTopicScanPrompt } from "./topic-scan.js";
 export { buildHumanPersonScanPrompt } from "./person-scan.js";
-export { buildHumanItemMatchPrompt } from "./item-match.js";
-export { buildHumanItemUpdatePrompt } from "./item-update.js";
+export { buildTopicMatchPrompt } from "./topic-match.js";
+export { buildTopicUpdatePrompt } from "./topic-update.js";
+export { buildPersonMatchPrompt } from "./person-match.js";
+export { buildPersonUpdatePrompt } from "./person-update.js";
+export { buildEventScanPrompt } from "./event-scan.js";
+export type { EventScanPromptData } from "./event-scan.js";
+
+export type { TopicMatchPromptData } from "./topic-match.js";
+export type { TopicUpdatePromptData } from "./topic-update.js";
+export type { PersonMatchPromptData } from "./person-match.js";
+export type { PersonUpdatePromptData } from "./person-update.js";
 
 export type {
   PromptOutput,
+  ParticipantContext,
   FactScanPromptData,
-  TraitScanPromptData,
   TopicScanPromptData,
   PersonScanPromptData,
+  FactFindPromptData,
   FactScanCandidate,
-  TraitScanCandidate,
   TopicScanCandidate,
   PersonScanCandidate,
   FactScanResult,
-  TraitScanResult,
+  FactFindResult,
   TopicScanResult,
   PersonScanResult,
-  ItemMatchPromptData,
+  EventScanCandidate,
+  EventScanResult,
   ItemMatchResult,
-  ItemUpdatePromptData,
   ExposureImpact,
   ItemUpdateResultBase,
   FactUpdateResult,
-  TraitUpdateResult,
-  TopicUpdateResult,
   PersonUpdateResult,
   ItemUpdateResult,
 } from "./types.js";

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

@@ -0,0 +1,65 @@
+import type { PromptOutput } from "./types.js";
+
+export interface PersonMatchPromptData {
+  candidate_name: string;
+  candidate_description: string;
+  candidate_relationship: string;
+  existing_people: Array<{
+    id: string;
+    name: string;
+    description: string;
+    relationship?: string;
+  }>;
+}
+
+export function buildPersonMatchPrompt(data: PersonMatchPromptData): PromptOutput {
+  if (!data.candidate_name) {
+    throw new Error("buildPersonMatchPrompt: candidate_name is required");
+  }
+
+  const system = `# Task
+
+You are checking if a PERSON already exists in our database.
+
+## Matching Rules
+
+1. **Exact match**: Same person by name or clear identity → return their ID
+2. **Similar match**: Same person referred to differently ("Mom" vs "Carol", "my boss" vs "Trumble") → return their ID
+3. **No match**: Genuinely new person → return "new"
+
+Be conservative. If you're unsure, return "new" — a duplicate is worse than a gap.
+
+# Existing People
+
+\`\`\`json
+${JSON.stringify(data.existing_people, 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 Person
+
+Name: ${data.candidate_name}
+Description: ${data.candidate_description}
+Relationship: ${data.candidate_relationship}
+
+Find the best match in existing people, or return "new" if this is a genuinely new person.
+
+\`\`\`json
+{
+  "matched_guid": "..." | "new"
+}
+\`\`\``;
+
+  return { system, user };
+}

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

@@ -8,72 +8,64 @@ export function buildHumanPersonScanPrompt(data: PersonScanPromptData): PromptOu
 
   const personaName = data.persona_name;
 
-  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
-* AI Persona (use \`type_of_person: "Persona"\`)
-
-**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
-- 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:
+  const system = `# Task
+
+You are scanning a conversation to quickly identify PEOPLE in the HUMAN USER's life.
+
+Detect and flag. Do NOT analyze deeply — that happens later.
+
+## What to Capture
+
+Flag a PERSON when they were meaningfully discussed — not just mentioned in passing.
+
+Be **conservative**: ignore one-off mentions, greetings, small talk, or jokes. Only flag people who matter to the human user's life.
+
+## What a PERSON Is
+
+Someone in the human user's world. Use the relationship as the primary classifier:
+
+**Immediate Family**: Father, Mother, Son, Daughter, Brother, Sister, Husband, Wife, Partner (and step/in-law variants)
+
+**Extended Family**: Grandfather, Grandmother, Aunt, Uncle, Cousin, Niece, Nephew
+
+**Social**: Friend, Close Acquaintance, Lover, Love Interest, Fiance, Spouse
+
+**Professional**: Coworker, Manager, Report, Mentor, Client
+
+**AI**: Persona (use \`relationship: "AI Persona"\` for AI companions and assistants)
+
+**NOT a PERSON:**
+- The user themselves
+- Biographical facts, topics, or hobbies
+- Fictional characters from books, movies, or media
+- Public figures only mentioned in passing (celebrities, politicians) — unless the user has a real relationship with them
+
+## When Identity Is Unclear
+
+If you can't identify which "Bob" or which "Brother" the user means, use "Unknown" and explain in the reason field. This triggers a later step to resolve ambiguity.
+
+Examples:
+- name: "Alice from work", relationship: "Coworker", description: "Mentioned but not described further", reason: "User referenced a work colleague named Alice"
+- name: "Unknown", relationship: "Sibling", description: "User mentioned a sibling but did not give a name", reason: "User said 'my brother' without further context"
+
+## Output Format
 
 \`\`\`json
 {
   "people": [
     {
-        "type_of_person": "The relationship from the list above",
-        "name_of_person": "The person's name",
-        "reason": "The justification of including this specific person"
+      "name": "The person's name, or 'Unknown' if not given",
+      "description": "1-2 sentences: who this person is and their role in the user's life",
+      "relationship": "Relationship type from the list above",
+      "reason": "Evidence from the conversation that justified flagging this person"
     }
   ]
 }
 \`\`\`
 
-**Return JSON only.**`;
-
-  const system = `${taskFragment}
-
-${specificNeedsFragment}
-
-${guidelinesFragment}
+**Return JSON only.**
 
-${criticalFragment}`;
+ONLY ANALYZE the "Most Recent Messages". The "Earlier Conversation" is provided for context only — it has already been processed.`;
 
   const earlierSection = data.messages_context.length > 0
     ? `## Earlier Conversation
@@ -90,16 +82,17 @@ ${earlierSection}${recentSection}
 
 ---
 
-Scan the "Most Recent Messages" for PEOPLE mentioned by the human user.
+Scan the "Most Recent Messages" for PEOPLE in the human user's life.
 
 **Return JSON:**
 \`\`\`json
 {
   "people": [
     {
-        "type_of_person": "The relationship from the list above",
-        "name_of_person": "The person's name",
-        "reason": "The justification of including this specific person"
+      "name": "The person's name, or 'Unknown' if not given",
+      "description": "1-2 sentences: who this person is and their role in the user's life",
+      "relationship": "Relationship type from the list above",
+      "reason": "Evidence from the conversation that justified flagging this person"
     }
   ]
 }