launchguard-ai README

项目的 README,来自 github.com/Jack81st/launchguard-ai。合并为一个 markdown 文件:README.md。

LaunchGuard AI

A reviewable product-launch workflow for pricing, policy checks, and Shopify drafts.

Python 3.9–3.12 LangGraph CI Coverage Shopify License: MIT

Quickstart · Architecture · Engineering Report · Threat Model · Roadmap · Contributing


The problem

A supplier record can become a product listing before anyone has checked the margin assumptions, applicable policies, or approval history. LaunchGuard keeps those decisions in one traceable workflow:

catalog and cost inputs
→ sourced FX rate
→ versioned policy citations
→ contribution-margin scenarios
→ structured listing draft
→ deterministic compliance checks
→ durable human review
→ idempotent Shopify DRAFT

LaunchGuard works from catalog and cost data supplied by the operator. It does not estimate demand or marketplace sales. If required evidence or approval is missing, the run stops before Shopify delivery.

LaunchGuard architecture and durable review boundary

How it works

Design choice Implementation Operational value
Checkpointed review LangGraph interrupt() plus SQLite checkpoints and stable thread IDs A run can pause, survive process restart, and resume after review
Deterministic business rules FX, pricing, retrieval, compliance, persistence, and delivery use explicit services Calculations and controls remain inspectable and testable
Traceable inputs Strict CSV/JSON SKU contract with a source reference Reviewers can see where the commercial assumptions came from
Versioned policy retrieval SQLite FTS5, market filters, effective dates, source paths, and citation IDs Reviewers can inspect exactly which rule supported the draft
Unit economics Duty, shipping, fulfillment, fees, VAT, returns, ads, margin, FX, and four stress scenarios Makes commercial feasibility visible before copy is approved
Draft-only delivery Dry-run default, explicit review, deterministic handle, remote lookup, local ledger, Shopify DRAFT status Reduces accidental publishing and duplicate products
Evaluation gate Reproducible cases for clean launches, commercial warnings, and prompt-injection blocking Changes can be measured instead of judged only by demos

Control room

LaunchGuard control room with a product review waiting for approval

Use the control room to start a launch review, compare the recommended price with its floor, inspect the FX source and policy citations, and approve or reject the draft. Runs waiting for review remain available after a restart.

Quickstart

Local Python

git clone https://github.com/Jack81st/launchguard-ai.git
cd launchguard-ai
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
launchguard serve

Open http://127.0.0.1:8080. The default setup works without model or Shopify credentials.

Docker

docker compose up --build

SQLite run history and checkpoints are stored in the launchguard-data volume.

Durable CLI review

Start an offline demonstration run:

launchguard start \
  --catalog examples/catalog.csv \
  --sku LG-BTL-001 \
  --offline

The command returns a run_id and exits with pending_approval. The process can now stop. Resume the same checkpoint later:

launchguard decide \
  --run-id lg_your_run_id \
  --action approve \
  --reviewer "Operations reviewer" \
  --note "Evidence, margin floor, and policy citations reviewed"

Reusing a completed run_id does not create another delivery.

Pricing model

LaunchGuard solves the price required to preserve the target contribution margin:

fixed cost = converted product cost + converted inbound shipping + duty + fulfillment

minimum price = fixed cost /
  (1 - platform fee - VAT - returns reserve - ad cost - target margin)

Each review includes:

The pricing result is decision support, not a forecast. Every input appears in the review package so the assumptions can be checked before approval.

Policy retrieval and generation

Policies are Markdown files with required metadata:

---
id: PRICING-GOVERNANCE-2026-02
title: Contribution Margin and Pricing Governance
market: GLOBAL
effective_date: 2026-02-01
---

SQLite FTS5 retrieves market-appropriate sections and returns the document ID, effective date, source path, content, and score. The default listing builder is deterministic. An OpenAI-compatible endpoint can be enabled for model-written copy, but the response must still pass schema validation and may cite only retrieved evidence IDs.

Shopify safety

Live delivery is unavailable unless all of these conditions are true:

  1. deterministic checks report no blockers;
  2. the graph is resumed with an explicit named reviewer decision;
  3. LAUNCHGUARD_SHOPIFY_MODE=live is configured;
  4. a valid *.myshopify.com domain and Admin API token are present.

The connector then:

Rate limits and transient server failures are retried. GraphQL user errors and partial price-update failures are surfaced rather than converted into success.

Quality evidence

make lint
make test
make eval

CI runs on Python 3.9, 3.11, and 3.12, enforces at least 80% branch-aware coverage, executes the evaluation gate, and builds the production container. Tests use mock transports and never need paid credentials.

Current verification results:

These figures measure the repository's test and regression suite; they do not measure commercial lift. The bundled evaluation reports:

See the engineering report for the design rationale, verification scope, and known limitations.

API

FastAPI exposes:

Method Endpoint Purpose
POST /api/runs Validate evidence and run until completion or review interrupt
GET /api/runs List recent runs
GET /api/runs/{run_id} Read persisted state and audit events
POST /api/runs/{run_id}/decision Resume a pending checkpoint with approve/reject and optional edits
GET /health Container and service health

Interactive OpenAPI documentation is available at /docs.

Repository layout

src/launchguard/
├── api.py                    # FastAPI and control-room API
├── workflow.py               # LangGraph, interrupt, resume, checkpointing
├── models.py                 # Strict evidence and output contracts
├── store.py                  # Run, event, approval, and delivery ledger
├── connectors/
│   ├── catalog.py            # Validated CSV catalog input
│   ├── fx.py                 # Live FX with explicit fallback provenance
│   └── shopify.py            # Guarded GraphQL draft delivery
└── services/
    ├── policies.py           # Versioned FTS5 retrieval
    ├── pricing.py            # Unit economics and stress scenarios
    ├── generation.py         # Deterministic and optional LLM generation
    └── compliance.py         # Deterministic safety and policy checks

Honest boundaries

Originality and license

This repository started with an empty Git history. It is not a fork and contains no BorderPilot source code, assets, history, or documentation. LaunchGuard uses open-source libraries through their documented APIs and is released under the MIT License.

launchguard-ai (Jack81st/launchguard-ai)

正在搜索数据库…

这是什么?LaunchGuard AI 是一个持久可靠、以证据为先的工作流,基于 LangGraph 构建,用于审核产品上架:计算定价、引用适用政策、要求人工审批,并可创建 Shopify 商品草稿。
这是我可以导入的库,还是独立工具?它是一个独立的 Python 服务/工具:你可以通过 CLI 运行,也可以作为带 API 的 FastAPI 服务器运行,而不是嵌入你自己代码中的库。
我该如何让它运行起来?可以用 Python 在本地运行,也可以通过 Docker 启动;Docker 方式下,SQLite 运行历史和检查点保存在 launchguard-data 卷中。
试用它需要 Shopify 或 OpenAI 凭据吗?不需要。默认配置无需任何模型或 Shopify 凭据即可运行,并以试运行模式执行;真正的 Shopify 发布需要设置 LAUNCHGUARDSHOPIFYMODE=live,以及 .myshopify.com 域名和 Admin API 令牌。
什么能阻止有问题或未经批准的商品上线?如果缺少必需的证据,或缺少明确指定的审核人批准,运行会在任何 Shopify 发布之前停止;同时,确定性检查也必须报告没有阻断性问题。
定价模型如何运作?它求解出能保持目标贡献利润率所需的价格,综合考虑关税、运费、履约、费用、增值税、退货、广告和汇率,然后用四种情景对结果进行压力测试,例如汇率不利波动 3%、退货率上升 2 个百分点(+2pp)。
什么是控制中心?它是审核界面,你可以在这里发起上架、将推荐价格与价格下限进行比较、查看汇率来源和政策引用,并批准或拒绝草稿;待处理的运行在重启后依然保留。
政策引用从哪里来?政策是带有必需元数据的 Markdown 文件,通过 SQLite FTS5 检索;生成的任何商品文案只能引用已检索到的证据 ID,并且必须通过模式校验。
这个项目的测试做得怎么样?在 Python 3.9/3.11/3.12 上的 CI 报告显示:34 项测试通过,考虑分支的覆盖率为 83.76%;在随附的评估集上,3/3 个评估用例通过,决策准确率和引用覆盖率均为 100%。
作者
Jack81st
大小
2.3 MB
星标
101
更新
提交Oct 07
时长
1个月
提交 · 90 天