Hugging Face's logo

kirha
/
planner

Safetensors
English
qwen3
tool-calling
planning
agent
lora
Model card Files
xet
Community
planner
File size: 4,321 Bytes 
656e8bd
f92c4f9
 
 
 
 
 
 
 
 
 
656e8bd
f92c4f9
656e8bd
f92c4f9
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
---
license: apache-2.0
language:
  - en
base_model: Qwen/Qwen3-8B
tags:
  - tool-calling
  - planning
  - agent
  - qwen3
  - lora
datasets:
  - kirha/planner-dataset
---

# Kirha Planner

A fine-tuned Qwen3-8B model that generates complete tool execution plans from natural language queries in a single pass.

## Why Tool Planning?

Traditional agentic systems let the LLM call tools iteratively until it finds the right data. This leads to unpredictable costs, high latency, and bloated context windows.

Tool Planning takes a different approach: analyze the request, build a complete execution graph, and only then execute. One LLM call produces the entire DAG — no back-and-forth.

This unlocks:
- **Cost predictability**: the plan is known before execution, costs can be estimated upfront
- **Parallel execution**: independent steps run concurrently, dependent steps chain automatically
- **Audit trail**: every plan includes reasoning traces and a complete execution log

### Composition with Output Schemas

Tool Planning relies on `outputSchema`, a capability now part of the official MCP specification. With output schemas, the planner knows what each tool returns before execution and can chain tools by matching output fields to input parameters. No exploratory calls needed.

## Output format

Given a set of tools and a user query, the model outputs:

```
<think>
I need to find the largest USDC holder on Base, then get their PnL.
First I need the chain ID for Base and the USDC contract address...
</think>
<plan>
[
  {
    "thought": "Get the chain ID for Base",
    "toolName": "getChainId",
    "arguments": { "blockchain": "Base" }
  },
  {
    "thought": "Search for the USDC coin",
    "toolName": "searchCoin",
    "arguments": { "query": "USDC", "limit": 1 }
  },
  {
    "thought": "Get the USDC contract address on Base",
    "toolName": "getCoinPlatformInfo",
    "arguments": {
      "coinId": "{1.coins.0.id}",
      "platform": "base"
    }
  },
  {
    "thought": "Get the top holder of USDC on Base",
    "toolName": "getTokenHolders",
    "arguments": {
      "chainId": "{0.chainId}",
      "tokenAddress": "{2.contractAddress}",
      "limit": 1
    }
  },
  {
    "thought": "Get the PnL for this wallet",
    "toolName": "getWalletPnL",
    "arguments": {
      "address": "{3.holders.0.address}"
    }
  }
]
</plan>
```

### Dependency references

Steps reference previous outputs using template strings:
- `{0.chainId}` — field `chainId` from step 0
- `{1.coins.0.id}` — nested path from step 1
- `{3.holders.0.address}` — array access from step 3

### Execution graph

```
Step 0: getChainId        Step 1: searchCoin
    │                         │
    │                         ↓
    │                     Step 2: getCoinPlatformInfo
    │                         │
    └────────────┬────────────┘
                 ↓
         Step 3: getTokenHolders
                 │
                 ↓
         Step 4: getWalletPnL
```

Steps 0 and 1 run in parallel. Step 3 waits for both 0 and 2. The executor resolves references at runtime.

## Usage

Use the [`@kirha/planner`](https://www.npmjs.com/package/@kirha/planner) TypeScript SDK to interact with this model. It handles parsing, validation, dependency resolution, and parallel execution of plans.

```bash
npm install @kirha/planner
```

Tools can come from any source, including MCP servers that have `outputSchema` defined.

See the [SDK documentation](https://github.com/kirha-ai/planner-typescript-sdk) for full usage examples.

## Training

- **Base model**: Qwen/Qwen3-8B
- **Method**: QLoRA (4-bit NF4, LoRA r=64, alpha=128)
- **Format**: Alpaca (instruction/input/output)
- **Dataset**: [kirha/planner-dataset](https://huggingface.co/datasets/kirha/planner-dataset)

The model learns planning methodology rather than memorizing specific APIs, enabling zero-shot generalization to any tool catalog at inference time. Noise tools are injected during training to teach discrimination between relevant and irrelevant options.

## Links

- [Dataset](https://huggingface.co/datasets/kirha/planner-dataset)
- [TypeScript SDK](https://www.npmjs.com/package/@kirha/planner)
- [Planner SDK source](https://github.com/kirha-ai/planner-typescript-sdk)