@emblemvault/hustle-react 1.0.0

package/README.md

@@ -0,0 +1,225 @@
+# @emblemvault/hustle-react
+
+React hooks and components for AI chat using the Hustle Incognito SDK.
+
+## Installation
+
+```bash
+npm install @emblemvault/hustle-react
+```
+
+## Quick Start
+
+### With Auth SDK (Recommended)
+
+```tsx
+import { EmblemAuthProvider, ConnectButton } from '@emblemvault/emblem-auth-react';
+import { HustleProvider, HustleChat } from '@emblemvault/hustle-react';
+
+function App() {
+  return (
+    <EmblemAuthProvider appId="your-app-id">
+      <HustleProvider>
+        <ConnectButton />
+        <HustleChat showSettings />
+      </HustleProvider>
+    </EmblemAuthProvider>
+  );
+}
+```
+
+### With API Key (Standalone)
+
+```tsx
+import { HustleProvider, HustleChat } from '@emblemvault/hustle-react';
+
+function App() {
+  return (
+    <HustleProvider apiKey="your-key" vaultId="your-vault">
+      <HustleChat showSettings />
+    </HustleProvider>
+  );
+}
+```
+
+## API Reference
+
+### HustleProvider
+
+Provides chat context to your app.
+
+```tsx
+<HustleProvider
+  // With auth SDK (default) - uses EmblemAuthProvider context
+  hustleApiUrl="https://agenthustle.ai"  // optional
+
+  // OR with API key (standalone)
+  apiKey="your-key"
+  vaultId="your-vault"
+
+  // Multi-instance support
+  instanceId="unique-id"  // Scopes settings per instance
+>
+  {children}
+</HustleProvider>
+```
+
+### useHustle
+
+Access chat state and methods.
+
+```tsx
+const {
+  // State
+  isReady,         // boolean - client ready to chat
+  isLoading,       // boolean
+  error,           // Error | null
+  models,          // Model[] - available AI models
+  client,          // HustleIncognitoClient | null
+
+  // Chat methods
+  chat,            // (options) => Promise<ChatResponse>
+  chatStream,      // (options) => AsyncIterable<StreamChunk>
+  uploadFile,      // (file) => Promise<Attachment>
+  loadModels,      // () => Promise<Model[]>
+
+  // Settings (persisted to localStorage)
+  selectedModel,      // string
+  setSelectedModel,   // (model: string) => void
+  systemPrompt,       // string
+  setSystemPrompt,    // (prompt: string) => void
+  skipServerPrompt,   // boolean
+  setSkipServerPrompt, // (skip: boolean) => void
+} = useHustle();
+```
+
+### HustleChat
+
+Complete chat UI component.
+
+```tsx
+<HustleChat
+  showSettings           // Show settings modal button
+  showDebug              // Show tool call debug info
+  placeholder="Message"  // Input placeholder
+  initialSystemPrompt="" // Initial system prompt
+
+  // Callbacks
+  onMessage={(msg) => {}}     // When user sends message
+  onToolCall={(tool) => {}}   // When AI calls a tool
+  onResponse={(content) => {}} // When AI responds
+/>
+```
+
+## Plugins
+
+Extend the AI with custom tools.
+
+### Using Built-in Plugins
+
+```tsx
+import { usePlugins, availablePlugins } from '@emblemvault/hustle-react';
+
+function PluginManager() {
+  const { plugins, registerPlugin, enablePlugin, disablePlugin } = usePlugins();
+
+  return (
+    <div>
+      {availablePlugins.map(plugin => (
+        <button onClick={() => registerPlugin(plugin)}>
+          Install {plugin.name}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+### Creating Custom Plugins
+
+```tsx
+import type { HustlePlugin } from '@emblemvault/hustle-react';
+
+const weatherPlugin: HustlePlugin = {
+  name: 'weather',
+  version: '1.0.0',
+  description: 'Get weather information',
+  enabled: true,
+  tools: [{
+    name: 'get_weather',
+    description: 'Get weather for a city',
+    parameters: {
+      type: 'object',
+      properties: {
+        city: { type: 'string', description: 'City name' },
+      },
+      required: ['city'],
+    },
+  }],
+  executors: {
+    get_weather: async ({ city }) => {
+      const response = await fetch(`/api/weather?city=${city}`);
+      return response.json();
+    },
+  },
+};
+
+// Register it
+const { registerPlugin } = usePlugins();
+registerPlugin(weatherPlugin);
+```
+
+### Plugin Hooks
+
+```tsx
+const plugin: HustlePlugin = {
+  // ... name, tools, executors
+
+  // Modify messages before sending
+  beforeRequest: (messages) => {
+    return messages.map(m => ({
+      ...m,
+      content: m.content.replace(/secret/gi, '[REDACTED]'),
+    }));
+  },
+
+  // Modify response after receiving
+  afterResponse: (response) => {
+    return {
+      ...response,
+      content: response.content + '\n\n---\nPowered by MyPlugin',
+    };
+  },
+};
+```
+
+## Multi-Instance Support
+
+Run multiple isolated chat instances:
+
+```tsx
+<HustleProvider instanceId="trading-bot">
+  <HustleChat />
+</HustleProvider>
+
+<HustleProvider instanceId="support-bot">
+  <HustleChat />
+</HustleProvider>
+```
+
+Each instance has separate settings and plugins stored under its ID.
+
+## Underlying SDK
+
+This package wraps [hustle-incognito](https://github.com/nicktaylor-/hustle-incognito) for React. The SDK handles:
+
+- Chat API communication
+- Streaming responses
+- Tool execution
+- Model selection
+
+For advanced usage, access the client directly via `useHustle().client`.
+
+## License
+
+MIT