# Verniq invoice demo runbook

AWS: **https://paint-invoicing.sol-se-emea.com**, self-service with no login.
Keep the Mac and relay online. See
[the AWS operator guide](deploy/aws/README.md) for hosted test commands.

Local: **http://localhost:8810**. SAM is at **http://localhost:8800**. The standalone A2A agent is on port 8811. The webpage
has separate Supplier invoices (AP) and Customer invoices (AR) sections.

## Start

```bash
cd /Users/raphaelcaillon/Documents/github/sam-invoice-pricing-reconciliation
.venv/bin/python scripts/start.py
# First installation or after changing agent configuration:
.venv/bin/python scripts/configure_sam.py
```

For a new checkout: `python3 -m venv .venv`, then
`.venv/bin/pip install -r requirements.lock.txt`. Configure `.env` using
`.env.example`. The current machine already has the SAP-only model proxy
running on port 3000. Credentials are read from its existing private env file,
not copied into the repository. SAM uses its existing home and data store.

## Automatic mode

Auto agents is on by default. Broker events invoke the next agent. Human approvals still gate hours, messages and rule application. The page updates as agents finish. Turn Auto agents off to pause orchestration for the manual scripts. A session reset waits for active work and pending delivery.

```bash
.venv/bin/python scripts/test_event_driven.py
```

This verifies the automatic AP and AR path using real SAM and SAP AI Core calls.

## Present

| Flow | Script | What to show |
|---|---|---|
| Supplier | docs/SUPPLIER_DEMO_SCRIPT.md | Clean acceptance, approved supplier conversation, EUR 2,070.70 prevented, buyer-approved 2% surcharge fix |
| Customer | docs/CUSTOMER_DEMO_SCRIPT.md | Sales billing checks, customer conversation, EUR 300 recovered, approved 1.5% sales condition, credit/delivery hold |

Submit an invoice opens the sample selector and PDF/JSON upload. Download the
individual PDF there, or use `samples/supplier/` and `samples/customer/` JSON
files. Printable examples are in `output/pdf/supplier/` and
`output/pdf/customer/`. The combined PDF is a reference book, not an upload
file. The parser accepts individual readable sample PDFs, not arbitrary
scanned invoices. Review extracted fields before submitting.

The Decision tab shows deterministic checks and an actual SAP AI SDK
explanation. Conversation calls live local SAM. Approvals uses explicitly
labeled demo personas. With Auto agents on, approving triggers the matching agent action. With it paused, run the matching action. Master data
shows the bounded proposal. Events shows every transition and approver user.
The page's SAM link opens the registered agents and execution trace.

## Reset and test

Click **New demo session** to start a fresh dataset without deleting previous
records. Do this before repeating fixed sample invoice IDs. Supplier and
customer flows can share a session.

```bash
.venv/bin/python scripts/demo_supplier.py --new-session --with-agents
.venv/bin/python scripts/demo_customer.py --with-agents
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python scripts/llm_smoke_test.py
```

Omit --with-agents for the fast deterministic HTTP scenarios. Never run two
scripts with --new-session concurrently. Logs, saved sessions, the local
broker audit and agent artifacts are under `.runtime/`, which is ignored by
Git. Application readiness: `/api/health`. Startup logs: `.runtime/web.log`
and `.runtime/sam.log` when started by the script.

## Scope

Live: local SAM agents, SAP AI SDK inference through existing SAP AI Core,
agent tools, embedded broker delivery, SQLite audit and approvals. Simulated:
SAP documents/posting and supplier/customer portals. Implemented integration code still awaiting tenant configuration: BTP deployment,
SAP Joule registration, live XSUAA role assignment, S/4HANA Destination qualification, external AEM durable
queues and ACL validation. The local app is bound to loopback. It is not a
production deployment. AEM setup defaults to an offline plan:
`.venv/bin/python scripts/aem_setup.py`.