@reverbia/sdk 1.0.0-next.20251125212314 → 1.0.0-next.20251127102727

package/README.md

@@ -1,45 +1,186 @@
-# AI SDK
-
-A TypeScript SDK for interacting with ZetaChain's AI Portal API. This SDK
-provides a type-safe, developer-friendly interface for building applications
-that leverage AI chat completion capabilities.
-
-## Overview
-
-The AI SDK is an auto-generated TypeScript client library that wraps the
-ZetaChain AI Portal REST API. It enables seamless integration of AI-powered chat
-completion features into your applications with full TypeScript type safety and
-modern async/await patterns.
-
-## Features
-
-- **Type-Safe API Client**: Fully typed interfaces generated from the OpenAPI
-  specification, ensuring compile-time safety and excellent IDE autocomplete
-  support
-- **Chat Completions**: Generate AI-powered chat responses using configurable
-  models and conversation history
-- **Streaming Support**: Built-in support for streaming responses for real-time
-  AI interactions
-- **Health Monitoring**: Check service health and status to ensure reliable API
-  connectivity
-- **Flexible Configuration**: Customizable client instances with support for
-  custom base URLs, authentication, and request/response interceptors
-- **Error Handling**: Configurable error handling with support for throwing
-  errors or returning error objects
-- **Server-Sent Events**: Native support for SSE (Server-Sent Events) for
-  real-time streaming capabilities
-
-## Architecture
-
-The SDK is automatically generated from the OpenAPI specification using
-`@hey-api/openapi-ts`, ensuring it stays in sync with the latest API changes.
-The generated client provides a clean, promise-based API that follows modern
-JavaScript/TypeScript best practices.
-
-## Use Cases
-
-- Building AI-powered chatbots and conversational interfaces
-- Integrating AI capabilities into web and mobile applications
-- Creating applications that require natural language processing
-- Developing tools that leverage large language models through ZetaChain's
-  gateway
+# @reverbia/sdk
+
+A TypeScript SDK that empowers developers to build AI-powered applications. It
+enables you to send prompts to LLMs with streaming support, manage long-term
+memories, and encrypt sensitive data, all without needing your own LLM API key.
+
+## Installation
+
+```bash
+pnpm install @reverbia/sdk@next
+```
+
+> **Note:** Currently, the SDK is pre-release so all new versions are released
+> under the `next` tag (released on every merge to the `main` branch). Check out
+> npm to see the latest version.
+
+## Configuration
+
+To use the SDK, you'll need to configure your Privy provider and API URL.
+
+```env
+PRIVY_APP_ID=cmhwlx82v000xle0cde4rjy5y
+API_URL=https://ai-portal-dev.zetachain.com
+```
+
+## Authentication
+
+The SDK currently only supports authentication via [Privy](https://privy.io) and
+expects a Privy identity token.
+
+```typescript
+import { useIdentityToken } from "@privy-io/react-auth";
+
+const { identityToken } = useIdentityToken();
+```
+
+## Usage
+
+For an example of how to use this functionality check out [the example
+repo](https://github.com/zeta-chain/ai-examples).
+
+### useChat
+
+The `useChat` hook provides a convenient way to send chat messages to the LLM
+API with automatic token management and loading state handling.
+
+```typescript
+import { useChat } from "@reverbia/sdk/react";
+```
+
+```typescript
+const { sendMessage, isLoading, stop } = useChat({
+  getToken: async () => identityToken || null,
+  onFinish: (response) => {
+    console.log("Chat finished:", response);
+  },
+  onError: (error) => {
+    console.error("Chat error:", error);
+  },
+  onData: (chunk) => {
+    console.log("Received chunk:", chunk);
+  },
+});
+
+const handleSend = async () => {
+  const result = await sendMessage({
+    messages: [{ role: "user", content: "Hello!" }],
+    model: "gpt-4o-mini",
+  });
+
+  if (result.error) {
+    console.error("Error:", result.error);
+  } else {
+    console.log("Response:", result.data);
+  }
+};
+```
+
+### useMemory
+
+The `useMemory` hook allows you to extract facts/memories from messages and
+search through stored memories (in IndexedDB) using semantic search.
+
+How it works:
+
+1. **Fact Extraction:** When prompts are sent to the LLM, they are analyzed for
+   relevant facts. If found, these facts are extracted and converted into vector
+   embeddings.
+2. **Storage:** Extracted memories and their embeddings are stored locally in
+   IndexedDB.
+3. **Retrieval:** New prompts are converted into embedding vectors and compared
+   against stored memories. Relevant memories are then retrieved and used as
+   context for the LLM interaction.
+
+```typescript
+import { useMemory } from "@reverbia/sdk/react";
+```
+
+```typescript
+const { extractMemoriesFromMessage, searchMemories } = useMemory({
+  getToken: async () => identityToken || null,
+  embeddingModel: "openai/text-embedding-3-small",
+});
+
+const handleExtract = async () => {
+  await extractMemoriesFromMessage({
+    messages: [
+      { role: "user", content: "My favorite color is blue" },
+      {
+        role: "assistant",
+        content: "I will remember that your favorite color is blue.",
+      },
+    ],
+    model: "gpt-4o",
+  });
+};
+
+const handleSearch = async () => {
+  const memories = await searchMemories("What is my favorite color?");
+  console.log(memories);
+};
+```
+
+### useEncryption
+
+The `useEncryption` hook and utilities help you encrypt and decrypt local data
+using a key derived from a wallet signature (requires `@privy-io/react-auth`).
+
+```typescript
+import { usePrivy } from "@privy-io/react-auth";
+import { useEncryption, encryptData, decryptData } from "@reverbia/sdk/react";
+```
+
+```typescript
+const { authenticated } = usePrivy();
+
+// Initialize encryption (requests signature if key not present)
+// Pass true when user is authenticated with wallet
+useEncryption(authenticated);
+
+// Encrypt data
+const saveSecret = async (text: string) => {
+  const encrypted = await encryptData(text);
+  localStorage.setItem("secret", encrypted);
+};
+
+// Decrypt data
+const loadSecret = async () => {
+  const encrypted = localStorage.getItem("secret");
+  if (encrypted) {
+    const decrypted = await decryptData(encrypted);
+    console.log(decrypted);
+  }
+};
+```
+
+### Direct API Access
+
+You can also make requests to SDK functions directly without using the React
+hooks.
+
+```typescript
+import { postApiV1ChatCompletions } from "@reverbia/sdk";
+
+const response = await postApiV1ChatCompletions({
+  body: {
+    messages: [{ role: "user", content: "Tell me a joke" }],
+    model: "gpt-4o-mini",
+  },
+  headers: {
+    Authorization: `Bearer ${identityToken}`,
+  },
+});
+
+if (response.data) {
+  console.log(response.data.choices[0].message.content);
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a pull request.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.mts

@@ -74,6 +74,10 @@ type LlmapiChatCompletionUsage = {
      * CompletionTokens is the number of tokens in the completion
      */
     completion_tokens?: number;
+    /**
+     * CostMicroUSD is the cost of this completion in micro-dollars (USD × 1,000,000)
+     */
+    cost_micro_usd?: number;
     /**
      * PromptTokens is the number of tokens in the prompt
      */
@@ -171,6 +175,10 @@ type LlmapiEmbeddingResponse = {
  * Usage contains token usage information
  */
 type LlmapiEmbeddingUsage = {
+    /**
+     * CostMicroUSD is the inference cost for this embedding request
+     */
+    cost_micro_usd?: number;
     /**
      * PromptTokens is the number of tokens in the prompt
      */

package/dist/index.d.ts

@@ -74,6 +74,10 @@ type LlmapiChatCompletionUsage = {
      * CompletionTokens is the number of tokens in the completion
      */
     completion_tokens?: number;
+    /**
+     * CostMicroUSD is the cost of this completion in micro-dollars (USD × 1,000,000)
+     */
+    cost_micro_usd?: number;
     /**
      * PromptTokens is the number of tokens in the prompt
      */
@@ -171,6 +175,10 @@ type LlmapiEmbeddingResponse = {
  * Usage contains token usage information
  */
 type LlmapiEmbeddingUsage = {
+    /**
+     * CostMicroUSD is the inference cost for this embedding request
+     */
+    cost_micro_usd?: number;
     /**
      * PromptTokens is the number of tokens in the prompt
      */

package/dist/react/index.d.mts

@@ -43,6 +43,10 @@ type LlmapiChatCompletionUsage = {
      * CompletionTokens is the number of tokens in the completion
      */
     completion_tokens?: number;
+    /**
+     * CostMicroUSD is the cost of this completion in micro-dollars (USD × 1,000,000)
+     */
+    cost_micro_usd?: number;
     /**
      * PromptTokens is the number of tokens in the prompt
      */

package/dist/react/index.d.ts

@@ -43,6 +43,10 @@ type LlmapiChatCompletionUsage = {
      * CompletionTokens is the number of tokens in the completion
      */
     completion_tokens?: number;
+    /**
+     * CostMicroUSD is the cost of this completion in micro-dollars (USD × 1,000,000)
+     */
+    cost_micro_usd?: number;
     /**
      * PromptTokens is the number of tokens in the prompt
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reverbia/sdk",
-  "version": "1.0.0-next.20251125212314",
+  "version": "1.0.0-next.20251127102727",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -49,7 +49,7 @@
   },
   "homepage": "https://github.com/zeta-chain/ai-sdk#readme",
   "dependencies": {
-    "@reverbia/portal": "1.0.0-next.20251120153026",
+    "@reverbia/portal": "1.0.0-next.20251126175613",
     "@reverbia/sdk": "1.0.0-next.20251120124145",
     "ai": "5.0.93"
   },