dashboard overview docs updates (#298)

* fix: update dialectic to chat

* fix: reasoning configuration

* fix: backlink get_context in summarizer

* fix: error handling

* chore: update dashboard overview

* fix: links due to other branches

* fix: proof

* fix: proof

---------

Co-authored-by: vintro <vince@plasticlabs.ai>
This commit is contained in:
Eri Barrett 2025-12-12 16:19:14 -05:00 committed by GitHub
parent adee668f37
commit 9c9c37f196
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 77 additions and 399 deletions

View File

@ -260,7 +260,7 @@
"pages": [
"v2.6.0-alpha/documentation/features/advanced/overview",
"v2.6.0-alpha/documentation/features/advanced/queue-status",
"v2.6.0-alpha/documentation/features/advanced/toggle-reasoning",
"v2.6.0-alpha/documentation/features/advanced/reasoning-configuration",
"v2.6.0-alpha/documentation/features/advanced/representation-scopes",
"v2.6.0-alpha/documentation/features/advanced/summarizer",
"v2.6.0-alpha/documentation/features/advanced/search",

Binary file not shown.

Before

Width:  |  Height:  |  Size: 135 KiB

After

Width:  |  Height:  |  Size: 265 KiB

View File

@ -1,5 +1,5 @@
---
title: 'Toggle Reasoning'
title: 'Reasoning Configuration'
description: 'Customize how Honcho reasons over peers, sessions, and messages'
icon: 'wrench'
---

View File

@ -16,9 +16,9 @@ Streaming is particularly useful for:
- Interactive agent experiences
- Reducing time-to-first-word in user interactions
## Streaming with the Dialectic Endpoint
## Streaming with the Chat Endpoint
One of the primary use cases for streaming in Honcho is with the Dialectic endpoint. This allows you to stream the AI's reasoning about a user in real-time.
One of the primary use cases for streaming in Honcho is with the [chat endpoint](/v2.6.0-alpha/documentation/features/chat). This allows you to stream the AI's reasoning about a user in real-time.
### Prerequisites
@ -70,7 +70,7 @@ import { Honcho } from '@honcho-ai/sdk';
```
</CodeGroup>
## Streaming from the Dialectic Endpoint
## Streaming from the Chat Endpoint
<CodeGroup>
```python Python

View File

@ -27,7 +27,7 @@ It's important to keep in mind that summary tasks run in the background and are
### Retrieving Summaries
Summaries are retrieved from the session by the `get_context` method. This method has two parameters:
Summaries are retrieved from the session by the [`get_context`](/v2.6.0-alpha/documentation/features/get-context) method. This method has two parameters:
* `summary`: A boolean indicating whether to include the summary in the return type. The default is true.
* `tokens`: An integer indicating the maximum number of tokens to use for the context. **If not provided, `get_context` will retrieve as many tokens as are required to create exhaustive conversation coverage.**

View File

@ -6,8 +6,11 @@ icon: 'messages'
The `get_context()` method is a powerful feature that retrieves formatted conversation context from sessions, making it easy to integrate with LLMs like OpenAI, Anthropic, and others. This guide covers everything you need to know about working with session context.
<Note>
By default, the context includes a blend of summary and messages ***which covers the entire session history of a peer***.
</Note>
By default, the context includes a blend of summary and messages which covers the entire history of the session. Summaries are automatically generated at intervals and recent messages are included depending on how many tokens the context is intended to be. You can specify any token limit you want, and can disable summaries to fill that limit entirely with recent messages. To get representation data, you need to specify a target peer.
Summaries are automatically generated at intervals and recent messages are included depending on how many tokens the context is intended to be. You can specify any token limit you want, and can disable summaries to fill that limit entirely with recent messages. To get representation data, you need to specify a target peer.
## Basic Usage
@ -601,40 +604,24 @@ anthropic_messages = context.to_anthropic(assistant=assistant)
### 3. Error Handling
Always handle potential errors when working with context:
Always handle potential errors when retrieving context:
<CodeGroup>
```python Python
try:
context = session.get_context(tokens=2000)
messages = context.to_openai(assistant=assistant)
# Use messages with LLM API
response = openai_client.chat.completions.create(
model="gpt-4",
messages=messages
)
except Exception as e:
print(f"Error getting context: {e}")
# Handle error appropriately
# Handle error appropriately (fallback to basic context, retry, etc.)
```
```typescript TypeScript
(async () => {
try {
const context = await session.getContext({ tokens: 2000 });
const messages = context.toOpenAI(assistant);
// Use messages with LLM API
const response = await openai.chat.completions.create({
model: "gpt-4",
messages: messages
});
} catch (error) {
console.error(`Error getting context: ${error}`);
// Handle error appropriately
// Handle error appropriately (fallback to basic context, retry, etc.)
}
})();
```

View File

@ -1,7 +1,7 @@
---
title: "The Honcho Dashboard"
icon: "rocket"
description: "Build socially intelligent agents without worrying about infrastructure"
description: "Build stateful agents without worrying about infrastructure"
sidebarTitle: "Dashboard Overview"
---
@ -10,7 +10,7 @@ sidebarTitle: "Dashboard Overview"
</Card>
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
<img src="/images/app-screenshots/peer-dash.png" alt="Peer Dashboard" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
</Frame>
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`.
<Frame>
<img src="/images/app-screenshots/peer-utilities.png" alt="Peer Management Dashboard" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
@ -101,14 +101,14 @@ Click into any peer to navigate to their respective utilities page. Next to the
Utilities include:
- **Message search** across all sessions for a `Peer`
- **Dialectic Chat** to query `Peer` representations globally or session-scoped (results vary dependant on the `Peer`'s configuration)
- **Chat** to query `Peer` representations with an optional session scope (results vary based on the `Peer`'s configuration)
<Frame>
<img src="/images/app-screenshots/chat-endpoint.png" alt="Chat Endpoint" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
</Frame>
- **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)
<Frame>
<img src="/images/app-screenshots/peer-utilities.png" alt="Peer Management Dashboard" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
@ -174,8 +174,3 @@ Dive into our [API Reference](/v2.6.0-alpha/api-reference) to explore all availa
</Card>
</CardGroup>
We're excited to see what you'll build with Honcho Platform. Let's create smarter, more personalized AI experiences together!
---
*Ready to build personally aligned AI? [Get started with Honcho →](https://app.honcho.dev)*

View File

@ -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
<Info>
**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.
</Info>
## Basic Usage
Working representations are accessed through the `working_rep()` method on Session or Peer objects:
<CodeGroup>
```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();
```
</CodeGroup>
## 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) |
<CodeGroup>
```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
});
```
</CodeGroup>
## 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
<CodeGroup>
```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);
```
</CodeGroup>
## 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
<CodeGroup>
```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);
```
</CodeGroup>
## 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:
<CodeGroup>
```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<string, any> = {};
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;
}
```
</CodeGroup>
### 3. Combine with Fresh Analysis When Needed
Use cached representations for baseline understanding, and fresh analysis for current insights:
<CodeGroup>
```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
};
```
</CodeGroup>
## 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.

View File

@ -26,38 +26,32 @@ prompting you to create a new one.
</div>
Once you've created an organization, you'll be taken to the dashboard and see
the Welcome page with integration guidance and links to documentation.
Once you've created an organization, you'll be taken to the welcome dashboard.
<Frame>
<img src="/images/app-screenshots/get-started-copy.png" alt="Honcho Dashboard Getting Started" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
</Frame>
Each organization has dedicated infrastructure running to isolate your
workloads. Once you add a valid payment method under the
Each organization has dedicated infrastructure running to isolate your workloads.
Once you add a valid payment method under the
[Billing](https://app.honcho.dev/billing) page, your instance will turn on.
## 2. Activate your Honcho instance
Navigate to the [Billing](https://app.honcho.dev/billing) page to add a payment method. Your Honcho instance provisions automatically, and you can monitor the deployment on the [Instance Status](https://app.honcho.dev/status) page until all systems show a green check mark.
With credits and a payment method on file (managed via the [Billing](https://app.honcho.dev/billing) page), your Honcho instance will be provisioned and ready to use. Monitor your machine status, and check for version upgrades on the [Instance Status](https://app.honcho.dev/status) page.
<Frame>
<img src="/images/app-screenshots/status-page.png" alt="Instance Status Page" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
</Frame>
You can also upgrade Honcho when new versions are made available directly from the status page.
If there is an upgrade available you will see an indicator like this:
<div style={{ maxWidth: "700px", margin: "0 auto" }}>
<Frame>
<img src="/images/app-screenshots/upgrade-honcho.png" alt="Upgrade Honcho" loading="lazy" decoding="async" fetchpriority="low" style={{ width: "100%", height: "auto" }} />
</Frame>
</div>
The **Performance** page provides comprehensive monitoring with usage metrics, health analytics, API response times, and endpoint usage across Honcho.
<Frame>
<img src="/images/app-screenshots/performance-analytics.png" alt="Performance Analytics Dashboard" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
</Frame>
Upgrading your machines may take a few minutes and you can monitor progress. If for any reason your machine goes offline, you will see a red status indicator. Navigate to the [Instance Status](https://app.honcho.dev/status) page and try to trigger a refresh of your machines.
## 3. Manage API Keys
The [API Keys](https://app.honcho.dev/api-keys) page allows you to create and manage authentication tokens for different environments. You can create admin-level keys with full instance access or scope keys to specific `Workspaces`, `Peers`, or `Sessions`.
@ -67,12 +61,48 @@ The [API Keys](https://app.honcho.dev/api-keys) page allows you to create and ma
</Frame>
## 4. Test with API Playground
The [API Playground](https://app.honcho.dev/playground) provides a Postman-like interface to test queries, explore endpoints, and validate your integration. Authenticate with an API key and send requests directly to your Honcho instance with real-time responses and full request/response logging.
The [API Playground](https://app.honcho.dev/playground) provides a developer-friendly interface to quickly iterate and test queries, explore endpoints, and validate your integration directly from your browser—no code required.
<Frame>
<img src="/images/app-screenshots/api-playground.png" alt="API Playground Interface" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
</Frame>
The playground automatically loads all available API endpoints to match your Honcho instance version. Endpoints can be filtered by category at the top of the list.
If you prefer, you can set up your queries in the UI and copy to cURL for help with building scripts or general terminal use.
### Step-by-Step:
**1. Select an Endpoint**: Choose your desired endpoint from the available list.
**2. Choose Path Parameters**: For fields like Workspace, Session, or Peer, select options from dropdown menus—no need to manually enter IDs.
**3. Add Request Body Data**: Complete any required fields for POST/PUT requests.
**4. Execute or Copy Request**: Run it directly or copy as cURL to use elsewhere (just add your API key).
### Example Usage
Build a complete conversation flow without ever leaving the playground:
1. **Create a Workspace**:
select `POST Get or Create Workspace` and type workspace name into the request body
→ Returns workspace ID
2. **Create new Peer(s)**:
select `POST Get or Create Peer,` choose your workspace from the dropdown, and type peer name into the request body. (repeat for each peer)
→ Returns peer ID
3. **POST Get or Create Session**
`POST /sessions` selecting your workspace from the dropdown then type session name into the request body
→ Returns session ID and adds to dropdown
4. **POST Create Messages for Session**
`POST /messages` selecting your workspace & session from the dropdown then type peer id(s) and message content into the request body
→ Adds message(s) to the session
## 5. Workspaces
The [Explore](https://app.honcho.dev/explore) page provides comprehensive `Workspace` management where you can create workspaces and begin exploring the platform. Each `Workspace` serves as a container for organizing your Honcho data.
@ -137,14 +167,27 @@ Here you can:
<img src="/images/app-screenshots/get-context.png" alt="Get Context" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
</Frame>
## 8. Webhooks Integration
The [Webhooks](https://app.honcho.dev/webhooks) page enables Webhook creation and management.
## 8. Performance Monitoring & Analytics
The **Performance** page offers comprehensive monitoring tools, including usage metrics, health analytics, API response times, and endpoint usage across Honcho.
<Frame>
<img src="/images/app-screenshots/performance-analytics.png" alt="Performance Analytics Dashboard" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
</Frame>
## 9. Webhooks Integration
The [Webhooks](https://app.honcho.dev/webhooks) page allows managing and creation of webhooks for Honcho. React to events in real-time—such as message delivery, session updates, peer state changes, and more—by sending event payloads via HTTP POST requests to your provided endpoints.
<Frame>
<img src="/images/app-screenshots/webhooks-page.png" alt="Webhooks Dashboard" width="1200" height="800" loading="lazy" decoding="async" fetchpriority="low" />
</Frame>
<Frame>
<img src="/images/app-screenshots/webhooks-create.png" alt="Create New Webhook" width="400" height="267" loading="lazy" decoding="async" fetchpriority="low" />
</Frame>
## 10. Organization Member Access
## 9. Organization Member Access
The [Members](https://app.honcho.dev/members) page provides organization administration to manage your team's access to Honcho with the ability to grant admin permissions.
<Frame>