Changelog - 2025-12-05 (#1)

Disambiguation Exclusion List: Explicit Wrong-Entity Filtering

Overview

This release adds explicit wrong-entity exclusion to the disambiguation system. Deal configurations can now specify a disambiguation array of URLs/domains that belong to different companies with similar names. Research agents will discard data from these sources, preventing entity confusion.

The Problem: Entity Confusion

When generating memos for companies with common names, LLMs and search engines often return data about the wrong company. This isn't hallucination—it's retrieving accurate data about a different entity.

Real Example: Reson8

Running the memo orchestrator on "Reson8" (a DNA/frequency wellness company at reson8.xyz) pulled in data from:

The existing disambiguation system (company URL, description, notes) wasn't strong enough to prevent this confusion.

Solution: Explicit Exclusion List

New JSON Field: disambiguation

Add a disambiguation array to deal configuration files listing URLs of wrong entities to exclude:

{
  "name": "Reson8",
  "description": "Reson8 uses wave frequencies to heal DNA damage and improve health.",
  "url": "https://reson8.xyz/",
  "stage": "Pre-Seed",
  "type": "direct",
  "mode": "justify",
  "deck": "inputs/2025-11_Reason8--Deck.pdf",
  "notes": "Focus on the science and team credentials.",
  "disambiguation": [
    "https://www.reson8.group/",
    "https://www.reson8media.com/",
    "https://reson8sms.com/"
  ]
}

How It Works

1. Config Loading: main.py reads the disambiguation array

2. Domain Extraction: URLs are parsed to extract domains (e.g., https://reson8.group/ → reson8.group)

3. State Propagation: Domains stored in disambiguation_excludes state field

4. Prompt Injection: Research agents add exclusion block to LLM prompts:

EXCLUDED ENTITIES - DO NOT USE DATA FROM THESE DOMAINS:
- reson8.group (WRONG company, different entity)
- reson8media.com (WRONG company, different entity)
- reson8sms.com (WRONG company, different entity)

If you find information from these domains, DISCARD IT completely.

Disambiguation System: Complete Architecture

The disambiguation system now has three layers:

Layer 1: Positive Identification (Existing)

{
  "url": "https://reson8.xyz/",
  "description": "Uses wave frequencies to heal DNA damage..."
}

Tells agents: "This IS the correct company"

Layer 2: Research Guidance (Existing)

{
  "notes": "Focus on team backgrounds and scientific validation..."
}

Tells agents: "Research these specific aspects"

Layer 3: Explicit Exclusion (NEW)

{
  "disambiguation": [
    "https://www.reson8.group/",
    "https://www.reson8media.com/"
  ]
}

Tells agents: "These are WRONG companies, discard their data"

Prompt Integration

Research Agent (src/agents/research_enhanced.py)

# Build exclusion block from disambiguation array
exclusion_block = ""
if disambiguation_excludes and len(disambiguation_excludes) > 0:
    exclusion_block = "\nEXCLUDED ENTITIES - DO NOT USE DATA FROM THESE DOMAINS:\n"
    for domain in disambiguation_excludes:
        exclusion_block += f"- {domain} (WRONG company, different entity)\n"
    exclusion_block += "\nIf you find information from these domains, DISCARD IT completely.\n"

# Add to disambiguation context
disambiguation_context += exclusion_block

Section Researcher (src/agents/perplexity_section_researcher.py)

disambiguation_block = f"""
CRITICAL - ENTITY DISAMBIGUATION:
There may be multiple companies named "{company_name}". You MUST research the CORRECT company:
- Company website: {company_url}
- Description: {company_description}

EXCLUDED DOMAINS (WRONG COMPANIES):
{exclusion_list}

DISAMBIGUATION RULES:
1. ONLY use sources that reference THIS specific company
2. If you find data for a DIFFERENT company with the same name, DISCARD IT
3. If a source is from an EXCLUDED DOMAIN, ignore it completely
4. If unsure, state "Data not verified for this entity"
"""

State Schema Changes

MemoState Addition

# In src/state.py
class MemoState(TypedDict):
    # ... existing fields ...
    disambiguation_excludes: List[str]  # NEW: domains to exclude

State Propagation Flow

{Deal}.json
    │
    │  "disambiguation": ["https://reson8.group/", ...]
    │
    ▼
main.py (parse URLs → extract domains)
    │
    │  disambiguation_excludes: ["reson8.group", "reson8media.com", ...]
    │
    ▼
MemoState
    │
    ▼
research_enhanced.py → perplexity_section_researcher.py → improve_section.py
    │
    │  Build exclusion block, add to prompts
    │
    ▼
LLM discards data from excluded domains

Example Configurations

High-Risk Name: Multiple Known Conflicts

{
  "name": "Mercury",
  "description": "Business banking platform for startups",
  "url": "https://mercury.com",
  "disambiguation": [
    "https://mercuryinsurance.com/",
    "https://mrcy.com/",
    "https://mercurysystems.com/",
    "https://mercurygate.com/"
  ]
}

Moderate Risk: Similar Startup Names

{
  "name": "Sava",
  "description": "AI-powered trust administration platform",
  "url": "https://www.savahq.com",
  "disambiguation": [
    "https://sava.ai",
    "https://www.savatechnologies.com"
  ]
}

Low Risk: Unique Name (No Exclusions Needed)

{
  "name": "UniqueStartupXYZ",
  "description": "Novel product in niche market",
  "url": "https://uniquestartupxyz.com"
}

Files Changed

Specification Updates

Configuration Updates

Implementation Status

Completed (Spec)

• Updated disambiguation spec with exclusion list design

• Added disambiguation field to Reson8 config

• Documented state propagation flow

• Documented prompt integration patterns

Completed (Code)

• main.py - Parse disambiguation array, populate disambiguation_excludes in state

• src/state.py - Add disambiguation_excludes: List[str] to MemoState

• src/workflow.py - Pass disambiguation_excludes through generate_memo() to state

• src/agents/research_enhanced.py - Build and inject exclusion block

• src/agents/perplexity_section_researcher.py - Add exclusion block to section queries

• cli/improve_section.py - Add exclusion block to improvement prompts

Testing Protocol

Test Case: Reson8 with Exclusions

Config:

{
  "name": "Reson8",
  "url": "https://reson8.xyz/",
  "disambiguation": [
    "https://www.reson8.group/",
    "https://www.reson8media.com/",
    "https://reson8sms.com/"
  ]
}

Expected Results:

• No citations from reson8.group, reson8media.com, reson8sms.com

• No social profiles from wrong entities (no x.com/Reson8SMS)

• No Crunchbase data from reson8-asia

• All research focused on reson8.xyz entity

Validation Command:

# Check for wrong-entity contamination in final draft
grep -i "reson8.group\|reson8media\|reson8sms\|reson8-asia" \
  io/dark-matter/deals/Reson8/outputs/Reson8-v*/4-final-draft.md

# Should return no results

Related Documentation

• context-vigilance/Disambiguation-Management-across-Agents.md - Full disambiguation architecture

• context-vigilance/Anti-Hallucination-Fact-Checker-Agent.md - Fact-checking integration

• context-vigilance/issue-resolution/Preventing-Hallucinations-in-Memo-Generation.md - Hallucination prevention

Contributors

Design and specification by Claude Code (Anthropic) with user guidance.