foxy-audit 1.0.0__tar.gz

foxy_audit-1.0.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Node / Next.js
+node_modules/
+.next/
+*.tsbuildinfo
+
+# Secrets / local config
+.env
+.env.local
+backend/.env
+*.local
+
+# DB backups (created by deploy/backup.sh on the VM)
+deploy/backups/
+
+# OS / editor
+.DS_Store
+Thumbs.db

foxy_audit-1.0.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: foxy-audit
+Version: 1.0.0
+Summary: Governance-as-Code SDK for AI compliance: local SHA-256 hashing + tamper-evident audit telemetry, with zero raw-text exfiltration.
+Project-URL: Homepage, https://foxyaudit.tech
+Project-URL: Documentation, https://foxyaudit.tech/docs.html
+Project-URL: Source, https://github.com/fatimaatta-09/Foxy-Audit
+Project-URL: Issues, https://github.com/fatimaatta-09/Foxy-Audit/issues
+Author: Foxy Audit
+License: MIT
+Keywords: ai,audit,compliance,eu-ai-act,governance,hipaa,soc2
+Classifier: Development Status :: 5 - Production/Stable
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: requests<3,>=2.31
+Provides-Extra: pii
+Requires-Dist: presidio-analyzer>=2.2; extra == 'pii'
+Requires-Dist: spacy>=3.7; extra == 'pii'
+Provides-Extra: test
+Requires-Dist: httpx>=0.27; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# foxy-audit (SDK)
+
+> Governance-as-Code for AI. One decorator → a tamper-evident, privacy-preserving audit trail.
+
+The SDK hashes your LLM prompt + response **locally** (SHA-256), throws the raw text away, and
+streams only metadata to the Foxy Audit backend. It also fires a best-effort local UDP ping so the
+desktop "fox" companion reacts in real time (green on every logged call, red on a policy breach).
+
+## Install
+
+```bash
+pip install -e .            # from this sdk/ folder, for local development
+```
+
+Runtime dependency: `requests` only.
+
+## Use
+
+```python
+import os
+from foxy_audit import FoxyClient
+
+foxy = FoxyClient(api_key=os.getenv("FOXY_API_KEY"))   # or just rely on the env var
+
+@foxy.audit(policy="hipaa_basic")
+def ask_model(prompt: str) -> str:
+    return llm_client.generate(prompt)     # your existing code — unchanged
+```
+
+Every call to `ask_model` is now hashed, logged, and graded. Or use the module-level decorator,
+which builds a client from the environment:
+
+```python
+from foxy_audit import audit
+
+@audit(policy="soc2")
+def summarize(text: str) -> str:
+    ...
+```
+
+### Attributing the model (`agent`)
+
+Pass `agent=` to record *which* model produced the interaction. The backend folds it into the
+tamper-evident hash chain, so the attribution can't be altered after the fact:
+
+```python
+@foxy.audit(policy="soc2", agent="gpt-4o")
+def ask_model(prompt: str) -> str:
+    ...
+```
+
+`agent` is optional — rows logged without it hash exactly as before, so existing chains keep
+verifying.
+
+## Configuration
+
+| Setting        | Kwarg          | Env var             | Default                  |
+|----------------|----------------|---------------------|--------------------------|
+| API key        | `api_key`      | `FOXY_API_KEY`      | _(none → HTTP disabled)_ |
+| Backend URL    | `endpoint`     | `FOXY_BACKEND_URL`  | `http://127.0.0.1:8000`  |
+| Desktop ping   | `desktop_ping` | —                   | `True` (127.0.0.1:9999)  |
+
+With no API key the SDK is a **graceful no-op for the cloud path**: it still runs your function and
+still pings the desktop fox, but skips the HTTP upload — so you can see the fox react before any
+backend exists.
+
+## Guarantees
+
+- **Never blocks** your function — the HTTP upload runs on a background daemon thread.
+- **Never raises** its own errors into your app — all telemetry failures are swallowed.
+- **Never sees raw text** server-side — only SHA-256 digests + token count + policy tag leave the host.
+- Works with both **sync and async** functions; the return value is always passed through unchanged.
+
+## What gets sent
+
+To the backend (`POST /v1/logs`, `Authorization: Bearer <key>`):
+
+```json
+{"prompt_hash": "<64 hex>", "response_hash": "<64 hex>", "token_count": 123, "policy_tag": "hipaa_basic"}
+```
+
+To the desktop fox (UDP `127.0.0.1:9999`):
+
+```json
+{"event": "hash_ok", "policy": "hipaa_basic", "tokens": 123, "ts": 1719300000}
+{"event": "policy_breach", "reason": "...", "risk_score": 87, "policy": "hipaa_basic", "ts": ...}
+```

foxy_audit-1.0.0/README.md

@@ -0,0 +1,87 @@
+# foxy-audit (SDK)
+
+> Governance-as-Code for AI. One decorator → a tamper-evident, privacy-preserving audit trail.
+
+The SDK hashes your LLM prompt + response **locally** (SHA-256), throws the raw text away, and
+streams only metadata to the Foxy Audit backend. It also fires a best-effort local UDP ping so the
+desktop "fox" companion reacts in real time (green on every logged call, red on a policy breach).
+
+## Install
+
+```bash
+pip install -e .            # from this sdk/ folder, for local development
+```
+
+Runtime dependency: `requests` only.
+
+## Use
+
+```python
+import os
+from foxy_audit import FoxyClient
+
+foxy = FoxyClient(api_key=os.getenv("FOXY_API_KEY"))   # or just rely on the env var
+
+@foxy.audit(policy="hipaa_basic")
+def ask_model(prompt: str) -> str:
+    return llm_client.generate(prompt)     # your existing code — unchanged
+```
+
+Every call to `ask_model` is now hashed, logged, and graded. Or use the module-level decorator,
+which builds a client from the environment:
+
+```python
+from foxy_audit import audit
+
+@audit(policy="soc2")
+def summarize(text: str) -> str:
+    ...
+```
+
+### Attributing the model (`agent`)
+
+Pass `agent=` to record *which* model produced the interaction. The backend folds it into the
+tamper-evident hash chain, so the attribution can't be altered after the fact:
+
+```python
+@foxy.audit(policy="soc2", agent="gpt-4o")
+def ask_model(prompt: str) -> str:
+    ...
+```
+
+`agent` is optional — rows logged without it hash exactly as before, so existing chains keep
+verifying.
+
+## Configuration
+
+| Setting        | Kwarg          | Env var             | Default                  |
+|----------------|----------------|---------------------|--------------------------|
+| API key        | `api_key`      | `FOXY_API_KEY`      | _(none → HTTP disabled)_ |
+| Backend URL    | `endpoint`     | `FOXY_BACKEND_URL`  | `http://127.0.0.1:8000`  |
+| Desktop ping   | `desktop_ping` | —                   | `True` (127.0.0.1:9999)  |
+
+With no API key the SDK is a **graceful no-op for the cloud path**: it still runs your function and
+still pings the desktop fox, but skips the HTTP upload — so you can see the fox react before any
+backend exists.
+
+## Guarantees
+
+- **Never blocks** your function — the HTTP upload runs on a background daemon thread.
+- **Never raises** its own errors into your app — all telemetry failures are swallowed.
+- **Never sees raw text** server-side — only SHA-256 digests + token count + policy tag leave the host.
+- Works with both **sync and async** functions; the return value is always passed through unchanged.
+
+## What gets sent
+
+To the backend (`POST /v1/logs`, `Authorization: Bearer <key>`):
+
+```json
+{"prompt_hash": "<64 hex>", "response_hash": "<64 hex>", "token_count": 123, "policy_tag": "hipaa_basic"}
+```
+
+To the desktop fox (UDP `127.0.0.1:9999`):
+
+```json
+{"event": "hash_ok", "policy": "hipaa_basic", "tokens": 123, "ts": 1719300000}
+{"event": "policy_breach", "reason": "...", "risk_score": 87, "policy": "hipaa_basic", "ts": ...}
+```

foxy_audit-1.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "foxy-audit"
+version = "1.0.0"
+description = "Governance-as-Code SDK for AI compliance: local SHA-256 hashing + tamper-evident audit telemetry, with zero raw-text exfiltration."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Foxy Audit" }]
+keywords = ["compliance", "audit", "ai", "governance", "hipaa", "soc2", "eu-ai-act"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+# A library: bound the major (never exact-pin) so it stays co-installable in a
+# consumer's environment. (Phase 5 · 5F)
+dependencies = ["requests>=2.31,<3"]
+
+[project.urls]
+Homepage = "https://foxyaudit.tech"
+Documentation = "https://foxyaudit.tech/docs.html"
+Source = "https://github.com/fatimaatta-09/Foxy-Audit"
+Issues = "https://github.com/fatimaatta-09/Foxy-Audit/issues"
+
+[project.scripts]
+foxy = "foxy_audit.cli:main"
+
+[project.optional-dependencies]
+test = ["httpx>=0.27", "pytest>=8"]
+# Deep NLP PII detection (names / locations / MRNs). Also needs a spaCy model:
+#   python -m spacy download en_core_web_lg
+pii = ["presidio-analyzer>=2.2", "spacy>=3.7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/foxy_audit"]

foxy_audit-1.0.0/src/foxy_audit/__init__.py

@@ -0,0 +1,44 @@
+"""
+Foxy Audit SDK — Governance-as-Code for AI applications.
+
+Wrap any LLM call with the ``@audit`` decorator and every invocation is
+hashed locally (SHA-256), the raw text is discarded, and only metadata is
+streamed to the Foxy Audit backend — plus a best-effort local UDP ping that
+makes the desktop "fox" companion react in real time.
+
+Quickstart
+----------
+    from foxy_audit import FoxyClient
+
+    foxy = FoxyClient(api_key="foxy_sk_...")     # or set $FOXY_API_KEY
+
+    @foxy.audit(policy="hipaa_basic")
+    def ask_model(prompt: str) -> str:
+        return llm_client.generate(prompt)       # your code, unchanged
+
+The decorator never blocks the wrapped function and never raises its own
+errors into your application — telemetry failure is swallowed silently.
+"""
+
+from .client import FoxyClient
+from .config import FoxyConfig
+
+__version__ = "0.1.0"
+__all__ = ["FoxyClient", "FoxyConfig", "audit", "__version__"]
+
+# Module-level convenience: a lazily-created client configured from the
+# environment (FOXY_API_KEY / FOXY_BACKEND_URL), so `from foxy_audit import audit`
+# works without explicitly constructing a client.
+_default_client = None
+
+
+def _client() -> FoxyClient:
+    global _default_client
+    if _default_client is None:
+        _default_client = FoxyClient()
+    return _default_client
+
+
+def audit(policy: str = "default"):
+    """Decorator bound to the default environment-configured client."""
+    return _client().audit(policy)

foxy_audit-1.0.0/src/foxy_audit/cli.py

@@ -0,0 +1,105 @@
+"""foxy doctor — one-command, end-to-end connectivity check for the Foxy Audit SDK.
+
+Sends a real test interaction through the whole path and reports what is actually
+connected: the backend (authenticated ingest), the desktop pet (a local UDP signal),
+and the tamper-evident chain (the test log verified server-side). This is the
+highest-leverage "is it all wired together?" check for you or a judge.
+
+    foxy doctor
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+import requests
+
+from . import hashing, udp
+from .config import FoxyConfig
+
+def _pick(uni: str, plain: str) -> str:
+    """Emoji if the terminal can encode it, else an ASCII marker (Windows cp1252-safe)."""
+    try:
+        uni.encode(sys.stdout.encoding or "utf-8")
+        return uni
+    except (UnicodeEncodeError, LookupError, TypeError):
+        return plain
+
+
+_OK = _pick("✅", "[OK]")
+_X = _pick("❌", "[X]")
+_ARROW = _pick("→", "->")
+_FOX = _pick("🦊", "")
+
+
+def _doctor(cfg: FoxyConfig) -> int:
+    print("Foxy Audit — doctor")
+    print(f"  backend : {cfg.endpoint}")
+    print(f"  pet     : {cfg.udp_host}:{cfg.udp_port}")
+    if not cfg.api_key:
+        print(f"  {_X} No API key set. Export FOXY_API_KEY (get one from a free signup or the "
+              f"dashboard), then re-run `foxy doctor`.")
+        return 1
+
+    # 1) BACKEND — authenticated ingest of one real test interaction.
+    prompt, response = "foxy doctor test prompt", "foxy doctor test response"
+    payload = [{
+        "prompt_hash": hashing.sha256_hex(prompt),
+        "response_hash": hashing.sha256_hex(response),
+        "token_count": hashing.estimate_tokens(prompt, response),
+        "policy_tag": "foxy-doctor",
+    }]
+    try:
+        r = requests.post(f"{cfg.endpoint}/v1/logs/batch",
+                          headers={"Authorization": f"Bearer {cfg.api_key}"},
+                          json=payload, timeout=cfg.timeout)
+    except requests.RequestException as exc:
+        print(f"  {_X} Backend unreachable at {cfg.endpoint} ({exc}). Is it running / is the URL right?")
+        return 1
+    if r.status_code == 401:
+        print(f"  {_X} Backend rejected the API key (401). Check FOXY_API_KEY.")
+        return 1
+    if r.status_code >= 400:
+        print(f"  {_X} Backend error {r.status_code}: {r.text[:200]}")
+        return 1
+    print(f"  {_OK} Backend reachable + authenticated — test log accepted (HTTP {r.status_code}).")
+
+    # 2) DESKTOP PET — fire the same instant signal the SDK sends on every call.
+    sent = udp.send_ping({"event": "evaluating", "policy": "foxy-doctor"},
+                         cfg.udp_host, cfg.udp_port)
+    tail = "watch the fox react" if sent else "no pet is listening — that is fine"
+    print(f"  {_ARROW} Sent a signal to the desktop pet ({tail}).")
+
+    # 3) CHAIN — confirm the ledger verifies server-side.
+    try:
+        v = requests.get(f"{cfg.endpoint}/v1/verify",
+                         headers={"Authorization": f"Bearer {cfg.api_key}"},
+                         timeout=cfg.timeout)
+        data = v.json() if v.ok else {}
+    except requests.RequestException:
+        data = {}
+    if data.get("ok"):
+        print(f"  {_OK} Ledger verified — {data.get('count', 0)} entries, chain intact.")
+    else:
+        print(f"  {_OK} Test log written. (Grading + chain verification complete server-side "
+              f"within a few seconds.)")
+
+    print(f"\nAll set — your calls are flowing end-to-end. {_FOX}".rstrip())
+    return 0
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="foxy", description="Foxy Audit SDK tools.")
+    sub = parser.add_subparsers(dest="command")
+    doc = sub.add_parser("doctor", help="check backend + desktop pet + chain end-to-end")
+    doc.add_argument("--api-key", default=None, help="override FOXY_API_KEY")
+    doc.add_argument("--backend", default=None, help="override FOXY_BACKEND_URL")
+    args = parser.parse_args(argv)
+    if args.command == "doctor":
+        return _doctor(FoxyConfig.resolve(api_key=args.api_key, endpoint=args.backend))
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

foxy_audit-1.0.0/src/foxy_audit/client.py

@@ -0,0 +1,124 @@
+"""FoxyClient — the developer-facing decorator.
+
+`@client.audit(policy)` wraps any function (sync or async) that calls an LLM.
+After the wrapped function returns, the SDK:
+
+  1. SHA-256-hashes the prompt and response locally, then discards the raw text.
+  2. Fires an instant best-effort `hash_ok` UDP ping to the desktop fox.
+  3. Enqueues the metadata for background HTTP delivery to the backend (only
+     when an API key is configured).
+
+The wrapped function's own return value is always passed through unchanged, and
+the SDK's own bookkeeping can never raise into the host application.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+import re
+
+from . import dispatch, hashing, pii, udp
+from .config import FoxyConfig
+
+log = logging.getLogger("foxy_audit")
+
+_POLICY_RE = re.compile(r"^[a-z0-9_]{1,32}$")
+_PROMPT_KWARGS = ("prompt", "user_prompt", "message", "text", "input", "query")
+
+
+def _extract_prompt(args: tuple, kwargs: dict) -> str:
+    """Best-effort: the first known prompt kwarg, else the first string arg."""
+    for key in _PROMPT_KWARGS:
+        val = kwargs.get(key)
+        if isinstance(val, str):
+            return val
+    for arg in args:
+        if isinstance(arg, str):
+            return arg
+    return ""
+
+
+class FoxyClient:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        endpoint: str | None = None,
+        udp_host: str | None = None,
+        udp_port: int | None = None,
+        desktop_ping: bool = True,
+        timeout: float = 5.0,
+    ) -> None:
+        self.cfg = FoxyConfig.resolve(
+            api_key=api_key,
+            endpoint=endpoint,
+            udp_host=udp_host,
+            udp_port=udp_port,
+            desktop_ping=desktop_ping,
+            timeout=timeout,
+        )
+
+    @property
+    def enabled(self) -> bool:
+        return self.cfg.enabled
+
+    def audit(self, policy: str = "default", agent: str | None = None):
+        """Return a decorator that audits the wrapped LLM-calling function.
+
+        `agent` records which model/agent produced the interaction (e.g.
+        "gpt-4o", "claude-3-opus"); the backend folds it into the tamper-evident
+        hash chain so it can't be altered after the fact (6B)."""
+        if not _POLICY_RE.match(policy):
+            log.warning("foxy-audit: invalid policy tag %r; falling back to 'default'", policy)
+            policy = "default"
+
+        def decorator(fn):
+            if inspect.iscoroutinefunction(fn):
+                @functools.wraps(fn)
+                async def awrapper(*args, **kwargs):
+                    response = await fn(*args, **kwargs)
+                    self.log_interaction(_extract_prompt(args, kwargs), response, policy, agent)
+                    return response
+                return awrapper
+
+            @functools.wraps(fn)
+            def wrapper(*args, **kwargs):
+                response = fn(*args, **kwargs)
+                self.log_interaction(_extract_prompt(args, kwargs), response, policy, agent)
+                return response
+            return wrapper
+
+        return decorator
+
+    # ── internal ──────────────────────────────────────────────────────────
+    def log_interaction(self, prompt, response, policy: str, agent: str | None = None) -> None:
+        """Perform cryptographic hashing synchronously and push to AsyncDispatcher."""
+        try:
+            prompt_s = "" if prompt is None else str(prompt)
+            response_s = "" if response is None else str(response)
+
+            # The backend owns the tamper-evident hash chain (it re-derives each
+            # link server-side), so the SDK only ships the per-interaction hashes;
+            # a client-side chain_hash/timestamp would just be ignored.
+            payload = {
+                "prompt_hash": hashing.sha256_hex(prompt_s),
+                "response_hash": hashing.sha256_hex(response_s),
+                "token_count": hashing.estimate_tokens(prompt_s, response_s),
+                "policy_tag": policy,
+                "pii_signals": pii.detect_pii(prompt_s, response_s),
+            }
+            if agent:
+                payload["agent"] = agent
+            # raw text goes out of scope here — never stored or transmitted
+
+            if self.cfg.desktop_ping:
+                udp.send_ping(
+                    {"event": "evaluating", "policy": policy, "tokens": payload["token_count"]},
+                    self.cfg.udp_host,
+                    self.cfg.udp_port,
+                )
+            if self.cfg.enabled:
+                dispatch.submit(self.cfg, payload)
+        except Exception as exc:  # telemetry must never break the host app
+            log.debug("foxy-audit observe error: %s", exc)

foxy_audit-1.0.0/src/foxy_audit/config.py

@@ -0,0 +1,58 @@
+"""Configuration resolution for the Foxy Audit SDK.
+
+Priority for every setting: explicit kwarg → environment variable → default.
+The SDK is a graceful no-op for the HTTP path when no API key is configured
+(it still fires the local UDP ping so the desktop fox reacts), so importing
+and decorating is always safe even before a key/backend exist.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+# The UDP host/port are fixed by the desktop app's sdk_bridge listener.
+DEFAULT_ENDPOINT = "http://127.0.0.1:8000"
+DEFAULT_UDP_HOST = "127.0.0.1"
+DEFAULT_UDP_PORT = 9999
+DEFAULT_TIMEOUT = 5.0
+
+
+@dataclass(frozen=True)
+class FoxyConfig:
+    api_key: str = ""
+    endpoint: str = DEFAULT_ENDPOINT
+    udp_host: str = DEFAULT_UDP_HOST
+    udp_port: int = DEFAULT_UDP_PORT
+    desktop_ping: bool = True
+    timeout: float = DEFAULT_TIMEOUT
+
+    @classmethod
+    def resolve(
+        cls,
+        api_key: str | None = None,
+        endpoint: str | None = None,
+        udp_host: str | None = None,
+        udp_port: int | None = None,
+        desktop_ping: bool = True,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> "FoxyConfig":
+        key = api_key if api_key is not None else os.getenv("FOXY_API_KEY", "")
+        ep = endpoint if endpoint is not None else os.getenv("FOXY_BACKEND_URL", DEFAULT_ENDPOINT)
+        return cls(
+            api_key=key.strip(),
+            endpoint=ep.rstrip("/"),
+            udp_host=udp_host or DEFAULT_UDP_HOST,
+            udp_port=int(udp_port or DEFAULT_UDP_PORT),
+            desktop_ping=desktop_ping,
+            timeout=timeout,
+        )
+
+    @property
+    def enabled(self) -> bool:
+        """True when the SDK should stream to the cloud backend.
+
+        When False, the decorator still runs the wrapped function and still
+        fires the local desktop ping — it just skips the HTTP POST.
+        """
+        return bool(self.api_key)

foxy_audit-1.0.0/src/foxy_audit/dispatch.py

@@ -0,0 +1,102 @@
+"""Background dispatch — keeps all network I/O off the host application's thread.
+
+A single lazily-started daemon thread drains a queue of ingest jobs in batches.
+For each batch, it POSTs the metadata to the backend.
+
+Every failure path is swallowed and logged at debug level — telemetry must never
+crash, block, or surface an error to the host app.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import queue
+import threading
+import time
+import requests
+
+from .config import FoxyConfig
+
+log = logging.getLogger("foxy_audit")
+
+
+class AsyncDispatcher:
+    def __init__(self, batch_size: int = 10, flush_interval: float = 1.0) -> None:
+        self._q: "queue.Queue[tuple[FoxyConfig, dict]]" = queue.Queue()
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+        self.batch_size = batch_size
+        self.flush_interval = flush_interval
+        self._shutdown = False
+        atexit.register(self.flush)
+
+    def _ensure_worker(self) -> None:
+        if self._thread is not None and self._thread.is_alive():
+            return
+        with self._lock:
+            if self._thread is None or not self._thread.is_alive():
+                self._shutdown = False
+                self._thread = threading.Thread(
+                    target=self._run, name="foxy-audit-async-dispatch", daemon=True
+                )
+                self._thread.start()
+
+    def submit(self, cfg: FoxyConfig, payload: dict) -> None:
+        self._ensure_worker()
+        self._q.put((cfg, payload))
+
+    def _run(self) -> None:
+        batch = []
+        last_flush = time.time()
+        
+        while not self._shutdown or not self._q.empty():
+            try:
+                # Wait up to the flush interval for an item
+                timeout = max(0.1, self.flush_interval - (time.time() - last_flush))
+                cfg, payload = self._q.get(timeout=timeout)
+                batch.append((cfg, payload))
+            except queue.Empty:
+                pass
+
+            now = time.time()
+            if batch and (len(batch) >= self.batch_size or now - last_flush >= self.flush_interval):
+                self._process_batch(batch)
+                batch = []
+                last_flush = now
+
+    def _process_batch(self, batch: list[tuple[FoxyConfig, dict]]) -> None:
+        if not batch:
+            return
+        
+        cfg = batch[0][0]
+        payloads = [item[1] for item in batch]
+        
+        try:
+            headers = {"Authorization": f"Bearer {cfg.api_key}", "Content-Type": "application/json"}
+            
+            # Normalise the endpoint to always be .../v1/logs/batch
+            # Strip any trailing slashes and known suffixes, then append the canonical path.
+            base = cfg.endpoint.rstrip("/")
+            for suffix in ("/v1/logs/batch", "/v1/logs", "/logs/batch", "/logs"):
+                if base.endswith(suffix):
+                    base = base[: -len(suffix)]
+                    break
+            endpoint = f"{base}/v1/logs/batch"
+
+            resp = requests.post(endpoint, json=payloads, headers=headers, timeout=cfg.timeout)
+            resp.raise_for_status()
+        except Exception as exc:
+            log.debug("foxy-audit POST failed: %s", exc)
+
+    def flush(self) -> None:
+        self._shutdown = True
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=2.0)
+
+
+_DISPATCHER = AsyncDispatcher()
+
+def submit(cfg: FoxyConfig, payload: dict) -> None:
+    """Enqueue an ingest job for background delivery."""
+    _DISPATCHER.submit(cfg, payload)

foxy_audit-1.0.0/src/foxy_audit/hashing.py

@@ -0,0 +1,31 @@
+"""Local hashing — the heart of the zero-knowledge ("data blindness") design.
+
+Prompt and response are hashed here, in-process, and the raw strings are never
+returned, stored, or transmitted. Only the resulting digests + a token estimate
+leave this module.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def sha256_hex(text: str) -> str:
+    """Lowercase 64-char hex SHA-256 of the UTF-8 encoding of `text`."""
+    return hashlib.sha256(str(text).encode("utf-8")).hexdigest()
+
+
+def estimate_tokens(*parts: str) -> int:
+    """Cheap, dependency-free token estimate.
+
+    Approximates a tokenizer with max(chars/4, whitespace-word-count) per part —
+    good enough for anomaly detection on the backend without pulling in a heavy
+    tokenizer dependency. Swap for tiktoken later if exactness is needed.
+    """
+    total = 0
+    for part in parts:
+        s = str(part)
+        if not s:
+            continue
+        total += max(len(s) // 4, len(s.split()))
+    return total

foxy_audit-1.0.0/src/foxy_audit/pii.py

@@ -0,0 +1,81 @@
+"""Client-side PII detection (Phase 5 · 5J).
+
+Runs in the SDK — the ONLY place that ever sees raw prompt/response text (the
+backend receives hashes + signals only). A lightweight, dependency-free regex
+layer runs ALWAYS; Microsoft Presidio (deep NLP: names, locations, MRNs) is used
+ONLY when the optional extra is installed (`pip install foxy-audit[pii]`), so the
+base SDK stays tiny. Detection emits SIGNAL LABELS (never the raw values), which
+ride along in the audit metadata for the judge to weigh.
+"""
+
+from __future__ import annotations
+
+import re
+
+_EMAIL_RE = re.compile(r"[\w.\-]+@[\w\-]+\.\w+")
+_SSN_RE = re.compile(r"\b\d{3}-\d{2}-\d{4}\b")
+_PHONE_RE = re.compile(r"(?<!\d)(?:\+?\d{1,3}[ .\-]?)?\(?\d{3}\)?[ .\-]?\d{3}[ .\-]?\d{4}(?!\d)")
+_IPV4_RE = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")
+_CARD_CANDIDATE_RE = re.compile(r"(?<!\d)(?:\d[ \-]?){13,19}(?!\d)")
+
+
+def _luhn_ok(digits: str) -> bool:
+    """Standard Luhn checksum — separates real card numbers from any 13–19 digit run."""
+    if not (13 <= len(digits) <= 19):
+        return False
+    total = 0
+    for i, ch in enumerate(reversed(digits)):
+        n = int(ch)
+        if i % 2 == 1:                       # double every second digit from the right
+            n *= 2
+            if n > 9:
+                n -= 9
+        total += n
+    return total % 10 == 0
+
+
+def _has_card(text: str) -> bool:
+    for m in _CARD_CANDIDATE_RE.finditer(text):
+        if _luhn_ok(re.sub(r"\D", "", m.group())):
+            return True
+    return False
+
+
+# ── optional Presidio (deep NLP) — only if the [pii] extra is installed ───────
+_PRESIDIO = None   # None = not tried yet, False = unavailable, else the engine
+
+
+def _presidio_signals(text: str) -> list[str]:
+    global _PRESIDIO
+    if _PRESIDIO is None:
+        try:
+            from presidio_analyzer import AnalyzerEngine
+            _PRESIDIO = AnalyzerEngine()
+        except Exception:                    # not installed / model missing → never retry
+            _PRESIDIO = False
+    if not _PRESIDIO:
+        return []
+    try:
+        results = _PRESIDIO.analyze(text=text, language="en")
+        return [f"presidio:{r.entity_type.lower()}" for r in results if r.score >= 0.5]
+    except Exception:
+        return []
+
+
+def detect_pii(prompt_s: str, response_s: str) -> list[str]:
+    """De-duplicated PII SIGNAL labels (never raw values) for prompt+response.
+    Lightweight regex always; Presidio signals appended when the extra is present."""
+    combined = f"{prompt_s} {response_s}"
+    signals: list[str] = []
+    if _EMAIL_RE.search(combined):
+        signals.append("email")
+    if _SSN_RE.search(combined):
+        signals.append("ssn_pattern")
+    if _PHONE_RE.search(combined):
+        signals.append("phone")
+    if _IPV4_RE.search(combined):
+        signals.append("ip_address")
+    if _has_card(combined):
+        signals.append("credit_card")
+    signals.extend(_presidio_signals(combined))
+    return sorted(set(signals))

foxy_audit-1.0.0/src/foxy_audit/udp.py

@@ -0,0 +1,44 @@
+"""Best-effort local UDP ping to the desktop fox companion.
+
+Speaks the exact protocol of the desktop app's sdk_bridge listener:
+a JSON datagram (<= 4096 bytes) sent to 127.0.0.1:9999, with an `event` of
+"evaluating" (grading pending — fired instantly), "policy_breach", or the legacy
+"hash_ok". This is purely cosmetic ambient feedback (the fox reacts); the
+authoritative record is the HTTP-written
+ledger row, so packet loss here is harmless. The whole send is wrapped so it
+can never raise into the SDK or the host application.
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import time
+
+MAX_PACKET = 4096  # must match sdk_bridge.MAX_PACKET_SIZE
+
+
+def send_ping(payload: dict, host: str = "127.0.0.1", port: int = 9999) -> bool:
+    """Fire a single UDP datagram. Returns True on success, False otherwise.
+
+    Always stamps `ts`. If the encoded payload exceeds the listener's 4096-byte
+    limit, the `reason` field (if present) is trimmed before re-encoding.
+    """
+    try:
+        msg = dict(payload)
+        msg.setdefault("ts", time.time())
+        data = json.dumps(msg).encode("utf-8")
+        if len(data) > MAX_PACKET and isinstance(msg.get("reason"), str):
+            overflow = len(data) - MAX_PACKET
+            msg["reason"] = msg["reason"][: max(0, len(msg["reason"]) - overflow - 1)]
+            data = json.dumps(msg).encode("utf-8")
+        if len(data) > MAX_PACKET:
+            return False  # still too big (no reason field to trim) — drop it
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        try:
+            sock.sendto(data, (host, port))
+        finally:
+            sock.close()
+        return True
+    except Exception:
+        return False

foxy_audit-1.0.0/tests/test_cli.py

@@ -0,0 +1,48 @@
+"""`foxy doctor` CLI — backend / pet / chain checks, with the network mocked."""
+from __future__ import annotations
+
+import requests
+
+import foxy_audit.cli as cli
+
+
+class _Resp:
+    def __init__(self, status=202, payload=None, text=""):
+        self.status_code = status
+        self._payload = payload or {}
+        self.text = text
+
+    @property
+    def ok(self):
+        return self.status_code < 400
+
+    def json(self):
+        return self._payload
+
+
+def test_doctor_all_green(monkeypatch, capsys):
+    monkeypatch.setattr(cli.requests, "post", lambda *a, **k: _Resp(202))
+    monkeypatch.setattr(cli.requests, "get", lambda *a, **k: _Resp(200, {"ok": True, "count": 1}))
+    monkeypatch.setattr(cli.udp, "send_ping", lambda *a, **k: True)
+    assert cli.main(["doctor", "--api-key", "foxy_sk_test", "--backend", "http://x"]) == 0
+    out = capsys.readouterr().out
+    assert "Backend reachable" in out and "Ledger verified" in out
+
+
+def test_doctor_bad_key(monkeypatch):
+    monkeypatch.setattr(cli.requests, "post", lambda *a, **k: _Resp(401, text="Invalid API key"))
+    monkeypatch.setattr(cli.udp, "send_ping", lambda *a, **k: True)
+    assert cli.main(["doctor", "--api-key", "bad", "--backend", "http://x"]) == 1
+
+
+def test_doctor_no_key(monkeypatch):
+    monkeypatch.delenv("FOXY_API_KEY", raising=False)
+    assert cli.main(["doctor", "--backend", "http://x"]) == 1
+
+
+def test_doctor_backend_unreachable(monkeypatch):
+    def _boom(*a, **k):
+        raise requests.RequestException("no route to host")
+    monkeypatch.setattr(cli.requests, "post", _boom)
+    monkeypatch.setattr(cli.udp, "send_ping", lambda *a, **k: True)
+    assert cli.main(["doctor", "--api-key", "foxy_sk_test", "--backend", "http://x"]) == 1

foxy_audit-1.0.0/tests/test_integration.py

@@ -0,0 +1,147 @@
+"""End-to-end SDK integration test against a stdlib mock backend + fake fox.
+
+Proves the full dispatch path without Postgres or Gemini:
+  • the instant `evaluating` UDP ping is emitted per audited call,
+  • the AsyncDispatcher POSTs a BATCH (a JSON list) to {endpoint}/v1/logs/batch
+    with a Bearer header, and each item carries only hashes / token_count /
+    policy_tag (never raw text),
+  • every audited call is eventually delivered (no drops across batches).
+
+Grading is asynchronous in the real backend (the batch endpoint returns 202
+{"status": "pending"} and the worker back-fills verdicts later), so the SDK gets
+no verdict at ingest time — breach signalling is not part of this HTTP path.
+
+Run:  PYTHONPATH=sdk/src python sdk/tests/test_integration.py
+ or:  pip install -e ./sdk && pytest sdk/tests/test_integration.py
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from foxy_audit import FoxyClient
+
+
+class _MockBackend:
+    """Captures POSTs and replies like the real batch endpoint (202, pending)."""
+
+    def __init__(self):
+        self.requests: list[tuple[str, dict, list]] = []   # (path, headers, body)
+        handler = self._make_handler()
+        self.server = HTTPServer(("127.0.0.1", 0), handler)
+        self.port = self.server.server_address[1]
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+        self.thread.start()
+
+    @property
+    def endpoint(self) -> str:
+        return f"http://127.0.0.1:{self.port}"
+
+    def _make_handler(self):
+        backend = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *_):  # silence
+                pass
+
+            def do_POST(self):
+                length = int(self.headers.get("Content-Length", 0))
+                body = json.loads(self.rfile.read(length) or b"[]")
+                backend.requests.append((self.path, dict(self.headers), body))
+                resp = json.dumps({"status": "pending", "count": len(body)}).encode()
+                self.send_response(202)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(resp)))
+                self.end_headers()
+                self.wfile.write(resp)
+
+        return Handler
+
+    def stop(self):
+        self.server.shutdown()
+
+
+def _udp_listener():
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind(("127.0.0.1", 0))
+    sock.settimeout(0.5)
+    return sock, sock.getsockname()[1]
+
+
+def _recv_event(sock, timeout=5.0):
+    sock.settimeout(timeout)
+    try:
+        data, _ = sock.recvfrom(4096)
+        return json.loads(data.decode())
+    except socket.timeout:
+        return None
+
+
+def _delivered(backend) -> list:
+    """All payload items received so far, across every batch POST."""
+    return [item for _, _, body in backend.requests for item in body]
+
+
+def _wait_for_delivered(backend, n, timeout=8.0):
+    deadline = time.time() + timeout
+    while len(_delivered(backend)) < n and time.time() < deadline:
+        time.sleep(0.02)
+    return len(_delivered(backend)) >= n
+
+
+def test_full_dispatch_batches_hashes_only():
+    backend = _MockBackend()
+    sock, udp_port = _udp_listener()
+    try:
+        foxy = FoxyClient(api_key="foxy_sk_test", endpoint=backend.endpoint, udp_port=udp_port)
+
+        @foxy.audit("hipaa_basic")
+        def ask(prompt: str) -> str:
+            return "a clinical summary response"
+
+        # ── first audited call ──
+        assert ask("a patient prompt") == "a clinical summary response"
+
+        pending = _recv_event(sock, 2.0)
+        assert pending and pending["event"] == "evaluating" and pending["policy"] == "hipaa_basic", pending
+
+        assert _wait_for_delivered(backend, 1), "backend never received the first batch"
+        path, headers, body = backend.requests[0]
+        assert path == "/v1/logs/batch", path
+        assert headers.get("Authorization") == "Bearer foxy_sk_test"
+        assert isinstance(body, list) and len(body) >= 1, body
+
+        item = body[0]
+        assert len(item["prompt_hash"]) == 64 and len(item["response_hash"]) == 64
+        assert item["policy_tag"] == "hipaa_basic" and isinstance(item["token_count"], int)
+        # zero-knowledge: no raw text leaves the host, under any key
+        wire = json.dumps(body)
+        assert "a patient prompt" not in wire and "clinical summary" not in wire
+
+        # ── second call: also delivered (a later batch or coalesced) ──
+        ask("another prompt")
+        pending2 = _recv_event(sock, 2.0)
+        assert pending2 and pending2["event"] == "evaluating", pending2
+
+        assert _wait_for_delivered(backend, 2), "second call was never delivered"
+        delivered = _delivered(backend)
+        assert len(delivered) == 2
+        assert all(len(d["prompt_hash"]) == 64 for d in delivered)
+        # every batch went to the batch endpoint with the same Bearer key
+        assert all(p == "/v1/logs/batch" for p, _, _ in backend.requests)
+        assert all(h.get("Authorization") == "Bearer foxy_sk_test"
+                   for _, h, _ in backend.requests)
+        print("integration: batched hash-only dispatch PASS")
+    finally:
+        sock.close()
+        backend.stop()
+
+
+if __name__ == "__main__":
+    test_full_dispatch_batches_hashes_only()
+    print("\nINTEGRATION TEST PASSED")

foxy_audit-1.0.0/tests/test_pii.py

@@ -0,0 +1,37 @@
+"""PII signal detection — the expanded regex layer (Phase 5 · 5J).
+
+Presidio is an optional extra; these cover the always-on, dependency-free layer.
+Only SIGNAL labels are asserted — raw values never leave the client.
+"""
+
+from __future__ import annotations
+
+from foxy_audit.pii import detect_pii
+
+
+def test_email_and_ssn():
+    assert "email" in detect_pii("reach me at jane.doe@acme.co", "")
+    assert "ssn_pattern" in detect_pii("", "ssn 123-45-6789")
+
+
+def test_phone():
+    assert "phone" in detect_pii("call (415) 555-2671 today", "")
+    assert "phone" in detect_pii("", "+1 415-555-2671")
+
+
+def test_credit_card_luhn_gated():
+    assert "credit_card" in detect_pii("card 4242 4242 4242 4242", "")     # valid Luhn
+    assert "credit_card" not in detect_pii("ref 4242 4242 4242 4241", "")  # fails Luhn
+
+
+def test_ip_address():
+    assert "ip_address" in detect_pii("connected from 192.168.1.100", "")
+
+
+def test_clean_text_has_no_signals():
+    assert detect_pii("what is the capital of France?", "Paris.") == []
+
+
+def test_signals_are_deduped_and_sorted():
+    sig = detect_pii("a@b.com and c@d.com", "")
+    assert sig == sorted(set(sig)) and sig.count("email") == 1

foxy_audit-1.0.0/tests/test_sdk.py

@@ -0,0 +1,122 @@
+"""Unit tests for the Foxy Audit SDK that need no backend.
+
+Run with:  pip install -e ./sdk[test]  &&  pytest sdk/tests
+"""
+
+import json
+import socket
+import time
+
+from foxy_audit import FoxyClient
+from foxy_audit import hashing
+
+
+def _udp_listener():
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind(("127.0.0.1", 0))          # ephemeral port
+    sock.settimeout(2.0)
+    return sock, sock.getsockname()[1]
+
+
+def test_hashing_is_64_hex():
+    h = hashing.sha256_hex("hello")
+    assert len(h) == 64 and all(c in "0123456789abcdef" for c in h)
+
+
+def test_return_value_passes_through():
+    foxy = FoxyClient(api_key="", desktop_ping=False)
+
+    @foxy.audit("demo")
+    def f(prompt: str) -> str:
+        return prompt.upper()
+
+    assert f("hi") == "HI"
+
+
+def test_host_exception_not_masked():
+    foxy = FoxyClient(api_key="", desktop_ping=False)
+
+    @foxy.audit("demo")
+    def boom(prompt: str) -> str:
+        raise ValueError("host error")
+
+    try:
+        boom("x")
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert str(e) == "host error"
+
+
+def test_evaluating_udp_emitted():
+    sock, port = _udp_listener()
+    try:
+        foxy = FoxyClient(api_key="", udp_port=port)   # no key → HTTP disabled, UDP still fires
+
+        @foxy.audit("hipaa_basic")
+        def ask(prompt: str) -> str:
+            return "a response"
+
+        ask("a prompt")
+        data, _ = sock.recvfrom(4096)
+        msg = json.loads(data.decode())
+        # the instant ping is "evaluating" (grading pending) — never a premature verdict
+        assert msg["event"] == "evaluating"
+        assert msg["policy"] == "hipaa_basic"
+        assert isinstance(msg["tokens"], int)
+        assert "ts" in msg
+    finally:
+        sock.close()
+
+
+def test_agent_included_in_payload(monkeypatch):
+    """audit(policy, agent=…) puts the agent into the backend payload (6B)."""
+    from foxy_audit import dispatch
+    captured = {}
+    monkeypatch.setattr(dispatch, "submit", lambda cfg, payload: captured.update(payload))
+    foxy = FoxyClient(api_key="foxy_sk_test", desktop_ping=False)   # enabled → dispatch fires
+
+    @foxy.audit("demo", agent="gpt-4o")
+    def ask(prompt: str) -> str:
+        return "resp"
+
+    ask("hi")
+    assert captured.get("agent") == "gpt-4o"
+
+
+def test_payload_omits_vestigial_fields(monkeypatch):
+    """The backend ignores chain_hash/timestamp; the SDK must not send them (7A-1)."""
+    from foxy_audit import dispatch
+    captured = {}
+    monkeypatch.setattr(dispatch, "submit", lambda cfg, payload: captured.update(payload))
+    foxy = FoxyClient(api_key="foxy_sk_test", desktop_ping=False)   # enabled → dispatch fires
+
+    @foxy.audit("demo")
+    def ask(prompt: str) -> str:
+        return "resp"
+
+    ask("hi")
+    assert captured, "expected a payload to be dispatched"
+    assert "chain_hash" not in captured
+    assert "timestamp" not in captured
+
+
+def test_agent_absent_by_default(monkeypatch):
+    from foxy_audit import dispatch
+    captured = {}
+    monkeypatch.setattr(dispatch, "submit", lambda cfg, payload: captured.update(payload))
+    foxy = FoxyClient(api_key="foxy_sk_test", desktop_ping=False)
+
+    @foxy.audit("demo")
+    def ask(prompt: str) -> str:
+        return "resp"
+
+    ask("hi")
+    assert not captured.get("agent")          # no agent when not specified
+
+
+def test_no_key_means_http_disabled_but_udp_enabled():
+    foxy = FoxyClient(api_key="")
+    assert foxy.enabled is False
+    foxy2 = FoxyClient(api_key="foxy_sk_test")
+    assert foxy2.enabled is True