🛠️ pi-json-tools

Smart Recovery Extension for Local LLMs on Pi Agent Auto-detect hallucination · Hallucinated path gate · Smart JSON recovery · Multi-language

[

](https://www.npmjs.com/package/pi-json-tools) [

](./LICENSE) [

](https://pi.ai) [

](https://www.typescriptlang.org/)

---

Why This Exists

Local LLMs like Qwen Coder, Llama, Mistral, and others are powerful but have common issues:

• Output commands as free text instead of valid JSON tool calls
• Generate hallucinations like double braces, empty code blocks, or chat template artifacts
• Forget tool-call format after a few turns
• Reference fabricated file paths that do not exist

pi-json-tools fixes all of this automatically — no model switching required.

---

Features

• Hallucination Detection — auto-detect broken output patterns
• Hallucinated Path Gate — block commands with fabricated paths before execution
• Smart JSON Parser — parse and recover malformed output into valid tool calls
• Auto Reminder — remind the model to use JSON format every N turns
• Timeout Protection — safe bash execution with configurable timeout
• Multi-language — auto-detect Indonesian, Chinese, Japanese, Korean, Arabic, English
• Auto Retry — retry parsing up to maxRetries times before giving up
• Auto Model Detection — auto-switch to JSON mode if model does not support native tools

---

Installation

Local

npm install pi-json-tools

Global

npm install -g pi-json-tools

Register in pi agent config (~/.pi/agent/settings.json):

{
  "packages": [
    {
      "source": "npm:pi-json-tools",
      "extensions": ["+extensions/qwen-json-tools.ts"]
    }
  ]
}

---

Configuration

File: ~/.pi/agent/pi-json-tools.json

{
  "logging": true,
  "maxRetries": 2,
  "timeout": 30000,
  "language": "auto",
  "injectEnvContext": true,
  "models": [
    "qwen", "gemma", "llama", "mistral", "phi", "deepseek",
    "yi", "solar", "vicuna", "orca", "wizard", "openchat",
    "neural", "nous", "hermes", "zephyr", "falcon"
  ]
}

Options:

• logging (boolean, default: true) — enable logging to ~/.pi/agent/pi-json-tools.log
• maxRetries (number, default: 2) — max JSON parse retry attempts
• timeout (number, default: 30000) — bash execution timeout in ms
• language (string, default: auto) — auto, id, zh, en, ja, ko, ar
• injectEnvContext (boolean, default: true) — inject real env context at session start
• models (string[]) — list of model name keywords to intercept

---

How It Works

LLM Output
    |
    v
Smart JSON Parser --> No tool call? --> Truncation retry / Pass as chat
    |
    v
Hallucinated Path Gate --> Detected? --> Block + warn
    |
    v
Execute Tool / Bash

---

Supported Tools

bash · read · write · edit · grep · find · ls

Accepted JSON Formats

Standard: {"name": "bash", "arguments": {"command": "ls -la"}}

Qwen alternative: {"tool": "bash", "input": {"command": "pwd"}}

Direct command: {"command": "npm install"}

OpenAI function call: {"type": "function", "function": {"name": "bash", "arguments": {"command": "ls"}}}

---

Hallucination Patterns Detected

• double_brace — double closing braces at end of output
• empty_array — empty array with stray comma
• artifact — Qwen chat template leaking into output
• path_error — wrong command format
• empty_codeblock — empty code block

Hallucinated Paths Blocked

• @mariozechner in path — pi agent internal path fabrication
• piadmin — non-existent admin path
• /app/config.json — generic hallucinated config path
• /dist/cli.js — hallucinated CLI path
• keybindings.json — editor config hallucination

---

Logging

Logs saved to ~/.pi/agent/pi-json-tools.log

To disable: { "logging": false }

---

Multi-language Support

Language is auto-detected from user input:

• Indonesian — keyword matching (apa, ini, tolong, coba, etc.)
• Chinese — CJK character range
• Japanese — Hiragana/Katakana range
• Korean — Hangul range
• Arabic — Arabic character range
• English — default fallback

---

Pi Agent Events Used

• session_start — reset state, show version
• agent_start — reset retry counter
• turn_start — reset per-turn state
• before_agent_start — inject system prompt
• context — inject real env context
• message_end — parse, gate, and execute

---

Troubleshooting

Model keeps hallucinating? Type /reset or exit and re-enter Pi (Ctrl+D twice).

Commands not executing? Check ~/.pi/agent/pi-json-tools.log and verify JSON format.

Timeout too short? Increase timeout in config, e.g. 60000 for 60 seconds.

Wrong reminder language? Set language manually: id, en, zh, ja, ko, ar.

Model not intercepted? Add the model name keyword to the models array in config.

---

Project Structure

pi-json-tools/
├── extensions/
│   └── qwen-json-tools.ts
├── CHANGELOG.md
├── package.json
└── README.md

---

Contributing

1. Fork this repository
2. Create a branch: git checkout -b feat/feature-name
3. Commit: git commit -m "feat: add feature X"
4. Push: git push origin feat/feature-name
5. Open a Pull Request

To add hallucination patterns, edit HALLUCINATED_PATH_PATTERNS in qwen-json-tools.ts.

---

License

MIT © DayuWidayadi

---

Made with love for the Pi Agent and local LLM community. If this extension helps you, please give it a star on GitHub!