overllm 0.1.0__py3-none-any.whl

overllm/__init__.py

@@ -0,0 +1,11 @@
+"""overllm - catch the LLM/AI calls you didn't need.
+
+A fast, deterministic (no-LLM) linter that flags LLM API calls where plain,
+cheaper, more reliable code would do the same job. Built on Python's own `ast`.
+"""
+
+__version__ = "0.1.0"
+
+from .models import Finding
+
+__all__ = ["Finding", "__version__"]

overllm/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

overllm/analyze.py

@@ -0,0 +1,118 @@
+"""Walk files, parse them, run rules, and apply suppression + config."""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+
+from .config import DEFAULT_EXCLUDES, Config
+from .detector import find_llm_calls
+from .models import Finding
+from .rules import run_rules
+
+# `# overllm: ignore` or `# overllm: ignore=rule-a,rule-b`
+_IGNORE_RE = re.compile(r"#\s*overllm:\s*ignore(?:=([\w\-,\s]+))?")
+_IGNORE_FILE_RE = re.compile(r"#\s*overllm:\s*ignore-file\b")
+
+
+def iter_python_files(paths: list[str], excludes: tuple[str, ...]) -> list[Path]:
+    all_excludes = set(DEFAULT_EXCLUDES) | set(excludes)
+
+    def excluded(p: Path) -> bool:
+        parts = set(p.parts)
+        if parts & set(DEFAULT_EXCLUDES):
+            return True
+        s = str(p)
+        return any(ex and ex in s for ex in excludes)
+
+    out: list[Path] = []
+    for raw in paths:
+        p = Path(raw)
+        if p.is_file():
+            if p.suffix == ".py" and not excluded(p):
+                out.append(p)
+        elif p.is_dir():
+            for f in sorted(p.rglob("*.py")):
+                if not excluded(f):
+                    out.append(f)
+    # dedupe, keep order
+    seen: set[str] = set()
+    uniq: list[Path] = []
+    for f in out:
+        r = str(f.resolve())
+        if r not in seen:
+            seen.add(r)
+            uniq.append(f)
+    return uniq
+
+
+def _line_directives(lines: list[str]) -> tuple[bool, dict[int, set[str] | None]]:
+    """Return (ignore_whole_file, {line_no: None-for-all | set-of-rule-ids})."""
+    per_line: dict[int, set[str] | None] = {}
+    ignore_file = False
+    for i, line in enumerate(lines, start=1):
+        if _IGNORE_FILE_RE.search(line):
+            ignore_file = True
+        m = _IGNORE_RE.search(line)
+        if m:
+            raw = m.group(1)
+            if raw:
+                per_line[i] = {r.strip() for r in raw.split(",") if r.strip()}
+            else:
+                per_line[i] = None  # ignore all rules on this line
+    return ignore_file, per_line
+
+
+def _suppressed(finding: Finding, node_lines: range, per_line: dict[int, set[str] | None]) -> bool:
+    # a directive on any physical line of the call (or the line above it) suppresses it
+    candidate_lines = set(node_lines) | {finding.line, finding.line - 1}
+    for ln in candidate_lines:
+        if ln in per_line:
+            rules = per_line[ln]
+            if rules is None or finding.rule in rules:
+                return True
+    return False
+
+
+def analyze_file(path: Path, config: Config) -> list[Finding]:
+    try:
+        source = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError:
+        return []  # not our job to report parse errors; stay quiet
+
+    lines = source.splitlines()
+    ignore_file, per_line = _line_directives(lines)
+    if ignore_file:
+        return []
+
+    calls = find_llm_calls(tree, lines)
+    findings: list[Finding] = []
+    seen: set[tuple] = set()
+    display_path = str(path)
+    for call in calls:
+        node_start = getattr(call.node, "lineno", call.line)
+        node_end = getattr(call.node, "end_lineno", node_start) or node_start
+        node_lines = range(node_start, node_end + 1)
+        for f in run_rules(call, display_path):
+            if not config.enabled(f.rule):
+                continue
+            if f.key in seen:
+                continue
+            if _suppressed(f, node_lines, per_line):
+                continue
+            seen.add(f.key)
+            findings.append(f)
+    return findings
+
+
+def analyze_paths(paths: list[str], config: Config) -> list[Finding]:
+    findings: list[Finding] = []
+    for f in iter_python_files(paths, config.exclude):
+        findings.extend(analyze_file(f, config))
+    findings.sort(key=lambda x: (x.path, x.line, x.col, x.rule))
+    return findings

overllm/cli.py

@@ -0,0 +1,64 @@
+"""Command-line entry point for overllm."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .analyze import analyze_paths
+from .config import load_config
+from .report import render
+from .rules import ALL_RULES
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="overllm",
+        description="Catch the LLM/AI calls you didn't need. Flags LLM API calls "
+        "where deterministic code is simpler, cheaper, and more reliable.",
+    )
+    p.add_argument("paths", nargs="*", default=["."], help="files or directories to scan (default: .)")
+    p.add_argument("--format", choices=["human", "json", "sarif", "markdown"], default="human")
+    p.add_argument("--select", help="comma-separated rule ids to run (default: all)")
+    p.add_argument("--ignore", help="comma-separated rule ids to skip")
+    p.add_argument("--config", type=Path, help="path to a config file (pyproject.toml or .overllm.toml)")
+    p.add_argument("--exit-zero", action="store_true", help="always exit 0, even when findings exist")
+    p.add_argument("--no-color", action="store_true", help="disable ANSI colors")
+    p.add_argument("--version", action="version", version=f"overllm {__version__}")
+    return p
+
+
+def _split(value: str | None) -> tuple[str, ...]:
+    if not value:
+        return ()
+    return tuple(v.strip() for v in value.split(",") if v.strip())
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    paths = args.paths or ["."]
+
+    config = load_config(explicit=args.config)
+    select = _split(args.select)
+    if select:
+        config.select = tuple(r for r in select if r in ALL_RULES) or ALL_RULES
+    ignore = _split(args.ignore)
+    if ignore:
+        config.ignore = tuple(set(config.ignore) | set(ignore))
+
+    findings = analyze_paths(paths, config)
+
+    use_color = sys.stdout.isatty() and not args.no_color
+    output = render(findings, args.format, use_color=use_color)
+    if output:
+        print(output)
+
+    if args.exit_zero:
+        return 0
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

overllm/config.py

@@ -0,0 +1,66 @@
+"""Configuration loading from pyproject.toml [tool.overllm] or .overllm.toml."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+try:  # tomllib is stdlib on 3.11+; config files are simply ignored below it
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover
+    tomllib = None
+
+from .rules import ALL_RULES
+
+DEFAULT_EXCLUDES = (
+    ".git", ".hg", ".svn", "__pycache__", ".venv", "venv", "env",
+    "node_modules", "build", "dist", ".mypy_cache", ".pytest_cache",
+    ".tox", "site-packages", ".eggs",
+)
+
+
+@dataclass
+class Config:
+    select: tuple[str, ...] = ALL_RULES
+    ignore: tuple[str, ...] = ()
+    exclude: tuple[str, ...] = ()
+
+    def enabled(self, rule: str) -> bool:
+        return rule in self.select and rule not in self.ignore
+
+
+def _read_table(path: Path) -> dict:
+    if tomllib is None:
+        return {}
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return {}
+    if path.name == "pyproject.toml":
+        return data.get("tool", {}).get("overllm", {}) or {}
+    return data
+
+
+def load_config(start: Path | None = None, explicit: Path | None = None) -> Config:
+    table: dict = {}
+    if explicit is not None:
+        table = _read_table(explicit)
+    else:
+        base = (start or Path.cwd()).resolve()
+        for parent in [base, *base.parents]:
+            for name in (".overllm.toml", "pyproject.toml"):
+                p = parent / name
+                if p.is_file():
+                    t = _read_table(p)
+                    if t or name == ".overllm.toml":
+                        table = t
+                        break
+            if table:
+                break
+
+    select = tuple(table.get("select", ALL_RULES))
+    ignore = tuple(table.get("ignore", ()))
+    exclude = tuple(table.get("exclude", ()))
+    # keep only known rule ids in select, so a typo does not silently disable everything
+    select = tuple(r for r in select if r in ALL_RULES) or ALL_RULES
+    return Config(select=select, ignore=ignore, exclude=exclude)

overllm/detector.py

@@ -0,0 +1,435 @@
+"""Detect LLM/AI API calls in a Python AST and extract their prompt.
+
+Deterministic and conservative: a call is only treated as an LLM call when it
+matches a known SDK signature (or a raw HTTP request to a known LLM host). The
+known-SDK surface is the precision anchor - we would rather miss an exotic
+wrapper than false-positive on an unrelated `.create()`.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+# --- Known call surfaces -----------------------------------------------------
+
+# Method-call suffixes (trailing attribute names). Matched against the tail of
+# the call's attribute chain, so the receiver variable name does not matter:
+# `client.chat.completions.create`, `self.oai.chat.completions.create`, etc.
+LLM_METHOD_SUFFIXES = (
+    ("chat", "completions", "create"),
+    ("chat", "completions", "parse"),
+    ("completions", "create"),
+    ("responses", "create"),
+    ("responses", "parse"),
+    ("messages", "create"),
+    ("messages", "stream"),
+    ("chat", "create"),
+    ("chat", "complete"),
+    ("models", "generate_content"),
+    ("generate_content",),
+)
+
+# Legacy module-level surfaces: openai.ChatCompletion.create, Completion.create.
+LLM_LEGACY_SUFFIXES = (
+    ("ChatCompletion", "create"),
+    ("ChatCompletion", "acreate"),
+    ("Completion", "create"),
+    ("Completion", "acreate"),
+)
+
+# Fully-qualified free/dotted calls.
+LLM_DOTTED_FQNS = {
+    "litellm.completion",
+    "litellm.acompletion",
+    "ollama.chat",
+    "ollama.generate",
+}
+
+# Bare free functions, only when imported from one of these modules.
+LLM_FREE_FUNCS = {
+    "completion": {"litellm"},
+    "acompletion": {"litellm"},
+}
+
+# Constructors that produce an LLM/chat object (mostly LangChain + SDK clients).
+LLM_CONSTRUCTORS = {
+    "ChatOpenAI", "AzureChatOpenAI", "OpenAI", "AzureOpenAI", "AsyncOpenAI",
+    "ChatAnthropic", "Anthropic", "AsyncAnthropic", "AnthropicVertex",
+    "ChatGoogleGenerativeAI", "GenerativeModel", "ChatVertexAI",
+    "ChatMistralAI", "MistralClient", "Mistral",
+    "ChatCohere", "ChatGroq", "ChatOllama", "OllamaLLM", "ChatBedrock",
+    "ChatLiteLLM", "LlamaCpp", "HuggingFaceHub", "LLMChain",
+}
+
+# Methods on a tracked LLM object that count as a call.
+LLM_OBJ_METHODS = {
+    "invoke", "ainvoke", "stream", "astream", "batch", "abatch",
+    "predict", "apredict", "generate", "agenerate", "complete", "acomplete",
+    "run", "call", "generate_content",
+}
+
+# Hosts that identify a raw-HTTP LLM request.
+LLM_HOSTS = (
+    "api.openai.com", "api.anthropic.com", "generativelanguage.googleapis.com",
+    "api.mistral.ai", "api.cohere.ai", "api.cohere.com", "api.groq.com",
+    "openrouter.ai", "api.together.xyz", "api.deepseek.com", "api.perplexity.ai",
+    "api.x.ai", ":11434",  # ollama default port
+)
+
+# Kwargs that all LLM chat/completion calls carry - used as a precision guard so
+# an unrelated `.messages.create()` (e.g. an ORM) is not mistaken for an LLM call.
+LLM_KWARGS = {"model", "messages", "prompt", "input", "contents"}
+
+LOOP_NODES = (ast.For, ast.AsyncFor, ast.comprehension)
+FUNC_NODES = (ast.FunctionDef, ast.AsyncFunctionDef)
+
+
+@dataclass
+class LLMCall:
+    node: ast.Call
+    line: int
+    col: int
+    api: str                      # openai_like | anthropic | google | positional | ollama_chat | ollama_generate | http
+    prompt_text: str = ""         # lowercased visible literal text of the user prompt
+    prompt_static: bool = False   # the user prompt is a compile-time constant
+    prompt_resolved: bool = False # we could locate and read the user prompt
+    in_loop: bool = False
+    snippet: str = ""
+
+
+# --- AST helpers -------------------------------------------------------------
+
+def _trailing_attrs(func: ast.expr) -> tuple[ast.expr, tuple[str, ...]]:
+    attrs: list[str] = []
+    node = func
+    while isinstance(node, ast.Attribute):
+        attrs.append(node.attr)
+        node = node.value
+    attrs.reverse()
+    return node, tuple(attrs)
+
+
+def _dotted(node: ast.expr) -> str | None:
+    parts: list[str] = []
+    while isinstance(node, ast.Attribute):
+        parts.append(node.attr)
+        node = node.value
+    if isinstance(node, ast.Name):
+        parts.append(node.id)
+        parts.reverse()
+        return ".".join(parts)
+    return None
+
+
+def _ctor_name(call: ast.Call) -> str | None:
+    f = call.func
+    if isinstance(f, ast.Name):
+        return f.id
+    if isinstance(f, ast.Attribute):
+        return f.attr
+    return None
+
+
+def _kw(call: ast.Call, name: str) -> ast.expr | None:
+    for k in call.keywords:
+        if k.arg == name:
+            return k.value
+    return None
+
+
+def _has_llm_kwarg(call: ast.Call) -> bool:
+    return any(k.arg in LLM_KWARGS for k in call.keywords)
+
+
+def _const_str(node: ast.expr | None) -> str | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def _dict_get(d: ast.Dict, key: str) -> ast.expr | None:
+    for k, v in zip(d.keys, d.values):
+        if _const_str(k) == key:
+            return v
+    return None
+
+
+def _literal_text_and_static(node: ast.expr) -> tuple[str, bool]:
+    """Collect the visible literal text of an expression and whether it is fully static.
+
+    Handles string literals, f-strings, `+` concatenation, `.format()` and `%`
+    templates, and lists/tuples of the above. Any variable, call, or interpolated
+    value makes it non-static (but we still keep literal siblings for keyword
+    matching).
+    """
+    texts: list[str] = []
+    static = True
+
+    def walk(n: ast.expr) -> None:
+        nonlocal static
+        if isinstance(n, ast.Constant):
+            if isinstance(n.value, str):
+                texts.append(n.value)
+        elif isinstance(n, ast.JoinedStr):
+            for v in n.values:
+                if isinstance(v, ast.Constant) and isinstance(v.value, str):
+                    texts.append(v.value)
+                elif isinstance(v, ast.FormattedValue):
+                    static = False
+                else:
+                    walk(v)
+        elif isinstance(n, ast.BinOp):
+            if isinstance(n.op, ast.Add):
+                walk(n.left)
+                walk(n.right)
+            elif isinstance(n.op, ast.Mod):
+                walk(n.left)  # the template string
+                static = False
+            else:
+                static = False
+        elif isinstance(n, (ast.List, ast.Tuple)):
+            for e in n.elts:
+                walk(e)
+        elif isinstance(n, ast.Call):
+            f = n.func
+            if (
+                isinstance(f, ast.Attribute)
+                and f.attr in ("format", "join", "strip")
+                and isinstance(f.value, ast.Constant)
+                and isinstance(f.value.value, str)
+            ):
+                texts.append(f.value.value)
+            static = False
+        else:
+            static = False
+
+    walk(node)
+    return " ".join(texts).lower().strip(), static
+
+
+def _messages_user_prompt(msgs: ast.expr) -> tuple[list[ast.expr], bool]:
+    """Extract the `content` of user-role messages from a `messages=[...]` list.
+
+    Returns (content_nodes, resolved). resolved is False when the messages list
+    is a variable or otherwise not a static list of dict literals with constant
+    roles - in which case we stay silent rather than guess.
+    """
+    if not isinstance(msgs, ast.List):
+        return [], False
+    contents: list[ast.expr] = []
+    for el in msgs.elts:
+        if not isinstance(el, ast.Dict):
+            return [], False
+        role = _const_str(_dict_get(el, "role"))
+        content = _dict_get(el, "content")
+        if role is None:
+            return [], False
+        if role == "user" and content is not None:
+            contents.append(content)
+    return contents, True
+
+
+# --- Prompt extraction per API shape ----------------------------------------
+
+def _extract_prompt(call: ast.Call, api: str) -> tuple[str, bool, bool]:
+    """Return (prompt_text_lower, is_static, resolved) for a detected LLM call."""
+    nodes: list[ast.expr] = []
+    resolved = True
+
+    if api in ("openai_like", "anthropic", "ollama_chat"):
+        messages = _kw(call, "messages")
+        if messages is not None:
+            nodes, resolved = _messages_user_prompt(messages)
+        else:
+            single = _kw(call, "prompt") or _kw(call, "input")
+            if single is None and call.args:
+                single = call.args[0]
+            if single is not None:
+                nodes = [single]
+            else:
+                resolved = False
+    elif api == "ollama_generate":
+        single = _kw(call, "prompt") or (call.args[0] if call.args else None)
+        if single is None:
+            resolved = False
+        else:
+            nodes = [single]
+    elif api == "google":
+        single = _kw(call, "contents") or (call.args[0] if call.args else None)
+        if single is None:
+            resolved = False
+        else:
+            nodes = [single]
+    elif api == "positional":
+        single = _kw(call, "input") or (call.args[0] if call.args else None)
+        if single is None:
+            resolved = False
+        else:
+            nodes = [single]
+    else:  # http / generic - prompt not statically inspectable
+        return "", False, False
+
+    if not resolved or not nodes:
+        return "", False, resolved and bool(nodes)
+
+    texts = []
+    static = True
+    for n in nodes:
+        t, s = _literal_text_and_static(n)
+        if t:
+            texts.append(t)
+        static = static and s
+    return " ".join(texts).strip(), static, True
+
+
+# --- Import / variable context ----------------------------------------------
+
+class _Context:
+    def __init__(self) -> None:
+        self.free_llm_names: set[str] = set()   # bare names that are LLM free funcs
+        self.llm_vars: set[str] = set()         # dotted names bound to an LLM object
+
+    def scan(self, tree: ast.AST) -> None:
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.module:
+                for alias in node.names:
+                    fn = alias.name
+                    mods = LLM_FREE_FUNCS.get(fn)
+                    if mods and node.module.split(".")[0] in mods:
+                        self.free_llm_names.add(alias.asname or fn)
+            elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+                value = node.value
+                if isinstance(value, ast.Call) and _ctor_name(value) in LLM_CONSTRUCTORS:
+                    targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+                    for t in targets:
+                        d = _dotted(t)
+                        if d:
+                            self.llm_vars.add(d)
+
+
+# --- Classification ----------------------------------------------------------
+
+_SUFFIX_API = {
+    ("chat", "completions", "create"): "openai_like",
+    ("chat", "completions", "parse"): "openai_like",
+    ("completions", "create"): "openai_like",
+    ("responses", "create"): "openai_like",
+    ("responses", "parse"): "openai_like",
+    ("messages", "create"): "anthropic",
+    ("messages", "stream"): "anthropic",
+    ("chat", "create"): "openai_like",
+    ("chat", "complete"): "openai_like",
+    ("models", "generate_content"): "google",
+    ("generate_content",): "google",
+}
+
+
+def _classify(call: ast.Call, ctx: _Context) -> str | None:
+    base, attrs = _trailing_attrs(call.func)
+
+    # 1. Known method suffixes (need an LLM-shaped kwarg as a precision guard).
+    for suf in LLM_METHOD_SUFFIXES:
+        if len(attrs) >= len(suf) and attrs[-len(suf):] == suf:
+            if suf == ("generate_content",) or _has_llm_kwarg(call) or call.args:
+                return _SUFFIX_API[suf]
+
+    # 2. Legacy module-level completion APIs.
+    for suf in LLM_LEGACY_SUFFIXES:
+        if len(attrs) >= len(suf) and attrs[-len(suf):] == suf:
+            return "openai_like"
+
+    # 3. LangChain / SDK object methods on a tracked LLM variable.
+    if attrs and attrs[-1] in LLM_OBJ_METHODS and isinstance(call.func, ast.Attribute):
+        recv = _dotted(call.func.value)
+        if recv in ctx.llm_vars:
+            return "positional"
+
+    # 4. Bare free functions imported from a known LLM module.
+    if isinstance(call.func, ast.Name) and call.func.id in ctx.free_llm_names:
+        return "openai_like"
+
+    # 5. Fully-qualified free/dotted calls.
+    d = _dotted(call.func)
+    if d in LLM_DOTTED_FQNS:
+        if d == "ollama.generate":
+            return "ollama_generate"
+        if d == "ollama.chat":
+            return "ollama_chat"
+        return "openai_like"
+
+    # 6. Raw HTTP to a known LLM host.
+    if attrs and attrs[-1] == "post" and _has_llm_host_arg(call):
+        return "http"
+
+    return None
+
+
+def _has_llm_host_arg(call: ast.Call) -> bool:
+    strings: list[str] = []
+    for a in call.args:
+        s = _const_str(a)
+        if s:
+            strings.append(s)
+    for k in call.keywords:
+        s = _const_str(k.value)
+        if s:
+            strings.append(s)
+    joined = " ".join(strings).lower()
+    return any(host in joined for host in LLM_HOSTS)
+
+
+# --- Loop ancestry -----------------------------------------------------------
+
+def _build_parents(tree: ast.AST) -> dict[int, ast.AST]:
+    parents: dict[int, ast.AST] = {}
+    for node in ast.walk(tree):
+        for child in ast.iter_child_nodes(node):
+            parents[id(child)] = node
+    return parents
+
+
+def _in_loop(node: ast.AST, parents: dict[int, ast.AST]) -> bool:
+    cur = parents.get(id(node))
+    while cur is not None:
+        if isinstance(cur, FUNC_NODES):
+            return False
+        if isinstance(cur, (ast.For, ast.AsyncFor)):
+            return True
+        if isinstance(cur, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
+            return True
+        cur = parents.get(id(cur))
+    return False
+
+
+# --- Entry point -------------------------------------------------------------
+
+def find_llm_calls(tree: ast.AST, source_lines: list[str]) -> list[LLMCall]:
+    ctx = _Context()
+    ctx.scan(tree)
+    parents = _build_parents(tree)
+
+    calls: list[LLMCall] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        api = _classify(node, ctx)
+        if api is None:
+            continue
+        text, static, resolved = _extract_prompt(node, api)
+        line = getattr(node, "lineno", 0)
+        snippet = source_lines[line - 1].strip() if 0 < line <= len(source_lines) else ""
+        calls.append(
+            LLMCall(
+                node=node,
+                line=line,
+                col=getattr(node, "col_offset", 0),
+                api=api,
+                prompt_text=text,
+                prompt_static=static,
+                prompt_resolved=resolved,
+                in_loop=_in_loop(node, parents),
+                snippet=snippet,
+            )
+        )
+    return calls

overllm/models.py

@@ -0,0 +1,29 @@
+"""Core data types shared across overllm."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+SEVERITIES = ("error", "warning", "info")
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One flagged LLM call.
+
+    A finding always names a concrete deterministic replacement in `suggestion`.
+    The rule fires only on an observable code pattern, never on taste.
+    """
+
+    path: str
+    line: int
+    col: int
+    rule: str
+    message: str
+    suggestion: str = ""
+    severity: str = "warning"
+    snippet: str = ""
+
+    @property
+    def key(self) -> tuple:
+        return (self.path, self.line, self.col, self.rule)

overllm/report.py

@@ -0,0 +1,157 @@
+"""Output formatters: human, json, sarif, markdown (for the PR comment)."""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+
+from . import __version__
+from .models import Finding
+
+_COLORS = {
+    "reset": "\033[0m",
+    "dim": "\033[2m",
+    "bold": "\033[1m",
+    "yellow": "\033[33m",
+    "cyan": "\033[36m",
+    "green": "\033[32m",
+}
+
+_RULE_HELP = "https://github.com/theadamdanielsson/overllm#rules"
+
+
+def _c(name: str, use_color: bool) -> str:
+    return _COLORS[name] if use_color else ""
+
+
+def format_human(findings: list[Finding], use_color: bool = True) -> str:
+    if not findings:
+        return f"{_c('green', use_color)}overllm: no needless LLM calls found.{_c('reset', use_color)}"
+    lines: list[str] = []
+    for f in findings:
+        loc = f"{f.path}:{f.line}:{f.col + 1}"
+        lines.append(
+            f"{_c('bold', use_color)}{loc}{_c('reset', use_color)} "
+            f"{_c('yellow', use_color)}{f.rule}{_c('reset', use_color)}  {f.message}"
+        )
+        if f.snippet:
+            lines.append(f"    {_c('dim', use_color)}{f.snippet}{_c('reset', use_color)}")
+        if f.suggestion:
+            lines.append(f"    {_c('cyan', use_color)}-> {f.suggestion}{_c('reset', use_color)}")
+        lines.append("")
+    n = len(findings)
+    files = len({f.path for f in findings})
+    lines.append(
+        f"{_c('bold', use_color)}{n} needless LLM call{'s' if n != 1 else ''} "
+        f"in {files} file{'s' if files != 1 else ''}.{_c('reset', use_color)}"
+    )
+    return "\n".join(lines)
+
+
+def format_json(findings: list[Finding]) -> str:
+    payload = [
+        {
+            "path": f.path,
+            "line": f.line,
+            "col": f.col,
+            "rule": f.rule,
+            "message": f.message,
+            "suggestion": f.suggestion,
+            "severity": f.severity,
+            "snippet": f.snippet,
+        }
+        for f in findings
+    ]
+    return json.dumps(payload, indent=2)
+
+
+def format_sarif(findings: list[Finding]) -> str:
+    rule_ids = sorted({f.rule for f in findings})
+    rules = [
+        {
+            "id": rid,
+            "name": rid,
+            "shortDescription": {"text": f"overllm {rid}"},
+            "helpUri": _RULE_HELP,
+        }
+        for rid in rule_ids
+    ]
+    results = [
+        {
+            "ruleId": f.rule,
+            "level": "warning",
+            "message": {"text": f"{f.message}. {f.suggestion}".strip()},
+            "locations": [
+                {
+                    "physicalLocation": {
+                        "artifactLocation": {"uri": f.path},
+                        "region": {"startLine": max(f.line, 1), "startColumn": f.col + 1},
+                    }
+                }
+            ],
+        }
+        for f in findings
+    ]
+    sarif = {
+        "version": "2.1.0",
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "overllm",
+                        "version": __version__,
+                        "informationUri": "https://github.com/theadamdanielsson/overllm",
+                        "rules": rules,
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }
+    return json.dumps(sarif, indent=2)
+
+
+_MARKER = "<!-- overllm-report -->"
+
+
+def format_markdown(findings: list[Finding]) -> str:
+    """One grounded PR comment. Humble, cites each line, silent posting handled upstream."""
+    if not findings:
+        return ""
+    n = len(findings)
+    by_file: dict[str, list[Finding]] = defaultdict(list)
+    for f in findings:
+        by_file[f.path].append(f)
+
+    out = [
+        _MARKER,
+        f"### \U0001f9f9 overllm found {n} LLM call{'s' if n != 1 else ''} that plain code could handle",
+        "",
+        "Each of these calls an AI model to do something a library or a few lines of code do "
+        "faster, cheaper, and deterministically. Worth a look, not gospel - "
+        "add `# overllm: ignore` on a line to silence a false positive.",
+        "",
+    ]
+    for path in sorted(by_file):
+        out.append(f"**`{path}`**")
+        for f in by_file[path]:
+            out.append(f"- `L{f.line}` **{f.rule}** - {f.message}.")
+            if f.suggestion:
+                out.append(f"  -> {f.suggestion}")
+        out.append("")
+    out.append(
+        "<sub>Flagged by [overllm](https://github.com/theadamdanielsson/overllm) - "
+        "it only reports calls where deterministic code wins, and stays silent otherwise.</sub>"
+    )
+    return "\n".join(out)
+
+
+def render(findings: list[Finding], fmt: str, use_color: bool = True) -> str:
+    if fmt == "json":
+        return format_json(findings)
+    if fmt == "sarif":
+        return format_sarif(findings)
+    if fmt == "markdown":
+        return format_markdown(findings)
+    return format_human(findings, use_color=use_color)

overllm/rules.py

@@ -0,0 +1,137 @@
+"""The rule set. Every rule keys off an observable code pattern, not taste, and
+every finding names a concrete deterministic replacement.
+
+v1 is deliberately about one thing: LLM calls you did not need. It does not do
+generic complexity, dead code, or style - that ground is already covered by
+other tools, and it is where an opinionated linter turns into noise.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .detector import LLMCall
+from .models import Finding
+
+# Rule ids
+STATIC_PROMPT = "static-prompt"
+LLM_EXTRACTION = "llm-extraction"
+LLM_IN_LOOP = "llm-in-loop"
+LLM_MECHANICAL = "llm-mechanical"
+
+ALL_RULES = (STATIC_PROMPT, LLM_EXTRACTION, LLM_IN_LOOP, LLM_MECHANICAL)
+
+# (compiled pattern, human message, suggestion)
+_EXTRACTION_PATTERNS: list[tuple[re.Pattern, str, str]] = [
+    (re.compile(r"\bextract\b.*\b(e-?mail)\b"),
+     "asks the model to extract an email address",
+     "match it with a regex, or use the `email-validator` package"),
+    (re.compile(r"\bextract\b.*\b(url|link|hyperlink)\b"),
+     "asks the model to extract a URL",
+     "use a regex or `urllib.parse`"),
+    (re.compile(r"\b(extract|parse|get)\b.*\b(date|datetime|timestamp)\b"),
+     "asks the model to extract or parse a date",
+     "use `datetime.strptime` or `dateutil.parser`"),
+    (re.compile(r"\bextract\b.*\b(phone|number|integer|amount|price|digit)\b"),
+     "asks the model to extract a number",
+     "use a regex, then `int()` / `float()`"),
+    (re.compile(r"\b(return|reply|respond|output|answer)\b.*\bonly\b.*\bjson\b"),
+     "asks the model to return raw JSON",
+     "use the SDK's structured-output / JSON mode, or `json.loads` on typed fields"),
+    (re.compile(r"\bvalid\s+json\b|\bjson\s+format\b|\bas\s+json\b"),
+     "asks the model to format output as JSON",
+     "use `json.dumps`, or the SDK's structured-output mode"),
+    (re.compile(r"\bparse\b.*\b(the\s+)?(json|csv|xml|yaml|html)\b"),
+     "asks the model to parse a structured format",
+     "use `json` / `csv` / `xml` / a real parser"),
+]
+
+_MECHANICAL_PATTERNS: list[tuple[re.Pattern, str, str]] = [
+    (re.compile(r"\b(sort|order)\b.*\b(these|this|them|the (list|items|array|names|numbers))\b|\balphabetize\b"),
+     "asks the model to sort",
+     "use `sorted()`"),
+    (re.compile(r"\breverse\b.*\b(the\s+)?(string|list|order|text|these|it)\b"),
+     "asks the model to reverse a sequence",
+     "use `reversed()` or `[::-1]`"),
+    (re.compile(r"\bcount\b.*\b(the\s+)?(number of\s+)?(words|characters|letters|items|occurrences|lines|elements)\b"),
+     "asks the model to count",
+     "use `len()`, `str.count()`, or `collections.Counter`"),
+    (re.compile(r"\b(sum|add up|total|average|mean)\b.*\b(these|the)\b.*\b(numbers|values|amounts)\b|\bcalculate the (sum|total|average|mean)\b"),
+     "asks the model to do arithmetic over values",
+     "use `sum()` / `statistics.mean()`"),
+    (re.compile(r"\b(remove duplicates|deduplicate|de-duplicate|unique(\s+values)?)\b"),
+     "asks the model to deduplicate",
+     "use `set()` or `dict.fromkeys()`"),
+    (re.compile(r"\b(uppercase|lowercase|to upper|to lower|capitalize|title[- ]?case)\b"),
+     "asks the model to change letter case",
+     "use `str.upper()` / `.lower()` / `.title()`"),
+    (re.compile(r"\bbase64\b"),
+     "asks the model to base64 encode/decode",
+     "use the `base64` module"),
+    (re.compile(r"\b(what is|calculate|compute)\b[^.]*\b\d+\s*[-+*/x×]\s*\d+"),
+     "asks the model to compute arithmetic on literal numbers",
+     "just compute it in code"),
+    (re.compile(r"\bformat\b.*\b(the\s+)?date\b|\bconvert\b.*\bdate\b"),
+     "asks the model to format a date",
+     "use `datetime.strftime` / `strptime`"),
+    (re.compile(r"\b(pretty[- ]?print|minify|format)\b.*\bjson\b"),
+     "asks the model to reformat JSON",
+     "use `json.dumps(indent=...)`"),
+]
+
+_MIN_STATIC_LEN = 12  # ignore trivial/placeholder prompts for the static rule
+
+
+def _finding(call: LLMCall, path: str, rule: str, message: str, suggestion: str) -> Finding:
+    return Finding(
+        path=path,
+        line=call.line,
+        col=call.col,
+        rule=rule,
+        message=message,
+        suggestion=suggestion,
+        snippet=call.snippet,
+    )
+
+
+def run_rules(call: LLMCall, path: str) -> list[Finding]:
+    out: list[Finding] = []
+    text = call.prompt_text
+
+    # R1: fully static user prompt - constant input, so the call buys nothing.
+    if (
+        call.prompt_resolved
+        and call.prompt_static
+        and len(text) >= _MIN_STATIC_LEN
+        and re.search(r"[a-z]{3,}", text)
+    ):
+        out.append(_finding(
+            call, path, STATIC_PROMPT,
+            "LLM call with a fully static prompt (no variables). The input is "
+            "constant, so this pays latency, money, and nondeterminism for a fixed result",
+            "precompute or cache the result; if you meant to include runtime data, interpolate it",
+        ))
+
+    # R2: the prompt asks for something a parser/regex does deterministically.
+    if text:
+        for pat, msg, sug in _EXTRACTION_PATTERNS:
+            if pat.search(text):
+                out.append(_finding(call, path, LLM_EXTRACTION, "LLM call " + msg, sug))
+                break
+
+    # R4: the prompt asks for a mechanical transform with a stdlib one-liner.
+    if text:
+        for pat, msg, sug in _MECHANICAL_PATTERNS:
+            if pat.search(text):
+                out.append(_finding(call, path, LLM_MECHANICAL, "LLM call " + msg, sug))
+                break
+
+    # R3: an LLM call inside a loop - one API round-trip per iteration.
+    if call.in_loop:
+        out.append(_finding(
+            call, path, LLM_IN_LOOP,
+            "LLM call inside a loop: one API round-trip per iteration (N calls, N latencies, N times the cost)",
+            "batch the inputs into a single call, cache repeated results, or if the per-item work is deterministic use a function",
+        ))
+
+    return out

overllm-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: overllm
+Version: 0.1.0
+Summary: Catch the LLM/AI calls you didn't need. A fast, deterministic linter that flags LLM API calls where plain code is simpler, cheaper, and more reliable.
+Project-URL: Homepage, https://github.com/theadamdanielsson/overllm
+Project-URL: Issues, https://github.com/theadamdanielsson/overllm/issues
+Author-email: Adam Danielsson <the.adam.danielsson@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,code-quality,cost,linter,llm,openai,pre-commit,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# overllm
+
+**Catch the LLM/AI calls you didn't need.**
+
+overllm is a small, fast linter with one job: find the places in your code where you call an AI model to do something plain code does better. You called GPT to parse a date. You called a model to extract JSON that `json.loads` already handles. You are paying latency, money, and nondeterminism for a regex.
+
+It reads your code with Python's own `ast` module. No model runs, no network, no API key. Same code in, same result out. Fast enough for a pre-commit hook.
+
+Everyone else lints the code the AI wrote. overllm catches where you are paying an AI to do what a library already does.
+
+## Install
+
+```bash
+pip install overllm
+```
+
+## Use it
+
+```bash
+overllm .            # scan the current project
+overllm src/         # scan a folder
+overllm app.py       # scan one file
+```
+
+Example output:
+
+```
+app.py:42:5 llm-mechanical  LLM call asks the model to sort
+    resp = client.chat.completions.create(model="gpt-4o", messages=[...])
+    -> use sorted()
+
+app.py:88:1 llm-in-loop  LLM call inside a loop: one API round-trip per iteration
+    completion(model="gpt-4o", messages=[{"role": "user", "content": f"tag {x}"}])
+    -> batch the inputs into a single call, cache repeated results, or use a function
+
+2 needless LLM calls in 1 file.
+```
+
+overllm exits non-zero when it finds something, so it gates a commit or a CI check. Pass `--exit-zero` to report without failing.
+
+## Rules
+
+Every rule fires only on a concrete code pattern, and every finding names the deterministic replacement. It stays silent when it is not sure.
+
+| Rule | Fires when | Suggests |
+| --- | --- | --- |
+| `static-prompt` | The user prompt is a compile-time constant (no variables). The input is fixed, so the call buys nothing. | precompute or cache the result |
+| `llm-extraction` | The prompt asks the model to extract or parse an email, URL, date, number, or JSON. | a regex, `json`, `datetime`, or the SDK's structured-output mode |
+| `llm-mechanical` | The prompt asks for a mechanical transform: sort, reverse, count, sum, deduplicate, change case, base64, arithmetic on literals. | the one-line stdlib equivalent |
+| `llm-in-loop` | An LLM call sits inside a `for`/`async for`/comprehension. One API round-trip per iteration. | batch, cache, or move it out of the loop |
+
+It detects calls to the OpenAI, Anthropic, Google, Mistral, Cohere, Groq, LangChain, LiteLLM, and Ollama SDKs, and raw HTTP requests to those hosts.
+
+## Silence a false positive
+
+```python
+resp = client.chat.completions.create(...)  # overllm: ignore
+resp = client.chat.completions.create(...)  # overllm: ignore=llm-in-loop
+```
+
+Put `# overllm: ignore-file` at the top of a file to skip the whole file.
+
+## Configure
+
+In `pyproject.toml` (Python 3.11+):
+
+```toml
+[tool.overllm]
+ignore = ["llm-in-loop"]
+exclude = ["examples/", "migrations/"]
+```
+
+Or on the command line: `--select`, `--ignore`, `--exclude` via config, `--config PATH`.
+
+## Pre-commit hook
+
+In `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/theadamdanielsson/overllm
+    rev: v0.1.0
+    hooks:
+      - id: overllm
+```
+
+## GitHub Action
+
+overllm ships an Action that scans a pull request and leaves one grounded comment. It stays silent when there is nothing to say.
+
+```yaml
+name: overllm
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: theadamdanielsson/overllm@v1
+        with:
+          paths: "."
+```
+
+## Other output formats
+
+```bash
+overllm --format json .      # machine-readable
+overllm --format sarif .     # upload to GitHub code scanning
+overllm --format markdown .  # the PR-comment body
+```
+
+## Why not just use an AI code reviewer?
+
+AI reviewers and AI-slop linters look at the code the model produced: comments, dead code, structure. None of them ask the question overllm asks, which is whether you needed the model at all. It is a different axis, and it is one plain static analysis can answer with high precision and zero cost.
+
+## License
+
+MIT © Adam Danielsson

overllm-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+overllm/__init__.py,sha256=c0UnUFK21IKVMHsUtS87oWHLkKjPrAQO9E_6XDPYjuw,304
+overllm/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+overllm/analyze.py,sha256=1fCT_RfaHKsTUdsJkeuUN2Cfb0WHNTQhBWLWE7dpEd0,3903
+overllm/cli.py,sha256=mBsQ0LYl7_lWM_ozzDnFjvELagr9hpP0gH2phfwYQUs,2204
+overllm/config.py,sha256=s-wbiyyYKOKICRSi-6UNRiyUxSMBZn233bCHSA7q9Ho,2116
+overllm/detector.py,sha256=MoSxrpZWRR7mKwEkCI7-1MC4IbZQHKD_zJVQiMztt0c,14884
+overllm/models.py,sha256=cURoXxAfEmbFz6GiZeGVhIz8x-6vPe-PM_pX_oxvLH4,642
+overllm/report.py,sha256=Ki2RpmVEBI8EVQIhYGKgKZ6tLZky2J-QHhfSbYXyG9g,4947
+overllm/rules.py,sha256=B0Wk5-gCl841FXcNPz3p8uvl20X4T8_8DSuYS4vPtU4,5908
+overllm-0.1.0.dist-info/METADATA,sha256=6NBFTAvaSxGxW5OSFrz8wlpN7xYVoiiqVKv7QapPtBQ,5041
+overllm-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+overllm-0.1.0.dist-info/entry_points.txt,sha256=lYfnMFlT1ZxjxtIgzMxpqOMDa5NcjDoNaToSmeb1l6g,45
+overllm-0.1.0.dist-info/licenses/LICENSE,sha256=dJo02JmanV48uwAVydix7ep6cVMAmT1gY_yoWItnDXc,1072
+overllm-0.1.0.dist-info/RECORD,,

overllm-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

overllm-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+overllm = overllm.cli:main

overllm-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Danielsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.