thinkless 0.2.0__tar.gz

thinkless-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+site/
+
+# ThinkLess runtime output (traces, viewer exports, scratch benchmark runs)
+.thinkless/
+
+# Editors and OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+.env.*
+!.env.example

thinkless-0.2.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[semantic versioning](https://semver.org/).
+
+## Unreleased
+
+## 0.2.0 - 2026-09-25
+
+First release on PyPI.
+
+### Added
+
+- `OpenRouterLLM` and the `openrouter:<slug>` spec: one key for models from
+  Anthropic, OpenAI, Google, Qwen, DeepSeek and others.
+- Billed cost: `Completion.cost_usd` and `ProviderResult.cost_usd` carry the
+  cost a backend reports (OpenRouter does); the engine prefers it over the
+  price table and records `cost_source` on spans. Benchmark reports add a
+  billed cost row, and the intent benchmark reports cost per 1k per provider
+  and per cascade threshold.
+- `--reasoning` for every CLI command that builds an LLM, and
+  `from_spec(..., reasoning=...)`, mapped to OpenRouter's `reasoning`,
+  Anthropic's `effort` and local thinking switches.
+- `HFClassifier`: any Hugging Face text-classification model as a provider for
+  the questions it was trained for.
+- `load_env()`, and the CLI reads `./.env` without overriding set variables.
+- Escalation context: when a question escalates to the LLM decider, the
+  engine includes the decisions already settled in the same batch. It removed
+  false injection flags on requests for a human that appeared when an LLM saw
+  the injection question alone. On by default (`Engine(escalation_context=...)`).
+- The System One wire format is tested against TypeSafe's official SDK models.
+
+### Fixed
+
+- `LLMDecider` detects replies cut off at the token limit, logs why, and
+  retries once with a larger budget instead of abstaining silently.
+- The OpenAI-compatible client retries once without `response_format` when an
+  endpoint rejects JSON mode.
+- A redaction test that failed about one run in fifty when a random span id
+  contained its marker.
+
+## 0.1.0 - 2026-09-25
+
+First public release.
+
+### Added
+
+- Typed questions: `Choice`, `Score`, `YesNo` and `Extract`, following the
+  System One wire format.
+- `Engine` with a confidence cascade across providers, batched provider calls,
+  `accepted`, `uncertain` and `abstained` statuses, per-question and
+  per-provider thresholds (`"question@provider"`), question-level provider
+  allowlists, and async variants of every call.
+- Normalized confidence, `(k * p_max - 1) / (k - 1)`, applied uniformly across
+  providers.
+- Decision providers: `Rules`, `GLiNER` (GLiNER 2.5), `Laya`, `SystemOne`
+  (TypeSafe Jev and compatible servers such as Kev and OpenJev) and
+  `LLMDecider`.
+- LLM backends: `TransformersLLM`, `OpenAICompatibleLLM` (OpenAI, Ollama, vLLM
+  and others) and `AnthropicLLM` with server-side refusal fallbacks.
+- Tracing: spans for runs, steps, decisions, provider attempts, generations,
+  tools and rules; JSONL, memory, console and OpenTelemetry sinks; run
+  summaries with decisions by plane, escalations, tokens, cost and time by
+  plane; content capture switch; a self-contained HTML viewer.
+- A price table with sources, overridable with `THINKLESS_PRICING`.
+- The support demo: an agent, a mock store, 53 labeled tickets and a separate
+  48-row calibration set.
+- Benchmarks: the support benchmark across `llm`, `hybrid` and `models` modes,
+  and intent benchmarks on Banking77, CLINC150 and Emotion with a simulated
+  cascade.
+- `thinkless` CLI: `doctor`, `demo`, `bench support`, `bench intents`,
+  `calibrate`, `trace ls`, `trace show` and `trace view`.

thinkless-0.2.0/LICENSE

@@ -0,0 +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 Praveen Kumar
+
+   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.
+

thinkless-0.2.0/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.5
+Name: thinkless
+Version: 0.2.0
+Summary: The decision plane for AI agents. Rules and small calibrated models make the routine decisions, the LLM is reserved for the steps that need thought, and every step is traced.
+Project-URL: Homepage, https://github.com/inboxpraveen/ThinkLess
+Project-URL: Documentation, https://github.com/inboxpraveen/ThinkLess/tree/main/docs
+Project-URL: Repository, https://github.com/inboxpraveen/ThinkLess
+Project-URL: Issues, https://github.com/inboxpraveen/ThinkLess/issues
+Project-URL: Changelog, https://github.com/inboxpraveen/ThinkLess/blob/main/CHANGELOG.md
+Author: Praveen Kumar
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,classification,decision-models,gliner,jev,laya,llm,observability,routing,system-one,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: accelerate>=1.0; extra == 'all'
+Requires-Dist: anthropic>=1.0; extra == 'all'
+Requires-Dist: datasets>=3.0; extra == 'all'
+Requires-Dist: gliner2[local]<3,>=2.0; extra == 'all'
+Requires-Dist: laya<0.4,>=0.3.20; extra == 'all'
+Requires-Dist: openai>=2.0; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.25; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.25; extra == 'all'
+Requires-Dist: protobuf>=4.25; extra == 'all'
+Requires-Dist: sentencepiece>=0.2; extra == 'all'
+Requires-Dist: torch>=2.1; extra == 'all'
+Requires-Dist: transformers<5,>=4.48; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=1.0; extra == 'anthropic'
+Provides-Extra: bench
+Requires-Dist: datasets>=3.0; extra == 'bench'
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: typesafe-sdk>=0.7; extra == 'dev'
+Provides-Extra: gliner
+Requires-Dist: gliner2[local]<3,>=2.0; extra == 'gliner'
+Requires-Dist: protobuf>=4.25; extra == 'gliner'
+Requires-Dist: sentencepiece>=0.2; extra == 'gliner'
+Requires-Dist: transformers<5,>=4.48; extra == 'gliner'
+Provides-Extra: laya
+Requires-Dist: laya<0.4,>=0.3.20; extra == 'laya'
+Requires-Dist: transformers<5,>=4.48; extra == 'laya'
+Provides-Extra: local
+Requires-Dist: accelerate>=1.0; extra == 'local'
+Requires-Dist: gliner2[local]<3,>=2.0; extra == 'local'
+Requires-Dist: laya<0.4,>=0.3.20; extra == 'local'
+Requires-Dist: protobuf>=4.25; extra == 'local'
+Requires-Dist: sentencepiece>=0.2; extra == 'local'
+Requires-Dist: torch>=2.1; extra == 'local'
+Requires-Dist: transformers<5,>=4.48; extra == 'local'
+Provides-Extra: local-llm
+Requires-Dist: accelerate>=1.0; extra == 'local-llm'
+Requires-Dist: torch>=2.1; extra == 'local-llm'
+Requires-Dist: transformers<5,>=4.48; extra == 'local-llm'
+Provides-Extra: openai
+Requires-Dist: openai>=2.0; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otel'
+Description-Content-Type: text/markdown
+
+<h1 align="center">ThinkLess</h1>
+
+<p align="center"><b>Stop using an LLM for every decision.</b></p>
+
+<p align="center">
+  <a href="https://pypi.org/project/thinkless/"><img alt="PyPI" src="https://img.shields.io/pypi/v/thinkless.svg"></a>
+  <a href="https://github.com/inboxpraveen/ThinkLess/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/inboxpraveen/ThinkLess/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/inboxpraveen/ThinkLess/blob/main/LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-blue.svg"></a>
+  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue.svg">
+  <a href="https://github.com/inboxpraveen/ThinkLess/blob/main/docs/benchmarks.md"><img alt="Benchmarks" src="https://img.shields.io/badge/benchmarks-reproducible-brightgreen.svg"></a>
+</p>
+
+ThinkLess is an open-source decision plane for AI agents. The routine
+judgments an agent makes (what the user wants, whether they asked for a
+person, which order they mean, whether a message is trying to manipulate the
+system) are answered by rules and small calibrated models in milliseconds. The
+LLM is kept for the steps that need it: writing, planning, and the decisions
+the small models are not sure about. Every step is traced with the plane that
+handled it, its confidence, latency, tokens and cost.
+
+It is model-neutral. Rules, [GLiNER 2.5](https://github.com/fastino-ai/GLiNER2),
+[Laya](https://github.com/NandhaKishorM/laya), TypeSafe's
+[Jev](https://typesafe.ai) (and any server speaking its System One API, such as
+Kev and OpenJev), any Hugging Face classifier, and any LLM (local through
+Transformers, Ollama or vLLM, or hosted through OpenRouter, Anthropic or
+OpenAI) plug into the same cascade. The whole stack also runs offline on a
+laptop GPU, with no API key.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/inboxpraveen/ThinkLess/main/docs/assets/trace-viewer.png" alt="The ThinkLess trace viewer comparing three decision planes on the support benchmark, with one ticket's waterfall: six decisions answered by rules, GLiNER and Laya in 126 ms, then a single LLM call for the reply" width="100%">
+</p>
+
+## Why
+
+A typical agent sends every branch of its workflow to one generative model:
+classify the request, extract the arguments, pick the tool, check the result,
+check the reply, then write the reply. Most of those are bounded questions with
+a handful of possible answers. A generative model answers them slowly, at full
+token cost, and without telling you how sure it is.
+
+ThinkLess treats each of them as a typed question. It asks the cheapest
+provider first and escalates only when the answer's confidence is below a
+threshold you set per question and per provider, from data. Your code reads a
+typed decision and never needs to know which model produced it.
+
+```python
+intent = engine.decide(ticket, INTENT)          # rules, then GLiNER, then Laya, then the LLM
+if intent.is_("refund_duplicate_charge"):       # only true when the answer is confident
+    ...
+```
+
+## Results
+
+Same agent, same 53 labeled support tickets, two decision planes: `llm` sends
+every decision to the LLM, `hybrid` asks rules, GLiNER and Laya first. Hosted
+models ran through OpenRouter, and the dollar figures are what OpenRouter
+billed ([full results](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/benchmarks.md)):
+
+| Fallback LLM | Success, `llm` | Success, `hybrid` | Billed per 1k tickets, `llm` | Billed per 1k tickets, `hybrid` | Decision time |
+|---|---:|---:|---:|---:|---:|
+| Qwen 3.7 Flash | 92.5% | **98.1%** | $0.034 | **$0.019** | 1.27 s to **0.58 s** |
+| Gemini 2.5 Flash Lite | 98.1% | **98.1%** | $0.104 | **$0.059** | 1.17 s to **0.76 s** |
+| GPT-5.6 Luna | 98.1% | **100%** | $0.235 | **$0.141** | 2.50 s to **1.18 s** |
+| Claude Haiku 4.5 | 98.1% | **98.1%** | $1.338 | **$0.788** | 2.21 s to **1.34 s** |
+| Qwen3-1.7B, local | 86.8% | **94.3%** | free | free | 1.84 s to **0.43 s** |
+
+- **Hybrid matched or beat the LLM-only design on every model, at 40 to 44
+  percent lower billed cost** and 35 to 55 percent less time spent on
+  decisions. 87 percent of hybrid decisions never reached the LLM.
+- **Small models are the most reliable extractors.** Rules and GLiNER found
+  every order number on every run. The larger hosted LLMs did too; Qwen 3.7
+  Flash and the local 1.7B model missed ones written without the word
+  "order".
+- **On Banking77 (77 intents, 500 examples) the cascade matched or beat its
+  LLM at a quarter of the cost.** GLiNER alone 71.8 percent; Qwen 3.7 Flash
+  alone 73.8 percent, cascade 74.8 percent; Claude Haiku 4.5 alone 76.2
+  percent, cascade 76.2 percent. Each time a quarter of the calls reached the
+  LLM.
+- **Nothing was tuned on the test tickets.** Thresholds and every fix were
+  validated on a separate calibration set first. The baseline is the
+  strongest form of the LLM design: all six triage questions in one prompt.
+- The support set is 53 synthetic tickets: evidence of the mechanism and its
+  failure modes, not a leaderboard. The [benchmarks page](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/benchmarks.md)
+  lists the weak areas found and what was done about each.
+
+## Quick start
+
+```bash
+pip install "thinkless[local]"        # GLiNER, Laya and a local LLM
+thinkless doctor                      # check the environment
+```
+
+```python
+from thinkless import Choice, Engine, Extract, JSONLSink, Tracer, YesNo
+from thinkless.llm import TransformersLLM
+from thinkless.providers import GLiNER, Laya, LLMDecider, Rules
+
+rules = Rules()
+rules.match("wants_human", r"\b(real person|a human|an agent|operator)\b", True, field="message")
+rules.extract("order", field="message", order_id=r"#\s?(\d{4,5})\b")
+
+llm = TransformersLLM("Qwen/Qwen3-1.7B")
+engine = Engine(
+    [rules, GLiNER(), Laya(), LLMDecider(llm)],     # cheapest first
+    llm=llm,
+    threshold=0.8,
+    tracer=Tracer([JSONLSink(".thinkless/traces")]),
+)
+
+with engine.run("ticket") as run:
+    decisions = engine.decide_many(
+        {"message": "I was charged twice for order #4471. Refund it or I'm cancelling."},
+        [
+            Choice("What does the customer want?", name="intent",
+                   options={"refund": "wants money back", "order_status": "asks where an order is",
+                            "cancel": "wants to cancel", "other": "anything else"}),
+            YesNo("Is the customer asking for a person?", name="wants_human"),
+            Extract(name="order", fields={"order_id": "the order number"}),
+        ],
+    )
+
+for name, d in decisions.items():
+    print(f"{name:12} {d.value!s:24} {d.status.value:9} via {d.provider}")
+print(run.summary().decisions_by_plane)      # which plane answered what
+```
+
+Prefer a hosted model? Put `OPENROUTER_API_KEY=...` in `.env` and swap one
+line; OpenRouter reaches Qwen, Gemini, GPT and Claude models with one key:
+
+```python
+from thinkless.llm import OpenRouterLLM
+
+llm = OpenRouterLLM("qwen/qwen3.7-flash", reasoning={"enabled": False})
+```
+
+Then open the trace:
+
+```bash
+thinkless trace view
+```
+
+No GPU? `pip install thinkless` and run
+[`examples/01_rules_only.py`](https://github.com/inboxpraveen/ThinkLess/blob/main/examples/01_rules_only.py): the API, the cascade
+and the traces with no model downloads.
+
+## Try the demo agent
+
+A complete customer support agent ships with the package: a mock store with
+orders, payments and a help center, 53 labeled tickets, and every hard case we
+could think of (order numbers written in ways a regex misses, a customer
+asking about someone else's order, prompt injections, requests for a human,
+Spanish and German tickets).
+
+```bash
+thinkless demo --ticket T-016                          # one ticket, printed as a trace tree
+thinkless demo --ticket T-051 --mode hybrid --mode llm # compare decision planes
+thinkless bench support                                # every ticket in every mode
+thinkless bench support --llm openrouter:qwen/qwen3.7-flash --reasoning off
+thinkless bench intents --dataset banking77
+```
+
+## How it works
+
+**Typed questions.** `Choice`, `Score`, `YesNo` and `Extract` declare what you
+want to know and which answers are allowed. They follow the System One wire
+format, so the same question works on every provider.
+[Questions](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/questions.md)
+
+**A confidence cascade.** Providers are tried cheapest first. Each gets one
+call with every open question it supports; answers that clear their threshold
+close, the rest move on. Unresolved questions come back `uncertain` with the
+best answer seen, and `decision.is_()` never matches an uncertain answer.
+[The cascade](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/cascade.md)
+
+**One meaning of confidence.** Providers disagree about what "confidence"
+means (Laya and TypeSafe compute it differently), so a threshold of 0.8 would
+mean different things per backend. ThinkLess derives a single normalized
+confidence from each provider's probabilities.
+[Confidence](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/confidence.md)
+
+**Thresholds from data.** `thinkless calibrate` sweeps thresholds on labeled
+examples and recommends the lowest one that meets your accuracy target, per
+question and per provider (`thresholds={"intent@gliner": 0.9}`).
+[Calibration](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/calibration.md)
+
+**Traces for everything.** Decisions, provider attempts, generations, tool
+calls and rule checks are spans with W3C-compatible ids. Write JSONL audit
+files, export to any OpenTelemetry backend with GenAI semantic conventions, or
+open the self-contained HTML viewer. Content capture can be switched off
+without losing structure, timings or confidences.
+[Tracing](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/tracing.md)
+
+## Providers and backends
+
+| Decision providers | Answers | Runs |
+|---|---|---|
+| `Rules` | every kind | in-process, under 1 ms |
+| `GLiNER` (GLiNER 2.5) | choice, extract | local, 16 to 38 ms on a laptop GPU, about 85 ms on CPU |
+| `Laya` | choice, score, yes/no | local, about 30 ms per batch on a laptop GPU |
+| `SystemOne` (Jev, Kev, OpenJev) | choice, score, yes/no | hosted or self-hosted HTTP |
+| `HFClassifier` | choice, yes/no, for the questions it was trained on | any Hugging Face text classifier, local |
+| `LLMDecider` | every kind | any LLM backend below |
+
+| LLM backends | Covers |
+|---|---|
+| `TransformersLLM` | any Hugging Face chat model, in-process |
+| `OpenRouterLLM` | hundreds of hosted models with one key, billed cost recorded per call |
+| `OpenAICompatibleLLM` | OpenAI, Ollama, vLLM, LM Studio, llama.cpp, Groq |
+| `AnthropicLLM` | Claude, with server-side refusal fallbacks |
+
+Writing your own provider is one class. [Providers](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/providers.md),
+[LLM backends](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/llm-backends.md)
+
+## Documentation
+
+- [Getting started](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/getting-started.md)
+- Concepts: [the four planes](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/planes.md),
+  [questions](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/questions.md),
+  [confidence](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/confidence.md),
+  [the cascade](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/cascade.md),
+  [tracing](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/concepts/tracing.md)
+- Guides: [the support agent](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/support-agent.md),
+  [calibration](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/calibration.md),
+  [providers](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/providers.md),
+  [LLM backends](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/llm-backends.md),
+  [production](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/production.md),
+  [troubleshooting](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/guides/troubleshooting.md)
+- [Benchmarks](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/benchmarks.md), [CLI reference](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/reference/cli.md),
+  [Python API](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/reference/api.md), [roadmap](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/roadmap.md)
+
+## Status
+
+ThinkLess is at 0.1: the core API (questions, the engine, decisions and
+traces) is meant to stay stable, and providers and benchmarks will grow.
+Next up are shadow mode, calibration from traces, calibrated LLM confidence
+from log probabilities, and live Jev runs. See the [roadmap](https://github.com/inboxpraveen/ThinkLess/blob/main/docs/roadmap.md).
+
+## Contributing
+
+Issues, providers, benchmark runs on other hardware and models, and new demo
+scenarios are all welcome. Start with [CONTRIBUTING.md](https://github.com/inboxpraveen/ThinkLess/blob/main/CONTRIBUTING.md). The
+bar for changes that affect accuracy, latency or cost is evidence: a before
+and after from `thinkless bench` or `thinkless calibrate`.
+
+## Sponsoring
+
+If ThinkLess saves your team time or money, consider
+[sponsoring its development](https://github.com/sponsors/inboxpraveen).
+Sponsorship funds frontier-model benchmark runs, more providers and more
+demos.
+
+## Citing
+
+See [CITATION.cff](https://github.com/inboxpraveen/ThinkLess/blob/main/CITATION.cff).
+
+## Acknowledgements
+
+ThinkLess builds on the work of the teams behind
+[Jev and the System One API](https://typesafe.ai) (TypeSafe AI),
+[GLiNER2](https://github.com/fastino-ai/GLiNER2) (Fastino),
+[Laya](https://github.com/NandhaKishorM/laya) (Convai Innovations),
+[Qwen](https://github.com/QwenLM) and
+[Banking77](https://github.com/PolyAI-LDN/task-specific-datasets) (PolyAI).
+
+ThinkLess is not affiliated with the NeurIPS 2025 paper
+[Thinkless: LLM Learns When to Think](https://github.com/VainF/Thinkless),
+which studies adaptive reasoning inside a single model.
+
+## License
+
+[Apache License 2.0](https://github.com/inboxpraveen/ThinkLess/blob/main/LICENSE).