Working with documents

The work this API is built for rarely looks like a conversation. It looks like ten thousand documents that have to be turned into structured rows, and a refusal in the middle of the run that costs you the run.

Extraction

Ask for the shape you want, name the fields in the prompt, and use JSON mode so the answer is parseable even when the content is not clean.

curl https://api.cognitivers.com/v1/chat/completions \
  -H "Authorization: Bearer $COGNITIVERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cog-fast",
    "response_format": { "type": "json_object" },
    "messages": [
      {
        "role": "system",
        "content": "Extract named people, places and dates as JSON with the keys people, places, dates. Reply with JSON only."
      },
      { "role": "user", "content": "<document>" }
    ]
  }'

Three habits that decide whether a batch run finishes:

• One document per request. Batching several documents into one prompt makes partial failure ambiguous and makes retries expensive.
• Validate every row. A schema check on the parsed JSON catches the cases the model got wrong, and those are the rows a human should read.
• Make the run resumable. Write output as you go, keyed by document id, so a failure at document 6,000 does not mean starting again.

Classification and moderation datasets

The same shape with a closed label set. Pin the labels in the system prompt, include what each label means, and ask for the label alone.

This is also how moderation training data gets built: a model with a policy layer will not label the material you need labelled, and a model without one will. What you do with the labels afterwards is governed by the acceptable use policy.

Retrieval over your own corpus

1. Embed the corpus once with cog-embed, in batches, keeping the model id next to the vectors.
2. At request time, embed the query, take the nearest passages, and pass them as context to cog-fast or cog-pro.
3. Cite the passage ids in your output so a reader can check the claim.

For a corpus that is queried repeatedly, retrieval beats resending the whole thing: it is cheaper, it is faster, and the model attends better to five relevant passages than to a hundred thousand tokens of which four matter.

Writing in volume

For translation, rewriting or generation over many items, the same rules apply: one item per request, cog-fast, output stored as you go, and a validation pass that flags rather than silently repairs.