README.md
# Crossborder AI FDE Kit
Multimodal commerce workflow toolkit for AI product video, Amazon listing operations,
Shopify / independent-site audits, private-domain CRM, EDM deliverability and product
selection research.
This repository is designed as a public artifact for a **Multimodal AI Product Manager**
and **Cross-border Commerce FDE Architect** profile. It does not try to be another
generic ecommerce dashboard. It shows how product facts, channel rules, visual QA,
creator content, email delivery and sourcing signals can be turned into repeatable
operating loops.
## What This Repo Demonstrates
- **Multimodal product judgment**: product-truth cards, image-text QA criteria, failure
labels and model-routing memory.
- **Amazon operations**: listing angle checks, review-objection mining, video / image
content recommendations and SKU-level next actions.
- **Independent-site execution**: hero clarity, offer hierarchy, trust signals, CTA
checks and paid-traffic landing-page readiness.
- **Private-domain growth**: lead segmentation for WhatsApp / WeCom / email follow-up
without turning the workflow into spam automation.
- **EDM quality**: SPF / DKIM / DMARC readiness thinking, subject-line risk, CTA clarity,
consent and deliverability checklist.
- **Product selection research**: simple scoring for sourcing candidates based on demand,
margin, review pressure, competitor density and content opportunity.
- **Trend-to-factory intelligence**: BERTopic-compatible trend clustering, Mermaid trend
chart output and factory matching by category, capability, market and MOQ.
## Repository Map
```text
src/commerce_fde/
multimodal.py Product truth, prompt routing, QA labels and model loop memory
amazon_ops.py Amazon listing and review-objection analysis
site_audit.py Shopify / independent-site landing-page checks
private_domain.py Lead segmentation and follow-up playbooks
edm.py EDM deliverability and message quality audit
sourcing.py Product selection scoring and lightweight page fetch utility
trend_intelligence.py
Trend topics, chart data and factory matching
cli.py JSON-in, JSON-out workflow CLI
docs/
architecture.md
open_source_reference_map.md
skills/
trend-factory-match.skill.md
examples/
sample_product.json
sample_sourcing_rows.json
sample_trend_documents.json
sample_factories.json
tests/
test_core.py
```
## Quick Start
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
commerce-fde audit examples/sample_product.json
commerce-fde score-sourcing examples/sample_sourcing_rows.json
commerce-fde trend-factory examples/sample_trend_documents.json examples/sample_factories.json
```
Optional BERTopic engine:
```bash
python -m pip install -e ".[topic]"
```
Without the optional dependency, the trend command uses a lightweight original
fallback so the public repo stays easy to install.
Run tests:
```bash
python -m unittest discover -s tests
```
## Example Output Shape
The main audit command returns a single JSON bundle:
```json
{
"multimodal": {
"qa_labels": ["product_shape_risk", "hand_object_contact", "commercial_readability"],
"model_route": "image-first -> video-model-test -> QA -> memory"
},
"amazon": {
"buying_reason": "portable cold-drink routine for daily use",
"listing_actions": ["tighten title", "add comparison image", "make 15s feature proof video"]
},
"site": {
"hero_score": 78,
"missing_signals": ["trust proof", "clear CTA above fold"]
},
"private_domain": {
"segment": "warm_product_interest",
"next_step": "send product-proof clip and one objection-handling message"
},
"edm": {
"risk_level": "medium",
"fixes": ["make consent source explicit", "reduce promotional wording"]
}
}
```
## Compliance And Ethics
This project intentionally avoids bypassing platform protections, scraping behind login,
mass unsolicited messaging, or pretending generated assets are final product evidence.
The crawler utility is a lightweight research helper and should be used only on pages
where collection is permitted by law, robots.txt and platform terms.
The trend module is built for decision support. It should not be used to claim hidden
platform data access; feed it lawful public observations, owned data exports or manual
research notes.
## Open Source Reference Notes
This repository is original code. It references proven open-source categories such as
CLIP-style image-text matching, web crawling frameworks, Shopify SDKs, email frameworks
and DMARC parsing tools. See [docs/open_source_reference_map.md](docs/open_source_reference_map.md).
## License
MIT.
skills/trend-factory-match.skill.md
# trend-factory-match.skill
Purpose: turn social/search/review trend signals into a factory shortlist and a
content-test plan for cross-border commerce.
## Loop
```text
intake
-> collect trend documents
-> topic-model with BERTopic optional adapter
-> chart demand signals
-> match factory capabilities
-> create product-truth card
-> route content test by channel
-> record result memory
```
## Inputs
- Trend documents: TikTok searches, Amazon reviews, Shopify competitor pages,
ad-library observations, creator comments.
- Factory profiles: category, capabilities, certifications, target markets, MOQ,
lead time, sample availability and content assets.
- Channel target: Amazon, Shopify, TikTok Shop, Reels, Shorts or Brazil B2B.
## Output
- Topic clusters with interpretable keywords.
- Mermaid chart data for trend strength.
- Ranked factories with match reasons.
- FDE next step: sample request, product-truth card, AI video angle or watchlist.
## Product Judgment
The skill does not treat "hot trend" as enough. A good candidate needs:
- visible buyer problem;
- factory capability and certification fit;
- enough margin to test content;
- product truth that can be shown visually;
- clear Amazon / Shopify / TikTok content angles;
- low risk of exaggerated claims or fake-looking video.
## Positioning
This skill is designed to show multimodal AI product-management thinking:
trend text becomes product opportunity, product opportunity becomes visual brief,
visual brief becomes factory validation and channel-specific content tests.