toolpack-sdk 3.0.0 → 3.2.0

package/README.md

@@ -19,7 +19,7 @@ The TypeScript SDK for building production AI agents — 100+ built-in tools, 8
 - **Rules** — Always-on behavioral constraints loaded from Markdown files, auto-discovered per mode and globally via `rulesDir`
 - **HITL Confirmation** — Human-in-the-loop approval for high-risk operations with configurable bypass rules
 - **Extensible at Every Layer** — Every built-in component is a plug-in point: custom tools (`ToolDefinition`), custom channels (`BaseChannel`), custom provider adapters (`ProviderAdapter`), custom agents (`BaseAgent`), custom modes (`createMode()`), and custom interceptors — all using the same interfaces as the built-ins
-- **100+ Built-in Tools** across 12 categories:
+- **100+ Built-in Tools** across 15 categories:
 - **MCP Client & Server** — consume external MCP servers via `createMcpToolProject()`, or expose Toolpack as an MCP server via `sdk.startMcpServer()` with static/JWT/custom auth, search mode, and agent exposure.
 
 | Category | Tools | Description |
@@ -505,7 +505,7 @@ client.on('tool:failed', (event) => { /* ... */ });
 
 ## Custom Tools
 
-In addition to the 100+ built-in tools, you can create and register your own custom tool projects using `createToolProject()`:
+In addition to the 100+ built-in tools, you can create and register your own custom tool projects using `createToolProject()`. Built-in tool categories used for mode filtering include `filesystem`, `coding`, `version-control`, `http`, `web`, `github`, `slack`, `execution`, `system`, and others — there is no combined `network` category.
 
 ```typescript
 import { Toolpack, createToolProject } from 'toolpack-sdk';
@@ -540,6 +540,7 @@ const myToolProject = createToolProject({
 });
 
 // Attach custom tools to a mode — scoped to that agent, not global.
+// To replace built-ins by name at init time, pass toolOverrides: [myToolProject].
 const sdk = await Toolpack.init({
   provider: 'openai',
   tools: true,
@@ -554,6 +555,9 @@ const result = await sdk.generate({
   model: 'gpt-4.1',
   mode: { ...sdk.getMode()!, customTools: [...myToolProject.tools] },
 });
+
+// Option C: load projects at runtime (rebuilds the tool search index once)
+await sdk.loadToolProjects([myToolProject]);
 ```
 
 ### Tool Project Structure
@@ -606,30 +610,24 @@ const response = await toolpack.chat('How do I configure authentication?');
 
 - **Multiple Providers**: In-memory (`MemoryProvider`) or persistent SQLite (`PersistentKnowledgeProvider`)
 - **Multiple Embedders**: OpenAI, Ollama (local), or custom embedders
-- **Multiple Sources**: Markdown, JSON, SQLite ingestion
+- **Multiple Sources**: Markdown, text, web, API, JSON, SQLite, and more
 - **Progress Events**: Track embedding progress with `onEmbeddingProgress`
 - **Metadata Filtering**: Query with filters like `{ hasCode: true, category: 'api' }`
+- **Incremental updates**: `ingest()`, `delete()`, and `deleteWhere()` for per-item lifecycle
 
-See the [Knowledge package README](./packages/toolpack-knowledge/README.md) for full documentation.
+See the [Knowledge package README](../toolpack-knowledge/README.md) for full documentation.
 
 ## Skills
 
-The skills system lets you define **reusable behavioral instructions** in `.skill.md` files and automatically inject them into requests based on message relevance — no agent code changes required.
+The skills system lets you define **reusable behavioral instructions** in `.skill.md` files and expose them to the agent via LLM-callable tools.
 
 ### Quick Start
 
 ```typescript
-import { Toolpack, createSkillInterceptor, createSkillTools } from 'toolpack-sdk';
+import { createSkillTools } from 'toolpack-sdk';
 
 const skillTools = createSkillTools({ dir: '.toolpack/skills' });
 
-const toolpack = await Toolpack.init({
-  provider: 'anthropic',
-  interceptors: [
-    createSkillInterceptor({ dir: '.toolpack/skills', maxSkills: 3, minScore: 0.3 }),
-  ],
-});
-
 // Attach skill tools per agent via ModeConfig.customTools:
 // agent.mode = { ...agentMode, customTools: [...skillTools.tools] };
 ```
@@ -664,21 +662,9 @@ When reviewing code:
 4. Be constructive — suggest improvements, not just problems
 ```
 
-When a user sends "review this PR", the interceptor automatically injects the `## Instructions` block before the LLM sees the message.
-
 ### How It Works
 
-- **`createSkillInterceptor`** — An SDK interceptor that runs BM25 search on every user message and prepends matching skill instructions as a `<skill-instructions>` block. Validates all files at `Toolpack.init()` time.
-- **`createSkillTools`** — Four LLM-callable tools (`skill.create`, `skill.read`, `skill.update`, `skill.list`) for managing the skill library at runtime.
-
-### `createSkillInterceptor` Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `dir` | string | `.toolpack/skills` | Path to the skill files directory |
-| `maxSkills` | number | `3` | Maximum number of skills injected per message |
-| `minScore` | number | `0.3` | BM25 relevance threshold |
-| `onValidationError` | `'fail'` \| `'warn'` | `'fail'` | How to handle invalid skill files at startup |
+**`createSkillTools`** registers four LLM-callable tools (`skill.create`, `skill.read`, `skill.update`, `skill.list`) for managing the skill library at runtime. The agent calls `skill.read` to load instructions on demand — skills are never auto-injected.
 
 See the [Skills guide](https://toolpacksdk.com/guides/skills) and [Skill Tools reference](https://toolpacksdk.com/tools/skills) for full documentation.
 
@@ -1020,7 +1006,7 @@ class FintechResearchAgent extends ResearchAgent {
 
 ### Features
 
-- ✅ **7 Built-in Channels** — Slack, Telegram, Discord, Email, SMS, Webhook, Scheduled
+- ✅ **8 Built-in Channels** — Slack, Telegram, Discord, Email, SMS, Webhook, Scheduled, Chat
 - ✅ **4 Built-in Agents** — Research, Coding, Data, Browser
 - ✅ **Event-Driven** — Full lifecycle events for monitoring
 - ✅ **Knowledge Integration** — Conversation memory and RAG
@@ -1033,10 +1019,10 @@ See the [Agents package README](./packages/toolpack-agents/README.md) for full d
 
 ## Multimodal Support
 
-The SDK supports multimodal inputs (text + images) across all vision-capable providers. Images can be provided in three formats:
+The SDK supports multimodal inputs (text + images + files) across all vision-capable providers. Images can be provided in three formats:
 
 ```typescript
-import { Toolpack, ImageFilePart, ImageDataPart, ImageUrlPart } from 'toolpack-sdk';
+import { Toolpack, ImageFilePart, ImageDataPart, ImageUrlPart, FilePart } from 'toolpack-sdk';
 
 const sdk = await Toolpack.init({ provider: 'openai' });
 
@@ -1071,6 +1057,30 @@ const response = await sdk.generate({
 });
 ```
 
+### File Attachments (Documents)
+
+Use `FilePart` to attach non-image files such as PDFs. Pass a public or pre-signed URL and the MIME type:
+
+```typescript
+import { FilePart, FILE_LIMITS } from 'toolpack-sdk';
+
+const doc: FilePart = {
+  type: 'file',
+  file: {
+    url: 'https://example.com/report.pdf',
+    mimeType: 'application/pdf',
+    name: 'report.pdf',  // optional
+    size: 204800,        // optional bytes, used for client-side limit checks
+  },
+};
+
+// FILE_LIMITS.image.maxBytes    → 10 MB
+// FILE_LIMITS.document.maxBytes → 10 MB
+// FILE_LIMITS.document.maxPages → 20 pages
+```
+
+A data URI (`data:<mime>;base64,<data>`) is also accepted in `file.url` for inline embedding.
+
 ### Provider Behavior
 
 | Provider | File Path | Base64 | URL |
@@ -1080,6 +1090,16 @@ const response = await sdk.generate({
 | Gemini | Converted to base64 | ✓ Native | Downloaded → base64 |
 | Ollama | Converted to base64 | ✓ Native | Downloaded → base64 |
 
+### Provider Support for File Attachments (FilePart)
+
+| Provider | URL | Inline base64 (`data:` URI) |
+|----------|-----|-----------------------------|
+| **Anthropic** | ✓ images and documents | ✓ auto-routed to `image` or `document` block |
+| **Anthropic Vertex** | ✓ | ✓ |
+| **Gemini** | ✓ (`fileData`) | ✓ (`inlineData`) |
+| **VertexAI** | ✓ (`fileData`) | ✓ (`inlineData`) |
+| **OpenAI** | ✓ images and documents | Images only (non-image base64 is dropped) |
+
 ## Configuration
 
 ### Environment Variables
@@ -1225,12 +1245,12 @@ const sdk = await Toolpack.init({
 ```typescript
 import { Toolpack } from 'toolpack-sdk';
 
-// ToolpackInitConfig — fields removed in v2.8:
+// ToolpackInitConfig — fields removed in v3.0.0:
 //   customTools   → use ModeConfig.customTools per agent instead
 //   modeOverrides → configure modes directly via registerMode()
 //   configPath    → configuration is now passed inline to Toolpack.init()
 //
-// Fields added in v2.8: logging, hitl, toolsConfig
+// Fields: logging, hitl, toolsConfig, toolOverrides (v3.1.0)
 const sdk = await Toolpack.init(config: ToolpackInitConfig): Promise<Toolpack>
 
 // Completions (routes through workflow engine if mode has workflow enabled)
@@ -1250,6 +1270,12 @@ sdk.getModes(): ModeConfig[]
 sdk.cycleMode(): ModeConfig
 sdk.registerMode(mode: ModeConfig): void
 
+// Tool projects
+await sdk.loadToolProject(project: ToolProject): Promise<void>
+await sdk.loadToolProjects(projects: ToolProject[]): Promise<void>
+sdk.searchTools(query: string, category?: string)
+sdk.getRegisteredToolNames(): string[]
+
 // Internal access
 sdk.getClient(): AIClient
 sdk.getWorkflowExecutor(): WorkflowExecutor