pal-code 0.1.0__py3-none-any.whl

pal/tokens.py

@@ -0,0 +1,21 @@
+"""Token counting. The default is a local estimate: it costs nothing and never touches the
+network. `provider_counter` asks the model's own tokenizer endpoint, which is exact but adds a
+network round trip per call, so it is opt-in (settings.token_counter = "provider")."""
+from __future__ import annotations
+
+from collections.abc import Callable
+
+
+def estimate_tokens(text: str) -> int:
+    """~4 characters per token, at least 1 for non-empty text."""
+    return max(1, len(text) // 4) if text else 0
+
+
+def estimate_messages(messages: list[dict]) -> int:
+    return sum(estimate_tokens(str(m.get("content", ""))) + 4 for m in messages)
+
+
+def make_counter(mode: str, core=None) -> Callable[[str], int]:
+    if mode == "provider" and core is not None:
+        return core.token_count
+    return estimate_tokens

pal/tool_catalog.py

@@ -0,0 +1,107 @@
+"""Every tool in Pal, by its human name: the single list the docs and `pal tools` are built from.
+
+A test compares this catalogue with what is really registered (the chat's tool box, the SDK, the optional OS tools), so it cannot
+drift: a tool that is added without an entry here, or listed here without existing, fails the tests.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ToolEntry:
+    name: str          # what the model and the Tool Manager call it
+    title: str         # its human name, like "File Read Tool"
+    group: str
+    summary: str
+    where: str         # who can use it, and what switches it on
+
+
+FILES = "Files and directories"
+DOCS = "Your documents (PDF, Word, text ...)"
+CODE = "Your code project (graphify)"
+CALC = "Calculation and text"
+LOOKUP = "Search and lookup"
+MEDIA = "Images and audio"
+SYSTEM = "System"
+
+_SVC = "chat, off until named in tools.services"
+_NET = "chat, off until tools.network is on"
+_DOC = "chat, offered when a document is attached"
+_PRJ = "chat, offered when a project is loaded"
+_OS = "SDK agents, opt-in (register_os_tools)"
+
+CATALOG: tuple[ToolEntry, ...] = (
+    ToolEntry("read_file", "File Read Tool", FILES, "Read a text file in the agent's workspace.", _OS),
+    ToolEntry("write_file", "File Writer Tool", FILES, "Write text to a workspace file (an overwrite asks first).", _OS),
+    ToolEntry("list_files", "Directory Read Tool", FILES, "List the files in the workspace.", _OS),
+    ToolEntry("save_file", "File Save Tool", FILES, "Save a new file to the workspace for download.", "chat, agents that list it"),
+    ToolEntry("file_to_markdown", "File to Markdown Converter Tool", FILES,
+              "Convert a PDF, Word, PowerPoint, Excel, EPUB, HTML or LaTeX file to markdown and save it.",
+              "chat, when a convertible file is in the workspace; SDK agents (opt-in)"),
+    ToolEntry("search_documents", "Document Search Tool", DOCS, "Find the parts of your attached documents that match a query.", _DOC),
+    ToolEntry("read_document", "Document Reader Tool", DOCS, "Read one part of an attached document.", _DOC),
+    ToolEntry("document_outline", "Document Outline Tool", DOCS, "List a document's parts with headings and sizes.", _DOC),
+    ToolEntry("build_code_graph", "Code Graph Builder Tool", CODE, "Index a source zip, or a folder of code, as a graph (graphify).",
+              "chat, when a zip or code is in the workspace"),
+    ToolEntry("query_code_graph", "Code Graph Query Tool", CODE, "Ask the code graph: matching nodes and source excerpts.", _PRJ),
+    ToolEntry("read_source", "Source Reader Tool", CODE, "Read lines of a source file in the project.", _PRJ),
+    ToolEntry("find_usages", "Usage Finder Tool", CODE, "Where a function or class is defined and used.", _PRJ),
+    ToolEntry("search_source", "Source Search Tool", CODE, "Find lines containing some text.", _PRJ),
+    ToolEntry("list_project_files", "Project File List Tool", CODE, "List the project's source files.", _PRJ),
+    ToolEntry("calculator", "Calculator Tool", CALC, "Exact arithmetic.", "chat, SDK"),
+    ToolEntry("current_time", "Clock Tool", CALC, "The current date and time.", "chat, SDK"),
+    ToolEntry("word_count", "Word Count Tool", CALC, "Count the words in a text.", "SDK"),
+    ToolEntry("count_tokens", "Token Counter Tool", CALC, "Estimate the tokens in a text (characters divided by 4).", "chat"),
+    ToolEntry("estimate_cost", "Cost Estimator Tool", CALC, "Dollars for some tokens at the model's price (LiteLLM's table).", "chat"),
+    ToolEntry("summarize_text", "Text Summarizer Tool", CALC, "A short summary of a text, by the local model.", "chat"),
+    ToolEntry("wolfram_alpha", "Wolfram|Alpha Tool", CALC, "Computed answers: maths, units, science, facts.", _SVC),
+    ToolEntry("currency_convert", "Currency Converter Tool", CALC, "Convert money at central bank reference rates.", _SVC),
+    ToolEntry("moon_phase", "Moon Phase Tool", CALC, "The moon's phase for a date, computed locally.", _SVC),
+    ToolEntry("words_api", "Words API Tool", CALC, "Definitions, synonyms, antonyms, rhymes, examples.", _SVC),
+    ToolEntry("google_search", "Google Search Tool", LOOKUP, "Google results for a query (through SerpApi).", _SVC),
+    ToolEntry("wikipedia", "Wikipedia Tool", LOOKUP, "The summary of a Wikipedia article.", _NET),
+    ToolEntry("arxiv_search", "arXiv Search Tool", LOOKUP, "Research papers on arXiv.", _NET),
+    ToolEntry("http_get", "HTTP GET Tool", LOOKUP, "Fetch a URL through the guarded network interface.", _OS),
+    ToolEntry("image_caption", "Image Caption Tool", MEDIA, "Describe an uploaded image.", _SVC + ", needs an uploaded image"),
+    ToolEntry("visual_question_answering", "Visual Question Answering Tool", MEDIA, "Answer a question about an uploaded image.",
+              _SVC + ", needs an uploaded image"),
+    ToolEntry("text_to_image", "Text-to-Image Tool", MEDIA, "Make an image from a description.", _SVC),
+    ToolEntry("text_to_audio", "Text-to-Audio Tool", MEDIA, "Turn text into spoken audio.", _SVC),
+    ToolEntry("speech_to_text", "Speech-to-Text Tool", MEDIA, "Transcribe an uploaded audio file.", _SVC + ", needs an uploaded audio file"),
+    ToolEntry("system_info", "System Info Tool", SYSTEM, "Operating system, memory and load.", _OS),
+)
+
+GROUPS: tuple[str, ...] = (FILES, DOCS, CODE, CALC, LOOKUP, MEDIA, SYSTEM)
+BY_NAME: dict[str, ToolEntry] = {e.name: e for e in CATALOG}
+
+# which environment variable each service tool needs (the services' own table is the source of truth)
+def key_needed(name: str) -> str | None:
+    from pal.chat.services import BY_NAME as SERVICES
+    spec = SERVICES.get(name)
+    return spec.key_env if spec else None
+
+
+def state(entry: ToolEntry, tools_cfg, env: Mapping[str, str]) -> str:
+    """For a tool that has to be switched on: whether it is on and ready, from the settings and the environment."""
+    from pal.chat.services import BY_NAME as SERVICES
+    if entry.name in SERVICES:
+        if "all" not in tools_cfg.services and entry.name not in tools_cfg.services:
+            return "off"
+        need = key_needed(entry.name)
+        return f"needs {need}" if need and not env.get(need) else "ready"
+    if entry.name in ("wikipedia", "arxiv_search"):
+        return "ready" if tools_cfg.network else "off"
+    return ""
+
+
+def render(tools_cfg, env: Mapping[str, str]) -> str:
+    lines = [f"Pal tools ({len(CATALOG)})", ""]
+    for group in GROUPS:
+        lines.append(group)
+        for e in (x for x in CATALOG if x.group == group):
+            st = state(e, tools_cfg, env)
+            lines.append(f"  {e.title:<36} {e.name:<26} {e.summary}  [{e.where}{'; ' + st if st else ''}]")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"

pal/tool_manager/__init__.py

@@ -0,0 +1,17 @@
+from pal.tool_manager.components.base import ToolCallRequest, ToolCallResult, ToolParam, ToolSpec
+from pal.tool_manager.components.conflict_resolver import ToolConflictResolver
+from pal.tool_manager.components.param_validator import ToolValidationError
+from pal.tool_manager.components.tool_registry import ToolDependencyError, ToolRegistry
+from pal.tool_manager.pipeline import ToolManagerPipeline
+
+__all__ = [
+    "ToolManagerPipeline",
+    "ToolCallRequest",
+    "ToolCallResult",
+    "ToolParam",
+    "ToolSpec",
+    "ToolConflictResolver",
+    "ToolValidationError",
+    "ToolDependencyError",
+    "ToolRegistry",
+]

pal/tool_manager/builtin.py

@@ -0,0 +1,82 @@
+"""Built-in read-only tools. `safe_eval` is an AST-based calculator: it never calls eval(), only
+allows numbers and + - * / // % ** with parentheses, and refuses expressions that would run for
+a long time or produce enormous numbers."""
+from __future__ import annotations
+
+import ast
+import operator
+import time
+from collections.abc import Callable
+from typing import Union
+
+from pal.tool_manager.components.base import ToolParam
+from pal.tool_manager.pipeline import ToolManagerPipeline
+
+Number = Union[int, float]
+
+_BIN: dict[type, Callable[[Number, Number], Number]] = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv,
+        ast.FloorDiv: operator.floordiv, ast.Mod: operator.mod, ast.Pow: operator.pow}
+_UNARY: dict[type, Callable[[Number], Number]] = {ast.UAdd: operator.pos, ast.USub: operator.neg}
+_MAX_LEN = 200
+_MAX_BITS = 20_000
+
+
+class CalculatorError(ValueError):
+    pass
+
+
+def _pow(a: Number, b: Number) -> Number:
+    if isinstance(a, int) and isinstance(b, int) and b > 0 and a not in (0, 1, -1) and a.bit_length() * b > _MAX_BITS:
+        raise CalculatorError("number too large")
+    if isinstance(b, float) and abs(b) > 1e6:
+        raise CalculatorError("exponent too large")
+    try:
+        r = a ** b
+    except (OverflowError, ZeroDivisionError) as e:
+        raise CalculatorError(str(e)) from e
+    if isinstance(r, complex):
+        raise CalculatorError("result is not a real number")
+    return r
+
+
+def _ev(node: ast.AST) -> Number:
+    if isinstance(node, ast.Expression):
+        return _ev(node.body)
+    if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool):
+        return node.value
+    if isinstance(node, ast.UnaryOp) and type(node.op) in _UNARY:
+        return _UNARY[type(node.op)](_ev(node.operand))
+    if isinstance(node, ast.BinOp) and type(node.op) in _BIN:
+        a, b = _ev(node.left), _ev(node.right)
+        if isinstance(node.op, ast.Pow):
+            return _pow(a, b)
+        try:
+            return _BIN[type(node.op)](a, b)
+        except ZeroDivisionError as e:
+            raise CalculatorError("division by zero") from e
+    raise CalculatorError("only numbers and + - * / // % ** ( ) are allowed")
+
+
+def safe_eval(expression: str) -> Number:
+    text = expression.strip().replace("^", "**").replace("\u00d7", "*").replace("\u00f7", "/")
+    if not text or len(text) > _MAX_LEN:
+        raise CalculatorError("empty or too long")
+    try:
+        tree = ast.parse(text, mode="eval")
+    except (SyntaxError, ValueError, RecursionError) as e:
+        raise CalculatorError("not a valid arithmetic expression") from e
+    try:
+        result = _ev(tree)
+    except RecursionError as e:
+        raise CalculatorError("expression too deeply nested") from e
+    if isinstance(result, float):
+        if result != result or result in (float("inf"), float("-inf")):
+            raise CalculatorError("result is not finite")
+        return int(result) if result.is_integer() and abs(result) < 1e15 else float(f"{result:.12g}")
+    return result
+
+
+def register_builtin_tools(tm: ToolManagerPipeline) -> None:
+    """calculator and current_time: no state, no files, no network."""
+    tm.register_tool("calculator", lambda: safe_eval, params=[ToolParam("expression", str)])
+    tm.register_tool("current_time", lambda: (lambda: time.strftime("%Y-%m-%d %H:%M:%S %z")), params=[])

pal/tool_manager/components/__init__.py

@@ -0,0 +1,19 @@
+from pal.tool_manager.components.base import ToolCallRequest, ToolCallResult, ToolParam, ToolSpec
+from pal.tool_manager.components.conflict_resolver import ToolConflictResolver
+from pal.tool_manager.components.param_validator import ToolValidationError, validate_params
+from pal.tool_manager.components.tool_call_queue import QueuedToolCall, ToolCallQueue
+from pal.tool_manager.components.tool_registry import ToolDependencyError, ToolRegistry
+
+__all__ = [
+    "ToolCallRequest",
+    "ToolCallResult",
+    "ToolParam",
+    "ToolSpec",
+    "ToolConflictResolver",
+    "ToolValidationError",
+    "validate_params",
+    "QueuedToolCall",
+    "ToolCallQueue",
+    "ToolDependencyError",
+    "ToolRegistry",
+]

pal/tool_manager/components/base.py

@@ -0,0 +1,53 @@
+"""
+Standardized tool interface and call request/response shapes (AIOS
+section 3.7). Every tool the tool manager loads conforms to ToolSpec --
+callers never invoke a tool's underlying callable directly, only ever
+through ToolManagerPipeline.invoke(), which validates parameters and
+resolves parallel-access conflicts uniformly regardless of what the
+tool itself actually does.
+"""
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+
+@dataclass
+class ToolParam:
+    name: str
+    type: type
+    required: bool = True
+    default: Any = None
+
+
+@dataclass
+class ToolSpec:
+    """A tool's standardized description. `loader` is called at most
+    once, the first time the tool is invoked by name -- "dynamically
+    loads the tool instance including executables initialization" means
+    exactly this: constructing/initializing whatever the tool actually
+    needs (a client, a subprocess handle, a loaded model, ...) is
+    deferred until the tool is first used, not paid for every tool ever
+    registered."""
+
+    name: str
+    loader: Callable[[], Callable[..., Any]]  # returns the callable that actually runs the tool
+    params: list[ToolParam] = field(default_factory=list)
+    parallel_limit: Optional[int] = None       # None = unlimited concurrent calls
+    dependencies: list[str] = field(default_factory=list)  # importable module names required at load time
+
+
+@dataclass
+class ToolCallRequest:
+    agent_id: str
+    tool_name: str
+    args: dict
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    submitted_at: float = field(default_factory=time.time)
+
+
+@dataclass
+class ToolCallResult:
+    ok: bool
+    result: Any = None
+    error: Optional[str] = None

pal/tool_manager/components/conflict_resolver.py

@@ -0,0 +1,27 @@
+"""
+Resolution of tool call conflicts (AIOS section 3.7): tools with a
+parallel-access limit (ToolSpec.parallel_limit) are tracked in a
+hashmap of tool_name -> current in-flight call count. A request is only
+admitted if doing so would not push that count past the tool's limit.
+"""
+from typing import Optional
+
+
+class ToolConflictResolver:
+    def __init__(self):
+        self._in_flight: dict[str, int] = {}
+
+    def can_acquire(self, tool_name: str, parallel_limit: Optional[int]) -> bool:
+        if parallel_limit is None:
+            return True
+        return self._in_flight.get(tool_name, 0) < parallel_limit
+
+    def acquire(self, tool_name: str) -> None:
+        self._in_flight[tool_name] = self._in_flight.get(tool_name, 0) + 1
+
+    def release(self, tool_name: str) -> None:
+        if tool_name in self._in_flight:
+            self._in_flight[tool_name] = max(0, self._in_flight[tool_name] - 1)
+
+    def in_flight_count(self, tool_name: str) -> int:
+        return self._in_flight.get(tool_name, 0)

pal/tool_manager/components/param_validator.py

@@ -0,0 +1,41 @@
+"""
+Parameter validation before execution -- "incorporating parameter
+validation before execution to prevent tool crashes." Runs before a
+tool's underlying callable is ever invoked, so a malformed call fails
+with a clear ToolValidationError instead of an arbitrary exception (or
+worse, silently wrong behavior) inside the tool itself.
+"""
+from pal.tool_manager.components.base import ToolParam
+
+
+class ToolValidationError(ValueError):
+    pass
+
+
+def validate_params(tool_name: str, params: list[ToolParam], args: dict) -> dict:
+    """Returns a normalized args dict (missing optional params filled in
+    with their declared defaults) or raises ToolValidationError."""
+    validated = {}
+    declared_names = {p.name for p in params}
+
+    for p in params:
+        if p.name in args:
+            value = args[p.name]
+            if p.type is float and isinstance(value, int) and not isinstance(value, bool):
+                value = float(value)                                     # JSON writes 100 for 100.0
+            if not isinstance(value, p.type) or (p.type in (int, float) and isinstance(value, bool)):
+                raise ToolValidationError(
+                    f"{tool_name}: parameter '{p.name}' expected {p.type.__name__}, "
+                    f"got {type(value).__name__}"
+                )
+            validated[p.name] = value
+        elif p.required:
+            raise ToolValidationError(f"{tool_name}: missing required parameter '{p.name}'")
+        else:
+            validated[p.name] = p.default
+
+    unknown = set(args) - declared_names
+    if unknown:
+        raise ToolValidationError(f"{tool_name}: unexpected parameter(s): {sorted(unknown)}")
+
+    return validated

pal/tool_manager/components/tool_call_queue.py

@@ -0,0 +1,111 @@
+"""
+Queued tool-call dispatch with conflict skip-ahead (AIOS section 3.7):
+"Request processing involves hashmap verification against usage and
+parallel limits; upon detecting conflicts, the system advances to
+subsequent queue requests until identifying a conflict-free candidate."
+
+Unlike the LLM syscall scheduler's FIFO/Round-Robin (section 3.3, which
+always processes requests in strict arrival or time-sliced order), a
+tool-call queue that hits a conflict does NOT block everything behind
+it: dispatch_next() scans forward past conflicting requests to find the
+first one that's runnable right now and executes that, leaving the
+conflicting ones in place (not requeued at the back -- their position
+in line doesn't change, only which one runs next does) for a later
+dispatch_next() call once capacity frees up.
+"""
+import time
+import uuid
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Optional
+
+from pal.tool_manager.components.base import ToolCallRequest, ToolCallResult
+from pal.tool_manager.components.conflict_resolver import ToolConflictResolver
+from pal.tool_manager.components.param_validator import validate_params
+from pal.tool_manager.components.tool_registry import ToolRegistry
+
+
+@dataclass
+class QueuedToolCall:
+    request: ToolCallRequest
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    submitted_at: float = field(default_factory=time.time)
+    status: str = "queued"  # queued | done | error
+    result: Optional[ToolCallResult] = None
+
+
+class ToolCallQueue:
+    def __init__(self, registry: ToolRegistry, conflict_resolver: ToolConflictResolver):
+        self.registry = registry
+        self.conflicts = conflict_resolver
+        self.queue: deque[QueuedToolCall] = deque()
+        self.requests: dict[str, QueuedToolCall] = {}
+
+    def submit(self, agent_id: str, tool_name: str, args: dict) -> str:
+        request = ToolCallRequest(agent_id=agent_id, tool_name=tool_name, args=args)
+        entry = QueuedToolCall(request=request)
+        self.requests[entry.id] = entry
+        self.queue.append(entry)
+        return entry.id
+
+    def dispatch_next(self) -> Optional[QueuedToolCall]:
+        """Scans the queue from the front for the first request whose
+        tool currently has capacity (hashmap check against its
+        parallel_limit), executes it, and removes it from the queue.
+        Returns None if the queue is empty or every queued request
+        currently conflicts."""
+        for entry in list(self.queue):
+            spec = self.registry.spec(entry.request.tool_name)
+            if not self.conflicts.can_acquire(entry.request.tool_name, spec.parallel_limit):
+                continue  # conflict -- advance to the next queued request
+
+            self.queue.remove(entry)
+            self._execute(entry)
+            return entry
+
+        return None  # nothing runnable right now
+
+    def _execute(self, entry: QueuedToolCall) -> None:
+        req = entry.request
+        spec = self.registry.spec(req.tool_name)
+        self.conflicts.acquire(req.tool_name)
+        try:
+            validated_args = validate_params(req.tool_name, spec.params, req.args)
+            fn = self.registry.get_callable(req.tool_name)
+            output = fn(**validated_args)
+            entry.result = ToolCallResult(ok=True, result=output)
+            entry.status = "done"
+        except Exception as e:
+            entry.result = ToolCallResult(ok=False, error=str(e))
+            entry.status = "error"
+        finally:
+            self.conflicts.release(req.tool_name)
+
+    def drain(self, max_iterations: int = 10_000) -> list[QueuedToolCall]:
+        """Repeatedly dispatch_next() until the queue is empty or
+        nothing left is runnable. Since this project executes tools
+        synchronously, a slot acquired in _execute() is released again
+        before dispatch_next() returns -- so a conflict only actually
+        blocks drain() here if the SAME tool's limit was already
+        exhausted by an in-flight call held open from OUTSIDE this
+        queue (e.g. another agent process using the same
+        ToolConflictResolver). max_iterations guards against that
+        making no progress."""
+        finished = []
+        i = 0
+        while self.queue and i < max_iterations:
+            entry = self.dispatch_next()
+            if entry is None:
+                break  # every remaining request currently conflicts
+            finished.append(entry)
+            i += 1
+        return finished
+
+    def get_result(self, request_id: str) -> QueuedToolCall:
+        return self.requests[request_id]
+
+    def forget(self, request_id: str) -> None:
+        self.requests.pop(request_id, None)
+
+    def pending_count(self) -> int:
+        return len(self.queue)

pal/tool_manager/components/tool_registry.py

@@ -0,0 +1,60 @@
+"""
+Standardized tool loading (AIOS section 3.7): tools are registered by
+ToolSpec but not actually constructed until first invoked by name --
+"dynamically loads the tool instance including executables
+initialization and dependencies verification" happens exactly once,
+lazily, here, and the resulting callable is cached for every later
+call.
+"""
+import importlib
+
+from pal.tool_manager.components.base import ToolSpec
+
+
+class ToolDependencyError(ImportError):
+    pass
+
+
+class ToolRegistry:
+    def __init__(self):
+        self._specs: dict[str, ToolSpec] = {}
+        self._loaded: dict[str, object] = {}
+
+    def register(self, spec: ToolSpec) -> None:
+        self._specs[spec.name] = spec
+
+    def is_registered(self, name: str) -> bool:
+        return name in self._specs
+
+    def spec(self, name: str) -> ToolSpec:
+        if name not in self._specs:
+            raise KeyError(f"no tool registered with name '{name}'")
+        return self._specs[name]
+
+    def get_callable(self, name: str):
+        """Dynamically loads (once) and returns the tool's underlying
+        callable. Verifies every declared dependency imports cleanly
+        BEFORE running the tool's own loader, so a missing dependency
+        fails with a clear ToolDependencyError naming exactly which
+        module is missing, rather than an opaque ImportError raised
+        from somewhere inside the tool's own loader/initialization
+        code."""
+        if name in self._loaded:
+            return self._loaded[name]
+
+        spec = self.spec(name)
+        for dep in spec.dependencies:
+            try:
+                importlib.import_module(dep)
+            except ImportError as e:
+                raise ToolDependencyError(f"tool '{name}' requires '{dep}', which is not installed") from e
+
+        instance = spec.loader()
+        self._loaded[name] = instance
+        return instance
+
+    def is_loaded(self, name: str) -> bool:
+        return name in self._loaded
+
+    def list_tools(self) -> list[str]:
+        return sorted(self._specs.keys())

pal/tool_manager/pipeline.py

@@ -0,0 +1,80 @@
+"""
+Tool Manager (AIOS section 3.7): standardized tool loading (uniform
+interface, parameter validation before execution, dynamic
+dependency-checked loading by name) and resolution of tool-call
+conflicts for tools with parallel-access limits (a hashmap of
+real-time in-flight counts, and a queue that skips ahead past
+conflicting requests rather than blocking on them).
+"""
+from typing import Optional
+
+from pal.tool_manager.components.base import ToolCallResult, ToolParam, ToolSpec
+from pal.tool_manager.components.conflict_resolver import ToolConflictResolver
+from pal.tool_manager.components.tool_call_queue import QueuedToolCall, ToolCallQueue
+from pal.tool_manager.components.tool_registry import ToolRegistry
+
+
+class ToolManagerPipeline:
+    def __init__(self):
+        self.registry = ToolRegistry()
+        self.conflicts = ToolConflictResolver()
+        self.queue = ToolCallQueue(self.registry, self.conflicts)
+
+    def register_tool(
+        self,
+        name: str,
+        loader,
+        params: list[ToolParam] = None,
+        parallel_limit: Optional[int] = None,
+        dependencies: list[str] = None,
+    ) -> None:
+        self.registry.register(ToolSpec(
+            name=name,
+            loader=loader,
+            params=params or [],
+            parallel_limit=parallel_limit,
+            dependencies=dependencies or [],
+        ))
+
+    def list_tools(self) -> list[str]:
+        return self.registry.list_tools()
+
+    def invoke(self, agent_id: str, tool_name: str, args: dict) -> ToolCallResult:
+        """Synchronous convenience call: submits to the queue and drains
+        dispatch attempts until THIS specific request completes (i.e.
+        until it's the conflict-free candidate dispatch_next() picks).
+        Looks synchronous to the caller even though it went through the
+        same centralized queue every tool call does -- same shape as
+        StorageSDK and Pipeline's LLM syscall dispatch."""
+        if not self.registry.is_registered(tool_name):
+            return ToolCallResult(ok=False, error=f"unknown tool: {tool_name}")
+        request_id = self.queue.submit(agent_id, tool_name, args)
+        try:
+            entry = self.queue.get_result(request_id)
+            while entry.status == "queued":
+                dispatched = self.queue.dispatch_next()
+                if dispatched is None:
+                    # Every queued call currently conflicts -- nothing this
+                    # loop can do would make progress right now.
+                    return ToolCallResult(
+                        ok=False,
+                        error=f"tool '{tool_name}' could not be dispatched -- all queued calls currently conflict",
+                    )
+                entry = self.queue.get_result(request_id)
+            return entry.result
+        finally:
+            self.queue.forget(request_id)
+
+    # -- queue-driven path, for callers that want direct control ---------------
+
+    def submit(self, agent_id: str, tool_name: str, args: dict) -> str:
+        return self.queue.submit(agent_id, tool_name, args)
+
+    def dispatch_next(self) -> Optional[QueuedToolCall]:
+        return self.queue.dispatch_next()
+
+    def drain(self, max_iterations: int = 10_000) -> list[QueuedToolCall]:
+        return self.queue.drain(max_iterations=max_iterations)
+
+    def get_result(self, request_id: str) -> QueuedToolCall:
+        return self.queue.get_result(request_id)

pal/tool_manager/utils/__init__.py

@@ -0,0 +1,3 @@
+"""No shared utilities yet for tool_manager -- reserved for future
+helpers (e.g. shared parameter-type coercion, tool discovery from a
+manifest file)."""

pal/web/__init__.py

@@ -0,0 +1,3 @@
+from pal.web.app import create_app
+
+__all__ = ["create_app"]