Metadata-Version: 2.4
Name: keble-amz
Version: 2.0.0
Summary: Typed Amazon raw-data provider services for Keble.
Author-email: zhenhao-ma <bob0103779@gmail.com>
Requires-Python: <3.14,>=3.13
Requires-Dist: keble-data-infra-contract<1,>=0.1.0
Requires-Dist: keble-db<2,>=1.9.0
Requires-Dist: keble-helpers<2,>=1.49
Requires-Dist: keble-keepa<2,>=1.3.0
Requires-Dist: motor<4,>=3
Requires-Dist: pydantic<3,>=2
Requires-Dist: redis<6,>=5
Requires-Dist: sentry-sdk<3,>=2
Description-Content-Type: text/markdown

# keble-amz

`keble-amz` 2.x is the framework-free Amazon raw-data provider package. The
legacy 1.x monolith remains preserved on maintenance branch `1.0.28`; current
source no longer embeds Keepa, cost analysis, shuffle/LLM analysis,
ScraperAPI, or bundled wheels.

Install the current public provider line with
`pip install "keble-amz>=2.0.0,<3"`. Its public dependency bounds require the
released data-infra contract, `keble-db>=1.9.0`, and `keble-keepa>=1.3.0`.

## Architecture

```text
keble-data-infra-contract
          ↑
keble-amz: AmazonServices ──> keble-keepa
          │                       │
          └── RedisLeaseManager <-┘ Mongo/Redis cache
```

`AmazonServices` exports three typed operations through one provider manifest:

- `lookup_products(ProductLookupQuery)` — exact batched ASIN lookup;
- `search_products(ProductSearchQuery)` — Keepa title finder plus product load;
- `rank_products(ProductRankingQuery)` — current official Amazon category
  bestseller board.

Provider methods return only `keble-data-infra-contract` values. Keepa DTOs,
cache policy, and usage accounting remain owned by `keble-keepa`. Shared
`Money`, `AmazonMarketplace`, hashing, and Redis owner-token leases are reused
from Keble packages rather than redeclared.

The package exports no FastAPI app or router. `keble-data-infra-api` consumes
the manifest and owns all paths, OpenAPI, error handlers, and runtime clients.

## Cache and concurrency

Keepa remains the only normalized provider cache. Amazon wraps complete
operation requests in `RedisLeaseManager` single-flight keys. Every contender
re-enters the Keepa handler after acquiring ownership, so it rechecks Mongo and
spends no upstream call after the first owner persists the result.

Redis lease acquisition and the cache-recheck-or-upstream critical section emit
Sentry child spans when the API initializes telemetry. Span names contain only
the stable Keepa operation and never ASINs, keywords, request JSON, responses,
or credentials.

Lookup delegates to `KeepaApiBatchLoader`, preserving exact per-ASIN cache
keys, caller order, duplicates, partial hits, negative hits, newest-write-wins
repair, request batching, and usage accounting.

## Verification

Python 3.13 and uv are required:

```bash
uv lock --check
uv run pytest -q \
  -m "not live and not slow and not eval and not local_stack and not db_stack and not container"
KEBLE_BACKEND_ENV_FILE=/path/to/keble.backend/.env \
RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 \
  uv run pytest -q tests/integration
KEBLE_BACKEND_ENV_FILE=/path/to/keble.backend/.env RUN_KEEPA_LIVE=1 \
  uv run pytest -q tests/live -m "live and keepa_live"
uv run npx --yes pyright .
uv build
```

Integration/live tests use unique Redis namespaces and Mongo collections and
clean them after each run. Secrets resolve by explicit name through the shared
backend-env test helper and are never copied into this repository.
