keble-keepa 1.2.1__tar.gz

keble_keepa-1.2.1/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

keble_keepa-1.2.1/.gitignore

@@ -0,0 +1,155 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintainted in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+.vscode/
+.lprof/
+.history/

keble_keepa-1.2.1/.python-version

@@ -0,0 +1 @@
+3.13

keble_keepa-1.2.1/AGENTS.md

@@ -0,0 +1,18 @@
+# Keble Keepa Agent Instructions
+
+Follow the root `TESTING_GUIDELINE.md` when changing tests in this repo.
+
+## Testing Rules
+
+- Use `keble_keepa.testing` for Keepa-dependent tests before creating new mocks.
+- Keep default tests offline: no real Keepa, no real LLMs, no live HTTP calls.
+- Mark recorded payload tests with `contract` / `keepa_contract`.
+- Mark Mongo-backed cache tests with `integration`, `db`, `mongo`, and `keepa`.
+- Mark live Keepa tests with `live`, `keepa_live`, and `requires_keepa_live`.
+- Do not add session-wide DB cleanup. Use isolated cache collections or exact
+  query-key cleanup per test.
+- Run `uv run pytest -m "not live and not slow and not eval and not local_stack"`
+  and `npx --yes pyright .` after test-infrastructure changes.
+- Update `README.md`, `AGENTS.md`, `CLAUDE.md`, and `AiAgentChangesLogs.md`
+  whenever testing behavior, commands, markers, fixtures, or dependencies
+  change.

keble_keepa-1.2.1/AiAgentChangesLogs.md

@@ -0,0 +1,272 @@
+## 2026-06-30 09:34 CST
+State: branch `fix/keepa-aiohttp-proxy-env`; package line `1.1.15` -> `1.1.16`.
+
+zma:
+- Continue the live E2E red-suite follow-up after local Docker proxy wiring.
+- Fix the remaining Keepa-backed positioning failures by making async Keepa aiohttp calls honor Docker proxy env, then rebuild and repin backend.
+
+Ai:
+- Added a typed `KeepaAioHttpSessionConfig` owner for async Keepa sessions and routed `_aget` / `_apost` through it.
+- Set aiohttp `trust_env=True` for async Keepa GET/POST requests so local Docker `HTTP_PROXY` / `HTTPS_PROXY` env is honored without adding package-level proxy values or production config.
+- Updated timeout/session tests to assert both configured timeout values and proxy-env honoring.
+
+## 2026-06-22 (fix: null contextFreeName breaks category lookup) — 1.1.15
+State: branch `fix/keepa-null-context-free-name` (from 1.1.14 @ 45b2e99). Fixes v3 Shuffle "Failed to load categories".
+
+zma: v3 Shuffle category dropdown shows "Failed to load categories"; prod curl revealed `CategoryLookupResponse.categories.<id>.contextFreeName → Input should be a valid string, input_value=None`.
+
+Ai: Keepa occasionally returns a null `contextFreeName` for some category nodes. `Category.context_free_name` was a required `str`, so the entire `CategoryLookupResponse` failed to parse and the (public) root/children category endpoints 500'd. Made `context_free_name: Optional[str] = None` + a `model_validator(mode="after")` that falls back to `name` when null, so downstream consumers (keble_amz_shuffle) still receive a real string. Bumped 1.1.14 -> 1.1.15. Verified: a category payload with `contextFreeName=None` now parses with `context_free_name == name`; normal values unchanged.
+
+## 2026-06-20 (opt-in singular/plural search expansion) — 1.1.14
+State: branch `fix/keyword-search-coverage` (from `main` @ 1.1.13); package line 1.1.13 -> 1.1.14. Track 3 of the keyword-coverage plan.
+
+zma: report-gen's Keepa title search sends RAW keywords with no singular/plural variant (esp. `*ies`), under-covering markets that split across inflections (e.g. "berry" misses "berries").
+
+Ai:
+- New dependency-free `keble_keepa/utils/keyword.py`: `singular_plural_variants(token)` (real BIDIRECTIONAL inflection — classifies by surface and emits the OPPOSITE number: `berry<->berries` ies-rule, `box<->boxes` es-rule, `dog<->dogs` plain-s; guards `glass`/`ss` and vowel+y; never both directions at once so no `dogses`) and `expand_singular_plural(keywords)` (inflects only the trailing head noun of each phrase, order-preserving dedup). Exported from `keble_keepa`. This is a deliberate minimal duplicate of `keble_amz_product_report.keyword_text` (keepa is the lower layer and must not import amz).
+- `batch_loader.asearch_asins_from_keepa` gained OPT-IN `expand_keyword_variants: bool = False`: when True, expands the search terms via the helper, deduplicates, and caps at the Keepa 50-keyword title-search limit before fan-out. The leaf is the single cap-enforcement site. Threaded the flag through `aload_similar_products` and `aload_similar_products_with_limit` (both internal leaf calls). Default False keeps every other caller (keble-keepa-analysis, keble-products, internal) byte-for-byte identical.
+- Tests: `tests/test_objects/test_keyword_inflection.py` (pure-unit inflection rules) + `tests/test_api/test_batch_loader.py` new cases (expansion fires only when opted-in; default OFF leaves keywords unchanged; 50-keyword cap; wrapper forwards the flag). Full `test_api`: 57 passed, 1 skipped.
+
+## 2026-06-30 13:22 CST
+State: branch `fix/keepa-publish-classifier`; package line moving from `1.2.0` to `1.2.1`.
+
+zma:
+- Complete the `keble-keepa` testing-toolkit release and publish it after verification.
+
+Ai:
+- Publish of `1.2.0` was blocked by PyPI rejecting the pre-existing custom classifier `Private :: Core keepa warpper therefore keep private`.
+- Removed the invalid classifier from Hatch and Poetry metadata.
+- Bumped to `1.2.1` instead of mutating the already-pushed `v1.2.0` tag.
+
+## 2026-06-30 13:10 CST
+State: branch `refactor/testing-layers-keble-keepa`; package line moving from `1.1.16` to `1.2.0`.
+
+zma:
+- Continue the cross-repo testing refactor after `keble-db`.
+- Enrich `keble-keepa` with shared testing fixtures and guards.
+- Keep default tests fast/offline, align markers, run pytest and `npx --yes pyright .`.
+
+Ai:
+- Added `keble_keepa.testing` with fake gateway, typed product factories, variation/raw payload factories, cassette secret filters, live Keepa guard, namespace helper, and schema assertions.
+- Registered the cross-repo pytest markers and pytest plugin entry point.
+- Reworked test bootstrap so default pytest no longer requires `.env`, Mongo, Redis, or Keepa token.
+- Replaced session-wide Keepa cache wiping with per-test cache collection isolation plus exact query-key cleanup in Mongo-backed tests.
+- Added toolkit unit coverage and `pyrightconfig.json`.
+- Validation: `uv run pytest -q -m "not live and not slow and not eval and not local_stack"` passed (`64 passed, 34 skipped, 16 deselected`), `uv run pytest -q` passed (`64 passed, 50 skipped`), `npx --yes pyright .` passed, and `uv build` produced `keble_keepa-1.2.0` sdist/wheel.
+
+## 2026-06-10 (cache poisoning fix, v1.1.12)
+State: branch `fix/keepa-cache-newest-first-and-refetch` (from `main` @ v1.1.11); package line moving from `1.1.11` to `1.1.12`.
+
+zma:
+- Live bootstrap report task `6a291e80cf834afeeb632e39` failed with 相关产品不足 / NO_SUFFICIENT_DATA while the core ASIN `B0DCF53PCH` was missing from a 10-ASIN cache read. Suspected NOT a genuine lack-of-products case; asked for investigation and the agreed fix policy: newest-first cache reads + a forced-refetch escape hatch.
+
+Ai:
+- Root cause: `to_response_cache` writes a negative `cache.data=None` row for every requested ASIN missing from a (partial) Keepa response, and all per-key cache readers used unsorted `first/afirst` (Mongo natural order) so the OLDEST row won. A negative row written 2026-06-05 shadowed a GOOD row written 2026-06-08 for the same key until TTL expiry.
+- `crud/keepa_cache.py`: new `_newest_first_cache_query` helper — all per-key readers (`get_from_cache`, `aget_from_cache`, `aget_request_products_cache_parts`) now order by `created` DESC with `_id` DESC tiebreak (same-millisecond writes stay deterministic).
+- `api/main.py`: `arequest_products` / `_aget` gained `skip_cache_read: bool = False` — bypasses Redis+Mongo cache READ, still WRITES the fresh response, so a forced fetch repairs a poisoned key for all later callers. `ready_mongo` now also creates the `{"key": 1, "created": -1}` index backing the per-key read (was a collection scan).
+- Tests: `tests/test_api/test_cache_newest_first.py` — newer-good-supersedes-older-negative for both readers + skip_cache_read bypass/repair (fake aiohttp live response, real pytest Mongo). Full suite: 90 passed, 1 skipped (pre-existing).
+## 2026-06-10 14:39 CST
+State: branch `fix/average-price-time-weighted-mean` (from `main` @ v1.1.10); package line moving from `1.1.10` to `1.1.11`.
+
+AndrewChan:
+- Production report `6a23b711148a3de3da0055ac` (ASIN `B08SSWY8SH`, amazon.com) showed price $97.95 while the real price is $19.95. Root-caused to `Product.average_price_int`; requested the time-weighted-mean fix (option 3 of the analysis).
+
+Ai:
+- Root cause: Keepa csv NEW (index 1) only records change points. The price has been stable at $19.95 since 2026-02-02, so the "recent 3 months" `filter_list(...)` window was empty and the code fell back to the all-time arithmetic mean of change points — dominated by years-old $90-$110 oscillations — which is exactly 9795 ($97.95).
+- Added `UnitDataList.time_weighted_mean(gte=..., lte=...)` in `keble_keepa/schemas/non_keepa/unit_data.py`: duration-weighted average over the change-point series; forward-fills the last change point before the window start; clamps each value's effective span to the window; rounds away 1-ulp float noise so constant series return their exact value; returns `None` when no value covers the window. `UnitDataList.mean` is unchanged (other consumers keep arithmetic-mean semantics).
+- `Product.average_price_int` now uses `time_weighted_mean(gte=now-3months)` with an all-time `time_weighted_mean()` fallback; the `stats` fallback chain is unchanged. Updated docstrings.
+- Known limitation documented in README: `-1` (offer unavailable) entries are still dropped at `UnitDataList.build`, so out-of-stock gaps count as the previous price's duration (same as before this fix).
+- Tests: `tests/test_objects/test_unit_data_time_weighted_mean.py` (forward-fill, duration weighting, change-frequency bias, empty/edge windows) and `tests/test_objects/test_product_average_price_int.py` (production regression scenario expecting 1995, mid-window change, single stable point, empty history). Full suite: `pytest tests/ -q` → 87 passed, 1 skipped (pre-existing skip).
+- End-to-end verification with live Keepa data for `B08SSWY8SH`: `average_price_int` now returns `1995` ($19.95) instead of `9795` ($97.95).
+- Bumped `1.1.10 -> 1.1.11`, regenerated `uv.lock` (`uv lock --check` passes), built the wheel and shipped it to `keble.backend/dependencies/` with the `requirements.keble.txt` bump (user-approved continuation). Compatibility checked: backend's pinned `keble_helpers-1.13.0` exports `UsageAccountingEvent` required by this package line. Production mirror intentionally not touched (user instruction).
+
+## 2026-06-06 13:00 CST
+State: branch `fix/keepa-prompt-cleanup`; package line moving from `1.1.9` to `1.1.10` (release-hygiene follow-up).
+
+zma:
+- Double-check a follow-up audit of the 1.1.9 prompt fixes and apply the valid cleanup items.
+
+Ai:
+- pyright: typed `Product._is_valid_keepa_timestamp` as `TypeGuard[int | float]` so `_extract_first_keepa_timestamp_from_series` narrows before `int(first)` (clears the last pre-existing `product.py:2425` error) — chose the TypeGuard over the audit's duplicate-`isinstance` suggestion to avoid duplicating validation logic.
+- tests: `pytest_sessionfinish` now also wipes the Keepa pytest Mongo cache collection, symmetric with `pytest_sessionstart`.
+- lock: regenerated `uv.lock` (was stale at `1.1.8`; `uv lock --check` now passes at `1.1.10`).
+- Bumped metadata `1.1.9 -> 1.1.10`, rebuilt the wheel. Deferred (per zma) the prompt-builder ownership refactor into schema classmethods; no backport to `0.0.x`/`1.0.x` (no `KeepaProductPrompt*` there).
+
+## 2026-06-06 12:00 CST
+State: branch `fix/keepa-prompt-typing-and-coverage`; package line moving from `1.1.8` to `1.1.9`.
+
+zma:
+- Fix Pylance `reportOptionalMemberAccess` on `retry_state.outcome.exception()` in `KeepaApiBatchLoader`.
+- Fix Pylance `reportArgumentType` where `KeepaProductPromptPhysicalFacts` dimension tuples (`tuple[float | None, ...]`) did not narrow to `tuple[float, float, float] | None`.
+- Confirm `int(round(latest_rating_unit.value))` does not corrupt ratings.
+- Address the silent-null risk of string-keyed field reads (`getattr`-style) and weak real-world test coverage of the `KeepaProductPrompt*` builders.
+
+Ai:
+- `batch_loader.py`: added `KeepaApiBatchLoader._retry_exception(retry_state)` with an explicit `outcome is None` guard (no getattr/try-except) and reused it in both `before_sleep` log callbacks, clearing the optional-access diagnostic.
+- `schemas/objects/product.py`: added `_dimension_triple_cm(*, length, width, height) -> tuple[float, float, float] | None` whose explicit per-axis None guard narrows the type; `KeepaProductPromptPhysicalFacts.from_product` now builds both item/package triples through it (behavior unchanged: all three axes required).
+- Rating fix: `_prompt_metric_value_text` now always divides the Keepa 0..50 rating unit by 10, so a genuine sub-0.5-star product (Keepa 1..5) renders correctly (e.g. Keepa `5` -> `0.5/5`, previously the `value > 5` heuristic wrongly produced `5.0/5`). The 0..50 rounding question is a no-op: the value rounded is the raw integer Keepa unit, the star `/10` conversion happens at display time.
+- Hardening: `_prompt_model_value` now raises `KeyError` when `field_name` is not a declared field of the model (typo/removed field fails loudly instead of nulling forever); legitimately-absent declared fields on partial `model_construct` fixtures still return `None`. Verified all 33 field names currently read are valid `Product` attributes.
+- Tests: added a full-scale rating parametrize (incl. the `(5, "0.5/5")` regression row) and an unknown-field `KeyError` test to `tests/test_objects/test_product_prompt_snapshot.py`; added live coverage `tests/test_api/test_objects/test_product_prompt_snapshot_irl.py` asserting physical facts/metrics/ranks (heavy ASIN) and rating/reviews (with `rating=1`) populate non-null from real Keepa products — guarding upstream Keepa field drift the field-name check cannot catch.
+- Bumped metadata `1.1.8 -> 1.1.9`, rebuilt the wheel, copied it into `keble.backend/dependencies/`, and updated `requirements.keble.txt`. All mock + live object/batch-loader tests pass (54 + 2); both originally-reported Pylance errors are gone. Note: one pre-existing unrelated `int(object)` pyright error at `product.py:2425` (`_collect_keepa_timestamp_series`) is left out of scope.
+
+## 2026-05-20 19:16 CST
+State: branch `fix/product-prompt-snapshot`; package line moving from `1.1.5` to `1.1.6`.
+
+zma:
+- Implement compact Keepa product prompt snapshots for LLM/RAG prompts.
+- Keep raw Keepa payload storage lossless, default historical windows to 7 days with explicit kwargs, exclude raw histories/reviews/offers, export public types, and add tests.
+
+Ai:
+- Added `KeepaProductPromptSnapshot`, bounded series/point/rank/variation/physical/latest metric schemas, plus `Product.to_prompt_snapshot(...)` and `Product.to_prompt_markdown(...)`.
+- Snapshot output keeps identity, category, image, features, dimensions, variations, latest metrics, and capped recent series while excluding raw `csv`, `salesRanks`, monthly-sold history, offers, and review payloads.
+- Bumped package metadata to `1.1.6`, built `dist/keble_keepa-1.1.6-py3-none-any.whl`, and verified focused prompt snapshot/release-date tests.
+
+## 2026-04-29 19:23 CST
+State: `keble-keepa` branch `fix/keepa-batch-concurrency` prepared for version `1.1.4`.
+
+zma:
+- Investigate review feedback on the Keepa hardening follow-up.
+- Confirm whether `max_concurrent_tasks` is enforced and update the codebase for confirmed issues.
+
+Ai:
+- Confirmed `max_concurrent_tasks` was not enforced for product batch requests.
+- Added validated positive `max_concurrent_tasks` handling and wrapped product requests in an async semaphore.
+- Added regression coverage proving five one-ASIN batches never exceed two concurrent Keepa requests when configured that way.
+- Bumped package metadata to `1.1.4` for backend consumption.
+
+## 2026-04-29 14:41 CST
+State: `keble-keepa` branch `fix/keepa-request-timeouts` prepared for version `1.1.3`.
+
+zma:
+- Implement the hardened Keepa 50-ASIN request plan from `main`.
+- Add HTTP timeout controls, partial product cache reuse, smaller product batches, and deterministic tests.
+- Build and prepare the package for backend consumption.
+
+Ai:
+- Added validated `KeepaApi` sync/async timeout configuration and applied it to all requests calls.
+- Added partial product cache loading that preserves exact `RequestProductsQuery` params and treats `data=None` rows as known cache hits.
+- Updated `KeepaApiBatchLoader` with configurable `product_batch_size=20`, cache preloading, ordered merge output, and richer retry warning logs.
+- Added timeout, partial-cache, batch-loader, split-fallback, and warning-log tests; verified the targeted Keepa suite passed.
+- Bumped package metadata to `1.1.3` and built `dist/keble_keepa-1.1.3-py3-none-any.whl`.
+
+## 2026-04-22 15:29 CST
+State: `keble-keepa` current branch `fix/keepa-images-field` prepared for version `1.1.2`.
+
+zma:
+- Investigate production report thumbnails rendering as grey boxes.
+- Fix the Keepa image contract drift for all affected maintained lines.
+- Use full patch-release flow with branches, tags, and downstream backend updates.
+
+Ai:
+- Added typed `ProductImage` support for Keepa's structured `images` field.
+- Updated `Product.image_filenames` / `image_filename` / `image_urls` / `image_url` to prefer structured images and preserve `imagesCSV` fallback.
+- Added current-line regression coverage for structured large image, structured medium fallback, legacy CSV fallback, and URL generation.
+- Bumped current package metadata to `1.1.2`.
+
+## 2026-04-21 16:52 CST
+State: `keble-keepa` current branch `fix/new-price-is-map-optional` prepared for version `1.1.1`.
+
+zma:
+- Found bug: `new_price_is_map` is actually optional in Keepa payloads.
+- Fix Keepa in all major versions.
+- Copy the latest `1.*` fix into `keble.backend` `2.1.*` main and update `requirements.keble.txt`.
+
+Ai:
+- Bumped package version to `1.1.1`.
+- Updated `Product.new_price_is_map` to accept missing `newPriceIsMAP` as `None` while preserving explicit boolean values.
+- Added regression tests for missing, `true`, and `false` `newPriceIsMAP` payloads.
+- Updated README release notes for the current bugfix.
+
+## 2026-02-27 19:25
+State: Backported guessed release-date extraction logic to backend-compatible keepa version line.
+
+zhenhao-ma:
+- Investigate release-date empty/new-old misclassification issue.
+- Ensure guessed release-date extraction has parametrized coverage for CSV/timestamp pair data.
+- Prepare package updates consumable by keble backend runtime.
+
+Ai:
+- Bumped package version to `1.0.2` on branch `1.0.2`.
+- Upgraded `Product.guessed_has_offer_since_datetime` extraction to scan valid Keepa timestamp series recursively (CSV + keepaTime-described lists), with invalid-series filtering.
+- Added `tests/test_objects/test_product_guessed_has_offer_since_datetime.py` with parametrized timestamp scenarios and invalid-data guard cases.
+- Updated `README.md` release notes for the backport.
+- Validation: `pytest tests/test_objects/test_product_guessed_has_offer_since_datetime.py -q --confcutdir=tests/test_objects` passed (8 tests).
+
+## 2026-03-06 10:02
+State: Keepa batch loading no longer fails the whole pipeline when one batch exhausts retries.
+
+zhenhao-ma:
+- Investigate positioning task failure caused by `KeepaApiBatchLoader._keepa_request_products` retry exhaustion.
+- Fix runtime behavior so task can continue with partial data.
+- Add regression coverage and release a new keepa package version.
+
+Ai:
+- Bumped `keble-keepa` to `1.0.3` on branch `1.0.3`.
+- Updated `keble_keepa/batch_loader.py`:
+  - keepa retry loop now avoids last-attempt sleep.
+  - `aload_asins_from_keepa` now applies split-and-continue fallback when a batch fails.
+  - single-ASIN hard failures are skipped with warning logs instead of aborting the full load.
+- Added tests in `tests/test_api/test_batch_loader.py`:
+  - split failed large batch into smaller chunks and recover.
+  - skip irrecoverable single-ASIN failures without raising.
+- Updated `README.md` with the `1.0.3` behavior notes.
+- Validation: `pytest -q` passed (`36 passed, 1 skipped`).
+
+## 2026-03-13 15:55 CST
+State: Synced future-timestamp inference fix from `0.0.19` commit `e062e5d` into branch `1.0.4`.
+
+AndrewChan:
+- Requested to sync only `./keble_keepa` code changes from commit `e062e5d9352b5e4afbfa7cf04e103e9ca4de3f85` into branch `1.0.4`.
+- Then requested syncing related `md` files, `tests/` code, and `AiAgentChangesLogs.md`.
+
+Ai:
+- Synced `keble_keepa/schemas/objects/product.py` logic to ignore future `listedSince` and non-future-only guessing from Keepa time series.
+- Synced regression tests in `tests/test_objects/test_product_guessed_has_offer_since_datetime.py` for:
+  - future `listedSince` fallback,
+  - all-future series returns `None`.
+- Updated `README.md` with a new `Version 1.0.4 update` section aligned to the synced behavior.
+- Added this `AiAgentChangesLogs.md` entry to document the branch-level synchronization work.
+## 2026-05-13 22:09 CST
+State: Preparing current-line Keepa release-date fallback fix on `fix/keepa-release-date-fallback`.
+
+zma:
+- Investigate ASINs whose release dates cannot be detected in AMZ reports.
+- Use Keepa API data when needed and fix the latest Keepa package line without regressing structured image handling.
+
+Ai:
+- Added `Product.tracking_since_datetime` as a typed fallback for products where Keepa reports `listedSince=0` but has a valid `trackingSince`.
+- Updated `Product.guessed_has_offer_since_datetime` to use valid `trackingSince` before historical series scanning.
+- Added schema coverage for the missing-listing-date case and bumped package metadata from `1.1.4` to `1.1.5`.
+## 2026-05-25 12:12
+State: branch `fix/task-cost-accounting-audit-hardening`; package `1.1.7`.
+
+zma:
+- Wire Keepa provider usage accounting at the provider boundary and use tenacity for retry ownership.
+
+Ai:
+- Added optional usage-recorder forwarding to async product finder and product request calls; cache hits do not emit usage.
+- Replaced Keepa batch retry loops with tenacity while preserving retry diagnostics.
+- Added tests that enforce async GET/POST usage context signatures and counted Keepa usage events.
+
+## 2026-05-26 09:46 CST
+State: branch `fix/task-cost-accounting-runtime-hardening`; package bumped to `1.1.8`.
+
+zma:
+- Harden Keepa retry ownership after audit found tenacity predicates retrying every `Exception`.
+- Keep provider-boundary usage accounting and avoid duplicate higher-level Keepa cost rows.
+
+Ai:
+- Narrowed batch-loader tenacity retry predicates to HTTP transport and timeout exceptions.
+- Added a regression test proving programming errors are not retried, refreshed helper dependency metadata, and rebuilt the package wheel.
+
+## 2026-06-13 20:05 CST
+State: branch `fix/keepa-finder-perpage`; package bumped to `1.1.13`.
+
+zma:
+- Continue Round-4.4 and fix the live `general_research` crash caused by Keepa Product Finder rejecting small `perPage` values.
+- Keep the fix at the source package boundary with typed validation.
+
+Ai:
+- Added typed Product Finder page bounds and `ProductFinderQuery.resolve_valid_finder_page(...)`.
+- Updated the batch loader to clamp requested `per_page` into Keepa-valid bounds and slice returned ASINs locally.
+- Added tests for small page-size requests and impossible-window typed rejection.

keble_keepa-1.2.1/CLAUDE.md

@@ -0,0 +1,15 @@
+# Keble Keepa Claude Instructions
+
+Follow the root `TESTING_GUIDELINE.md` for all Keepa test work.
+
+Use `keble_keepa.testing` (`FakeKeepaGateway`, factories, cassette filters, and
+`requires_keepa_live`) instead of ad-hoc raw Keepa mocks. Never hit the real
+Keepa API from default tests. Put each test in the lowest useful layer and keep
+the standard marker vocabulary aligned with the other Keble repos.
+
+Required checks after test-infrastructure changes:
+
+```bash
+uv run pytest -m "not live and not slow and not eval and not local_stack"
+npx --yes pyright .
+```