From d4b617f4c1de99e2bbfd339155b4b310c6fba912 Mon Sep 17 00:00:00 2001 From: vintro Date: Mon, 8 Dec 2025 21:42:25 -0500 Subject: [PATCH] fix: various tweaks, another plan --- .../core-concepts/representation.mdx | 2 +- .../advanced/representation-scopes.mdx | 2 +- .../features/advanced/toggle-reasoning.mdx | 18 +++++++++++------- docs/v2/guides/discord.mdx | 12 ++++++------ docs/v2/guides/file-uploads.mdx | 2 +- docs/v2/guides/overview.mdx | 10 ++++------ 6 files changed, 24 insertions(+), 22 deletions(-) diff --git a/docs/v2/documentation/core-concepts/representation.mdx b/docs/v2/documentation/core-concepts/representation.mdx index 30d84c6e..dfc7444a 100644 --- a/docs/v2/documentation/core-concepts/representation.mdx +++ b/docs/v2/documentation/core-concepts/representation.mdx @@ -33,7 +33,7 @@ In the diagram below, assume `observe_me` isn't turned off (again, default behav ![](/images/observe_config.png) -The shared session that Alice and Bob have informs their respective representations of each other. Alice has a small set of conclusions that pertain to Bob, and Bob has a small set of conclusions that pertain to Alice. Honcho can observe the totality of each peer's interactions, forming representations of the peers themselves, and enable peers to store conclusions about peers they interact with based only on what they witness in shared sessions. +The shared session that Alice and Bob have informs their respective representations of each other. Alice has a small set of conclusions that pertain to Bob, and Bob has a small set of conclusions that pertain to Alice. Honcho can observe the totality of each peer's interactions, forming representations of the peers themselves, and enable peers to store conclusions about peers they interact with based only on what they witness in shared sessions. Why would you want peers observing others? So you can simulate stateful *perspectives*. If Bob participates in sessions 1 and 2 with Alice, while Carol only participates in session 3, Bob's representation of Alice will be built from sessions 1 and 2, while Carol's representation will only include what happened in session 3. This information segmentation based on what each agent observed is critical for accurately segmenting statefulness in multi-agent scenarios. diff --git a/docs/v2/documentation/features/advanced/representation-scopes.mdx b/docs/v2/documentation/features/advanced/representation-scopes.mdx index 47c6f463..21b46c09 100644 --- a/docs/v2/documentation/features/advanced/representation-scopes.mdx +++ b/docs/v2/documentation/features/advanced/representation-scopes.mdx @@ -30,7 +30,7 @@ Alice → Charlie: "I didn't eat breakfast. I lied to Bob." With global representations, Bob could query Honcho and discover the lie. With local representations, Bob's model of Alice only includes what Bob has directly observed—so he still believes Alice ate pancakes. -Global vs Local Representations +![](/images/observe_config.png) Local representations are disabled by default. Enable them only when you need perspective-taking or information asymmetry. diff --git a/docs/v2/documentation/features/advanced/toggle-reasoning.mdx b/docs/v2/documentation/features/advanced/toggle-reasoning.mdx index 12f6a2cb..608f0d0b 100644 --- a/docs/v2/documentation/features/advanced/toggle-reasoning.mdx +++ b/docs/v2/documentation/features/advanced/toggle-reasoning.mdx @@ -1,12 +1,10 @@ --- title: 'Toggle Reasoning' -description: 'Concerned with all the places you can turn reasoning off' +description: 'Customize how Honcho reasons over peers, sessions, and messages' icon: 'wrench' --- -Customizing how Honcho handles peers, sessions, and messages - -Honcho's reasoning engine can be configured at multiple levels to control how it processes messages, generates facts, creates summaries, and builds peer representations. +Honcho's reasoning can be configured at multiple levels to control how it processes messages, generates conclusions, creates summaries, and builds peer representations. 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. @@ -14,6 +12,8 @@ Configuration follows a hierarchy: **message > session > workspace > global defa Honcho uses a hierarchical configuration system where more specific settings override more general ones: +TODO: should peer be included here? + 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 @@ -27,7 +27,7 @@ All configuration fields are optional. If not specified, the value is inherited ### Reasoning Configuration -Controls the core reasoning engine that extracts facts and insights from messages. +Controls whether the system should reason over messages. | Field | Type | Description | |-------|------|-------------| @@ -60,7 +60,9 @@ const session = await honcho.session("private-session", { ### Peer Card Configuration -Controls how peer cards (concise summaries of what's known about a peer) are generated and used. +TODO: is create a catch-all for update? + +Controls how peer cards (containing key biographical information) are generated and used. | Field | Type | Description | |-------|------|-------------| @@ -121,6 +123,8 @@ const session = await honcho.session("verbose-session", { ### Dream Configuration +TODO: fill out code blocks? or get rid of them? having them there for comments seems silly + Controls the "dreaming" process that consolidates and refines representations. Available at workspace and session levels only. | Field | Type | Description | @@ -142,7 +146,7 @@ Controls the "dreaming" process that consolidates and refines representations. A ## 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. +By default, all peers are "observed" by Honcho. This means that Honcho will reason over 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 access advanced reasoning for. You may therefore disable observation of a peer by setting the `observe_me` flag in their configuration to `false`. diff --git a/docs/v2/guides/discord.mdx b/docs/v2/guides/discord.mdx index a87826ac..5b24dca8 100644 --- a/docs/v2/guides/discord.mdx +++ b/docs/v2/guides/discord.mdx @@ -193,14 +193,14 @@ After generating the response, we save both the user's input and the bot's respo ## Slash Commands -Discord bots also offer slash command functionality. Here's an example using Honcho's dialectic feature: +Discord bots also offer slash command functionality. Here's an example using Honcho's chat endpoint feature: ```python @bot.slash_command( - name="dialectic", - description="Query the Honcho Dialectic endpoint.", + name="chat", + description="Query the peer's representation in natural language.", ) -async def dialectic(ctx, query: str): +async def chat(ctx, query: str): await ctx.defer() try: @@ -225,7 +225,7 @@ async def dialectic(ctx, query: str): ) ``` -This slash command uses Honcho's dialectic functionality to answer questions about the user based on their conversation history. +This slash command uses Honcho's chat endpoint functionality to answer questions about the user based on their conversation history. ## Setup and Configuration @@ -248,7 +248,7 @@ The new Honcho peer/session API makes Discord bot integration much simpler and m - **Peer/Session Model**: Users are represented as peers, conversations as sessions - **Automatic Context Management**: `session.get_context().to_openai()` automatically formats chat history - **Message Storage**: `session.add_messages()` stores both user and assistant messages -- **Dialectic Queries**: `peer.chat()` enables querying conversation history +- **Representation Queries**: `peer.chat()` enables querying conversation history - **Helper Functions**: Clean code organization with focused helper functions This approach provides a clean, maintainable structure for building Discord bots with conversational memory and context management. diff --git a/docs/v2/guides/file-uploads.mdx b/docs/v2/guides/file-uploads.mdx index 1f275fa6..62842856 100644 --- a/docs/v2/guides/file-uploads.mdx +++ b/docs/v2/guides/file-uploads.mdx @@ -4,7 +4,7 @@ description: 'Upload PDFs, text files, and JSON documents to create messages in icon: 'upload' --- -Honcho's file upload feature allows you to convert documents into messages automatically. Upload PDFs, text files, or JSON documents, and Honcho will extract the text content, split it into appropriately sized chunks, and create messages that become part of your peer's knowledge or session context. +Honcho's file upload feature allows you to convert documents into messages automatically. Upload PDFs, text files, or JSON documents, and Honcho will extract the text content, split it into appropriately sized chunks, and create messages that become part of your peer's representation or session context. This feature is perfect for ingesting documents, reports, research papers, or any text-based content that you want your AI agents to understand and reference. diff --git a/docs/v2/guides/overview.mdx b/docs/v2/guides/overview.mdx index dcaf5b48..2aee50a4 100644 --- a/docs/v2/guides/overview.mdx +++ b/docs/v2/guides/overview.mdx @@ -1,17 +1,15 @@ --- -title: "Spellbooks and Tutorials" +title: "Guides, Cookbooks, and Integrations" sidebarTitle: 'Overview' description: 'Helpful guides and design patterns for building with Honcho' icon: 'hat-wizard' --- - Before you start a tutorial, follow [Quickstart](/v2/documentation/introduction/quickstart) to get up and running with Honcho in your language of choice. + Before you start a guide, follow [Quickstart](/v2/documentation/introduction/quickstart) to get up and running with Honcho in your language of choice. -AI development often feels like magic - you craft the right prompt and get exactly what you need. Our Spellbooks are practical guides that show you how to cast effective spells with Honcho. +These guides provide concrete examples and implementation patterns for building with Honcho. Whether you're integrating Honcho into existing platforms, exploring advanced features, or getting up and running quickly, you'll find working code you can adapt to your needs. -Whether you're integrating Honcho into existing platforms, exploring advanced features, or getting up and running quickly, these guides provide concrete examples and implementation patterns. - -Each spellbook focuses on a specific use case with working code you can adapt to your needs. The goal is to get you from idea to working prototype as quickly as possible, then provide the depth you need to scale and customize. +Each guide focuses on a specific use case with practical examples. The goal is to get you from idea to working prototype as quickly as possible, then provide the depth you need to scale and customize. ## Application Interfaces