Honchox

Req-based Elixir client for the Honcho v3 API.

Honchox wraps Req with built-in authentication, transient retry logic, and structured error handling to provide a clean interface to the Honcho API.

Installation

Add honchox to your list of dependencies in mix.exs:

def deps do
  [
    {:honchox, "~> 0.1.0"}
  ]
end

Quick start

# Create a client (reads HONCHO_API_KEY from env)
client = Honchox.new()

# Create a peer in a workspace
{:ok, peer} = Honchox.Peers.get_or_create(client, "alice",
  workspace_id: "my-workspace",
  metadata: %{role: "user"}
)

# Start a session
{:ok, session} = Honchox.Sessions.get_or_create(client, "session-1",
  workspace_id: "my-workspace",
  metadata: %{topic: "onboarding"}
)

# Add messages
{:ok, _msgs} = Honchox.Sessions.add_messages(client, "session-1", [
  %{peer_id: "alice", content: "Hello!"},
  %{peer_id: "bot", content: "Hi Alice, how can I help?"}
], workspace_id: "my-workspace")

# Search across the workspace
{:ok, results} = Honchox.Workspaces.search(client, "onboarding",
  workspace_id: "my-workspace",
  limit: 5
)

Modules

Module	Description
`Honchox`	Client initialization and low-level HTTP methods
`Honchox.Workspaces`	Workspace lifecycle, search, queue status, dream scheduling
`Honchox.Peers`	Peer lifecycle, chat, context, representation, cards
`Honchox.Sessions`	Session lifecycle, messages, peer membership, context, files
`Honchox.Conclusions`	Conclusion CRUD and semantic search
`Honchox.Keys`	Scoped JWT creation and delegated authentication
`Honchox.Observations`	(deprecated) Backward-compatible aliases for conclusions
`Honchox.Error`	Structured error with kind, status, and body

Configuration

Option	Env var	Default
`:api_key`	`HONCHO_API_KEY`	(required unless `:jwt`)
`:jwt`	—	(scoped bearer token)
`:base_url`	`HONCHO_URL`	`https://api.honcho.ai`
`:timeout`	—	`60_000` ms
`:max_retries`	—	`2`

client = Honchox.new(
  api_key: "sk-...",
  base_url: "https://api.honcho.dev",
  timeout: 30_000,
  max_retries: 3
)

Error handling

All functions return {:ok, result} or {:error, %Honchox.Error{}}. Pattern match on the error :kind for granular handling:

case Honchox.Peers.get_or_create(client, "alice", workspace_id: "ws") do
  {:ok, peer} ->
    peer

  {:error, %Honchox.Error{kind: :http_error, status: status}} ->
    Logger.error("HTTP #{status}")

  {:error, %Honchox.Error{kind: :timeout}} ->
    Logger.warning("Request timed out, retrying...")

  {:error, %Honchox.Error{kind: :transport, message: msg}} ->
    Logger.error("Network error: #{msg}")
end

Documentation

Full documentation is available on HexDocs.

To generate docs locally:

mix docs
open doc/index.html

License

MIT