RomanNum3ral
/
honcho
mirror of https://github.com/plastic-labs/honcho.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

fix: update to main changes

This commit is contained in:
vintro 2025-12-04 10:59:28 -05:00
parent 77a240cfd6
commit e5e44f4619
No known key found for this signature in database
5 changed files with 1019 additions and 410 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

280
docs/v2/documentation/features/advanced/configuration.mdx
View File

@ -1,14 +1,146 @@
---
title: 'Configure Reasoning'
description: 'Customizing how Honcho handles peers and sessions'
description: 'Customizing how Honcho handles peers, sessions, and messages'
icon: 'wrench'
---
Entities in Honcho can sometimes be configured to change the behavior of the deriver, which is responsible for generating and storing facts, summaries, and user representations.
TODO: remove deriver references
These configurations can be set at the peer, session, and session-peer level (AKA the state of a peer within a specific session).
Honcho's reasoning engine can be configured at multiple levels to control how it processes messages, generates facts, creates summaries, and builds peer representations.
### Peer Configuration
Configuration follows a hierarchy: **message > session > workspace > global defaults**. Settings at lower levels override those at higher levels, giving you fine-grained control over behavior.
## Configuration Hierarchy
Honcho uses a hierarchical configuration system where more specific settings override more general ones:
1. **Global Defaults**: Built-in system defaults
2. **Workspace Configuration**: Settings that apply to all sessions in a workspace
3. **Session Configuration**: Settings that apply to all messages in a session
4. **Message Configuration**: Settings that apply to a specific message
<Info>
All configuration fields are optional. If not specified, the value is inherited from the next level up in the hierarchy.
</Info>
## Configuration Options
### Deriver Configuration
Controls the core reasoning engine that extracts facts and insights from messages.
| Field | Type | Description |
|-------|------|-------------|
| `enabled` | `bool` | Whether to enable deriver functionality. When disabled, no facts or representations are generated. |
<CodeGroup>
```python Python
from honcho import Honcho
honcho = Honcho()
# Disable deriver at session level
session = honcho.session("private-session", config={
"deriver": {"enabled": False}
})
```
```typescript TypeScript
import { Honcho } from "@honcho-ai/sdk";
const honcho = new Honcho({});
// Disable deriver at session level
const session = await honcho.session("private-session", {
config: {
deriver: { enabled: false }
}
});
```
</CodeGroup>
### Peer Card Configuration
Controls how peer cards (concise summaries of what's known about a peer) are generated and used.
| Field | Type | Description |
|-------|------|-------------|
| `use` | `bool` | Whether to use peer cards during the deriver process. |
| `create` | `bool` | Whether to generate peer cards based on message content. |
<CodeGroup>
```python Python
# Disable peer card generation but still use existing cards
session = honcho.session("my-session", config={
"peer_card": {"create": False, "use": True}
})
```
```typescript TypeScript
// Disable peer card generation but still use existing cards
const session = await honcho.session("my-session", {
config: {
peer_card: { create: false, use: true }
}
});
```
</CodeGroup>
### Summary Configuration
Controls automatic conversation summarization. Available at workspace and session levels only.
| Field | Type | Description |
|-------|------|-------------|
| `enabled` | `bool` | Whether to enable summary functionality. |
| `messages_per_short_summary` | `int` | Number of messages between short summaries. Must be ≥ 10. |
| `messages_per_long_summary` | `int` | Number of messages between long summaries. Must be ≥ 20 and greater than `messages_per_short_summary`. |
<CodeGroup>
```python Python
# Customize summary frequency
session = honcho.session("verbose-session", config={
"summary": {
"enabled": True,
"messages_per_short_summary": 15,
"messages_per_long_summary": 45
}
})
```
```typescript TypeScript
// Customize summary frequency
const session = await honcho.session("verbose-session", {
config: {
summary: {
enabled: true,
messages_per_short_summary: 15,
messages_per_long_summary: 45
}
}
});
```
</CodeGroup>
### Dream Configuration
Controls the "dreaming" process that consolidates and refines representations. Available at workspace and session levels only.
| Field | Type | Description |
|-------|------|-------------|
| `enabled` | `bool` | Whether to enable dream functionality. Automatically disabled if deriver is disabled. |
<CodeGroup>
```python Python
# Disable dreams for a workspace
# (done via API when creating/updating workspace)
```
```typescript TypeScript
// Disable dreams for a workspace
// (done via API when creating/updating workspace)
```
</CodeGroup>
---
## Peer Configuration
By default, all peers are "observed" by Honcho. This means that Honcho will derive facts from messages sent by the peer and generate a representation of them. In most cases, this is why you use Honcho! However, sometimes an application requires a peer that should not be observed: for example, an assistant or game NPC that your program will never need to ask questions about.
@ -27,7 +159,7 @@ honcho = Honcho()
peer = honcho.peer("my-peer", config={"observe_me": False})
# Change peer's configuration
peer.set_peer_config({"observe_me": True})
peer.set_config({"observe_me": True})
# Note: creating the same peer again will also replace the configuration
peer = honcho.peer("my-peer", config={"observe_me": False})
@ -43,7 +175,7 @@ import { Honcho } from "@honcho-ai/sdk";
const peer = await honcho.peer("my-peer", { config: { observe_me: false } });
// Change peer's configuration
await peer.setPeerConfig({ observe_me: true });
await peer.setConfig({ observe_me: true });
// Note: creating the same peer again will also replace the configuration
await honcho.peer("my-peer", { config: { observe_me: false } });
@ -51,9 +183,9 @@ import { Honcho } from "@honcho-ai/sdk";
```
</CodeGroup>
### Session Configuration
## Session Configuration
By default, all sessions have the deriver enabled, much like peers. You may create a session that escapes the deriver's watchful eye by setting the `deriver_disabled` flag to `true`. You can update the flag by calling `get_or_create` on the session with a new configuration.
Sessions support the full configuration schema. You can disable the deriver entirely for a session, customize summary behavior, or adjust peer card settings.
<CodeGroup>
```python Python
@ -62,8 +194,18 @@ from honcho import Honcho
# Initialize client
honcho = Honcho()
# Create session with configuration
session = honcho.session("my-session", config={"deriver_disabled": True})
# Create session with deriver disabled
session = honcho.session("my-session", config={
"deriver": {"enabled": False}
})
# Create session with custom summary settings
session = honcho.session("detailed-session", config={
"summary": {
"messages_per_short_summary": 10,
"messages_per_long_summary": 30
}
})
```
```typescript TypeScript
import { Honcho } from "@honcho-ai/sdk";
@ -72,15 +214,73 @@ import { Honcho } from "@honcho-ai/sdk";
// Initialize client
const honcho = new Honcho({});
// Create session with configuration
const session = await honcho.session("my-session", { config: { deriver_disabled: true } });
// Create session with deriver disabled
const session = await honcho.session("my-session", {
config: { deriver: { enabled: false } }
});
// Create session with custom summary settings
const detailedSession = await honcho.session("detailed-session", {
config: {
summary: {
messages_per_short_summary: 10,
messages_per_long_summary: 30
}
}
});
})();
```
</CodeGroup>
### Session-Peer Configuration
## Message Configuration
Configuration at the session-peer level is the most common use case for configuration flags. You will often want to arrange a session such that certain peers observe others in order to form "local representations" of them. There are two flags that can be set at the session-peer level:
Individual messages can override session and workspace configuration for fine-grained control. This is useful for excluding specific messages from processing or adjusting behavior on a per-message basis.
<CodeGroup>
```python Python
from honcho import Honcho
honcho = Honcho()
session = honcho.session("my-session")
user = honcho.peer("user")
# Create a message that skips deriver processing
session.add_messages([
user.message("This message won't be analyzed", config={
"deriver": {"enabled": False}
})
])
# Create a message with custom peer card settings
session.add_messages([
user.message("Use existing card but don't update it", config={
"peer_card": {"use": True, "create": False}
})
])
```
```typescript TypeScript
import { Honcho } from "@honcho-ai/sdk";
(async () => {
const honcho = new Honcho({});
const session = await honcho.session("my-session");
const user = await honcho.peer("user");
// Create a message that skips deriver processing
await session.addMessages([
user.message("This message won't be analyzed", {
configuration: { deriver: { enabled: false } }
})
]);
})();
```
</CodeGroup>
## Session-Peer Configuration
Configuration at the session-peer level controls how peers observe each other within a specific session. This is the most common use case for enabling "local representations" — where one peer forms a model of another peer based only on what they observe in that session.
There are two flags that can be set at the session-peer level:
- `observe_me`: Whether this peer should *be observed* by others in the session. By default, this is `true`. This overrides the peer-level `observe_me` flag.
@ -96,7 +296,7 @@ You can dynamically change the configuration of a session-peer by calling `set_p
<CodeGroup>
```python Python
from honcho import Honcho
from honcho import Honcho, SessionPeerConfig
# Initialize client
honcho = Honcho()
@ -113,11 +313,11 @@ session.add_peers([alice, bob])
# Add another peer to the session with a custom configuration
charlie = honcho.peer("charlie")
session.add_peers([charlie, {"observe_me": False, "observe_others": True}])
session.add_peers([(charlie, SessionPeerConfig(observe_me=False, observe_others=True))])
# Set session-peer configuration
session.set_peer_config(alice, {"observe_others": True})
session.set_peer_config(bob, {"observe_me": False})
session.set_peer_config(alice, SessionPeerConfig(observe_others=True))
session.set_peer_config(bob, SessionPeerConfig(observe_me=False))
# Get session-peer configuration
charlie_config = session.get_peer_config(charlie)
@ -142,7 +342,7 @@ import { Honcho } from "@honcho-ai/sdk";
// Add another peer to the session with a custom configuration
const charlie = await honcho.peer("charlie");
await session.addPeers([charlie, { observe_me: false, observe_others: true }]);
await session.addPeers([[charlie, { observe_me: false, observe_others: true }]]);
// Set session-peer configuration
await session.setPeerConfig(alice, { observe_others: true });
@ -154,3 +354,45 @@ import { Honcho } from "@honcho-ai/sdk";
})();
```
</CodeGroup>
## Full Configuration Schema Reference
### Workspace & Session Configuration
```json
{
"deriver": {
"enabled": true
},
"peer_card": {
"use": true,
"create": true
},
"summary": {
"enabled": true,
"messages_per_short_summary": 20,
"messages_per_long_summary": 60
},
"dream": {
"enabled": true
}
}
```
### Message Configuration
```json
{
"deriver": {
"enabled": true
},
"peer_card": {
"use": true,
"create": true
}
}
```
<Note>
Message configuration only supports `deriver` and `peer_card` settings. Summary and dream configurations are session/workspace-level only.
</Note>

861
docs/v2/documentation/features/get-context.mdx
View File

File diff suppressed because it is too large Load Diff

204
docs/v2/documentation/reference/sdk.mdx
View File

@ -278,6 +278,17 @@ results = alice.search("programming")
metadata = alice.get_metadata()
metadata["location"] = "Paris"
alice.set_metadata(metadata)
# Get peer context (representation + peer card in one call)
context = alice.get_context()
context = alice.get_context(target="bob") # What alice knows about bob
# Get working representation with semantic search
rep = alice.working_rep(search_query="preferences", search_top_k=10)
# Access observations
self_observations = alice.observations.list() # Self-observations
bob_observations = alice.observations_of("bob").list() # Observations of bob
```
```typescript TypeScript
@ -318,6 +329,109 @@ await alice.setMetadata({
...metadata,
location: "Paris"
});
// Get peer context (representation + peer card in one call)
const context = await alice.getContext();
const targetContext = await alice.getContext("bob"); // What alice knows about bob
// Get working representation with semantic search
const rep = await alice.workingRep(undefined, undefined, {
searchQuery: "preferences",
searchTopK: 10
});
// Access observations
const selfObs = await alice.observations.list(); // Self-observations
const bobObs = await alice.observationsOf("bob").list(); // Observations of bob
```
</CodeGroup>
### Peer Context
The `get_context()` method on peers retrieves both the working representation and peer card in a single API call:
<CodeGroup>
```python Python
# Get peer's own context
context = alice.get_context()
print(context.representation) # Working representation
print(context.peer_card) # Peer card as list of strings
# Get context about another peer (what alice knows about bob)
bob_context = alice.get_context(target="bob")
# Get context with semantic search
context = alice.get_context(
target="bob",
search_query="work preferences",
search_top_k=10,
search_max_distance=0.8,
include_most_derived=True,
max_observations=50
)
```
```typescript TypeScript
// Get peer's own context
const context = await alice.getContext();
console.log(context.representation); // Working representation
console.log(context.peerCard); // Peer card as array of strings
// Get context about another peer (what alice knows about bob)
const bobContext = await alice.getContext("bob");
// Get context with semantic search
const searchedContext = await alice.getContext("bob", {
searchQuery: "work preferences",
searchTopK: 10,
searchMaxDistance: 0.8,
includeMostDerived: true,
maxObservations: 50
});
```
</CodeGroup>
### Observations
Peers can access their observations (facts derived from messages) through the `observations` property and `observations_of()` method:
<CodeGroup>
```python Python
# Access self-observations (what honcho knows about alice)
self_obs = alice.observations
# List self-observations
obs_list = self_obs.list()
# Search self-observations semantically
results = self_obs.query("food preferences")
# Delete an observation
self_obs.delete("observation-id")
# Access observations of another peer (what alice knows about bob)
bob_obs = alice.observations_of("bob")
bob_obs_list = bob_obs.list()
bob_search = bob_obs.query("work history")
```
```typescript TypeScript
// Access self-observations (what honcho knows about alice)
const selfObs = alice.observations;
// List self-observations
const obsList = await selfObs.list();
// Search self-observations semantically
const results = await selfObs.query("food preferences");
// Delete an observation
await selfObs.delete("observation-id");
// Access observations of another peer (what alice knows about bob)
const bobObs = alice.observationsOf("bob");
const bobObsList = await bobObs.list();
const bobSearch = await bobObs.query("work history");
```
</CodeGroup>
@ -361,12 +475,42 @@ messages = session.get_messages()
# Get conversation context
context = session.get_context(summary=True, tokens=2000)
# Get context with peer representation included
context = session.get_context(
tokens=2000,
peer_target="user",
peer_perspective="assistant",
last_user_message="What are my preferences?",
limit_to_session=True,
search_top_k=10,
search_max_distance=0.8,
include_most_derived=True,
max_observations=25
)
# Search session content
results = session.search("help")
# Working representation queries
# Working representation queries with semantic search
global_rep = session.working_rep("alice")
targeted_rep = session.working_rep(alice, bob)
targeted_rep = session.working_rep(alice, target=bob)
searched_rep = session.working_rep(
"alice",
search_query="preferences",
search_top_k=10,
include_most_derived=True
)
# Upload a file to create messages
messages = session.upload_file(
file=open("document.pdf", "rb"),
peer_id="user",
metadata={"source": "upload"},
created_at="2024-01-15T10:30:00Z"
)
# Delete session (async - returns 202)
session.delete()
# Metadata management
session.set_metadata({"topic": "product planning", "status": "active"})
@ -402,12 +546,43 @@ const messages = await session.getMessages();
// Get conversation context
const context = await session.getContext({ summary: true, tokens: 2000 });
// Get context with peer representation included
const richContext = await session.getContext({
tokens: 2000,
peerTarget: "user",
peerPerspective: "assistant",
lastUserMessage: "What are my preferences?",
limitToSession: true,
searchTopK: 10,
searchMaxDistance: 0.8,
includeMostDerived: true,
maxObservations: 25
});
// Search session content
const results = await session.search("help");
// Working representation queries
// Working representation queries with semantic search
const globalRep = await session.workingRep("alice");
const targetedRep = await session.workingRep(alice, bob);
const targetedRep = await session.workingRep(alice, { target: bob });
const searchedRep = await session.workingRep("alice", undefined, {
searchQuery: "preferences",
searchTopK: 10,
includeMostDerived: true
});
// Upload a file to create messages
const messages = await session.uploadFile(
fileBuffer,
"user",
{
metadata: { source: "upload" },
createdAt: "2024-01-15T10:30:00Z"
}
);
// Delete session (async - returns 202)
await session.delete();
// Metadata management
await session.setMetadata({
@ -494,10 +669,27 @@ The SessionContext object has the following structure:
"message_id": 123,
"summary_type": "short|long",
"created_at": "2024-01-15T10:30:00Z"
}
},
"peer_representation": "string (optional)",
"peer_card": ["string"] // optional, included when peer_target is provided
}
```
**Session Context Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `summary` | `bool` | Whether to include summary (default: true) |
| `tokens` | `int` | Maximum tokens to include |
| `peer_target` | `str` | Peer ID to get representation for |
| `peer_perspective` | `str` | Peer ID for perspective (requires peer_target) |
| `last_user_message` | `str` | Most recent message for semantic search |
| `limit_to_session` | `bool` | Limit representation to session only |
| `search_top_k` | `int` | Number of semantic search results (1-100) |
| `search_max_distance` | `float` | Max semantic distance (0.0-1.0) |
| `include_most_derived` | `bool` | Include most derived observations |
| `max_observations` | `int` | Max observations to include (1-100) |
## Advanced Usage
### Multi-Party Conversations
@ -757,4 +949,4 @@ for await (const peer of await honcho.getPeers()) {
// Process one peer at a time without loading all into memory
}
```
</CodeGroup>
</CodeGroup>

78
docs/v2/documentation/scratch/working-rep.mdx
View File

@ -22,7 +22,7 @@ Working representations are automatically generated and cached through Honcho's
## Basic Usage
Working representations are accessed through the `working_rep()` method on Session objects:
Working representations are accessed through the `working_rep()` method on Session or Peer objects:
<CodeGroup>
```python Python
@ -50,6 +50,9 @@ response = user.chat("What is this user's main concern right now?", session_id=s
# 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
@ -77,7 +80,76 @@ const response = await user.chat("What is this user's main concern right now?",
// Retrieve the cached working representation for the user
const userRepresentation = await session.workingRep("user-123");
console.log("Cached user representation:", userRepresentation);
// Returns: { representation: Object }
// 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>
@ -272,4 +344,4 @@ Working representations provide fast access to cached psychological models that
- 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.
You can build efficient applications that leverage Honcho's continuous learning about peer knowledge and mental states without the latency of real-time generation.

6
docs/v2/guides/storing-data.mdx
View File

@ -18,7 +18,7 @@ A `Message` is sent by a `Peer` and saved in a `Session`
session = honcho.session("sample-session")
message = peer.message("Hello, world!", session_id=session.id)
message = peer.message("Hello, world!")
session.add_messages([message])
```
@ -42,7 +42,7 @@ Once a `Message` is saved in Honcho, it will kick off a background task that
looks at the new data to generate insights about the `Peer` that sent the `Message`
This is the default behavior of Honcho and can be turned off by [configuring the
Peer or Session](/v2/documentation/features/advanced/configuration)
Peer or Session](/v2/documentation/core-concepts/configuration)
This pattern of having a Peer, Session, and Messages is highly flexible and
works for many different use cases and agent setups. Some use cases may only
@ -58,4 +58,4 @@ In this case you can simply
- Make a `Peer` for the AI
Then you can make a `Session` for each thread of conversation and save
`Messages` from the user and assistant in each turn of conversation
`Messages` from the user and assistant in each turn of conversation