7.6 KiB
7.6 KiB
Honcho Python SDK
The official Python library for the Honcho conversational memory platform. Honcho provides tools for managing peers, sessions, and conversation context across multi-party interactions, enabling advanced conversational AI applications with persistent memory and theory-of-mind capabilities.
Installation
pip install honcho-ai
Quick Start
from honcho import Honcho
# Initialize client
client = Honcho(api_key="your-api-key")
# Create peers (participants in conversations)
alice = client.peer("alice")
bob = client.peer("bob")
# Create a session for group conversations
session = client.session("conversation-1")
# Add messages to the session
session.add_messages([
alice.message("Hello, Bob!"),
bob.message("Hi Alice, how are you?")
])
# Wait for deriver to process all messages (only necessary if very recent messages are critical to query)
client.poll_deriver_status()
# Query conversation context
response = alice.chat("What did Bob say to the user?")
print(response)
Core Concepts
Peers
Peers represent participants in conversations.
# Create peers
assistant = client.peer("assistant")
user = client.peer("user-123")
# Chat with global context
response = user.chat("What did I talk about yesterday?")
# Chat with perspective of another peer
response = user.chat("Does the assistant know my preferences?", target=assistant)
Sessions
Sessions group related conversations and messages:
# Create a session
session = client.session("project-discussion")
# Add peers to session
session.add_peers([alice, bob])
# Add messages
session.add_messages([
alice.message("Let's discuss the project timeline"),
bob.message("I think we need two more weeks")
])
# Get conversation context
context = session.get_context()
Messages and Context
Retrieve and use conversation history:
# Get messages from a session
messages = session.get_messages()
# Convert to OpenAI format for further prompting
openai_messages = context.to_openai(assistant="assistant")
# Convert to Anthropic format for further prompting
anthropic_messages = context.to_anthropic(assistant="assistant")
Async Support
from honcho import AsyncHoncho
async def main():
client = AsyncHoncho(api_key="your-api-key")
Metadata Management
# Set peer metadata
user.set_metadata({"location": "San Francisco", "preferences": {"theme": "dark"}})
# Session metadata
session.set_metadata({"topic": "project-planning", "priority": "high"})
Multi-Perspective Queries
# Alice's view of what Bob knows
response = alice.chat("Does Bob remember our discussion about the budget?", target=bob)
# Session-specific perspective
response = alice.chat("What does Bob think about this project?",
target=bob,
session_id=session.id)
Reasoning Artifacts (Read-Only)
Honcho generates reasoning artifacts during periodic "dreams" where reasoning agents analyze observed patterns and form hypotheses, predictions, and inductions. These artifacts provide transparency into the system's understanding of peers.
Hypotheses
Hypotheses are explanatory theories about observed patterns:
# Get active hypotheses for a peer (via client)
hypotheses = client.get_hypotheses(
observer="user_123",
observed="user_123",
status="active"
)
# Get hypotheses using Peer convenience method
peer = client.peer("user_123")
hypotheses = peer.get_hypotheses(status="active")
# Get hypotheses about another peer
hypotheses = peer.get_hypotheses(target="user_456")
# Get hypothesis details
hypothesis = client.get_hypothesis("hyp_abc123")
print(hypothesis.content)
print(hypothesis.confidence)
# Get hypothesis evolution tree
genealogy = client.get_hypothesis_genealogy("hyp_abc123")
print(f"Parents: {len(genealogy['parents'])}")
print(f"Children: {len(genealogy['children'])}")
Predictions
Predictions are testable claims derived from hypotheses:
# List predictions
predictions = client.get_predictions(
hypothesis_id="hyp_abc123",
status="unfalsified"
)
# Semantic search for similar predictions
similar = client.search_predictions(
"prefers dark mode over light mode",
hypothesis_id="hyp_abc123"
)
# Get falsification traces for a prediction
traces = client.get_prediction_traces("pred_xyz789")
Falsification Traces
Traces record the falsification process:
# List traces
traces = client.get_traces(
prediction_id="pred_xyz789",
final_status="unfalsified"
)
# Get trace details
trace = client.get_trace("trace_123")
print(f"Search queries: {trace.search_queries}")
print(f"Contradicting premises: {trace.contradicting_premise_ids}")
print(f"Reasoning chain: {trace.reasoning_chain}")
Inductions
Inductions are stable patterns extracted from unfalsified predictions:
# Get high-confidence patterns (via client)
inductions = client.get_inductions(
observer="user_123",
observed="user_123",
confidence="high"
)
# Get patterns using Peer convenience method
peer = client.peer("user_123")
patterns = peer.get_inductions(confidence="high")
# Get patterns about another peer
patterns = peer.get_inductions(
target="user_456",
pattern_type="behavioral"
)
# Get pattern sources (provenance)
sources = client.get_induction_sources("ind_abc123")
print(f"Based on {len(sources['source_predictions'])} predictions")
print(f"From {len(sources['source_premises'])} observations")
Note: All reasoning artifacts are read-only. They are generated exclusively during reasoning dreams and cannot be created or modified via the API.
Type Safety
The SDK includes TypedDict definitions for all reasoning artifacts, providing IDE autocomplete and type checking:
from honcho import Honcho
from honcho import Hypothesis, Induction, Prediction, FalsificationTrace
client = Honcho()
peer = client.peer("user-123")
# Type hints provide IDE autocomplete
hypotheses: list[Hypothesis] = peer.get_hypotheses(status="active")
for hyp in hypotheses:
print(hyp["content"]) # IDE knows this key exists
print(hyp["confidence_score"]) # Autocomplete available
print(hyp["tier"]) # Type-safe access
# Works with all reasoning artifact types
inductions: list[Induction] = peer.get_inductions(confidence="high")
for pattern in inductions:
print(f"Pattern: {pattern['content']}")
print(f"Type: {pattern['pattern_type']}")
print(f"Stability: {pattern['stability_score']}")
Available types: Hypothesis, Prediction, FalsificationTrace, Induction, HypothesisGenealogy, InductionSources
Configuration
Environment Variables
export HONCHO_API_KEY="your-api-key"
export HONCHO_BASE_URL="https://api.honcho.dev" # Optional
export HONCHO_WORKSPACE_ID="your-workspace" # Optional
Client Options
client = Honcho(
api_key="your-api-key",
environment="production", # or "local", "demo"
workspace_id="custom-workspace",
base_url="https://api.honcho.dev"
)
Examples
Check out the examples/ directory for complete usage examples:
example.py- Comprehensive feature demonstrationchat.py- Basic multi-peer chatasync_example.py- Async/await usagesearch.py- Context search and retrievalreasoning_artifacts.py- Querying hypotheses, predictions, traces, and inductions
License
Apache 2.0 - see LICENSE for details.