{
  "markdown": "# XFMS — Xpansion Framework Model Source\n\n[![PyPI](https://img.shields.io/pypi/v/xfms.svg?label=pypi&color=blue)](https://pypi.org/project/xfms/)\n[![Python](https://img.shields.io/pypi/pyversions/xfms.svg)](https://pypi.org/project/xfms/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![smithery badge](https://smithery.ai/badge/russ-mwq9/xfms)](https://smithery.ai/servers/russ-mwq9/xfms)\n[![Xpansion Framework](https://img.shields.io/badge/part%20of-Xpansion%20Framework-black)](https://xpansion.dev)\n\n**Pick the right LLM for your task — without the Twitter vibes.**\n\nState what you're using the model for. XFMS aggregates evidence from\neight independent benchmark sources, normalizes it onto a common\nscale, lets your intent decide which dimensions matter, and returns\na ranked shortlist with plain-English rationale for every pick.\n\nXFMS is one module of the **[Xpansion Framework](https://xpansion.dev)** —\na unified architecture for governing AI-assisted work.\n\n---\n\n## What this repository is\n\nA **thin Python client** and **command-line tool** for calling the\nhosted XFMS API at `xfms.xpansion.dev`. About 250 lines of code. It\nturns a one-liner into a ranked LLM shortlist.\n\nWhat this repository is **not**: the recommender engine, the score\ncatalog, or the ingestion pipeline. Those run on the hosted service.\nThe methodology behind every pick is published in full at\n[docs/methodology.md](docs/methodology.md) — every claim there maps\nto code that runs at request time, you just don't run it locally.\n\n---\n\n## What you say:\n\n> *\"Fixing bugs in our Python codebase.\"*\n\n## What you get:\n\n```\nTop picks:\n   1. 0.842  GPT-5.5                 (openai/gpt-5.5)         via OpenAI\n   2. 0.811  Claude Opus 4.7         (anthropic/claude-opus-4.7) via Anthropic\n   3. 0.798  Gemini 3.1 Pro Preview  (google/gemini-3.1-pro-preview) via Google\n\nInferred quality weights from your purpose:\n  • structured_output_reliability  42.0%  ← BigCodeBench, Aider Polyglot\n  • instruction_following          28.0%  ← LiveBench, Tau-Bench\n  • factuality                     20.0%  ← MMLU, GPQA\n  • coherence                      10.0%  ← LongBench\n\n─── Explanation ───\nPicked GPT-5.5: strong on structured output and instruction following —\nthe two dimensions that dominate code-edit work. Beats Claude on Aider\nPolyglot and matches it on LiveBench reasoning, at roughly 60% of the\nper-token cost.\n```\n\nWant to see how the picks actually behave on your kind of query? Add `--ab`:\n\n```\n─── A/B probe ───\nRan 5 test queries against the top picks.\n  • GPT-4o-mini  avg_latency=5579 ms  total_cost=$0.00156  successes=5\n  • GPT-5.5      avg_latency=8190 ms  total_cost=$0.07640  successes=5\n  • GPT-5.4      avg_latency=8783 ms  total_cost=$0.03493  successes=5\n\nCommentary:\n  Across 5 real test queries, GPT-4o-mini was both cheapest ($0.0016 total)\n  and fastest (5579 ms avg). Clear winner — 98% cheaper and 36% faster\n  than the slowest pick.\n```\n\n---\n\n## What XFMS does for you\n\nBeyond ranking, XFMS gives you these levers to honor what you actually meant:\n\n- **`--primary <branch>`** — sacrosanct user preference. When you say\n  *\"cheapest model, period\"*, the engine switches to lexicographic\n  ranking: cost wins, other dimensions only break ties. No more\n  weighted-blend surprises.\n- **`--ab`** — runs the top 3 picks against 5 real test queries\n  (expanding to 10 or 15 if results trade off) and surfaces commentary\n  on who won what. Grounds the recommendation in actual model behavior,\n  not just benchmarks.\n- **`--strict-priorities`** — when you name two co-equal drivers\n  (\"cheap but high quality too\"), the engine refuses to silently\n  blend; it asks you which way to break the tie.\n- **Latent-requirement suggestions** — engine surfaces capabilities\n  you didn't ask for but probably need (streaming for real-time chat,\n  vision for OCR), so you don't get burned by what you didn't know.\n- **Deterministic by design** — every internal model call is content-\n  cached; same input always returns the same answer. The \"I got\n  different picks for the same question\" failure mode is gone.\n\n---\n\n## Install — add one URL to your AI client\n\nXFMS is a hosted Model Context Protocol (MCP) server. There is no\npackage to install on your machine. You point your AI assistant —\nClaude Code, Cursor, Continue, Cline, or any MCP-speaking host — at\nthe URL below and the tools appear inside your chat:\n\n**`https://xfms.xpansion.dev/mcp/`**\n\nThat's it. The three discovery tools — `rank`, `pick`, `discover` —\nare free and work with no key. Your AI assistant does the small\ninternal thinking work; we pay for nothing on your behalf, and you\npay for nothing either.\n\nThe two live-probe tools — `compare` and `benchmark` — actually run\ntest queries against the real candidate models on OpenRouter. That\ninference cost rides with you, so they require your own OpenRouter\nkey in an `X-OpenRouter-Key` header. You probably already have one —\nyou're an OpenRouter model picker's target audience. If not, grab\none at [openrouter.ai/keys](https://openrouter.ai/keys).\n\nThe key travels encrypted to our server, is never logged, never\npersisted — used once per request and dropped. Same security posture\nas every other API key in your MCP config.\n\nConcrete install snippets for each AI client are in the next\nsection.\n\n---\n\n## Use it inside Claude Code, Cursor, or any MCP client\n\nXFMS speaks **Model Context Protocol** (MCP) — the standard your\nAI assistant uses to call external tools. Once connected, you can\nask the assistant *\"which model should I use for OCR on shipping\nmanifests?\"* and it calls XFMS for you. No leaving the chat. No\ncopy-pasting between windows.\n\n### Hosted install — one line, no install required\n\nThe XFMS engine hosts the MCP server itself at\n**`https://xfms.xpansion.dev/mcp/`**. Two install shapes depending on\nwhich tools you want.\n\n### The free three — `rank`, `pick`, `discover`\n\nJust point your client at the URL. No key, no signup.\n\n**Claude Code:**\n\n```bash\nclaude mcp add xfms --transport http https://xfms.xpansion.dev/mcp/\n```\n\n**Cursor** (`~/.cursor/mcp.json`) — or paste through *Settings → MCP*:\n\n```json\n{\n  \"mcpServers\": {\n    \"xfms\": {\n      \"url\": \"https://xfms.xpansion.dev/mcp/\"\n    }\n  }\n}\n```\n\n### All five tools — adds `compare` and `benchmark`\n\nThese two run real test queries against the actual candidate models\non OpenRouter, so they require your OpenRouter key in an\n`X-OpenRouter-Key` header. Same install, one extra line:\n\n**Claude Code:**\n\n```bash\nclaude mcp add xfms --transport http https://xfms.xpansion.dev/mcp/ \\\n  --header \"X-OpenRouter-Key: sk-or-v1-your-key-here\"\n```\n\n**Cursor** (`~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"xfms\": {\n      \"url\": \"https://xfms.xpansion.dev/mcp/\",\n      \"headers\": {\n        \"X-OpenRouter-Key\": \"sk-or-v1-your-key-here\"\n      }\n    }\n  }\n}\n```\n\n**Continue / Cline / any other MCP host** — same URL + headers\npattern; check your host's docs for the JSON config shape.\n\nDon't have an OpenRouter key yet? Grab one at\n[openrouter.ai/keys](https://openrouter.ai/keys). Restart your\nclient, then ask it:\n\n> *\"Use XFMS to pick a model for summarizing long legal contracts.\"*\n\nFive tools are available to the assistant: **`rank`** (a ranked\nshortlist), **`pick`** (the single best pick), **`discover`** (which\nquality dimensions matter for your purpose, without ranking),\n**`compare`** (live A/B between models you've already named), and\n**`benchmark`** (live A/B against the engine's top 3 picks).\n`compare` and `benchmark` require the `X-OpenRouter-Key` header\nabove; the other three don't.\n\n---\n\n## Override the system's inference\n\nIf you know which quality dimension matters most for your task, say\nso — your preference always wins over the LLM's inference:\n\n```bash\nxfms rank \"code refactor\" --leaf-priorities \"structured_output_reliability=1.0,factuality=0.5\"\n```\n\n```python\nxfms.rank(\n    \"code refactor\",\n    leaf_priorities={\"structured_output_reliability\": 1.0, \"factuality\": 0.5},\n)\n```\n\n---\n\n## How XFMS picks — the four principles\n\nMethodology in full at [`docs/methodology.md`](docs/methodology.md).\nThe short version:\n\n1. **No provider self-reports.** Every score comes from a\n   third-party evaluator running the same protocol across every\n   model.\n2. **No single-source dependence.** Eight independent benchmark\n   sources contribute today; no single leaderboard determines a\n   pick.\n3. **User intent beats LLM inference.** The system infers weights\n   from your purpose, but your stated `leaf_priorities` always\n   override the inference.\n4. **Honest gaps over invented signal.** Missing data is recorded\n   as missing — no interpolation, no synthetic scores. Coverage\n   gaps surface on every pick.\n\n---\n\n## Part of the Xpansion Framework\n\nXFMS doesn't stand alone — it's the model-selection layer of the\n**[Xpansion Framework](https://xpansion.dev)**.\n\n### The Xpansion thesis\n\n> **Humans communicate with intent compressed by contextual experience.\n> AI simply predicts patterns in language. Xpansion is the execution\n> layer that bridges them.**\n\nEvery sentence a human types carries lifetimes of context that the\nspeaker assumes the other side will decompress — what counts as \"good\nenough,\" which constraints are non-negotiable, what failures last\nmonth taught them, what their house style demands. AI doesn't share\nthat context. It predicts patterns in language, filling in the gaps\nwith whatever's plausible to its training data. The result reads as\nplausible but isn't intent-honoring: sessions lose context, security\nholes ship silently, contracts break without warning, and there's no\nway to verify that what was built actually matches what was asked\nfor. **They don't know what they don't know, and neither does AI.**\n\nXpansion closes the gap. It **decompresses finite intent upfront**,\n**enforces it through code-driven AI behavior**, and **delivers\nbinary-verified results against the intent across persistent\nmemory** that survives every session boundary.\n\n### Model Source — the model-selection enforcement\n\nWhen you say *\"the best model for this task\"*, you're compressing\na lot: what counts as *best* depends on whether you care about\nfactual reasoning or coherent prose, whether cost matters more\nthan latency, whether you actually need vision or just text,\nwhether the call has to stream, whether a particular benchmark\ndominates your real workload. AI on its own predicts the pattern\n— *what model do most people pick for queries that look like\nthis?* — and gives you a plausible-sounding answer that's often\nwrong for *you*.\n\nXFMS does the decompression. It takes your stated purpose, infers\nwhich benchmarks actually map to it, honors your stated primary\npreferences without silently overriding them, surfaces the latent\nrequirements you didn't know to ask about (streaming for real-time\nchat, vision for OCR), and probes the top picks against your real\nquery to verify the recommendation — not predict it. Then it\ntells you, in plain English, why it picked what it picked.\n\n### One module per enforcement\n\nThe rest of the Xpansion stack enforces the same decompress-\nenforce-verify contract for different parts of the work:\n\n- **Dispatch** (`Dispatch`) — runtime task router. Watches what\n  kind of work you're doing and routes it to the right tool.\n- **Finite Intent** (`XFFI`) — turns *\"build me a feature\"* into a\n  finite spec with binary terminals *before* any code gets written.\n  Stops scope drift at the source.\n- **Boundary Auditor** (`XFBA`) — checks every code edit against\n  contracts. Stops broken function signatures and mismatched types\n  from ever reaching production.\n- **Systemic Impact Analysis** (`XSIA`) — maps the blast radius of\n  a proposed change before it lands. Tells you what else might\n  break.\n- **Token Conservation** (`XFTC`) — manages how much of the\n  conversation has to stay in the assistant's working memory.\n  Prevents context loss in long sessions.\n- **Execution Audit** (`XFXA`) — verifies every promise from the\n  spec was actually met before declaring a task done. The final\n  binary check.\n- **Memory Tree** (`XFMT`) — session snapshots that stay\n  searchable across conversations. Your assistant remembers what\n  you decided last week.\n- **Security Auditor** (`XFSA`) — static + AI security scanning on\n  every code edit. Catches secrets, injection paths, and unsafe\n  patterns before they ship.\n\nThe full picture, with the rest of the modules, lives at\n[xpansion.dev](https://xpansion.dev).\n\n**Xpansion is in pre-signup right now.** Early access and founding\nlicenses are open at [xpansion.dev](https://xpansion.dev). XFMS is\nthe first piece to ship public + free — the rest follow.\n\n---\n\n## Local development\n\n```bash\ngit clone https://github.com/VisionAIrySE/XFMS.git\ncd XFMS\npython3 -m venv .venv\n.venv/bin/pip install -e .[dev]\n.venv/bin/python -m pytest tests/ -v\n```\n\nThe tests mock the HTTP layer so they run offline — no API keys\nneeded to develop.\n\n---\n\n## License\n\nThis client library is MIT-licensed. The recommender engine, the\ncatalog, and the ingestion pipeline are not open source. See\n[`NOTICE`](NOTICE) for the patent reservation language and the\nrelationship to the broader Xpansion Framework IP.\n\n---\n\n## Contact\n\n- **Russ Wright** — russ@visionairy.biz\n- **Xpansion Framework** — [xpansion.dev](https://xpansion.dev)\n- **Security disclosures** — see [`SECURITY.md`](SECURITY.md)\n",
  "bytes": 13405,
  "sha": "160afee92581844d67ff3261bb8f3b28bc3b0974d7457e4915083a0568aa6d83",
  "repo_slug": "visionairyse/xfms",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_dev_xpansion_xfms_ea845969/readme"
}