{"id":9814,"library":"honcho-ai","title":"Honcho AI Python SDK","description":"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.","status":"active","version":"2.1.1","language":"en","source_language":"en","source_url":"https://github.com/plastic-labs/honcho","tags":["AI","SDK","API client","LLM","Chatbot"],"install":[{"cmd":"pip install honcho-ai","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Data validation and parsing for API responses and requests.","package":"pydantic","optional":false},{"reason":"Asynchronous HTTP client for making API requests.","package":"httpx","optional":false},{"reason":"Backports and enhancements for Python's typing module.","package":"typing-extensions","optional":false},{"reason":"Retry decorator for handling transient errors with exponential backoff.","package":"tenacity","optional":false}],"imports":[{"note":"The Honcho client is located within the 'client' submodule, not directly under the top-level package.","wrong":"from honcho import Honcho","symbol":"Honcho","correct":"from honcho.client import Honcho"}],"quickstart":{"code":"import os\nfrom honcho.client import Honcho\n\n# Ensure HONCHO_API_KEY is set in your environment\n# Alternatively, pass api_key directly: api_key=\"your_api_key\"\napi_key = os.environ.get('HONCHO_API_KEY', '')\n\nif not api_key:\n    raise ValueError(\"HONCHO_API_KEY environment variable not set.\")\n\nclient = Honcho(api_key=api_key)\n\ntry:\n    response = client.chat.completions.create(\n        messages=[{\"role\": \"user\", \"content\": \"What is the capital of France?\"}],\n        model=\"llama-3.8b-plastic-v2\" # Or another available model like 'mixtral-8x7b-plastic-v2'\n    )\n    print(response.choices[0].message.content)\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Set `export HONCHO_API_KEY='your_key'` in your shell or use `honcho_client = Honcho(api_key=os.environ.get('HONCHO_API_KEY'))`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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'.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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\")`.","cause":"The Honcho API key was not provided or is incorrect, leading to an authentication failure.","error":"honcho.error.AuthenticationError: Missing or invalid API key"},{"fix":"The `Honcho` client is located in the `client` submodule. Use `from honcho.client import Honcho` instead.","cause":"Attempting to import the `Honcho` client directly from the top-level `honcho` package.","error":"ImportError: cannot import name 'Honcho' from 'honcho'"},{"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'.","cause":"The specified model name in `client.chat.completions.create(model='...')` does not exist or is not available for your Honcho instance.","error":"honcho.error.NotFoundError: Model 'non-existent-model' not found."}]}