Fix failing test, add full coverage, docs, examples

Remove compatibility mode

Author: aschwa

README.md

@@ -45,6 +45,7 @@ Use the `dottxt` CLI for login, model discovery, and one-off generation.
 - CLI reference: [docs/cli.md](docs/cli.md)
 - Client reference: [docs/client.md](docs/client.md)
 - Schema validation: `dottxt schema check schema.json`
+- Pydantic conditionals: [docs/pydantic.md](docs/pydantic.md)
 
 ## Client Surfaces
 
@@ -275,6 +276,8 @@ The compatibility surface expects the wrapped OpenAI-style
 - [Use a dataclass type to generate](examples/generate_dataclass.py)
 - [Use a TypedDict type to generate](examples/generate_typed_dict.py)
 - [Use a Genson schema builder to generate](examples/generate_genson.py)
+- [Pydantic conditionals: value-based `when`](examples/pydantic_conditionals_when.py)
+- [Pydantic conditionals: presence-based `when_present`](examples/pydantic_conditionals_when_present.py)
 - [List available models](examples/list_models.py)
 - [OpenAI-Compatible chat completions](examples/openai_chat_completions.py)
 - [Stream fields as they arrive](examples/stream_field_printer.py)

docs/pydantic.md

@@ -0,0 +1,102 @@
+# Pydantic Conditional Schemas
+
+`dottxt.pydantic_conditionals` adds JSON Schema conditionals to Pydantic models.
+Use it when you need schema-level `if`/`then`/`else` or dependency rules that are
+enforced through a Pydantic response model passed to `DotTxt.generate(...)`.
+
+## Imports
+
+`ConditionalModel` must be listed before `BaseModel` in class inheritance:
+`class MyModel(ConditionalModel, BaseModel): ...`.
+
+```python
+from typing import Annotated, ClassVar
+
+from pydantic import BaseModel, Field
+
+from dottxt import DotTxt
+from dottxt.pydantic_conditionals import (
+    ConditionalModel,
+    RequiredWith,
+    when,
+    when_present,
+)
+```
+
+## Pattern 1: Value-Based Conditional (`when`) with `generate(...)`
+
+Use `when(...)` to trigger constraints when a field has a specific value.
+
+```python
+class Address(ConditionalModel, BaseModel):
+    country: str
+    postal_code: str | None = None
+
+    model_conditions: ClassVar = (
+        when(country="USA")
+        .require("postal_code")
+        .constrain(postal_code=Field(pattern=r"^\d{5}$")),
+    )
+
+
+client = DotTxt()
+result = client.generate(
+    model="openai/gpt-oss-20b",
+    input=(
+        "Return a JSON object for a US shipping address. "
+        "Set country to USA and include a valid 5-digit postal_code."
+    ),
+    response_format=Address,
+)
+print(result.model_dump())
+```
+
+## Pattern 2: Presence-Based Conditional (`when_present`) with `generate(...)`
+
+Use `when_present(...)` to trigger constraints when a field exists, independent
+of its value.
+
+```python
+class Payment(ConditionalModel, BaseModel):
+    credit_card: str | None = None
+    billing_address: str | None = None
+
+    model_conditions: ClassVar = (
+        when_present("credit_card").require("billing_address"),
+    )
+
+
+client = DotTxt()
+result = client.generate(
+    model="openai/gpt-oss-20b",
+    input=(
+        "Return a JSON object representing a payment payload. "
+        "Include credit_card and billing_address fields."
+    ),
+    response_format=Payment,
+)
+print(result.model_dump())
+```
+
+## Pattern 3: Annotation-Based Dependency (`RequiredWith`)
+
+Use `RequiredWith` when one field must be present whenever another field is
+present.
+
+```python
+class FileOperation(ConditionalModel, BaseModel):
+    content: str | None = None
+    create_parents: Annotated[bool | None, RequiredWith("content")] = None
+```
+
+## Runnable Examples
+
+- [examples/pydantic_conditionals_when.py](../examples/pydantic_conditionals_when.py)
+- [examples/pydantic_conditionals_when_present.py](../examples/pydantic_conditionals_when_present.py)
+
+## References
+
+- JSON Schema conditionals: <https://json-schema.org/understanding-json-schema/reference/conditionals>
+- JSON Schema object dependencies: <https://json-schema.org/understanding-json-schema/reference/conditionals#dependentrequired>
+- Pydantic JSON schema docs: <https://docs.pydantic.dev/latest/concepts/json_schema/>
+- Pydantic `Field` constraints: <https://docs.pydantic.dev/latest/concepts/fields/>

examples/pydantic_conditionals_when.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+from pydantic import BaseModel, Field
+
+from dottxt import DotTxt
+from dottxt.pydantic_conditionals import ConditionalModel, when
+
+
+class Address(ConditionalModel, BaseModel):
+    country: str
+    postal_code: str | None = None
+
+    model_conditions: ClassVar = (
+        when(country="USA")
+        .require("postal_code")
+        .constrain(postal_code=Field(pattern=r"^\d{5}$")),
+    )
+
+
+if __name__ == "__main__":
+    client = DotTxt()
+    result = client.generate(
+        model="openai/gpt-oss-20b",
+        input=(
+            "Return a JSON object for a US shipping address. "
+            "Set country to USA and include a valid 5-digit postal_code."
+        ),
+        response_format=Address,
+    )
+    print(result)
+    print(result.model_dump())

examples/pydantic_conditionals_when_present.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+from dottxt import DotTxt
+from dottxt.pydantic_conditionals import ConditionalModel, when_present
+
+
+class Payment(ConditionalModel, BaseModel):
+    credit_card: str | None = None
+    billing_address: str | None = None
+
+    model_conditions: ClassVar = (
+        when_present("credit_card").require("billing_address"),
+    )
+
+
+if __name__ == "__main__":
+    client = DotTxt()
+    result = client.generate(
+        model="openai/gpt-oss-20b",
+        input=(
+            "Return a JSON object representing a payment payload. "
+            "Include credit_card and billing_address fields."
+        ),
+        response_format=Payment,
+    )
+    print(result)
+    print(result.model_dump())

src/dottxt/pydantic_conditionals/compatibility.py

@@ -17,7 +17,6 @@
 from pydantic import BaseModel
 from pydantic.annotated_handlers import GetJsonSchemaHandler
 
-from .compatibility import apply_compatibility_mode
 from .constraint import Constraint, build_constraints, compute_constraints
 
 CONDITIONALS_REF_MARKER = "$$ref"
@@ -67,7 +66,7 @@ def _normalize_require_fields(field: str | tuple[str] | list[str]) -> list[str]:
         return list(field)
     if isinstance(field, list):
         return field
-    raise ValueError("Parameter should be list or str.")
+    raise ValueError("Parameter must be a list or str.")
 
 
 class QueryBuilder:
@@ -137,8 +136,8 @@ def __and__(self, other: QueryBuilder | DependentSchemaBuilder) -> QueryBuilder:
             and self.conditions
         ):
             raise ValueError(
-                "Canot combine wheres specified with Schemas with ones specified "
-                "with conditions."
+                "Cannot combine where clauses specified with schemas with "
+                "ones specified with conditions."
             )
 
         conditions = self.conditions[0] if len(self.conditions) == 1 else {}
@@ -179,8 +178,8 @@ def __or__(self, other: QueryBuilder | DependentSchemaBuilder) -> QueryBuilder:
             and self.conditions
         ):
             raise ValueError(
-                "Canot combine wheres specified with Schemas with ones specified "
-                "with conditions."
+                "Cannot combine where clauses specified with schemas with "
+                "ones specified with conditions."
             )
 
         if isinstance(other, DependentSchemaBuilder):
@@ -227,7 +226,7 @@ def then_apply(self, schema: type[BaseModel]) -> Self:
 
     def then_apply_only(self, schema: type[BaseModel]) -> Self:
         """Mixes in this schema when the condition is met (``then`` clause).
-        "additionalPropertes" is set to false!
+        ``additionalProperties`` is set to ``False``.
 
         This does not combine with ``constrain`` or other ``then_apply`` methods.
         The last ``then_apply`` will take precedence.
@@ -254,7 +253,7 @@ def else_apply(self, schema: type[BaseModel]) -> Self:
 
     def else_apply_only(self, schema: type[BaseModel]) -> Self:
         """Mixes in this schema when the condition is *not* met (``else`` clause).
-        "additionalPropertes" is set to false!
+        ``additionalProperties`` is set to ``False``.
 
         This does not combine with ``otherwise`` or other ``else_apply`` methods.
         The last ``else_apply`` will take precedence.
@@ -561,22 +560,10 @@ def __get_pydantic_json_schema__(
     def model_json_schema(
         cls,
         *args,
-        compatibility_mode: str | bool = False,
         **kwargs: Any,
     ) -> dict[str, Any]:
-        """Generate JSON Schema for this model, applying compatibility mode if needed.
-
-        Args:
-            compatibility_mode: Controls schema conversion.
-                ``False`` (default) -- no conversion.
-                ``True`` -- full conversion (dependentRequired/Schemas -> if/then/else).
-                to if/then/else only.
-        """
+        """Generate JSON Schema for this model."""
         result = super().model_json_schema(*args, **kwargs)  # type: ignore[misc]
         result = _remove_conditionals_ref_marker(result)
 
-        mode = compatibility_mode or getattr(cls, "model_compatibility_mode", False)
-        if mode is True:
-            result = apply_compatibility_mode(result)
-
         return result