llm-feedback-control 0.1.0__py3-none-any.whl

llm_feedback_control/__init__.py

@@ -0,0 +1,106 @@
+"""llm-feedback-control — get reliable, checkable structured output from a small
+local language model by wrapping it in ordinary deterministic code.
+
+WHAT IT DOES, concretely
+------------------------
+You hand it a process described in plain English::
+
+    "A claim enters Intake. From Intake it goes to Triage. Triage goes to
+     FastTrack or to Investigation. ..."
+
+and it:
+  1. turns that into a state machine (states + transitions);
+  2. computes *provable* facts about it — which steps are dead ends, whether
+     there are loops, which steps can't be reached;
+  3. writes a report in which every statement is backed by one of those
+     checked facts (so it can't quietly make things up);
+  4. knows its own limits: if the text isn't actually a finite step-by-step
+     process (e.g. "prices drift up as confidence grows"), it REFUSES instead
+     of inventing a fake state machine; and if the model's first pass missed
+     part of the process, it loops to fill the gaps — or refuses if it can't.
+
+WHY "FEEDBACK CONTROL" (the analogy, explained)
+-----------------------------------------------
+The design is borrowed from electronics. A raw LLM is like a very high-gain
+amplifier: hugely powerful, but left to run "open-loop" it overshoots — fluent,
+yet it drifts and hallucinates. Engineers tame such an amplifier by adding a
+*feedback loop*: feed the output back, compare it to a stable reference, and
+trade some raw power for precision and stability. This library is that feedback
+loop for an LLM. The "reference" is plain, deterministic code — graph checks
+and schema rules the model's output is measured against.
+
+Two kinds of feedback, in plain terms:
+
+  - NEGATIVE feedback = the stabilising checks (``run_audit``):
+      * decide first whether the text is even the kind of thing we can analyse
+        exactly, and refuse the fuzzy ones;
+      * force the model's answer into a strict shape (with a no-model fallback);
+      * compute the provable graph facts;
+      * say "I can't do this exactly" rather than guess.
+  - POSITIVE feedback = the gap-filling loop (``extract_iterative``):
+        re-ask the model about anything the text mentions that's missing from
+        its answer, repeating until nothing is missing (a "fixed point") — and
+        refuse if it never settles.
+
+Zero third-party runtime dependencies. The deterministic core runs with no model
+at all; an LLM is a pure upgrade and is fully injectable (pass ``generate=``).
+
+Quickstart (works with no model)::
+
+    from llm_feedback_control import run_audit
+    r = run_audit("A claim enters Intake. From Intake it goes to Triage. "
+                  "Triage goes to FastTrack or to Investigation.")
+    print(r["result"]); print(r["report_facts"])
+"""
+from .llm import gen, gen_ceiling, info, doctor, BackendError
+from .auditor import (
+    run_audit,
+    regime_gate,
+    gate_heuristic,
+    extract_workflow,
+    exact_analysis,
+    graph_facts,
+    transfer_operator,
+    fp_orbit,
+    grounded_report,
+    valid,
+    fallback_extract,
+    norm,
+)
+from .feedback import (
+    extract_iterative,
+    consistency_gaps,
+    candidate_states,
+    candidate_trans,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # headline
+    "run_audit",
+    "extract_iterative",
+    # negative-feedback pipeline parts
+    "regime_gate",
+    "gate_heuristic",
+    "extract_workflow",
+    "exact_analysis",
+    "graph_facts",
+    "transfer_operator",
+    "fp_orbit",
+    "grounded_report",
+    "valid",
+    "fallback_extract",
+    "norm",
+    # positive-feedback parts
+    "consistency_gaps",
+    "candidate_states",
+    "candidate_trans",
+    # client
+    "gen",
+    "gen_ceiling",
+    "info",
+    "doctor",
+    "BackendError",
+    "__version__",
+]

llm_feedback_control/__main__.py

@@ -0,0 +1,98 @@
+"""Command-line entry point:  python -m llm_feedback_control  /  lfc
+
+  lfc "A claim enters Intake. From Intake it goes to Triage."   # audit text
+  lfc --check                                                   # backend doctor
+  lfc --demo                                                    # M1/M2/M3 demos
+  lfc                                                           # quick sample run
+
+The audit runs with no model at all (deterministic regex extraction + exact
+graph analysis); if an LLM backend is reachable it is used automatically and
+the extraction quality goes up. Run ``lfc --check`` to see what's available.
+"""
+import argparse
+import json
+import sys
+
+from . import __version__, run_audit, doctor, info
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8")
+except Exception:
+    pass
+
+SAMPLE = ("A claim enters Intake. From Intake it goes to Triage. Triage goes to "
+          "FastTrack or to Investigation. FastTrack goes to Payout. Investigation "
+          "goes to Payout or to Denied. Payout goes to Closed. Denied goes to Closed.")
+
+
+def _print_audit(r):
+    print("gate      :", r["gate"]["verdict"], "|", r["gate"]["reason"])
+    if "extraction" in r:
+        ex = r["extraction"]
+        print(f"extracted : via={ex['via']}  states={ex['states']}")
+        print(f"            transitions={ex['transitions']}")
+    if "report_facts" in r:
+        print("facts     :")
+        for line in r["report_facts"].rstrip().splitlines():
+            print("   " + line)
+    if r.get("report_english"):
+        print("grounded  :", r["report_english"][:400])
+    print("result    :", r["result"])
+
+
+def _print_doctor():
+    d = doctor()
+    print("llm-feedback-control doctor")
+    print("  config :", info())
+    if d["ollama_reachable"]:
+        print(f"  ollama : reachable at {d['ollama_host']}")
+        print(f"  models : {', '.join(d['models_available']) or '(none pulled)'}")
+        if d["small_model_present"]:
+            print(f"  -> small model '{d['small_model']}' is present. Full LLM path enabled.")
+        else:
+            print(f"  -> small model '{d['small_model']}' NOT pulled. Run:  "
+                  f"ollama pull {d['small_model']}")
+    else:
+        print(f"  ollama : NOT reachable at {d['ollama_host']}")
+        print("  -> The deterministic pipeline still works (regex extraction + exact")
+        print("     graph analysis). For the full LLM path, install Ollama")
+        print("     (https://ollama.com) and `ollama pull {}`,".format(d["small_model"]))
+        print("     or set CEILING_BACKEND=openai with OPENAI_API_KEY.")
+    if d["ceiling_backend"] == "openai":
+        print("  openai :", "OPENAI_API_KEY set" if d["openai_key_set"] else "OPENAI_API_KEY MISSING")
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="lfc",
+        description="LLM feedback control: audit a process description into an "
+                    "exact, grounded, refusable report.")
+    ap.add_argument("text", nargs="?", help="process description to audit "
+                    "(omit to run a built-in sample)")
+    ap.add_argument("--check", action="store_true", help="probe the LLM backend and exit")
+    ap.add_argument("--demo", action="store_true", help="run the M1/M2/M3 demos and exit")
+    ap.add_argument("--json", action="store_true", help="print the raw audit dict as JSON")
+    ap.add_argument("--version", action="version", version=f"llm-feedback-control {__version__}")
+    args = ap.parse_args(argv)
+
+    if args.check:
+        _print_doctor()
+        return 0
+    if args.demo:
+        from .auditor import main as demo_main
+        demo_main()
+        return 0
+
+    text = args.text or SAMPLE
+    if not args.text:
+        print(f"(no text given — auditing a built-in sample; pass your own as an argument)\n")
+    r = run_audit(text)
+    if args.json:
+        print(json.dumps(r, indent=2))
+    else:
+        _print_audit(r)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

llm_feedback_control/auditor.py

@@ -0,0 +1,337 @@
+"""The LLM-feedback-control pipeline, end-to-end and self-contained.
+
+A small LLM is wrapped in a deterministic feedback network so the system knows
+what it can compute exactly, does so, and refuses the rest:
+
+    English text
+      -> extract finite transition system   (LLM + schema + deterministic fallback)
+      -> regime gate                         (hybrid: heuristic + LLM tie-break)
+      -> exact analysis                      (standard graph facts + an optional
+                                              finite-field spectral fingerprint)
+      -> readout contract + injectivity      (refuse non-injective lifts)
+      -> grounded report                     (every claim backed by a trace fact)
+
+This is the NEGATIVE-feedback half (gate / ground / refuse). The bounded
+POSITIVE-feedback loop (iterate-to-fixed-point re-extraction) lives in
+feedback.py.
+
+Every entry point that can use an LLM takes an injectable ``generate`` callable
+(``f(prompt, fmt=None) -> str``); it defaults to the local-Ollama client in
+``llm.py``. If no model is reachable, the pipeline degrades to the deterministic
+path automatically — so ``run_audit`` returns a real result with no model at all.
+
+Demos (run ``python -m llm_feedback_control.auditor``):
+  M1  process auditor on a real workflow (exact trace + grounded report)
+  M2  gate refusal on belief/continuous input ("model-only, refused")
+  M3  non-injective readout refusal (the no-hallucinated-synthesis guard)
+plus a HARDENING test of the gate on deliberately ambiguous / mixed inputs.
+"""
+import sys, json, re
+
+from .llm import gen
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8")
+except Exception:
+    pass
+
+
+def norm(s):
+    return re.sub(r"[^a-z0-9]", "", str(s).lower())
+
+
+# === exact engine: F_p fp_orbit + graph facts (self-contained) ============
+PRIMES = (2, 3, 5, 7)
+
+
+def fp_orbit(M, x0, p, max_steps=20000):
+    n = len(x0); x = [v % p for v in x0]; seen = {}; orbit = []
+    for t in range(max_steps):
+        k = tuple(x)
+        if k in seen:
+            s = seen[k]
+            return s, t - s, orbit[s:]          # transient, period, cycle vectors
+        seen[k] = t; orbit.append(x)
+        x = [sum(M[i][j] * x[j] for j in range(n)) % p for i in range(n)]
+    return None, None, []
+
+
+def transfer_operator(states, trans, p):
+    idx = {s: i for i, s in enumerate(states)}; n = len(states)
+    M = [[0] * n for _ in range(n)]
+    for a, b in trans:
+        if a in idx and b in idx:
+            M[idx[b]][idx[a]] = (M[idx[b]][idx[a]] + 1) % p     # flow a -> b
+    return M, idx
+
+
+def graph_facts(states, trans):
+    out = {s: [b for a, b in trans if a == s] for s in states}
+    terminals = sorted(s for s in states if not out.get(s))
+    start = states[0] if states else None
+    seen = set()
+    if start is not None:
+        stack = [start]; seen = {start}
+        while stack:
+            u = stack.pop()
+            for v in out.get(u, []):
+                if v not in seen:
+                    seen.add(v); stack.append(v)
+    unreachable = sorted(s for s in states if s not in seen)
+    # cycle detection (DFS)
+    WHITE, GREY, BLACK = 0, 1, 2
+    color = {s: WHITE for s in states}; has_cycle = [False]
+    def dfs(u):
+        color[u] = GREY
+        for v in out.get(u, []):
+            if color.get(v) == GREY:
+                has_cycle[0] = True
+            elif color.get(v) == WHITE:
+                dfs(v)
+        color[u] = BLACK
+    for s in states:
+        if color[s] == WHITE:
+            dfs(s)
+    return dict(terminal_states=terminals, unreachable_states=unreachable,
+                has_cycle=has_cycle[0])
+
+
+def exact_analysis(states, trans):
+    """Per-prime exact trace + bad-prime + readout injectivity (the M3 guard)."""
+    if not states:
+        return {"primes": [], "facts": graph_facts(states, trans)}
+    x0 = [1] + [0] * (len(states) - 1)               # launch at the start state
+    per_prime = []
+    for p in PRIMES:
+        M, _ = transfer_operator(states, trans, p)
+        transient, period, cycle = fp_orbit(M, x0, p)
+        mode = cycle[0] if cycle else [0] * len(states)
+        bad = all(v == 0 for v in mode)
+        # readout = sum of mode; injective iff distinct cycle vectors -> distinct readouts
+        readouts = [sum(v) % p for v in cycle] if cycle else []
+        distinct_vecs = len({tuple(v) for v in cycle})
+        injective = len(set(readouts)) == distinct_vecs if cycle else True
+        per_prime.append(dict(prime=p, transient=transient, period=period,
+                              mode=mode, bad_prime=bad, readout_injective=injective))
+    return {"primes": per_prime, "facts": graph_facts(states, trans)}
+
+
+# === regime gate (hybrid: heuristic + LLM tie-break) ======================
+CONT_BELIEF = ["continuous", "continuously", "drift", "rises", "grows", "increase",
+               "rate", "percent", "gradually", "slowly", "temperature", "price",
+               "demand", "confidence", "trust", "trusts", "trustworthy", "feels",
+               "happier", "sentiment", "usually", "accumulat", "improves", "volume"]
+FINITE_CUES = ["goes to", "moves from", "enters", "starts in", "opens in", "proceed to",
+               "escalates", "commits", "rolls back", "either", " or ", "then",
+               "if approved", "if rejected", "if unresolved", "retry", "fails"]
+
+
+def gate_heuristic(text):
+    t = text.lower()
+    cont = sum(t.count(c) for c in CONT_BELIEF)
+    fin = sum(t.count(c) for c in FINITE_CUES)
+    return fin, cont
+
+
+def regime_gate(text, use_llm=True, generate=None):
+    """Route text into "finite_structural", "model_only", or "mixed".
+
+    Clear cases are decided by a cheap heuristic; only genuinely ambiguous cases
+    consult the LLM (``generate`` or the default Ollama client). With no model
+    reachable the LLM tie-break is skipped and the heuristic decides."""
+    g = generate or gen
+    fin, cont = gate_heuristic(text)
+    margin = abs(fin - cont)
+    # clear cases: decide by heuristic
+    if margin >= 2 and not (fin > 0 and cont > 0 and min(fin, cont) >= 2):
+        verdict = "finite_structural" if fin > cont else "model_only"
+        return dict(verdict=verdict, reason=f"heuristic (fin={fin},cont={cont})", source="heuristic")
+    # ambiguous / mixed: ask the LLM to adjudicate
+    if use_llm:
+        try:
+            raw = g('Classify the description into exactly one label: '
+                    '"finite_structural" (a finite set of states and transitions), '
+                    '"model_only" (continuous/probabilistic/belief-driven, no finite state machine), '
+                    'or "mixed" (both). Return JSON {"label": "..."}. '
+                    f'Description: "{text}"', fmt="json")
+            label = json.loads(raw).get("label", "").strip()
+            if label in ("finite_structural", "model_only", "mixed"):
+                return dict(verdict=label, reason=f"LLM tie-break (fin={fin},cont={cont})", source="llm")
+        except Exception:
+            pass
+    # fallback: both present -> mixed; else heuristic
+    if fin > 0 and cont > 0:
+        return dict(verdict="mixed", reason=f"both cues present (fin={fin},cont={cont})", source="heuristic")
+    return dict(verdict="finite_structural" if fin >= cont else "model_only",
+                reason=f"heuristic-fallback (fin={fin},cont={cont})", source="heuristic")
+
+
+# === extraction (LLM + schema + deterministic fallback) ===================
+def valid(o):
+    return (isinstance(o, dict) and isinstance(o.get("states"), list)
+            and isinstance(o.get("transitions"), list)
+            and all(isinstance(t, list) and len(t) == 2 for t in o["transitions"]))
+
+
+def fallback_extract(text):
+    st, tr = set(), set()
+    for m in re.finditer(r"([A-Z][A-Za-z0-9]+)\s+(?:goes to|moves to|to)\s+([A-Z][A-Za-z0-9]+)"
+                         r"(?:\s+or(?: to)?\s+([A-Z][A-Za-z0-9]+))?", text):
+        a, b, c = m.group(1), m.group(2), m.group(3)
+        st |= {a, b}; tr.add((a, b))
+        if c: st.add(c); tr.add((a, c))
+    for m in re.finditer(r"(?:enters|starts in|opens in)\s+([A-Z][A-Za-z0-9]+)", text):
+        st.add(m.group(1))
+    # Order states by FIRST APPEARANCE in the text, not alphabetically: the graph
+    # analysis treats states[0] as the start, so "start = first state mentioned"
+    # must hold (this matches how an LLM lists them in narrative order).
+    first = {}
+    for m in re.finditer(r"[A-Z][A-Za-z0-9]+", text):
+        first.setdefault(m.group(0), len(first))
+    states = sorted(st, key=lambda s: first.get(s, len(first)))
+    return {"states": states, "transitions": [list(t) for t in sorted(tr)]}
+
+
+def extract_workflow(text, generate=None):
+    """Extract a finite state machine: LLM (schema-validated) with a
+    deterministic regex fallback. Returns ``(graph, how)`` where how is
+    "llm" or "fallback"."""
+    g = generate or gen
+    try:
+        raw = g('Extract the finite state machine. Return ONLY JSON '
+                '{"states":[...],"transitions":[["FROM","TO"],...]} using exact state '
+                f'names from the text. Text: "{text}"', fmt="json")
+        o = json.loads(raw)
+        if valid(o) and o["states"]:
+            return o, "llm"
+    except Exception:
+        pass
+    return fallback_extract(text), "fallback"
+
+
+# === grounded report ======================================================
+def grounded_report(states, trace, llm=True, generate=None):
+    g = generate or gen
+    facts = trace["facts"]
+    bad = [pp["prime"] for pp in trace["primes"] if pp["bad_prime"]]
+    noninj = [pp["prime"] for pp in trace["primes"] if not pp["readout_injective"]]
+    deterministic = (
+        f"- States ({len(states)}): {', '.join(states)}\n"
+        f"- Terminal states: {', '.join(facts['terminal_states']) or 'none'}\n"
+        f"- Unreachable from start: {', '.join(facts['unreachable_states']) or 'none'}\n"
+        f"- Contains a cycle (loop): {facts['has_cycle']}\n"
+        f"- Bad primes (mode annihilates): {bad or 'none'}\n"
+        f"- Non-injective readout at primes (lift REFUSED): {noninj or 'none'}\n"
+    )
+    english = ""
+    if llm:
+        try:
+            english = g("Write two plain sentences describing this process using ONLY "
+                        "these verified facts. Name only the listed states; invent nothing.\n"
+                        + deterministic).strip()
+        except Exception:
+            english = "(LLM rewrite unavailable; deterministic facts above are authoritative.)"
+    return deterministic, english
+
+
+# === end-to-end audit =====================================================
+def run_audit(text, verbose=True, generate=None):
+    """Full pipeline: gate -> extract -> exact analysis -> grounded report,
+    with explicit refusals. Works with no model (deterministic fallback);
+    pass ``generate`` to use a specific LLM backend."""
+    gate = regime_gate(text, generate=generate)
+    out = {"text": text, "gate": gate}
+    if gate["verdict"] == "model_only":
+        out["result"] = "REFUSED: model-only regime; no exact finite-structural analysis."
+        return out
+    graph, how = extract_workflow(text, generate=generate)
+    out["extraction"] = {"via": how, "states": graph["states"], "transitions": graph["transitions"]}
+    if not graph["states"]:
+        out["result"] = "REFUSED: no finite structure could be extracted."
+        return out
+    trace = exact_analysis(graph["states"], [tuple(t) for t in graph["transitions"]])
+    out["trace"] = trace
+    det, eng = grounded_report(graph["states"], trace, llm=True, generate=generate)
+    out["report_facts"] = det
+    out["report_english"] = eng
+    out["result"] = "OK" + (" (mixed: finite part analysed, continuous part deferred)"
+                            if gate["verdict"] == "mixed" else "")
+    return out
+
+
+# === demos ================================================================
+def banner(t):
+    print("\n" + "=" * 74 + f"\n{t}\n" + "=" * 74)
+
+
+def demo_M1():
+    banner("M1 — process auditor (full pipeline, exact trace + grounded report)")
+    text = ("A customer order enters Review. If approved it goes to Packing. If "
+            "rejected it goes to Refund. Packing goes to Shipped. Shipped goes to "
+            "Closed. Refund goes to Closed.")
+    r = run_audit(text)
+    print("gate     :", r["gate"]["verdict"], "|", r["gate"]["reason"])
+    print("extracted:", r["extraction"]["via"], r["extraction"]["states"])
+    print("report facts:\n" + r["report_facts"])
+    print("grounded english:", r.get("report_english", "")[:300])
+    print("result   :", r["result"])
+
+
+def demo_M2():
+    banner("M2 — gate refusal on belief/continuous input")
+    text = "The market price drifts until confidence improves, then buyers slowly return."
+    r = run_audit(text)
+    print("input   :", text)
+    print("gate    :", r["gate"]["verdict"], "|", r["gate"]["reason"])
+    print("result  :", r["result"])
+
+
+def demo_M3():
+    banner("M3 — non-injective readout refusal (no hallucinated synthesis)")
+    # a symmetric 4-cycle: its F_p standing mode has a multi-vector cycle whose
+    # sum-readout collapses distinct vectors -> the lift must be refused.
+    states = ["S0", "S1", "S2", "S3"]
+    trans = [("S0", "S1"), ("S1", "S2"), ("S2", "S3"), ("S3", "S0"),
+             ("S1", "S0"), ("S2", "S1"), ("S3", "S2"), ("S0", "S3")]  # undirected 4-cycle
+    trace = exact_analysis(states, trans)
+    for pp in trace["primes"]:
+        tag = "BAD-PRIME" if pp["bad_prime"] else ("READOUT NON-INJECTIVE -> LIFT REFUSED"
+              if not pp["readout_injective"] else "ok")
+        print(f"  prime {pp['prime']}: period={pp['period']} mode={pp['mode']}  -> {tag}")
+    refused = [pp["prime"] for pp in trace["primes"] if not pp["readout_injective"] or pp["bad_prime"]]
+    print(f"  => CRT synthesis runs ONLY over primes with injective readouts; "
+          f"refused/degenerate primes excluded: {refused}")
+
+
+def test_gate_hard():
+    banner("Q2 HARDENING — gate on ambiguous / mixed inputs (hybrid vs heuristic-only)")
+    corpus = [
+        ("After validation the system either commits or rolls back.", "finite_structural"),
+        ("The retry counter increments each cycle until it reaches the limit, then the job fails.", "finite_structural"),
+        ("Orders move from Review to Packing, and packing time grows as volume increases.", "mixed"),
+        ("If the customer trusts the brand, they proceed to Checkout; otherwise they leave.", "mixed"),
+        ("The model's confidence rises with each correct prediction.", "model_only"),
+        ("A request goes to Pending, then to Approved or Denied.", "finite_structural"),
+        ("Sentiment improves gradually as more reviews accumulate.", "model_only"),
+        ("A ticket escalates from Tier1 to Tier2 to Tier3 if unresolved.", "finite_structural"),
+    ]
+    h_ok = hyb_ok = 0
+    for text, truth in corpus:
+        fin, cont = gate_heuristic(text)
+        h_pred = "finite_structural" if fin > cont else ("model_only" if cont > fin else "mixed")
+        hyb = regime_gate(text, use_llm=True)["verdict"]
+        h_ok += (h_pred == truth); hyb_ok += (hyb == truth)
+        print(f"  truth={truth:<17} heuristic={h_pred:<17} hybrid={hyb:<17} | {text[:42]}")
+    print(f"\n  heuristic-only accuracy: {h_ok}/{len(corpus)}   hybrid(LLM) accuracy: {hyb_ok}/{len(corpus)}")
+
+
+def main():
+    demo_M1()
+    demo_M2()
+    demo_M3()
+    test_gate_hard()
+    print("\n(all stages self-contained; nothing imported from any external solver)")
+
+
+if __name__ == "__main__":
+    main()

llm_feedback_control/feedback.py

@@ -0,0 +1,151 @@
+"""The bounded POSITIVE-feedback loop (the op-amp "close the loop").
+
+Negative feedback (gate / ground / refuse) is validated in auditor.py: it
+stabilises, but it checks FORM, not COMPLETENESS — a one-shot extraction can
+silently drop a branch and the system still says "OK".
+
+This adds the regenerative loop that fixes that, using a reference that needs
+NONE of the special mathematics — just deterministic text<->graph consistency:
+
+    extract (LLM)  ->  consistency_gaps(text, graph)  [deterministic reference]
+        ^                                   |
+        |____ re-prompt with the gaps  <----'   (positive feedback: amplify coverage)
+
+Bounded by: a FIXED-POINT test (stop when the graph stops changing / no gaps)
+and an iteration cap with a REFUSAL clamp (if it can't converge, say so — do
+NOT report a confident-but-incomplete result). That refusal clamp is the
+stability bound that keeps the regenerative loop from running away.
+
+The reference is plain regex graph consistency — so the "LLM feedback control /
+refusal-as-stabilizer" discipline stands on its own, with no special math.
+The LLM backend is injectable via ``generate`` (defaults to llm.gen).
+"""
+import re, json
+from .llm import gen
+from .auditor import valid, fallback_extract, norm
+
+STOP = {"If", "The", "A", "An", "After", "Once", "When", "Otherwise", "It", "Then"}
+
+
+def candidate_states(text):
+    c = set()
+    for m in re.finditer(r"(?:goes to|moves to|move to|back to|to|enters|starts in|opens in|into)\s+([A-Z][A-Za-z0-9]+)", text):
+        c.add(m.group(1))
+    for m in re.finditer(r"\b([A-Z][A-Za-z0-9]+)\s+(?:goes|moves|closes|enters|ends)", text):
+        c.add(m.group(1))
+    return {s for s in c if s not in STOP}
+
+
+def candidate_trans(text):
+    tr = set()
+    for m in re.finditer(r"([A-Z][A-Za-z0-9]+)\s+(?:goes to|moves to|move to)\s+([A-Z][A-Za-z0-9]+)"
+                         r"(?:\s+or(?: to)?\s+([A-Z][A-Za-z0-9]+))?", text):
+        a, b, c = m.group(1), m.group(2), m.group(3)
+        if a not in STOP: tr.add((a, b))
+        if c: tr.add((a, c))
+    return tr
+
+
+def consistency_gaps(text, graph):
+    """Deterministic reference: what does the TEXT mention that the GRAPH lacks?"""
+    gs = {norm(s) for s in graph.get("states", [])}
+    gt = {(norm(a), norm(b)) for a, b in graph.get("transitions", [])}
+    miss_s = sorted({s for s in candidate_states(text) if norm(s) not in gs})
+    miss_t = sorted({(a, b) for a, b in candidate_trans(text)
+                     if (norm(a), norm(b)) not in gt})
+    return miss_s, miss_t
+
+
+def extract_iterative(text, max_iters=4, verbose=True, generate=None):
+    """Positive-feedback extraction: re-prompt on deterministic gaps until a
+    fixed point, bounded by ``max_iters`` + a refusal clamp.
+
+    Returns ``(graph, initial, history, converged)``: the final graph, the
+    open-loop iter-0 snapshot, a per-iteration history, and whether it
+    converged to a clean fixed point (no residual gaps). Pass ``generate`` to
+    use a specific LLM backend; with no model it returns the deterministic
+    extraction unchanged (history length 1)."""
+    g = generate or gen
+    # iteration 0: plain extraction
+    try:
+        raw = g('Extract the finite state machine. Return ONLY JSON '
+                '{"states":[...],"transitions":[["FROM","TO"],...]} using exact state '
+                f'names from the text. Text: "{text}"', fmt="json")
+        graph = json.loads(raw)
+        if not (valid(graph) and graph.get("states")):
+            graph = fallback_extract(text)
+    except Exception:
+        graph = fallback_extract(text)
+
+    initial = json.loads(json.dumps(graph))   # iter-0 (open-loop) snapshot
+    history = []
+    for it in range(max_iters):
+        miss_s, miss_t = consistency_gaps(text, graph)
+        sig = (tuple(sorted(norm(s) for s in graph["states"])),
+               tuple(sorted((norm(a), norm(b)) for a, b in graph["transitions"])))
+        history.append((it, len(graph["states"]), len(graph["transitions"]), miss_s, miss_t))
+        if verbose:
+            print(f"  iter {it}: states={graph['states']}")
+            print(f"          gaps -> missing states {miss_s or '∅'}, missing transitions {miss_t or '∅'}")
+        if not miss_s and not miss_t:
+            return graph, initial, history, True   # FIXED POINT (converged, no gaps)
+        # positive feedback: re-prompt with the deterministic gaps
+        gaps_txt = (f"missing states: {miss_s}; missing transitions: {miss_t}")
+        try:
+            raw = g('Here is a state machine you extracted, and a list of items the '
+                    'source text mentions that are MISSING from it. Return the COMPLETE '
+                    'corrected machine as JSON {"states":[...],"transitions":[["FROM","TO"],...]}, '
+                    'adding the missing items (and their transitions) using exact names. '
+                    f'Current: {json.dumps({"states": graph["states"], "transitions": graph["transitions"]})}. '
+                    f'Missing per the text: {gaps_txt}. Source text: "{text}"', fmt="json")
+            ng = json.loads(raw)
+            if valid(ng) and ng.get("states"):
+                # check it actually changed (avoid stalling)
+                nsig = (tuple(sorted(norm(s) for s in ng["states"])),
+                        tuple(sorted((norm(a), norm(b)) for a, b in ng["transitions"])))
+                graph = ng
+                if nsig == sig:
+                    break                          # no change -> not converging
+        except Exception:
+            break
+    # exhausted iterations with residual gaps -> REFUSAL CLAMP (stability bound)
+    miss_s, miss_t = consistency_gaps(text, graph)
+    converged = not miss_s and not miss_t
+    return graph, initial, history, converged
+
+
+def main():
+    print("=" * 74)
+    print("POSITIVE-FEEDBACK EXTRACTION (op-amp 'close the loop'); reference = plain")
+    print("text<->graph consistency, NO special math involved")
+    print("=" * 74)
+    text = ("A customer order enters Review. If approved it goes to Packing. If "
+            "rejected it goes to Refund. Packing goes to Shipped. Shipped goes to "
+            "Closed. Refund goes to Closed.")
+    print(f"\nText: {text}\n")
+    graph, _initial, history, converged = extract_iterative(text)
+    print("\n" + "-" * 74)
+    print(f"iterations run: {len(history)}")
+    if converged:
+        print(f"CONVERGED to a fixed point with NO residual gaps. Final states: {graph['states']}")
+        print("  -> the dropped branch was recovered by the regenerative loop, then the")
+        print("     fixed-point test (negative-feedback reference) stopped it cleanly.")
+    else:
+        ms, mt = consistency_gaps(text, graph)
+        print(f"DID NOT CONVERGE within the cap. REFUSAL CLAMP fires:")
+        print(f"  residual gaps: missing states {ms}, missing transitions {mt}")
+        print("  -> the system refuses to report a confident-but-incomplete result")
+        print("     (the stability bound that keeps positive feedback from faking 'OK').")
+    print("\n" + "=" * 74)
+    print("PRINCIPLE DEMONSTRATED")
+    print("=" * 74)
+    print("""\
+- POSITIVE feedback (regenerative re-extraction) recovered coverage that the
+  one-shot negative-feedback pass could not — it amplified toward completeness.
+- It was made SAFE by two negative-feedback bounds: a deterministic fixed-point
+  reference (text<->graph consistency) and a refusal clamp on non-convergence.
+- The reference uses ZERO special mathematics — just regex graph consistency.""")
+
+
+if __name__ == "__main__":
+    main()

llm_feedback_control/llm.py

@@ -0,0 +1,143 @@
+"""LLM client for llm-feedback-control.
+
+Two backends behind a tiny interface:
+  * gen()         — a local Ollama model (default phi3:mini, the "small model")
+  * gen_ceiling() — a stronger reference model: a larger Ollama model OR the
+                    OpenAI API (used only as a quality CEILING in experiments)
+
+Everything is configurable by environment variable so the same code runs
+locally and on a remote box (e.g. EC2) without edits:
+
+  OLLAMA_HOST      default http://localhost:11434
+  LFC_MODEL        default phi3:mini            (the small model under test)
+  LFC_CEILING      default llama3.1:8b          (a bigger local Ollama model)
+  CEILING_BACKEND  "ollama" (default) or "openai"
+  OPENAI_API_KEY   required iff CEILING_BACKEND=openai
+  OPENAI_MODEL     default gpt-4o-mini
+
+Only the standard library is used (urllib + json) — no SDK dependency, and the
+whole package has **zero third-party runtime dependencies**.
+
+You are never locked to Ollama: every high-level entry point in this package
+(`run_audit`, `extract_iterative`, `regime_gate`, ...) accepts an injectable
+``generate`` callable, so you can plug in OpenAI, Anthropic, a local server, or
+any function ``f(prompt, fmt=None) -> str``. The functions in this module are
+just the convenient defaults.
+"""
+import os
+import json
+import urllib.request
+import urllib.error
+
+OLLAMA_HOST = os.environ.get("OLLAMA_HOST", "http://localhost:11434").rstrip("/")
+MODEL = os.environ.get("LFC_MODEL", "phi3:mini")
+CEILING_MODEL = os.environ.get("LFC_CEILING", "llama3.1:8b")
+CEILING_BACKEND = os.environ.get("CEILING_BACKEND", "ollama")
+OPENAI_MODEL = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+
+
+class BackendError(RuntimeError):
+    """No LLM backend was reachable. The message explains exactly what to do.
+
+    Note: the high-level pipeline (`run_audit`, `extract_iterative`, ...) catches
+    this internally and falls back to the deterministic path, so a missing model
+    degrades gracefully rather than crashing. This is only raised to callers who
+    invoke `gen` / `gen_ceiling` directly.
+    """
+
+
+def _ollama(prompt, fmt, model, timeout):
+    body = {"model": model, "prompt": prompt, "stream": False,
+            "options": {"temperature": 0.0}}
+    if fmt:
+        body["format"] = fmt
+    req = urllib.request.Request(f"{OLLAMA_HOST}/api/generate",
+                                 data=json.dumps(body).encode(),
+                                 headers={"Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read()).get("response", "")
+    except urllib.error.URLError as e:
+        raise BackendError(
+            f"Could not reach an Ollama server at {OLLAMA_HOST} ({e}).\n"
+            f"  - Install Ollama:  https://ollama.com\n"
+            f"  - Start it and pull the small model:  ollama pull {MODEL}\n"
+            f"  - Or point OLLAMA_HOST at a running server.\n"
+            f"  - Or use OpenAI: set CEILING_BACKEND=openai and OPENAI_API_KEY,\n"
+            f"    or pass your own generate=... callable.\n"
+            f"  (The deterministic pipeline still works with NO model at all — "
+            f"run_audit() falls back to a regex extractor + exact graph analysis.)"
+        ) from e
+
+
+def gen(prompt, fmt=None, model=None, timeout=600):
+    """Generate from a local Ollama model. ``fmt="json"`` forces valid JSON.
+    Greedy decode (temperature 0) for reproducibility.
+
+    Raises :class:`BackendError` (with actionable guidance) if no server is
+    reachable."""
+    return _ollama(prompt, fmt, model or MODEL, timeout)
+
+
+def _gen_openai(prompt, model=None, timeout=120):
+    try:
+        key = os.environ["OPENAI_API_KEY"]
+    except KeyError as e:
+        raise BackendError(
+            "CEILING_BACKEND=openai but OPENAI_API_KEY is not set in the "
+            "environment."
+        ) from e
+    body = {"model": model or OPENAI_MODEL,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0, "response_format": {"type": "json_object"}}
+    req = urllib.request.Request("https://api.openai.com/v1/chat/completions",
+                                 data=json.dumps(body).encode(),
+                                 headers={"Content-Type": "application/json",
+                                          "Authorization": f"Bearer {key}"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read())["choices"][0]["message"]["content"]
+    except urllib.error.URLError as e:
+        raise BackendError(f"Could not reach the OpenAI API ({e}).") from e
+
+
+def gen_ceiling(prompt, fmt="json", timeout=600):
+    """Generate from the CEILING model (a stronger reference). Backend chosen by
+    CEILING_BACKEND: a bigger local Ollama model, or the OpenAI API."""
+    if CEILING_BACKEND == "openai":
+        return _gen_openai(prompt, timeout=timeout)
+    return gen(prompt, fmt=fmt, model=CEILING_MODEL, timeout=timeout)
+
+
+def info():
+    return (f"small={MODEL} @ {OLLAMA_HOST} | ceiling={CEILING_MODEL} "
+            f"(backend={CEILING_BACKEND})")
+
+
+def doctor():
+    """Probe the configured backend and report what's available.
+
+    Returns a status dict. Never raises — safe to call before anything is set
+    up. Used by ``python -m llm_feedback_control --check``."""
+    status = {
+        "ollama_host": OLLAMA_HOST,
+        "small_model": MODEL,
+        "ceiling_backend": CEILING_BACKEND,
+        "ceiling_model": CEILING_MODEL,
+        "openai_key_set": bool(os.environ.get("OPENAI_API_KEY")),
+    }
+    try:
+        req = urllib.request.Request(f"{OLLAMA_HOST}/api/tags")
+        with urllib.request.urlopen(req, timeout=5) as r:
+            models = json.loads(r.read()).get("models", [])
+        names = [m.get("name") or m.get("model") for m in models]
+        status["ollama_reachable"] = True
+        status["models_available"] = names
+        status["small_model_present"] = any(
+            MODEL.split(":")[0] in (n or "") for n in names)
+    except Exception as e:  # noqa: BLE001 — doctor must never raise
+        status["ollama_reachable"] = False
+        status["models_available"] = []
+        status["small_model_present"] = False
+        status["error"] = str(e)
+    return status

llm_feedback_control-0.1.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: llm-feedback-control
+Version: 0.1.0
+Summary: Reliable, checkable structured output from a small local LLM, by wrapping it in a deterministic feedback loop: a regime gate + exact graph analysis + explicit refusal, plus a bounded re-extraction loop. Zero runtime dependencies; runs with no model at all.
+Author-email: Edward Chalk <edward.chalk@sapientronic.ai>
+License: llm-feedback-control
+        
+        Copyright (c) 2026 Edward Chalk (sapientronic.ai)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to use,
+        copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+        the Software, and to permit persons to whom the Software is furnished to do
+        so, subject to the following conditions:
+        
+        1. The above copyright notice and this permission notice shall be included
+           in all copies or substantial portions of the Software.
+        
+        2. Attribution. Any publication, presentation, derivative work, or product
+           that uses or builds on this Software must include visible attribution to
+           Edward Chalk and sapientronic.ai. The phrase "Built with llm-feedback-control
+           by Edward Chalk (sapientronic.ai)" or equivalent is acceptable.
+        
+        3. The Software is provided "AS IS", without warranty of any kind, express
+           or implied, including but not limited to the warranties of merchantability,
+           fitness for a particular purpose, and noninfringement. In no event shall
+           the authors or copyright holders be liable for any claim, damages, or
+           other liability, whether in an action of contract, tort, or otherwise,
+           arising from, out of, or in connection with the Software or the use or
+           other dealings in the Software.
+        
+        This license is modeled on the MIT License with an explicit attribution
+        clause (clause 2).
+        
+Project-URL: Homepage, https://github.com/pcoz/llm-feedback-control
+Project-URL: Repository, https://github.com/pcoz/llm-feedback-control
+Project-URL: Issues, https://github.com/pcoz/llm-feedback-control/issues
+Project-URL: Changelog, https://github.com/pcoz/llm-feedback-control/blob/main/CHANGELOG.md
+Keywords: llm,feedback-control,structured-extraction,state-machine,workflow,hallucination,reliability,ollama,small-language-model,auditable,refusal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: aws
+Requires-Dist: boto3>=1.26; extra == "aws"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# llm-feedback-control
+
+**Get reliable, checkable structured output from a small, local language model —
+by wrapping it in ordinary deterministic code.**
+
+[![CI](https://github.com/pcoz/llm-feedback-control/actions/workflows/ci.yml/badge.svg)](https://github.com/pcoz/llm-feedback-control/actions/workflows/ci.yml)
+
+---
+
+## What it actually does
+
+You hand it a process written in plain English:
+
+> "A claim enters Intake. From Intake it goes to Triage. Triage goes to FastTrack
+> or to Investigation. FastTrack goes to Payout. Investigation goes to Payout or
+> to Denied. Payout goes to Closed. Denied goes to Closed."
+
+and it:
+
+1. **turns that into a state machine** — the steps (states) and the arrows between
+   them (transitions);
+2. **computes provable facts** about it — which steps are dead ends, whether
+   there are loops, which steps can't be reached from the start;
+3. **writes a report where every statement is backed by one of those checked
+   facts** — so it can't quietly make things up;
+4. **knows its own limits.** If the text isn't actually a finite step-by-step
+   process (e.g. *"prices drift up as confidence grows"*), it **refuses** instead
+   of inventing a fake state machine. And if the model's first pass missed part of
+   the process, it **loops to fill the gaps** — or refuses if it can't.
+
+The point: you get **higher-quality, auditable structured output from a *small*
+model**, trading a few extra passes (latency) for accuracy — no extra parameters,
+no special mathematics, no cloud. It runs on a laptop, and the deterministic parts
+run **with no model at all**.
+
+## Quickstart (works with no model)
+
+```bash
+pip install llm-feedback-control      # zero dependencies — pulls nothing else
+```
+
+```python
+from llm_feedback_control import run_audit
+
+r = run_audit("A claim enters Intake. From Intake it goes to Triage. "
+              "Triage goes to FastTrack or to Investigation.")
+print(r["result"])         # OK
+print(r["report_facts"])   # terminals, loops, unreachable steps — all checked
+```
+
+That already works on a bare install: with no model reachable it uses a
+deterministic regex extractor plus exact graph analysis. **Plug in a model and the
+extraction quality goes up — nothing else changes.**
+
+From the command line:
+
+```bash
+lfc "A ticket opens in New. New goes to Assigned. Assigned goes to Resolved."
+lfc --check        # tells you exactly what backend is available and what to do
+lfc --demo         # runs the three worked demos
+```
+
+### Add a model (optional, recommended)
+
+The library is **not tied to any provider.** Three ways to give it a model:
+
+```bash
+# 1. Local, free, private — install Ollama (https://ollama.com), then:
+ollama pull phi3:mini
+
+# 2. OpenAI (stdlib HTTP, no SDK):
+export CEILING_BACKEND=openai OPENAI_API_KEY=sk-...
+```
+
+```python
+# 3. Bring your own: pass any callable f(prompt, fmt=None) -> str
+def my_llm(prompt, fmt=None):
+    ...                       # call Anthropic, a local server, anything
+run_audit(text, generate=my_llm)
+```
+
+Run `lfc --check` any time to see what's wired up.
+
+## How it works — "feedback control", explained
+
+The design is borrowed from **electronics.** A raw LLM is like a very high-gain
+amplifier: hugely powerful, but left to run "open-loop" it overshoots — fluent,
+yet it drifts and hallucinates. Engineers tame such an amplifier by adding a
+**feedback loop**: feed the output back, compare it against a stable reference,
+and trade some raw power for precision and stability. This library is that
+feedback loop for an LLM. The "reference" is plain deterministic code — graph
+checks and schema rules — that the model's output is measured against.
+
+There are two kinds of feedback, and the library uses both:
+
+### Negative feedback — the stabilising checks (`run_audit`)
+
+This is the half that *grounds and refuses*. In plain terms:
+
+| step | what it means |
+|---|---|
+| **regime gate** | First decide whether the text is even the kind of thing we can analyse exactly (a finite, step-by-step process) versus something fuzzy and continuous. Refuse the fuzzy ones. |
+| **extraction + schema** | Ask the model for the state machine, but force the answer into a strict shape — and fall back to a deterministic regex extractor if it won't comply (or if there's no model). |
+| **exact analysis** | Compute provable facts about the graph: dead ends, loops, unreachable steps. (Plus an *optional* finite-field "spectral fingerprint" — see below.) |
+| **grounded report** | Write the summary using only those verified facts, naming only real states. |
+| **explicit refusal** | When the input is out of regime, or a result can't be made exact, say so — don't guess. |
+
+### Positive feedback — the gap-filling loop (`extract_iterative`)
+
+A one-shot extraction often silently **drops a branch** — the model says "OK"
+while quietly missing *Investigation → Denied*. Positive feedback fixes that: it
+**re-asks the model about anything the source text mentions that's missing from
+the answer**, and repeats until nothing is missing (a *fixed point*).
+
+Positive feedback is where capability *and* instability both live, so it's bounded
+by two negative-feedback safeguards: a deterministic consistency check (does the
+graph cover everything the text mentions?) and a **refusal clamp** — if it can't
+converge within a few passes, it refuses to report a confident-but-incomplete
+result rather than running away. This **refusal-as-stabilizer** is what makes the
+regenerative loop safe.
+
+## What's measured so far
+
+Indicative results, not benchmarks — small corpora, a 3.8B local model
+(`phi3:mini`), greedy decoding. See [`docs/results.md`](docs/results.md) for the
+full tables and method.
+
+**Headline (run on EC2 against a ~28 GB ceiling model, mixtral 8x7B):** on a
+messy, branchy, distractor-laden workflow corpus, the small model **+ the feedback
+loop essentially matches a model ~7× its size.**
+
+| configuration | states F1 | transitions F1 |
+|---|---|---|
+| small model (phi3:mini), one-shot | 0.98 | 0.89 |
+| **small model + feedback loop** | **1.00** | **0.90** |
+| big ceiling model (mixtral, ~28 GB), one-shot | 1.00 | 0.91 |
+
+→ the loop recovers **100%** of the small→big gap on states and **77%** on
+transitions — and on several individual workflows the closed-loop small model
+*beat* the big model, because the deterministic reference catches edges that raw
+fluency invents or drops.
+
+Other measured pieces: extraction states precision/recall ≈ 1.00 / 0.92; the
+regime gate scores 1.00 precision/recall separating finite from continuous on a
+clean corpus (it's brittle on deliberately *mixed* inputs — an open problem).
+
+## Documentation
+
+| doc | contents |
+|---|---|
+| [`docs/index.md`](docs/index.md) | overview and where to start |
+| [`docs/architecture.md`](docs/architecture.md) | the op-amp model in depth; the pipeline; refusal-as-stabilizer |
+| [`docs/usage.md`](docs/usage.md) | install, the API, the CLI, configuration, bring-your-own-backend |
+| [`docs/results.md`](docs/results.md) | the measured results, method, and honest scope |
+| [`docs/api.md`](docs/api.md) | reference for every public function |
+| [`docs/faq.md`](docs/faq.md) | "do I need a GPU?", "what models?", "does it work offline?" … |
+
+## Repository layout
+
+```
+src/llm_feedback_control/   the package (zero-dependency, pure standard library)
+  llm.py                    the LLM client + injectable backend + a doctor()
+  auditor.py                the negative-feedback pipeline (run_audit)
+  feedback.py               the bounded positive-feedback loop (extract_iterative)
+  __main__.py               the `lfc` command-line tool
+experiments/                repro scripts for the measured results (not shipped)
+aws/                        optional: run a large ceiling model on EC2 (not shipped)
+docs/                       the documentation suite
+tests/                      deterministic tests (no model / no network)
+```
+
+## Honest scope
+
+- **A reliability architecture, not a model improvement.** The win is "the system
+  knows what it can compute exactly and refuses the rest" — orthogonal to model
+  scale. It helps on the *structured / verifiable slice* (workflows, state
+  machines, configs), not open-ended generation.
+- **It uses no special mathematics.** The deterministic reference is plain
+  graph/text consistency. (The finite-field "spectral fingerprint" is an *optional*
+  extra exact check, honestly redundant with graph analysis for most workflow
+  audits — keep it or ignore it.)
+- **Needs a deterministic reference.** Where there's nothing to check against, the
+  gate (correctly) refuses to claim exactness.
+- **Results are indicative.** Small corpora; treat the numbers as direction, not
+  guarantees.
+
+## Origin
+
+This project is the practical, validated spin-off of an internal research
+investigation. The investigation's grander mathematical claims did not hold up
+under measurement; this engineering architecture — LLM feedback control with
+refusal-as-stabilizer — is the part that did. It stands on its own.
+
+## License
+
+MIT with an attribution clause — see [`LICENSE`](LICENSE).
+Built with llm-feedback-control by Edward Chalk (sapientronic.ai).

llm_feedback_control-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+llm_feedback_control/__init__.py,sha256=75Udenah_ANeGOwYttX_-5kWtFr_r-WxQhet4HPQ4a8,3723
+llm_feedback_control/__main__.py,sha256=L_1H35DBTkyPO-6OsjUuMPt2jNwTVbSsCmmG5vYAMR0,3969
+llm_feedback_control/auditor.py,sha256=EjbIZbqKaEvUvXnnrBXJ-cjO99Xw7ioxLWgkgEvZfRY,15491
+llm_feedback_control/feedback.py,sha256=gQqfembMfGGTlgF6HcYOXkQAlEM2l39xK9MKdZDV0AA,7570
+llm_feedback_control/llm.py,sha256=Pm5V7Km43AXcKykW4aDX28mPrK8hbqhygg1zl49q5Do,6290
+llm_feedback_control-0.1.0.dist-info/licenses/LICENSE,sha256=ITnVOjCtoAKd-QQxtLh77T94TSkmzIddIxyEHWtWSlQ,1434
+llm_feedback_control-0.1.0.dist-info/METADATA,sha256=vY7GFnHYzPgAVZDFLNjv8RwOtZlwgo9R1SZpwK3eT0s,13086
+llm_feedback_control-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+llm_feedback_control-0.1.0.dist-info/entry_points.txt,sha256=FqOQG5kIa81IkFvvuD_y5Nk3I2DQCvtTQSC5TeMhOV4,59
+llm_feedback_control-0.1.0.dist-info/top_level.txt,sha256=dhKfG5rAR6PqKr4uSAslVgGcmQq19gzvPN_S2UKp1SE,21
+llm_feedback_control-0.1.0.dist-info/RECORD,,

llm_feedback_control-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

llm_feedback_control-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lfc = llm_feedback_control.__main__:main

llm_feedback_control-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+llm-feedback-control
+
+Copyright (c) 2026 Edward Chalk (sapientronic.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included
+   in all copies or substantial portions of the Software.
+
+2. Attribution. Any publication, presentation, derivative work, or product
+   that uses or builds on this Software must include visible attribution to
+   Edward Chalk and sapientronic.ai. The phrase "Built with llm-feedback-control
+   by Edward Chalk (sapientronic.ai)" or equivalent is acceptable.
+
+3. The Software is provided "AS IS", without warranty of any kind, express
+   or implied, including but not limited to the warranties of merchantability,
+   fitness for a particular purpose, and noninfringement. In no event shall
+   the authors or copyright holders be liable for any claim, damages, or
+   other liability, whether in an action of contract, tort, or otherwise,
+   arising from, out of, or in connection with the Software or the use or
+   other dealings in the Software.
+
+This license is modeled on the MIT License with an explicit attribution
+clause (clause 2).

llm_feedback_control-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+llm_feedback_control