# Evident task SDK 1.0.2

Research with sources, extract local PDFs, check acceptance criteria, and optionally report private metadata to a team. Node.js 22.13 or newer. MIT licensed. This package is distributed from Evident; it is not published on the npm registry.

## Install

```sh
npm install https://evidentagents.com/sdk/evidentagents-task-sdk-1.0.2.tgz
```

## Research: an end-to-end public task

Save as `research.mjs`, then run `node research.mjs`:

```js
import {EvidentClient} from '@evidentagents/task-sdk';
const client = new EvidentClient();
const contract = {
  kind: 'research', scope: 'microsoft', min_sources: 2,
  required_domains: ['learn.microsoft.com'],
  max_latency_ms: 30000, max_cost_usd: 0
};
const plan = await client.plan(contract);
console.log(plan.matching.recommendation);
const result = await client.research({
  contract,
  query: 'Azure Blob Storage lifecycle management',
  execute: true // Explicitly allow this public query to reach Microsoft Learn.
});
console.log(JSON.stringify(result, null, 2));
```

The selected provider receives the query. Use public topics only. The SDK returns source URLs and excerpts from the provider response. It does not invent a synthesized answer or publication date. `claim_support` remains unknown: your Agent or reviewer must read the source and check whether it supports the actual answer. Supply claims with `text` and `source_urls` to `validateResult` to check citation structure; this still does not establish factual correctness.

`cloudflare` is the other documented free scope. `public_web` uses the Exa public MCP endpoint and requires `acceptUnknownPrice: true` and a nonzero budget because current account/price eligibility is unknown. No payment or credentials are sent by this SDK, and HTTP 401/402/429 stops the request. No retries or automatic provider switching occur. For a strict cost ceiling use your own provider with enforceable account limits.

## PDF: local extraction and source-linked fields

Save as `extract.mjs`, replace the file path, then run `node extract.mjs`:

```js
import {EvidentClient} from '@evidentagents/task-sdk';
const client = new EvidentClient();
const result = await client.extract({
  contract: {
    kind: 'extraction', local_only: true, min_pages: 1,
    max_latency_ms: 60000, max_cost_usd: 0,
    fields: [{key: 'invoice_date', type: 'date', required: true}]
  },
  file: './authorized-document.pdf',
  fieldLabels: {invoice_date: 'Invoice date:'},
  execute: true
});
console.log(JSON.stringify(result, null, 2));
```

File contents, extracted text and values remain local. Exact line labels must uniquely identify a value; ambiguous or missing values stay missing. Dates must be ISO `YYYY-MM-DD`; numbers must use an unambiguous decimal representation. Field evidence contains page and original quoted line. This is deterministic text extraction, not OCR or general document understanding.

For a simple table, supply `options: {page: 1, columns: [0, 200, 400, 600], y_min: 0, y_max: 800}` and contract `table_columns: 3`. Output includes JSON cells and formula-neutralized CSV. These boundaries are PDF coordinates chosen by the caller. Scans, handwriting, arbitrary tables, merged cells and XLSX are not supported. Maximum 20 MiB and 100 pages. A deadline terminates the local worker; an AbortSignal can cancel it. Completed checks never automatically assert full task success.

## Validate an adapted output locally

```js
import {validateResult} from '@evidentagents/task-sdk';
const report = validateResult(contract, output, {latency_ms: 1250, cost_usd: 0});
```

Checks return `pass`, `fail`, or `unknown`. A missing cost is unknown, not zero. Freshness uses supplied publication dates, never retrieval time. No arbitrary JSON Schema execution, scripts or model instructions are taken from provider output. Keep unknown factual support and document fidelity visible.

## Private team recording and alerts

Create a workspace and a seven-day scoped Agent token at https://evidentagents.com/workspace. Put it in your local environment; never paste it into source, command arguments or screenshots.

```js
import {EvidentClient} from '@evidentagents/task-sdk';
const team = new EvidentClient({
  workspaceId: process.env.EVIDENT_WORKSPACE_ID,
  workspaceToken: process.env.EVIDENT_WORKSPACE_TOKEN
});
// After inspecting a result, explicitly choose your assessed outcome.
const saved = await team.record(result, {
  requestKey: 'stable-unique-attempt-001',
  environment: 'production', // Default is test. Never mark a fixture as real usage.
  outcome: 'partial'
});
console.log(saved.feedback_url); // Optional, separate consumer confirmation to publish.
const alerts = await team.alerts();
console.log(alerts.alerts);
// Follow next_cursor as the alerts(after) argument until null.
```

Only service/task/version, duration, optional reported cost, contract hash, check counts and test/production classification are saved. No contract text, prompts, file contents or field values are sent by `record`. Recording is caller-reported, not a platform-certified execution. Stable request keys prevent duplicate metadata, not duplicate supplier executions; preserve the execution result yourself before retrying `record`.

Team quality UI: `/workspace/quality?id=WORKSPACE_ID`.
Agent API: `GET /api/v3/quality?workspace_id=WORKSPACE_ID&after=CURSOR` with the workspace Bearer token. `POST /api/v3/quality` with `{action:"acknowledge", workspace_id, alert_id}` acknowledges an alert. Owner browser sessions alone can set duration and USD-cost thresholds. These are alert thresholds, not billing enforcement. Poll when your application runs; this SDK does not install a background scheduler or send emails.

## Small discovery surface

Configure Streamable HTTP MCP at **https://evidentagents.com/mcp/tasks** for four public tools:

- `prepare_task_contract`
- `get_task_connection_plan`
- `get_task_benchmarks`
- `find_open_task_needs`

The full, backward-compatible endpoint remains `/mcp`. Neither discovery endpoint executes suppliers. No token needed for public discovery; workspace tokens are for the REST team API only.

A2A planning is available through `/.well-known/agent-card.json` and `POST /a2a`, pinned to protocol 0.3.0. Send `message/send` with one DataPart containing the raw contract:

```json
{"jsonrpc":"2.0","id":"plan-1","method":"message/send","params":{"message":{"kind":"message","role":"user","messageId":"request-1","parts":[{"kind":"data","data":{"kind":"extraction","local_only":true}}]}}}
```

This returns a synchronous Message with the plan. It does not expose asynchronous execution, files, stored tasks, streaming or push notifications. `tasks/get` and `tasks/cancel` return TaskNotFound because no task is retained.

## Unmet needs and provider responses

Read `GET /api/v3/demands`, following `next_cursor` as `after`. To prepare a request, POST `{title,contract}` to `/api/v3/demands/draft`. Return its `confirmation_url` to the requester. Nothing is saved until that person signs in, reviews the title/contract and chooses private or public visibility. They can close and remove it from public view. Providers can propose their own reviewed, published service through `/demands`; proposals are visible to the requester. No off-platform messages or automatic purchases occur.

## Pricing and quality boundaries

Public discovery and current team features have no Evident platform subscription charge. Hosted paid execution, wallet payments, recurring billing and an SLA are not enabled. Supplier pricing, quotas and machine costs remain separate. Sample results are bounded fixtures, not customer satisfaction or success-rate claims. Use task constraints and evidence provenance when making decisions.

Documentation: https://evidentagents.com/services/quality
Contract schema: https://evidentagents.com/api/v3/task-contract/schema
Public measured fixtures: https://evidentagents.com/services/task-lab
Current fixed-query checks: https://evidentagents.com/api/v3/task-canaries