# AiAgentChangesLogs

````markdown
Update `AiAgentChangesLogs.md` in project root directory on each completion. Include timestamp, project state, my prompt and your changes. Be simple when you are simply fixing a small bug. Be concise and conclusive when you are updating large portion of the codebase. Sample format: 
```markdown
## 2026-01-01 14:00
State: <the state of the project linked to this section>

<My github username>: <a summary of my prompt, shorten it if too long>
<!-- you may want to use git to check my git username, since there are multiple people working in the same branch -->

Ai: <a summary on what have you changed? Especially the mechanism, dependencies, schemas, etc...>
```
````

## 2026-02-10 18:10
State: Added implementation and tests for Amazon product URL parsing in enum typings; no existing change log file was present, so this file was initialized.

zhenhao-ma: complete my parse_amazon_product_url function in AmazonMarketplace enum

Ai: Implemented `AmazonMarketplace.parse_amazon_product_url` with strict parsing for supported Amazon domains and common product URL path formats (`/dp/`, `/gp/product/`, `/gp/aw/d/`, `/exec/obidos/asin/`, `/product/`). Added new parser tests for valid and invalid URLs in `tests/test_typings/test_typing.py`. Verified with pytest (`9 parser tests passed`, `98 total typing tests passed`).

## 2026-02-10 18:16
State: Expanded Amazon product URL parser coverage and strengthened normalization behavior for domain/path cases.

zhenhao-ma: further update my functions based on your finding. and makesure you can handle domain with or without www. and case insensitively. and ensure returned asin are all in uppercase

Ai: Updated `AmazonMarketplace.parse_amazon_product_url` to improve real-world URL coverage and normalization. Domain matching now explicitly normalizes host case and strips repeated `www.` prefixes, then resolves marketplaces with length-sorted domain matching to avoid subset collisions (such as `amazon.com` vs `amazon.com.mx`). Expanded supported URL patterns (`/gp/aw/dp/`, `/gp/dp/`, `/o/asin/`, `/product-reviews/`, `/gp/offer-listing/`, `/gp/customer-reviews/`) and added a query fallback for `asin=`. ASIN output remains normalized to uppercase. Added new tests for mixed-case URLs, with/without `www`, subset domains, and added path/query variants. Verified with pytest (`15 parser tests passed`, `104 total typing tests passed`).

## 2026-02-10 20:40
State: Added AI prompt URL extraction helpers with image/webpage classification and dedicated test coverage.

zhenhao-ma: did my lib offers extract url extracter from prompt. since users imput prompt can contain different types of url (such as image or webpage), if there is none, add a function to ai/helpers.py

Ai: Added `extract_urls_from_prompt` in `keble_helpers/ai/helpers.py` and a typed schema `PromptUrlExtractionResult` (`all_urls`, `image_urls`, `webpage_urls`). Implemented URL parsing with deduplication, trailing punctuation cleanup, HTTP/HTTPS validation, and `is_image_url` classification by extension. Exported new helpers via `keble_helpers/ai/__init__.py`. Added tests in `tests/test_ai_helpers.py` and verified with pytest (`11 passed` across AI helper/agent/token-related tests).

## 2026-03-05 13:01
State: Global helper runtime loop-safety fix + multimodal resilience contract finalized.

zhenhao-ma: Replace local image preflight copies with shared helper runtime and fix persistent runtime instability.

Ai:
- Added loop-safe semaphore handling in `keble_helpers/ai/image_runtime.py` (semaphore is now event-loop-local to prevent cross-loop future errors).
- Added regression test `test_preflight_runtime_is_loop_safe_for_reuse`.
- Kept typed preflight + model image-404 fallback retry contract with `tenacity(reraise=True)`.
- Updated package version `1.11.4 -> 1.11.5` and rebuilt wheel.
- Updated `README.md` with a dedicated "Pydantic AI image runtime" section and usage contract.
- Validation:
  - `tests/test_ai_image_runtime.py` -> 8 passed.

## 2026-03-05 13:41
State: Helper image runtime cache hardening follow-up.

zhenhao-ma: Address reviewer concern on potential unbounded preflight cache growth.

Ai:
- Added bounded cache maintenance in `keble_helpers/ai/image_runtime.py`:
  - evict expired entries on each cache access,
  - cap cache size and evict oldest entry at capacity.
- Added test `test_preflight_runtime_evicts_expired_cache_entries`.
- Bumped package version `1.11.5 -> 1.11.6` and rebuilt wheel.
- Validation: `tests/test_ai_image_runtime.py` -> 9 passed.

## 2026-03-06 09:18
State: Configurable HTTP status policy for image preflight + release `1.11.7`.

zhenhao-ma: Make image preflight status filtering configurable (`only_accepts` / `rejects`), enforce mutually exclusive config, keep default reject behavior, then release and propagate strict status policy usage to consumers.

Ai:
- Updated `ImagePromptPreflightRuntime` in `keble_helpers/ai/image_runtime.py`:
  - added `only_accepts: list[int] | None`,
  - added `rejects: list[int] | None`,
  - raises `ValueError` when both are provided,
  - defaults to `rejects=[404]` when neither is provided.
- Wired status policy into preflight decision evaluation.
- Added test coverage in `tests/test_ai_image_runtime.py` for:
  - default policy behavior,
  - `only_accepts` behavior,
  - `rejects` behavior,
  - mutual-exclusion validation.
- Updated helper README usage docs for the new status-policy contract.
- Added `pytest-asyncio` to test dependencies and refreshed lockfile.
- Bumped version `1.11.6 -> 1.11.7`.
- Validation: `poetry run pytest -q` -> `228 passed`.
- Build + publish: `poetry build`, `poetry publish` completed for `keble-helpers 1.11.7`.
## 2026-03-06 09:22
State: Release hardening for strict status policy correctness on redirecting image URLs.

zhenhao-ma:
- Keep preflight status policy configurable and make strict acceptance reliable for consumer runtimes.

Ai:
- Updated preflight HTTP probe to avoid auto-following redirects, so 3xx status codes are evaluated by policy directly.
- Added redirect-focused regression test to ensure `only_accepts=[200,206]` rejects redirected URLs while permissive default still allows non-404 statuses.
- Updated README to document redirect-handling behavior.
- Bumped version to `1.11.8` for release.

## 2026-03-06 14:42 CST
State: branch keble-helpers-1.11.9

zhenhao-ma: continue issue.README investigation; centralize image prompt checker ownership in backend; remove misleading helper/runtime split; verify with pytest; append the new findings to updated.README.md.

Ai: Renamed the public helper concept to `ImagePromptChecker`, removed the legacy public `ImagePromptPreflightRuntime` surface, collapsed `arun_with_image_fallback(...)` to a single checker-owned policy path, added regression coverage for checker retry ownership, updated README, and bumped the package to `1.11.9`.

## 2026-03-07 17:41 CST
State: branch `keble-helpers-1.11.10`; helpers own canonical shared `CommerceEntityType`.

zhenhao-ma:
- Investigate the review feedback about the missing Phase 3 helper extraction.
- If correct, move canonical `CommerceEntityType` into helpers and align downstream repos.

Ai:
- Added full-superset `CommerceEntityType` to helper typings, exported it through `keble_helpers.typings` and root package imports, added README/test coverage, and bumped the package to `1.11.10`.

## 2026-03-07 18:26 CST
State: branch `keble-helpers-1.11.11`; helper-owned `CommerceEntityType` keeps acronym-preserving title formatting.

zhenhao-ma:
- Investigate the latest review feedback.
- Fix helper acronym formatting regression after the shared enum migration.
- Continue the positioning follow-up phases from the current landed state.

Ai:
- Replaced the plain title-casing implementation of `CommerceEntityType.upper_snake_to_title()` with acronym-aware formatting so `SKU` remains uppercase.
- Added regression coverage for `SKU` and `BRAND_MENTION`, updated README guidance, and bumped the package to `1.11.11`.
