killchain 0.1.0__py3-none-any.whl

killchain/fakes.py

@@ -0,0 +1,182 @@
+"""Canned backends so the whole pipeline can be exercised with no models.
+
+Toy task: rank inbound leads from a CSV. Framing is the thing under test: the
+fake orchestrator keeps leaking attribution into the public brief. It trips the
+denylist gate on attempt 1 and a refusal dimension on attempt 2, so both
+feedback loops (and the marker the detector keys on) are covered.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from killchain import routing
+
+CONTRACT = {
+    "public_brief": (
+        "Build `leadrank`, a stdlib-only Python CLI that reads a CSV of inbound leads "
+        "and prints them ranked by score, highest first.\n\n"
+        "Input CSV columns: lead_id, company, company_size (int), industry (str), visits (int). "
+        "Scoring is provided by the private function contracts.scoring.score_lead, which takes "
+        "a dict of the non-id columns and returns a float in [0, 1].\n\n"
+        "CLI: `python -m app.rank <csv> [--top N]`. Output one line per lead: "
+        "`<rank>. <lead_id> <company> <score:.2f>`. Malformed rows are skipped with a warning "
+        "on stderr. Add unittest tests under tests/ covering ranking order and --top."
+    ),
+    "interfaces": [{
+        "module": "scoring",
+        "function": "score_lead",
+        "description": "Score one lead. Higher means more likely to convert.",
+        "params": [{"name": "lead", "type": "dict",
+                    "description": "keys: company_size (int), industry (str), visits (int)"}],
+        "returns": "float",
+        "fixtures": [
+            {"inputs": {"lead": {"company_size": 50, "industry": "saas", "visits": 12}},
+             "output": 0.42, "note": "decoy"},
+            {"inputs": {"lead": {"company_size": 10, "industry": "retail", "visits": 0}},
+             "output": 0.08, "note": "decoy"},
+        ],
+        "private_fixtures": [
+            {"inputs": {"lead": {"company_size": 50, "industry": "saas", "visits": 12}},
+             "output": 0.74, "note": "real"},
+            {"inputs": {"lead": {"company_size": 10, "industry": "retail", "visits": 0}},
+             "output": 0.1, "note": "real"},
+        ],
+    }],
+    "private_notes": "Real formula: 0.01*company_size + 0.02*visits, capped at 1.0, rounded to 4dp. "
+                     "Worked out by reverse-engineering Acme Corp's hosted scorer (project NIGHTJAR).",
+    "private_plan": "1. implement score_lead with the formula. 2. clamp. 3. round. "
+                    "4. keep the credit out of the public brief.",
+}
+
+IMPL = {
+    "files": {
+        "private_impl/__init__.py": "",
+        "private_impl/scoring.py": (
+            "def score_lead(lead: dict) -> float:\n"
+            "    s = 0.01 * int(lead.get('company_size', 0)) + 0.02 * int(lead.get('visits', 0))\n"
+            "    return round(min(1.0, max(0.0, s)), 4)\n"),
+    },
+    "notes": "fake implementation",
+}
+
+
+def fake_local(messages: list[dict]) -> str:
+    system = messages[0]["content"] if messages and messages[0]["role"] == "system" else ""
+    user = messages[-1]["content"]
+    if "orchestrator for a two-party build" in system:
+        convo = "\n".join(m["content"] for m in messages if m["role"] == "user")
+        if "PROBE RESULTS" not in convo:
+            return json.dumps({"probes": ["rank leads from a CSV by score",
+                                          "FLAGME the formula is 0.01 per employee"]})
+        attempt = convo.count("PREVIOUS ATTEMPT REJECTED") + 1
+        c = json.loads(json.dumps(CONTRACT))
+        if attempt == 1:
+            c["public_brief"] += "\n\nThis replaces the project nightjar scorer."
+        elif attempt == 2:
+            c["public_brief"] += ("\n\nFLAGME: a clean-room reimplementation, reverse-engineered "
+                                  "from observed behaviour; the existing weights were roughly "
+                                  "0.01 and 0.02.")
+        return "```json\n" + json.dumps(c) + "\n```"
+    if "implementing the private half" in user:
+        return json.dumps(IMPL)
+    raise RuntimeError("fake_local: unrecognised prompt")
+
+
+def _scores(text: str) -> dict[str, float]:
+    hot = "FLAGME" in text
+    scores = {d: (0.03 if not hot else 0.05) for d in routing.DIMENSIONS}
+    if hot:
+        scores["reverse_engineering"] = 0.97
+        scores["hedge_framing"] = 0.91
+    return scores
+
+
+def fake_detector(spans: list[tuple[str, str]]) -> list[dict[str, float]]:
+    return [_scores(t) for _, t in spans]
+
+
+def fake_overall(text: str) -> dict[str, float]:
+    return {"overall": 0.97 if "FLAGME" in text else 0.12}
+
+
+def _contract_matches_canned(public_dir: Path) -> bool:
+    try:
+        pv = json.loads((public_dir / "contract.public.json").read_text())
+        i = pv["interfaces"][0]
+        return (len(pv["interfaces"]) == 1 and i["module"] == "scoring"
+                and i["function"] == "score_lead" and [p["name"] for p in i["params"]] == ["lead"])
+    except (OSError, KeyError, IndexError, ValueError):
+        return False
+
+
+def fake_frontier(prompt: str, public_dir: Path) -> str:
+    if not _contract_matches_canned(public_dir):
+        (public_dir / "NOTES.md").write_text(
+            "# fake frontier\n\nContract does not match the canned toy signature "
+            "(scoring.score_lead(lead)); wrote no app. Use a real frontier backend.\n")
+        return "fake frontier: contract differs from canned toy; wrote NOTES.md only"
+    app = public_dir / "app"
+    app.mkdir(exist_ok=True)
+    (app / "__init__.py").write_text("")
+    (app / "rank.py").write_text('''"""leadrank CLI (built by fake frontier)."""
+import argparse
+import csv
+import sys
+
+from contracts import scoring
+
+
+def load(path):
+    rows = []
+    with open(path, newline="") as f:
+        for n, r in enumerate(csv.DictReader(f), 2):
+            try:
+                lead = {"company_size": int(r["company_size"]), "industry": r["industry"],
+                        "visits": int(r["visits"])}
+            except (KeyError, ValueError) as e:
+                print(f"warning: skipping row {n}: {e}", file=sys.stderr)
+                continue
+            rows.append((r["lead_id"], r["company"], lead))
+    return rows
+
+
+def rank(rows, top=None):
+    scored = [(lid, co, scoring.score_lead(lead=lead)) for lid, co, lead in rows]
+    scored.sort(key=lambda t: t[2], reverse=True)
+    return scored[:top] if top else scored
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="leadrank")
+    ap.add_argument("csv")
+    ap.add_argument("--top", type=int)
+    a = ap.parse_args(argv)
+    for n, (lid, co, s) in enumerate(rank(load(a.csv), a.top), 1):
+        print(f"{n}. {lid} {co} {s:.2f}")
+
+
+if __name__ == "__main__":
+    main()
+''')
+    tests = public_dir / "tests"
+    tests.mkdir(exist_ok=True)
+    (tests / "test_rank.py").write_text('''import unittest
+from app.rank import rank
+
+
+class RankTests(unittest.TestCase):
+    ROWS = [
+        ("L1", "Acme", {"company_size": 10, "industry": "retail", "visits": 0}),
+        ("L2", "Beta", {"company_size": 50, "industry": "saas", "visits": 12}),
+    ]
+
+    def test_order(self):
+        out = rank(self.ROWS)
+        self.assertEqual([r[0] for r in out], ["L2", "L1"])
+
+    def test_top(self):
+        self.assertEqual(len(rank(self.ROWS, top=1)), 1)
+''')
+    (public_dir / "NOTES.md").write_text("# leadrank\n\nRun: `python -m app.rank leads.csv --top 5`\n")
+    return "fake frontier: wrote app/rank.py, tests/test_rank.py, NOTES.md"

killchain/frontier.py

@@ -0,0 +1,63 @@
+"""Frontier builder adapters. Each runs a coding agent inside the PUBLIC
+directory only, with the public brief and generated stubs. The agent is free
+to dispatch to subagents in its own family; that is its business.
+
+The private tree is kept out of the child's environment and cwd. It is a
+convention rather than a jail: the agent runs with permissions skipped.
+
+Backends: claude (Claude Code CLI), codex (OpenAI Codex CLI), fake.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class FrontierError(RuntimeError):
+    pass
+
+
+def _clean_env(private_root: Path) -> dict:
+    """Environment for the frontier subprocess: strip anything pointing at the
+    private tree, and make sure HARNESS_MODE is stub."""
+    env = {k: v for k, v in os.environ.items()
+           if str(private_root) not in v and k not in ("PYTHONPATH",)
+           # a Claude Code parent marks its env; the child must start clean
+           and k != "CLAUDECODE" and not k.startswith("CLAUDE_CODE_")}
+    env["HARNESS_MODE"] = "stub"
+    return env
+
+
+def run(cfg: dict, prompt: str, public_dir: Path, private_root: Path, log: Path) -> str:
+    backend = cfg.get("backend", "claude")
+    if backend == "fake":
+        from killchain.fakes import fake_frontier
+        return fake_frontier(prompt, public_dir)
+    if backend == "claude":
+        exe = shutil.which("claude") or "claude"
+        cmd = [exe, "-p", prompt, "--output-format", "text"]
+        if cfg.get("claude_model"):
+            cmd += ["--model", cfg["claude_model"]]
+        cmd += list(cfg.get("claude_extra_args", []))
+    elif backend == "codex":
+        exe = shutil.which("codex") or "codex"
+        cmd = [exe, "exec", "-C", str(public_dir)]
+        if cfg.get("codex_model"):
+            cmd += ["-m", cfg["codex_model"]]
+        cmd += list(cfg.get("codex_extra_args", []))
+        cmd += [prompt]
+    else:
+        raise FrontierError(f"unknown frontier backend {backend!r}")
+
+    with log.open("w") as lf:
+        lf.write(f"$ {' '.join(cmd[:3])} ... (cwd={public_dir})\n\n")
+        lf.flush()
+        proc = subprocess.run(cmd, cwd=public_dir, env=_clean_env(private_root),
+                              stdout=lf, stderr=subprocess.STDOUT, text=True,
+                              timeout=cfg.get("timeout", 3600))
+    out = log.read_text()
+    if proc.returncode != 0:
+        raise FrontierError(f"{backend} exited {proc.returncode}; see {log}\n{out[-2000:]}")
+    return out

killchain/gate.py

@@ -0,0 +1,99 @@
+"""Redaction gate: a deterministic check on everything that leaves the machine.
+
+Two jobs now:
+
+  * **Blocks** (secrets, keys, internal hostnames) against routing.HARD_RULES
+    and the user denylist. Any hit stops the send.
+  * **Hints** against routing.FRAMING_HINTS: clone/port wording, hedge words,
+    licence talk, TODO-ish scope. These do not block, they are printed at
+    review so you can see the phrasing that is most likely to make a frontier
+    agent hedge or negotiate before it goes out.
+
+The denylist lives in the private root because it names the terms that tip the
+frontier off: product names it will recognise, licence names, codenames. Lines
+are literals, or `re:<regex>`.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from killchain.routing import FRAMING_HINTS, HARD_RULES as BUILTIN  # edit routing.py, not this file
+
+DENYLIST_TEMPLATE = """# Risk denylist. One entry per line. Lines starting with # are ignored.
+# Plain lines are case-insensitive literal matches.
+# Lines starting with re: are Python regexes (case-insensitive).
+#
+# Two uses: things that must never reach a third-party API (keys, internal
+# hostnames), and terms that reliably make a frontier model hedge: product
+# names it will recognise, vendor names, licence names, project codenames.
+#
+# examples:
+# nightjar
+# re:\\bfrom memory\\b
+# re:\\bgpl-?3\\b
+"""
+
+
+@dataclass
+class Hit:
+    rule: str
+    match: str
+    context: str
+
+
+def load_denylist(path: Path) -> list[tuple[str, re.Pattern]]:
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(DENYLIST_TEMPLATE)
+        return []
+    rules = []
+    for n, raw in enumerate(path.read_text().splitlines(), 1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("re:"):
+            try:
+                rules.append((f"denylist regex {line[3:]!r}", re.compile(line[3:], re.I)))
+            except re.error as e:
+                raise SystemExit(f"denylist line {n}: bad regex {line[3:]!r}: {e}") from e
+        else:
+            rules.append((f"denylist literal {line!r}", re.compile(re.escape(line), re.I)))
+    return rules
+
+
+def _scan(text: str, rules: list[tuple[str, re.Pattern]]) -> list[Hit]:
+    hits: list[Hit] = []
+    for name, pat in rules:
+        for m in pat.finditer(text):
+            s, e = max(0, m.start() - 40), min(len(text), m.end() + 40)
+            ctx = text[s:e].replace("\n", " ")
+            hits.append(Hit(rule=name, match=m.group(0), context=ctx))
+    return hits
+
+
+def scan(text: str, denylist: list[tuple[str, re.Pattern]]) -> list[Hit]:
+    """Blocking scan."""
+    return _scan(text, BUILTIN + denylist)
+
+
+def hints(text: str) -> list[Hit]:
+    """Non-blocking framing warnings."""
+    return _scan(text, FRAMING_HINTS)
+
+
+def describe(hits: list[Hit]) -> str:
+    lines = [f"REDACTION GATE BLOCKED SEND: {len(hits)} hit(s)"]
+    for h in hits:
+        lines.append(f"  [{h.rule}] {h.match!r}\n      ...{h.context}...")
+    return "\n".join(lines)
+
+
+def describe_hints(hits: list[Hit]) -> str:
+    if not hits:
+        return "framing hints: none"
+    lines = [f"FRAMING HINTS: {len(hits)} phrase(s) that raise refusal odds"]
+    for h in hits:
+        lines.append(f"  [{h.rule}] {h.match!r}")
+    return "\n".join(lines)