least-cost-capable 0.1.1__tar.gz

least_cost_capable-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ALTA VISTA360, S.L.U.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

least_cost_capable-0.1.1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: least-cost-capable
+Version: 0.1.1
+Summary: Portable Agent Skill and helper that picks the lowest declared cost rank among catalogued models with the required capabilities. No provider calls.
+Author: ALTA VISTA360, S.L.U.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kanibal-studio/least-cost-capable
+Project-URL: Issues, https://github.com/kanibal-studio/least-cost-capable/issues
+Project-URL: PyPI, https://pypi.org/project/least-cost-capable/
+Keywords: agent-skills,ai-agents,llm,model-routing,cost-optimization,claude-code
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# least-cost-capable
+
+A portable Agent Skill and small Python helper for comparing declared relative cost ranks among agent models in a supplied catalogue. It checks task capability, availability, authorization, and whether cost evidence is comparable. It does not contact model providers, spend credits, launch agents, or guarantee actual savings or dispatch.
+
+Run with Python 3.10 or newer:
+
+```sh
+python scripts/select_model.py examples/catalogue.json
+```
+
+The example selects `standard-code`: the lower-ranked candidate lacks debugging capability, and the unavailable candidate is excluded. Tests cover mismatched input/output cost metrics, unknown evidence, duplicate IDs, and invalid catalogue roots. Invalid JSON or malformed catalogue data exits with a named command-line validation error and no selection.
+
+## Use with Claude Code
+
+Install it as a personal skill, available in every project:
+
+```sh
+git clone https://github.com/kanibal-studio/least-cost-capable ~/.claude/skills/least-cost-capable
+```
+
+Or copy this folder into a project's `.claude/skills/least-cost-capable/` to share it with the repository. Claude Code reads `SKILL.md` from that folder, and the helper stays at `scripts/select_model.py` inside it. Describe the task, give Claude a catalogue in the format of `examples/catalogue.json` (or the facts to build one), and ask it to use the least-cost-capable skill. The skill reports a choice from the catalogue's facts only; it does not switch models, change settings or launch agents.
+
+Created by ALTA VISTA360, S.L.U. (`kanibal-studio`).
+
+- [Altavista360](https://altavista360.com/)
+- [Altavista Conseil](https://altavista-conseil.com/)
+- [Kanibal Studio](https://infos.kanibal-studio.com/)
+
+Licensed under the [MIT License](LICENSE).

least_cost_capable-0.1.1/README.md

@@ -0,0 +1,29 @@
+# least-cost-capable
+
+A portable Agent Skill and small Python helper for comparing declared relative cost ranks among agent models in a supplied catalogue. It checks task capability, availability, authorization, and whether cost evidence is comparable. It does not contact model providers, spend credits, launch agents, or guarantee actual savings or dispatch.
+
+Run with Python 3.10 or newer:
+
+```sh
+python scripts/select_model.py examples/catalogue.json
+```
+
+The example selects `standard-code`: the lower-ranked candidate lacks debugging capability, and the unavailable candidate is excluded. Tests cover mismatched input/output cost metrics, unknown evidence, duplicate IDs, and invalid catalogue roots. Invalid JSON or malformed catalogue data exits with a named command-line validation error and no selection.
+
+## Use with Claude Code
+
+Install it as a personal skill, available in every project:
+
+```sh
+git clone https://github.com/kanibal-studio/least-cost-capable ~/.claude/skills/least-cost-capable
+```
+
+Or copy this folder into a project's `.claude/skills/least-cost-capable/` to share it with the repository. Claude Code reads `SKILL.md` from that folder, and the helper stays at `scripts/select_model.py` inside it. Describe the task, give Claude a catalogue in the format of `examples/catalogue.json` (or the facts to build one), and ask it to use the least-cost-capable skill. The skill reports a choice from the catalogue's facts only; it does not switch models, change settings or launch agents.
+
+Created by ALTA VISTA360, S.L.U. (`kanibal-studio`).
+
+- [Altavista360](https://altavista360.com/)
+- [Altavista Conseil](https://altavista-conseil.com/)
+- [Kanibal Studio](https://infos.kanibal-studio.com/)
+
+Licensed under the [MIT License](LICENSE).

least_cost_capable-0.1.1/least_cost_capable.egg-info/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: least-cost-capable
+Version: 0.1.1
+Summary: Portable Agent Skill and helper that picks the lowest declared cost rank among catalogued models with the required capabilities. No provider calls.
+Author: ALTA VISTA360, S.L.U.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kanibal-studio/least-cost-capable
+Project-URL: Issues, https://github.com/kanibal-studio/least-cost-capable/issues
+Project-URL: PyPI, https://pypi.org/project/least-cost-capable/
+Keywords: agent-skills,ai-agents,llm,model-routing,cost-optimization,claude-code
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# least-cost-capable
+
+A portable Agent Skill and small Python helper for comparing declared relative cost ranks among agent models in a supplied catalogue. It checks task capability, availability, authorization, and whether cost evidence is comparable. It does not contact model providers, spend credits, launch agents, or guarantee actual savings or dispatch.
+
+Run with Python 3.10 or newer:
+
+```sh
+python scripts/select_model.py examples/catalogue.json
+```
+
+The example selects `standard-code`: the lower-ranked candidate lacks debugging capability, and the unavailable candidate is excluded. Tests cover mismatched input/output cost metrics, unknown evidence, duplicate IDs, and invalid catalogue roots. Invalid JSON or malformed catalogue data exits with a named command-line validation error and no selection.
+
+## Use with Claude Code
+
+Install it as a personal skill, available in every project:
+
+```sh
+git clone https://github.com/kanibal-studio/least-cost-capable ~/.claude/skills/least-cost-capable
+```
+
+Or copy this folder into a project's `.claude/skills/least-cost-capable/` to share it with the repository. Claude Code reads `SKILL.md` from that folder, and the helper stays at `scripts/select_model.py` inside it. Describe the task, give Claude a catalogue in the format of `examples/catalogue.json` (or the facts to build one), and ask it to use the least-cost-capable skill. The skill reports a choice from the catalogue's facts only; it does not switch models, change settings or launch agents.
+
+Created by ALTA VISTA360, S.L.U. (`kanibal-studio`).
+
+- [Altavista360](https://altavista360.com/)
+- [Altavista Conseil](https://altavista-conseil.com/)
+- [Kanibal Studio](https://infos.kanibal-studio.com/)
+
+Licensed under the [MIT License](LICENSE).

least_cost_capable-0.1.1/least_cost_capable.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+least_cost_capable.egg-info/PKG-INFO
+least_cost_capable.egg-info/SOURCES.txt
+least_cost_capable.egg-info/dependency_links.txt
+least_cost_capable.egg-info/entry_points.txt
+least_cost_capable.egg-info/requires.txt
+least_cost_capable.egg-info/top_level.txt
+scripts/__init__.py
+scripts/select_model.py
+tests/test_select_model.py

least_cost_capable-0.1.1/least_cost_capable.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

least_cost_capable-0.1.1/least_cost_capable.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+least-cost-capable = least_cost_capable.select_model:main

least_cost_capable-0.1.1/least_cost_capable.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=8

least_cost_capable-0.1.1/least_cost_capable.egg-info/top_level.txt

@@ -0,0 +1 @@
+least_cost_capable

least_cost_capable-0.1.1/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "least-cost-capable"
+dynamic = ["version"]
+description = "Portable Agent Skill and helper that picks the lowest declared cost rank among catalogued models with the required capabilities. No provider calls."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "ALTA VISTA360, S.L.U." }]
+keywords = [
+    "agent-skills",
+    "ai-agents",
+    "llm",
+    "model-routing",
+    "cost-optimization",
+    "claude-code",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+least-cost-capable = "least_cost_capable.select_model:main"
+
+[project.urls]
+Homepage = "https://github.com/kanibal-studio/least-cost-capable"
+Issues = "https://github.com/kanibal-studio/least-cost-capable/issues"
+PyPI = "https://pypi.org/project/least-cost-capable/"
+
+[tool.setuptools]
+packages = ["least_cost_capable"]
+package-dir = { least_cost_capable = "scripts" }
+
+[tool.setuptools.dynamic]
+version = { attr = "least_cost_capable.__version__" }

least_cost_capable-0.1.1/scripts/__init__.py

@@ -0,0 +1,3 @@
+"""least-cost-capable: compare declared cost ranks among capable catalogued models."""
+
+__version__ = "0.1.1"

least_cost_capable-0.1.1/scripts/select_model.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Choose a least-cost capable model from an explicit JSON catalogue."""
+import argparse
+import json
+import math
+from pathlib import Path
+
+
+def select(catalogue):
+    if not isinstance(catalogue, dict):
+        raise ValueError("catalogue root must be a JSON object")
+    required = catalogue.get("required_capabilities")
+    models = catalogue.get("models")
+    if not isinstance(required, list) or not all(isinstance(x, str) for x in required):
+        raise ValueError("required_capabilities must be a list of strings")
+    if not isinstance(models, list):
+        raise ValueError("models must be a list")
+    if any(not isinstance(m, dict) for m in models):
+        raise ValueError("each models entry must be an object")
+    if any(not isinstance(m.get("id"), str) or not m["id"].strip() for m in models):
+        raise ValueError("each model must have a non-empty string id")
+    ids = [m["id"] for m in models]
+    if len(set(ids)) != len(ids):
+        raise ValueError("model ids must be unique")
+
+    exclusions, unresolved, capable = [], [], []
+    for m in models:
+        reasons = []
+        questions = []
+        if m.get("available") is False:
+            reasons.append("unavailable")
+        elif m.get("available") is not True:
+            questions.append("availability unknown")
+        if m.get("authorized") is False:
+            reasons.append("unauthorized")
+        elif m.get("authorized") is not True:
+            questions.append("authorization unknown")
+
+        caps = m.get("capabilities")
+        complete = m.get("capabilities_complete")
+        if caps is not None and (not isinstance(caps, list)
+                                 or not all(isinstance(c, str) for c in caps)):
+            raise ValueError("capabilities must be null or a list of strings")
+        if complete is not True:
+            questions.append("capability list not confirmed complete")
+        elif caps is None:
+            questions.append("capabilities unknown")
+        elif not set(required).issubset(set(caps)):
+            reasons.append("required capability absent from complete list")
+
+        if reasons:
+            exclusions.append({"id": m["id"], "reasons": reasons})
+        if questions:
+            unresolved.append({"id": m["id"], "questions": questions})
+        if reasons or questions:
+            continue
+        capable.append(m)
+
+    if not capable:
+        return {"status": "needs_information" if unresolved else "no_candidate_in_catalogue",
+                "selected": None,
+                "reason": ("No eligible capable model is established in the supplied catalogue; "
+                           "this does not prove none exists outside it."),
+                "unresolved": unresolved, "excluded": exclusions}
+
+    def comparable_cost(m):
+        cost = m.get("cost")
+        if not isinstance(cost, dict):
+            return False
+        fields = ("metric", "unit", "workload", "window", "source", "as_of", "relative_rank")
+        if not all(field in cost for field in fields):
+            return False
+        return (all(isinstance(cost[field], str) and cost[field].strip()
+                    for field in fields[:-1])
+                and isinstance(cost["relative_rank"], (int, float))
+                and not isinstance(cost["relative_rank"], bool)
+                and math.isfinite(cost["relative_rank"]))
+
+    missing = [m["id"] for m in capable if not comparable_cost(m)]
+    if missing:
+        return {"status": "needs_information", "selected": None,
+                "reason": ("Cost evidence must declare metric, unit, workload, window, source, "
+                           "as_of, and a finite relative_rank."),
+                "missing_cost": missing, "unresolved": unresolved, "excluded": exclusions}
+
+    signatures = {(m["cost"]["metric"], m["cost"]["unit"],
+                   m["cost"]["workload"], m["cost"]["window"],
+                   m["cost"]["source"], m["cost"]["as_of"]) for m in capable}
+    if len(signatures) != 1:
+        return {"status": "needs_information", "selected": None,
+                "reason": ("Capable candidates have different cost metrics, units, workloads, "
+                           "windows, sources, or as_of dates."),
+                "unresolved": unresolved, "excluded": exclusions}
+    winner = min(capable, key=lambda m: m["cost"]["relative_rank"])
+    return {"status": "selected", "selected": winner["id"],
+            "comparison": {key: winner["cost"][key] for key in
+                           ("metric", "unit", "workload", "window", "source", "as_of")},
+            "supplied_relative_rank": winner["cost"]["relative_rank"],
+            "reason": ("Lowest supplied rank for the declared matching cost comparison; "
+                       "this is not a claim of real-world savings or a dispatch guarantee."),
+            "unresolved": unresolved, "excluded": exclusions}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("catalogue", type=Path, help="Path to a JSON catalogue")
+    args = parser.parse_args()
+    try:
+        result = select(json.loads(args.catalogue.read_text(encoding="utf-8")))
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        parser.error(str(exc))
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

least_cost_capable-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

least_cost_capable-0.1.1/tests/test_select_model.py

@@ -0,0 +1,105 @@
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+
+SCRIPT = Path(__file__).parents[1] / "scripts/select_model.py"
+SPEC = importlib.util.spec_from_file_location("select_model", SCRIPT)
+module = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(module)
+
+
+def model(identifier, *, capabilities, metric="API input-token cost",
+          unit="USD per million input tokens", workload="same task",
+          window="last 7 days", rank=1, available=True, authorized=True,
+          capabilities_complete=True, source="synthetic", as_of="2026-10-11"):
+    return {"id": identifier, "capabilities": capabilities,
+            "capabilities_complete": capabilities_complete,
+            "cost": {"metric": metric, "unit": unit, "workload": workload,
+                     "window": window, "relative_rank": rank,
+                     "source": source, "as_of": as_of},
+            "available": available, "authorized": authorized}
+
+
+def test_selects_lowest_comparable_capable_and_excludes_unavailable():
+    result = module.select({"required_capabilities": ["code", "debug"], "models": [
+        model("too-weak", capabilities=["code"], rank=0),
+        model("standard", capabilities=["code", "debug"], rank=2),
+        model("unavailable", capabilities=["code", "debug"], rank=0, available=False),
+        model("costlier", capabilities=["code", "debug"], rank=5),
+    ]})
+    assert result["status"] == "selected"
+    assert result["selected"] == "standard"
+
+
+def test_refuses_to_compare_api_input_and_output_cost():
+    result = module.select({"required_capabilities": ["code"], "models": [
+        model("input", capabilities=["code"], metric="API input-token cost", rank=1),
+        model("output", capabilities=["code"], metric="API output-token cost", rank=0),
+    ]})
+    assert result["status"] == "needs_information"
+    assert result["selected"] is None
+
+
+def test_missing_cost_for_capable_candidate_stays_unknown():
+    unknown = model("unknown", capabilities=["code"])
+    unknown.pop("cost")
+    result = module.select({"required_capabilities": ["code"], "models": [
+        model("priced", capabilities=["code"], rank=2), unknown,
+    ]})
+    assert result["status"] == "needs_information"
+    assert result["missing_cost"] == ["unknown"]
+
+
+def test_unknown_availability_authorization_or_capabilities_remains_unresolved():
+    result = module.select({"required_capabilities": ["code"], "models": [
+        model("availability-unknown", capabilities=["code"], available=None),
+        model("authorization-unknown", capabilities=["code"], authorized=None),
+        model("capabilities-incomplete", capabilities=["code"], capabilities_complete=False),
+    ]})
+    assert result["status"] == "needs_information"
+    assert result["selected"] is None
+    assert {item["id"] for item in result["unresolved"]} == {
+        "availability-unknown", "authorization-unknown", "capabilities-incomplete"}
+
+
+def test_known_exclusion_is_reported_alongside_other_unknown_states():
+    result = module.select({"required_capabilities": ["code"], "models": [
+        model("unknown-and-forbidden", capabilities=["code"], authorized=False, available=None),
+        model("unavailable-but-authorization-unknown", capabilities=["code"],
+              available=False, authorized=None),
+    ]})
+    excluded = {item["id"]: item["reasons"] for item in result["excluded"]}
+    unresolved = {item["id"]: item["questions"] for item in result["unresolved"]}
+    assert "unauthorized" in excluded["unknown-and-forbidden"]
+    assert "availability unknown" in unresolved["unknown-and-forbidden"]
+    assert "unavailable" in excluded["unavailable-but-authorization-unknown"]
+    assert "authorization unknown" in unresolved["unavailable-but-authorization-unknown"]
+
+
+def test_duplicate_ids_are_rejected():
+    repeated = model("same", capabilities=["code"])
+    try:
+        module.select({"required_capabilities": ["code"], "models": [repeated, dict(repeated)]})
+    except ValueError as exc:
+        assert "unique" in str(exc)
+    else:
+        raise AssertionError("duplicate model ids must fail closed")
+
+
+@pytest.mark.parametrize("catalogue", [None, [], "not-an-object"])
+def test_invalid_catalogue_root_returns_named_error(catalogue):
+    with pytest.raises(ValueError, match="catalogue root must be a JSON object"):
+        module.select(catalogue)
+
+
+def test_no_capability_candidate_only_claims_catalogue_scope_and_reports_exclusions():
+    result = module.select({"required_capabilities": ["debug"], "models": [
+        model("weak", capabilities=["code"]),
+        model("off", capabilities=["debug"], available=False),
+    ]})
+    assert result["status"] == "no_candidate_in_catalogue"
+    assert "outside it" in result["reason"]
+    assert {tuple(x["reasons"]) for x in result["excluded"]} == {
+        ("required capability absent from complete list",), ("unavailable",)}