diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6faab7d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,52 @@ +# CLAUDE.md + +**solid-ag-chat** is a SolidJS library for building chat UIs with AG-UI protocol support and bidirectional tool execution. This is a library (not a ready-to-use UI), providing primitives and hooks for developers to build custom chat interfaces. + +## Development Setup + +The project contains three versions in separate directories: + +```bash +# v2 (Current - Recommended) +cd v2 && npm run dev # Watch mode +cd v2 && npm run build # Production build + +# v1 (Previous) +cd v1 && npm run dev +cd v1 && npm run build + +# v0 (Deprecated) +cd v0 && npm run dev +cd v0 && npm run build +``` + +## Architecture Highlights + +Each version has its own architecture: + +- **v2**: Exports through `v2/src/index.ts`, primitives in `v2/src/primitives/`, state in `v2/src/store/` +- **v1**: Exports through `v1/src/index.ts`, similar structure to v2 but without tool execution +- **v0**: Exports through `v0/src/index.tsx`, includes built-in UI components + +All versions build to ES module and CommonJS formats with peer dependencies on solid-js. + +## Version Structure + +- **v2 (Current):** Bidirectional tool execution with automatic handler invocation +- **v1 (Previous):** Official AG-UI protocol support +- **v0 (Deprecated):** Legacy version with built-in UI components + +## State Management & Key Features + +The library provides hooks like `useConversation`, `useMessages`, `useToolCalls`, and `useToolExecution` for managing chat state through SolidJS signals and stores. V2 adds tool registration, execution state tracking, and human-in-the-loop patterns. + +## Integration & Workflows + +The backend expects POST requests with conversation history and returns streaming responses via Server-Sent Events following the AG-UI protocol. For active development across library and consuming apps, the recommended approach uses `npm run dev` (watch mode) alongside `npm link` for local testing without npm publication. + +## Key Dependencies + +- **@ag-ui/core** & **@ag-ui/client** - Official AG-UI protocol +- **RxJS** - Reactive streams +- **fast-json-patch** - JSON Patch for state deltas +- **solid-js** (peer) - Reactive UI framework diff --git a/LOCAL_DEVELOPMENT.md b/LOCAL_DEVELOPMENT.md new file mode 100644 index 0000000..7a9f480 --- /dev/null +++ b/LOCAL_DEVELOPMENT.md @@ -0,0 +1,600 @@ +# Local Development - Using @livefire2015/solid-ag-chat Without Publishing to npm + +This guide shows how to use @livefire2015/solid-ag-chat in other applications during local development without publishing to npm. + +## Version Selection + +The library has three versions available: + +| Version | Directory | Status | Use Case | +|---------|-----------|--------|----------| +| v2 | `v2/` | **Current** | Bidirectional tool execution (recommended) | +| v1 | `v1/` | Previous | Official AG-UI protocol support | +| v0 | `v0/` | Deprecated | Legacy with built-in UI components | + +**Note**: Throughout this guide, replace `v2` with `v1` or `v0` if you need to work with those versions. + +## Table of Contents + +- [Method 1: npm link (Recommended)](#method-1-npm-link-recommended) +- [Method 2: Local File Path](#method-2-local-file-path) +- [Method 3: Workspace/Monorepo](#method-3-workspacemonorepo) +- [Method 4: Build and Copy](#method-4-build-and-copy) +- [Hot Reloading Setup](#hot-reloading-setup) +- [Troubleshooting](#troubleshooting) + +## Method 1: npm link (Recommended) + +The `npm link` command creates a symbolic link, making the library available globally and then linking it to your project. + +### Step-by-Step + +**1. In the solid-ag-chat/v2 directory:** + +```bash +cd /path/to/solid-ag-chat/v2 + +# Build the library first +npm run build + +# Create a global symlink +npm link +``` + +**2. In your application directory:** + +```bash +cd /path/to/your-app + +# Link the @livefire2015/solid-ag-chat package +npm link @livefire2015/solid-ag-chat +``` + +**3. Use it in your app:** + +```tsx +import { ChatProvider, useConversation, useMessages } from '@livefire2015/solid-ag-chat'; +import { createSdkAgent } from '@livefire2015/solid-ag-chat'; + +const client = createSdkAgent({ + baseUrl: 'http://localhost:8000', +}); + +const App = () => { + return ( + + + + ); +}; +``` + +### Advantages +- Works like a real npm package +- Easy to set up +- Can link to multiple projects +- Changes reflected after rebuild + +### Development Workflow + +```bash +# In solid-ag-chat/v2 directory +# Make changes to source code +npm run build + +# Changes are now available in linked apps +# Just refresh your app +``` + +### Unlinking + +When you're done: + +```bash +# In your application +npm unlink @livefire2015/solid-ag-chat + +# In solid-ag-chat/v2 directory +npm unlink +``` + +## Method 2: Local File Path + +Install the library directly from the file system. + +### Setup + +**In your application's package.json:** + +```json +{ + "dependencies": { + "@livefire2015/solid-ag-chat": "file:../solid-ag-chat/v2", + "solid-js": "^1.8.0" + } +} +``` + +Then install: + +```bash +npm install +``` + +### Advantages +- Simple and straightforward +- Works with npm/yarn/pnpm +- No global linking needed + +### Disadvantages +- Copies files (not symlink) +- Need to reinstall after changes + +### Development Workflow + +```bash +# 1. Make changes in solid-ag-chat/v2 +cd /path/to/solid-ag-chat/v2 +npm run build + +# 2. Reinstall in your app +cd /path/to/your-app +npm install +``` + +### Updating + +After making changes: + +```bash +# Force reinstall +npm install --force +# or +rm -rf node_modules/@livefire2015/solid-ag-chat +npm install +``` + +## Method 3: Workspace/Monorepo + +Best for managing multiple related packages. + +### Setup with npm Workspaces + +Create a workspace structure: + +``` +my-project/ +├── packages/ +│ ├── solid-ag-chat/ # The library +│ └── my-app/ # Your application +└── package.json # Root package.json +``` + +**Root package.json:** + +```json +{ + "name": "my-monorepo", + "private": true, + "workspaces": [ + "packages/*" + ] +} +``` + +**my-app/package.json:** + +```json +{ + "name": "my-app", + "dependencies": { + "@livefire2015/solid-ag-chat": "*", + "solid-js": "^1.8.0" + } +} +``` + +**Install from root:** + +```bash +# From root directory +npm install +``` + +### Advantages +- Auto-linked between packages +- Shared dependencies +- Easy to manage +- Professional setup + +### Using pnpm Workspaces + +**pnpm-workspace.yaml:** + +```yaml +packages: + - 'packages/*' +``` + +**Root package.json:** + +```json +{ + "name": "my-monorepo", + "private": true +} +``` + +Then: + +```bash +pnpm install +``` + +## Method 4: Build and Copy + +Manually copy the built library to your project. + +### Setup + +**1. Build solid-ag-chat:** + +```bash +cd /path/to/solid-ag-chat/v2 +npm run build +``` + +**2. Copy to your project:** + +```bash +# Create a local directory for the library +cd /path/to/your-app +mkdir -p local-packages/solid-ag-chat + +# Copy the built files +cp -r /path/to/solid-ag-chat/v2/dist local-packages/solid-ag-chat/ +cp /path/to/solid-ag-chat/v2/package.json local-packages/solid-ag-chat/ +``` + +**3. Install from local directory:** + +```json +{ + "dependencies": { + "@livefire2015/solid-ag-chat": "file:./local-packages/solid-ag-chat" + } +} +``` + +### Advantages +- Full control +- No symbolic links +- Can version locally + +### Disadvantages +- Manual process +- Need to copy after changes + +## Hot Reloading Setup + +For real-time development without rebuilding. + +### Option 1: Watch Mode with npm link + +**1. In solid-ag-chat/v2:** + +```bash +cd /path/to/solid-ag-chat/v2 +npm link +npm run dev # This runs vite build --watch +``` + +**2. In your app:** + +```bash +npm link @livefire2015/solid-ag-chat +npm run dev +``` + +Now changes in solid-ag-chat will automatically rebuild and update in your app! + +### Option 2: Direct Source Import (Advanced) + +Configure your app to import the source directly (requires matching build setup). + +**vite.config.ts in your app:** + +```typescript +import { defineConfig } from 'vite'; +import solidPlugin from 'vite-plugin-solid'; +import path from 'path'; + +export default defineConfig({ + plugins: [solidPlugin()], + resolve: { + alias: { + '@livefire2015/solid-ag-chat': path.resolve(__dirname, '../solid-ag-chat/v2/src') + } + } +}); +``` + +**Advantages:** +- Instant updates +- No rebuild needed +- Best developer experience + +**Disadvantages:** +- Complex setup +- Build configs must match + +## Practical Examples + +### Example 1: Quick Test Setup + +```bash +# Terminal 1: solid-ag-chat +cd /path/to/solid-ag-chat/v2 +npm run build +npm link + +# Terminal 2: your app +cd ~/projects/my-chat-app +npm link @livefire2015/solid-ag-chat +npm run dev + +# Make changes, rebuild, refresh browser +``` + +### Example 2: Active Development + +```bash +# Terminal 1: solid-ag-chat (watch mode) +cd /path/to/solid-ag-chat/v2 +npm run dev + +# Terminal 2: your app +cd ~/projects/my-chat-app +npm link @livefire2015/solid-ag-chat +npm run dev + +# Changes auto-rebuild and update! +``` + +### Example 3: Monorepo Setup + +```bash +# Create structure +mkdir my-project +cd my-project + +# Move or clone solid-ag-chat +mv /path/to/solid-ag-chat ./packages/ + +# Create app +mkdir -p packages/my-app + +# Setup workspace +cat > package.json << 'EOF' +{ + "name": "my-project", + "private": true, + "workspaces": ["packages/*"] +} +EOF + +# Install everything +npm install + +# Now solid-ag-chat is automatically linked! +cd packages/my-app +npm run dev +``` + +## Troubleshooting + +### Issue: "Cannot find module '@livefire2015/solid-ag-chat'" + +**Solution:** + +```bash +# Rebuild the library +cd /path/to/solid-ag-chat/v2 +npm run build + +# Relink +npm link + +# In your app +cd /path/to/your-app +npm link @livefire2015/solid-ag-chat +``` + +### Issue: "Module not found" after linking + +**Solution:** Check that the library is built: + +```bash +ls /path/to/solid-ag-chat/v2/dist +# Should show: index.js, index.d.ts, index.cjs +``` + +If empty, run `npm run build`. + +### Issue: Changes not reflecting + +**Solution:** + +```bash +# 1. Rebuild the library +cd /path/to/solid-ag-chat/v2 +npm run build + +# 2. Hard refresh your app +# In browser: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows) + +# 3. Or restart dev server +cd /path/to/your-app +# Ctrl+C to stop +npm run dev +``` + +### Issue: Multiple versions of SolidJS + +**Solution:** Use peer dependencies and ensure SolidJS is only installed once: + +```bash +# In your app +npm list solid-js + +# Should show only one version +# If multiple, remove duplicates +cd /path/to/solid-ag-chat/v2 +npm uninstall solid-js +``` + +### Issue: TypeScript can't find types + +**Solution:** + +```bash +# Make sure types are built +cd /path/to/solid-ag-chat/v2 +npm run build + +# Check dist folder +ls dist/index.d.ts # Should exist +``` + +## Best Practices + +### 1. Always Build Before Linking + +```bash +cd /path/to/solid-ag-chat/v2 +npm run build +npm link +``` + +### 2. Use Watch Mode for Active Development + +```bash +npm run dev +``` + +### 3. Version Your Changes + +Even during local development, commit your changes: + +```bash +git commit -m "feat: add new feature" +``` + +This helps track what version your app is using. + +### 4. Document Local Setup + +In your app's README: + +```markdown +## Local Development with @livefire2015/solid-ag-chat + +This project uses a local version of @livefire2015/solid-ag-chat: + +\`\`\`bash +cd ../solid-ag-chat/v2 +npm run build +npm link + +cd ../my-app +npm link @livefire2015/solid-ag-chat +\`\`\` +``` + +## Comparison Table + +| Method | Setup | Updates | Hot Reload | Multiple Apps | Complexity | +|--------|-------|---------|------------|---------------|------------| +| npm link | Easy | Manual rebuild | With watch | Yes | Low | +| File path | Easy | Reinstall | No | No | Low | +| Workspace | Medium | Automatic | No | Yes | Medium | +| Build/Copy | Manual | Manual | No | No | Low | +| Direct source | Hard | Instant | Yes | Yes | High | + +## Recommended Workflow + +**For casual testing:** +```bash +npm link # Quick and easy +``` + +**For active development:** +```bash +npm run dev # Automatic rebuilds (watch mode) +npm link +``` + +**For team projects:** +```bash +# Use monorepo with workspaces +# Most professional and maintainable +``` + +## When to Publish to npm + +Consider publishing when: +- Library is stable +- Multiple teams need it +- You want version control +- Need semantic versioning +- Want public distribution + +During development, local methods are faster and more flexible! + +## Working with Different Versions + +### Linking a Specific Version + +```bash +# For v2 (recommended) +cd /path/to/solid-ag-chat/v2 +npm run build && npm link + +# For v1 +cd /path/to/solid-ag-chat/v1 +npm run build && npm link + +# For v0 +cd /path/to/solid-ag-chat/v0 +npm run build && npm link +``` + +### Version-Specific Imports + +```tsx +// v2 - Bidirectional tool execution +import { ChatProvider, useConversation, useToolExecution } from '@livefire2015/solid-ag-chat'; + +// v1 - AG-UI protocol support +import { ChatProvider, useConversation, useMessages } from '@livefire2015/solid-ag-chat'; + +// v0 - Built-in UI components +import { ChatContainer, MessageList, Composer } from '@livefire2015/solid-ag-chat'; +``` + +### Switching Between Versions + +To switch from one version to another: + +```bash +# Unlink current version +npm unlink @livefire2015/solid-ag-chat + +# Link new version +cd /path/to/solid-ag-chat/v1 # or v0, v2 +npm run build +npm link + +# In your app +npm link @livefire2015/solid-ag-chat +``` diff --git a/LOCAL_DEV_QUICKSTART.md b/LOCAL_DEV_QUICKSTART.md new file mode 100644 index 0000000..2263c4e --- /dev/null +++ b/LOCAL_DEV_QUICKSTART.md @@ -0,0 +1,281 @@ +# Local Development Quick Start + +Quick reference for using @livefire2015/solid-ag-chat locally without publishing to npm. + +## Version Selection + +| Version | Directory | Status | Description | +|---------|-----------|--------|-------------| +| **v2** | `v2/` | Current | Bidirectional tool execution (recommended) | +| v1 | `v1/` | Previous | AG-UI protocol support | +| v0 | `v0/` | Deprecated | Built-in UI components | + +**Note**: Examples below use v2. Replace with `v1` or `v0` as needed. + +--- + +## Quick Start (2 minutes) + +### Method 1: npm link (Recommended) + +**In solid-ag-chat/v2 directory:** +```bash +cd v2 +npm run build +npm link +``` + +**In your app directory:** +```bash +npm link @livefire2015/solid-ag-chat +npm run dev +``` + +Done! Your app now uses the local version. + +--- + +## All Methods at a Glance + +### 1. npm link (Best for development) +```bash +# solid-ag-chat/v2 +npm run build +npm link + +# your-app +npm link @livefire2015/solid-ag-chat +``` + +### 2. File Path (Simple) +```json +// your-app/package.json +{ + "dependencies": { + "@livefire2015/solid-ag-chat": "file:../solid-ag-chat/v2" + } +} +``` + +### 3. Monorepo (Professional) +``` +project/ +├── packages/ +│ ├── solid-ag-chat/ +│ └── your-app/ +└── package.json (with "workspaces") +``` + +--- + +## Common Commands + +### In solid-ag-chat/v2 directory + +```bash +# Build once +npm run build + +# Build and watch for changes +npm run dev + +# Unlink +npm unlink +``` + +### In your app directory + +```bash +# Link solid-ag-chat +npm link @livefire2015/solid-ag-chat + +# Unlink solid-ag-chat +npm unlink @livefire2015/solid-ag-chat + +# Install from npm instead +npm install @livefire2015/solid-ag-chat +``` + +--- + +## Development Workflow + +### Quick Test (No hot reload) +```bash +# Terminal 1: solid-ag-chat +cd v2 +npm run build +npm link + +# Terminal 2: your-app +npm link @livefire2015/solid-ag-chat +npm run dev + +# Make changes → rebuild → refresh browser +``` + +### Active Development (With hot reload) +```bash +# Terminal 1: solid-ag-chat +cd v2 +npm run dev # watch mode + +# Terminal 2: your-app +npm link @livefire2015/solid-ag-chat +npm run dev + +# Changes auto-rebuild! +``` + +--- + +## Troubleshooting + +### "Cannot find module '@livefire2015/solid-ag-chat'" +```bash +cd solid-ag-chat/v2 +npm run build +npm link +``` + +### Changes not showing +```bash +# Rebuild +cd solid-ag-chat/v2 +npm run build + +# Hard refresh browser: Cmd+Shift+R +``` + +### Multiple SolidJS versions +```bash +# Remove SolidJS from solid-ag-chat (it's a peer dependency) +cd solid-ag-chat/v2 +npm uninstall solid-js + +# Your app should provide it +``` + +--- + +## File Locations + +```bash +# Your setup might look like: +~/projects/ +├── solid-ag-chat/v2/ # This library +└── my-chat-app/ # Your app using it + +# Or in a monorepo: +~/projects/my-monorepo/ +└── packages/ + ├── solid-ag-chat/ + └── my-chat-app/ +``` + +--- + +## Method Comparison + +| Method | Setup Time | Hot Reload | Best For | +|--------|-----------|------------|----------| +| npm link | 30 sec | With watch | Most cases | +| File path | 1 min | No | Simple projects | +| Monorepo | 5 min | No | Teams | + +--- + +## Real-World Examples + +### Example 1: Testing a Bug Fix +```bash +# 1. Make changes in solid-ag-chat/v2 +vim src/primitives/useConversation.ts + +# 2. Rebuild +npm run build + +# 3. Test in your app (already linked) +# Just refresh the browser! +``` + +### Example 2: Developing New Feature +```bash +# Start watch mode +cd solid-ag-chat/v2 +npm run dev # Leave this running + +# In another terminal +cd your-app +npm run dev + +# Now edit solid-ag-chat files +# They'll auto-rebuild and update! +``` + +### Example 3: Switching Between Local and npm +```bash +# Use local version +npm link @livefire2015/solid-ag-chat + +# Switch back to npm version +npm unlink @livefire2015/solid-ag-chat +npm install @livefire2015/solid-ag-chat +``` + +--- + +## Working with All Versions + +### Quick Link Commands + +```bash +# v2 (Current - Recommended) +cd solid-ag-chat/v2 && npm run build && npm link + +# v1 (Previous) +cd solid-ag-chat/v1 && npm run build && npm link + +# v0 (Deprecated) +cd solid-ag-chat/v0 && npm run build && npm link +``` + +### Version-Specific Features + +| Version | Key Exports | +|---------|-------------| +| v2 | `useToolExecution`, `useToolCalls`, `usePendingTools` | +| v1 | `useConversation`, `useMessages`, `useStreamingText` | +| v0 | `ChatContainer`, `MessageList`, `Composer` | + +### Switching Versions + +```bash +# Unlink current +npm unlink @livefire2015/solid-ag-chat + +# Link different version +cd solid-ag-chat/v1 # or v0, v2 +npm run build && npm link + +# In your app +npm link @livefire2015/solid-ag-chat +``` + +--- + +## Full Documentation + +For detailed information, see: +- [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md) - Complete guide +- [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) - Codebase overview + +--- + +## Need Help? + +**Issue not listed?** Check [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md) for: +- Detailed troubleshooting +- Advanced configurations +- Alternative methods +- Best practices diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md new file mode 100644 index 0000000..e34f629 --- /dev/null +++ b/PROJECT_STRUCTURE.md @@ -0,0 +1,355 @@ +# Project Structure + +Overview of the solid-ag-chat library architecture and codebase organization. + +## Directory Structure + +``` +solid-ag-chat/ +├── v2/ # Latest: v2.0.0 - Bidirectional tool execution +│ ├── src/ +│ │ ├── index.ts # Main exports +│ │ ├── types.ts # Type definitions (AG-UI protocol + extensions) +│ │ ├── tool-executor.ts # V2: Tool execution engine +│ │ ├── primitives/ # SolidJS hooks & components +│ │ │ ├── ChatProvider.tsx # Context provider for AG-UI client +│ │ │ ├── useChat.ts # Main hook +│ │ │ ├── useConversation.ts # Single conversation management +│ │ │ ├── useConversationList.ts # Multi-conversation list +│ │ │ ├── useMessages.ts # Message retrieval +│ │ │ ├── useStreamingText.ts # Streaming text accumulation +│ │ │ ├── useToolCalls.ts # V2: Tool call tracking +│ │ │ ├── useToolExecution.ts # V2: Tool execution state +│ │ │ └── usePendingTools.ts # V2: Pending tools queue +│ │ ├── store/ # State management (low-level) +│ │ │ ├── state.ts # ChatState definition +│ │ │ └── createAgUiStore.ts # Solid store creation & event handling +│ │ ├── transport/ # Client implementations +│ │ │ ├── sdk-agent.ts # Official AG-UI SDK wrapper +│ │ │ └── sse.ts # LEGACY: Custom SSE client +│ │ └── testing/ # Testing utilities +│ │ ├── mockClient.ts # Mock AG-UI client for testing +│ │ └── scenarios.ts # Test scenarios +│ ├── package.json +│ ├── tsconfig.json +│ ├── vite.config.ts +│ └── README.md +├── v1/ # v1.0.7 - Official AG-UI protocol support +│ ├── src/ +│ │ ├── index.ts # Main exports +│ │ ├── types.ts # Type definitions +│ │ ├── primitives/ # SolidJS hooks (no tool execution) +│ │ │ ├── ChatProvider.tsx +│ │ │ ├── useChat.ts +│ │ │ ├── useConversation.ts +│ │ │ ├── useConversationList.ts +│ │ │ ├── useMessages.ts +│ │ │ └── useStreamingText.ts +│ │ ├── store/ # State management +│ │ └── transport/ # Client implementations +│ ├── package.json +│ ├── tsconfig.json +│ └── vite.config.ts +├── v0/ # DEPRECATED - Legacy version with UI +│ ├── src/ +│ │ ├── index.tsx # Main exports (note: .tsx) +│ │ ├── components/ # Built-in UI components +│ │ │ ├── ChatContainer.tsx +│ │ │ ├── MessageList.tsx +│ │ │ ├── Message.tsx +│ │ │ └── Composer.tsx +│ │ ├── hooks/ # Chat hooks +│ │ │ └── useChatStream.ts +│ │ └── stores/ # Multiple storage modes +│ ├── package.json +│ ├── tsconfig.json +│ └── vite.config.ts +├── CLAUDE.md # AI assistant instructions +├── LOCAL_DEVELOPMENT.md # Local development guide +├── LOCAL_DEV_QUICKSTART.md # Quick start for local dev +├── PUBLISHING.md # NPM publishing guide +├── PROJECT_STRUCTURE.md # This file +└── .gitignore +``` + +## Core Components + +### Primitives (Hooks) + +The library provides SolidJS hooks for building chat interfaces: + +| Hook | Purpose | +|------|---------| +| `useChat` | Main hook combining conversation and message management | +| `useConversation` | Single conversation state and actions | +| `useConversationList` | Multi-conversation list management | +| `useMessages` | Message retrieval for a conversation | +| `useStreamingText` | Real-time streaming text accumulation | +| `useToolCalls` | Tool call tracking (V2) | +| `useToolExecution` | Tool execution state (V2) | +| `usePendingTools` | Pending tools queue (V2) | + +### Transport Layer + +Two client implementations: + +1. **SdkAgClient** (`sdk-agent.ts`) - Official AG-UI SDK wrapper (recommended) +2. **SseAgClient** (`sse.ts`) - Legacy custom SSE client + +### State Management + +The store follows SolidJS reactive patterns: + +```typescript +interface ChatState { + revision: string; // Server revision tracking + conversations: Record; + messages: Record; + attachments: Record; + messagesByConversation: Record; + streaming: Record; + toolCallsInProgress: Record; + activeConversationId?: Id; +} +``` + +## Integration Approaches + +### 1. Provider Pattern (Recommended) + +Use `ChatProvider` with hooks for full functionality: + +```tsx +import { ChatProvider, useConversation, useMessages } from '@livefire2015/solid-ag-chat'; +import { createSdkAgent } from '@livefire2015/solid-ag-chat'; + +const client = createSdkAgent({ baseUrl: 'http://localhost:8000' }); + +const App = () => ( + + + +); +``` + +### 2. Direct Store Access + +For full control, use the store directly: + +```tsx +import { createAgUiStore } from '@livefire2015/solid-ag-chat'; + +const store = createAgUiStore(client); +// Access store.state and store.actions directly +``` + +### 3. With Tool Execution (V2) + +Register tools for bidirectional execution: + +```tsx +const tools = [ + { + name: 'get_weather', + description: 'Get weather for a location', + parameters: { /* JSON Schema */ }, + handler: async (args) => { + return { temperature: 72, conditions: 'sunny' }; + } + } +]; + + + + +``` + +## Backend Requirements + +The library expects a backend implementing the AG-UI protocol: + +### Request Format + +```typescript +POST /agent/run +{ + "messages": [ + { "role": "user", "content": "Hello" }, + { "role": "assistant", "content": "Hi there!" } + ], + "context": { /* optional */ }, + "tools": [ /* tool definitions */ ] +} +``` + +### Response Format + +Server-Sent Events stream with AG-UI events: + +``` +event: TEXT_MESSAGE_START +data: {"messageId": "msg_1", "role": "assistant"} + +event: TEXT_MESSAGE_CONTENT +data: {"messageId": "msg_1", "delta": "Hello"} + +event: TEXT_MESSAGE_END +data: {"messageId": "msg_1"} +``` + +## Key Dependencies + +| Package | Purpose | +|---------|---------| +| `@ag-ui/core` | Official AG-UI protocol types | +| `@ag-ui/client` | Official HTTP agent (SDK) | +| `rxjs` | Reactive streams/observables | +| `fast-json-patch` | JSON Patch for state deltas | +| `solid-js` (peer) | Reactive UI framework | + +## Build Configuration + +The library builds with Vite in library mode: + +- **ES Module**: `dist/index.js` +- **CommonJS**: `dist/index.cjs` +- **TypeScript**: `dist/index.d.ts` + +External dependencies (not bundled): solid-js, solid-js/web, fast-json-patch, @ag-ui/core, @ag-ui/client, rxjs + +## Version Evolution + +| Version | Status | Key Features | +|---------|--------|--------------| +| v0 | Deprecated | Full component library with built-in UI | +| v1 | Previous | Official AG-UI protocol, hooks pattern | +| v2 | Current | Bidirectional tool execution, enhanced state tracking | + +### v0 Details (Deprecated) + +- **Architecture**: Complete UI component library +- **Key Exports**: `ChatContainer`, `MessageList`, `Message`, `Composer`, `useChatStream` +- **Storage Modes**: Local, remote, IndexedDB +- **Use Case**: Quick prototyping with pre-built UI + +### v1 Details (Previous) + +- **Architecture**: Hooks-based library (no UI components) +- **Key Exports**: `ChatProvider`, `useConversation`, `useMessages`, `useStreamingText` +- **Protocol**: Official AG-UI protocol support +- **Use Case**: Custom UI with AG-UI backend + +### v2 Details (Current) + +- **Architecture**: Hooks-based with bidirectional tool execution +- **Key Exports**: All v1 exports + `useToolCalls`, `useToolExecution`, `usePendingTools` +- **Protocol**: Full AG-UI protocol with tool execution +- **Use Case**: AI agents with tool calling capabilities + +## Development Commands + +### v2 (Recommended) + +```bash +cd v2 +npm run build # Build for distribution +npm run dev # Watch mode for development +npm run build:js # Build JS and declarations +``` + +### v1 + +```bash +cd v1 +npm run build # Build for distribution +npm run dev # Watch mode for development +``` + +### v0 + +```bash +cd v0 +npm run build # Build for distribution +npm run dev # Watch mode for development +``` + +## Exported APIs + +### v2 Exports + +```typescript +// Transport Layer +export { SdkAgClient, createSdkAgent } from './transport/sdk-agent'; +export { SseAgClient } from './transport/sse'; + +// Primitives +export { ChatProvider, useChatContext } from './primitives/ChatProvider'; +export { useChat } from './primitives/useChat'; +export { useConversation } from './primitives/useConversation'; +export { useConversationList } from './primitives/useConversationList'; +export { useMessages } from './primitives/useMessages'; +export { useStreamingText } from './primitives/useStreamingText'; +export { useToolCalls } from './primitives/useToolCalls'; // V2 only +export { useToolExecution } from './primitives/useToolExecution'; // V2 only +export { usePendingTools } from './primitives/usePendingTools'; // V2 only + +// Utilities +export { createAgUiStore } from './store/createAgUiStore'; +export { ToolExecutor } from './tool-executor'; // V2 only +export { MockAgClient } from './testing/mockClient'; +export { runBasicScenario } from './testing/scenarios'; +``` + +### v1 Exports + +```typescript +// Transport Layer +export { SdkAgClient, createSdkAgent } from './transport/sdk-agent'; +export { SseAgClient } from './transport/sse'; + +// Primitives +export { ChatProvider, useChatContext } from './primitives/ChatProvider'; +export { useChat } from './primitives/useChat'; +export { useConversation } from './primitives/useConversation'; +export { useConversationList } from './primitives/useConversationList'; +export { useMessages } from './primitives/useMessages'; +export { useStreamingText } from './primitives/useStreamingText'; + +// Utilities +export { createAgUiStore } from './store/createAgUiStore'; +``` + +### v0 Exports + +```typescript +// Components (Pre-built UI) +export { ChatContainer } from './components/ChatContainer'; +export { MessageList } from './components/MessageList'; +export { Message } from './components/Message'; +export { Composer } from './components/Composer'; + +// Hooks +export { useChatStream } from './hooks/useChatStream'; + +// Stores +export { createLocalStore } from './stores/local'; +export { createRemoteStore } from './stores/remote'; +``` + +## Testing + +Testing utilities are provided for unit testing: + +```typescript +import { MockAgClient, runBasicScenario } from '@livefire2015/solid-ag-chat'; + +const mockClient = new MockAgClient(); +await runBasicScenario(mockClient); +``` + +## Next Steps + +- See [CLAUDE.md](./CLAUDE.md) for AI assistant context +- See [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md) for development setup +- See [PUBLISHING.md](./PUBLISHING.md) for npm publishing +- See `v2/README.md` for detailed usage documentation diff --git a/PUBLISHING.md b/PUBLISHING.md new file mode 100644 index 0000000..ea0100f --- /dev/null +++ b/PUBLISHING.md @@ -0,0 +1,437 @@ +# Publishing to NPM + +This guide explains how to publish @livefire2015/solid-ag-chat to npm. + +## Version Overview + +The project contains three versions that can be published independently: + +| Version | Directory | npm Package Version | Status | +|---------|-----------|---------------------|--------| +| v2 | `v2/` | 2.x.x | **Current** (Recommended) | +| v1 | `v1/` | 1.x.x | Previous | +| v0 | `v0/` | 0.x.x | Deprecated | + +**Note**: Each version directory has its own `package.json` with its own version number. + +## Prerequisites + +Before publishing, ensure you have: + +1. npm account (logged in with access to publish) +2. Access to publish to the `@livefire2015` scope +3. Clean git working directory +4. Library built successfully + +## Pre-Publication Checklist + +Before publishing a new version, complete this checklist: + +### 1. Update Package Metadata (if needed) + +Edit `v2/package.json` to verify: + +```json +{ + "name": "@livefire2015/solid-ag-chat", + "version": "2.0.0", + "author": "livefire2015", + "license": "MIT", + "repository": { + "type": "git", + "url": "https://github.com/livefire2015/solid-ag-chat.git" + }, + "bugs": { + "url": "https://github.com/livefire2015/solid-ag-chat/issues" + }, + "homepage": "https://github.com/livefire2015/solid-ag-chat#readme" +} +``` + +### 2. Verify Package Contents + +Check what will be published: + +```bash +cd v2 +npm pack --dry-run +``` + +This shows all files that will be included in the package. Verify that: +- `dist/` folder is included +- `README.md` is included +- Source files (`src/`) are NOT included (they shouldn't be) +- `node_modules/` is NOT included + +### 3. Build the Library + +```bash +cd v2 +npm run build +``` + +Verify the build output in `dist/`: +- `dist/index.js` - ES module +- `dist/index.cjs` - CommonJS module +- `dist/index.d.ts` - TypeScript definitions + +## Publishing Process + +### For First-Time Publication + +If this is the first time publishing: + +```bash +# 1. Verify you're logged in +npm whoami + +# 2. Check package name is available +npm search @livefire2015/solid-ag-chat + +# 3. Build the library +cd v2 +npm run build + +# 4. Publish (with public access for scoped packages) +npm publish --access public +``` + +### For Subsequent Releases + +#### Option 1: Using npm version (Recommended) + +npm automatically updates version, creates git tag, and commits: + +```bash +cd v2 + +# For patch release (2.0.0 -> 2.0.1) - Bug fixes +npm version patch + +# For minor release (2.0.0 -> 2.1.0) - New features, backward compatible +npm version minor + +# For major release (2.0.0 -> 3.0.0) - Breaking changes +npm version major +``` + +Then build and publish: + +```bash +npm run build +npm publish +``` + +#### Option 2: Manual Version Update + +```bash +# 1. Manually edit version in v2/package.json +# Change "version": "2.0.0" to "version": "2.1.0" + +# 2. Build the library +npm run build + +# 3. Commit the version change +git add v2/package.json +git commit -m "Bump version to 2.1.0" +git tag v2.1.0 +git push && git push --tags + +# 4. Publish to npm +npm publish +``` + +## Version Guidelines (Semantic Versioning) + +Follow [Semantic Versioning](https://semver.org/): + +- **MAJOR** (2.0.0 -> 3.0.0): Breaking changes + - Removing exported functions/hooks + - Changing hook APIs in incompatible ways + - Renaming props or exports + +- **MINOR** (2.0.0 -> 2.1.0): New features, backward compatible + - Adding new hooks + - Adding new props to existing hooks + - Adding new utilities + +- **PATCH** (2.0.0 -> 2.0.1): Bug fixes, backward compatible + - Fixing bugs + - Updating documentation + - Performance improvements + +## Release Workflow + +### Complete Release Process + +```bash +# 1. Ensure clean working directory +git status + +# 2. Pull latest changes +git pull origin main + +# 3. Update version (choose one: patch, minor, major) +cd v2 +npm version minor -m "Release v%s: Add new feature" + +# 4. Build the library +npm run build + +# 5. Publish to npm +npm publish + +# 6. Push git changes and tags +git push && git push --tags + +# 7. Create GitHub release (optional but recommended) +# Go to GitHub -> Releases -> Create new release +# Use the tag you just created (e.g., v2.1.0) +# Add release notes describing changes +``` + +## Post-Publication + +### 1. Verify Package on npm + +Visit: https://www.npmjs.com/package/@livefire2015/solid-ag-chat + +Check that: +- Version number is correct +- README is displaying properly +- Dependencies are correct +- File count looks reasonable + +### 2. Test Installation + +In a separate project, test installing the package: + +```bash +npm install @livefire2015/solid-ag-chat +# or +npm install @livefire2015/solid-ag-chat@2.1.0 +``` + +### 3. Update Documentation + +If you have external documentation, update it with: +- New version number +- New features +- Migration guide (for breaking changes) + +## Unpublishing (Emergency Only) + +**Warning**: Unpublishing can break projects that depend on your package! + +You can only unpublish within 72 hours of publishing: + +```bash +# Unpublish a specific version +npm unpublish @livefire2015/solid-ag-chat@2.0.0 + +# Unpublish entire package (use with extreme caution!) +npm unpublish @livefire2015/solid-ag-chat --force +``` + +Better alternative: Publish a new patch version with the fix. + +## Deprecating Old Versions + +If you want to discourage use of an old version: + +```bash +npm deprecate @livefire2015/solid-ag-chat@1.0.0 "Please upgrade to v2 for bidirectional tool execution" +``` + +## npm Scripts for Publishing + +You can add these helper scripts to `v2/package.json`: + +```json +{ + "scripts": { + "prepublishOnly": "npm run build", + "version": "npm run build && git add -A dist", + "postversion": "git push && git push --tags", + "release:patch": "npm version patch && npm publish", + "release:minor": "npm version minor && npm publish", + "release:major": "npm version major && npm publish" + } +} +``` + +Then you can simply run: + +```bash +npm run release:minor +``` + +## Troubleshooting + +### Error: "You do not have permission to publish" + +Make sure you're logged in and have access to the `@livefire2015` scope: + +```bash +npm whoami +npm access ls-packages +``` + +### Error: "Version already exists" + +You're trying to publish a version that already exists. Update the version: + +```bash +npm version patch +``` + +### Error: "Package name too similar to existing package" + +If publishing for the first time, npm might flag similar package names. Contact npm support or choose a different name. + +### Files Missing in Published Package + +Check your `package.json` `files` array: + +```json +{ + "files": [ + "dist", + "README.md" + ] +} +``` + +## Best Practices + +1. **Always build before publishing**: Run `npm run build` +2. **Use semantic versioning**: Follow MAJOR.MINOR.PATCH correctly +3. **Write good release notes**: Document what changed in each version +4. **Keep dependencies updated**: Regularly update peer dependencies +5. **Test the published package**: Install it in a test project +6. **Tag releases in git**: Use `git tag` for version tracking +7. **Create GitHub releases**: Add release notes on GitHub + +## Quick Reference + +```bash +# Check login status +npm whoami + +# Dry run to see what will be published +cd v2 +npm pack --dry-run + +# Build +npm run build + +# Publish (first time) +npm publish --access public + +# Update version and publish (subsequent releases) +npm version patch # or minor, or major +npm run build +npm publish + +# Push git changes +git push && git push --tags +``` + +## Example Release + +Here's a complete example of publishing version 2.1.0 with new features: + +```bash +# 1. Ensure everything is ready +cd v2 +git status +npm run build + +# 2. Update version +npm version minor -m "Release v%s: Add useToolExecution improvements" +# This creates commit and tag automatically + +# 3. Publish +npm publish + +# 4. Push to git +git push origin main +git push --tags + +# 5. Create GitHub release +# Go to https://github.com/livefire2015/solid-ag-chat/releases/new +# Select tag: v2.1.0 +# Title: "v2.1.0 - Tool Execution Improvements" +# Description: +# ## New Features +# - Improved tool execution state tracking +# - Added new hooks for pending tools +# +# ## Breaking Changes +# None +# +# ## Installation +# ```bash +# npm install @livefire2015/solid-ag-chat@2.1.0 +# ``` +``` + +Done! Your package is now published to npm! + +## Publishing Different Versions + +### Publishing v2 (Current) + +```bash +cd v2 +npm run build +npm version minor -m "Release v%s: New feature" +npm publish +git push && git push --tags +``` + +### Publishing v1 (Previous) + +```bash +cd v1 +npm run build +npm version patch -m "Release v%s: Bug fix" +npm publish +git push && git push --tags +``` + +### Publishing v0 (Deprecated) + +**Note**: v0 is deprecated. Only publish critical security fixes. + +```bash +cd v0 +npm run build +npm version patch -m "Release v%s: Security fix" +npm publish +git push && git push --tags + +# Mark as deprecated +npm deprecate @livefire2015/solid-ag-chat@0.x.x "Please upgrade to v2" +``` + +### Version-Specific Build Outputs + +| Version | ES Module | CommonJS | Types | +|---------|-----------|----------|-------| +| v2 | `dist/index.js` | `dist/index.cjs` | `dist/index.d.ts` | +| v1 | `dist/index.js` | `dist/index.cjs` | `dist/index.d.ts` | +| v0 | `dist/index.js` | `dist/index.cjs` | `dist/index.d.ts` | + +### Checking Published Versions + +```bash +# View all published versions +npm view @livefire2015/solid-ag-chat versions + +# View specific version info +npm view @livefire2015/solid-ag-chat@2.0.0 + +# Check deprecation status +npm view @livefire2015/solid-ag-chat deprecated +```