CONVERSATION_HISTORY.md

Conversation History Feature

Overview

The backend now supports multi-turn conversations with persistent history across requests. Each conversation is tracked using a unique session_id.

Features

• ✅ Session-based conversation tracking
• ✅ Automatic session cleanup (1 hour timeout by default)
• ✅ Message history trimming (max 20 messages per session)
• ✅ Works with /ask, /ask_stream, and /code_assist endpoints
• ✅ History management endpoints

How to Use

1. Starting a Conversation (without session_id)

The backend will automatically create a new session:

curl -X POST http://127.0.0.1:7860/ask \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Hello, can you help me write a Python function?",
    "metadata": {"skill": "moderate_learner", "emotion": "neutral"}
  }'

Response includes session_id:

{
  "reply": "I'd be happy to help...",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

2. Continuing a Conversation (with session_id)

Pass the session_id to continue the conversation:

curl -X POST http://127.0.0.1:7860/ask \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Can you make it handle edge cases?",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": {"skill": "moderate_learner", "emotion": "neutral"}
  }'

The AI will remember the previous context (the function you were discussing).

3. Streaming Responses

Works the same way with /ask_stream:

curl -X POST http://127.0.0.1:7860/ask_stream \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Explain how this works",
    "session_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

The session_id is sent as an SSE event: event: session\ndata: <session_id>\n\n

4. Code Assistance with History

Use /code_assist with conversation history:

curl -X POST http://127.0.0.1:7860/code_assist \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Write a function to calculate fibonacci",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": {"skill": "moderate_learner", "emotion": "curious"}
  }'

History Management Endpoints

Get Conversation History

curl -X POST http://127.0.0.1:7860/get_history \
  -H "Content-Type: application/json" \
  -d '{"session_id": "550e8400-e29b-41d4-a716-446655440000"}'

Response:

{
  "session_id": "550e8400-...",
  "messages": [
    {"role": "system", "content": "You are CodeMate..."},
    {"role": "user", "content": "Hello..."},
    {"role": "assistant", "content": "I'd be happy..."}
  ],
  "message_count": 5,
  "last_active": 1699459200.123
}

Clear History for a Session

curl -X POST http://127.0.0.1:7860/clear_history \
  -H "Content-Type: application/json" \
  -d '{"session_id": "550e8400-e29b-41d4-a716-446655440000"}'

Clear All Sessions

curl -X POST http://127.0.0.1:7860/clear_history \
  -H "Content-Type: application/json" \
  -d '{}'

List All Active Sessions

curl http://127.0.0.1:7860/list_sessions

Response:

{
  "sessions": [
    {
      "session_id": "550e8400-...",
      "message_count": 5,
      "last_active": 1699459200.123
    }
  ],
  "total_count": 1
}

Configuration (Environment Variables)

# Session timeout in seconds (default: 3600 = 1 hour)
HISTORY_TIMEOUT_SECONDS=3600

# Maximum messages per session (default: 20)
MAX_HISTORY_LENGTH=20

Architecture

Message Format

Messages follow the OpenAI chat format:

{
  "role": "system" | "user" | "assistant",
  "content": "message text"
}

Storage

• In-memory storage using defaultdict
• Auto-cleanup of old sessions when > 100 sessions exist
• Each session stores messages + last_active timestamp

Trimming

When a session exceeds MAX_HISTORY_LENGTH:

• System message is preserved
• Only recent messages are kept
• Ensures token limits aren't exceeded

Example Multi-Turn Conversation

# Turn 1
curl -X POST http://127.0.0.1:7860/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "Write a Python function to reverse a string"}'

# Response: {"reply": "Here's a function...", "session_id": "abc-123"}

# Turn 2 (AI remembers the function from Turn 1)
curl -X POST http://127.0.0.1:7860/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "Can you add error handling to it?", "session_id": "abc-123"}'

# Turn 3 (AI remembers both previous turns)
curl -X POST http://127.0.0.1:7860/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "Now make it work with unicode", "session_id": "abc-123"}'

Notes

• Sessions are stored in memory (cleared on server restart)
• For production, consider using Redis or a database
• The cache still works for identical first messages
• Conversation history is NOT cached (each message with history is unique)