Docs Refresh (#200)
* Initial Draft * Split up code block * Clean up code * Add retrieval use cases * fix: Code Rabbit Suggestions * Code Rabbit AGain
This commit is contained in:
Vineeth Voruganti
GitHub
parent
6b7cf82c1c
commit
2c5c0f0b62
182
README.md
182
README.md
|
|
@ -1,23 +1,117 @@
|
|||
# 🫡 Honcho
|
||||
<!-- markdownlint-disable MD033 -->
|
||||
<div align="center">
|
||||
<a href="https://app.honcho.dev" target="_blank">
|
||||
<img src="assets/honcho.svg" alt="Honcho" width="400">
|
||||
</a>
|
||||
</div>
|
||||
<!-- markdownlint-enable MD033 -->
|
||||
|
||||
---
|
||||
|
||||
|
||||
[](https://discord.gg/plasticlabs)
|
||||
[](https://arxiv.org/abs/2310.06983)
|
||||
|
||||
|
||||
[](https://twitter.com/plastic_labs)
|
||||
[](https://pypi.org/project/honcho-ai/)
|
||||
[](https://npmjs.org/package/@honcho-ai/sdk)
|
||||
[](https://discord.gg/plasticlabs)
|
||||
[](https://arxiv.org/abs/2310.06983)
|
||||
|
||||
Honcho is an infrastructure layer for building AI agents with social cognition and theory-of-mind capabilities. It enables developers to create AI agents and LLM-powered applications that are personalized to their end users by leveraging the inherent theory-of-mind capabilities of LLMs to build coherent models of user psychology over time.
|
||||
Honcho is an AI-native memory library for building agents with perfect memory and
|
||||
social cognition.
|
||||
|
||||
Read about the project [here](https://blog.plasticlabs.ai/blog/A-Simple-Honcho-Primer).
|
||||
It provides [state-of-the-art
|
||||
memory](https://blog.plasticlabs.ai/research/Introducing-Neuromancer-XR) and
|
||||
then goes beyond storage by reasoning about the stored data to build
|
||||
rich psychological profiles of each user in your system.
|
||||
|
||||
Read the user documentation [here](https://docs.honcho.dev)
|
||||
Use it to build
|
||||
|
||||
## Table of Contents
|
||||
- Highly personalized experiences
|
||||
- Agents with social cognition
|
||||
- Agents with rich identity that evolve over time
|
||||
- Multi-agent systems with complex social dynamics
|
||||
|
||||
## TL;DR - Getting Started
|
||||
|
||||
With Honcho you can easily setup your application's workflow, save your
|
||||
interaction history, and leverage generated insights to inform the behavior of
|
||||
your agents
|
||||
|
||||
> Typescript examples are available in our [docs](https://docs.honcho.dev)
|
||||
|
||||
1. Install the SDK
|
||||
|
||||
```bash
|
||||
# Python
|
||||
pip install honcho-ai
|
||||
uv add honcho-ai
|
||||
poetry add honcho-ai
|
||||
```
|
||||
|
||||
2. Setup your `Workspace`, `Peers`, `Session`, and send `Messages`
|
||||
|
||||
```python
|
||||
from honcho import Honcho
|
||||
|
||||
####### Storing Data in Honcho
|
||||
|
||||
# 1. Initialize your Honcho client, by default SDK will use the demo environment and workspace named "default"
|
||||
honcho = Honcho(environment="demo", workspace_id="my-app-testing")
|
||||
|
||||
# 2.. Initialize Peers
|
||||
alice = honcho.peer("alice")
|
||||
tutor = honcho.peer("tutor")
|
||||
|
||||
# 3. Make a Session and send messages
|
||||
|
||||
session = honcho.session("session-1")
|
||||
|
||||
session.add_messages(
|
||||
alice.message("Hey there can you help me with my math homework"),
|
||||
tutor.message("Absolutely send me your first problem!"),
|
||||
.
|
||||
.
|
||||
.
|
||||
)
|
||||
```
|
||||
|
||||
3. Leverage insights from Honcho to inform your agent's behavior
|
||||
|
||||
```python
|
||||
|
||||
### 1. Use the Dialectic API to ask questions about your users in natural language
|
||||
response = alice.chat("What learning styles does the user respond to best?")
|
||||
|
||||
### 2. Use Get context to get most recent messages and summaries to continue a conversation
|
||||
context = session.get_context(summary=True, tokens=10000)
|
||||
|
||||
# Convert to a format to send to OpenAI and get the next message
|
||||
openai_messages = context.to_openai_messages(assistant=tutor)
|
||||
|
||||
from openai import OpenAI
|
||||
client = Openai()
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4",
|
||||
messages=openai_messages
|
||||
)
|
||||
|
||||
### 3. Search for similar messages
|
||||
results = alice.search("Math Homework")
|
||||
|
||||
### 4. Get a cached working representation of a Peer for the Session
|
||||
alice_representation = session.working_rep("alice")
|
||||
|
||||
```
|
||||
|
||||
This is a simple example of how you can use Honcho to build a chatbot and
|
||||
leverage insights to personalize the agent's behavior.
|
||||
|
||||
Sign up at [app.honcho.dev](https://app.honcho.dev) to get started with a managed version of Honcho.
|
||||
|
||||
Learn more ways to use Honcho on our [developer docs](https://docs.honcho.dev).
|
||||
|
||||
Read about the design philosophy and history of the project on our [blog](https://blog.plasticlabs.ai/).
|
||||
|
||||
## Project Structure
|
||||
|
||||
- [Project Structure](#project-structure)
|
||||
- [Usage](#usage)
|
||||
- [Local Development](#local-development)
|
||||
- [Prerequisites and Dependencies](#prerequisites-and-dependencies)
|
||||
|
|
@ -31,12 +125,11 @@ Read the user documentation [here](https://docs.honcho.dev)
|
|||
- [Example](#example)
|
||||
- [Architecture](#architecture)
|
||||
- [Storage](#storage)
|
||||
- [Insights](#insights)
|
||||
- [Reasoning](#reasoning)
|
||||
- [Retrieving Data & Insights](#retrieving-data--insights)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
|
||||
## Project Structure
|
||||
|
||||
The Honcho project is split between several repositories with this one hosting
|
||||
the core service logic. This is implemented as a FastAPI server/API to store
|
||||
data about an application's state.
|
||||
|
|
@ -396,9 +489,9 @@ Below is a mapping of the different primitives and their relationships.
|
|||
Workspaces
|
||||
├── Peers ←──────────────────┐
|
||||
│ ├── Sessions │
|
||||
│ ├── Collections │
|
||||
│ │ └── Documents │
|
||||
│ └── Messages (peer-level)│
|
||||
│ └── Collections │
|
||||
│ └── Documents │
|
||||
│ │
|
||||
│ │
|
||||
└── Sessions ←───────────────┤ (many-to-many)
|
||||
├── Peers ───────────────┘
|
||||
|
|
@ -411,7 +504,6 @@ Workspaces
|
|||
- **Peers** and **Sessions** have a many-to-many relationship (peers can participate in multiple sessions, sessions can have multiple peers)
|
||||
- **Messages** can exist at two levels:
|
||||
- **Session-level**: Communication between peers within a session
|
||||
- **Peer-level**: Data ingested by a peer to enhance its global representation
|
||||
- **Collections** belong to specific **Peers**
|
||||
- **Documents** are stored within **Collections**
|
||||
|
||||
|
|
@ -441,7 +533,6 @@ Sessions can involve multiple peers with configurable observation settings.
|
|||
The `Message` represents an atomic data unit that can exist at two levels:
|
||||
|
||||
- **Session-level Messages**: Communication between peers within a session context
|
||||
- **Peer-level Messages**: Arbitrary data ingested by a peer to enhance its global representation (independent of any session)
|
||||
|
||||
All messages are labeled by their source peer and can be processed
|
||||
asynchronously to update theory-of-mind models. This flexible design allows for
|
||||
|
|
@ -462,26 +553,49 @@ representations of peers.
|
|||
|
||||
As stated before a `Document` is vector embedded data stored in a `Collection`.
|
||||
|
||||
### Insights
|
||||
### Reasoning
|
||||
|
||||
The Insight functionality of Honcho is built on top of the Storage service. As
|
||||
The reasoning functionality of Honcho is built on top of the Storage service. As
|
||||
`Messages` and `Sessions` are created for `Peers`, Honcho will asynchronously
|
||||
reason about peer psychology to derive facts about them and store them
|
||||
in reserved `Collections`.
|
||||
|
||||
The system uses a sophisticated message processing pipeline:
|
||||
A high level summary of the pipeline is as follows:
|
||||
|
||||
1. Messages are created via API
|
||||
2. Enqueued for background processing including:
|
||||
- `representation`: Update peer's theory of mind
|
||||
- `summary`: Create session summaries
|
||||
1. Messages are created via the API
|
||||
2. Derivation Tasks are enqueued for background processing including:
|
||||
- `representation`: To update theory-of-mind representations of `Peers`
|
||||
- `summary`: To create summaries of `Sessions`
|
||||
3. Session-based queue processing ensures proper ordering
|
||||
4. Results are stored internally in the vector database
|
||||
4. Results are stored internally
|
||||
|
||||
To read more about how this works read our [Research Paper](https://arxiv.org/abs/2310.06983)
|
||||
|
||||
Developers can then leverage these insights in their application to better
|
||||
serve peer needs. The primary interface for using these insights is through
|
||||
### Retrieving Data & Insights
|
||||
|
||||
Honcho exposes several different ways to retrieve data from the system to best
|
||||
serve the needs of any given application.
|
||||
|
||||
#### Get Context
|
||||
|
||||
In long-running conversations with an LLM, the context window can fill up
|
||||
quickly. To address this, Honcho provides a `get_context`
|
||||
endpoint that returns a combination of messages and summaries from a
|
||||
session, up to a provided token limit.
|
||||
|
||||
Use this to keep sessions going indefinitely.
|
||||
|
||||
#### Search
|
||||
|
||||
There are several search endpoints that let developers query messages at the
|
||||
`Workspace`, `Session`, or `Peer` level using a hybrid search strategy.
|
||||
|
||||
Requests can include advanced filters to further refine
|
||||
the results.
|
||||
|
||||
#### Dialectic API
|
||||
|
||||
The flagship interface for using these insights is through
|
||||
the [Dialectic Endpoint](https://blog.plasticlabs.ai/blog/Introducing-Honcho's-Dialectic-API).
|
||||
|
||||
This is a regular API endpoint (`/peers/{peer_id}/chat`) that takes natural language requests to get data
|
||||
|
|
@ -497,6 +611,16 @@ API include:
|
|||
- Asking Honcho for a 2nd opinion or approach about how to respond to the Peer
|
||||
- Getting personalized responses that incorporate long-term facts and context
|
||||
|
||||
#### Working Representations
|
||||
|
||||
For low-latency use cases,
|
||||
Honcho provides access to a `get_working_representation` endpoint that
|
||||
returns a static document with insights about a `Peer` in the context of a
|
||||
particular session.
|
||||
|
||||
Use this to quickly add context to a prompt without having to wait for an LLM
|
||||
response.
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions to Honcho! Please read our [Contributing Guide](./CONTRIBUTING.md) for details on our development process, coding conventions, and how to submit pull requests.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,27 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 491.02 144">
|
||||
<defs>
|
||||
<style>
|
||||
.cls-1 {
|
||||
fill: #b5daff;
|
||||
}
|
||||
|
||||
.cls-2 {
|
||||
fill: #191919;
|
||||
}
|
||||
</style>
|
||||
</defs>
|
||||
<rect class="cls-1" x="0" y="0" width="491.02" height="144" rx="70.34" ry="70.34"/>
|
||||
<g>
|
||||
<path class="cls-2" d="M42.36,73.11h0s0,0,0,0Z"/>
|
||||
<g>
|
||||
<path class="cls-2" d="M111.94,38.5v24.08h-16.9v-24.08h-21.06c-11.88,0-22.94,6.36-28.94,16.61-2.66,1.61-4.45,2.74-4.49,2.76-5.17,2.82-7.76,5.51-9.03,7.64-.99.02-1.84.75-1.98,1.75-.16,1.11.62,2.14,1.73,2.3s2.14-.62,2.3-1.73c.08-.57-.09-1.13-.42-1.55,1.87-3.02,5.83-5.51,8.25-6.83.42-.23,23.87-14.43,25.63-14.08.29.06.72.22,1.06.91.93,1.93-7.61,7.63-9.35,8.67-1.67,1-3.13,2.06-4.41,3.2-2.69,2.4-4.49,5.09-5.36,8.05-.53,1.78-2.02,6.91-5.66,8.19-.26-.57-.78-1.02-1.44-1.16-1.1-.23-2.18.48-2.41,1.58-.22,1.04.4,2.06,1.4,2.37,2.51,16.26,16.43,28.31,33.09,28.32h0s21.07.01,21.07.01v-28.16h16.9v28.16h21.07V38.5h-21.07,0ZM55.16,59.86c-.08,1.04-.32,2.24-.91,3.02-.62.82-1.79,1.52-2.84,2.01.83-1.79,2.09-3.47,3.75-5.03h0ZM73.96,83.12h-8.26c-.88,0-1.6.71-1.6,1.6,0,.44.18.84.47,1.13.29.29.69.47,1.13.47h8.26v17.37c-15.77,0-28.94-11.42-31.31-26.81.24-.18.44-.4.59-.67,3.01-1.08,5.29-2.56,7.32-9.03,1.09-.38,3.81-1.46,5.13-3.21,1.32-1.75,1.34-4.5,1.29-5.64.83-.63,1.73-1.24,2.7-1.82,5.56-3.33,11.57-7.86,10.05-11.01-.5-1.04-1.31-1.7-2.33-1.9-1.93-.38-11.56,5.06-18.73,9.32,5.94-7.87,15.32-12.63,25.31-12.63v42.82h0Z"/>
|
||||
<ellipse class="cls-2" cx="63.3" cy="66.65" rx="3.45" ry="5.35"/>
|
||||
<path class="cls-2" d="M187.15,40.14c4.44,2.01,7.66,5.5,9.66,10.49,2.01,4.99,3.01,12.11,3.01,21.36s-1,16.38-3.01,21.36c-2.01,4.99-5.23,8.48-9.66,10.49-4.44,2.01-10.64,3.01-18.6,3.01s-14.07-1-18.5-3.01c-4.44-2.01-7.66-5.5-9.66-10.49-2.01-4.99-3.01-12.11-3.01-21.36s1-16.38,3.01-21.36c2.01-4.99,5.23-8.48,9.66-10.49,4.44-2.01,10.6-3.01,18.5-3.01s14.16,1,18.6,3.01h0ZM162.97,54.38c-1.26,1.07-2.15,2.95-2.67,5.63s-.78,6.69-.78,11.99.26,9.31.78,11.99c.52,2.69,1.41,4.56,2.67,5.63s3.12,1.6,5.58,1.6,4.32-.53,5.58-1.6,2.15-2.95,2.67-5.63c.52-2.69.78-6.69.78-11.99s-.26-9.31-.78-11.99c-.52-2.69-1.41-4.56-2.67-5.63s-3.13-1.6-5.58-1.6-4.32.53-5.58,1.6Z"/>
|
||||
<path class="cls-2" d="M265.77,98.22c0,2.4-.61,4.21-1.84,5.44s-3.04,1.84-5.44,1.84h-8.06c-2.01,0-3.54-.45-4.61-1.36s-2.25-2.49-3.54-4.76l-14.57-23.02c-1.62-2.91-3.11-6.73-4.47-11.46h-.68c.64,4.53.97,8.61.97,12.24v28.36h-19.42v-59.73c0-2.4.61-4.21,1.84-5.44s3.04-1.84,5.44-1.84h8.06c2.01,0,3.53.45,4.56,1.36,1.03.91,2.23,2.49,3.59,4.76l13.99,21.95c1.75,3.11,3.46,6.93,5.15,11.46h.68c-.58-4.92-.88-8.97-.88-12.14l-.1-27.39h19.33v59.73h0Z"/>
|
||||
<path class="cls-2" d="M312.49,37.91c3.04.39,6.34,1.07,9.91,2.04l-1.55,15.34c-1.49,0-2.62-.03-3.4-.1l-17.09-.1c-2.27,0-3.98.47-5.15,1.41-1.17.94-1.98,2.59-2.43,4.95-.45,2.37-.68,5.87-.68,10.54s.23,8.18.68,10.54c.45,2.37,1.26,4.01,2.43,4.95,1.17.94,2.88,1.41,5.15,1.41,5.31,0,9.53-.05,12.67-.15s6.23-.31,9.27-.63l1.55,15.34c-3.43,1.17-6.9,1.99-10.39,2.48s-7.87.73-13.11.73c-7.51,0-13.47-1.12-17.87-3.35-4.4-2.23-7.59-5.86-9.57-10.88-1.98-5.02-2.96-11.83-2.96-20.44s.99-15.43,2.96-20.44c1.97-5.02,5.16-8.64,9.57-10.88,4.4-2.23,10.36-3.35,17.87-3.35,5.05,0,9.09.19,12.14.58h0Z"/>
|
||||
<path class="cls-2" d="M387.85,38.49v67.01h-21.07v-28.17h-16.9v28.17h-21.07V38.49h21.07v24.08h16.9v-24.08s21.07,0,21.07,0Z"/>
|
||||
<path class="cls-2" d="M441.99,40.14c4.44,2.01,7.66,5.5,9.66,10.49,2.01,4.99,3.01,12.11,3.01,21.36s-1,16.38-3.01,21.36c-2.01,4.99-5.23,8.48-9.66,10.49-4.44,2.01-10.64,3.01-18.6,3.01s-14.07-1-18.5-3.01c-4.44-2.01-7.66-5.5-9.66-10.49-2.01-4.99-3.01-12.11-3.01-21.36s1-16.38,3.01-21.36,5.23-8.48,9.66-10.49c4.44-2.01,10.6-3.01,18.5-3.01s14.16,1,18.6,3.01h0ZM417.81,54.38c-1.26,1.07-2.15,2.95-2.67,5.63-.52,2.69-.78,6.69-.78,11.99s.26,9.31.78,11.99c.52,2.69,1.41,4.56,2.67,5.63s3.12,1.6,5.58,1.6,4.32-.53,5.58-1.6,2.15-2.95,2.67-5.63c.52-2.69.78-6.69.78-11.99s-.26-9.31-.78-11.99c-.52-2.69-1.41-4.56-2.67-5.63s-3.13-1.6-5.58-1.6-4.32.53-5.58,1.6Z"/>
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 4.0 KiB |
|
|
@ -27,8 +27,6 @@ Honcho has a hierarchical data model centered around the entities below.
|
|||
W[Workspaces] -->|have| P[Peers]
|
||||
W -->|have| S[Sessions]
|
||||
|
||||
P -->|have| PM[Messages]
|
||||
|
||||
S -->|have| SM[Messages]
|
||||
|
||||
P <-.->|many-to-many| S
|
||||
|
|
@ -36,13 +34,12 @@ Honcho has a hierarchical data model centered around the entities below.
|
|||
style W fill:#FF5A7E,stroke:#333,stroke-width:2px,color:#fff
|
||||
style P fill:#e1f5fe,stroke:#0277bd,color:#000
|
||||
style S fill:#f3e5f5,stroke:#7b1fa2,color:#000
|
||||
style PM fill:#e8f5e9,stroke:#2e7d32,color:#000
|
||||
style SM fill:#e8f5e9,stroke:#2e7d32,color:#000
|
||||
```
|
||||
|
||||
There are `Workspaces` at the top that contain `Peers` and `Sessions`. A `Peer`
|
||||
can be part of many `Sessions` and a `Session` can have many `Peers`. Both
|
||||
`Sessions` and `Peers` can have `Messages`
|
||||
can be part of many `Sessions` and a `Session` can have many `Peers`. `Sessions`
|
||||
hold messages that are sent by `Peers`.
|
||||
|
||||
### <Icon icon="building" /> Workspaces
|
||||
|
||||
|
|
@ -103,14 +100,16 @@ Sessions represent individual conversation threads or interaction contexts betwe
|
|||
- Support tickets
|
||||
- Meeting transcripts
|
||||
- Learning sessions
|
||||
- Single-Peer onboarding sessions where data is imported from an external source
|
||||
|
||||
---
|
||||
|
||||
### <Icon icon="envelope" /> Messages
|
||||
|
||||
Messages are the fundamental units of interaction within sessions. They may
|
||||
also be used at the peer level to ingest information of any kind that is not related to a specific interaction, but provides
|
||||
important context for a peer (emails, docs, files, etc.).
|
||||
also be used to ingest information of any kind that is not related to a specific interaction, but provides
|
||||
important context for a peer (emails, docs, files, etc.). Simple make a session
|
||||
with a single peer and structure the data as messages.
|
||||
|
||||
**Key Features:**
|
||||
- **Rich Content**: Support for text, metadata, and structured data
|
||||
|
|
|
|||
|
|
@ -47,23 +47,32 @@ Designed for developers and agents alike:
|
|||
|
||||
## How It Works
|
||||
|
||||
Honcho operates through two integrated layers:
|
||||
### Storage
|
||||
|
||||
Developers use Honcho to store information about their users and application via
|
||||
two integrated layers:
|
||||
|
||||
<img src="/images/basic_honcho_flowchart.png" alt="Basic Honcho Flowchart" />
|
||||
|
||||
**Memory Layer**: Captures all user interactions - messages, preferences, and
|
||||
behavioral patterns - in a user-centric data model that scales from individual
|
||||
conversations to complex multi-agent scenarios. This also queues up messages for the insights layer to process.
|
||||
behavioral patterns - in a peer-centric data model that scales from individual
|
||||
conversations to complex multi-agent scenarios. This also queues up messages for
|
||||
the reasoning layer to process.
|
||||
|
||||
**Insights Layer**: Continuously analyzes stored interactions to build
|
||||
**Reasoning Layer**: Continuously analyzes stored interactions to build
|
||||
psychological profiles using [theory of mind](glossary#theory-of-mind)
|
||||
inference, extracting patterns about communication style, decision-making
|
||||
preferences, and mental models.
|
||||
|
||||
Agents access this understanding through the [dialectic
|
||||
endpoint](../core-concepts/architecture#dialectic-api) - a natural language API
|
||||
where they can ask specific questions about users and receive actionable
|
||||
insights.
|
||||
### Retrieval
|
||||
|
||||
Once data is stored and generated within Honcho, the API exposes several
|
||||
different ways to retrieve and use those insights.
|
||||
|
||||
**[Dialectic API](../guides/dialectic-endpoint)**: This is the
|
||||
flagship endpoint that allows developers to send natural language queries to
|
||||
Honcho to chat with the representation of each user in your system to get
|
||||
dynamic, in-context actionable insights.
|
||||
|
||||
Example Queries
|
||||
- "What's the best way to explain technical concepts to this user?"
|
||||
|
|
@ -72,6 +81,23 @@ Example Queries
|
|||
- "How does this user prefer to receive feedback?"
|
||||
- "What are this user's core values based on our conversations?"
|
||||
|
||||
**[Get Context](../guides/get-context)**: This endpoint abstracts context window
|
||||
constraints and continuously retrieves the most relevant and recent data from a
|
||||
conversation. Provide a token budget and Honcho will rturn a combination of
|
||||
summaries and messages that pvoide session context. Use this for creating
|
||||
long-running conversations. We crafted our summaries to provide the most
|
||||
[coverage of a session possible](../core-concepts/summarizer).
|
||||
|
||||
**[Search](../guides/search)**: This endpoint allows you to search across Honcho
|
||||
for relevant messages either at the workspace, peer, or session level. This
|
||||
endpoint uses a hybrid search strategy that combines text search and cosine
|
||||
similarity.
|
||||
|
||||
**[Working Representations](../guides/working-rep)**: Get a cached, snapshot
|
||||
of a user in the context of a session. Instead of waiting for an LLM to
|
||||
synthesize an in-context response via the Dialectic endpoint, use this to get
|
||||
recent insights you can plug into your context window.
|
||||
|
||||
## Ideal For
|
||||
|
||||
**Personalized AI assistants** that need to understand individual psychology, not just remember conversations.
|
||||
|
|
|
|||
Loading…
Reference in New Issue