Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ahvn.top/llms.txt

Use this file to discover all available pages before exploring further.

HeavenBase routes LLM calls through an OpenAI-compatible gateway. The default provider is OpenRouter, giving you access to most major models with a single API key. Model choices never appear in your code. You reference presets — normal chat presets choose the model and behavior, while heavenbase.llm.default_provider chooses where that model is served. Explicit provider= arguments and provider pins on a preset still override the default provider.

​
1. Set an API Key

HeavenBase ships with built-in configs for these providers. Set the relevant environment variables or use hb cfg set: 
# Single API key for OpenAI, Anthropic, Google, DeepSeek, and 200+ models.
# Default to using <OPENROUTER_API_KEY> environment variable.
export OPENROUTER_API_KEY="sk-or-v1-..."
hb cfg set heavenbase.llm.default_provider openrouter   # default
hb cfg set heavenbase.llm.providers.openrouter.base_url "https://openrouter.ai/api/v1"  # default
hb cfg set heavenbase.llm.presets.chat.model deepseek-v4-flash   # default model for chat preset
If you have an older config that pins a preset provider, unset it so default_provider can take effect: 
hb cfg unset heavenbase.llm.presets.chat.provider
You can also manually set hb cfg set heavenbase.llm.providers.<provider>.base_url for any OpenAI-compatible provider, and hb cfg set heavenbase.llm.providers.<provider>.api_key if the provider doesn’t use the standard environment variable. Local providers (ollama, lmstudio, and vllm) accept provider-specific model IDs too; the curated qwen3.6-flash entry maps to each local provider’s configured name. Any LiteLLM-compatible provider can be added via config. See the LLM overview for the complete provider and model catalog.

​
2. CLI Chat

Send a message. By default this uses the chat preset with deepseek-v4-flash on your configured default_provider (openrouter out of the box): 
$ hb llm chat "What is a data gateway?"

A data gateway is a middleware layer that sits between applications
and their data sources, providing unified access, routing, caching,
and security policies without coupling clients to specific backends...
Override the preset with --preset: 
$ hb llm chat --preset system "Name three data backends"

SQLite, PostgreSQL, and Elasticsearch.
Options:
  • --preset / -p: use a named preset (system, chat, reason, coder, embed, local, …)
  • --model / -m: override the model (ds-flash, sonnet, gpt, … support canonical model names or defined aliases)
  • --provider / -b: override the provider (openrouter, openai, anthropic, …)
  • --verbose / -v: show the resolved LLM spec including model, provider, gateway, args, etc.
  • --input / -i: read the prompt from a file
The chat preset is used by hb llm chat and hb llm session. The default hb.LLM() (no preset) uses system, a lightweight preset for short orchestration calls. The embed preset controls hb llm embed and uses text-embedding-3-small; set heavenbase.llm.presets.embed.provider when your default provider does not serve embeddings.

​
3. CLI Embeddings

The embed preset defaults to text-embedding-3-small (1536 dimensions). It uses your default_provider unless you pin an embedding provider. Configuring an embedding provider is similar to chat, just set the embed preset’s provider and model. 
export OPENROUTER_API_KEY="sk-or-v1-..."
hb cfg set heavenbase.llm.presets.embed.provider openrouter
hb cfg set heavenbase.llm.presets.embed.model openai/text-embedding-3-small
It returns a Python-style list: 
$ hb llm embed "Semantic text to embed"
[0.01234568, -0.00987654, 0.04567891, -0.02345679, 0.03456789, 0.00123457, ...]
len=1536  dim=1536  tokens=8
Pass --json for full output including usage: 
hb llm embed "hello" --json

​
4. Interactive Session

Start a multi-turn session: 
hb llm session
The session uses the chat preset. Type messages at the >>> prompt. Example: 
$ hb llm session
Session started. Type /help for commands, /bye or /exit to quit.
>>> What is a data gateway?
A data gateway is a middleware layer that provides unified access
to multiple data sources with routing and caching.
>>> List three use cases
1. Multi-database query routing
2. Read/write splitting
3. API gateway for vector and structured data
>>> /bye
Slash commands: /help, /save <path>, /load <path>, /clear, /regen <seed>, /back, /tools, /mcp, /exit. Attach MCP tools to a session with repeated --mcp values. Each value can be a URL or a registered Toolkit ref: 
hb llm session --mcp quickstart.math-tools
hb llm session --mcp http://127.0.0.1:7001/mcp
Inside a running session, use /mcp to add more tools. For one-shot tool use, attach MCP directly to chat: 
hb llm chat --mcp quickstart.math-tools "What's 42 * 73?"

​
5. Python API

The LLM class is the same engine the CLI uses. Construct one with no arguments for the system preset, or pass any overrides: 
import heavenbase as hb

# Default: system preset (lightweight, deepseek-v4-flash via default_provider)
llm = hb.LLM()

llm = hb.LLM(preset="chat")
text = llm.chat("Reply with exactly: hello world")
print(text)
# hello world
The LLM constructor accepts preset, model, provider, gateway, and any extra kwargs (e.g., temperature, max_tokens, seed) which become provider request defaults. When only a normal chat preset is given, the model comes from heavenbase.llm.presets.<name>.model and the provider comes from heavenbase.llm.default_provider unless the preset explicitly pins one.

​
Further Exploration

Related resources: