gut is a Python library for making small judgments about text, returning YES, NO, or UNSURE. It is designed for TypeSafe AI's Jev, and can also run on Ollama, vLLM, OpenAI, or local NLI models.
Purpose: Solve non-logical judgment problems in code, for example: Is this comment spam? Which team does this ticket belong to? How urgent is it? Is the agent's task complete? Traditional approaches either use regex and keyword rules (free but error-prone), frontier large models (strong understanding but slow and expensive), or train classifiers (requires labeled data and a pipeline). gut provides a fourth approach: use small models designed specifically for this kind of problem, directly output probabilities, option distributions, or scores, without generating or parsing text, and bill only by input.
Main capabilities:
- Complete a judgment in one line of Python code: likely / classify / rate → YES, NO, or UNSURE.
- No prompts, no parsing, no thresholds; the call site does not specify a model.
- Supports three question types: yes/no, single choice, and rating.
- Can express uncertainty: returns UNSURE, and can describe the degree of caution in words via parameters such as lean="yes" and stakes="high"; gut automatically calculates the threshold.
- Supports batch processing: Jev supports concurrent requests, local models support batching, and cached content is not asked again. @gut.semantic can do the same for multiple questions on the same topic.
- Configurable models: uses Jev by default, and can also run on local NLI, local LLM, Ollama, vLLM, or OpenAI, with no changes needed in the same line of code.
- Supports cascading: ask the cheapest model first, and pass only the uncertain parts to more expensive models.
- Every answer is the model's own probability, not parsed from text; decision.model indicates which model gave the answer.
- Supports custom models as backends.
- Provides FakeBackend for testing, for example gut.FakeBackend(answers={"is spam": 0.97}).
- Provides a command-line tool and an MCP server, suitable for agents: large models think, small models make quick decisions.
Usage: The PyPI package name is gutfeel (gut is already taken), and it is imported as import gut. The documentation includes getting started,backends, uncertainty, batch asking, async, exact cost, caching and observability, command line, MCP server, honest limitations, and other pages. The examples/ directory shows the same code running on different backends.
Use cases:
- Agents need to quickly judge a large number of files, commits, or search results rather than reading them one by one.
- Need low-cost, low-latency classification or decision-making on text.
- Need to handle judgment tasks involving uncertainty.
Limitations:
- The project is pre-1.0, with an Apache-2.0 license.
- Every code block in the documentation runs in the test suite.
- Other specific limitations are not provided yet.
