softschema 0.1.4__tar.gz → 0.2.1__tar.gz

{softschema-0.1.4 → softschema-0.2.1}/AGENTS.md

@@ -4,16 +4,16 @@ This repo teaches and implements the soft schema pattern.
 
 Start here:
 
-- [Softschema Guide](docs/softschema-guide.md): standalone concept and adoption guide
+- [softschema Guide](docs/softschema-guide.md): standalone concept and adoption guide
   for humans and agents.
-- [Softschema Spec](docs/softschema-spec.md): exact language-neutral artifact format.
-- [Movie page example](examples/movie_page/README.md): complete Python-backed example.
+- [softschema Spec](docs/softschema-spec.md): exact language-neutral artifact format.
+- [Movie Page Example](examples/movie_page/README.md): complete Python-backed example.
 
 softschema ships two interchangeable implementations with the same CLI and library
 surface: Python/Pydantic (`softschema`, `softschema-py`) and TypeScript/Zod
 (`softschema`, `softschema-ts`). They are held to exact behavioral parity: same flags,
-same canonical JSON Schema sidecar, same validation results, so authoring an artifact is
-identical regardless of which you run.
+same canonical compiled JSON Schema, same validation results, so authoring an artifact
+is identical regardless of which you run.
 
 For implementer reference (only when changing a package itself):
 

{softschema-0.1.4 → softschema-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softschema
-Version: 0.1.4
+Version: 0.2.1
 Summary: Soft schema conventions and validation tools for Markdown/YAML artifacts
 Project-URL: Homepage, https://github.com/jlevy/softschema
 Project-URL: Repository, https://github.com/jlevy/softschema
@@ -28,8 +28,24 @@ Description-Content-Type: text/markdown
 
 # softschema
 
+Soft schemas: gradual, practical validation for Markdown/YAML artifacts that mix prose
+and structured data—built for humans and coding agents.
+
 ## Quick Start
 
+Try it anywhere, with nothing installed but [uv](https://docs.astral.sh/uv/) or Node.
+Print the bundled example artifact and its compiled schema, then validate—the artifact
+is fully self-describing, so no flags are needed:
+
+```bash
+uvx softschema@latest docs example-artifact > spirited-away.md
+uvx softschema@latest docs example-schema > movie-page.schema.yaml
+uvx softschema@latest validate spirited-away.md
+```
+
+(Or `npx softschema@latest ...` for the Node implementation; the two are
+interchangeable.)
+
 To set up softschema in a repository with an agent, tell the agent:
 
 > Run `uvx softschema@latest --help` (for the Python implementation) or
@@ -47,13 +63,13 @@ flexible document context and machine-readable values.
 The idea is quite simple, but I’ve found it non-obvious enough that coding agents do not
 come up with this approach themselves.
 
-However if given the information and tools in this repo, soft schemas are unreasonably
+However, if given the information and tools in this repo, soft schemas are unreasonably
 effective. Agents become far better at designing and building complex workflows that mix
 structured and unstructured data, such as document processing, data extraction,
 scientific or financial analyses, and many similar applications.
 
 **Soft schemas** are what we call the general practice.
-**Softschema** is the name of this repository’s Markdown-and-YAML spec and the matching
+**softschema** is the name of this repository’s Markdown-and-YAML spec and the matching
 `softschema` CLI that implements it.
 
 ## How Do Soft Schemas Work?
@@ -135,60 +151,20 @@ Keeping prose and structured values in one artifact is more convenient and
 context-efficient. A reader (human or agent) has only one place to look, and information
 can stay as loose prose until a downstream consumer needs it in more formal schemas.
 
-## What Is This Repo?
-
-This repo is simply:
-
-- A few documents for use by agents, including a [spec](docs/softschema-spec.md)
-  defining soft schema file format conventions for Markdown documents with YAML
-  frontmatter.
-
-- A small CLI (and library) that handles formatting, compilation, validation, and other
-  common workflows on soft schema-style documents.
-
-The CLI can be used directly, as a library, or installed as a skill.
-
-For the full conceptual reference and adoption playbooks, see the
-[Softschema Guide](docs/softschema-guide.md).
-
-## Two Synchronized Implementations
-
-softschema ships **two complete, fully supported implementations** with the same CLI and
-library surface:
-
-- **Python / Pydantic**: [`softschema`](docs/softschema-python-design.md) on PyPI (run
-  as `softschema` or `softschema-py`).
-- **TypeScript / Zod**: [`softschema`](docs/softschema-typescript-design.md) on npm (run
-  as `softschema` or `softschema-ts`).
-
-The TypeScript package is a **synchronized port** of the Python one, held to **exact
-behavioral parity**: equivalent CLI inputs, outputs, and flags; equivalent library APIs;
-the same canonical JSON Schema sidecar (content-identical, with an equal `schema_sha256`
-fingerprint over its canonical JSON); and the same engine-neutral validation results.
-Only idiomatic surface details differ (snake_case ↔ camelCase, Pydantic ↔ Zod).
-Authoring or validating an artifact is identical regardless of which you run, so a team
-can adopt either runtime, or both, without divergence.
-
-The two are **maintained in lockstep**: every behavior change lands in a shared
-golden-test corpus first, then in both packages, and CI fails if their outputs or
-compiled schemas drift.
-They release together under **the same version number** on PyPI and npm.
-See
-[Keeping Python and TypeScript in Parity](docs/development.md#keeping-python-and-typescript-in-parity)
-for the development process and the parity invariants CI enforces, and
-[Publishing](https://github.com/jlevy/softschema/blob/main/docs/publishing.md) for the
-synchronized release.
-
-## Example Artifact Shape
+## The Artifact Shape
 
 The default shape is Markdown with YAML frontmatter.
-Use `softschema.contract` to name the contract for the enclosed payload:
+The `softschema:` block is the self-description quartet: `contract` names the payload
+contract, `schema` points at the compiled JSON Schema (relative to the document),
+`envelope` names the payload key, and `status` sets validation strictness:
 
 ```markdown
 ---
 title: Spirited Away (2001)
 softschema:
   contract: example.movies:MoviePage/v1
+  schema: movie-page.schema.yaml
+  envelope: movie
   status: enforced
 movie:
   title: Spirited Away
@@ -197,153 +173,108 @@ movie:
   mpaa_rating: PG
   directors:
     - Hayao Miyazaki
-  genres:
-    - Animation
-    - Adventure
-    - Family
-  synopsis: >
-    Ten-year-old Chihiro and her parents stumble into a mysterious abandoned town
-    that turns out to be a spirit world. After her parents are transformed into pigs,
-    Chihiro must take a job in a magical bathhouse run by the witch Yubaba and find a
-    way to break the spell so the family can return home.
-  cast:
-    - actor: Rumi Hiiragi
-      character: Chihiro / Sen
-    - actor: Miyu Irino
-      character: Haku
-    - actor: Mari Natsuki
-      character: Yubaba
+  genres: [Animation, Adventure, Family]
   ratings:
-    rotten_tomatoes:
-      critics_percent: 96
-      audience_percent: 96
-      critic_review_count: 225
     imdb:
       score: 8.6
       total_votes: 850000
 ---
 # Spirited Away (2001)
 
-*Spirited Away* is Hayao Miyazaki’s animated fantasy about ten-year-old Chihiro, who
+*Spirited Away* is Hayao Miyazaki's animated fantasy about ten-year-old Chihiro, who
 slips into a spirit world and takes a job in a bathhouse for the gods to free her
 parents from the witch Yubaba.
 It won the 2003 Academy Award for Best Animated Feature.
-
-Rotten Tomatoes shows a 96% Tomatometer from 225 critic reviews and a 96% Popcornmeter
-from the audience; IMDb users give it 8.6 out of 10 across more than 850,000 votes.
-
-<!-- The reader-facing body continues with prose and tables; see the full example. -->
 ```
 
 The YAML payload is authoritative; a consumer reads it.
 The Markdown body overlaps with it but is for human readers: the prose adds context like
-the film’s Academy Award (which no structured field carries), the YAML alone carries
-downstream fields such as `critic_review_count`, and the full example’s body mirrors
-some YAML fields as tables for the reader’s convenience.
+the film’s Academy Award (which no structured field carries), and the full example’s
+body mirrors some YAML fields as tables for the reader’s convenience.
 
-Only the `softschema` block and the chosen envelope key (`movie:` above) are
+Only the `softschema` block and the declared envelope key (`movie:` above) are
 softschema’s concern.
-Additional top-level frontmatter keys, such as the `title:` above (or fields like
-`description:`, `tags:`, or any other host-specific metadata), are a separate concern.
-softschema neither forbids nor interprets them, so an artifact can coexist with whatever
+Additional top-level frontmatter keys, such as the `title:` above (or `description:`,
+`tags:`, or any other host-specific metadata), are a separate concern: softschema
+neither forbids nor interprets them, so an artifact can coexist with whatever
 frontmatter conventions a static-site generator, doc indexer, or other tool already
-expects. When an artifact carries any such extra top-level key, the validator can no
-longer infer the envelope on its own; pass `--envelope` (or set `envelope_key` on the
-registered contract) to designate the payload.
-
-The example illustrates the structural variety a softschema artifact can carry:
-constrained integers (`release_year`, `runtime_minutes`), an enum (`mpaa_rating`
-restricted to `G`, `PG`, `PG-13`, `R`, `NC-17`, `NR`), lists of strings (`directors`,
-`genres`), a list of structured records (`cast`), and nested objects (`ratings`). The
-full artifact, model, and generated JSON Schema live under
-[examples/movie_page/](examples/movie_page/README.md).
-
-## Contract IDs
-
-Recommended style:
-
-```text
-namespace:UpperCamelCaseName/version
-```
-
-Examples:
-
-- `example.movies:MoviePage/v1`
-- `example.docs:IncidentReview/v1`
-- `com.acme.docs:IncidentReview/1.0`
+expects. Because the artifact declares `envelope: movie`, validation still needs no
+flags.
 
-The ID names an artifact payload contract, not a required class or import path.
+Every key after `contract` is optional; a minimal artifact carries `contract` alone and
+binds its schema some other way (a `--schema` flag, or a host registry in library use).
+Contract IDs follow an enforced shape, `[namespace:]Name[/version]`—for example
+`example.movies:MoviePage/v1` or `com.acme.docs:IncidentReview/1.0`—naming a payload
+contract, not a class or import path.
 
-## Try the Python Package
+## Validate
 
-Install dependencies (see [Installation](docs/installation.md) for uv and Python setup):
+A self-describing artifact validates with no flags; flags override the document when you
+need to point a run elsewhere:
 
 ```bash
-uv sync --all-extras
+softschema validate doc.md                              # uses the document's bindings
+softschema validate doc.md --schema candidate.schema.yaml   # try a different schema
+softschema validate doc.md --envelope incident          # designate the payload key
 ```
 
-Validate the example:
+`validate` reports structural (JSON Schema) and semantic (Pydantic/Zod model) results
+separately as deterministic JSON. Semantic validation loads a model with
+`--model module:Class` (Python) or `--model path:export` (Zod)—note that `--model`
+imports and executes local code, so use it only with trusted models; a compiled schema
+via `--schema` executes nothing and is the safe path for untrusted input.
 
-```bash
-uv run softschema validate examples/movie_page/spirited-away.md \
-  --model examples.movie_page.model:MoviePage \
-  --schema examples/movie_page/movie-page.schema.yaml \
-  --envelope movie
-```
+## Install
 
-`validate` reads `softschema.contract` and `softschema.status` from the document.
-`--envelope movie` designates the payload key, which the example needs because the
-artifact also carries a top-level `title:` that softschema does not interpret.
-When an artifact has exactly one non-`softschema` top-level key, that key is inferred as
-the envelope automatically and `--envelope` is unnecessary.
-`--contract` and `--status` override the corresponding `softschema:` fields.
+Two supported ways to consume softschema; pick by use:
 
-Read the bundled docs from the CLI:
+- **Pin it as a dependency** for projects, CI gates, and library use (reproducible,
+  fast, offline, and the only way to `import` it):
 
-```bash
-uv run softschema docs --list
-uv run softschema docs --list --json
-uv run softschema docs guide
-uv run softschema docs example-artifact
-uv run softschema skill --brief
-```
+  ```bash
+  uv add --dev softschema==0.2.1        # Python
+  npm install -D softschema@0.2.1       # Node (or: bun add -d)
+  ```
 
-The examples are plain files under `examples/`. The CLI can print them so an agent or
-human can copy from them, but it does not scaffold or mutate another project.
+- **Zero-install** for one-off checks and agent bootstrap:
 
-Compile the example schema sidecar:
+  ```bash
+  uvx softschema@latest --help
+  npx softschema@latest --help
+  ```
 
-```bash
-uv run softschema compile examples.movie_page.model:MoviePage \
-  --contract example.movies:MoviePage/v1 \
-  --out examples/movie_page/movie-page.schema.yaml
-```
+The rule of thumb: if softschema runs more than once, or in CI, or you import it—pin it.
+For a quick check or an agent bootstrapping with nothing installed, use a zero-install
+runner. See [Installation](docs/installation.md) for details, including the supply-chain
+cool-off that makes `@latest` safe to recommend.
 
-## Try the TypeScript Package
+## Use as a Library
 
-The TypeScript CLI takes the same arguments and emits byte-identical output.
-Validate the same artifact against the same language-neutral schema sidecar with a
-pinned zero-install runner:
+Both packages expose the same surface (idiomatic per language).
+Register contracts at startup and validate at file boundaries:
 
-```bash
-npx softschema@latest validate examples/movie_page/spirited-away.md \
-  --schema examples/movie_page/movie-page.schema.yaml \
-  --envelope movie
+```python
+from pathlib import Path
+from softschema import Contract, Contracts, validate_artifact
+
+registry = Contracts()
+registry.register(Contract(id="mycorp.docs:IncidentReview/v1", model=IncidentReview,
+                           envelope_key="incident"))
+result = validate_artifact(Path("incident.md"),
+                           contract_id="mycorp.docs:IncidentReview/v1",
+                           registry=registry)
 ```
 
-The bundled docs and skill are served identically:
+```ts
+import { validateArtifact } from "softschema";
 
-```bash
-npx softschema@latest docs --list
-npx softschema@latest docs guide
-npx softschema@latest skill --brief
+const result = validateArtifact("incident.md", contract);
 ```
 
-Semantic models are written in Zod instead of Pydantic; everything else (flags, result
-JSON, error records, and the compiled sidecar, down to its `schema_sha256`) matches the
-Python package exactly.
-See the [TypeScript Design](docs/softschema-typescript-design.md) doc for the Zod model
-shape and the full Python ↔ TypeScript API table.
+A host registry’s bindings outrank the document’s own (`softschema.schema`/`envelope`),
+so a document cannot silently redirect a host’s validation; a contract registered
+without a schema path lets self-describing documents bind themselves.
+See the [softschema Guide](docs/softschema-guide.md) for the full playbooks.
 
 ## Use as an Agent Skill
 
@@ -382,31 +313,40 @@ uvx softschema@latest skill --install
 Both mirrors carry a `DO NOT EDIT` marker.
 Re-run `skill --install` to refresh after upgrading the CLI.
 
-## Repository Layout
+## Two Synchronized Implementations
 
-```text
-docs/                  guide, spec, package design (Python + TypeScript), and workflow docs
-examples/movie_page/   complete example with model, host integration, artifact, schema
-examples/parity/       cross-language parity fixture (Pydantic + Zod compile to one schema)
-packages/python/       Python/Pydantic implementation and tests
-packages/typescript/   TypeScript/Zod implementation and tests
-skills/softschema/     agent-facing usage guidance (shared SKILL.md source)
-tests/golden/          shared CLI golden corpus, run against both implementations
-```
+softschema ships **two complete, fully supported implementations** with the same CLI and
+library surface:
+
+- **Python / Pydantic**: [`softschema`](docs/softschema-python-design.md) on PyPI (run
+  as `softschema` or `softschema-py`).
+- **TypeScript / Zod**: [`softschema`](docs/softschema-typescript-design.md) on npm (run
+  as `softschema` or `softschema-ts`).
 
-The root `pyproject.toml` builds the Python package from
-`packages/python/src/softschema`; `packages/typescript` builds the npm `softschema`
-package with bun. The shared golden corpus and the cross-language conformance test keep
-the two implementations byte-for-byte in sync.
+The two are held to **exact behavioral parity**: equivalent CLI inputs, outputs, and
+flags; equivalent library APIs; the same canonical compiled JSON Schema
+(content-identical, with an equal `schema_sha256` fingerprint); and the same
+engine-neutral validation results.
+Every behavior change lands in a shared golden-test corpus first, then in both packages,
+and CI fails if their outputs or compiled schemas drift.
+They release together under the same version number on PyPI and npm.
 
-## Development and Contributing
+## Further Reading
+
+- [softschema Guide](docs/softschema-guide.md): the full mental model and adoption
+  playbooks.
+- [softschema Spec](docs/softschema-spec.md): the exact artifact format and validation
+  rules.
+- [Movie Page Example](examples/movie_page/README.md): the complete example backing the
+  snippets above.
+- [Installation](docs/installation.md): pinned vs zero-install, uv and Node setup.
 
-See [Development](docs/development.md) for repo setup, common commands, CI checks,
-release workflow, and pointers to the installation and publishing docs.
+## Development and Contributing
 
-The Python and TypeScript implementations **must be kept in exact sync**. Any behavior
-change goes through the shared golden corpus first and then lands in both packages; see
-[Keeping Python and TypeScript in Parity](docs/development.md#keeping-python-and-typescript-in-parity).
+Repo setup, common commands, CI checks, the parity process, and the release workflow
+live in [Development](docs/development.md).
+The Python and TypeScript implementations must be kept in exact sync: any behavior
+change goes through the shared golden corpus first and then lands in both packages.
 
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.