@sahan-sac/ai-core 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,40 +1,48 @@
-# @sahan-sac/ai-core
-
-## 0.4.0
-
-### Minor Changes
-
-- 396e692: Three more free-tier adapters:
-  - `groq`: Groq free plan, keyed by `GROQ_API_KEY`. Default models `openai/gpt-oss-120b` for the blog and `openai/gpt-oss-20b` for chat.
-  - `mistral`: Mistral free Experiment plan, keyed by `MISTRAL_API_KEY`. This plan may train on prompts, so the adapter runs in the blog chain only unless `AI_PROVIDER_ORDER_CHAT` lists it.
-  - `cloudflare`: Cloudflare Workers AI, with 10,000 free neurons a day. Needs `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_AI_API_TOKEN`.
-  
-  None of them is paid, so none needs `AI_ALLOW_PAID`. Each model can be overridden per purpose. Adapters gain an optional `defaultPurposes`.
-
-### Patch Changes
-
-- 1570cf6: A provider that answers 402 (no credits, or an empty prepaid wallet) now cools down for 30 minutes instead of being retried on every request, so an unfunded account costs one probe per window rather than a failed round trip each time. `cooldownFor` is exported.
-
-## 0.3.1
-
-### Patch Changes
-
-- 5e7f3cb: The build shares modules between subpaths (code splitting) instead of copying them into each one. Before, a class imported from two subpaths was two different classes, so `instanceof` failed (for example `EmailGuardError` from `@sahan-sac/email-kit/guards` against an error thrown through `./layout`), and module-level state such as caches existed once per subpath.
-
-## 0.3.0
-
-### Minor Changes
-
-- b9d2dd6: `createAiService().generate()` takes an optional `signal`. Aborting it stops the chain at once: running attempts are aborted, no further provider starts, and the result is `errorClass: "aborted"`. Aborted attempts are not logged and do not put a provider into cooldown.
-- 4fa21e3: Provider registry and more providers. New `@sahan-sac/ai-core/adapters`: each provider is an adapter with its own env guard and paid flag (`BUILTIN_ADAPTERS`), and `realProviders` builds the chain from it. Added OpenAI, Anthropic (Messages API over REST), DeepSeek, xAI, Perplexity and one custom OpenAI-compatible endpoint (`AI_CUSTOM_*`), all paid and gated by `AI_ALLOW_PAID` (the custom one unless `AI_CUSTOM_FREE`). `AI_PROVIDER_ORDER`, `AI_PROVIDER_ORDER_BLOG` and `AI_PROVIDER_ORDER_CHAT` choose which providers run and in what order; an explicit order is kept as given (`AiProvider.priority`), while cooling providers still drop behind healthy ones. `providerStatuses` explains each adapter's place for health screens, `textAiConfigured(env, purpose?)` checks one purpose's chain, and apps can pass their own adapters to `realProviders`. New factories `openAiCompatibleProvider` and `anthropicProvider`. Existing variables and `realProviders(env, purpose, fetch?)` work as before.
-- f465908: Owner guidance and on-demand checks. `@sahan-sac/ai-core/guard` adds `guidanceSection(text)`, which appends the site owner's standing guidance after a prompt's fixed rules (it steers, never overrides them, and never changes how fenced data is treated), `mergeGuidance(...parts)` to join global and per-feature guidance, and an optional `maxLength` on `wrapUserData`. `@sahan-sac/ai-core/adapters` adds `checkProvider(env, id)` and `checkChain(env, purpose)`: each sends a one-line prompt (a few tokens) through one adapter or a whole chain and reports who answered, how long it took and every fall-through, for a health screen's manual Check button. Neither runs on its own, and neither cools a provider down for real traffic.
-
-## 0.2.0
-
-No changes in this release.
-
-## 0.1.0
-
-### Minor Changes
-
-- b620f44: First release. ai-core: the free-by-default provider chain (Gemini, OpenRouter, NVIDIA, then paid Vertex) with hedging, cooldowns and deadlines, env-driven model resolution, image generation, prompt guards and the shared env schema (ENABLE_BLOG_AI, ENABLE_CHATBOT). blog-kit: full-post, SEO, draft and cover generation, AI images through an ImageSink port, and pure blog utilities. chat-kit: runChat, guarded prompts, output filtering, the knowledge builder, the ChatStore contract and the visitor rate-limit cookie. Licensed Apache-2.0.
+# @sahan-sac/ai-core
+
+## 0.5.0
+
+### Minor Changes
+
+- c0127d5: OmniRoute provider. `omniroute` is a free adapter for a self-hosted OmniRoute gateway: one OpenAI-compatible endpoint that pools many providers' free tiers and fails over between them. It turns on with `OMNIROUTE_BASE_URL` (https, or http on localhost; `/v1` is added when missing; credentials in the URL are refused), sends `OMNIROUTE_API_KEY` when set, and defaults to the gateway's `auto/best-free` model (`OMNIROUTE_MODEL`, `BLOG_OMNIROUTE_MODEL` and `CHAT_OMNIROUTE_MODEL` override it). It is first in the default order, so it leads the chat and blog chains whenever it is configured, and it never needs `AI_ALLOW_PAID`.
+  
+  Free only, even with `AI_ALLOW_PAID`: a model override that is not a free route (`isFreeRoute`: ends `-free` or `:free`) is replaced by `auto/best-free`. `OMNIROUTE_ALLOW_PAID` lets an override name a paid route, but only together with `AI_ALLOW_PAID`; the gateway then counts as paid for that purpose and runs as a last resort. `ProviderAdapter.paid` takes an optional `purpose`, so an adapter can be paid for one purpose and free for the other.
+
+## 0.4.0
+
+### Minor Changes
+
+- 396e692: Three more free-tier adapters:
+  - `groq`: Groq free plan, keyed by `GROQ_API_KEY`. Default models `openai/gpt-oss-120b` for the blog and `openai/gpt-oss-20b` for chat.
+  - `mistral`: Mistral free Experiment plan, keyed by `MISTRAL_API_KEY`. This plan may train on prompts, so the adapter runs in the blog chain only unless `AI_PROVIDER_ORDER_CHAT` lists it.
+  - `cloudflare`: Cloudflare Workers AI, with 10,000 free neurons a day. Needs `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_AI_API_TOKEN`.
+  
+  None of them is paid, so none needs `AI_ALLOW_PAID`. Each model can be overridden per purpose. Adapters gain an optional `defaultPurposes`.
+
+### Patch Changes
+
+- 1570cf6: A provider that answers 402 (no credits, or an empty prepaid wallet) now cools down for 30 minutes instead of being retried on every request, so an unfunded account costs one probe per window rather than a failed round trip each time. `cooldownFor` is exported.
+
+## 0.3.1
+
+### Patch Changes
+
+- 5e7f3cb: The build shares modules between subpaths (code splitting) instead of copying them into each one. Before, a class imported from two subpaths was two different classes, so `instanceof` failed (for example `EmailGuardError` from `@sahan-sac/email-kit/guards` against an error thrown through `./layout`), and module-level state such as caches existed once per subpath.
+
+## 0.3.0
+
+### Minor Changes
+
+- b9d2dd6: `createAiService().generate()` takes an optional `signal`. Aborting it stops the chain at once: running attempts are aborted, no further provider starts, and the result is `errorClass: "aborted"`. Aborted attempts are not logged and do not put a provider into cooldown.
+- 4fa21e3: Provider registry and more providers. New `@sahan-sac/ai-core/adapters`: each provider is an adapter with its own env guard and paid flag (`BUILTIN_ADAPTERS`), and `realProviders` builds the chain from it. Added OpenAI, Anthropic (Messages API over REST), DeepSeek, xAI, Perplexity and one custom OpenAI-compatible endpoint (`AI_CUSTOM_*`), all paid and gated by `AI_ALLOW_PAID` (the custom one unless `AI_CUSTOM_FREE`). `AI_PROVIDER_ORDER`, `AI_PROVIDER_ORDER_BLOG` and `AI_PROVIDER_ORDER_CHAT` choose which providers run and in what order; an explicit order is kept as given (`AiProvider.priority`), while cooling providers still drop behind healthy ones. `providerStatuses` explains each adapter's place for health screens, `textAiConfigured(env, purpose?)` checks one purpose's chain, and apps can pass their own adapters to `realProviders`. New factories `openAiCompatibleProvider` and `anthropicProvider`. Existing variables and `realProviders(env, purpose, fetch?)` work as before.
+- f465908: Owner guidance and on-demand checks. `@sahan-sac/ai-core/guard` adds `guidanceSection(text)`, which appends the site owner's standing guidance after a prompt's fixed rules (it steers, never overrides them, and never changes how fenced data is treated), `mergeGuidance(...parts)` to join global and per-feature guidance, and an optional `maxLength` on `wrapUserData`. `@sahan-sac/ai-core/adapters` adds `checkProvider(env, id)` and `checkChain(env, purpose)`: each sends a one-line prompt (a few tokens) through one adapter or a whole chain and reports who answered, how long it took and every fall-through, for a health screen's manual Check button. Neither runs on its own, and neither cools a provider down for real traffic.
+
+## 0.2.0
+
+No changes in this release.
+
+## 0.1.0
+
+### Minor Changes
+
+- b620f44: First release. ai-core: the free-by-default provider chain (Gemini, OpenRouter, NVIDIA, then paid Vertex) with hedging, cooldowns and deadlines, env-driven model resolution, image generation, prompt guards and the shared env schema (ENABLE_BLOG_AI, ENABLE_CHATBOT). blog-kit: full-post, SEO, draft and cover generation, AI images through an ImageSink port, and pure blog utilities. chat-kit: runChat, guarded prompts, output filtering, the knowledge builder, the ChatStore contract and the visitor rate-limit cookie. Licensed Apache-2.0.

package/LICENSE

@@ -1,202 +1,202 @@
-                                 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 2026 Sahan Sachintha
-
-   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.
+                                 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 2026 Sahan Sachintha
+
+   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.

package/README.md

@@ -57,6 +57,8 @@ const schema = z.object({ ...aiEnvSchema.shape, DATABASE_URL: z.string() });
 | `OPENROUTER_BASE_URL`, `OPENROUTER_ALLOW_PAID_MODELS` | OpenRouter API, `false` | OpenRouter settings |
 | `OPENAI_API_KEY`, `OPENAI_BASE_URL` | unset, OpenAI API | OpenAI (paid); the base URL also points it at any OpenAI-compatible gateway |
 | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` | unset, Anthropic API | Anthropic Messages API over REST (paid) |
+| `OMNIROUTE_BASE_URL`, `OMNIROUTE_API_KEY` | unset | Your self-hosted [OmniRoute](https://github.com/diegosouzapw/OmniRoute) gateway (https, or http on localhost; `/v1` added when missing) and its gateway key. Free only and first in the default order when set. Model `auto/best-free`; override with `OMNIROUTE_MODEL` or `BLOG_`/`CHAT_` variants. An override must be a free route (ends `-free` or `:free`), or the free default replaces it |
+| `OMNIROUTE_ALLOW_PAID` | `false` | Lets an OmniRoute override name a paid route. `AI_ALLOW_PAID` alone never does; both must be on, and the paid route then runs as a last resort |
 | `GROQ_API_KEY` | unset | Groq free plan (no card). Models `openai/gpt-oss-120b` (blog) and `openai/gpt-oss-20b` (chat); override with `GROQ_MODEL` or `BLOG_`/`CHAT_` variants |
 | `MISTRAL_API_KEY` | unset | Mistral free (Experiment) plan, which may train on prompts. Blog chain only, unless `AI_PROVIDER_ORDER_CHAT` lists `mistral` |
 | `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_AI_API_TOKEN` | unset | Cloudflare Workers AI, 10,000 free neurons a day. Models `@cf/openai/gpt-oss-120b` / `-20b`; override with `CLOUDFLARE_AI_MODEL` |

package/dist/adapters.d.ts

@@ -1,6 +1,6 @@
 import './env.js';
 import './models.js';
-export { A as AdapterContext, a as AdapterState, b as AdapterStatus, B as BUILTIN_ADAPTERS, C as CHECK_PROMPT, D as DEFAULT_ORDER, F as FREE_TEXT_MODELS, P as PAID_TEXT_MODELS, c as ProviderAdapter, d as ProviderCheck, e as chainPlan, f as checkChain, g as checkProvider, h as configuredOrder, p as providerStatuses, realProviders } from './providers.js';
+export { A as AdapterContext, a as AdapterState, b as AdapterStatus, B as BUILTIN_ADAPTERS, C as CHECK_PROMPT, D as DEFAULT_ORDER, F as FREE_TEXT_MODELS, P as PAID_TEXT_MODELS, c as ProviderAdapter, d as ProviderCheck, e as chainPlan, f as checkChain, g as checkProvider, h as configuredOrder, i as isFreeRoute, o as omniRouteBaseUrl, j as omniRouteModel, p as providerStatuses, realProviders } from './providers.js';
 import 'zod';
 import './guard.js';
 import './log.js';

package/dist/adapters.js

@@ -8,9 +8,12 @@ import {
   checkChain,
   checkProvider,
   configuredOrder,
+  isFreeRoute,
+  omniRouteBaseUrl,
+  omniRouteModel,
   providerStatuses,
   realProviders
-} from "./chunk-BK4B76LD.js";
+} from "./chunk-D6KCXFSF.js";
 import "./chunk-BL4J2JNX.js";
 import "./chunk-PMC3UWQ2.js";
 import "./chunk-RBSLNDFW.js";
@@ -24,6 +27,9 @@ export {
   checkChain,
   checkProvider,
   configuredOrder,
+  isFreeRoute,
+  omniRouteBaseUrl,
+  omniRouteModel,
   providerStatuses,
   realProviders
 };

package/dist/availability.js

@@ -1,6 +1,6 @@
 import {
   chainPlan
-} from "./chunk-BK4B76LD.js";
+} from "./chunk-D6KCXFSF.js";
 import {
   imageConfigFromEnv
 } from "./chunk-MRNQPHWI.js";

package/dist/{chunk-BK4B76LD.js → chunk-D6KCXFSF.js}

@@ -24,6 +24,8 @@ function modelFor(env, provider, purpose, fallback) {
 }
 var need = (env, ...names) => names.filter((name) => !env[name]);
 var FREE_TEXT_MODELS = {
+  // OmniRoute's own alias: its "best free" combo, which only routes to free providers.
+  omniroute: { blog: "auto/best-free", chat: "auto/best-free" },
   groq: { blog: "openai/gpt-oss-120b", chat: "openai/gpt-oss-20b" },
   mistral: { blog: "mistral-medium-latest", chat: "mistral-small-latest" },
   cloudflare: { blog: "@cf/openai/gpt-oss-120b", chat: "@cf/openai/gpt-oss-20b" }
@@ -50,6 +52,28 @@ function compatibleAdapter(spec) {
     })
   };
 }
+function omniRouteBaseUrl(env) {
+  const raw = env.OMNIROUTE_BASE_URL?.trim();
+  if (!raw) return null;
+  try {
+    const url = new URL(raw);
+    const local = /^(?:localhost|127\.0\.0\.1|\[::1\])$/.test(url.hostname);
+    if (url.username || url.password) return null;
+    if (!(url.protocol === "https:" || url.protocol === "http:" && local)) return null;
+    const base = `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+    return base.endsWith("/v1") ? base : `${base}/v1`;
+  } catch {
+    return null;
+  }
+}
+function isFreeRoute(model) {
+  return /[-:/]free$/i.test(model.trim());
+}
+function omniRouteModel(env, purpose) {
+  const model = modelFor(env, "OMNIROUTE", purpose, FREE_TEXT_MODELS.omniroute);
+  return isFreeRoute(model) || env.OMNIROUTE_ALLOW_PAID && paidAllowed(env) ? model : FREE_TEXT_MODELS.omniroute[purpose];
+}
+var PURPOSES = ["blog", "chat"];
 var openRouterAdapter = (id, keyVar) => ({
   id,
   label: id === "openrouter" ? "OpenRouter" : "OpenRouter (second key)",
@@ -66,6 +90,25 @@ var openRouterAdapter = (id, keyVar) => ({
   })
 });
 var BUILTIN_ADAPTERS = [
+  {
+    // OmniRoute: a self-hosted gateway that pools many providers' free tiers
+    // behind one OpenAI-compatible endpoint and fails over between them. First
+    // in the default order, so it leads whenever its address is set. Free only
+    // unless OMNIROUTE_ALLOW_PAID (see omniRouteModel); a paid route then
+    // counts as paid, so it runs as a last resort like any paid provider.
+    id: "omniroute",
+    label: "OmniRoute (self-hosted gateway)",
+    paid: (env, purpose) => (purpose ? [purpose] : PURPOSES).some((each) => !isFreeRoute(omniRouteModel(env, each))),
+    missing: (env) => omniRouteBaseUrl(env) ? [] : ["OMNIROUTE_BASE_URL"],
+    create: ({ env, purpose, fetch: fetch2 }) => openAiCompatibleProvider({
+      name: "omniroute",
+      // A gateway may run without keys; the header must still be well formed.
+      apiKey: env.OMNIROUTE_API_KEY || "none",
+      baseUrl: omniRouteBaseUrl(env),
+      model: omniRouteModel(env, purpose),
+      fetch: fetch2
+    })
+  },
   {
     id: "gemini",
     label: "Gemini",
@@ -195,13 +238,13 @@ function providerStatuses(env, purpose, adapters = BUILTIN_ADAPTERS) {
       continue;
     }
     const missing = adapter.missing(env);
-    const paid = adapter.paid(env);
+    const paid = adapter.paid(env, purpose);
     const state = missing.length ? "not_configured" : paid && !paidAllowed(env) ? "needs_paid" : "active";
     statuses.push({ id, label: adapter.label, paid, state, missing, ...state === "active" ? { position: position++ } : {} });
   }
   for (const adapter of adapters) {
     if (!ids.includes(adapter.id)) {
-      statuses.push({ id: adapter.id, label: adapter.label, paid: adapter.paid(env), state: "not_in_order", missing: adapter.missing(env) });
+      statuses.push({ id: adapter.id, label: adapter.label, paid: adapter.paid(env, purpose), state: "not_in_order", missing: adapter.missing(env) });
     }
   }
   return statuses;
@@ -250,7 +293,7 @@ function realProviders(env, purpose, fetchImpl, adapters = BUILTIN_ADAPTERS) {
   const explicit = configuredOrder(env, purpose) !== null;
   return chainPlan(env, purpose, adapters).map((adapter, index) => {
     const provider = adapter.create({ env, purpose, fetch: fetchImpl });
-    return explicit ? { name: provider.name, generate: provider.generate, priority: index } : { name: provider.name, generate: provider.generate, lastResort: adapter.paid(env) || provider.lastResort };
+    return explicit ? { name: provider.name, generate: provider.generate, priority: index } : { name: provider.name, generate: provider.generate, lastResort: adapter.paid(env, purpose) || provider.lastResort };
   });
 }
 
@@ -609,6 +652,9 @@ export {
   vertexProvider,
   FREE_TEXT_MODELS,
   PAID_TEXT_MODELS,
+  omniRouteBaseUrl,
+  isFreeRoute,
+  omniRouteModel,
   BUILTIN_ADAPTERS,
   DEFAULT_ORDER,
   configuredOrder,

package/dist/{chunk-SI7JE5BG.js → chunk-TEOP42ST.js}

@@ -26,6 +26,16 @@ var aiEnvSchema = z.object({
   OPENROUTER_ALLOW_PAID_MODELS: flag,
   GEMINI_API_KEY: text,
   NVIDIA_API_KEY: text,
+  // OmniRoute (./adapters): a self-hosted gateway pooling free tiers. The
+  // address turns it on; the key is a gateway key from its dashboard.
+  OMNIROUTE_BASE_URL: text,
+  OMNIROUTE_API_KEY: text,
+  OMNIROUTE_MODEL: text,
+  BLOG_OMNIROUTE_MODEL: text,
+  CHAT_OMNIROUTE_MODEL: text,
+  // Lets an OmniRoute model override name a paid route; AI_ALLOW_PAID must be
+  // on as well. Off: only free routes (`-free`, `:free`) are ever sent.
+  OMNIROUTE_ALLOW_PAID: flag,
   // More free tiers (./adapters). Groq: free plan, no card. Mistral: free
   // Experiment plan, which may train on prompts, so it joins the chat chain
   // only when AI_PROVIDER_ORDER_CHAT lists it. Cloudflare Workers AI: 10,000

package/dist/env.d.ts

@@ -11,6 +11,12 @@ declare const aiEnvSchema: z.ZodObject<{
     OPENROUTER_ALLOW_PAID_MODELS: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean, string | undefined>>;
     GEMINI_API_KEY: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     NVIDIA_API_KEY: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    OMNIROUTE_BASE_URL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    OMNIROUTE_API_KEY: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    OMNIROUTE_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    BLOG_OMNIROUTE_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    CHAT_OMNIROUTE_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    OMNIROUTE_ALLOW_PAID: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean, string | undefined>>;
     GROQ_API_KEY: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     GROQ_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     BLOG_GROQ_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;

package/dist/env.js

@@ -3,7 +3,7 @@ import {
   aiEnvFromProcess,
   aiEnvSchema,
   parseAiEnv
-} from "./chunk-SI7JE5BG.js";
+} from "./chunk-TEOP42ST.js";
 export {
   DEFAULT_GOOGLE_TOKEN_URI,
   aiEnvFromProcess,

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   aiEnvFromProcess,
   aiEnvSchema,
   parseAiEnv
-} from "./chunk-SI7JE5BG.js";
+} from "./chunk-TEOP42ST.js";
 export {
   aiEnvFromProcess,
   aiEnvSchema,

package/dist/providers.d.ts

@@ -200,8 +200,11 @@ interface ProviderAdapter {
      * AI_PROVIDER_ORDER(_BLOG|_CHAT) still adds it anywhere it is listed.
      */
     readonly defaultPurposes?: readonly TextPurpose[];
-    /** Costs money: runs only with AI_ALLOW_PAID. */
-    paid(env: AiEnv): boolean;
+    /**
+     * Costs money: runs only with AI_ALLOW_PAID. `purpose` is set when the
+     * answer can differ per purpose; without it, true when any purpose is paid.
+     */
+    paid(env: AiEnv, purpose?: TextPurpose): boolean;
     /** Env variable names still missing; empty means configured. Never values. */
     missing(env: AiEnv): string[];
     create(context: AdapterContext): AiProvider;
@@ -211,6 +214,10 @@ interface ProviderAdapter {
  * writes long JSON, so it gets the larger model; chat gets the faster one.
  */
 declare const FREE_TEXT_MODELS: {
+    readonly omniroute: {
+        readonly blog: "auto/best-free";
+        readonly chat: "auto/best-free";
+    };
     readonly groq: {
         readonly blog: "openai/gpt-oss-120b";
         readonly chat: "openai/gpt-oss-20b";
@@ -250,6 +257,21 @@ declare const PAID_TEXT_MODELS: {
         readonly chat: "sonar";
     };
 };
+/**
+ * OMNIROUTE_BASE_URL as the gateway's `/v1` base, or null when unset or unsafe.
+ * https only, except plain http on localhost for a gateway on the same machine;
+ * never credentials in the URL.
+ */
+declare function omniRouteBaseUrl(env: AiEnv): string | null;
+/** An OmniRoute model id that names a free route: `auto/best-free`, `<provider>/<model>:free`. */
+declare function isFreeRoute(model: string): boolean;
+/**
+ * The OmniRoute model for a purpose. Free only by default: an override that is
+ * not a free route counts only with OMNIROUTE_ALLOW_PAID and AI_ALLOW_PAID both
+ * on; otherwise the free default replaces it, so the gateway keeps answering
+ * for free instead of dropping out of the chain.
+ */
+declare function omniRouteModel(env: AiEnv, purpose: TextPurpose): string;
 declare const BUILTIN_ADAPTERS: readonly ProviderAdapter[];
 /** Free tiers first (fastest, most reliable first), paid last. */
 declare const DEFAULT_ORDER: string[];
@@ -320,4 +342,4 @@ declare function checkChain(env: AiEnv, purpose: TextPurpose, options?: {
  */
 declare function realProviders(env: AiEnv, purpose: TextPurpose, fetchImpl?: typeof fetch, adapters?: readonly ProviderAdapter[]): AiProvider[];
 
-export { type AdapterContext as A, AI_COOLDOWN_MS, AI_TIMEOUT_MS, type AiAttempt, type AiAttemptStatus, type AiGenerateOptions, type AiHealth, type AiOutcome, type AiProvider, type AiResult, type AiServiceDeps, BUILTIN_ADAPTERS as B, CHECK_PROMPT as C, DEFAULT_ORDER as D, FREE_TEXT_MODELS as F, HEDGE, type JsonMode, PAID_TEXT_MODELS as P, type AdapterState as a, anthropicOutcome, anthropicProvider, type AdapterStatus as b, type ProviderAdapter as c, cooldownFor, createAiHealth, createAiService, type ProviderCheck as d, chainPlan as e, checkChain as f, checkProvider as g, geminiOutcome, geminiProvider, configuredOrder as h, nvidiaProvider, openAiCompatibleProvider, openRouterProvider, providerStatuses as p, realProviders, sharedAiHealth, vertexProvider };
+export { type AdapterContext as A, AI_COOLDOWN_MS, AI_TIMEOUT_MS, type AiAttempt, type AiAttemptStatus, type AiGenerateOptions, type AiHealth, type AiOutcome, type AiProvider, type AiResult, type AiServiceDeps, BUILTIN_ADAPTERS as B, CHECK_PROMPT as C, DEFAULT_ORDER as D, FREE_TEXT_MODELS as F, HEDGE, type JsonMode, PAID_TEXT_MODELS as P, type AdapterState as a, anthropicOutcome, anthropicProvider, type AdapterStatus as b, type ProviderAdapter as c, cooldownFor, createAiHealth, createAiService, type ProviderCheck as d, chainPlan as e, checkChain as f, checkProvider as g, geminiOutcome, geminiProvider, configuredOrder as h, isFreeRoute as i, omniRouteModel as j, nvidiaProvider, omniRouteBaseUrl as o, openAiCompatibleProvider, openRouterProvider, providerStatuses as p, realProviders, sharedAiHealth, vertexProvider };

package/dist/providers.js

@@ -15,7 +15,7 @@ import {
   realProviders,
   sharedAiHealth,
   vertexProvider
-} from "./chunk-BK4B76LD.js";
+} from "./chunk-D6KCXFSF.js";
 import "./chunk-BL4J2JNX.js";
 import "./chunk-PMC3UWQ2.js";
 import "./chunk-RBSLNDFW.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sahan-sac/ai-core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Free-by-default AI provider chain with fallback (chain of responsibility over provider adapters: Gemini, OpenRouter, NVIDIA, OpenAI, Anthropic, DeepSeek, xAI, Perplexity, any OpenAI-compatible endpoint, Vertex), env-configurable order, hedging, cooldowns and deadlines, image generation and prompt-injection guards. Shared by @sahan-sac/blog-kit and @sahan-sac/chat-kit.",
   "license": "Apache-2.0",
   "repository": {