Publish pinned CUDA TF32 inference source and example

inference/LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

inference/NOTICE

@@ -0,0 +1,246 @@
+AXDocLayout-M v1.2 CUDA TF32 runtime update
+Modified by AutomatosX on 2026-10-17: explicit ONNX Runtime CUDA execution,
+TF32 policy and placement verification, equivalent vectorized postprocessing,
+release identity, integrity bindings and inference documentation. Model weights,
+public classes and raster coordinates are unchanged from v1.1. The complete
+inference source is supplied in inference/. License: AGPL-3.0-only.
+
+AXDocLayout-M v1.2
+Copyright 2026 AutomatosX
+
+This release as a whole, including its model weights and modified inference
+source, is licensed under GNU AGPL version 3 only (AGPL-3.0-only).
+See LICENSE. Commercial use is permitted subject to the license terms.
+No additional non-commercial restriction is imposed.
+
+Modified by AutomatosX on 2026-10-17: updated model artifacts, release
+identity, source-neutral taxonomy identifier, artifact integrity bindings,
+usage documentation and distribution license. Public class IDs and raster
+coordinates are unchanged. The complete inference source is in inference/.
+
+Previously Apache-2.0-licensed components retain their original notices and
+rights. The following notice and full Apache-2.0 text are preserved for those
+components; they do not offer the new model weights under Apache-2.0.
+
+--- Preserved component notice ---
+AX DocLayout
+Copyright 2026 AutomatosX
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+The detector architecture is RT-DETRv2 (`rtdetrv2_r50vd_m`). Upstream
+RT-DETR is licensed under Apache-2.0 and is not included in this bundle.
+
+--- Apache License 2.0 for prior components ---
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

inference/README.md

@@ -0,0 +1,16 @@
+# AX DocLayout v1.2 CUDA inference source
+
+ONNX Runtime CUDA + TF32 inference for AXDocLayout-M v1.2, using unchanged FP32
+weights and 1024 letterbox geometry. Requires supported Linux x86-64/NVIDIA
+CUDA 12.8 setup and Python 3.12 or 3.13.
+
+```bash
+python -m pip install ".[onnx]"
+python examples/predict_page.py page.png --backend onnx
+```
+
+The ONNX extra installs the pinned GPU runtime and CUDA/cuDNN dependencies.
+The backend requires CUDA and verifies TF32/compute placement. A GPU failure
+raises an error. Use the immutable source and weight revisions in the model
+repository root README. For an explicit CPU comparison, install `.[torch]`
+and select `--backend pytorch`. See LICENSE and NOTICE (AGPL-3.0-only).

inference/examples/predict_page.py

@@ -0,0 +1,61 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Detect layout on one page raster using the pinned public Hub weights."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import warnings
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+from ax_doclayout import AXDocLayout, AXDocLayoutError, InvalidPageImageError, PageImage
+from ax_doclayout.contract import MAX_PAGE_PIXELS
+
+MODEL_ID = "AutomatosX/AXDocLayout-M-v1.2"
+REVISION = "7efd000fc7a1ef50ed7913835f2d8f10f30dc8e3"
+
+
+def load_page(path: Path, *, page_index: int) -> PageImage:
+    """Decode a raster without recording its filename or pixels in the output."""
+
+    try:
+        with path.open("rb") as handle:
+            if handle.read(5) == b"%PDF-" or path.suffix.lower() == ".pdf":
+                raise InvalidPageImageError("provide a page raster image")
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", Image.DecompressionBombWarning)
+            with Image.open(path) as image:
+                if image.width * image.height > MAX_PAGE_PIXELS:
+                    raise InvalidPageImageError("page raster exceeds pixel limit")
+                rgb = np.asarray(image.convert("RGB"), dtype=np.uint8)
+    except (OSError, ValueError, Image.DecompressionBombError, Image.DecompressionBombWarning):
+        raise InvalidPageImageError("page raster could not be decoded") from None
+    return PageImage(rgb=rgb, page_index=page_index)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("image", type=Path)
+    parser.add_argument("--backend", choices=("onnx", "pytorch"), default="onnx")
+    parser.add_argument("--page-index", type=int, default=0)
+    args = parser.parse_args(argv)
+    try:
+        page = load_page(args.image, page_index=args.page_index)
+        model = AXDocLayout.from_pretrained(
+            MODEL_ID, revision=REVISION, backend=args.backend,
+        )
+        print(json.dumps(model.predict(page).to_json(), indent=2, allow_nan=False))
+    except AXDocLayoutError as error:
+        print(f"ax-doclayout: {error}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

inference/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ax-doclayout"
+version = "1.2.0.post2"
+description = "AX DocLayout page-raster layout inference."
+readme = "README.md"
+requires-python = ">=3.12,<3.14"
+license = "AGPL-3.0-only"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "AutomatosX" }]
+dependencies = ["huggingface-hub>=0.36,<2", "numpy>=1.26,<3", "pillow>=12.2,<13"]
+
+[project.optional-dependencies]
+onnx = [
+  "onnxruntime-gpu[cuda,cudnn]==1.23.2",
+  "nvidia-cuda-runtime-cu12==12.8.90",
+  "nvidia-cuda-nvrtc-cu12==12.8.93",
+  "nvidia-cufft-cu12==11.3.3.83",
+  "nvidia-curand-cu12==10.3.9.90",
+  "nvidia-cublas-cu12==12.8.4.1",
+  "nvidia-cudnn-cu12==9.10.2.21",
+]
+torch = ["torch>=2.12,<2.13", "safetensors>=0.4,<1"]
+
+[project.scripts]
+ax-doclayout = "ax_doclayout.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ax_doclayout = ["py.typed"]

inference/src/ax_doclayout/__init__.py

@@ -0,0 +1,82 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""AX DocLayout: page-raster document structure detection.
+
+The AXDocLayout-M v1.2 model contract is a layout detector: an RGB page
+raster in, versioned JSON boxes out. The public API verifies the pinned
+immutable Hub bundle before inference. ``LocalOnnxBundle`` is an
+unqualified local runner pinned to the staged ONNX digest; it is not Hub load.
+"""
+
+from __future__ import annotations
+
+from ax_doclayout.artifact import SOURCE_CHECKPOINT_SHA256, STAGED_ONNX_SHA256
+from ax_doclayout.contract import (
+    COORDINATE_SPACE,
+    DETECTION_SCHEMA_VERSION,
+    PREPROCESS_ID,
+    TAXONOMY_ID,
+    BoundingBox,
+    Element,
+    InvalidPageStructureError,
+    ModelIdentity,
+    PageImage,
+    PageStructure,
+)
+from ax_doclayout.errors import (
+    ArtifactUnavailableError,
+    AXDocLayoutError,
+    BackendUnavailableError,
+    InferenceError,
+    InvalidPageImageError,
+    InvalidRevisionError,
+)
+from ax_doclayout.local_onnx import QUALIFICATION, LocalOnnxBundle, LocalOnnxResult
+from ax_doclayout.model import AXDocLayout
+from ax_doclayout.postprocess import (
+    DEFAULT_SCORE_THRESHOLD,
+    elements_from_letterbox_detections,
+    page_structure_from_elements,
+)
+from ax_doclayout.preprocess import (
+    Letterbox,
+    inverse_letterbox_box,
+    letterbox_page,
+    letterbox_rgb,
+)
+
+__version__ = "1.2.0.post2"
+
+__all__ = [
+    "COORDINATE_SPACE",
+    "DEFAULT_SCORE_THRESHOLD",
+    "DETECTION_SCHEMA_VERSION",
+    "PREPROCESS_ID",
+    "QUALIFICATION",
+    "SOURCE_CHECKPOINT_SHA256",
+    "STAGED_ONNX_SHA256",
+    "TAXONOMY_ID",
+    "AXDocLayout",
+    "AXDocLayoutError",
+    "ArtifactUnavailableError",
+    "BackendUnavailableError",
+    "BoundingBox",
+    "Element",
+    "InferenceError",
+    "InvalidPageImageError",
+    "InvalidPageStructureError",
+    "InvalidRevisionError",
+    "Letterbox",
+    "LocalOnnxBundle",
+    "LocalOnnxResult",
+    "ModelIdentity",
+    "PageImage",
+    "PageStructure",
+    "__version__",
+    "elements_from_letterbox_detections",
+    "inverse_letterbox_box",
+    "letterbox_page",
+    "letterbox_rgb",
+    "page_structure_from_elements",
+]

inference/src/ax_doclayout/_cuda_onnx.py

@@ -0,0 +1,115 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Verified ONNX Runtime CUDA execution with explicit TF32 policy."""
+
+from __future__ import annotations
+
+import ctypes
+import importlib.metadata
+import json
+import tempfile
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from ax_doclayout.errors import BackendUnavailableError
+
+_COMPUTE_OPS = {"Conv", "FusedConv", "MatMul", "FusedMatMul", "Gemm", "GridSample", "Softmax"}
+_PROVIDER = "CUDAExecutionProvider"
+_OPTIONS = {"use_tf32": "1", "cudnn_conv_algo_search": "HEURISTIC", "device_id": "0"}
+
+
+def _placement(events: object) -> dict[str, dict[str, int]]:
+    """Require observed CUDA compute and retain all remaining CPU placements."""
+    if not isinstance(events, list):
+        raise BackendUnavailableError("cuda_placement_unverified")
+    providers: Counter[str] = Counter()
+    cpu_ops: Counter[str] = Counter()
+    compute: Counter[str] = Counter()
+    for event in events:
+        if not isinstance(event, dict) or not isinstance(event.get("args"), dict):
+            continue
+        args = event["args"]
+        provider, op = args.get("provider"), args.get("op_name")
+        if not isinstance(provider, str) or not isinstance(op, str):
+            continue
+        providers[provider] += 1
+        if provider != _PROVIDER:
+            cpu_ops[op] += 1
+        if op in _COMPUTE_OPS:
+            if provider != _PROVIDER:
+                raise BackendUnavailableError("cuda_compute_placement_failed")
+            compute[op] += 1
+    if not any("Conv" in op for op in compute):
+        raise BackendUnavailableError("cuda_compute_unverified")
+    return {"providers": dict(providers), "cpu_ops": dict(cpu_ops), "cuda_compute": dict(compute)}
+
+
+def _session(path: Path, *, ort: Any, profile_prefix: str | None = None) -> Any:
+    options = ort.SessionOptions()
+    options.intra_op_num_threads = 4
+    options.inter_op_num_threads = 1
+    options.log_severity_level = 3
+    if profile_prefix is not None:
+        options.enable_profiling = True
+        options.profile_file_prefix = profile_prefix
+    session = ort.InferenceSession(
+        str(path), sess_options=options,
+        providers=[(_PROVIDER, dict(_OPTIONS)), "CPUExecutionProvider"],
+    )
+    if not session.get_providers() or session.get_providers()[0] != _PROVIDER:
+        raise BackendUnavailableError("cuda_provider_not_primary")
+    session.disable_fallback()
+    actual = session.get_provider_options().get(_PROVIDER, {})
+    if actual.get("use_tf32") != "1" or actual.get("device_id") != "0":
+        raise BackendUnavailableError("cuda_tf32_policy_unverified")
+    return session
+
+
+def _require_tf32_device() -> None:
+    """Check CUDA-visible device zero supports TF32 without importing PyTorch."""
+    distribution = importlib.metadata.distribution("nvidia-cuda-runtime-cu12")
+    library = distribution.locate_file("nvidia/cuda_runtime/lib/libcudart.so.12")
+    runtime = ctypes.CDLL(str(library))
+    query = runtime.cudaDeviceGetAttribute
+    query.argtypes = [ctypes.POINTER(ctypes.c_int), ctypes.c_int, ctypes.c_int]
+    query.restype = ctypes.c_int
+    major = ctypes.c_int()
+    # CUDA Runtime enum cudaDevAttrComputeCapabilityMajor is 75.
+    status = query(ctypes.byref(major), 75, 0)
+    if status != 0 or major.value < 8:
+        raise BackendUnavailableError("tf32_capable_cuda_device_required")
+
+
+def create_cuda_session(path: Path, *, ort: Any) -> Any:
+    """Load only the CUDA TF32 path; reject unavailable or unverified execution.
+
+    The startup trace uses a synthetic raster and is deleted before returning.
+    CPU shape/control operations remain explicit; recognized compute must use
+    CUDA. This check does not claim that every graph node runs on the GPU.
+    """
+    try:
+        # Load the CUDA/cuDNN libraries installed by the pinned GPU extra.
+        if hasattr(ort, "preload_dlls"):
+            ort.preload_dlls(directory="")
+        if _PROVIDER not in ort.get_available_providers():
+            raise BackendUnavailableError("cuda_provider_unavailable")
+        _require_tf32_device()
+        with tempfile.TemporaryDirectory(prefix="ax-cuda-probe-") as directory:
+            probe = _session(path, ort=ort, profile_prefix=str(Path(directory) / "profile"))
+            outputs = probe.run(["labels", "boxes", "scores"], {
+                "images": np.zeros((1, 3, 1024, 1024), dtype=np.float32),
+                "orig_target_sizes": np.array([[1024, 1024]], dtype=np.int64),
+            })
+            if len(outputs) != 3 or not all(np.isfinite(value).all() for value in outputs):
+                raise BackendUnavailableError("cuda_probe_outputs_invalid")
+            _placement(json.loads(Path(probe.end_profiling()).read_text()))
+            del probe
+        return _session(path, ort=ort)
+    except BackendUnavailableError:
+        raise
+    except Exception:  # noqa: BLE001 - redact third-party paths and library errors
+        raise BackendUnavailableError("cuda_backend_load_failed") from None

inference/src/ax_doclayout/_hub_pin.py

@@ -0,0 +1,23 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+"""Verified immutable identity of the AXDocLayout-M v1.2 bundle."""
+from __future__ import annotations
+
+from ax_doclayout.artifact import ArtifactFile, ArtifactReceipt
+
+PINNED_HUB_RECEIPT = ArtifactReceipt(
+    model_id='AutomatosX/AXDocLayout-M-v1.2',
+    model_revision='7efd000fc7a1ef50ed7913835f2d8f10f30dc8e3',
+    artifact_sha256='sha256:bcbfd65dc33bc08c05c5c511fe52c22dd439baf04c3f09c64f15dd3a78e9782d',
+    artifact_files=(
+        ArtifactFile(name='LICENSE', sha256='sha256:0d96a4ff68ad6d4b6f1f30f713b18d5184912ba8dd389f86aa7710db079abcb0'),
+        ArtifactFile(name='MODEL_CARD.md', sha256='sha256:f9680372775ec966971cdb373fb73413e9f5306573ec72e480358c4f7717f5ec'),
+        ArtifactFile(name='NOTICE', sha256='sha256:9faf3d395b2e23fde5419f4bf6ac22c093da2f92a48ba7533e88259de0173317'),
+        ArtifactFile(name='artifact-manifest.json', sha256='sha256:823c64a31559fa80f113e6c3d7be7163c43049a0a14c40028f6080a4bd5175ac'),
+        ArtifactFile(name='config.json', sha256='sha256:c60877aed03fc6a53d16303e1c6f0d2c86fddaf49b6f77c84daa243b61412a85'),
+        ArtifactFile(name='model.onnx', sha256='sha256:2d5928719c391e424a1132f8c5eadb23e4d164d3576f00ff14010ebe55aaea81'),
+        ArtifactFile(name='model.safetensors', sha256='sha256:3b97ba1c0b1b0816f45e79a76bb2fd495e026d2394471b76ce1a442baa2989c4'),
+        ArtifactFile(name='preprocessor_config.json', sha256='sha256:96c6b8cb4afc4b1a6dec51ce44a24d68ea05b42cdf2b78ce1df12a0ef3ec9f5b'),
+        ArtifactFile(name='taxonomy.json', sha256='sha256:896360d61d534175ea9d13164c96021bfb2b8aca6936a587a3dc1197b8deec35'),
+    ),
+)

inference/src/ax_doclayout/_local_onnx.py

@@ -0,0 +1,175 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Private, digest-verified ONNX inference over a local nine-file bundle.
+
+This path is not ``from_pretrained``. It never claims a Hub revision, never
+marks a bundle publishable, and never emits a DocLayout-YOLO result shape.
+Callers inject ``session_run`` in tests so the default suite does not need
+onnxruntime, CUDA, or the 127 MiB staging graph.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from ax_doclayout.artifact import (
+    MODEL_ID,
+    STAGED_ONNX_SHA256,
+    verify_artifact_manifest,
+)
+from ax_doclayout.contract import Element, PageImage
+from ax_doclayout.errors import (
+    ArtifactError,
+    ArtifactUnavailableError,
+    BackendUnavailableError,
+)
+from ax_doclayout.postprocess import (
+    DEFAULT_SCORE_THRESHOLD,
+    elements_from_letterbox_detections,
+)
+from ax_doclayout.preprocess import letterbox_nchw, letterbox_page, orig_target_sizes
+
+QUALIFICATION = "local-bundle-unqualified"
+ONNX_INPUT_IMAGES = "images"
+ONNX_INPUT_SIZES = "orig_target_sizes"
+
+
+SessionRun = Callable[[Mapping[str, np.ndarray]], object]
+
+
+@dataclass(frozen=True, slots=True)
+class LocalOnnxResult:
+    """One unqualified local-bundle detection. Not a Hub ``PageStructure``."""
+
+    page_index: int
+    width_px: int
+    height_px: int
+    elements: tuple[Element, ...]
+    qualification: str
+    bundle_root: str
+    threshold: float
+
+    def as_published_page_structure(self) -> None:
+        """Refuse to impersonate a Hub-qualified ``PageStructure``."""
+
+        raise ArtifactUnavailableError(
+            "local ONNX bundle is not a published AX DocLayout artifact"
+        )
+
+
+class LocalOnnxBundle:
+    """Run the staged ONNX file after the manifest binds every payload digest."""
+
+    def __init__(
+        self,
+        directory: Path,
+        *,
+        session_run: SessionRun | None = None,
+        expected_onnx_sha256: str | None = STAGED_ONNX_SHA256,
+    ) -> None:
+        manifest = verify_artifact_manifest(directory)
+        if manifest.model_id != MODEL_ID:
+            raise ArtifactError("artifact_model_id_invalid")
+        onnx_digest = ""
+        for item in manifest.artifact_files:
+            if item.name == "model.onnx":
+                onnx_digest = item.sha256
+                break
+        if not onnx_digest:
+            raise ArtifactError("artifact_file_unavailable")
+        if (
+            expected_onnx_sha256 is not None
+            and onnx_digest != expected_onnx_sha256
+        ):
+            raise ArtifactError("artifact_onnx_digest_mismatch")
+        self._directory = directory
+        self._onnx_path = directory / "model.onnx"
+        if not self._onnx_path.is_file():
+            raise ArtifactError("artifact_file_unavailable")
+        self._root = _file_digest(directory / "artifact-manifest.json")
+        self._session_run = session_run
+
+    def predict(
+        self,
+        page: PageImage,
+        *,
+        threshold: float = DEFAULT_SCORE_THRESHOLD,
+    ) -> LocalOnnxResult:
+        """Detect on one RGB page. Output stays unqualified."""
+
+        letterbox = letterbox_page(page)
+        feeds = {
+            ONNX_INPUT_IMAGES: letterbox_nchw(letterbox),
+            ONNX_INPUT_SIZES: orig_target_sizes(letterbox),
+        }
+        labels, boxes, scores = _split_outputs(self._run(feeds))
+        elements = elements_from_letterbox_detections(
+            labels=labels,
+            boxes=boxes,
+            scores=scores,
+            page=page,
+            letterbox=letterbox,
+            threshold=threshold,
+        )
+        return LocalOnnxResult(
+            page_index=page.page_index,
+            width_px=page.width_px,
+            height_px=page.height_px,
+            elements=elements,
+            qualification=QUALIFICATION,
+            bundle_root=self._root,
+            threshold=float(threshold),
+        )
+
+    def _run(self, feeds: Mapping[str, np.ndarray]) -> object:
+        if self._session_run is not None:
+            return self._session_run(feeds)
+        try:
+            import onnxruntime as ort
+        except ImportError as error:
+            raise BackendUnavailableError("onnxruntime is not installed") from error
+        try:
+            session = ort.InferenceSession(
+                str(self._onnx_path),
+                providers=["CPUExecutionProvider"],
+            )
+            return session.run(None, dict(feeds))
+        except Exception as error:  # onnxruntime exposes no common base error
+            raise ArtifactError("onnx_inference_failed") from error
+
+
+def _split_outputs(outputs: object) -> tuple[Any, Any, Any]:
+    if not isinstance(outputs, (tuple, list)) or len(outputs) < 3:
+        raise ArtifactError("onnx_outputs_invalid")
+    return outputs[0], outputs[1], outputs[2]
+
+
+def _file_digest(path: Path) -> str:
+    """Hash one regular file without following symlinks."""
+
+    import hashlib
+    import os
+
+    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path, flags)
+    except OSError as error:
+        raise ArtifactError("artifact_manifest_unavailable") from error
+    digest = hashlib.sha256()
+    try:
+        while True:
+            chunk = os.read(descriptor, 1024 * 1024)
+            if not chunk:
+                break
+            digest.update(chunk)
+    except OSError as error:
+        raise ArtifactError("artifact_manifest_unavailable") from error
+    finally:
+        os.close(descriptor)
+    return digest.hexdigest()

inference/src/ax_doclayout/_local_pytorch.py

@@ -0,0 +1,122 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Digest-verified PyTorch inference over a local nine-file bundle.
+
+This path loads the staged safetensors into the in-repo RT-DETRv2-M
+architecture. It is not ``from_pretrained`` and it never marks a bundle
+publishable.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import torch
+
+from ax_doclayout._torch_rtdetrv2 import build_rtdetrv2_r50vd_m
+from ax_doclayout.artifact import (
+    MODEL_ID,
+    STAGED_SAFETENSORS_SHA256,
+    _reject_json_constant,
+    _unique_object,
+    verify_artifact_manifest,
+)
+from ax_doclayout.contract import Element, PageImage
+from ax_doclayout.errors import ArtifactError, BackendUnavailableError
+from ax_doclayout.postprocess import (
+    DEFAULT_SCORE_THRESHOLD,
+    elements_from_letterbox_detections,
+)
+from ax_doclayout.preprocess import letterbox_nchw, letterbox_page, orig_target_sizes
+
+ARCHITECTURE_ID = "rtdetrv2_r50vd_m"
+
+
+class LocalPytorchBundle:
+    """Run the staged safetensors after the manifest binds every payload digest."""
+
+    def __init__(
+        self,
+        directory: Path,
+        *,
+        expected_safetensors_sha256: str | None = STAGED_SAFETENSORS_SHA256,
+    ) -> None:
+        try:
+            from safetensors import SafetensorError
+            from safetensors.torch import load_file
+        except ImportError as error:
+            raise BackendUnavailableError("safetensors is not installed") from error
+        manifest = verify_artifact_manifest(directory)
+        if manifest.model_id != MODEL_ID:
+            raise ArtifactError("artifact_model_id_invalid")
+        weights_digest = ""
+        for item in manifest.artifact_files:
+            if item.name == "model.safetensors":
+                weights_digest = item.sha256
+                break
+        if not weights_digest:
+            raise ArtifactError("artifact_file_unavailable")
+        if (
+            expected_safetensors_sha256 is not None
+            and weights_digest != expected_safetensors_sha256
+        ):
+            raise ArtifactError("artifact_safetensors_digest_mismatch")
+        weights_path = directory / "model.safetensors"
+        if not weights_path.is_file():
+            raise ArtifactError("artifact_file_unavailable")
+        try:
+            state = load_file(str(weights_path))
+        except (SafetensorError, OSError, ValueError) as error:
+            raise ArtifactError("artifact_safetensors_unreadable") from error
+        model = build_rtdetrv2_r50vd_m()
+        try:
+            model.load_state_dict(state, strict=True)
+        except RuntimeError as error:
+            raise ArtifactError("artifact_state_dict_mismatch") from error
+        model.eval()
+        self._model = model
+        self._directory = directory
+
+    def predict_elements(
+        self,
+        page: PageImage,
+        *,
+        threshold: float = DEFAULT_SCORE_THRESHOLD,
+    ) -> tuple[Element, ...]:
+        """Detect on one RGB page and return original-raster elements."""
+
+        letterbox = letterbox_page(page)
+        images = torch.from_numpy(letterbox_nchw(letterbox))
+        sizes = torch.from_numpy(orig_target_sizes(letterbox))
+        with torch.no_grad():
+            labels, boxes, scores = self._model(images, sizes)
+        return elements_from_letterbox_detections(
+            labels=labels.cpu().numpy(),
+            boxes=boxes.cpu().numpy(),
+            scores=scores.cpu().numpy(),
+            page=page,
+            letterbox=letterbox,
+            threshold=threshold,
+        )
+
+
+def read_publishable(path: Path) -> bool:
+    """Read the staging receipt flag. Missing or malformed receipts fail closed."""
+
+    import json
+
+    try:
+        payload = json.loads(
+            path.read_text(encoding="utf-8"),
+            object_pairs_hook=_unique_object,
+            parse_constant=_reject_json_constant,
+        )
+    except (OSError, ValueError) as error:
+        raise ArtifactError("staging_receipt_unreadable") from error
+    if not isinstance(payload, dict) or "publishable" not in payload:
+        raise ArtifactError("staging_publishable_missing")
+    flag = payload["publishable"]
+    if not isinstance(flag, bool):
+        raise ArtifactError("staging_publishable_invalid")
+    return flag

inference/src/ax_doclayout/_torch_rtdetrv2.py

@@ -0,0 +1,490 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Original RT-DETRv2-M modules for the staged AXDocLayout-M v1.2 safetensors.
+
+The layer names follow the staged checkpoint so ``load_state_dict`` is strict.
+This module does not open a Hub revision and does not serialize JSON.
+"""
+
+from __future__ import annotations
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+HIDDEN = 256
+NUM_CLASSES = 12
+NUM_QUERIES = 300
+# The staged ONNX graph executes the first three decoder layers and the
+# third pair of score and box heads. Later checkpoint layers stay loaded.
+INFERENCE_LAYERS = 3
+NUM_LEVELS = 3
+NUM_HEADS = 8
+NUM_POINTS = 4
+OFFSET_SCALE = 0.5
+FEAT_CHANNELS = (512, 1024, 2048)
+STAGE_CHANNELS = (256, 512, 1024, 2048)
+STAGE_BLOCKS = (3, 4, 6, 3)
+STAGE_STRIDES = (1, 2, 2, 2)
+
+
+def inverse_sigmoid(value: torch.Tensor, eps: float = 1e-5) -> torch.Tensor:
+    """Map probabilities back to logits with a finite clamp."""
+
+    clipped = value.clamp(0.0, 1.0)
+    numerator = clipped.clamp(min=eps)
+    denominator = (1.0 - clipped).clamp(min=eps)
+    return torch.log(numerator / denominator)
+
+
+def sincos_position_embedding(
+    height: int, width: int, *, device: torch.device, dtype: torch.dtype
+) -> torch.Tensor:
+    """2D sine-cosine embedding, shape ``[1, height * width, hidden]``."""
+
+    grid_y, grid_x = torch.meshgrid(
+        torch.arange(height, device=device, dtype=dtype),
+        torch.arange(width, device=device, dtype=dtype),
+        indexing="ij",
+    )
+    omega_count = HIDDEN // 4
+    omega = torch.arange(omega_count, device=device, dtype=dtype) / omega_count
+    omega = 1.0 / (10000.0 ** omega)
+    out_y = grid_y.reshape(-1, 1) * omega.reshape(1, -1)
+    out_x = grid_x.reshape(-1, 1) * omega.reshape(1, -1)
+    return torch.cat((out_y.sin(), out_y.cos(), out_x.sin(), out_x.cos()), dim=1)[
+        None
+    ]
+
+
+class ConvNorm(nn.Module):
+    """Convolution, batch norm, and an optional pointwise activation."""
+
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int,
+        kernel: int,
+        stride: int,
+        activation: str | None,
+    ) -> None:
+        super().__init__()
+        self.conv = nn.Conv2d(
+            in_channels,
+            out_channels,
+            kernel,
+            stride=stride,
+            padding=kernel // 2,
+            bias=False,
+        )
+        self.norm = nn.BatchNorm2d(out_channels)
+        self.activation = activation
+
+    def forward(self, tensor: torch.Tensor) -> torch.Tensor:
+        tensor = self.norm(self.conv(tensor))
+        if self.activation == "relu":
+            return F.relu(tensor)
+        if self.activation == "silu":
+            return F.silu(tensor)
+        return tensor
+
+
+class StrideShortcut(nn.Module):
+    """Average-pool then a stride-1 projection. Used by stage downsamples."""
+
+    def __init__(self, in_channels: int, out_channels: int) -> None:
+        super().__init__()
+        self.pool = nn.AvgPool2d(kernel_size=2, stride=2, ceil_mode=True)
+        self.conv = ConvNorm(in_channels, out_channels, 1, 1, None)
+
+    def forward(self, tensor: torch.Tensor) -> torch.Tensor:
+        return self.conv(self.pool(tensor))
+
+
+class ResidualBlock(nn.Module):
+    """Bottleneck with a ReLU after the residual add."""
+
+    def __init__(self, in_channels: int, out_channels: int, stride: int) -> None:
+        super().__init__()
+        mid = out_channels // 4
+        self.branch2a = ConvNorm(in_channels, mid, 1, 1, "relu")
+        self.branch2b = ConvNorm(mid, mid, 3, stride, "relu")
+        self.branch2c = ConvNorm(mid, out_channels, 1, 1, None)
+        if stride == 2:
+            self.short = StrideShortcut(in_channels, out_channels)
+        elif in_channels != out_channels:
+            self.short = ConvNorm(in_channels, out_channels, 1, 1, None)
+        else:
+            self.short = None
+
+    def forward(self, tensor: torch.Tensor) -> torch.Tensor:
+        residual = tensor if self.short is None else self.short(tensor)
+        transformed = self.branch2c(self.branch2b(self.branch2a(tensor)))
+        return F.relu(transformed + residual)
+
+
+class Backbone(nn.Module):
+    """PResNet-50-vd stem and four stages. Returns strides 8, 16, and 32."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.conv1 = nn.Module()
+        self.conv1.conv1_1 = ConvNorm(3, 32, 3, 2, "relu")
+        self.conv1.conv1_2 = ConvNorm(32, 32, 3, 1, "relu")
+        self.conv1.conv1_3 = ConvNorm(32, 64, 3, 1, "relu")
+        self.pool = nn.MaxPool2d(kernel_size=3, stride=2, padding=1)
+        stages = []
+        in_channels = 64
+        for out_channels, blocks, stride in zip(
+            STAGE_CHANNELS, STAGE_BLOCKS, STAGE_STRIDES, strict=True
+        ):
+            layers = []
+            for index in range(blocks):
+                block_stride = stride if index == 0 else 1
+                layers.append(ResidualBlock(in_channels, out_channels, block_stride))
+                in_channels = out_channels
+            stage = nn.Module()
+            stage.blocks = nn.ModuleList(layers)
+            stages.append(stage)
+        self.res_layers = nn.ModuleList(stages)
+
+    def forward(self, tensor: torch.Tensor) -> list[torch.Tensor]:
+        tensor = self.conv1.conv1_3(self.conv1.conv1_2(self.conv1.conv1_1(tensor)))
+        tensor = self.pool(tensor)
+        outputs: list[torch.Tensor] = []
+        for stage_index, stage in enumerate(self.res_layers):
+            for block in stage.blocks:
+                tensor = block(tensor)
+            if stage_index > 0:
+                outputs.append(tensor)
+        return outputs
+
+
+class RepVggBlock(nn.Module):
+    """3x3 plus 1x1 branches, summed, then SiLU."""
+
+    def __init__(self, channels: int) -> None:
+        super().__init__()
+        self.conv1 = ConvNorm(channels, channels, 3, 1, None)
+        self.conv2 = ConvNorm(channels, channels, 1, 1, None)
+
+    def forward(self, tensor: torch.Tensor) -> torch.Tensor:
+        return F.silu(self.conv1(tensor) + self.conv2(tensor))
+
+
+class CspRepBlock(nn.Module):
+    """Two 1x1 paths, repeated RepVGG blocks, then a 1x1 projection."""
+
+    def __init__(self, in_channels: int, out_channels: int, blocks: int = 3) -> None:
+        super().__init__()
+        hidden = out_channels // 2
+        self.conv1 = ConvNorm(in_channels, hidden, 1, 1, "silu")
+        self.conv2 = ConvNorm(in_channels, hidden, 1, 1, "silu")
+        self.bottlenecks = nn.Sequential(
+            *[RepVggBlock(hidden) for _ in range(blocks)]
+        )
+        self.conv3 = ConvNorm(hidden, out_channels, 1, 1, "silu")
+
+    def forward(self, tensor: torch.Tensor) -> torch.Tensor:
+        return self.conv3(self.bottlenecks(self.conv1(tensor)) + self.conv2(tensor))
+
+
+class EncoderLayer(nn.Module):
+    """One post-norm self-attention block with a GELU feed-forward."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.self_attn = nn.MultiheadAttention(HIDDEN, NUM_HEADS, batch_first=True)
+        self.linear1 = nn.Linear(HIDDEN, HIDDEN * 4)
+        self.linear2 = nn.Linear(HIDDEN * 4, HIDDEN)
+        self.norm1 = nn.LayerNorm(HIDDEN)
+        self.norm2 = nn.LayerNorm(HIDDEN)
+
+    def forward(self, tensor: torch.Tensor, position: torch.Tensor) -> torch.Tensor:
+        query = tensor + position
+        attended, _ = self.self_attn(query, query, tensor, need_weights=False)
+        tensor = self.norm1(tensor + attended)
+        return self.norm2(tensor + self.linear2(F.gelu(self.linear1(tensor))))
+
+
+class HybridEncoder(nn.Module):
+    """Project three backbone levels, encode the deepest, then FPN and PAN."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.input_proj = nn.ModuleList(
+            [ConvNorm(channels, HIDDEN, 1, 1, None) for channels in FEAT_CHANNELS]
+        )
+        layer = EncoderLayer()
+        tower = nn.Module()
+        tower.layers = nn.ModuleList([layer])
+        self.encoder = nn.ModuleList([tower])
+        self.lateral_convs = nn.ModuleList(
+            [ConvNorm(HIDDEN, HIDDEN, 1, 1, "silu") for _ in range(2)]
+        )
+        self.fpn_blocks = nn.ModuleList(
+            [CspRepBlock(HIDDEN * 2, HIDDEN) for _ in range(2)]
+        )
+        self.downsample_convs = nn.ModuleList(
+            [ConvNorm(HIDDEN, HIDDEN, 3, 2, "silu") for _ in range(2)]
+        )
+        self.pan_blocks = nn.ModuleList(
+            [CspRepBlock(HIDDEN * 2, HIDDEN) for _ in range(2)]
+        )
+
+    def forward(self, features: list[torch.Tensor]) -> list[torch.Tensor]:
+        projected = [
+            layer(feature) for layer, feature in zip(self.input_proj, features, strict=True)
+        ]
+        deepest = projected[-1]
+        batch, _channels, height, width = deepest.shape
+        tokens = deepest.flatten(2).transpose(1, 2)
+        position = sincos_position_embedding(
+            height, width, device=tokens.device, dtype=tokens.dtype
+        )
+        tokens = self.encoder[0].layers[0](tokens, position)
+        projected[-1] = tokens.transpose(1, 2).reshape(batch, HIDDEN, height, width)
+
+        inner = [projected[-1]]
+        for index in range(NUM_LEVELS - 1, 0, -1):
+            block_index = NUM_LEVELS - 1 - index
+            high = self.lateral_convs[block_index](inner[0])
+            inner[0] = high
+            upsampled = F.interpolate(high, scale_factor=2.0, mode="nearest")
+            fused = self.fpn_blocks[block_index](
+                torch.cat((upsampled, projected[index - 1]), dim=1)
+            )
+            inner.insert(0, fused)
+
+        outputs = [inner[0]]
+        for index in range(NUM_LEVELS - 1):
+            downsampled = self.downsample_convs[index](outputs[-1])
+            outputs.append(
+                self.pan_blocks[index](torch.cat((downsampled, inner[index + 1]), dim=1))
+            )
+        return outputs
+
+
+class MultiScaleAttention(nn.Module):
+    """Deformable attention over three feature levels, four points per head."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        points = NUM_HEADS * NUM_LEVELS * NUM_POINTS
+        self.sampling_offsets = nn.Linear(HIDDEN, points * 2)
+        self.attention_weights = nn.Linear(HIDDEN, points)
+        self.value_proj = nn.Linear(HIDDEN, HIDDEN)
+        self.output_proj = nn.Linear(HIDDEN, HIDDEN)
+        self.num_points_scale = nn.Parameter(torch.empty(NUM_LEVELS * NUM_POINTS))
+
+    def forward(
+        self,
+        query: torch.Tensor,
+        reference: torch.Tensor,
+        value: torch.Tensor,
+        spatial_shapes: list[tuple[int, int]],
+    ) -> torch.Tensor:
+        batch, queries, _channels = query.shape
+        head_dim = HIDDEN // NUM_HEADS
+        projected = self.value_proj(value).view(batch, -1, NUM_HEADS, head_dim)
+        offsets = self.sampling_offsets(query).view(
+            batch, queries, NUM_HEADS, NUM_LEVELS, NUM_POINTS, 2
+        )
+        weights = self.attention_weights(query).view(
+            batch, queries, NUM_HEADS, NUM_LEVELS * NUM_POINTS
+        )
+        weights = torch.softmax(weights, dim=-1).view(
+            batch, queries, NUM_HEADS, NUM_LEVELS, NUM_POINTS
+        )
+        scale = self.num_points_scale.view(1, 1, 1, NUM_LEVELS, NUM_POINTS, 1)
+        locations = (
+            reference[:, :, None, :, None, :2]
+            + offsets * scale * reference[:, :, None, :, None, 2:] * OFFSET_SCALE
+        )
+        grids = locations.mul(2.0).sub(1.0)
+        split_sizes = [height * width for height, width in spatial_shapes]
+        values = projected.split(split_sizes, dim=1)
+        sampled = []
+        for level, ((height, width), level_value) in enumerate(
+            zip(spatial_shapes, values, strict=True)
+        ):
+            level_grid = (
+                grids[:, :, :, level]
+                .permute(0, 2, 1, 3, 4)
+                .reshape(batch * NUM_HEADS, queries, NUM_POINTS, 2)
+            )
+            image = (
+                level_value.reshape(batch, height, width, NUM_HEADS, head_dim)
+                .permute(0, 3, 4, 1, 2)
+                .reshape(batch * NUM_HEADS, head_dim, height, width)
+            )
+            sampled.append(
+                F.grid_sample(
+                    image,
+                    level_grid,
+                    mode="bilinear",
+                    padding_mode="zeros",
+                    align_corners=False,
+                )
+            )
+        stacked = torch.stack(sampled, dim=-2)
+        # sampled: [B*heads, dim, queries, points] -> [B, Q, heads, levels, points, dim]
+        stacked = stacked.view(batch, NUM_HEADS, head_dim, queries, NUM_LEVELS, NUM_POINTS)
+        stacked = stacked.permute(0, 3, 1, 4, 5, 2)
+        weighted = (stacked * weights.unsqueeze(-1)).sum(dim=(3, 4))
+        merged = weighted.reshape(batch, queries, HIDDEN)
+        return self.output_proj(merged)
+
+
+class DecoderLayer(nn.Module):
+    """Self-attention, multi-scale attention, and a ReLU feed-forward."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.self_attn = nn.MultiheadAttention(HIDDEN, NUM_HEADS, batch_first=True)
+        self.cross_attn = MultiScaleAttention()
+        self.linear1 = nn.Linear(HIDDEN, HIDDEN * 4)
+        self.linear2 = nn.Linear(HIDDEN * 4, HIDDEN)
+        self.norm1 = nn.LayerNorm(HIDDEN)
+        self.norm2 = nn.LayerNorm(HIDDEN)
+        self.norm3 = nn.LayerNorm(HIDDEN)
+
+    def forward(
+        self,
+        target: torch.Tensor,
+        query_pos: torch.Tensor,
+        reference: torch.Tensor,
+        memory: torch.Tensor,
+        spatial_shapes: list[tuple[int, int]],
+    ) -> torch.Tensor:
+        query = target + query_pos
+        attended, _ = self.self_attn(query, query, target, need_weights=False)
+        target = self.norm1(target + attended)
+        cross = self.cross_attn(target + query_pos, reference, memory, spatial_shapes)
+        target = self.norm2(target + cross)
+        return self.norm3(target + self.linear2(F.relu(self.linear1(target))))
+
+
+class Mlp(nn.Module):
+    """Linear stack with ReLU between layers and none on the last layer."""
+
+    def __init__(self, in_features: int, hidden: int, out_features: int, layers: int) -> None:
+        super().__init__()
+        widths = [in_features] + [hidden] * (layers - 1) + [out_features]
+        self.layers = nn.ModuleList(
+            nn.Linear(left, right) for left, right in zip(widths, widths[1:])
+        )
+
+    def forward(self, tensor: torch.Tensor) -> torch.Tensor:
+        for index, layer in enumerate(self.layers):
+            tensor = layer(tensor)
+            if index + 1 < len(self.layers):
+                tensor = F.relu(tensor)
+        return tensor
+
+
+class EncOutput(nn.Module):
+    """Project encoder memory and normalize it before the proposal heads."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.proj = nn.Linear(HIDDEN, HIDDEN)
+        self.norm = nn.LayerNorm(HIDDEN)
+
+    def forward(self, tensor: torch.Tensor) -> torch.Tensor:
+        return self.norm(self.proj(tensor))
+
+
+class RTDETRV2R50VDM(nn.Module):
+    """Staged AXDocLayout-M v1.2 detector. Returns letterbox-space labels, boxes, and scores."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.backbone = Backbone()
+        self.encoder = HybridEncoder()
+        self.decoder = nn.Module()
+        self.decoder.input_proj = nn.ModuleList(
+            [ConvNorm(HIDDEN, HIDDEN, 1, 1, None) for _ in range(NUM_LEVELS)]
+        )
+        self.decoder.enc_output = EncOutput()
+        self.decoder.enc_score_head = nn.Linear(HIDDEN, NUM_CLASSES)
+        self.decoder.enc_bbox_head = Mlp(HIDDEN, HIDDEN, 4, 3)
+        self.decoder.query_pos_head = Mlp(4, 512, HIDDEN, 2)
+        self.decoder.denoising_class_embed = nn.Embedding(NUM_CLASSES + 1, HIDDEN)
+        tower = nn.Module()
+        tower.layers = nn.ModuleList(DecoderLayer() for _ in range(6))
+        self.decoder.decoder = tower
+        self.decoder.dec_score_head = nn.ModuleList(
+            nn.Linear(HIDDEN, NUM_CLASSES) for _ in range(6)
+        )
+        self.decoder.dec_bbox_head = nn.ModuleList(
+            Mlp(HIDDEN, HIDDEN, 4, 3) for _ in range(6)
+        )
+        self.decoder.register_buffer("anchors", torch.empty(1, 21504, 4), persistent=True)
+        self.decoder.register_buffer(
+            "valid_mask", torch.empty(1, 21504, 1, dtype=torch.bool), persistent=True
+        )
+
+    def forward(
+        self, images: torch.Tensor, orig_target_sizes: torch.Tensor
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        features = self.encoder(self.backbone(images))
+        memories = []
+        shapes: list[tuple[int, int]] = []
+        for projection, feature in zip(self.decoder.input_proj, features, strict=True):
+            projected = projection(feature)
+            _batch, _channels, height, width = projected.shape
+            shapes.append((height, width))
+            memories.append(projected.flatten(2).transpose(1, 2))
+        memory = torch.cat(memories, dim=1)
+        valid = self.decoder.valid_mask.to(dtype=memory.dtype)
+        encoded = self.decoder.enc_output(memory * valid)
+        proposal_scores = self.decoder.enc_score_head(encoded).max(dim=-1).values
+        proposal_scores = proposal_scores.masked_fill(
+            ~self.decoder.valid_mask[..., 0], float("-inf")
+        )
+        _values, indices = torch.topk(proposal_scores, NUM_QUERIES, dim=1)
+        boxes = self.decoder.enc_bbox_head(encoded) + self.decoder.anchors
+        reference = torch.gather(
+            boxes, 1, indices.unsqueeze(-1).expand(-1, -1, 4)
+        ).detach().sigmoid()
+        target = torch.gather(
+            encoded, 1, indices.unsqueeze(-1).expand(-1, -1, HIDDEN)
+        ).detach()
+        level_reference = reference.unsqueeze(2).expand(-1, -1, NUM_LEVELS, -1)
+        logits = boxes_unactivated = None
+        for layer, score_head, box_head in zip(
+            list(self.decoder.decoder.layers)[:INFERENCE_LAYERS],
+            list(self.decoder.dec_score_head)[:INFERENCE_LAYERS],
+            list(self.decoder.dec_bbox_head)[:INFERENCE_LAYERS],
+            strict=True,
+        ):
+            query_pos = self.decoder.query_pos_head(reference)
+            target = layer(target, query_pos, level_reference, memory, shapes)
+            logits = score_head(target)
+            boxes_unactivated = box_head(target) + inverse_sigmoid(reference)
+            reference = boxes_unactivated.detach().sigmoid()
+            level_reference = reference.unsqueeze(2).expand(-1, -1, NUM_LEVELS, -1)
+        if logits is None or boxes_unactivated is None:
+            raise RuntimeError("decoder_did_not_run")
+        cx, cy, width, height = boxes_unactivated.sigmoid().unbind(-1)
+        xyxy = torch.stack(
+            (cx - 0.5 * width, cy - 0.5 * height, cx + 0.5 * width, cy + 0.5 * height),
+            dim=-1,
+        )
+        sizes = orig_target_sizes.to(dtype=xyxy.dtype)
+        scale = torch.stack((sizes[:, 0], sizes[:, 1], sizes[:, 0], sizes[:, 1]), dim=-1)
+        xyxy = xyxy * scale[:, None, :]
+        flat_scores = torch.sigmoid(logits).flatten(1)
+        scores, flat_index = torch.topk(flat_scores, NUM_QUERIES, dim=1)
+        labels = flat_index.remainder(NUM_CLASSES)
+        query_index = flat_index.div(NUM_CLASSES, rounding_mode="floor")
+        selected = torch.gather(xyxy, 1, query_index.unsqueeze(-1).expand(-1, -1, 4))
+        return labels, selected, scores
+
+
+def build_rtdetrv2_r50vd_m() -> RTDETRV2R50VDM:
+    """Construct the unloaded AXDocLayout-M v1.2 architecture."""
+
+    return RTDETRV2R50VDM()

inference/src/ax_doclayout/artifact.py

@@ -0,0 +1,563 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Immutable AXDocLayout-M v1.2 artifact receipts and bundle verification.
+
+The Hub bundle contains nine files.  ``artifact-manifest.json`` describes the
+other eight payload files, while a separately trusted receipt binds all nine
+files and their content root.  Keeping the receipt outside the bundle avoids a
+self-digest cycle.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ax_doclayout.contract import PREPROCESS_ID, TAXONOMY_ID
+from ax_doclayout.errors import ArtifactError
+
+ARTIFACT_ROOT_SCHEMA = "ax-doclayout.artifact-root/1"
+ARTIFACT_RECEIPT_SCHEMA = "ax-doclayout.artifact-receipt/1"
+ARTIFACT_MANIFEST_SCHEMA = "ax-doclayout.artifact-manifest/1"
+MODEL_ID = "AutomatosX/AXDocLayout-M-v1.2"
+LEGACY_MODEL_ID = "AutomatosX/AXDocStruct-M-v0.1"
+SOURCE_CHECKPOINT_SHA256 = (
+    "sha256:e4747f71d40e14c89c561c720c043ad2be5dadf68668f071983f3ef1111a70fa"
+)
+STAGED_ONNX_SHA256 = (
+    "sha256:2d5928719c391e424a1132f8c5eadb23e4d164d3576f00ff14010ebe55aaea81"
+)
+STAGED_SAFETENSORS_SHA256 = (
+    "sha256:3b97ba1c0b1b0816f45e79a76bb2fd495e026d2394471b76ce1a442baa2989c4"
+)
+SUPPORTED_ONNX_OPSET = 16
+ARTIFACT_BUNDLE_FILES = (
+    "LICENSE",
+    "MODEL_CARD.md",
+    "NOTICE",
+    "artifact-manifest.json",
+    "config.json",
+    "model.onnx",
+    "model.safetensors",
+    "preprocessor_config.json",
+    "taxonomy.json",
+)
+ARTIFACT_MANIFEST_PAYLOAD_FILES = tuple(
+    name for name in ARTIFACT_BUNDLE_FILES if name != "artifact-manifest.json"
+)
+
+_MAX_RECEIPT_BYTES = 64 * 1024
+_MAX_MANIFEST_BYTES = 64 * 1024
+_REVISION_RE = re.compile(r"^[0-9a-f]{40}$")
+_SHA256_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactFile:
+    """One manifest-relative artifact file identity."""
+
+    name: str
+    sha256: str
+
+    def __post_init__(self) -> None:
+        if self.name not in ARTIFACT_BUNDLE_FILES:
+            raise ArtifactError("artifact_file_name_invalid")
+        if (
+            not isinstance(self.sha256, str)
+            or _SHA256_RE.fullmatch(self.sha256) is None
+        ):
+            raise ArtifactError("artifact_file_digest_invalid")
+
+    def to_json(self) -> dict[str, str]:
+        """Return the canonical JSON shape."""
+        return {"name": self.name, "sha256": self.sha256}
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactReceipt:
+    """Trusted, package-external identity for one immutable Hub bundle."""
+
+    model_id: str
+    model_revision: str
+    artifact_sha256: str
+    artifact_files: Sequence[ArtifactFile]
+    taxonomy: str = TAXONOMY_ID
+    preprocess: str = PREPROCESS_ID
+    schema_version: str = ARTIFACT_RECEIPT_SCHEMA
+
+    def __post_init__(self) -> None:
+        files = tuple(self.artifact_files)
+        object.__setattr__(self, "artifact_files", files)
+        if self.schema_version != ARTIFACT_RECEIPT_SCHEMA:
+            raise ArtifactError("artifact_receipt_schema_invalid")
+        if self.model_id != MODEL_ID:
+            raise ArtifactError("artifact_model_id_invalid")
+        if (
+            not isinstance(self.model_revision, str)
+            or _REVISION_RE.fullmatch(self.model_revision) is None
+        ):
+            raise ArtifactError("artifact_revision_invalid")
+        if self.taxonomy != TAXONOMY_ID:
+            raise ArtifactError("artifact_taxonomy_invalid")
+        if self.preprocess != PREPROCESS_ID:
+            raise ArtifactError("artifact_preprocess_invalid")
+        if (
+            not isinstance(self.artifact_sha256, str)
+            or _SHA256_RE.fullmatch(self.artifact_sha256) is None
+        ):
+            raise ArtifactError("artifact_root_digest_invalid")
+        _validate_complete_files(files)
+        expected_root = artifact_root_sha256(files)
+        if self.artifact_sha256 != expected_root:
+            raise ArtifactError("artifact_root_digest_mismatch")
+
+    def to_json(self) -> dict[str, object]:
+        """Return the strict receipt JSON shape."""
+        return {
+            "artifact_files": [item.to_json() for item in self.artifact_files],
+            "artifact_sha256": self.artifact_sha256,
+            "model_id": self.model_id,
+            "model_revision": self.model_revision,
+            "preprocess": self.preprocess,
+            "schema_version": self.schema_version,
+            "taxonomy": self.taxonomy,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactManifest:
+    """Canonical in-bundle identity for the eight non-manifest payloads."""
+
+    artifact_files: Sequence[ArtifactFile]
+    onnx_opset: int = SUPPORTED_ONNX_OPSET
+    model_id: str = MODEL_ID
+    taxonomy: str = TAXONOMY_ID
+    preprocess: str = PREPROCESS_ID
+    schema_version: str = ARTIFACT_MANIFEST_SCHEMA
+
+    def __post_init__(self) -> None:
+        files = tuple(self.artifact_files)
+        object.__setattr__(self, "artifact_files", files)
+        if self.schema_version != ARTIFACT_MANIFEST_SCHEMA:
+            raise ArtifactError("artifact_manifest_schema_invalid")
+        if self.model_id != MODEL_ID:
+            raise ArtifactError("artifact_model_id_invalid")
+        if self.taxonomy != TAXONOMY_ID:
+            raise ArtifactError("artifact_taxonomy_invalid")
+        if self.preprocess != PREPROCESS_ID:
+            raise ArtifactError("artifact_preprocess_invalid")
+        if (
+            isinstance(self.onnx_opset, bool)
+            or not isinstance(self.onnx_opset, int)
+            or self.onnx_opset != SUPPORTED_ONNX_OPSET
+        ):
+            raise ArtifactError("artifact_onnx_opset_unsupported")
+        _validate_manifest_files(files)
+
+    def to_json(self) -> dict[str, object]:
+        """Return the strict manifest JSON shape."""
+        return {
+            "backends": {
+                "onnx": {
+                    "file": "model.onnx",
+                    "format": "onnx",
+                    "opset": self.onnx_opset,
+                    "precision": "fp32",
+                    "standard_ops_only": True,
+                },
+                "pytorch": {
+                    "file": "model.safetensors",
+                    "format": "safetensors",
+                    "precision": "fp32",
+                },
+            },
+            "files": [item.to_json() for item in self.artifact_files],
+            "model_id": self.model_id,
+            "preprocess": self.preprocess,
+            "schema_version": self.schema_version,
+            "taxonomy": self.taxonomy,
+        }
+
+
+def canonical_json_bytes(payload: Mapping[str, object]) -> bytes:
+    """Serialize strict ASCII JSON without a trailing newline."""
+    try:
+        return json.dumps(
+            payload,
+            allow_nan=False,
+            ensure_ascii=True,
+            separators=(",", ":"),
+            sort_keys=True,
+        ).encode("ascii")
+    except (TypeError, ValueError, UnicodeError) as exc:
+        raise ArtifactError("artifact_json_invalid") from exc
+
+
+def _validate_complete_files(files: Sequence[ArtifactFile]) -> None:
+    if any(not isinstance(item, ArtifactFile) for item in files):
+        raise ArtifactError("artifact_files_invalid")
+    names = tuple(item.name for item in files)
+    if len(names) != len(set(names)):
+        raise ArtifactError("artifact_file_duplicate")
+    if names != ARTIFACT_BUNDLE_FILES:
+        raise ArtifactError("artifact_file_set_invalid")
+
+
+def _validate_manifest_files(files: Sequence[ArtifactFile]) -> None:
+    if any(not isinstance(item, ArtifactFile) for item in files):
+        raise ArtifactError("artifact_files_invalid")
+    names = tuple(item.name for item in files)
+    if len(names) != len(set(names)):
+        raise ArtifactError("artifact_file_duplicate")
+    if names != ARTIFACT_MANIFEST_PAYLOAD_FILES:
+        raise ArtifactError("artifact_manifest_file_set_invalid")
+
+
+def artifact_root_sha256(files: Sequence[ArtifactFile]) -> str:
+    """Compute the content root over the sorted complete nine-file set."""
+    items = tuple(files)
+    _validate_complete_files(items)
+    payload = {
+        "files": [item.to_json() for item in items],
+        "schema_version": ARTIFACT_ROOT_SCHEMA,
+    }
+    return "sha256:" + hashlib.sha256(canonical_json_bytes(payload)).hexdigest()
+
+
+def _open_regular_file(path: Path) -> int:
+    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path, flags)
+    except OSError as exc:
+        raise ArtifactError("artifact_file_unavailable") from exc
+    try:
+        opened = os.fstat(descriptor)
+        observed = path.lstat()
+        if (
+            not stat.S_ISREG(opened.st_mode)
+            or not stat.S_ISREG(observed.st_mode)
+            or (opened.st_dev, opened.st_ino) != (observed.st_dev, observed.st_ino)
+        ):
+            raise ArtifactError("artifact_file_unavailable")
+    except (OSError, ArtifactError):
+        os.close(descriptor)
+        raise
+    return descriptor
+
+
+def _hash_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    descriptor = _open_regular_file(path)
+    try:
+        with os.fdopen(descriptor, "rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                digest.update(chunk)
+    except OSError as exc:
+        raise ArtifactError("artifact_file_unavailable") from exc
+    return "sha256:" + digest.hexdigest()
+
+
+def _bundle_files(directory: Path) -> tuple[ArtifactFile, ...]:
+    try:
+        directory_mode = directory.lstat().st_mode
+    except OSError as exc:
+        raise ArtifactError("artifact_bundle_unavailable") from exc
+    if not stat.S_ISDIR(directory_mode):
+        raise ArtifactError("artifact_bundle_unavailable")
+    try:
+        names = tuple(sorted(path.name for path in directory.iterdir()))
+    except OSError as exc:
+        raise ArtifactError("artifact_bundle_unavailable") from exc
+    if names != ARTIFACT_BUNDLE_FILES:
+        raise ArtifactError("artifact_bundle_file_set_invalid")
+    files: list[ArtifactFile] = []
+    for name in ARTIFACT_BUNDLE_FILES:
+        path = directory / name
+        files.append(ArtifactFile(name=name, sha256=_hash_file(path)))
+    return tuple(files)
+
+
+def _payload_files(directory: Path) -> tuple[ArtifactFile, ...]:
+    try:
+        directory_mode = directory.lstat().st_mode
+    except OSError as exc:
+        raise ArtifactError("artifact_bundle_unavailable") from exc
+    if not stat.S_ISDIR(directory_mode):
+        raise ArtifactError("artifact_bundle_unavailable")
+    try:
+        names = tuple(sorted(path.name for path in directory.iterdir()))
+    except OSError as exc:
+        raise ArtifactError("artifact_bundle_unavailable") from exc
+    allowed_sets = {
+        ARTIFACT_MANIFEST_PAYLOAD_FILES,
+        ARTIFACT_BUNDLE_FILES,
+    }
+    if names not in allowed_sets:
+        raise ArtifactError("artifact_bundle_file_set_invalid")
+    return tuple(
+        ArtifactFile(name=name, sha256=_hash_file(directory / name))
+        for name in ARTIFACT_MANIFEST_PAYLOAD_FILES
+    )
+
+
+def build_artifact_manifest(
+    directory: Path,
+    *,
+    onnx_opset: int = SUPPORTED_ONNX_OPSET,
+) -> ArtifactManifest:
+    """Build the manifest from the exact eight payload files."""
+    return ArtifactManifest(
+        artifact_files=_payload_files(directory),
+        onnx_opset=onnx_opset,
+    )
+
+
+def build_artifact_receipt(
+    directory: Path,
+    *,
+    model_revision: str,
+) -> ArtifactReceipt:
+    """Build a receipt after a complete bundle has an immutable Hub revision."""
+    verify_artifact_manifest(directory)
+    files = _bundle_files(directory)
+    return ArtifactReceipt(
+        model_id=MODEL_ID,
+        model_revision=model_revision,
+        artifact_sha256=artifact_root_sha256(files),
+        artifact_files=files,
+    )
+
+
+def verify_artifact_bundle(directory: Path, receipt: ArtifactReceipt) -> None:
+    """Fail closed unless every staged byte matches a trusted receipt."""
+    if not isinstance(receipt, ArtifactReceipt):
+        raise ArtifactError("artifact_receipt_invalid")
+    verify_artifact_manifest(directory)
+    observed = _bundle_files(directory)
+    if observed != receipt.artifact_files:
+        raise ArtifactError("artifact_file_digest_mismatch")
+    if artifact_root_sha256(observed) != receipt.artifact_sha256:
+        raise ArtifactError("artifact_root_digest_mismatch")
+
+
+def _reject_json_constant(_: str) -> None:
+    raise ValueError("non_finite_json")
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate_json_key")
+        result[key] = value
+    return result
+
+
+def _exact_keys(
+    value: Mapping[str, Any],
+    expected: set[str],
+    code: str = "artifact_receipt_fields_invalid",
+) -> None:
+    if set(value) != expected:
+        raise ArtifactError(code)
+
+
+def _parse_artifact_file(value: object) -> ArtifactFile:
+    if not isinstance(value, dict):
+        raise ArtifactError("artifact_file_invalid")
+    _exact_keys(value, {"name", "sha256"}, "artifact_file_invalid")
+    try:
+        return ArtifactFile(name=value["name"], sha256=value["sha256"])
+    except (KeyError, TypeError) as exc:
+        raise ArtifactError("artifact_file_invalid") from exc
+
+
+def _validated_backends(value: object) -> int:
+    if not isinstance(value, dict):
+        raise ArtifactError("artifact_backends_invalid")
+    _exact_keys(value, {"onnx", "pytorch"}, "artifact_backends_invalid")
+    onnx = value["onnx"]
+    pytorch = value["pytorch"]
+    if not isinstance(onnx, dict) or not isinstance(pytorch, dict):
+        raise ArtifactError("artifact_backends_invalid")
+    _exact_keys(
+        onnx,
+        {"file", "format", "opset", "precision", "standard_ops_only"},
+        "artifact_backends_invalid",
+    )
+    _exact_keys(
+        pytorch,
+        {"file", "format", "precision"},
+        "artifact_backends_invalid",
+    )
+    opset = onnx["opset"]
+    if (
+        onnx["file"] != "model.onnx"
+        or onnx["format"] != "onnx"
+        or onnx["precision"] != "fp32"
+        or onnx["standard_ops_only"] is not True
+        or isinstance(opset, bool)
+        or not isinstance(opset, int)
+        or opset != SUPPORTED_ONNX_OPSET
+        or pytorch
+        != {
+            "file": "model.safetensors",
+            "format": "safetensors",
+            "precision": "fp32",
+        }
+    ):
+        raise ArtifactError("artifact_backends_invalid")
+    return opset
+
+
+def parse_artifact_manifest(raw: bytes) -> ArtifactManifest:
+    """Parse canonical manifest bytes with exact backend and payload metadata."""
+    if len(raw) > _MAX_MANIFEST_BYTES:
+        raise ArtifactError("artifact_manifest_too_large")
+    try:
+        value = json.loads(
+            raw,
+            object_pairs_hook=_unique_object,
+            parse_constant=_reject_json_constant,
+        )
+    except (TypeError, ValueError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ArtifactError("artifact_manifest_json_invalid") from exc
+    if not isinstance(value, dict):
+        raise ArtifactError("artifact_manifest_invalid")
+    _exact_keys(
+        value,
+        {
+            "backends",
+            "files",
+            "model_id",
+            "preprocess",
+            "schema_version",
+            "taxonomy",
+        },
+        "artifact_manifest_fields_invalid",
+    )
+    raw_files = value["files"]
+    if not isinstance(raw_files, list):
+        raise ArtifactError("artifact_files_invalid")
+    manifest = ArtifactManifest(
+        artifact_files=tuple(_parse_artifact_file(item) for item in raw_files),
+        onnx_opset=_validated_backends(value["backends"]),
+        model_id=value["model_id"],
+        taxonomy=value["taxonomy"],
+        preprocess=value["preprocess"],
+        schema_version=value["schema_version"],
+    )
+    if canonical_json_bytes(manifest.to_json()) != raw:
+        raise ArtifactError("artifact_manifest_not_canonical")
+    return manifest
+
+
+def load_artifact_manifest(path: Path) -> ArtifactManifest:
+    """Load one bounded canonical in-bundle manifest."""
+    descriptor = _open_regular_file(path)
+    try:
+        with os.fdopen(descriptor, "rb") as handle:
+            raw = handle.read(_MAX_MANIFEST_BYTES + 1)
+    except OSError as exc:
+        raise ArtifactError("artifact_manifest_unavailable") from exc
+    if len(raw) > _MAX_MANIFEST_BYTES:
+        raise ArtifactError("artifact_manifest_too_large")
+    return parse_artifact_manifest(raw)
+
+
+def verify_artifact_manifest(directory: Path) -> ArtifactManifest:
+    """Verify the manifest against the exact eight payload bytes."""
+    manifest = load_artifact_manifest(directory / "artifact-manifest.json")
+    observed = _payload_files(directory)
+    if tuple(manifest.artifact_files) != observed:
+        raise ArtifactError("artifact_manifest_digest_mismatch")
+    return manifest
+
+
+def parse_artifact_receipt(raw: bytes) -> ArtifactReceipt:
+    """Parse canonical trusted-receipt bytes with duplicate-key rejection."""
+    if len(raw) > _MAX_RECEIPT_BYTES:
+        raise ArtifactError("artifact_receipt_too_large")
+    try:
+        value = json.loads(
+            raw,
+            object_pairs_hook=_unique_object,
+            parse_constant=_reject_json_constant,
+        )
+    except (TypeError, ValueError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ArtifactError("artifact_receipt_json_invalid") from exc
+    if not isinstance(value, dict):
+        raise ArtifactError("artifact_receipt_invalid")
+    _exact_keys(
+        value,
+        {
+            "artifact_files",
+            "artifact_sha256",
+            "model_id",
+            "model_revision",
+            "preprocess",
+            "schema_version",
+            "taxonomy",
+        },
+    )
+    raw_files = value["artifact_files"]
+    if not isinstance(raw_files, list):
+        raise ArtifactError("artifact_files_invalid")
+    receipt = ArtifactReceipt(
+        model_id=value["model_id"],
+        model_revision=value["model_revision"],
+        artifact_sha256=value["artifact_sha256"],
+        artifact_files=tuple(_parse_artifact_file(item) for item in raw_files),
+        taxonomy=value["taxonomy"],
+        preprocess=value["preprocess"],
+        schema_version=value["schema_version"],
+    )
+    if canonical_json_bytes(receipt.to_json()) != raw:
+        raise ArtifactError("artifact_receipt_not_canonical")
+    return receipt
+
+
+def load_trusted_receipt(path: Path) -> ArtifactReceipt:
+    """Load one operator-pinned local receipt without contacting the Hub."""
+    descriptor = _open_regular_file(path)
+    try:
+        with os.fdopen(descriptor, "rb") as handle:
+            raw = handle.read(_MAX_RECEIPT_BYTES + 1)
+    except OSError as exc:
+        raise ArtifactError("artifact_receipt_unavailable") from exc
+    if len(raw) > _MAX_RECEIPT_BYTES:
+        raise ArtifactError("artifact_receipt_too_large")
+    return parse_artifact_receipt(raw)
+
+
+__all__ = [
+    "ARTIFACT_BUNDLE_FILES",
+    "ARTIFACT_MANIFEST_PAYLOAD_FILES",
+    "ARTIFACT_MANIFEST_SCHEMA",
+    "ARTIFACT_RECEIPT_SCHEMA",
+    "ARTIFACT_ROOT_SCHEMA",
+    "LEGACY_MODEL_ID",
+    "MODEL_ID",
+    "SUPPORTED_ONNX_OPSET",
+    "ArtifactFile",
+    "ArtifactManifest",
+    "ArtifactReceipt",
+    "artifact_root_sha256",
+    "build_artifact_manifest",
+    "build_artifact_receipt",
+    "canonical_json_bytes",
+    "load_artifact_manifest",
+    "load_trusted_receipt",
+    "parse_artifact_manifest",
+    "parse_artifact_receipt",
+    "verify_artifact_bundle",
+    "verify_artifact_manifest",
+]

inference/src/ax_doclayout/cli.py

@@ -0,0 +1,77 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""``ax-doclayout`` command line: one page raster in, canonical JSON out."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ax_doclayout.contract import PageImage
+from ax_doclayout.errors import AXDocLayoutError, InvalidPageImageError
+from ax_doclayout.model import BACKENDS, AXDocLayout
+
+_PDF_MAGIC = b"%PDF-"
+
+
+def _load_rgb(path: Path):
+    """Decode a page raster; PDFs are rejected by content and by file name."""
+
+    try:
+        with path.open("rb") as stream:
+            head = stream.read(len(_PDF_MAGIC))
+    except OSError as error:
+        raise InvalidPageImageError(
+            f"cannot read page raster: {error.strerror}"
+        ) from None
+    if head.startswith(_PDF_MAGIC) or path.suffix.lower() == ".pdf":
+        raise InvalidPageImageError("the CLI takes a decoded page raster, not a PDF")
+    import numpy as np
+    from PIL import Image, UnidentifiedImageError
+
+    try:
+        with Image.open(path) as image:
+            return np.asarray(image.convert("RGB"), dtype=np.uint8)
+    except (OSError, UnidentifiedImageError, Image.DecompressionBombError, ValueError) as error:
+        raise InvalidPageImageError(
+            f"cannot decode page raster: {type(error).__name__}"
+        ) from None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="ax-doclayout")
+    commands = parser.add_subparsers(dest="command", required=True)
+    predict = commands.add_parser(
+        "predict", help="detect layout regions on one page raster"
+    )
+    predict.add_argument("image", type=Path)
+    predict.add_argument("--page-index", type=int, required=True)
+    predict.add_argument("--model", required=True)
+    predict.add_argument("--revision", required=True)
+    predict.add_argument("--backend", choices=BACKENDS, required=True)
+    predict.add_argument("--output", default="-")
+    arguments = parser.parse_args(argv)
+
+    try:
+        page = PageImage(
+            rgb=_load_rgb(arguments.image), page_index=arguments.page_index
+        )
+        model = AXDocLayout.from_pretrained(
+            arguments.model, revision=arguments.revision, backend=arguments.backend
+        )
+        payload = json.dumps(model.predict(page).to_json(), indent=2)
+    except AXDocLayoutError as error:
+        print(f"ax-doclayout: {error}", file=sys.stderr)
+        return 2
+    if arguments.output == "-":
+        print(payload)
+    else:
+        Path(arguments.output).write_text(payload + "\n", encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

inference/src/ax_doclayout/contract.py

@@ -0,0 +1,286 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Typed values of the raster detection contract (spec sections 4, 5, 7, 9).
+
+Everything here is the consumer-facing shape; nothing here runs a model.
+Every violation raises an ``AXDocLayoutError`` subclass.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from numbers import Integral, Real
+from typing import Any
+
+import numpy as np
+
+from ax_doclayout.errors import AXDocLayoutError, InvalidPageImageError
+
+# stayed because the payload shape is unchanged. The previous prefix is
+# not an alias.
+DETECTION_SCHEMA_VERSION = "ax-doclayout.detection/1"
+TAXONOMY_ID = "ax-doclayout-11/1"
+PREPROCESS_ID = "rgb-letterbox-1024/1"
+COORDINATE_SPACE = "raster-pixels-top-left"
+DEFAULT_THRESHOLD_PROFILE = "default/1"
+
+# Public class ids are preserved; id 0 is reserved and never returned.
+CLASS_NAMES: Mapping[int, str] = {
+    1: "caption",
+    2: "footnote",
+    3: "formula",
+    4: "list_item",
+    5: "page_footer",
+    6: "page_header",
+    7: "picture",
+    8: "section_header",
+    9: "table",
+    10: "text",
+    11: "title",
+}
+
+# Rasters past this many pixels are rejected before any preprocessing.
+MAX_PAGE_PIXELS = 50_000_000
+
+HUB_COMMIT_RE = re.compile(r"^[0-9a-f]{40}$")
+SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+class InvalidPageStructureError(AXDocLayoutError):
+    """A detection result violates the canonical contract."""
+
+
+def _integer(value: object, name: str, *, minimum: int = 0) -> int:
+    """Return ``value`` as a plain int; bools and non-integral types are rejected."""
+
+    if isinstance(value, bool) or not isinstance(value, Integral):
+        raise InvalidPageStructureError(f"{name} must be an integer")
+    result = int(value)
+    if result < minimum:
+        raise InvalidPageStructureError(f"{name} must be >= {minimum}")
+    return result
+
+
+def _finite(value: object, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise InvalidPageStructureError(f"{name} must be a real number")
+    result = float(value)
+    if not math.isfinite(result):
+        raise InvalidPageStructureError(f"{name} must be finite")
+    return result
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class PageImage:
+    """One decoded page raster: HWC ``uint8`` RGB plus its zero-based page index.
+
+    The array is copied to C-contiguous, read-only form on construction so
+    later caller mutation can neither change a validated page nor be frozen
+    as a side effect of constructing one.
+    """
+
+    rgb: np.ndarray
+    page_index: int
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.rgb, np.ndarray):
+            raise InvalidPageImageError("rgb must be a numpy array")
+        if self.rgb.ndim != 3 or self.rgb.shape[2] != 3:
+            raise InvalidPageImageError("rgb must be HWC with three channels")
+        if self.rgb.dtype != np.uint8:
+            raise InvalidPageImageError("rgb must be uint8")
+        height, width = self.rgb.shape[:2]
+        if height == 0 or width == 0:
+            raise InvalidPageImageError("rgb must not be empty")
+        if height * width > MAX_PAGE_PIXELS:
+            raise InvalidPageImageError("rgb exceeds the page pixel limit")
+        if isinstance(self.page_index, bool) or not isinstance(
+            self.page_index, Integral
+        ):
+            raise InvalidPageImageError("page_index must be an int")
+        if self.page_index < 0:
+            raise InvalidPageImageError(
+                "page_index must be zero-based and non-negative"
+            )
+        rgb = np.array(self.rgb, dtype=np.uint8, order="C", copy=True)
+        rgb.setflags(write=False)
+        object.__setattr__(self, "rgb", rgb)
+        object.__setattr__(self, "page_index", int(self.page_index))
+
+    @property
+    def width_px(self) -> int:
+        return int(self.rgb.shape[1])
+
+    @property
+    def height_px(self) -> int:
+        return int(self.rgb.shape[0])
+
+
+@dataclass(frozen=True, slots=True)
+class BoundingBox:
+    """Half-open pixel-edge box ``[x_min, x_max) x [y_min, y_max)`` on the original raster."""
+
+    x_min: float
+    y_min: float
+    x_max: float
+    y_max: float
+
+    def validate(self, width_px: int, height_px: int) -> None:
+        x_min = _finite(self.x_min, "x_min")
+        y_min = _finite(self.y_min, "y_min")
+        x_max = _finite(self.x_max, "x_max")
+        y_max = _finite(self.y_max, "y_max")
+        if not (0 <= x_min < x_max <= width_px):
+            raise InvalidPageStructureError(
+                "bounding box x range must satisfy 0 <= x_min < x_max <= width_px"
+            )
+        if not (0 <= y_min < y_max <= height_px):
+            raise InvalidPageStructureError(
+                "bounding box y range must satisfy 0 <= y_min < y_max <= height_px"
+            )
+
+    def to_json(self) -> dict[str, float]:
+        return {
+            "x_min": float(self.x_min),
+            "y_min": float(self.y_min),
+            "x_max": float(self.x_max),
+            "y_max": float(self.y_max),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class Element:
+    """One detected region. ``id`` is opaque and stable only within its result."""
+
+    id: str
+    class_id: int
+    confidence: float
+    bbox: BoundingBox
+
+    @property
+    def class_name(self) -> str:
+        if isinstance(self.class_id, bool) or self.class_id not in CLASS_NAMES:
+            raise InvalidPageStructureError(f"unknown class id {self.class_id!r}")
+        return CLASS_NAMES[int(self.class_id)]
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "class_id": int(self.class_id),
+            "class_name": self.class_name,
+            "confidence": float(self.confidence),
+            "bbox": self.bbox.to_json(),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ModelIdentity:
+    """The immutable artifact a result came from (spec section 7)."""
+
+    id: str
+    revision: str
+    artifact_sha256: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.id, str) or not self.id.strip():
+            raise InvalidPageStructureError("model id must be a non-empty string")
+        if (
+            not isinstance(self.revision, str)
+            or HUB_COMMIT_RE.fullmatch(self.revision) is None
+        ):
+            raise InvalidPageStructureError(
+                "model revision must be a 40-character immutable Hub commit"
+            )
+        if (
+            not isinstance(self.artifact_sha256, str)
+            or SHA256_RE.fullmatch(self.artifact_sha256) is None
+        ):
+            raise InvalidPageStructureError(
+                "artifact_sha256 must be a 64-character hex digest"
+            )
+
+    def to_json(self) -> dict[str, str]:
+        return {
+            "id": self.id,
+            "revision": self.revision,
+            "artifact_sha256": self.artifact_sha256,
+            "taxonomy": TAXONOMY_ID,
+            "preprocess": PREPROCESS_ID,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class PageStructure:
+    """The canonical detection result for one page (spec section 9)."""
+
+    model: ModelIdentity
+    page_index: int
+    width_px: int
+    height_px: int
+    elements: Sequence[Element] = field(default_factory=tuple)
+    threshold_profile: str = DEFAULT_THRESHOLD_PROFILE
+    threshold_override: float | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.model, ModelIdentity):
+            raise InvalidPageStructureError("model must be a ModelIdentity")
+        object.__setattr__(self, "page_index", _integer(self.page_index, "page_index"))
+        object.__setattr__(
+            self, "width_px", _integer(self.width_px, "width_px", minimum=1)
+        )
+        object.__setattr__(
+            self, "height_px", _integer(self.height_px, "height_px", minimum=1)
+        )
+        if (
+            not isinstance(self.threshold_profile, str)
+            or not self.threshold_profile.strip()
+        ):
+            raise InvalidPageStructureError(
+                "threshold_profile must be a non-empty string"
+            )
+        if self.threshold_override is not None:
+            override = _finite(self.threshold_override, "threshold_override")
+            if not 0.0 <= override <= 1.0:
+                raise InvalidPageStructureError(
+                    "threshold_override must be within [0, 1]"
+                )
+            object.__setattr__(self, "threshold_override", override)
+        elements = tuple(self.elements)
+        object.__setattr__(self, "elements", elements)
+        seen: set[str] = set()
+        for element in elements:
+            if not isinstance(element, Element):
+                raise InvalidPageStructureError("elements must be Element values")
+            if not isinstance(element.id, str) or not element.id:
+                raise InvalidPageStructureError("element ids must be non-empty strings")
+            if element.id in seen:
+                raise InvalidPageStructureError(f"duplicate element id {element.id!r}")
+            seen.add(element.id)
+            _ = element.class_name  # raises for reserved or unknown ids
+            confidence = _finite(element.confidence, "confidence")
+            if not 0.0 <= confidence <= 1.0:
+                raise InvalidPageStructureError("confidence must be within [0, 1]")
+            if not isinstance(element.bbox, BoundingBox):
+                raise InvalidPageStructureError("element bbox must be a BoundingBox")
+            element.bbox.validate(self.width_px, self.height_px)
+
+    def to_json(self) -> dict[str, Any]:
+        inference: dict[str, Any] = {"threshold_profile": self.threshold_profile}
+        if self.threshold_override is not None:
+            inference["threshold_override"] = float(self.threshold_override)
+        return {
+            "schema_version": DETECTION_SCHEMA_VERSION,
+            "model": self.model.to_json(),
+            "page": {
+                "page_index": int(self.page_index),
+                "width_px": int(self.width_px),
+                "height_px": int(self.height_px),
+                "coordinate_space": COORDINATE_SPACE,
+            },
+            "inference": inference,
+            "elements": [element.to_json() for element in self.elements],
+        }

inference/src/ax_doclayout/errors.py

@@ -0,0 +1,45 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Public error types. Messages stay content-free."""
+from __future__ import annotations
+
+
+class AXDocLayoutError(Exception):
+    """Base error for the public contract."""
+
+
+class InvalidPageImageError(AXDocLayoutError):
+    """Page raster failed validation."""
+
+
+class PdfRejectedError(AXDocLayoutError):
+    """CLI and loaders reject PDF inputs."""
+
+
+class UnsupportedBackendError(AXDocLayoutError):
+    """Backend missing, unknown, or unavailable."""
+
+
+class ArtifactError(AXDocLayoutError):
+    """Artifact identity, digest, or files failed closed."""
+
+
+class ArtifactUnavailableError(ArtifactError):
+    """No published immutable artifact is available to load."""
+
+
+class InvalidRevisionError(ArtifactError):
+    """Hub revision is not a 40-character commit."""
+
+
+class BackendUnavailableError(UnsupportedBackendError):
+    """Requested inference backend is missing or unknown."""
+
+
+class InferenceError(AXDocLayoutError):
+    """A loaded backend could not execute page-raster inference."""
+
+
+class TaxonomyError(AXDocLayoutError):
+    """Unknown or reserved class identity."""

inference/src/ax_doclayout/hub_release.py

@@ -0,0 +1,205 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Trusted Hub identity and local verification of the FP32 model bundle."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from ax_doclayout import _hub_pin
+from ax_doclayout.artifact import (
+    MODEL_ID,
+    STAGED_ONNX_SHA256,
+    STAGED_SAFETENSORS_SHA256,
+    ArtifactReceipt,
+    _bundle_files,
+    _open_regular_file,
+    build_artifact_receipt,
+    verify_artifact_bundle,
+    verify_artifact_manifest,
+)
+from ax_doclayout.contract import HUB_COMMIT_RE
+from ax_doclayout.errors import (
+    ArtifactError,
+    ArtifactUnavailableError,
+    BackendUnavailableError,
+    InvalidRevisionError,
+)
+
+PINNED_HUB_RECEIPT = _hub_pin.PINNED_HUB_RECEIPT
+
+_MAX_SAFETENSORS_HEADER = 8 * 1024 * 1024
+# FP32 weights plus the integer batch counters and the one bool mask that
+# PyTorch stores beside them. BF16, FP16, and FP64 are rejected.
+_ALLOWED_SAFETENSORS_DTYPES = frozenset({"F32", "I64", "BOOL"})
+
+
+def safetensors_dtypes(path: Path) -> tuple[str, ...]:
+    """Return tensor dtypes from a safetensors header, without reading weights."""
+
+    descriptor = _open_regular_file(path)
+    try:
+        with os.fdopen(descriptor, "rb") as handle:
+            prefix = handle.read(8)
+            if len(prefix) != 8:
+                raise ArtifactError("staging_safetensors_header_invalid")
+            length = int.from_bytes(prefix, "little")
+            if length <= 0 or length > _MAX_SAFETENSORS_HEADER:
+                raise ArtifactError("staging_safetensors_header_invalid")
+            raw = handle.read(length)
+    except OSError as exc:
+        raise ArtifactError("staging_safetensors_unreadable") from exc
+    if len(raw) != length:
+        raise ArtifactError("staging_safetensors_header_invalid")
+    try:
+        header = json.loads(raw.decode("utf-8"))
+    except (UnicodeError, ValueError) as exc:
+        raise ArtifactError("staging_safetensors_header_invalid") from exc
+    if not isinstance(header, dict):
+        raise ArtifactError("staging_safetensors_header_invalid")
+    dtypes: list[str] = []
+    for key, value in header.items():
+        if not isinstance(key, str):
+            raise ArtifactError("staging_safetensors_header_invalid")
+        if key.startswith("__"):
+            continue
+        if not isinstance(value, dict) or not isinstance(value.get("dtype"), str):
+            raise ArtifactError("staging_safetensors_header_invalid")
+        dtypes.append(value["dtype"])
+    if not dtypes:
+        raise ArtifactError("staging_safetensors_empty")
+    return tuple(dtypes)
+
+
+def _require_fp32_weights(path: Path) -> None:
+    dtypes = set(safetensors_dtypes(path))
+    if "F32" not in dtypes or not dtypes <= _ALLOWED_SAFETENSORS_DTYPES:
+        raise ArtifactError("staging_safetensors_not_fp32")
+
+
+def verify_staged_v01_bundle(
+    directory: Path,
+    receipt_path: Path,
+    *,
+    require_staged_digests: bool = True,
+) -> None:
+    """Fail closed unless a nine-file bundle is FP32 and still unpublished."""
+
+    from ax_doclayout._local_pytorch import read_publishable
+
+    if read_publishable(receipt_path):
+        raise ArtifactError("staging_publishable_must_stay_false")
+    verify_artifact_manifest(directory)
+    observed = _bundle_files(directory)
+    by_name = {item.name: item.sha256 for item in observed}
+    if require_staged_digests and (
+        by_name["model.safetensors"] != STAGED_SAFETENSORS_SHA256
+        or by_name["model.onnx"] != STAGED_ONNX_SHA256
+    ):
+        raise ArtifactError("staging_weight_digest_mismatch")
+    _require_fp32_weights(directory / "model.safetensors")
+    _require_receipt_agreement(receipt_path, by_name)
+
+
+def _require_receipt_agreement(receipt_path: Path, by_name: dict[str, str]) -> None:
+    try:
+        payload = json.loads(receipt_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise ArtifactError("staging_receipt_unreadable") from exc
+    if not isinstance(payload, dict):
+        raise ArtifactError("staging_receipt_unreadable")
+    model_id = payload.get("model_id", MODEL_ID)
+    if model_id != MODEL_ID:
+        raise ArtifactError("artifact_model_id_invalid")
+    files = payload.get("artifact_files")
+    if files is None:
+        return
+    if not isinstance(files, list):
+        raise ArtifactError("staging_receipt_unreadable")
+    for item in files:
+        if not isinstance(item, dict):
+            raise ArtifactError("staging_receipt_unreadable")
+        name = item.get("name")
+        digest = item.get("sha256")
+        if name in by_name and digest != by_name[name]:
+            raise ArtifactError("staging_receipt_digest_mismatch")
+
+
+def qualify_published_bundle(
+    *,
+    model_id: str,
+    revision: str,
+    backend: str,
+    receipt: ArtifactReceipt | None,
+    bundle: Path | None,
+) -> Path | None:
+    """Verify one pinned receipt against local bytes.
+
+    ``None`` means no production receipt is pinned. A pinned receipt with a
+    missing or mismatched bundle raises. This function does not download and
+    does not run a backend.
+    """
+
+    if receipt is None:
+        return None
+    if backend not in ("pytorch", "onnx"):
+        raise BackendUnavailableError(
+            "backend must be given explicitly as one of pytorch, onnx"
+        )
+    if model_id != MODEL_ID or model_id != receipt.model_id:
+        raise ArtifactError("artifact_model_id_invalid")
+    if revision != receipt.model_revision:
+        raise ArtifactError("artifact_revision_invalid")
+    if bundle is None:
+        raise ArtifactUnavailableError(
+            "published bundle is not available for hash verification"
+        )
+    verify_artifact_bundle(bundle, receipt)
+    _require_fp32_weights(bundle / "model.safetensors")
+    return bundle
+
+
+SIGN_OFF_FIELDS = ("adr_0031", "license_pack", "model_card")
+
+
+def require_publication_signoff(path: Path) -> None:
+    """Refuse publication until ADR-0031 and the license pack are approved."""
+
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise ArtifactError("publication_signoff_missing") from exc
+    if not isinstance(payload, dict):
+        raise ArtifactError("publication_signoff_missing")
+    for field in SIGN_OFF_FIELDS:
+        if payload.get(field) != "approved":
+            raise ArtifactError("publication_signoff_incomplete")
+
+
+def publish_redownloaded_bundle(
+    *,
+    bundle: Path,
+    staging_receipt: Path,
+    signoff: Path,
+    revision: str,
+    downloaded: Path,
+    require_staged_digests: bool = True,
+) -> ArtifactReceipt:
+    """Build a receipt only after a redownload matches the staged nine files."""
+
+    require_publication_signoff(signoff)
+    verify_staged_v01_bundle(
+        bundle,
+        staging_receipt,
+        require_staged_digests=require_staged_digests,
+    )
+    if not isinstance(revision, str) or HUB_COMMIT_RE.fullmatch(revision) is None:
+        raise InvalidRevisionError(
+            "revision must be a 40-character immutable Hub commit"
+        )
+    if _bundle_files(bundle) != _bundle_files(downloaded):
+        raise ArtifactError("hub_redownload_digest_mismatch")
+    return build_artifact_receipt(downloaded, model_revision=revision)

inference/src/ax_doclayout/local_detection.py

@@ -0,0 +1,62 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Canonical JSON for unqualified local detections.
+
+Both the local ONNX runner and the local PyTorch runner serialize through
+this function. The payload is not a published ``PageStructure``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ax_doclayout.artifact import canonical_json_bytes
+from ax_doclayout.contract import Element
+
+LOCAL_DETECTION_SCHEMA = "ax-doclayout.local-detection/1"
+LOCAL_QUALIFICATION = "local-bundle-unqualified"
+# Shared unqualified serialization. PyTorch and ONNX agree well inside
+# these places; the published parity gate is coarser (0.5 px, 0.001 score).
+SCORE_DECIMALS = 4
+BOX_DECIMALS = 3
+
+
+def _places(value: float, places: int) -> float:
+    return round(float(value), places)
+
+
+def canonical_local_detection_bytes(
+    *,
+    page_index: int,
+    width_px: int,
+    height_px: int,
+    elements: Sequence[Element],
+    threshold: float,
+) -> bytes:
+    """Serialize one unqualified page detection with sorted keys."""
+
+    payload = {
+        "elements": [
+            {
+                "bbox": {
+                    "x_max": _places(element.bbox.x_max, BOX_DECIMALS),
+                    "x_min": _places(element.bbox.x_min, BOX_DECIMALS),
+                    "y_max": _places(element.bbox.y_max, BOX_DECIMALS),
+                    "y_min": _places(element.bbox.y_min, BOX_DECIMALS),
+                },
+                "class_id": int(element.class_id),
+                "class_name": element.class_name,
+                "confidence": _places(element.confidence, SCORE_DECIMALS),
+                "id": element.id,
+            }
+            for element in elements
+        ],
+        "height_px": int(height_px),
+        "page_index": int(page_index),
+        "qualification": LOCAL_QUALIFICATION,
+        "schema_version": LOCAL_DETECTION_SCHEMA,
+        "threshold": float(threshold),
+        "width_px": int(width_px),
+    }
+    return canonical_json_bytes(payload)

inference/src/ax_doclayout/local_onnx.py

@@ -0,0 +1,26 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Unqualified local nine-file ONNX runner.
+
+This is a public operator surface for a digest-pinned staging bundle. It is
+not ``from_pretrained``, does not claim a Hub revision, and does not emit a
+DocLayout-YOLO result shape.
+"""
+
+from __future__ import annotations
+
+from ax_doclayout._local_onnx import (
+    QUALIFICATION,
+    LocalOnnxBundle,
+    LocalOnnxResult,
+)
+from ax_doclayout.artifact import SOURCE_CHECKPOINT_SHA256, STAGED_ONNX_SHA256
+
+__all__ = [
+    "QUALIFICATION",
+    "SOURCE_CHECKPOINT_SHA256",
+    "STAGED_ONNX_SHA256",
+    "LocalOnnxBundle",
+    "LocalOnnxResult",
+]

inference/src/ax_doclayout/model.py

@@ -0,0 +1,158 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Load a verified immutable Hub bundle and detect layout on RGB pages."""
+
+from __future__ import annotations
+
+import importlib
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from ax_doclayout.artifact import MODEL_ID, ArtifactReceipt
+from ax_doclayout.contract import (
+    HUB_COMMIT_RE,
+    Element,
+    ModelIdentity,
+    PageImage,
+    PageStructure,
+)
+from ax_doclayout.errors import (
+    ArtifactError,
+    ArtifactUnavailableError,
+    AXDocLayoutError,
+    BackendUnavailableError,
+    InferenceError,
+    InvalidPageImageError,
+    InvalidRevisionError,
+)
+from ax_doclayout.hub_release import PINNED_HUB_RECEIPT, qualify_published_bundle
+from ax_doclayout.postprocess import page_structure_from_elements
+
+BACKENDS = ("pytorch", "onnx")
+_PredictElements = Callable[[PageImage], tuple[Element, ...]]
+
+
+def _download_bundle(directory: Path, *, receipt: ArtifactReceipt) -> None:
+    """Materialize regular files from the Hub cache before strict verification."""
+
+    try:
+        from huggingface_hub import hf_hub_download
+    except ImportError:
+        raise BackendUnavailableError("huggingface-hub is not installed") from None
+    try:
+        for item in receipt.artifact_files:
+            cached = hf_hub_download(
+                repo_id=receipt.model_id,
+                filename=item.name,
+                revision=receipt.model_revision,
+                token=False,
+            )
+            # Hub cache entries may be symlinks. Only the copied, hash-verified
+            # regular files are handed to artifact validation and the backend.
+            shutil.copyfile(cached, directory / item.name)
+    except Exception:  # noqa: BLE001 - redact third-party download error details
+        raise ArtifactUnavailableError("hub_bundle_download_failed") from None
+
+
+def _load_backend(directory: Path, *, backend: str) -> _PredictElements:
+    """Load all backend state before the temporary verified bundle is removed."""
+
+    if backend == "pytorch":
+        from ax_doclayout._local_pytorch import LocalPytorchBundle
+
+        return LocalPytorchBundle(directory).predict_elements
+
+    import onnxruntime as ort
+
+    from ax_doclayout._cuda_onnx import create_cuda_session
+    from ax_doclayout._local_onnx import LocalOnnxBundle
+
+    session = create_cuda_session(directory / "model.onnx", ort=ort)
+    runner = LocalOnnxBundle(
+        directory, session_run=lambda feeds: session.run(None, dict(feeds)),
+    )
+
+    def predict_elements(page: PageImage) -> tuple[Element, ...]:
+        return runner.predict(page).elements
+
+    return predict_elements
+
+
+class AXDocLayout:
+    """A trusted Hub artifact with explicit CUDA ONNX or CPU PyTorch inference."""
+
+    def __init__(self, model_id: str, revision: str, backend: str) -> None:
+        self.model_id = model_id
+        self.revision = revision
+        self.backend = backend
+        self._predict_elements: _PredictElements | None = None
+        self._identity: ModelIdentity | None = None
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        model_id: str,
+        *,
+        revision: str,
+        backend: str | None = None,
+    ) -> AXDocLayout:
+        if not isinstance(revision, str) or HUB_COMMIT_RE.fullmatch(revision) is None:
+            raise InvalidRevisionError(
+                "revision must be a 40-character immutable Hub commit; "
+                "'main', a tag, or 'latest' is not accepted"
+            )
+        if not isinstance(backend, str) or backend not in BACKENDS:
+            raise BackendUnavailableError(
+                "backend must be given explicitly as one of pytorch, onnx"
+            )
+        receipt = PINNED_HUB_RECEIPT
+        if not isinstance(model_id, str) or model_id != MODEL_ID:
+            raise ArtifactError("artifact_model_id_invalid")
+        if receipt is None or revision != receipt.model_revision:
+            raise ArtifactUnavailableError("no trusted artifact for this revision")
+        try:
+            dependencies = ("torch", "safetensors") if backend == "pytorch" else ("onnxruntime",)
+            for dependency in dependencies:
+                try:
+                    importlib.import_module(dependency)
+                except (ImportError, OSError):
+                    raise BackendUnavailableError("requested backend is not installed") from None
+            with TemporaryDirectory(prefix="ax-doclayout-hub-") as temporary:
+                directory = Path(temporary)
+                _download_bundle(directory, receipt=receipt)
+                qualified = qualify_published_bundle(
+                    model_id=model_id, revision=revision, backend=backend,
+                    receipt=receipt, bundle=directory,
+                )
+                if qualified is None:
+                    raise ArtifactUnavailableError("no trusted artifact for this revision")
+                predictor = _load_backend(qualified, backend=backend)
+        except AXDocLayoutError:
+            raise
+        except Exception:  # noqa: BLE001 - keep public errors content-free
+            raise ArtifactError("hub_backend_load_failed") from None
+        model = cls(model_id, revision, backend)
+        model._predict_elements = predictor
+        model._identity = ModelIdentity(
+            id=receipt.model_id, revision=receipt.model_revision,
+            artifact_sha256=receipt.artifact_sha256.removeprefix("sha256:"),
+        )
+        return model
+
+    def predict(self, page: PageImage) -> PageStructure:
+        if self._predict_elements is None or self._identity is None:
+            raise ArtifactUnavailableError("no loaded artifact; construct through from_pretrained")
+        if not isinstance(page, PageImage):
+            raise InvalidPageImageError("page must be a PageImage")
+        try:
+            elements = self._predict_elements(page)
+            return page_structure_from_elements(
+                page=page, elements=elements, identity=self._identity,
+            )
+        except AXDocLayoutError:
+            raise
+        except Exception:  # noqa: BLE001 - keep public errors content-free
+            raise InferenceError("page_inference_failed") from None

inference/src/ax_doclayout/postprocess.py

@@ -0,0 +1,126 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Map letterbox-space detector outputs onto canonical ``PageStructure`` elements.
+
+Class id 0 is reserved and never returned. Names that exist only on the
+DocLayout-YOLO incumbent (``figure_caption``, ``table_caption``, and similar)
+are not invented here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+
+from ax_doclayout.contract import (
+    CLASS_NAMES,
+    DEFAULT_THRESHOLD_PROFILE,
+    BoundingBox,
+    Element,
+    InvalidPageStructureError,
+    ModelIdentity,
+    PageImage,
+    PageStructure,
+)
+from ax_doclayout.preprocess import Letterbox
+
+DEFAULT_SCORE_THRESHOLD = 0.30
+
+
+def elements_from_letterbox_detections(
+    *,
+    labels: object,
+    boxes: object,
+    scores: object,
+    page: PageImage,
+    letterbox: Letterbox,
+    threshold: float = DEFAULT_SCORE_THRESHOLD,
+) -> tuple[Element, ...]:
+    """Keep finite, in-range detections and invert them onto the original raster."""
+
+    try:
+        threshold_value = float(threshold)
+    except (TypeError, ValueError) as exc:
+        raise InvalidPageStructureError("threshold must be within [0, 1]") from exc
+    if not 0.0 <= threshold_value <= 1.0:
+        raise InvalidPageStructureError("threshold must be within [0, 1]")
+    try:
+        label_array = np.asarray(labels)
+        box_array = np.asarray(boxes, dtype=np.float64)
+        score_array = np.asarray(scores, dtype=np.float64)
+    except (TypeError, ValueError) as exc:
+        raise InvalidPageStructureError(
+            "detection arrays must be rectangular numeric arrays"
+        ) from exc
+    if label_array.ndim == 0 or box_array.ndim == 0 or score_array.ndim == 0:
+        raise InvalidPageStructureError("detection arrays must share a length")
+    if label_array.ndim == 2 and label_array.shape[0] == 1:
+        if box_array.ndim != 3 or score_array.ndim != 2:
+            raise InvalidPageStructureError("detection arrays must share a batch dimension")
+        if box_array.shape[0] != 1 or score_array.shape[0] != 1:
+            raise InvalidPageStructureError("detection arrays must share a batch dimension")
+        label_array = label_array[0]
+        box_array = box_array[0]
+        score_array = score_array[0]
+    if box_array.ndim != 2 or box_array.shape[1] != 4:
+        raise InvalidPageStructureError("boxes must be an N x 4 xyxy array")
+    if label_array.ndim != 1 or score_array.ndim != 1:
+        raise InvalidPageStructureError("detection arrays must share a length")
+    if label_array.shape[0] != box_array.shape[0] or label_array.shape[0] != score_array.shape[0]:
+        raise InvalidPageStructureError("detection arrays must share a length")
+    if not np.isfinite(letterbox.scale) or letterbox.scale <= 0.0:
+        return ()
+    # Apply identical float64 geometry in bulk before allocating Python objects.
+    valid = (
+        np.isfinite(box_array).all(axis=1)
+        & np.isfinite(score_array)
+        & (score_array >= threshold_value)
+        & (score_array <= 1.0)
+    )
+    indices = np.flatnonzero(valid)
+    mapped = box_array[indices].copy()
+    mapped -= [letterbox.pad_left, letterbox.pad_top,
+               letterbox.pad_left, letterbox.pad_top]
+    mapped /= letterbox.scale
+    np.clip(mapped, 0.0, [page.width_px, page.height_px,
+                         page.width_px, page.height_px], out=mapped)
+    nonempty = (mapped[:, 0] < mapped[:, 2]) & (mapped[:, 1] < mapped[:, 3])
+    kept: list[Element] = []
+    for index, box in zip(indices[nonempty], mapped[nonempty], strict=True):
+        try:
+            class_id = int(label_array[index])
+        except (TypeError, ValueError, OverflowError):
+            continue
+        if class_id not in CLASS_NAMES:
+            continue
+        kept.append(
+            Element(
+                id=f"{page.page_index}:{len(kept)}",
+                class_id=class_id,
+                confidence=float(score_array[index]),
+                bbox=BoundingBox(*(float(value) for value in box)),
+            )
+        )
+    return tuple(kept)
+
+
+def page_structure_from_elements(
+    *,
+    page: PageImage,
+    elements: Sequence[Element],
+    identity: ModelIdentity,
+    threshold_override: float | None = None,
+) -> PageStructure:
+    """Bind already-inverted elements to a caller-supplied model identity."""
+
+    return PageStructure(
+        model=identity,
+        page_index=page.page_index,
+        width_px=page.width_px,
+        height_px=page.height_px,
+        elements=tuple(elements),
+        threshold_profile=DEFAULT_THRESHOLD_PROFILE,
+        threshold_override=threshold_override,
+    )

inference/src/ax_doclayout/preprocess.py

@@ -0,0 +1,145 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Public ``rgb-letterbox-1024/1`` geometry. Independent of any detector graph.
+
+This is the signed AXDocLayout-M v1.2 preprocess: HWC uint8 RGB, bilinear resize of the
+longer side to 1024, white pad, odd remainder bottom/right, then inverse
+mapping of letterbox-space boxes back onto the original raster.
+
+It is not a DocLayout-YOLO drop-in. That incumbent uses a different colour
+order, a different pad value, and a different class vocabulary. Those
+differences are left unmapped on purpose.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from PIL import Image
+
+from ax_doclayout.contract import PREPROCESS_ID, PageImage
+from ax_doclayout.errors import InvalidPageImageError
+
+SIZE = 1024
+PAD_RGB = (255, 255, 255)
+FILL_SCALE = 1.0 / 255.0
+
+
+@dataclass(frozen=True, slots=True)
+class Letterbox:
+    """One 1024-square canvas plus the exact inverse-mapping terms."""
+
+    canvas: np.ndarray
+    scale: float
+    pad_left: int
+    pad_top: int
+    pad_right: int
+    pad_bottom: int
+    size: int = SIZE
+
+    def __post_init__(self) -> None:
+        canvas = np.ascontiguousarray(self.canvas)
+        if canvas.ndim != 3 or canvas.shape != (self.size, self.size, 3):
+            raise InvalidPageImageError("letterbox canvas must be size x size x 3")
+        if canvas.dtype != np.uint8:
+            raise InvalidPageImageError("letterbox canvas must be uint8")
+        object.__setattr__(self, "canvas", canvas)
+
+
+def letterbox_rgb(rgb: np.ndarray, *, size: int = SIZE) -> Letterbox:
+    """Letterbox a decoded HWC uint8 RGB array under ``rgb-letterbox-1024/1``."""
+
+    if not isinstance(rgb, np.ndarray):
+        raise InvalidPageImageError("rgb must be a numpy array")
+    if rgb.ndim != 3 or rgb.shape[2] != 3:
+        raise InvalidPageImageError("rgb must be HWC with three channels")
+    if rgb.dtype != np.uint8:
+        raise InvalidPageImageError("rgb must be uint8")
+    height, width = (int(rgb.shape[0]), int(rgb.shape[1]))
+    if height < 1 or width < 1:
+        raise InvalidPageImageError("rgb must not be empty")
+    scale = size / max(width, height)
+    new_width = max(1, round(width * scale))
+    new_height = max(1, round(height * scale))
+    image = Image.fromarray(np.ascontiguousarray(rgb), mode="RGB")
+    resized = image.resize((new_width, new_height), Image.BILINEAR)
+    pad_width = size - new_width
+    pad_height = size - new_height
+    pad_left = pad_width // 2
+    pad_right = pad_width - pad_left
+    pad_top = pad_height // 2
+    pad_bottom = pad_height - pad_top
+    if pad_right < 0 or pad_bottom < 0:
+        raise InvalidPageImageError("letterbox overflow")
+    canvas = Image.new("RGB", (size, size), PAD_RGB)
+    canvas.paste(resized, (pad_left, pad_top))
+    return Letterbox(
+        canvas=np.asarray(canvas, dtype=np.uint8),
+        scale=float(scale),
+        pad_left=int(pad_left),
+        pad_top=int(pad_top),
+        pad_right=int(pad_right),
+        pad_bottom=int(pad_bottom),
+        size=int(size),
+    )
+
+
+def letterbox_page(page: PageImage, *, size: int = SIZE) -> Letterbox:
+    """Letterbox a validated ``PageImage``."""
+
+    return letterbox_rgb(page.rgb, size=size)
+
+
+def letterbox_nchw(letterbox: Letterbox) -> np.ndarray:
+    """Return a batch-1 NCHW float32 tensor in ``[0, 1]``."""
+
+    chw = np.transpose(letterbox.canvas, (2, 0, 1)).astype(np.float32)
+    chw *= np.float32(FILL_SCALE)
+    return np.ascontiguousarray(chw[None, ...])
+
+
+def inverse_letterbox_box(
+    box: tuple[float, float, float, float] | list[float],
+    letterbox: Letterbox,
+    *,
+    width_px: int,
+    height_px: int,
+) -> tuple[float, float, float, float] | None:
+    """Map a letterbox xyxy box onto the original raster, or drop it."""
+
+    if width_px < 1 or height_px < 1:
+        return None
+    try:
+        x_min, y_min, x_max, y_max = (float(value) for value in box)
+    except (TypeError, ValueError):
+        return None
+    if not all(np.isfinite(value) for value in (x_min, y_min, x_max, y_max)):
+        return None
+    scale = letterbox.scale
+    if scale <= 0.0:
+        return None
+    mapped = (
+        (x_min - letterbox.pad_left) / scale,
+        (y_min - letterbox.pad_top) / scale,
+        (x_max - letterbox.pad_left) / scale,
+        (y_max - letterbox.pad_top) / scale,
+    )
+    clipped_x_min = min(max(mapped[0], 0.0), float(width_px))
+    clipped_y_min = min(max(mapped[1], 0.0), float(height_px))
+    clipped_x_max = min(max(mapped[2], 0.0), float(width_px))
+    clipped_y_max = min(max(mapped[3], 0.0), float(height_px))
+    if clipped_x_min >= clipped_x_max or clipped_y_min >= clipped_y_max:
+        return None
+    return clipped_x_min, clipped_y_min, clipped_x_max, clipped_y_max
+
+
+def orig_target_sizes(letterbox: Letterbox) -> np.ndarray:
+    """Sizes fed to the exported graph. The graph is bound to the letterbox square."""
+
+    side = np.int64(letterbox.size)
+    return np.ascontiguousarray([[side, side]])
+
+
+PREPROCESS = PREPROCESS_ID

inference/src/ax_doclayout/taxonomy.py

@@ -0,0 +1,56 @@
+# Copyright 2026 AutomatosX
+# SPDX-License-Identifier: AGPL-3.0-only
+# Modified 2026-10-17 for v1.2; prior component notices are in NOTICE.
+"""Canonical 11-class layout taxonomy."""
+from __future__ import annotations
+
+from ax_doclayout.errors import TaxonomyError
+
+TAXONOMY_ID = "ax-doclayout-11/1"
+RESERVED_ID = 0
+
+CLASS_NAMES: dict[int, str] = {
+    1: "caption",
+    2: "footnote",
+    3: "formula",
+    4: "list_item",
+    5: "page_footer",
+    6: "page_header",
+    7: "picture",
+    8: "section_header",
+    9: "table",
+    10: "text",
+    11: "title",
+}
+
+NAME_TO_ID: dict[str, int] = {name: class_id for class_id, name in CLASS_NAMES.items()}
+
+
+def public_name(class_id: int) -> str:
+    if class_id == RESERVED_ID:
+        raise TaxonomyError("class_id_reserved")
+    try:
+        return CLASS_NAMES[class_id]
+    except KeyError as exc:
+        raise TaxonomyError("class_id_unknown") from exc
+
+
+def public_id(class_name: str) -> int:
+    try:
+        return NAME_TO_ID[class_name]
+    except KeyError as exc:
+        raise TaxonomyError("class_name_unknown") from exc
+
+
+def to_internal(class_id: int) -> int:
+    """Map public 1–11 to zero-based indices 0–10."""
+    if class_id not in CLASS_NAMES:
+        raise TaxonomyError("class_id_unknown")
+    return class_id - 1
+
+
+def from_internal(index: int) -> int:
+    class_id = index + 1
+    if class_id not in CLASS_NAMES:
+        raise TaxonomyError("class_id_unknown")
+    return class_id