# Agent Evidence Sufficiency Engine (`bono718/agent-evidence-sufficiency-engine`) Actor

Check structured evidence against source, freshness and confidence requirements. Return SUPPORTED, CONTRADICTED or INSUFFICIENT with auditable reasons. No LLM calls.

- **URL**: https://apify.com/bono718/agent-evidence-sufficiency-engine.md
- **Developed by:** [Alessandro Bonometti](https://apify.com/bono718) (community)
- **Categories:** AI, Agents, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 evidence evaluations

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Agent Evidence Sufficiency Engine

Evaluate whether supplied structured evidence satisfies an explicit contract before an agent proceeds. One claim per run, JSON input/output, no LLM calls or external evidence fetching.

Returns **SUPPORTED**, **CONTRADICTED**, or **INSUFFICIENT**, with evidence IDs, exclusion reasons, source-group counts, freshness and provenance assessments.

### Supported v0.1 scope

This is the deterministic exact-value subset of C.I. #3 freeze specification v2.0. It evaluates observations already normalized by the caller. It does not interpret prose, authenticate sources, verify real-world truth, independently establish source independence, or calibrate model confidence. No semantic evaluator or arbitrary predicate DSL is included in this release.

### Input contract

- `mode`: precondition, trigger, claim, or outcome. A workflow label; decision rules are identical.
- `claim_or_condition`: `{ "id": "shipment_delivered", "expected_value": true }`.
- `evaluation_time`: explicit ISO8601 timestamp with timezone.
- `evidence_requirements`: required `minimum_independent_sources` (1–1000), `required_source_types` (unique strings), `max_age_seconds` (nonnegative), `confidence_threshold` (0–1), `require_provenance` (boolean).
- `evidence_bundle`: up to 1000 objects containing unique `id`, `claim_id`, `source_id`, `source_type`, `observed_at`, and `value`. Supply `confidence` (0–1); missing confidence is excluded, not invented. Optional `independence_group` defaults to source_id. Optional `provenance` must contain a nonempty `reference`.
- `resolution_policy`: `insufficient_on_conflict` (default) or `contradiction_veto`.

Evidence is eligible only if its claim_id matches, its time is not in the future or too old, confidence meets the threshold, and required provenance is present. Eligible `value` is compared with expected_value using strict JSON equality, without coercion. A different value counts as contradiction: normalize observations before calling; do not use unrelated descriptive text as values.

Counts use unique independence groups, not evidence records. Different source IDs with a shared upstream origin must declare the same independence_group. The engine trusts these declarations; a copied record with a falsely independent group cannot be detected automatically. Repeated source IDs must declare consistent grouping. Source-type coverage and independent-group count are separate requirements.

A side must meet both independent-source count and required-source-type coverage. Pure support meeting the contract yields SUPPORTED; pure contradiction meeting it yields CONTRADICTED. Mixed eligible evidence defaults to INSUFFICIENT. Under contradiction_veto, any eligible contradiction blocks support, but CONTRADICTED still requires the full contradiction contract.

`confidence` is the minimum caller-supplied confidence on the decisive side, or null for abstention. It is **not a calibrated probability that the claim is true**. Provenance checks verify reference presence only.

Unknown fields are rejected to avoid silently ignoring unsupported requirements. Input errors fail the run rather than producing a verdict.

### Example

See `examples/input.json`: delivery asserted by a carrier and acknowledged by an independent receiver, both fresh and with provenance references. Result: SUPPORTED. Remove the receiver: INSUFFICIENT. Change the receiver value to false: INSUFFICIENT under the default conflict policy. Change both to false: CONTRADICTED.

### Output and use

The default dataset contains one evaluation. The same JSON is saved as OUTPUT in the default key-value store. Inspect decision, reason_codes and resolution_details before a downstream action. A supported evidence contract is not an authorization to execute a payment or other action.

Core has no network or marketplace dependency. Run locally with `node cli.js examples/input.json`; test with `npm test`. Inputs and evidence are processed on Apify when you use this Actor; avoid unnecessary sensitive payloads.

Contact: bonometti.work.ai@gmail.com

# Actor input Schema

## `claim_or_condition` (type: `object`):

See README for the exact supported contract.

## `evidence_requirements` (type: `object`):

See README for the exact supported contract.

## `evidence_bundle` (type: `array`):

Up to 1000 structured observations. Explicit confidence and claim_id are required for eligible evidence.

## `mode` (type: `string`):

Workflow label; all modes use the same declared evidence contract.

## `evaluation_time` (type: `string`):

Explicit ISO8601 time with timezone. No hidden current-time dependency.

## `resolution_policy` (type: `string`):

Default abstains on mixed eligible evidence. Veto requires the full contradiction contract.

## Actor input object example

```json
{
  "claim_or_condition": {
    "id": "shipment_delivered",
    "expected_value": true
  },
  "evidence_requirements": {
    "minimum_independent_sources": 2,
    "required_source_types": [
      "carrier",
      "receiver"
    ],
    "max_age_seconds": 86400,
    "confidence_threshold": 0.8,
    "require_provenance": true
  },
  "evidence_bundle": [
    {
      "id": "carrier-a-event",
      "claim_id": "shipment_delivered",
      "source_id": "carrier-a",
      "source_type": "carrier",
      "independence_group": "carrier-a",
      "observed_at": "2026-10-18T06:00:00Z",
      "provenance": {
        "reference": "carrier-a:record:123"
      },
      "confidence": 0.95,
      "value": true
    },
    {
      "id": "receiver-b-event",
      "claim_id": "shipment_delivered",
      "source_id": "receiver-b",
      "source_type": "receiver",
      "independence_group": "receiver-b",
      "observed_at": "2026-10-18T06:30:00Z",
      "provenance": {
        "reference": "receiver-b:record:123"
      },
      "confidence": 0.9,
      "value": true
    }
  ],
  "mode": "outcome",
  "evaluation_time": "2026-10-18T07:00:00Z",
  "resolution_policy": "insufficient_on_conflict"
}
```

# Actor output Schema

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

No description

# 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 = {
    "claim_or_condition": {
        "id": "shipment_delivered",
        "expected_value": true
    },
    "evidence_requirements": {
        "minimum_independent_sources": 2,
        "required_source_types": [
            "carrier",
            "receiver"
        ],
        "max_age_seconds": 86400,
        "confidence_threshold": 0.8,
        "require_provenance": true
    },
    "evidence_bundle": [
        {
            "id": "carrier-a-event",
            "claim_id": "shipment_delivered",
            "source_id": "carrier-a",
            "source_type": "carrier",
            "independence_group": "carrier-a",
            "observed_at": "2026-10-18T06:00:00Z",
            "provenance": {
                "reference": "carrier-a:record:123"
            },
            "confidence": 0.95,
            "value": true
        },
        {
            "id": "receiver-b-event",
            "claim_id": "shipment_delivered",
            "source_id": "receiver-b",
            "source_type": "receiver",
            "independence_group": "receiver-b",
            "observed_at": "2026-10-18T06:30:00Z",
            "provenance": {
                "reference": "receiver-b:record:123"
            },
            "confidence": 0.9,
            "value": true
        }
    ],
    "evaluation_time": "2026-10-18T07:00:00Z"
};

// Run the Actor and wait for it to finish
const run = await client.actor("bono718/agent-evidence-sufficiency-engine").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 = {
    "claim_or_condition": {
        "id": "shipment_delivered",
        "expected_value": True,
    },
    "evidence_requirements": {
        "minimum_independent_sources": 2,
        "required_source_types": [
            "carrier",
            "receiver",
        ],
        "max_age_seconds": 86400,
        "confidence_threshold": 0.8,
        "require_provenance": True,
    },
    "evidence_bundle": [
        {
            "id": "carrier-a-event",
            "claim_id": "shipment_delivered",
            "source_id": "carrier-a",
            "source_type": "carrier",
            "independence_group": "carrier-a",
            "observed_at": "2026-10-18T06:00:00Z",
            "provenance": { "reference": "carrier-a:record:123" },
            "confidence": 0.95,
            "value": True,
        },
        {
            "id": "receiver-b-event",
            "claim_id": "shipment_delivered",
            "source_id": "receiver-b",
            "source_type": "receiver",
            "independence_group": "receiver-b",
            "observed_at": "2026-10-18T06:30:00Z",
            "provenance": { "reference": "receiver-b:record:123" },
            "confidence": 0.9,
            "value": True,
        },
    ],
    "evaluation_time": "2026-10-18T07:00:00Z",
}

# Run the Actor and wait for it to finish
run = client.actor("bono718/agent-evidence-sufficiency-engine").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 '{
  "claim_or_condition": {
    "id": "shipment_delivered",
    "expected_value": true
  },
  "evidence_requirements": {
    "minimum_independent_sources": 2,
    "required_source_types": [
      "carrier",
      "receiver"
    ],
    "max_age_seconds": 86400,
    "confidence_threshold": 0.8,
    "require_provenance": true
  },
  "evidence_bundle": [
    {
      "id": "carrier-a-event",
      "claim_id": "shipment_delivered",
      "source_id": "carrier-a",
      "source_type": "carrier",
      "independence_group": "carrier-a",
      "observed_at": "2026-10-18T06:00:00Z",
      "provenance": {
        "reference": "carrier-a:record:123"
      },
      "confidence": 0.95,
      "value": true
    },
    {
      "id": "receiver-b-event",
      "claim_id": "shipment_delivered",
      "source_id": "receiver-b",
      "source_type": "receiver",
      "independence_group": "receiver-b",
      "observed_at": "2026-10-18T06:30:00Z",
      "provenance": {
        "reference": "receiver-b:record:123"
      },
      "confidence": 0.9,
      "value": true
    }
  ],
  "evaluation_time": "2026-10-18T07:00:00Z"
}' |
apify call bono718/agent-evidence-sufficiency-engine --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bono718/agent-evidence-sufficiency-engine"
        }
    }
}
```

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/V3a9DWaRnxmFbhbsL/builds/Xmm5ik9LHt4jI5oRi/openapi.json