# Vigil — Researches, Learns, and Shows Its Work (`equ1n0x/codebook-loop`) Actor

Give Vigil a question, statement, claim, or subject. With permission, it searches for evidence, learns what the evidence actually separates, and shows every source behind what it found. Keep going and it learns. When evidence cannot carry something, it returns the exact gap instead of guessing.

- **URL**: https://apify.com/equ1n0x/codebook-loop.md
- **Developed by:** [Noah Davidson](https://apify.com/equ1n0x) (community)
- **Categories:** AI, Agents, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $100.00 / 1,000 reading row returneds

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/platform/actors/running/actors-in-store#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

## Vigil — Researches, Learns, and Shows Its Work

> **Vigil is an agnostic, non-parametric Proculmen multiplier:** the summit advances through being
> reached.

Give Vigil a question, statement, claim, subject, document, or image. With permission, it searches
for evidence, learns what the evidence actually separates, and shows every source behind what it
found. Keep going and it learns. When evidence cannot carry something, Vigil returns the exact gap
instead of guessing.

Vigil returns a structured web of evidence: the distinctions it finds, the data supporting them,
and the relationships or gaps between them. Bring that result into the next exchange with new
ground and Vigil recursively updates it through time. We call this evolving, inspectable structure
the **living map**. You can inspect it, edit it, download it, and carry it forward; Vigil never keeps
it from you.

For technically inclined readers: the map is a monadic, recursively updated relational matrix over
accrued evidence. Each exchange receives the prior structure and new ground, then returns the
updated structure together with what remains unresolved.

**You do not need to arrive with labels or a codebook.** Permit a web search or supply material of
your own and Vigil proposes the first map, showing the source passages behind every distinction.
On your own computer, sovereign Vigil can also read the files and drives you permit. The Apify
edition cannot see those drives unless you explicitly upload or connect them.

If you already have a map, you may supply it directly — its labels and the phrases your material actually uses for them. Vigil reads
your passages against it and returns three things: what carried, what didn't, and the question the
leftovers raise.

**Every coded row carries the verbatim sentence that produced it.** Not a score, not a probability —
the words in your text that the label was admitted on.

### What it does with what it cannot place

A passage that reaches two of your labels equally is not an error and not a tie to be broken. It is
the one part of your material your map does not yet separate, so it comes back naming **which
two**, as the next question — generated from that pair, never composed.

A passage that reaches a label while carrying none of its phrases comes back too, asking whether the
label is missing a phrase your material uses or does not belong to this text.

Nothing here selects what happens next. The leftovers do.

### No map yet?

Run it with `mode: derive` and a question. Permit web gathering and Vigil searches for addressed
ground, or offer documents/files directly when you want to choose the ground yourself. It splits
what it receives by what the passages share and
names each group from its own distinctive words, showing you which passages each distinction came
from. Rename them, merge two that are really one, drop what isn't a distinction — then code with it.

Every proposed label is made of your words. Nothing is brought in.

### What it will not do

- **It will not invent a label or rename yours.** It finds distinctions; naming them is yours.
- **It will not quote a word you did not send.** Checked on every response, not promised.
- **It will not grade your material.** What you say is evidence, not a claim to be assessed.
- **It will not grade against nothing.** Ask it to check text with no sources supplied and it says
  so, rather than returning something that reads like a finding.

### A picture instead of typed text

Send a screenshot or a scan and it reads the text out of it. What it reads comes back **labelled as
a reading** — never quoted as your words, never added to your map. The eye reads every surface it
covers clearly; the label preserves whose words are whose. If you want the text received as your own direct
evidence, type it, which supplies it in your voice rather than changing the provenance of the image.

Marks it cannot name are not dropped. They come back grouped by what recurs, so you can name one and
have every member named with it.

### It keeps nothing

No model and no weights file — the loop is plain Python. It makes an outbound request only when you
explicitly permit web gathering; the received source addresses come home in the result. Your map
arrives with the run, grows inside it, and goes home in the output. Nothing is
stored between runs and nothing is keyed to you.

Every result also returns a complete application receipt. Paste that receipt into
`priorApplications` on a later run and its unresolved spans re-enter as fresh ground, while its ID
records which earlier application was received. The receipt includes the exact passages, bytes, and
bits offered to that run. This is caller-carried recurrence, not a hidden account or server memory.

Across a session you can prove the thing that matters: **the same frame, more ground.** The frame tag
on every response is cut to exclude accrued examples, so it stays identical while your evidence
grows — if it changed, your map changed, and you would see it.

### Pricing — in mouse arithmetic

You do not pay because the machine opened its door. You pay for what comes home in your hand.

| What comes home | Price |
|---|---:|
| One proposed distinction in a first lens, with its marker words and source passages | **$1.00** |
| One returned reading row — a quoted admission, named open address, or labelled image reading | **$0.10** |
| Optional source check: one sentence checked against evidence you supplied | **$0.10** |
| Optional source check: an additional catch where that evidence does not carry the sentence | **$1.00** |

A first lens with four proposed distinctions costs **$4.00**. A later turn returning twelve rows
costs **$1.20**. You can count both from the work returned. Starting, empty input, refusal, and a
genesis that proposes nothing are free. The unknown material is not sold by size: an open-address
row costs ten cents because the useful address formed, not because your remainder belongs to us.

**And the large run, said out loud rather than left for your invoice.** Genesis charges a dollar for
every distinction it actually forms, and *how many it forms is set by your material* — nothing in
the input caps it. A first lens over a large body can return thirty or forty distinctions and cost
thirty or forty dollars. That is the map you asked for, and it is well under what the same first
pass costs in anyone's time. But **you cannot know the figure before the run**, and a bill you
cannot predict is a worse barrier than a bill that is merely large. So here is how to hold it:
**offer a slice first** — one document, one interview — read what comes back, and widen only when
the map is worth widening. Genesis is paid once per body of material; every later turn against that
lens is rows at ten cents.

**A distinction carrying no marker phrases costs the same dollar.** Markers are the refusal
instrument, and a label with none was admitted on agreement alone — the weaker guarantee. The run
names those labels in the same breath, so you can see exactly which they are. The price does not
drop for them.

### Honest edges

- **Genesis is the expensive step.** Proposing a first map costs real compute and scales with
  how much ground is received; a later turn against an existing map is fast. You pay genesis once per
  body of material.
- **The eye sees every surface it covers clearly and keeps provenance intact.** Image readings are
  labelled and kept out of your map because Vigil reading a surface is not the same act as you
  supplying those words directly.
- **Marker phrases are the refusal instrument.** A label carrying none can still be admitted, on
  agreement alone — the run names those labels for you rather than letting the weaker guarantee pass
  unmentioned.

# Actor input Schema

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

Choose `derive` when you want Vigil to investigate a question, statement, claim, or subject. Choose `turn` when you want it to continue from an earlier reading.

## `lens` (type: `object`):

Your own labels and the phrases your material uses for them. A label WITH marker phrases can be refused by your own words when none of them appear; a label without them is admitted on agreement alone, and the run tells you which of yours those are. Required for `turn`. The demo lens is three labels from gig-work recruitment copy — run as-is and watch the last sentence, the one that contradicts the others, come back UNPLACED rather than forced into a label, carrying the question it raises about your codebook.

## `say` (type: `string`):

The text to read, in your own words. It is split into passages the way the door splits them, coded against your lens, and never audited — what you say is evidence, not a claim to be graded.

## `question` (type: `string`):

A question, statement, claim, or subject. It addresses the search and comes home with the result, so the evidence remains answerable to what you actually gave Vigil.

## `gatherFromWeb` (type: `boolean`):

Your permission for Vigil to search the public web using what you gave it and investigate the evidence it receives. Every source address comes back in the result. Off means no outbound request is made.

## `documents` (type: `array`):

A few pieces of your own material. They are split by mutual compressibility and each group is named by its own distinctive words, so every proposed distinction comes out of your text and none is brought in. You are shown what each came from before anything is coded.

## `surface` (type: `string`):

A screenshot or scan, base64-encoded, for when your evidence is an image rather than typed text. What the eye reads comes back as a READING — labelled `read_as`, never quoted as your words and never added to your lens. If you want the text as evidence, type it under Your material.

## `transcript` (type: `array`):

Prior turns, re-supplied by you. They are evidence, not memory: nothing is stored between runs and nothing is keyed to you, which is what lets the run keep nothing while a conversation still carries.

## `receives` (type: `array`):

IDs of earlier Vigil application receipts this run continues. They establish lineage only; the actor stores nothing between runs.

## `priorApplications` (type: `array`):

Paste complete application receipts returned by earlier runs. Their unresolved spans enter this run as fresh ground and their IDs establish lineage. You carry the recurrence; Vigil stores nothing between runs.

## `check` (type: `string`):

Text YOU hand over to be checked — never your own material, and never anything this run wrote. It reports which sentences the evidence carries and which it does not, with the exact words absent. Carriage, never truth.

## `evidence` (type: `array`):

Supply these with `check`. Without them nothing is checked and the run says so, rather than grading against nothing and returning something that reads like a finding.

## Actor input object example

```json
{
  "mode": "derive",
  "lens": {
    "matching_modes": {
      "framing": {
        "flexibility": {
          "lexical_markers": [
            "your own schedule",
            "whenever you want",
            "decide when"
          ]
        },
        "earnings": {
          "lexical_markers": [
            "earn",
            "per week",
            "take home"
          ]
        },
        "onboarding": {
          "lexical_markers": [
            "sign up",
            "no experience",
            "get started"
          ]
        }
      }
    },
    "exemplars": {}
  },
  "say": "You set your own schedule. Earn up to $1,200 per week. Sign up in minutes with no experience needed. The dispatcher assigns your route each morning and you cannot decline it.",
  "question": "What does the current evidence say about this question?",
  "gatherFromWeb": false,
  "documents": [
    "You set your own schedule and decide when to work.",
    "Work whenever you want with total flexibility.",
    "Earn up to $1,200 per week driving with us.",
    "Sign up in minutes. No experience needed."
  ]
}
```

# Actor output Schema

## `reading` (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 = {
    "mode": "derive",
    "lens": {
        "matching_modes": {
            "framing": {
                "flexibility": {
                    "lexical_markers": [
                        "your own schedule",
                        "whenever you want",
                        "decide when"
                    ]
                },
                "earnings": {
                    "lexical_markers": [
                        "earn",
                        "per week",
                        "take home"
                    ]
                },
                "onboarding": {
                    "lexical_markers": [
                        "sign up",
                        "no experience",
                        "get started"
                    ]
                }
            }
        },
        "exemplars": {}
    },
    "say": "You set your own schedule. Earn up to $1,200 per week. Sign up in minutes with no experience needed. The dispatcher assigns your route each morning and you cannot decline it.",
    "question": "What does the current evidence say about this question?",
    "documents": [
        "You set your own schedule and decide when to work.",
        "Work whenever you want with total flexibility.",
        "Earn up to $1,200 per week driving with us.",
        "Sign up in minutes. No experience needed."
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("equ1n0x/codebook-loop").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 = {
    "mode": "derive",
    "lens": {
        "matching_modes": { "framing": {
                "flexibility": { "lexical_markers": [
                        "your own schedule",
                        "whenever you want",
                        "decide when",
                    ] },
                "earnings": { "lexical_markers": [
                        "earn",
                        "per week",
                        "take home",
                    ] },
                "onboarding": { "lexical_markers": [
                        "sign up",
                        "no experience",
                        "get started",
                    ] },
            } },
        "exemplars": {},
    },
    "say": "You set your own schedule. Earn up to $1,200 per week. Sign up in minutes with no experience needed. The dispatcher assigns your route each morning and you cannot decline it.",
    "question": "What does the current evidence say about this question?",
    "documents": [
        "You set your own schedule and decide when to work.",
        "Work whenever you want with total flexibility.",
        "Earn up to $1,200 per week driving with us.",
        "Sign up in minutes. No experience needed.",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("equ1n0x/codebook-loop").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 '{
  "mode": "derive",
  "lens": {
    "matching_modes": {
      "framing": {
        "flexibility": {
          "lexical_markers": [
            "your own schedule",
            "whenever you want",
            "decide when"
          ]
        },
        "earnings": {
          "lexical_markers": [
            "earn",
            "per week",
            "take home"
          ]
        },
        "onboarding": {
          "lexical_markers": [
            "sign up",
            "no experience",
            "get started"
          ]
        }
      }
    },
    "exemplars": {}
  },
  "say": "You set your own schedule. Earn up to $1,200 per week. Sign up in minutes with no experience needed. The dispatcher assigns your route each morning and you cannot decline it.",
  "question": "What does the current evidence say about this question?",
  "documents": [
    "You set your own schedule and decide when to work.",
    "Work whenever you want with total flexibility.",
    "Earn up to $1,200 per week driving with us.",
    "Sign up in minutes. No experience needed."
  ]
}' |
apify call equ1n0x/codebook-loop --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,equ1n0x/codebook-loop"
        }
    }
}

```

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/cXs0svlScBQJbzjfd/builds/AyG7WPQiJ30ONeRFG/openapi.json