Skip to content

Conversation

monotykamary
Copy link
Contributor

  • What kind of change does this PR introduce?
    Feature — foundational Zod schema integration across Ax signatures, runtime validation, and developer tooling.

  • What is the current behavior? (You can also link to an open issue here)
    Signatures must be authored manually. Existing Zod schemas are not reusable inside Ax, Zod validations never run during generation, and there’s minimal telemetry when features are downgraded. This gap is highlighted in feat: add comprehensive zod schema support #388 and issue Standard Schema for Signature Input/Output? #348 (“Standard Schema for Signature Input/Output?”).

  • What is the new behavior (if this is a feature change)?

    • Introduces AxSignature.fromZod/toZod for bidirectional conversion with downgrade telemetry, strict-mode enforcement, and metadata captured in AxZodRegistry.
    • Allows programs (AxProgram, AxGen, template.ax, etc.) to accept raw Zod schemas, wiring options such as parsing mode, assertion level, and streaming intent through AxZodSignatureOptions.
    • Auto-registers Zod-backed assertions in AxGen, applying .parse/.safeParse/.catch/.default semantics to LLM outputs and aligning downgrade notes with runtime validation failures.
    • Adds helpers like AxSignature.debugZodConversion, getZodConversionIssues, and reportZodConversionIssues for auditing schema fidelity.
    • Provides documentation (docs/ZOD_INTEGRATION.md), SIGNATURES guide updates, and deterministic examples (OpenAI generation, runtime repair, round-trip stories) to demonstrate migration paths and workflows without API keys.
    • Expands the unit suite to cover round-trips, defaults/catches, downgrade reporting, streaming repair scenarios, and AxGen/Zod constructor ergonomics.
    • Makes Zod a peer-focused dependency so downstream packages can opt in without bundling it twice.
  • Other information:

    • Full workspace checks (npm install, which triggers lint, format, type-check, unit, and spelling tasks) pass locally.
    • Streaming-time validation remains a TODO; assertions currently run on final outputs with forward-compatible hooks in place.
    • Outstanding npm advisories: 8 vulnerabilities (1 low, 7 moderate) reported by the lockfile; no functional impact observed, but we can iterate via npm audit fix separately.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant