@naturali/cli 0.129.0 → 0.130.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.129.0";
+var version = "0.130.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -2773,7 +2773,7 @@ var Generations = class {
 	/**
 	* List generations
 	*
-	* Returns generations the caller can access, optionally filtered by agent, trace, orchestration run, node, and status. Replaces the former per-trace generations endpoint (use the trace_id query filter).
+	* Returns generations the caller can access, optionally filtered by agent, trace, orchestration run, node, and status. The generations of one trace are the `trace_id` filter.
 	*
 	* Filtering by `orchestration_run_id` is the supported way to get from an orchestration run to the generations its agent nodes produced: a node execution record carries no generation id, so the pointer lives here, alongside the run's other attribution columns.
 	*
@@ -3069,7 +3069,7 @@ var Memories = class {
 	/**
 	* Create a memory
 	*
-	* Writes a fact to the specified memory store through the standard write algorithm: the content is embedded (or matched to text the store already holds), compared against the most similar currently-valid memory, and resolved to exactly one of three outcomes — `skipped` at or above `duplicate_threshold`, `superseded` at or above `supersede_threshold`, `created` below it. Every call records one assertion, whatever the outcome.
+	* Writes a fact to the specified memory store through the standard write algorithm: the content is embedded (or matched to text the store already holds), compared against the most similar currently-valid memory, and resolved to exactly one of three outcomes — `skipped` at or above `duplicate_threshold`, `superseded` at or above `supersede_threshold`, `created` below it. `supersedes` overrides that comparison entirely, retiring the memory it names. Every call records one assertion, whatever the outcome.
 	*/
 	static createMemory(options) {
 		return (options.client ?? client).post({
@@ -3171,6 +3171,71 @@ var Memories = class {
 		});
 	}
 };
+var MemoryRules = class {
+	/**
+	* List memory rules
+	*
+	* Returns memory rules, newest first. Narrow to one store with `memory_store_id` — that form is authorized against the store itself, so it answers "what feeds this store?" in one call.
+	*/
+	static listMemoryRules(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/memory-rules",
+			...options
+		});
+	}
+	/**
+	* Create a memory rule
+	*
+	* Creates an ingestion rule on a memory store. With neither `agent_id` nor `tool_id` the built-in extractor runs, configurable through `prompt`, `ai_provider_id` and `model`.
+	*/
+	static createMemoryRule(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/memory-rules",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Delete a memory rule
+	*
+	* Deletes a memory rule. The assertions it wrote are kept; their `rule_id` becomes null.
+	*/
+	static deleteMemoryRule(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/memory-rules/{memory_rule_id}",
+			...options
+		});
+	}
+	/**
+	* Get a memory rule
+	*
+	* Returns a specific memory rule
+	*/
+	static getMemoryRule(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/memory-rules/{memory_rule_id}",
+			...options
+		});
+	}
+	/**
+	* Update a memory rule
+	*
+	* Updates a memory rule. Validation runs against the rule as it would stand after the change, so a one-field update cannot pair a handler with a stored extractor override from the side.
+	*/
+	static updateMemoryRule(options) {
+		return (options.client ?? client).patch({
+			url: "/v1/projects/{project_id}/memory-rules/{memory_rule_id}",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+};
 var MemoryStores = class {
 	/**
 	* List memory stores
@@ -4922,6 +4987,7 @@ var NaturaliClient = class {
 	ingestionRules;
 	knowledge;
 	memories;
+	memoryRules;
 	memoryStores;
 	modelRoutes;
 	quotas;
@@ -4972,6 +5038,7 @@ var NaturaliClient = class {
 		this.ingestionRules = bindResource(IngestionRules, this.http);
 		this.knowledge = bindResource(Knowledge, this.http);
 		this.memories = bindResource(Memories, this.http);
+		this.memoryRules = bindResource(MemoryRules, this.http);
 		this.memoryStores = bindResource(MemoryStores, this.http);
 		this.modelRoutes = bindResource(ModelRoutes, this.http);
 		this.quotas = bindResource(Quotas, this.http);
@@ -5017,6 +5084,7 @@ var src_exports = /* @__PURE__ */ __exportAll({
 	IngestionRules: () => IngestionRules,
 	Knowledge: () => Knowledge,
 	Memories: () => Memories,
+	MemoryRules: () => MemoryRules,
 	MemoryStores: () => MemoryStores,
 	ModelRoutes: () => ModelRoutes,
 	Models: () => Models,
@@ -6936,13 +7004,6 @@ const routes = {
 				"type": "object",
 				"in": "body"
 			},
-			{
-				"name": "extract",
-				"description": "Per-turn override of the agent's `knowledge_config.extraction` default. Omit to follow the agent's stored config. Set `false` to suppress automatic memory store extraction for this turn (e.g. an operational or tool-listing turn that would only add noise to a curated memory store). Set `true` to force extraction on for this turn even when the agent does not enable it by default, provided the agent has a `write_memory_store_id`. Has no effect on streaming or `requires_action` turns, which never extract.",
-				"required": false,
-				"type": "boolean",
-				"in": "body"
-			},
 			{
 				"name": "knowledge_config",
 				"description": "Per-generation knowledge retrieval override. Array filters (memory_store_ids, document_ids, document_paths) are unioned with the agent's stored knowledge_config; `tags` pairs are merged with the override winning per key; scalar fields (min_score, limit) use the per-generation value when present.",
@@ -11463,7 +11524,7 @@ const routes = {
 	"list-generations": {
 		serviceClass: "Generations",
 		operationId: "listGenerations",
-		description: "Returns generations the caller can access, optionally filtered by agent, trace, orchestration run, node, and status. Replaces the former per-trace generations endpoint (use the trace_id query filter). Filtering by `orchestration_run_id` is the supported way to get from an orchestration run to the generations its agent nodes produced: a node execution record carries no generation id, so the pointer lives here, alongside the run's other attribution columns.",
+		description: "Returns generations the caller can access, optionally filtered by agent, trace, orchestration run, node, and status. The generations of one trace are the `trace_id` filter. Filtering by `orchestration_run_id` is the supported way to get from an orchestration run to the generations its agent nodes produced: a node execution record carries no generation id, so the pointer lives here, alongside the run's other attribution columns.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/generations",
 		httpMethod: "get",
 		pathParams: ["project_id"],
@@ -12335,13 +12396,6 @@ const routes = {
 				"type": "number",
 				"in": "body"
 			},
-			{
-				"name": "min_score",
-				"description": "Deprecated alias for `min_similarity`, with identical behavior. While ranking was single-signal `score` equaled `similarity_score`, so this has only ever filtered cosine and an existing value keeps returning the same results. `min_similarity` wins when both are sent. Removed in v2.",
-				"required": false,
-				"type": "number",
-				"in": "body"
-			},
 			{
 				"name": "rrf_k",
 				"description": "The `k` in the reciprocal rank fusion term `1 / (k + rank)`, which sets how steeply a result's contribution decays with its position in each ranked list. A smaller value weights the very top of each list more heavily. Defaults to the deployment's `KNOWLEDGE_RRF_K`, itself 60 by default. Only applies when `query` is provided.",
@@ -12351,7 +12405,7 @@ const routes = {
 			},
 			{
 				"name": "recency_half_life_days",
-				"description": "Half-life, in days, of a recency decay applied to **memory store** results after fusion: a result's `score` is multiplied by `2 ^ (-age_in_days / recency_half_life_days)`, where age is measured from its `updated_at`. Document results are never decayed. `0` — the default, and the default of the deployment's `KNOWLEDGE_RECENCY_HALF_LIFE_DAYS` — disables the blend entirely; it is a switch, not a lower bound, and sending `0` turns off a deployment-wide decay for this one request. Accepts fractions (`0.5` is twelve hours). How many ranks a given half-life costs depends on `rrf_k`. Only applies when `query` is provided.",
+				"description": "Half-life, in days, of a recency decay applied to **memory store** results after fusion: a result's `score` is multiplied by `2 ^ (-age_in_days / recency_half_life_days)`, where age is measured from its `updated_at`. Document results are never decayed. `0` — the default, and the default of the deployment's `KNOWLEDGE_RECENCY_HALF_LIFE_DAYS` — disables the blend entirely; it is a switch, not a lower bound, and sending `0` turns off a deployment-wide decay for this one request. Accepts fractions (`0.5` is twelve hours). How many ranks a given half-life costs depends on `rrf_k`. Only applies when `query` is provided. **No value is known to be safe in general**: every half-life measured against the reference corpus that lifted recency-sensitive queries also cost relevance-sensitive ones, which is why this ships disabled. Measure against your own corpus before setting it — see the Retrieval Quality guide.",
 				"required": false,
 				"type": "number",
 				"in": "body"
@@ -12363,6 +12417,20 @@ const routes = {
 				"type": "integer",
 				"in": "body"
 			},
+			{
+				"name": "include_documents",
+				"description": "Set `false` to leave the document store out of this search. A `query` names no store, so it reaches both; the store-specific filters narrow *within* a store rather than choosing between them. This is the switch, and a filter naming the other store never overrides it. `false` for both stores is `400`.",
+				"required": false,
+				"type": "boolean",
+				"in": "body"
+			},
+			{
+				"name": "include_memories",
+				"description": "Set `false` to leave the memory store out of this search. The mirror of `include_documents`, for a caller that wants documents alone.",
+				"required": false,
+				"type": "boolean",
+				"in": "body"
+			},
 			{
 				"name": "memory_store_ids",
 				"description": "Search memories within these specific memory stores",
@@ -12386,7 +12454,7 @@ const routes = {
 			},
 			{
 				"name": "tags",
-				"description": "Filter results to documents and memories whose `tags` contain every one of these key-value pairs (exact, case-sensitive match). The only filter that scopes both stores, so passing it alone searches both. For memories it matches at memory granularity: a memory is returned when its parent memory store's tags match or its own do.",
+				"description": "Filter results to documents and memories whose `tags` contain every one of these key-value pairs (exact, case-sensitive match). Scopes both stores, so passing it alone searches both — as `query` does. For memories it matches at memory granularity: a memory is returned when its parent memory store's tags match or its own do.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -12455,7 +12523,7 @@ const routes = {
 	"create-memory": {
 		serviceClass: "Memories",
 		operationId: "createMemory",
-		description: "Writes a fact to the specified memory store through the standard write algorithm: the content is embedded (or matched to text the store already holds), compared against the most similar currently-valid memory, and resolved to exactly one of three outcomes — `skipped` at or above `duplicate_threshold`, `superseded` at or above `supersede_threshold`, `created` below it. Every call records one assertion, whatever the outcome.",
+		description: "Writes a fact to the specified memory store through the standard write algorithm: the content is embedded (or matched to text the store already holds), compared against the most similar currently-valid memory, and resolved to exactly one of three outcomes — `skipped` at or above `duplicate_threshold`, `superseded` at or above `supersede_threshold`, `created` below it. `supersedes` overrides that comparison entirely, retiring the memory it names. Every call records one assertion, whatever the outcome.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/memories",
 		httpMethod: "post",
 		pathParams: ["project_id"],
@@ -12510,6 +12578,13 @@ const routes = {
 				"type": "object",
 				"in": "body"
 			},
+			{
+				"name": "supersedes",
+				"description": "The memory this write replaces, named outright. The declaration outranks the thresholds in both directions: the target is retired and the write returns `superseded` however similar or distant the two texts are. This is what reaches a contradiction cosine cannot see (\"The office is in Lisbon\" then \"We closed the Lisbon office\"). The target must be a still-valid memory in the same memory store, and the caller needs `memories:UpdateMemory` on it as well as `memories:CreateMemory` on the store.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
 			{
 				"name": "duplicate_threshold",
 				"description": "Cosine similarity at or above which the incoming content is a duplicate of an existing memory and the write is skipped. Overrides the store's `duplicate_threshold` for this call; falls back to the store's value, then to `0.95`.",
@@ -12721,6 +12796,283 @@ const routes = {
 			"in": "path"
 		}]
 	},
+	"list-memory-rules": {
+		serviceClass: "MemoryRules",
+		operationId: "listMemoryRules",
+		description: "Returns memory rules, newest first. Narrow to one store with `memory_store_id` — that form is authorized against the store itself, so it answers \"what feeds this store?\" in one call.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/memory-rules",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: [
+			"memory_store_id",
+			"limit",
+			"offset"
+		],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "memory_store_id",
+				"description": "Only the rules of this memory store",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "limit",
+				"description": "Number of results per page",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "offset",
+				"description": "Number of results to skip",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			}
+		]
+	},
+	"create-memory-rule": {
+		serviceClass: "MemoryRules",
+		operationId: "createMemoryRule",
+		description: "Creates an ingestion rule on a memory store. With neither `agent_id` nor `tool_id` the built-in extractor runs, configurable through `prompt`, `ai_provider_id` and `model`.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/memory-rules",
+		httpMethod: "post",
+		pathParams: ["project_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "memory_store_id",
+				"description": "The destination store, and the rule's owning scope",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "on",
+				"description": "The event a firing reads. `agents.generation.completed` fires once per completed turn whatever the transport, and is the only event the built-in extractor may bind to. `conversations.message.generated` fires per persisted assistant reply and is conversation-backed, so it is for custom handlers.",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "source_agent_ids",
+				"description": "Agents whose turns this rule reads. Omit or send `null` for every agent in the store's project.",
+				"required": false,
+				"type": "array",
+				"in": "body"
+			},
+			{
+				"name": "agent_id",
+				"description": "Handler agent (mutually exclusive with tool_id)",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "tool_id",
+				"description": "Handler tool (mutually exclusive with agent_id)",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "action",
+				"description": "Operation id, for a tool handler",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "preset_parameters",
+				"description": "Merged into a tool handler's input before invocation. The turn's own fields are reserved and win.",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			},
+			{
+				"name": "prompt",
+				"description": "Replaces the built-in extractor's task instructions. The JSON response contract and the transcript are always appended. Not valid with a handler.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "ai_provider_id",
+				"description": "Provider override for the built-in extractor's completion. Not valid with a handler.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "model",
+				"description": "Model override for the built-in extractor's completion. Not valid with a handler.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "enabled",
+				"description": "A disabled rule is kept and never fires",
+				"required": false,
+				"type": "boolean",
+				"in": "body"
+			}
+		]
+	},
+	"get-memory-rule": {
+		serviceClass: "MemoryRules",
+		operationId: "getMemoryRule",
+		description: "Returns a specific memory rule",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/memory-rules",
+		httpMethod: "get",
+		pathParams: ["project_id", "memory_rule_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "memory_rule_id",
+			"description": "Memory rule ID",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"update-memory-rule": {
+		serviceClass: "MemoryRules",
+		operationId: "updateMemoryRule",
+		description: "Updates a memory rule. Validation runs against the rule as it would stand after the change, so a one-field update cannot pair a handler with a stored extractor override from the side.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/memory-rules",
+		httpMethod: "patch",
+		pathParams: ["project_id", "memory_rule_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "memory_rule_id",
+				"description": "Memory rule ID",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "on",
+				"description": "The event a firing reads. `agents.generation.completed` fires once per completed turn whatever the transport, and is the only event the built-in extractor may bind to. `conversations.message.generated` fires per persisted assistant reply and is conversation-backed, so it is for custom handlers.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "source_agent_ids",
+				"description": "Send `null` to widen the rule to every agent in the project",
+				"required": false,
+				"type": "array",
+				"in": "body"
+			},
+			{
+				"name": "agent_id",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "tool_id",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "action",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "preset_parameters",
+				"description": "",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			},
+			{
+				"name": "prompt",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "ai_provider_id",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "model",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "enabled",
+				"description": "",
+				"required": false,
+				"type": "boolean",
+				"in": "body"
+			}
+		]
+	},
+	"delete-memory-rule": {
+		serviceClass: "MemoryRules",
+		operationId: "deleteMemoryRule",
+		description: "Deletes a memory rule. The assertions it wrote are kept; their `rule_id` becomes null.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/memory-rules",
+		httpMethod: "delete",
+		pathParams: ["project_id", "memory_rule_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "memory_rule_id",
+			"description": "Memory rule ID",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
 	"list-memory-stores": {
 		serviceClass: "MemoryStores",
 		operationId: "listMemoryStores",
@@ -15969,7 +16321,7 @@ const routes = {
 			},
 			{
 				"name": "context_keys",
-				"description": "Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Naturali-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.",
+				"description": "Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Naturali-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.",
 				"required": false,
 				"type": "array",
 				"in": "body"
@@ -16107,7 +16459,7 @@ const routes = {
 			},
 			{
 				"name": "context_keys",
-				"description": "Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Naturali-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.",
+				"description": "Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Naturali-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.",
 				"required": false,
 				"type": "array",
 				"in": "body"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.129.0",
+  "version": "0.130.0",
   "description": "Command-line interface for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@naturali/sdk": "0.129.0",
+    "@naturali/sdk": "0.130.0",
     "@ttoss/openapi-codegen": "^0.3.0",
     "@types/node": "^26.5.1",
     "tsdown": "^0.23.0",