@allansantos-dev/smart-tool 0.0.0-stage → 0.9.1

package/gateway.py

@@ -0,0 +1,220 @@
+"""Model gateway through adapters: how Smart Tool reaches embedding, chat and (optionally) rerank models.
+
+Pattern copied from OpenCode providers (implementation + options, credentials kept apart; opencode.ai/docs/providers)
+and LiteLLM custom handlers (a fixed set of methods registered by name; docs.litellm.ai custom_llm_server).
+
+An adapter is a Python module with:
+  NAME    unique id (str)
+  LABEL   name shown in the setup screen
+  FIELDS  sequence of {"name", "label", optional "secret", "required", "placeholder", "hint"}
+  request(options, route, body=None, timeout=15) -> (json, headers)
+          route is OpenAI-style: "models", "model/info", "embeddings", "chat/completions", "rerank"; body None = GET.
+          HTTP errors propagate as urllib.error.HTTPError.
+  verify(options) -> None, raising RuntimeError with a reason a person can act on.
+
+Built-in adapters live in model_adapters/; any .py in ADAPTERS_DIR is loaded as a user adapter. Non-secret options
+stay in config.json; secret fields go to the DPAPI key store.
+"""
+import importlib.util
+import os
+import threading
+import time
+
+import config
+import secret_store
+from model_adapters import openai_compatible
+
+ADAPTERS_DIR = os.path.join(config.CONFIG_DIR, "adapters")
+BUILTIN = (openai_compatible,)
+STATUS_TTL_S = 30
+_lock = threading.Lock()
+_loaded = {"key": None, "adapters": {}, "errors": []}
+_status = {"at": 0.0, "key": None, "value": None}
+
+
+def _check(module, origin):
+    for attribute in ("NAME", "LABEL", "FIELDS"):
+        if not getattr(module, attribute, None):
+            raise ValueError(f"{origin}: missing {attribute}")
+    for function in ("request", "verify"):
+        if not callable(getattr(module, function, None)):
+            raise ValueError(f"{origin}: missing function {function}()")
+    for field in module.FIELDS:
+        if not isinstance(field, dict) or not field.get("name") or not field.get("label"):
+            raise ValueError(f"{origin}: each FIELDS entry needs name and label")
+    return module
+
+
+def adapters():
+    """({name: module}, [load errors]); user adapters are re-imported only when their files change."""
+    errors, stamped = [], []
+    try:
+        names = sorted(name for name in os.listdir(ADAPTERS_DIR) if name.endswith(".py"))
+    except FileNotFoundError:
+        names = []
+    except OSError as exc:
+        names, errors = [], [f"{ADAPTERS_DIR}: {type(exc).__name__}: {exc}"]
+    for name in names:
+        path = os.path.join(ADAPTERS_DIR, name)
+        try:
+            stamped.append((path, os.path.getmtime(path)))
+        except OSError:
+            continue
+    key = (tuple(stamped), tuple(errors))
+    with _lock:
+        if _loaded["key"] == key:
+            return dict(_loaded["adapters"]), list(_loaded["errors"])
+    # Imported outside the lock: an adapter that calls back into gateway at import time must not deadlock the daemon.
+    found = {module.NAME: module for module in BUILTIN}
+    for path, _mtime in stamped:
+        try:
+            spec = importlib.util.spec_from_file_location(
+                "smart_tool_adapter_" + os.path.splitext(os.path.basename(path))[0], path)
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+            _check(module, path)
+            if module.NAME in found:
+                raise ValueError(f"{path}: NAME {module.NAME!r} already exists")
+            found[module.NAME] = module
+        except Exception as exc:
+            errors.append(f"{os.path.basename(path)}: {type(exc).__name__}: {exc}")
+    with _lock:
+        _loaded.update(key=key, adapters=found, errors=errors)
+    return dict(found), list(errors)
+
+
+def _secret_name(adapter, field):
+    return f"adapter:{adapter}:{field}"
+
+
+def selected():
+    """(adapter module or None, options with secrets in clear). Unknown adapter in config fails loudly."""
+    cfg = config.load_config()
+    name = cfg.get("model_adapter") or ""
+    if not name:
+        return None, {}
+    found, errors = adapters()
+    if name not in found:
+        raise RuntimeError(f"Model adapter {name!r} not found" + (f" ({'; '.join(errors)})" if errors else ""))
+    module = found[name]
+    options = dict((cfg.get("model_adapter_options") or {}).get(name) or {})
+    for field in module.FIELDS:
+        if field.get("secret"):
+            options[field["name"]] = config.get_provider_api_key(_secret_name(name, field["name"]))
+    return module, options
+
+
+def describe():
+    """Setup screen view: adapters with fields, stored non-secret values and secret state; never the secrets."""
+    cfg = config.load_config()
+    found, errors = adapters()
+    stored = cfg.get("model_adapter_options") or {}
+    listing = []
+    for name, module in found.items():
+        fields = []
+        for field in module.FIELDS:
+            entry = {key: field.get(key) for key in ("name", "label", "secret", "required", "placeholder", "hint")}
+            if field.get("secret"):
+                entry["state"] = config.provider_key_status(_secret_name(name, field["name"]))
+            else:
+                entry["value"] = (stored.get(name) or {}).get(field["name"], "")
+            fields.append(entry)
+        listing.append({"name": name, "label": module.LABEL, "builtin": module in BUILTIN, "fields": fields})
+    return {"selected": cfg.get("model_adapter") or "", "adapters": listing, "errors": errors, "dir": ADAPTERS_DIR}
+
+
+def save(name, values):
+    """Verifies with the adapter before storing. Secret field absent/None keeps the stored value; "" removes it.
+    name "" disconnects."""
+    if not name:
+        config.update_config(lambda cfg: cfg.update(model_adapter=""))
+        forget_status()
+        return
+    found, _errors = adapters()
+    if name not in found:
+        raise ValueError(f"Adapter {name!r} does not exist.")
+    module, values = found[name], values or {}
+    plain, secrets, options = {}, {}, {}
+    for field in module.FIELDS:
+        key = field["name"]
+        value = values.get(key)
+        if field.get("secret"):
+            if value is None:
+                try:
+                    value = config.get_provider_api_key(_secret_name(name, key))
+                except secret_store.SecretProtectionError:
+                    raise ValueError(f"The saved value of {field['label']} cannot be opened in this Windows profile; "
+                                     "paste it again.") from None
+            else:
+                secrets[key] = str(value).strip()
+                value = secrets[key]
+                if value:
+                    config.check_provider_key_format(value)
+        else:
+            value = str(value or "").strip()
+            plain[key] = value
+        if field.get("required") and not value:
+            raise ValueError(f"Fill in {field['label']}.")
+        options[key] = value
+    module.verify(options)
+
+    def mutate(cfg):
+        stored = dict(cfg.get("model_adapter_options") or {})
+        stored[name] = plain
+        cfg.update(model_adapter=name, model_adapter_options=stored)
+    config.update_config(mutate)
+    for key, value in secrets.items():
+        config.set_provider_api_key(_secret_name(name, key), value)
+    forget_status()
+
+
+def remove_secret(name, field):
+    """Deletes one stored secret without testing the connection (a revoked key must be removable)."""
+    found, _errors = adapters()
+    module = found.get(name)
+    if module is None or not any(f["name"] == field and f.get("secret") for f in module.FIELDS):
+        raise ValueError(f"{name}/{field} is not a secret adapter field.")
+    config.set_provider_api_key(_secret_name(name, field), "")
+    forget_status()
+
+
+def forget_status():
+    with _lock:
+        _status.update(at=0.0, key=None, value=None)
+
+
+def status():
+    """{"status": "ready" | "not_configured" | "error", "adapter", "label", "error"}, checked every STATUS_TTL_S."""
+    try:
+        module, options = selected()
+    except Exception as exc:
+        return {"status": "error", "adapter": config.load_config().get("model_adapter"), "label": "",
+                "error": f"{type(exc).__name__}: {exc}"}
+    if module is None:
+        return {"status": "not_configured", "adapter": "", "label": "",
+                "error": "No model gateway configured."}
+    key = (module.NAME, tuple(sorted(options.items())))
+    with _lock:
+        if _status["key"] == key and time.monotonic() - _status["at"] < STATUS_TTL_S:
+            return dict(_status["value"])
+    try:
+        module.verify(options)
+        value = {"status": "ready", "adapter": module.NAME, "label": module.LABEL, "error": ""}
+    except Exception as exc:
+        value = {"status": "error", "adapter": module.NAME, "label": module.LABEL, "error": str(exc)}
+    with _lock:
+        _status.update(at=time.monotonic(), key=key, value=value)
+    return dict(value)
+
+
+def fingerprint():
+    """Changes whenever the adapter or its options change (cache key for the model catalog)."""
+    module, options = selected()
+    return (module.NAME if module else "", tuple(sorted(options.items())))
+
+
+def request(route, body=None, timeout=15):
+    module, options = selected()
+    if module is None:
+        raise RuntimeError("No model gateway configured: choose an adapter in the setup screen.")
+    return module.request(options, route, body=body, timeout=timeout)

package/hook_decision.py

@@ -0,0 +1,96 @@
+"""Decisão do PreToolUse do Smart Tool, tomada dentro do daemon já aquecido.
+
+O Claude Code chama a rota POST /hooks/pretool como hook `type: "http"` (sem processo por chamada); o Codex usa o
+hook de comando `hooks/pretool_router.py`, que só repassa o payload para a mesma rota.
+
+INVARIANTE: a saída só pode ser `{}` (neutra) ou `deny`. `permissionDecision: "allow"` pula a confirmação do usuário
+no Claude Code, e nenhuma decisão aqui é sobre periculosidade, só sobre custo de contexto. Diagnóstico vai em
+`systemMessage`, que não altera permissão.
+"""
+import json
+import os
+
+import config
+import endpoint_sync
+import router
+
+WEB_TOOLS = ("WebSearch", "WebFetch")
+SMART_TOOL_SERVER = "smart-tool"
+REASON_MAX_CHARS = 200
+
+
+def clean_reason(reason):
+    """The reason is free LLM text fed to the host model: one line, bounded (repository content reaches the router
+    prompt through tool_input)."""
+    text = " ".join(str(reason or "").split())
+    return text[:REASON_MAX_CHARS] or "call broad enough to be worth an indexed search"
+
+
+def deny(reason):
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny",
+                                   "permissionDecisionReason": reason}}
+
+
+def smart_tool_in_session(cwd):
+    """Claude Code loads MCP servers from ~/.claude.json (user and per project) and the project's .mcp.json."""
+    with open(endpoint_sync.claude_json(), encoding="utf-8") as stream:
+        data = json.load(stream)
+    key = os.path.normcase(os.path.normpath(cwd or ""))
+    project = next((value for path, value in (data.get("projects") or {}).items()
+                    if os.path.normcase(os.path.normpath(path)) == key), {})
+    if SMART_TOOL_SERVER in (project.get("disabledMcpServers") or []):
+        return False
+    if SMART_TOOL_SERVER in (data.get("mcpServers") or {}) or SMART_TOOL_SERVER in (project.get("mcpServers") or {}):
+        return True
+    try:
+        with open(os.path.join(cwd or "", ".mcp.json"), encoding="utf-8") as stream:
+            return SMART_TOOL_SERVER in (json.load(stream).get("mcpServers") or {})
+    except (OSError, ValueError):
+        return False
+
+
+def advise(reason):
+    """Same routing advice without blocking: the agent sees it next to the tool result and decides next time."""
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse",
+                                   "additionalContext": f"Smart Tool tip (the call was not blocked): {reason}"}}
+
+
+def decide(payload, client, web_route):
+    """Hook output for one PreToolUse payload, following config hook_mode (redirect | advise | off)."""
+    cfg = config.load_config()
+    mode = config.hook_mode(cfg)
+    if mode == "off" or not isinstance(payload, dict):
+        return {}
+    output = _route(payload, client, web_route, cfg)
+    reason = (output.get("hookSpecificOutput") or {}).get("permissionDecisionReason")
+    return advise(reason) if mode == "advise" and reason else output
+
+
+def _route(payload, client, web_route, cfg):
+    tool_name = payload.get("tool_name", "")
+    tool_input = payload.get("tool_input") if isinstance(payload.get("tool_input"), dict) else {}
+    cwd = payload.get("cwd")
+    router_model = cfg.get("router_model")
+    if not router_model:
+        return {}
+    if tool_name in WEB_TOOLS:
+        try:
+            present = smart_tool_in_session(cwd)
+        except (OSError, ValueError):
+            present = False
+        if not present:
+            return {}
+        decision = web_route(tool_name, str(tool_input.get("url") or ""))
+        return deny(clean_reason(decision.get("reason"))) if decision.get("redirect") else {}
+    router.CLIENT = client
+    try:
+        decision, reason = router.decide(tool_name, tool_input, router_model, cwd=cwd)
+    except Exception as exc:
+        try:
+            router.log_unavailable(tool_name, tool_input, exc)
+        except Exception:
+            pass
+        return {"systemMessage": f"Smart Tool unavailable, routing skipped: {type(exc).__name__}"}
+    if decision == "redirect":
+        return deny(f"Use smart_search instead of raw {tool_name}: {clean_reason(reason)}")
+    return {}

package/hooks/pretool_router.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Hook PreToolUse de comando (Codex): cliente fino que repassa o payload ao daemon do Smart Tool (POST
+/hooks/pretool), onde a decisão roda já aquecida (`hook_decision.py`). O Claude Code chama a mesma rota direto, como
+hook `type: "http"`. Falha aberto: daemon fora do ar ou erro = saída neutra `{}`, nunca `allow`.
+"""
+import json
+import os
+import sys
+import urllib.parse
+import urllib.request
+
+sys.stdin.reconfigure(encoding="utf-8")
+sys.stdout.reconfigure(encoding="utf-8")
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
+import daemon_launcher
+
+TIMEOUT_S = 14
+
+
+def _client():
+    args = sys.argv[1:]
+    return args[args.index("--client") + 1] if "--client" in args and args.index("--client") + 1 < len(args) else ""
+
+
+def main():
+    raw = sys.stdin.buffer.read()
+    base = daemon_launcher.daemon_url_if_up()
+    if not base:
+        daemon_launcher.start_daemon_if_down()
+        print(json.dumps({"systemMessage": "Smart Tool: daemon subindo, roteamento pulado nesta chamada."},
+                         ensure_ascii=False))
+        return
+    request = urllib.request.Request(f"{base}/hooks/pretool?{urllib.parse.urlencode({'client': _client()})}",
+                                     data=raw, headers={"Content-Type": "application/json"}, method="POST")
+    with urllib.request.urlopen(request, timeout=TIMEOUT_S) as response:
+        output = json.loads(response.read() or b"{}")
+    print(json.dumps(output if isinstance(output, dict) else {}, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except BaseException:
+        print("{}")

package/index_inventory.py

@@ -0,0 +1,75 @@
+"""Inventário somente leitura de visões, arquivos e trechos já persistidos."""
+import re
+from pathlib import Path
+
+import indexer
+import index_views
+import project_identity
+import document_text
+
+
+def views(root):
+    key = project_identity.project_id(root)
+    current = index_views.describe(root)
+    paths = list(Path(indexer.INDEX_DIR).glob(key + '.v-*.sqlite3'))
+    paths += [Path(indexer.INDEX_DIR)/(item+'.sqlite3') for item in
+              dict.fromkeys([key, *project_identity.legacy_ids(root)])]
+    rows = []
+    for path in dict.fromkeys(paths):
+        if not path.is_file() or not re.fullmatch(r'[a-f0-9]{16}(?:\.v-[a-f0-9]{16})?\.sqlite3', path.name):
+            continue
+        conn = indexer._readonly(str(path))
+        try:
+            meta = indexer._metadata(conn)
+            view_id = meta.get('view_id') or ('legacy' if current['git'] else 'workspace')
+            rows.append({'view_id': view_id, 'label': meta.get('view_label') or 'Legacy, no identified branch',
+                         'branch': meta.get('git_branch'), 'commit': meta.get('git_commit'),
+                         'current': view_id == current['view_id'], 'path': str(path),
+                         'files': conn.execute('SELECT count(*) FROM manifest').fetchone()[0],
+                         'chunks': conn.execute('SELECT count(*) FROM chunks').fetchone()[0],
+                         'model': meta.get('model_id'), 'dimensions': meta.get('dimensions'),
+                         'updated_at': meta.get('updated_at'), 'bytes': path.stat().st_size})
+        finally:
+            conn.close()
+    return sorted(rows, key=lambda row: (not row['current'], row['label']))
+
+
+def inspect(root, view_id=None, file_path=None, storage_id=None):
+    if file_path is not None:
+        if not isinstance(file_path, str):
+            raise ValueError("file_path must be a string.")
+        file_path = file_path.replace(chr(92), "/").removeprefix("./")
+    available = views(root)
+    current = index_views.describe(root)
+    explicit_view = view_id is not None or storage_id is not None
+    view_id = view_id or current['view_id']
+    selected = next((row for row in available if (Path(row['path']).name==storage_id if storage_id else row['view_id']==view_id)), None)
+    if selected is None and available and not explicit_view:
+        selected = available[0]
+    if not selected:
+        return {'views': available, 'selected': None, 'files': [], 'chunks': [],
+                'message': 'This view has not been indexed yet. Run a search or use Index now.'}
+    conn = indexer._readonly(selected['path'])
+    try:
+        columns = {row[1] for row in conn.execute('PRAGMA table_info(manifest)')}
+        # Índices anteriores ao manifest incremental não têm size/mtime_ns.
+        # A inspeção é somente leitura; não migrar nem medir o arquivo de outra branch.
+        size_column = 'm.size' if 'size' in columns else 'NULL'
+        files = [{'path': path, 'chunks': count, 'hash': digest, 'size': size} for path, count, digest, size in
+                 conn.execute(f'SELECT m.path,count(c.id),m.hash,{size_column} FROM manifest m LEFT JOIN chunks c ON c.path=m.path GROUP BY m.path ORDER BY m.path LIMIT 1001')]
+        chunks = []
+        if file_path is not None:
+            if not conn.execute('SELECT 1 FROM manifest WHERE path=?', (file_path,)).fetchone():
+                raise ValueError(f'File is outside the indexed view: {file_path}')
+            files = []
+            chunks = [{'start_line': start, 'end_line': end, 'text': text, 'dimensions': int(size or 0)//4,
+                       'location_kind':document_text.location_kind(file_path)}
+                      for start, end, text, size in conn.execute(
+                          'SELECT start_line,end_line,text,length(embedding) FROM chunks WHERE path=? ORDER BY start_line LIMIT 100', (file_path,))]
+        return {'views': available, 'selected': selected, 'files': files[:1000],
+                'truncated': len(files)>1000, 'chunks': chunks, 'max_chunks_displayed': 100,
+                'current_view': index_views.public(current),
+                'message': '' if selected['current'] else 'The current view is not shown. You are inspecting the stored index of ' + selected['label'] + '.',
+                'graph_type': 'project_branch_directory_file', 'read_only': True}
+    finally:
+        conn.close()

package/index_profile.py

@@ -0,0 +1,167 @@
+import collections
+import fnmatch
+import json
+import os
+import re
+import time
+
+import model_client
+
+PROFILE_VERSION = 2
+KINDS = ("code", "test", "doc")
+RETRY_AFTER_S = 3600
+MAX_DIRS = 90
+PROSE = {"md", "txt", "docx", "rst", "adoc"}
+# Data and markup inside a documentation folder are reports, not code (GitHub Linguist treats docs/ as documentation).
+DOC_DATA = {"html", "htm", "json", "csv", "xml", "yaml", "yml", "svg"}
+_NAME_DOC = re.compile(r"(^|/)(readme|changelog|license|licence|contributing|install|history|authors)(\.[^/]*)?$", re.I)
+_DIR_DOC = re.compile(r"(^|/)(docs?|adrs?|documentation)/", re.I)
+_TEST = re.compile(r"(^|/)(tests?|__tests__|spec|specs|e2e|fixtures?|testdata|test-utils?)(/|$)|(^|/)test_[^/]+\.py$|"
+                   r"(^|/)conftest\.py$|_test\.(py|go)$|\.(test|spec)\.[cm]?[jt]sx?$|(^|/)[^/]*[a-z0-9](?-i:Tests?)\.java$|"
+                   r"(^|/)src/test/|(^|/)test[-_][^/]*\.[cm]?[jt]sx?$|[-_]test\.[cm]?[jt]sx?$", re.I)
+_TEST_PROSE = re.compile(r"(^|/)(tests?|__tests__|e2e|fixtures?|testdata|test-utils?)(/|$)|(^|/)src/test/", re.I)
+_TEXT_LINE = re.compile(r"[A-Za-zÀ-ú]{3,}\s+[A-Za-zÀ-ú]{3,}")
+
+_TOOL = {"type": "function", "function": {
+    "name": "submit_profile", "description": "Submit the search-index profile.",
+    "parameters": {"type": "object", "required": ["groups", "languages"], "properties": {
+        "groups": {"type": "array", "items": {"type": "object", "required": ["path", "kind"], "properties": {
+            "path": {"type": "string", "description": "directory relative to root, '.' for root, or a glob like '**/NOTES.md'"},
+            "kind": {"type": "string", "enum": list(KINDS)}}}},
+        "languages": {"type": "object", "required": ["identifiers", "comments", "doc"], "properties": {
+            "identifiers": {"type": "array", "items": {"type": "string"},
+                            "description": "natural languages of identifier names (functions, classes, variables), most prevalent first (BCP-47)"},
+            "comments": {"type": "array", "items": {"type": "string"},
+                         "description": "natural languages of code comments and docstrings, most prevalent first (BCP-47)"},
+            "doc": {"type": "array", "items": {"type": "string"},
+                    "description": "natural languages of documentation, most prevalent first (BCP-47)"}}}}}}}
+
+_PROMPT = """You are profiling a repository for a code-search index at {root}.
+Classify where things live, by directory, not file by file. Three kinds:
+- code: anything the product runs or loads: source, templates, HTML pages, config, scripts, and prompt/instruction files that the product itself executes (e.g. agent/skill/command definitions of a plugin).
+- test: automated tests and their fixtures, mocks and helpers (unit, integration, e2e), even in folders with unusual names.
+- doc: material written for people: README, CHANGELOG, docs/, ADRs, plans, guides, notes.
+Use the most specific path needed: a directory, or a glob for files that break the rule of their directory. Paths not listed inherit from their closest listed parent.
+Also report the natural languages used, most prevalent first, separately for identifier names, for code comments and docstrings, and for docs. Identifiers are often English even when comments are not. Use the text samples as evidence.
+Directories (dir, file count, extensions, sample names, text sample):
+{rows}
+(total directories with indexed files: {total}; only the {shown} largest are shown)"""
+
+
+def _ext(path):
+    name = path.rsplit("/", 1)[-1]
+    return name.rsplit(".", 1)[-1].lower() if "." in name else ""
+
+
+def _sample(root, rel):
+    try:
+        with open(os.path.join(root, rel), "rb") as stream:
+            raw = stream.read(4000).decode("utf-8", "ignore")
+    except OSError:
+        return ""
+    return " | ".join(line.strip() for line in raw.splitlines() if _TEXT_LINE.search(line))[:260]
+
+
+def _evidence(root, included):
+    by_dir = collections.defaultdict(list)
+    for rel in included:
+        by_dir[rel.rsplit("/", 1)[0] if "/" in rel else "."].append(rel)
+    rows = []
+    for rel_dir, files in sorted(by_dir.items(), key=lambda item: -len(item[1]))[:MAX_DIRS]:
+        names = [path.rsplit("/", 1)[-1] for path in files]
+        text = next((path for path in files if _ext(path) in PROSE | {"py", "js", "ts", "java", "html", "mjs", "cjs"}), None)
+        rows.append({"dir": rel_dir, "files": len(files),
+                     "ext": dict(collections.Counter(_ext(path) or "(none)" for path in files).most_common(6)),
+                     "sample": names[:5], "text_sample": _sample(root, text) if text else ""})
+    return rows, len(by_dir)
+
+
+def _valid(args):
+    groups, languages = args.get("groups"), args.get("languages")
+    return (isinstance(groups, list) and all(isinstance(g, dict) and isinstance(g.get("path"), str)
+                                             and g.get("kind") in KINDS for g in groups)
+            and isinstance(languages, dict) and all(isinstance(languages.get(key), list) and
+                                                    all(isinstance(item, str) for item in languages[key])
+                                                    for key in ("identifiers", "comments", "doc")))
+
+
+def decide(root, included, model, deadline=None):
+    rows, total = _evidence(root, included)
+    remaining = deadline - time.monotonic() if deadline is not None else 120
+    if remaining <= 0:
+        raise TimeoutError("Profile analysis deadline exceeded.")
+    response = model_client.fetch("/v1/chat/completions", model_client.get_token(), method="POST",
+                                  timeout=min(120, remaining), body={
+        "model": model, "temperature": 0, "tools": [_TOOL], "tool_choice": "required",
+        "messages": [{"role": "user", "content": _PROMPT.format(
+            root=root, rows=json.dumps(rows, ensure_ascii=False), total=total, shown=len(rows))}]})
+    calls = response["choices"][0]["message"].get("tool_calls") or []
+    try:
+        args = next((json.loads(call["function"]["arguments"] or "{}") for call in calls
+                     if call["function"]["name"] == "submit_profile"), None)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"The model returned a profile with invalid JSON: {exc}") from exc
+    if not isinstance(args, dict) or not _valid(args):
+        raise RuntimeError("The model did not define a valid profile of groups and languages.")
+    return {"version": PROFILE_VERSION, "groups": args["groups"], "languages": args["languages"],
+            "model": model, "decided_at": time.time()}
+
+
+def _explicit_kind(path, groups):
+    """Kind of the most specific profile group that names this path; None when only the root group covers it."""
+    covering = [group for group in groups if _covers(path, group)]
+    return _model_kind(path, covering) if covering else None
+
+
+def _covers(path, group):
+    pattern = group["path"].replace(chr(92), "/").removeprefix("./").strip("/") or "."
+    if pattern == ".":
+        return False
+    if any(char in pattern for char in "*?["):
+        return fnmatch.fnmatch(path, pattern) or fnmatch.fnmatch(path, pattern.replace("**/", ""))
+    return path.startswith(pattern + "/")
+
+
+def _model_kind(path, groups):
+    best = None
+    for group in groups:
+        pattern = group["path"].replace(chr(92), "/").removeprefix("./").strip("/") or "."
+        if any(char in pattern for char in "*?["):
+            if fnmatch.fnmatch(path, pattern) or fnmatch.fnmatch(path, pattern.replace("**/", "")):
+                return group["kind"]
+        elif pattern == "." or path.startswith(pattern + "/"):
+            depth = 0 if pattern == "." else len(pattern)
+            if best is None or depth > best[0]:
+                best = (depth, group["kind"])
+    return best[1] if best else "doc"
+
+
+def current(profile):
+    return profile if (profile or {}).get("version") == PROFILE_VERSION else None
+
+
+def kind(path, profile):
+    groups = (current(profile) or {}).get("groups") or []
+    ext = _ext(path)
+    if ext in PROSE:
+        if _NAME_DOC.search(path) or _DIR_DOC.search(path):
+            return "doc"
+        if _TEST_PROSE.search(path):
+            return "test"
+        return _model_kind(path, groups or [{"path": ".", "kind": "doc"}])
+    if _TEST.search(path):
+        return "test"
+    if ext in DOC_DATA and _DIR_DOC.search(path) and _explicit_kind(path, groups) != "code":
+        return "doc"
+    if not ext and _NAME_DOC.search(path):
+        return "doc"
+    return "test" if groups and _model_kind(path, groups) == "test" else "code"
+
+
+def public(profile):
+    profile = current(profile)
+    if not profile:
+        return {"source": "rules", "identifier_languages": [], "comment_languages": [], "doc_languages": []}
+    languages = profile["languages"]
+    return {"source": "model", "identifier_languages": languages["identifiers"],
+            "comment_languages": languages["comments"], "doc_languages": languages["doc"]}