ipyllm 0.4.0__tar.gz → 0.6.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ipyllm
3
- Version: 0.4.0
3
+ Version: 0.6.0
4
4
  Summary: Interact with LLM models from your IPython REPL
5
5
  Author: Juan Pablo de la Cruz Gutiérrez
6
6
  Author-email: Juan Pablo de la Cruz Gutiérrez <juampatronics@gmail.com>
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
16
16
  Requires-Dist: ipython>=9.17.1
17
17
  Requires-Dist: llm>=0.36
18
18
  Requires-Dist: llm-ollama>=0.17.1
19
+ Requires-Dist: rapidfuzz>=3.0
19
20
  Requires-Dist: pyyaml>=6.0
20
21
  Requires-Python: >=3.11
21
22
  Project-URL: Homepage, https://github.com/juampatronics/ipyllm
@@ -25,7 +26,7 @@ Project-URL: Issues, https://github.com/juampatronics/ipyllm/issues
25
26
  Description-Content-Type: text/markdown
26
27
 
27
28
  <div align="center">
28
- <img src="docs/ipyllm_logo.svg" alt="Synaptic Prompt Logo" width="150"/>
29
+ <img src="https://juampatronics.com/images/ipyllm_logo.svg" alt="Synaptic Prompt Logo" width="150"/>
29
30
  <br/>
30
31
  <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Abuild" alt="Build">
31
32
  <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=build" alt="Build"/>
@@ -44,7 +45,8 @@ Description-Content-Type: text/markdown
44
45
  # ipyllm
45
46
 
46
47
  An IPython extension for discussing your interactive Python session with models
47
- supported by the [`llm`](https://llm.datasette.io/) Python package.
48
+ supported by the [`llm`](https://llm.datasette.io/) Python package. For a detailed description,
49
+ as well as a discussion of use cases, please refer to the [blog](https://juampatronics.com/tags/ipyllm/).
48
50
 
49
51
  ## Install and load
50
52
 
@@ -75,10 +77,13 @@ configure provider keys using `llm keys set PROVIDER`.
75
77
  The [MkDocs documentation](docs/index.md) covers installation, model
76
78
  configuration, prompts, adding files to the context, command-output and
77
79
  last-error diagnosis, debugging with `ipyllm.embed`, available tools, Agent
78
- Skills,
80
+ Skills, per-prompt and per-model token usage,
79
81
  approval settings, and safety. Preview or build the site with:
80
82
 
81
83
  ```console
82
84
  uv run mkdocs serve
83
85
  uv run mkdocs build
84
86
  ```
87
+
88
+ An online version is available at the [homepage](https://juampatronics.com/ipyllm/).
89
+
@@ -1,5 +1,5 @@
1
1
  <div align="center">
2
- <img src="docs/ipyllm_logo.svg" alt="Synaptic Prompt Logo" width="150"/>
2
+ <img src="https://juampatronics.com/images/ipyllm_logo.svg" alt="Synaptic Prompt Logo" width="150"/>
3
3
  <br/>
4
4
  <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Abuild" alt="Build">
5
5
  <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=build" alt="Build"/>
@@ -18,7 +18,8 @@
18
18
  # ipyllm
19
19
 
20
20
  An IPython extension for discussing your interactive Python session with models
21
- supported by the [`llm`](https://llm.datasette.io/) Python package.
21
+ supported by the [`llm`](https://llm.datasette.io/) Python package. For a detailed description,
22
+ as well as a discussion of use cases, please refer to the [blog](https://juampatronics.com/tags/ipyllm/).
22
23
 
23
24
  ## Install and load
24
25
 
@@ -49,10 +50,13 @@ configure provider keys using `llm keys set PROVIDER`.
49
50
  The [MkDocs documentation](docs/index.md) covers installation, model
50
51
  configuration, prompts, adding files to the context, command-output and
51
52
  last-error diagnosis, debugging with `ipyllm.embed`, available tools, Agent
52
- Skills,
53
+ Skills, per-prompt and per-model token usage,
53
54
  approval settings, and safety. Preview or build the site with:
54
55
 
55
56
  ```console
56
57
  uv run mkdocs serve
57
58
  uv run mkdocs build
58
59
  ```
60
+
61
+ An online version is available at the [homepage](https://juampatronics.com/ipyllm/).
62
+
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ipyllm"
3
- version = "0.4.0"
3
+ version = "0.6.0"
4
4
  description = "Interact with LLM models from your IPython REPL"
5
5
  readme = "README.md"
6
6
  license-files = ["LICENSE"]
@@ -10,6 +10,7 @@ dependencies = [
10
10
  "ipython>=9.17.1",
11
11
  "llm>=0.36",
12
12
  "llm-ollama>=0.17.1",
13
+ "rapidfuzz>=3.0",
13
14
  "pyyaml>=6.0",
14
15
  ]
15
16
  classifiers = [
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ipyllm"
3
- version = "0.4.0"
3
+ version = "0.6.0"
4
4
  description = "Interact with LLM models from your IPython REPL"
5
5
  readme = "README.md"
6
6
  license-files = ["LICENSE"]
@@ -13,6 +13,7 @@ dependencies = [
13
13
  "ipython>=9.17.1",
14
14
  "llm>=0.36",
15
15
  "llm-ollama>=0.17.1",
16
+ "rapidfuzz>=3.0",
16
17
  "pyyaml>=6.0",
17
18
  ]
18
19
  classifiers = [
@@ -0,0 +1,252 @@
1
+ # Copyright 2026 Juan Pablo de la Cruz Gutiérrez
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """Autocomplete local file and directory names for ``@`` prompt references.
16
+
17
+ When the user types ``@`` at the start of a word, IPython offers the entries
18
+ of the referenced directory (files and subdirectories, the latter with a
19
+ trailing ``/``) so paths can be assembled one tab at a time.
20
+
21
+ Typing ``@@`` instead triggers a fuzzy search over the whole current
22
+ directory tree (via ``rapidfuzz``); the chosen match replaces the ``@@``
23
+ trigger and the loose query with a single ``@`` reference.
24
+ """
25
+
26
+ import os
27
+ import re
28
+
29
+ from rapidfuzz import fuzz, process, utils
30
+
31
+
32
+ def _word_at(line: str, index: int) -> bool:
33
+ """Return True when the character at ``index`` starts a word in ``line``."""
34
+ return index == 0 or line[index - 1].isspace()
35
+
36
+
37
+ def _completion(text: str, kind: str = "file"):
38
+ from IPython.core.completer import SimpleCompletion
39
+
40
+ return SimpleCompletion(text=text, type=kind)
41
+
42
+
43
+ def _list_matches(base: str, fragment: str) -> list:
44
+ try:
45
+ entries = sorted(os.listdir(base))
46
+ except OSError:
47
+ return []
48
+ matches = []
49
+ for entry in entries:
50
+ if not entry.startswith(fragment):
51
+ continue
52
+ full = os.path.join(base, entry) if base != os.curdir else entry
53
+ if os.path.isdir(full):
54
+ matches.append(_completion(entry + "/"))
55
+ else:
56
+ matches.append(_completion(entry))
57
+ return matches
58
+
59
+
60
+ class AtFileMatcher:
61
+ """An IPython completion matcher (API v2) that completes ``@`` paths.
62
+
63
+ A no-op (empty result, other matchers proceed) unless the token being
64
+ completed is directly preceded by an ``@`` that starts a word. This keeps
65
+ emails and other in-word ``@`` characters untouched.
66
+ """
67
+
68
+ matcher_api_version = 2
69
+ matcher_identifier = "ipyllm.at_file_matcher"
70
+
71
+ def __init__(self) -> None:
72
+ # _get_matcher_id falls back to ``__qualname__`` when reading the id,
73
+ # which is evaluated eagerly; provide it so instances resolve cleanly.
74
+ self.__qualname__ = "ipyllm.completer.AtFileMatcher"
75
+
76
+ def __call__(self, context) -> dict:
77
+ token = context.token
78
+ prefix = context.text_until_cursor
79
+ before = prefix[:-len(token)] if token else prefix
80
+
81
+ if not before.endswith("@"):
82
+ return self._result([])
83
+ at_index = len(before) - 1
84
+ if not _word_at(before, at_index):
85
+ return self._result([])
86
+
87
+ if token:
88
+ base = os.path.dirname(token) or os.curdir
89
+ fragment = os.path.basename(token)
90
+ else:
91
+ base = os.curdir
92
+ fragment = ""
93
+
94
+ matches = _list_matches(base, fragment)
95
+ return self._result(matches)
96
+
97
+ @staticmethod
98
+ def _result(completions: list) -> dict:
99
+ return {
100
+ "completions": completions,
101
+ "suppress": bool(completions),
102
+ "ordered": True,
103
+ }
104
+
105
+
106
+ at_file_matcher = AtFileMatcher()
107
+
108
+
109
+ # Directories that never hold files a user would reference; skipped while
110
+ # scanning for the fuzzy index.
111
+ _IGNORED_DIRS = {
112
+ ".git",
113
+ "__pycache__",
114
+ "node_modules",
115
+ ".venv",
116
+ "venv",
117
+ ".mypy_cache",
118
+ ".pytest_cache",
119
+ ".ipynb_checkpoints",
120
+ ".idea",
121
+ "site-packages",
122
+ "dist-packages",
123
+ }
124
+ _MAX_INDEXED_ENTRIES = 20_000
125
+ _SCORE_CUTOFF = 45
126
+ _DEFAULT_LIMIT = 25
127
+
128
+ # The double-@ trigger followed by a loose query (spaces allowed) up to the
129
+ # cursor, optionally inside quotes; anchored so the query ends at the cursor.
130
+ _FUZZY_TRIGGER = re.compile(r"@@([^'\"\n]*)$")
131
+
132
+ _index_root: str | None = None
133
+ _index_paths: list[str] = []
134
+
135
+
136
+ def _scan_tree(root: str) -> list[str]:
137
+ """Collect relative paths under ``root``: files, and dirs with a trailing ``/``."""
138
+ paths: list[str] = []
139
+ for dirpath, dirnames, filenames in os.walk(root):
140
+ dirnames[:] = sorted(d for d in dirnames if d not in _IGNORED_DIRS)
141
+ base = os.path.relpath(dirpath, root)
142
+ if base == os.curdir:
143
+ base = ""
144
+ for name in sorted(filenames):
145
+ paths.append(os.path.join(base, name).replace(os.sep, "/") if base else name)
146
+ if len(paths) >= _MAX_INDEXED_ENTRIES:
147
+ return paths
148
+ for name in dirnames:
149
+ rel = os.path.join(base, name) if base else name
150
+ paths.append(rel.replace(os.sep, "/") + "/")
151
+ return paths
152
+
153
+
154
+ def _fuzzy_search(query: str, limit: int) -> list[tuple[str, str]]:
155
+ """Fuzzy-match ``query`` against the current directory tree.
156
+
157
+ Returns ``(path, kind)`` pairs best match first; kind is ``"dir"`` when
158
+ the path is a directory (marked with a trailing ``/``).
159
+ """
160
+ global _index_root, _index_paths
161
+ root = os.getcwd()
162
+ if root != _index_root: # first use or the working directory changed
163
+ _index_root = root
164
+ _index_paths = _scan_tree(root)
165
+
166
+ if not query.strip():
167
+ return [(p, "dir" if p.endswith("/") else "file") for p in _index_paths[:limit]]
168
+
169
+ hits = process.extract(
170
+ query,
171
+ _index_paths,
172
+ scorer=fuzz.WRatio,
173
+ processor=utils.default_process,
174
+ limit=limit,
175
+ score_cutoff=_SCORE_CUTOFF,
176
+ )
177
+ return [
178
+ (_index_paths[i], "dir" if _index_paths[i].endswith("/") else "file")
179
+ for _, _score, i in hits
180
+ ]
181
+
182
+
183
+ class FuzzyFileMatcher:
184
+ """An IPython completion matcher (API v2) for fuzzy ``@@`` references.
185
+
186
+ A no-op (empty result, other matchers proceed) unless the text before the
187
+ cursor ends with a word-leading ``@@``. In that case the query after the
188
+ trigger (which may contain spaces) is fuzzy-matched against the whole
189
+ current directory tree, and each candidate replaces the trigger and query
190
+ with a single-``@`` reference so ``%llm`` resolves it as a file.
191
+ """
192
+
193
+ matcher_api_version = 2
194
+ matcher_identifier = "ipyllm.fuzzy_file_matcher"
195
+
196
+ def __init__(self) -> None:
197
+ # _get_matcher_id falls back to ``__qualname__`` when reading the id,
198
+ # which is evaluated eagerly; provide it so instances resolve cleanly.
199
+ self.__qualname__ = "ipyllm.completer.FuzzyFileMatcher"
200
+
201
+ def __call__(self, context) -> dict:
202
+ text = context.text_until_cursor
203
+ match = _FUZZY_TRIGGER.search(text)
204
+ if not match:
205
+ return self._result([])
206
+ if text[: match.start()] and not text[match.start() - 1].isspace():
207
+ return self._result([]) # not word-leading; e.g. a double-@ in a word
208
+
209
+ query = match.group(1)
210
+ limit = context.limit or _DEFAULT_LIMIT
211
+ hits = _fuzzy_search(query, limit)
212
+ completions = [_completion("@" + path, kind) for path, kind in hits]
213
+ return self._result(
214
+ completions,
215
+ matched_fragment=text[match.start():], # replace "@@query"
216
+ )
217
+
218
+ @staticmethod
219
+ def _result(completions: list, matched_fragment: str | None = None) -> dict:
220
+ result = {
221
+ "completions": completions,
222
+ "suppress": bool(completions),
223
+ "ordered": True,
224
+ }
225
+ if matched_fragment is not None:
226
+ result["matched_fragment"] = matched_fragment
227
+ return result
228
+
229
+
230
+ fuzzy_file_matcher = FuzzyFileMatcher()
231
+
232
+
233
+ def install_completer(shell) -> None:
234
+ """Register the ``@`` and ``@@`` file matchers on ``shell``'s completer."""
235
+ completer = getattr(shell, "Completer", None)
236
+ if completer is None:
237
+ return
238
+ for matcher in (at_file_matcher, fuzzy_file_matcher):
239
+ if matcher not in completer.custom_matchers:
240
+ completer.custom_matchers.append(matcher)
241
+
242
+
243
+ def uninstall_completer(shell) -> None:
244
+ """Remove the ``@`` and ``@@`` file matchers from ``shell``, if present."""
245
+ completer = getattr(shell, "Completer", None)
246
+ if completer is None:
247
+ return
248
+ for matcher in (at_file_matcher, fuzzy_file_matcher):
249
+ try:
250
+ completer.custom_matchers.remove(matcher)
251
+ except ValueError:
252
+ pass
@@ -0,0 +1,72 @@
1
+ # Copyright 2026 Juan Pablo de la Cruz Gutiérrez
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ import configparser
16
+ from pathlib import Path
17
+
18
+ from IPython.core.error import UsageError
19
+
20
+ CONFIG_FILE = ".ipyllmrc"
21
+ CONFIG_SECTION = "ipyllm"
22
+ CONFIG_KEYS = ("model", "require_approval", "debug", "save_session", "chain_limit")
23
+
24
+
25
+ def find_config_file() -> Path | None:
26
+ """Return the config file to use: current directory first, then ``$HOME``."""
27
+ for candidate in (Path.cwd() / CONFIG_FILE, Path.home() / CONFIG_FILE):
28
+ if candidate.is_file():
29
+ return candidate
30
+ return None
31
+
32
+
33
+ def read_config_values(path: Path) -> dict[str, str]:
34
+ """Parse a config file with a section, a single section, or no header."""
35
+ try:
36
+ content = path.read_text(encoding="utf-8")
37
+ except OSError as exc:
38
+ raise UsageError(f"Cannot read config file {path}: {exc}") from exc
39
+ parser = configparser.ConfigParser(interpolation=None)
40
+ try:
41
+ parser.read_string(content)
42
+ except configparser.MissingSectionHeaderError:
43
+ parser.read_string(f"[{CONFIG_SECTION}]\n{content}")
44
+ except configparser.Error as exc:
45
+ raise UsageError(f"Cannot parse config file {path}: {exc}") from exc
46
+ if CONFIG_SECTION in parser:
47
+ selected = parser[CONFIG_SECTION]
48
+ elif parser.sections():
49
+ selected = parser[parser.sections()[0]]
50
+ else:
51
+ selected = parser.defaults()
52
+ return {
53
+ key: value for key, value in selected.items() if key not in ("DEFAULT", "__name__")
54
+ }
55
+
56
+
57
+ def parse_bool(value: str, key: str) -> bool:
58
+ normalized = value.strip().lower()
59
+ if normalized in {"1", "true", "on", "yes", "y"}:
60
+ return True
61
+ if normalized in {"0", "false", "off", "no", "n"}:
62
+ return False
63
+ raise ValueError(f"expected on or off, got {value!r}")
64
+
65
+
66
+ def format_config_file(values: dict[str, str]) -> str:
67
+ """Render config values as an ``.ipyllmrc`` document."""
68
+ lines = [f"[{CONFIG_SECTION}]"]
69
+ for key in CONFIG_KEYS:
70
+ if key in values:
71
+ lines.append(f"{key} = {values[key]}")
72
+ return "\n".join(lines) + "\n"
@@ -13,9 +13,10 @@
13
13
  # limitations under the License.
14
14
 
15
15
  import builtins
16
- import mimetypes
16
+ import os
17
17
  import re
18
18
  import shlex
19
+ import sys
19
20
  from itertools import islice
20
21
  from pathlib import Path
21
22
 
@@ -25,8 +26,16 @@ from IPython.core.interactiveshell import InteractiveShell
25
26
  from IPython.core.magic import Magics, line_cell_magic, magics_class
26
27
  from traitlets import Bool, Integer, List, Unicode
27
28
 
29
+ from .config import (
30
+ CONFIG_FILE,
31
+ find_config_file,
32
+ format_config_file,
33
+ parse_bool,
34
+ read_config_values,
35
+ )
28
36
  from .diagnostics import DiagnosticRunner
29
37
  from .recorder import SessionRecorder
38
+ from .resources import parse_resources
30
39
  from .skills import MAX_SKILL_CHARS, Skill, SkillCatalog, SkillError, discover_skills
31
40
 
32
41
  _SYSTEM_PROMPT = """\
@@ -44,10 +53,6 @@ _MAX_VARIABLES = 80
44
53
  _MAX_HISTORY_ENTRIES = 30
45
54
  _MAX_CONTEXT_CHARS = 12_000
46
55
  _MAX_REPR_CHARS = 4_000
47
- _MAX_FILE_CONTENT_CHARS = 12_000
48
- _MAX_DIR_FILES = 100
49
- _MEDIA_PREFIXES = ("image/", "audio/", "video/")
50
- _MEDIA_TYPES = {"application/pdf"}
51
56
  _HIDDEN_NAMES = {
52
57
  "In",
53
58
  "Out",
@@ -57,51 +62,118 @@ _HIDDEN_NAMES = {
57
62
  "quit",
58
63
  }
59
64
  _SKILL_SELECTOR = re.compile(r"^/([^\s]+)(?:\s+|$)")
60
- _AT_REFERENCE = re.compile(r"@([^\s@]+)")
61
-
62
-
63
- def _list_dir_files(root: Path) -> tuple[list[Path], bool]:
64
- """List regular files under ``root`` breadth-first, skipping hidden
65
- entries and capping the total at ``_MAX_DIR_FILES``."""
66
- files: list[Path] = []
67
- queue: list[Path] = [root]
68
- index = 0
69
- while index < len(queue) and len(files) < _MAX_DIR_FILES:
70
- directory = queue[index]
71
- index += 1
72
- try:
73
- entries = sorted(directory.iterdir())
74
- except OSError:
75
- continue
76
- for entry in entries:
77
- if entry.name.startswith("."):
78
- continue
79
- if entry.is_dir():
80
- queue.append(entry)
81
- elif entry.is_file():
82
- files.append(entry)
83
- if len(files) >= _MAX_DIR_FILES:
84
- break
85
- return files, len(files) >= _MAX_DIR_FILES
86
65
 
87
66
 
88
- def _detect_type(path: Path) -> str | None:
89
- try:
90
- from llm.utils import mimetype_from_path
67
+ # --- Readable output styling ---------------------------------------------
91
68
 
92
- detected = mimetype_from_path(str(path))
93
- if detected:
94
- return detected
95
- except Exception:
96
- pass
97
- return mimetypes.guess_type(path.name)[0]
69
+ _ANSI_DIM = "\x1b[2m"
70
+ _ANSI_RESET = "\x1b[0m"
71
+ _DISPLAY_RESULT_CHARS = 400
98
72
 
99
73
 
100
- def _display_name(path: Path) -> str:
74
+ def _color_enabled(stream) -> bool:
75
+ """Whether ANSI styling should be emitted on ``stream``."""
76
+ if os.environ.get("NO_COLOR") is not None:
77
+ return False
78
+ if os.environ.get("FORCE_COLOR") is not None:
79
+ return True
101
80
  try:
102
- return str(path.resolve().relative_to(Path.cwd()))
103
- except ValueError:
104
- return str(path)
81
+ return bool(stream.isatty())
82
+ except (AttributeError, ValueError, OSError):
83
+ return False
84
+
85
+
86
+ def _dim(text: str, enabled: bool) -> str:
87
+ """Wrap ``text`` in dim styling, or return it unchanged when disabled."""
88
+ if not enabled:
89
+ return text
90
+ return f"{_ANSI_DIM}{text}{_ANSI_RESET}"
91
+
92
+
93
+ def _truncate_display(text: str, limit: int = _DISPLAY_RESULT_CHARS) -> str:
94
+ if len(text) <= limit:
95
+ return text
96
+ return text[:limit].rstrip() + "…"
97
+
98
+
99
+ def _response_rounds(response):
100
+ """Yield the individual responses making up ``response``.
101
+
102
+ A chained (tool-call) response yields one entry per model round; a
103
+ single response yields itself. Every yielded object exposes
104
+ ``stream_events()`` and, when the provider supports it, ``usage()``.
105
+ """
106
+ rounds = getattr(response, "responses", None)
107
+ if rounds is None:
108
+ yield response
109
+ return
110
+ yield from rounds()
111
+
112
+
113
+ def _display_response(response) -> tuple[int, int]:
114
+ """Print a model response with readable styling.
115
+
116
+ The model's answer text is written in the normal foreground while its
117
+ reasoning (thought) is dimmed. Intermediate tool results are rendered by
118
+ ``_display_tool_result``. When color is disabled (output is piped or
119
+ ``NO_COLOR`` is set) everything is printed as plain text.
120
+
121
+ Returns the (input, output) token counts summed across every round of the
122
+ response; each value is ``0`` when the provider did not report it.
123
+ """
124
+ stream = sys.stdout
125
+ dim = _color_enabled(stream)
126
+ total_input = 0
127
+ total_output = 0
128
+ last_char = ""
129
+ for round_response in _response_rounds(response):
130
+ first_text = True
131
+ for event in round_response.stream_events():
132
+ etype = getattr(event, "type", None)
133
+ chunk = getattr(event, "chunk", "") or ""
134
+ if etype == "text" and chunk:
135
+ if (
136
+ first_text
137
+ and last_char
138
+ and not last_char.isspace()
139
+ and not chunk[0].isspace()
140
+ ):
141
+ # Mirror the chain's round-boundary space so consecutive
142
+ # answers do not run together.
143
+ stream.write(" ")
144
+ first_text = False
145
+ if not chunk:
146
+ continue
147
+ if etype == "reasoning":
148
+ stream.write(_dim(chunk, dim))
149
+ elif etype == "text":
150
+ stream.write(chunk)
151
+ last_char = chunk[-1]
152
+ # tool_call_* / tool_result events are rendered by _display_tool_result.
153
+ stream.flush()
154
+ usage_fn = getattr(round_response, "usage", None)
155
+ if callable(usage_fn):
156
+ usage = usage_fn()
157
+ total_input += getattr(usage, "input", 0) or 0
158
+ total_output += getattr(usage, "output", 0) or 0
159
+ stream.write("\n")
160
+ stream.flush()
161
+ return total_input, total_output
162
+
163
+
164
+ def _display_tool_result(tool, tool_call, tool_result) -> None:
165
+ """Show an intermediate tool result in dim text.
166
+
167
+ Wired in as the ``after_call`` callback so each result appears dim,
168
+ between the answer text that precedes and follows it.
169
+ """
170
+ output = str(tool_result.output or "").strip()
171
+ line = f"· {tool_call.name}"
172
+ if output:
173
+ line += f": {_truncate_display(output)}"
174
+ stream = sys.stdout
175
+ stream.write(_dim(line + "\n", _color_enabled(stream)))
176
+ stream.flush()
105
177
 
106
178
 
107
179
  @magics_class
@@ -149,22 +221,30 @@ class IpyllmMagics(Magics):
149
221
  self._approval_override: bool | None = None
150
222
  self._conversation = None
151
223
  self._resume_requests: list[str] = []
224
+ self._token_usage: dict[str, dict[str, int]] = {}
152
225
  self._recorder = SessionRecorder(shell)
153
226
  self._diagnostics = DiagnosticRunner(shell, self._ask)
227
+ self._config_path: Path | None = None
228
+ self._apply_config_file()
154
229
 
155
230
  @line_cell_magic
156
231
  def llm(self, line: str, cell: str | None = None) -> None:
157
232
  """Ask the configured model a question, optionally as a cell magic.
158
233
 
159
234
  Use ``%llm --model MODEL``, ``%llm --approval on|off``,
160
- ``%llm --debug on|off``, ``%llm --skills``, ``%llm --config``, and
161
- ``%llm --reset`` to manage this session. In cell mode use
235
+ ``%llm --debug on|off``, ``%llm --skills``, ``%llm --config``,
236
+ ``%llm --save-config [FILE]``, and ``%llm --reset`` to manage this
237
+ session. Settings can be stored in a ``.ipyllmrc`` file (in the
238
+ current directory or ``$HOME``), which is loaded automatically at
239
+ startup; ``%llm --save-config`` writes the current settings to one.
240
+ In cell mode use
162
241
  ``%%llm --run`` to capture a shell command for diagnosis. Use
163
242
  ``%llm --last-error`` to have the model diagnose the most recent
164
243
  exception in this session. Start a
165
244
  prompt with ``/skill-name`` to load a local skill. Reference local
166
245
  files with ``@path`` to add them to the context (``@`` autocompletes
167
- file and directory names); several files may be referenced. A
246
+ file and directory names; ``@@`` fuzzy-searches the whole tree);
247
+ several files may be referenced. A
168
248
  single-line prompt must not end in ``?`` (IPython reserves that for
169
249
  object help); use ``%%llm`` for such questions.
170
250
  """
@@ -211,108 +291,63 @@ class IpyllmMagics(Magics):
211
291
  attachments=attachments or None,
212
292
  chain_limit=self.chain_limit,
213
293
  )
214
- print(response.text())
294
+ last_input, last_output = _display_response(response)
295
+ self._record_tokens(conversation, last_input, last_output)
215
296
  self._resume_requests.clear()
216
297
 
217
- def _parse_resources(self, prompt: str) -> tuple[str, list[str], list]:
218
- """Split ``@`` file references out of ``prompt``.
219
-
220
- Returns the cleaned prompt (each resolved reference replaced by a
221
- readable marker), a list of text-content fragments, and a list of
222
- ``llm.Attachment``. References that are not a word-leading ``@`` (for
223
- example an email address) or that do not resolve to an existing file
224
- or directory are left in the prompt unchanged.
225
- """
226
- fragments: list[str] = []
227
- attachments: list = []
228
- seen: set[Path] = set()
229
- parts: list[str] = []
230
- last = 0
231
- for match in _AT_REFERENCE.finditer(prompt):
232
- start, end = match.span()
233
- if start == 0 or prompt[start - 1].isspace():
234
- marker, frag, atts = self._resolve_reference(
235
- match.group(1), seen
236
- )
237
- parts.append(prompt[last:start])
238
- parts.append(marker)
239
- fragments.extend(frag)
240
- attachments.extend(atts)
241
- else:
242
- parts.append(prompt[last:end])
243
- last = end
244
- parts.append(prompt[last:])
245
- return "".join(parts), fragments, attachments
246
-
247
- def _resolve_reference(
248
- self, reference: str, seen: set[Path]
249
- ) -> tuple[str, list[str], list]:
250
- path = Path(reference).expanduser()
251
- if not path.is_absolute():
252
- path = Path.cwd() / path
253
-
254
- if path.is_dir():
255
- files, truncated = _list_dir_files(path)
256
- if not files:
257
- return f"[directory: {_display_name(path)} (no files)]", [], []
258
- count = f"first {len(files)} files" if truncated else f"{len(files)} files"
259
- marker = f"[directory: {_display_name(path)} ({count})]"
260
- elif path.is_file():
261
- files = [path]
262
- marker = f"[file: {_display_name(path)}]"
263
- else:
264
- return f"@{reference}", [], []
265
-
266
- fragments: list[str] = []
267
- attachments: list = []
268
- for file in files:
269
- resolved = file.resolve()
270
- if resolved in seen:
271
- continue
272
- seen.add(resolved)
273
- if self._is_media_file(file):
274
- attachments.append(llm.Attachment(path=str(file)))
275
- else:
276
- content = self._read_text_resource(file)
277
- fragments.append(
278
- f"[file: {_display_name(file)}]\n{content}"
279
- )
280
- return marker, fragments, attachments
281
-
282
- def _is_media_file(self, path: Path) -> bool:
283
- detected = _detect_type(path)
284
- if detected is None:
285
- return False
286
- return detected.startswith(_MEDIA_PREFIXES) or detected in _MEDIA_TYPES
287
-
288
- def _read_text_resource(self, path: Path) -> str:
289
- detected = _detect_type(path) or ""
290
- is_known_text = detected.startswith("text/")
291
- try:
292
- with path.open("rb") as handle:
293
- raw = handle.read(_MAX_FILE_CONTENT_CHARS * 4 + 4)
294
- except OSError as exc:
295
- raise UsageError(f"Cannot read {path}: {exc}") from exc
296
- if b"\x00" in raw[:8192]:
297
- raise UsageError(
298
- f"{path} is not a text file and this model cannot attach it. "
299
- "Use an image, audio, video, or PDF, or convert it to a text "
300
- "file."
298
+ def _model_name(self, conversation) -> str:
299
+ """Best-effort human-readable name of the conversation's model."""
300
+ model = getattr(conversation, "model", None)
301
+ for attr in ("model_id", "id", "name"):
302
+ value = getattr(model, attr, None)
303
+ if value:
304
+ return str(value)
305
+ return "model"
306
+
307
+ def _record_tokens(self, conversation, input_tokens: int, output_tokens: int) -> None:
308
+ """Add this prompt's tokens to the per-model session totals and show them."""
309
+ name = self._model_name(conversation)
310
+ totals = self._token_usage.setdefault(
311
+ name, {"in": 0, "out": 0, "prompts": 0}
312
+ )
313
+ totals["in"] += input_tokens
314
+ totals["out"] += output_tokens
315
+ totals["prompts"] += 1
316
+ self._display_token_line(name, input_tokens, output_tokens)
317
+
318
+ def _display_token_line(self, name: str, input_tokens: int, output_tokens: int) -> None:
319
+ """Print the per-prompt and per-model session token totals."""
320
+ totals = self._token_usage[name]
321
+ last = input_tokens + output_tokens
322
+ total = totals["in"] + totals["out"]
323
+ line = (
324
+ f"tokens · last prompt: {last} ({input_tokens} in, {output_tokens} out) · "
325
+ f"session: {total} ({totals['in']} in, {totals['out']} out) · "
326
+ f"model: {name}"
327
+ )
328
+ stream = sys.stdout
329
+ stream.write(_dim(line, _color_enabled(stream)))
330
+ stream.write("\n")
331
+ stream.flush()
332
+
333
+ def _print_token_totals(self) -> None:
334
+ """Show the per-model token totals accumulated this session."""
335
+ if not self._token_usage:
336
+ print("No token usage recorded yet.")
337
+ return
338
+ print("Token usage for this session:")
339
+ for name in self._token_usage:
340
+ totals = self._token_usage[name]
341
+ total = totals["in"] + totals["out"]
342
+ print(
343
+ f" {name}: {total} tokens "
344
+ f"({totals['in']} in, {totals['out']} out) "
345
+ f"over {totals['prompts']} prompt(s)"
301
346
  )
302
- try:
303
- content = raw.decode("utf-8")
304
- except UnicodeDecodeError:
305
- if is_known_text:
306
- content = raw.decode("utf-8", errors="ignore")
307
- else:
308
- raise UsageError(
309
- f"{path} is not a text file and this model cannot attach it. "
310
- "Use an image, audio, video, or PDF, or convert it to a "
311
- "text file."
312
- ) from None
313
- if len(content) > _MAX_FILE_CONTENT_CHARS:
314
- content = content[:_MAX_FILE_CONTENT_CHARS]
315
- return content
347
+
348
+ def _parse_resources(self, prompt: str) -> tuple[str, list[str], list]:
349
+ """Resolve local file references in a prompt."""
350
+ return parse_resources(prompt)
316
351
 
317
352
  def _resume_request_context(self) -> str:
318
353
  if not self._resume_requests:
@@ -343,7 +378,7 @@ class IpyllmMagics(Magics):
343
378
  if command == "--help" and len(args) == 1:
344
379
  print(
345
380
  "%llm PROMPT | %%llm PROMPT\n"
346
- " (reference files with @path; @ autocompletes names)\n"
381
+ " (reference files with @path; @ autocompletes names; @@ fuzzy-searches)\n"
347
382
  " (a single-line prompt must not end in '?'; use %%llm for it)\n"
348
383
  "%%llm --run [diagnostic request]\n"
349
384
  "%llm --last-error [diagnostic request]\n"
@@ -355,6 +390,8 @@ class IpyllmMagics(Magics):
355
390
  "%llm --resume FILE.py\n"
356
391
  "%llm --chain-limit N\n"
357
392
  "%llm --config\n"
393
+ "%llm --tokens\n"
394
+ "%llm --save-config [FILE]\n"
358
395
  "%llm --reset"
359
396
  )
360
397
  return True
@@ -375,8 +412,7 @@ class IpyllmMagics(Magics):
375
412
  self._recorder.enable(args[1])
376
413
  return True
377
414
  if command == "--resume" and len(args) == 2:
378
- self._resume_requests = self._recorder.resume(args[1])
379
- self._conversation = None
415
+ self._resume_session(args[1])
380
416
  return True
381
417
  if command == "--chain-limit" and len(args) == 2:
382
418
  try:
@@ -396,18 +432,26 @@ class IpyllmMagics(Magics):
396
432
  model_id = self._model_id or self.model or "llm default"
397
433
  approval = self._current_approval_policy()
398
434
  save_path = self._recorder.save_path or "off"
435
+ source = self._config_path or "defaults"
399
436
  print(
400
437
  f"Model: {model_id}\n"
401
438
  f"Require execution approval: {approval}\n"
402
439
  f"Show execution tracebacks: {self.debug}\n"
403
440
  f"Save session to: {save_path}\n"
404
- f"Chain limit: {self.chain_limit}"
441
+ f"Chain limit: {self.chain_limit}\n"
442
+ f"Config file: {source}"
405
443
  )
406
444
  return True
445
+ if command == "--tokens" and len(args) == 1:
446
+ self._print_token_totals()
447
+ return True
448
+ if command == "--save-config" and len(args) in (1, 2):
449
+ target = args[1] if len(args) == 2 else None
450
+ self._save_config(target)
451
+ return True
407
452
  if command == "--model" and len(args) == 2:
408
453
  llm.get_model(args[1])
409
- self._model_id = args[1]
410
- self._conversation = None
454
+ self._set_model_id(args[1])
411
455
  print(f"Using LLM model {args[1]!r}. Conversation reset.")
412
456
  return True
413
457
  if command == "--approval" and len(args) == 2:
@@ -430,9 +474,80 @@ class IpyllmMagics(Magics):
430
474
  "`%llm --debug on|off`, "
431
475
  "`%llm --skills`, `%llm --save FILE.py|off`, "
432
476
  "`%llm --resume FILE.py`, `%llm --chain-limit N`, "
433
- "`%llm --config`, `%llm --reset`."
477
+ "`%llm --config`, `%llm --tokens`, `%llm --save-config [FILE]`, `%llm --reset`."
434
478
  )
435
479
 
480
+ def _apply_config_file(self) -> None:
481
+ """Load ``.ipyllmrc`` (current dir, then ``$HOME``) and apply values.
482
+
483
+ Present entries override the defaults; missing entries keep their
484
+ defaults. Problems are reported to the user but never prevent the
485
+ extension from loading.
486
+ """
487
+ path = find_config_file()
488
+ if path is None:
489
+ return
490
+ self._config_path = path
491
+ try:
492
+ values = read_config_values(path)
493
+ except UsageError as exc:
494
+ print(f"Warning: {exc}; using defaults.", file=sys.stderr)
495
+ return
496
+ for key, value in values.items():
497
+ self._apply_config_value(key, value)
498
+
499
+ def _apply_config_value(self, key: str, value: str) -> None:
500
+ """Apply a single config entry, reporting (not raising) on bad values."""
501
+ try:
502
+ if key == "model":
503
+ value = value.strip()
504
+ if value:
505
+ self._set_model_id(value)
506
+ elif key == "require_approval":
507
+ self.require_approval = parse_bool(value, key)
508
+ elif key == "debug":
509
+ self.debug = parse_bool(value, key)
510
+ elif key == "save_session":
511
+ value = value.strip()
512
+ if value and value.lower() != "off":
513
+ self._recorder.enable(value)
514
+ elif key == "chain_limit":
515
+ limit = int(value)
516
+ if limit < 1:
517
+ raise ValueError("must be a positive integer")
518
+ self.chain_limit = limit
519
+ else:
520
+ print(
521
+ f"Warning: ignoring unknown config key {key!r} in .ipyllmrc.",
522
+ file=sys.stderr,
523
+ )
524
+ except (ValueError, UsageError) as exc:
525
+ print(
526
+ f"Warning: invalid {key!r} in .ipyllmrc ({exc}); using default.",
527
+ file=sys.stderr,
528
+ )
529
+
530
+ def _save_config(self, filename: str | None) -> None:
531
+ """Write the current config values to ``.ipyllmrc`` (or ``filename``)."""
532
+ path = (
533
+ Path(filename).expanduser()
534
+ if filename
535
+ else Path.cwd() / CONFIG_FILE
536
+ )
537
+ values = {
538
+ "model": self._model_id or (self.model or ""),
539
+ "require_approval": "on" if self._current_approval_policy() else "off",
540
+ "debug": "on" if self.debug else "off",
541
+ "save_session": str(self._recorder.save_path or "off"),
542
+ "chain_limit": str(self.chain_limit),
543
+ }
544
+ try:
545
+ path.write_text(format_config_file(values), encoding="utf-8")
546
+ except OSError as exc:
547
+ raise UsageError(f"Cannot write config file {path}: {exc}") from exc
548
+ self._config_path = path
549
+ print(f"Saved config to {path}.")
550
+
436
551
  def _discover_skills(self) -> SkillCatalog:
437
552
  return discover_skills(self.skill_paths)
438
553
 
@@ -496,10 +611,23 @@ class IpyllmMagics(Magics):
496
611
  self.execute_code,
497
612
  ],
498
613
  before_call=self._before_tool_call,
614
+ after_call=_display_tool_result,
499
615
  chain_limit=self.chain_limit,
500
616
  )
501
617
  return self._conversation
502
618
 
619
+ def _invalidate_conversation(self) -> None:
620
+ self._conversation = None
621
+
622
+ def _set_model_id(self, model_id: str) -> None:
623
+ self._model_id = model_id
624
+ self._invalidate_conversation()
625
+
626
+ def _resume_session(self, filename: str) -> None:
627
+ requests = self._recorder.resume(filename)
628
+ self._invalidate_conversation()
629
+ self._resume_requests = requests
630
+
503
631
  def _current_approval_policy(self) -> bool:
504
632
  if self._approval_override is not None:
505
633
  return self._approval_override
@@ -602,4 +730,4 @@ class IpyllmMagics(Magics):
602
730
 
603
731
  def reset(self) -> None:
604
732
  """Clear conversation state without changing model or approval settings."""
605
- self._conversation = None
733
+ self._invalidate_conversation()
@@ -0,0 +1,164 @@
1
+ # Copyright 2026 Juan Pablo de la Cruz Gutiérrez
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ import mimetypes
16
+ import re
17
+ from pathlib import Path
18
+
19
+ import llm
20
+ from IPython.core.error import UsageError
21
+
22
+ MAX_FILE_CONTENT_CHARS = 12_000
23
+ MAX_DIR_FILES = 100
24
+ MEDIA_PREFIXES = ("image/", "audio/", "video/")
25
+ MEDIA_TYPES = {"application/pdf"}
26
+ _AT_REFERENCE = re.compile(r"@([^\s@]+)")
27
+
28
+
29
+ def _list_dir_files(root: Path) -> tuple[list[Path], bool]:
30
+ """List regular files breadth-first, skipping hidden entries and capping size."""
31
+ files: list[Path] = []
32
+ queue: list[Path] = [root]
33
+ index = 0
34
+ while index < len(queue) and len(files) < MAX_DIR_FILES:
35
+ directory = queue[index]
36
+ index += 1
37
+ try:
38
+ entries = sorted(directory.iterdir())
39
+ except OSError:
40
+ continue
41
+ for entry in entries:
42
+ if entry.name.startswith("."):
43
+ continue
44
+ if entry.is_dir():
45
+ queue.append(entry)
46
+ elif entry.is_file():
47
+ files.append(entry)
48
+ if len(files) >= MAX_DIR_FILES:
49
+ break
50
+ return files, len(files) >= MAX_DIR_FILES
51
+
52
+
53
+ def _detect_type(path: Path) -> str | None:
54
+ try:
55
+ from llm.utils import mimetype_from_path
56
+
57
+ detected = mimetype_from_path(str(path))
58
+ if detected:
59
+ return detected
60
+ except Exception:
61
+ pass
62
+ return mimetypes.guess_type(path.name)[0]
63
+
64
+
65
+ def _display_name(path: Path) -> str:
66
+ try:
67
+ return str(path.resolve().relative_to(Path.cwd()))
68
+ except ValueError:
69
+ return str(path)
70
+
71
+
72
+ def _is_media_file(path: Path) -> bool:
73
+ detected = _detect_type(path)
74
+ if detected is None:
75
+ return False
76
+ return detected.startswith(MEDIA_PREFIXES) or detected in MEDIA_TYPES
77
+
78
+
79
+ def _read_text_resource(path: Path) -> str:
80
+ detected = _detect_type(path) or ""
81
+ is_known_text = detected.startswith("text/")
82
+ try:
83
+ with path.open("rb") as handle:
84
+ raw = handle.read(MAX_FILE_CONTENT_CHARS * 4 + 4)
85
+ except OSError as exc:
86
+ raise UsageError(f"Cannot read {path}: {exc}") from exc
87
+ if b"\x00" in raw[:8192]:
88
+ raise UsageError(
89
+ f"{path} is not a text file and this model cannot attach it. "
90
+ "Use an image, audio, video, or PDF, or convert it to a text "
91
+ "file."
92
+ )
93
+ try:
94
+ content = raw.decode("utf-8")
95
+ except UnicodeDecodeError:
96
+ if is_known_text:
97
+ content = raw.decode("utf-8", errors="ignore")
98
+ else:
99
+ raise UsageError(
100
+ f"{path} is not a text file and this model cannot attach it. "
101
+ "Use an image, audio, video, or PDF, or convert it to a "
102
+ "text file."
103
+ ) from None
104
+ if len(content) > MAX_FILE_CONTENT_CHARS:
105
+ content = content[:MAX_FILE_CONTENT_CHARS]
106
+ return content
107
+
108
+
109
+ def _resolve_reference(
110
+ reference: str, seen: set[Path]
111
+ ) -> tuple[str, list[str], list]:
112
+ path = Path(reference).expanduser()
113
+ if not path.is_absolute():
114
+ path = Path.cwd() / path
115
+
116
+ if path.is_dir():
117
+ files, truncated = _list_dir_files(path)
118
+ if not files:
119
+ return f"[directory: {_display_name(path)} (no files)]", [], []
120
+ count = f"first {len(files)} files" if truncated else f"{len(files)} files"
121
+ marker = f"[directory: {_display_name(path)} ({count})]"
122
+ elif path.is_file():
123
+ files = [path]
124
+ marker = f"[file: {_display_name(path)}]"
125
+ else:
126
+ return f"@{reference}", [], []
127
+
128
+ fragments: list[str] = []
129
+ attachments: list = []
130
+ for file in files:
131
+ resolved = file.resolve()
132
+ if resolved in seen:
133
+ continue
134
+ seen.add(resolved)
135
+ if _is_media_file(file):
136
+ attachments.append(llm.Attachment(path=str(file)))
137
+ else:
138
+ content = _read_text_resource(file)
139
+ fragments.append(f"[file: {_display_name(file)}]\n{content}")
140
+ return marker, fragments, attachments
141
+
142
+
143
+ def parse_resources(prompt: str) -> tuple[str, list[str], list]:
144
+ """Replace resolvable ``@path`` references and collect their contents."""
145
+ fragments: list[str] = []
146
+ attachments: list = []
147
+ seen: set[Path] = set()
148
+ parts: list[str] = []
149
+ last = 0
150
+ for match in _AT_REFERENCE.finditer(prompt):
151
+ start, end = match.span()
152
+ if start == 0 or prompt[start - 1].isspace():
153
+ marker, resource_fragments, resource_attachments = _resolve_reference(
154
+ match.group(1), seen
155
+ )
156
+ parts.append(prompt[last:start])
157
+ parts.append(marker)
158
+ fragments.extend(resource_fragments)
159
+ attachments.extend(resource_attachments)
160
+ else:
161
+ parts.append(prompt[last:end])
162
+ last = end
163
+ parts.append(prompt[last:])
164
+ return "".join(parts), fragments, attachments
@@ -1,119 +0,0 @@
1
- # Copyright 2026 Juan Pablo de la Cruz Gutiérrez
2
- #
3
- # Licensed under the Apache License, Version 2.0 (the "License");
4
- # you may not use this file except in compliance with the License.
5
- # You may obtain a copy of the License at
6
- #
7
- # http://www.apache.org/licenses/LICENSE-2.0
8
- #
9
- # Unless required by applicable law or agreed to in writing, software
10
- # distributed under the License is distributed on an "AS IS" BASIS,
11
- # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
- # See the License for the specific language governing permissions and
13
- # limitations under the License.
14
-
15
- """Autocomplete local file and directory names for ``@`` prompt references.
16
-
17
- When the user types ``@`` at the start of a word, IPython offers the entries
18
- of the referenced directory (files and subdirectories, the latter with a
19
- trailing ``/``) so paths can be assembled one tab at a time.
20
- """
21
-
22
- import os
23
-
24
-
25
- def _word_at(line: str, index: int) -> bool:
26
- """Return True when the character at ``index`` starts a word in ``line``."""
27
- return index == 0 or line[index - 1].isspace()
28
-
29
-
30
- def _completion(text: str):
31
- from IPython.core.completer import SimpleCompletion
32
-
33
- return SimpleCompletion(text=text, type="file")
34
-
35
-
36
- def _list_matches(base: str, fragment: str) -> list:
37
- try:
38
- entries = sorted(os.listdir(base))
39
- except OSError:
40
- return []
41
- matches = []
42
- for entry in entries:
43
- if not entry.startswith(fragment):
44
- continue
45
- full = os.path.join(base, entry) if base != os.curdir else entry
46
- if os.path.isdir(full):
47
- matches.append(_completion(entry + "/"))
48
- else:
49
- matches.append(_completion(entry))
50
- return matches
51
-
52
-
53
- class AtFileMatcher:
54
- """An IPython completion matcher (API v2) that completes ``@`` paths.
55
-
56
- A no-op (empty result, other matchers proceed) unless the token being
57
- completed is directly preceded by an ``@`` that starts a word. This keeps
58
- emails and other in-word ``@`` characters untouched.
59
- """
60
-
61
- matcher_api_version = 2
62
- matcher_identifier = "ipyllm.at_file_matcher"
63
-
64
- def __init__(self) -> None:
65
- # _get_matcher_id falls back to ``__qualname__`` when reading the id,
66
- # which is evaluated eagerly; provide it so instances resolve cleanly.
67
- self.__qualname__ = "ipyllm.completer.AtFileMatcher"
68
-
69
- def __call__(self, context) -> dict:
70
- token = context.token
71
- prefix = context.text_until_cursor
72
- before = prefix[:-len(token)] if token else prefix
73
-
74
- if not before.endswith("@"):
75
- return self._result([])
76
- at_index = len(before) - 1
77
- if not _word_at(before, at_index):
78
- return self._result([])
79
-
80
- if token:
81
- base = os.path.dirname(token) or os.curdir
82
- fragment = os.path.basename(token)
83
- else:
84
- base = os.curdir
85
- fragment = ""
86
-
87
- matches = _list_matches(base, fragment)
88
- return self._result(matches)
89
-
90
- @staticmethod
91
- def _result(completions: list) -> dict:
92
- return {
93
- "completions": completions,
94
- "suppress": bool(completions),
95
- "ordered": True,
96
- }
97
-
98
-
99
- at_file_matcher = AtFileMatcher()
100
-
101
-
102
- def install_completer(shell) -> None:
103
- """Register the ``@`` file matcher on ``shell``'s completer."""
104
- completer = getattr(shell, "Completer", None)
105
- if completer is None:
106
- return
107
- if at_file_matcher not in completer.custom_matchers:
108
- completer.custom_matchers.append(at_file_matcher)
109
-
110
-
111
- def uninstall_completer(shell) -> None:
112
- """Remove the ``@`` file matcher from ``shell``'s completer, if present."""
113
- completer = getattr(shell, "Completer", None)
114
- if completer is None:
115
- return
116
- try:
117
- completer.custom_matchers.remove(at_file_matcher)
118
- except ValueError:
119
- pass
File without changes
File without changes
File without changes
File without changes
File without changes