@orchata-ai/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Orchata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,420 @@
+<div align="center">
+    <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.orchata.ai/img/orchata-logo-dark.svg">
+    <img alt="Orchata Logo" src="https://cdn.orchata.ai/img/orchata-logo-light.svg">
+    </picture>
+</div>
+
+<div align="center">
+
+**Infrastructure for intelligent applications**
+
+[![Website](https://img.shields.io/badge/Website-orchata.ai-blue?style=for-the-badge&logo=internet-explorer)](https://orchata.ai)
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?style=for-the-badge&logo=github)](https://github.com/orchata-ai)
+
+</div>
+
+## Orchata TypeScript SDK
+
+The official TypeScript/JavaScript SDK for [Orchata](https://orchata.ai).
+
+## Features
+
+- **Type-safe** - Full TypeScript support with auto-completion
+- **Universal** - Works with Node.js 18+, Deno, Bun, and browsers
+- **Zero runtime dependencies** - Uses native `fetch` for HTTP requests
+- **Modern** - ESM-first with CommonJS fallback
+- **AI-ready** - Built-in tools for Vercel AI SDK v5+ integration
+
+## Installation
+
+```bash
+# npm
+npm install @orchata-ai/sdk
+
+# pnpm
+pnpm add @orchata-ai/sdk
+
+# yarn
+yarn add @orchata-ai/sdk
+
+# bun
+bun add @orchata-ai/sdk
+```
+
+### Optional: AI SDK Integration
+
+If you want to use the Vercel AI SDK tools (`@orchata-ai/sdk/ai`), also install:
+
+```bash
+npm install ai@^5.0.0 zod@^3.22.0
+```
+
+## Quick Start
+
+```typescript
+import { Orchata } from '@orchata-ai/sdk';
+
+const client = new Orchata({
+  apiKey: 'oai_your_api_key' // Get one at https://app.orchata.ai
+});
+
+// Query your knowledge base
+const { results } = await client.query({
+  spaceIds: 'space_123',
+  query: 'How do I reset my password?'
+});
+
+console.log(results[0].chunk.content);
+```
+
+## Usage
+
+### Spaces
+
+Spaces are knowledge bases that contain your documents.
+
+```typescript
+// List all spaces
+const { spaces, total } = await client.spaces.list();
+
+// Create a new space
+const { space } = await client.spaces.create({
+  name: 'Documentation',
+  description: 'Product documentation and guides',
+  icon: 'book'
+});
+
+// Get a specific space
+const { space } = await client.spaces.get('space_123');
+
+// Update a space
+const { space } = await client.spaces.update('space_123', {
+  name: 'Updated Name',
+  description: 'New description'
+});
+
+// Delete a space
+await client.spaces.delete('space_123');
+```
+
+### Documents
+
+Documents are the content you want to query.
+
+```typescript
+// List documents in a space
+const { documents } = await client.documents.list({
+  spaceId: 'space_123'
+});
+
+// Upload a document (raw content)
+const { document } = await client.documents.upload({
+  spaceId: 'space_123',
+  content: '# My Document\n\nSome markdown content...',
+  filename: 'my-doc.md',
+  metadata: { category: 'guides' }
+});
+
+// Upload a file (browser)
+const { document } = await client.documents.uploadFile({
+  spaceId: 'space_123',
+  file: fileInput.files[0]
+});
+
+// Batch upload multiple documents
+const result = await client.documents.batchUpload({
+  spaceId: 'space_123',
+  documents: [
+    { filename: 'doc1.md', content: '# Doc 1\n\nContent...' },
+    { filename: 'doc2.md', content: '# Doc 2\n\nContent...' },
+  ]
+});
+console.log(`Uploaded: ${result.totalSuccessful}, Failed: ${result.totalFailed}`);
+
+// Get processed content
+const { content } = await client.documents.getContent('doc_123', 'space_123');
+
+// Delete a document
+await client.documents.delete('doc_123', 'space_123');
+```
+
+### Queries
+
+Query your knowledge base using semantic search.
+
+```typescript
+// Simple query
+const { results } = await client.query({
+  spaceIds: 'space_123',
+  query: 'How do I authenticate?'
+});
+
+// Query multiple spaces
+const { results } = await client.query({
+  spaceIds: ['space_123', 'space_456'],
+  query: 'authentication',
+  topK: 5  // Return top 5 results
+});
+
+// Filter by metadata
+const { results } = await client.query({
+  spaceIds: 'space_123',
+  query: 'API reference',
+  metadata: { category: 'docs' }
+});
+
+// Group results by space
+const { groupedBySpace } = await client.query({
+  spaceIds: ['space_123', 'space_456'],
+  query: 'authentication',
+  groupBySpace: true
+});
+
+// Process results
+for (const result of results) {
+  console.log(`Score: ${result.similarity}`);
+  console.log(`Content: ${result.chunk.content}`);
+  console.log(`Document: ${result.document.filename}`);
+  console.log(`Space: ${result.space.name}`);
+}
+```
+
+### Smart Query
+
+Discover which spaces are most relevant for a query.
+
+```typescript
+// Find relevant spaces
+const { relevantSpaces } = await client.smartQuery({
+  query: 'How do I authenticate users?',
+  maxSpaces: 3
+});
+
+// Use different relevance methods
+const { relevantSpaces } = await client.smartQuery({
+  query: 'authentication',
+  relevanceMethod: 'hybrid',  // 'keyword', 'embedding', or 'hybrid'
+  keywordWeight: 0.5
+});
+
+// Full workflow: discover then query
+const { relevantSpaces } = await client.smartQuery({
+  query: 'user authentication'
+});
+
+const { results } = await client.query({
+  spaceIds: relevantSpaces.map(s => s.space.id),
+  query: 'user authentication'
+});
+```
+
+## Vercel AI SDK Integration
+
+The SDK includes tools for the [Vercel AI SDK](https://sdk.vercel.ai/) v5+, allowing AI models to query your knowledge base.
+
+### Installation
+
+```bash
+# Install the SDK with AI SDK dependencies
+npm install @orchata-ai/sdk ai zod
+
+# Or with specific versions
+npm install @orchata-ai/sdk ai@^5.0.0 zod@^3.22.0
+```
+
+> **Note:** The AI tools require `ai` v5.0.0+ and `zod` v3.22.0+ as peer dependencies. These are optional - if you don't need AI SDK integration, you can use the core SDK without them.
+
+### Basic Usage
+
+```typescript
+import { Orchata } from '@orchata-ai/sdk';
+import { createOrchataTools } from '@orchata-ai/sdk/ai';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const client = new Orchata({ apiKey: 'oai_xxx' });
+const tools = createOrchataTools(client);
+
+const { text } = await generateText({
+  model: openai('gpt-4-turbo'),
+  tools,
+  prompt: 'What does our documentation say about authentication?'
+});
+```
+
+### Available Tools
+
+The `createOrchataTools` function creates these tools:
+
+| Tool | Description |
+|------|-------------|
+| `queryKnowledge` | Search the knowledge base for relevant information |
+| `findRelevantSpaces` | Discover which spaces are most relevant for a query |
+| `listSpaces` | List all available knowledge spaces |
+| `getDocumentContent` | Get the full content of a specific document |
+| `uploadDocument` | Upload new content (disabled by default) |
+| `createSpace` | Create a new space (disabled by default) |
+
+### Simple Query Tool
+
+For simple use cases, use the `createQueryTool` helper:
+
+```typescript
+import { Orchata } from '@orchata-ai/sdk';
+import { createQueryTool } from '@orchata-ai/sdk/ai';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const client = new Orchata({ apiKey: 'oai_xxx' });
+
+// Create a tool that queries a specific space
+const queryTool = createQueryTool(client, 'space_123');
+
+const { text } = await generateText({
+  model: openai('gpt-4-turbo'),
+  tools: { query: queryTool },
+  prompt: 'What is our refund policy?'
+});
+```
+
+### Configuration Options
+
+```typescript
+const tools = createOrchataTools(client, {
+  // Restrict which spaces the AI can access
+  allowedSpaceIds: ['space_123', 'space_456'],
+
+  // Default number of results (default: 5)
+  defaultTopK: 10,
+
+  // Enable document upload (default: false)
+  enableUpload: true,
+
+  // Enable space creation (default: false)
+  enableSpaceCreation: true,
+});
+```
+
+### With Streaming
+
+```typescript
+import { streamText } from 'ai';
+
+const result = streamText({
+  model: openai('gpt-4-turbo'),
+  tools,
+  prompt: 'Summarize our API documentation'
+});
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## Error Handling
+
+The SDK throws typed errors for different scenarios:
+
+```typescript
+import {
+  Orchata,
+  OrchataError,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError
+} from '@orchata-ai/sdk';
+
+try {
+  const { results } = await client.query({
+    spaceIds: 'space_123',
+    query: 'test'
+  });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof NotFoundError) {
+    console.error('Space not found');
+  } else if (error instanceof RateLimitError) {
+    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
+  } else if (error instanceof OrchataError) {
+    console.error(`API error: ${error.message} (${error.status})`);
+  } else {
+    throw error;
+  }
+}
+```
+
+### Error Types
+
+| Error | Status | Description |
+|-------|--------|-------------|
+| `BadRequestError` | 400 | Invalid request parameters |
+| `AuthenticationError` | 401 | Missing or invalid API key |
+| `PermissionDeniedError` | 403 | Insufficient permissions |
+| `NotFoundError` | 404 | Resource not found |
+| `ConflictError` | 409 | Resource conflict |
+| `UnprocessableEntityError` | 422 | Validation error |
+| `RateLimitError` | 429 | Too many requests |
+| `InternalServerError` | 5xx | Server error |
+| `TimeoutError` | - | Request timeout |
+| `ConnectionError` | - | Network connectivity issue |
+
+## Configuration
+
+```typescript
+const client = new Orchata({
+  // Required: Your API key
+  apiKey: 'oai_xxx',
+
+  // Optional: Custom base URL (default: https://api.orchata.ai)
+  baseUrl: 'https://api.orchata.ai',
+
+  // Optional: Request timeout in ms (default: 30000)
+  timeout: 30000,
+
+  // Optional: Custom fetch implementation
+  fetch: customFetch
+});
+```
+
+## Runtime Support
+
+| Runtime | Supported | Notes |
+|---------|-----------|-------|
+| Node.js 18+ | ✅ | Uses native fetch |
+| Node.js 16-17 | ⚠️ | Requires fetch polyfill |
+| Deno | ✅ | Full support |
+| Bun | ✅ | Full support |
+| Browsers | ✅ | Modern browsers |
+| Cloudflare Workers | ✅ | Full support |
+
+## TypeScript
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import type {
+  Space,
+  Document,
+  QueryParams,
+  QueryResponse,
+  QueryResultItem
+} from '@orchata-ai/sdk';
+
+// Types are automatically inferred
+const { spaces } = await client.spaces.list();
+//    ^? Space[]
+
+const { results } = await client.query({ spaceIds: 'x', query: 'test' });
+//    ^? QueryResultItem[]
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+

package/dist/ai.cjs

@@ -0,0 +1,266 @@
+'use strict';
+
+var ai = require('ai');
+var zod = require('zod');
+
+// src/ai/tools.ts
+function createOrchataTools(client, options = {}) {
+  const {
+    allowedSpaceIds,
+    defaultTopK = 5,
+    enableUpload = false,
+    enableSpaceCreation = false
+  } = options;
+  const tools = {};
+  tools.queryKnowledge = ai.tool({
+    description: "Search the knowledge base for relevant information. Returns the most similar content chunks from documents. Use this when you need to find specific information or answer questions based on stored knowledge.",
+    inputSchema: zod.z.object({
+      query: zod.z.string().describe("The search query or question to find relevant content for"),
+      spaceIds: zod.z.union([zod.z.string(), zod.z.array(zod.z.string())]).optional().describe(
+        "Space ID(s) to search in. If not provided, searches all accessible spaces."
+      ),
+      topK: zod.z.number().int().min(1).max(20).optional().describe(`Number of results to return (default: ${defaultTopK})`)
+    }),
+    execute: async ({ query, spaceIds, topK }) => {
+      let targetSpaceIds = spaceIds;
+      if (allowedSpaceIds && allowedSpaceIds.length > 0) {
+        if (targetSpaceIds) {
+          const requested = Array.isArray(targetSpaceIds) ? targetSpaceIds : [targetSpaceIds];
+          targetSpaceIds = requested.filter(
+            (id) => allowedSpaceIds.includes(id)
+          );
+          if (targetSpaceIds.length === 0) {
+            return {
+              error: "None of the requested spaces are accessible",
+              results: []
+            };
+          }
+        } else {
+          targetSpaceIds = allowedSpaceIds;
+        }
+      }
+      if (!targetSpaceIds) {
+        const { relevantSpaces } = await client.smartQuery({
+          query,
+          maxSpaces: 3
+        });
+        if (relevantSpaces.length === 0) {
+          return {
+            message: "No relevant spaces found for this query",
+            results: []
+          };
+        }
+        targetSpaceIds = relevantSpaces.map((s) => s.space.id);
+      }
+      const { results, totalResults } = await client.query({
+        query,
+        spaceIds: targetSpaceIds,
+        topK: topK ?? defaultTopK
+      });
+      return {
+        totalResults,
+        results: results.map((r) => ({
+          content: r.chunk.content,
+          similarity: r.similarity,
+          document: {
+            id: r.document.id,
+            filename: r.document.filename
+          },
+          space: {
+            id: r.space.id,
+            name: r.space.name
+          }
+        }))
+      };
+    }
+  });
+  tools.findRelevantSpaces = ai.tool({
+    description: "Discover which knowledge spaces are most relevant for a query. Use this to understand what topics are covered or to find the right space before querying.",
+    inputSchema: zod.z.object({
+      query: zod.z.string().describe("The query to find relevant spaces for"),
+      maxSpaces: zod.z.number().int().min(1).max(10).optional().describe("Maximum number of spaces to return (default: 3)")
+    }),
+    execute: async ({ query, maxSpaces }) => {
+      const { relevantSpaces, totalSpaces } = await client.smartQuery({
+        query,
+        maxSpaces: maxSpaces ?? 3
+      });
+      let filtered = relevantSpaces;
+      if (allowedSpaceIds && allowedSpaceIds.length > 0) {
+        filtered = relevantSpaces.filter(
+          (s) => allowedSpaceIds.includes(s.space.id)
+        );
+      }
+      return {
+        totalSpacesSearched: totalSpaces,
+        relevantSpaces: filtered.map((s) => ({
+          id: s.space.id,
+          name: s.space.name,
+          description: s.space.description,
+          relevanceScore: s.relevanceScore,
+          matchReason: s.matchReason
+        }))
+      };
+    }
+  });
+  tools.listSpaces = ai.tool({
+    description: "List all available knowledge spaces. Use this to see what topics or categories of knowledge are available.",
+    inputSchema: zod.z.object({
+      status: zod.z.enum(["active", "archived", "all"]).optional().describe("Filter by space status (default: active)")
+    }),
+    execute: async ({ status }) => {
+      const { spaces, total } = await client.spaces.list({
+        status: status ?? "active",
+        pageSize: 100
+      });
+      let filtered = spaces;
+      if (allowedSpaceIds && allowedSpaceIds.length > 0) {
+        filtered = spaces.filter((s) => allowedSpaceIds.includes(s.id));
+      }
+      return {
+        total: filtered.length,
+        spaces: filtered.map((s) => ({
+          id: s.id,
+          name: s.name,
+          description: s.description,
+          icon: s.icon
+        }))
+      };
+    }
+  });
+  tools.getDocumentContent = ai.tool({
+    description: "Get the full processed content of a specific document. Use this when you need the complete text of a document after finding it via search.",
+    inputSchema: zod.z.object({
+      documentId: zod.z.string().describe("The ID of the document to retrieve"),
+      spaceId: zod.z.string().describe("The ID of the space containing the document")
+    }),
+    execute: async ({ documentId, spaceId }) => {
+      if (allowedSpaceIds && !allowedSpaceIds.includes(spaceId)) {
+        return { error: "Access denied to this space" };
+      }
+      try {
+        const { content, filename } = await client.documents.getContent(
+          documentId,
+          spaceId
+        );
+        return { filename, content };
+      } catch (error) {
+        return {
+          error: error instanceof Error ? error.message : "Failed to get document"
+        };
+      }
+    }
+  });
+  if (enableUpload) {
+    tools.uploadDocument = ai.tool({
+      description: "Upload new content to the knowledge base. Use this to add new information that should be searchable.",
+      inputSchema: zod.z.object({
+        spaceId: zod.z.string().describe("The ID of the space to upload the document to"),
+        content: zod.z.string().describe("The markdown or text content to upload"),
+        filename: zod.z.string().optional().describe("Optional filename (defaults to document.md)")
+      }),
+      execute: async ({ spaceId, content, filename }) => {
+        if (allowedSpaceIds && !allowedSpaceIds.includes(spaceId)) {
+          return { error: "Access denied to this space" };
+        }
+        try {
+          const { document } = await client.documents.upload({
+            spaceId,
+            content,
+            filename
+          });
+          return {
+            success: true,
+            documentId: document.id,
+            filename: document.filename,
+            status: document.status
+          };
+        } catch (error) {
+          return {
+            error: error instanceof Error ? error.message : "Failed to upload document"
+          };
+        }
+      }
+    });
+  }
+  if (enableSpaceCreation) {
+    tools.createSpace = ai.tool({
+      description: "Create a new knowledge space. Use this to organize knowledge into a new category.",
+      inputSchema: zod.z.object({
+        name: zod.z.string().describe("The name of the space"),
+        description: zod.z.string().describe("A description of what the space contains"),
+        icon: zod.z.enum([
+          "folder",
+          "book",
+          "file-text",
+          "database",
+          "package",
+          "archive",
+          "briefcase",
+          "inbox",
+          "layers",
+          "box"
+        ]).optional().describe("Icon for the space (default: folder)")
+      }),
+      execute: async ({ name, description, icon }) => {
+        try {
+          const { space } = await client.spaces.create({
+            name,
+            description,
+            icon: icon ?? "folder"
+          });
+          return {
+            success: true,
+            spaceId: space.id,
+            name: space.name,
+            slug: space.slug
+          };
+        } catch (error) {
+          return {
+            error: error instanceof Error ? error.message : "Failed to create space"
+          };
+        }
+      }
+    });
+  }
+  return tools;
+}
+function createQueryTool(client, spaceIds, options = {}) {
+  const { topK = 5 } = options;
+  return ai.tool({
+    description: "Search the knowledge base for relevant information. Returns the most similar content chunks from documents.",
+    inputSchema: zod.z.object({
+      query: zod.z.string().describe("The search query or question to find relevant content for")
+    }),
+    execute: async ({ query }) => {
+      let targetSpaceIds = spaceIds;
+      if (!targetSpaceIds) {
+        const { relevantSpaces } = await client.smartQuery({
+          query,
+          maxSpaces: 3
+        });
+        if (relevantSpaces.length === 0) {
+          return { results: [], message: "No relevant spaces found" };
+        }
+        targetSpaceIds = relevantSpaces.map((s) => s.space.id);
+      }
+      const { results } = await client.query({
+        query,
+        spaceIds: targetSpaceIds,
+        topK
+      });
+      return {
+        results: results.map((r) => ({
+          content: r.chunk.content,
+          similarity: r.similarity,
+          source: `${r.space.name} / ${r.document.filename}`
+        }))
+      };
+    }
+  });
+}
+
+exports.createOrchataTools = createOrchataTools;
+exports.createQueryTool = createQueryTool;
+//# sourceMappingURL=ai.cjs.map
+//# sourceMappingURL=ai.cjs.map