@cohortapp/agent-sdk 2.3.0

package/scripts/pre-draft-context.py

@@ -0,0 +1,994 @@
+#!/usr/bin/env python3
+"""Pre-draft fact retrieval module — Memory Enhancement Phase 4.
+
+Pulls relevant entity context BEFORE composing any outbound message.
+Closes the gap where the agent drafts messages without first checking what
+they know about the recipient and related entities.
+
+Integration points — call this script before any of these send scripts:
+  - scripts/send-email-threaded.py  (email composition)
+  - scripts/slack-send.sh           (Slack messaging)
+  - scripts/send-whatsapp.sh        (WhatsApp messaging)
+
+Usage:
+  python3 scripts/pre-draft-context.py --recipient "Graham Syder"
+  python3 scripts/pre-draft-context.py --recipient "Graham Syder" --topic "fitout"
+  python3 scripts/pre-draft-context.py --recipient "sam@example.com" --format brief
+  python3 scripts/pre-draft-context.py --recipient "Jordan" --topic "83b election" --format brief
+
+Output:
+  --format json  (default) → Full structured JSON to stdout
+  --format brief           → 3-5 line summary suitable for prompt injection
+
+Performance target: < 500ms (no API calls — file reads only).
+Exit codes: 0 = context found, 1 = recipient not found, 2 = error
+
+Created: 2026-04-04 — Memory Enhancement Phase 4
+"""
+import argparse
+import json
+import re
+import sys
+import time
+from pathlib import Path
+
+# Try to import PyYAML at module level (avoids repeated import overhead)
+_yaml_mod = None
+_yaml_loader = None
+try:
+    import yaml as _yaml_mod
+    try:
+        _yaml_loader = _yaml_mod.CSafeLoader  # C extension — 10x faster
+    except AttributeError:
+        _yaml_loader = None
+except ImportError:
+    pass
+
+# ─────────────────────────────────────────────
+# Path resolution
+# ─────────────────────────────────────────────
+SCRIPT_DIR = Path(__file__).resolve().parent
+REPO_ROOT = SCRIPT_DIR.parent
+
+ENTITY_INDEX_PATH = REPO_ROOT / "memory" / "indexes" / "entity-relationships.yaml"
+ENTITY_INDEX_CACHE_PATH = REPO_ROOT / "memory" / "indexes" / ".entity-relationships.json"
+USER_PROFILES_DIR = REPO_ROOT / "memory" / "profiles" / "users"
+QUEUES_DIR = REPO_ROOT / "state" / "queues"
+INTERACTIONS_DIR = REPO_ROOT / "memory" / "interactions"
+
+
+# ─────────────────────────────────────────────
+# YAML parser — reused from validate-outbound.py
+# ─────────────────────────────────────────────
+def _parse_yaml(text):
+    """Parse YAML text into nested Python objects.
+
+    Uses PyYAML with C loader (fastest) if available, then safe_load,
+    falls back to built-in recursive parser.
+    """
+    if _yaml_mod is not None:
+        if _yaml_loader is not None:
+            return _yaml_mod.load(text, Loader=_yaml_loader) or {}
+        else:
+            return _yaml_mod.safe_load(text) or {}
+    lines = text.split('\n')
+    return _parse_yaml_block(lines, 0, 0)[0]
+
+
+def _parse_yaml_block(lines, start, base_indent):
+    """Recursively parse a YAML block."""
+    result = {}
+    i = start
+    while i < len(lines):
+        raw = lines[i]
+        stripped = raw.lstrip()
+        if not stripped or stripped.startswith('#'):
+            i += 1
+            continue
+        indent = len(raw) - len(raw.lstrip())
+        if indent < base_indent and i > start:
+            break
+        if indent > base_indent and i > start:
+            break
+
+        if stripped.startswith('- '):
+            lst, i = _parse_yaml_list(lines, i, indent)
+            if not result:
+                return lst, i
+            break
+
+        if ':' in stripped and not stripped.startswith('-'):
+            key, _, rest = stripped.partition(':')
+            key = key.strip()
+            rest = rest.strip()
+            if rest:
+                result[key] = _yaml_scalar(rest)
+                i += 1
+            else:
+                child_indent, child_idx = _next_content_line(lines, i + 1)
+                if child_indent is not None and child_indent > indent:
+                    child_stripped = lines[child_idx].lstrip()
+                    if child_stripped.startswith('- '):
+                        value, i = _parse_yaml_list(lines, child_idx, child_indent)
+                    else:
+                        value, i = _parse_yaml_block(lines, child_idx, child_indent)
+                    result[key] = value
+                else:
+                    result[key] = None
+                    i += 1
+        else:
+            i += 1
+    return result, i
+
+
+def _parse_yaml_list(lines, start, base_indent):
+    """Parse a YAML list."""
+    result = []
+    i = start
+    while i < len(lines):
+        raw = lines[i]
+        stripped = raw.lstrip()
+        if not stripped or stripped.startswith('#'):
+            i += 1
+            continue
+        indent = len(raw) - len(raw.lstrip())
+        if indent < base_indent:
+            break
+        if indent > base_indent:
+            break
+        if not stripped.startswith('- '):
+            break
+
+        item_content = stripped[2:].strip()
+        if ':' in item_content and not item_content.startswith('"') and not item_content.startswith("'"):
+            k, _, v = item_content.partition(':')
+            k = k.strip()
+            v = v.strip()
+            item_dict = {k: _yaml_scalar(v) if v else None}
+            child_indent, child_idx = _next_content_line(lines, i + 1)
+            if child_indent is not None and child_indent > indent:
+                extra, i = _parse_yaml_block(lines, child_idx, child_indent)
+                if isinstance(extra, dict):
+                    item_dict.update(extra)
+            else:
+                i += 1
+            result.append(item_dict)
+        else:
+            result.append(_yaml_scalar(item_content))
+            i += 1
+    return result, i
+
+
+def _next_content_line(lines, start):
+    """Find next non-blank, non-comment line."""
+    i = start
+    while i < len(lines):
+        stripped = lines[i].lstrip()
+        if stripped and not stripped.startswith('#'):
+            indent = len(lines[i]) - len(lines[i].lstrip())
+            return indent, i
+        i += 1
+    return None, None
+
+
+def _yaml_scalar(text):
+    """Convert a YAML scalar string to Python type."""
+    if not text:
+        return None
+    if (text.startswith('"') and text.endswith('"')) or \
+       (text.startswith("'") and text.endswith("'")):
+        return text[1:-1]
+    if '  #' in text:
+        text = text[:text.index('  #')].strip()
+    if text.lower() in ('true', 'yes'):
+        return True
+    if text.lower() in ('false', 'no'):
+        return False
+    if text.lower() in ('null', '~', ''):
+        return None
+    try:
+        return int(text)
+    except ValueError:
+        pass
+    try:
+        return float(text)
+    except ValueError:
+        pass
+    return text.strip('"').strip("'")
+
+
+# ─────────────────────────────────────────────
+# Entity index loading (mirrors validate-outbound.py)
+# ─────────────────────────────────────────────
+_entity_index_cache = None
+
+
+def _load_entity_data():
+    """Load raw entity data from YAML, using JSON cache when fresh.
+
+    The JSON cache is regenerated when the YAML file is newer.
+    Returns parsed dict with 'entities' and 'relationships' keys.
+    """
+    if not ENTITY_INDEX_PATH.exists():
+        return {'entities': [], 'relationships': []}
+
+    # Check if JSON cache is fresh
+    if ENTITY_INDEX_CACHE_PATH.exists():
+        yaml_mtime = ENTITY_INDEX_PATH.stat().st_mtime
+        json_mtime = ENTITY_INDEX_CACHE_PATH.stat().st_mtime
+        if json_mtime >= yaml_mtime:
+            try:
+                return json.loads(ENTITY_INDEX_CACHE_PATH.read_text(encoding='utf-8'))
+            except Exception:
+                pass  # Fall through to YAML parsing
+
+    # Parse YAML and write JSON cache
+    text = ENTITY_INDEX_PATH.read_text(encoding='utf-8')
+    data = _parse_yaml(text)
+    if not isinstance(data, dict):
+        return {'entities': [], 'relationships': []}
+
+    # Write cache (best-effort, non-blocking)
+    try:
+        ENTITY_INDEX_CACHE_PATH.write_text(
+            json.dumps(data, default=str, ensure_ascii=False),
+            encoding='utf-8'
+        )
+    except Exception:
+        pass
+
+    return data
+
+
+def load_entity_index():
+    """Load and index entity-relationships.yaml.
+
+    Returns dict with:
+      - entities: list of entity dicts
+      - relationships: list of relationship dicts
+      - by_name: dict mapping lowercase name/alias -> entity dict
+      - by_email: dict mapping lowercase email -> entity dict
+      - rels_by_subject: dict mapping entity id -> list of rels
+      - rels_by_object: dict mapping entity id -> list of rels
+    """
+    global _entity_index_cache
+    if _entity_index_cache is not None:
+        return _entity_index_cache
+
+    empty = {
+        'entities': [], 'relationships': [],
+        'by_name': {}, 'by_email': {},
+        'rels_by_subject': {}, 'rels_by_object': {},
+    }
+
+    if not ENTITY_INDEX_PATH.exists():
+        _entity_index_cache = empty
+        return _entity_index_cache
+
+    try:
+        data = _load_entity_data()
+        if not isinstance(data, dict):
+            _entity_index_cache = empty
+            return _entity_index_cache
+
+        entities = data.get('entities', []) or []
+        relationships = data.get('relationships', []) or []
+
+        by_name = {}
+        by_email = {}
+        for entity in entities:
+            if not isinstance(entity, dict):
+                continue
+            name = entity.get('name', '')
+            if name and isinstance(name, str):
+                by_name[name.lower()] = entity
+                parts = name.split()
+                if len(parts) >= 2:
+                    short = f"{parts[0]} {parts[-1]}"
+                    by_name[short.lower()] = entity
+                if len(parts) >= 1:
+                    first = parts[0].lower()
+                    if first not in by_name:
+                        by_name[first] = entity
+
+            aliases = entity.get('aliases', []) or []
+            if isinstance(aliases, list):
+                for alias in aliases:
+                    if alias and isinstance(alias, str):
+                        by_name[alias.lower()] = entity
+
+            email = entity.get('email', '')
+            if email and isinstance(email, str):
+                by_email[email.lower()] = entity
+
+        rels_by_subject = {}
+        rels_by_object = {}
+        for rel in relationships:
+            if not isinstance(rel, dict):
+                continue
+            subj = rel.get('subject', '')
+            obj = rel.get('object', '')
+            if subj:
+                rels_by_subject.setdefault(subj, []).append(rel)
+            if obj:
+                rels_by_object.setdefault(obj, []).append(rel)
+
+        _entity_index_cache = {
+            'entities': entities,
+            'relationships': relationships,
+            'by_name': by_name,
+            'by_email': by_email,
+            'rels_by_subject': rels_by_subject,
+            'rels_by_object': rels_by_object,
+        }
+    except Exception:
+        _entity_index_cache = empty
+
+    return _entity_index_cache
+
+
+def lookup_entity(name_or_email):
+    """Find an entity by name, alias, or email.
+
+    Returns the entity dict or None.
+    """
+    idx = load_entity_index()
+    key = name_or_email.lower().strip()
+    if not key:
+        return None
+
+    # Try email first
+    entity = idx['by_email'].get(key)
+    if entity:
+        return entity
+
+    # Try name/alias
+    entity = idx['by_name'].get(key)
+    if entity:
+        return entity
+
+    # Try first+last from multi-word input
+    parts = key.split()
+    if len(parts) >= 2:
+        short = f"{parts[0]} {parts[-1]}"
+        entity = idx['by_name'].get(short)
+        if entity:
+            return entity
+
+    # Single name
+    if len(parts) == 1:
+        entity = idx['by_name'].get(parts[0])
+        if entity:
+            return entity
+
+    return None
+
+
+# ─────────────────────────────────────────────
+# Relationship classification
+# ─────────────────────────────────────────────
+ADAPTIC_IDS = {
+    'company:northwind-group', 'company:northwind-holdings',
+    'company:northwind-am-difc', 'company:northwind-technologies',
+    'company:northwind-group-investments', 'company:northwind-investments',
+    'company:northwind-inc', 'company:northwind-ai-uk',
+    'company:northwind-am-uk', 'company:northwind-am-cayman',
+    'company:northwind-am-asia', 'company:northwind-asia',
+    'company:northwind-am-eu', 'company:northwind-am-us',
+    'company:northwind-am-ksa', 'company:northwind-ksa',
+}
+
+
+def classify_relationship(entity_id):
+    """Classify a person or company's relationship to Northwind.
+
+    Returns dict: relationship_type, is_internal, relationships_to_northwind.
+    """
+    idx = load_entity_index()
+    rels = idx['rels_by_subject'].get(entity_id, [])
+
+    company_rels = []
+    is_internal = False
+    rel_type = 'unknown'
+
+    for rel in rels:
+        obj = rel.get('object', '')
+        pred = rel.get('predicate', '')
+        if obj in ADAPTIC_IDS or obj.startswith('company:northwind'):
+            company_rels.append(rel)
+            if pred in ('employed_by', 'directs'):
+                is_internal = True
+                rel_type = 'internal'
+            elif pred == 'vendor_candidate_for' and rel_type != 'internal':
+                rel_type = 'vendor_candidate'
+            elif pred == 'vendor_for' and rel_type not in ('internal', 'vendor_candidate'):
+                rel_type = 'external_vendor'
+            elif pred == 'advises' and rel_type not in ('internal', 'vendor_candidate', 'external_vendor'):
+                rel_type = 'external_advisor'
+            elif pred == 'invests_in' and rel_type not in ('internal',):
+                rel_type = 'investor'
+            elif pred == 'regulates' and rel_type not in ('internal',):
+                rel_type = 'regulator'
+
+    if rel_type == 'unknown':
+        for rel in rels:
+            if rel.get('predicate') == 'employed_by':
+                rel_type = 'external'
+                break
+
+    return {
+        'relationship_type': rel_type,
+        'is_internal': is_internal,
+        'relationships_to_northwind': company_rels,
+    }
+
+
+# ─────────────────────────────────────────────
+# User profile loading
+# ─────────────────────────────────────────────
+def load_user_profile(entity):
+    """Load the full user profile YAML for an entity.
+
+    Returns parsed dict or None.
+    """
+    profile_path = entity.get('profile_path', '')
+    if profile_path:
+        full_path = REPO_ROOT / profile_path
+        if full_path.exists():
+            try:
+                text = full_path.read_text(encoding='utf-8')
+                return _parse_yaml(text)
+            except Exception:
+                pass
+
+    # Fallback: try to derive slug from entity name
+    name = entity.get('name', '')
+    if name:
+        slug = name.lower().replace(' ', '-')
+        # Remove middle names for slug
+        parts = name.lower().split()
+        if len(parts) >= 2:
+            slug = f"{parts[0]}-{parts[-1]}"
+        candidate = USER_PROFILES_DIR / f"{slug}.yaml"
+        if candidate.exists():
+            try:
+                text = candidate.read_text(encoding='utf-8')
+                return _parse_yaml(text)
+            except Exception:
+                pass
+
+    return None
+
+
+# ─────────────────────────────────────────────
+# Queue scanning — find active items mentioning a person
+# ─────────────────────────────────────────────
+def scan_queues_for_person(name, entity_id=None, slug=None):
+    """Scan all queue YAML files for items mentioning this person.
+
+    Uses fast text search to skip files that don't mention the person,
+    then parses only matching item blocks to extract structured data.
+
+    Returns list of dicts with: queue, item_id, title, status, priority.
+    """
+    if not QUEUES_DIR.exists():
+        return []
+
+    # Build search terms for initial text-based filtering
+    search_terms = set()
+    search_terms.add(name.lower())
+    if entity_id:
+        parts = entity_id.split(':')
+        if len(parts) == 2:
+            search_terms.add(parts[1].lower())
+    if slug:
+        search_terms.add(slug.lower())
+
+    results = []
+    for qfile in sorted(QUEUES_DIR.glob('*.yaml')):
+        try:
+            text = qfile.read_text(encoding='utf-8')
+            text_lower = text.lower()
+
+            # Fast check: skip entire file if no search term appears
+            if not any(term in text_lower for term in search_terms):
+                continue
+
+            # Extract queue_name from early lines (avoid full parse)
+            queue_name = qfile.stem
+            for line in text.split('\n')[:5]:
+                if line.startswith('queue_name:'):
+                    queue_name = line.split(':', 1)[1].strip().strip('"').strip("'")
+                    break
+
+            # Parse item blocks using text-based extraction
+            # Split on '  - id:' which marks each queue item
+            item_blocks = re.split(r'\n  - id:', text)
+            if len(item_blocks) < 2:
+                # Try alternate format
+                item_blocks = re.split(r'\n  -\s+id:', text)
+
+            for i, block in enumerate(item_blocks):
+                if i == 0:
+                    continue  # Skip preamble before first item
+
+                block_lower = block.lower()
+
+                # Check if this block mentions the person
+                if not any(term in block_lower for term in search_terms):
+                    continue
+
+                # Extract fields with simple regex
+                item_id = ''
+                id_match = re.match(r'\s*(\S+)', block)
+                if id_match:
+                    item_id = id_match.group(1).strip()
+
+                def _extract_field(field_name, text_block):
+                    pattern = rf'^\s*{field_name}:\s*(.+?)$'
+                    m = re.search(pattern, text_block, re.MULTILINE)
+                    if m:
+                        val = m.group(1).strip().strip('"').strip("'")
+                        return val
+                    return ''
+
+                status = _extract_field('status', block)
+                # Only include active items
+                if status.lower() in ('closed', 'resolved', 'cancelled'):
+                    continue
+
+                title = _extract_field('title', block)
+                priority = _extract_field('priority', block)
+                due = _extract_field('due', block)
+
+                results.append({
+                    'queue': queue_name,
+                    'item_id': item_id,
+                    'title': title,
+                    'status': status,
+                    'priority': priority,
+                    'due': due if due else None,
+                })
+
+        except Exception:
+            continue
+
+    return results
+
+
+# ─────────────────────────────────────────────
+# Interaction history — recent communications
+# ─────────────────────────────────────────────
+def get_recent_interactions(entity, max_items=10):
+    """Load recent interaction history for the entity.
+
+    Checks memory/interactions/{email,slack,meetings}/ for the entity's slug.
+    Returns list of interaction summaries (most recent first).
+    """
+    name = entity.get('name', '')
+    parts = name.lower().split()
+    if len(parts) >= 2:
+        slug = f"{parts[0]}-{parts[-1]}"
+    elif parts:
+        slug = parts[0]
+    else:
+        return []
+
+    interactions = []
+
+    def _parse_interaction(entry, channel):
+        """Normalize an interaction entry from any JSONL schema variant."""
+        # Handle both timestamp formats: 'timestamp' and 'date'
+        ts = entry.get('timestamp', '') or entry.get('date', '') or ''
+        # Handle both direction formats: 'direction' and 'type'
+        direction = entry.get('direction', '') or entry.get('type', '') or ''
+        # Handle summary: 'summary', 'content', or fall back to 'action_taken'
+        summary = entry.get('summary', '') or entry.get('content', '') or entry.get('action_taken', '') or ''
+        return {
+            'channel': channel,
+            'timestamp': ts,
+            'direction': direction,
+            'subject': entry.get('subject', ''),
+            'summary': summary,
+        }
+
+    # Check email interactions
+    email_dir = INTERACTIONS_DIR / "email" / slug
+    if email_dir.exists():
+        for f in sorted(email_dir.glob('*.jsonl'), reverse=True):
+            try:
+                for line in f.read_text(encoding='utf-8').strip().split('\n'):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                        interactions.append(_parse_interaction(entry, 'email'))
+                    except json.JSONDecodeError:
+                        continue
+            except Exception:
+                continue
+
+    # Check Slack DM interactions
+    slack_dm_dir = INTERACTIONS_DIR / "slack" / "dm" / slug if INTERACTIONS_DIR.exists() else None
+    if slack_dm_dir and slack_dm_dir.exists():
+        for f in sorted(slack_dm_dir.glob('*.jsonl'), reverse=True):
+            try:
+                for line in f.read_text(encoding='utf-8').strip().split('\n'):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                        interactions.append(_parse_interaction(entry, 'slack_dm'))
+                    except json.JSONDecodeError:
+                        continue
+            except Exception:
+                continue
+
+    # Check meeting interactions
+    meetings_dir = INTERACTIONS_DIR / "meetings" / slug if INTERACTIONS_DIR.exists() else None
+    if meetings_dir and meetings_dir.exists():
+        for f in sorted(meetings_dir.glob('*.jsonl'), reverse=True):
+            try:
+                for line in f.read_text(encoding='utf-8').strip().split('\n'):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                        interactions.append(_parse_interaction(entry, 'meeting'))
+                    except json.JSONDecodeError:
+                        continue
+            except Exception:
+                continue
+
+    # Sort by timestamp descending
+    interactions.sort(key=lambda x: x.get('timestamp', ''), reverse=True)
+    return interactions[:max_items]
+
+
+# ─────────────────────────────────────────────
+# Related entities
+# ─────────────────────────────────────────────
+def get_related_entities(entity_id):
+    """Find all entities related to this one via the relationship graph.
+
+    Returns list of dicts: related_entity_id, related_entity_name,
+    predicate, direction ('outgoing'/'incoming'), notes.
+    """
+    idx = load_entity_index()
+    related = []
+
+    # Entities we look up by id
+    entity_by_id = {}
+    for e in idx['entities']:
+        if isinstance(e, dict) and e.get('id'):
+            entity_by_id[e['id']] = e
+
+    # Outgoing relationships (this entity is subject)
+    for rel in idx['rels_by_subject'].get(entity_id, []):
+        obj_id = rel.get('object', '')
+        obj_entity = entity_by_id.get(obj_id, {})
+        related.append({
+            'entity_id': obj_id,
+            'entity_name': obj_entity.get('name', obj_id),
+            'predicate': rel.get('predicate', ''),
+            'direction': 'outgoing',
+            'scope': rel.get('scope', ''),
+            'status': rel.get('status', ''),
+            'notes': rel.get('notes', ''),
+        })
+
+    # Incoming relationships (this entity is object)
+    for rel in idx['rels_by_object'].get(entity_id, []):
+        subj_id = rel.get('subject', '')
+        subj_entity = entity_by_id.get(subj_id, {})
+        related.append({
+            'entity_id': subj_id,
+            'entity_name': subj_entity.get('name', subj_id),
+            'predicate': rel.get('predicate', ''),
+            'direction': 'incoming',
+            'scope': rel.get('scope', ''),
+            'status': rel.get('status', ''),
+            'notes': rel.get('notes', ''),
+        })
+
+    return related
+
+
+# ─────────────────────────────────────────────
+# Topic filtering
+# ─────────────────────────────────────────────
+def filter_by_topic(context, topic):
+    """Boost relevance of context items matching the given topic.
+
+    Adds a 'topic_relevant' flag to queue items and interactions
+    that mention the topic.
+    """
+    if not topic:
+        return context
+
+    topic_lower = topic.lower()
+    topic_words = topic_lower.split()
+
+    # Tag queue items
+    for item in context.get('active_queue_items', []):
+        searchable = f"{item.get('title', '')} {item.get('queue', '')}".lower()
+        item['topic_relevant'] = any(w in searchable for w in topic_words)
+
+    # Tag interactions
+    for item in context.get('recent_interactions', []):
+        searchable = f"{item.get('subject', '')} {item.get('summary', '')}".lower()
+        item['topic_relevant'] = any(w in searchable for w in topic_words)
+
+    # Tag related entities
+    for item in context.get('related_entities', []):
+        searchable = f"{item.get('entity_name', '')} {item.get('scope', '')} {item.get('notes', '')}".lower()
+        item['topic_relevant'] = any(w in searchable for w in topic_words)
+
+    return context
+
+
+# ─────────────────────────────────────────────
+# Main retrieval function
+# ─────────────────────────────────────────────
+def retrieve_context(recipient, topic=None):
+    """Retrieve full pre-draft context for a recipient.
+
+    Args:
+        recipient: Name or email of the person to look up.
+        topic: Optional topic to filter/boost relevant items.
+
+    Returns:
+        dict with full context, or None if recipient not found.
+    """
+    t0 = time.time()
+
+    # 1. Find entity in index
+    entity = lookup_entity(recipient)
+    if entity is None:
+        return None
+
+    entity_id = entity.get('id', '')
+    entity_name = entity.get('name', '')
+
+    # 2. Classify relationship
+    rel_info = classify_relationship(entity_id)
+
+    # 3. Load user profile
+    profile = load_user_profile(entity)
+
+    # 4. Extract key profile fields
+    standing_instructions = []
+    communication_prefs = {}
+    last_interaction = None
+    interaction_summary_notes = ''
+
+    if profile:
+        si = profile.get('standing_instructions', [])
+        if isinstance(si, list):
+            standing_instructions = si
+        elif isinstance(si, str) and si.strip() in ('[]', ''):
+            standing_instructions = []
+        else:
+            standing_instructions = [si] if si else []
+        communication_prefs = profile.get('communication_preferences', {}) or {}
+        isummary = profile.get('interaction_summary', {}) or {}
+        last_interaction = isummary.get('last_interaction')
+        interaction_summary_notes = str(isummary.get('notes', '') or '').strip()
+
+    # 5. Scan queues for active items about this person
+    slug = None
+    if entity_id and ':' in entity_id:
+        slug = entity_id.split(':')[1]
+    queue_items = scan_queues_for_person(entity_name, entity_id, slug)
+
+    # 6. Get recent interaction history
+    interactions = get_recent_interactions(entity)
+
+    # 7. Get related entities
+    related = get_related_entities(entity_id)
+
+    # 8. Build context object
+    context = {
+        'recipient': {
+            'name': entity_name,
+            'entity_id': entity_id,
+            'type': entity.get('type', ''),
+            'role': entity.get('primary_role', ''),
+            'company': entity.get('primary_company', ''),
+            'email': entity.get('email', ''),
+            'timezone': entity.get('timezone', ''),
+            'notes': entity.get('notes', ''),
+        },
+        'relationship': {
+            'type': rel_info['relationship_type'],
+            'is_internal': rel_info['is_internal'],
+            'company_relationships': [
+                {
+                    'predicate': r.get('predicate', ''),
+                    'object': r.get('object', ''),
+                    'status': r.get('status', ''),
+                    'scope': r.get('scope', ''),
+                    'notes': r.get('notes', ''),
+                }
+                for r in rel_info['relationships_to_northwind']
+            ],
+        },
+        'communication': {
+            'preferences': communication_prefs,
+            'standing_instructions': standing_instructions,
+            'last_interaction': str(last_interaction) if last_interaction else None,
+            'interaction_notes': interaction_summary_notes,
+        },
+        'related_entities': related,
+        'active_queue_items': queue_items,
+        'recent_interactions': interactions,
+        'topic': topic,
+        'retrieval_time_ms': round((time.time() - t0) * 1000, 1),
+    }
+
+    # 9. Apply topic filtering if provided
+    if topic:
+        context = filter_by_topic(context, topic)
+
+    return context
+
+
+# ─────────────────────────────────────────────
+# Brief format — concise summary for prompt injection
+# ─────────────────────────────────────────────
+def format_brief(context):
+    """Format context as a 3-5 line summary for prompt injection.
+
+    Returns a string.
+    """
+    if context is None:
+        return "RECIPIENT NOT FOUND — no entity data available. Verify recipient identity before drafting."
+
+    r = context['recipient']
+    rel = context['relationship']
+    comm = context['communication']
+
+    lines = []
+
+    # Line 1: Identity + relationship
+    rel_label = rel['type'].replace('_', ' ')
+    company_name = r.get('company', '')
+    if company_name and ':' in company_name:
+        # Resolve company entity id to name
+        idx = load_entity_index()
+        for e in idx['entities']:
+            if isinstance(e, dict) and e.get('id') == company_name:
+                company_name = e.get('name', company_name)
+                break
+    role_str = f"{r['role']}, {company_name}" if r['role'] and company_name else r['role'] or ''
+    lines.append(f"RECIPIENT: {r['name']} — {role_str} [{rel_label}]")
+
+    # Line 2: Communication preferences + standing instructions
+    prefs = comm.get('preferences', {})
+    tone = prefs.get('tone', prefs.get('voice', ''))
+    channel = prefs.get('preferred_channel', prefs.get('channel_preference', ''))
+    pref_parts = []
+    if tone:
+        pref_parts.append(f"tone: {tone}")
+    if channel:
+        pref_parts.append(f"prefers: {channel}")
+    instructions = comm.get('standing_instructions', [])
+    if instructions and isinstance(instructions, list) and len(instructions) > 0:
+        pref_parts.append(f"instructions: {'; '.join(str(i) for i in instructions[:2])}")
+    if pref_parts:
+        lines.append(f"COMMS: {', '.join(pref_parts)}")
+
+    # Line 3: Active items
+    active = context.get('active_queue_items', [])
+    topic = context.get('topic', '')
+    if topic:
+        topic_items = [i for i in active if i.get('topic_relevant')]
+        if topic_items:
+            lines.append(f"ACTIVE ({topic}): {len(topic_items)} item(s) — " +
+                         '; '.join(i['title'][:60] for i in topic_items[:3]))
+        elif active:
+            lines.append(f"ACTIVE: {len(active)} item(s) — " +
+                         '; '.join(i['title'][:60] for i in active[:3]))
+    elif active:
+        lines.append(f"ACTIVE: {len(active)} item(s) — " +
+                     '; '.join(i['title'][:60] for i in active[:3]))
+
+    # Line 4: Last interaction
+    last = comm.get('last_interaction')
+    interactions = context.get('recent_interactions', [])
+    # Find the most recent interaction with a non-empty timestamp
+    latest_with_ts = None
+    for ix in interactions:
+        if ix.get('timestamp'):
+            latest_with_ts = ix
+            break
+    if latest_with_ts:
+        channel = latest_with_ts.get('channel', '')
+        summary = latest_with_ts.get('summary', '') or latest_with_ts.get('subject', '')
+        if summary and len(summary) > 80:
+            summary = summary[:77] + '...'
+        lines.append(f"LAST CONTACT: {latest_with_ts['timestamp']} via {channel} — {summary}")
+    elif interactions:
+        # Have interactions but none with timestamps — use first one's subject
+        latest = interactions[0]
+        channel = latest.get('channel', '')
+        summary = latest.get('summary', '') or latest.get('subject', '')
+        if summary and len(summary) > 80:
+            summary = summary[:77] + '...'
+        if summary:
+            lines.append(f"LAST CONTACT: via {channel} — {summary}")
+    elif last:
+        lines.append(f"LAST CONTACT: {last}")
+
+    # Line 5: Key notes/warnings
+    notes = r.get('notes', '') or ''
+    interaction_notes = comm.get('interaction_notes', '') or ''
+    # Prefer interaction notes for internal people (richer context)
+    note_text = interaction_notes if (rel['is_internal'] and interaction_notes) else notes
+    if not note_text:
+        note_text = interaction_notes or notes
+    if note_text:
+        # Take first sentence if long
+        if len(note_text) > 100:
+            first_sentence = note_text.split('.')[0].strip()
+            if first_sentence and len(first_sentence) < 100:
+                note_text = first_sentence + '.'
+            else:
+                note_text = note_text[:97] + '...'
+        lines.append(f"NOTE: {note_text}")
+
+    return '\n'.join(lines)
+
+
+# ─────────────────────────────────────────────
+# CLI entry point
+# ─────────────────────────────────────────────
+def main():
+    parser = argparse.ArgumentParser(
+        description='Pre-draft fact retrieval — retrieve entity context before composing messages.'
+    )
+    parser.add_argument('--recipient', required=True,
+                        help='Recipient name or email address')
+    parser.add_argument('--topic', default=None,
+                        help='Optional topic to filter/boost relevant context')
+    parser.add_argument('--format', dest='output_format', default='json',
+                        choices=['json', 'brief'],
+                        help='Output format: json (full) or brief (3-5 line summary)')
+
+    args = parser.parse_args()
+
+    try:
+        context = retrieve_context(args.recipient, args.topic)
+
+        if context is None:
+            if args.output_format == 'brief':
+                print(format_brief(None))
+            else:
+                print(json.dumps({
+                    'status': 'not_found',
+                    'recipient_query': args.recipient,
+                    'message': f'No entity found matching "{args.recipient}"',
+                }, indent=2))
+            sys.exit(1)
+
+        if args.output_format == 'brief':
+            print(format_brief(context))
+        else:
+            # Sanitize for JSON serialization
+            print(json.dumps(context, indent=2, default=str))
+
+        sys.exit(0)
+
+    except Exception as e:
+        print(json.dumps({
+            'status': 'error',
+            'message': str(e),
+        }), file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == '__main__':
+    main()