Honcho

A User context management solution for building AI Agents and LLM powered applications.

Read about the motivation of this project here.

Read the user documenation here

Project Structure

The Honcho repo is a monorepo containing the server/API that manages database interactions and storing data about an application's state along with the python sdk for interacting with the API.

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 for dependency management

A separate changelog is managed for the sdk and api in their respective directories.

Usage

API

The API can be run either by installing the necessary dependencies and then specifying the appropriate environment variables.

1. Create a virtualenv and install the API's dependencies

cd honcho/api/ # change to the api directory
poetry shell # Activate virutal environment
poetry install # install dependencies

2. Copy the .env.template file and specify the type of database and connection_uri. For testing sqlite is fine. The below example uses an in-memory sqlite database.

Honcho has been tested with Postgresql and PGVector

DATABASE_TYPE=postgres
CONNECTION_URI=postgresql://testuser:testpwd@localhost:5432/honcho

3. launch a postgresd with pgvector enabled with docker-compose

cd honcho/api/local
docker-compose up -d

4. Run the API via uvicorn

cd honcho/api # change to the api directory
poetry shell # Activate virtual environment if not already enabled
python -m uvicorn src.main:app --reload

Docker

Alternatively there is also a Dockerfile included to run the API server from a docker container.

The .env file is not loaded into the docker container and should still be configured from outside.

cd honcho/api
docker build -t honcho-api .
docker run --env-file .env -p 8000:8000 honcho-api:latest

Deploy on Fly

The API can also be deployed on fly.io. Follow the Fly.io Docs to setup your environment and the flyctl.

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

cd honcho/api
flyctl launch --no-deploy # Follow the prompts and edit as you see fit
cat .env | flyctl secrets import # Load in your secrets
flyctl deploy # Deploy with appropriate environment variables

Client SDK

Install the honcho client sdk from a python project with the following command:

pip install honcho-ai

alternatively if you are using poetry run:

poetry add honcho-ai

checkout the example folder 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.

poetry add --editable ./{path_to_honcho}/honcho/sdk

See more information here

Contributing

This project is completely open source and welcomes any and all open source 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 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

License

Honcho is licensed under the AGPL-3.0 License. Learn more at the License file