Merchval Kernel

An experimental policy-execution layer for AI-assisted business operations.

AI agents are good at understanding conversations, extracting information, and proposing actions. They should not independently decide whether a refund, claim, fee reversal, or other controlled business action is authorized.

Merchval sits between an AI agent and the systems that execute business actions:

Customer conversation
        ↓
AI proposes a structured action
        ↓
Merchval obtains trusted business evidence
        ↓
OPA evaluates the executable policy
        ↓
ALLOW · DENY · NEEDS_EVIDENCE · REQUIRE_APPROVAL
        ↓
Human approval or controlled execution
        ↓
Auditable DecisionPacket

The model can interpret the conversation. It cannot establish trusted facts, change the active policy, approve its own proposal, or convert a policy-engine failure into permission.

The agent proposes. Policy controls the decision.

Why Merchval exists

Business policy often lives in website pages, internal documents, support macros, spreadsheets, and employee knowledge.

Traditional automation is predictable but becomes brittle when customer language is ambiguous, evidence is missing, or exceptions require human judgment.

LLM agents handle ambiguous language better, but prompts alone are not a reliable authority boundary. A model can misunderstand a rule, use unsupported customer claims, over-promise an outcome, or attempt an action without the required approval.

Merchval separates these responsibilities:

• AI interprets unstructured conversations and proposes actions.
• Trusted adapters obtain facts from business systems.
• OPA evaluates versioned executable policy.
• Merchval manages missing evidence, approvals, audit history, and controlled execution.
• Humans retain authority wherever policy requires it.

Contracts-first and policy-first

Merchval combines two complementary approaches.

Contracts-first integration

Every important boundary has a structured and versioned contract:

• intent and evidence packs;
• trusted evidence with provenance;
• policy input and policy decision;
• approval requirements;
• DecisionPackets;
• action receipts and audit events.

Contracts make integrations testable and prevent prompts, model output, adapters, and policy engines from exchanging ambiguous data.

Policy-first authority

Business authority does not live in prompts or scattered application conditionals.

Executable policy determines:

• which evidence is required;
• which evidence sources are trusted;
• whether an action is eligible;
• when approval is required;
• which roles may approve;
• which obligations must be completed;
• what happens when policy evaluation fails.

Contracts define the language of the system. Policy determines what the system is allowed to do.

Who Merchval is for

Merchval is intended for teams building AI-assisted workflows where an incorrect action has financial, operational, or regulatory consequences:

• AI and platform engineers connecting agents to business tools;
• e-commerce teams automating refunds and returns;
• insurance operations collecting and reviewing claim evidence;
• banking operations preparing fee or dispute reviews;
• policy, risk, and compliance teams that need explainable decisions;
• support leaders who need consistent escalation and human approval.

Merchval is most relevant when an agent can propose an action but should not possess final authority.

How Merchval differs

Category	What it primarily provides	Where Merchval differs
LLM guardrails, such as NeMo Guardrails or Guardrails AI	Controls model inputs, outputs, topics, or dialogue behavior	Merchval governs business actions using trusted evidence, executable policy, approval authority, and durable audit records.
Agent frameworks, such as LangGraph or the Agents SDK	Orchestrates models, tools, memory, and agent workflows	Merchval can sit beneath an agent framework as the authority boundary before a protected tool executes.
Open Policy Agent	Evaluates structured input against Rego policy	Merchval uses OPA and adds the surrounding agent-to-policy workflow: evidence collection, missing facts, cases, approvals, receipts, and audit history.
Helpdesks and workflow tools	Route tickets and operational tasks	Merchval produces a policy-backed DecisionPacket that those systems can display, approve, or execute.
Prompt-only policy enforcement	Places policy instructions in the model context	Merchval treats model output as an untrusted proposal and keeps final authority outside the model.

Merchval does not attempt to replace OPA, agent frameworks, helpdesks, or business systems. It connects them around a stricter execution boundary.

Current proof

The repository contains one complete experimental vertical slice.

E-commerce refunds

A customer message becomes a structured refund proposal. Order amount, date, and customer verification come from a trusted adapter. OPA evaluates the refund policy and returns reasons, obligations, and approval requirements.

The included demonstration proves:

• free-text message ingestion;
• trusted versus model-proposed evidence;
• real OPA policy evaluation;
• policy revision provenance;
• missing-evidence handling;
• fail-closed behavior;
• human approval boundaries;
• auditable DecisionPackets.

The repository also includes bounded insurance-evidence and banking-review examples. These demonstrate that the contracts and packet workflow can transfer to other domains. They do not decide insurance coverage, authorize payouts, resolve banking disputes, or move money.

What Merchval is not

Merchval is currently a public-alpha engineering project. It is not:

• a production-ready authorization service;
• a replacement for legal or policy review;
• a guarantee of regulatory compliance;
• a system that automatically converts policy prose into correct executable rules;
• a payment, refund, insurance, or banking provider;
• a claim that AI agents become perfectly secure.

The project demonstrates a defensible architectural property:

Even when an AI agent misunderstands a request or receives adversarial instructions, it does not own the evidence, policy, approval, or execution authority.

What It Does

• Receives inbound support messages through /ingest, /webhooks/dev, or /webhooks/chatwoot.
• Creates or reuses workspaces and conversations.
• Deduplicates inbound messages by external message ID within a conversation.
• Runs the prediction and routing pipeline.
• Extracts facts such as order ID, reason code, and requested action from configured pack slots.
• Creates or updates DecisionPackets from the active workspace pack; bundled demos cover refund/return, insurance evidence completeness, and banking review recommendations.
• Asks one clarification question when required fields are missing.
• Supports packet actions such as approve, reject, edit, override, send, and retry send.
• Records audit events, outcome events, approval actions, and message history.
• Exposes a debug trace endpoint for inspecting a conversation end to end.
• Runs either synchronously or through a Celery worker when ASYNC_MODE=true.

Repository Map

• app/ - Python application package, tests, migrations, and local runtime config.
• app/kernel_api/ - FastAPI app, contracts, domain logic, services, DB models, and providers.
• app/kernel_worker/ - Celery worker entrypoint for async message processing.
• app/tests/ - Unit, API, scenario, simulator, and DB-gated tests.
• build/_schemas/ - Active MVP intent pack schema used by the runtime.
• fixtures/ - Order and scenario fixtures used by the pipeline and simulator.
• docs/ - Curated architecture, demos, launch positioning, and release evidence.

Main Runtime Flow

1. A message arrives through an ingest or webhook endpoint.
2. The API ensures a workspace and conversation exist.
3. The inbound message is persisted with a trace ID and dedupe protection.
4. The pipeline loads the active pack, routes text, extracts facts, and writes prediction/routing records.
5. For T3 cases declared by the active pack, a DecisionPacket is created or updated.
6. If information is missing, the kernel emits one clarification message.
7. A human or owner action approves, rejects, edits, overrides, sends, or retries the packet.
8. The kernel writes approval, audit, outbound message, idempotency, and outcome records.

See docs/architecture-high-level.md and docs/architecture-code-level.md for more detail.

Quickstart

The supported clean-clone path starts PostgreSQL, Redis, OPA, migrations, the API, and the worker with authentication enabled:

cd app
.\scripts\demo_up.ps1

cd app
./scripts/demo_up.sh

The script generates an ephemeral API key and waits for both the API and the OPA bundle. See docs/quickstart.md for setup, or run the outcome-driven agent refund-policy tutorial to submit a support message and inspect its trusted evidence, OPA decision, required approval, and audit trail.

Useful Configuration

Configuration is read from environment variables or .env in app/.

• DATABASE_URL - SQLAlchemy/Postgres URL.
• CELERY_BROKER_URL - Redis broker URL for Celery.
• CELERY_RESULT_BACKEND - Redis result backend URL for Celery.
• PACK_PATH - path to the active pack schema.
• ASYNC_MODE - when true, ingestion enqueues Celery work instead of running the pipeline inline.
• AUTH_MODE and MERCHVAL_API_KEYS - fail-closed alpha authentication and workspace binding.
• POLICY_MODE, OPA_BASE_URL, and POLICY_EXPECTED_REVISION - executable OPA policy boundary.
• PREDICTOR_MODE - predictor metadata mode, currently defaulting to packdriven.
• PROVIDER_MODE - provider mode, currently defaulting to fake.
• ORDER_LOOKUP_MODE - order lookup mode, currently defaulting to fixture.
• CHATWOOT_WEBHOOK_ENABLED - enables the Chatwoot webhook endpoint.
• CHATWOOT_WEBHOOK_SECRET and CHATWOOT_WEBHOOK_SIGNATURE_SECRET - Chatwoot authentication controls; at least one is required when the webhook is enabled.

Key Endpoints

• GET /health - liveness check.
• POST /ingest - generic inbound message ingestion.
• POST /webhooks/dev - local/dev webhook shape.
• POST /webhooks/chatwoot - Chatwoot webhook shape with fail-closed secret and/or signature verification.
• GET /packs/active - returns or seeds the active pack version for a workspace.
• POST /packs/{pack_version_id}/activate - activates an existing pack version.
• GET /packets/{packet_id} - reads a DecisionPacket.
• POST /packets/{packet_id}/actions - records and applies packet actions.
• GET /debug/trace/{conversation_id} - returns messages, predictions, decisions, packets, approvals, audit events, and outcomes for a conversation.

Documentation

• docs/quickstart.md - clean-clone container demo and offline test setup.
• docs/tutorials/test-your-agent-refund-policy.md - integrate an agent-style refund request and inspect the complete policy decision.
• demo/storefront/ - interactive fictional store showing chat, OPA policy evaluation, human approval, and an honest simulated receipt.
• docs/pack-authoring.md - pack structure, policy boundary, validation, and runtime proof.
• docs/troubleshooting.md - startup, authentication, OPA, database, and Windows diagnostics.
• docs/architecture-high-level.md - system-level concepts, runtime flow, and deployment shape.
• docs/architecture-code-level.md - package and module responsibilities.
• docs/policy-automation-layer-architecture.md - target business and system architecture for the Policy Automation Layer direction.
• docs/policy-orchestrator-hypothesis.md - product hypothesis for a policy-first orchestrator with SLM/LLM learning loop.
• docs/demo/mvp0-demo.md - original e-commerce walkthrough.
• docs/demo/industry-demos.md - runnable three-industry proof, boundaries, artifacts, and limitations.
• docs/launch/value-proposition.md - target users, workflow, defensible claim, and non-claims.
• docs/launch/opa-differentiation.md - why Merchval complements OPA rather than rebuilding it.
• docs/release/dependency-inventory.md and docs/release/sbom.cdx.json - release dependency evidence.
• ROADMAP.md and CHANGELOG.md - public direction and alpha changes.