cencori 1.3.0 → 1.4.0

package/README.md

@@ -130,6 +130,46 @@ const response = await cencori.ai.embeddings({
 console.log(response.embeddings[0]); // [0.1, 0.2, ...]
 ```
 
+### Vision (Image Understanding)
+
+Analyze, describe, OCR, and classify images. Routes across OpenAI, Anthropic, and Google vision-capable models.
+
+```typescript
+// General analysis with a custom prompt
+const result = await cencori.vision.analyze({
+  image: { url: 'https://example.com/photo.jpg' },
+  prompt: 'What breed of dog is this?'
+});
+
+// OCR from a local file
+import fs from 'node:fs';
+const buf = fs.readFileSync('receipt.png');
+const { text } = await cencori.vision.ocr({
+  image: { base64: buf.toString('base64'), mimeType: 'image/png' }
+});
+
+// Structured classification
+const { classification } = await cencori.vision.classify({
+  image: { url: 'https://example.com/product.jpg' }
+});
+// classification: { primary_category, tags, objects, safe_for_work, ... }
+```
+
+Drop-in React uploader for your own product (`cencori/react`):
+
+```tsx
+import { VisionUploader } from 'cencori/react';
+
+<VisionUploader
+  endpoint="https://cencori.com/api/ai/vision"
+  apiKey={process.env.NEXT_PUBLIC_CENCORI_KEY}
+  task="describe"
+  onResult={(r) => console.log(r)}
+/>
+```
+
+Full API in [docs](https://cencori.com/docs/ai/endpoints/vision).
+
 ### Image Generation
 
 Generate images from text prompts using multiple providers:

package/dist/documents/index.d.mts

@@ -0,0 +1,94 @@
+import { C as CencoriConfig } from '../types-kh1whvNH.mjs';
+
+/**
+ * Documents API — extract text from PDFs and images, summarize, and query.
+ *
+ * @example
+ *   const { text, pageCount } = await cencori.documents.extract({
+ *       document: { url: 'https://example.com/contract.pdf' },
+ *   });
+ *
+ * @example
+ *   const { summary } = await cencori.documents.summarize({
+ *       document: { base64, mimeType: 'application/pdf' },
+ *   });
+ *
+ * @example
+ *   const { answer } = await cencori.documents.query({
+ *       document: { url: 'https://example.com/report.pdf' },
+ *       question: 'What is the total revenue for Q3?',
+ *   });
+ */
+
+type DocumentExtractMethod = 'pdf_text' | 'vision_ocr';
+type DocumentKind = 'pdf' | 'image';
+interface DocumentInput {
+    url?: string;
+    base64?: string;
+    mimeType?: string;
+    filename?: string;
+}
+interface DocumentRequest {
+    document: DocumentInput;
+    prompt?: string;
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+interface DocumentQueryRequest extends DocumentRequest {
+    question: string;
+}
+interface DocumentUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+interface DocumentCost {
+    providerCostUsd: number;
+    cencoriChargeUsd: number;
+    markupPercentage: number;
+}
+interface DocumentExtractResult {
+    text: string;
+    pageCount: number;
+    kind: DocumentKind;
+    method: DocumentExtractMethod;
+    model?: string;
+    provider?: string;
+    metadata?: Record<string, unknown>;
+    usage?: DocumentUsage;
+    cost?: DocumentCost;
+}
+interface DocumentSummarizeResult {
+    summary: string;
+    text: string;
+    pageCount: number;
+    model: string;
+    provider: string;
+    extractMethod: DocumentExtractMethod;
+    usage: DocumentUsage;
+    cost: DocumentCost;
+}
+interface DocumentQueryResult {
+    answer: string;
+    question: string;
+    pageCount: number;
+    model: string;
+    provider: string;
+    extractMethod: DocumentExtractMethod;
+    usage: DocumentUsage;
+    cost: DocumentCost;
+}
+declare class DocumentsNamespace {
+    private config;
+    constructor(config: Required<CencoriConfig>);
+    /** Extract text from a PDF (native, no LLM) or image (via Vision OCR). */
+    extract(request: DocumentRequest): Promise<DocumentExtractResult>;
+    /** Extract then summarize the document with a chat model. */
+    summarize(request: DocumentRequest): Promise<DocumentSummarizeResult>;
+    /** Extract then answer a question about the document. */
+    query(request: DocumentQueryRequest): Promise<DocumentQueryResult>;
+    private post;
+}
+
+export { type DocumentCost, type DocumentExtractMethod, type DocumentExtractResult, type DocumentInput, type DocumentKind, type DocumentQueryRequest, type DocumentQueryResult, type DocumentRequest, type DocumentSummarizeResult, type DocumentUsage, DocumentsNamespace };

package/dist/documents/index.d.ts

@@ -0,0 +1,94 @@
+import { C as CencoriConfig } from '../types-kh1whvNH.js';
+
+/**
+ * Documents API — extract text from PDFs and images, summarize, and query.
+ *
+ * @example
+ *   const { text, pageCount } = await cencori.documents.extract({
+ *       document: { url: 'https://example.com/contract.pdf' },
+ *   });
+ *
+ * @example
+ *   const { summary } = await cencori.documents.summarize({
+ *       document: { base64, mimeType: 'application/pdf' },
+ *   });
+ *
+ * @example
+ *   const { answer } = await cencori.documents.query({
+ *       document: { url: 'https://example.com/report.pdf' },
+ *       question: 'What is the total revenue for Q3?',
+ *   });
+ */
+
+type DocumentExtractMethod = 'pdf_text' | 'vision_ocr';
+type DocumentKind = 'pdf' | 'image';
+interface DocumentInput {
+    url?: string;
+    base64?: string;
+    mimeType?: string;
+    filename?: string;
+}
+interface DocumentRequest {
+    document: DocumentInput;
+    prompt?: string;
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+interface DocumentQueryRequest extends DocumentRequest {
+    question: string;
+}
+interface DocumentUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+interface DocumentCost {
+    providerCostUsd: number;
+    cencoriChargeUsd: number;
+    markupPercentage: number;
+}
+interface DocumentExtractResult {
+    text: string;
+    pageCount: number;
+    kind: DocumentKind;
+    method: DocumentExtractMethod;
+    model?: string;
+    provider?: string;
+    metadata?: Record<string, unknown>;
+    usage?: DocumentUsage;
+    cost?: DocumentCost;
+}
+interface DocumentSummarizeResult {
+    summary: string;
+    text: string;
+    pageCount: number;
+    model: string;
+    provider: string;
+    extractMethod: DocumentExtractMethod;
+    usage: DocumentUsage;
+    cost: DocumentCost;
+}
+interface DocumentQueryResult {
+    answer: string;
+    question: string;
+    pageCount: number;
+    model: string;
+    provider: string;
+    extractMethod: DocumentExtractMethod;
+    usage: DocumentUsage;
+    cost: DocumentCost;
+}
+declare class DocumentsNamespace {
+    private config;
+    constructor(config: Required<CencoriConfig>);
+    /** Extract text from a PDF (native, no LLM) or image (via Vision OCR). */
+    extract(request: DocumentRequest): Promise<DocumentExtractResult>;
+    /** Extract then summarize the document with a chat model. */
+    summarize(request: DocumentRequest): Promise<DocumentSummarizeResult>;
+    /** Extract then answer a question about the document. */
+    query(request: DocumentQueryRequest): Promise<DocumentQueryResult>;
+    private post;
+}
+
+export { type DocumentCost, type DocumentExtractMethod, type DocumentExtractResult, type DocumentInput, type DocumentKind, type DocumentQueryRequest, type DocumentQueryResult, type DocumentRequest, type DocumentSummarizeResult, type DocumentUsage, DocumentsNamespace };

package/dist/documents/index.js

@@ -0,0 +1,88 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/documents/index.ts
+var documents_exports = {};
+__export(documents_exports, {
+  DocumentsNamespace: () => DocumentsNamespace
+});
+module.exports = __toCommonJS(documents_exports);
+function toBody(request, extra = {}) {
+  const body = {
+    prompt: request.prompt,
+    model: request.model,
+    max_tokens: request.maxTokens,
+    temperature: request.temperature,
+    ...extra
+  };
+  if (request.document.url) {
+    body.document_url = request.document.url;
+  } else if (request.document.base64) {
+    body.document_base64 = request.document.base64;
+    body.mime_type = request.document.mimeType;
+    body.filename = request.document.filename;
+  } else {
+    throw new Error("documents request requires document.url or document.base64");
+  }
+  return body;
+}
+var DocumentsNamespace = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Extract text from a PDF (native, no LLM) or image (via Vision OCR). */
+  async extract(request) {
+    return this.post("/api/ai/documents/extract", toBody(request));
+  }
+  /** Extract then summarize the document with a chat model. */
+  async summarize(request) {
+    return this.post("/api/ai/documents/summarize", toBody(request));
+  }
+  /** Extract then answer a question about the document. */
+  async query(request) {
+    if (!request.question) throw new Error("documents.query requires a `question`");
+    return this.post("/api/ai/documents/query", toBody(request, { question: request.question }));
+  }
+  async post(path, body) {
+    const response = await fetch(`${this.config.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "CENCORI_API_KEY": this.config.apiKey,
+        "Content-Type": "application/json",
+        ...this.config.headers
+      },
+      body: JSON.stringify(body)
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      const message = data && typeof data === "object" && "message" in data && typeof data.message === "string" ? data.message : `Documents request failed with status ${response.status}`;
+      const code = data && typeof data === "object" && "error" in data && typeof data.error === "string" ? data.error : "request_failed";
+      const err = new Error(message);
+      err.code = code;
+      err.details = data;
+      throw err;
+    }
+    return data;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DocumentsNamespace
+});
+//# sourceMappingURL=index.js.map

package/dist/documents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/documents/index.ts"],"sourcesContent":["/**\n * Documents API — extract text from PDFs and images, summarize, and query.\n *\n * @example\n *   const { text, pageCount } = await cencori.documents.extract({\n *       document: { url: 'https://example.com/contract.pdf' },\n *   });\n *\n * @example\n *   const { summary } = await cencori.documents.summarize({\n *       document: { base64, mimeType: 'application/pdf' },\n *   });\n *\n * @example\n *   const { answer } = await cencori.documents.query({\n *       document: { url: 'https://example.com/report.pdf' },\n *       question: 'What is the total revenue for Q3?',\n *   });\n */\n\nimport type { CencoriConfig } from '../types';\n\nexport type DocumentExtractMethod = 'pdf_text' | 'vision_ocr';\nexport type DocumentKind = 'pdf' | 'image';\n\nexport interface DocumentInput {\n    url?: string;\n    base64?: string;\n    mimeType?: string;\n    filename?: string;\n}\n\nexport interface DocumentRequest {\n    document: DocumentInput;\n    prompt?: string;\n    model?: string;\n    maxTokens?: number;\n    temperature?: number;\n}\n\nexport interface DocumentQueryRequest extends DocumentRequest {\n    question: string;\n}\n\nexport interface DocumentUsage {\n    promptTokens: number;\n    completionTokens: number;\n    totalTokens: number;\n}\n\nexport interface DocumentCost {\n    providerCostUsd: number;\n    cencoriChargeUsd: number;\n    markupPercentage: number;\n}\n\nexport interface DocumentExtractResult {\n    text: string;\n    pageCount: number;\n    kind: DocumentKind;\n    method: DocumentExtractMethod;\n    model?: string;\n    provider?: string;\n    metadata?: Record<string, unknown>;\n    usage?: DocumentUsage;\n    cost?: DocumentCost;\n}\n\nexport interface DocumentSummarizeResult {\n    summary: string;\n    text: string;\n    pageCount: number;\n    model: string;\n    provider: string;\n    extractMethod: DocumentExtractMethod;\n    usage: DocumentUsage;\n    cost: DocumentCost;\n}\n\nexport interface DocumentQueryResult {\n    answer: string;\n    question: string;\n    pageCount: number;\n    model: string;\n    provider: string;\n    extractMethod: DocumentExtractMethod;\n    usage: DocumentUsage;\n    cost: DocumentCost;\n}\n\ninterface JsonBody {\n    document_url?: string;\n    document_base64?: string;\n    mime_type?: string;\n    filename?: string;\n    prompt?: string;\n    model?: string;\n    max_tokens?: number;\n    temperature?: number;\n    question?: string;\n}\n\nfunction toBody(request: DocumentRequest, extra: Partial<JsonBody> = {}): JsonBody {\n    const body: JsonBody = {\n        prompt: request.prompt,\n        model: request.model,\n        max_tokens: request.maxTokens,\n        temperature: request.temperature,\n        ...extra,\n    };\n    if (request.document.url) {\n        body.document_url = request.document.url;\n    } else if (request.document.base64) {\n        body.document_base64 = request.document.base64;\n        body.mime_type = request.document.mimeType;\n        body.filename = request.document.filename;\n    } else {\n        throw new Error('documents request requires document.url or document.base64');\n    }\n    return body;\n}\n\nexport class DocumentsNamespace {\n    private config: Required<CencoriConfig>;\n\n    constructor(config: Required<CencoriConfig>) {\n        this.config = config;\n    }\n\n    /** Extract text from a PDF (native, no LLM) or image (via Vision OCR). */\n    async extract(request: DocumentRequest): Promise<DocumentExtractResult> {\n        return this.post<DocumentExtractResult>('/api/ai/documents/extract', toBody(request));\n    }\n\n    /** Extract then summarize the document with a chat model. */\n    async summarize(request: DocumentRequest): Promise<DocumentSummarizeResult> {\n        return this.post<DocumentSummarizeResult>('/api/ai/documents/summarize', toBody(request));\n    }\n\n    /** Extract then answer a question about the document. */\n    async query(request: DocumentQueryRequest): Promise<DocumentQueryResult> {\n        if (!request.question) throw new Error('documents.query requires a `question`');\n        return this.post<DocumentQueryResult>('/api/ai/documents/query', toBody(request, { question: request.question }));\n    }\n\n    private async post<T>(path: string, body: JsonBody): Promise<T> {\n        const response = await fetch(`${this.config.baseUrl}${path}`, {\n            method: 'POST',\n            headers: {\n                'CENCORI_API_KEY': this.config.apiKey,\n                'Content-Type': 'application/json',\n                ...this.config.headers,\n            },\n            body: JSON.stringify(body),\n        });\n        const data = await response.json();\n        if (!response.ok) {\n            const message =\n                (data && typeof data === 'object' && 'message' in data && typeof data.message === 'string')\n                    ? data.message\n                    : `Documents request failed with status ${response.status}`;\n            const code =\n                (data && typeof data === 'object' && 'error' in data && typeof data.error === 'string')\n                    ? data.error\n                    : 'request_failed';\n            const err = new Error(message) as Error & { code?: string; details?: unknown };\n            err.code = code;\n            err.details = data;\n            throw err;\n        }\n        return data as T;\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAsGA,SAAS,OAAO,SAA0B,QAA2B,CAAC,GAAa;AAC/E,QAAM,OAAiB;AAAA,IACnB,QAAQ,QAAQ;AAAA,IAChB,OAAO,QAAQ;AAAA,IACf,YAAY,QAAQ;AAAA,IACpB,aAAa,QAAQ;AAAA,IACrB,GAAG;AAAA,EACP;AACA,MAAI,QAAQ,SAAS,KAAK;AACtB,SAAK,eAAe,QAAQ,SAAS;AAAA,EACzC,WAAW,QAAQ,SAAS,QAAQ;AAChC,SAAK,kBAAkB,QAAQ,SAAS;AACxC,SAAK,YAAY,QAAQ,SAAS;AAClC,SAAK,WAAW,QAAQ,SAAS;AAAA,EACrC,OAAO;AACH,UAAM,IAAI,MAAM,4DAA4D;AAAA,EAChF;AACA,SAAO;AACX;AAEO,IAAM,qBAAN,MAAyB;AAAA,EAG5B,YAAY,QAAiC;AACzC,SAAK,SAAS;AAAA,EAClB;AAAA;AAAA,EAGA,MAAM,QAAQ,SAA0D;AACpE,WAAO,KAAK,KAA4B,6BAA6B,OAAO,OAAO,CAAC;AAAA,EACxF;AAAA;AAAA,EAGA,MAAM,UAAU,SAA4D;AACxE,WAAO,KAAK,KAA8B,+BAA+B,OAAO,OAAO,CAAC;AAAA,EAC5F;AAAA;AAAA,EAGA,MAAM,MAAM,SAA6D;AACrE,QAAI,CAAC,QAAQ,SAAU,OAAM,IAAI,MAAM,uCAAuC;AAC9E,WAAO,KAAK,KAA0B,2BAA2B,OAAO,SAAS,EAAE,UAAU,QAAQ,SAAS,CAAC,CAAC;AAAA,EACpH;AAAA,EAEA,MAAc,KAAQ,MAAc,MAA4B;AAC5D,UAAM,WAAW,MAAM,MAAM,GAAG,KAAK,OAAO,OAAO,GAAG,IAAI,IAAI;AAAA,MAC1D,QAAQ;AAAA,MACR,SAAS;AAAA,QACL,mBAAmB,KAAK,OAAO;AAAA,QAC/B,gBAAgB;AAAA,QAChB,GAAG,KAAK,OAAO;AAAA,MACnB;AAAA,MACA,MAAM,KAAK,UAAU,IAAI;AAAA,IAC7B,CAAC;AACD,UAAM,OAAO,MAAM,SAAS,KAAK;AACjC,QAAI,CAAC,SAAS,IAAI;AACd,YAAM,UACD,QAAQ,OAAO,SAAS,YAAY,aAAa,QAAQ,OAAO,KAAK,YAAY,WAC5E,KAAK,UACL,wCAAwC,SAAS,MAAM;AACjE,YAAM,OACD,QAAQ,OAAO,SAAS,YAAY,WAAW,QAAQ,OAAO,KAAK,UAAU,WACxE,KAAK,QACL;AACV,YAAM,MAAM,IAAI,MAAM,OAAO;AAC7B,UAAI,OAAO;AACX,UAAI,UAAU;AACd,YAAM;AAAA,IACV;AACA,WAAO;AAAA,EACX;AACJ;","names":[]}

package/dist/documents/index.mjs

@@ -0,0 +1,63 @@
+// src/documents/index.ts
+function toBody(request, extra = {}) {
+  const body = {
+    prompt: request.prompt,
+    model: request.model,
+    max_tokens: request.maxTokens,
+    temperature: request.temperature,
+    ...extra
+  };
+  if (request.document.url) {
+    body.document_url = request.document.url;
+  } else if (request.document.base64) {
+    body.document_base64 = request.document.base64;
+    body.mime_type = request.document.mimeType;
+    body.filename = request.document.filename;
+  } else {
+    throw new Error("documents request requires document.url or document.base64");
+  }
+  return body;
+}
+var DocumentsNamespace = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Extract text from a PDF (native, no LLM) or image (via Vision OCR). */
+  async extract(request) {
+    return this.post("/api/ai/documents/extract", toBody(request));
+  }
+  /** Extract then summarize the document with a chat model. */
+  async summarize(request) {
+    return this.post("/api/ai/documents/summarize", toBody(request));
+  }
+  /** Extract then answer a question about the document. */
+  async query(request) {
+    if (!request.question) throw new Error("documents.query requires a `question`");
+    return this.post("/api/ai/documents/query", toBody(request, { question: request.question }));
+  }
+  async post(path, body) {
+    const response = await fetch(`${this.config.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "CENCORI_API_KEY": this.config.apiKey,
+        "Content-Type": "application/json",
+        ...this.config.headers
+      },
+      body: JSON.stringify(body)
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      const message = data && typeof data === "object" && "message" in data && typeof data.message === "string" ? data.message : `Documents request failed with status ${response.status}`;
+      const code = data && typeof data === "object" && "error" in data && typeof data.error === "string" ? data.error : "request_failed";
+      const err = new Error(message);
+      err.code = code;
+      err.details = data;
+      throw err;
+    }
+    return data;
+  }
+};
+export {
+  DocumentsNamespace
+};
+//# sourceMappingURL=index.mjs.map

package/dist/documents/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/documents/index.ts"],"sourcesContent":["/**\n * Documents API — extract text from PDFs and images, summarize, and query.\n *\n * @example\n *   const { text, pageCount } = await cencori.documents.extract({\n *       document: { url: 'https://example.com/contract.pdf' },\n *   });\n *\n * @example\n *   const { summary } = await cencori.documents.summarize({\n *       document: { base64, mimeType: 'application/pdf' },\n *   });\n *\n * @example\n *   const { answer } = await cencori.documents.query({\n *       document: { url: 'https://example.com/report.pdf' },\n *       question: 'What is the total revenue for Q3?',\n *   });\n */\n\nimport type { CencoriConfig } from '../types';\n\nexport type DocumentExtractMethod = 'pdf_text' | 'vision_ocr';\nexport type DocumentKind = 'pdf' | 'image';\n\nexport interface DocumentInput {\n    url?: string;\n    base64?: string;\n    mimeType?: string;\n    filename?: string;\n}\n\nexport interface DocumentRequest {\n    document: DocumentInput;\n    prompt?: string;\n    model?: string;\n    maxTokens?: number;\n    temperature?: number;\n}\n\nexport interface DocumentQueryRequest extends DocumentRequest {\n    question: string;\n}\n\nexport interface DocumentUsage {\n    promptTokens: number;\n    completionTokens: number;\n    totalTokens: number;\n}\n\nexport interface DocumentCost {\n    providerCostUsd: number;\n    cencoriChargeUsd: number;\n    markupPercentage: number;\n}\n\nexport interface DocumentExtractResult {\n    text: string;\n    pageCount: number;\n    kind: DocumentKind;\n    method: DocumentExtractMethod;\n    model?: string;\n    provider?: string;\n    metadata?: Record<string, unknown>;\n    usage?: DocumentUsage;\n    cost?: DocumentCost;\n}\n\nexport interface DocumentSummarizeResult {\n    summary: string;\n    text: string;\n    pageCount: number;\n    model: string;\n    provider: string;\n    extractMethod: DocumentExtractMethod;\n    usage: DocumentUsage;\n    cost: DocumentCost;\n}\n\nexport interface DocumentQueryResult {\n    answer: string;\n    question: string;\n    pageCount: number;\n    model: string;\n    provider: string;\n    extractMethod: DocumentExtractMethod;\n    usage: DocumentUsage;\n    cost: DocumentCost;\n}\n\ninterface JsonBody {\n    document_url?: string;\n    document_base64?: string;\n    mime_type?: string;\n    filename?: string;\n    prompt?: string;\n    model?: string;\n    max_tokens?: number;\n    temperature?: number;\n    question?: string;\n}\n\nfunction toBody(request: DocumentRequest, extra: Partial<JsonBody> = {}): JsonBody {\n    const body: JsonBody = {\n        prompt: request.prompt,\n        model: request.model,\n        max_tokens: request.maxTokens,\n        temperature: request.temperature,\n        ...extra,\n    };\n    if (request.document.url) {\n        body.document_url = request.document.url;\n    } else if (request.document.base64) {\n        body.document_base64 = request.document.base64;\n        body.mime_type = request.document.mimeType;\n        body.filename = request.document.filename;\n    } else {\n        throw new Error('documents request requires document.url or document.base64');\n    }\n    return body;\n}\n\nexport class DocumentsNamespace {\n    private config: Required<CencoriConfig>;\n\n    constructor(config: Required<CencoriConfig>) {\n        this.config = config;\n    }\n\n    /** Extract text from a PDF (native, no LLM) or image (via Vision OCR). */\n    async extract(request: DocumentRequest): Promise<DocumentExtractResult> {\n        return this.post<DocumentExtractResult>('/api/ai/documents/extract', toBody(request));\n    }\n\n    /** Extract then summarize the document with a chat model. */\n    async summarize(request: DocumentRequest): Promise<DocumentSummarizeResult> {\n        return this.post<DocumentSummarizeResult>('/api/ai/documents/summarize', toBody(request));\n    }\n\n    /** Extract then answer a question about the document. */\n    async query(request: DocumentQueryRequest): Promise<DocumentQueryResult> {\n        if (!request.question) throw new Error('documents.query requires a `question`');\n        return this.post<DocumentQueryResult>('/api/ai/documents/query', toBody(request, { question: request.question }));\n    }\n\n    private async post<T>(path: string, body: JsonBody): Promise<T> {\n        const response = await fetch(`${this.config.baseUrl}${path}`, {\n            method: 'POST',\n            headers: {\n                'CENCORI_API_KEY': this.config.apiKey,\n                'Content-Type': 'application/json',\n                ...this.config.headers,\n            },\n            body: JSON.stringify(body),\n        });\n        const data = await response.json();\n        if (!response.ok) {\n            const message =\n                (data && typeof data === 'object' && 'message' in data && typeof data.message === 'string')\n                    ? data.message\n                    : `Documents request failed with status ${response.status}`;\n            const code =\n                (data && typeof data === 'object' && 'error' in data && typeof data.error === 'string')\n                    ? data.error\n                    : 'request_failed';\n            const err = new Error(message) as Error & { code?: string; details?: unknown };\n            err.code = code;\n            err.details = data;\n            throw err;\n        }\n        return data as T;\n    }\n}\n"],"mappings":";AAsGA,SAAS,OAAO,SAA0B,QAA2B,CAAC,GAAa;AAC/E,QAAM,OAAiB;AAAA,IACnB,QAAQ,QAAQ;AAAA,IAChB,OAAO,QAAQ;AAAA,IACf,YAAY,QAAQ;AAAA,IACpB,aAAa,QAAQ;AAAA,IACrB,GAAG;AAAA,EACP;AACA,MAAI,QAAQ,SAAS,KAAK;AACtB,SAAK,eAAe,QAAQ,SAAS;AAAA,EACzC,WAAW,QAAQ,SAAS,QAAQ;AAChC,SAAK,kBAAkB,QAAQ,SAAS;AACxC,SAAK,YAAY,QAAQ,SAAS;AAClC,SAAK,WAAW,QAAQ,SAAS;AAAA,EACrC,OAAO;AACH,UAAM,IAAI,MAAM,4DAA4D;AAAA,EAChF;AACA,SAAO;AACX;AAEO,IAAM,qBAAN,MAAyB;AAAA,EAG5B,YAAY,QAAiC;AACzC,SAAK,SAAS;AAAA,EAClB;AAAA;AAAA,EAGA,MAAM,QAAQ,SAA0D;AACpE,WAAO,KAAK,KAA4B,6BAA6B,OAAO,OAAO,CAAC;AAAA,EACxF;AAAA;AAAA,EAGA,MAAM,UAAU,SAA4D;AACxE,WAAO,KAAK,KAA8B,+BAA+B,OAAO,OAAO,CAAC;AAAA,EAC5F;AAAA;AAAA,EAGA,MAAM,MAAM,SAA6D;AACrE,QAAI,CAAC,QAAQ,SAAU,OAAM,IAAI,MAAM,uCAAuC;AAC9E,WAAO,KAAK,KAA0B,2BAA2B,OAAO,SAAS,EAAE,UAAU,QAAQ,SAAS,CAAC,CAAC;AAAA,EACpH;AAAA,EAEA,MAAc,KAAQ,MAAc,MAA4B;AAC5D,UAAM,WAAW,MAAM,MAAM,GAAG,KAAK,OAAO,OAAO,GAAG,IAAI,IAAI;AAAA,MAC1D,QAAQ;AAAA,MACR,SAAS;AAAA,QACL,mBAAmB,KAAK,OAAO;AAAA,QAC/B,gBAAgB;AAAA,QAChB,GAAG,KAAK,OAAO;AAAA,MACnB;AAAA,MACA,MAAM,KAAK,UAAU,IAAI;AAAA,IAC7B,CAAC;AACD,UAAM,OAAO,MAAM,SAAS,KAAK;AACjC,QAAI,CAAC,SAAS,IAAI;AACd,YAAM,UACD,QAAQ,OAAO,SAAS,YAAY,aAAa,QAAQ,OAAO,KAAK,YAAY,WAC5E,KAAK,UACL,wCAAwC,SAAS,MAAM;AACjE,YAAM,OACD,QAAQ,OAAO,SAAS,YAAY,WAAW,QAAQ,OAAO,KAAK,UAAU,WACxE,KAAK,QACL;AACV,YAAM,MAAM,IAAI,MAAM,OAAO;AAC7B,UAAI,OAAO;AACX,UAAI,UAAU;AACd,YAAM;AAAA,IACV;AACA,WAAO;AAAA,EACX;AACJ;","names":[]}

package/dist/index.d.mts

@@ -3,7 +3,9 @@ export { j as ChatMessage, a as ChatRequest, b as ChatResponse, o as CodeInterpr
 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, VisionTask, VisionUsage } from './vision/index.mjs';
+export { VisionClassification, VisionClassifyResult, VisionCost, VisionDescribeResult, VisionImage, VisionOcrResult, VisionProvider, VisionRequest, VisionResult, VisionStreamChunk, VisionTask, VisionUsage } from './vision/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';
 import { WorkflowNamespace } from './workflow/index.mjs';
 import { StorageNamespace } from './storage/index.mjs';
@@ -229,6 +231,26 @@ declare class Cencori {
      * });
      */
     readonly vision: VisionNamespace;
+    /**
+     * Documents - Extract text from PDFs and images, summarize, and query
+     *
+     * @example
+     * const { text } = await cencori.documents.extract({
+     *   document: { url: 'https://example.com/contract.pdf' }
+     * });
+     *
+     * @example
+     * const { summary } = await cencori.documents.summarize({
+     *   document: { url: 'https://example.com/report.pdf' }
+     * });
+     *
+     * @example
+     * const { answer } = await cencori.documents.query({
+     *   document: { url },
+     *   question: 'What is the total revenue for Q3?',
+     * });
+     */
+    readonly documents: DocumentsNamespace;
     /**
      * Agents - Create and manage AI agents programmatically.
      *
@@ -369,4 +391,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, 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, 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 };

package/dist/index.d.ts

@@ -3,7 +3,9 @@ export { j as ChatMessage, a as ChatRequest, b as ChatResponse, o as CodeInterpr
 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, VisionTask, VisionUsage } from './vision/index.js';
+export { VisionClassification, VisionClassifyResult, VisionCost, VisionDescribeResult, VisionImage, VisionOcrResult, VisionProvider, VisionRequest, VisionResult, VisionStreamChunk, VisionTask, VisionUsage } from './vision/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';
 import { WorkflowNamespace } from './workflow/index.js';
 import { StorageNamespace } from './storage/index.js';
@@ -229,6 +231,26 @@ declare class Cencori {
      * });
      */
     readonly vision: VisionNamespace;
+    /**
+     * Documents - Extract text from PDFs and images, summarize, and query
+     *
+     * @example
+     * const { text } = await cencori.documents.extract({
+     *   document: { url: 'https://example.com/contract.pdf' }
+     * });
+     *
+     * @example
+     * const { summary } = await cencori.documents.summarize({
+     *   document: { url: 'https://example.com/report.pdf' }
+     * });
+     *
+     * @example
+     * const { answer } = await cencori.documents.query({
+     *   document: { url },
+     *   question: 'What is the total revenue for Q3?',
+     * });
+     */
+    readonly documents: DocumentsNamespace;
     /**
      * Agents - Create and manage AI agents programmatically.
      *
@@ -369,4 +391,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, 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, 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 };

package/dist/index.js

@@ -26,6 +26,7 @@ __export(src_exports, {
   Cencori: () => Cencori,
   CencoriError: () => CencoriError,
   ComputeNamespace: () => ComputeNamespace,
+  DocumentsNamespace: () => DocumentsNamespace,
   MemoryClient: () => MemoryClient,
   RateLimitError: () => RateLimitError,
   SafetyError: () => SafetyError,
@@ -643,6 +644,17 @@ function toBody(request) {
     temperature: request.temperature,
     response_format: request.responseFormat
   };
+  if (request.images && request.images.length > 0) {
+    body.images = request.images.map((img) => {
+      if (img.url) return { url: img.url };
+      if (img.base64) return { base64: img.base64, mime_type: img.mimeType };
+      throw new Error("Each entry in images requires url or base64");
+    });
+    return body;
+  }
+  if (!request.image) {
+    throw new Error("vision request requires `image` or `images[]`");
+  }
   if (request.image.url) {
     body.image_url = request.image.url;
   } else if (request.image.base64) {
@@ -676,6 +688,57 @@ var VisionNamespace = class {
   async classify(request) {
     return this.post("/api/ai/vision/classify", request);
   }
+  /**
+   * Stream a vision analysis. Yields `{ delta }` chunks as text arrives, then
+   * a final `{ done: true, model, provider, usage, cost }` chunk with totals.
+   *
+   * @example
+   * for await (const chunk of cencori.vision.analyzeStream({ image: { url } })) {
+   *   if (chunk.delta) process.stdout.write(chunk.delta);
+   *   if (chunk.done) console.log(chunk.cost);
+   * }
+   */
+  async *analyzeStream(request) {
+    const body = { ...toBody(request), stream: true };
+    const response = await fetch(`${this.config.baseUrl}/api/ai/vision`, {
+      method: "POST",
+      headers: {
+        "CENCORI_API_KEY": this.config.apiKey,
+        "Content-Type": "application/json",
+        ...this.config.headers
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}));
+      const message = data && typeof data === "object" && "message" in data && typeof data.message === "string" ? data.message : `Vision stream request failed with status ${response.status}`;
+      throw new Error(message);
+    }
+    if (!response.body) throw new Error("Response body is null");
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.startsWith("data: ")) continue;
+          const data = line.slice(6);
+          if (data === "[DONE]") return;
+          try {
+            yield JSON.parse(data);
+          } catch {
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
   async post(path, request) {
     const response = await fetch(`${this.config.baseUrl}${path}`, {
       method: "POST",
@@ -699,6 +762,66 @@ var VisionNamespace = class {
   }
 };
 
+// src/documents/index.ts
+function toBody2(request, extra = {}) {
+  const body = {
+    prompt: request.prompt,
+    model: request.model,
+    max_tokens: request.maxTokens,
+    temperature: request.temperature,
+    ...extra
+  };
+  if (request.document.url) {
+    body.document_url = request.document.url;
+  } else if (request.document.base64) {
+    body.document_base64 = request.document.base64;
+    body.mime_type = request.document.mimeType;
+    body.filename = request.document.filename;
+  } else {
+    throw new Error("documents request requires document.url or document.base64");
+  }
+  return body;
+}
+var DocumentsNamespace = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Extract text from a PDF (native, no LLM) or image (via Vision OCR). */
+  async extract(request) {
+    return this.post("/api/ai/documents/extract", toBody2(request));
+  }
+  /** Extract then summarize the document with a chat model. */
+  async summarize(request) {
+    return this.post("/api/ai/documents/summarize", toBody2(request));
+  }
+  /** Extract then answer a question about the document. */
+  async query(request) {
+    if (!request.question) throw new Error("documents.query requires a `question`");
+    return this.post("/api/ai/documents/query", toBody2(request, { question: request.question }));
+  }
+  async post(path, body) {
+    const response = await fetch(`${this.config.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "CENCORI_API_KEY": this.config.apiKey,
+        "Content-Type": "application/json",
+        ...this.config.headers
+      },
+      body: JSON.stringify(body)
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      const message = data && typeof data === "object" && "message" in data && typeof data.message === "string" ? data.message : `Documents request failed with status ${response.status}`;
+      const code = data && typeof data === "object" && "error" in data && typeof data.error === "string" ? data.error : "request_failed";
+      const err = new Error(message);
+      err.code = code;
+      err.details = data;
+      throw err;
+    }
+    return data;
+  }
+};
+
 // src/sessions/index.ts
 var SessionsNamespace = class {
   constructor(config) {
@@ -1223,6 +1346,7 @@ var Cencori = class {
     };
     this.ai = new AINamespace(this.config);
     this.vision = new VisionNamespace(this.config);
+    this.documents = new DocumentsNamespace(this.config);
     this.agents = new AgentsNamespace(this.config);
     this.compute = new ComputeNamespace();
     this.workflow = new WorkflowNamespace();
@@ -1650,6 +1774,7 @@ cencori.chat = cencori;
   Cencori,
   CencoriError,
   ComputeNamespace,
+  DocumentsNamespace,
   MemoryClient,
   RateLimitError,
   SafetyError,