Token Reduction Engine

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

Security Scan

The skill's code matches its claimed purpose (a client for a local 'Brain' validation API), but the documentation, config, and runtime behavior are inconsistent and could allow unnoticed data transmission to arbitrary endpoints.

Purpose & Capability

The package is a client SDK that posts (query,response) pairs to a 'Brain' API for deterministic validation, which aligns with the described purpose. The included Python file implements validate and batch validation and declares a default API URL and threshold consistent with a validation client.

Instruction Scope

SKILL.md documents CLI commands (validate, batch, status) and a Quick Reference that the script should accept subcommands (e.g., 'validate' or 'batch'), but the bundled script's CLI only accepts two positional args and has no handling for 'batch' or 'status'. SKILL.md also instructs adding an "api_url" to agent config, but the client does not read that config key — it uses the CERTAINLOGIC_API environment variable or the hardcoded default. These mismatches mean the instructions will mislead users and grant the agent more discretion than intended by the docs.

Install Mechanism

No install spec is provided (instruction-only with a small client file). Nothing is downloaded at install time and no third-party packages are automatically fetched, so installation risk is low.

Credentials

skill.json and SKILL.md declare no required environment variables, yet the client reads CERTAINLOGIC_API from the environment (BRAIN_API = os.getenv('CERTAINLOGIC_API', 'http://127.0.0.1:8000')). This undocumented env var can redirect all validated data to any URL the environment points to. The SKILL.md recommends adding an api_url to agent config, but there's no code that reads that config key, creating a mismatch between declared configuration and actual env-var-controlled behavior.

Persistence & Privilege

The skill does not request persistent/always inclusion and does not modify other skills or global agent settings. It is a simple client library with no elevated platform privileges.

What to consider before installing

This skill appears to be a small client for a Brain validation API and is not obviously malicious, but there are clear inconsistencies you should address before trusting it with real data: - The SKILL.md Quick Reference and commands (batch, status, subcommand 'validate') do not match the script's CLI implementation; the script expects two positional args only. Don't rely on the documented CLI until the author fixes it. - The code reads CERTAINLOGIC_API from the environment but the skill metadata/documentation does not declare that env var. If CERTAINLOGIC_API is set to a remote server, the client will POST all (query,response) pairs there. Ensure the environment variable is unset or explicitly set to a trusted local URL (e.g., http://127.0.0.1:8000) before use. - SKILL.md suggests adding an api_url to agent config, but the client does not read that config key. Either the server URL should be read from agent config (and documented), or documentation should instruct how to set the CERTAINLOGIC_API env var / pass api_url to HGuardClient explicitly. - There's a minor metadata mismatch: skill.json lists version 1.0.1 while registry metadata shows 1.0.2 — verify you have the intended release. Practical steps: run the client in an isolated environment, verify where network requests go (use a network monitor or localhost-only binding), and consider asking the publisher to fix the docs and expose a documented, explicit way to set the API endpoint (prefer passing api_url into HGuardClient). If you cannot confirm the server endpoint is local/trusted, avoid sending sensitive data through this client.

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

Need	Command
Validate a response	python3 scripts/hguard_client.py validate "query" "response"
Batch validate	python3 scripts/hguard_client.py batch <input.json> <output.json>
Check status	python3 scripts/hguard_client.py status

Installation

clawhub install token-reduction-engine

Configuration

Add to your agent config:

{
  "api_url": "http://localhost:8000"
}

Python API

# You must have the Brain API running at localhost:8000
from scripts.hguard_client import HGuardClient

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?", "Python recursion depth is 500.")
print(bad["valid"])   # False
print(bad["flags"])   # ["Factual mismatch: ..."]

Metrics

metrics = client.get_session_metrics()
print(f"Cache hit rate: {metrics['cache_hit_rate']}%")
print(f"Tokens saved: {metrics['tokens_saved']}")
print(f"Flags caught: {metrics['flags_caught']}")

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 config

Uninstall

clawhub uninstall token-reduction-engine

License

MIT-0 (Free, no attribution required)

Note

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