evidence-gate-py 0.1.0__tar.gz

evidence_gate_py-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+dist/
+*.tgz
+__pycache__/
+*.pyc
+.pytest_cache/
+build/
+*.egg-info/
+.venv/
+.DS_Store
+
+node_modules/
+package-lock.json

evidence_gate_py-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: evidence-gate-py
+Version: 0.1.0
+Summary: Stop your AI from making up facts about your own data.
+Project-URL: Homepage, https://github.com/LopezDray/evidence-gate
+Author: LopezDray
+License: MIT
+Keywords: agents,ai,grounding,guardrails,hallucination,llm,rag,reliability
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Evidence Gate
+
+**Stop your AI from making up facts about your own data.**
+
+A tiny, zero-dependency gate you call **before** an LLM generates anything. It looks at the records you actually have and returns whether the model may summarize, whether the data is stale or low-quality, and the exact caveats to inject into your prompt.
+
+It is the missing step between "retrieve" and "generate" in most RAG and agent pipelines: a check that the evidence is actually good enough to speak from.
+
+```js
+import { evidenceGate, presets } from "evidence-gate";
+
+const gate = evidenceGate({ records: myRecords, rules: presets.FINANCE });
+
+if (!gate.allowedActions.summarize) {
+  return gate.caveats.join(" ");   // e.g. "No financial statements available — the AI must not invent numbers."
+}
+
+const prompt = `${systemPrompt}\n\nDATA RULES:\n- ${gate.caveats.join("\n- ")}\n\n${userPrompt}`;
+```
+
+---
+
+## The problem
+
+LLMs answer confidently even when the underlying data is missing, stale, or partial. Over your own database that means a chatbot inventing a quarter that doesn't exist, quoting a number from a cached/secondary source as if it were authoritative, or saying "as of today" about data that's months old.
+
+Content-safety guardrails (toxicity, PII) don't catch this. This is a **grounding** problem, and it needs a grounding gate.
+
+## What it does
+
+Given a set of evidence `records` and a `rules` preset, Evidence Gate returns:
+
+```js
+{
+  status: "available" | "quality_warning" | "fallback" | "missing",
+  freshness: "fresh" | "stale" | "unknown",
+  allowedActions: { summarize, compare, /* + your forbidden actions forced to false */ },
+  warnings: [{ level, code, message }],
+  caveats: ["...strings ready to inject into the prompt..."]
+}
+```
+
+- **`status`** — is there enough authoritative evidence to speak from at all?
+- **`allowedActions`** — gate generation on `summarize`; forbidden actions (e.g. `personalized_advice`, `diagnose`, `claim_realtime`) are always `false`.
+- **`caveats`** — drop straight into your system prompt so the model self-limits.
+
+It is fully **domain-agnostic**. The same engine works for finance, healthcare, support, legal — a domain is just a preset.
+
+## Install
+
+```bash
+npm install evidence-gate
+# or
+pip install evidence-gate
+```
+
+## Records
+
+Each record is one observation/period you have evidence for:
+
+```js
+{
+  date: "2026-03-31",   // ISO date of the observation
+  qualityScore: 92,     // optional 0-100
+  quality: "clean",     // optional "clean" | "review"
+  flags: ["RESTATED"],  // optional data-quality flags
+  tier: "primary"       // optional "primary" (default) | "fallback" (cached/secondary)
+}
+```
+
+## Presets
+
+A preset is a ruleset. Adding a vertical = copying a preset, never touching the core.
+
+```js
+export const FINANCE = {
+  primaryLabel: "financial statements",
+  staleDays: 135,
+  minRecords: 4,
+  qualityThreshold: 70,
+  forbiddenActions: ["personalized_advice", "claim_realtime"],
+};
+```
+
+Ships with `FINANCE`, `HEALTH`, and `SUPPORT` examples. Override any message via `rules.messages`.
+
+## Use it as an MCP server
+
+Give an agent a fact-checker it calls before it speaks. The package ships an MCP server exposing a `check_evidence` tool, so any MCP-compatible agent (Claude, IDE assistants, etc.) can gate itself.
+
+```bash
+npm install evidence-gate @modelcontextprotocol/sdk   # the SDK is an optional peer
+```
+
+Register it with your client:
+
+```json
+{
+  "mcpServers": {
+    "evidence-gate": { "command": "npx", "args": ["evidence-gate-mcp"] }
+  }
+}
+```
+
+The tool accepts `{ records, supporting?, preset?, rules? }` and returns the gate result. Instruct your agent to call it first and refuse to answer when `allowedActions.summarize` is `false`.
+
+## Why trust it
+
+The engine is intentionally small and pure — no network, no dependencies, all logic unit-tested. It runs in production today inside a financial-data application, gating an LLM over real, messy, sometimes-missing filings.
+
+## License
+
+MIT

evidence_gate_py-0.1.0/README.md

@@ -0,0 +1,113 @@
+# Evidence Gate
+
+**Stop your AI from making up facts about your own data.**
+
+A tiny, zero-dependency gate you call **before** an LLM generates anything. It looks at the records you actually have and returns whether the model may summarize, whether the data is stale or low-quality, and the exact caveats to inject into your prompt.
+
+It is the missing step between "retrieve" and "generate" in most RAG and agent pipelines: a check that the evidence is actually good enough to speak from.
+
+```js
+import { evidenceGate, presets } from "evidence-gate";
+
+const gate = evidenceGate({ records: myRecords, rules: presets.FINANCE });
+
+if (!gate.allowedActions.summarize) {
+  return gate.caveats.join(" ");   // e.g. "No financial statements available — the AI must not invent numbers."
+}
+
+const prompt = `${systemPrompt}\n\nDATA RULES:\n- ${gate.caveats.join("\n- ")}\n\n${userPrompt}`;
+```
+
+---
+
+## The problem
+
+LLMs answer confidently even when the underlying data is missing, stale, or partial. Over your own database that means a chatbot inventing a quarter that doesn't exist, quoting a number from a cached/secondary source as if it were authoritative, or saying "as of today" about data that's months old.
+
+Content-safety guardrails (toxicity, PII) don't catch this. This is a **grounding** problem, and it needs a grounding gate.
+
+## What it does
+
+Given a set of evidence `records` and a `rules` preset, Evidence Gate returns:
+
+```js
+{
+  status: "available" | "quality_warning" | "fallback" | "missing",
+  freshness: "fresh" | "stale" | "unknown",
+  allowedActions: { summarize, compare, /* + your forbidden actions forced to false */ },
+  warnings: [{ level, code, message }],
+  caveats: ["...strings ready to inject into the prompt..."]
+}
+```
+
+- **`status`** — is there enough authoritative evidence to speak from at all?
+- **`allowedActions`** — gate generation on `summarize`; forbidden actions (e.g. `personalized_advice`, `diagnose`, `claim_realtime`) are always `false`.
+- **`caveats`** — drop straight into your system prompt so the model self-limits.
+
+It is fully **domain-agnostic**. The same engine works for finance, healthcare, support, legal — a domain is just a preset.
+
+## Install
+
+```bash
+npm install evidence-gate
+# or
+pip install evidence-gate
+```
+
+## Records
+
+Each record is one observation/period you have evidence for:
+
+```js
+{
+  date: "2026-03-31",   // ISO date of the observation
+  qualityScore: 92,     // optional 0-100
+  quality: "clean",     // optional "clean" | "review"
+  flags: ["RESTATED"],  // optional data-quality flags
+  tier: "primary"       // optional "primary" (default) | "fallback" (cached/secondary)
+}
+```
+
+## Presets
+
+A preset is a ruleset. Adding a vertical = copying a preset, never touching the core.
+
+```js
+export const FINANCE = {
+  primaryLabel: "financial statements",
+  staleDays: 135,
+  minRecords: 4,
+  qualityThreshold: 70,
+  forbiddenActions: ["personalized_advice", "claim_realtime"],
+};
+```
+
+Ships with `FINANCE`, `HEALTH`, and `SUPPORT` examples. Override any message via `rules.messages`.
+
+## Use it as an MCP server
+
+Give an agent a fact-checker it calls before it speaks. The package ships an MCP server exposing a `check_evidence` tool, so any MCP-compatible agent (Claude, IDE assistants, etc.) can gate itself.
+
+```bash
+npm install evidence-gate @modelcontextprotocol/sdk   # the SDK is an optional peer
+```
+
+Register it with your client:
+
+```json
+{
+  "mcpServers": {
+    "evidence-gate": { "command": "npx", "args": ["evidence-gate-mcp"] }
+  }
+}
+```
+
+The tool accepts `{ records, supporting?, preset?, rules? }` and returns the gate result. Instruct your agent to call it first and refuse to answer when `allowedActions.summarize` is `false`.
+
+## Why trust it
+
+The engine is intentionally small and pure — no network, no dependencies, all logic unit-tested. It runs in production today inside a financial-data application, gating an LLM over real, messy, sometimes-missing filings.
+
+## License
+
+MIT

evidence_gate_py-0.1.0/evidence_gate/__init__.py

@@ -0,0 +1,21 @@
+"""Evidence Gate — stop your AI from making up facts about your own data."""
+from .core import (
+    evidence_gate,
+    classify_status,
+    derive_allowed_actions,
+    parse_date,
+    days_since,
+    freshness_label,
+)
+from . import presets
+
+__all__ = [
+    "evidence_gate",
+    "classify_status",
+    "derive_allowed_actions",
+    "parse_date",
+    "days_since",
+    "freshness_label",
+    "presets",
+]
+__version__ = "0.1.0"

evidence_gate_py-0.1.0/evidence_gate/core.py

@@ -0,0 +1,123 @@
+"""Evidence Gate — core engine (Python).
+
+Decide whether an LLM may speak about a set of records, BEFORE it generates
+anything — based on evidence coverage, freshness, and quality.
+
+No dependencies. Domain-agnostic: bring records + a ruleset (preset).
+
+    record = {"date", "quality_score"?, "quality"?, "flags"?, "tier"?}
+"""
+from datetime import datetime, date
+
+
+def parse_date(value):
+    if not value:
+        return None
+    try:
+        return datetime.strptime(str(value)[:10], "%Y-%m-%d").date()
+    except ValueError:
+        return None
+
+
+def days_since(d):
+    if not d:
+        return None
+    return (date.today() - d).days
+
+
+def freshness_label(latest, threshold_days):
+    age = days_since(latest)
+    if age is None:
+        return "unknown"
+    return "stale" if age > threshold_days else "fresh"
+
+
+def classify_status(records, rules):
+    """records[] + rules -> status of the primary evidence group.
+
+    rules: {"stale_days", "min_records", "quality_threshold"}
+    status: "available" | "quality_warning" | "fallback" | "missing"
+    """
+    usable = records or []
+    if not usable:
+        return {"status": "missing", "freshness": "unknown", "latest": None,
+                "count": 0, "quality_min": None, "flags": []}
+
+    dates = [d for d in (parse_date(r.get("date")) for r in usable) if d]
+    latest = max(dates) if dates else None
+    freshness = freshness_label(latest, rules["stale_days"]) if latest else "unknown"
+    latest_str = latest.isoformat() if latest else None
+
+    if all(r.get("tier") == "fallback" for r in usable):
+        return {"status": "fallback", "freshness": freshness, "latest": latest_str,
+                "count": len(usable), "quality_min": None, "flags": []}
+
+    scores = [r["quality_score"] for r in usable if r.get("quality_score") is not None]
+    quality_min = min(scores) if scores else None
+    flags = []
+    for r in usable:
+        wf = r.get("flags")
+        if isinstance(wf, list):
+            flags.extend(wf)
+        elif isinstance(wf, str) and wf:
+            flags.append(wf)
+    flags = sorted(set(flags))
+
+    review_quality = any(r.get("quality") == "review" for r in usable)
+    has_quality_issue = (
+        (quality_min is not None and quality_min < rules["quality_threshold"])
+        or bool(flags)
+        or review_quality
+    )
+
+    if len(usable) < rules["min_records"]:
+        status = "quality_warning"
+    elif has_quality_issue:
+        status = "quality_warning"
+    else:
+        status = "available"
+
+    return {"status": status, "freshness": freshness, "latest": latest_str,
+            "count": len(usable), "quality_min": quality_min, "flags": flags}
+
+
+def derive_allowed_actions(primary_status, supporting_present=False, forbidden_actions=None):
+    summarize = primary_status in ("available", "quality_warning", "fallback") or supporting_present
+    compare = primary_status in ("available", "quality_warning")
+    actions = {"summarize": summarize, "compare": compare}
+    for a in (forbidden_actions or []):
+        actions[a] = False
+    return actions
+
+
+def evidence_gate(records=None, supporting=None, rules=None):
+    """records + rules -> {status, freshness, allowed_actions, warnings, caveats}."""
+    if not rules:
+        raise ValueError("evidence_gate: `rules` (a preset) is required")
+
+    primary = classify_status(records or [], rules)
+    supporting_present = bool(supporting or [])
+    allowed = derive_allowed_actions(primary["status"], supporting_present, rules.get("forbidden_actions"))
+
+    warnings = []
+    m = rules.get("messages", {})
+    label = rules.get("primary_label", "primary data")
+    st = primary["status"]
+    if st == "missing":
+        warnings.append({"level": "block", "code": "primary_missing",
+                         "message": m.get("primary_missing", f"No {label} available — the AI must not invent numbers.")})
+    elif st == "fallback":
+        warnings.append({"level": "review", "code": "primary_fallback",
+                         "message": m.get("primary_fallback", f"{label} is cached/fallback, not authoritative — the AI must say so.")})
+    elif st == "quality_warning":
+        warnings.append({"level": "review", "code": "primary_quality",
+                         "message": m.get("primary_quality", f"{label} has a data-quality warning — the AI must add a caveat.")})
+    if primary["freshness"] == "stale":
+        warnings.append({"level": "review", "code": "primary_stale",
+                         "message": m.get("primary_stale", f'{label} is stale (older than {rules["stale_days"]} days) — the AI must not say "latest" or "today".')})
+    if not supporting_present:
+        warnings.append({"level": "info", "code": "no_supporting",
+                         "message": m.get("no_supporting", "No supporting evidence — primary source only.")})
+
+    return {"status": st, "freshness": primary["freshness"], "allowed_actions": allowed,
+            "warnings": warnings, "caveats": [w["message"] for w in warnings]}

evidence_gate_py-0.1.0/evidence_gate/presets.py

@@ -0,0 +1,25 @@
+"""Evidence Gate — example presets. A vertical is just a ruleset."""
+
+FINANCE = {
+    "primary_label": "financial statements",
+    "stale_days": 135,
+    "min_records": 4,
+    "quality_threshold": 70,
+    "forbidden_actions": ["personalized_advice", "claim_realtime"],
+}
+
+HEALTH = {
+    "primary_label": "lab results",
+    "stale_days": 90,
+    "min_records": 2,
+    "quality_threshold": 80,
+    "forbidden_actions": ["diagnose", "prescribe", "claim_realtime"],
+}
+
+SUPPORT = {
+    "primary_label": "knowledge-base documents",
+    "stale_days": 365,
+    "min_records": 1,
+    "quality_threshold": 50,
+    "forbidden_actions": ["make_promises", "claim_realtime"],
+}

evidence_gate_py-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "evidence-gate-py"
+version = "0.1.0"
+description = "Stop your AI from making up facts about your own data."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["llm", "rag", "ai", "agents", "guardrails", "hallucination", "grounding", "reliability"]
+authors = [{ name = "LopezDray" }]
+
+[project.urls]
+Homepage = "https://github.com/LopezDray/evidence-gate"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["evidence_gate"]

evidence_gate_py-0.1.0/tests/test_core.py

@@ -0,0 +1,53 @@
+"""Evidence Gate — core tests: python -m pytest  (or: python tests/test_core.py)"""
+import os
+import sys
+from datetime import date, timedelta
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from evidence_gate.core import classify_status, derive_allowed_actions, evidence_gate
+from evidence_gate.presets import FINANCE, HEALTH
+
+
+def iso(days_ago):
+    return (date.today() - timedelta(days=days_ago)).isoformat()
+
+
+def rec(q, days_ago, **extra):
+    return {"date": iso(days_ago), "quality_score": q, **extra}
+
+
+def test_classify():
+    assert classify_status([rec(95, 5)] * 4, FINANCE)["status"] == "available"
+    assert classify_status([rec(95, 5)] * 2, FINANCE)["status"] == "quality_warning"
+    assert classify_status([rec(95, 5), rec(95, 5), rec(95, 5), rec(40, 5)], FINANCE)["status"] == "quality_warning"
+    assert classify_status([], FINANCE)["status"] == "missing"
+    assert classify_status([rec(95, 5, tier="fallback")] * 2, FINANCE)["status"] == "fallback"
+    assert classify_status([rec(95, 200)] * 4, FINANCE)["freshness"] == "stale"
+
+
+def test_allowed_actions():
+    a = derive_allowed_actions("available", forbidden_actions=["personalized_advice"])
+    assert a["summarize"] and a["compare"] and a["personalized_advice"] is False
+    assert derive_allowed_actions("missing")["summarize"] is False
+    assert derive_allowed_actions("missing", supporting_present=True)["summarize"] is True
+
+
+def test_date_validation():
+    from evidence_gate.core import parse_date
+    assert parse_date(None) is None
+    assert parse_date("not-a-date") is None
+    assert parse_date("2026-13-01") is None   # impossible month
+    assert parse_date("2026-02-31") is None   # impossible day
+    assert parse_date("2024-02-29") is not None  # valid leap day
+
+
+def test_domain_swap():
+    g = evidence_gate(records=[rec(95, 5), rec(95, 5)], rules=HEALTH)
+    assert g["status"] == "available"
+    assert g["allowed_actions"]["diagnose"] is False
+    assert g["allowed_actions"]["prescribe"] is False
+
+
+if __name__ == "__main__":
+    test_classify(); test_allowed_actions(); test_date_validation(); test_domain_swap()
+    print("all tests passed")