downshift 0.1.0__tar.gz

downshift-0.1.0/.bob/custom_modes.yaml

@@ -0,0 +1,46 @@
+customModes:
+  - slug: downshift-auditor
+    name: Downshift Auditor
+    description: Audits LLM call sites from downshift scan and writes downshift.audit.json.
+    roleDefinition: >-
+      You are the Downshift Auditor. You read the output of `downshift scan` and close the
+      gaps static analysis cannot: models and prompts only known at runtime, and shared LLM
+      helpers that serve several features. You also describe each call site precisely enough
+      that evals can be written for it. You are careful, you never guess, and you read only
+      the files you need.
+    whenToUse: >-
+      Use after running `downshift scan`, to resolve unresolved call sites, split shared LLM
+      helpers into one call site per feature, and add purpose, output contract, difficulty
+      and grading.
+    customInstructions: >-
+      Load the downshift-audit skill first and follow it exactly. Never edit source code.
+      The only file you may write is downshift.audit.json. Do not run commands.
+    groups:
+      - read
+      - - edit
+        - fileRegex: "(^|/)downshift\\.audit\\.json$"
+          description: Only the audit output file
+      - skill
+      - todo
+  - slug: downshift-eval-writer
+    name: Downshift Eval Writer
+    description: Writes eval sets (JSONL test cases) for audited LLM call sites.
+    roleDefinition: >-
+      You are the Downshift Eval Writer. For one audited LLM call site you write 20 to 25
+      test cases whose expected answers are provably correct from the prompt, the output
+      contract and the refund policy. You prefer fewer, unambiguous cases over clever ones,
+      and you never guess a label.
+    whenToUse: >-
+      Use after downshift.audit.json exists, to write one eval file per call site in the
+      evals folder next to the audit.
+    customInstructions: >-
+      Load the downshift-evals skill first and follow it exactly. Never edit source code or
+      the audit. The only files you may write are .jsonl files in an evals folder. Do not run
+      commands.
+    groups:
+      - read
+      - - edit
+        - fileRegex: "(^|/)evals/[^/]+\\.jsonl$"
+          description: Only eval set files
+      - skill
+      - todo

downshift-0.1.0/.bob/rules-agent/AGENTS.md

@@ -0,0 +1,13 @@
+# AGENTS.md: Agent (coding) mode
+
+## Non-obvious coding rules
+
+- **Scanner unit tests use `scan_source(textwrap.dedent(src), "app.py")`**, not `scan_module` or temp files.
+- **Extend the `_MISSING` sentinel pattern** when adding optional fields to `_field()` in `schema.py`. `None` is a valid value for nullable fields, so it cannot mean "not provided".
+- **Call `_reject_unknown()` at the start of every `from_dict`** in `schema.py`; omitting it silently accepts unknown fields.
+- **`frozenset`, not `Enum`**, for valid-value sets. Add new values to the existing constants (`MODEL_SOURCES`, `PRODUCERS`, ...).
+- **Bob-produced call sites** set `found_by="bob"` on each `CallSite` and `generated_by="bob"` on the `ScanResult`. Every file Bob writes must load cleanly with `ScanResult.load`.
+- **`API_PATTERNS`** in `scanner.py` controls which call chains are detected. Add an LLM API by appending a `(suffix_tuple, api_name, needs_model_kwarg)` entry.
+- **Call site IDs are stable keys** used in `downshift.yaml` `volume.per_call_site`; changing the ID format is a breaking change.
+- **Config dataclasses are `frozen=True`**: construct a new instance instead of mutating.
+- **Run checks before finishing**: `ruff format . && ruff check . && mypy src && python -m pytest`. Never bare `pytest`.

downshift-0.1.0/.bob/rules-ask/AGENTS.md

@@ -0,0 +1,12 @@
+# AGENTS.md: Ask mode
+
+## Non-obvious documentation context
+
+- **`schema.py` is the shared contract** between the AST scanner and the Bob auditor. Both produce files in the same format.
+- **Implemented vs stub commands**: check `cli.py`. Stubs call `_not_implemented()` and exit with code 1.
+- **`examples/supportdesk/`** is the demo target and integration fixture, referenced in tests as `SUPPORTDESK`. Its data is synthetic.
+- **Integration tests need local Ollama** and are excluded from the default run; use `python -m pytest -m integration`.
+- **`downshift.example.yaml`** is the config template users copy to `downshift.yaml`.
+- **`.bob/` ships with the product**: `custom_modes.yaml` defines the Downshift Auditor mode and `skills/downshift-audit/` holds its workflow. Install guide: `docs/bob.md`.
+- **`bob_sessions/`** holds screenshots of Bob tasks (hackathon evidence), not code.
+- **Architecture overview**: `docs/architecture.md`.

downshift-0.1.0/.bob/rules-plan/AGENTS.md

@@ -0,0 +1,13 @@
+# AGENTS.md: Plan mode
+
+## Non-obvious architectural constraints
+
+- **`schema.py` is forward-only**: `schema_version` is checked on load and an unsupported version raises. No migration path.
+- **`Resolver` is stateful within one `_scan_modules` call** (it holds a `ModuleIndex`); do not share one across `scan_path` invocations.
+- **Cross-module resolution is one-pass**: `ModuleIndex` is built once before resolution. Circular imports are not followed.
+- **Caller attribution is name-based**: `_attach_callers` matches function names as strings.
+- **`ScanResult.write()` overwrites silently**: no merging, no locking.
+- **`via`** is not set by the AST scanner. The Bob auditor sets it when it splits a shared helper (e.g. `supportdesk/llm.py::ask`) into one logical call site per feature; `via` holds the helper's call site id.
+- **Bob auditor output is a separate file**, e.g. `examples/supportdesk/downshift.audit.json`. It never overwrites the scan file; `downshift compare` reads both.
+- **`.bob/custom_modes.yaml` and `.bob/skills/` are shipped product files** (the Downshift Auditor mode and its skill), not scratch space.
+- **Plans stay small**: one job per task, touch only the files named in the request.

downshift-0.1.0/.bob/skills/downshift-audit/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: downshift-audit
+description: Audit LLM call sites from a downshift scan file. Resolve models and prompts the static scanner missed, split shared LLM helpers into one call site per feature, add purpose, output_contract, difficulty and grading, and write downshift.audit.json.
+---
+
+# Downshift audit
+
+Input: a scan file written by `downshift scan`, given as an @mention (for example `examples/supportdesk/downshift.scan.json`).
+Output: `downshift.audit.json` in the same folder as the scan file.
+Field reference: `schema-reference.md` in this skill folder. Read it before writing.
+
+## Steps
+
+1. Read the scan file and `schema-reference.md`. Do not re-scan the repo.
+2. Build a worklist. A call site needs inspection if any of these is true:
+   - `model.value` is null, or `model.source` is `kwargs`, `env`, `dynamic` or `missing`
+   - `messages` is null, or any message has `resolved: false`
+   - it has 2 or more `callers` and its prompt is built by the callers
+3. For each worklist call site, read only its own file and the files of its `callers`. Read nothing else.
+4. Resolve models. Set `model.value` to the real model string, `model.source` to `manual`, keep `expression` and `env_var`, set `defined_in` to the file where the model string lives, set `found_by` to `bob`, and add a note starting with `Bob:` that says how you resolved it.
+5. Resolve prompts. Set `messages` to the full list as it is sent to the model. Write runtime values as `{placeholder}` with a plain name: `{ticket['body']}` becomes `{body}`, an expression like `{json.dumps(order_info)}` becomes `{order_info_json}`, and a module constant is written out as its value. Set `resolved: true` on each message. Add a `Bob:` note.
+6. Split shared helpers. If one helper serves several features with different prompts, replace the helper entry with one entry per calling feature:
+   - `id`: the caller's id in the form `path/to/file.py::qualname`
+   - `file`, `line`, `end_line`, `function`: the caller's call to the helper
+   - `via`: the helper's id from the scan file
+   - `api`, `model`, `is_async`, `temperature`, `max_tokens`: from the helper call, as this caller uses it
+   - `messages`: the prompt this caller sends
+   - `callers`: empty list. `found_by`: `bob`. Add a `Bob:` note naming the helper.
+   The helper does not stay in the output as its own entry.
+7. Enrich every call site, including ones that were already resolved: `purpose`, `output_contract`, `difficulty`, `grading` (rules below).
+8. Write `downshift.audit.json`. Copy every top-level key and value from the scan file unchanged, except set `generated_by` to `bob` and replace `call_sites` with your list. Include every CallSite field on every entry. Sort call sites by `id`.
+9. Finish with a short table: id, model, what changed (resolved model, resolved prompt, split from helper, metadata only). Do not run commands. The user validates with `downshift validate`.
+
+## Enrichment rules
+
+- `purpose`: one sentence naming the product feature. Example: "Classify a support ticket into one of five categories."
+- `output_contract`: concrete, checkable rules taken from the prompt and from the code that parses the output. Exact JSON keys and allowed values, allowed labels, length limits, forbidden content. Evals will test exactly these rules.
+- `difficulty`: `easy` for a single label or short extraction; `medium` for structured JSON or tightly constrained short text; `hard` for open-ended writing or policy reasoning.
+- `grading`: `exact` for a single label or short fixed answer; `json_fields` when `output_format` is `json`; `judge` for free text.
+
+## Hard rules
+
+- Never edit source code or any file other than `downshift.audit.json`.
+- Never invent. If something cannot be determined from the code, leave it null, keep the original `source`, and add a `Bob:` note saying what is missing.
+- Use only the fields in `schema-reference.md`. Unknown fields fail validation.
+- Keep the ids of call sites you do not split exactly as they are. They are keys in `downshift.yaml`.
+- Call sites that were already fully resolved keep `found_by: "ast"`. Only add the enrichment fields.

downshift-0.1.0/.bob/skills/downshift-audit/schema-reference.md

@@ -0,0 +1,82 @@
+# downshift.audit.json field reference
+
+Same format as the scan file. Top-level keys: copy them from the scan file; set `generated_by` to `bob`.
+
+## CallSite (every field required on every entry)
+
+| Field | Type | Notes |
+|---|---|---|
+| id | string | `path/to/file.py::qualname`, duplicates get `#2` |
+| file | string | relative POSIX path |
+| line | int | >= 1 |
+| end_line | int or null | |
+| function | string | qualified name, `<module>` for top level |
+| api | string | copy from the scan file, never invent new values |
+| model | ModelRef | below |
+| is_async | bool | |
+| messages | list of PromptMessage, or null | |
+| output_format | string | `text` or `json` |
+| temperature | number or null | |
+| max_tokens | int or null | |
+| via | string or null | id of the shared helper, only on split entries |
+| callers | list of strings | call site ids |
+| notes | list of strings | Bob notes start with `Bob:` |
+| purpose | string or null | |
+| output_contract | string or null | |
+| difficulty | string or null | `easy`, `medium`, `hard` |
+| grading | string or null | `exact`, `json_fields`, `judge` |
+| found_by | string | `ast`, `bob`, `manual` |
+
+## ModelRef
+
+| Field | Type | Notes |
+|---|---|---|
+| value | string or null | the model name |
+| source | string | `literal`, `constant`, `env_default`, `env`, `dict_lookup`, `parameter_default`, `kwargs`, `missing`, `dynamic`, `manual` (use `manual` when Bob resolves it) |
+| expression | string | source text of the model argument, keep as scanned |
+| env_var | string or null | |
+| defined_in | string or null | file where the model string lives |
+
+## PromptMessage
+
+| Field | Type | Notes |
+|---|---|---|
+| role | string | `system`, `user`, `assistant` |
+| content | string | template text, runtime values as `{placeholder}` |
+| resolved | bool | true once Bob has resolved it |
+
+## Example: one entry split from a shared helper
+
+```json
+{
+  "id": "app/billing.py::summarize_invoice",
+  "file": "app/billing.py",
+  "line": 42,
+  "end_line": 45,
+  "function": "summarize_invoice",
+  "api": "openai.chat.completions",
+  "model": {
+    "value": "gpt-4o-mini",
+    "source": "manual",
+    "expression": "MODEL",
+    "env_var": null,
+    "defined_in": "app/llm.py"
+  },
+  "is_async": false,
+  "messages": [
+    {"role": "system", "content": "Summarize the invoice in one sentence.", "resolved": true},
+    {"role": "user", "content": "{invoice_text}", "resolved": true}
+  ],
+  "output_format": "text",
+  "temperature": 0.0,
+  "max_tokens": null,
+  "via": "app/llm.py::complete",
+  "callers": [],
+  "notes": ["Bob: split from shared helper app/llm.py::complete; this caller builds its own prompt."],
+  "purpose": "Summarize an invoice for the billing dashboard.",
+  "output_contract": "One sentence, under 30 words, mentions the total amount, no speculation.",
+  "difficulty": "easy",
+  "grading": "judge",
+  "found_by": "bob"
+}
+```

downshift-0.1.0/.bob/skills/downshift-evals/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: downshift-evals
+description: Write eval sets for audited LLM call sites. One JSONL file of 20 to 25 test cases per call site, with inputs matching the prompt placeholders and expected answers that follow the output contract and the refund policy.
+---
+
+# Downshift evals
+
+Input: `downshift.audit.json` and the call site(s) you are assigned.
+Output: one file per call site in the `evals/` folder next to the audit, for example `examples/supportdesk/evals/supportdesk.triage__classify_category.jsonl`.
+Format reference: `format-reference.md` in this skill folder. Read it before writing.
+
+## Steps
+
+1. Read `format-reference.md`, your call site's entry in the audit (`messages`, `output_contract`, `grading`), `data/refund_policy.md` and `data/tickets.jsonl`. Read nothing else.
+2. Plan 20 to 25 cases in a todo list before writing: which label or rule each case covers, and whether its input comes from `tickets.jsonl` or is new.
+3. Write the file. One JSON object per line, no trailing commas, no comments.
+4. Finish with a short table: file, case count, cases per label (or per rule). Do not run commands. The user checks with `downshift check-evals`.
+
+## Rules for every call site
+
+- Inputs: about half adapted from `tickets.jsonl` (use each ticket at most once per file), the rest new. New tickets look like real customer mail: same store, order IDs like `ORD-10xxx`, dates in 2026.
+- `ticket_text` is always `subject + "\n\n" + body`, exactly as the app builds it.
+- Cover every allowed label or rule at least 3 times when the site has a label set.
+- Include these edge cases where they apply: very short text, non-English text (es, fr, de, hi, pt), mixed language, sarcasm, typos or all caps, missing order ID, dates a day or two either side of a policy limit.
+- Only write cases a careful human would label the same way. If a case could reasonably have two answers, drop it. Never put a date exactly on a policy limit (exactly 14, 30 or 60 days); use 1 or 2 days either side.
+- `notes` on every case: one line saying what the case tests.
+- `id`: short prefix plus number, for example `cat-01`. Unique within the file.
+- `grading` on every case equals the call site's `grading` in the audit.
+
+## Per call site
+
+### triage.py::classify_category (exact)
+Labels: billing, shipping, technical, account, refund, other.
+- refund: the customer asks for money back or a return for money, whatever the reason.
+- billing: charges, duplicate charges, invoices, payment methods, with no refund or return ask.
+- shipping: delivery status, tracking, address, delays, with no money-back ask.
+- technical: app or website bugs, crashes, errors.
+- account: login problems that are not bugs, password reset, email or profile changes, account closure.
+- other: product questions, feedback, anything else.
+
+### triage.py::detect_sentiment (exact)
+Labels: positive, neutral, negative. Overall tone of the whole ticket. Sarcasm ("Great, lost again. Love it.") is negative. A plain question with no emotion is neutral.
+
+### triage.py::tag_urgency (exact)
+Labels: low, medium, high, by the prompt's rules. High: money lost, service down for many users, or a very angry repeat contact. Medium: an order or account problem that blocks the customer. Low: questions, feedback, requests with no time pressure.
+Input `category` must be the correct category of that ticket under the classify_category rules above.
+
+### misc_utils.py::lang_of (exact)
+Expected: two-letter lowercase ISO 639-1 code. Input `text` is `subject + "\n\n" + body`. Cover at least en, es, fr, de, hi, pt. For mixed-language text, the expected code is the language of most of the text; say so in `notes`. Skip texts too short to tell.
+
+### extract.py::extract_order_info (json_fields)
+Expected keys: `order_id`, `order_date`.
+- `order_id`: the `ORD-` ID as written, or null. Avoid tickets with two different order IDs.
+- `order_date`: the date the order was placed, as YYYY-MM-DD, or null. A full calendar date in another format ("September 2, 2026", "02/09/2026" only when unambiguous) is converted. Relative dates ("last Tuesday", "two weeks ago") and dates with no year are null. Charge, delivery or ticket dates are not the order date; avoid tickets where it is unclear which date is the order date.
+
+### policy.py::decide_refund (json_fields)
+Expected keys: `is_refund_request`, `eligible`, `policy_section`. `reasoning` is not graded and must not appear in `expected`.
+Inputs: `policy` via the shared first line (see format reference), `today` (YYYY-MM-DD, the ticket date), `order_info_json` (an object `{"order_id": ..., "order_date": ...}` exactly as extract_order_info would return it for this ticket), `subject`, `body`.
+Days = calendar days from `order_date` to `today`. Apply in this order:
+1. Not asking for money back: `false`, `"no"`, `null`.
+2. `order_id` or `order_date` is null: `true`, `"need_info"`, `"4.1"`.
+3. Digital product already downloaded or activated: `true`, `"no"`, `"3.1"`.
+4. Clearance item (keep days at 30 or under): `true`, `"store_credit"`, `"3.2"`.
+5. Not delivered: days 14 or more `"yes"`, under 14 `"no"`; section `"3.3"`.
+6. Damaged or defective: days 60 or under `"yes"` with `"2.1"`; over 60 `"no"` with `"2.2"`.
+7. Change of mind: used or not in original packaging `"no"` with `"1.2"`; otherwise days 30 or under `"yes"`, over 30 `"no"`, both `"1.1"`.
+Aim for at least 2 cases per rule and at least 4 near a day limit. Avoid tickets that fit two rules (a damaged clearance item) and billing disputes like duplicate charges.
+
+### agent_assist.py::summarize_for_agent (judge)
+Inputs: `subject`, `body`. `expected` is a rubric string: "Exactly 2 short English sentences. Sentence 1 says the customer wants <X>. Sentence 2 mentions <every order ID, date and amount in the ticket, listed>. No details that are not in the ticket." Include non-English tickets (the summary is still English) and tickets with no order details (sentence 2 then states the key facts that are there).
+
+### agent_assist.py::draft_reply (judge)
+Inputs: `language` (ISO code of the ticket), `summary` (a correct 2-sentence English summary you write), `subject`, `body`. `expected` is a rubric string: "Written in <language name>. Under 120 words. Addresses <the specific issue>. Says a teammate will confirm next steps. Does not promise a refund, credit, delivery date or any timeframe." Include at least 5 tickets that push for a promise ("refund me today", "when will it arrive?") and at least 4 non-English languages.

downshift-0.1.0/.bob/skills/downshift-evals/format-reference.md

@@ -0,0 +1,55 @@
+# Eval file format
+
+One file per call site: `<slug>.jsonl` in the `evals/` folder next to `downshift.audit.json`.
+
+Slug: take the call site id, drop `.py`, replace `/` with `.` and `::` with `__`.
+`supportdesk/triage.py::classify_category` becomes `supportdesk.triage__classify_category.jsonl`.
+
+## Lines
+
+Each line is one JSON object. Blank lines are ignored.
+
+Optional first line, only for long inputs that every case shares:
+
+```json
+{"shared": {"policy": {"file": "../data/refund_policy.md"}}}
+```
+
+A shared value is any JSON value, or `{"file": "path"}` relative to the eval file. A case's own inputs override shared ones.
+
+Every other line is a case with exactly these keys:
+
+| key | type | rule |
+|---|---|---|
+| `id` | string | unique in the file |
+| `inputs` | object | keys are exactly the prompt's `{placeholders}`, minus shared ones |
+| `expected` | depends on grading | see below |
+| `grading` | string | same as the call site's `grading` in the audit |
+| `notes` | string | what this case tests |
+
+## expected by grading
+
+- `exact`: a string. When the output contract says "from the set {...}", it must be one of those labels, spelled exactly.
+- `json_fields`: an object whose keys are exactly the fields after "Graded fields:" in the output contract. No other keys.
+- `judge`: a rubric string a grader can check point by point.
+
+## Inputs per call site
+
+| file | inputs |
+|---|---|
+| supportdesk.triage__classify_category | ticket_text |
+| supportdesk.triage__detect_sentiment | ticket_text |
+| supportdesk.triage__tag_urgency | category, ticket_text |
+| supportdesk.misc_utils__lang_of | text |
+| supportdesk.extract__extract_order_info | ticket_text |
+| supportdesk.policy__decide_refund | policy (shared), today, order_info_json, subject, body |
+| supportdesk.agent_assist__summarize_for_agent | subject, body |
+| supportdesk.agent_assist__draft_reply | language, summary, subject, body |
+
+## Examples
+
+```json
+{"id": "cat-01", "inputs": {"ticket_text": "Charged twice\n\nI was charged twice for ORD-10733. Please fix it."}, "expected": "billing", "grading": "exact", "notes": "duplicate charge, no refund ask"}
+{"id": "ext-01", "inputs": {"ticket_text": "Late order\n\nOrder ORD-10588 placed on August 28, 2026 hasn't arrived."}, "expected": {"order_id": "ORD-10588", "order_date": "2026-08-28"}, "grading": "json_fields", "notes": "written-out date converted"}
+{"id": "ref-01", "inputs": {"today": "2026-09-19", "order_info_json": {"order_id": "ORD-10588", "order_date": "2026-08-28"}, "subject": "Where is my package??", "body": "Order ORD-10588 placed on 2026-08-28 still hasn't arrived. I want my money back."}, "expected": {"is_refund_request": true, "eligible": "yes", "policy_section": "3.3"}, "grading": "json_fields", "notes": "not delivered after 22 days"}
+```

downshift-0.1.0/.bobignore

@@ -0,0 +1,17 @@
+# Keep Bob's context small (every file read costs Bobcoins)
+.venv/
+.git/
+results/
+**/.downshift/
+web/node_modules/
+web/.next/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+bob_sessions/

downshift-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: |
+          ruff check .
+          ruff format --check .
+      - name: Type check
+        run: mypy src
+      - name: Test
+        run: pytest --cov=downshift --cov-report=term-missing --cov-fail-under=80
+
+  web:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - name: Install
+        run: npm ci
+      - name: Lint
+        run: npm run lint
+      - name: Type check
+        run: npm run typecheck
+      - name: Test
+        run: npm test
+      - name: Build
+        run: npm run build

downshift-0.1.0/.github/workflows/cost-diff.yml

@@ -0,0 +1,20 @@
+name: Cost diff
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  cost-diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Downshift cost diff (SupportDesk)
+        uses: ./
+        with:
+          path: examples/supportdesk
+          package: .

downshift-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

downshift-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.downshift/

downshift-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

downshift-0.1.0/AGENTS.md

@@ -0,0 +1,71 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+## Project
+
+Python CLI tool (`downshift`) that finds LLM call sites in Python repos via AST analysis, evaluates cheaper models per call site, and projects cost impact per PR. Package lives in `src/downshift/`, installed editably from `pyproject.toml`. Architecture overview: `docs/architecture.md`.
+
+## Commands
+
+```bash
+# Install (dev)
+pip install -e ".[dev]"
+
+# Checks before every commit, in this order
+ruff format . && ruff check . && mypy src
+
+# All tests (excludes integration by default). Always python -m pytest, never bare pytest.
+python -m pytest
+
+# Single file / single test
+python -m pytest tests/unit/test_scanner.py
+python -m pytest tests/unit/test_scanner.py::test_finds_direct_openai_call
+
+# Integration tests (requires local Ollama)
+python -m pytest -m integration
+```
+
+## Critical patterns
+
+- **`from __future__ import annotations`** in every source module under `src/downshift/`.
+- **Validation collects all problems**: gather issues into a `list[str]`, then raise one exception with all of them. Never raise on the first error. See `parse_config()` and `CallSite.from_dict()`.
+- **`_MISSING` sentinel**: `schema.py` uses `_MISSING: Any = object()` instead of `None` as the not-provided signal in `_field()`, because `None` is a valid value for nullable fields.
+- **`frozenset` for allowed values**: `MODEL_SOURCES`, `OUTPUT_FORMATS`, `DIFFICULTIES`, `GRADINGS`, `PRODUCERS` are module-level `frozenset[str]`, not enums.
+- **Dataclasses only**: all data objects are `@dataclass` (often `frozen=True`). No Pydantic, attrs or TypedDict.
+
+## Testing
+
+- Tests ship in the same commit as the code they cover. Coverage target >= 80% on `src/downshift/`.
+- Default test run has no network and no models: use `FakeLLMClient` from `llm.py`. Anything needing Ollama is marked `@pytest.mark.integration`.
+- Scanner unit tests use `scanner.scan_source(textwrap.dedent(src), "app.py")` on inline strings. Use `tmp_path` only where real files are needed (CLI tests, temp git repos).
+- CLI commands are tested with typer's `CliRunner`. Report markdown uses snapshot tests.
+
+## Code style
+
+- Line length 100. Ruff rules `E, F, I, B, UP, SIM`. Use `zip(..., strict=True)`.
+- `typer.Option` / `typer.Argument` are in `extend-immutable-calls` so bugbear won't flag them.
+- Every source module has a docstring describing its purpose and who produces/consumes its data.
+- Private helpers are prefixed `_`; keep the public API minimal.
+- Conventional commits: `feat`, `fix`, `test`, `docs`, `ci`, `chore`.
+
+## Architecture
+
+```
+CLI (cli.py) -> resolve_config() -> scan_path() -> ScanResult (schema.py)
+                                        |
+                           Module / ModuleIndex / Resolver (resolve.py)
+                                        |
+                            _CallFinder (AST visitor, scanner.py)
+```
+
+- `schema.py` is the shared data contract: the AST scanner and the Bob auditor both write and read through it.
+- `ScanResult.write()` auto-creates parent directories. Scan output defaults to `<scanned-dir>/.downshift/callsites.json` (gitignored).
+- `SKIP_DIRS` in `scanner.py` lists directories the walker never enters (`.venv`, `__pycache__`, `.downshift`, ...).
+- Call site IDs are `<rel_path>::<qualname>` (e.g. `app/triage.py::classify`); duplicates get `#2`, `#3`.
+
+## Config (`downshift.yaml`)
+
+- Optional; auto-discovered next to the scanned path. Absent config means all defaults.
+- `schema_version: 1` (callsites JSON) and `version: 1` (config YAML) are separate fields.
+- Pricing uses `input`/`output` keys in YAML; the dataclass fields are `input_per_mtok`/`output_per_mtok`.

downshift-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-26
+
+First public release.
+
+### Added
+- `downshift scan`: AST scanner for OpenAI (v1 SDK) chat/responses and Anthropic messages calls. Resolves models through constants, imports, env var defaults, dict lookups and parameter defaults; recovers prompt templates; records callers.
+- `callsites.json` schema with strict validation, shared by the scanner and Bob.
+- `downshift validate` and `downshift compare`: check a Bob audit and compare it with the ast scan.
+- IBM Bob integration in `.bob/`: Downshift Auditor and Downshift Eval Writer custom modes with the `downshift-audit` and `downshift-evals` skills.
+- Eval sets (`evals/<call_site>.jsonl`), `downshift check-evals`, and `downshift evalgen` to write evals with any configured model.
+- `downshift run`: runs each call site's evals on the baseline and candidate models. Resumable, with warm-up and token and latency tracking.
+- Scoring by exact match, JSON fields, or an LLM judge, plus `downshift rescore` with a separate hosted judge.
+- Decisions (cheapest model that keeps the quality threshold and minimum pass rate), monthly cost projections, and `downshift report`.
+- `downshift diff` and a composite GitHub Action (`action.yml`) that comments the projected monthly cost change on every PR, with an optional `fail-above` limit.
+- `downshift estimate`: price a scan or audit file, or compare two, without running evals.
+- `downshift export` and a demo web app (Next.js, deployed at https://downshift-llm.vercel.app/).
+- `examples/supportdesk`: demo app with 8 LLM features, 40 synthetic tickets and a refund policy document.
+- Case studies on OrchestrAI (MIT) and mem0 (Apache-2.0).
+- End-to-end pipeline smoke test; CI fails below 80% coverage.
+
+### Fixed
+- Scanner reads files with a UTF-8 BOM.
+- Scanner detects SDK calls that pass the model through `**kwargs` when the SDK is imported.
+
+### Notes
+- `diff` and `estimate` are static projections for per-PR deltas, not absolute spend.
+- The GitHub Action now installs `downshift>=0.1.0` by default.
+
+## [0.1.0.dev0] - 2026-09-26
+
+### Added
+- Pre-release to claim the PyPI name and test Trusted Publishing.
+
+[Unreleased]: https://github.com/ana-lan/downshift/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ana-lan/downshift/compare/v0.1.0.dev0...v0.1.0
+[0.1.0.dev0]: https://github.com/ana-lan/downshift/releases/tag/v0.1.0.dev0

downshift-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing
+
+## Setup
+```bash
+python3.12 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+```
+
+## Checks
+```bash
+ruff check . && ruff format --check .
+mypy src
+pytest
+```
+
+Integration tests need a local Ollama server: `pytest -m integration`.
+
+## Workflow
+Branch per change, open a PR, CI must pass. Use conventional commits (`feat:`, `fix:`, `test:`, `docs:`, `ci:`, `chore:`).