diff --git a/docs/docs.json b/docs/docs.json index 4df76911..890415d5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -34,7 +34,7 @@ "group": "Core Concepts", "pages": [ "v2/documentation/core-concepts/architecture", - "v2/documentation/core-concepts/features/messages-and-memories", + "v2/documentation/core-concepts/features/storing-data", "v2/documentation/core-concepts/features/dialectic-endpoint", "v2/documentation/core-concepts/features/get-context", "v2/documentation/core-concepts/features/search", @@ -43,7 +43,7 @@ "v2/documentation/core-concepts/features/using-filters", "v2/documentation/core-concepts/features/file-uploads", "v2/documentation/core-concepts/features/queue-status", - "v2/documentation/core-concepts/features/local-vs-global-representations", + "v2/documentation/core-concepts/features/local-vs-global", "v2/documentation/core-concepts/configuration", "v2/documentation/core-concepts/summarizer", "v2/documentation/core-concepts/glossary" diff --git a/docs/v2/documentation/core-concepts/features.mdx b/docs/v2/documentation/core-concepts/features.mdx deleted file mode 100644 index cc1d402e..00000000 --- a/docs/v2/documentation/core-concepts/features.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: 'Features' -description: 'Key features and capabilities of Honcho' -icon: 'star' ---- - -This page is a quick overview of the features within Honcho. In-depth -guides are available for each feature in the [Spellbooks - Design Patterns](../../guides/overview#design-patterns) section. - -### Local vs Global Representation -Peers in Honcho are abstract entities that can represent humans, agents, or NPCs. Honcho has a two-layer approach to forming representations of Peers. -- **Global Representation**: Representation owned by a Peer that is constructed from everything the Peer has sent within Honcho. -- **Local Representation**: The representation that a Peer forms of other Peers, based on the messages those other Peers have sent (as observed by the Peer forming the representation). -- At the Session level, you can configure which Peers are able to observe messages from other Peers in that Session. This determines which Peers form representations of others within the Session. - -### Queue Status -To help developers understand when a Peer's representation is fully up to date, Honcho exposes the ability to poll the status of Peer-centric queues that construct representations. -- If no Session is specified, the queue status reflects pending work for the Peer's global representation. -- If a Session is specified, the queue status reflects pending work for the Peer's working representation in that Session. - -### Search -Honcho implements a powerful search endpoint that allows you to search for messages across a workspace, session, or peer with complex [filters](/v2/guides/using-filters). - -The search process combines full-text and semantic search using reciprocal rank fusion. By default, all messages ingested into Honcho have embeddings generated and stored in the database, enabling semantic search -- if this feature is disabled, the search process will only use full-text search. - -Results are returned in the form of a list of Message objects, and you may choose how many results to return. The default is 10 results, with a maximum of 100. - -In the SDK, search is available on `Workspace`, `Session`, and `Peer` objects, and an optional `filters` parameter may be used to apply a narrower search scope such as a time range or developer-defined metadata attached to messages. - -Note that results are not ordered by recency, only relevance. Results can be sorted by timestamp or a filter on the `created_at` field can limit results to recent messages. - -[Look here for examples of how to use search in the SDK](/v2/guides/search). - -### Scoped API Keys -Builders can create scoped API keys to control access to different resources within Honcho. -- **Workspace-Level Keys**: Access to everything scoped to a Workspace. -- **Peer-Level Keys**: Access to everything scoped to a Peer. -- **Session-Level Keys**: Access to everything scoped to a Session. - -### Get Context -Honcho provides a powerful context retrieval feature that delivers formatted conversation context from sessions, making it easy to integrate with LLMs like OpenAI, Anthropic, and others. -- By default, the context includes a blend of summary and messages which covers the entire history of the session. -- Summaries are generated automatically at intervals, and recent messages are included based on your specified token budget for the context. -- You can set any token limit, and if you prefer, you can disable summaries so that the context consists entirely of the most recent messages up to your chosen limit. diff --git a/docs/v2/documentation/core-concepts/features/local-vs-global.mdx b/docs/v2/documentation/core-concepts/features/local-vs-global.mdx new file mode 100644 index 00000000..16f04494 --- /dev/null +++ b/docs/v2/documentation/core-concepts/features/local-vs-global.mdx @@ -0,0 +1,68 @@ +--- +title: Local vs Global Representations +description: Use Honcho that model directional relationships of Peers +icon: location-pin +--- + +One of the unique affordances of Honcho is that it allows developers to model +directional relationships between Peers. What I mean by this is you can model +how one `Peer` thinks about another `Peer`. + +There are many use cases where you don't want every agent or human to know +everything about another user such as games or multi-agent workflows. To +illustrate further the following examples shows 2 conversations. + +Conversation #1 (With Bob and Alice) +``` +Alice: I had a great breakfast today. +Bob: What did you eat? +Alice: I had pancakes and eggs and bacon +``` + +Conversation #2 (With Alice and Charlie) +``` +Alice: I actually didn't eat any breakfast today. +Charlie: Oh that's too bad. +Alice: But I lied to Bob and told him I did, so back me up if you see them. +``` + +Alice told Bob a lie in this conversation. If we stored both of these +conversations in Honcho with Alice, Bob, and Charlie as `Peers` and let them +use Honcho to get insights on each other then Bob would immediately know this +deception. For example: + + + ```python Python + # Bob could run + alice.chat("What did Alice eat today?") + # Response: Alice did not eat anything today + ``` + + +This is a problem. Bob shouldn't be able to know everything about Alice in this +situation. So to support these situations we support what we call **Local +Representations**. + +By default insights generated for a `Peer` are scoped globally. This means every +message sent by that `Peer` in any conversation updates the same representation +of that `Peer`. However, we can enable **Local Representations** so Bob can +form a representation Alice based only on what they observe Alice do. + +This feature is illustrated in the graphic below: +Peer Representations + +We can enable local representation for a peer by setting `observe_others=True`. +This is show in the [Configure +Reasoning](/v2/documentation/core-concepts/configuration) page. + +Now if we used Bob's local representation of Alice then Bob would only get +insights on what they've seen Alice say to them. + +```python +bob.chat(target="alice", query="What did Alice eat today?") +# Response: Alice ate pancakes, eggs, and bacon +``` + + + Local Representations are turned off by default + diff --git a/docs/v2/documentation/core-concepts/features/queue-status.mdx b/docs/v2/documentation/core-concepts/features/queue-status.mdx new file mode 100644 index 00000000..73f732f2 --- /dev/null +++ b/docs/v2/documentation/core-concepts/features/queue-status.mdx @@ -0,0 +1,132 @@ +--- +title: Queue Status +description: Learn how to check the status of the Deriver +icon: lines-leaning +--- + +Whenever `Messages` are stored in Honcho a background process called the +[Deriver](/docs/v2/documentation/core-concepts/architecture#reasoning-layer) is +triggered to reasoning about the conversation and generate insights. + +The Deriver is an asynchronous process and depending on load may not immediately +generated insights for the latest message you've sent. To help with this, Honcho +provides several utilities to check the status of the Deriver. + + +```python Python +from honcho import Honcho +honcho = Honcho() + +status = honcho.get_deriver_status() +honcho.poll_deriver_status() +``` + +```typescript typescript +import { Honcho } from '@honcho-ai/sdk'; + +const honcho = new Honcho({}); + +const status = await honcho.getDeriverStatus(); +await honcho.pollDeriverStatus(); +``` + + +Output types + + +```python Python +class DeriverStatus(BaseModel): + completed_work_units: int + """Completed work units""" + + in_progress_work_units: int + """Work units currently being processed""" + + pending_work_units: int + """Work units waiting to be processed""" + + total_work_units: int + """Total work units""" + + sessions: Optional[Dict[str, Sessions]] = None + """Per-session status when not filtered by session""" +``` +```typescript TypeScript +Promise<{ + totalWorkUnits: number + completedWorkUnits: number + inProgressWorkUnits: number + pendingWorkUnits: number + sessions?: Record + }> + +``` + + +Whenever a `Message` is sent it will generate several tasks. These could +be tasks such as generating insights, cleaning up a representation, summarizing +a conversation etc. These tasks are defined based on who is sending the +message, what `Session` the message is in, and potentially who is observing the +message. We call the combination of these parameters a `work_unit` + +This has a few different implications. + +- tasks within the same work_unit are processed sequentially, but multiple +work_units will be processed in parallel +- If local representations are turned in a Session then a `Message` will + generate an additional work unit for every `Peer` that has `observe_others=True` + +The `get_deriver_status` and `poll_deriver_status` methods can take additional +parameters to scope the status to a specific work unit + + +```python Python +def get_deriver_status( + self, + observer_id: str | None = None, + sender_id: str | None = None, + session_id: str | None = None, + ) -> DeriverStatus: +``` +```typescript TypeScript + +export const DeriverStatusOptionsSchema = z.object({ + observerId: z.string().optional(), + senderId: z.string().optional(), + sessionId: z.string().optional(), + timeoutMs: z + .number() + .positive('Timeout must be a positive number') + .optional(), +}) + +``` + + +Additionally, there are deriver status and polling deriver status methods +available on the `Session` objects in each of the SDKs. + +Below are the function signatures for the session level deriver status method + + +```python python +@validate_call + def get_deriver_status( + self, + observer_id: str | None = None, + sender_id: str | None = None, + ) -> DeriverStatus: +``` + +```typescript TypeScript +async getDeriverStatus( + options?: Omit + ): Promise<{ + totalWorkUnits: number + completedWorkUnits: number + inProgressWorkUnits: number + pendingWorkUnits: number + sessions?: Record + }> +``` + diff --git a/docs/v2/documentation/core-concepts/features/storing-data.mdx b/docs/v2/documentation/core-concepts/features/storing-data.mdx new file mode 100644 index 00000000..0a7f910a --- /dev/null +++ b/docs/v2/documentation/core-concepts/features/storing-data.mdx @@ -0,0 +1,61 @@ +--- +title: Storing Data +description: "Store Data in Honcho to Generate Memories and Insights" +icon: "memory" +--- + +The most basic building block of Honcho's data model is the `Message` object. +A `Message` is sent by a `Peer` and saved in a `Session` + + + + ```python Python + from honcho import Honcho + + honcho = Honcho() + + peer = honcho.peer("sample-peer") + + session = honcho.session("sample-session") + + message = peer.message("Hello, world!", session_id=session.id) + + session.add_messages([message]) + ``` + + ```typescript TypeScript + import { Honcho } from '@honcho-ai/sdk'; + + const honcho = new Honcho({}); + + const peer = await honcho.peer('sample-peer'); + + const session = await honcho.session('sample-session'); + + const message = peer.message('Hello, world!'); + + await session.addMessages([message]); +``` + + +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/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 +need a single Peer, but many Sessions. Others will only use a single `Session` +for their entire app. These are flexible components that work in any situation. + +## Chat Bots + +A common use case for Honcho to is to build a Chatbot like ChatGPT or Claude. +This this case you can simply + +- Make a `Peer` for the User +- 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