@naturali/cli 0.41.0 → 0.42.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.41.0";
+var version = "0.42.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const jsonBodySerializer = { bodySerializer: (body) => JSON.stringify(body, (_key, value) => typeof value === "bigint" ? value.toString() : value) };
@@ -1361,7 +1361,11 @@ var Knowledge = class {
 	/**
 	* Create a document
 	*
-	* Add an inline-text document to the collection. The platform ingests the content (chunk + embed) and records the document's ingestion status. File upload (PDF/binary) is a deliberate follow-up.
+	* Add a document to the collection, from **inline text** (`content`) or from an **uploaded file** (`file`, base64, plus `content_type` and `filename`) — exactly one of the two.
+	*
+	* `application/pdf`, `text/plain` and `text/markdown` are extracted natively. Any other media type needs a converter (`POST /v1/projects/{project_id}/knowledge/converters`) registered for it in the project; without one the request is rejected with `unsupported_content_type` and no document is created.
+	*
+	* Ingestion (extract → chunk → embed) runs in the background: the document comes back `pending` and becomes `indexed` or `failed`, which is announced by the `knowledge.document_ingested` / `knowledge.ingest_failed` webhook events.
 	*
 	*/
 	static createKnowledgeDocument(options) {
@@ -1406,6 +1410,86 @@ var Knowledge = class {
 			...options
 		});
 	}
+	/**
+	* List converters
+	*
+	* Lists the media converters registered in the project.
+	*/
+	static listKnowledgeConverters(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/knowledge/converters",
+			...options
+		});
+	}
+	/**
+	* Create a converter
+	*
+	* Register a converter for a media type the platform cannot extract natively, so files of that type become ingestable documents like any other. A converter maps a `content_type` glob (`image*`, `audio/mpeg`, …) onto one of two workers:
+	*
+	* - an **agent** (`agent_id`) — the file is handed to a
+	* multimodal model with a fixed "extract all the text" instruction and
+	* its answer becomes the document text. The shortest path for images
+	* and scanned PDFs; nothing to map.
+	*
+	* - a **tool** (`tool_id`) — the file is passed to an
+	* `http` tool as `{ content_type, filename, data_base64 }`, and
+	* whatever string the tool returns becomes the document text. The path
+	* for dedicated non-chat APIs (speech-to-text, a specialist OCR
+	* engine); use the tool's `execute.body_mode: multipart` for
+	* form-data endpoints and its `output_mapping` to reduce a JSON
+	* response to the bare string.
+	*
+	*
+	* Exactly one of `agent_id` / `tool_id`, and one converter per `content_type` in a project.
+	*
+	*/
+	static createKnowledgeConverter(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/knowledge/converters",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Delete a converter
+	*
+	* Removes the converter. Documents already ingested through it are untouched; new files of that media type stop being ingestable until another converter covers them.
+	*
+	*/
+	static deleteKnowledgeConverter(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/knowledge/converters/{converter_id}",
+			...options
+		});
+	}
+	/**
+	* Get a converter
+	*/
+	static getKnowledgeConverter(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/knowledge/converters/{converter_id}",
+			...options
+		});
+	}
+	/**
+	* Update a converter
+	*
+	* Change the worker or the chunking defaults. At least one field is required; `agent_id` and `tool_id` stay mutually exclusive, so setting one clears the other.
+	*
+	*/
+	static updateKnowledgeConverter(options) {
+		return (options.client ?? client).patch({
+			url: "/v1/projects/{project_id}/knowledge/converters/{converter_id}",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
 };
 var Models = class {
 	/**
@@ -4389,7 +4473,7 @@ const routes = {
 	"create-knowledge-document": {
 		serviceClass: "Knowledge",
 		operationId: "createKnowledgeDocument",
-		description: "Add an inline-text document to the collection. The platform ingests the content (chunk + embed) and records the document's ingestion status. File upload (PDF/binary) is a deliberate follow-up.",
+		description: "Add a document to the collection, from **inline text** (`content`) or from an **uploaded file** (`file`, base64, plus `content_type` and `filename`) — exactly one of the two. `application/pdf`, `text/plain` and `text/markdown` are extracted natively. Any other media type needs a converter (`POST /v1/projects/{project_id}/knowledge/converters`) registered for it in the project; without one the request is rejected with `unsupported_content_type` and no document is created. Ingestion (extract → chunk → embed) runs in the background: the document comes back `pending` and becomes `indexed` or `failed`, which is announced by the `knowledge.document_ingested` / `knowledge.ingest_failed` webhook events.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
 		httpMethod: "post",
 		pathParams: ["project_id", "collection_id"],
@@ -4411,14 +4495,28 @@ const routes = {
 			},
 			{
 				"name": "content",
-				"description": "The document's text content.",
-				"required": true,
+				"description": "The document's text content. Mutually exclusive with `file`.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "file",
+				"description": "The file's bytes, base64-encoded. Mutually exclusive with `content`.\n",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "content_type",
+				"description": "Media type of `file`. `application/pdf`, `text/plain` and `text/markdown` are extracted natively; anything else needs a matching converter in the project. Required with `file`.\n",
+				"required": false,
 				"type": "string",
 				"in": "body"
 			},
 			{
 				"name": "filename",
-				"description": "A label for the document; also its logical filename.",
+				"description": "A label for the document; also its logical filename. Required with `file`.\n",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -4429,6 +4527,27 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "chunk_strategy",
+				"description": "How the extracted text is split for embedding. `page` (the default) makes one chunk per page, which is what lets a retrieved chunk cite a page number; `size` makes fixed-width character windows, which retrieves more sharply on dense pages at the cost of that citation; `whole` keeps the document as a single chunk. Ignored for inline text.\n",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "chunk_size",
+				"description": "Window width in characters, when `chunk_strategy` is `size`.",
+				"required": false,
+				"type": "integer",
+				"in": "body"
+			},
+			{
+				"name": "chunk_overlap",
+				"description": "Characters of overlap between consecutive windows, when `chunk_strategy` is `size`. Must be smaller than `chunk_size`.\n",
+				"required": false,
+				"type": "integer",
+				"in": "body"
 			}
 		]
 	},
@@ -4540,6 +4659,237 @@ const routes = {
 			}
 		]
 	},
+	"list-knowledge-converters": {
+		serviceClass: "Knowledge",
+		operationId: "listKnowledgeConverters",
+		description: "Lists the media converters registered in the project.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: ["limit", "cursor"],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "limit",
+				"description": "Maximum items per page.",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "cursor",
+				"description": "Opaque pagination cursor from a previous response's next_cursor.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			}
+		]
+	},
+	"create-knowledge-converter": {
+		serviceClass: "Knowledge",
+		operationId: "createKnowledgeConverter",
+		description: "Register a converter for a media type the platform cannot extract natively, so files of that type become ingestable documents like any other. A converter maps a `content_type` glob (`image/*`, `audio/mpeg`, …) onto one of two workers: - an **agent** (`agent_id`) — the file is handed to a multimodal model with a fixed \"extract all the text\" instruction and its answer becomes the document text. The shortest path for images and scanned PDFs; nothing to map. - a **tool** (`tool_id`) — the file is passed to an `http` tool as `{ content_type, filename, data_base64 }`, and whatever string the tool returns becomes the document text. The path for dedicated non-chat APIs (speech-to-text, a specialist OCR engine); use the tool's `execute.body_mode: multipart` for form-data endpoints and its `output_mapping` to reduce a JSON response to the bare string. Exactly one of `agent_id` / `tool_id`, and one converter per `content_type` in a project.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
+		httpMethod: "post",
+		pathParams: ["project_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "content_type",
+				"description": "The media-type glob to claim — an exact type (`audio/mpeg`) or a `*` wildcard on the subtype (`image/*`).\n",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "agent_id",
+				"description": "An agent in this project, used as the converter.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "tool_id",
+				"description": "An `http` tool in this project, used as the converter.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "preset_parameters",
+				"description": "Fixed arguments merged into every tool-converter call.",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			},
+			{
+				"name": "native_extraction",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "chunk_strategy",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "chunk_size",
+				"description": "",
+				"required": false,
+				"type": "integer",
+				"in": "body"
+			},
+			{
+				"name": "chunk_overlap",
+				"description": "",
+				"required": false,
+				"type": "integer",
+				"in": "body"
+			}
+		]
+	},
+	"get-knowledge-converter": {
+		serviceClass: "Knowledge",
+		operationId: "getKnowledgeConverter",
+		description: "Get a converter",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
+		httpMethod: "get",
+		pathParams: ["project_id", "converter_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "converter_id",
+			"description": "Knowledge converter public ID (igr_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"update-knowledge-converter": {
+		serviceClass: "Knowledge",
+		operationId: "updateKnowledgeConverter",
+		description: "Change the worker or the chunking defaults. At least one field is required; `agent_id` and `tool_id` stay mutually exclusive, so setting one clears the other.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
+		httpMethod: "patch",
+		pathParams: ["project_id", "converter_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "converter_id",
+				"description": "Knowledge converter public ID (igr_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "content_type",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "agent_id",
+				"description": "Switches the converter to this agent, clearing `tool_id`.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "tool_id",
+				"description": "Switches the converter to this tool, clearing `agent_id`.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "preset_parameters",
+				"description": "",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			},
+			{
+				"name": "native_extraction",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "chunk_strategy",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "chunk_size",
+				"description": "",
+				"required": false,
+				"type": "integer",
+				"in": "body"
+			},
+			{
+				"name": "chunk_overlap",
+				"description": "",
+				"required": false,
+				"type": "integer",
+				"in": "body"
+			}
+		]
+	},
+	"delete-knowledge-converter": {
+		serviceClass: "Knowledge",
+		operationId: "deleteKnowledgeConverter",
+		description: "Removes the converter. Documents already ingested through it are untouched; new files of that media type stop being ingestable until another converter covers them.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
+		httpMethod: "delete",
+		pathParams: ["project_id", "converter_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "converter_id",
+			"description": "Knowledge converter public ID (igr_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
 	"list-models": {
 		serviceClass: "Models",
 		operationId: "listModels",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Command-line interface for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     "tsx": "^4.23.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.10",
-    "@naturali/sdk": "0.41.0"
+    "@naturali/sdk": "0.42.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",