cencori 1.4.0 → 1.4.1

package/README.md

@@ -170,6 +170,31 @@ import { VisionUploader } from 'cencori/react';
 
 Full API in [docs](https://cencori.com/docs/ai/endpoints/vision).
 
+### Documents (PDF & Image Extraction)
+
+Extract text from PDFs and images, summarize documents, and answer questions about them. Text-based PDFs use native parsing — no LLM tokens, free.
+
+```typescript
+// Extract text — native PDF parsing, free
+const { text, method } = await cencori.documents.extract({
+  document: { url: 'https://example.com/contract.pdf' },
+});
+console.log(method); // 'pdf_text' means free
+
+// Summarize
+const { summary } = await cencori.documents.summarize({
+  document: { url: 'https://example.com/report.pdf' },
+});
+
+// Q&A — strict "Not found" if the answer isn't in the doc
+const { answer } = await cencori.documents.query({
+  document: { url: 'https://example.com/contract.pdf' },
+  question: 'What is the termination clause?',
+});
+```
+
+Full API in [docs](https://cencori.com/docs/ai/endpoints/documents). See the [Contract Analyzer tutorial](https://cencori.com/docs/guides/build-a-contract-analyzer) for an end-to-end example.
+
 ### Image Generation
 
 Generate images from text prompts using multiple providers:

package/dist/index.d.mts

@@ -4,6 +4,8 @@ import { AINamespace } from './ai/index.mjs';
 export { StreamChunk } from './ai/index.mjs';
 import { VisionNamespace } from './vision/index.mjs';
 export { VisionClassification, VisionClassifyResult, VisionCost, VisionDescribeResult, VisionImage, VisionOcrResult, VisionProvider, VisionRequest, VisionResult, VisionStreamChunk, VisionTask, VisionUsage } from './vision/index.mjs';
+import { VoiceNamespace } from './voice/index.mjs';
+export { AudioFormat, AudioInput, STTProvider, SpeakRequest, SpeakResult, TTSProvider, TranscribeRequest, TranscribeResult, TranscriptFormat, TranscriptSegment, TranscriptWord, VoiceModelInfo } from './voice/index.mjs';
 import { DocumentsNamespace } from './documents/index.mjs';
 export { DocumentCost, DocumentExtractMethod, DocumentExtractResult, DocumentInput, DocumentKind, DocumentQueryRequest, DocumentQueryResult, DocumentRequest, DocumentSummarizeResult, DocumentUsage } from './documents/index.mjs';
 import { ComputeNamespace } from './compute/index.mjs';
@@ -180,6 +182,118 @@ declare class SessionsNamespace {
     }>;
 }
 
+/**
+ * Cencori Chat namespace — OpenAI-compatible chat completions with
+ * gateway-level memory.
+ *
+ * The magic path: one line makes chat stateful.
+ *
+ * @example
+ * ```typescript
+ * const response = await cencori.chat.completions.create({
+ *     model: 'gpt-4o',
+ *     messages: [{ role: 'user', content: 'What did we agree about pricing?' }],
+ *     memory: { userId: session.user.id },
+ * });
+ * console.log(response.choices[0].message.content);
+ * console.log(response.memory?.retrieved); // facts injected into this reply
+ * ```
+ */
+
+interface ChatMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    scope?: 'session' | 'user';
+    retrieve?: boolean;
+    write?: boolean;
+    topK?: number;
+    threshold?: number;
+    namespace?: string;
+    extract?: {
+        model?: string;
+        prompt?: string;
+        minImportance?: number;
+    };
+}
+interface ChatCompletionMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+}
+interface ChatCompletionCreateParams {
+    model: string;
+    messages: ChatCompletionMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    user?: string;
+    memory?: ChatMemoryOptions;
+    tools?: unknown[];
+    tool_choice?: unknown;
+    prompt?: {
+        name: string;
+        variables?: Record<string, string>;
+    };
+}
+interface ChatCompletionResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: string;
+            content: string;
+            tool_calls?: unknown[];
+        };
+        finish_reason: string;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    memory?: {
+        retrieved: Array<{
+            id: string;
+            score: number;
+            content: string;
+        }>;
+        written: Array<{
+            id: string;
+            content: string;
+        }>;
+        write_status: 'pending' | 'disabled';
+    };
+}
+interface ChatCompletionChunk {
+    delta: string;
+    raw: Record<string, unknown>;
+}
+interface ChatCompletionStream extends AsyncIterable<ChatCompletionChunk> {
+    /** Number of memories injected into this request (from X-Cencori-Memory-Retrieved). */
+    memoriesRetrieved: number;
+}
+declare class Completions {
+    private config;
+    constructor(config: Required<CencoriConfig>);
+    private endpoint;
+    private headers;
+    /**
+     * Create a chat completion. Include `memory: { userId }` to retrieve
+     * relevant facts before the model call and persist new ones after it.
+     */
+    create(params: ChatCompletionCreateParams): Promise<ChatCompletionResponse>;
+    /**
+     * Stream a chat completion (SSE). Memory writeback still runs after the
+     * stream completes; `memoriesRetrieved` reports the injected count.
+     */
+    stream(params: ChatCompletionCreateParams): Promise<ChatCompletionStream>;
+}
+declare class ChatNamespace {
+    readonly completions: Completions;
+    constructor(config: Required<CencoriConfig>);
+}
+
 /**
  * Cencori - Unified AI Infrastructure SDK
  *
@@ -216,6 +330,18 @@ declare class Cencori {
      * await cencori.ai.chat({ model: 'gpt-4o', messages: [...] });
      */
     readonly ai: AINamespace;
+    /**
+     * Chat - OpenAI-compatible chat completions with gateway memory.
+     * One line makes chat stateful.
+     *
+     * @example
+     * const response = await cencori.chat.completions.create({
+     *   model: 'gpt-4o',
+     *   messages: [{ role: 'user', content: 'What did we agree about pricing?' }],
+     *   memory: { userId: session.user.id },
+     * });
+     */
+    readonly chat: ChatNamespace;
     /**
      * Vision - Analyze, describe, OCR, and classify images
      *
@@ -231,6 +357,28 @@ declare class Cencori {
      * });
      */
     readonly vision: VisionNamespace;
+    /**
+     * Voice - Text-to-speech and speech-to-text across providers
+     *
+     * @example
+     * const { audio } = await cencori.voice.speak({
+     *   input: 'Hello from Cencori.',
+     *   model: 'aura-asteria-en', // Deepgram; provider inferred from model
+     * });
+     *
+     * @example
+     * const { text } = await cencori.voice.transcribe({
+     *   audio: fileBytes,
+     *   model: 'nova-3',
+     * });
+     *
+     * @example
+     * const { segments } = await cencori.voice.diarize({
+     *   audio: fileBytes,
+     *   model: 'assemblyai-universal',
+     * });
+     */
+    readonly voice: VoiceNamespace;
     /**
      * Documents - Extract text from PDFs and images, summarize, and query
      *
@@ -391,4 +539,4 @@ declare class SafetyError extends CencoriError {
  */
 declare function fetchWithRetry(url: string, options: RequestInit, maxRetries?: number): Promise<Response>;
 
-export { AINamespace, type Agent, type AgentConfig, type AgentKey, type AgentListItem, AgentsNamespace, AuthenticationError, Cencori, CencoriConfig, CencoriError, ComputeNamespace, type CreateAgentKeyParams, type CreateAgentParams, type CreateSessionParams, DocumentsNamespace, MemoryClient, type PaginatedResponse, RateLimitError, RequestOptions, SafetyError, type Session, type SessionEvent, type SessionListParams, SessionsNamespace, StorageNamespace, TelemetryClient, type TurnParams, type UpdateAgentParams, VisionNamespace, WorkflowNamespace, Cencori as default, fetchWithRetry };
+export { AINamespace, type Agent, type AgentConfig, type AgentKey, type AgentListItem, AgentsNamespace, AuthenticationError, Cencori, CencoriConfig, CencoriError, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatCompletionResponse, type ChatCompletionStream, type ChatMemoryOptions, ChatNamespace, ComputeNamespace, type CreateAgentKeyParams, type CreateAgentParams, type CreateSessionParams, DocumentsNamespace, MemoryClient, type PaginatedResponse, RateLimitError, RequestOptions, SafetyError, type Session, type SessionEvent, type SessionListParams, SessionsNamespace, StorageNamespace, TelemetryClient, type TurnParams, type UpdateAgentParams, VisionNamespace, VoiceNamespace, WorkflowNamespace, Cencori as default, fetchWithRetry };

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import { AINamespace } from './ai/index.js';
 export { StreamChunk } from './ai/index.js';
 import { VisionNamespace } from './vision/index.js';
 export { VisionClassification, VisionClassifyResult, VisionCost, VisionDescribeResult, VisionImage, VisionOcrResult, VisionProvider, VisionRequest, VisionResult, VisionStreamChunk, VisionTask, VisionUsage } from './vision/index.js';
+import { VoiceNamespace } from './voice/index.js';
+export { AudioFormat, AudioInput, STTProvider, SpeakRequest, SpeakResult, TTSProvider, TranscribeRequest, TranscribeResult, TranscriptFormat, TranscriptSegment, TranscriptWord, VoiceModelInfo } from './voice/index.js';
 import { DocumentsNamespace } from './documents/index.js';
 export { DocumentCost, DocumentExtractMethod, DocumentExtractResult, DocumentInput, DocumentKind, DocumentQueryRequest, DocumentQueryResult, DocumentRequest, DocumentSummarizeResult, DocumentUsage } from './documents/index.js';
 import { ComputeNamespace } from './compute/index.js';
@@ -180,6 +182,118 @@ declare class SessionsNamespace {
     }>;
 }
 
+/**
+ * Cencori Chat namespace — OpenAI-compatible chat completions with
+ * gateway-level memory.
+ *
+ * The magic path: one line makes chat stateful.
+ *
+ * @example
+ * ```typescript
+ * const response = await cencori.chat.completions.create({
+ *     model: 'gpt-4o',
+ *     messages: [{ role: 'user', content: 'What did we agree about pricing?' }],
+ *     memory: { userId: session.user.id },
+ * });
+ * console.log(response.choices[0].message.content);
+ * console.log(response.memory?.retrieved); // facts injected into this reply
+ * ```
+ */
+
+interface ChatMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    scope?: 'session' | 'user';
+    retrieve?: boolean;
+    write?: boolean;
+    topK?: number;
+    threshold?: number;
+    namespace?: string;
+    extract?: {
+        model?: string;
+        prompt?: string;
+        minImportance?: number;
+    };
+}
+interface ChatCompletionMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+}
+interface ChatCompletionCreateParams {
+    model: string;
+    messages: ChatCompletionMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    user?: string;
+    memory?: ChatMemoryOptions;
+    tools?: unknown[];
+    tool_choice?: unknown;
+    prompt?: {
+        name: string;
+        variables?: Record<string, string>;
+    };
+}
+interface ChatCompletionResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: string;
+            content: string;
+            tool_calls?: unknown[];
+        };
+        finish_reason: string;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    memory?: {
+        retrieved: Array<{
+            id: string;
+            score: number;
+            content: string;
+        }>;
+        written: Array<{
+            id: string;
+            content: string;
+        }>;
+        write_status: 'pending' | 'disabled';
+    };
+}
+interface ChatCompletionChunk {
+    delta: string;
+    raw: Record<string, unknown>;
+}
+interface ChatCompletionStream extends AsyncIterable<ChatCompletionChunk> {
+    /** Number of memories injected into this request (from X-Cencori-Memory-Retrieved). */
+    memoriesRetrieved: number;
+}
+declare class Completions {
+    private config;
+    constructor(config: Required<CencoriConfig>);
+    private endpoint;
+    private headers;
+    /**
+     * Create a chat completion. Include `memory: { userId }` to retrieve
+     * relevant facts before the model call and persist new ones after it.
+     */
+    create(params: ChatCompletionCreateParams): Promise<ChatCompletionResponse>;
+    /**
+     * Stream a chat completion (SSE). Memory writeback still runs after the
+     * stream completes; `memoriesRetrieved` reports the injected count.
+     */
+    stream(params: ChatCompletionCreateParams): Promise<ChatCompletionStream>;
+}
+declare class ChatNamespace {
+    readonly completions: Completions;
+    constructor(config: Required<CencoriConfig>);
+}
+
 /**
  * Cencori - Unified AI Infrastructure SDK
  *
@@ -216,6 +330,18 @@ declare class Cencori {
      * await cencori.ai.chat({ model: 'gpt-4o', messages: [...] });
      */
     readonly ai: AINamespace;
+    /**
+     * Chat - OpenAI-compatible chat completions with gateway memory.
+     * One line makes chat stateful.
+     *
+     * @example
+     * const response = await cencori.chat.completions.create({
+     *   model: 'gpt-4o',
+     *   messages: [{ role: 'user', content: 'What did we agree about pricing?' }],
+     *   memory: { userId: session.user.id },
+     * });
+     */
+    readonly chat: ChatNamespace;
     /**
      * Vision - Analyze, describe, OCR, and classify images
      *
@@ -231,6 +357,28 @@ declare class Cencori {
      * });
      */
     readonly vision: VisionNamespace;
+    /**
+     * Voice - Text-to-speech and speech-to-text across providers
+     *
+     * @example
+     * const { audio } = await cencori.voice.speak({
+     *   input: 'Hello from Cencori.',
+     *   model: 'aura-asteria-en', // Deepgram; provider inferred from model
+     * });
+     *
+     * @example
+     * const { text } = await cencori.voice.transcribe({
+     *   audio: fileBytes,
+     *   model: 'nova-3',
+     * });
+     *
+     * @example
+     * const { segments } = await cencori.voice.diarize({
+     *   audio: fileBytes,
+     *   model: 'assemblyai-universal',
+     * });
+     */
+    readonly voice: VoiceNamespace;
     /**
      * Documents - Extract text from PDFs and images, summarize, and query
      *
@@ -391,4 +539,4 @@ declare class SafetyError extends CencoriError {
  */
 declare function fetchWithRetry(url: string, options: RequestInit, maxRetries?: number): Promise<Response>;
 
-export { AINamespace, type Agent, type AgentConfig, type AgentKey, type AgentListItem, AgentsNamespace, AuthenticationError, Cencori, CencoriConfig, CencoriError, ComputeNamespace, type CreateAgentKeyParams, type CreateAgentParams, type CreateSessionParams, DocumentsNamespace, MemoryClient, type PaginatedResponse, RateLimitError, RequestOptions, SafetyError, type Session, type SessionEvent, type SessionListParams, SessionsNamespace, StorageNamespace, TelemetryClient, type TurnParams, type UpdateAgentParams, VisionNamespace, WorkflowNamespace, Cencori as default, fetchWithRetry };
+export { AINamespace, type Agent, type AgentConfig, type AgentKey, type AgentListItem, AgentsNamespace, AuthenticationError, Cencori, CencoriConfig, CencoriError, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatCompletionResponse, type ChatCompletionStream, type ChatMemoryOptions, ChatNamespace, ComputeNamespace, type CreateAgentKeyParams, type CreateAgentParams, type CreateSessionParams, DocumentsNamespace, MemoryClient, type PaginatedResponse, RateLimitError, RequestOptions, SafetyError, type Session, type SessionEvent, type SessionListParams, SessionsNamespace, StorageNamespace, TelemetryClient, type TurnParams, type UpdateAgentParams, VisionNamespace, VoiceNamespace, WorkflowNamespace, Cencori as default, fetchWithRetry };