llm-feedback-control 0.2.1

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.

llm-feedback-control

Reliable, checkable structured data out of a small, local language model — by wrapping it in deterministic feedback.

What it does

Language models are fluent but they make things up — and they sound just as sure when they're wrong. That bites hardest when you ask one to pull structure out of text (the steps of a process, the fields of a form): it gets most of it right, then quietly invents or drops the rest.

This library turns free text into structured data you can trust. It pairs the model with a deterministic reference — real checking code suited to what you're extracting — and runs a feedback loop that:

• verifies the model's answer against that reference,
• fills in what the model missed by re-asking with the gaps pointed out,
• refuses — says "I'm not sure" — when it can't verify the result, instead of guessing.

Because the checking (not the model's size) does the heavy lifting, a small model you run for free on a laptop becomes reliable enough to use. In our tests a 3.8B model wrapped this way matches one about seven times larger.

What you can extract

It's one engine pointed at different targets. A target is anything you can pair with a schema and a deterministic check — two ship today, more are a small addition (the loop is public and injectable):

• workflows / processes → state machines (run_audit) — states, transitions, dead ends, unreachable steps, loops;
• form fields (invoices, applications, claims) against a field schema (extract_form) — verifies each value against the source, recovers ones the model hallucinated, refuses on missing required fields;
• records / tables, entities & relations, configs / specs — bring a schema + a reference and call feedback_loop.

It helps on the structured, verifiable slice — where a deterministic reference exists. For open-ended generation (summaries, sentiment) there's nothing to check against, so it refuses to claim exactness, by design.

Documentation

The full user manual is in docs/:

chapter	contents
Getting started	install, the API, the lfc CLI, choosing/bringing a model, configuration
How it works	the op-amp model: negative/positive feedback, refusal-as-stabilizer, the general engine
API reference	every public function
Results	measured numbers, method, honest scope
Worked examples	actual run transcripts
FAQ	GPU? models? offline? why did it refuse?
Changelog	release history

Install

pip install llm-feedback-control     # zero dependencies

Then follow Getting started. The deterministic parts run with no model at all; a model (local Ollama, OpenAI, or your own callable) is a pure upgrade.

License

MIT with an attribution clause — see LICENSE. Built with llm-feedback-control by Edward Chalk (sapientronic.ai).