diff --git a/docs/v2.6.0-alpha/documentation/reference/platform.mdx b/docs/v2.6.0-alpha/documentation/reference/platform.mdx index 479ffcb2..daba5c57 100644 --- a/docs/v2.6.0-alpha/documentation/reference/platform.mdx +++ b/docs/v2.6.0-alpha/documentation/reference/platform.mdx @@ -10,7 +10,7 @@ sidebarTitle: "Dashboard Overview" The quickest way to begin using Honcho in production is with the -[Honcho Cloud Platform](https://app.honcho.dev). Sign up, generate an API key, +[Honcho Cloud Service](https://app.honcho.dev). Sign up, generate an API key, and start building with Honcho. ## 1. Go to [app.honcho.dev](https://app.honcho.dev) @@ -93,7 +93,7 @@ Expand the `Peers` list from the `Workspace` dashboard to see a detailed view of Peer Dashboard -Click into any peer to navigate to their respective utilities page. Next to the `Peer` name you can edit the [Global Peer Configuration](/v2.6.0-alpha/documentation/core-concepts/configuration), and in the tabs below, explore all utilities for the `Peer`. +Click into any peer to navigate to their respective utilities page. Next to the `Peer` name you can edit the [Peer Configuration](/v2.6.0-alpha/documentation/features/advanced/reasoning-configuration), and in the tabs below, explore all utilities for the `Peer`. Peer Management Dashboard @@ -108,7 +108,7 @@ Utilities include: - **Session logs** view which `Sessions` the `Peer` is active -- **Peer configuration and metadata management** including [Session-Peer Configuration](/v2.6.0-alpha/documentation/core-concepts/configuration#session-peer-configuration) +- **Peer configuration and metadata management** including [Session-Peer Configuration](/v2.6.0-alpha/documentation/features/advanced/reasoning-configuration#session-configuration) Peer Management Dashboard diff --git a/docs/v2.6.0-alpha/documentation/scratch/working-rep.mdx b/docs/v2.6.0-alpha/documentation/scratch/working-rep.mdx deleted file mode 100644 index f3ea09b6..00000000 --- a/docs/v2.6.0-alpha/documentation/scratch/working-rep.mdx +++ /dev/null @@ -1,347 +0,0 @@ ---- -title: 'Working Representations' -description: "Learn how to retrieve cached peer knowledge and understanding using Honcho's working representation system" -icon: 'brain' ---- - -Working representations are Honcho's system for accessing cached psychological models that capture what peers know, think, and remember. Unlike the `chat()` method which generates fresh representations on-demand, the `working_rep()` method retrieves pre-computed representations that have been automatically built and stored as conversations progress. - -## How Working Representations Are Created - -Working representations are automatically generated and cached through Honcho's background processing system: - -1. **Automatic Generation**: When messages are added to sessions, they trigger background jobs that analyze conversations using theory of mind inference and long-term memory integration - -2. **Cached Storage**: The generated representations are stored in the database as metadata on `Peer` objects (for global representations) or `SessionPeer` objects (for session-scoped representations) - -3. **Retrieval**: The `working_rep()` method provides fast access to these cached representations without requiring LLM processing - - -**Cached vs On-Demand**: `working_rep()` retrieves cached representations for fast access, while `peer.chat()` generates fresh representations using the dialectic system. Use `working_rep()` when you need fast access to stored knowledge, and `chat()` when you need current analysis with custom queries. - - -## Basic Usage - -Working representations are accessed through the `working_rep()` method on Session or Peer objects: - - -```python Python -from honcho import Honcho - -# Initialize client -honcho = Honcho() - -# Create peers and session -user = honcho.peer("user-123") -assistant = honcho.peer("ai-assistant") -session = honcho.session("support-conversation") - -# Add conversation to trigger representation generation -session.add_messages([ - user.message("I'm having trouble with my billing account"), - assistant.message("I can help with that. What specific issue are you seeing?"), - user.message("My credit card was charged twice last month"), - assistant.message("I see duplicate charges on your account. Let me refund one of them.") -]) - -# Chat to generate a working representation -response = user.chat("What is this user's main concern right now?", session_id=session.id) - -# Retrieve the cached working representation for the user -user_representation = session.working_rep("user-123") -print("Cached user representation:", user_representation) - -# Or access from the peer directly -peer_representation = user.working_rep() -``` - -```typescript TypeScript -import { Honcho } from "@honcho-ai/sdk"; - -// Initialize client -const honcho = new Honcho({}); - -// Create peers and session -const user = await honcho.peer("user-123"); -const assistant = await honcho.peer("ai-assistant"); -const session = await honcho.session("support-conversation"); - -// Add conversation to trigger representation generation -await session.addMessages([ - user.message("I'm having trouble with my billing account"), - assistant.message("I can help with that. What specific issue are you seeing?"), - user.message("My credit card was charged twice last month"), - assistant.message("I see duplicate charges on your account. Let me refund one of them.") -]); - -// Chat to generate a working representation -const response = await user.chat("What is this user's main concern right now?", { sessionId: session.id }); - -// Retrieve the cached working representation for the user -const userRepresentation = await session.workingRep("user-123"); -console.log("Cached user representation:", userRepresentation); - -// Or access from the peer directly -const peerRepresentation = await user.workingRep(); -``` - - -## Semantic Search in Representations - -Working representations support semantic search to retrieve the most relevant observations for a given query. This is useful when you want to focus the representation on specific topics. - -### Parameters - -| Parameter | Type | Description | -|-----------|------|-------------| -| `search_query` | `str` | Semantic search query to filter relevant observations | -| `search_top_k` | `int` | Number of semantic search results to include (1-100) | -| `search_max_distance` | `float` | Maximum semantic distance threshold (0.0-1.0) | -| `include_most_derived` | `bool` | Whether to include the most recently derived observations | -| `max_observations` | `int` | Maximum number of observations to include (1-100) | - - -```python Python -# Get representation focused on a specific topic -billing_rep = session.working_rep( - "user-123", - search_query="billing and payment issues", - search_top_k=10, - search_max_distance=0.8, - include_most_derived=True, - max_observations=25 -) - -# Get representation from peer with target -# What user-123 knows about the assistant -local_rep = session.working_rep( - "user-123", - target="ai-assistant", - search_query="support interactions" -) - -# Access from peer object with semantic search -user_rep = user.working_rep( - session=session, - search_query="preferences", - search_top_k=5 -) -``` - -```typescript TypeScript -// Get representation focused on a specific topic -const billingRep = await session.workingRep("user-123", { - searchQuery: "billing and payment issues", - searchTopK: 10, - searchMaxDistance: 0.8, - includeMostDerived: true, - maxObservations: 25 -}); - -// Get representation from peer with target -// What user-123 knows about the assistant -const localRep = await session.workingRep("user-123", { - target: "ai-assistant", - searchQuery: "support interactions" -}); - -// Access from peer object with semantic search -const userRep = await user.workingRep(session, undefined, { - searchQuery: "preferences", - searchTopK: 5 -}); -``` - - -## Understanding Representation Content - -Cached working representations contain structured psychological analysis based on conversation history. The format typically includes: - -### Current Mental State Predictions -Information about what the peer is currently thinking, feeling, or focused on based on recent messages. - -### Relevant Long-term Facts -Facts about the peer that have been extracted and stored over time from various conversations. - -### Example Representation Structure - - -```python Python -# Example of what a cached representation might contain -representation = session.working_rep("user-123") - -# Typical content structure: -""" -PREDICTION ABOUT THE USER'S CURRENT MENTAL STATE: -The user appears frustrated with a billing issue, specifically concerning duplicate charges. -They seem to have some confidence in the support process as they provided specific details. - -RELEVANT LONG-TERM FACTS ABOUT THE USER: -- User has had previous billing inquiries -- User prefers direct, specific communication -- User is detail-oriented when reporting issues -""" - -print("Full representation:", representation) -``` - -```typescript TypeScript -// Example of what a cached representation might contain -const representation = await session.workingRep("user-123"); - -// Typical content structure: -/* -PREDICTION ABOUT THE USER'S CURRENT MENTAL STATE: -The user appears frustrated with a billing issue, specifically concerning duplicate charges. -They seem to have some confidence in the support process as they provided specific details. - -RELEVANT LONG-TERM FACTS ABOUT THE USER: -- User has had previous billing inquiries -- User prefers direct, specific communication -- User is detail-oriented when reporting issues -*/ - -console.log("Full representation:", representation); -``` - - -## When Representations Are Updated - -Working representations are automatically updated through Honcho's background processing system: - -### Message Processing Pipeline - -1. **Message Creation**: When messages are added via `session.add_messages()` or similar methods -2. **Background Queuing**: Messages are queued for processing in the background -3. **Theory of Mind Analysis**: The system analyzes conversation patterns and psychological states -4. **Fact Extraction**: Long-term facts are extracted and stored in vector embeddings -5. **Representation Generation**: New representations are created combining current analysis with historical facts -6. **Cache Update**: The new representation is stored in the database metadata - -### Processing Triggers - -Representations are updated when: -- New messages are added to sessions -- Sufficient new content has accumulated -- The background processing system determines an update is needed - -## Comparison with Chat Method - -Understanding when to use `working_rep()` vs `peer.chat()`: - -### Use `working_rep()` when: -- You need fast access to stored psychological models -- You want to see what the system has already learned about a peer -- You're building dashboards or analytics that display peer understanding -- You need consistent representations that don't change between calls - -### Use `peer.chat()` when: -- You need to ask specific questions about a peer -- You want fresh analysis based on current conversation state -- You need customized insights for specific use cases -- You want to query about relationships between peers - - -```python Python -# Fast cached access -cached_rep = session.working_rep("user-123") -print("Cached:", cached_rep[:100] + "...") - -# Custom query with fresh analysis -custom_analysis = user.chat("What is this user's main concern right now?", session_id=session.id) -print("Fresh analysis:", custom_analysis) -``` - -```typescript TypeScript -// Fast cached access -const cachedRep = await session.workingRep("user-123"); -console.log("Cached:", cachedRep.substring(0, 100) + "..."); - -// Custom query with fresh analysis -const customAnalysis = await user.chat("What is this user's main concern right now?", { sessionId: session.id }); -console.log("Fresh analysis:", customAnalysis); -``` - - -## Best Practices - -### 1. Ensure Availability Before Using - -Make sure that a representation exists before processing it by using the chat endpoint first. - -### 2. Use for Fast Analytics - -Cached representations are ideal for analytics dashboards: - - -```python Python -# Good: Fast dashboard updates using cached data -def update_analytics_dashboard(sessions): - analytics = {} - for session in sessions: - for peer_id in session.get_peer_ids(): - rep = session.working_rep(peer_id) - analytics[peer_id] = analyze_representation(rep) - return analytics -``` - -```typescript TypeScript -// Good: Fast dashboard updates using cached data -async function updateAnalyticsDashboard(sessions) { - const analytics: Record = {}; - for (const session of sessions) { - const peerIds = await session.getPeerIds(); - for (const peerId of peerIds) { - const rep = await session.workingRep(peerId); - analytics[peerId] = analyzeRepresentation(rep); - } - } - return analytics; -} -``` - - -### 3. Combine with Fresh Analysis When Needed - -Use cached representations for baseline understanding, and fresh analysis for current insights: - - -```python Python -# Get baseline understanding from cache -baseline = session.working_rep("user-123") - -# Get current specific insights -current_state = user.chat("How is this user feeling right now?", session_id=session.id) - -# Combine for comprehensive view -comprehensive_view = { - "baseline_knowledge": baseline, - "current_analysis": current_state -} -``` - -```typescript TypeScript -// Get baseline understanding from cache -const baseline = await session.workingRep("user-123"); - -// Get current specific insights -const currentState = await user.chat("How is this user feeling right now?", { sessionId: session.id }); - -// Combine for comprehensive view -const comprehensiveView = { - baselineKnowledge: baseline, - currentAnalysis: currentState -}; -``` - - -## Conclusion - -Working representations provide fast access to cached psychological models that Honcho automatically builds and maintains. By understanding how to: - -- Retrieve cached representations using `session.working_rep()` -- Parse and interpret representation content -- Handle cases where representations aren't available -- Combine cached and fresh analysis appropriately - -You can build efficient applications that leverage Honcho's continuous learning about peer knowledge and mental states without the latency of real-time generation.