@sperax/tool-notebook

Create and manage documents in the topic notebook

Notebook is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-notebook

Usage

import { NotebookManifest } from '@sperax/tool-notebook';

// NotebookManifest.api is a JSON-Schema tool definition, ready to hand to any model.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-notebook

API reference

createDocument

Create a new document in the notebook. Use this to save reports, notes, articles, or any content that should persist in the topic.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | content | string | yes | The document content in Markdown format | | description | string | yes | A brief summary of the document (1-2 sentences) | | title | string | yes | A descriptive title for the document | | type | markdown | note | report | article | no | The type of document |

updateDocument

Update an existing document. Can modify title, content, or append new content to existing document.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | append | boolean | no | If true, append content to existing document instead of replacing | | content | string | no | New content for the document | | id | string | yes | The document ID to update | | title | string | no | New title for the document |

getDocument

Retrieve the full content of a specific document from the notebook.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | string | yes | The document ID to retrieve |

deleteDocument

Delete a document from the notebook. This action cannot be undone.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | string | yes | The document ID to delete |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-notebook is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0