Token Reduction Engine

Middleware that deterministically validates AI text to catch hallucinations without LLM calls, improving fact accuracy and saving tokens.

Security Scan

The package is a coherent client for a separate 'Brain API' (fits its stated purpose) but has metadata inconsistencies and transmits user queries/responses to whatever API URL is configured — so verify the server provenance and avoid pointing it at untrusted remote endpoints.

Purpose & Capability

Name, description, SKILL.md, and the included Python client all align: this is a client/SDK that sends (query,response) pairs to a Brain API for deterministic validation. No unrelated credentials, binaries, or functionality are requested.

Instruction Scope

The client sends full query/response text to an external HTTP endpoint (CERTAINLOGIC_API). SKILL.md defaults to localhost:8000 but allows overriding to any URL — if pointed at a remote/untrusted server this can exfiltrate sensitive content. The CLI/instructions do not instruct reading unrelated system files, but they do allow writing batch output files. Also, on API errors the client returns 'valid': true by default, which is a surprising behavior that can mask validation failures.

Install Mechanism

No install spec (instruction-only with a small client file). Nothing is downloaded or written by an installer; risk from the install mechanism is low.

Credentials

No credentials or sensitive environment variables are required. The SKILL.md and code reference CERTAINLOGIC_API (default localhost) but the registry metadata does not declare required env vars — minor metadata inconsistency. The main proportionality concern is that the client will send whatever text you give it to the configured API URL; that network access is necessary for the purpose but must be trusted.

Persistence & Privilege

Skill is not always: true, does not request elevated system privileges, and does not modify other skills' configs. It runs as an ordinary client invoked by the agent or user.

What to consider before installing

This package is essentially a network client — it sends AI queries and responses to a Brain API you configure. Before installing or using it: (1) verify the origin of the server you will point CERTAINLOGIC_API at (run the server locally or review server code if using a third party); (2) do not set CERTAINLOGIC_API to an untrusted remote URL (that would leak the text you validate); (3) note the metadata mismatches (registry version 1.0.3 vs packaged skill.json 1.0.1 and no homepage/source) — prefer packages with clear provenance; (4) test in an isolated environment and review the server implementation if you plan to send sensitive data; (5) be aware that on API errors the client returns valid:true by default, which could mask validation failures.

Deterministic AI validation middleware. Catches hallucinations before they reach users. Zero LLM calls required for fact-based queries. Typical results: 20% token savings, 95%+ accuracy on facts.

Quick Reference

# Validate a single response
python3 scripts/hguard_client.py validate "What is 2+2?" "4"

# Batch validate from file
python3 scripts/hguard_client.py batch input.json output.json

# Check Brain API status
python3 scripts/hguard_client.py status

Installation

clawhub install token-reduction-engine

Python API

from scripts.hguard_client import HGuardClient

# Uses localhost:8000 by default. Override with CERTAINLOGIC_API env var.
client = HGuardClient()

# Validate any AI-generated text
result = client.validate("What is Docker?", "Docker is a containerization platform.")
print(result["valid"])       # True
print(result["confidence"])  # 1.0

# Check for hallucinations
bad = client.validate("What is Python recursion depth?", "Depth is 500.")
print(bad["valid"])   # False
print(bad["flags"])   # ["Factual mismatch: ..."]

# Batch process
results = client.batch_validate([
    {"query": "Q1", "response": "A1"},
    {"query": "Q2", "response": "A2"},
])

# Check API status
status = client.status()

Configuration

Set the Brain API URL via environment variable:

export CERTAINLOGIC_API="http://localhost:8000"

Or pass it directly to the client:

client = HGuardClient(api_url="http://your-brain-api:8000")

Troubleshooting

Issue	Fix
"Brain API not found"	Start the brain service at localhost:8000
"No facts loaded"	Load facts via Brain API endpoint
Validation too strict	Adjust threshold in code: client.set_threshold(0.5)

Uninstall

clawhub uninstall token-reduction-engine

License

MIT-0 (Free, no attribution required)

Note

Requires a running Brain API instance. This package provides the client only. The server must be configured separately.