laya-mcp 0.1.0__tar.gz

laya_mcp-0.1.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 [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.

laya_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: laya-mcp
+Version: 0.1.0
+Summary: MCP server for Laya typed decisions: a warm model sidecar, token-budget preflight, a persisted calibration store, and honest confidence.
+Author: PerryLink
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/PerryLink/laya-mcp
+Project-URL: Repository, https://github.com/PerryLink/laya-mcp
+Project-URL: Issues, https://github.com/PerryLink/laya-mcp/issues
+Keywords: laya,mcp,mcp-server,decision-model,system-one,calibration,typed-decisions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: laya<0.4,>=0.3.4
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn>=0.27; extra == "server"
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.28; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: pyyaml>=6; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Dynamic: license-file
+
+# laya-mcp
+
+[Laya](https://github.com/NandhaKishorM/laya) is a fast, non-autoregressive
+"System 1" decision model: it answers typed questions — `noul` (yes/no),
+`choice`, `score` — over a piece of state and returns probabilities, in a single
+forward pass. It is genuinely good, and it is a research artifact.
+
+This is the part that makes it survive contact with a server.
+
+```bash
+pip install 'laya-mcp[mcp]'
+laya-mcp serve            # loads the model once, keeps it warm on 127.0.0.1:8787
+laya-mcp install          # registers it with whichever agent harness you have
+```
+
+> **Status: 0.1.0, work in progress.** The core is implemented and its pure logic
+> is covered by 66 checks, but it has not yet been exercised end-to-end against a
+> live harness in CI. Interfaces may move before 1.0.
+
+---
+
+## The problem this solves
+
+Laya truncates things silently, and the omissions are the kind you only notice
+after acting on a wrong answer.
+
+**It cuts the state, from the end, and says nothing.** `build_sequence` gives the
+state whatever room is left after the options and slices it `st[:room]`. A long
+document loses its tail — which for a contract, a log or an email thread is often
+where the answer was — and the model then answers about the surviving prefix at
+full confidence. Nothing in the response marks it.
+
+**It shortens options until labels are indistinguishable.** Options share a fixed
+`head_max_len` budget (192 tokens on the English checkpoint, 256 on the others).
+Past a point every label gets ~4 tokens. This is the documented cause of the
+Banking77 collapse (0.425 against Jev's 0.870), and again, nothing reports it.
+
+**Its validation is one check.** An unknown `type` is a bare `KeyError` from
+`QTYPES[q["t"]]`; a missing `criteria` is a bare `KeyError` too. They are
+indistinguishable from a bug in the model, and neither names the question at
+fault.
+
+**Its `confidence` is not accuracy.** It is `1 - H(p)/log(k)` for `choice` and
+`score` and `max(p, 1-p)` for `noul`. A normalised entropy is *low* when
+probability is spread out even when the top option is right, and *high* on a
+confident wrong answer — the English checkpoint scores 0.000 accuracy on Khmer at
+0.952 confidence. A threshold on it does not mean what it looks like.
+
+**And it demotes itself to CPU in silence.** On a CUDA OOM it moves the model to
+CPU in fp32, in place, permanently, printing to stdout. No flag is set anywhere.
+A process that hits this once keeps answering, roughly 10–15x slower, and nothing
+in the response admits it.
+
+So this package adds what is missing: a **preflight** that says what would be
+cut, **structured errors** naming the question, an **honest confidence contract**,
+and a **health surface** that reports a demotion.
+
+---
+
+## What it does
+
+| | |
+|---|---|
+| **Warm sidecar** | One `Router`, preloaded, for the life of the process. Laya's default (`max_loaded=1`) rebuilds a model on every language switch — measured upstream at a 7.4 s median reload on CPU, 10.3 s on a T4. |
+| **Token-budget preflight** | `laya_plan` reports exactly what would be truncated, and how many tokens each option actually gets, **without running the model**. The option arithmetic reproduces `build_sequence` line for line. |
+| **Structured errors** | Every Laya failure becomes a code, an HTTP status, the offending question id, and a hint. `KeyError('ranking')` becomes `invalid_question` naming the type. |
+| **Honest confidence** | `confidence` is labelled for what it is, on every response. `noul` answers also carry a `no` / `uncertain` / `yes` band, because a calibrated probability is not a decision. |
+| **Calibration store** | Fit a temperature per `(primitive, option bucket)` against your own labels, persist it, reload it. `laya-multilingual` ships **no** fitted temperatures at all, so its probabilities are raw until you do this. |
+| **Device honesty** | Reports a silent CPU demotion, and `doctor` proves the GPU works by running a real op rather than trusting `torch.cuda.is_available()`. |
+| **Serialised inference** | A lock, by default. Laya is not thread-safe: `system_one` reassigns `self.device` and calls `self.model.to(...)` on an OOM, so concurrent calls can race a device move against a forward pass. |
+| **Restartable** | `DELETE /model` releases the model and empties the CUDA allocator cache, which `Router.unload` does not. A model server that leaks needs to be recyclable. |
+
+---
+
+## One installer, five harnesses
+
+There is no portable way to register an MCP server. Measured against real
+installed harnesses, they disagree on the file, the format, and the key:
+
+| harness | config | format | key |
+|---|---|---|---|
+| Claude Code | `~/.claude.json` | JSON | `mcpServers` |
+| Codex | `~/.codex/config.toml` | TOML | `[mcp_servers.<name>]` |
+| opencode | `~/.config/opencode/opencode.json[c]` | JSON | `mcp` |
+| OpenClaw | `~/.openclaw/openclaw.json` | JSON | `mcp.servers` |
+| Hermes | `~/.hermes/config.yaml` | YAML | `mcp_servers` |
+
+`laya-mcp install` detects which are present and writes the right shape to each.
+Every writer merges rather than replaces, backs the file up first, and refuses to
+touch a file it cannot parse — `~/.claude.json` is a large shared file holding
+history and per-project state, and clobbering it to install a decision model
+would be a catastrophic trade.
+
+Two honest limitations:
+
+* **opencode differs from everyone three more times** inside its own entry:
+  `command` is a single array holding the executable *and* its arguments, the
+  environment key is `environment`, not `env`, and the toggle is `enabled`.
+  Setting `disabled: true` there is silently ignored.
+* **`pi` is not supported.** Not an oversight: `pi` has no native MCP support.
+  Its settings reference contains no MCP key, and its own upstream request for MCP
+  is titled *"Add MCP extension example"* — in `pi`, MCP is an extension you
+  build. There is no config file an installer can write. `install` detects it and
+  says so.
+
+`install` points the harness at `python -m laya_mcp mcp` rather than at the
+`laya-mcp` console script, deliberately: on Windows a console script is a `.cmd`
+shim and the MCP SDK spawns with `shell: false`, which cannot execute it.
+
+---
+
+## Tools
+
+| tool | what it answers |
+|---|---|
+| `laya_ask` | A batch of typed questions over one state. The general one. |
+| `laya_noul` | One yes/no question. Returns `P(true)` and a band. |
+| `laya_choice` | One multiple-choice question. Returns the label and the distribution. |
+| `laya_score` | One ordered-scale question. |
+| `laya_plan` | "Will this fit, and what will be cut?" — no forward pass. |
+
+Every description says what the tool is *not* for. A decision model asked to write
+prose produces nothing useful, and an agent that does not know that will keep
+trying.
+
+---
+
+## HTTP
+
+```bash
+laya-mcp serve --model english --port 8787
+curl -s localhost:8787/health
+curl -s localhost:8787/ask -H 'content-type: application/json' -d '{
+  "state": {"subject": "Duplicate charge", "body": "Billed twice. Refund or we cancel."},
+  "questions": {
+    "churn": {"type": "noul", "instructions": "Does the user threaten to cancel?"},
+    "team":  {"type": "choice", "instructions": "Which team?",
+              "criteria": {"billing": "invoices, refunds", "tech": "bugs, outages"}}
+  }
+}'
+```
+
+`GET /health`, `GET /capabilities`, `GET /version`, `POST /ask`, `POST /plan`,
+`DELETE /model`. Loopback only by default; binding elsewhere warns loudly, because
+there is no authentication.
+
+`POST /plan` takes the same body as `/ask` and returns the same `budget` block
+`/ask` reports, computed by the same `plan_questions` call — without a forward
+pass. It is how a client can ask "will this be cut?" before paying for an answer.
+On a cold host it pays a model *load*, which is not the same thing as an
+inference.
+
+---
+
+## Configuration worth knowing
+
+| flag | why |
+|---|---|
+| `--head-max-len` | Raised at startup, this is the fix for high-cardinality `choice`. Options share it, so more room per label is the only way to keep them distinguishable. Read fresh on every call, so setting it once is enough. |
+| `--max-len` | The total budget. Raising it is the fix for a truncated state. |
+| `--concurrency` | Raise only if you know Laya is not sharing device state. The default of 1 is correctness, not caution. |
+| `--sidecar` | Point `laya-mcp mcp` at a running `serve`. Strongly recommended: a harness spawns one stdio server per session, and hosting the model in each one pays the load cost per session. |
+
+---
+
+## What this does not fix
+
+Upstream's own numbers are worth repeating, because an integration layer that
+implies otherwise is lying to you.
+
+* **The base checkpoints are near chance zero-shot on typed decisions** — 0.362
+  for English against a **0.461 majority-class baseline**. Guessing the most
+  common answer beats the model.
+* **`score` is the weakest primitive.** Independently measured at 35% against
+  Jev's 70% on a five-level ordinal task.
+* **Calibration needs labelled data.** Raw ECE is 0.466 for English and 0.314 for
+  multilingual, improving to 0.081 and 0.106 after fitting. A temperature cannot
+  be invented; this package will not pretend to.
+* **Position bias is real.** One published fixture run answered "A" on 46 of 50
+  multiple-choice items.
+* **Accuracy falls off above ~20 options**, per the author.
+
+Calibration makes a probability *honest*; it cannot make a model *right*. If the
+accuracy is not there for your task, fit on your own domain or do not deploy it.
+
+---
+
+## Verify
+
+```bash
+python tests/smoke_pure.py         # 66 checks: validation, planning, calibration, errors
+python tests/install_harnesses.py  # 35 checks: every harness dialect, in a temp dir
+python tests/mcp_protocol.py       # 25 checks: a real MCP handshake and real tool calls
+laya-mcp doctor                    # what is installed, and what the GPU can really do
+```
+
+126 checks, and each suite covers a layer the others cannot reach.
+
+`smoke_pure.py` needs no torch, model, network or harness config. `install_harnesses.py`
+redirects every harness into a temporary directory, because `~/.claude.json` is a
+large shared file holding history and per-project state and a test that clobbered
+it would be a worse bug than any it could catch.
+
+`mcp_protocol.py` is the one that matters most and the one that was missing
+longest. It spawns the server exactly as a harness does
+(`python -m laya_mcp mcp`), performs the real `initialize` handshake with the
+official SDK, lists tools, and calls them through the sidecar to the model. Two
+real defects escaped the other suites and were caught only here: `FastMCP` in
+mcp 1.30 takes no `version` argument, so the server failed to start at all; and
+the token-budget warning was written into the DSH plugin's tool description but
+never into this server's, so a client using MCP could not have known that an
+oversized state is cut from the end.
+
+The harness dialects were additionally verified by letting the harnesses parse
+the files this tool writes: `codex mcp list --json` and `openclaw mcp list --json`
+both report the registered server with the correct stdio transport. For the other
+three the format is verified but harness acceptance is not, which is stated rather
+than implied — `pi` has no MCP support at all, and this machine's Hermes runtime is
+incomplete.
+
+## Licence
+
+Apache-2.0. Laya is Apache-2.0, by Convai Innovations. This is an independent
+integration and is not affiliated with or endorsed by that project.