@aeye/core 0.4.0 → 0.5.0

package/aeye-core-prompts.md

@@ -47,6 +47,13 @@ A `Prompt` only does real work when the context supplies `execute` and/or `strea
 
 `PromptReconfigInput` stats include: `iteration`, `maxIterations`, `toolParseErrors`, `toolCallErrors`, `tools` (names), `toolSuccesses`, and remaining `toolRetries` / `outputRetries` / `forgetRetries`. `PromptReconfig` lets you return `{ config?, maxIterations?, toolRetries?, outputRetries?, forgetRetries? }`.
 
+Four semantics of that hook are load-bearing and are not visible in the types:
+
+- **`PromptReconfig.maxIterations` is RELATIVE, not absolute.** The loop assigns `maxIterations = iterations + value`, so returning `N` means "this round plus `N - 1` more". Return `budget - stats.iteration` to set an absolute ceiling. Returning `0` **breaks out immediately** — and with no result parsed yet the run then throws its own generic `failed without a specified error`, so `0` is not a graceful stop.
+- **`PromptReconfigInput.maxIterations` is the ceiling as it stood BEFORE this call** — whatever the previous round set. A decision that must track a ceiling you are raising in the same call has to use your own value, not this field.
+- **The error/success counters are cumulative for the run**, not per round: `toolSuccesses` / `toolParseErrors` / `toolCallErrors` only ever grow, so "did THIS round make progress?" is a delta you keep yourself. `toolRetries` / `outputRetries` / `forgetRetries` are the opposite — they are the *remaining* allowances and count down.
+- **`reconfig` runs at the END of an iteration**, after tool dispatch and output parsing and before the `dynamic` re-resolve — so anything it changes takes effect on the NEXT model call.
+
 ## Methods
 
 ```typescript

package/aeye-core-schema.md

@@ -29,10 +29,25 @@ A descriptor (see `src/schema.ts` line ~26 for the fully documented interface) d
 | `tupleEncoding` | `'object-numeric-keys'` vs `'prefix-items'` vs `'items-union'`. |
 | `optionalAsNullable` | Emit optionals as `T \| null` (OpenAI strict) vs drop from `required[]`. |
 | `allowAllOf` / `allowAnyOf` / `allowOneOf` | Combinator support. |
+| `allowRootRef` / `allowDefsRef` | Whether `$ref: '#'` / `$ref: '#/$defs/X'` are permitted. |
+| `anyEncoding` | How `z.any()` / `z.unknown()` is emitted — see below. |
 | `supportedStringFormats` | `'all'` or a `Set<string>` whitelist. |
 | `supportsRecursion` | Whether `$ref` self-reference works. |
 | `maxStrictTools` / `maxStrictOptionalParams` / `maxStrictUnionTypes` | Per-request slot budgets (`undefined` = no documented limit). |
 
+### `anyEncoding` — and what each mode requires
+
+An open "any JSON value" slot has no single portable spelling, so each dialect picks one. **Each mode needs keywords the same descriptor has to allow**, and `checkDescriptorConsistency` enforces that pairing:
+
+| Mode | Shape | Requires |
+|------|------|------|
+| `'recursive-strict'` | `$defs/Any` with array-of-pairs records (OpenAI strict has no open objects) | `allowAnyOf`, `allowDefsRef`, `supportsRecursion` |
+| `'recursive-open'` | `$defs/Any` with `additionalProperties: <self>` | `allowAnyOf`, `allowDefsRef`, `supportsRecursion` |
+| `'flat'` | inline non-recursive `anyOf` over every JSON type | `allowAnyOf` |
+| `'unconstrained'` | the empty schema `{}` (plus any `description`) | nothing |
+
+`'unconstrained'` is the only mode available to a dialect that forbids combinators **and** named `$defs` (Google). Per JSON Schema a schema with no assertion keywords validates every instance, which is exactly what "any value" means — so it is lossless as a constraint, and the source schema's `description` still rides along as the human/model-facing signal.
+
 ## Built-in descriptors
 
 Seven ship frozen and pre-registered:
@@ -41,9 +56,10 @@ Seven ship frozen and pre-registered:
 |------|------|-------|
 | `OPENAI_STRICT` | openai / strict | records→array-of-pairs, tuples→numeric-key objects, `optional → T \| null`, closed objects, restricted format whitelist. |
 | `ANTHROPIC_STRICT` | anthropic / strict | closed objects, no recursion, no length/range constraints; budgets 20 tools / 24 optional params / 16 unions. |
-| `GOOGLE_STRICT` | google / strict | `prefixItems`, `$ref: '#'` recursion, `propertyOrdering`, restricted format whitelist. |
+| `GOOGLE_STRICT` | google / strict | `prefixItems`, `$ref: '#'` recursion, `propertyOrdering`, restricted format whitelist, `z.any()` → `unconstrained` (Gemini forbids `anyOf` and named `$defs`). |
 | `LENIENT` | lenient / non-strict | No rewrites; everything passes through. Default for unannotated models. |
-| `OPENAI_NON_STRICT`, `ANTHROPIC_NON_STRICT`, `GOOGLE_NON_STRICT` | family / non-strict | Aliased to `LENIENT` but tagged with the family for diagnostics. |
+| `OPENAI_NON_STRICT`, `ANTHROPIC_NON_STRICT` | family / non-strict | Aliased to `LENIENT` but tagged with the family for diagnostics. |
+| `GOOGLE_NON_STRICT` | google / non-strict | `LENIENT` **except** `anyEncoding: 'unconstrained'`. Gemini compiles a decoding grammar whenever a tool call is forced, and rejects a self-referencing `$defs/Any` when it does — which has nothing to do with a per-tool strict flag (Google's function-calling API has none), so the encoding belongs to the dialect. |
 
 ## Functions
 
@@ -53,6 +69,7 @@ toJSONSchema(schema: z.ZodType,
 strictify<S extends z.ZodType>(schema: S, descriptor?: FormatDescriptor): S   // default OPENAI_STRICT
 analyzeSchema(schema): SchemaFeatures
 registerDescriptor(descriptor: FormatDescriptor): void
+checkDescriptorConsistency(descriptor: FormatDescriptor): string[]   // [] when consistent
 getDescriptor(family: DescriptorFamily, strict: boolean): FormatDescriptor
 getDescriptorById(id: string | undefined): FormatDescriptor
 hasDescriptorFamily(family: string | undefined): boolean
@@ -64,6 +81,7 @@ strictPriority(requested: boolean | number | undefined): number
 - `toJSONSchema` accepts a descriptor, a `ToJSONSchemaOptions` object, or a boolean (back-compat: `true` ⇒ `OPENAI_STRICT`, `false` ⇒ `LENIENT`).
 - `strictify` rewrites a Zod schema in place per the descriptor (results cached in a WeakMap; same OOM-safe pattern as `analyzeSchema`).
 - `analyzeSchema` returns `SchemaFeatures`: `{ hasRecursion, optionalParameterCount, unionTypeCount, recordCount, tupleCount }` — cached per schema.
+- `checkDescriptorConsistency` reports settings that ask the emitter for a keyword the same descriptor forbids (today: `anyEncoding` vs `allowAnyOf` / `allowDefsRef` / `supportsRecursion`). `registerDescriptor` runs it and `console.warn`s each problem, because otherwise the first report of a contradiction is a provider HTTP 400.
 
 ```typescript
 import { OPENAI_STRICT, ANTHROPIC_STRICT, getDescriptor, toJSONSchema } from '@aeye/core';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeye/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "@aeye Core - Core primitives for AI components (agents, tools, prompts)",
   "type": "module",
   "main": "dist/index.js",