Compare and save configurations

Use Run when you know which tool and options to use. Use Discover when
you want to compare alternatives before choosing. Your connected AI agent can
handle these steps, or you can follow the CLI walkthrough below.

Run

Use Run when the capability and configuration are already known. A configuration
is the provider plus its provider-native options, not only a provider name.

Run can execute:

A capability with your ordered list of providers and fallback options.
A finalized saved discovery.
A deterministic catalog default when providers are omitted.

Run reports which providers it tried and the options it used. When a provider
returns records, you or your agent check whether they contain what you need.

Each Run executes once. To repeat a check, your application schedules the next
Run and supplies the returned cursor where the capability supports one.

Discover

Use Discover when you need to decide between providers or options:

You or your AI agent define the goal, requested fields, representative input,
and materially different candidates.
Scrappycoco executes candidates under comparable conditions.
Scrappycoco returns candidate-specific records, native outputs, exact
options, attempts, cost, failures, and truncation.
You or your AI agent determine which candidates satisfy the request.
Among equally satisfactory candidates, cost is the default tie-breaker
unless the user requires another priority.
You or your AI agent save an explicit primary configuration and, when useful,
a tested independent fallback, then finalizes the discovery.

Discover returns evidence, not a winner. Candidate order does not imply a
Scrappycoco recommendation.

What to compare

Compare materially different configurations, including rendering mode, wait
behavior, output format, actions, proxy settings, and other native options that
can change the result. Named candidate IDs allow multiple configurations of the
same provider to remain distinct.

Walkthrough with the CLI

Set up the CLI first. The example uses jq to capture the saved configuration ID.

Create discovery.json with the goal, runtime parameter, and materially
different candidates to test:

{
  "goal": "Extract the main content and links from a public web page.",
  "priority": "quality",
  "configuration": {
    "name": "Web content extraction",
    "summary": "Compare extraction configurations on one representative URL.",
    "parameters": [
      {
        "name": "url",
        "label": "Page URL",
        "description": "Public page to extract.",
        "type": "string",
        "required": true,
        "test_value": "https://example.com"
      }
    ],
    "routes": [
      {
        "id": "content",
        "label": "Page content",
        "purpose": "Return the main readable content and native links.",
        "source": "web",
        "capability": "extract_content",
        "input_template": {"url": "${url}"},
        "routing": "compare",
        "providers": [],
        "provider_options": {},
        "candidates": [
          {
            "id": "firecrawl-markdown",
            "provider": "firecrawl_scrape",
            "options": {
              "formats": ["markdown", "links"],
              "only_main_content": true
            }
          },
          {
            "id": "tavily-extract",
            "provider": "tavily_extract",
            "options": {}
          }
        ]
      }
    ]
  }
}

Save that JSON as discovery.json, then create the Discovery:

DISCOVERY_RESPONSE="$(npx --yes @scrappycoco/cli@latest discover \
  --file discovery.json --json)"
DISCOVERY_ID="$(printf '%s' "$DISCOVERY_RESPONSE" | jq -r '.id')"
printf 'Created Discovery: %s\n' "$DISCOVERY_ID"

Scrappycoco also adds one default candidate for each currently available
provider that the draft omits. The explicit candidates above represent native
option variants; inspect all returned candidate evidence before selecting a
configuration.

Test all candidates on representative input:

npx --yes @scrappycoco/cli@latest discover \
  --id "$DISCOVERY_ID" \
  --test \
  --input '{"url":"https://example.com"}' \
  --output evidence.json \
  --json

You or your AI agent evaluate the evidence, update the route to an explicit
provider and exact tested options, and finalize it. For example, if the
firecrawl-markdown candidate satisfied the goal, save this complete update as
finalized-route.json:

{
  "configuration": {
    "name": "Web content extraction",
    "summary": "Extract page content with the selected tested configuration.",
    "parameters": [
      {
        "name": "url",
        "label": "Page URL",
        "description": "Public page to extract.",
        "type": "string",
        "required": true
      }
    ],
    "routes": [
      {
        "id": "content",
        "label": "Page content",
        "purpose": "Return the main readable content and native links.",
        "source": "web",
        "capability": "extract_content",
        "input_template": {"url": "${url}"},
        "routing": "waterfall",
        "providers": ["firecrawl_scrape"],
        "provider_options": {
          "firecrawl_scrape": {
            "formats": ["markdown", "links"],
            "only_main_content": true
          }
        },
        "candidates": []
      }
    ]
  }
}

Apply the update, finalize it, and run the saved configuration:

npx --yes @scrappycoco/cli@latest discover \
  --id "$DISCOVERY_ID" --update finalized-route.json --json
npx --yes @scrappycoco/cli@latest discover \
  --id "$DISCOVERY_ID" --finalize --json
npx --yes @scrappycoco/cli@latest run \
  --config "$DISCOVERY_ID" --input '{"url":"https://example.com"}' --json