@symplek/core 0.0.0-stage → 1.0.0-beta.2

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+## 1.0.0-beta.2
+
+### Patch Changes
+
+- 91ca43f: First public beta. Everything since the internal `1.0.0-beta.1` milestone, which was never published.
+
+  **@symplek/core, added**
+  - OpenTelemetry export: `configureOpenTelemetry()`, `exportTraces()` and `shutdownOpenTelemetry()` emit spans with `gen_ai.*` attributes. The OTel packages are optional peer dependencies.
+  - `.reflect()` operator for critique and improvement loops driven by agents you supply.
+  - Idempotency keys on `AgentUnit.run()` with an injectable `IdempotencyStore`. Concurrent runs on the same key execute once. If the work succeeds but the store write fails, the run raises `IdempotencyStoreWriteError` instead of inviting a retry. At-most-once holds while the store is available.
+  - Subpath exports: `@symplek/core/confidence`, `/coherence`, `/interview`, `/change-kernel`, `/operators` and `/rehearsal`.
+  - `converge` accepts `mergeStrategy: "last" | "reduce"`.
+  - Provider SDKs load on first use, so `@symplek/core/server` only needs the SDK for the provider you call. A missing SDK raises a `PROVIDER_ERROR` naming the package to install.
+  - Zod 4 is supported alongside Zod 3. The `zod` peer range is `^3.25.28 || ^4.0.0`.
+
+  **@symplek/core, fixed**
+  - `Symplek.configure()` now takes effect (it was a silent no-op). It falls back to the provider's conventional environment variable when no `apiKey` is given, never pairs a key with a provider it was not supplied for, and a newer call supersedes an older bootstrap still in flight.
+  - A provider API key in the environment is enough to run. `ai()`, `Symplek()`, `stream()` and agents (`Symplek.agent()`) load the matching provider on first use with no `configure()` call. Reaching for a second provider by id does not change the default one.
+  - `ai(prompt, { schema })` tells the model the schema. The JSON Schema for the Zod type is sent with the request, where before the model was asked for JSON and never shown the fields.
+  - Schemas with arrays, enums, unions, literals and nullable fields are converted in full. The previous converter dropped every field that was not a string, number, boolean or object.
+  - The Anthropic adapter returns the answer when the reply begins with a thinking block, which is what current Claude models send. It used to return an empty string. Its default output cap is 16000 tokens, and a refusal is reported as a `content_filter` finish.
+  - A refused request, or one that spends its output limit before any answer is written, throws `PROVIDER_ERROR` from `ai()`, `Symplek()`, `stream()` and agents (`Symplek.agent()`). It used to come back as an empty string that read as a reply.
+  - Default models are current: `claude-opus-5-5`, `claude-sonnet-5-5` and `claude-haiku-5-5` for Anthropic, `gemini-3.8-flash` and `gemini-3.5-flash-lite` for Google, `gpt-4o` and `gpt-4o-mini` for OpenAI. The previous Google defaults and the Anthropic fast default were ids the providers no longer serve.
+  - `require("@symplek/core")` and `require("@symplek/core/server")` share one copy of the code. Each CommonJS entry point used to carry its own, so a provider configured through one was invisible to the other.
+  - Each module format has its own type declarations, so a CommonJS project under `node16` resolution type-checks.
+  - Coordination operators no longer print the legacy-mode deprecation warning for callers who never chose legacy mode.
+  - API keys are removed from error messages and from the attached `cause`, in every occurrence.
+  - Default model selection follows the provider actually in use, so Anthropic and Google callers no longer receive OpenAI model ids.
+  - Anthropic streaming reports accurate token totals.
+  - Options that were accepted and ignored now apply: `timeout` and `retry` when a schema is given, `provider`, `system` and `temperature` on `Symplek.agent`, `SymplekOptions.confidence`, and `StreamOptions.signal`.
+  - Consensus cancels losing voters when a vote times out and does not start work for a caller that has already cancelled.
+  - Compensation and saga rollback report every failed undo, not only the first.
+  - Interview converges: answers populate the context, corrections replace earlier answers, and extraction validates against the schema. Creating an interview without a `contextSchema` throws.
+  - Replay reports a tampered trace. An edited event throws `ReplayDivergenceError`, and an edited output comes back with `matched: false`.
+  - A recorded model call stores the hash that replay compares it against, so replaying an unchanged call no longer logs a mismatch.
+  - Consultation enforces its latency budget while a specialist is running and no longer drops unavailable required specialists silently.
+  - Lock `extend()` writes a new entry, and in-memory lock state is per instance.
+  - Traces are no longer handed between concurrent callers through process-global state, and what is recorded matches the documented contract.
+  - `retry(0)`, non-finite vote confidences and non-positive round limits fail early or are clamped instead of propagating `undefined` or `NaN`.
+  - `sanitizeContext` handles circular objects and redacts inside arrays.
+
+  **@symplek/core, changed**
+  - `TrackedResult` values cannot be forged by constructing a look-alike object.
+  - `zod-to-json-schema` is a runtime dependency. It converts Zod 3 schemas; Zod 4 schemas use Zod's own converter.
+  - The debug cost line prints an estimate only for models with a known list price, and no figure otherwise.
+  - `openrouter` is not offered as a provider until it has a working adapter.
+  - The in-memory idempotency cache expires entries after one hour by default.
+
+  **@symplek/pro**
+  - Confidence, coherence, change-kernel, interview and the operators now re-export `@symplek/core` behind the license gate, replacing copies that had drifted from it.
+  - Importing without a license key fails with an error that names the one thing that fixes it: set `SYMPLEK_PRO_LICENSE_KEY` before the import. A malformed key gets its own error, which no longer echoes part of the key.
+  - TaCo consensus treats agreement as voters agreeing with each other, so a unanimous rejection converges.
+  - The antibody scanner gives the same verdict on the same input when a pattern carries the `g` flag.
+  - Stigmergy rejects evaporation rates that produced `NaN` confidence.
+  - The trust registry returns copies, so inspecting a grant cannot change it.
+  - `@symplek/core` is a caret peer range, where it used to pack as an exact version pin.
+  - A `test` script so the package's suite runs in CI.
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0-beta.1] - 2026-04-13
+
+### Added
+
+- **OC-0**: Initial package structure with AgentUnit algebra extracted from Convex source.
+- **OC-0**: Tier boundary enforcement separating open-core surfaces from Convex-internal code.
+- **OC-1**: Weft namespace facade (`Weft.stream`, `Weft.agent`, `Weft.configure`, `Weft.providers`).
+- **OC-1**: WeftBuilder and AgentBuilder connected to the public API.
+- **OC-1**: Golden-path test suite with 25 passing tests.
+- **OC-1**: Quickstart documentation.
+- **OC-2 DX**: `WeftError` messages include `[weft@VERSION]` prefix for self-identifying stack traces.
+- **OC-2 DX**: Debug mode (`ai.debug = true`) logs one-line trace per AI call to stderr.
+- **OC-2 DX**: Provider adapters surface missing API key as `WeftError` with `code: PROVIDER_ERROR`, `why`, `fix`, and `example` fields.
+- **OC-2 DX**: JSDoc `@example`, `@param`, `@returns` added to all public `AgentUnit` methods and exported functions.
+- **OC-2 PKG**: Package metadata complete for npm discoverability (`keywords`, `description`, `engines`).
+
+### Changed
+
+- **OC-0**: Import path cleanup for published package layout and consumer ergonomics.
+
+[Unreleased]: https://github.com/wefthq/weft/compare/weft-core@1.0.0-beta.1...HEAD
+[1.0.0-beta.1]: https://github.com/wefthq/weft/releases/tag/weft-core@1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Symplek Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,241 @@
-# Temporary Holding Version
+# @symplek/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Composable AI agents for TypeScript. Free, MIT-licensed.**
+
+[![npm](https://img.shields.io/npm/v/@symplek/core)](https://www.npmjs.com/package/@symplek/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)
+
+---
+
+## Install
+
+```bash
+pnpm add @symplek/core zod
+# or
+npm install @symplek/core zod
+```
+
+Node 20 or later. `zod` is a required peer (3.25.28 or later, or 4.x). Schemas from either generation work at runtime. One typing gap: with zod 3.25 installed, a schema built from `zod/v4` does not type-check against the `schema` option, so install zod 4 if you write Zod 4 schemas.
+
+To call a model you also need that provider's SDK and its API key:
+
+| Provider | SDK to install | Key in the environment |
+|---|---|---|
+| `openai` | `openai` | `OPENAI_API_KEY` |
+| `anthropic` | `@anthropic-ai/sdk` | `ANTHROPIC_API_KEY` |
+| `google` | `@google/generative-ai` | `GOOGLE_GENERATIVE_AI_API_KEY` |
+
+The composition operators need none of that. They work on any async function.
+
+---
+
+## Working in 3 lines
+
+```typescript
+import { Symplek } from "@symplek/core/server";
+
+Symplek.configure({ provider: "openai", apiKey: process.env.OPENAI_API_KEY });
+const result = await Symplek("List three benefits of TypeScript");
+console.log(result.value); // "1. Static typing catches errors early..."
+```
+
+With the key already in the environment you can skip `configure()`. Symplek finds the key and loads the matching provider on the first call. If more than one provider key is set, it takes the first of OpenAI, Anthropic, Google.
+
+> `@symplek/core/server` loads provider SDKs, so it is Node.js only. Browser-safe exports live at `@symplek/core`.
+
+---
+
+## What you get
+
+- **Lazy units.** `AgentUnit<T>` builds a computation chain and runs nothing until `.run()` is called.
+- **Parallel execution.** `AgentUnit.zipAll([a, b, c])` runs units side by side and returns the results in order.
+- **Single-round consensus.** `.consensus([voter1, voter2, voter3])` polls the voters and tallies the vote. Every voter counts equally unless you pass `weights`; a voter's own `confidence` is recorded, not used as its weight.
+- **Resilience operators.** `.retry(3)`, `.timeout(5000)` and `.fallback(backup)` compose on any unit.
+- **A result envelope.** Every `.run()` returns a `TrackedResult<T>`: your value plus a source label and a confidence figure. Read [what those fields mean](#what-run-gives-you-back) before relying on them.
+- **Structured output.** Pass a Zod schema and get a validated object back.
+- **Streaming.** `Symplek.stream(task)` returns an `AsyncGenerator<string>` of output chunks.
+
+---
+
+## From simple to multi-agent
+
+### Step 1: one agent
+
+```typescript
+import { Symplek } from "@symplek/core/server";
+
+Symplek.configure({ provider: "openai", apiKey: process.env.OPENAI_API_KEY });
+
+const result = await Symplek("What is the capital of France?");
+console.log(result.value); // "Paris"
+```
+
+### Step 2: agents in parallel
+
+```typescript
+import { Symplek, AgentUnit, createContext } from "@symplek/core/server";
+
+const ctx = createContext();
+
+const result = await AgentUnit.zipAll([
+  Symplek.unit(async () => "low risk"),
+  Symplek.unit(async () => "proceed"),
+]).map(([analysis, recommendation]) => ({ analysis, recommendation })).run(ctx);
+
+console.log(result.value); // { analysis: "low risk", recommendation: "proceed" }
+```
+
+`Symplek.unit(fn)` is the same as `AgentUnit.from(fn)`, reachable from the namespace you already imported.
+
+### Step 3: consensus vote
+
+```typescript
+import { Symplek, createContext } from "@symplek/core/server";
+
+const ctx = createContext();
+
+// Start from a Symplek(task) call and move into coordination with .coordinate()
+const voted = await Symplek("Should we ship the feature?")
+  .coordinate()
+  .consensus([
+    (_) => ({ decision: "approve" as const, confidence: 0.9 }),
+    (_) => ({ decision: "approve" as const, confidence: 0.8 }),
+    (_) => ({ decision: "reject" as const,  confidence: 0.6, reasoning: "Needs more testing" }),
+  ])
+  .run(ctx);
+
+console.log(voted.value.approved);  // true
+console.log(voted.value.consensus); // "reached"
+```
+
+Or start from a plain value with `Symplek.of`:
+
+```typescript
+const voted = await Symplek.of("Ship the feature")
+  .consensus([voter1, voter2, voter3])
+  .run(ctx);
+```
+
+### Step 4: resilience
+
+```typescript
+import { Symplek, createContext } from "@symplek/core/server";
+
+const ctx = createContext();
+
+type Reply = { cached: boolean; result: string };
+
+const robust = Symplek
+  .unit<Reply>(async () => callExternalAPI())
+  .retry(3)
+  .timeout(10_000)
+  .fallback(Symplek.of<Reply>({ cached: true, result: "default response" }));
+
+const result = await robust.run(ctx);
+```
+
+`.timeout()` stops waiting after the deadline. It does not cancel the work underneath. The fallback has to produce the same type as the unit it backs up.
+
+---
+
+## Structured output
+
+Pass a Zod schema and the reply comes back parsed and validated:
+
+```typescript
+import { ai } from "@symplek/core/server";
+import { z } from "zod";
+
+const Review = z.object({
+  sentiment: z.enum(["positive", "negative"]),
+  tags: z.array(z.string()),
+});
+
+const review = await ai("Classify this review: fast delivery, great fit", { schema: Review });
+console.log(review.sentiment); // "positive"
+```
+
+Symplek sends the model the JSON Schema for your Zod type, asks for JSON only, then validates the reply. A reply that does not match throws a `SymplekError` with code `INVALID_SCHEMA`. Nothing forces the model to comply beyond that instruction (plus JSON mode on the providers that have one), so plan for the error on weaker models.
+
+---
+
+## Which model runs
+
+Set one yourself and that is the one that runs: `Symplek.configure({ model })`, or the `model` option on a call.
+
+If you set none, Symplek picks from a built-in table:
+
+| Provider | Default | `quality: "high"` | `quality: "fast"` |
+|---|---|---|---|
+| `openai` | `gpt-4o-mini` | `gpt-4o` | `gpt-4o-mini` |
+| `anthropic` | `claude-sonnet-5-5` | `claude-opus-5-5` | `claude-haiku-5-5` |
+| `google` | `gemini-3.8-flash` | `gemini-3.8-flash` | `gemini-3.5-flash-lite` |
+
+One thing to know about before it shows up on a bill. With no model and no `quality` set, a prompt longer than 500 characters, or one containing "analyze", "complex", "reason", "think", "evaluate", "summarize" or "extract", is sent to the `high` column. Set `model` or `quality` if you want to decide that yourself.
+
+Providers retire model ids. If a default stops working, set `model` explicitly and upgrade when a release updates the table.
+
+Two provider behaviours worth knowing. The Anthropic adapter does not forward `temperature` or `topP`, because current Claude models reject them. When a provider declines a request, the call throws `PROVIDER_ERROR`. Reaching the output limit before writing any answer text also throws `PROVIDER_ERROR`. A call that stops normally before writing any text returns an empty string.
+
+---
+
+## What `.run()` gives you back
+
+`.run(ctx)` resolves to a `TrackedResult<T>`: `value`, `source`, `confidence`, `sourceChain` and `minChainConfidence`.
+
+Be clear about what the numbers are:
+
+- `source` is `"agent"` for everything `.run()` produces. `.tracked({ source, confidence })` attaches your own label, which you then read at `result.value.source`: the outer envelope still says `"agent"`.
+- `confidence` starts at 0.85 and moves by a fixed amount per operator in the chain (for example +0.10 for `consensus`, -0.05 for `retry`). It never looks at the output.
+- `objectiveConfidence`, on consensus and debate results, is the figure calculated from the votes themselves.
+
+The [root README](../../README.md#what-run-gives-you-back) has the full table.
+
+---
+
+## Record and replay
+
+`.rehearse()` runs a unit once and records the outcome. `.replay(trace)` returns that stored outcome later without running the unit, after checking the trace has not been altered.
+
+It records the final output, not the steps inside the unit, and replay does not re-run your agent. The [root README](../../README.md#record-and-replay) says exactly what it does and does not do.
+
+---
+
+## Key exports
+
+| Export | From | Description |
+|---|---|---|
+| `AgentUnit` | `@symplek/core` | The lazy unit: `.from()`, `.of()`, `.map()`, `.flatMap()`, `.zipAll()`, `.race()` and the operators above |
+| `createContext` | `@symplek/core` | Creates the `AgentContext` that `.run()` takes. Works with no arguments |
+| `SymplekError` | `@symplek/core` | Structured error with `.code`, `.message` and `.action` |
+| `InMemoryIdempotencyStore` | `@symplek/core` | Idempotency store for `.run(ctx, { idempotency })`. Dedupes side-effecting runs (`reject` or `return-cached`, optional TTL) |
+| `Symplek` | `@symplek/core/server` | The facade: `Symplek(task)`, `.run()`, `.stream()`, `.agent()`, `.unit()`, `.of()`, `.configure()`, `.providers()` |
+| `ai` | `@symplek/core/server` | One model call, with an optional Zod `schema` |
+
+---
+
+## Need more?
+
+Everything above is in `@symplek/core` under MIT, along with teams, the solo gate, coherence, confidence, interview, change-kernel, contracts and observability.
+
+[`@symplek/pro`](../symplek-pro/README.md) adds four things, behind a license key:
+
+- **Multi-round TaCo consensus.** Agents see each other's rationale and revote until they converge.
+- **Stigmergic confidence.** Pheromone-style coordination with evaporation and decay.
+- **Agent antibodies.** Scans agent output against registered patterns: reject, warn or quarantine.
+- **Trust registry.** Trusted-traveler lanes with a configurable scan depth per agent.
+
+---
+
+## Links
+
+- [Record and replay](../../docs/ARCHITECTURE.md): what `.rehearse()` and `.replay()` do, and the pieces underneath
+- [Tier boundary](../../docs/tier-boundary.md): what is in `@symplek/core` and what is in `@symplek/pro`
+- [GitHub](https://github.com/symplek/symplek)
+
+---
+
+## License
+
+MIT

package/dist/agent/index.cjs

@@ -0,0 +1,20 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+var _chunkIJP2U2XScjs = require('../chunk-IJP2U2XS.cjs');
+
+// src/agent/tool.ts
+function tool(config) {
+  return config;
+}
+
+
+
+
+
+
+
+exports.DEFAULT_LOOP_OPTIONS = _chunkIJP2U2XScjs.DEFAULT_LOOP_OPTIONS; exports.ToolApprovalRequiredError = _chunkIJP2U2XScjs.ToolApprovalRequiredError; exports.createToolApprovalComputation = _chunkIJP2U2XScjs.createToolApprovalComputation; exports.createToolApprovalGateComputation = _chunkIJP2U2XScjs.createToolApprovalGateComputation; exports.stopWhen = _chunkIJP2U2XScjs.stopWhen; exports.tool = tool;

package/dist/agent/index.d.cts

@@ -0,0 +1,3 @@
+export { bk as DEFAULT_LOOP_OPTIONS, bl as LoopExecuteOptions, bm as LoopOperatorOptions, aa as LoopOptions, bn as StepInfo, bo as StepModifications, a9 as Tool, bj as ToolApprovalPayload, bp as stopWhen, bq as tool } from '../runStandalone-Dql9RPr8.cjs';
+export { T as ToolApprovalPending, b as ToolApprovalRequiredError, d as createToolApprovalComputation, e as createToolApprovalGateComputation } from '../index-idgX6aVg.cjs';
+import 'zod';

package/dist/agent/index.d.ts

@@ -0,0 +1,3 @@
+export { bk as DEFAULT_LOOP_OPTIONS, bl as LoopExecuteOptions, bm as LoopOperatorOptions, aa as LoopOptions, bn as StepInfo, bo as StepModifications, a9 as Tool, bj as ToolApprovalPayload, bp as stopWhen, bq as tool } from '../runStandalone-Dql9RPr8.js';
+export { T as ToolApprovalPending, b as ToolApprovalRequiredError, d as createToolApprovalComputation, e as createToolApprovalGateComputation } from '../index-BiYShIGN.js';
+import 'zod';

package/dist/agent/index.js

@@ -0,0 +1,20 @@
+import {
+  DEFAULT_LOOP_OPTIONS,
+  ToolApprovalRequiredError,
+  createToolApprovalComputation,
+  createToolApprovalGateComputation,
+  stopWhen
+} from "../chunk-XSO3HG4U.js";
+
+// src/agent/tool.ts
+function tool(config) {
+  return config;
+}
+export {
+  DEFAULT_LOOP_OPTIONS,
+  ToolApprovalRequiredError,
+  createToolApprovalComputation,
+  createToolApprovalGateComputation,
+  stopWhen,
+  tool
+};