Honcho AI Python SDK

2.1.1 · active · verified Fri Apr 17

The official Python SDK for Honcho AI, designed for an optimized developer experience. It provides convenient access to Honcho's AI models, including chat completions and other services. The current version is 2.1.1, and it follows an active release cadence with regular updates.

Common errors

```
honcho.error.AuthenticationError: Missing or invalid API key
```
cause The Honcho API key was not provided or is incorrect, leading to an authentication failure.

fix Ensure the `HONCHO_API_KEY` environment variable is set or pass the `api_key` parameter correctly during client initialization: `Honcho(api_key="your_key")`.
```
ImportError: cannot import name 'Honcho' from 'honcho'
```
cause Attempting to import the `Honcho` client directly from the top-level `honcho` package.

fix The `Honcho` client is located in the `client` submodule. Use `from honcho.client import Honcho` instead.
```
honcho.error.NotFoundError: Model 'non-existent-model' not found.
```
cause The specified model name in `client.chat.completions.create(model='...')` does not exist or is not available for your Honcho instance.

fix Verify the model name against the Honcho documentation or available models. Common models include 'llama-3.8b-plastic-v2' or 'mixtral-8x7b-plastic-v2'.

Warnings

gotcha API Key management: Always ensure your HONCHO_API_KEY is securely loaded, preferably via environment variables, to avoid hardcoding credentials. The SDK expects the key as `api_key` parameter or `HONCHO_API_KEY` env var.
Fix: Set `export HONCHO_API_KEY='your_key'` in your shell or use `honcho_client = Honcho(api_key=os.environ.get('HONCHO_API_KEY'))`.
gotcha Model not found errors: Using an incorrect or unavailable model name will result in an API error. Available models can change or vary by Honcho deployment.
Fix: Consult Honcho documentation or the API's model listing for valid model identifiers. Common models include 'llama-3.8b-plastic-v2' or 'mixtral-8x7b-plastic-v2'.
breaking As a relatively new SDK in a fast-evolving domain, future minor or major versions may introduce breaking changes in API client methods, parameter names, or response object structures. Review release notes carefully when upgrading.
Fix: Always pin to specific minor versions (`honcho-ai~=2.1.0`) in production to control updates, and thoroughly test applications after upgrading to a new `honcho-ai` version.
gotcha Understanding the response object structure: The `create` methods return Pydantic models. Accessing results often involves navigating nested attributes like `response.choices[0].message.content` which might not be immediately intuitive for new users.
Fix: Refer to the method's return type hints or examples to correctly parse the response object. Use IDE auto-completion for easier exploration of attributes.

Install

pip install honcho-ai Install latest version

Imports

Honcho
wrong:
```
from honcho import Honcho
```
correct:
```
from honcho.client import Honcho
```
The Honcho client is located within the 'client' submodule, not directly under the top-level package.

Quickstart

This quickstart initializes the Honcho client using an API key from an environment variable and makes a simple chat completion request. Replace the model name with an appropriate one if 'llama-3.8b-plastic-v2' is not available or desired.

import os
from honcho.client import Honcho

# Ensure HONCHO_API_KEY is set in your environment
# Alternatively, pass api_key directly: api_key="your_api_key"
api_key = os.environ.get('HONCHO_API_KEY', '')

if not api_key:
    raise ValueError("HONCHO_API_KEY environment variable not set.")

client = Honcho(api_key=api_key)

try:
    response = client.chat.completions.create(
        messages=[{"role": "user", "content": "What is the capital of France?"}],
        model="llama-3.8b-plastic-v2" # Or another available model like 'mixtral-8x7b-plastic-v2'
    )
    print(response.choices[0].message.content)
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →