diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e44c14..901329f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +## [0.2.0-alpha] - 2026-05-09 + +Second public alpha focused on Java-native structured extraction hardening and +release safety. + +### Added + +- Java-native schema generation for records and simple POJOs, including nested + objects, lists, maps, enums, dates, numbers, Jackson property annotations, and + fail-fast rejection for raw `Object` / unbounded shapes. +- Typed extraction contract tests proving Java records are schema-validated + before deserialization, then retried on repairable provider output. +- Internal mapper support for `Optional` so absent and explicit `null` + values map consistently to `Optional.empty()`. + +### Changed + +- `Optional` now has precise schema semantics: it is omitted from + `required`, and only Optional fields include `null` in their generated type. +- Non-Optional reference fields are strict: explicit JSON `null` is rejected by + local schema validation before typed object mapping. +- Custom dotted field constraints now traverse Optional intermediate values + safely, so caller-owned validation works for optional nested objects. +- CI now requires Spotless, Checkstyle, full recorded verification, integration + tests, and Jacoco coverage gates before merge; release tags verify before + deploying to Maven Central. + +### Fixed + +- Fixed Java typed extraction paths where Optional fields could validate at the + schema layer but fail during runtime object mapping. +- Fixed overly permissive non-Optional object schemas that previously accepted + `null`. + ## [0.1.0-alpha] - 2026-05-09 First public alpha. The audit primitives the Java enterprise stack has been @@ -59,5 +93,6 @@ missing — every LLM-extracted field carries a verifiable evidence chain failures via `dev.failsafe:failsafe`; per-call retry count carried on `Provenance`. -[Unreleased]: https://github.com/doctruthhq/DocTruth/compare/v0.1.0-alpha...HEAD +[Unreleased]: https://github.com/doctruthhq/DocTruth/compare/v0.2.0-alpha...HEAD +[0.2.0-alpha]: https://github.com/doctruthhq/DocTruth/compare/v0.1.0-alpha...v0.2.0-alpha [0.1.0-alpha]: https://github.com/doctruthhq/DocTruth/releases/tag/v0.1.0-alpha diff --git a/README.es.md b/README.es.md index 8332a67..605039d 100644 --- a/README.es.md +++ b/README.es.md @@ -29,7 +29,7 @@ No es un framework de agentes, un framework de chains, un wrapper de bases vecto Requiere Java 25+. Verifica Maven Central: ```bash -mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha +mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.2.0-alpha ``` Usar en un proyecto Maven: @@ -38,11 +38,11 @@ Usar en un proyecto Maven: ai.doctruth doctruth-java - 0.1.0-alpha + 0.2.0-alpha ``` -Gradle usa la misma coordenada: `ai.doctruth:doctruth-java:0.1.0-alpha`. +Gradle usa la misma coordenada: `ai.doctruth:doctruth-java:0.2.0-alpha`. Actualizar a la última release: @@ -110,7 +110,7 @@ DocTruth soporta exportaciones comunes de Pydantic v2 JSON Schema, incluyendo `$ Herramienta de migración en build-time: ```bash -java -jar target/doctruth-java-0.1.0-alpha.jar \ +java -jar target/doctruth-java-0.2.0-alpha.jar \ migrate pydantic myapp.schemas:ResumeExtraction \ --out schemas/resume.schema.json \ --check @@ -134,8 +134,8 @@ Los clientes usan `java.net.http.HttpClient` del JDK; no hay SDKs de proveedores ## CLI ```bash -java -jar target/doctruth-java-0.1.0-alpha.jar parse contract.pdf -java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check +java -jar target/doctruth-java-0.2.0-alpha.jar parse contract.pdf +java -jar target/doctruth-java-0.2.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check ``` ## Documentación @@ -150,9 +150,9 @@ java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Mo ## Estado -`0.1.0-alpha` es una alpha pública temprana. La API es usable, está probada y se publica para recibir feedback, pero puede cambiar antes de `1.0`. +`0.2.0-alpha` es una alpha pública temprana. La API es usable, está probada y se publica para recibir feedback, pero puede cambiar antes de `1.0`. -Baseline actual: 628 unit tests y 16 integration tests pasando, con 2 smoke tests externos omitidos, coverage gates en 90% line / 80% branch, jar único de aproximadamente 202 KB. +Baseline actual: 645 unit tests y 16 integration tests pasando, con 2 smoke tests externos omitidos, coverage gates en 90% line / 80% branch, jar único de aproximadamente 205 KB. ## Licencia diff --git a/README.md b/README.md index e0a365a..3123186 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ It is not an agent framework, chain framework, vector database wrapper, or UI. I Requires Java 25+. Verify Maven Central availability: ```bash -mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha +mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.2.0-alpha ``` Use in a Maven project: @@ -38,11 +38,11 @@ Use in a Maven project: ai.doctruth doctruth-java - 0.1.0-alpha + 0.2.0-alpha ``` -Gradle uses the same coordinate: `ai.doctruth:doctruth-java:0.1.0-alpha`. +Gradle uses the same coordinate: `ai.doctruth:doctruth-java:0.2.0-alpha`. Upgrade to the latest release: @@ -123,7 +123,7 @@ DocTruth supports common Pydantic v2 JSON Schema exports, including local `$defs Build-time helper: ```bash -java -jar target/doctruth-java-0.1.0-alpha.jar \ +java -jar target/doctruth-java-0.2.0-alpha.jar \ migrate pydantic myapp.schemas:ResumeExtraction \ --out schemas/resume.schema.json \ --check @@ -147,8 +147,8 @@ Provider clients use JDK `java.net.http.HttpClient`; no vendor SDKs are on the c ## CLI ```bash -java -jar target/doctruth-java-0.1.0-alpha.jar parse contract.pdf -java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check +java -jar target/doctruth-java-0.2.0-alpha.jar parse contract.pdf +java -jar target/doctruth-java-0.2.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check ``` ## Documentation @@ -163,9 +163,9 @@ java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Mo ## Status -`0.1.0-alpha` is an early public alpha. The API is usable, tested, and published for feedback, but may still change before `1.0`. +`0.2.0-alpha` is an early public alpha. The API is usable, tested, and published for feedback, but may still change before `1.0`. -Current verification baseline: 628 unit tests and 16 integration tests passing, with 2 external smoke tests skipped, coverage gates at 90% line / 80% branch, single jar about 202 KB. +Current verification baseline: 645 unit tests and 16 integration tests passing, with 2 external smoke tests skipped, coverage gates at 90% line / 80% branch, single jar about 205 KB. ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index dee3efb..6a8eeca 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -29,7 +29,7 @@ DocTruth 主要回答一个问题： 需要 Java 25+。验证 Maven Central 可用： ```bash -mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha +mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.2.0-alpha ``` 在 Maven 项目中使用： @@ -38,11 +38,11 @@ mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha ai.doctruth doctruth-java - 0.1.0-alpha + 0.2.0-alpha ``` -Gradle 使用同一个坐标：`ai.doctruth:doctruth-java:0.1.0-alpha`。 +Gradle 使用同一个坐标：`ai.doctruth:doctruth-java:0.2.0-alpha`。 升级到最新 release： @@ -110,7 +110,7 @@ DocTruth 支持常见 Pydantic v2 JSON Schema 输出，包括本地 `$defs` / `$ 构建期迁移工具： ```bash -java -jar target/doctruth-java-0.1.0-alpha.jar \ +java -jar target/doctruth-java-0.2.0-alpha.jar \ migrate pydantic myapp.schemas:ResumeExtraction \ --out schemas/resume.schema.json \ --check @@ -134,8 +134,8 @@ Provider client 使用 JDK `java.net.http.HttpClient`，不引入 vendor SDK。 ## CLI ```bash -java -jar target/doctruth-java-0.1.0-alpha.jar parse contract.pdf -java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check +java -jar target/doctruth-java-0.2.0-alpha.jar parse contract.pdf +java -jar target/doctruth-java-0.2.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check ``` ## 文档 @@ -150,9 +150,9 @@ java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Mo ## 状态 -`0.1.0-alpha` 是早期公开 alpha。API 已可用、已测试、可供反馈，但在 `1.0` 前仍可能调整。 +`0.2.0-alpha` 是早期公开 alpha。API 已可用、已测试、可供反馈，但在 `1.0` 前仍可能调整。 -当前验证基线：628 个 unit test 和 16 个 integration test 通过，2 个外部 smoke test 跳过，覆盖率门槛为 90% line / 80% branch，单 jar 约 202 KB。 +当前验证基线：645 个 unit test 和 16 个 integration test 通过，2 个外部 smoke test 跳过，覆盖率门槛为 90% line / 80% branch，单 jar 约 205 KB。 ## License diff --git a/README.zh-TW.md b/README.zh-TW.md index ae33014..0439b7c 100644 --- a/README.zh-TW.md +++ b/README.zh-TW.md @@ -29,7 +29,7 @@ DocTruth 主要回答一個問題： 需要 Java 25+。驗證 Maven Central 可用： ```bash -mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha +mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.2.0-alpha ``` 在 Maven 專案中使用： @@ -38,11 +38,11 @@ mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha ai.doctruth doctruth-java - 0.1.0-alpha + 0.2.0-alpha ``` -Gradle 使用同一個座標：`ai.doctruth:doctruth-java:0.1.0-alpha`。 +Gradle 使用同一個座標：`ai.doctruth:doctruth-java:0.2.0-alpha`。 升級到最新 release： @@ -110,7 +110,7 @@ DocTruth 支援常見 Pydantic v2 JSON Schema 輸出，包括本地 `$defs` / `$ 建置期遷移工具： ```bash -java -jar target/doctruth-java-0.1.0-alpha.jar \ +java -jar target/doctruth-java-0.2.0-alpha.jar \ migrate pydantic myapp.schemas:ResumeExtraction \ --out schemas/resume.schema.json \ --check @@ -134,8 +134,8 @@ Provider client 使用 JDK `java.net.http.HttpClient`，不引入 vendor SDK。 ## CLI ```bash -java -jar target/doctruth-java-0.1.0-alpha.jar parse contract.pdf -java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check +java -jar target/doctruth-java-0.2.0-alpha.jar parse contract.pdf +java -jar target/doctruth-java-0.2.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check ``` ## 文件 @@ -150,9 +150,9 @@ java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Mo ## 狀態 -`0.1.0-alpha` 是早期公開 alpha。API 已可用、已測試、可供回饋，但在 `1.0` 前仍可能調整。 +`0.2.0-alpha` 是早期公開 alpha。API 已可用、已測試、可供回饋，但在 `1.0` 前仍可能調整。 -目前驗證基線：628 個 unit test 和 16 個 integration test 通過，2 個外部 smoke test 跳過，覆蓋率門檻為 90% line / 80% branch，單 jar 約 202 KB。 +目前驗證基線：645 個 unit test 和 16 個 integration test 通過，2 個外部 smoke test 跳過，覆蓋率門檻為 90% line / 80% branch，單 jar 約 205 KB。 ## License diff --git a/examples/evidence-overlay/README.md b/examples/evidence-overlay/README.md index 4dd26e2..750ed4b 100644 --- a/examples/evidence-overlay/README.md +++ b/examples/evidence-overlay/README.md @@ -35,7 +35,7 @@ Then compile + run the standalone example (no Maven submodule): ```bash JAVA_HOME=/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home \ mvn -q dependency:build-classpath -Dmdep.outputFile=/tmp/cp.txt -CP="target/doctruth-java-0.1.0-SNAPSHOT.jar:$(cat /tmp/cp.txt)" +CP="target/doctruth-java-0.2.0-alpha.jar:$(cat /tmp/cp.txt)" javac -cp "$CP" -d /tmp/overlay-build examples/evidence-overlay/EvidenceOverlay.java java -cp "/tmp/overlay-build:$CP" ai.doctruth.examples.evidenceoverlay.EvidenceOverlay ``` diff --git a/examples/pydantic-interop/README.md b/examples/pydantic-interop/README.md index 050f4a0..bd2a06c 100644 --- a/examples/pydantic-interop/README.md +++ b/examples/pydantic-interop/README.md @@ -17,7 +17,7 @@ runtime dependency. If your Python model is importable as `myapp.schemas:ResumeExtraction`: ```bash -java -jar target/doctruth-java-0.1.0-SNAPSHOT.jar \ +java -jar target/doctruth-java-0.2.0-alpha.jar \ migrate pydantic myapp.schemas:ResumeExtraction \ --out examples/pydantic-interop/resume.schema.json \ --check @@ -38,7 +38,7 @@ Build the jar and classpath: JAVA_HOME=/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home \ mvn -B -ntp package -DskipTests mvn -q dependency:build-classpath -Dmdep.outputFile=/tmp/doctruth-cp.txt -CP="target/doctruth-java-0.1.0-SNAPSHOT.jar:$(cat /tmp/doctruth-cp.txt)" +CP="target/doctruth-java-0.2.0-alpha.jar:$(cat /tmp/doctruth-cp.txt)" ``` Compile and run: diff --git a/examples/quickstart/README.md b/examples/quickstart/README.md index 797ff6d..74a5697 100644 --- a/examples/quickstart/README.md +++ b/examples/quickstart/README.md @@ -44,7 +44,7 @@ mvn exec:java \ export OPENAI_API_KEY=sk-... mvn -q -f /path/to/doctruth-java/pom.xml package -DskipTests mvn -q -f /path/to/doctruth-java/pom.xml dependency:build-classpath -Dmdep.outputFile=/tmp/doctruth-cp.txt -CP="/path/to/doctruth-java/target/doctruth-java-0.1.0-SNAPSHOT.jar:$(cat /tmp/doctruth-cp.txt)" +CP="/path/to/doctruth-java/target/doctruth-java-0.2.0-alpha.jar:$(cat /tmp/doctruth-cp.txt)" javac -cp "$CP" -d build /path/to/doctruth-java/examples/quickstart/Quickstart.java java -cp "build:$CP" ai.doctruth.examples.quickstart.Quickstart ``` diff --git a/pom.xml b/pom.xml index 77ae384..5ea9fc1 100644 --- a/pom.xml +++ b/pom.xml @@ -7,7 +7,7 @@ ai.doctruth doctruth-java - 0.2.0-SNAPSHOT + 0.2.0-alpha jar DocTruth