Completions & Streaming

const res = await theo.complete({
  prompt: "Explain microservices architecture",
  mode: "auto",           // or "fast", "think", "code", "research", etc.
  skills: ["deep-research"],
  conversation_id: "conv_abc123",  // optional — continue a conversation
  persona: { system_prompt: "You are a senior architect..." },
  tools: [/* inline tool definitions */],
  temperature: 0.7,
  max_iterations: 8,
  metadata: { source: "my-app" },
});

console.log(res.content);                  // Generated text
console.log(res.model.label);              // "Theo Reason"
console.log(res.resolved_mode);            // "think"
console.log(res.tools_used);               // [{ name, status, description? }]
console.log(res.usage.cost_cents);         // 0.15
console.log(res.usage.prompt_tokens);      // 42
console.log(res.usage.completion_tokens);  // 128
console.log(res.usage.total_tokens);       // 170
console.log(res.usage.cached);             // true when served from semantic cache
console.log(res.conversation_id);          // server-side conversation id or null
console.log(res.request_id);               // mirror of the X-Request-Id header

interface CompletionUsage {
  cost_cents: number;           // markup-inclusive
  prompt_tokens: number;        // always 0 for non-text modes
  completion_tokens: number;    // always 0 for non-text modes
  total_tokens: number;
  cached?: boolean;             // true when served from the semantic cache
}

const stream = theo.stream({ prompt: "Explain DNS" });

// Hook up a "Stop generating" button
stopButton.onclick = () => stream.cancel();

for await (const event of stream) {
  switch (event.type) {
    case "meta":     console.log("Mode:", event.data.resolved_mode); break;
    case "token":    process.stdout.write(event.token); break;
    case "tool":     console.log("Tool:", event.data.name, event.data.status); break;
    case "artifact": renderArtifact(event.data); break;
    case "error":    console.error("Stream error:", event.data.error); break;
    case "done":     console.log("\nCost:", event.data.usage.cost_cents); break;
  }
}

// Populated from meta + done events:
console.log("conversation_id:", stream.conversationId);
console.log("usage:", stream.usage);
console.log("model:", stream.model);
console.log("request_id:", stream.requestId);
console.log("full content:", stream.content); // accumulated from token events
console.log("was cancelled?", stream.isCancelled);