Session Handoff

from dakera import DakeraClient
from datetime import datetime
import json

client = DakeraClient(base_url="http://localhost:3300", api_key="dk-...")

class HandoffSession:
    """
    Manages a session with proper handoff support.
    Tracks context memories and generates structured handoff summaries.
    """

    def __init__(self, agent_id: str, user_id: str, channel: str = "webchat"):
        self.agent_id = agent_id
        self.user_id = user_id
        self.channel = channel
        self.session_id = None
        self.context_memories = []
        self.attempted_resolutions = []
        self.client = client

    def start(self) -> str:
        session = self.client.start_session(
            agent_id=self.agent_id,
            metadata={"user_id": self.user_id, "channel": self.channel}
        )
        self.session_id = session["id"]
        return self.session_id

    def store_event(self, content: str, event_type: str, importance: float = 0.75):
        """Store a conversation event with session binding."""
        mem = self.client.store_memory(
            agent_id=self.agent_id,
            content=content,
            importance=importance,
            session_id=self.session_id,
            tags=["event", event_type]
        )
        self.context_memories.append({"id": mem["id"], "content": content, "type": event_type})
        return mem

    def record_attempt(self, action: str, outcome: str):
        """Track what was tried and what happened."""
        record = f"Tried: {action}. Outcome: {outcome}."
        self.attempted_resolutions.append(record)
        return self.store_event(record, "attempted-resolution", importance=0.7)

    def handoff(self, target_agent: str, reason: str, sentiment: str,
                user_goal: str, recommended_action: str, urgency: str = "normal") -> dict:
        """
        Execute handoff sequence:
        1. Store structured summary at importance 1.0
        2. End session with handoff metadata
        Returns handoff data for the target agent
        """
        attempts_text = " ".join(self.attempted_resolutions) if self.attempted_resolutions else "No prior attempts."

        summary_content = (
            f"HANDOFF SUMMARY [{urgency.upper()}]: "
            f"User goal: {user_goal}. "
            f"Situation: {attempts_text} "
            f"User sentiment: {sentiment}. "
            f"Recommended next action: {recommended_action}."
        )

        # Store at importance 1.0 — will always surface first on recall
        summary_mem = self.client.store_memory(
            agent_id=self.agent_id,
            content=summary_content,
            importance=1.0,
            session_id=self.session_id,
            tags=["handoff", "session-summary", f"priority:{urgency}", f"target:{target_agent}"]
        )

        # End the session with handoff metadata
        self.client.end_session(
            session_id=self.session_id,
            metadata={
                "handoff_to": target_agent,
                "escalation_reason": reason,
                "handoff_memory_id": summary_mem["id"],
                "urgency": urgency,
                "timestamp": datetime.utcnow().isoformat()
            }
        )

        return {
            "source_session_id": self.session_id,
            "handoff_memory_id": summary_mem["id"],
            "target_agent": target_agent,
            "urgency": urgency
        }


class IncomingSession:
    """Target agent session — loads handoff context immediately."""

    def __init__(self, agent_id: str, handler_id: str, handoff_data: dict):
        self.agent_id = agent_id
        self.handler_id = handler_id
        self.handoff_data = handoff_data
        self.session_id = None
        self.client = client

    def start_and_load_context(self, query: str = "current issue and situation", top_k: int = 8):
        """Start session and immediately recall handoff context."""
        session = self.client.start_session(
            agent_id=self.agent_id,
            metadata={
                "handler": self.handler_id,
                "handoff_from": self.handoff_data["source_session_id"],
                "channel": "webchat"
            }
        )
        self.session_id = session["id"]

        # Recall context — handoff summary (importance 1.0) surfaces first
        context = self.client.recall(
            agent_id=self.agent_id,
            query=query,
            top_k=top_k
        )

        return context

    def get_opening_message(self, context: list) -> str:
        """Generate an opening message that acknowledges context continuity."""
        if not context:
            return "How can I help you today?"

        handoff_summary = context[0]  # Highest importance memory = handoff summary
        content = handoff_summary.get("content", "")

        # Extract key facts for the opening message
        if "HANDOFF SUMMARY" in content:
            return (
                "I've just been briefed on your situation — I have the full context "
                "from your previous conversation. Let me take it from here and get this resolved for you."
            )
        return "I've reviewed your case history. Let me pick up where we left off."


# ===== USAGE: Customer Support Escalation =====

# BOT HANDLES INITIAL CONVERSATION
bot_session = HandoffSession(
    agent_id="support-bot",
    user_id="user-u_9k3m",
    channel="webchat"
)
bot_session.start()

# Store events as conversation unfolds
bot_session.store_event(
    "User: Maria Santos reports unauthorized charge $89.99 on Jan 15. Transaction: TXN-88291.",
    event_type="issue-report",
    importance=0.85
)

bot_session.store_event(
    "User confirmed account ownership. Identity verified.",
    event_type="verification",
    importance=0.6
)

# Record resolution attempts
bot_session.record_attempt(
    action="Standard refund flow for TXN-88291",
    outcome="FAILED — transaction exceeds 30-day refund window"
)
bot_session.record_attempt(
    action="Offered $90 account credit as alternative",
    outcome="REJECTED — user insists on full refund only"
)

bot_session.store_event(
    "User expressed frustration: 'This is the third time I am calling about this.'",
    event_type="sentiment",
    importance=0.9
)

# BOT TRIGGERS ESCALATION
handoff_data = bot_session.handoff(
    target_agent="human-agent",
    reason="refund-window-exceeded-supervisor-required",
    sentiment="High frustration — 3rd contact, previous resolution attempts failed",
    user_goal="Full refund of $89.99 unauthorized charge TXN-88291",
    recommended_action="Supervisor override refund. Mention 5-min ETA already committed.",
    urgency="high"
)

print(f"Handoff initiated. Session: {handoff_data['source_session_id']}")

# HUMAN AGENT RECEIVES HANDOFF
human_session = IncomingSession(
    agent_id="support-bot",
    handler_id="agent-sarah",
    handoff_data=handoff_data
)

context = human_session.start_and_load_context(
    query="billing dispute refund situation and what was tried",
    top_k=8
)

print(f"
Context loaded ({len(context)} memories):")
for mem in context:
    print(f"  [{mem['importance']:.2f}] {mem['content'][:100]}")

opening = human_session.get_opening_message(context)
print(f"
Agent opening: "{opening}"")

import { DakeraClient } from '@dakera-ai/dakera';

const client = new DakeraClient({ baseUrl: 'http://localhost:3300', apiKey: 'dk-...' });

interface HandoffData {
  sourceSessionId: string;
  handoffMemoryId: string;
  targetAgent: string;
  urgency: string;
}

// ===== SOURCE AGENT (Bot) =====

// 1. Start bot session
const botSession = await client.listSessions(); // or start via startSession API
const sessionId = 'sess_bot_7f2a'; // from start session response

// 2. Store context events during conversation
await client.storeMemory('support-bot', {
  content: 'User Maria Santos disputes $89.99 charge TXN-88291 from Jan 15. Not authorized.',
  importance: 0.85,
  tags: ['billing', 'dispute', 'unauth-charge']
});

await client.storeMemory('support-bot', {
  content: 'Standard refund flow failed: transaction exceeds 30-day window.',
  importance: 0.75,
  tags: ['attempted-resolution', 'failed']
});

await client.storeMemory('support-bot', {
  content: 'Credit offer ($90) rejected. User insists on refund only. Third contact about this issue.',
  importance: 0.85,
  tags: ['attempted-resolution', 'sentiment:frustrated']
});

// 3. Generate and store handoff summary at maximum importance
const summaryMem = await client.storeMemory('support-bot', {
  content: [
    'HANDOFF SUMMARY [HIGH]:',
    'User: Maria Santos (user-u_9k3m).',
    'Goal: Full refund of $89.99 unauthorized charge TXN-88291 (Jan 15).',
    'Tried: standard refund (30-day limit exceeded), credit offer (rejected).',
    'Sentiment: high frustration, 3rd contact.',
    'Committed: escalation within 5 minutes.',
    'Action: supervisor override refund required.'
  ].join(' '),
  importance: 1.0,
  tags: ['handoff', 'session-summary', 'priority:high']
});

// 4. End bot session with handoff metadata
await client.sessionMemories(sessionId); // confirm memories stored
// end_session called via API

const handoffData: HandoffData = {
  sourceSessionId: sessionId,
  handoffMemoryId: summaryMem.id,
  targetAgent: 'human-sarah',
  urgency: 'high'
};

// ===== TARGET AGENT (Human) =====

// 5. Start new session linked to original
const humanSession = await client.listSessions(); // start human session

// 6. Recall context — handoff summary surfaces first due to importance: 1.0
const context = await client.recall(
  'support-bot',
  'billing dispute refund situation attempted resolutions',
  { top_k: 8 }
);

console.log(`Context loaded (${context.length} memories):`);
context.forEach(mem => {
  console.log(`  [${mem.importance.toFixed(2)}] ${mem.content.substring(0, 100)}`);
});

// First memory is always the handoff summary
const handoffSummary = context[0];
console.log(`
Handoff summary: ${handoffSummary.content}`);

// 7. Human agent acknowledges continuity
const opening = handoffSummary.content.includes('HANDOFF SUMMARY')
  ? "I have the full context from your previous conversation. I'm going to resolve this for you now."
  : "Let me pull up your case.";

console.log(`Agent opening: "${opening}"`);

use dakera_rs::{Client, StoreMemoryRequest, RecallRequest};

let client = Client::new("http://localhost:3300", "dk-...");

// ===== SOURCE AGENT =====

// Store conversation context
client.store_memory("support-bot", StoreMemoryRequest {
    content: "User reports $89.99 unauthorized charge TXN-88291 on Jan 15.".into(),
    importance: Some(0.85),
    tags: vec!["billing".into(), "dispute".into()],
    ..Default::default()
}).await?;

client.store_memory("support-bot", StoreMemoryRequest {
    content: "Standard refund failed: 30-day limit exceeded. Credit offer rejected.".into(),
    importance: Some(0.75),
    tags: vec!["attempted-resolution".into(), "failed".into()],
    ..Default::default()
}).await?;

client.store_memory("support-bot", StoreMemoryRequest {
    content: "User: frustrated, 3rd contact about this charge.".into(),
    importance: Some(0.9),
    tags: vec!["sentiment".into(), "high-priority".into()],
    ..Default::default()
}).await?;

// Store handoff summary at importance 1.0
let summary = client.store_memory("support-bot", StoreMemoryRequest {
    content: concat!(
        "HANDOFF SUMMARY [HIGH]: User Maria Santos disputes $89.99 TXN-88291 Jan 15. ",
        "Standard refund failed (30d limit). Credit rejected. Third contact. ",
        "Sentiment: high frustration. Action: supervisor override refund required. ",
        "Bot committed: escalation within 5 minutes."
    ).into(),
    importance: Some(1.0),
    tags: vec!["handoff".into(), "session-summary".into(), "priority:high".into()],
    ..Default::default()
}).await?;

println!("Handoff summary stored: {}", summary.id);

// ===== TARGET AGENT =====

// Recall — handoff summary surfaces first (importance 1.0)
let context = client.recall("support-bot", RecallRequest {
    query: "billing dispute refund situation and resolution attempts".into(),
    top_k: Some(8),
    ..Default::default()
}).await?;

println!("Context memories: {}", context.len());
for mem in &context {
    println!("  [{:.2}] {}", mem.importance, &mem.content[..mem.content.len().min(100)]);
}

if let Some(summary) = context.first() {
    println!("
Handoff summary: {}", summary.content);
}

client := dakera.NewClient("http://localhost:3300", "dk-...")
ctx := context.Background()

// ===== SOURCE AGENT =====

// Store context events during bot conversation
client.StoreMemory(ctx, "support-bot", dakera.StoreMemoryRequest{
    Content:    "User Maria Santos disputes $89.99 charge TXN-88291 from Jan 15. Not authorized.",
    Importance: 0.85,
    Tags:       []string{"billing", "dispute"},
})

client.StoreMemory(ctx, "support-bot", dakera.StoreMemoryRequest{
    Content:    "Standard refund failed: 30-day window exceeded. Credit offer rejected by user.",
    Importance: 0.75,
    Tags:       []string{"attempted-resolution", "failed"},
})

client.StoreMemory(ctx, "support-bot", dakera.StoreMemoryRequest{
    Content:    "User frustrated: third contact about this charge. High priority.",
    Importance: 0.9,
    Tags:       []string{"sentiment", "high-priority"},
})

// Handoff summary at maximum importance
summaryContent := strings.Join([]string{
    "HANDOFF SUMMARY [HIGH]:",
    "User: Maria Santos. Goal: refund $89.99 TXN-88291 Jan 15.",
    "Tried: standard refund (30d limit failed), credit ($90 rejected).",
    "3rd contact. High frustration.",
    "Action: supervisor override required. Bot committed 5-min ETA.",
}, " ")

summary, _ := client.StoreMemory(ctx, "support-bot", dakera.StoreMemoryRequest{
    Content:    summaryContent,
    Importance: 1.0,
    Tags:       []string{"handoff", "session-summary", "priority:high"},
})
fmt.Printf("Handoff summary ID: %s
", summary.ID)

// ===== TARGET AGENT =====

// Recall context — handoff summary (importance 1.0) always first
memories, _ := client.Recall(ctx, "support-bot", dakera.RecallRequest{
    Query: "billing dispute refund situation attempts",
    TopK:  8,
})

fmt.Printf("Context loaded: %d memories
", len(memories))
for _, mem := range memories {
    content := mem.Content
    if len(content) > 100 {
        content = content[:100]
    }
    fmt.Printf("  [%.2f] %s
", mem.Importance, content)
}

if len(memories) > 0 {
    fmt.Printf("
Handoff summary: %s
", memories[0].Content)
}