### Install toolslm

Source: https://github.com/answerdotai/toolslm/blob/main/README.md

Install the toolslm library using pip.

```sh
pip install toolslm
```

--------------------------------

### Import toolslm modules

Source: https://github.com/answerdotai/toolslm/blob/main/index.ipynb

Initial setup to import necessary XML utilities from the library.

```python
#| hide
from toolslm.xml import *
```

--------------------------------

### Import Markdown Hierarchy Utilities

Source: https://github.com/answerdotai/toolslm/blob/main/04_md_hier.ipynb

Initial setup for using the md_hier module and IPython display tools.

```python
from toolslm.md_hier import *
from IPython.display import Markdown
```

```python
#| hide
from nbdev.showdoc import show_doc
```

--------------------------------

### Example Type Handling

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates the handling of integer and Path types using the _handle_type function.

```python
_handle_type(int, None), _handle_type(Path, None)
```

--------------------------------

### Generate Context from Sample Files

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Example of using `files2ctx` to generate XML context from a list of Python and CSS files, with a maximum size limit.

```python
fnames = ['samples/sample_core.py', 'samples/sample_styles.css']
hl_md(files2ctx(fnames, max_size=120))
```

--------------------------------

### Example of creating a JSON schema parameter

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates the usage of the `_param` function to generate a schema dictionary for a function parameter.

```python
n,o = first(d.items())
print(n,'//', o)
_param(n, o)

```

--------------------------------

### Example Usage of find_docs

Source: https://github.com/answerdotai/toolslm/blob/main/03_download.ipynb

Demonstrates finding the documentation URL for a specific web page.

```python
fl_url = 'https://answerdotai.github.io/fastlite'

find_docs(fl_url)
```

--------------------------------

### Generate Context from Samples Folder

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Example of using `folder2ctx` to generate XML context from the 'samples' directory, including a prose introduction and filtering for Python files.

```python
print(folder2ctx('samples', prefix=True, types='py'))
```

--------------------------------

### Handle Type Mapping

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Examples of mapping Python types to JSON schema definitions.

```python
_handle_type(list, None), _handle_type(tuple[str], None), _handle_type(set[str], None)
```

```python
_handle_type(dict, None), _handle_type(dict[str,str], None)
```

--------------------------------

### Iterate and Find Docs for Multiple URLs

Source: https://github.com/answerdotai/toolslm/blob/main/03_download.ipynb

Iterates through a list of URLs and prints the found documentation URL for each. This example is marked for non-evaluation.

```python
#| eval: false
for o in urls: print(find_docs(o))
```

--------------------------------

### Get Package Context for Symbol

Source: https://github.com/answerdotai/toolslm/blob/main/05_inspecttools.ipynb

Returns XML context of all files in the symbol's top-level package. Delegates to sym2pkgctx for additional arguments.

```python
#| export
@llmtool
@delegates(sym2pkgctx)
def symfiles_package(
    sym:str,      # Dotted symbol path or "_last" for previous result
    **kwargs
):
    """Return XML context of all files in `sym`'s top-level package"""
    try: s = resolve(sym)
    except SymbolNotFound as e: return str(e)
    return sym2pkgctx(s, **kwargs)
```

--------------------------------

### Export Notebook Components

Source: https://github.com/answerdotai/toolslm/blob/main/03_download.ipynb

Exports components from the current notebook using nbdev's export functionality. This example is hidden and marked for non-evaluation.

```python
#|hide
#|eval: false
from nbdev.doclinks import nbdev_export
nbdev_export()
```

--------------------------------

### Example of Python type to JSON schema type conversion

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates the output of the `_types` function for various Python type hints, including generic types and unions.

```python
_types(list[int]), _types(set[int]), _types(int), _types('int')

```

```python
_types(List[int]), _types(Optional[str]), _types(str | None), _types(Tuple[str, int])

```

--------------------------------

### Convert Specific Folder in GitHub Repo to Context

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Converts the contents of a specific folder within a GitHub repository to context. This example targets the 'samples' folder.

```python
#| eval: false
print(repo2ctx('https://github.com/AnswerDotAI/toolslm/tree/main/samples'))
```

--------------------------------

### Get File Path and Content for a Symbol

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Retrieves the file path and its content for a given Python symbol. The output is formatted as a Markdown string.

```python
#| export
def sym2file(sym):
    """Return md string with filepath and contents for a symbol's source file"""
    f = Path(inspect.getfile(sym))
    return f"- `{f}`\n\n````\n{f.read_text()}\n````"
```

--------------------------------

### Get Folder Context for Symbol

Source: https://github.com/answerdotai/toolslm/blob/main/05_inspecttools.ipynb

Returns XML context of files in the folder containing the symbol's definition. Delegates to sym2folderctx for additional arguments.

```python
#| export
@llmtool
@delegates(sym2folderctx)
def symfiles_folder(
    sym:str,      # Dotted symbol path or "_last" for previous result
    **kwargs
):
    """Return XML context of files in the folder containing `sym`'s definition"""
    try: s = resolve(sym)
    except SymbolNotFound as e: return str(e)
    return sym2folderctx(s, **kwargs)
```

--------------------------------

### Test find_docs with Suffixes and Base URLs

Source: https://github.com/answerdotai/toolslm/blob/main/03_download.ipynb

Tests the `find_docs` function with various URL suffixes and base URLs to ensure consistent behavior. This example is marked for non-evaluation.

```python
#| eval: false
suffixes = ["/", "/tmp", "/tmp/tmp/"]
for suff in suffixes:
    for o in urls:  test_eq(find_docs(o), find_docs(o+suff))

test_eq(find_docs("https://github.com"), "https://github.com/llms.txt")
test_eq(find_docs("https://github.com/AnswerDotAI"), "https://github.com/llms.txt")
test_eq(find_docs("https://github.com/AnswerDotAI/"), "https://github.com/llms.txt")
```

--------------------------------

### Try to Get URL if Not 404

Source: https://github.com/answerdotai/toolslm/blob/main/03_download.ipynb

Attempts to retrieve a URL and returns the URL if the status code is not 404, otherwise returns None. Useful for checking resource availability.

```python
#| export
def _tryget(url):
    """Return response from `url` if `status_code!=404`, otherwise `None`"""
    res = get(url)
    return None if res.status_code==404 else url
```

--------------------------------

### Get Package Context for a Symbol

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

This function retrieves the content of files within a symbol's root package, with options to filter by file types and skip specific files or folders. It utilizes `sym2pkgpath` and `folder2ctx`.

```python
#| export
@delegates(folder2ctx)
def sym2pkgctx(
    sym,
    types:str|list='py', # List or comma-separated str of ext types from: py, js, java, c, cpp, rb, r, ex, sh, web, doc, cfg
    skip_file_re:str=r'^_mod', # Skip files matching regex
    skip_folder_re:str=r'^(\.|__)', # Skip folders matching regex
    **kwargs
):
    """Return contents of files in a symbol's root package"""
    return folder2ctx(sym2pkgpath(sym), types=types, skip_file_re=skip_file_re, skip_folder_re=skip_folder_re, **kwargs)
```

--------------------------------

### Folder to Context CLI Options (Part 1)

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

This output details the usage and options for the `folder2ctx` command-line tool, including path, output inclusion, and prefix settings.

```text
Output:
usage: folder2ctx [-h] [--path PATH] [--no-out] [--prefix] [--no-include_base]
                  [--title TITLE] [--max_size MAX_SIZE] [--max_total MAX_TOTAL]
                  [--readme_first] [--files_only] [--sigs_only] [--no-ids]
                  [--no-recursive] [--no-symlinks] [--file_glob FILE_GLOB]
                  [--file_re FILE_RE] [--folder_re FOLDER_RE]
                  [--skip_file_glob SKIP_FILE_GLOB]
                  [--skip_file_re SKIP_FILE_RE]
                  [--skip_folder_re SKIP_FOLDER_RE] [--ret_folders] [--no-sort]
                  [--types TYPES] [--exts EXTS]

CLI to convert folder contents to XML context, handling notebooks

options:
  -h, --help                       show this help message and exit
  --path PATH                      Folder name containing files to add to
                                   context (default: .)
  --no-out                         Include notebook cell outputs? (default:
                                   True)
  --prefix      
```

--------------------------------

### Get Directory Listing of Symbol Attributes

Source: https://context7.com/answerdotai/toolslm/llms.txt

Returns a list of attributes for a given Python symbol. Can optionally exclude private attributes (those starting with an underscore).

```python
from toolslm.inspecttools import symdir, importmodule

importmodule('pathlib')

# Get all attributes
attrs = symdir('pathlib.Path')
print(attrs[:10])  # First 10 attributes

# Exclude private attributes
public_attrs = symdir('pathlib.Path', exclude_private=True)
print(public_attrs)  # Only public methods and attributes
```

--------------------------------

### Create and Use a Simple Namespace

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates creating a namespace with a simple function and then calling that function through the namespace.

```python
def sums(a, b): return a + b
ns = mk_ns(sums)
ns
```

```python
ns['sums'](1, 2)
```

--------------------------------

### Folder to Context CLI Options (Part 2)

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

This output continues detailing the options for the `folder2ctx` CLI, covering settings for including base paths, titles, size limits, and file filtering.

```text
                   Include Anthropic's suggested prose intro?
                                   (default: False)
  --no-include_base                Include full path in src? (default: True)
  --title TITLE                    Optional title attr for Documents element
  --max_size MAX_SIZE              Skip files larger than this (bytes) (default:
                                   100000)
  --max_total MAX_TOTAL            Max total output size in bytes (default:
                                   10000000)
  --readme_first                   Prioritize README files at start of context? (default: False)
  --files_only                     Return dict of {filename: size} instead of
                                   context? (default: False)
  --sigs_only                      Return signatures instead of full text for
                                   python files? (default: False)
  --no-ids                         Include cell ids in notebooks? (default:
                                   True)
  --no-recursive                   search subfolders (default: True)
  --no-symlinks                    follow symlinks? (default: True)
  --file_glob FILE_GLOB            Only include files matching glob
  --file_re FILE_RE                Only include files matching regex
  --folder_re FOLDER_RE            Only enter folders matching regex
  --skip_file_glob SKIP_FILE_GLOB  Skip files matching glob
  --skip_file_re SKIP_FILE_RE      Skip files matching regex
  --skip_folder_re SKIP_FOLDER_RE  Skip folders matching regex,
  --ret_folders                    return folders, not just files (default: False)
  --no-sort                        sort files by name within each folder
                                   (default: True)
  --types TYPES                    list or comma-separated str of ext types
                                   from: py, js, java, c, cpp, rb, r, ex, sh,
                                   web, doc, cfg
  --exts EXTS                      list or comma-separated str of exts to
                                   include
```

--------------------------------

### Define silly_test Function

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Starts the definition of a function with string annotations.

```python
def silly_test(
```

--------------------------------

### Get Python Function Schema

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Retrieves the schema for the python execution function.

```python
get_schema(python)
```

--------------------------------

### Folder to Context CLI Help

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Display the help message for the `folder2ctx` command-line interface. This shows all available options for converting folder contents to context.

```bash
#| eval: false
!folder2ctx -h
```

--------------------------------

### Get Symbol Length

Source: https://github.com/answerdotai/toolslm/blob/main/05_inspecttools.ipynb

Returns the length of a given symbol. Use '_last' for the previous result.

```python
#| export
@llmtool
def symlen(
    sym: str  # Dotted symbol path or "_last" for previous result
):
    """Returns the length of the given symbol"""
    return len(resolve(sym))
```

--------------------------------

### Get Schema for Hidden Fields

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates how to retrieve a function schema while optionally excluding internal fields.

```python
get_schema(test_hidden, skip_hidden=True)  # should exclude _internal
```

```python
get_schema(test_hidden)
```

--------------------------------

### Get Type and Value with symtype_val

Source: https://github.com/answerdotai/toolslm/blob/main/05_inspecttools.ipynb

Returns a list of tuples containing both the type and the repr of the provided symbols.

```python
def symtype_val(
    syms: str  # Comma separated str list of dotted symbol paths (e.g `Interval` or `sympy.sets.sets.Interval`); "_last" for prev result
):
    """List of 2-ple of (type,repr) of symbols' values.

    Examples:
    
    - `symtype_val("a,c,notexist")` -> `[(<class 'str'>,'foo'),(<class 'int'>,1), 'SymbolNotFound']`"""
    def f(o):
        try: r = resolve(o)
        except SymbolNotFound as e: return 'SymbolNotFound'
        return (type(r), repr(r))
    return [f(o) for o in re.split(r'\,\s*', syms)]
```

```python
symtype_val('a,b,foofoo')
```

--------------------------------

### Fetch Documentation

Source: https://context7.com/answerdotai/toolslm/llms.txt

Retrieves documentation from URLs, with support for auto-discovering llms.txt or markdown files.

```python
from toolslm.download import read_docs

# Fetch documentation (auto-discovers llms.txt or markdown)
docs = read_docs('https://docs.python.org/3/')
print(docs[:500])

# With options
docs = read_docs(
    'https://fastcore.fast.ai/',
    optional=True,  # Include optional sections from llms.txt
    rm_comments=True,  # Remove HTML comments
    rm_details=True  # Remove <details> sections
)
```

--------------------------------

### Define a sample function for docments

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

A simple function with type hints and docstrings to demonstrate docments.

```python
def silly_sum(
    a:int, # First thing to sum
    b:int=1, # Second thing to sum
    c:list[int]=None, # A pointless argument
) -> int: # The sum of the inputs
    """Adds a + b."""
    return a + b

```

--------------------------------

### Generate Schema Excluding Hidden Parameters

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Shows how to use `skip_hidden=True` to exclude parameters starting with an underscore (`_`) from the generated schema.

```python
def test_hidden(a: int, _internal: str = "x"):
    "Test func"
    pass

get_schema(test_hidden, skip_hidden=True)
```

--------------------------------

### Create Tool with Required Arguments

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates creating a tool where arguments are required by the schema, and the function call reflects this requirement.

```python
tool_req_hy = dict2obj(dict(name='run', description='Run command', inputSchema=dict(type='object', properties={'approval-policy': {'type': 'string'}, 'cmd': {'type': 'string'}}, required=['approval-policy', 'cmd'])))

seen = []
fn = mk_tool(disp, tool_req_hy)
fn('never', 'ls')
test_eq(seen[-1], ('run', {'approval-policy': 'never', 'cmd': 'ls'}))
```

--------------------------------

### GET /get_schema

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Generates a JSON schema for a provided class, function, or method, extracting metadata from docstrings and type annotations.

```APIDOC
## GET /get_schema

### Description
Generates a JSON schema for a class, function, or method. It extracts parameter details, docstrings, and return type information to build a structured schema object.

### Parameters
#### Request Body
- **f** (callable|dict) - Required - The function, method, or class to generate a schema for.
- **pname** (string) - Optional - Key name for parameters (default: 'input_schema').
- **evalable** (boolean) - Optional - Whether to stringify defaults that cannot be literal_eval'd (default: False).
- **skip_hidden** (boolean) - Optional - Whether to skip parameters starting with '_' (default: False).
- **name** (string) - Optional - Override function name.

### Response
#### Success Response (200)
- **name** (string) - The name of the function or method.
- **description** (string) - The docstring of the function, including return information.
- **[pname]** (object) - The generated JSON schema object containing properties, types, and requirements.

### Response Example
{
  "name": "get_schema",
  "description": "Generate JSON schema for a class, function, or method",
  "input_schema": {
    "type": "object",
    "properties": {
      "f": {"type": "object"},
      "pname": {"type": "string", "default": "input_schema"}
    },
    "required": ["f"]
  }
}
```

--------------------------------

### Define Sample Markdown Content

Source: https://github.com/answerdotai/toolslm/blob/main/04_md_hier.ipynb

Create a sample markdown string to demonstrate hierarchical parsing.

```python
sample_md = """
# Introduction

Welcome to our documentation.

## Getting Started

Follow these steps to begin.

### Installation

Run the following command:

```bash
# Install the packackge
pip install our-package
```

### Configuration

Set up your config file.

## Advanced Usage

For advanced users only.

# Appendix

Additional resources."""
```

--------------------------------

### Demonstrate Exception to String Conversion

Source: https://github.com/answerdotai/toolslm/blob/main/02_shell.ipynb

Illustrates the usage of the `exception2str` function by catching a ZeroDivisionError and printing its string representation.

```python
try: print(1/0)
except Exception as e: print(exception2str(e))
```

--------------------------------

### Display Documentation for create_heading_dict

Source: https://github.com/answerdotai/toolslm/blob/main/04_md_hier.ipynb

View the docstring and signature for the primary parsing function.

```python
show_doc(create_heading_dict)
```

--------------------------------

### Generate schema for an instance method

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates schema generation for class methods including default arguments.

```python
class Dummy:
    def sums(
        self,
        a:int,  # First thing to sum
        b:int=1 # Second thing to sum
    ): # The sum of the inputs
        "Adds a + b."
        print(f"Finding the sum of {a} and {b}")
        return a + b

get_schema(Dummy.sums)
```

```text
Result:
{'name': 'sums',
 'description': 'Adds a + b.',
 'input_schema': {'type': 'object',
  'properties': {'a': {'type': 'integer', 'description': 'First thing to sum'},
   'b': {'type': 'integer',
    'description': 'Second thing to sum',
    'default': 1}},
  'required': ['a']}}
```

--------------------------------

### CLI for Folder to Context Conversion

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Use this Python function as a CLI to convert folder contents to XML context, handling notebooks. It accepts various options to customize the context generation.

```python
#| export
#| hide
@call_parse
@delegates(folder2ctx)
def folder2ctx_cli(
    path:str='.', # Folder name containing files to add to context
    out:bool=True, # Include notebook cell outputs?
    **kwargs # Passed to `folder2ctx`
)->str: # XML for Claude context
    """CLI to convert folder contents to XML context, handling notebooks"""
    print(folder2ctx(path, out=out, **kwargs))
```

--------------------------------

### Sanitize Name for Python Identifier

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Converts a string into a valid Python identifier by normalizing it, prefixing with '_' if it starts with a digit, and appending '_' if it's a keyword. Uses `_norm_nm`.

```python
#| export
def _py_nm(nm):
    nm = _norm_nm(nm, '_')
    if not nm: return '_'
    if nm and nm[0].isdigit(): nm = f'_{nm}'
    if keyword.iskeyword(nm): nm = f'{nm}_'
    return nm
```

--------------------------------

### CLI Wrapper for GitHub Repository to Context Conversion

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

A command-line interface function that wraps `repo2ctx`, allowing for easy conversion of GitHub repository contents to XML context directly from the command line. It supports various parameters for filtering and output control.

```python
#| export
#| hide
@call_parse
@delegates(repo2ctx, but='include_base,title,readme_first')
def repo2ctx_cli(
    owner:str,  # GitHub repo owner or "owner/repo" or a full github URL
    repo:str=None,   # GitHub repo name (leave empty if using "owner/repo" or URL format)
    ref:str=None,  # Git ref (branch/tag/sha)
    folder:str=None,  # Only include files under this path
    out:bool=True, # Include notebook cell outputs?
    **kwargs # Passed to `repo2ctx`
)->str: # XML for Claude context
    """CLI to convert GitHub repo contents to XML context"""
    print(repo2ctx(owner, repo, ref=ref, folder=folder, out=out, **kwargs))
```

--------------------------------

### Execute Code in Stateful Shell

Source: https://github.com/answerdotai/toolslm/blob/main/02_shell.ipynb

Demonstrates executing a simple print statement and an addition operation within the initialized stateful shell. It shows how to access the result and captured stdout.

```python
shell = get_shell()
r = shell.run_cell('print(3); 1+1')
r.result,r.stdout
```

--------------------------------

### Add Timeout and Capture to run_cell

Source: https://github.com/answerdotai/toolslm/blob/main/02_shell.ipynb

Extends the `TerminalInteractiveShell.run_cell` method to include a timeout feature and capture stdout/stderr. If a timeout occurs, a `TimeoutError` is raised. Ensure IPython is installed.

```python
@patch
def run_cell(self:TerminalInteractiveShell, cell, timeout=None):
    """Wrapper for original `run_cell` which adds timeout and output capture"""
    if timeout:
        def handler(*args): raise TimeoutError()
        signal.signal(signal.SIGALRM, handler)
        signal.alarm(timeout)
    try:
        with capture_output() as io: result = self.orig_run(cell)
        result.stdout = io.stdout
        return result
    except TimeoutException as e:
        result = self.ExecutionResult(error_before_exec=None, error_in_exec=e)
    finally:
        if timeout: signal.alarm(0)
```

--------------------------------

### Union Type Handling

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates how new (3.10+) and old Union syntax are parsed into schema components.

```python
def _example_new_unioin(opt_tup: str | None): pass

d = docments(_example_new_unioin, full=True)
anno1 = first(d.items())[1].anno
(anno1, get_origin(anno1), get_args(anno1))
```

```python
def _example_old_union(opt_tup: Union[str, type(None)] =None): pass

d = docments(_example_old_union, full=True)
anno2 = first(d.items())[1].anno
(anno2, get_origin(anno2), get_args(anno2))
```

--------------------------------

### Create XML from document strings

Source: https://context7.com/answerdotai/toolslm/llms.txt

Formats a list of raw strings into the standard XML document format.

```python
from toolslm.xml import docs_xml

# Create XML from document strings
documents = [
    "This is the first document content.",
    "This is the second document content."
]
sources = ["doc1.txt", "doc2.txt"]

xml_output = docs_xml(
    documents,
    srcs=sources,
    prefix=True,  # Include prose intro
    title="Reference Documents"
)
print(xml_output)
```

--------------------------------

### Get Root Package Path for a Symbol

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Use this function to determine the root directory of a Python package associated with a given symbol. It requires the symbol to have a `__module__` attribute.

```python
#| export
def sym2pkgpath(sym):
    """Get root package path for a symbol"""
    mod = sym.__name__ if inspect.ismodule(sym) else sym.__module__
    root = mod.split('.')[0]
    return Path(sys.modules[root].__path__[0])
```

--------------------------------

### Execute Code Raising an Exception

Source: https://github.com/answerdotai/toolslm/blob/main/02_shell.ipynb

Shows how to execute code that raises an exception within the stateful shell and how to retrieve and format the exception details using `exception2str`.

```python
r = shell.run_cell('raise Exception("blah")')
print(exception2str(r.error_in_exec))
```

--------------------------------

### Create Doctype Named Tuple

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Wraps content and source into a doctype tuple, automatically generating an MD5 hash for the source if none is provided.

```python
#| export
def mk_doctype(content:str,  # The document content
           src:Optional[str]=None # URL, filename, etc; defaults to `md5(content)` if not provided
          ) -> namedtuple:
    "Create a `doctype` named tuple"
    if src is None: src = hashlib.md5(content.encode()).hexdigest()[:8]
    return doctype(_add_nls(str(src).strip()), _add_nls(content.strip()))
```

```python
doc = 'This is a "sample"'
mk_doctype(doc)
```

--------------------------------

### Create Tool from Function and Schema

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Creates a callable tool from a Python function and a tool schema. The function is wrapped to accept arguments according to the schema and track calls.

```python
seen = []
def disp(name, **kwargs):
    seen.append((name, kwargs))
    return kwargs

fn = mk_tool(disp, tool_hy)
test_eq(fn('ls', approval_policy='never'), {'cmd': 'ls', 'approval-policy': 'never'})
test_eq(seen[-1], ('run', {'cmd': 'ls', 'approval-policy': 'never'}))
```

--------------------------------

### Get Schema for a Symbol in a Namespace

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Retrieves the schema for a given symbol name within a namespace. Optionally replaces dots with dashes in the schema name. Requires `get_schema` and `resolve_nm`.

```python
#| export
def get_schema_nm(nm:str, ns, dot2dash=False, **kwargs):
    """Get schema for symbol `nm` in namespace `ns`, preserving the full dotted name"""
    name = nm.replace('.', '-') if dot2dash else nm
    return get_schema(resolve_nm(nm, ns), name=name, **kwargs)
```

--------------------------------

### Get Value and Type of Python Symbols

Source: https://context7.com/answerdotai/toolslm/llms.txt

Retrieves the runtime value and type for one or more Python symbols specified by their dotted paths. Multiple symbols can be requested as a comma-separated string.

```python
from toolslm.inspecttools import symval, symtype, importmodule

importmodule('sys')

# Get values
values = symval('sys.version,sys.platform')
print(values)  # ['3.11.0 ...', 'linux']

# Get types
types = symtype('sys.version,sys.path')
print(types)  # [<class 'str'>, <class 'list'>]
```

--------------------------------

### Execute a Simple Function Call

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates calling the `sums` function using `call_func` with a list containing the function itself as the namespace.

```python
call_func('sums', {'a': 1, 'b': 2}, ns=[sums])
```

--------------------------------

### Generate XML context from GitHub repositories

Source: https://context7.com/answerdotai/toolslm/llms.txt

Fetches files directly via the GitHub API to generate XML context without requiring a local clone.

```python
from toolslm.xml import repo2ctx

# Using owner/repo format
xml_context = repo2ctx('fastai/fastcore', types='py', max_size=50000)

# Using full GitHub URL with specific folder
xml_context = repo2ctx(
    'https://github.com/anthropics/anthropic-cookbook/tree/main/misc',
    types='py,ipynb'
)

# Specify branch/tag and folder
xml_context = repo2ctx(
    'answerdotai',
    'toolslm',
    ref='main',
    folder='toolslm',
    show_filters=True  # Include filter info in title
)
```

--------------------------------

### Get Source Code of a Python Symbol

Source: https://context7.com/answerdotai/toolslm/llms.txt

Retrieves the source code for a given Python symbol specified by its dotted path. Requires the module to be imported first. Supports retrieving the source of the previously resolved symbol using '_last'.

```python
from toolslm.inspecttools import symsrc, importmodule

# First import the module
importmodule('json')

# Get source code
source = symsrc('json.dumps')
print(source)  # Prints source code of json.dumps function

# Chain with _last for previous result
symsrc('_last')  # Source of previously resolved symbol
```

--------------------------------

### Generate Schema for Path Type with Default

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Illustrates schema generation for a function parameter with a `Path` type and a default value.

```python
def _path_test(path: Path = Path('.')):
    "Mandatory docstring"
get_schema(_path_test)
```

--------------------------------

### Generate XML context from specific files

Source: https://context7.com/answerdotai/toolslm/llms.txt

Converts a list of specific file paths into the XML context format.

```python
from toolslm.xml import files2ctx

# Convert specific files to context
xml_context = files2ctx(
    ['src/main.py', 'src/utils.py', 'README.md'],
    prefix=True,  # Include Anthropic's suggested prose intro
    max_size=100000  # Skip files larger than 100KB
)
print(xml_context)
# Output:
# Here are some documents for you to reference for your task:
#
# <documents><document index="1"><src>
# src/main.py
# </src><document-content>
# [file contents]
# </document-content></document>...</documents>
```

--------------------------------

### Initialize Stateful IPython Shell

Source: https://github.com/answerdotai/toolslm/blob/main/02_shell.ipynb

Creates and configures a `TerminalInteractiveShell` instance with minimal functionality, disabling logging and display prompts. This provides a clean environment for executing code.

```python
def get_shell()->TerminalInteractiveShell:
    """Get a `TerminalInteractiveShell` with minimal functionality"""
    sh = TerminalInteractiveShell()
    sh.logger.log_output = sh.history_manager.enabled = False
    dh = sh.displayhook
    dh.finish_displayhook = dh.write_output_prompt = dh.start_displayhook = lambda: None
    dh.write_format_data = lambda format_dict, md_dict=None: None
    sh.logstart = sh.automagic = sh.autoindent = False
    sh.autocall = 0
    sh.system = lambda cmd: None
    return sh
```

--------------------------------

### Find LLM-Friendly Documentation URL

Source: https://github.com/answerdotai/toolslm/blob/main/03_download.ipynb

Recursively searches for an LLM-friendly `llms.txt` or markdown file from a given URL. It checks common locations and falls back to parent directories if necessary.

```python
#| export
def find_docs(url):
    """If available, return LLM-friendly llms.txt context or markdown file location from `url`"""
    base,path,fname = split_url(url)
    url = (base+path+fname).strip('/')
    if fname=='/llms.txt': return url
    if Path(fname).suffix in('.md', '.txt', '.rst'): return _tryget(url)
    if '.' in fname: return _tryget(url+'.md') or find_docs(url[:url.rfind('/')])
    res = _tryget(url+'/llms.txt')
    if res: return res
    res = _tryget(url+'/index.md')
    if res: return res
    res = _tryget(url+'/index.html.md')
    if res: return res
    res = _tryget(url+'/index-commonmark.md')
    if res: return res
    parsed_url = urlparse(url)
    if parsed_url.path == '/' or not parsed_url.path: return None
    return find_docs(urljoin(url, '..'))
```

--------------------------------

### Call a Method Using Global Namespace

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates calling a method (`ca.f`) using `call_func` by passing the `globals()` dictionary as the namespace.

```python
test_eq(call_func('ca.f', {'a': 5}, ns=globals()), 1)
```

--------------------------------

### Create Document Format Tuple

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Generates a formatted tuple for a single document using the recommended Anthropic structure.

```python
#| export
def mk_doc(index:int,  # The document index
           content:str,  # The document content
           src:Optional[str]=None, # URL, filename, etc; defaults to `md5(content)` if not provided
           **kwargs
          ) -> tuple:
    "Create an `ft` format tuple for a single doc in Anthropic's recommended format"
    dt = mk_doctype(content, src)
    content = Document_content(NotStr(dt.content))
    src = Src(NotStr(dt.src))
    return Document(src, content, index=index, **kwargs)
```

```python
mk_doc(1, doc, title="test")
```

--------------------------------

### CLI: folder2ctx

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Command line interface to convert folder contents into XML context, supporting various filtering and configuration options.

```APIDOC
## CLI folder2ctx

### Description
Converts a local folder's contents into an XML format suitable for LLM context. It handles notebooks and provides extensive filtering options.

### Method
CLI Command

### Parameters
#### Options
- **--path** (str) - Optional - Folder name containing files to add to context (default: .)
- **--no-out** (flag) - Optional - Exclude notebook cell outputs
- **--title** (str) - Optional - Optional title attribute for Documents element
- **--max_size** (int) - Optional - Skip files larger than this (bytes) (default: 100000)
- **--max_total** (int) - Optional - Max total output size in bytes (default: 10000000)
- **--types** (str) - Optional - List or comma-separated string of extension types to include
- **--exts** (str) - Optional - List or comma-separated string of extensions to include
```

--------------------------------

### Convert Folder Contents to XML Context

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Recursively converts folder contents to XML context, supporting notebook conversion, file size limits, and options to include or exclude paths and prioritize README files. Can also return file sizes instead of context.

```python
#| export
@delegates(globtastic, but='func')
def folder2ctx(
    path:Union[str,Path], # Folder to read
    prefix:bool=False, # Include Anthropic's suggested prose intro?
    out:bool=True, # Include notebook cell outputs?
    include_base:bool=True, # Include full path in src?
    title:str=None, # Optional title attr for Documents element
    max_size:int=100_000, # Skip files larger than this (bytes)
    max_total:int=10_000_000,  # Max total output size in bytes
    readme_first:bool=False,  # Prioritize README files at start of context?
    files_only:bool=False,  # Return dict of {filename: size} instead of context?
    sigs_only:bool=False,  # Return signatures instead of full text? (where supported by `codesigs` lib)
    ids:bool=True,  # Include cell ids in notebooks?
    **kwargs
)->Union[str,dict]:
    """Convert folder contents to XML context, handling notebooks"""
    folder = Path(path).expanduser()
    fnames = pglob(folder, **kwargs)
    if files_only: return {str(f.relative_to(folder)): f.stat().st_size for f in fnames}
    if readme_first: fnames = sorted(fnames, key=lambda f: (0 if 'readme' in f.name.lower() else 1, f))
    srcs = fnames if include_base else [f.relative_to(folder) for f in fnames]
    res = files2ctx(fnames, prefix=prefix, out=out, srcs=srcs, title=title, max_size=max_size, sigs_only=sigs_only, ids=ids)
    suf = f"\n\n[TRUNCATED: output size {{_outsz_}} exceeded max size {max_total} bytes]"
    if max_total and len(res) > max_total: res = truncstr(res, max_total, suf=suf, sizevar='_outsz_')
    return res
```

--------------------------------

### Create XML context from folder

Source: https://github.com/answerdotai/toolslm/blob/main/README.md

Use the folder2ctx helper to generate XML context from files in a specified folder. Supports file globbing for filtering.

```python
print(folder2ctx('samples', prefix=False, file_glob='*.py'))
```

--------------------------------

### Convert Notebook Output to XML

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Transforms a single notebook output object into an XML-compatible format.

```python
#| export
def cell2out(o):
    "Convert single notebook output to XML format"
    if hasattr(o, 'data'): 
        txt = get_mime_text(o.data)
        if txt: return Out(txt, mime='markdown' if 'text/markdown' in o.data else 'plain')
    if hasattr(o, 'text'):
        txt = o.text if isinstance(o.text, str) else ''.join(o.text)
        return Out(txt, type='stream', name=o.get('name', 'stdout'))
    if hasattr(o, 'ename'): return Out(f"{o.ename}: {o.evalue}", type='error')
```

--------------------------------

### Convert GitHub Repo to Context with File Type and Output Control

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Converts a GitHub repository to context, specifying file types and enabling `files_only=True` to return a dictionary of file sizes instead of XML. The `out=False` argument prevents the inclusion of notebook cell outputs.

```python
#| eval: false
print(repo2ctx('answerdotai/toolslm', types='py', skip_file_re='^_', out=False, files_only=True))
```

--------------------------------

### Create Callable Tools from Schema

Source: https://context7.com/answerdotai/toolslm/llms.txt

Wraps a dispatcher function with a JSON schema definition to create a callable tool object.

```python
from toolslm.funccall import mk_tool, schema2sig
from types import SimpleNamespace

# Define a tool schema
tool = SimpleNamespace(
    name='calculate_area',
    description='Calculate the area of a rectangle',
    inputSchema={
        'properties': {
            'width': {'type': 'number', 'description': 'Width of rectangle'},
            'height': {'type': 'number', 'description': 'Height of rectangle'}
        },
        'required': ['width', 'height']
    }
)

# Create dispatcher function
def dispatcher(name, **kwargs):
    if name == 'calculate_area':
        return kwargs['width'] * kwargs['height']

# Create callable tool
calculate_area = mk_tool(dispatcher, tool)

# Use the tool
result = calculate_area(width=5.0, height=3.0)
print(result)  # Output: 15.0
print(calculate_area.__doc__)  # Output: Calculate the area of a rectangle
```

--------------------------------

### Read and Convert HTML to Markdown with CSS Selectors

Source: https://github.com/answerdotai/toolslm/blob/main/03_download.ipynb

Fetches HTML from a URL, optionally selects elements using a CSS selector, and converts the result to clean markdown. Can handle single or multiple selections and wrap multi-selections with a specified tag.

```python
def read_html(url, # URL to read
              sel=None, # Read only outerHTML of CSS selector `sel`
              rm_comments=True, # Removes HTML comments
              rm_details=True, # Removes `<details>` tags
              multi=False, # Get all matches to `sel` or first one  
              wrap_tag=None, #If multi, each selection wrapped with <wrap_tag>content</wrap_tag>
              ignore_links=True,
             ):
    """Get `url`, optionally selecting CSS selector `sel`, and convert to clean markdown"""
    page = get(url).text
    if sel:
        from bs4 import BeautifulSoup
        soup = BeautifulSoup(page, 'html.parser')
        if multi:
            page = [str(el) for el in soup.select(sel)]
            if not wrap_tag: page = "\n".join(page)
        else: page = str(soup.select_one(sel))
    mds = map(lambda x: clean_md(html2md(x, ignore_links=ignore_links), rm_comments, rm_details=rm_details), tuplify(page))
    if wrap_tag: return '\n'.join([f"\n<{wrap_tag}>\n{o}</{wrap_tag}>\n" for o in mds])
    else: return'\n'.join(mds)
```

--------------------------------

### Generate XML context from folders

Source: https://context7.com/answerdotai/toolslm/llms.txt

Converts folder contents to XML, supporting file filtering, size limits, and signature-only modes.

```python
from toolslm.xml import folder2ctx

# Basic usage - convert a folder to XML context
xml_context = folder2ctx('src/', file_glob='*.py')
print(xml_context)
# Output:
# <documents><document index="1"><src>
# src/main.py
# </src><document-content>
# def hello():
#     print("Hello, World!")
# </document-content></document></documents>

# With Anthropic's suggested prose intro and file type filtering
xml_context = folder2ctx(
    'project/',
    prefix=True,  # Include prose intro
    types='py,js',  # Only Python and JavaScript files
    max_size=50000,  # Skip files larger than 50KB
    max_total=1000000,  # Max total output size
    sigs_only=True  # Only include signatures and docstrings
)

# Get file listing without content (for planning)
file_sizes = folder2ctx('src/', files_only=True)
# Returns: {'main.py': 1234, 'utils.py': 5678}
```

--------------------------------

### Generate Schema for Parameterized Dictionary

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates schema generation for a function parameter typed as a parameterized dictionary (`Dict[str, int]`).

```python
def _dict_test(d: Dict[str, int]):
    "Mandatory docstring"
    pass
get_schema(_dict_test)
```

--------------------------------

### Convert GitHub Repo to Context with Filters

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Converts a GitHub repository to context, filtering by file extensions and skipping files matching a regex. The `out=False` argument prevents the inclusion of notebook cell outputs.

```python
#| eval: false
print(repo2ctx('answerdotai/toolslm', exts=('ipynb','py'), skip_file_re='^_', out=False, max_total=500))
```

--------------------------------

### Split URL into Base, Path, and Filename

Source: https://github.com/answerdotai/toolslm/blob/main/03_download.ipynb

Splits a URL into its base, path, and filename components. Normalizes an empty filename to '/'.

```python
#| export
def split_url(url):
    """Split `url` into base, path, and file name, normalising name to '/' if empty"""
    parsed = urlparse(url.strip('/'))
    base = f"{parsed.scheme}://{parsed.netloc}"
    path,spl,fname = parsed.path.rpartition('/')
    fname = spl+fname
    if not path and not fname: path='/'
    return base,path,fname
```

--------------------------------

### Create Namespace for Callable Functions

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Creates a namespace dictionary from various inputs (mappings, callables, dictionaries). Useful for defining allowed functions for LLMs to call, preventing security risks.

```python
#| export
def mk_ns(fs):
    if isinstance(fs, abc.Mapping): return fs
    merged = {}
    for o in listify(fs):
        if isinstance(o, dict): merged |= o
        elif callable(o) and hasattr(o, '__name__'): merged |= {o.__name__: o}
    return merged
```

--------------------------------

### Python: repo2ctx

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Python function to convert a GitHub repository into XML context without requiring a local clone.

```APIDOC
## repo2ctx

### Description
Converts a GitHub repository to XML context. It can accept a full GitHub URL, or owner/repo strings.

### Parameters
- **owner** (str) - Required - GitHub repo owner, "owner/repo", or full GitHub URL
- **repo** (str) - Optional - GitHub repo name
- **ref** (str) - Optional - Git ref (branch/tag/sha)
- **folder** (str) - Optional - Only include files under this path
- **token** (str) - Optional - GitHub token (uses GITHUB_TOKEN env var if None)

### Response
- **Returns** (str/dict) - XML string for LM context or a dictionary of file sizes if files_only is set.
```

--------------------------------

### Symbol Files Package API

Source: https://github.com/answerdotai/toolslm/blob/main/05_inspecttools.ipynb

Retrieves the XML context of all files within the top-level package of a given symbol.

```APIDOC
## GET /symfiles_package

### Description
Return XML context of all files in `sym`'s top-level package.

### Method
GET

### Endpoint
/symfiles_package

### Parameters
#### Query Parameters
- **sym** (str) - Required - Dotted symbol path or "_last" for previous result
- **kwargs** - Optional - Additional keyword arguments to pass to `sym2pkgctx`.

### Response
#### Success Response (200)
- **xml_context** (str) - The XML context of the files in the package.

#### Error Response (404)
- **error** (str) - Description of the error if the symbol is not found.

### Response Example
```json
{
  "xml_context": "<files>...</files>"
}
```
```

--------------------------------

### Generate XML for Source and Document

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Converts source and document objects into XML strings.

```python
to_xml(Src('a'))
```

```python
to_xml(Document('a'))
```

--------------------------------

### Accessing docments output as AttrDict

Source: https://github.com/answerdotai/toolslm/blob/main/01_funccall.ipynb

Demonstrates accessing schema information using attribute notation or dictionary keys.

```python
d.a.docment, d['a']['anno']

```

--------------------------------

### Interactive Shell Execution

Source: https://context7.com/answerdotai/toolslm/llms.txt

Provides an IPython-based shell environment for executing code cells with timeout support.

```python
from toolslm.shell import get_shell

# Create interactive shell
shell = get_shell()

# Execute code with timeout
result = shell.run_cell("import numpy as np; np.array([1,2,3])", timeout=30)
print(result.stdout)  # Output from execution

# Execute multiple cells
shell.run_cell("x = 10")
result = shell.run_cell("x * 2")
print(result.stdout)  # Output: 20
```

--------------------------------

### Convert Files to XML Context

Source: https://github.com/answerdotai/toolslm/blob/main/00_xml.ipynb

Converts a list of files into XML context, with options to control notebook output, cell IDs, line numbers, and file size limits. Uses `read_file` for individual file processing.

```python
#| export
@delegates(docs_xml)
def files2ctx(
    fnames:list[Union[str,Path]], # List of file names to add to context
    srcs:Optional[list]=None, # Use the labels instead of `fnames`
    max_size:int=None, # Skip files larger than this (bytes)
    out:bool=True, # Include notebook cell outputs?
    ids:bool=True,  # Include cell ids in notebooks?
    nums:bool=False, # Include line numbers in notebook cell source?
    sigs_only:bool=False, # Only include signatures and docstrings (where supported by `codesigs` lib)
    **kwargs
)->str: # XML for LM context
    """Convert files to XML context, handling notebooks"""
    fnames = [Path(o).expanduser() for o in listify(fnames)]
    contents = [read_file(o, max_size=max_size, out=out, ids=ids, sigs_only=sigs_only, nums=nums) for o in fnames]
    return docs_xml(contents, srcs or fnames, **kwargs)
```