fixes #754

Author: jph00

fastcore/_modidx.py

@@ -588,6 +588,7 @@
                                'fastcore.test.test_stdout': ('test.html#test_stdout', 'fastcore/test.py'),
                                'fastcore.test.test_warns': ('test.html#test_warns', 'fastcore/test.py')},
             'fastcore.tools': { 'fastcore.tools._fmt_path': ('tools.html#_fmt_path', 'fastcore/tools.py'),
+                                'fastcore.tools._load_valid_paths': ('tools.html#_load_valid_paths', 'fastcore/tools.py'),
                                 'fastcore.tools.create': ('tools.html#create', 'fastcore/tools.py'),
                                 'fastcore.tools.ensure': ('tools.html#ensure', 'fastcore/tools.py'),
                                 'fastcore.tools.explain_exc': ('tools.html#explain_exc', 'fastcore/tools.py'),

fastcore/imports.py

@@ -100,3 +100,17 @@ def remove_suffix(text, suffix):
     "Temporary until py39 is a prereq"
     return text[:-len(suffix)] if text.endswith(suffix) else text
 
+def is_usable_tool(func:callable):
+    "True if the function has a docstring and all parameters have types, meaning that it can be used as an LLM tool."
+    from inspect import Parameter,signature
+    if not func.__doc__ or not callable(func): return False
+    return all(p.annotation != Parameter.empty for p in signature(func).parameters.values())
+
+__llmtools__ = set()
+
+def llmtool(f):
+    assert is_usable_tool(f), f"Function {f.__name__} is not usable as a tool"
+    __llmtools__.add(f.__name__)
+    f.__llmtool__ = True
+    return f
+

fastcore/tools.py

@@ -3,10 +3,11 @@
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/12_tools.ipynb.
 
 # %% auto #0
-__all__ = ['explain_exc', 'ensure', 'valid_path', 'run_cmd', 'rg', 'sed', 'view', 'create', 'insert', 'str_replace',
-           'strs_replace', 'replace_lines', 'move_lines', 'get_callable']
+__all__ = ['valid_paths', 'explain_exc', 'ensure', 'valid_path', 'run_cmd', 'rg', 'sed', 'view', 'create', 'insert',
+           'str_replace', 'strs_replace', 'replace_lines', 'move_lines', 'get_callable']
 
 # %% ../nbs/12_tools.ipynb #578246d2
+from .xdg import *
 from .imports import *
 from .xtras import truncstr
 from shlex import split
@@ -27,10 +28,21 @@ def ensure(b: bool, msg:str=""):
     if not b: raise ValueError(msg)
 
 
+# %% ../nbs/12_tools.ipynb #6afaf015
+def _load_valid_paths():
+    cfg = xdg_config_home() / 'fc_tools_paths'
+    base = ['.', '/tmp']
+    if not cfg.exists(): return base
+    return base + cfg.read_text().split()
+
+valid_paths = _load_valid_paths()
+
 # %% ../nbs/12_tools.ipynb #e4288129
-def valid_path(path:str, must_exist:bool=True) -> Path:
+def valid_path(path:str, must_exist:bool=True, chk_perms:bool=True) -> Path:
     'Return expanded/resolved Path, raising FileNotFoundError if must_exist and missing'
     p = Path(path).expanduser().resolve()
+    vpaths = [Path(vp).expanduser().resolve() for vp in valid_paths]
+    if chk_perms and not any(p == vp or vp in p.parents for vp in vpaths): raise PermissionError(f'Path not in valid_paths: {p}')
     if must_exist and not p.exists(): raise FileNotFoundError(f'File not found: {p}')
     return p
 
@@ -52,6 +64,7 @@ def run_cmd(
     return res + outp.stderr
 
 # %% ../nbs/12_tools.ipynb #eb253a39
+@llmtool
 def rg(
     argstr:str, # All args to the command, will be split with shlex
     disallow_re:str=None, # optional regex which, if matched on argstr, will disallow the command
@@ -61,6 +74,7 @@ def rg(
     return run_cmd('rg', '-n '+argstr, disallow_re=disallow_re, allow_re=allow_re)
 
 # %% ../nbs/12_tools.ipynb #09de7b32
+@llmtool
 def sed(
     argstr:str, # All args to the command, will be split with shlex
     disallow_re:str=None, # optional regex which, if matched on argstr, will disallow the command
@@ -80,6 +94,7 @@ def _fmt_path(f, p, skip_folders=()):
     return f'{f} ({f.stat().st_size/1024:.1f}k)'
 
 # %% ../nbs/12_tools.ipynb #5dd1aaf3
+@llmtool
 def view(
     path:str, # Path to directory or file to view
     view_range:tuple[int,int]=None, # Optional 1-indexed (start, end) line range for files, end=-1 for EOF. Do NOT use unless it's known that the file is too big to keep in context—simply view the WHOLE file when possible
@@ -88,7 +103,7 @@ def view(
 ):
     'View directory or file contents with optional line range and numbers'
     try:
-        p = valid_path(path)
+        p = valid_path(path, chk_perms=False)
         header = None
         if p.is_dir():
             lines = [s for f in p.glob('**/*') if (s := _fmt_path(f, p, skip_folders))]
@@ -106,6 +121,7 @@ def view(
     except: return explain_exc('viewing')
 
 # %% ../nbs/12_tools.ipynb #36f58e38
+@llmtool
 def create(
     path: str, # Path where the new file should be created
     file_text: str, # Content to write to the file
@@ -122,6 +138,7 @@ def create(
     except: return explain_exc('creating file')
 
 # %% ../nbs/12_tools.ipynb #434147ef
+@llmtool
 def insert(
     path: str, # Path to the file to modify
     insert_line: int, # Line number where to insert (0-based indexing)
@@ -139,6 +156,7 @@ def insert(
     except: return explain_exc('inserting text')
 
 # %% ../nbs/12_tools.ipynb #9272ff7d
+@llmtool
 def str_replace(
     path: str, # Path to the file to modify
     old_str: str, # Text to find and replace
@@ -157,6 +175,7 @@ def str_replace(
     except: return explain_exc('replacing text')
 
 # %% ../nbs/12_tools.ipynb #eb907119
+@llmtool
 def strs_replace(
     path:str, # Path to the file to modify
     old_strs:list[str], # List of strings to find and replace
@@ -167,6 +186,7 @@ def strs_replace(
     return 'Results for each replacement:\n' + '; '.join(res)
 
 # %% ../nbs/12_tools.ipynb #94dd09ed
+@llmtool
 def replace_lines(
     path:str, # Path to the file to modify
     start_line:int, # Starting line number to replace (1-based indexing)
@@ -184,6 +204,7 @@ def replace_lines(
     except: return explain_exc('replacing lines')
 
 # %% ../nbs/12_tools.ipynb #b136abf8
+@llmtool
 def move_lines(
     path: str,  # Path to the file to modify
     start_line: int,  # Starting line number to move (1-based)

nbs/12_tools.ipynb

@@ -27,6 +27,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
+    "from fastcore.xdg import *\n",
     "from fastcore.imports import *\n",
     "from fastcore.xtras import truncstr\n",
     "from shlex import split\n",
@@ -41,7 +42,7 @@
    "outputs": [],
    "source": [
     "#| hide\n",
-    "from fastcore.test import test_eq\n",
+    "from fastcore.test import test_eq,test_fail\n",
     "from toolslm.funccall import get_schema\n",
     "import inspect"
    ]
@@ -135,6 +136,23 @@
     "calc_div(1,0)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6afaf015",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def _load_valid_paths():\n",
+    "    cfg = xdg_config_home() / 'fc_tools_paths'\n",
+    "    base = ['.', '/tmp']\n",
+    "    if not cfg.exists(): return base\n",
+    "    return base + cfg.read_text().split()\n",
+    "\n",
+    "valid_paths = _load_valid_paths()"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -143,32 +161,26 @@
    "outputs": [],
    "source": [
     "#| export\n",
-    "def valid_path(path:str, must_exist:bool=True) -> Path:\n",
+    "def valid_path(path:str, must_exist:bool=True, chk_perms:bool=True) -> Path:\n",
     "    'Return expanded/resolved Path, raising FileNotFoundError if must_exist and missing'\n",
     "    p = Path(path).expanduser().resolve()\n",
+    "    vpaths = [Path(vp).expanduser().resolve() for vp in valid_paths]\n",
+    "    if chk_perms and not any(p == vp or vp in p.parents for vp in vpaths): raise PermissionError(f'Path not in valid_paths: {p}')\n",
     "    if must_exist and not p.exists(): raise FileNotFoundError(f'File not found: {p}')\n",
     "    return p"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "a2b93ffe",
+   "id": "c30153ab",
    "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "Path('/Users/jhoward/aai-ws/fastcore/nbs')"
-      ]
-     },
-     "execution_count": null,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
+   "outputs": [],
    "source": [
-    "valid_path(\".\")"
+    "assert valid_path('.')\n",
+    "assert valid_path('/tmp')\n",
+    "\n",
+    "test_fail(lambda: valid_path('..'), exc=PermissionError)"
    ]
   },
   {
@@ -299,6 +311,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
+    "@llmtool\n",
     "def rg(\n",
     "    argstr:str, # All args to the command, will be split with shlex\n",
     "    disallow_re:str=None, # optional regex which, if matched on argstr, will disallow the command\n",
@@ -436,6 +449,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
+    "@llmtool\n",
     "def sed(\n",
     "    argstr:str, # All args to the command, will be split with shlex\n",
     "    disallow_re:str=None, # optional regex which, if matched on argstr, will disallow the command\n",
@@ -539,6 +553,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
+    "@llmtool\n",
     "def view(\n",
     "    path:str, # Path to directory or file to view\n",
     "    view_range:tuple[int,int]=None, # Optional 1-indexed (start, end) line range for files, end=-1 for EOF. Do NOT use unless it's known that the file is too big to keep in context—simply view the WHOLE file when possible\n",
@@ -547,7 +562,7 @@
     "):\n",
     "    'View directory or file contents with optional line range and numbers'\n",
     "    try:\n",
-    "        p = valid_path(path)\n",
+    "        p = valid_path(path, chk_perms=False)\n",
     "        header = None\n",
     "        if p.is_dir():\n",
     "            lines = [s for f in p.glob('**/*') if (s := _fmt_path(f, p, skip_folders))]\n",
@@ -639,6 +654,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
+    "@llmtool\n",
     "def create(\n",
     "    path: str, # Path where the new file should be created\n",
     "    file_text: str, # Content to write to the file\n",
@@ -665,7 +681,13 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Created file /path/test.txt.\n",
+      "Created file /path/test.txt.\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
       "Contents:\n",
       "      1 │ Hello, world!\n"
      ]
@@ -686,6 +708,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
+    "@llmtool\n",
     "def insert(\n",
     "    path: str, # Path to the file to modify\n",
     "    insert_line: int, # Line number where to insert (0-based indexing)\n",
@@ -731,6 +754,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
+    "@llmtool\n",
     "def str_replace(\n",
     "    path: str, # Path to the file to modify\n",
     "    old_str: str, # Text to find and replace\n",
@@ -799,6 +823,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
+    "@llmtool\n",
     "def strs_replace(\n",
     "    path:str, # Path to the file to modify\n",
     "    old_strs:list[str], # List of strings to find and replace\n",
@@ -863,6 +888,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
+    "@llmtool\n",
     "def replace_lines(\n",
     "    path:str, # Path to the file to modify\n",
     "    start_line:int, # Starting line number to replace (1-based indexing)\n",
@@ -929,6 +955,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
+    "@llmtool\n",
     "def move_lines(\n",
     "    path: str,  # Path to the file to modify\n",
     "    start_line: int,  # Starting line number to move (1-based)\n",
@@ -1120,39 +1147,6 @@
     "    }"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "6ef89850",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "'run_cmd; explain_exc; ensure; valid_path; rg; sed; view; create; insert; str_replace; strs_replace; replace_lines; move_lines; get_callable; calc_div'"
-      ]
-     },
-     "execution_count": null,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "'; '.join(get_callable())"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "4092b227",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Verify that all public functions defined in this module have valid schemas\n",
-    "# (i.e., they have proper type annotations and docstrings required by get_schema)\n",
-    "for f,_o in get_callable().items(): test_eq(f, get_schema(globals()[f])['name'])"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "ed04dff5",