Function-Calling Patterns with Hermes-Function-Calling

How to use

Use this when the generic OpenAI tool-calling examples do not map cleanly onto the Hermes prompt format and you need runnable, maintainer-shipped reference scripts showing the exact template, decorator, and recursion flags that work with the Hermes function-calling stack.

functioncall.py is the main entry point; its default demo wraps yfinance to pull live stock prices and fundamentals.

--query sets the natural-language request, defaulting to the current TSLA price.

--max_depth caps the recursive iterations at a default of 5; tool results feed back into the model for multi-hop function calling.

--num_fewshot includes few-shot examples in context.

--load_in4bit enables bitsandbytes 4-bit loading.

--chat_template sets the prompt format, defaulting to chatml.

jsonmode.py produces structured JSON output: it defines a Pydantic schema — the shipped example is a Character for a Dragon Ball Z entity with name, species, role, traits, and special attacks — and validates model output against it.

functions.py is the idiomatic tool-registration layer: tools are defined with a @tool decorator, collected in get_openai_tools(), and converted via convert_to_openai_tool(f).

prompter.py is the prompt builder: it reads the system prompt from YAML and fills tools, examples, schema, and supports the GOAP-style <scratch_pad> block (Goal / Actions / Observation / Reflection) shown in the Hermes-3 template for multi-step reasoning.

--max_depth is the multi-hop lever: depth 1 means one tool call then an answer, while higher depths let the model call a tool, read the result, call another, and synthesize. Watch for loops on ambiguous queries.

Pydantic is the contract in jsonmode.py: the model is prompted to emit JSON and the validator enforces the schema. If your schema has optional fields, mark them Optional, or the validator rejects valid-but-partial output.

@tool plus convert_to_openai_tool is the project's idiomatic pattern — don't hand-write the OpenAI tool JSON if you can decorate a function and let the converter build it.

This repo predates the in-agent Hermes tool system: it is the reference for model-level function calling and for serving Hermes-FC over an OpenAI-compatible endpoint, not for the agent's own skill/MCP tools.

Set up by cloning the repo and following its dependency install.

git clone https://github.com/NousResearch/Hermes-Function-Calling
cd Hermes-Function-Calling
# follow repo's dependency install (transformers, pydantic, yfinance, bitsandbytes optional)

Run the shipped demos.

# live financial data via yfinance, single-hop
python functioncall.py --query "Current stock price and 52-week range of NVDA"

# recursive multi-hop: let the model chain tool calls up to depth 5
python functioncall.py --query "Compare P/E ratios of AAPL, MSFT, GOOGL" --max_depth 5

# structured JSON output against a Pydantic schema
python jsonmode.py --query "Return a JSON object for Goku from Dragon Ball Z"

# few-shot augmented function calling
python functioncall.py --query "..." --num_fewshot 3

Prompts: the GOAP scratch-pad shape comes from prompter.py and the Hermes-3 template.

The GOAP scratch-pad shape (from prompter.py, Hermes-3 template):

<scratch_pad>
Goal: <what the user wants>
Actions: <candidate tool calls, with args>
Observation: <result of the last action>
Reflection: <what to do next, or final answer>
</scratch_pad>

Registering a custom tool follows the functions.py pattern:

from functions import tool, get_openai_tools, convert_to_openai_tool

@tool
def get_stock_price(ticker: str) -> dict:
    """Return the latest price for the given ticker."""
    ...

tools = [convert_to_openai_tool(get_stock_price)]