README

A LangGraph multi-agent system that audits a live Magento 2 / Adobe Commerce catalog, finds data-quality problems across 5 dimensions, and auto-fixes them with human-in-the-loop approval and a one-command rollback journal.

CatalogGuard AI never writes to your store without explicit approval. Every applied change is journaled so any fix batch can be reverted with a single command.

What it audits

Dimension	Examples
Duplicates	Exact & near-duplicate products via embedding similarity (ChromaDB)
Attributes	Required attrs empty, wrong types, placeholders ("TBD"), missing images/weight
Content	Descriptions too short, keyword-stuffed, copied from feeds, HTML corruption
SEO	Missing/duplicate meta, length violations, missing alt text, thin content
Sanity	Zero categories, price=0 on enabled, special>regular, enabled+zero-stock

Architecture

flowchart TD
    S[Supervisor] --> E[ExtractorAgent]
    S --> D[DuplicateAgent]
    S --> A[AttributeAgent]
    S --> C[ContentAgent]
    S --> O[SEOAgent]
    S --> N[SanityAgent]
    S --> F[FixProposalAgent]
    F --> H[(Review Queue · HITL)]
    H --> P[ApplyAgent]
    P --> R[(Rollback Journal)]

Loading

Rule-based checks run before any LLM call (never spend a token on what a regex catches). LLM calls use structured outputs only and are traced in LangSmith. Provider is abstracted — Claude API ↔ AWS Bedrock is a config flag.

Quickstart

make install                                   # py3.11 venv + dev deps
cp .env.example .env                           # add Magento token + ANTHROPIC_API_KEY
make verify                                    # lint + types + compile + 100% core tests

python -m catalogguard extract                 # pull catalog -> SQLite (resumable)
python -m catalogguard audit --checks sanity,attributes,duplicates,seo
python -m catalogguard propose --checks seo    # generate AI fix proposals
python -m catalogguard serve                   # review UI at http://127.0.0.1:8000
python -m catalogguard apply --batch run-1     # apply APPROVED fixes (journaled)
python -m catalogguard rollback --batch run-1  # one-command revert

No API key? Set CATALOGGUARD_LLM_PROVIDER=stub to run the entire loop offline. Full walkthrough: docs/USER_GUIDE.md.

CLI commands

Command	Purpose
extract	Pull the catalog into the local SQLite cache (paginated, resumable).
audit	Scan cached products → reports/report.{json,md}.
propose	Audit + generate AI fix proposals into the review queue.
serve	FastAPI + HTMX review UI (approve / reject / edit / bulk-approve).
apply	Write APPROVED fixes to Magento with a rollback journal.
rollback	Restore the previous values of an applied batch.

Eval scorecard

The differentiator: a synthetic broken-catalog generator (catalogguard.evals.synthetic) injects known defects to give ground truth, and we report precision/recall/F1 per dimension. Reproduce with python evals/score.py; CI fails on any F1 regression (--check-baseline).

Dimension	Precision	Recall	F1
Sanity	1.00	1.00	1.00
Attributes	1.00	1.00	1.00
Duplicates	1.00	1.00	1.00
SEO	1.00	1.00	1.00

Rule-based checks are deterministic, so they recover every injected defect on the synthetic benchmark. LLM-scored content quality is evaluated separately with Ragas (faithfulness/length).

Engineering discipline

• Build-verified: make verify = ruff + mypy --strict + byte-compile + import-layering + pytest.
• 100% core coverage, enforced in CI (fail_under = 100).
• Traceable: every requirement maps to code → test → eval in docs/TRACEABILITY.md; CI fails if a requirement has no test.
• Logged: structured JSON runtime logs + token-cost ledger; build history in docs/build-log.md.
• Decisions recorded as ADRs in docs/decisions/.

Roadmap

• ✅ v0.1 — extract + audit (5 dimensions) + HITL review + apply/rollback + Magento admin module
• v0.2 — ChromaDB embedding index by default, LangSmith dashboards, Packagist release
• v0.3 — scheduled audits, Slack notifications, multi-store support

License

MIT © NavinDBhudiya