overllm 0.1.0__tar.gz

overllm-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+*.log

overllm-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: overllm
+  name: overllm (flag needless LLM calls)
+  description: Flags LLM/AI API calls where deterministic code would be simpler, cheaper, and more reliable.
+  entry: overllm
+  language: python
+  types: [python]
+  require_serial: false

overllm-0.1.0/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.

overllm-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,124 @@
+# 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/action.yml

@@ -0,0 +1,71 @@
+name: "overllm"
+description: "Flag LLM/AI calls where deterministic code is simpler. Posts one grounded PR comment, silent when clean."
+author: "Adam Danielsson"
+branding:
+  icon: "scissors"
+  color: "yellow"
+
+inputs:
+  paths:
+    description: "Files or directories to scan."
+    required: false
+    default: "."
+  fail-on-findings:
+    description: "Fail the check (exit non-zero) when findings exist."
+    required: false
+    default: "true"
+  comment:
+    description: "Post a single grounded comment on the pull request."
+    required: false
+    default: "true"
+  github-token:
+    description: "Token used to post the PR comment. Needs pull-requests: write."
+    required: false
+    default: ${{ github.token }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install overllm
+      shell: bash
+      run: |
+        python3 -m venv "$RUNNER_TEMP/overllm-venv"
+        "$RUNNER_TEMP/overllm-venv/bin/python" -m pip install -q --upgrade pip
+        "$RUNNER_TEMP/overllm-venv/bin/python" -m pip install -q "$GITHUB_ACTION_PATH"
+
+    - name: Run overllm
+      id: scan
+      shell: bash
+      run: |
+        BIN="$RUNNER_TEMP/overllm-venv/bin/overllm"
+        set +e
+        "$BIN" --format markdown ${{ inputs.paths }} > "$RUNNER_TEMP/overllm.md"
+        echo "found=$?" >> "$GITHUB_OUTPUT"
+        "$BIN" ${{ inputs.paths }} --no-color
+        exit 0
+
+    - name: Comment on PR
+      if: ${{ inputs.comment == 'true' && github.event_name == 'pull_request' && steps.scan.outputs.found == '1' }}
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+        PR: ${{ github.event.pull_request.number }}
+        REPO: ${{ github.repository }}
+      run: |
+        marker="<!-- overllm-report -->"
+        existing=$(gh api "repos/$REPO/issues/$PR/comments" --paginate \
+          --jq ".[] | select(.body | contains(\"$marker\")) | .id" | head -1)
+        if [ -n "$existing" ]; then
+          gh api -X PATCH "repos/$REPO/issues/comments/$existing" \
+            -F body=@"$RUNNER_TEMP/overllm.md" >/dev/null
+        else
+          gh api -X POST "repos/$REPO/issues/$PR/comments" \
+            -F body=@"$RUNNER_TEMP/overllm.md" >/dev/null
+        fi
+
+    - name: Fail if findings
+      if: ${{ inputs.fail-on-findings == 'true' && steps.scan.outputs.found == '1' }}
+      shell: bash
+      run: |
+        echo "::error::overllm found LLM calls that plain code could handle. See the job log or PR comment."
+        exit 1

overllm-0.1.0/examples/needless_llm_calls.py

@@ -0,0 +1,53 @@
+"""Examples of LLM calls that plain code should handle. overllm flags every one.
+
+The last function is a legitimate call that overllm leaves alone.
+"""
+
+from openai import OpenAI
+from litellm import completion
+from langchain_openai import ChatOpenAI
+
+client = OpenAI()
+
+
+def greeting():
+    # static-prompt: the input is constant, so the call buys nothing
+    return client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "Write a short friendly greeting."}],
+    )
+
+
+def get_email(text):
+    # llm-extraction: an email is a regex, not a model call
+    return client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": f"Extract the email address from: {text}"}],
+    )
+
+
+def sort_names(names):
+    # llm-mechanical: this is sorted()
+    llm = ChatOpenAI(model="gpt-4o")
+    return llm.invoke(f"Sort these names alphabetically: {names}")
+
+
+def tag_all(items):
+    # llm-in-loop: one API round-trip per item
+    tags = []
+    for item in items:
+        tags.append(
+            completion(model="gpt-4o", messages=[{"role": "user", "content": f"Tag this: {item}"}])
+        )
+    return tags
+
+
+def draft_reply(message):
+    # legitimate: open-ended generation over real input. overllm stays silent.
+    return client.chat.completions.create(
+        model="gpt-4o",
+        messages=[
+            {"role": "system", "content": "You are a warm, concise support agent."},
+            {"role": "user", "content": f"The customer wrote: {message}. Draft a reply."},
+        ],
+    )

overllm-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "overllm"
+version = "0.1.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Adam Danielsson", email = "the.adam.danielsson@gmail.com" }]
+keywords = ["linter", "llm", "ai", "static-analysis", "pre-commit", "openai", "anthropic", "cost", "code-quality"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/theadamdanielsson/overllm"
+Issues = "https://github.com/theadamdanielsson/overllm/issues"
+
+[project.scripts]
+overllm = "overllm.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/overllm"]
+
+[tool.overllm]
+# example config; all optional
+# ignore = ["llm-in-loop"]
+# exclude = ["examples/", "tests/fixtures/"]

overllm-0.1.0/src/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-0.1.0/src/overllm/__main__.py

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

overllm-0.1.0/src/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-0.1.0/src/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())