depdesk 0.1.0__tar.gz

depdesk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wendel Ortiz
+
+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.

depdesk-0.1.0/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: depdesk
+Version: 0.1.0
+Summary: Know which of your model calls are on a clock.
+Author: Wendel Ortiz
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Ort0x36/deprecation-desk
+Project-URL: Source, https://github.com/Ort0x36/deprecation-desk
+Project-URL: Issues, https://github.com/Ort0x36/deprecation-desk/issues
+Project-URL: Changelog, https://github.com/Ort0x36/deprecation-desk/blob/main/CHANGELOG.md
+Keywords: llm,llmops,deprecation,model-deprecation,model-lifecycle,openai,anthropic,claude,gpt,ai-engineering,static-analysis,linter,cli,ci,migration,technical-debt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# depdesk
+
+**Know which of your model calls are on a clock.**
+
+[![ci](https://github.com/Ort0x36/deprecation-desk/actions/workflows/ci.yml/badge.svg)](https://github.com/Ort0x36/deprecation-desk/actions/workflows/ci.yml)
+[![pypi](https://img.shields.io/pypi/v/depdesk)](https://pypi.org/project/depdesk/)
+[![python](https://img.shields.io/badge/python-3.9%20to%203.13-blue)](https://www.python.org/downloads/)
+[![dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)](pyproject.toml)
+[![licence](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)
+
+Providers retire models on their schedule, not yours. The notice arrives by
+email, to one person, months before anything breaks, and then it is forgotten
+until a request starts failing in production. `depdesk` crosses the deprecation
+notices you did not read with the models your code actually calls, and fails
+your build while there is still time to do something about it.
+
+Zero dependencies. Python 3.9 or newer. Anthropic and OpenAI today, and any
+provider you write a catalog entry for.
+
+## Install
+
+```bash
+pip install depdesk
+```
+
+## Try it in thirty seconds
+
+```bash
+depdesk check .
+```
+
+That is the whole setup. Point it at a repository and it reports every model
+identifier it finds, crossed against the provider's published deprecation
+dates. There is a deliberately broken sample in
+[`examples/legacy-app`](examples/legacy-app) if you want to see a failing run
+before pointing it at your own code.
+
+```
+$ depdesk check . --fail-in 60
+depdesk: 2 files scanned in .
+catalog verified 2026-09-20 (2 days ago)
+
+ALREADY RETIRED
+
+  claude-opus-4-1-20250805
+      provider:    anthropic
+      retirement:  2026-08-05 (48 days ago)
+      announced:   2026-06-05
+      replacement: claude-opus-4-8
+      app/legacy.py:1: OLD = "claude-opus-4-1-20250805"
+
+RETIRES SOON
+
+  gpt-5.4-cyber
+      provider:    openai
+      retirement:  2026-10-01 (9 days left)
+      announced:   2026-09-11
+      replacement: gpt-5.6-cyber
+      app/legacy.py:2: CYBER = "gpt-5.4-cyber"
+
+DEPRECATED PARAMETERS
+
+  temperature
+      behaviour:   Returns a 400 error when set to a non-default value.
+      replacement: Omit the parameter and steer behaviour through prompting.
+      sdk:         The Python SDK (v1.0 and later) removes temperature, top_p
+                   and top_k, so passing them raises a TypeError.
+      app/legacy.py:9: temperature=0,
+          file also names: claude-opus-5
+
+Summary: 1 already retired, 1 retires soon.
+$ echo $?
+2
+```
+
+Every line of that output is real: it is the tool running against a two file
+sample, not a mockup.
+
+## What it finds
+
+**Models on a clock.** Identifiers written anywhere in the tree, including
+`.env` files and config, matched against the provider's own retirement dates.
+Each finding carries the announcement date, the retirement date, the
+replacement the provider names, and the exact lines where you use it.
+
+**Deprecated parameters.** Model retirement is the loud failure. The quiet one
+is a parameter that starts returning 400 on newer models while your code keeps
+passing it, which is what happened to `temperature`, `top_p` and `top_k` on
+Claude Opus 4.7 and later. No changelog files that under "deprecation", and
+nothing in your test suite catches it if your tests never hit the new model.
+`depdesk` parses your Python with the standard library `ast` module, so it
+finds the keyword argument itself, not a string that looks like one.
+
+**Endpoints and products** that the provider has put on notice, matched the
+same way.
+
+Where the provider's own wording is ambiguous about which models a rule covers,
+`depdesk` says so and downgrades the finding to review instead of guessing.
+
+## Put it in CI
+
+This is the point of the exit codes: the build starts failing the day a
+provider gives you notice, not the day the model dies.
+
+```yaml
+# .github/workflows/depdesk.yml
+name: model deprecations
+on:
+  push:
+  schedule:
+    - cron: "0 7 * * 1"   # Monday morning, so notice arrives before the deadline
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install depdesk
+      - run: depdesk check . --fail-in 60
+```
+
+| code | meaning |
+| --- | --- |
+| 0 | nothing needs attention |
+| 1 | something is deprecated, but outside the `--fail-in` window |
+| 2 | something is already retired, or retires within `--fail-in` |
+| 3 | the tool could not do its job |
+
+## Weight it by real traffic
+
+Scanning code tells you what is referenced. It does not tell you what is hot.
+Point `--usage` at an export and every finding gains a share of traffic, so you
+can tell a dead constant from 40% of production.
+
+```bash
+depdesk check . --usage usage.csv
+depdesk check . --usage usage.csv --usage-count-column input_tokens
+```
+
+```
+ALREADY RETIRED
+
+  claude-3-5-sonnet-20241022  [3.3% of measured calls]
+      provider:    anthropic
+      retirement:  2025-10-28 (329 days ago)
+      announced:   2025-08-13
+      replacement: claude-sonnet-4-6
+      seen in usage data but not found anywhere in the scanned tree
+
+  claude-opus-4-1-20250805  [15.3% of measured calls]
+      provider:    anthropic
+      retirement:  2026-08-05 (48 days ago)
+      announced:   2026-06-05
+      replacement: claude-opus-4-8
+      app/legacy.py:1: OLD = "claude-opus-4-1-20250805"
+```
+
+That first finding is the one worth the flag: a retired model still taking
+traffic from code that is not in this repository at all.
+
+For Anthropic: Claude Console, **Usage**, **Export**. The CSV has an API key
+column and a model column, and `depdesk` sniffs them. CSV and JSON both work.
+
+## Ask what breaks later
+
+```bash
+depdesk check . --today 2027-01-01
+```
+
+More useful than it sounds: it answers "what breaks over the holidays" before
+anyone leaves.
+
+## When a finding is not a finding
+
+Documentation, changelogs and migration notes legitimately name models that are
+dead. A tool you cannot silence on a line you have already judged is a tool
+people stop running, so there are two escapes, both deliberate:
+
+```python
+OLD = "claude-opus-4-1-20250805"  # depdesk: ignore
+```
+
+```bash
+depdesk check . --exclude "CHANGELOG.md" --exclude "*/migrations/*"
+```
+
+The marker silences one line, in any file type, in whatever comment syntax that
+file uses, because it is matched as text. `--exclude` takes a glob, matched
+against the path and the file name, and repeats. Neither has a project level
+config file on purpose: an ignore list nobody reads is how a tool like this
+starts lying.
+
+## Commands and flags
+
+```
+depdesk check [PATH ...]      scan a tree and report what is dying
+depdesk upstream              ask whether the provider pages moved
+depdesk list                  print the catalog
+```
+
+| flag on `check` | what it does |
+| --- | --- |
+| `--fail-in DAYS` | how close a retirement has to be to fail the build (default 90) |
+| `--sunset-in DAYS` | also report active models with an announced earliest retirement inside this window |
+| `--usage FILE` | weight findings by real call volume |
+| `--usage-model-column`, `--usage-count-column` | override the sniffed columns |
+| `--today YYYY-MM-DD` | ask what this repository looks like on a future date |
+| `--locations N` | how many source lines to print per finding (default 3) |
+| `--json` | machine readable output |
+| `--exclude GLOB` | skip paths matching this glob, repeatable |
+| `--no-unknown` | stop reporting identifiers the catalog does not know |
+| `--catalog FILE` | use your own catalog, for a provider we do not cover |
+
+## The catalog, and why you can trust it
+
+The only thing that makes this tool worth anything is whether the dates in it
+are true. So they are not hidden: [`depdesk/data/catalog.json`](depdesk/data/catalog.json)
+is plain JSON, every entry was transcribed from the provider's own page, and
+the file records when that happened. `depdesk check` prints a warning when the
+catalog is more than 30 days old.
+
+```bash
+depdesk upstream          # did the provider pages change since then?
+depdesk upstream --save   # record the current state as the new baseline
+```
+
+`upstream` does not parse the page into a catalog. An earlier version hashed
+the whole page and produced a different digest on three consecutive fetches of
+the same unchanged content, because provider docs carry per-request markup. So
+it extracts the model identifiers and the dates, compares those against the
+catalog, and prints what appeared and what disappeared. A human decides what it
+means. A scraper that half works would produce a catalog that looks maintained
+and is not, which is the exact failure this tool exists to prevent.
+
+`upstream` exits 1 when a page moved, 3 when it could not be fetched, and 0
+otherwise. It prints, but does not fail on, the identifiers a page names that
+the catalog does not mention: the OpenAI page alone names 35 of those and
+always will, because a deprecation page also lists models that are not being
+deprecated. That is a standing difference, not an event, and a weekly alarm
+that fires on it stops being read. Pass `--strict` if you do want those to
+fail.
+
+This repository runs `upstream` every Monday and
+[opens an issue](.github/workflows/catalog-drift.yml) when a provider page
+moves, so drift lands in front of a person instead of in a log nobody reads.
+
+## What it does not do
+
+Being plain about the limits, because the whole point is to be trustworthy:
+
+- **It does not know your provider's private schedule.** It knows what is on the
+  public deprecation pages, transcribed by hand.
+- **It only covers Anthropic and OpenAI today.** Other providers are a catalog
+  entry away, and pull requests are welcome. `--catalog` takes your own file.
+- **It finds identifiers written as text.** A model id assembled at runtime from
+  string pieces will not be found by the scanner. The `--usage` path catches
+  that case, which is part of why it exists.
+- **It reads `.env` files**, because that is where model configuration lives. It
+  prints only lines that matched a model identifier, but if that bothers you,
+  scan a narrower path.
+- **It will not edit your code.** Migrating a prompt is a judgement call and this
+  tool has no opinion about your prompts.
+
+## Contributing
+
+Catalog out of date? A pull request editing `depdesk/data/catalog.json` is the
+fastest path, and the diff is readable by anyone. Want a provider we do not
+cover? Open an issue with a link to their public deprecation page. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Development
+
+```bash
+python3 -m pytest -q tests/
+python3 -m depdesk check .
+```
+
+The test suite pins the behaviour that matters: that `gpt-4-turbo` does not
+match inside `gpt-4-turbo-preview`, that an active model stays silent, that the
+parameter rule needs an affected model in the same file before it fires, and
+that the fingerprint survives cosmetic markup changes but not a changed date.
+
+## Licence
+
+MIT. Built by [Wendel Ortiz](https://github.com/Ort0x36) while running an LLM
+product in production.

depdesk-0.1.0/README.md

@@ -0,0 +1,288 @@
+# depdesk
+
+**Know which of your model calls are on a clock.**
+
+[![ci](https://github.com/Ort0x36/deprecation-desk/actions/workflows/ci.yml/badge.svg)](https://github.com/Ort0x36/deprecation-desk/actions/workflows/ci.yml)
+[![pypi](https://img.shields.io/pypi/v/depdesk)](https://pypi.org/project/depdesk/)
+[![python](https://img.shields.io/badge/python-3.9%20to%203.13-blue)](https://www.python.org/downloads/)
+[![dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)](pyproject.toml)
+[![licence](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)
+
+Providers retire models on their schedule, not yours. The notice arrives by
+email, to one person, months before anything breaks, and then it is forgotten
+until a request starts failing in production. `depdesk` crosses the deprecation
+notices you did not read with the models your code actually calls, and fails
+your build while there is still time to do something about it.
+
+Zero dependencies. Python 3.9 or newer. Anthropic and OpenAI today, and any
+provider you write a catalog entry for.
+
+## Install
+
+```bash
+pip install depdesk
+```
+
+## Try it in thirty seconds
+
+```bash
+depdesk check .
+```
+
+That is the whole setup. Point it at a repository and it reports every model
+identifier it finds, crossed against the provider's published deprecation
+dates. There is a deliberately broken sample in
+[`examples/legacy-app`](examples/legacy-app) if you want to see a failing run
+before pointing it at your own code.
+
+```
+$ depdesk check . --fail-in 60
+depdesk: 2 files scanned in .
+catalog verified 2026-09-20 (2 days ago)
+
+ALREADY RETIRED
+
+  claude-opus-4-1-20250805
+      provider:    anthropic
+      retirement:  2026-08-05 (48 days ago)
+      announced:   2026-06-05
+      replacement: claude-opus-4-8
+      app/legacy.py:1: OLD = "claude-opus-4-1-20250805"
+
+RETIRES SOON
+
+  gpt-5.4-cyber
+      provider:    openai
+      retirement:  2026-10-01 (9 days left)
+      announced:   2026-09-11
+      replacement: gpt-5.6-cyber
+      app/legacy.py:2: CYBER = "gpt-5.4-cyber"
+
+DEPRECATED PARAMETERS
+
+  temperature
+      behaviour:   Returns a 400 error when set to a non-default value.
+      replacement: Omit the parameter and steer behaviour through prompting.
+      sdk:         The Python SDK (v1.0 and later) removes temperature, top_p
+                   and top_k, so passing them raises a TypeError.
+      app/legacy.py:9: temperature=0,
+          file also names: claude-opus-5
+
+Summary: 1 already retired, 1 retires soon.
+$ echo $?
+2
+```
+
+Every line of that output is real: it is the tool running against a two file
+sample, not a mockup.
+
+## What it finds
+
+**Models on a clock.** Identifiers written anywhere in the tree, including
+`.env` files and config, matched against the provider's own retirement dates.
+Each finding carries the announcement date, the retirement date, the
+replacement the provider names, and the exact lines where you use it.
+
+**Deprecated parameters.** Model retirement is the loud failure. The quiet one
+is a parameter that starts returning 400 on newer models while your code keeps
+passing it, which is what happened to `temperature`, `top_p` and `top_k` on
+Claude Opus 4.7 and later. No changelog files that under "deprecation", and
+nothing in your test suite catches it if your tests never hit the new model.
+`depdesk` parses your Python with the standard library `ast` module, so it
+finds the keyword argument itself, not a string that looks like one.
+
+**Endpoints and products** that the provider has put on notice, matched the
+same way.
+
+Where the provider's own wording is ambiguous about which models a rule covers,
+`depdesk` says so and downgrades the finding to review instead of guessing.
+
+## Put it in CI
+
+This is the point of the exit codes: the build starts failing the day a
+provider gives you notice, not the day the model dies.
+
+```yaml
+# .github/workflows/depdesk.yml
+name: model deprecations
+on:
+  push:
+  schedule:
+    - cron: "0 7 * * 1"   # Monday morning, so notice arrives before the deadline
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install depdesk
+      - run: depdesk check . --fail-in 60
+```
+
+| code | meaning |
+| --- | --- |
+| 0 | nothing needs attention |
+| 1 | something is deprecated, but outside the `--fail-in` window |
+| 2 | something is already retired, or retires within `--fail-in` |
+| 3 | the tool could not do its job |
+
+## Weight it by real traffic
+
+Scanning code tells you what is referenced. It does not tell you what is hot.
+Point `--usage` at an export and every finding gains a share of traffic, so you
+can tell a dead constant from 40% of production.
+
+```bash
+depdesk check . --usage usage.csv
+depdesk check . --usage usage.csv --usage-count-column input_tokens
+```
+
+```
+ALREADY RETIRED
+
+  claude-3-5-sonnet-20241022  [3.3% of measured calls]
+      provider:    anthropic
+      retirement:  2025-10-28 (329 days ago)
+      announced:   2025-08-13
+      replacement: claude-sonnet-4-6
+      seen in usage data but not found anywhere in the scanned tree
+
+  claude-opus-4-1-20250805  [15.3% of measured calls]
+      provider:    anthropic
+      retirement:  2026-08-05 (48 days ago)
+      announced:   2026-06-05
+      replacement: claude-opus-4-8
+      app/legacy.py:1: OLD = "claude-opus-4-1-20250805"
+```
+
+That first finding is the one worth the flag: a retired model still taking
+traffic from code that is not in this repository at all.
+
+For Anthropic: Claude Console, **Usage**, **Export**. The CSV has an API key
+column and a model column, and `depdesk` sniffs them. CSV and JSON both work.
+
+## Ask what breaks later
+
+```bash
+depdesk check . --today 2027-01-01
+```
+
+More useful than it sounds: it answers "what breaks over the holidays" before
+anyone leaves.
+
+## When a finding is not a finding
+
+Documentation, changelogs and migration notes legitimately name models that are
+dead. A tool you cannot silence on a line you have already judged is a tool
+people stop running, so there are two escapes, both deliberate:
+
+```python
+OLD = "claude-opus-4-1-20250805"  # depdesk: ignore
+```
+
+```bash
+depdesk check . --exclude "CHANGELOG.md" --exclude "*/migrations/*"
+```
+
+The marker silences one line, in any file type, in whatever comment syntax that
+file uses, because it is matched as text. `--exclude` takes a glob, matched
+against the path and the file name, and repeats. Neither has a project level
+config file on purpose: an ignore list nobody reads is how a tool like this
+starts lying.
+
+## Commands and flags
+
+```
+depdesk check [PATH ...]      scan a tree and report what is dying
+depdesk upstream              ask whether the provider pages moved
+depdesk list                  print the catalog
+```
+
+| flag on `check` | what it does |
+| --- | --- |
+| `--fail-in DAYS` | how close a retirement has to be to fail the build (default 90) |
+| `--sunset-in DAYS` | also report active models with an announced earliest retirement inside this window |
+| `--usage FILE` | weight findings by real call volume |
+| `--usage-model-column`, `--usage-count-column` | override the sniffed columns |
+| `--today YYYY-MM-DD` | ask what this repository looks like on a future date |
+| `--locations N` | how many source lines to print per finding (default 3) |
+| `--json` | machine readable output |
+| `--exclude GLOB` | skip paths matching this glob, repeatable |
+| `--no-unknown` | stop reporting identifiers the catalog does not know |
+| `--catalog FILE` | use your own catalog, for a provider we do not cover |
+
+## The catalog, and why you can trust it
+
+The only thing that makes this tool worth anything is whether the dates in it
+are true. So they are not hidden: [`depdesk/data/catalog.json`](depdesk/data/catalog.json)
+is plain JSON, every entry was transcribed from the provider's own page, and
+the file records when that happened. `depdesk check` prints a warning when the
+catalog is more than 30 days old.
+
+```bash
+depdesk upstream          # did the provider pages change since then?
+depdesk upstream --save   # record the current state as the new baseline
+```
+
+`upstream` does not parse the page into a catalog. An earlier version hashed
+the whole page and produced a different digest on three consecutive fetches of
+the same unchanged content, because provider docs carry per-request markup. So
+it extracts the model identifiers and the dates, compares those against the
+catalog, and prints what appeared and what disappeared. A human decides what it
+means. A scraper that half works would produce a catalog that looks maintained
+and is not, which is the exact failure this tool exists to prevent.
+
+`upstream` exits 1 when a page moved, 3 when it could not be fetched, and 0
+otherwise. It prints, but does not fail on, the identifiers a page names that
+the catalog does not mention: the OpenAI page alone names 35 of those and
+always will, because a deprecation page also lists models that are not being
+deprecated. That is a standing difference, not an event, and a weekly alarm
+that fires on it stops being read. Pass `--strict` if you do want those to
+fail.
+
+This repository runs `upstream` every Monday and
+[opens an issue](.github/workflows/catalog-drift.yml) when a provider page
+moves, so drift lands in front of a person instead of in a log nobody reads.
+
+## What it does not do
+
+Being plain about the limits, because the whole point is to be trustworthy:
+
+- **It does not know your provider's private schedule.** It knows what is on the
+  public deprecation pages, transcribed by hand.
+- **It only covers Anthropic and OpenAI today.** Other providers are a catalog
+  entry away, and pull requests are welcome. `--catalog` takes your own file.
+- **It finds identifiers written as text.** A model id assembled at runtime from
+  string pieces will not be found by the scanner. The `--usage` path catches
+  that case, which is part of why it exists.
+- **It reads `.env` files**, because that is where model configuration lives. It
+  prints only lines that matched a model identifier, but if that bothers you,
+  scan a narrower path.
+- **It will not edit your code.** Migrating a prompt is a judgement call and this
+  tool has no opinion about your prompts.
+
+## Contributing
+
+Catalog out of date? A pull request editing `depdesk/data/catalog.json` is the
+fastest path, and the diff is readable by anyone. Want a provider we do not
+cover? Open an issue with a link to their public deprecation page. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Development
+
+```bash
+python3 -m pytest -q tests/
+python3 -m depdesk check .
+```
+
+The test suite pins the behaviour that matters: that `gpt-4-turbo` does not
+match inside `gpt-4-turbo-preview`, that an active model stays silent, that the
+parameter rule needs an affected model in the same file before it fires, and
+that the fingerprint survives cosmetic markup changes but not a changed date.
+
+## Licence
+
+MIT. Built by [Wendel Ortiz](https://github.com/Ort0x36) while running an LLM
+product in production.

depdesk-0.1.0/depdesk/__init__.py

@@ -0,0 +1,3 @@
+"""depdesk: know which of your model calls are on a clock."""
+
+__version__ = "0.1.0"