From beed4e5e9778d5f7b460b550a74005adfcbc7f41 Mon Sep 17 00:00:00 2001 From: Vitor Hideyoshi Date: Wed, 26 Nov 2025 09:00:57 -0300 Subject: [PATCH] chore: improves documentation and readme --- README.md | 54 ++++++++++++++++++++++++++++++--- docs/source/usage.ref_cache.rst | 6 ++++ docs/source/usage.rst | 7 ++++- 3 files changed, 61 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 56a5962..47c2040 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Jambo - JSON Schema to Pydantic Converter -

+

- + Last commit Tests @@ -19,12 +19,13 @@

**Jambo** is a Python package that automatically converts [JSON Schema](https://json-schema.org/) definitions into [Pydantic](https://docs.pydantic.dev/) models. -It's designed to streamline schema validation and enforce type safety using Pydantic's powerful validation features. +It's designed to streamline schema validation and enforce type safety using Pydantic's validation features. -Created to simplifying the process of dynamically generating Pydantic models for AI frameworks like [LangChain](https://www.langchain.com/), [CrewAI](https://www.crewai.com/), and others. +Created to simplify the process of dynamically generating Pydantic models for AI frameworks like [LangChain](https://www.langchain.com/), [CrewAI](https://www.crewai.com/), and others. --- + ## ✨ Features - ✅ Convert JSON Schema into Pydantic models dynamically; @@ -56,10 +57,25 @@ pip install jambo ## 🚀 Usage +There are two ways to build models with Jambo: + +1. The original static API: `SchemaConverter.build(schema)` doesn't persist any reference cache between calls and doesn't require any configuration. +2. The new instance API: use a `SchemaConverter()` instance and call `build_with_cache`, which exposes and persists a reference cache and helper methods. + +The instance API is useful when you want to reuse generated subtypes, inspect cached models, or share caches between converters. See the docs for full details: https://jambo.readthedocs.io/en/latest/usage.ref_cache.html + + +> [!NOTE] +> The use of the instance API and ref cache can cause schema and type name collisions if not managed carefully, therefore +> it's recommended that each namespace or schema source uses its own `SchemaConverter` instance. +> If you don't need cache control, the static API is simpler and sufficient for most use cases. + + +### Static (compatibility) example + ```python from jambo import SchemaConverter - schema = { "title": "Person", "type": "object", @@ -70,12 +86,40 @@ schema = { "required": ["name"], } +# Old-style convenience API (kept for compatibility) Person = SchemaConverter.build(schema) obj = Person(name="Alice", age=30) print(obj) ``` +### Instance API (recommended for cache control) + +```python +from jambo import SchemaConverter + +converter = SchemaConverter() + +schema = { + "title": "Person", + "type": "object", + "properties": { + "name": {"type": "string"}, + "age": {"type": "integer"}, + "address": {"type": "object", "properties": {"street": {"type": "string"}}}, + }, + "required": ["name"], +} + +# build_with_cache populates the converter's instance-level ref cache +Person = converter.build_with_cache(schema) + +# you can retrieve cached subtypes by name/path +cached_person = converter.get_cached_ref("Person") +# clear the instance cache when needed +converter.clear_ref_cache() +``` + --- ## ✅ Example Validations diff --git a/docs/source/usage.ref_cache.rst b/docs/source/usage.ref_cache.rst index adcf2f9..7fda88e 100644 --- a/docs/source/usage.ref_cache.rst +++ b/docs/source/usage.ref_cache.rst @@ -10,6 +10,12 @@ and :py:meth:`SchemaConverter.build `. However, only :py:meth:`SchemaConverter.build_with_cache ` exposes the cache through a supported API; :py:meth:`SchemaConverter.build ` uses the cache internally and does not provide access to it. +The reference cache accepts a mutable mapping (typically a plain Python dict) +that maps reference names (strings) to generated Pydantic model classes. +Since only the reference names are stored it can cause name collisions if +multiple schemas with overlapping names are processed using the same cache. +Therefore, it's recommended that each namespace or schema source uses its own +:class:`SchemaConverter` instance. ----------------------------------------- Configuring and Using the Reference Cache diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 5a7dc08..5db74f4 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -42,7 +42,7 @@ Static Method (no config) The :py:meth:`SchemaConverter.build ` static method takes a JSON Schema dictionary and returns a Pydantic model class. -Note: the static ``build`` method was the original public API of this library and is kept for backwards compatibility. It creates and returns a model class for the provided schema but does not expose or persist an instance cache. +Note: the static ``build`` method was the original public API of this library. It creates and returns a model class for the provided schema but does not expose or persist an instance cache. -------------------------------- @@ -97,6 +97,11 @@ the instance method persists and exposes the reference cache and provides helper :py:meth:`SchemaConverter.get_cached_ref ` and :py:meth:`SchemaConverter.clear_ref_cache `. +.. warning:: + The instance API with reference cache can lead to schema and type name collisions if not managed carefully. + It's recommended that each namespace or schema source uses its own `SchemaConverter` instance. + If you don't need cache control, the static API is simpler and sufficient for most use cases. + For details and examples about the reference cache and the different cache modes (instance cache, per-call cache, ephemeral cache), see: .. toctree::