Skip to content

Commit

Permalink
Fixes DEV-298
Browse files Browse the repository at this point in the history
  • Loading branch information
VVoruganti committed May 14, 2024
1 parent 6b9bcd6 commit 19e714c
Show file tree
Hide file tree
Showing 7 changed files with 184 additions and 123 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Server.

Honcho is developed using [python](https://www.python.org/) and [poetry](https://python-poetry.org/).

The minimum python version is `3.8.1`
The minimum python version is `3.9`
The minimum poetry version is `1.4.1`

### Setup
Expand Down
57 changes: 5 additions & 52 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Apps
Users familiar with APIs such as the OpenAI Assistants API will be familiar with
much of the mapping here.

**Apps**
#### Apps

This is the top level construct of Honcho. Developers can register different
`Apps` for different assistants, agents, AI enabled features, etc. It is a way to
Expand All @@ -95,7 +95,7 @@ isolation data between use cases.
Within an `App` everything revolves around a `User`. the `User` object very
literally represent a user of an application.

**Sessions**
#### Sessions

The `Session` object represents a set of interactions a `User` has with an
`App`. Other application may refer to this as a thread or conversation.
Expand All @@ -105,7 +105,7 @@ The `Session` object represents a set of interactions a `User` has with an
The `Message` represents an atomic interaction of a `User` in a `Session`.
`Message`s are labed as either a `User` or AI message.

**Metamessages**
#### Metamessages

A `Metamessage` is very similar to a `Message` with different use case. They are
meant to be used to store intermediate inference from AI assistants or other
Expand All @@ -117,7 +117,7 @@ information such as logs.
Each `Metamessage` is associated with a `Message`. The convention we recommend
is to attach a `Metamessage` to the `Message` it was derived from or based on.

**Collections**
#### Collections

At a high level a `Collection` is a named group of `Documents`. Developers
familiar with RAG based applications will be familar with these. `Collection`s
Expand All @@ -128,7 +128,7 @@ Developers can create multiple `Collection`s for a user for different purposes
such as modeling different personas, adding third-party data such as emails and
PDF files, and more.

**Documents**
#### Documents

As stated before a `Document` is vector embedded data stored in a `Collection`.

Expand Down Expand Up @@ -157,53 +157,6 @@ API include:
- Asking Honcho to hydrate a prompt with data about the `User`s behavior
- Asking Honcho for a 2nd opinion or approach about how to respond to the User

<!-- The folders are structured as follows: -->

<!-- - `api/` - contains a FastAPI application that provides user context management -->
<!-- routes -->
<!-- - `sdk/` - contains the code for the python sdk and package hosted on PyPI -->
<!-- - `example/` - contains example code for different use cases of honcho -->

<!-- This project utilizes [poetry](https://python-poetry.org/) for dependency -->
<!-- management -->

<!-- A separate changelog is managed for the sdk and api in their respective -->
<!-- directories. -->

<!-- ### Client SDK -->

<!-- Install the honcho client sdk from a python project with the following command: -->

<!-- ```bash -->
<!-- pip install honcho-ai -->
<!-- ``` -->

<!-- alternatively if you are using poetry run: -->

<!-- ```bash -->
<!-- poetry add honcho-ai -->
<!-- ``` -->

<!-- checkout the [SDK Reference](https://api.python.honcho.dev) for a detailed -->
<!-- look at the different methods and how to use them. -->

<!-- Also, check out the[example folder](./example/) for examples of how to use the sdk -->
<!-- checkout the [SDK Reference](https://api.python.honcho.dev) for a detailed -->
<!-- look at the different methods and how to use them. -->

<!-- Also, check out the[example folder](./example/) for examples of how to use the sdk -->

<!-- #### Use Locally -->

<!-- For local development of the sdk you can add the local directory as a package -->
<!-- using poetry with the following commands. -->

<!-- ```bash -->
<!-- poetry add --editable ./{path_to_honcho}/honcho/sdk -->
<!-- ``` -->

<!-- See more information [here](https://python-poetry.org/docs/cli/#add) -->

## License

Honcho is licensed under the AGPL-3.0 License. Learn more at the [License file](./LICENSE)
5 changes: 5 additions & 0 deletions docs/contributing/deploying.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,11 @@ icon: 'rocket'

If you're happy with how things are working locally, deploying your Honcho instance is a breeze with [Fly](https://fly.io). Follow the [Fly.io Docs](https://fly.io/docs/getting-started/) to setup your environment and the `flyctl`.

A sample `fly.toml` is included for convenience in the repository.

<Warning>Note. The fly.toml does not include launching a Postgres database. This must
be configured separately</Warning>

Once `flyctl` is set up use the the following commands to launch the application:

```bash
Expand Down
11 changes: 5 additions & 6 deletions docs/contributing/guidelines.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,9 @@ contributions. The workflow for contributing is to make a fork of the
repository. You can claim an issue in the issues tab or start a new thread to
indicate a feature or bug fix you are working on.

Once you have finished your contribution make a PR pointed at the `staging`
branch, and it will be reviewed by a project manager. Feel free to join us in
our [discord](http://discord.gg/plasticlabs) to discuss your changes or get
help.
Once you have finished your contribution make a PR , and it will be reviewed by
a project manager. Feel free to join us in our
[discord](http://discord.gg/plasticlabs) to discuss your changes or get help.

Once your changes are accepted and merged into staging they will undergo a
period of live testing before entering the upstream into `main`
Your changes will undergo a period of testing and discussion before finally
being entered into the `main` branch and being staged for release
102 changes: 72 additions & 30 deletions docs/contributing/self-hosting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,60 +5,102 @@ description: 'Running a local version of the Honcho API Server'
icon: 'cloud'
---

> This guide was made using a M1 Macbook Pro. For any compatibility issues
> on different platforms please raise an Issue.
### Prerequisites and Dependencies

Honcho is a monorepo that contains the server and API to manage database interactions. It stores data about an application's state along with the python sdk for interacting with the API.
You can host it locally quite easily! This can be beneficial for iterative development, testing, and debugging. This guide will go through the different ways to host locally.
Honcho is developed using [python](https://www.python.org/) and [poetry](https://python-poetry.org/).

The minimum python version is `3.9`
The minimum poetry version is `1.4.1`

### Setup

1. Clone the repository:
Once the dependencies are installed on the system run the following steps to get
the local project setup.

1. Clone the repository

```bash
git clone git@github.com:plastic-labs/honcho.git
git clone https://github.com/plastic-labs/honcho.git
```

2. Copy the `.env.template` file to `.env` and specify the type of database and `CONNECTION_URI`. For testing sqlite is fine. The below example uses a sqlite database with a local file:
2. Enter the repository and install the python dependencies

> Honcho has been tested with Postgresql and SQLite
We recommend using a virtual environment to isolate the dependencies for Honcho
from other projects on the same system. With `poetry` a virtual environment can
be generated using the `poetry shell` command. Once the virtual environment is
created and activated install the dependencies with `poetry install`

```env
DATABASE_TYPE=sqlite
CONNECTION_URI=sqlite:///api.db
Putting this together:

```bash
cd honcho
poetry shell
poetry install
```

Now the tutorial will diverge based on how you'd like to run the API.
3. Set up a database

### Poetry
Honcho utilized [Postgres](https://www.postgresql.org/) for its database with
pgvector. An easy way to get started with a postgresdb is to create a project
with [Supabase](https://supabase.com/)

This project utilizes [Poetry](https://python-poetry.org/) for dependency management, so you can run the API through a poetry virtual environment.
A `docker-compose` template is also available with a database configuration
available.

3. Create a virtualenv and install the API's dependencies:
```bash
cd honcho/api/ # change to the api directory
poetry shell # Activate virutal environment
poetry install # install dependencies
4. Edit the environment variables.

Honcho uses a `.env` file for managing runtime environment variables. A
`.env.template` file is included for convenience. Several of the configurations
are not required and are only necessary for additional logging, monitoring, and
security.

Below are the required configurations

```env
CONNECTION_URI= # Connection uri for a postgres database
OPENAI_API_KEY= # API Key for OpenAI used for insights
```
> Note that the `CONNECTION_URI` must have the prefix `postgresql+psycopg` to
> function properly. This is a requirement brought by `sqlalchemy`
The template has the additional functionality disabled by default. To ensure
that they are disabled you can verify the following environment variables are
set to false.

```env
USE_AUTH_SERVICE=false
OPENTELEMETRY_ENABLED=false
SENTRY_ENABLED=false
```

4. Run the API via uvicorn:
5. Launch the API

With the dependencies installed, a database setup and enabled with `pgvector`,
and the environment variables setup you can now launch a local instance of
Honcho. The following command will launch the storage API for Honcho

```bash
cd honcho/api # change to the api directory
poetry shell # Activate virtual environment if not already enabled
python -m uvicorn src.main:app --reload
python -m uvicorn src.main:app --reload --port 8000
```
This is a development server that will reload whenever code is changed. When
first launching the API with a connection the database it will provision the
necessary tables for Honcho to operate.

### Docker

Alternatively there is also a `Dockerfile` included to run the API server from a docker container.
As mentioned earlier a `docker-compose` template is included for running Honcho.
As an alternative to running Honcho locally it can also be run with the compose
template.

The `.env` file is not loaded into the docker container and should still be configured from outside.
Copy the template and update the appropriate environment variables before
launching the service.

3. Build the docker image:
```bash
cd honcho/api
docker build -t honcho-api .
```

4. Run the docker image:
```bash
docker run --env-file .env -p 8000:8000 honcho-api:latest
cp docker-compose.yml.example docker-compose.yml
[ update the file with openai key and other wanted environment variables ]
docker compose up
```
19 changes: 13 additions & 6 deletions docs/getting-started/introduction.mdx
Original file line number Diff line number Diff line change
@@ -1,14 +1,21 @@
---
title: 🫡 Welcome to Honcho
sidebarTitle: 'Overview'
description: 'Honcho is an open source framework for building personalized AI experiences.'
description: 'Honcho is an open source platform for building personalized AI experiences.'
icon: 'face-saluting'
---

<Snippet file="overview-shields.mdx" />

Honcho provides a simple API for managing multiple concurrent sessions across numerous users.
Now you can focus on improving your service instead of spending countless hours figuring out how to get it to scale. To learn more about the project, check out our [blog post](https://blog.plasticlabs.ai/blog/A-Simple-Honcho-Primer).
Honcho provides an simple API store data for AI applications in a user-centric
fashion and derive insights about users that improve the ability of
applications to quickly deliver value to the User.

Now you can focus on improving your service instead of spending
countless hours figuring out how to get it to scale and be personalized.

To learn more about the project, check out our [blog
post](https://blog.plasticlabs.ai/blog/A-Simple-Honcho-Primer).

Get started below!

Expand All @@ -28,10 +35,10 @@ Get started below!
Get an overview of the different primitives and structure of Honcho
</Card>
<Card
title="Integrate with Langchain"
icon="bird"
title="Honcho Primer"
icon="scroll"
href="/guides/langchain"
>
Learn how to use LangChain and Honcho together to quickly scale your agents to many users
Read our blog post that introduces Honcho, the motivations behind it, and what it will enable.
</Card>
</CardGroup>
Loading

0 comments on commit 19e714c

Please sign in to comment.