# Grounded Synthesizer (reference)

This is a runnable reference implementation of the Stringer Grounded Synthesizer, a research
service that returns extractive quotations with citations from verified public sources and
refuses a topic it cannot ground. It mirrors the caller-observable surface of the hosted
service at `synthesis.getstringer.app` and holds nothing back that a caller can see.

The boundary rule is the one stated in the worker header: a behaviour belongs here when an
unauthenticated caller can observe it from outside. The bearer-gated admin stats route, the
Durable Object funnel counters, the caller hashing, and the provider cost rate card stay out.

## What the reference runs on

Node.js 20 or newer. The Worker is dependency-free and runs with no API keys and no external
state, because the default research provider is a fixture-backed stub. That is the point: a
stranger can clone the tree and watch the grounding and the refusal end to end without
holding a single paid key.

```bash
git clone <this repository>
cd synthesizer-public
node --test test_discovery.mjs test_worker.mjs
```

To run it as a Worker locally, use Wrangler 4 (`npx wrangler dev`). No secret setup is
required; the free allowance is held in process for the reference and is documented as such
in `wrangler.toml`.

## Hosted endpoints (the service this documents)

- MCP: `https://synthesis.getstringer.app/mcp`
- MCP tool: `synthesize_intelligence`
- REST: `POST https://synthesis.getstringer.app/v1/synthesize`
- REST alias: `POST https://synthesis.getstringer.app/v1/execute`
- Discovery: `/.well-known/mcp.json`, `/server.json`, `/llms.txt`, `/llms-full.txt`, `/robots.txt`, `/sitemap.xml`

The first three calls are free, total, with no signup and no claim header. The allowance does
not reset. After that, a brief synthesis costs USD 0.10 and a deep synthesis costs USD 0.25,
both paid through x402 v2 USDC on Base (`eip155:8453`). An unpaid call after the allowance is
exhausted returns HTTP `402` with the accepted payment requirement in `PAYMENT-REQUIRED` and
the tier price in `X-402-Price-USD`.

## Grounding contract

- A brief synthesis requires at least 2 distinct verified sources.
- A deep synthesis requires at least 3 distinct verified sources.
- Every claim is an extractive quotation with a source URL and a character offset.
- `GROUNDED`: the quotation checks passed.
- `REFUSED_UNVERIFIED_CLAIMS`: fewer than the required verified sources, or a quote failed
  verbatim verification.
- `SOURCE_EXTRACTION_FAILED`: a named source could not be fetched or extracted.

The refusal is the product's whole claim. The test harness observes the grounded case and the
refusal case red before making each green, so neither path can pass on a test that has never
failed.

## Swapping the stub for a real provider

The research provider is an injectable seam. `synthesizeGroundedReport` takes a `provider`
argument, and the fetch handler reads `env.researchProvider`. The default is
`createFixtureProvider()`, which searches a fixed corpus of three source documents and never
makes a network call.

A real provider implements the same two methods:

```js
{
  async search(query, numResults, domainsFilter) {
    // Return [{ url, title }] from your search backend.
  },
  async extract(url) {
    // Return { ok: true, document: { url, title, markdown, via } } on success, or
    // { ok: false, source_url: url, stage, reason } on failure.
  },
}
```

Wire one in by exporting it on the Worker environment, for example with an Exa search key and
a Firecrawl scrape key held as Worker secrets. The reference never hard-codes a provider's
unit cost and never names the hosted service's margin internals; the seam is the only thing a
reader needs to change.

## REST

```bash
curl -i https://synthesis.getstringer.app/v1/synthesize \
  -H 'Content-Type: application/json' \
  --data '{"topic":"Base network USDC settlement","depth":"brief"}'
```

Free responses carry `X-Stringer-Access-Tier: free` and `X-Stringer-Free-Remaining`. The
fourth call returns HTTP `402`. See `openapi.json` and `RECIPES.md` for the full flow.

## MCP

Streamable HTTP at `https://synthesis.getstringer.app/mcp`. Clients must send both
`application/json` and `text/event-stream` in `Accept`. The server implements `initialize`,
`ping`, `tools/list`, and `tools/call` for `synthesize_intelligence`.

## Test

```bash
node --test test_discovery.mjs test_worker.mjs
python3 -m py_compile client_sdk.py
```

## License

MIT. See `LICENSE`.