pyacri 0.4.0__py3-none-any.whl

acri/__init__.py

@@ -0,0 +1,73 @@
+"""acri — a client-side capability resolver. `import acri` is the whole product.
+
+`run()` is the one function that touches every module: corpus's index,
+compass's ranking, port's provider call, and ledger's trace. Integration
+tests call this, not a hand-wired re-implementation of the pipeline.
+
+Named `__init__.py`, not `kernel.py`: docs/architecture.md #5 retired
+kernel/runtime/OS vocabulary for this project on purpose. The entry point
+doesn't get to bring it back through the filename.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from .adapters import from_callables, from_mcp_tools
+from .compass import Resolved
+from .compass import resolve as _compass_resolve
+from .corpus import Corpus, Tool, index
+from .escape_hatch import FIND_MORE_TOOLS, find_more_tools
+from .ledger import Entry, Ledger
+from .port import GenerationResult, cached_call, gemini, openai_compatible
+from .router import route
+
+__all__ = [
+    "Tool", "Corpus", "index", "from_callables", "from_mcp_tools",
+    "Resolved", "resolve",
+    "FIND_MORE_TOOLS", "find_more_tools",
+    "GenerationResult", "gemini", "openai_compatible",
+    "Entry", "Ledger",
+    "run",
+]
+
+_PROVIDERS = {"openai": openai_compatible, "gemini": gemini}
+
+
+def resolve(query: str, corpus: Corpus, k: int = 5) -> list[Resolved]:
+    """Rank `corpus` against `query`, return the top k. See compass.resolve for the algorithm."""
+    return _compass_resolve(query, corpus, k)
+
+
+def run(
+    query: str,
+    corpus: Corpus,
+    client: Any,
+    provider: str = "openai",
+    *,
+    k: int = 5,
+    model: str | None = None,
+    cheap_model: str | None = None,
+    ledger: Ledger | None = None,
+    cache: dict[Any, GenerationResult] | None = None,
+) -> GenerationResult:
+    """Resolve tools for `query`, call `provider` with them, log the trace if a ledger is given.
+
+    `cache` (a dict) skips a repeated (provider, model, query, offered tools) call -- see
+    port.cached_call, decisions.md #8c. `cheap_model` routes this one call to a cheaper
+    tier -- see router.route, decisions.md #1.
+    """
+    call = _PROVIDERS.get(provider)
+    if call is None:
+        raise ValueError(f"unknown provider: {provider!r} (expected one of {sorted(_PROVIDERS)})")
+    model = route(model, cheap_model)
+    start = time.time()
+    resolved = _compass_resolve(query, corpus, k)
+    offered = [*resolved, Resolved(tool=FIND_MORE_TOOLS, score=0.0)]
+    key = (provider, model, query, tuple(r.tool.name for r in resolved))
+    kwargs = {"model": model} if model else {}
+    result = cached_call(call, cache, key, client, query, offered, **kwargs)
+    if ledger is not None:
+        selected = [c["name"] for c in result.tool_calls]
+        ledger.record(query, resolved, selected, (time.time() - start) * 1000, corpus_size=len(corpus))
+    return result

acri/_synonyms.py

@@ -0,0 +1,31 @@
+"""_synonyms — query-side alias expansion for compass. Not corpus-facing.
+
+Words a user types that never literally appear in any tool description --
+BM25 has no stemming or semantic understanding, so "rain" and "weather" are
+unrelated tokens to it otherwise. Applied to the query only, never the
+corpus: expanding doc text here would let a tool's description quietly
+start matching queries for a synonym it never claimed, and would shift
+df/idf for every other tool too. Every entry traces to a real recall@5
+miss, not a guess -- see assay/diagnose.py.
+"""
+from __future__ import annotations
+
+ALIASES: dict[str, tuple[str, ...]] = {
+    "pr": ("pull", "request"),
+    "meeting": ("event",),
+    "rain": ("weather",),
+    "raining": ("weather",),
+    "storm": ("weather",),
+    "warning": ("alerts",),
+    "warnings": ("alerts",),
+    "text": ("sms", "message"),
+    "sharpen": ("upscale", "resolution"),
+    "money": ("refund", "charge"),
+}
+
+
+def expand(tokens: list[str]) -> list[str]:
+    expanded = list(tokens)
+    for tok in tokens:
+        expanded.extend(ALIASES.get(tok, ()))
+    return expanded

acri/_template.py

@@ -0,0 +1,27 @@
+"""_template — the acri init scaffold. Split out of cli.py (word-cap): this
+is static content, not CLI parsing/dispatch logic.
+"""
+from __future__ import annotations
+
+TEMPLATE = """\
+version: 1
+
+models:
+  default: gemini-2.5-flash
+  # cheap: a stateless, prefix-free tier only -- classification, extraction,
+  # summarizing a tool result. See docs/architecture.md #4.4. Optional.
+  # cheap: gemini-2.5-flash-lite
+
+mcp:
+  # - name: github
+  #   command: ["npx", "-y", "@modelcontextprotocol/server-github"]
+  # - name: postgres
+  #   url: http://localhost:3001
+
+resolve:
+  k: 5
+
+limits:
+  timeout_ms: 5000
+  max_cost_per_task_usd: 0.05
+"""

acri/_text.py

@@ -0,0 +1,34 @@
+"""_text — tokenization shared by corpus (indexing) and compass (scoring).
+
+Internal to the package: both sides must tokenize identically or BM25 scores
+against a corpus the query was never consistently split against.
+"""
+from __future__ import annotations
+
+import re
+
+_TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+# Standard English function words (the NLTK stoplist's non-contraction
+# core), filtered before scoring. Started as a smaller ad-hoc set; expanded
+# to this external, non-cherry-picked list after "into" — missing from the
+# original set — tied github_merge_pull_request with translate/salesforce
+# tools that happened to also contain "into". A hand-patched one-word-at-a-
+# time list invites tuning to whichever queries you happen to be looking at;
+# a standard external stoplist doesn't. See assay/diagnose.py.
+_STOPWORDS = frozenset("""
+    a an the is are was were be been being am of in on at to for with and or
+    but this that these those what which who whom me my you your it its we
+    they do does did into from by about up down out off over under again
+    further then once here there when where why how all any both each few
+    more most other some such no nor not only own same so than too very s t
+    can will just now if because as until while against between during
+    before after above below
+""".split())
+
+
+def tokenize(text: str) -> list[str]:
+    # Strip apostrophes before splitting: "user's" -> "users" as one token,
+    # not "user" + a stray "s" that then matches every other possessive.
+    text = text.lower().replace("'", "").replace("’", "")
+    return [t for t in _TOKEN_RE.findall(text) if t not in _STOPWORDS]

acri/adapters.py

@@ -0,0 +1,50 @@
+"""adapters — turn external tool descriptions into `corpus.Tool`."""
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable
+
+from .corpus import Tool
+
+_TYPE_MAP = {str: "string", int: "integer", float: "number", bool: "boolean"}
+
+
+def from_mcp_tools(mcp_tools: list[dict[str, Any]]) -> list[Tool]:
+    """Adapt an MCP `tools/list` response into Tools. Feed the result to `index()`."""
+    return [
+        Tool(
+            name=t["name"],
+            description=t.get("description", ""),
+            parameters=t.get("inputSchema", {"type": "object", "properties": {}}),
+        )
+        for t in mcp_tools
+    ]
+
+
+def _schema_from_callable(f: Callable[..., Any]) -> dict[str, Any]:
+    sig = inspect.signature(f)
+    props: dict[str, Any] = {}
+    required: list[str] = []
+    for name, param in sig.parameters.items():
+        if param.kind in (param.VAR_POSITIONAL, param.VAR_KEYWORD):
+            continue
+        props[name] = {"type": _TYPE_MAP.get(param.annotation, "string")}
+        if param.default is inspect.Parameter.empty:
+            required.append(name)
+    schema: dict[str, Any] = {"type": "object", "properties": props}
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def from_callables(funcs: list[Callable[..., Any]]) -> list[Tool]:
+    """Adapt plain Python functions into Tools, deriving each schema from its signature."""
+    return [
+        Tool(
+            name=f.__name__,
+            description=(f.__doc__ or "").strip(),
+            parameters=_schema_from_callable(f),
+            handler=f,
+        )
+        for f in funcs
+    ]

acri/cli.py

@@ -0,0 +1,97 @@
+"""cli — `acri init` writes a template acri.yaml; `acri check` validates one;
+`acri up` runs the daemon; `acri studio` runs the read-only dashboard. Both
+ship ahead of decisions.md's own gates, at the maintainer's request -- see
+acri/server.py and acri/studio.py for specifics.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ._template import TEMPLATE
+
+
+def _init(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    if path.exists():
+        print(f"{path} already exists -- not overwriting.", file=sys.stderr)
+        return 1
+    path.write_text(TEMPLATE, encoding="utf-8")
+    print(f"wrote {path}")
+    return 0
+
+
+def _check(args: argparse.Namespace) -> int:
+    try:
+        from .config import from_yaml  # lazy: needs pyacri[yaml]
+        from .credentials import missing_env_vars
+    except ImportError:
+        print("acri check needs PyYAML -- pip install pyacri[yaml]", file=sys.stderr)
+        return 1
+    path = Path(args.path)
+    if not path.exists():
+        print(f"{path} not found -- run `acri init` first.", file=sys.stderr)
+        return 1
+    missing = missing_env_vars(from_yaml(path))
+    if missing:
+        print("missing credentials:")
+        for var in missing:
+            print(f"  {var}")
+        return 1
+    print(f"ok - {path} is valid, all credentials present")
+    return 0
+
+
+def _up(args: argparse.Namespace) -> int:
+    try:
+        from .server import serve  # lazy: needs pyacri[server]
+    except ImportError:
+        print("acri up needs mcp and PyYAML -- pip install pyacri[server]", file=sys.stderr)
+        return 1
+    serve(args.path, host=args.host, port=args.port, log_conversations=args.log_conversations)
+    return 0
+
+
+def _studio(args: argparse.Namespace) -> int:
+    try:
+        from .studio import serve_studio  # lazy: needs pyacri[yaml]
+    except ImportError:
+        print("acri studio needs PyYAML -- pip install pyacri[studio]", file=sys.stderr)
+        return 1
+    serve_studio(args.path, ledger_path=args.ledger, host=args.host, port=args.port)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="acri")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser("init", help="write a template acri.yaml")
+    p_init.add_argument("path", nargs="?", default="acri.yaml")
+    p_init.set_defaults(func=_init)
+
+    p_check = sub.add_parser("check", help="validate acri.yaml and its credentials")
+    p_check.add_argument("path", nargs="?", default="acri.yaml")
+    p_check.set_defaults(func=_check)
+
+    p_up = sub.add_parser("up", help="run the daemon: an OpenAI-compatible endpoint over acri.yaml's tools")
+    p_up.add_argument("path", nargs="?", default="acri.yaml")
+    p_up.add_argument("--host", default="127.0.0.1")
+    p_up.add_argument("--port", type=int, default=8080)
+    p_up.add_argument("--log-conversations", action="store_true")
+    p_up.set_defaults(func=_up)
+
+    p_studio = sub.add_parser("studio", help="run the read-only dashboard over acri.yaml and the ledger")
+    p_studio.add_argument("path", nargs="?", default="acri.yaml")
+    p_studio.add_argument("--ledger", default=".acri/ledger.jsonl")
+    p_studio.add_argument("--host", default="127.0.0.1")
+    p_studio.add_argument("--port", type=int, default=8099)
+    p_studio.set_defaults(func=_studio)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

acri/compass.py

@@ -0,0 +1,70 @@
+"""compass — the resolver. Given a query, returns the k tools that matter.
+
+This is the product. It performs no language understanding — BM25 scores
+query terms against tool text, weighting terms that are rare in the corpus.
+That's deliberate: understanding is the model's job and costs a model call.
+compass only does recall (narrow N tools to k candidates); the model still
+does precision (pick one, write its arguments). See docs/decisions.md.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from ._synonyms import expand as _expand
+from ._text import tokenize as _tokenize
+from .corpus import Corpus, Tool
+
+_K1 = 1.5
+_B = 0.75
+
+
+@dataclass(frozen=True)
+class Resolved:
+    """One ranked tool and acri's confidence in it.
+
+    `score` is relative to the best match for this query (1.0 = best), not a
+    calibrated probability — a 0.9 does not mean "90% sure".
+    """
+
+    tool: Tool
+    score: float
+
+
+def _idf(df: int, n_docs: int) -> float:
+    return math.log(1 + (n_docs - df + 0.5) / (df + 0.5))
+
+
+def bm25(query_tokens: list[str], corpus: Corpus, doc_idx: int) -> float:
+    doc_len = len(corpus.doc_tokens[doc_idx])
+    freqs = corpus.doc_freqs[doc_idx]
+    n_docs = len(corpus.tools)
+    score = 0.0
+    for tok in query_tokens:
+        f = freqs.get(tok)
+        if not f:
+            continue
+        idf = _idf(corpus.df.get(tok, 0), n_docs)
+        denom = f + _K1 * (1 - _B + _B * doc_len / corpus.avgdl)
+        score += idf * (f * (_K1 + 1)) / denom
+    return score
+
+
+def resolve(query: str, corpus: Corpus, k: int = 5) -> list[Resolved]:
+    """Rank every tool in `corpus` against `query`, return the top k.
+
+    Tools that score zero (no shared term with the query) are dropped rather
+    than padded in — an empty result means "nothing in this corpus matches",
+    which the caller should handle via `port`'s no-tools path, not treat as
+    an error.
+    """
+    if len(corpus) == 0:
+        return []
+    query_tokens = _expand(_tokenize(query))
+    raw = [bm25(query_tokens, corpus, i) for i in range(len(corpus))]
+    top = max(raw, default=0.0)
+    if top <= 0.0:
+        return []
+    scored = [Resolved(tool=corpus.tools[i], score=raw[i] / top) for i in range(len(corpus)) if raw[i] > 0.0]
+    scored.sort(key=lambda r: r.score, reverse=True)
+    return scored[:k]

acri/config.py

@@ -0,0 +1,87 @@
+"""config — parses acri.yaml. docs/decisions.md: "declarative configuration".
+
+Declares capabilities and limits, never control flow -- no steps/on_error/
+conditionals, on purpose (see decisions.md). Requires PyYAML: `pip install
+pyacri[yaml]`. Not imported from acri/__init__.py, so `import acri` alone never
+needs it -- the core library stays dependency-free.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_SUPPORTED_VERSION = 1
+
+
+@dataclass(frozen=True)
+class ModelsConfig:
+    default: str | None = None
+    cheap: str | None = None
+
+
+@dataclass(frozen=True)
+class SandboxConfig:  # v1.1 resource/network/volume limits -- see acri.sandbox.sandboxed()
+    image: str
+    memory: str = "256m"
+    cpus: float = 0.5
+    network: bool = True
+    volumes: dict[str, str] | None = None  # host path -> container path
+
+
+@dataclass(frozen=True)
+class McpEntry:
+    name: str
+    command: list[str] | None = None
+    url: str | None = None
+    sandbox: SandboxConfig | None = None  # command: entries only -- see _mcp_entry
+
+
+@dataclass(frozen=True)
+class Limits:
+    timeout_ms: int | None = None
+    max_cost_per_task_usd: float | None = None
+
+
+@dataclass(frozen=True)
+class Config:
+    """Parsed acri.yaml. `k` and `limits` mirror acri.run()'s own parameters --
+    limits aren't enforced yet (that's v1.0's held-back remainder)."""
+
+    version: int
+    models: ModelsConfig = field(default_factory=ModelsConfig)
+    mcp: list[McpEntry] = field(default_factory=list)
+    k: int = 5
+    limits: Limits = field(default_factory=Limits)
+
+
+def _mcp_entry(raw: dict[str, Any]) -> McpEntry:
+    command, url = raw.get("command"), raw.get("url")
+    if bool(command) == bool(url):
+        raise ValueError(f"mcp entry {raw.get('name')!r} needs exactly one of command or url")
+    sandbox = raw.get("sandbox")
+    if sandbox and not command:
+        raise ValueError(f"mcp entry {raw.get('name')!r}: sandbox needs command, not url")
+    return McpEntry(name=raw["name"], command=command, url=url,
+                     sandbox=SandboxConfig(**sandbox) if sandbox else None)
+
+
+def from_yaml(path: str | Path) -> Config:
+    """Load and validate an acri.yaml. Raises ValueError on an unsupported
+    version or a malformed mcp entry; yaml.YAMLError on invalid YAML."""
+    data = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
+    version = data.get("version")
+    if version != _SUPPORTED_VERSION:
+        raise ValueError(f"unsupported acri.yaml version: {version!r} (expected {_SUPPORTED_VERSION})")
+    models = data.get("models") or {}
+    resolve = data.get("resolve") or {}
+    limits = data.get("limits") or {}
+    return Config(
+        version=version,
+        models=ModelsConfig(default=models.get("default"), cheap=models.get("cheap")),
+        mcp=[_mcp_entry(m) for m in data.get("mcp") or []],
+        k=resolve.get("k", 5),
+        limits=Limits(timeout_ms=limits.get("timeout_ms"), max_cost_per_task_usd=limits.get("max_cost_per_task_usd")),
+    )

acri/corpus.py

@@ -0,0 +1,57 @@
+"""corpus — the capability index. Ingests tools into one searchable body, once."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from ._text import tokenize as _tokenize
+
+
+@dataclass(frozen=True)
+class Tool:
+    """One capability: a name, a description, a JSON Schema, and how to reach it.
+
+    `handler` is optional — resolution never calls it. It's a place for the
+    caller (or a future dispatcher) to find the actual function.
+    """
+
+    name: str
+    description: str
+    parameters: dict[str, Any] = field(default_factory=lambda: {"type": "object", "properties": {}})
+    handler: Callable[..., Any] | None = None
+
+
+@dataclass
+class Corpus:
+    """A built capability index. Construct with `index()`, not directly.
+
+    The four fields below are the prebuilt BM25 index that `compass.resolve`
+    reads — treat this as an opaque handle unless you're changing the ranking.
+    """
+
+    tools: list[Tool]
+    doc_tokens: list[list[str]]
+    doc_freqs: list[dict[str, int]]
+    df: dict[str, int]
+    avgdl: float
+
+    def __len__(self) -> int:
+        return len(self.tools)
+
+
+def index(tools: list[Tool]) -> Corpus:
+    """Build a searchable Corpus once. Reuse it across turns — never rebuild per query."""
+    if not tools:
+        raise ValueError("index() needs at least one tool")
+    doc_tokens = [_tokenize(f"{t.name} {t.description}") for t in tools]
+    doc_freqs: list[dict[str, int]] = []
+    df: dict[str, int] = {}
+    for tokens in doc_tokens:
+        freqs: dict[str, int] = {}
+        for tok in tokens:
+            freqs[tok] = freqs.get(tok, 0) + 1
+        doc_freqs.append(freqs)
+        for tok in freqs:
+            df[tok] = df.get(tok, 0) + 1
+    avgdl = sum(len(t) for t in doc_tokens) / len(doc_tokens)
+    return Corpus(tools=list(tools), doc_tokens=doc_tokens, doc_freqs=doc_freqs, df=df, avgdl=avgdl)

acri/credentials.py

@@ -0,0 +1,25 @@
+"""credentials — which env vars a Config's models need, and which are missing.
+
+Split out of config.py: parsing acri.yaml and checking credentials are
+different concerns that happen to both feed `acri check`.
+"""
+from __future__ import annotations
+
+import os
+
+from .config import Config
+
+_ENV_VARS = {"gemini": "GEMINI_API_KEY", "openai": "OPENAI_API_KEY"}
+
+
+def provider_for(model: str) -> str:
+    return "gemini" if "gemini" in model.lower() else "openai"
+
+
+def missing_env_vars(config: Config) -> list[str]:
+    """Standard env vars (GEMINI_API_KEY, OPENAI_API_KEY) any configured model needs,
+    that aren't set. Inferred from the model name, not a `provider:` field -- the
+    documented acri.yaml example doesn't have one."""
+    models = [m for m in (config.models.default, config.models.cheap) if m]
+    needed = {_ENV_VARS[provider_for(m)] for m in models}
+    return sorted(v for v in needed if not os.environ.get(v))

acri/daemon.py

@@ -0,0 +1,75 @@
+"""daemon — the request handler `acri up` will eventually serve over HTTP.
+
+No socket here, on purpose: this is the thin OpenAI-shaped layer over
+acri.run(), kept separately testable so "the daemon is a thin wrapper over
+the library, never a superset" (docs/decisions.md) is a test, not just a
+sentence. Wiring this into a real listening process is v1.0's gated part.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import run
+from .corpus import Corpus
+from .ledger import Ledger
+from .port import GenerationResult
+
+DEFAULT_LEDGER_PATH = Path(".acri/ledger.jsonl")
+
+
+def default_ledger(path: Path | str = DEFAULT_LEDGER_PATH) -> Ledger:
+    """A Ledger backed by `.acri/ledger.jsonl` (docs/decisions.md), creating the
+    directory if it doesn't exist yet."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return Ledger(path)
+
+
+class RedactingLedger:
+    """Wraps a real Ledger, dropping the query text before it's recorded.
+
+    docs/decisions.md: "ledger records decisions, scores, and token counts.
+    Conversation content is opt-in." -- `acri up`'s default. Duck-typed to
+    Ledger.record's signature, nothing else; `run()` never checks the type.
+    """
+
+    def __init__(self, ledger: Ledger) -> None:
+        self._ledger = ledger
+
+    def record(self, query: str, offered: Any, selected: list[str], latency_ms: float, cost_usd: float | None = None) -> Any:
+        return self._ledger.record("<redacted>", offered, selected, latency_ms, cost_usd)
+
+
+def handle_chat_completion(
+    request: dict[str, Any],
+    corpus: Corpus,
+    client: Any,
+    provider: str = "openai",
+    *,
+    k: int = 5,
+    cheap_model: str | None = None,
+    ledger: Ledger | None = None,
+    cache: dict[Any, GenerationResult] | None = None,
+) -> dict[str, Any]:
+    """Handle one OpenAI-shaped `/v1/chat/completions` request via acri.run() --
+    not a reimplementation of resolve+call.
+
+    Single-turn only: the last message's content is the query. `acri/server.py`
+    wraps this in SSE at the wire level; multi-turn history and true upstream
+    streaming (vs. one blocking call chunked out) are still open.
+    """
+    messages = request.get("messages") or []
+    query = messages[-1]["content"] if messages else ""
+    result = run(
+        query, corpus, client, provider,
+        k=k, model=request.get("model"), cheap_model=cheap_model,
+        ledger=ledger, cache=cache,
+    )
+    message: dict[str, Any] = {"role": "assistant", "content": result.text}
+    if result.tool_calls:
+        message["tool_calls"] = [
+            {"id": f"call_{i}", "type": "function", "function": tc}
+            for i, tc in enumerate(result.tool_calls)
+        ]
+    return {"choices": [{"message": message}]}

acri/escape_hatch.py

@@ -0,0 +1,38 @@
+"""escape_hatch — find_more_tools, the recovery path architecture.md #4.1 names.
+
+`compass.resolve()` picks k tools once per task and that resolution is never
+rewritten (see compass.py, decisions.md #4.1: rewriting a sent prefix costs
+more than doing nothing). But a bad initial resolution still has to be
+recoverable, so `compass` "always includes a find_more_tools capability" --
+this is that capability, kept out of compass.py so resolve()'s own contract
+(pure ranking, nothing appended) stays untouched and every recall@k number
+in assay/ stays valid.
+
+`acri.run()` appends FIND_MORE_TOOLS to what's actually sent to the provider,
+not to the ledger's `offered` -- the ledger records what compass resolved,
+not the constant scaffolding wrapped around it. Calling it re-searches the
+full corpus; acri never auto-executes it, same as any other Tool.handler.
+"""
+from __future__ import annotations
+
+from .compass import resolve
+from .corpus import Corpus, Tool
+
+FIND_MORE_TOOLS = Tool(
+    name="find_more_tools",
+    description="Search for tools beyond the ones already offered, when none of them fit this task.",
+    parameters={
+        "type": "object",
+        "properties": {"query": {"type": "string", "description": "what capability you need"}},
+        "required": ["query"],
+    },
+)
+
+
+def find_more_tools(query: str, corpus: Corpus, exclude: list[str] | None = None, k: int = 5) -> list[dict[str, str]]:
+    """Re-run resolution against the full corpus, skipping names already offered.
+    The caller executes this when the model calls `find_more_tools` and appends
+    the result as a normal tool result -- an append, never a rewrite."""
+    exclude = set(exclude or ())
+    found = resolve(query, corpus, k=k + len(exclude))
+    return [{"name": r.tool.name, "description": r.tool.description} for r in found if r.tool.name not in exclude][:k]