Return Recovery

Find the right accounting record for a refund that already settled.

A customer returns a $60 lamp. Their order contains two lines with the same SKU, billed on different invoices. The payment processor confirms the refund, but the accounting system has no credit. Return Recovery traces the refund to the original order line, asks an operator to approve the exact correction, and checks that the accounting record exists after the write.

The demo runs a real InterSystems IRIS AI Hub agent with DeepSeek inside an interoperability production. Storefront, payment, warehouse, and accounting records are simulated.

Run the native demo · Try the cases · How it works · Verify

Run the native demo

Use Docker with the Compose plugin, Python 3.11+, and a DeepSeek API key with available balance. The verified IRIS image is AI Hub Community 2027.1.0AI.109.0 for ARM64. Download the matching Docker archive and container license key from the InterSystems AI Hub Early Access portal.

1. Clone the repository and load your downloaded archive.

   git clone https://github.com/kris70lesgo/return-recovery.git
   cd return-recovery
   docker load -i /path/to/iris_arm64-community-2027.1.0AI.109.0-docker.tar.gz
   docker image ls
   

2. Copy your downloaded license and generate local credentials.

   mkdir -p data
   cp /path/to/iris-container-arm64.key data/iris-container-arm64.key
   chmod 644 data/iris-container-arm64.key
   python3 scripts/setup_local.py
   

   In the generated .env, set IRIS_IMAGE to the exact repository:tag shown by docker image ls, and set DEEPSEEK_API_KEY to your key. The script generates IRIS_PASSWORD and RECOVERY_BRIDGE_TOKEN. The image, license, and credentials stay local.

3. Start the services. Run iris qlist until it reports running, then load and start the native production.

   docker compose --profile iris up -d --build
   docker compose exec -T iris iris qlist
   docker compose exec -T iris iris session IRIS < iris/install.script
   

   The installer prints Return Recovery native production installed. on success. The native health endpoint reports production_running: true. Sign in with _SYSTEM and the generated IRIS_PASSWORD.

4. Open Return Recovery. Choose Native IRIS AI Hub, then Investigate case → Approve correction → Apply and verify. The expected receipt is an accounting credit of $60.00 for line L2 → invoice INV-102. The customer payment stays settled.

With Colima or another named Docker context, replace docker in each command with docker --context YOUR_CONTEXT. The dashboard and IRIS REST port bind to localhost. Compose volumes preserve case state and agent sessions across restarts.

Try without a model key

After cloning, run python3 scripts/setup_local.py and docker compose up -d --build. Open the same dashboard URL and choose Rules baseline. This runs the deterministic recovery demo without starting IRIS.

Try the cases

Use Rules baseline for repeatable failure demonstrations. The sidebar contains all 12 fixtures, and Simulation controls → Reset this case returns a fixture to its starting state.

How it works

flowchart LR
    UI["Next.js dashboard"] --> API["Recovery API"]
    API --> S["IRIS Business Service"]
    S --> P["IRIS Business Process"]
    P --> O["IRIS Business Operation"]
    O --> A["AI Hub agent · DeepSeek"]
    A -->|Read evidence and return a decision| API
    API --> V["Validate proposal against records"]
    V --> H["Operator approval"]
    H --> R["Apply and verify accounting receipt"]

The AI Hub agent reads six sources through scoped tools and decides whether the case is ready, needs review, or needs more evidence. The recovery engine derives the correction from authoritative line, invoice, settlement, and policy records. Operator approval binds the proposal to the evidence revision. Each correction has a stable operation ID, and the app checks the simulated ledger after applying it or recovering from a lost acknowledgment.

Verify

Install uv to run the test commands.

uv run --frozen pytest -q
uv run --frozen python scripts/smoke.py
# With the native Compose bundle running, this calls DeepSeek.
uv run --frozen python scripts/native_smoke.py --case RR02 --apply
uv run --frozen python scripts/native_smoke.py --case RR04

The suite passes 38 tests. A native run of RR02 used 3 model requests and 7 tool calls, wrote one simulated accounting record, and verified it. RR04 returned human review with zero proposed writes. The IRIS production trace shows the service, process, and operation messages. AI Hub stores the agent session, and the proposal records the session ID and token counts.

The demo exercises an isolated simulated ledger. Results describe fixture behavior and do not establish production reliability or an advantage over the rules baseline.

License

Project source is available under the MIT License. Obtain InterSystems IRIS AI Hub and its license separately from InterSystems.