Temporal Annotations for LLMs

Per-model recommendations

Based on Benchmark 5 (40 deterministic MCQs, three annotation conditions, seven mid-to-frontier models, two difficulty sets). One run per condition — directional guidance, not a formal ranking. Task difficulty matters: some models shift their best format on the hard set.

Hard-set task findings

The hard set (Benchmark 5, 40 MCQs, circular-reasoning and composite-cycle questions) reveals format shifts that are invisible in easy-set scores. Numbers below are from results-llm-temporal-hard.json (date: 2026-08-03, deterministic seeds).

Compact labels

Compact labels encode the current temporal position as a single human-readable string: time-of-day:08:15UTC weekday:Fri week-of-year:wk11/52 month:Mar year:2026. LLMs read and compare these the same way they read any other text — no floating-point arithmetic required.

Request compact labels by passing annotationFormat: "compact" in the request body. The response carries meta.compactAnnotation.

POST /v1/full
X-API-Key: tblk_live_YOUR_KEY
Content-Type: application/json

{
  "annotationFormat": "compact"
}

// Response includes:
// meta.compactAnnotation:
//   "time-of-day:08:15UTC weekday:Fri week-of-year:wk11/52 month:Mar year:2026"

Inject meta.compactAnnotation wherever your prompt describes time — system prompt, user message, or inline with each event. Example:

// Build a system-prompt that includes the annotation
const res = await fetch("https://api.temporalblock.com/v1/full", {
  method: "POST",
  headers: { "X-API-Key": "tblk_live_...", "Content-Type": "application/json" },
  body: JSON.stringify({ annotationFormat: "compact" }),
});
const { meta } = await res.json();

// Prepend the annotation to your prompt
const systemPrompt = `Current time context: ${meta.compactAnnotation}

You are a scheduling assistant ...`;

Spiral (sin, cos) coordinates

The spiral coordinate encodes time as a set of (sin, cos) pairs — one per temporal scale from hour-of-day through year-of-decade. These are the same features fed to ML models in Benchmarks 1–4. Most LLMs handle them poorly, but DeepSeek is an exception: raw floats gave a +22 pp gain on temporal reasoning.

The spiral coordinate is returned in every /v1/full response as meta.spiralCoordinate — no extra request parameter required.

POST /v1/full
X-API-Key: tblk_live_YOUR_KEY
Content-Type: application/json

{}   // no annotationFormat — spiralCoordinate is always present

// Response includes:
// meta.spiralCoordinate:
//   { hr: { sin: 0.707, cos: 0.707 }, day: { sin: -0.866, cos: 0.5 }, ... }

// Serialize the spiral coordinate into the prompt for DeepSeek
const res = await fetch("https://api.temporalblock.com/v1/full", {
  method: "POST",
  headers: { "X-API-Key": "tblk_live_...", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const { meta } = await res.json();
const sc = meta.spiralCoordinate;

// Format each scale as the LLM will see it
const spiralText = Object.entries(sc)
  .map(([scale, v]) => `${scale}: sin=${v.sin.toFixed(3)} cos=${v.cos.toFixed(3)}`)
  .join(", ");

const systemPrompt = `Current spiral coordinates: ${spiralText}

You are ...`;

Pre-built system-prompt paragraph

If you want to skip formatting logic entirely, request includeSpiralBlock: true. The response adds meta.spiralBlock — a full, ready-to-paste system-prompt paragraph that describes the current temporal position in prose. It can be used alongside annotationFormat: "compact" if you want both.

POST /v1/full
X-API-Key: tblk_live_YOUR_KEY
Content-Type: application/json

{
  "annotationFormat": "compact",
  "includeSpiralBlock": true
}

// Response includes both:
// meta.compactAnnotation  — Compact Spiral string
// meta.spiralBlock        — full system-prompt paragraph for any model

Terse variants: same accuracy, fewer tokens

Both formats have a terse rendering measured in Benchmark 6: terse compact (18:36Z Thu wk8 Feb-2025) costs 1.68× plain-timestamp tokens, and terse spiral (2-decimal floats, hr/day/mo scales only) costs 2.58× — versus 2.53× and 3.92× for the verbose forms.

The accuracy gains survive the compression. Re-running the Benchmark 5 question set with terse annotations across five mid-tier models: terse compact matched or beat plain timestamps on every model — gpt-5.4 (98% vs 75% plain), gpt-5.2 (95% vs 80%), claude-sonnet-4-6 (83% vs 75%), gemini-2.5-flash (80% vs 78%) — and DeepSeek kept its spiral advantage with terse spiral (85% vs 70% plain). The per-family recommendations above are unchanged; terse is simply the cheaper way to apply them.

Auto-select with llmModel

If you already know which model you are calling, pass its name as llmModel and omit annotationFormat — the API will apply the benchmark-proven best format for that model family automatically.

An explicit annotationFormat always wins over llmModel. Both /v1/full and GET /v1/spiral accept the parameter.

// /v1/full — let the API pick the right format (easy tasks)
const res = await fetch("https://api.temporalblock.com/v1/full", {
  method: "POST",
  headers: { "X-API-Key": process.env.TBLK_KEY!, "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "What happened last week?",
    llmModel: "gpt-5.4",   // → API sets annotationFormat:"compact" automatically
    syncProvider: "openai",
    syncApiKey: process.env.OPENAI_KEY!,
  }),
});
const { meta } = await res.json();
// meta.compactAnnotation is populated — no annotationFormat param needed

// For hard circular / composite-cycle tasks with gpt-5.4:
//   omit BOTH annotationFormat AND llmModel — passing llmModel:"gpt-5.4" auto-selects
//   compact for the OpenAI family, overriding the spiral intent (+20 pp at stake).
//   Also clear any stored per-key compact default first if needed.
// deepseek-chat → llmModel:"deepseek-chat" is safe (does not trigger compact auto-select);
//   or omit both and use meta.spiralCoordinate directly (40/40 hard set)
// gemini-2.5-flash, claude-sonnet-4-6 → annotationFormat:"compact" in all conditions

// GET /v1/spiral — same llmModel param works as a query string
// GET /v1/spiral?llmModel=deepseek-chat
// → spiralCoordinate is always present; no extra annotation added (spiral family)

Manual switching per model

If you prefer explicit control, pass annotationFormat directly. The annotation format is a per-request parameter, so you can pick it at call time:

// isHardTask: true for deep circular / composite-cycle reasoning prompts
function pickFormat(model: string, isHardTask = false): string | undefined {
  if (model.startsWith("deepseek"))      return undefined; // always use spiralCoordinate
  if (model.startsWith("claude-opus-5")) return undefined; // auto-skipped (refusal risk)
  // gpt-5.4 on hard circular tasks: omit annotationFormat, use meta.spiralCoordinate
  // (+20 pp over compact — 27/40 vs 19/40 on hard set)
  if (isHardTask && model === "gpt-5.4") return undefined;
  // gemini-2.5-flash and claude-sonnet-4-6 stay on compact even for hard tasks
  return "compact";
}

const annotationFormat = pickFormat(model, isHardTask);
const body: Record<string, unknown> = { /* your other params */ };
if (annotationFormat) body.annotationFormat = annotationFormat;
// IMPORTANT for gpt-5.4 hard tasks: also omit llmModel from the request body.
// Passing llmModel:"gpt-5.4" auto-selects compact for the OpenAI family
// (resolution chain: annotationFormat > llmModel auto-pick > stored key default).
// For deepseek, llmModel:"deepseek-chat" is safe — it does not trigger compact.
// If your key has a stored compact default, clear it first:
//   PATCH /api/keys/:id/annotation-format  { "annotationFormat": null }
// meta.spiralCoordinate is always present in every /v1/full response — no extra param needed.
const isGpt54Hard = isHardTask && model === "gpt-5.4";
if (!isGpt54Hard) body.llmModel = model;

const res = await fetch("https://api.temporalblock.com/v1/full", {
  method: "POST",
  headers: { "X-API-Key": process.env.TBLK_KEY!, "Content-Type": "application/json" },
  body: JSON.stringify(body),
});