OrderAnchor

OrderAnchor helps a custom-printing team catch changed customer instructions before production. It interprets order messages for a human to confirm, keeps the reviewed order history in Hindsight, and checks an editable production brief against the currently supported details. The application also answers order questions and questions about a clearly labeled synthetic company/customer dataset.

1. Configure .env

Clone this repository and open a terminal in its root. Copy the template; keep the resulting .env file private:

Copy-Item .env.example .env

Edit .env and supply your own values for:

HINDSIGHT_BASE_URL=<your Hindsight API base URL>
HINDSIGHT_API_KEY=<your Hindsight API key>
GROQ_API_KEY=<your Groq API key>

Keep the other values from .env.example unless you need to change them. GROQ_MODEL selects the extraction model; DATABASE_PATH controls the local SQLite file; DEMO_MODE=true enables the fresh-demo-run action. Do not commit .env or paste keys into the browser. The Hindsight URL must be an http or https API base URL without credentials or query parameters.

The site can start with empty keys, but message interpretation and verified order-memory checks require the configured external services. /api/health only reports whether credentials are present; it does not prove the services are reachable.

2. Install and launch

Use regular, GIL-enabled Python 3.11–3.13. From the repository root in PowerShell:

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8765

Use py -3.12 or py -3.11 instead if that is your installed version. Do not use the free-threaded 3.13t build with these pinned packages. Open http://127.0.0.1:8765/ in a browser. API documentation is at http://127.0.0.1:8765/docs.

No frontend build or migration command is needed. The server serves the HTML, CSS, and JavaScript and creates/updates its SQLite schema at startup. The default database is var/orderecho.sqlite3; it is local data and is ignored by Git. Run one Uvicorn process with its default single worker.

3. Try the workflow

You can create an order in the browser, or seed three fictional orders from a second terminal while the server is running:

.\.venv\Scripts\python.exe -m scripts.seed_demo

Seeding uses data/demo_orders.json, real order/message/review/check paths, and Hindsight, so valid Hindsight credentials and network access are required. --new-run creates a separate synthetic namespace without deleting previous runs. Seeding does not call Groq for its pre-reviewed sample interpretations; create a new message in the browser to exercise live Groq extraction.

In the website, select or create an order, add messages in the order they were sent, and confirm or reject each suggested interpretation. Confirmed details appear in Current order details. Edit a field in Update the brief, then select Check brief to compare the planned brief with the reviewed instructions. Update report reruns the check; the download action is available only when the displayed report matches the current form. Ask OrderAnchor about the selected order, or ask about synthetic customers, sales, or reviews. Complete an order to open its 24-hour restart window, or delete an order with confirmation.

Only reviewed customer instructions can establish an approved change. A check may return CHANGES_REQUIRED or HOLD when values disagree or the evidence is incomplete. A READY result means the checked brief is consistent with verified instructions; it is not an authorization to manufacture.

Data and verification

data/demo_orders.json and data/synthetic_business_data.json are fictional. data/synthetic_production_schedule.json contains an illustrative two-minutes-per-shirt estimate, not a factory capacity or delivery promise. The app does not import email/chat histories or place manufacturing orders.

For local automated tests, install the development requirements and run:

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -m "not live" -q

With live credentials, check the external services using:

.\.venv\Scripts\python.exe -m scripts.smoke
.\.venv\Scripts\python.exe -m scripts.live_acceptance

These live checks create synthetic records in your configured Hindsight account and may use paid service quotas. The application stores orders, messages, reviews, check results, and job states in SQLite. Hindsight stores reviewed documents by order; Groq proposes structured interpretations. Failed or unverifiable memory retrieval holds a check instead of treating missing evidence as approval.