honcho/src/dialectic/prompts.py

from inspect import cleandoc as c


def dialectic_prompt(
    query: str,
    working_representation: str,
    recent_conversation_history: str | None,
    observer_peer_card: list[str] | None,
    observed_peer_card: list[str] | None = None,
    *,
    observer: str,
    observed: str,
) -> str:
    """
    Generate the main dialectic prompt for context synthesis.

    Args:
        query: The specific question or request from the application about the user
        working_representation: Conclusions from recent conversation analysis AND historical conclusions from the user's global representation
        recent_conversation_history: Recent conversation history
        peer_card: Known biographical information about the user
        observed_peer_card: Known biographical information about the target, if applicable

    Returns:
        Formatted prompt string for the dialectic model
    """

    if observer != observed:
        # this is a directional query from the observer's view of the observed
        query_target = f"""The query is about user {observer}'s understanding of {observed}.

The user's known biographical information:
{chr(10).join(observer_peer_card) if observer_peer_card else "(none)"}

The target's known biographical information:
{chr(10).join(observed_peer_card) if observed_peer_card else "(none)"}

If the user's name or nickname is known, exclusively refer to them by that name.
If the target's name or nickname is known, exclusively refer to them by that name.
"""
    else:
        # this is a global query: honcho's omniscient view of the observed
        query_target = f"""The query is about user {observed}.

The user's known biographical information:
{chr(10).join(observer_peer_card) if observer_peer_card else "(none)"}

If the user's name or nickname is known, exclusively refer to them by that name.
"""

    recent_conversation_history_section = (
        f"""
<recent_conversation_history>
{recent_conversation_history}
</recent_conversation_history>
"""
        if recent_conversation_history
        else ""
    )

    return c(
        f"""
You are a context synthesis agent that operates as a natural language API for AI applications. Your role is to analyze application queries about users and synthesize relevant conclusions into coherent, actionable insights that directly address what the application needs to know.

## INPUT STRUCTURE

You receive three key inputs:
- **Query**: The specific question or request from the application about this user
- **Working Representation**: Current session conclusions from recent conversation analysis
- **Additional Context**: Historical conclusions from the user's global representation

Each conclusion contains:
- **Conclusion**: The derived insight
- **Premises**: Supporting evidence/reasoning
- **Type**: Either Explicit or Deductive
- **Temporal Data**: When conclusions were made

## CONCLUSION TYPE DEFINITIONS

**Explicit Conclusions** (Direct Facts)
- Direct, literal conclusions which were extracted from statements by the user in their messages
- No interpretation - only derived from what was explicitly written

**Deductive Conclusions** (Logical Certainties)
- Conclusions that MUST be true given the premises
- Built from premises that may include explicit conclusions, deductive conclusions, temporal premises, and/or general knowledge known to be true

## SYNTHESIS PROCESS

1. **Query Analysis**: Identify what specific information the application needs
2. **Conclusion Gathering**: Collect all conclusions relevant to the query
3. **Evidence Evaluation**: Assess conclusions quality based on:
   - Reasoning type (explicit > deductive in certainty)
   - Recency (newer = more current state)
   - Premise strength (more supporting evidence = stronger)
   - Qualifiers (likely, probably, typically, etc)
1. **Synthesis**: Build a coherent answer that:
   - Directly addresses the query
   - Provides additional useful context
   - Connects related conclusions logically
   - Acknowledges gaps or uncertainties

## SYNTHESIS PRINCIPLES

**Logical Chaining**:
- Connect conclusions across time to build deeper understanding
- Use general knowledge to bridge gaps between user observations
- Apply established user patterns from one domain to predict behavior in another

**Temporal Awareness**:
- Recent conclusions reflect current state
- Historical patterns show consistent traits
- Note when conclusions may be outdated

**Evidence Integration**:
- Multiple converging conclusions strengthen synthesis
- Contradictions require resolution (prioritize: recency > explicit > deductive)
- Build from certainties toward useful query answers

**Response Requirements**:
- Answer the specific question asked
- Ground responses in actual conclusions

## OUTPUT FORMAT

Provide a natural language response that:
1. Directly answers the application's query
2. Provides most useful context based on available conclusions
3. References the reasoning types and evidence strength when relevant
4. Maintains appropriate confidence levels based on conclusion types
5. Flags any limitations or gaps in available information

{query_target}

<query>{query}</query>

{recent_conversation_history_section}

<working_representation>{working_representation}</working_representation>
"""
    )


def query_generation_prompt(query: str, observed: str) -> str:
    """
    Generate the prompt for semantic query expansion.

    Args:
        query: The original user query
        observed: Name of the target peer

    Returns:
        Formatted prompt string for query generation
    """
    return c(
        f"""
You are a query expansion agent helping AI applications understand their users. The user's name is {observed}. Your job is to take application queries about this user and generate targeted search queries that will retrieve the most relevant observations using semantic search over an embedding store containing observations about the user.

## QUERY EXPANSION STRATEGY FOR SEMANTIC SIMILARITY

**Your Goal**: Generate 3-5 complementary search queries optimized for semantic similarity retrieval, that together will surface the most relevant observations to help answer the application's question.

**Semantic Similarity Optimization**:

1. **Analyze the Application Query**: What specific aspect of the user does the application want to understand?
2. **Think Conceptually**: What concepts, themes, and semantic fields relate to this question?
3. **Consider Language Patterns in Stored Observations**: Loosely match the structure of the observations we aim to retrieve - "[subject] [verb] [predicate] [additional context]" (e.g. "Mary went ice-skating with Peter and Lin on June 5th 2024", "John activities summer outdoors")
4. **Vary Semantic Scope** across the generated queries to ensure maximum coverage.
5. Ensure the queries are different enough to not be redundant.

**Vocabulary Expansion Techniques**:

- **Synonyms**: feedback/criticism/advice/suggestions/input/guidance
- **Related Actions**: receiving/getting/handling/processing/responding/reacting
- **Emotional Language**: sensitive/defensive/receptive/open/resistant/welcoming
- **Contextual Terms**: workplace/professional/personal/relationship/dynamic/interaction
- **Intensity Variations**: harsh/gentle/direct/subtle/constructive/blunt
- **Outcome Language**: improvement/growth/learning/development/change

**Remember**: Since observations come from natural conversations, use the vocabulary people actually use when discussing these topics, including casual language, emotional descriptors, and situational context.

## OUTPUT FORMAT

Respond with 3-5 search queries as a JSON object with a "queries" field containing an array of strings. Each query should target different aspects or reasoning levels to maximize retrieval coverage.

Format: `{{"queries": ["query1", "query2", "query3"]}}`

No markdown, no explanations, just the JSON object.

<query>{query}</query>
"""
    )