296 lines
7.6 KiB
Markdown
296 lines
7.6 KiB
Markdown
# Honcho Python SDK
|
|
|
|
The official Python library for the [Honcho](https://github.com/plastic-labs/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
|
|
|
|
```bash
|
|
pip install honcho-ai
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```python
|
|
# 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
|
|
|
|
```python
|
|
from honcho import AsyncHoncho
|
|
|
|
async def main():
|
|
client = AsyncHoncho(api_key="your-api-key")
|
|
```
|
|
|
|
### Metadata Management
|
|
|
|
```python
|
|
# 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
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```python
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```python
|
|
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 demonstration
|
|
- `chat.py` - Basic multi-peer chat
|
|
- `async_example.py` - Async/await usage
|
|
- `search.py` - Context search and retrieval
|
|
- `reasoning_artifacts.py` - Querying hypotheses, predictions, traces, and inductions
|
|
|
|
## License
|
|
|
|
Apache 2.0 - see [LICENSE](../../LICENSE) for details.
|
|
|
|
## Support
|
|
|
|
- [Documentation](https://docs.honcho.dev)
|
|
- [GitHub Issues](https://github.com/plastic-labs/honcho-sdks/issues)
|
|
- [Discord Community](https://discord.gg/honcho)
|