ai.matey.react.hooks 0.2.0

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

@@ -0,0 +1,75 @@
+/**
+ * useStream Hook
+ *
+ * React hook for generic text streaming with state management.
+ *
+ * @module
+ */
+/**
+ * Stream hook options.
+ */
+export interface UseStreamOptions {
+    /** Called for each chunk */
+    onChunk?: (chunk: string) => void;
+    /** Called when stream completes */
+    onComplete?: (fullText: string) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Initial text value */
+    initialText?: string;
+}
+/**
+ * Stream hook return value.
+ */
+export interface UseStreamReturn {
+    /** Current streamed text */
+    text: string;
+    /** Whether streaming is active */
+    isStreaming: boolean;
+    /** Error if any */
+    error: Error | undefined;
+    /** Start streaming from a response */
+    startStream: (response: Response) => Promise<string>;
+    /** Start streaming from a ReadableStream */
+    startReadableStream: (stream: ReadableStream<Uint8Array>) => Promise<string>;
+    /** Start streaming from an async iterable */
+    startAsyncIterable: (iterable: AsyncIterable<string>) => Promise<string>;
+    /** Stop streaming */
+    stop: () => void;
+    /** Reset state */
+    reset: () => void;
+    /** Manually set text */
+    setText: (text: string) => void;
+}
+/**
+ * useStream - React hook for generic text streaming.
+ *
+ * Provides state management for streaming text from various sources
+ * including fetch responses, ReadableStreams, and async iterables.
+ *
+ * @example
+ * ```tsx
+ * import { useStream } from 'ai.matey.react.hooks';
+ *
+ * function StreamingComponent() {
+ *   const { text, isStreaming, startStream, stop } = useStream({
+ *     onComplete: (fullText) => console.log('Completed:', fullText),
+ *   });
+ *
+ *   const handleClick = async () => {
+ *     const response = await fetch('/api/stream');
+ *     await startStream(response);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleClick} disabled={isStreaming}>Start</button>
+ *       <button onClick={stop} disabled={!isStreaming}>Stop</button>
+ *       <pre>{text}</pre>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useStream(options?: UseStreamOptions): UseStreamReturn;
+//# sourceMappingURL=use-stream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-stream.d.ts","sourceRoot":"","sources":["../../src/use-stream.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,mCAAmC;IACnC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,sBAAsB;IACtB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,yBAAyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB;IACnB,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IACzB,sCAAsC;IACtC,WAAW,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,4CAA4C;IAC5C,mBAAmB,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,6CAA6C;IAC7C,kBAAkB,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACzE,qBAAqB;IACrB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,kBAAkB;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,wBAAwB;IACxB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA0JzE"}

package/dist/types/use-token-count.d.ts

@@ -0,0 +1,68 @@
+/**
+ * useTokenCount Hook
+ *
+ * React hook for estimating token counts.
+ *
+ * @module
+ */
+/**
+ * Token count options.
+ */
+export interface UseTokenCountOptions {
+    /** Text to count tokens for */
+    text?: string;
+    /** Model to use for estimation */
+    model?: string;
+    /** Custom tokenizer function */
+    tokenizer?: (text: string) => number;
+    /** Debounce delay in ms */
+    debounceMs?: number;
+}
+/**
+ * Token count return value.
+ */
+export interface UseTokenCountReturn {
+    /** Estimated token count */
+    tokenCount: number;
+    /** Characters count */
+    characterCount: number;
+    /** Word count */
+    wordCount: number;
+    /** Whether estimation is in progress */
+    isEstimating: boolean;
+    /** Count tokens for text */
+    countTokens: (text: string) => number;
+}
+/**
+ * useTokenCount - React hook for estimating token counts.
+ *
+ * Provides real-time token estimation for text input,
+ * useful for staying within model context limits.
+ *
+ * @example
+ * ```tsx
+ * import { useTokenCount } from 'ai.matey.react.hooks';
+ *
+ * function TokenCounter() {
+ *   const [text, setText] = useState('');
+ *   const { tokenCount, characterCount, wordCount } = useTokenCount({ text });
+ *
+ *   return (
+ *     <div>
+ *       <textarea value={text} onChange={(e) => setText(e.target.value)} />
+ *       <p>Tokens: ~{tokenCount} | Words: {wordCount} | Characters: {characterCount}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useTokenCount(options?: UseTokenCountOptions): UseTokenCountReturn;
+/**
+ * Model-specific token limits.
+ */
+export declare const MODEL_TOKEN_LIMITS: Record<string, number>;
+/**
+ * Get token limit for a model.
+ */
+export declare function getModelTokenLimit(model: string): number | undefined;
+//# sourceMappingURL=use-token-count.d.ts.map

package/dist/types/use-token-count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-token-count.d.ts","sourceRoot":"","sources":["../../src/use-token-count.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,2BAA2B;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,YAAY,EAAE,OAAO,CAAC;IACtB,4BAA4B;IAC5B,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACvC;AA4BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAuDrF;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgBrD,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcpE"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "ai.matey.react.hooks",
+  "version": "0.2.0",
+  "description": "Additional React hooks for AI Matey - useAssistant, useStream, useTokenCount",
+  "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.react.core": "*"
+  },
+  "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",
+    "useAssistant",
+    "useStream",
+    "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-hooks"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,143 @@
+# ai.matey.react.hooks
+
+Additional specialized React hooks for AI applications.
+
+Part of the [ai.matey](https://github.com/johnhenry/ai.matey) monorepo.
+
+## Installation
+
+```bash
+npm install ai.matey.react.hooks
+```
+
+## Quick Start
+
+```tsx
+import { useAssistant } from 'ai.matey.react.hooks';
+
+function AssistantChat() {
+  const { messages, input, handleInputChange, handleSubmit, status } = useAssistant({
+    api: '/api/assistant',
+    assistantId: 'asst_xxx',
+  });
+
+  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={status === 'in_progress'}>
+          Send
+        </button>
+      </form>
+      <p>Status: {status}</p>
+    </div>
+  );
+}
+```
+
+## Exports
+
+### Hooks
+
+- `useAssistant` - OpenAI Assistants API integration with thread management
+- `useTokenCount` - Token counting and context window tracking
+- `useStream` - Low-level stream consumption hook
+
+### Types
+
+- `AssistantMessage`, `Annotation`, `AssistantStatus` - Assistant types
+- `UseAssistantOptions`, `UseAssistantReturn` - useAssistant types
+- `UseTokenCountOptions`, `UseTokenCountReturn` - useTokenCount types
+- `UseStreamOptions`, `UseStreamReturn` - useStream types
+
+## API Reference
+
+### useAssistant
+
+React hook for OpenAI Assistants API with thread and run management.
+
+```tsx
+const {
+  messages,          // AssistantMessage[] - Chat history with annotations
+  input,             // string - Current input
+  setInput,          // (value: string) => void
+  handleInputChange, // (e: ChangeEvent) => void
+  handleSubmit,      // (e?: FormEvent) => void
+  append,            // (message: string | Message) => Promise<void>
+  threadId,          // string | undefined - Current thread ID
+  status,            // AssistantStatus - Run status
+  stop,              // () => void - Cancel current run
+  setMessages,       // (messages: AssistantMessage[]) => void
+  error,             // Error | undefined
+} = useAssistant({
+  api: '/api/assistant',    // API endpoint
+  assistantId: 'asst_xxx',  // OpenAI Assistant ID
+  threadId: 'thread_xxx',   // Existing thread to continue
+  headers: {},              // Request headers
+  body: {},                 // Extra request body
+  onStatus: (status) => {}, // Called on status change
+  onError: (error) => {},   // Called on error
+});
+```
+
+**AssistantStatus values:**
+- `awaiting_message` - Ready for input
+- `in_progress` - Processing request
+- `requires_action` - Tool call pending
+- `completed` - Run finished
+- `failed` - Run failed
+- `cancelled` - Run cancelled
+- `expired` - Run expired
+
+### useTokenCount
+
+Track token usage and context window limits.
+
+```tsx
+const {
+  tokenCount,        // number - Current token count
+  maxTokens,         // number - Model's max context
+  remainingTokens,   // number - Tokens remaining
+  isNearLimit,       // boolean - Within 10% of limit
+  isOverLimit,       // boolean - Exceeded limit
+  updateText,        // (text: string) => void - Update counted text
+} = useTokenCount({
+  model: 'gpt-4',           // Model name for limits
+  text: '',                 // Initial text to count
+  warningThreshold: 0.9,    // Threshold for isNearLimit
+});
+```
+
+**Supported models:**
+- `gpt-4`, `gpt-4-turbo`: 128,000 tokens
+- `gpt-3.5-turbo`: 16,385 tokens
+- `claude-3-opus`, `claude-3-sonnet`: 200,000 tokens
+- And more...
+
+### useStream
+
+Low-level hook for consuming async iterables/streams.
+
+```tsx
+const {
+  data,              // T[] - Accumulated data
+  isStreaming,       // boolean
+  error,             // Error | undefined
+  start,             // (stream: AsyncIterable<T>) => void
+  stop,              // () => void
+  reset,             // () => void
+} = useStream<ChunkType>({
+  onChunk: (chunk) => {},   // Called for each chunk
+  onComplete: (data) => {}, // Called when done
+  onError: (error) => {},   // Called on error
+});
+```
+
+## License
+
+MIT - see [LICENSE](./LICENSE) for details.