@benkhz/context-manager 1.0.0

package/README.md

@@ -0,0 +1,231 @@
+# @benkhz/context-manager
+
+A vanilla JS class that manages LLM conversation context end-to-end. Zero runtime dependencies.
+
+## Installation
+
+```bash
+npm install @benkhz/context-manager
+```
+
+---
+
+## Quick start
+
+```js
+import { AIContextManager, openaiPreset } from '@benkhz/context-manager'
+
+const mgr = new AIContextManager({
+  endpoint: 'https://api.openai.com/v1/chat/completions',
+  model:    'gpt-4o',
+  headers:  { Authorization: `Bearer ${process.env.OPENAI_KEY}` },
+  hooks: {
+    ...openaiPreset,
+  },
+})
+
+const reply = await mgr.send('What is the capital of France?')
+console.log(reply.content) // "The capital of France is Paris."
+```
+
+---
+
+## Design decisions
+
+| Concern | Decision | Rationale |
+|---|---|---|
+| Provider agnosticism | Caller supplies `formatRequest` + `parseResponse` hooks | No lock-in; presets ship for OpenAI and Anthropic as reference |
+| Context compaction | Manager POSTs to the same endpoint with a summarise prompt | Automatic; `onCompact` hook overrides for custom logic |
+| Reactive state | `setState / getState / subscribe` — callbacks fire synchronously | Familiar, zero magic, easy to test |
+| Tool loop cap | 10 iterations max | Guards against infinite loops without blocking legitimate multi-step reasoning |
+| Context sizing | Character count approximation | Token counting requires a tokenizer dep; chars are close enough for limit-triggering |
+
+---
+
+## Constructor
+
+```js
+new AIContextManager(config)
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `endpoint` | `string` | **required** | URL to POST every LLM request to |
+| `hooks` | `object` | **required** | See [Hooks](#hooks) |
+| `model` | `string` | — | Passed through to `formatRequest` |
+| `maxTokens` | `number` | — | Passed through to `formatRequest` |
+| `contextLimit` | `number` | `80_000` | Char count that triggers auto-compaction |
+| `compactKeepLast` | `number` | `6` | Messages preserved verbatim after compaction |
+| `headers` | `object` | `{}` | Extra HTTP headers on every `fetch` call |
+
+---
+
+## Hooks
+
+All hooks live in `config.hooks`. Only `formatRequest` and `parseResponse` are required.
+
+### Required
+
+#### `formatRequest(context, config) → RequestBody`
+
+Converts the internal context snapshot into the HTTP request body.
+
+```js
+// context shape
+{
+  messages: [{ role, content, toolCalls?, toolCallId? }],
+  tools:    [{ name, schema: { description, parameters } }],
+  summary:  string | null,
+}
+
+// config shape (your constructor options + per-call system override)
+{ endpoint, model, maxTokens, headers, system? }
+```
+
+#### `parseResponse(rawJson) → ParsedResponse`
+
+Converts the raw HTTP response JSON into the internal shape.
+
+```js
+// must return
+{
+  content:    string,                              // assistant text
+  stopReason: string,                              // e.g. 'stop', 'tool_use'
+  toolCalls?: [{ id, name, args }],               // present when model calls tools
+}
+```
+
+### Optional lifecycle hooks
+
+| Hook | Signature | Description |
+|---|---|---|
+| `beforeSend` | `(messages[]) → messages[]` | Transform or filter the message array before each POST. Return the array. |
+| `afterReceive` | `(parsed) → parsed` | Transform the parsed response before tool/message processing. |
+| `onCompact` | `(overflow[], currentSummary) → string \| void` | Return a summary string to override the LLM-generated one. |
+| `onToolCall` | `(name, args) → args \| void` | Intercept before a tool runs. Return new args to override. |
+| `onToolResult` | `(name, result) → result` | Transform a tool result before appending to context. |
+| `onError` | `(error, phase) → void` | Called on any error. `phase` is `'send'`, `'compact'`, or `'tool'`. |
+| `onStateChange` | `(key, oldVal, newVal) → void` | Observe every state mutation globally. |
+| `onContextLimit` | `(charCount, limit) → 'compact' \| 'truncate' \| 'error'` | Choose what happens when the context limit is hit. Defaults to `'compact'`. |
+
+---
+
+## Messaging API
+
+```js
+const reply = await mgr.send('your message')
+// → { role: 'assistant', content: string }
+
+await mgr.send('follow-up', { system: 'You are a pirate.' })
+
+await mgr.compact()
+```
+
+---
+
+## Tool API
+
+```js
+mgr.addTool(
+  'getWeather',
+  {
+    description: 'Get current weather for a city',
+    parameters: {
+      type: 'object',
+      properties: { city: { type: 'string', description: 'City name' } },
+      required: ['city'],
+    },
+  },
+  async ({ city }) => ({ temp: 72, unit: 'F', condition: 'sunny' })
+)
+
+mgr.removeTool('getWeather')
+mgr.getTools()   // → [{ name, schema }]
+```
+
+---
+
+## Event bus
+
+```js
+mgr.on('message:sent',     ({ message }) => ...)
+mgr.on('message:received', ({ message }) => ...)
+mgr.on('tool:call',        ({ name, args }) => ...)
+mgr.on('tool:result',      ({ name, result }) => ...)
+mgr.on('context:compact',  ({ messageCount }) => ...)
+mgr.on('context:compacted',({ summary }) => ...)
+mgr.on('state:change',     ({ key, oldValue, newValue }) => ...)
+mgr.on('error',            ({ error, phase }) => ...)
+
+mgr.off('message:received', handler)
+mgr.once('message:received', handler)
+```
+
+---
+
+## Reactive state
+
+```js
+mgr.setState('userId', 'u_123')
+mgr.getState('userId')              // → 'u_123'
+
+const unsub = mgr.subscribe('userId', (newVal, oldVal) => {
+  console.log(`userId changed: ${oldVal} → ${newVal}`)
+})
+unsub()
+```
+
+---
+
+## Introspection
+
+```js
+mgr.getMessages()   // → Message[] (shallow copy)
+mgr.getSummary()    // → string | null
+mgr.getTools()      // → [{ name, schema }]
+mgr.getContext()    // → { messages, summary, tools }
+mgr.reset()         // clear messages, summary, state — returns this
+```
+
+---
+
+## Presets
+
+```js
+import { openaiPreset, anthropicPreset } from '@benkhz/context-manager'
+
+// OpenAI / Azure / Ollama / LM Studio
+const mgr = new AIContextManager({
+  hooks: {
+    ...openaiPreset,
+    beforeSend: msgs => msgs.filter(m => m.content),
+  },
+})
+
+// Anthropic Messages API
+const mgr = new AIContextManager({
+  hooks: { ...anthropicPreset },
+})
+```
+
+---
+
+## Context compaction
+
+When the total character count of `_messages` exceeds `contextLimit`:
+
+1. `onContextLimit` hook is called — returns `'compact'` (default), `'truncate'`, or `'error'`
+2. If `compact`: the overflow messages are sent to the LLM with a summarise prompt
+3. The summary is stored in `_summary`; the last `compactKeepLast` messages are kept verbatim
+4. `formatRequest` receives `context.summary` and can inline it however the API prefers
+
+The `onCompact` hook can return a string to bypass the LLM call entirely.
+
+---
+
+## Open decisions
+
+- **Token counting** — currently approximated via character count. A future `tokenizer` option could accept a `(messages) => number` fn for more accurate limiting.
+- **Streaming** — `send()` is request/response only.
+- **Persistence** — `getContext()` returns a serialisable snapshot. A future `loadContext(snapshot)` method would complete the persistence story.
+- **Multi-modal** — content is currently assumed to be `string`.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@benkhz/context-manager",
+  "version": "1.0.0",
+  "description": "Provider-agnostic LLM context manager with tool execution, auto-compaction, reactive state, and an event bus.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./presets/openai": "./src/presets/openai.js",
+    "./presets/anthropic": "./src/presets/anthropic.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "llm",
+    "ai",
+    "context-manager",
+    "openai",
+    "anthropic",
+    "tool-calling",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BenKhz/context-manager"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "echo 'No build step — pure ESM source'",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "vue": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "vue": { "optional": true }
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/vue": "^8.1.0",
+    "@vitejs/plugin-vue": "^6.0.7",
+    "@vitest/coverage-v8": "^3.2.4",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "vitest": "^3.2.4",
+    "vue": "^3.5.35"
+  }
+}

package/src/AIContextManager.js

@@ -0,0 +1,284 @@
+import { EventEmitter } from './EventEmitter.js'
+
+const MAX_TOOL_ITERATIONS  = 10
+const DEFAULT_CONTEXT_LIMIT     = 80_000
+const DEFAULT_COMPACT_KEEP_LAST = 6
+
+export class AIContextManager {
+  /**
+   * @param {object} config
+   * @param {string}   config.endpoint        — URL to POST every LLM request to
+   * @param {string}   [config.model]         — forwarded to formatRequest
+   * @param {number}   [config.maxTokens]     — forwarded to formatRequest
+   * @param {number}   [config.contextLimit]  — char count before auto-compact (default 80 000)
+   * @param {number}   [config.compactKeepLast] — messages to keep verbatim after compact (default 6)
+   * @param {object}   [config.headers]       — extra HTTP headers on every fetch
+   * @param {object}   config.hooks           — see README for full hook reference
+   */
+  constructor(config = {}) {
+    const {
+      endpoint,
+      model,
+      maxTokens,
+      contextLimit     = DEFAULT_CONTEXT_LIMIT,
+      compactKeepLast  = DEFAULT_COMPACT_KEEP_LAST,
+      headers          = {},
+      hooks            = {},
+    } = config
+
+    if (!endpoint)            throw new Error('AIContextManager: config.endpoint is required')
+    if (!hooks.formatRequest) throw new Error('AIContextManager: hooks.formatRequest is required')
+    if (!hooks.parseResponse) throw new Error('AIContextManager: hooks.parseResponse is required')
+
+    this._config = { endpoint, model, maxTokens, contextLimit, compactKeepLast, headers }
+    this._hooks  = hooks
+
+    this._messages    = []
+    this._summary     = null
+    this._tools       = new Map()    // name → { schema, handler }
+    this._emitter     = new EventEmitter()
+    this._state       = new Map()    // reactive state
+    this._subscribers = new Map()    // key → Set<fn>
+  }
+
+  // ── Messaging ───────────────────────────────────────────────────────────────
+
+  /**
+   * Send a user message and receive the assistant reply.
+   * Handles tool loops, auto-compaction, and all lifecycle hooks.
+   *
+   * @param {string} content
+   * @param {object} [opts]
+   * @param {string} [opts.system]  — per-call system prompt override
+   * @returns {Promise<{ role: 'assistant', content: string }>}
+   */
+  async send(content, opts = {}) {
+    const userMsg = { role: 'user', content }
+    this._messages.push(userMsg)
+    this._emitter.emit('message:sent', { message: userMsg })
+
+    // beforeSend hook — can return a transformed messages array (sync or async)
+    if (this._hooks.beforeSend) {
+      const next = await this._hooks.beforeSend([...this._messages])
+      if (Array.isArray(next)) this._messages = next
+    }
+
+    // Auto-compact when approaching the context limit
+    const chars = this._charCount()
+    if (chars > this._config.contextLimit) {
+      const policy = this._hooks.onContextLimit?.(chars, this._config.contextLimit) ?? 'compact'
+      if      (policy === 'compact')   await this.compact()
+      else if (policy === 'truncate')  this._truncate()
+      else throw new Error(`AIContextManager: context limit exceeded (${chars} chars)`)
+    }
+
+    try {
+      const assistantMsg = await this._runLoop(opts.system)
+      this._messages.push(assistantMsg)
+      this._emitter.emit('message:received', { message: assistantMsg })
+      return assistantMsg
+    } catch (err) {
+      this._hooks.onError?.(err, 'send')
+      this._emitter.emit('error', { error: err, phase: 'send' })
+      throw err
+    }
+  }
+
+  /**
+   * Summarise overflow messages and slim the context window.
+   * Called automatically by send() when contextLimit is reached,
+   * or can be called manually at any time.
+   */
+  async compact() {
+    const keep     = this._config.compactKeepLast
+    const overflow = this._messages.slice(0, -keep)
+    if (!overflow.length) return
+
+    this._emitter.emit('context:compact', { messageCount: overflow.length })
+
+    // Hook can override the summary (sync or async); fallback to LLM-generated summary
+    let summary = await this._hooks.onCompact?.(overflow, this._summary)
+    if (!summary) summary = await this._summarise(overflow)
+
+    this._summary  = summary
+    this._messages = this._messages.slice(-keep)
+    this._emitter.emit('context:compacted', { summary })
+  }
+
+  // ── Tools ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Register a local tool the LLM can call.
+   *
+   * @param {string}   name
+   * @param {object}   schema      — { description, parameters } (JSON Schema for parameters)
+   * @param {Function} handler     — async (args) => result
+   */
+  addTool(name, schema, handler) {
+    this._tools.set(name, { schema, handler })
+    return this
+  }
+
+  removeTool(name) {
+    this._tools.delete(name)
+    return this
+  }
+
+  // ── Event bus ────────────────────────────────────────────────────────────────
+
+  on(event, fn)   { this._emitter.on(event, fn);   return this }
+  off(event, fn)  { this._emitter.off(event, fn);  return this }
+  once(event, fn) { this._emitter.once(event, fn); return this }
+
+  // ── Reactive state ───────────────────────────────────────────────────────────
+
+  setState(key, value) {
+    const oldValue = this._state.get(key)
+    this._state.set(key, value)
+    this._hooks.onStateChange?.(key, oldValue, value)
+    this._emitter.emit('state:change', { key, oldValue, newValue: value })
+    this._subscribers.get(key)?.forEach(cb => cb(value, oldValue))
+    return this
+  }
+
+  getState(key) {
+    return this._state.get(key)
+  }
+
+  /**
+   * Subscribe to changes on a specific state key.
+   * @returns {Function} unsubscribe — call to stop listening
+   */
+  subscribe(key, cb) {
+    if (!this._subscribers.has(key)) this._subscribers.set(key, new Set())
+    this._subscribers.get(key).add(cb)
+    return () => this._subscribers.get(key).delete(cb)
+  }
+
+  // ── Introspection ─────────────────────────────────────────────────────────────
+
+  getMessages() { return [...this._messages] }
+  getSummary()  { return this._summary }
+  getTools()    { return [...this._tools.entries()].map(([name, { schema }]) => ({ name, schema })) }
+
+  /** Full snapshot of context — useful for debugging or serialisation */
+  getContext() {
+    return { messages: this.getMessages(), summary: this._summary, tools: this.getTools() }
+  }
+
+  /** Reset all conversation state. Does not touch config or registered tools. */
+  reset() {
+    this._messages    = []
+    this._summary     = null
+    this._state       = new Map()
+    this._subscribers = new Map()
+    return this
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Core LLM call + tool execution loop.
+   * Recurses until the model stops calling tools or MAX_TOOL_ITERATIONS is hit.
+   */
+  async _runLoop(system, depth = 0) {
+    if (depth >= MAX_TOOL_ITERATIONS) {
+      throw new Error(`AIContextManager: tool loop exceeded ${MAX_TOOL_ITERATIONS} iterations`)
+    }
+
+    const context = this.getContext()
+    const body    = this._hooks.formatRequest(context, { ...this._config, system })
+    const raw     = await this._fetch(body)
+    let   parsed  = this._hooks.parseResponse(raw)
+
+    if (this._hooks.afterReceive) {
+      parsed = (await this._hooks.afterReceive(parsed)) ?? parsed
+    }
+
+    // No tool calls → return the final assistant message
+    if (!parsed.toolCalls?.length) {
+      return { role: 'assistant', content: parsed.content ?? '' }
+    }
+
+    // Append the assistant turn that requested tools, then execute each
+    const assistantMsg = {
+      role:      'assistant',
+      content:   parsed.content ?? '',
+      toolCalls: parsed.toolCalls,
+    }
+    this._messages.push(assistantMsg)
+
+    for (const tc of parsed.toolCalls) {
+      const toolDef = this._tools.get(tc.name)
+      if (!toolDef) throw new Error(`AIContextManager: unknown tool "${tc.name}"`)
+
+      let args = tc.args
+      this._emitter.emit('tool:call', { name: tc.name, args })
+      const intercepted = await this._hooks.onToolCall?.(tc.name, args)
+      if (intercepted !== undefined) args = intercepted
+
+      let result
+      try {
+        result = await toolDef.handler(args)
+      } catch (err) {
+        this._hooks.onError?.(err, 'tool')
+        this._emitter.emit('error', { error: err, phase: 'tool' })
+        throw err
+      }
+
+      const transformed = await this._hooks.onToolResult?.(tc.name, result)
+      if (transformed !== undefined) result = transformed
+
+      this._emitter.emit('tool:result', { name: tc.name, result })
+      this._messages.push({ role: 'tool', content: JSON.stringify(result), toolCallId: tc.id })
+    }
+
+    return this._runLoop(system, depth + 1)
+  }
+
+  /** POST overflow messages to the LLM with a summarise prompt */
+  async _summarise(messages) {
+    const summaryMessages = [
+      ...(this._summary
+        ? [{ role: 'system', content: `Previous summary:\n${this._summary}` }]
+        : []),
+      {
+        role: 'user',
+        content: [
+          'Summarise the conversation below. Preserve all key facts, decisions, and context. Be concise.',
+          '',
+          ...messages.map(m => `${m.role.toUpperCase()}: ${m.content}`),
+        ].join('\n'),
+      },
+    ]
+
+    const context = { messages: summaryMessages, tools: [], summary: null }
+    const body    = this._hooks.formatRequest(context, this._config)
+    const raw     = await this._fetch(body)
+    const parsed  = this._hooks.parseResponse(raw)
+    return parsed.content
+  }
+
+  async _fetch(body) {
+    const res = await fetch(this._config.endpoint, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json', ...this._config.headers },
+      body:    JSON.stringify(body),
+    })
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new Error(`AIContextManager: HTTP ${res.status} — ${text}`)
+    }
+    return res.json()
+  }
+
+  /** Approximate context size in characters */
+  _charCount() {
+    return this._messages.reduce((n, m) => n + (m.content?.length ?? 0), 0)
+  }
+
+  /** Hard truncation — drop oldest messages down to compactKeepLast */
+  _truncate() {
+    this._messages = this._messages.slice(-this._config.compactKeepLast)
+  }
+}

package/src/EventEmitter.js

@@ -0,0 +1,33 @@
+export class EventEmitter {
+  constructor() {
+    this._handlers = new Map()
+  }
+
+  on(event, fn) {
+    if (!this._handlers.has(event)) this._handlers.set(event, new Set())
+    this._handlers.get(event).add(fn)
+    return this
+  }
+
+  off(event, fn) {
+    this._handlers.get(event)?.delete(fn)
+    return this
+  }
+
+  once(event, fn) {
+    const wrapper = data => { fn(data); this.off(event, wrapper) }
+    return this.on(event, wrapper)
+  }
+
+  emit(event, data) {
+    this._handlers.get(event)?.forEach(fn => fn(data))
+    return this
+  }
+
+  /** Awaits all handlers for an event in parallel. Use sparingly — prefer hooks for flow control. */
+  async emitAsync(event, data) {
+    const handlers = this._handlers.get(event)
+    if (handlers) await Promise.all([...handlers].map(fn => fn(data)))
+    return this
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export { AIContextManager } from './AIContextManager.js'
+export { openaiPreset }     from './presets/openai.js'
+export { anthropicPreset }  from './presets/anthropic.js'

package/src/index.js

@@ -0,0 +1,3 @@
+export { AIContextManager } from './AIContextManager.js'
+export { openaiPreset }     from './presets/openai.js'
+export { anthropicPreset }  from './presets/anthropic.js'

package/src/presets/anthropic.js

@@ -0,0 +1,58 @@
+/**
+ * Anthropic Messages API formatRequest / parseResponse preset.
+ *
+ * Usage:
+ *   import { anthropicPreset } from 'libs'
+ *   const mgr = new AIContextManager({ hooks: { ...anthropicPreset, beforeSend } })
+ */
+export const anthropicPreset = {
+  formatRequest(context, config) {
+    const systemParts = [
+      config.system,
+      context.summary ? `[Conversation history]\n${context.summary}` : null,
+    ].filter(Boolean)
+
+    const messages = context.messages.map(m => {
+      if (m.role === 'tool') {
+        // Anthropic wraps tool results in a user turn
+        return {
+          role: 'user',
+          content: [{ type: 'tool_result', tool_use_id: m.toolCallId, content: m.content }],
+        }
+      }
+      if (m.toolCalls?.length) {
+        return {
+          role: 'assistant',
+          content: [
+            ...(m.content ? [{ type: 'text', text: m.content }] : []),
+            ...m.toolCalls.map(tc => ({ type: 'tool_use', id: tc.id, name: tc.name, input: tc.args })),
+          ],
+        }
+      }
+      return { role: m.role, content: m.content }
+    })
+
+    const body = { model: config.model, messages }
+    if (systemParts.length) body.system = systemParts.join('\n\n')
+    if (config.maxTokens) body.max_tokens = config.maxTokens
+    if (context.tools.length) {
+      body.tools = context.tools.map(t => ({
+        name:         t.name,
+        description:  t.schema.description,
+        input_schema: t.schema.parameters,
+      }))
+    }
+
+    return body
+  },
+
+  parseResponse(raw) {
+    const text     = raw.content?.find(b => b.type === 'text')
+    const toolUses = raw.content?.filter(b => b.type === 'tool_use') ?? []
+    return {
+      content:    text?.text ?? '',
+      stopReason: raw.stop_reason,
+      toolCalls:  toolUses.length ? toolUses.map(b => ({ id: b.id, name: b.name, args: b.input })) : undefined,
+    }
+  },
+}

package/src/presets/openai.js

@@ -0,0 +1,66 @@
+/**
+ * OpenAI-compatible formatRequest / parseResponse preset.
+ * Works with OpenAI, Azure OpenAI, Ollama, LM Studio, and most proxies.
+ *
+ * Usage:
+ *   import { openaiPreset } from 'libs'
+ *   const mgr = new AIContextManager({ hooks: { ...openaiPreset, beforeSend } })
+ */
+export const openaiPreset = {
+  formatRequest(context, config) {
+    const messages = []
+
+    // Prepend system message with any summary inline
+    const systemParts = [
+      config.system,
+      context.summary ? `[Conversation history]\n${context.summary}` : null,
+    ].filter(Boolean)
+
+    if (systemParts.length) {
+      messages.push({ role: 'system', content: systemParts.join('\n\n') })
+    }
+
+    for (const m of context.messages) {
+      if (m.role === 'tool') {
+        messages.push({ role: 'tool', tool_call_id: m.toolCallId, content: m.content })
+      } else if (m.toolCalls?.length) {
+        messages.push({
+          role: 'assistant',
+          content: m.content || null,
+          tool_calls: m.toolCalls.map(tc => ({
+            id: tc.id,
+            type: 'function',
+            function: { name: tc.name, arguments: JSON.stringify(tc.args) },
+          })),
+        })
+      } else {
+        messages.push({ role: m.role, content: m.content })
+      }
+    }
+
+    const body = { model: config.model, messages }
+    if (config.maxTokens) body.max_tokens = config.maxTokens
+    if (context.tools.length) {
+      body.tools = context.tools.map(t => ({
+        type: 'function',
+        function: { name: t.name, description: t.schema.description, parameters: t.schema.parameters },
+      }))
+    }
+
+    return body
+  },
+
+  parseResponse(raw) {
+    const choice   = raw.choices?.[0]
+    const message  = choice?.message ?? {}
+    return {
+      content:    message.content ?? '',
+      stopReason: choice?.finish_reason,
+      toolCalls:  message.tool_calls?.map(tc => ({
+        id:   tc.id,
+        name: tc.function.name,
+        args: JSON.parse(tc.function.arguments),
+      })),
+    }
+  },
+}