haluguard 0.1.0__tar.gz

haluguard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 haluguard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

haluguard-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: haluguard
+Version: 0.1.0
+Summary: CLI for haluguard — verify LLM output for hallucinations from your terminal or CI/CD.
+Project-URL: Homepage, https://haluguard.com
+Project-URL: Documentation, https://haluguard.com
+Project-URL: Repository, https://github.com/haluguard/haluguard-cli
+Project-URL: Issues, https://haluguard.com
+Author-email: haluguard <support@haluguard.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,fact-checking,hallucination,haluguard,llm,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# haluguard CLI
+
+[![PyPI version](https://img.shields.io/pypi/v/haluguard.svg)](https://pypi.org/project/haluguard/)
+[![License](https://img.shields.io/pypi/l/haluguard.svg)](./LICENSE)
+
+Verify LLM output for hallucinations directly from your terminal or CI/CD pipeline.
+Plugs into the [haluguard](https://haluguard.com) hosted API.
+
+## Install
+
+```bash
+pip install haluguard
+```
+
+Zero runtime dependencies — pure stdlib, installs in seconds.
+
+## Quick start
+
+```bash
+# 1. Save your API token (get one at haluguard.com)
+haluguard auth login
+
+# 2. Verify a file
+haluguard check report.md
+
+# 3. Or pipe input
+echo "Microsoft was founded in 1981 by Bill Gates." | haluguard check
+
+# JSON output for scripts / CI
+haluguard check report.md --json | jq .
+
+# Exit non-zero only above a confidence threshold (useful in CI)
+haluguard check report.md --threshold 0.7
+```
+
+## Output
+
+Human-readable by default:
+
+```
+✗ HALLUCINATIONS    severity=clear  score=0.95  claims=1/2  latency=4ms
+verdict source: data_contradicted
+
+  [CONTRADICTED] high · wikidata
+    claim:    Microsoft was founded in 1981
+    evidence: Wikidata confirms Microsoft was founded in 1975
+    source:   https://www.wikidata.org/wiki/Q2283
+    fix:      1975
+```
+
+`--json` returns the raw API response (verdict, severity_tier, score, findings, etc).
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Clean / no hallucinations above threshold |
+| 1    | Hallucinations detected |
+| 2    | Transient API error (rate-limited, 5xx, network) |
+| 3    | Auth error (no token / invalid token) |
+| 4    | Bad input / usage |
+
+## CI/CD example — GitHub Actions
+
+```yaml
+- name: Verify generated docs
+  env:
+    HALUGUARD_TOKEN: ${{ secrets.HALUGUARD_TOKEN }}
+  run: |
+    pip install haluguard
+    haluguard check generated/release-notes.md --threshold 0.7
+```
+
+For a dedicated GitHub Action with richer output, see
+[haluguard-action](https://github.com/haluguard/check-action).
+
+## Env vars
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `HALUGUARD_TOKEN` | (required) | Bearer token. Used in CI. Overrides `~/.haluguard/config.json`. |
+| `HALUGUARD_API_URL` | `https://api.haluguard.com` | Override for self-host / dev. |
+| `NO_COLOR` | unset | Disable ANSI colors. |
+
+## License
+
+MIT (the CLI itself). The hosted API behind it is a paid subscription
+service — see [haluguard.com](https://haluguard.com).

haluguard-0.1.0/README.md

@@ -0,0 +1,88 @@
+# haluguard CLI
+
+[![PyPI version](https://img.shields.io/pypi/v/haluguard.svg)](https://pypi.org/project/haluguard/)
+[![License](https://img.shields.io/pypi/l/haluguard.svg)](./LICENSE)
+
+Verify LLM output for hallucinations directly from your terminal or CI/CD pipeline.
+Plugs into the [haluguard](https://haluguard.com) hosted API.
+
+## Install
+
+```bash
+pip install haluguard
+```
+
+Zero runtime dependencies — pure stdlib, installs in seconds.
+
+## Quick start
+
+```bash
+# 1. Save your API token (get one at haluguard.com)
+haluguard auth login
+
+# 2. Verify a file
+haluguard check report.md
+
+# 3. Or pipe input
+echo "Microsoft was founded in 1981 by Bill Gates." | haluguard check
+
+# JSON output for scripts / CI
+haluguard check report.md --json | jq .
+
+# Exit non-zero only above a confidence threshold (useful in CI)
+haluguard check report.md --threshold 0.7
+```
+
+## Output
+
+Human-readable by default:
+
+```
+✗ HALLUCINATIONS    severity=clear  score=0.95  claims=1/2  latency=4ms
+verdict source: data_contradicted
+
+  [CONTRADICTED] high · wikidata
+    claim:    Microsoft was founded in 1981
+    evidence: Wikidata confirms Microsoft was founded in 1975
+    source:   https://www.wikidata.org/wiki/Q2283
+    fix:      1975
+```
+
+`--json` returns the raw API response (verdict, severity_tier, score, findings, etc).
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Clean / no hallucinations above threshold |
+| 1    | Hallucinations detected |
+| 2    | Transient API error (rate-limited, 5xx, network) |
+| 3    | Auth error (no token / invalid token) |
+| 4    | Bad input / usage |
+
+## CI/CD example — GitHub Actions
+
+```yaml
+- name: Verify generated docs
+  env:
+    HALUGUARD_TOKEN: ${{ secrets.HALUGUARD_TOKEN }}
+  run: |
+    pip install haluguard
+    haluguard check generated/release-notes.md --threshold 0.7
+```
+
+For a dedicated GitHub Action with richer output, see
+[haluguard-action](https://github.com/haluguard/check-action).
+
+## Env vars
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `HALUGUARD_TOKEN` | (required) | Bearer token. Used in CI. Overrides `~/.haluguard/config.json`. |
+| `HALUGUARD_API_URL` | `https://api.haluguard.com` | Override for self-host / dev. |
+| `NO_COLOR` | unset | Disable ANSI colors. |
+
+## License
+
+MIT (the CLI itself). The hosted API behind it is a paid subscription
+service — see [haluguard.com](https://haluguard.com).

haluguard-0.1.0/haluguard_cli/__init__.py

@@ -0,0 +1,3 @@
+"""haluguard CLI — verify LLM output from your terminal or CI/CD pipeline."""
+
+__version__ = "0.1.0"

haluguard-0.1.0/haluguard_cli/__main__.py

@@ -0,0 +1,292 @@
+"""haluguard CLI — entry point.
+
+Usage:
+    haluguard auth login              # paste your token, save to ~/.haluguard/config.json
+    haluguard auth logout
+    haluguard auth status
+
+    haluguard check FILE              # verify a file
+    haluguard check                   # verify stdin
+    haluguard check --json            # raw JSON output (for scripts)
+    haluguard check --threshold 0.7   # exit non-zero if score >= 0.7
+
+    haluguard version
+    haluguard help
+
+Env vars:
+    HALUGUARD_TOKEN     — overrides config (used in CI/CD)
+    HALUGUARD_API_URL   — defaults to https://api.haluguard.com (override for self-host/dev)
+
+Exit codes:
+    0    clean / no hallucinations above threshold
+    1    hallucinations detected at or above threshold
+    2    transient API error (rate-limited, 5xx)
+    3    auth error (401/403)
+    4    bad input / usage
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+import urllib.error
+import urllib.request
+
+
+__version__ = "0.1.0"
+
+DEFAULT_API_URL = "https://api.haluguard.com"
+CONFIG_DIR  = Path.home() / ".haluguard"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+# ---------- ANSI colors (auto-disable on non-TTY / NO_COLOR) ----------
+
+def _supports_color() -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    return sys.stdout.isatty()
+
+def _c(code: str, text: str) -> str:
+    if not _supports_color():
+        return text
+    return f"\033[{code}m{text}\033[0m"
+
+def red(s):    return _c("31", s)
+def green(s):  return _c("32", s)
+def yellow(s): return _c("33", s)
+def gray(s):   return _c("90", s)
+def bold(s):   return _c("1", s)
+
+
+# ---------- Config storage ----------
+
+def load_config() -> dict:
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_FILE.read_text())
+    except Exception:  # noqa: BLE001
+        return {}
+
+def save_config(cfg: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(cfg, indent=2))
+    try:
+        CONFIG_FILE.chmod(0o600)
+    except Exception:  # noqa: BLE001
+        pass
+
+def resolve_token() -> str | None:
+    return os.environ.get("HALUGUARD_TOKEN") or load_config().get("token")
+
+def resolve_api_url() -> str:
+    return (
+        os.environ.get("HALUGUARD_API_URL")
+        or load_config().get("api_url")
+        or DEFAULT_API_URL
+    ).rstrip("/")
+
+
+# ---------- HTTP ----------
+
+def call_check(text: str, user_prompt: str | None = None,
+               token: str | None = None, api_url: str | None = None,
+               timeout: float = 60.0) -> dict:
+    payload = json.dumps({"text": text, "user_prompt": user_prompt}).encode("utf-8")
+    req = urllib.request.Request(
+        f"{api_url or resolve_api_url()}/v1/check",
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {token or resolve_token() or ''}",
+            "User-Agent": f"haluguard-cli/{__version__}",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="ignore")
+        try:
+            j = json.loads(body)
+            detail = j.get("detail") or body
+        except Exception:  # noqa: BLE001
+            detail = body
+        if e.code in (401, 403):
+            sys.stderr.write(red(f"auth error ({e.code}): {detail}\n"))
+            sys.stderr.write(gray("Run `haluguard auth login` or set HALUGUARD_TOKEN.\n"))
+            sys.exit(3)
+        if e.code == 429 or 500 <= e.code < 600:
+            sys.stderr.write(yellow(f"transient API error ({e.code}): {detail}\n"))
+            sys.exit(2)
+        sys.stderr.write(red(f"API error ({e.code}): {detail}\n"))
+        sys.exit(2)
+    except urllib.error.URLError as e:
+        sys.stderr.write(red(f"connection error: {e.reason}\n"))
+        sys.exit(2)
+
+
+# ---------- Commands ----------
+
+def cmd_auth_login(args) -> int:
+    if args.token:
+        token = args.token
+    else:
+        sys.stderr.write("Paste your haluguard API token (starts with hg_live_): ")
+        sys.stderr.flush()
+        token = sys.stdin.readline().strip()
+    if not token.startswith("hg_"):
+        sys.stderr.write(red("That doesn't look like a haluguard token.\n"))
+        return 4
+    cfg = load_config()
+    cfg["token"] = token
+    save_config(cfg)
+    print(green(f"✓ Token saved to {CONFIG_FILE}"))
+    return 0
+
+def cmd_auth_logout(args) -> int:
+    cfg = load_config()
+    if cfg.pop("token", None) is None:
+        print(gray("No token was saved."))
+        return 0
+    save_config(cfg)
+    print(green("✓ Logged out (token removed)."))
+    return 0
+
+def cmd_auth_status(args) -> int:
+    token = resolve_token()
+    if not token:
+        print(red("Not logged in. Run `haluguard auth login`."))
+        return 3
+    masked = token[:12] + "…" + token[-4:]
+    print(green(f"Logged in. Token: {masked}"))
+    print(gray(f"API: {resolve_api_url()}"))
+    return 0
+
+def cmd_check(args) -> int:
+    if args.file == "-" or args.file is None:
+        if sys.stdin.isatty() and args.file is None:
+            sys.stderr.write(yellow("No input file or stdin. Pipe text or pass a file.\n"))
+            sys.stderr.write(gray("Examples:\n"))
+            sys.stderr.write(gray("  haluguard check report.md\n"))
+            sys.stderr.write(gray('  echo "Microsoft was founded in 1981" | haluguard check\n'))
+            return 4
+        text = sys.stdin.read()
+    else:
+        p = Path(args.file)
+        if not p.exists():
+            sys.stderr.write(red(f"File not found: {p}\n"))
+            return 4
+        text = p.read_text()
+
+    text = text.strip()
+    if not text:
+        sys.stderr.write(yellow("Empty input.\n"))
+        return 4
+
+    if not resolve_token():
+        sys.stderr.write(red("Not logged in. Run `haluguard auth login` or set HALUGUARD_TOKEN.\n"))
+        return 3
+
+    response = call_check(text, user_prompt=args.user_prompt)
+
+    if args.json:
+        print(json.dumps(response, indent=2))
+    else:
+        _print_human_report(response)
+
+    score = float(response.get("score") or 0)
+    is_hallu = response.get("verdict") == "hallucinations_found"
+    if args.threshold is not None:
+        return 1 if score >= args.threshold else 0
+    return 1 if is_hallu else 0
+
+def _print_human_report(r: dict) -> None:
+    is_hallu = r.get("verdict") == "hallucinations_found"
+    tier = r.get("severity_tier") or "—"
+    score = r.get("score", 0)
+    n_h = r.get("n_hallucinations", 0)
+    n_c = r.get("n_claims", 0)
+    dur = r.get("duration_ms", 0)
+    src = r.get("verdict_source") or ""
+
+    head = red("✗ HALLUCINATIONS") if is_hallu else green("✓ CLEAN")
+    print(f"{bold(head)}    severity={tier}  score={score:.2f}  claims={n_h}/{n_c}  latency={int(dur)}ms")
+    if src:
+        print(gray(f"verdict source: {src}"))
+    print()
+
+    findings = r.get("findings") or []
+    if not findings:
+        print(gray("No findings."))
+        return
+
+    for f in findings:
+        verdict = (f.get("verdict") or "").upper()
+        if verdict == "CONTRADICTED":
+            label = red(f"[{verdict}]")
+        elif verdict == "GROUNDED":
+            label = green(f"[{verdict}]")
+        else:
+            label = gray(f"[{verdict}]")
+        sev = f.get("severity") or ""
+        sev_str = f" {sev}" if sev else ""
+        verifier = f.get("verifier") or ""
+        print(f"  {label}{sev_str} {gray('· ' + verifier)}")
+        print(f"    {bold('claim:')}    {f.get('claim') or ''}")
+        if f.get("evidence"):
+            print(f"    {bold('evidence:')} {f.get('evidence')}")
+        if f.get("source_url"):
+            print(f"    {bold('source:')}   {gray(f.get('source_url'))}")
+        if f.get("suggested_correction"):
+            print(f"    {bold('fix:')}      {f.get('suggested_correction')}")
+        print()
+
+
+# ---------- Arg parser ----------
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="haluguard",
+        description="Verify LLM output for hallucinations from your terminal or CI/CD.",
+    )
+    p.add_argument("--version", action="version", version=f"haluguard {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    # check
+    pc = sub.add_parser("check", help="Verify text from a file or stdin.")
+    pc.add_argument("file", nargs="?", default=None, help="File path, or '-' for stdin (default: stdin).")
+    pc.add_argument("--user-prompt", default=None, help="Optional user prompt that produced the text.")
+    pc.add_argument("--json", action="store_true", help="Output raw JSON.")
+    pc.add_argument("--threshold", type=float, default=None,
+                    help="Exit 1 only if score >= THRESHOLD (default: any 'hallucinations_found' triggers exit 1).")
+    pc.set_defaults(func=cmd_check)
+
+    # auth
+    pa = sub.add_parser("auth", help="Manage authentication token.")
+    auth_sub = pa.add_subparsers(dest="auth_command", required=True)
+    pal = auth_sub.add_parser("login", help="Save your API token locally.")
+    pal.add_argument("--token", default=None, help="Pass token inline (otherwise prompts).")
+    pal.set_defaults(func=cmd_auth_login)
+    pao = auth_sub.add_parser("logout", help="Remove the saved token.")
+    pao.set_defaults(func=cmd_auth_logout)
+    pas = auth_sub.add_parser("status", help="Show whether a token is configured.")
+    pas.set_defaults(func=cmd_auth_status)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

haluguard-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "haluguard"
+version = "0.1.0"
+description = "CLI for haluguard — verify LLM output for hallucinations from your terminal or CI/CD."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "haluguard", email = "support@haluguard.com" }]
+requires-python = ">=3.9"
+keywords = ["llm", "hallucination", "verification", "cli", "haluguard", "fact-checking"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Quality Assurance",
+]
+# Zero runtime deps — uses urllib from stdlib so it stays tiny and trivially installable.
+dependencies = []
+
+[project.urls]
+Homepage      = "https://haluguard.com"
+Documentation = "https://haluguard.com"
+Repository    = "https://github.com/haluguard/haluguard-cli"
+Issues        = "https://haluguard.com"
+
+[project.scripts]
+haluguard = "haluguard_cli.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["haluguard_cli"]