@niscorp/signal 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# @niscorp/signal
+
+## 0.1.3
+
+### Patch Changes
+
+- 63445cb: `complete()` and `stream()` on a decision provider say their own name.
+
+  Both run through `stepStream`, and the refusal a decision provider gives a chat verb named that instead: `signal.complete('…')` failed with `stepStream() is not available on a decision provider…` and `context.verb: "stepStream"`, for a call the caller never made.
+
+  The error now names the verb that was called — `complete() is not available on a decision provider — it answers decide() and generates no text`, `context.verb: "complete"`, and the same for `stream`. `step`, `stepStream` and `embed` already named themselves.
+
+  Only those two strings change. The code is `E_VERB_NOT_SUPPORTED` as before, it is raised at the same moment (for `stream()`, when the stream is first read), and no request is sent.
+
+  **What to change:** nothing.
+
+- 8973c15: DOCS.md says what `embed()` and `meta.provider.raw` do. `embed()` does not check `supportsEmbedding`: the flag is what `describe()` reports, and the request is sent either way; a refused request is `E_PROVIDER_ERROR` with the provider's own error under `context.raw`. `meta.provider.raw` is `null` after `complete()` and `stream()`, which read the reply as a stream and keep no body (`step()` returns the body), and it is the provider's error for a call Signal recovered from a rejection. No code changed.
+
+  **What to change:** nothing.
+
+- ce21cf7: DOCS.md says what a tool's `input` schema may be. The model is sent its JSON Schema, taken from the schema's output side, and the arguments are parsed with it once. So an `input` schema validates and does not convert:
+  - One with no JSON Schema (a `.transform()`, a `z.date()`) rejects the call before any request is made, with Zod's own error rather than a `SignalError`.
+  - One whose output is another kind than its input (`z.stringbool()`) is described to the model by its output: told `boolean`, a model that sends one gets `input_invalid` back, and it is the string that is accepted.
+
+  Convert inside `execute`. DOCS.md says this under "Defining Tools", and a test holds the first. No code changed.
+
+  **What to change:** nothing.
+
+## 0.1.2
+
+### Patch Changes
+
+- fe30458: Every package exports its `package.json`, so an app can say which version of a package it runs by reading it from the package:
+
+  ```ts
+  import prism from '@niscorp/prism/package.json' with { type: 'json' };
+  prism.version; // the version that is installed, not the range that asked for it
+  ```
+
+  Until now the `exports` map hid it, and the only way to the version was a path into `node_modules`. `check:packages` installs the tarballs and reads every package's version this way.
+
+  **What to change:** nothing. An app that read a version by path can read it by name.
+
+## 0.1.1
+
+### Patch Changes
+
+- b67a125: Documentation only: each package's README, reference and design docs checked against its source and corrected — install lines and peers, signatures, defaults, status codes, licenses (loom, signal: Apache-2.0), and API that existed but was not documented.

package/DESIGN.md

@@ -62,8 +62,7 @@ sides is two changes.
 - **The router owns classification.** A response is `tool_calls`
   (declared tool), `output` (anything whose repaired value passes the
   acceptance gate — exit-tool args and pseudo-tool args included), or
-  `failed` with evidence (+ `attempted` when a parsed candidate existed
-  but failed the gate; + `truncated` when bytes end mid-structure).
+  `failed` with evidence (+ `truncated` when bytes end mid-structure).
   Callers switch on the outcome; they never parse strings.
 - **Rejections are arrivals.** A provider 400 that carries the model's
   attempt is recovered by an error-hook strategy and routed

package/DOCS.md

@@ -8,7 +8,7 @@ Complete reference for `@niscorp/signal`.
 
 ### Stateless Immutable Builder
 
-Signal uses an immutable builder pattern. Every configuration method returns a **new instance** — the original is never modified. `complete()` is the only method that executes.
+Signal uses an immutable builder pattern. Every configuration method returns a **new instance** — the original is never modified. Nothing is sent until an execution method (`complete()`, `stream()`, `step()`, `stepStream()`, `embed()`, `decide()`) is called.
 
 ```typescript
 const base = createSignal('groq').systemPrompt('You are helpful.');
@@ -35,6 +35,9 @@ Each provider has a capability profile that Signal uses to pick the right strate
 - **`nativeTools`** — Can the provider do tool calling natively?
 - **`nativeJsonSchema`** — Can it enforce a JSON Schema on the response?
 - **`nativeJsonMode`** — Can it guarantee JSON output?
+- **`toolsWithStructuredOutput`** — Is `response_format` accepted together with `tools` in one request?
+- **`validatesToolArgs`** — Does the endpoint validate tool-call arguments server-side and reject the request on a mismatch?
+- **`manglesNestedToolArgs`** — Does the model corrupt nested tool-call arguments?
 - **`multimodal`** — Does it accept image content?
 - **`supportsEmbedding`** — Can it convert text to vectors?
 
@@ -50,7 +53,18 @@ You don't need to think about this unless you're overriding defaults.
 const signal = createSignal('groq');
 ```
 
-Reads `GROQ_API_KEY` from environment automatically. Known providers: `'groq'`, `'openai'`, `'openrouter'`, `'anthropic'`, `'google'`.
+Reads `GROQ_API_KEY` from environment automatically. Known providers: `'groq'`, `'openai'`, `'openrouter'`, `'anthropic'`, `'google'`, `'typesafe'`.
+
+| Provider | Env var | Default model |
+|----------|---------|---------------|
+| `'groq'` | `GROQ_API_KEY` | `qwen/qwen3.8-27b` |
+| `'openai'` | `OPENAI_API_KEY` | `gpt-4o` |
+| `'openrouter'` | `OPENROUTER_API_KEY` | `openai/gpt-4o` |
+| `'anthropic'` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| `'google'` | `GOOGLE_API_KEY` | `gemini-2.0-flash` |
+| `'typesafe'` | `TYPESAFE_API_KEY` | `jev-latest` |
+
+`'anthropic'` and `'google'` are registry rows whose adapters are not implemented yet: the client builds and `describe()` answers, but every execution method throws `E_PROVIDER_ERROR` (`E_MISSING_API_KEY` first when no key is set; `count()`, which never reaches the adapter, still works). Reach those models through `'openrouter'`.
 
 ### Known Provider with Options
 
@@ -73,7 +87,7 @@ const signal = createSignal({
 });
 ```
 
-Any OpenAI-compatible API works.
+Any OpenAI-compatible API works. A custom provider is outside the registry, so it states what it does itself — `capabilities` (a `Partial<Capabilities>`; unstated fields are `false`) and, optionally, `wire` strategy ids. `adapter` defaults to `'openai-compatible'`.
 
 ---
 
@@ -115,7 +129,7 @@ signal.history(previousMessages)
 ```
 
 ### `.retries(count)`
-Set max validation retries (default: 2). When a response fails Zod validation, Signal feeds the error back to the model and tries again.
+Set max validation retries (default: 2). When a response fails Zod validation, Signal feeds the error back to the model and tries again; once the retries are spent the call fails with `E_VALIDATION_FAILED`.
 ```typescript
 signal.retries(3)
 ```
@@ -127,7 +141,7 @@ signal.apiKey('gsk_...')
 ```
 
 ### `.options(opts)`
-Set LLM options (temperature, maxTokens, etc.). These are rarely needed.
+Set LLM options: `temperature`, `maxTokens`, `topP`, `stopSequences`, `seed`, `signal` (an `AbortSignal`), `reasoningEffort`. Merged over any options already set. These are rarely needed.
 ```typescript
 signal.options({ temperature: 0 })
 ```
@@ -144,10 +158,11 @@ createSignal('groq').describe()
 // { provider: 'groq', model: 'qwen/qwen3.8-27b', kind: 'chat', modelKnown: true, capabilities: {…} }
 ```
 A `reasoningEffort` the model's row does not list is refused when the
-client is built (`SignalError`), not by a provider 400 mid-run.
+client is built (`SignalError`, `E_VALIDATION_FAILED`), not by a provider 400
+mid-run. An unmeasured model is not checked.
 
 ### `.onRetry(handler)`
-Hook called on each validation retry.
+Hook called on each validation failure, including the last one that exhausts the retries.
 ```typescript
 signal.onRetry((error, attempt) => console.log(`Retry ${attempt}:`, error.message))
 ```
@@ -179,9 +194,39 @@ await signal.complete([
 ]);
 ```
 
-### `.stream(input)`
+### `.stream(input, options?)`
+
+The same run as `complete()`, delivered as it happens. Returns `AsyncIterable<StreamEvent<T>>`; `options.signal` (an `AbortSignal`) aborts it.
+
+```typescript
+for await (const event of signal.stream('Tell me a story')) {
+  if (event.type === 'text') process.stdout.write(event.text);
+  if (event.type === 'done') console.log(event.meta.usage);
+}
+```
+
+```typescript
+type StreamEvent<T> =
+  | { type: 'text'; text: string }
+  | { type: 'tool_start'; name: string; args: unknown }
+  | { type: 'tool_end'; name: string; result: unknown }
+  | { type: 'retry'; reason: string; attempt: number }
+  | { type: 'error'; error: Error; recovered: boolean }
+  | { type: 'done'; response: T; history: Message[]; meta: SignalMeta };
+```
+
+Schema validation happens at the end of the stream; when the retries are spent the stream ends with an `error` event (which `complete()` throws).
+
+### `.step(request)` / `.stepStream(request, options?)`
+
+The low-level primitives `complete()` and `stream()` are built on: one model call, no tool execution, no schema retries. The caller owns the loop. `step()` takes a `StepRequest` (`messages`, `tools`, `toolChoice`, `output`, `responseFormat`, `options`) and returns a `StepResult` (`content`, `toolCalls`, `usage`, `finishReason`, `raw`, and — when the request carried `output.accept` — the routed `outcome` and `wire` report). `stepStream()` yields `text`, `reasoning` and `tool_call_delta` events and a final `done` carrying the `StepResult`.
 
-Not yet implemented. Will return `AsyncIterable<StreamEvent<T>>`.
+### `.count(input)`
+
+Rough token count for a string or a message list. A heuristic (about 4 characters per token), not a tokenizer.
+```typescript
+const tokens = await signal.count('How long is this?');
+```
 
 ---
 
@@ -209,12 +254,14 @@ type SignalMeta = {
   retries: number;                  // validation retries that occurred
   toolCalls: ToolCallRecord[];      // tools called, args, results, timing
   provider: {
-    raw: unknown;                   // raw API response for debugging
-    errors: ProviderError[];        // all errors including recovered ones
+    raw: unknown;                   // null: these calls read the reply as a stream, which leaves no body to keep (an array, one entry per call, when the run took several)
+    errors: ProviderError[];        // currently always empty
   };
 };
 ```
 
+`step()` returns the provider's response body as its `raw`. Where a provider rejected a call and Signal recovered the attempt from the rejection, that call's `raw` is the provider's error.
+
 ---
 
 ## Structured Output
@@ -237,15 +284,15 @@ const { response } = await createSignal('groq')
 
 ### How It Works
 
-1. Zod schema is converted to JSON Schema via `z.toJSONSchema()`
-2. Based on provider capabilities:
-   - `nativeJsonSchema` → sends JSON Schema as `response_format`
-   - `nativeJsonMode` → sends `response_format: json_object` + schema in system prompt
-   - Neither → schema in system prompt only
-3. Response is parsed as JSON
+1. Zod schema is converted to JSON Schema (draft-07)
+2. Based on capabilities:
+   - `nativeJsonSchema` (and, when tools are set, `toolsWithStructuredOutput`) → sends JSON Schema as `response_format`
+   - otherwise `nativeJsonMode` and no tools → sends `response_format: json_object` + schema in a system message
+   - otherwise → schema in a system message only
+3. The response is normalized by the wire layer (JSON extraction and repairs, each counted only if the result passes the schema)
 4. Validated with `schema.safeParse()`
-5. On failure: Zod errors are sent back to the model as a correction message
-6. Retries up to `retries` times (default: 2)
+5. On failure: the evidence is sent back to the model as a correction message
+6. Retries up to `retries` times (default: 2), then fails with `E_VALIDATION_FAILED`
 7. Returns typed, validated result
 
 ---
@@ -271,7 +318,9 @@ const searchTool = defineTool({
 });
 ```
 
-The Zod `input` schema validates the model's arguments before `execute` runs. The return value is stringified and sent back to the model.
+The Zod `input` schema validates the model's arguments before `execute` runs. The return value is stringified and sent back to the model. A call to an unknown tool, arguments that fail the schema, and an `execute` that throws do not fail the run: each goes back to the model as an `error: …` tool result (and is recorded in `meta.toolCalls`).
+
+The model is sent the `input` schema as JSON Schema, taken from the schema's output side, so an `input` schema validates and does not convert. One with no JSON Schema (a `.transform()`, a `z.date()`) rejects the call before any request is made, with Zod's own error (`Transforms cannot be represented in JSON Schema`) rather than a `SignalError`. One whose output is another kind than its input (`z.stringbool()`) is described to the model by its output: told `boolean`, a model that sends one gets `input_invalid` back, and it is the string (`"true"`) that is accepted. Convert inside `execute`.
 
 ### Using Tools
 
@@ -287,17 +336,15 @@ const { response, meta } = await createSignal('groq')
 
 ### How Tool Calling Works
 
-Signal picks a strategy based on provider capabilities:
-
-**Native tools** (OpenAI) — Uses the provider's native `tools` parameter and `tool_calls` response. The model decides when to call tools.
-
-**Unified schema** (Groq, others) — Tool descriptions are injected into the system prompt. The response format includes a discriminator field (`_action: "call" | "respond"`). Signal handles the loop:
+Tools use the provider's native `tools` parameter and `tool_calls` response; the model decides when to call them. A provider without `nativeTools` cannot take tools — the call throws `E_PROVIDER_ERROR`. Signal handles the loop:
 
-1. Model responds with `_action: "call"` + tool name + args
+1. Model responds with tool calls
 2. Signal validates args with Zod, executes the tool
 3. Tool result is sent back to the model
-4. Model responds with `_action: "respond"` + final answer
-5. Final answer is validated against the output schema
+4. Model responds with the final answer
+5. With a schema set, the final answer is validated against it
+
+Where the model cannot combine `response_format` with tools (`toolsWithStructuredOutput: false`, e.g. Groq), the schema rides a system message instead and is validated client-side. A run that is still calling tools after 10 tool turns (plus the retry budget) fails with `E_MAX_ITERATIONS`.
 
 ---
 
@@ -348,6 +395,14 @@ const small = await embedder.embed('text', { dimensions: 256 });
 // small: number[256]
 ```
 
+### Usage
+
+`embed()` returns vectors only. To read what the call cost, pass `onUsage` — called after a successful call with the provider's usage and the model that resolved:
+
+```typescript
+await embedder.embed('text', { onUsage: (usage, model) => meter(model, usage.totalTokens) });
+```
+
 ### Similarity
 
 Cosine similarity between embedding vectors measures semantic relatedness:
@@ -369,7 +424,7 @@ const similarity = cosine(a, b);
 
 ### Provider Support
 
-Only providers with `supportsEmbedding: true` can embed. Currently: **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`). Calling `embed()` on a provider without support throws `E_PROVIDER_ERROR`.
+`embed()` does not check `supportsEmbedding`: the flag is what `describe()` reports, and the request goes to the provider's embeddings endpoint either way. Of the known providers only **OpenAI** is marked as having one (`text-embedding-3-small`, `text-embedding-3-large`). An endpoint that refuses the request surfaces as `E_PROVIDER_ERROR` (`Embedding error: …`, the provider's own error under `context.raw`). A decision provider and the two adapters that are not implemented fail before any request is made.
 
 Use a separate Signal client for embedding — embedding models are different from chat models:
 
@@ -468,12 +523,10 @@ All errors are `SignalError` instances with a `.code` and optional `.context`:
 | `E_MISSING_API_KEY` | No API key found (env or explicit) |
 | `E_MISSING_MODEL` | No model specified for custom provider |
 | `E_MISSING_SDK` | Provider SDK not installed |
-| `E_VALIDATION_FAILED` | Response failed Zod validation after all retries |
-| `E_MAX_RETRIES` | Retry loop exhausted |
-| `E_PROVIDER_ERROR` | Provider API error (rate limit, server error, etc.) |
-| `E_TOOL_NOT_FOUND` | Model called an unknown tool |
-| `E_TOOL_EXECUTION` | Tool execute() threw |
-| `E_TOOL_VALIDATION` | Tool args failed Zod validation |
+| `E_VALIDATION_FAILED` | Response failed Zod validation after all retries; a `decide()` answer failed its gate; a `reasoningEffort` the model does not take |
+| `E_MAX_ITERATIONS` | The tool loop did not finish within its turn limit |
+| `E_PROVIDER_ERROR` | Provider API error (rate limit, server error, a refused `embed()`, etc.); tools on a provider without `nativeTools`; an adapter that is not implemented |
+| `E_MAX_RETRIES`, `E_TOOL_NOT_FOUND`, `E_TOOL_EXECUTION`, `E_TOOL_VALIDATION` | Declared in `ErrorCode`, not currently thrown — tool failures go back to the model as tool results, and exhausted retries are `E_VALIDATION_FAILED` |
 | `E_VERB_NOT_SUPPORTED` | A chat verb was called on a decision provider |
 
 ```typescript
@@ -494,7 +547,7 @@ try {
 
 Groq is fast and cheap but has quirks:
 
-- **No native tools + structured output together.** Signal uses the unified schema strategy automatically.
+- **No native tools + structured output together.** With tools set, Signal sends no `response_format` there; the schema rides a system message and is validated client-side.
 - **`json_validate_failed` errors.** Groq sometimes returns the model's failed output in the error. Signal extracts and recovers from this.
 - **Model-dependent capabilities.** What each Groq model does (json_schema, nested tool args, reasoning efforts) is its own row in the model registry, measured by the probe.
 - **Tool args are validated server-side.** So `respond` params would enforce nothing on Groq, and `auto` resolves every agent there to `emit`.

package/README.md

@@ -53,6 +53,8 @@ signal.schema(zodSchema)           // typed structured output
 signal.tools([myTool])             // tool calling
 signal.history(messages)           // multi-turn
 signal.retries(3)                  // validation retries
+signal.options({ temperature: 0 }) // sampling / generation options
+signal.apiKey(key)                 // override the env key
 signal.describe()                  // provider, model, capabilities — from the registry
 signal.onRetry(handler)            // retry hook
 signal.onToolCall(handler)         // tool call hook
@@ -114,4 +116,4 @@ API keys are read from environment variables (`GROQ_API_KEY`, `OPENAI_API_KEY`,
 
 ## License
 
-MIT
+Apache-2.0

package/dist/index.cjs

@@ -1502,9 +1502,9 @@ var createSignalFromConfig = (config) => {
     });
     return { ...result, outcome: routed.outcome, wire: routed.wire };
   };
-  const stepStream = (request, streamOptions) => {
+  const stepStreamAs = (verb) => (request, streamOptions) => {
     const run = async function* () {
-      const adapter = await getChatAdapter("stepStream");
+      const adapter = await getChatAdapter(verb);
       const resolved = resolveProvider(config);
       const declared = new Set((request.tools ?? []).map((tool) => tool.name));
       const merged = config.options !== void 0 || request.options !== void 0 ? { ...request, options: { ...config.options, ...request.options } } : request;
@@ -1544,6 +1544,7 @@ var createSignalFromConfig = (config) => {
     };
     return run();
   };
+  const stepStream = stepStreamAs("stepStream");
   const decideCalibrated = async (adapter, model, request, started) => {
     const response = await adapter.decide(
       { model, state: request.state, questions: request.questions },
@@ -1631,7 +1632,7 @@ var createSignalFromConfig = (config) => {
         onRetry: config.onRetry,
         onToolCall: config.onToolCall
       },
-      { stepStream, model: resolveProvider(config).model, capabilities: resolveCapabilities(config) }
+      { stepStream: stepStreamAs("complete"), model: resolveProvider(config).model, capabilities: resolveCapabilities(config) }
     ),
     stream: (input, streamOptions) => runStream(
       {
@@ -1644,7 +1645,7 @@ var createSignalFromConfig = (config) => {
         onRetry: config.onRetry,
         onToolCall: config.onToolCall
       },
-      { stepStream, model: resolveProvider(config).model, capabilities: resolveCapabilities(config) }
+      { stepStream: stepStreamAs("stream"), model: resolveProvider(config).model, capabilities: resolveCapabilities(config) }
     ),
     // ─── Low-level primitives — the execution core itself ────
     step,