{"_id":"@aleph/openai-streaming-hooks","name":"@aleph/openai-streaming-hooks","dist-tags":{"latest":"2.0.0"},"versions":{"2.0.0":{"name":"@aleph/openai-streaming-hooks","version":"2.0.0","description":"React Hooks for streaming connections to OpenAI APIs","main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","scripts":{"lint":"eslint src/ --ext .ts","build":"tsc","clean":"rm -rf node_modules/ dist/ coverage/","prepare":"npm run build","example":"vite serve example","test":"vitest","test:coverage":"vitest run --coverage","prettier":"prettier --write ."},"keywords":["react","react-hooks","openai"],"author":{"name":"jonrhall"},"contributors":[{"name":"Michael Flohr","url":"https://github.com/MatchuPitchu"}],"license":"MIT","dependencies":{"react":"^18.2.0"},"devDependencies":{"@testing-library/react":"^14.0.0","@types/react":"^18.0.29","@types/react-dom":"^18.0.11","@typescript-eslint/eslint-plugin":"^5.56.0","@typescript-eslint/parser":"^5.56.0","@vitejs/plugin-react":"^3.1.0","@vitest/coverage-c8":"^0.31.0","eslint":"^8.36.0","eslint-config-prettier":"^8.8.0","eslint-plugin-import":"^2.27.5","eslint-plugin-n":"^15.6.1","eslint-plugin-promise":"^6.1.1","eslint-plugin-react":"^7.32.2","jsdom":"^21.1.1","prettier":"2.8.8","react-dom":"^18.2.0","typescript":"^5.0.2","vite":"^4.2.1","vitest":"^0.31.0"},"gitHead":"eaf44b3313edad84c439797511e96a1e4f0f44c9","_id":"@aleph/openai-streaming-hooks@2.0.0","_nodeVersion":"18.17.0","_npmVersion":"9.6.7","dist":{"integrity":"sha512-U47Jum69LMIZyxcODFgGj9cT3Vg//CGfUr8NKcdGQkCpr4oQsQDV8M+LrxmtqMKT3g3ge/cGmzwzwZmsM+ZuAQ==","shasum":"f2091079a6af1c67549029327afa5a182a8e9e87","tarball":"https://registry.npmjs.org/@aleph/openai-streaming-hooks/-/openai-streaming-hooks-2.0.0.tgz","fileCount":32,"unpackedSize":1117934,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIE0vb4z7hWN6fhYZuOpCWgvmfMdRLNKRLZDIZAE1cAx8AiEA87o4VH2BTVegxBaJh0a8LfMK2yjmFmCmgJe7Z/rG/OQ="}]},"_npmUser":{"name":"alephsf","email":"ping@alephsf.com"},"directories":{},"maintainers":[{"name":"tusinga","email":"amanda@alephsf.com"},{"name":"alephsf","email":"ping@alephsf.com"},{"name":"oppodeldoc","email":"matt@alephsf.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/openai-streaming-hooks_2.0.0_1703475435314_0.03804032533290158"},"_hasShrinkwrap":false}},"time":{"created":"2023-12-25T03:37:15.211Z","2.0.0":"2023-12-25T03:37:15.559Z","modified":"2023-12-25T03:37:15.900Z"},"maintainers":[{"name":"tusinga","email":"amanda@alephsf.com"},{"name":"alephsf","email":"ping@alephsf.com"},{"name":"oppodeldoc","email":"matt@alephsf.com"}],"description":"React Hooks for streaming connections to OpenAI APIs","keywords":["react","react-hooks","openai"],"contributors":[{"name":"Michael Flohr","url":"https://github.com/MatchuPitchu"}],"author":{"name":"jonrhall"},"license":"MIT","readme":"# OpenAI Streaming Hooks\n\n> Talk directly to [OpenAI Completion APIs](https://platform.openai.com/docs/api-reference/chat) and stream the response back in real-time in the browser--no server required.\n>\n> **All models based on GPT3.5 and GPT4 are supported!**\n\nProvides a [custom React Hook](https://react.dev/learn/reusing-logic-with-custom-hooks) capable of calling OpenAI Chat Completions APIs with [streaming support](https://github.com/openai/openai-cookbook/blob/main/examples/How_to_stream_completions.ipynb) enabled by [ReadableStreams](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).\n\nThe library then decorates every Completion response with metadata about the transaction such as:\n\n- The number of tokens used in the response\n- The total time it took to complete the request\n- Each chunk received in the stream\n- The timestamp each chunk was received\n- The timestamp from when the Completion was finished\n\n## Example\n\n![Usage example](https://github.com/jonrhall/openai-streaming-hooks/blob/main/example/example.gif)\n\n[Example code here](https://github.com/jonrhall/openai-streaming-hooks/blob/main/example/example.tsx)\n\nSee section on [running the example](#running-the-example) for more information.\n\n## Use\n\n1. Install the OpenAI Streaming Hooks library via a package manager like `npm` or `yarn`:\n\n```bash\nnpm install --save openai-streaming-hooks\n```\n\n2. Import the hook and use it:\n\n```tsx\nimport { useChatCompletion } from 'openai-streaming-hooks';\n\nconst Component = () => {\n  const { messages, submitPrompt } = useChatCompletion({\n    model: 'gpt-3.5-turbo', // Required\n    apiKey: 'your-api-key', // Required\n    temperature: 0.9,\n  });\n  ...\n};\n```\n\n### Supported Model Parameters\n\n[All API parameters supported by the OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) are also supported here.\n\nFor example, it is OK to include optional params like `temperature`, `max_tokens`, etc. when instantiating the chat hook in the above code block.\n\n### Hook Shape\n\nInvoking the hook returns several properties for manipulating messages, submitting queries and understanding the state of the hook:\n\n```ts\nconst {\n  messages, // The list of messages in the completion\n  loading, // If a new completion request is currently in progress\n  submitPrompt, // Submits a prompt for completion, for more information see \"Submitting a Prompt\"\n  abortResponse, // Allows the user to abort a chat response that is in progress, see \"Aborting responses\"\n  resetMessages, // Reset the messages list to empty, see \"Resetting Message List\"\n  setMessages, // Overwrites any messages in the list, see \"Setting Message List\"\n} = useChatCompletion(...);\n```\n\n## Types of Completions\n\n**Currently, this package only supports Chat Completions. Adding Text Completions support to this package is a future roadmap item (pull requests accepted).**\n\nThere are two main types of completions available from OpenAI:\n\n1. [Chat Completions](https://platform.openai.com/docs/guides/chat), which includes models like `gpt-4` and `gpt-3.5-turbo`.\n2. [Text Completions](https://platform.openai.com/docs/guides/completion), which includes models like `text-davinci-003`.\n\nThere are some pretty big fundamental differences in the way these models are supported on the API side. Chat Completions consider the context of previous messages when making the next completion. Text Completions only consider the context passed into the explicit message it is currently answering.\n\nFor more information on chat vs. text completion models, see [LangChain's excellent blog post on the topic](https://blog.langchain.dev/chat-models/).\n\n### Chat Completions\n\nAn individual message in a chat completion's `messages` list looks like this:\n\n```ts\ninterface ChatMessage {\n  content: string; // The content of the completion\n  role: string; // The role of the person/AI in the message\n  timestamp: number; // The timestamp of when the completion finished\n  meta: {\n    loading: boolean; // If the completion is still being executed\n    responseTime: string; // The total elapsed time the completion took\n    chunks: ChatCompletionToken[]; // The chunks returned as a part of streaming the execution of the completion\n  };\n}\n```\n\nEach chunk corresponds to a token streamed back to the client in the completion. A `ChatCompletionToken` is the base incremental shape of content in the stream returned from the OpenAI API. It looks like this:\n\n```ts\ninterface ChatCompletionToken {\n  content: string; // The partial content, if any, received in the chunk\n  role: string; // The role, if any, received in the chunk\n  timestamp: number; // The time the chunk was received\n}\n```\n\n## Submitting a Prompt\n\nCall the `submitPrompt` function to initiate a chat completion request whose response will be streamed back to the client from the OpenAI Chat Completions API. A query takes a list of new messages to append to the existing `messages` list and submits fully appended `messages` list to OpenAI's Chat Completions API.\n\nA sample message list might look like:\n\n```ts\nconst newMessages = [\n  {\n    role: 'system',\n    content: 'You are a short story bot, you write short stories for kids',\n  },\n  {\n    role: 'user',\n    content: 'Write a story about a lonely bunny',\n  },\n];\n```\n\nWhen the prompt is submitted, a blank message is appended to the end of the `messages` list with its `meta.loading` state set to `true` (the `loading` flag of the hook will also be set to `true`). This message will be where the content that is streamed back to the client is collected in real-time.\n\nNew chunks of the message will appear in the `meta.chunks` list and your React component will be updated every time a new chunk appears automatically.\n\n> 💡 **Chunks correspond directly to tokens.**\n>\n> By counting the number of chunks, you can count the number of tokens that a response used.\n\n### Aborting responses\n\nIf a prompt has been submitted and the response is still being streamed back to the client, it is possible to invoke the `abortResponse` function to stop the response stream from continuing. This function will only work if the request is in progress.\n\n## Setting Message List\n\nThe hook exposes a `setMessages` function which will overwrite any existing messages\n\nThis function will not set the messages list is a chat complete request is in progress.\n\n## Resetting Message List\n\nIf the `resetMessages` function is called the messages list will be set back to empty, as long as the function is invoked when a chat completion request isn't in progress.\n\n## Running the Example\n\n1. Clone this package locally and navigate to it:\n\n```bash\ngit clone https://github.com/jonrhall/openai-streaming-hooks.git\ncd openai-streaming-hooks\n```\n\n2. Export your [OpenAI API Key](https://platform.openai.com/account/api-keys) as environment variable `VITE_OPENAI_API_KEY`:\n\n```bash\nexport VITE_OPENAI_API_KEY=your-key-here\n```\n\n3. Run the example dev server:\n\n```bash\nnpm run example\n```\n\n4. Navigate to `https://localhost:5179` to see the live example.\n\n## Contributors\n\n<div style=\"display: flex;\">\n  <a href=\"https://github.com/jonrhall\" style=\"display: flex; flex-direction: column; align-items: center; padding: 0 10px 0 0;\">\n    <img src=\"https://github.com/jonrhall.png\" alt=\"Jon Hall\" title=\"Jon Hall\" width=\"100\" height=\"100\"/>\n    <span>Jon Hall</span>\n  </a>\n  <a href=\"https://github.com/MatchuPitchu\" style=\"display: flex; flex-direction: column; align-items: center; padding: 0 10px 0 0;\">\n    <img src=\"https://github.com/MatchuPitchu.png\" alt=\"Michael Flohr\" title=\"Michael Flohr\" width=\"100\" height=\"100\"/>\n    <span>Michael Flohr</span>\n  </a>\n</div>\n\n### Future Contributions\n\n- This package accepts contributions in the form of Pull Requests against the `main` branch.\n- Please follow the coding format as put forth in the ESLint and Prettier definitions used in the package.\n- Passing unit tests for all new code/functionality also is greatly appreciated, if not mandatory for PR acceptance in most cases.\n- Before contributing, please see our developer [Code of Conduct](https://github.com/jonrhall/openai-streaming-hooks/blob/main/CODE_OF_CONDUCT.md).\n","readmeFilename":"README.md"}