Migrating from v1.1 to v1.2

This guide helps you migrate from Toolpack SDK v1.1.0 to v1.2.0. The primary change is the extraction of the Knowledge module into a separate package.

What's New in v1.2.0

• Knowledge module extracted to @toolpack-sdk/knowledge package
• ESM-first with dual CJS build for better compatibility
• Enhanced Windows support with full CI testing
• 52% smaller package size with minification and tree-shaking

Breaking Changes

1. Knowledge Module Moved

The Knowledge functionality has been extracted to a separate package.

Before (v1.1.0)

import { Knowledge, MemoryProvider } from 'toolpack-knowledge';

After (v1.2.0)

import { Knowledge, MemoryProvider } from '@toolpack-sdk/knowledge';

Action required:

1. Install the new package:

   npm install @toolpack-sdk/knowledge

2. Update all imports from toolpack-sdk/knowledge to @toolpack-sdk/knowledge

2. SDK Integration Remains Unchanged

The SDK's integration with Knowledge is still seamless:

import { Toolpack } from 'toolpack-sdk';
import { Knowledge } from '@toolpack-sdk/knowledge';

// This works exactly the same as before
const kb = await Knowledge.create({...});

const toolpack = await Toolpack.init({
  provider: 'anthropic',
  knowledge: kb,  // Duck-typed integration
});

Step-by-Step Migration

Step 1: Update Dependencies

# Update SDK to v1.2.0
npm install toolpack-sdk@1.2.0

# Install Knowledge package
npm install @toolpack-sdk/knowledge

Step 2: Update Imports

Replace all occurrences in your codebase:

// Find and replace:
// FROM: import { X } from 'toolpack-sdk/knowledge';
// TO:   import { X } from '@toolpack-sdk/knowledge';

// Available exports:
import {
  Knowledge,
  MemoryProvider,
  PersistentKnowledgeProvider,
  MarkdownSource,
  OpenAIEmbedder,
  OllamaEmbedder,
} from '@toolpack-sdk/knowledge';

Step 3: Verify TypeScript Configuration

Ensure your tsconfig.json handles ESM properly:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2022"
  }
}

Step 4: Test Your Application

Run your test suite to ensure everything works:

npm test

New Features You Can Use

ESM-First Import (Recommended)

// Modern ESM syntax (v1.2.0 default)
import { Toolpack } from 'toolpack-sdk';

CJS Compatibility (If Needed)

// CommonJS still supported
const { Toolpack } = require('toolpack-sdk');

Enhanced Knowledge Querying

v1.2.0 adds improved metadata filtering:

const results = await kb.query('authentication', {
  filter: {
    hasCode: true,
    category: { $in: ['api', 'guide'] },
    priority: { $gt: 5 }
  }
});

API Changes

Knowledge Package APIs

Feature	v1.1.0	v1.2.0	Notes
Import path	toolpack-sdk/knowledge	@toolpack-sdk/knowledge	Breaking
Knowledge.create()	Same	Same	No changes
MemoryProvider	Same	Same	No changes
MarkdownSource	Same	Same	No changes
Metadata filters	Basic	Enhanced	New operators: $in, $gt, $lt

SDK APIs

Feature	v1.1.0	v1.2.0	Notes
Toolpack.init()	Same	Same	No changes
knowledge option	Same	Same	Duck-typed integration
Build format	CJS only	ESM + CJS	Better compatibility

Troubleshooting

"Cannot find module '@toolpack-knowledge'"

Solution: Install the package:

npm install @toolpack-sdk/knowledge

"Module not found: toolpack-knowledge"

Solution: Update your imports:

// Change from:
import { Knowledge } from 'toolpack-knowledge';

// To:
import { Knowledge } from '@toolpack-sdk/knowledge';

TypeScript Errors

Solution: Update tsconfig.json:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

Package Size Warnings

v1.2.0 is 52% smaller (186KB → 38KB). If you see bundle size issues:

• Ensure you're using the ESM build (dist/index.js)
• Check sideEffects is properly configured in your bundler

Rollback Plan

If you encounter issues:

# Revert to v1.1.0
npm install toolpack-sdk@1.1.0

# Remove Knowledge package
npm uninstall @toolpack-sdk/knowledge

Summary

Breaking changes:

• Knowledge imports: toolpack-knowledge → @toolpack-sdk/knowledge
• New dependency: npm install @toolpack-sdk/knowledge

Unchanged:

• SDK initialization and configuration
• Knowledge integration via knowledge option
• All Knowledge APIs (create, query, providers, sources)

Benefits:

• Smaller SDK package (52% reduction)
• Modular architecture
• Independent versioning
• ESM + CJS dual build

Need Help?

• Knowledge Package Guide - Full documentation
• GitHub Issues - Report problems
• Discussions - Ask questions