ai.matey.react.core 0.2.0

package/dist/types/use-completion.d.ts

@@ -0,0 +1,37 @@
+/**
+ * useCompletion Hook
+ *
+ * React hook for text completion interfaces with streaming support.
+ *
+ * @module
+ */
+import type { UseCompletionOptions, UseCompletionReturn } from './types.js';
+/**
+ * useCompletion - React hook for text completion.
+ *
+ * Provides state management and streaming for single-turn
+ * text completion tasks.
+ *
+ * @example
+ * ```tsx
+ * import { useCompletion } from 'ai.matey.react.core';
+ *
+ * function CompletionComponent() {
+ *   const { completion, input, handleInputChange, handleSubmit, isLoading } = useCompletion({
+ *     api: '/api/completion',
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <p>{completion}</p>
+ *       <form onSubmit={handleSubmit}>
+ *         <input value={input} onChange={handleInputChange} placeholder="Enter a prompt..." />
+ *         <button type="submit" disabled={isLoading}>Complete</button>
+ *       </form>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCompletion(options?: UseCompletionOptions): UseCompletionReturn;
+//# sourceMappingURL=use-completion.d.ts.map

package/dist/types/use-completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-completion.d.ts","sourceRoot":"","sources":["../../src/use-completion.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EAEpB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAoMrF"}

package/dist/types/use-object.d.ts

@@ -0,0 +1,47 @@
+/**
+ * useObject Hook
+ *
+ * React hook for streaming structured objects with streaming support.
+ *
+ * @module
+ */
+import type { UseObjectOptions, UseObjectReturn } from './types.js';
+/**
+ * useObject - React hook for streaming structured objects.
+ *
+ * Provides state management for streaming JSON objects with
+ * partial updates as data arrives.
+ *
+ * @example
+ * ```tsx
+ * import { useObject } from 'ai.matey.react.core';
+ *
+ * interface Recipe {
+ *   name: string;
+ *   ingredients: string[];
+ *   instructions: string[];
+ * }
+ *
+ * function RecipeGenerator() {
+ *   const { object, submit, isLoading } = useObject<Recipe>({
+ *     api: '/api/generate-recipe',
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => submit('Generate a pasta recipe')} disabled={isLoading}>
+ *         Generate Recipe
+ *       </button>
+ *       {object && (
+ *         <div>
+ *           <h2>{object.name}</h2>
+ *           <ul>{object.ingredients?.map((i, idx) => <li key={idx}>{i}</li>)}</ul>
+ *         </div>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useObject<T>(options?: UseObjectOptions<T>): UseObjectReturn<T>;
+//# sourceMappingURL=use-object.d.ts.map

package/dist/types/use-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-object.d.ts","sourceRoot":"","sources":["../../src/use-object.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAE,gBAAgB,CAAC,CAAC,CAAM,GAAG,eAAe,CAAC,CAAC,CAAC,CAwKlF"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "ai.matey.react.core",
+  "version": "0.2.0",
+  "description": "Core React hooks for AI Matey - useChat, useCompletion, useObject",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "readme.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "ai.matey.types": "*",
+    "ai.matey.core": "*",
+    "ai.matey.wrapper": "*"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "react",
+    "hooks",
+    "useChat",
+    "useCompletion",
+    "ai-matey"
+  ],
+  "author": "AI Matey",
+  "license": "MIT",
+  "homepage": "https://github.com/johnhenry/ai.matey#readme",
+  "bugs": {
+    "url": "https://github.com/johnhenry/ai.matey/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/ai.matey.git",
+    "directory": "packages/react-core"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,232 @@
+# ai.matey.react.core
+
+Core React hooks for AI chat interactions.
+
+Part of the [ai.matey](https://github.com/johnhenry/ai.matey) monorepo.
+
+## Installation
+
+```bash
+npm install ai.matey.react.core
+```
+
+## Quick Start
+
+### HTTP Mode (Default)
+
+```tsx
+import { useChat } from 'ai.matey.react.core';
+
+function ChatComponent() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
+    api: '/api/chat',
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} />
+        <button type="submit" disabled={isLoading}>Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+### Direct Backend Mode
+
+Use any backend adapter directly without HTTP - great for Electron apps, browser extensions, or when you want to skip the server:
+
+```tsx
+import { useChat } from 'ai.matey.react.core';
+import { OpenAIBackend } from 'ai.matey.backend/openai';
+
+// Create backend (could also be Anthropic, Gemini, Ollama, etc.)
+const backend = new OpenAIBackend({
+  apiKey: process.env.REACT_APP_OPENAI_API_KEY,
+});
+
+function ChatComponent() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
+    direct: {
+      backend,
+      systemPrompt: 'You are a helpful assistant.',
+    },
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} />
+        <button type="submit" disabled={isLoading}>Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+## Exports
+
+### Hooks
+
+- `useChat` - Chat interface with streaming support
+- `useCompletion` - Text completion interface
+- `useObject` - Structured object generation
+
+### Types
+
+- `Message` - Chat message type
+- `ToolCall`, `ToolInvocation`, `Tool` - Tool calling types
+- `UseChatOptions`, `UseChatReturn` - useChat types
+- `UseCompletionOptions`, `UseCompletionReturn` - useCompletion types
+- `UseObjectOptions`, `UseObjectReturn` - useObject types
+- `DirectBackend`, `DirectModeOptions`, `DirectToolCallHandler` - Direct mode types
+
+## API Reference
+
+### useChat
+
+React hook for building chat interfaces with streaming support.
+
+Supports two modes:
+1. **HTTP Mode** (default): Uses `api` endpoint with fetch
+2. **Direct Mode**: Uses `direct.backend` for direct backend access
+
+```tsx
+const {
+  messages,        // Message[] - Chat history
+  input,           // string - Current input value
+  setInput,        // (value: string) => void - Set input
+  handleInputChange, // (e: ChangeEvent) => void - Input change handler
+  handleSubmit,    // (e?: FormEvent) => void - Form submit handler
+  append,          // (message: Message | string) => Promise<string | null>
+  reload,          // () => Promise<string | null> - Reload last response
+  stop,            // () => void - Stop streaming
+  setMessages,     // (messages: Message[]) => void
+  isLoading,       // boolean - Request in progress
+  error,           // Error | undefined
+  data,            // unknown[] | undefined - Additional data
+} = useChat(options);
+```
+
+#### HTTP Mode Options
+
+```tsx
+useChat({
+  api: '/api/chat',           // API endpoint (default: '/api/chat')
+  initialMessages: [],        // Initial messages
+  initialInput: '',           // Initial input value
+  id: 'chat-1',              // Chat instance ID
+  headers: {},               // Request headers
+  body: {},                  // Extra request body fields
+  onFinish: (message) => {}, // Called when response completes
+  onError: (error) => {},    // Called on error
+  onResponse: (response) => {}, // Called with fetch response
+  streamProtocol: 'data',    // 'data' (SSE) or 'text'
+});
+```
+
+#### Direct Mode Options
+
+```tsx
+useChat({
+  direct: {
+    // Required: Backend adapter (any ai.matey backend or Bridge)
+    backend: myBackendAdapter,
+
+    // Optional: System prompt
+    systemPrompt: 'You are a helpful assistant.',
+
+    // Optional: Default IR parameters
+    defaultParameters: {
+      temperature: 0.7,
+      maxTokens: 1000,
+    },
+
+    // Optional: Available tools
+    tools: [
+      {
+        name: 'get_weather',
+        description: 'Get weather for a location',
+        parameters: { /* JSON Schema */ },
+      },
+    ],
+
+    // Optional: Tool call handler
+    onToolCall: async (name, input, id) => {
+      return 'Tool result';
+    },
+
+    // Optional: Auto-execute tools (default: false)
+    autoExecuteTools: true,
+
+    // Optional: Max tool rounds (default: 10)
+    maxToolRounds: 5,
+  },
+  // Common options still work
+  initialMessages: [],
+  onFinish: (message) => {},
+  onError: (error) => {},
+});
+```
+
+### useCompletion
+
+React hook for text completion interfaces.
+
+```tsx
+const {
+  completion,      // string - Current completion
+  input,           // string - Current input
+  setInput,        // (value: string) => void
+  handleInputChange,
+  handleSubmit,
+  complete,        // (prompt: string) => Promise<string | null>
+  stop,
+  isLoading,
+  error,
+} = useCompletion({
+  api: '/api/completion',
+  // ... similar options to useChat
+});
+```
+
+### useObject
+
+React hook for generating structured objects.
+
+```tsx
+const {
+  object,          // T | undefined - Generated object
+  submit,          // (input: string) => void
+  isLoading,
+  error,
+} = useObject<MyType>({
+  api: '/api/object',
+  schema: myZodSchema, // Zod schema for validation
+});
+```
+
+## Direct Mode vs HTTP Mode
+
+| Feature | HTTP Mode | Direct Mode |
+|---------|-----------|-------------|
+| Setup | Requires API endpoint | Just a backend adapter |
+| Server needed | Yes | No |
+| Use case | Full-stack apps | Electron, browser extensions, testing |
+| Streaming | Via SSE | Native async iterators |
+| Tool calling | Via API | Built-in with `wrapper-ir` |
+
+## License
+
+MIT - see [LICENSE](./LICENSE) for details.