The Maybe Engine

The Maybe Engine is a bank-delivered hackathon prototype for autonomous, explainable financial judgment. It turns an employee purchase request into an immediate Yes, No, or actionable Maybe while respecting the bank's boundary, the CEO's mandate, and the company's financial position.

The prototype answers one question:

If twelve premium laptops do not fit the CEO's mandate, can the system find a viable alternative that still delivers the customer project?

The happy-path answer is Maybe → Yes: reduce the commitment from 180,000 SEK to 128,000 SEK, preserve twelve devices and the Friday deadline, protect the cash buffer, and avoid 52,000 SEK.

What the solution demonstrates

• An employee describes the business outcome and what the system may negotiate.
• FastAPI gathers sanitized evidence from the existing Zwapgrid and Open Payments sandbox adapters, curated financial test data, and clearly labelled simulated security and legal sources.
• OpenAI Terra creates a structured counterproposal when the original request does not fit.
• Deterministic backend controls validate amount, budget, liquidity, supplier, quantity, and risk conditions. The model cannot waive those controls.
• Accepting the alternative re-runs validation and creates a decision record.
• Payment and accounting are presented as explicit next-step handoffs; the prototype does not claim that either action has been executed.
• The CEO dashboard shows decisions actually made, opens an outcome-focused decision record, and exposes the mandate-grounded Decision Brief.
• The CEO can deliberately open Simulate mandate using this decision to replay that exact case with different boundaries and risk tolerances.
• The bank view shows aggregate facility impact without exposing internal company prompts or judgment context.

Happy flow

1. Open Employee and review the prefilled request for twelve premium laptops from Premium Devices AB at 180,000 SEK.
2. Select Ask the Maybe Engine. The backend checks the company position, provider evidence, CEO mandate, and available negotiation levers.
3. Review Maybe — here is a viable path. The proposed alternative buys eight devices, rents four for six weeks, changes supplier, and caps the commitment at 128,000 SEK.
4. Inspect the evidence to distinguish live sandbox traces, curated test data, and simulated provider messages. The Terra context can also be inspected without revealing credentials or private model reasoning.
5. Select Accept alternative. The result becomes Yes — alternative approved, with 52,000 SEK avoided and the cash buffer preserved.
6. Review the outcome-focused payment and accounting cards. Their CTA buttons currently show frontend confirmations only; no payment or write-back occurs.
7. Open CEO. The Premium Devices decision now appears at the top of Decision Activity.
8. Select See decision details, then expand Decision Brief to inspect the actual explanation and conditions behind the decision.
9. Select Simulate mandate using this decision to load the Atlas case into Mandate Workbench and test different mandate scenarios.
10. Open Bank to show projected facility utilization and remaining headroom without revealing the CEO's internal context.

Application views

View	Purpose
Employee	Capture the requested business outcome and allowed negotiation levers.
Decision	Explain why the original request does not fit and present a validated alternative.
Accepted outcome	Confirm the business result and show honest payment/accounting handoffs.
CEO	Show decision activity, Decision Briefs, and decision-based mandate simulation.
Bank	Show aggregate exposure and available capacity without exposing internal prompts.

Decision and AI responsibility

The prototype separates policy, negotiation, and explanation:

1. Deterministic backend checks establish whether a request fits the mandate.
2. Terra may construct a structured counterproposal for the employee flow.
3. The backend validates every actionable proposal field before displaying it.
4. Acceptance re-runs the same controls, so a modified or unsafe proposal fails.
5. Terra writes the human-readable Decision Brief from the mandate, case data, and policy result. It does not choose or override the deterministic outcome.
6. If Terra is unavailable or returns an invalid proposal, a safe template fallback keeps the demo operational and is labelled accordingly.

In Mandate Workbench, amount, liquidity, and risk-tolerance parameters affect the policy result. The Decision-brief context fields affect the generated explanation only; they are not hidden policy rules in this MVP.

Data and integration modes

Capability	MVP mode	What the interface claims
Zwapgrid consent	Existing live sandbox adapter	Sandbox response is inspectable; credentials remain server-side.
Accounting position	Curated test data	The displayed balance is test data, not a live ledger balance.
Open Payments bank discovery	Existing live sandbox adapter	Sandbox bank/API trace is inspectable; no payment is initiated.
Recorded Future	Simulated provider plug	Scenario-aware security risk messages, always labelled simulated.
Legora	Simulated provider plug	Scenario-aware legal messages, always labelled simulated.
Counterproposal	Terra with safe template fallback	Model proposes; deterministic controls validate.
Decision Brief	Terra with safe narrative fallback	Model explains an application-owned policy result.
Payment action	Confirmation-only demo handoff	Bank authentication and authorization are still required.
Accounting action	Proposed entry	No accounting write-back has occurred.

Sandbox availability never owns the core judgment path. Missing configuration or a provider error is returned as inspectable evidence status instead of breaking the happy-flow decision.

CEO decision records

The CEO dashboard intentionally avoids persistence for this hackathon slice:

• The accepted Premium Devices decision is held in browser state for the current session and appears immediately in Decision Activity.
• Three additional decision records are seeded demo cases.
• Opening a seeded record calls the existing mandate-evaluation endpoint to create its actual Decision Brief. The response is cached for that browser session.
• Opening the current operational record reuses the proposal rationale and conditions already returned during the employee flow.
• Mandate Workbench remains hidden until the user chooses Simulate mandate using this decision.

This gives the demo a coherent story without adding authentication, a database, or dashboard infrastructure.

Architecture

Browser · Next.js
        |
        | same-origin /api/* requests
        v
FastAPI orchestration boundary
        |
        |-- deterministic mandate and acceptance controls
        |-- Terra counterproposal and Decision Brief generation
        |-- existing Zwapgrid sandbox adapter
        |-- existing Open Payments sandbox adapter
        `-- curated and simulated evidence plugs

Browser session state
        |-- employee request, proposal, and acceptance
        |-- current CEO decision + seeded decision history
        `-- seeded bank presentation state

The browser only talks to FastAPI. Provider behavior, model calls, prompts, policy logic, and all secrets remain in the backend. Next.js forwards /api/* to FastAPI so local-network or tunnel users only need access to the frontend.

Run locally

Prerequisites:

• Python 3
• Node.js and npm
• An OPENAI_API_KEY for live Terra text generation
• Optional Zwapgrid and Open Payments sandbox credentials

Backend

cd backend
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
.venv/bin/uvicorn app.main:app --reload --port 8000

Set OPENAI_API_KEY in backend/.env. The default model is gpt-5.6-terra; it can be overridden with OPENAI_MODEL. Keep LLM_MODE=openai for generated demo text.

Frontend

In a second terminal:

cd frontend
npm install
npm run dev

Open http://localhost:3000.

The default backend target is http://127.0.0.1:8000. Set BACKEND_ORIGIN in frontend/.env.local only when FastAPI runs elsewhere.

Environment configuration

Copy backend/.env.example to backend/.env. Relevant variables are:

OPENAI_API_KEY
OPENAI_MODEL=gpt-5.6-terra
LLM_MODE=openai

ZWAPGRID_CONSENT_BASE_URL
ZWAPGRID_ACCOUNTING_BASE_URL
ZWAPGRID_API_KEY
ZWAPGRID_CONSENT_ID

OPENPAYMENTS_CLIENT_ID
OPENPAYMENTS_CLIENT_SECRET
OPENPAYMENTS_AUTH_HOST=https://auth.sandbox.openbankingplatform.com
OPENPAYMENTS_API_HOST=https://api.sandbox.openbankingplatform.com

Legacy OPENPAYMENTS_ID and OPENPAYMENTS_SECRET names are accepted by the backend. Never put provider or OpenAI secrets in frontend environment files.

Share the demo

Local network

Keep FastAPI on port 8000, then expose only the frontend:

cd frontend
npm run build
npm run start:share

Colleagues on the same network can open the machine's LAN address on port 3000. macOS may ask whether Node may accept incoming connections.

Temporary Cloudflare tunnel

For a short, supervised remote demo, run the optimized frontend on a loopback port and point a Cloudflare quick tunnel at it:

cd frontend
npm run build
npm run start -- -H 127.0.0.1 -p 3100
cloudflared tunnel --url http://127.0.0.1:3100

The generated trycloudflare.com address is temporary and changes when the tunnel restarts. A quick tunnel is unauthenticated: anyone with the URL can use the prototype and trigger backend-owned OpenAI or sandbox calls. Keep it open only during a supervised demo; use Cloudflare Access or another authenticated environment for broader sharing.

Verification

Run backend tests and frontend checks before a demo:

PYTHONPATH=backend backend/.venv/bin/python -m unittest discover -s backend/tests -v
cd frontend
npm run typecheck
npm run build

Manual smoke test:

1. Complete Employee → Maybe → Accept.
2. Confirm the payment and accounting CTA confirmation dialogs.
3. Open CEO and verify that Premium Devices is the first decision.
4. Open its Decision Brief and then its mandate simulation.
5. Inspect one Zwapgrid/Open Payments sandbox trace and one simulated provider record.

Repository shape

frontend/   Next.js happy flow, CEO dashboard/workbench, and bank view
backend/    FastAPI orchestration, rules, adapters, and Terra calls
docs/       Architecture and browser/backend API contract
scripts/    Local environment helper scripts

Additional documentation:

• Architecture
• API contract

Deliberate MVP boundaries

• One convincing laptop happy path
• No authentication or multi-tenancy
• No database or durable decision history
• No background job system
• No autonomous payment initiation
• No accounting write-back
• No live Recorded Future or Legora integration
• No production deployment or scalability architecture

These are intentional hackathon constraints, not hidden production claims.