How reagento/adaptix works
Project type and purpose
• This is a Python open-source library (“adaptix”) providing an extremely flexible and configurable data model conversion system (loading, dumping, and model-to-model conversion).
• It is not a full-stack application but a modular library with a clear public API, rich internal subsystems, and integrations with external model frameworks (dataclasses, attrs, pydantic, SQLAlchemy, msgspec).
File structure
• Top-level directories:
• src/adaptix – the core Python package, subdivided into public modules and a large _internal package.
• tests, benchmarks, docs, examples, scripts – supporting code, not part of the runtime system.
• Key internal subdirectories under src/adaptix/_internal:
• code_tools – compilation and code‐generation utilities
• conversion – “model A → model B” conversion engine
• model_tools – introspection of a variety of model types
• morphing – JSON/schema loader & dumper generator
• provider – request dispatch, schema overlay, value providers
• retort – central mediator, routing, error handling
• type_tools – type normalization and resolution
• Public modules under src/adaptix:
• retort.py – main entry point (Retort)
• conversion – public API for converters (get_converter)
• provider, load_error, struct_trail, type_tools – supporting APIs
• integrations – adapters for pydantic, SQLAlchemy, msgspec
README for additional insights
• Public API revolves around two use cases:
a) instantiating a global Retort to load/dump arbitrary models ↔ Python dicts
b) calling get_converter to transform one model type into another
• Emphasis on performance, extensibility, and separation of concerns
a. Main components to include:
• Public API layer
– Retort (loading/dumping mediator)
– get_converter (conversion factory)
• Internal subsystems
– Retort subsystem (routers, request bus, error renderer)
– Conversion subsystem (facade, code_generator, coercer/provider)
– Morphing subsystem (loader/provider, dumper/provider, JSON schema)
– Model tools subsystem (introspection for dataclass, attrs, Pydantic, SQLA, NamedTuple, TypedDict, msgspec)
– Provider subsystem (value providers, overlay schema, loc_stack filtering)
– Code tools subsystem (AST templater, code_builder, compiler)
– Type tools subsystem (type normalization, generic resolution)
• External integrations
– Dataclasses (built-in)
– attrs, Pydantic, SQLAlchemy, msgspec
• Data flow / dependencies
– Application → Public API → Retort / Converter → Internal subsystems → Integration adapters → Model frameworks
– Code generation path: Conversion → Code tools → Generated loader/dumper code → Morphing
b. Relationships and interactions
– Retort uses Provider + Model tools + Morphing under the hood
– Conversion subsystem orchestrates code_tools + provider + type_tools to produce conversion functions
– Morphing subsystem interacts with JSON/schema and provider subsystems to load/dump raw data
– Integration adapters plug into Model tools and Morphing subsystems
c. Architectural patterns and principles
– Single Responsibility Principle (each subsystem has a focused domain)
– Mediator pattern (Retort as central orchestrator)
– Facade pattern (conversion façade, morphing façade)
– Plugin architecture (integration modules discoverable under integrations/…)
– Code generation pipeline (AST templater → code builder → compiler)
d. Technologies and frameworks
– Python packaging and modules
– AST‐based code generation
– Model frameworks (dataclasses, attrs, Pydantic, SQLAlchemy, msgspec)
Elements
• Clear labels for: Public API, Retort subsystem, Conversion subsystem, Morphing subsystem, Model tools, Provider, Code tools, Type tools, Integrations
• Gray for internal subsystems
• Green for code generation/morph components
• Orange for integration adapters/external models
Detail
• Explicitly show each internal package as a separate component
• Flow of data and code (e.g. how a load(...) call propagates through retort → provider → morphing → model construction)
• Avoid lumping all internals together; break down into at least Retort, Conversion, Morphing, ModelTools, Provider, CodeTools, TypeTools, Integrations