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.
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:
{
async search(query, numResults, domainsFilter) {
},
async extract(url) {
},
}
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
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
node --test test_discovery.mjs test_worker.mjs
python3 -m py_compile client_sdk.py
License
MIT. See LICENSE.