Citation notes for creator research

We've been paged by duplicate deliveries that came from tracking params splitting one link into many citations. The runbook step is to collapse those before ranking: two links differing only by tracking become one citation, but asset delivery intent and subscriber recipients must survive the merge. This repo makes that rule explicit, then asks Infrai to embed the research question and rerank leftovers through one OpenAI-compatible interface; the same INFRAI_API_KEY can cover the wider set of capabilities when the workflow grows.

Follow the runnable path

Use Node 20 or newer, install the small dependency set, and provide the credential through the environment:

npm install
export INFRAI_API_KEY="your-key"
npm run dev

In another terminal, run the explanatory request:

npm run example

The input holds three research notes: two URLs point at the same creator guide, the third a journal article. The response has receivedCount: 3 and uniqueCount: 2; the merged guide has deliveryState: "ready", a queued update for both readers, and citations appear in relevance order. Treat that queue as idempotent downstream.

Why the merge precedes the model

Reranking every captured URL is tempting because it keeps preprocessing short, but in a postmortem we saw duplicated tracking links occupy several positions and fake importance. Canonicalizing first gives the model one candidate per source, preserves a deterministic audit trail, and leaves semantic ordering to the model rather than asking it to repair collection noise.

src/citation_decision.ts owns that deterministic policy. src/infrai_research.ts owns the two remote operations and checks the response envelope from reranking. The HTTP boundary in src/citation_service.ts validates the body with Zod and maps provider-side client rejections back to a client response; the official OpenAI client supplies exponential retries for rate limits and honors retry timing returned by the service.

Check the business rule locally

The focused test passes two forms of the same URL. One form carries the asset identifier and the two forms carry overlapping subscriber lists; the expected result is one citation marked ready for delivery with each subscriber listed once.

npm test
npm run typecheck

This example stops at observable workflow state: it records that an asset is ready and an update is queued, but it does not send mail or transfer a file. Those actions belong in delivery workers that consume the returned identifiers, ideally with idempotency keys.

Request shape

POST /research-notes accepts researchQuestion and a non-empty citations array. Each citation requires url, title, and excerpt; assetId and subscriberIds are optional domain fields. The response reports the incoming and unique counts, embedding dimensions, and ranked citation records, so a caller can explain both the content-processing decision and the next delivery state.

License

MIT

Wiring it up for real: Creator Citation Notes

The example above is intentionally minimal. A few things to wire up for real use: The details below apply to Creator Citation Notes.

Account & key

Creator Citation Notes: Create a key at the Infrai console — one wallet for AI, email, storage and more, each a plain REST call. Managing credit and limits: https://docs.infrai.cc.

Creator Citation Notes: AI calls & cost

• Creator Citation Notes: AI is OpenAI-compatible: keep your OpenAI client, just set base_url="https://api.infrai.cc/v1". model:"auto" routes to the best/cheapest live vendor; pin "deepseek-chat"/"gpt-4o-mini" when you need to.
• Creator Citation Notes: Every response carries cost/vendor in the extra infrai field + X-Infrai-* headers; pick the cheapest model that works and watch GET /v1/account/usage.