# AI Decision State & Evidence Monitor (`suezcanal.xyz/decision-monitor`) Actor

Monitor whether a previously justified structured decision still holds after evidence, assumptions or blockers change. Returns deterministic deltas and replay-safe checkpoints.

- **URL**: https://apify.com/suezcanal.xyz/decision-monitor.md
- **Developed by:** [Matteo Messina](https://apify.com/suezcanal.xyz) (community)
- **Categories:** AI, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.01 / decision monitor comparison

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

AI Decision State & Evidence Monitor is a deterministic, stateless comparison Actor for workflows that need to know whether a previously justified structured decision still holds after evidence, assumptions, or blockers change.

It is designed for agentic workflows that need explicit decision-state deltas and reproducible checkpoints — not for website/page monitoring.

### How a monitor sequence works

On the first run, provide only `request`. Decision Monitor creates revision 1 of the checkpoint and an idempotency record. This is a baseline, so `outcome` is `BASELINE_CREATED`, there is no comparison report, and no pay-per-event charge is emitted.

On a later run, pass a new `request` plus the previous `checkpoint`. Decision Monitor compares the prior and current structured decision snapshots and evidence inventories, returns `outcome: COMPARED`, writes the next checkpoint, and emits the `decision-monitor-comparison` billing event.

A comparison is billable even when the legitimate result is no change. The paid work unit is the deterministic comparison, not the existence of a transition.

For an exact retry, pass the same request together with its previously returned `prior_record`. When the request fingerprint matches, the Actor returns `outcome: REPLAYED` and does not charge again. Reusing the same idempotency key with a different payload is rejected.

### What it detects

A comparison report can identify:

- decision transitions;
- changed assumptions;
- added or removed blockers;
- added, removed, or changed evidence IDs;
- unchanged evidence count;
- changed source IDs and URLs;
- deterministic reasons for the observed delta.

### What it does not do

Decision Monitor does not crawl websites, watch page selectors, fetch new evidence, schedule itself, infer a decision policy, or maintain hidden cross-customer persistence. It only compares caller-supplied structured state.

The caller or orchestrator owns persistence and passes the prior checkpoint explicitly. The beta contract assumes a single active writer per `monitor_id`; `expected_checkpoint_id` can be used as a stale-write guard.

### Input

The top-level input contains `request` plus an optional previous `checkpoint` and optional `prior_record` for exact replay. The request contains a `monitor_id`, `idempotency_key`, optional expected checkpoint ID, current decision snapshot, and current evidence inventory.

### Output

One dataset item contains:

- `outcome`: `BASELINE_CREATED`, `COMPARED`, or `REPLAYED`;
- comparison `report` when applicable;
- the next `checkpoint`;
- `idempotency_record`;
- `billing_event` only for a newly performed comparison.

### Pricing

The beta price is USD 0.01 per new `decision-monitor-comparison`. Baseline creation is free. An exact idempotent replay is free. A new comparison that confirms no change is still charged once because the comparison itself is the paid unit.

### Typical uses

Use Decision Monitor after a grant/tender qualification, research conclusion, operational assessment, or other structured agent decision when later evidence or assumptions may invalidate the original justification.

### Limitations

The Actor's causal reasons describe deterministic changes in the supplied snapshots and evidence. They are not a claim that an external real-world event caused the transition. The Actor does not arbitrate concurrent writers or authorize downstream side effects.

### Suez Evidence & Decision Infrastructure for AI Agents

Decision Monitor is the change-detection layer of the Suez evidence-and-decision tool family. **Agent Readiness** audits machine-facing publication, **Research Verification** checks evidence sufficiency, **Task Feasibility** preflights execution, **Opportunity Decision** provides a bounded qualification decision, and **Decision Monitor** determines whether that decision still holds as structured state changes.

# Actor input Schema

## `request` (type: `object`):

Current monitor ID, idempotency key, optional expected checkpoint ID, structured decision snapshot and evidence inventory.

## `checkpoint` (type: `object`):

Optional checkpoint returned by the previous successful run. Omit it on the first run to create an unbilled baseline.

## `prior_record` (type: `object`):

Optional record for this exact monitor\_id and idempotency\_key. Supply it when replaying a previously completed request to return the stored result without a second charge.

## Actor input object example

```json
{
  "request": {
    "monitor_id": "opportunity-001",
    "idempotency_key": "check-001",
    "current": {
      "decision": "GO",
      "assumptions": {
        "eligibility_confirmed": true
      },
      "blockers": []
    },
    "current_evidence": []
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Default dataset items containing outcome, optional decision/evidence delta report, next checkpoint, idempotency record and billing event metadata.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "request": {
        "monitor_id": "opportunity-001",
        "idempotency_key": "check-001",
        "current": {
            "decision": "GO",
            "assumptions": {
                "eligibility_confirmed": true
            },
            "blockers": []
        },
        "current_evidence": []
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("suezcanal.xyz/decision-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "request": {
        "monitor_id": "opportunity-001",
        "idempotency_key": "check-001",
        "current": {
            "decision": "GO",
            "assumptions": { "eligibility_confirmed": True },
            "blockers": [],
        },
        "current_evidence": [],
    } }

# Run the Actor and wait for it to finish
run = client.actor("suezcanal.xyz/decision-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "request": {
    "monitor_id": "opportunity-001",
    "idempotency_key": "check-001",
    "current": {
      "decision": "GO",
      "assumptions": {
        "eligibility_confirmed": true
      },
      "blockers": []
    },
    "current_evidence": []
  }
}' |
apify call suezcanal.xyz/decision-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,suezcanal.xyz/decision-monitor"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/wbIZci4DgEeKbjNR9/builds/FXZKZ445sydOvvRhA/openapi.json