ai-kit-python 1.4.2__py3-none-any.whl

aikit/integrations/claude-settings.data-ask.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "ask": [
+      "Bash(rm -rf *)",
+      "Bash(rm -fr *)",
+      "Bash(git reset --hard*)",
+      "Bash(git clean *)",
+      "Bash(docker system prune*)",
+      "Bash(docker volume rm *)",
+      "Bash(docker volume prune*)"
+    ]
+  },
+  "stacks": {
+    "LARAVEL": [
+      "Bash(php artisan migrate*)",
+      "Bash(php artisan db:wipe*)",
+      "Bash(php artisan db:seed*)"
+    ],
+    "MOODLE": [
+      "Bash(php admin/cli/upgrade.php*)"
+    ]
+  }
+}

aikit/integrations/claude-settings.git-ask.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "ask": [
+      "Bash(git commit)",
+      "Bash(git commit *)",
+      "Bash(git push)",
+      "Bash(git push *)"
+    ]
+  }
+}

aikit/integrations/copilot-instructions.md

@@ -0,0 +1,3 @@
+# Project instructions
+
+Read AGENTS.md, ai-kit/CORE.md, settings, and current PROJECT_CONTEXT before edits; use WIKI for applicable rules.

aikit/integrations/security-audit.json

@@ -0,0 +1,135 @@
+{
+  "schema": 1,
+  "repository": "https://github.com/cloudflare/security-audit-skill",
+  "revision": "c1c8a8c1471069fb0e188eeaff69b8e8db6564a8",
+  "source_directory": "skills/security-audit",
+  "license": "MIT",
+  "files": {
+    "LICENSE": {
+      "sha256": "e598e694aa506650c7192d5ea3be0e50aca0d356ea00551c53429f0b01eb6391",
+      "git_blob": "6dbc9ecb3a5b9080e95b962869e8c7ab16cfdc20",
+      "git_mode": "100644",
+      "size": 1078
+    },
+    "AI-AND-LLM.md": {
+      "sha256": "7335a95c43554eadefcf03ece639291bb0e038c398a179299e3887ffe06bd2ef",
+      "git_blob": "02ba9039eca4cec811fefc77bce0d7349b379aae",
+      "git_mode": "100644",
+      "size": 10617
+    },
+    "ATTACK-CLASSES.md": {
+      "sha256": "3ee4f00c6e8c9dcf6dd02dd5ac2a4ceb322e2085f3e9fbe79cf0c6330bc7ef83",
+      "git_blob": "18a2beb4dbb554fb52b0a0293b8bd9108207f8fa",
+      "git_mode": "100644",
+      "size": 15695
+    },
+    "CLIENT-SIDE.md": {
+      "sha256": "613f6b98f86083e045525c5b60154ffdab122bac35f1e05eb17488e6e453370c",
+      "git_blob": "8ba673e9e7e3d02f5518aa0219bcbeec7957531b",
+      "git_mode": "100644",
+      "size": 8594
+    },
+    "CLOUD-AND-DEPLOYMENT.md": {
+      "sha256": "3c80f3088be22345e07b057c056d6ed99fe2b0304f794398964f7ccd5a496ca3",
+      "git_blob": "5569f76c7740744aa3f60aaa89eaefe275f2e6c9",
+      "git_mode": "100644",
+      "size": 8291
+    },
+    "DATA-ISOLATION-AND-LIFECYCLE.md": {
+      "sha256": "307dcb3e24d292715c4a041190e7bb135646a37eb6187619ae01d000a634a4ad",
+      "git_blob": "0cba1fa463b62c9b0caba710a201e29c1eecd0ec",
+      "git_mode": "100644",
+      "size": 7798
+    },
+    "DESKTOP-MOBILE-AND-LOCAL-IPC.md": {
+      "sha256": "58eae8ee0ca6a46611c501ec5a3ab47fdff88dd7db0d8d74789bbf8bb19d8cb2",
+      "git_blob": "d6230098651bff6348d3868c11f566bfb1306e7f",
+      "git_mode": "100644",
+      "size": 8739
+    },
+    "HUNTING.md": {
+      "sha256": "71c121decea1322c47c718f6e110f1a892980bb4266bd7ac55ef043a213ade09",
+      "git_blob": "377d4dcfbe88a049379448cd7892717185401597",
+      "git_mode": "100644",
+      "size": 22446
+    },
+    "MEMORY-SAFETY-AND-BINARY.md": {
+      "sha256": "7c8b0dccfb35315cca2455509674d49632b2fe37e1f3aac16c1a496a7e9924a7",
+      "git_blob": "86ff4920752661fc4a31a35ca4f962ace5dd5f48",
+      "git_mode": "100644",
+      "size": 10513
+    },
+    "PROTOCOLS-RPC-AND-MESSAGING.md": {
+      "sha256": "8b73816fa5b3697c9c40977f0c836b40f01d6e81929ff2720fe83ce089e9a619",
+      "git_blob": "b04ab88f852224838fdc9683d9fcccd858b0778a",
+      "git_mode": "100644",
+      "size": 7483
+    },
+    "RECONNAISSANCE.md": {
+      "sha256": "02ca887aca84de8ae137f1891bd2f0a54f28d3fa6da92a27f54734382b3381a2",
+      "git_blob": "1a170a93ab76b93dc5ac268a5b690beb423a8aa9",
+      "git_mode": "100644",
+      "size": 15902
+    },
+    "report-schema.json": {
+      "sha256": "6575c9de4a62255699ea052ebf9a49ebfb373a32891bcd89af6f55cc84b35519",
+      "git_blob": "55815a3687a45fff63d8ebf20068611bd6ad6d9a",
+      "git_mode": "100644",
+      "size": 14494
+    },
+    "RESOURCE-EXHAUSTION-AND-AVAILABILITY.md": {
+      "sha256": "4326fab5c92a0b4c420a70196254040105cd794026562130b59bf1a6db3e4baa",
+      "git_blob": "6cbbd1e2cfa482068c8279c2f7da9db43d3f54b8",
+      "git_mode": "100644",
+      "size": 7476
+    },
+    "SKILL.md": {
+      "sha256": "5e3e96a1e438d8f35fef0a1e38f02d4f00e2bdf910401b7dfe00e6779c6dac85",
+      "git_blob": "92178dad304d3f63e37582a297026a7874e12c62",
+      "git_mode": "100644",
+      "size": 22026
+    },
+    "SUPPLY-CHAIN-AND-RELEASE.md": {
+      "sha256": "f372e919940e335468ba1ae09f99026c3986a345f7fe26f8068f132e199f52a5",
+      "git_blob": "bf96aed0803bc07471483ab129dea86759c3e305",
+      "git_mode": "100644",
+      "size": 7258
+    },
+    "validate-coverage-ledger.cjs": {
+      "sha256": "2eb280bd2e33c002916f86db9b29f9edfedb6454e5db973c766290465b868ac8",
+      "git_blob": "0ef58657bef18b26a92321df6c8e3d31bc8e6659",
+      "git_mode": "100755",
+      "size": 33522
+    },
+    "validate-coverage-ledger.test.cjs": {
+      "sha256": "cfb9df26b03469a4279a70e7664a2a5434dd6f8c2c204e91f9b0aeb9dd71e648",
+      "git_blob": "b1444f57e1b021a61175733b8c356171861c8701",
+      "git_mode": "100644",
+      "size": 28483
+    },
+    "validate-findings.cjs": {
+      "sha256": "e85f232e36bfac0f866f244da50376692d6b45c690beadcb00608b0e6c8b5283",
+      "git_blob": "2843feceddb7e30bf10d6e4f7bbe6640e4c57799",
+      "git_mode": "100755",
+      "size": 28806
+    },
+    "validate-findings.test.cjs": {
+      "sha256": "b92001117a92c4161d43777a0ba2fa182a8a4d97f2304cc8c0cee5331497b73b",
+      "git_blob": "8d245b226bbe2fdf28b46b3203b99c2824039d2d",
+      "git_mode": "100644",
+      "size": 26384
+    },
+    "VALIDATION-AND-REPORTING.md": {
+      "sha256": "b892470cb89bb31f33403e050d4bdfbe2cdaef940ade1496fa65e32b2e129449",
+      "git_blob": "5e200d7387e665e53e0e4190fa4a5814c334c507",
+      "git_mode": "100644",
+      "size": 17843
+    },
+    "WEB-PROTOCOL-AND-AUTH.md": {
+      "sha256": "4f3066dffa23c5635859187be9b96c32f2aff29a688186b91ff0c63e47d62b5c",
+      "git_blob": "1a099fa575cf52a61e9a627f91b61015120fa517",
+      "git_mode": "100644",
+      "size": 12300
+    }
+  }
+}

aikit/integrations/strix.json

@@ -0,0 +1,69 @@
+{
+  "schema": 1,
+  "repository": "https://github.com/usestrix/strix",
+  "revision": "f7a32ae62d94872631bc8415073868d02a6ffdaf",
+  "source_directory": "skills",
+  "license": "Apache-2.0",
+  "files": {
+    "LICENSE": {
+      "sha256": "7db9697134251e314bd8d39257fe170c98b3e2ad9b2ed67e97acaf9613e7b9e3",
+      "git_blob": "65c4e8f58a00552cc29f6bd1dcaf1c4ef10012b8",
+      "git_mode": "100644",
+      "size": 11345
+    },
+    "api-security-testing/SKILL.md": {
+      "sha256": "bd04c90d87be2353ebefee33363af0818746345e25c80ed36f63fcdd2b25509c",
+      "git_blob": "d21a25da6167f79c3caff745abc142b2118c2691",
+      "git_mode": "100644",
+      "size": 6331
+    },
+    "application-security-testing/SKILL.md": {
+      "sha256": "b3041c800a9a1d34e04164c5f700b6d12bbc237f098d760c09ec076c92d2a654",
+      "git_blob": "0c27bd5df4a346abfc1e81efc62f49b066637f52",
+      "git_mode": "100644",
+      "size": 4557
+    },
+    "ci-security-scanning-with-strix/SKILL.md": {
+      "sha256": "f8e1dd61721dc302bd64155f80a2a3b16a5bf5bca598ae23d98aad8fefebea91",
+      "git_blob": "69ae726776b8c1dbc667f18a9f972a66e4656c4e",
+      "git_mode": "100644",
+      "size": 9019
+    },
+    "find-security-vulnerabilities-in-code/SKILL.md": {
+      "sha256": "e7c25f1a0aea437d011d96dd306736b644597b07aa5a6dbc5588eefaab248e0a",
+      "git_blob": "b1829e9cba9db38d6d76e9fa274da3caa188ac75",
+      "git_mode": "100644",
+      "size": 4386
+    },
+    "fix-security-vulnerabilities-with-strix/SKILL.md": {
+      "sha256": "bb1b351fd60c91e4875207f3fe4f35774ff5194261a00aea9f4752e459f24a9f",
+      "git_blob": "6912cb542b3e5c46e99fa196cd29039de9a8e574",
+      "git_mode": "100644",
+      "size": 5997
+    },
+    "managed-pentesting-with-strix/SKILL.md": {
+      "sha256": "45e1432ea897e59e67a5102513a4b9aac7372a5666d68d620ee867bbfa8b290b",
+      "git_blob": "246aa882580962a89aaef2ad89d5d3c6e150a793",
+      "git_mode": "100644",
+      "size": 23639
+    },
+    "owasp-top-10-testing/SKILL.md": {
+      "sha256": "02b1cbe60d40c44493309418c7824f1f681d9f32bf0299ca246892c46cb130af",
+      "git_blob": "328e217f7e0ab0fe43f448de49c1b2fb2897a6a7",
+      "git_mode": "100644",
+      "size": 6245
+    },
+    "penetration-testing-with-strix/SKILL.md": {
+      "sha256": "8051d93f1ccc96c7268ca7b3d3d589c56997c620164773617ceb53af8832692c",
+      "git_blob": "afd56cea3920da1f5092f90244c3db7519b8b0ae",
+      "git_mode": "100644",
+      "size": 10131
+    },
+    "web-app-penetration-testing/SKILL.md": {
+      "sha256": "2e8df0b9233971c496d0c0c7660808fc717c08d4165455a0423229045389608a",
+      "git_blob": "99331fa8bb83315a3bce4449592bb77504421d30",
+      "git_mode": "100644",
+      "size": 4320
+    }
+  }
+}

aikit/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-kit-python"
+description = "Offline installer and portable instructions that give AI coding agents project memory, stack rules, guardrails, and adaptive model routing."
+readme = {file = "docs/PYPI_DESCRIPTION.md", content-type = "text/markdown"}
+requires-python = ">=3.10"
+authors = [{name = "Igor Sazonov"}]
+license = "MIT AND Apache-2.0"
+license-files = [
+    "LICENSE",
+    "template/ai-kit/vendor/security-audit/LICENSE",
+    "template/ai-kit/vendor/strix/LICENSE",
+]
+keywords = ["ai-agents", "coding-assistant", "context-engineering", "agent-skills", "project-memory", "developer-tools"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "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 :: Software Development",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://github.com/tigusigalpa/ai-kit"
+Documentation = "https://github.com/tigusigalpa/ai-kit#readme"
+Source = "https://github.com/tigusigalpa/ai-kit"
+Issues = "https://github.com/tigusigalpa/ai-kit/issues"
+Changelog = "https://github.com/tigusigalpa/ai-kit/blob/main/CHANGELOG.md"
+
+[project.scripts]
+aikit = "aikit.aikit_cli:main"
+
+[tool.setuptools]
+packages = ["aikit", "aikit.scripts"]
+package-dir = {aikit = ".", "aikit.scripts" = "scripts"}
+include-package-data = true
+
+[tool.setuptools.package-data]
+aikit = ["VERSION", "LICENSE", "MANIFEST.in", "pyproject.toml", "Makefile", "Dockerfile", ".dockerignore", ".gitignore", ".gitattributes", "*.md", "*.json", "ai-kit/*.md", "ai-kit/router/*.md", "ai-kit/router/providers/*.md", "ai-kit/stacks/*.md", "ai-kit/profiles/*.md", "docs/**/*", "integrations/**/*", "template/**/*", "template/.agents/**/*", "templates/**/*", ".github/**/*", ".agents/**/*", "docker/**/*", "deploy/**/*", "tests/*.py", "tests/fixtures/**/*"]
+
+[tool.setuptools.dynamic]
+version = {file = ["VERSION"]}
+
+[tool.setuptools.exclude-package-data]
+aikit = [
+    "AGENTS.md", "PROJECT_CONTEXT.md", "WIKI.md", "auth.json", ".netrc", ".pypirc", ".env", ".env.*",
+    "ai-kit/.metrics/*", "ai-kit/.memory/*", "ai-kit/.upstream-cache/*", "ai-kit/.design/*", "docs/.private/*",
+    "**/.env", "**/.env.*", "**/auth.json", "**/.netrc", "**/.pypirc",
+    "*.pem", "*.p12", "*.pfx", "id_rsa*", "id_ed25519*",
+    "**/*.pem", "**/*.p12", "**/*.pfx", "**/id_rsa*", "**/id_ed25519*",
+]

aikit/scripts/__init__.py

@@ -0,0 +1 @@
+"""AI-KIT command implementations."""

aikit/scripts/adapters.py

@@ -0,0 +1,184 @@
+"""Review client adapters and retire only unchanged AI-KIT-owned adapter files."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import install
+
+
+STATE_PATH = "ai-kit/.install-state.json"
+
+
+def target_root(target: Path) -> Path:
+    target = target.absolute()
+    if install.is_link(target):
+        raise ValueError("Refusing a linked project root")
+    target = target.resolve()
+    if not target.is_dir():
+        raise ValueError("Project must be an existing directory")
+    return target
+
+
+def installed_state(target: Path, registry: dict) -> dict:
+    path = install.safe_path(target, STATE_PATH)
+    if not path.is_file():
+        raise ValueError("No installer state found; is AI-KIT installed in this project?")
+    state = install.read_json(path, {})
+    # Read-only audits must reach their obstruction report; lexical/link boundaries stay strict.
+    install.validate_state(state, target, registry["names"], allow_obstructions=True)
+    return state
+
+
+def report(*, root: Path = install.ROOT, project: Path | None = None) -> dict:
+    registry = install.load_agent_registry(root)
+    state = None
+    detected: dict[str, list[str]] = {}
+    target = None
+    if project is not None:
+        target = target_root(project)
+        state = installed_state(target, registry)
+        detected = install.detect_agents(target, registry)
+    clients = []
+    for name in sorted(registry["names"]):
+        metadata = registry["metadata"][name]
+        managed = []
+        blocked = []
+        selected = None
+        if state is not None:
+            selected = name in state["agents"]
+            for relative in sorted(state["files"]):
+                if install.adapter_owner(relative, registry) != name:
+                    continue
+                try:
+                    exists = install.safe_path(target, relative).is_file()
+                except (ValueError, NotADirectoryError):
+                    blocked.append(relative)
+                    continue
+                if exists:
+                    managed.append(relative)
+        clients.append({"client": name, "documentation_status": metadata["status"],
+                        "verified_documentation_date": metadata["verified_documentation_date"],
+                        "sources": metadata["sources"], "activation": metadata["activation"],
+                        "selected": selected, "detected": detected.get(name, []), "managed_paths": managed,
+                        "blocked_paths": blocked})
+    return {"project": str(target) if target is not None else None, "clients": clients,
+            "note": "Documentation status does not prove native client activation."}
+
+
+def retirement_plan(project: Path, agent: str, *, root: Path = install.ROOT) -> dict:
+    target = target_root(project)
+    registry = install.load_agent_registry(root)
+    if agent not in registry["names"]:
+        raise ValueError("Unknown client: " + agent)
+    state = installed_state(target, registry)
+    if agent in state["agents"] and len(state["agents"]) == 1:
+        raise ValueError("Cannot retire the last selected client; install a replacement selection first")
+    records = state["files"]
+    removals, conflicts, absent = [], [], []
+    for relative in sorted(records):
+        if install.adapter_owner(relative, registry) != agent:
+            continue
+        try:
+            path = install.safe_path(target, relative)
+        except (ValueError, NotADirectoryError):
+            conflicts.append(relative)
+            continue
+        if not path.exists():
+            absent.append(relative)
+            continue
+        if not path.is_file():
+            conflicts.append(relative)
+            continue
+        data = path.read_bytes()
+        record = records[relative]
+        if record.get("local_adaptation") or install.digest(data) != record.get("installed_hash"):
+            conflicts.append(relative)
+            continue
+        removals.append({"path": relative, "old": data,
+                         "backup": "ai-kit/.upstream-cache/retirements/" + install.digest(data) + "/" + relative})
+    next_state = dict(state)
+    next_files = dict(records)
+    for item in removals:
+        next_files.pop(item["path"], None)
+    for relative in absent:
+        next_files.pop(relative, None)
+    next_state["files"] = next_files
+    next_state["agents"] = [name for name in state["agents"] if name != agent]
+    state_path = install.safe_path(target, STATE_PATH)
+    old_state = state_path.read_bytes()
+    state_data = (json.dumps(next_state, indent=2, sort_keys=True) + "\n").encode("utf-8")
+    return {"target": str(target), "agent": agent, "removals": removals, "conflicts": conflicts,
+            "absent": absent, "state_path": STATE_PATH, "state_old": old_state, "state_data": state_data,
+            "warnings": ((["Selected client will be deselected only after this explicit retirement."]
+                          if agent in state["agents"] else []) +
+                         (["Modified or non-file adapter paths require manual retirement."] if conflicts else []))}
+
+
+def apply_retirement(plan: dict) -> bool:
+    if plan["conflicts"]:
+        return False
+    target = Path(plan["target"])
+    state_path = install.safe_path(target, plan["state_path"])
+    if state_path.read_bytes() != plan["state_old"]:
+        raise ValueError("Installer state changed after preview")
+    for item in plan["removals"]:
+        path = install.safe_path(target, item["path"])
+        actual = path.read_bytes() if path.exists() and path.is_file() else None
+        if actual != item["old"]:
+            raise ValueError("Adapter changed after preview: " + item["path"])
+    completed = []
+    try:
+        for item in plan["removals"]:
+            path = install.safe_path(target, item["path"])
+            backup = install.safe_path(target, item["backup"])
+            if backup.exists():
+                if backup.read_bytes() != item["old"]:
+                    raise ValueError("Existing retirement backup differs: " + item["backup"])
+            else:
+                install.atomic_write(backup, item["old"])
+            path.unlink()
+            completed.append(item)
+        install.atomic_write(state_path, plan["state_data"])
+    except (OSError, ValueError):
+        for item in reversed(completed):
+            path = install.safe_path(target, item["path"])
+            if not path.exists():
+                install.atomic_write(path, item["old"])
+        raise
+    return True
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    report_parser = sub.add_parser("report", help="List client documentation status and installed adapter evidence")
+    report_parser.add_argument("--project", type=Path)
+    retire = sub.add_parser("retire", help="Preview or remove unchanged tracked files and explicitly deselect one client")
+    retire.add_argument("project", type=Path)
+    retire.add_argument("--agent", required=True)
+    retire.add_argument("--apply", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "report":
+            print(json.dumps(report(project=args.project), indent=2))
+            return 0
+        plan = retirement_plan(args.project, args.agent)
+        print(json.dumps({"target": plan["target"], "agent": plan["agent"], "preview": not args.apply,
+                          "removals": [item["path"] for item in plan["removals"]],
+                          "backups": [item["backup"] for item in plan["removals"]],
+                          "conflicts": plan["conflicts"], "absent": plan["absent"],
+                          "warnings": plan["warnings"]}, indent=2))
+        if args.apply:
+            apply_retirement(plan)
+        return 2 if plan["conflicts"] else 0
+    except (OSError, ValueError, UnicodeError, json.JSONDecodeError) as exc:
+        print(f"Adapter operation refused: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aikit/scripts/adaptive.py

@@ -0,0 +1,167 @@
+"""Optional routing modes, pins and measured recommendations, without a switching runtime."""
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import install
+import learning
+import metrics
+import router
+
+MODES = ("manual", "fixed", "recommended", "adaptive")
+PROFILES = ("economy", "balanced", "quality")
+
+
+def defaults() -> dict:
+    return {"schema": 1, "mode": "recommended", "profile": "balanced", "project_pin": None,
+            "task_pins": {}, "minimum_cases": 20, "quality_floor": 0.8,
+            "context_bytes": {"economy": 16000, "balanced": 32000, "quality": 64000},
+            "orchestration": {"planner": "work", "executor": "work", "reviewer": "work", "escalation": "escalation"}}
+
+
+def validate_pin(value: object) -> dict:
+    if not isinstance(value, dict) or set(value) != {"provider", "model", "effort"}:
+        raise ValueError("A pin needs provider, model and effort (null when unknown/not controlled)")
+    for key in ("provider", "model"):
+        metrics._identifier(value[key], key)
+    if value["effort"] is not None:
+        metrics._identifier(value["effort"], "effort")
+    return value
+
+
+def validate_config(value: object) -> dict:
+    base = defaults()
+    if not isinstance(value, dict) or set(value) - set(base):
+        raise ValueError("Invalid routing configuration or unknown fields")
+    base.update(copy.deepcopy(value))
+    if type(base["schema"]) is not int or base["schema"] != 1:
+        raise ValueError("Expected routing schema 1")
+    if not isinstance(base["mode"], str) or not isinstance(base["profile"], str) or base["mode"] not in MODES or base["profile"] not in PROFILES:
+        raise ValueError("Unknown routing mode/profile")
+    if base["project_pin"] is not None:
+        validate_pin(base["project_pin"])
+    if not isinstance(base["task_pins"], dict):
+        raise ValueError("task_pins must be an object")
+    for key, pin in base["task_pins"].items():
+        metrics._identifier(key, "task pin ID")
+        validate_pin(pin)
+    if type(base["minimum_cases"]) is not int or base["minimum_cases"] < 5:
+        raise ValueError("Minimum sample must be at least five distinct cases")
+    if type(base["quality_floor"]) not in {int, float} or not 0.5 <= base["quality_floor"] <= 1:
+        raise ValueError("Quality floor must be 0.5-1")
+    if (not isinstance(base["context_bytes"], dict) or set(base["context_bytes"]) != set(PROFILES) or
+            any(type(v) is not int or v < 1 for v in base["context_bytes"].values())):
+        raise ValueError("Every profile needs a positive context byte budget")
+    roles = base["orchestration"]
+    if (not isinstance(roles, dict) or set(roles) != {"planner", "executor", "reviewer", "escalation"} or
+            any(v not in router.ROLES for v in roles.values())):
+        raise ValueError("Orchestration roles must map to configured routing roles")
+    return base
+
+
+def load_config(project: Path | None = None, root: Path = router.ROOT) -> dict:
+    path = (install.safe_path(metrics._target(project), "ai-kit/router/routing.json") if project else
+            root / "template/ai-kit/router/routing.json")
+    return validate_config(json.loads(path.read_text(encoding="utf-8")) if path.exists() else {})
+
+
+def recommend_route(text: str, selection: dict, providers: dict, *, config: dict | None = None,
+                    records: list[dict] | None = None, mode: str | None = None, profile: str | None = None,
+                    task_id: str | None = None, stack: str = "unknown", capabilities: list[str] | None = None,
+                    **overrides) -> dict:
+    config = validate_config(config or {})
+    mode, profile = mode or config["mode"], profile or config["profile"]
+    if mode not in MODES or profile not in PROFILES:
+        raise ValueError("Unknown routing mode/profile")
+    if stack not in metrics.STACKS:
+        raise ValueError("Unknown stack")
+    if task_id is not None:
+        metrics._identifier(task_id, "task_id")
+    capabilities = capabilities or []
+    for capability in capabilities:
+        metrics._identifier(capability, "capability")
+    pin = config["task_pins"].get(task_id, config["project_pin"])
+    source = "task pin" if task_id in config["task_pins"] else "project pin"
+    explicit = any(overrides.get(k) is not None for k in ("provider", "model", "effort"))
+    call = dict(overrides)
+    effective_pin = copy.deepcopy(pin)
+    if pin:
+        if overrides.get("provider") is not None and overrides["provider"] != pin["provider"]:
+            effective_pin.pop("model", None)
+            effective_pin.pop("effort", None)
+        elif overrides.get("model") is not None and overrides["model"] != pin["model"]:
+            effective_pin.pop("effort", None)
+        call = {**effective_pin, **{k: v for k, v in overrides.items() if v is not None}}
+        selection = copy.deepcopy(selection)
+        for name in router.ROLES:
+            spec = selection["roles"].get(name)
+            if isinstance(spec, dict):
+                spec.pop("effort", None)
+    result = router.route_result(text, selection, providers, **call)
+    if mode in {"manual", "fixed"} and not pin and overrides.get("model") is None:
+        raise ValueError("Manual/fixed mode requires a project/task pin or explicit model")
+    if mode in {"manual", "fixed"} and not result["resolved"]:
+        raise ValueError("Pinned model is unresolved")
+    if pin and "effort" in effective_pin and overrides.get("effort") is None:
+        # Null pin effort explicitly means no effort control; the ladder cannot override it.
+        result["effort"] = effective_pin["effort"]
+        result["effort_source"] = source
+    configured_effort = router._role_selection(result["role"], selection).get("effort") is not None
+    if not pin and not explicit and not configured_effort:
+        supported = router._supported_efforts(providers.get(result["provider"], {}), result["model"])
+        ladder = ("none", "minimal", "low", "medium", "high", "xhigh", "max")
+        if profile == "quality" and result["effort"] in ladder and "high" in supported and ladder.index(result["effort"]) < ladder.index("high"):
+            result["effort"], result["effort_source"] = "high", "quality profile"
+        elif profile == "economy" and result["level"] < 3 and result["effort"] == "medium" and "low" in supported:
+            result["effort"], result["effort_source"] = "low", "economy profile"
+    learned = None
+    if mode == "adaptive" and not pin and not explicit and not configured_effort:
+        classified = router.classify_task(text, operation=overrides.get("operation"),
+                                         risks=overrides.get("risks", ()), components=overrides.get("components"))
+        task_class = overrides.get("operation") or classified["signals"][0].split(": ")[-1]
+        available = {selection.get("default_provider")}
+        available.update(router._role_selection(name, selection).get("provider") for name in router.ROLES)
+        if any(selection["local_models"].values()):
+            available.update(name for name, catalogue in providers.items() if catalogue.get("user_supplied_models"))
+        available.discard(None)
+        learned = learning.recommend(records or [], result, stack=stack, task_class=task_class,
+                                     level=result["level"], capabilities=capabilities,
+                                     minimum=config["minimum_cases"],
+                                     quality_floor=max(config["quality_floor"], 0.95 if profile == "quality" else 0.5),
+                                     profile=profile, allowed_providers=available)
+        if learned:
+            catalogue = providers.get(learned["provider"], {})
+            declared = list(catalogue.get("roles", {}).values())
+            supported = set(next((s.get("capabilities", []) for s in declared if s.get("model") == learned["model"]), []))
+            known_models = {s.get("model") for s in declared} | (set(selection["local_models"].values()) if catalogue.get("user_supplied_models") else set())
+            efforts = router._supported_efforts(catalogue, learned["model"])
+            if (catalogue and catalogue.get("verification_status") != "pending" and learned["model"] in known_models and
+                    (learned["effort"] is None or learned["effort"] in efforts) and set(capabilities) <= supported):
+                proposed = router.route_result(text, selection, providers, **{
+                    **overrides, **{k: learned[k] for k in ("provider", "model", "effort")}})
+                result = proposed
+                result["effort"] = learned["effort"]
+                result["effort_source"] = "matched measurements"
+            else:
+                learned = None
+    result.update({"routing_mode": mode, "optimization_profile": profile,
+                   "context_budget_bytes": config["context_bytes"][profile],
+                   "independent_review": profile == "quality" or result["level"] >= 4,
+                   "escalation_policy": "diagnosed failure; independent review before acceptance" if profile == "quality" else
+                                        "bounded rework before diagnosed escalation; preserve quality floor" if profile == "economy" else
+                                        "diagnosed capability shortfall; include recovery cost",
+                   "recommendation_source": "explicit" if explicit else source if pin else
+                                            "matched measurements" if learned else "capability ladder",
+                   "measurement_evidence": learned, "execution_confirmed": False})
+    declared = providers.get(result["provider"], {}).get("roles", {}).values()
+    known = set(next((s.get("capabilities", []) for s in declared if s.get("model") == result["model"]), []))
+    result["capabilities_verified"] = set(capabilities) <= known
+    if not result["capabilities_verified"]:
+        result["adjustments"].append("Required capabilities are not declared for this model; verify before execution.")
+    if mode == "adaptive" and not learned and not pin and not explicit:
+        result["adjustments"].append("Insufficient comparable measured evidence; retain the capability recommendation.")
+    return result