@sembl/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sembl 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

@@ -0,0 +1,103 @@
+# @sembl/core
+
+Runtime for SEMBL — semantic coercion for TypeScript. Describe what a type
+*means*, and turn unstructured input into a validated instance of it.
+
+```ts
+const draft = await sembl(listingHtml).partialCoerceTo(StayDetailsSchema);
+```
+
+This package holds the decorators, the runtime schema types, the coerce API,
+validation, and tracing. Schemas are produced from your decorated classes by
+[`@sembl/compiler`](https://github.com/nickrunner/sembl/tree/main/packages/compiler);
+the LLM call is made by a provider package
+([Anthropic](https://github.com/nickrunner/sembl/tree/main/packages/provider-anthropic),
+[OpenAI](https://github.com/nickrunner/sembl/tree/main/packages/provider-openai)).
+
+See the [project README](https://github.com/nickrunner/sembl#readme) for the
+full walkthrough.
+
+## Install
+
+```sh
+pnpm add @sembl/core
+pnpm add -D @sembl/compiler
+```
+
+## Describing a type
+
+`@Schema` says what a type is for, `@Describe` what each field means,
+`@Constrain` bounds a value beyond its type, and `@ValuesFrom` says the legal
+values come from somewhere resolved at runtime.
+
+```ts
+import { Schema, Describe, Constrain, ValuesFrom } from "@sembl/core";
+
+@Schema("A short-term rental listing as a host would describe it.")
+export class Listing {
+  @Describe("Display name for the listing.")
+  @Constrain({ maxLength: 40 })
+  name!: string;
+
+  @Describe("Amenities the property offers.")
+  @ValuesFrom("amenities")
+  @Constrain({ maxItems: 5 })
+  amenities!: string[];
+}
+```
+
+## Coercing
+
+`coerce` throws if a required field is missing; `partialCoerce` doesn't, and
+returns `Partial<T>` with nulls stripped — the right one for pre-filling a form
+a human will review. Both throw `CoerceError` on a type mismatch or a violated
+constraint, with a `FieldValidationIssue[]` a form can render per field.
+
+```ts
+import { sembl, SemblConfig } from "@sembl/core";
+
+SemblConfig.configure({
+  provider,
+  bundle,
+  // Called once per distinct source per coercion; you own any caching.
+  enumResolver: async (sourceId) => (await cms.taxonomy(sourceId)).map((d) => d.slug),
+});
+
+const draft = await sembl(listingHtml).partialCoerceTo<Listing>(listingSchema);
+```
+
+If a source backing a **required** field fails to resolve, coercion throws
+`EnumResolutionError` rather than quietly widening the field to a free-form
+string. A source backing only optional fields widens and records a trace event.
+
+## Repair and provenance
+
+`maxRepairAttempts` sends validation failures back to the model with its own
+rejected output and the reasons. It only spends a call when validation actually
+failed:
+
+```ts
+await coerce<Listing>(scrapedHtml, { provider, schema, maxRepairAttempts: 1 });
+```
+
+`partialCoerceWithProvenance` (and its strict sibling) additionally reports how
+well the input supported each field, so a review UI can flag the guesses:
+
+```ts
+const { data, provenance } = await partialCoerceWithProvenance<Listing>(html, {
+  provider,
+  schema,
+});
+// provenance.name → { confidence: "high", evidence: "the Sea Cabin sleeps 6" }
+```
+
+Provenance works by requesting a derived schema that wraps each field as
+`{ value, confidence, evidence }`, then splitting the response apart and
+validating the values against your original schema — no provider is involved.
+Top-level fields only.
+
+## Tracing
+
+Pass `traceSinks` to see prompt construction, schema build, enum resolution,
+the LLM call with token usage, and validation as nested spans. Implement
+`TraceSink` (one `write(span)` method) to forward them anywhere.