meshctx-ctxkit 0.1.0__py3-none-any.whl

meshctx_ctxkit/__init__.py

@@ -0,0 +1,17 @@
+"""ctxkit — local-first context kit for agents.
+
+Two products in one MCP server:
+
+1. ``memory``  — cross-session memory on local disk. Survives restarts,
+   never leaves the machine. No account, no cloud.
+2. ``consensus`` — the same question asked across multiple models, then
+   scored for agreement. Catches hallucinations that a single model
+   would confidently hand you.
+
+Everything degrades gracefully: with no API key and no browser it still
+runs (memory works fully offline; consensus returns a clear, actionable
+error instead of crashing).
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

meshctx_ctxkit/__main__.py

@@ -0,0 +1,72 @@
+"""CLI: ``ctxkit`` command line interface.
+
+    ctxkit add "fact text" --tag project/alpha
+    ctxkit search "query" [--limit 5]
+    ctxkit stats
+    ctxkit verify "text to check"
+    ctxkit serve           # run the MCP stdio server
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .memory import MemoryStore
+from .consensus import run_offline_checks
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="ctxkit",
+                                 description="local-first memory + verification for agents")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_add = sub.add_parser("add", help="store a memory")
+    p_add.add_argument("text")
+    p_add.add_argument("--tag", action="append", default=[])
+
+    p_search = sub.add_parser("search", help="search memories")
+    p_search.add_argument("query")
+    p_search.add_argument("--limit", type=int, default=5)
+
+    sub.add_parser("stats", help="store stats")
+
+    p_verify = sub.add_parser("verify", help="offline sanity checks on text")
+    p_verify.add_argument("text")
+
+    p_lic = sub.add_parser("license", help="show license tier, expiry and usage")
+    p_lic.add_argument("--key", help="verify a specific license token instead of the stored one")
+
+    sub.add_parser("serve", help="run MCP stdio server")
+
+    args = ap.parse_args(argv)
+    if args.cmd == "serve":
+        from .server import main as serve_main
+        serve_main()
+        return 0
+    store = MemoryStore()
+    if args.cmd == "license":
+        from .license import load_license_from_env, verify_license
+        from .usage import UsageMeter
+        lic = verify_license(args.key) if args.key else load_license_from_env()
+        out = lic.to_dict()
+        out["usage"] = UsageMeter(store.path.parent).snapshot()
+        out["free_tools"] = ["ctx_remember", "ctx_recall", "ctx_forget",
+                             "ctx_stats", "ctx_verify_text"]
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+        return 0
+    if args.cmd == "add":
+        mem = store.remember(args.text, tags=args.tag)
+        print(json.dumps({"ok": True, "id": mem.id}, ensure_ascii=False))
+    elif args.cmd == "search":
+        print(json.dumps({"hits": store.recall(args.query, args.limit)},
+                         ensure_ascii=False, indent=2))
+    elif args.cmd == "stats":
+        print(json.dumps(store.stats(), ensure_ascii=False, indent=2))
+    elif args.cmd == "verify":
+        print(json.dumps(run_offline_checks(args.text), ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

meshctx_ctxkit/consensus.py

@@ -0,0 +1,314 @@
+"""Verification & multi-model consensus for ctxkit.
+
+Two layers:
+
+``run_offline_checks(text)``
+    Pure-stdlib sanity checks that catch the most common LLM failure
+    modes without any network: broken arithmetic, impossible dates,
+    unreachable-looking URLs, and unqualified absolute claims.
+
+``multi_model_consensus(question, ...)``
+    Ask the same question to N OpenAI-compatible endpoints, extract
+    each model's key claims, and score cross-model agreement. This is
+    the paid/hosted path (``ctxkit[api]`` + ``CTXKIT_API_KEY``); it is
+    optional and the server never requires it.
+
+The offline layer is the free product core; the consensus layer is the
+commercial add-on. Both are honest about what they cannot do: they flag
+suspicion, they do not prove truth.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import statistics
+from dataclasses import dataclass, field, asdict
+from typing import Any, Callable
+
+# ── offline checks ─────────────────────────────────────────────────────
+
+_NUM = r"\d[\d,]*(?:\.\d+)?"
+_ARITH_RE = re.compile(
+    rf"({_NUM})\s*([+\-*/×x÷])\s*({_NUM})\s*=\s*({_NUM})", re.IGNORECASE
+)
+_WORD_ARITH_RE = re.compile(
+    r"({num})\s*(plus|minus|times|multiplied by|divided by)\s*({num})\s*"
+    r"(?:is|equals|=)\s*({num})".format(num=_NUM),
+    re.IGNORECASE,
+)
+_PCT_RE = re.compile(
+    rf"({_NUM})\s*%\s*of\s*({_NUM})\s*(?:is|equals|=)\s*({_NUM})", re.IGNORECASE
+)
+_YEAR_RE = re.compile(r"\b((?:18|19|20|21)\d{2})\b")
+_MD_DATE_RE = re.compile(
+    r"\b(January|February|March|April|May|June|July|August|September|October|"
+    r"November|December)\s+(\d{1,2})(?:st|nd|rd|th)?\b,?\s*((?:18|19|20|21)\d{2})?",
+    re.IGNORECASE,
+)
+_URL_RE = re.compile(r"https?://[^\s<>\"')\]]+", re.IGNORECASE)
+_ABSOLUTE_RE = re.compile(
+    r"\b(always|never|100%|guaranteed|impossible|everyone|nobody|"
+    r"all users|zero risk|risk[- ]free|completely safe)\b",
+    re.IGNORECASE,
+)
+_MONTH_DAYS = {
+    "january": 31, "february": 29, "march": 31, "april": 30, "may": 31,
+    "june": 30, "july": 31, "august": 31, "september": 30, "october": 31,
+    "november": 30, "december": 31,
+}
+_OPS = {"+": 1, "-": 1, "*": 1, "/": 1, "×": 1, "x": 1, "÷": 1,
+        "plus": 1, "minus": 1, "times": 1, "multiplied by": 1, "divided by": 1}
+
+
+def _num(s: str) -> float:
+    return float(s.replace(",", ""))
+
+
+def _fmt(x: float) -> str:
+    return f"{x:.6f}".rstrip("0").rstrip(".")
+
+
+@dataclass
+class CheckResult:
+    name: str
+    passed: bool
+    detail: str
+
+
+def arithmetic_check(text: str) -> list[CheckResult]:
+    """Recompute every ``a op b = c`` pattern stated in the text."""
+    out: list[CheckResult] = []
+    for a, op, b, c in _ARITH_RE.findall(text):
+        try:
+            x, y, z = _num(a), _num(b), _num(c)
+            got = {"+": x + y, "-": x - y, "*": x * y, "×": x * y, "x": x * y,
+                   "/": x / y if y else float("inf"), "÷": x / y if y else float("inf")}[op.lower() if op.lower() in ("x",) else op]
+        except Exception:
+            continue
+        ok = abs(got - z) < 1e-6 * max(1.0, abs(z))
+        out.append(CheckResult(
+            "arithmetic", ok,
+            f'"{a} {op} {b} = {c}" — computed {_fmt(got)}'
+            + ("" if ok else f", text says {c}")))
+    for a, op, b, c in _WORD_ARITH_RE.findall(text):
+        try:
+            x, y, z = _num(a), _num(b), _num(c)
+            got = {"plus": x + y, "minus": x - y, "times": x * y,
+                   "multiplied by": x * y,
+                   "divided by": x / y if y else float("inf")}[op.lower()]
+        except Exception:
+            continue
+        ok = abs(got - z) < 1e-6 * max(1.0, abs(z))
+        out.append(CheckResult(
+            "arithmetic", ok,
+            f'"{a} {op} {b} = {c}" — computed {_fmt(got)}'
+            + ("" if ok else f", text says {c}")))
+    return out
+
+
+def percent_check(text: str) -> list[CheckResult]:
+    out: list[CheckResult] = []
+    for p, base, claimed in _PCT_RE.findall(text):
+        try:
+            got = _num(base) * _num(p) / 100.0
+        except Exception:
+            continue
+        ok = abs(got - _num(claimed)) < 1e-6 * max(1.0, abs(got))
+        out.append(CheckResult(
+            "percent", ok,
+            f'"{p}% of {base} = {claimed}" — computed {_fmt(got)}'
+            + ("" if ok else f", text says {claimed}")))
+    return out
+
+
+def date_check(text: str, *, now_year: int | None = None) -> list[CheckResult]:
+    import datetime
+    this_year = now_year or datetime.date.today().year
+    out: list[CheckResult] = []
+    for year in _YEAR_RE.findall(text):
+        y = int(year)
+        if y > this_year + 2:
+            out.append(CheckResult(
+                "date", False,
+                f"year {y} is more than 2 years in the future "
+                f"(current {this_year}) — likely a hallucinated date"))
+    for month, day, year in _MD_DATE_RE.findall(text):
+        d = int(day)
+        max_d = _MONTH_DAYS[month.lower()]
+        if d > max_d:
+            out.append(CheckResult(
+                "date", False,
+                f'"{month} {day}" does not exist ({month} has {max_d} days)'))
+    return out
+
+
+def absolute_claim_check(text: str) -> list[CheckResult]:
+    hits = sorted({m.group(0).lower() for m in _ABSOLUTE_RE.finditer(text)})
+    if not hits:
+        return [CheckResult("absolute_claims", True, "no unqualified absolutes found")]
+    return [CheckResult(
+        "absolute_claims", False,
+        "unqualified absolutes (verify or hedge these): " + ", ".join(hits))]
+
+
+def url_check(text: str) -> list[CheckResult]:
+    urls = _URL_RE.findall(text)
+    if not urls:
+        return []
+    suspicious = [u for u in urls
+                  if u.endswith((".png", ".jpg", ".pdf")) and "arxiv" not in u]
+    ok = not suspicious
+    return [CheckResult(
+        "url_format", ok,
+        f"{len(urls)} URL(s) found" + (f"; suspicious: {suspicious}" if suspicious else ""))]
+
+
+def run_offline_checks(text: str) -> dict[str, Any]:
+    checks = (arithmetic_check(text) + percent_check(text)
+              + date_check(text) + absolute_claim_check(text) + url_check(text))
+    failed = [c for c in checks if not c.passed]
+    return {
+        "verdict": "suspicious" if failed else "clean",
+        "n_checks": len(checks),
+        "failed": [asdict(c) for c in failed],
+        "passed": [asdict(c) for c in checks if c.passed],
+    }
+
+
+# ── multi-model consensus (optional, hosted) ──────────────────────────
+
+_STOP = {"the", "a", "an", "of", "is", "are", "was", "were", "to", "in",
+         "on", "for", "and", "or", "that", "this", "it", "with", "as", "by"}
+
+
+def _norm_claim(s: str) -> frozenset[str]:
+    words = re.findall(r"[a-z0-9]+", s.lower())
+    return frozenset(w for w in words if w not in _STOP)
+
+
+def claim_similarity(a: str, b: str) -> float:
+    sa, sb = _norm_claim(a), _norm_claim(b)
+    if not sa or not sb:
+        return 0.0
+    return len(sa & sb) / len(sa | sb)
+
+
+def extract_claims(answer: str) -> list[str]:
+    """Ask-format helper: models are instructed to end with a JSON array of
+    claims; pull it out, falling back to sentence split."""
+    m = re.search(r"\[\s*\".*\"\s*\]", answer, re.DOTALL)
+    if m:
+        try:
+            arr = json.loads(m.group(0))
+            if isinstance(arr, list) and arr and all(isinstance(x, str) for x in arr):
+                return arr
+        except json.JSONDecodeError:
+            pass
+    sents = re.split(r"(?<=[.!?])\s+", answer.strip())
+    return [s for s in sents if len(s.split()) >= 4][:8]
+
+
+@dataclass
+class ConsensusReport:
+    question: str
+    models: list[str]
+    verdict: str                      # high | medium | low | error
+    agreement_score: float            # 0..1
+    shared_claims: list[str] = field(default_factory=list)
+    outlier_claims: dict[str, list[str]] = field(default_factory=dict)
+    per_model: dict[str, str] = field(default_factory=dict)
+    notes: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def score_consensus(question: str, answers: dict[str, str],
+                    threshold: float = 0.45) -> ConsensusReport:
+    """Pure scoring — injectable and testable without any network."""
+    models = list(answers)
+    if len(models) < 2:
+        return ConsensusReport(question, models, "error", 0.0, notes=[
+            "consensus needs >= 2 model answers"])
+    claim_sets = {m: extract_claims(a) for m, a in answers.items()}
+    shared: list[str] = []
+    outliers: dict[str, list[str]] = {m: [] for m in models}
+    pair_scores: list[float] = []
+    matched: set[tuple[int, int]] = set()
+    for m in models:
+        for claim in claim_sets[m]:
+            hit = False
+            for n in models:
+                if n == m:
+                    continue
+                for i, c2 in enumerate(claim_sets[n]):
+                    if claim_similarity(claim, c2) >= threshold:
+                        pair_scores.append(claim_similarity(claim, c2))
+                        matched.add((models.index(m), models.index(n)))
+                        hit = True
+                        break
+                if hit:
+                    break
+            if hit and claim not in shared:
+                shared.append(claim)
+            elif not hit:
+                outliers[m].append(claim)
+    n_pairs = len(models) * (len(models) - 1)
+    coverage = len({(i, j) for i, j in matched}) / n_pairs if n_pairs else 0.0
+    avg_sim = statistics.mean(pair_scores) if pair_scores else 0.0
+    score = round(0.6 * coverage + 0.4 * avg_sim, 3)
+    verdict = "high" if score >= 0.7 else ("medium" if score >= 0.4 else "low")
+    return ConsensusReport(question, models, verdict, score,
+                           shared_claims=shared[:10],
+                           outlier_claims={m: v[:5] for m, v in outliers.items() if v},
+                           per_model={m: a[:400] for m, a in answers.items()},
+                           notes=["lexical claim matching; threshold "
+                                  f"{threshold} — flags suspicion, does not prove truth"])
+
+
+CONSENSUS_PROMPT = (
+    "Answer the question below. After your answer, append a line "
+    "'CLAIMS:' followed by a JSON array of 3-7 short factual claims "
+    "your answer depends on.\n\nQuestion: {q}"
+)
+
+
+def default_http_transport(model: str, prompt: str, timeout: float) -> str:
+    """OpenAI-compatible chat completion. Requires httpx + env config:
+    CTXKIT_API_BASE, CTXKIT_API_KEY. The model name is passed through."""
+    import httpx  # optional extra
+    base = os.environ.get("CTXKIT_API_BASE", "").rstrip("/")
+    key = os.environ.get("CTXKIT_API_KEY", "")
+    if not base or not key:
+        raise RuntimeError("CTXKIT_API_BASE / CTXKIT_API_KEY not configured")
+    r = httpx.post(
+        f"{base}/chat/completions",
+        headers={"Authorization": f"Bearer {key}"},
+        json={"model": model, "messages": [{"role": "user", "content": prompt}],
+              "temperature": 0.2},
+        timeout=timeout,
+    )
+    r.raise_for_status()
+    return r.json()["choices"][0]["message"]["content"]
+
+
+def multi_model_consensus(question: str, models: list[str],
+                          transport: Callable[[str, str, float], str] | None = None,
+                          timeout: float = 120.0) -> dict[str, Any]:
+    transport = transport or default_http_transport
+    prompt = CONSENSUS_PROMPT.format(q=question)
+    answers: dict[str, str] = {}
+    errors: dict[str, str] = {}
+    for m in models:
+        try:
+            answers[m] = transport(m, prompt, timeout)
+        except Exception as e:  # one model failing must not kill the report
+            errors[m] = str(e)[:200]
+    if len(answers) < 2:
+        return {"verdict": "error", "question": question,
+                "errors": errors,
+                "notes": ["need >= 2 successful model calls for consensus"]}
+    report = score_consensus(question, answers)
+    report.notes.append(f"model errors: {errors}" if errors else "all models answered")
+    return report.to_dict()

meshctx_ctxkit/license.py

@@ -0,0 +1,179 @@
+"""License checking for ctxkit's paid tier.
+
+Design constraint that drives everything here: **the license must verify
+offline.** A user who paid should not be locked out because our licence
+server is down, and we should not be running a phone-home endpoint that
+sees every user's usage.
+
+So licenses are Ed25519-signed tokens (JWT, ``EdDSA``):
+  - private key lives only on the server (never shipped)
+  - public key is baked into the package
+  - the client verifies the signature locally, against the expiry
+
+This module is intentionally dependency-light: it uses ``PyJWT[crypto]``
+when available, and falls back to a clear error when it is not. Memory and
+verification (the free tier) never touch this module at all.
+"""
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+Tier = Literal["free", "pro", "team"]
+
+# Public key shipped with the client. Replace with the real one when the
+# Stripe setup is live (see billing/README.md). The placeholder is refused
+# explicitly rather than silently trusting anything.
+# The public key baked into the package at build time. This is the key the
+# billing service signs licences with.
+BUILTIN_PUBLIC_KEY = """-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAsnFCGUPdXj1osPhWOsdxNj8ngmaMciTksQP2h86hmw8=
+-----END PUBLIC KEY-----"""
+
+
+def _resolve_public_key() -> str:
+    """Return the public key to verify against.
+
+    Reads ``CTXKIT_LICENSE_PUBKEY`` at *call* time rather than import time.
+    Resolving it at import made the override silently useless for anyone who
+    exported the variable after the module was already imported (e.g. from a
+    test or a wrapper script) — the override looked supported but did nothing.
+    """
+    return os.environ.get("CTXKIT_LICENSE_PUBKEY") or BUILTIN_PUBLIC_KEY
+
+
+# Kept for backwards compatibility with anything importing the old name.
+PUBLIC_KEY_PEM = BUILTIN_PUBLIC_KEY
+
+_PLACEHOLDER = "PLACEHOLDER_REPLACE_ME"
+
+# Free tier never expires and needs no token.
+FREE = "free"
+
+QUOTAS: dict[Tier, dict[str, Any]] = {
+    "free":  {"consensus_per_month": 0,    "email_support": False, "managed_keys": False, "seats": 1},
+    "pro":   {"consensus_per_month": 300,  "email_support": True,  "managed_keys": False, "seats": 1},
+    "team":  {"consensus_per_month": 3000, "email_support": True,  "managed_keys": True,  "seats": 5},
+}
+
+
+@dataclass
+class License:
+    tier: Tier = "free"
+    email: str = ""
+    exp: int = 0                       # unix ts; 0 = never (free)
+    seats: int = 1
+    managed_keys: bool = False
+    claims: dict[str, Any] = field(default_factory=dict)
+    reason: str = ""                   # why the license isn't active, if so
+
+    @property
+    def active(self) -> bool:
+        return self.tier != "free" and (self.exp == 0 or self.exp > time.time())
+
+    @property
+    def consensus_quota(self) -> int:
+        return QUOTAS[self.tier]["consensus_per_month"]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "tier": self.tier,
+            "active": self.active,
+            "email": self.email,
+            "expires": self.exp,
+            "expires_human": (time.strftime("%Y-%m-%d %H:%M UTC", time.gmtime(self.exp))
+                              if self.exp else "never"),
+            "seats": self.seats,
+            "managed_keys": self.managed_keys,
+            "consensus_quota": self.consensus_quota,
+            "reason": self.reason,
+        }
+
+
+def _jwt():
+    try:
+        import jwt  # type: ignore
+        return jwt
+    except ImportError:  # pragma: no cover - optional dependency path
+        return None
+
+
+def verify_license(token: str | None, public_key: str | None = None,
+                   *, now: float | None = None) -> License:
+    """Verify a license token locally. Never raises; returns a License with
+    ``reason`` set if anything is off."""
+    if not token:
+        return License(tier="free", reason="no token (free tier)")
+    jwt = _jwt()
+    if jwt is None:
+        return License(tier="free", reason=(
+                "licence verification needs PyJWT: "
+                "pip install 'meshctx-ctxkit[license]'"))
+    key = public_key or _resolve_public_key()
+    if _PLACEHOLDER in key:
+        return License(tier="free",
+                       reason="license public key not configured in this build")
+    try:
+        # EdDSA only. Rejecting HS256/RS256 prevents the classic
+        # "alg: none" and public-key-as-HMAC-secret downgrade attacks.
+        claims = jwt.decode(token, key, algorithms=["EdDSA"],
+                            options={"require": ["tier", "exp"]})
+    except Exception as e:
+        return License(tier="free", reason=f"invalid license: {type(e).__name__}: {e}")
+
+    tier = claims.get("tier", "free")
+    if tier not in QUOTAS:
+        return License(tier="free", reason=f"unknown tier: {tier}")
+    exp = int(claims.get("exp") or 0)
+    lic = License(
+        tier=tier,
+        email=claims.get("email", ""),
+        exp=exp,
+        seats=int(claims.get("seats") or QUOTAS[tier]["seats"]),
+        managed_keys=bool(claims.get("managed_keys",
+                                     QUOTAS[tier]["managed_keys"])),
+        claims=claims,
+    )
+    if now is not None and exp and exp <= now:
+        lic.tier = "free"
+        lic.reason = f"license expired on {time.strftime('%Y-%m-%d', time.gmtime(exp))}"
+    return lic
+
+
+def load_license_from_env(public_key: str | None = None) -> License:
+    """Read CTXKIT_LICENSE, or ~/.ctxkit/license.key if the env var is unset."""
+    token = os.environ.get("CTXKIT_LICENSE", "").strip()
+    if not token:
+        path = os.path.join(os.environ.get("CTXKIT_HOME") or 
+                            os.path.join(os.path.expanduser("~"), ".ctxkit"),
+                            "license.key")
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                token = fh.read().strip()
+        except OSError:
+            token = ""
+    return verify_license(token, public_key)
+
+
+def sign_license(private_key_pem: str, *, tier: Tier, email: str,
+                 days: int = 30, seats: int | None = None,
+                 managed_keys: bool | None = None) -> str:
+    """Server-side only. Produces the token we email to a paying customer."""
+    jwt = _jwt()
+    if jwt is None:
+        raise RuntimeError("PyJWT required on the signing side: pip install pyjwt[crypto]")
+    now = int(time.time())
+    claims: dict[str, Any] = {
+        "tier": tier,
+        "email": email,
+        "iat": now,
+        "exp": now + days * 86400,
+        "iss": "ctxkit-billing",
+    }
+    if seats is not None:
+        claims["seats"] = seats
+    if managed_keys is not None:
+        claims["managed_keys"] = managed_keys
+    return jwt.encode(claims, private_key_pem, algorithm="EdDSA")