163 lines
No EOL
13 KiB
Text
163 lines
No EOL
13 KiB
Text
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": "# Hindsight-OpenAI Tutorial\n\n**A drop-in replacement for the OpenAI Python client with automatic memory integration**\n\n## What is Hindsight-OpenAI?\n\n`hindsight-openai` is a transparent wrapper around the official OpenAI Python client that automatically:\n\n- 🧠 **Injects relevant memories** from your Hindsight system into conversations\n- 💾 **Stores conversation history** to Hindsight for future retrieval \n- 🔄 **Works seamlessly** with existing OpenAI code (just change the import)\n- ⚡ **Supports both sync and async** clients\n\n## Why Use It?\n\n### The Problem\n\nAI assistants typically have no memory of previous conversations. Each interaction starts fresh, requiring you to:\n- Repeat context manually\n- Copy-paste relevant information\n- Build custom RAG pipelines\n- Manage conversation history yourself\n\n### The Solution\n\nHindsight-OpenAI gives your AI **automatic long-term memory**:\n- Remembers past conversations\n- Recalls user preferences and facts\n- Maintains context across sessions\n- Zero code changes to your existing OpenAI usage\n\n## Prerequisites\n\n1. **Hindsight API server running** (see main Hindsight README)\n2. **OpenAI API key** or compatible API (Groq, OpenRouter, etc.)\n3. **Python >= 3.10**"
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": "## Setup\n\nFirst, let's set up our environment and configure Hindsight integration:"
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {
|
|
"jupyter": {
|
|
"is_executing": true
|
|
}
|
|
},
|
|
"outputs": [],
|
|
"source": "import os\nfrom hindsight_openai import configure, AsyncOpenAI\n\n# Set your API keys\n# Option 1: Use Groq (fast and free)\nGROQ_API_KEY = os.getenv(\"GROQ_API_KEY\", \"your-groq-api-key\")\nif not GROQ_API_KEY:\n raise (\"GROQ_API_KEY not set\") \n\n# Option 2: Use OpenAI\n# OPENAI_API_KEY = os.getenv(\"OPENAI_API_KEY\", \"sk-...\")\n\n# Configure Hindsight integration\nconfigure(\n hindsight_api_url=\"http://localhost:8888\", # Your Hindsight API server\n agent_id=\"tutorial-user\", # Unique ID for this user/agent\n store_conversations=True, # Auto-save conversations\n inject_memories=True, # Auto-inject relevant context\n)\n\nprint(\"✓ Hindsight configured successfully!\")\nprint(\"\")\nprint(\"NOTE: This tutorial uses AsyncOpenAI which works perfectly in Jupyter notebooks.\")\nprint(\"For regular Python scripts, you can use the sync OpenAI client instead.\")"
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": "## Example 1: Basic Usage (No Changes Needed!)\n\nUse the OpenAI client exactly as you normally would. Hindsight works transparently in the background."
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": "# Create client (using Groq's OpenAI-compatible API)\nclient = AsyncOpenAI(\n api_key=GROQ_API_KEY,\n base_url=\"https://api.groq.com/openai/v1\",\n)\n\n# First conversation - establish some facts\nprint(\"=== First Conversation ===\")\nresponse = await client.chat.completions.create(\n model=\"llama-3.1-8b-instant\",\n messages=[\n {\"role\": \"user\", \"content\": \"My name is Alice and I love Python programming!\"}\n ],\n)\n\nprint(f\"Assistant: {response.choices[0].message.content}\\n\")\nprint(\"→ This conversation is now stored in Hindsight!\")"
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": "## Example 2: Memory Injection in Action\n\nNow ask a question that requires remembering the previous conversation:"
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": "print(\"=== Second Conversation (with memory) ===\")\nresponse = await client.chat.completions.create(\n model=\"llama-3.1-8b-instant\",\n messages=[\n {\"role\": \"user\", \"content\": \"What's my name and what do I like?\"}\n ],\n)\n\nprint(f\"Assistant: {response.choices[0].message.content}\\n\")\nprint(\"→ Hindsight automatically injected relevant memories before this request!\")\nprint(\"→ The AI knew your name and preferences without you repeating them.\")"
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": "## How It Works\n\nBehind the scenes, Hindsight-OpenAI:\n\n### 1. **Memory Storage**\nAfter each API call:\n- Captures the full conversation context\n- Stores it in Hindsight's semantic memory system\n- Indexes it for fast retrieval\n\n### 2. **Memory Injection**\nBefore each API call:\n- Extracts the user's query\n- Searches Hindsight for relevant past conversations\n- Injects top memories as a system message\n\n### What Gets Sent to OpenAI\n\nWithout Hindsight:\n```python\nmessages = [\n {\"role\": \"user\", \"content\": \"What's my name?\"}\n]\n```\n\nWith Hindsight (automatic):\n```python\nmessages = [\n {\n \"role\": \"system\",\n \"content\": \"Relevant context from your memory:\\n\\n1. User's name is Alice\\n (Date: 2024-11-18)\\n (Type: world)\"\n },\n {\"role\": \"user\", \"content\": \"What's my name?\"}\n]\n```"
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Example 3: Multi-Turn Conversations\n",
|
|
"\n",
|
|
"Build up context over multiple interactions:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"# Conversation 1: Share a preference\n",
|
|
"print(\"=== Conversation 1: Sharing preferences ===\")\n",
|
|
"response = await client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[\n",
|
|
" {\"role\": \"user\", \"content\": \"I'm working on a machine learning project using PyTorch.\"}\n",
|
|
" ],\n",
|
|
")\n",
|
|
"print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
"\n",
|
|
"# Conversation 2: Different topic\n",
|
|
"print(\"=== Conversation 2: Different topic ===\")\n",
|
|
"response = await client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[\n",
|
|
" {\"role\": \"user\", \"content\": \"I prefer functional programming over OOP.\"}\n",
|
|
" ],\n",
|
|
")\n",
|
|
"print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
"\n",
|
|
"# Conversation 3: Ask for recommendations\n",
|
|
"print(\"=== Conversation 3: Getting personalized advice ===\")\n",
|
|
"response = await client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[\n",
|
|
" {\"role\": \"user\", \"content\": \"Can you recommend a good book for me based on what you know?\"}\n",
|
|
" ],\n",
|
|
")\n",
|
|
"print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
"print(\"→ The AI used your programming interests and preferences to make recommendations!\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": "## Example 4: Document Grouping\n\nGroup related conversations using `document_id`:"
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": "from hindsight_openai import configure\n\n# Configure with document ID for a specific project\nconfigure(\n hindsight_api_url=\"http://localhost:8888\",\n agent_id=\"tutorial-user\",\n document_id=\"ml-project-2024\", # All conversations tagged with this ID\n)\n\n# All these conversations will be grouped together\nconversations = [\n \"I'm using ResNet for image classification\",\n \"My dataset has 10,000 images\",\n \"Training accuracy is stuck at 65%\",\n]\n\nfor msg in conversations:\n response = await client.chat.completions.create(\n model=\"llama-3.1-8b-instant\",\n messages=[{\"role\": \"user\", \"content\": msg}],\n )\n print(f\"User: {msg}\")\n print(f\"Assistant: {response.choices[0].message.content}\\n\")\n\nprint(\"→ All these conversations are grouped under document 'ml-project-2024'\")"
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": "## Example 5: Async Support\n\nWorks perfectly with AsyncOpenAI for high-throughput applications:"
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": "from hindsight_openai import AsyncOpenAI\nimport asyncio\n\nasync def async_example():\n # Create async client\n async_client = AsyncOpenAI(\n api_key=GROQ_API_KEY,\n base_url=\"https://api.groq.com/openai/v1\",\n )\n \n # Store a fact\n print(\"=== Storing fact ===\")\n response = await async_client.chat.completions.create(\n model=\"llama-3.1-8b-instant\",\n messages=[{\"role\": \"user\", \"content\": \"My favorite color is blue.\"}],\n )\n print(f\"Assistant: {response.choices[0].message.content}\\n\")\n \n # Query with memory\n print(\"=== Querying with memory ===\")\n response = await async_client.chat.completions.create(\n model=\"llama-3.1-8b-instant\",\n messages=[{\"role\": \"user\", \"content\": \"What's my favorite color?\"}],\n )\n print(f\"Assistant: {response.choices[0].message.content}\\n\")\n\n# Run async example\nawait async_example()\nprint(\"→ Async operations work seamlessly with Hindsight!\")"
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": "## Configuration Options\n\nFine-tune Hindsight's behavior:"
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": "from hindsight_openai import configure\n\n# Full configuration example\nconfigure(\n hindsight_api_url=\"http://localhost:8888\", # Hindsight API URL\n agent_id=\"my-agent\", # Agent identifier (required)\n api_key=None, # Optional Hindsight API key\n \n # Features\n store_conversations=True, # Store conversations automatically\n inject_memories=True, # Inject memories automatically\n \n # Organization\n document_id=\"session-123\", # Optional document grouping\n \n # Control\n enabled=True, # Master on/off switch\n)\n\nprint(\"Configuration options explained:\")\nprint(\"- store_conversations: Automatically save conversations to Hindsight\")\nprint(\"- inject_memories: Automatically retrieve and inject relevant context\")\nprint(\"- document_id: Group related conversations together\")\nprint(\"- enabled=False: Disable Hindsight without changing code\")"
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": "## Use Cases\n\n### 1. **Personal AI Assistant**\n- Remembers your preferences, work history, and interests\n- Provides personalized recommendations\n- Maintains context across days/weeks\n\n### 2. **Customer Support Chatbot**\n- Recalls previous support tickets\n- Knows customer preferences and history\n- Provides consistent, context-aware responses\n\n### 3. **Research Assistant**\n- Remembers documents you've discussed\n- Connects related topics from different sessions\n- Builds knowledge over time\n\n### 4. **Code Review Tool**\n- Remembers project architecture decisions\n- Recalls past code review comments\n- Maintains consistency across reviews\n\n## Benefits Summary\n\n✅ **Zero Code Changes** - Drop-in replacement for OpenAI client \n✅ **Automatic Context** - No manual RAG pipeline needed \n✅ **Long-term Memory** - Conversations persist across sessions \n✅ **Smart Retrieval** - Semantic search finds relevant context \n✅ **Both Sync/Async** - Works with any OpenAI client pattern \n✅ **Configurable** - Fine-tune behavior to your needs \n✅ **Transparent** - Original OpenAI responses unchanged \n\n## Next Steps\n\n- **Explore Hindsight API**: Check out the main Hindsight README for advanced features\n- **Customize Search**: Tune `memory_search_budget` for your use case\n- **Use Document IDs**: Organize conversations by project/session\n- **Try Different Models**: Works with OpenAI, Groq, Ollama, and more\n\n## Resources\n\n- [Hindsight Main README](../README.md) - Core memory system docs\n- [Hindsight-OpenAI README](README.md) - Package documentation\n- [OpenAI API Docs](https://platform.openai.com/docs/api-reference) - Original API reference"
|
|
}
|
|
],
|
|
"metadata": {
|
|
"kernelspec": {
|
|
"display_name": "Python 3 (ipykernel)",
|
|
"language": "python",
|
|
"name": "python3"
|
|
},
|
|
"language_info": {
|
|
"codemirror_mode": {
|
|
"name": "ipython",
|
|
"version": 3
|
|
},
|
|
"file_extension": ".py",
|
|
"mimetype": "text/x-python",
|
|
"name": "python",
|
|
"nbconvert_exporter": "python",
|
|
"pygments_lexer": "ipython3",
|
|
"version": "3.11.10"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 4
|
|
} |