@absolutejs/ai 0.0.56 → 0.0.58

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `@absolutejs/ai`.
+
+This file is generated by `absolute-changelog` from the entries in
+`changelog/`. Edit an entry, not this file — and add new ones under
+`changelog/unreleased/`.
+
+## 0.0.58 — 2026-09-15
+
+### Added
+
+- **Keep compacted text useful with read-only original-source search, checkpointed ingestion, and capacity-checked terminal tool loops** (`createAITextSource`, `prepareAITextInput`, `PrepareAITextInputOptions`, `streamAIWithTools`, `StreamAIWithToolsOptions`)
+
+## 0.0.57 — 2026-09-15
+
+### Added
+
+- **Add model-specific token capacity, optional provider capacity configuration, and recoverable long-text preparation** (`inspectAIInput`, `prepareAITextInput`, `AIProviderConfig`, `OpenAIConfig`, `OpenAIResponsesConfig`)
+
+### Internal
+
+- **Regenerate the OpenRouter client declaration with equivalent reordered response union types** (`createOpenRouterClient`)

package/README.md

@@ -329,3 +329,77 @@ Use `openrouterResponses(config)` when an AbsoluteJS agent should stream through
 OpenRouter's stateless Responses API, or `openrouterMessages(config)` for the
 native Anthropic Messages protocol. Both accept the same model/provider policies
 and `providerOptions.openrouter` controls, including replayable hosted-tool data.
+
+### Model capacity and long text
+
+Use `inspectAIInput(provider, params)` to count the complete request, including
+instructions and tools, and reserve room for the requested reply. The result
+includes `inputTokens`, `availableInputTokens`, model `limits`, and `fits`.
+There is no package-wide character limit or character-to-token estimate.
+
+For text conversations, `prepareAITextInput(provider, params, options)` returns
+`{ params, compacted, sectionsProcessed }`. Requests that fit pass through
+unchanged. Oversized text is read in counted sections into rolling notes; the
+final request is counted again before being returned. Summaries can lose detail,
+so persist the original source first and retain it for download and resume.
+
+```ts
+import { prepareAITextInput } from "@absolutejs/ai";
+
+// Save original messages before preparation. This may make additional model calls.
+const prepared = await prepareAITextInput(provider, params, {
+  onProgress: ({ processedCharacters, totalCharacters }) => {
+    reportProgress(processedCharacters, totalCharacters);
+  },
+  onUsage: (usage) => recordSectionUsage(usage),
+});
+for await (const chunk of provider.stream(prepared.params)) {
+  // Render the reply and record its usage as usual.
+}
+```
+
+Anthropic and Gemini retrieve native model metadata and count using their native
+APIs. OpenAI uses its input-token counting API and an exact, documented model
+catalog because its model-list API does not expose context limits. OpenAI
+providers accept `modelLimits` for additional model IDs or compatible endpoints.
+Unknown models/providers fail with `AIInputError` (`capacity_unavailable`) rather
+than guessing. Custom providers can implement the optional `inputCapacity`
+capability. Existing `stream` calls remain unchanged.
+
+Automatic preparation supports text-only history. It rejects oversized tool or
+multimodal histories rather than flattening them. Handle preparation errors in
+the UI while preserving the original input; expose retry without clearing the
+conversation. File upload/storage limits are application transport limits and
+should be reported separately from model capacity.
+
+#### Keep originals useful after compaction
+
+`createAITextSource(messages)` builds a session-scoped, read-only source index.
+Its `tools` map exposes `search_text_source` and `read_text_source` for use with
+`streamAIWithTools`. Search returns bounded **verbatim** passages with stable
+message IDs and character offsets; read can retrieve adjoining passages. This
+is lexical search, so ask the model to try alternate terms and never treat no
+matches as proof a fact is absent. Keep originals persisted and rebuild the
+index on resume. The index performs no model calls or external network access.
+
+Attach these tools when using compacted notes, and instruct the model to verify
+numbers, dates, exceptions, and corrections in the originals before finalizing.
+Never make the rolling summary the only accessible copy of a large document.
+
+`prepareAITextInput` accepts a server-owned `checkpoint` and calls
+`onCheckpoint` after each completed section. Store that checkpoint for retries;
+its model/task and original-prefix fingerprints must match before it is reused.
+Edited input or changed instructions invalidate it. Original text remains the
+source of truth. Do not accept checkpoints or generated notes from a client.
+
+`streamAIWithTools({ validateInput: true, ... })` checks every model request,
+including accumulated tool results, before sending it. It also rejects streams
+that end without a completion marker. `stopAfterTools: ["finish"]` stops after a
+named tool succeeds, avoiding an extra generation or later tool side effects
+when the application is ready to validate and persist a result.
+
+For a bounded live regression against the intake model, set `ANTHROPIC_API_KEY`
+and run `bun scripts/eval-text-source.ts`. It uses synthetic text, simulates a
+small context, and verifies that original-source lookups recover later budget
+and deadline corrections omitted from the notes. It makes real, billed model
+calls; the ordinary test suite uses deterministic local providers instead.

package/changelog.json

@@ -0,0 +1,47 @@
+{
+	"contract": 1,
+	"name": "@absolutejs/ai",
+	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "Keep compacted text useful with read-only original-source search, checkpointed ingestion, and capacity-checked terminal tool loops",
+					"symbols": [
+						"createAITextSource",
+						"prepareAITextInput",
+						"PrepareAITextInputOptions",
+						"streamAIWithTools",
+						"StreamAIWithToolsOptions"
+					]
+				}
+			],
+			"date": "2026-09-15",
+			"version": "0.0.58"
+		},
+		{
+			"changes": [
+				{
+					"kind": "internal",
+					"summary": "Regenerate the OpenRouter client declaration with equivalent reordered response union types",
+					"symbols": [
+						"createOpenRouterClient"
+					]
+				},
+				{
+					"kind": "added",
+					"summary": "Add model-specific token capacity, optional provider capacity configuration, and recoverable long-text preparation",
+					"symbols": [
+						"inspectAIInput",
+						"prepareAITextInput",
+						"AIProviderConfig",
+						"OpenAIConfig",
+						"OpenAIResponsesConfig"
+					]
+				}
+			],
+			"date": "2026-09-15",
+			"version": "0.0.57"
+		}
+	]
+}