ipyllm 0.5.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.5.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>
@@ -77,7 +77,7 @@ configure provider keys using `llm keys set PROVIDER`.
77
77
  The [MkDocs documentation](docs/index.md) covers installation, model
78
78
  configuration, prompts, adding files to the context, command-output and
79
79
  last-error diagnosis, debugging with `ipyllm.embed`, available tools, Agent
80
- Skills,
80
+ Skills, per-prompt and per-model token usage,
81
81
  approval settings, and safety. Preview or build the site with:
82
82
 
83
83
  ```console
@@ -50,7 +50,7 @@ configure provider keys using `llm keys set PROVIDER`.
50
50
  The [MkDocs documentation](docs/index.md) covers installation, model
51
51
  configuration, prompts, adding files to the context, command-output and
52
52
  last-error diagnosis, debugging with `ipyllm.embed`, available tools, Agent
53
- Skills,
53
+ Skills, per-prompt and per-model token usage,
54
54
  approval settings, and safety. Preview or build the site with:
55
55
 
56
56
  ```console
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ipyllm"
3
- version = "0.5.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"]
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ipyllm"
3
- version = "0.5.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"]
@@ -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,16 +221,23 @@ 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
@@ -212,108 +291,63 @@ class IpyllmMagics(Magics):
212
291
  attachments=attachments or None,
213
292
  chain_limit=self.chain_limit,
214
293
  )
215
- print(response.text())
294
+ last_input, last_output = _display_response(response)
295
+ self._record_tokens(conversation, last_input, last_output)
216
296
  self._resume_requests.clear()
217
297
 
218
- def _parse_resources(self, prompt: str) -> tuple[str, list[str], list]:
219
- """Split ``@`` file references out of ``prompt``.
220
-
221
- Returns the cleaned prompt (each resolved reference replaced by a
222
- readable marker), a list of text-content fragments, and a list of
223
- ``llm.Attachment``. References that are not a word-leading ``@`` (for
224
- example an email address) or that do not resolve to an existing file
225
- or directory are left in the prompt unchanged.
226
- """
227
- fragments: list[str] = []
228
- attachments: list = []
229
- seen: set[Path] = set()
230
- parts: list[str] = []
231
- last = 0
232
- for match in _AT_REFERENCE.finditer(prompt):
233
- start, end = match.span()
234
- if start == 0 or prompt[start - 1].isspace():
235
- marker, frag, atts = self._resolve_reference(
236
- match.group(1), seen
237
- )
238
- parts.append(prompt[last:start])
239
- parts.append(marker)
240
- fragments.extend(frag)
241
- attachments.extend(atts)
242
- else:
243
- parts.append(prompt[last:end])
244
- last = end
245
- parts.append(prompt[last:])
246
- return "".join(parts), fragments, attachments
247
-
248
- def _resolve_reference(
249
- self, reference: str, seen: set[Path]
250
- ) -> tuple[str, list[str], list]:
251
- path = Path(reference).expanduser()
252
- if not path.is_absolute():
253
- path = Path.cwd() / path
254
-
255
- if path.is_dir():
256
- files, truncated = _list_dir_files(path)
257
- if not files:
258
- return f"[directory: {_display_name(path)} (no files)]", [], []
259
- count = f"first {len(files)} files" if truncated else f"{len(files)} files"
260
- marker = f"[directory: {_display_name(path)} ({count})]"
261
- elif path.is_file():
262
- files = [path]
263
- marker = f"[file: {_display_name(path)}]"
264
- else:
265
- return f"@{reference}", [], []
266
-
267
- fragments: list[str] = []
268
- attachments: list = []
269
- for file in files:
270
- resolved = file.resolve()
271
- if resolved in seen:
272
- continue
273
- seen.add(resolved)
274
- if self._is_media_file(file):
275
- attachments.append(llm.Attachment(path=str(file)))
276
- else:
277
- content = self._read_text_resource(file)
278
- fragments.append(
279
- f"[file: {_display_name(file)}]\n{content}"
280
- )
281
- return marker, fragments, attachments
282
-
283
- def _is_media_file(self, path: Path) -> bool:
284
- detected = _detect_type(path)
285
- if detected is None:
286
- return False
287
- return detected.startswith(_MEDIA_PREFIXES) or detected in _MEDIA_TYPES
288
-
289
- def _read_text_resource(self, path: Path) -> str:
290
- detected = _detect_type(path) or ""
291
- is_known_text = detected.startswith("text/")
292
- try:
293
- with path.open("rb") as handle:
294
- raw = handle.read(_MAX_FILE_CONTENT_CHARS * 4 + 4)
295
- except OSError as exc:
296
- raise UsageError(f"Cannot read {path}: {exc}") from exc
297
- if b"\x00" in raw[:8192]:
298
- raise UsageError(
299
- f"{path} is not a text file and this model cannot attach it. "
300
- "Use an image, audio, video, or PDF, or convert it to a text "
301
- "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)"
302
346
  )
303
- try:
304
- content = raw.decode("utf-8")
305
- except UnicodeDecodeError:
306
- if is_known_text:
307
- content = raw.decode("utf-8", errors="ignore")
308
- else:
309
- raise UsageError(
310
- f"{path} is not a text file and this model cannot attach it. "
311
- "Use an image, audio, video, or PDF, or convert it to a "
312
- "text file."
313
- ) from None
314
- if len(content) > _MAX_FILE_CONTENT_CHARS:
315
- content = content[:_MAX_FILE_CONTENT_CHARS]
316
- 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)
317
351
 
318
352
  def _resume_request_context(self) -> str:
319
353
  if not self._resume_requests:
@@ -356,6 +390,8 @@ class IpyllmMagics(Magics):
356
390
  "%llm --resume FILE.py\n"
357
391
  "%llm --chain-limit N\n"
358
392
  "%llm --config\n"
393
+ "%llm --tokens\n"
394
+ "%llm --save-config [FILE]\n"
359
395
  "%llm --reset"
360
396
  )
361
397
  return True
@@ -376,8 +412,7 @@ class IpyllmMagics(Magics):
376
412
  self._recorder.enable(args[1])
377
413
  return True
378
414
  if command == "--resume" and len(args) == 2:
379
- self._resume_requests = self._recorder.resume(args[1])
380
- self._conversation = None
415
+ self._resume_session(args[1])
381
416
  return True
382
417
  if command == "--chain-limit" and len(args) == 2:
383
418
  try:
@@ -397,18 +432,26 @@ class IpyllmMagics(Magics):
397
432
  model_id = self._model_id or self.model or "llm default"
398
433
  approval = self._current_approval_policy()
399
434
  save_path = self._recorder.save_path or "off"
435
+ source = self._config_path or "defaults"
400
436
  print(
401
437
  f"Model: {model_id}\n"
402
438
  f"Require execution approval: {approval}\n"
403
439
  f"Show execution tracebacks: {self.debug}\n"
404
440
  f"Save session to: {save_path}\n"
405
- f"Chain limit: {self.chain_limit}"
441
+ f"Chain limit: {self.chain_limit}\n"
442
+ f"Config file: {source}"
406
443
  )
407
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
408
452
  if command == "--model" and len(args) == 2:
409
453
  llm.get_model(args[1])
410
- self._model_id = args[1]
411
- self._conversation = None
454
+ self._set_model_id(args[1])
412
455
  print(f"Using LLM model {args[1]!r}. Conversation reset.")
413
456
  return True
414
457
  if command == "--approval" and len(args) == 2:
@@ -431,9 +474,80 @@ class IpyllmMagics(Magics):
431
474
  "`%llm --debug on|off`, "
432
475
  "`%llm --skills`, `%llm --save FILE.py|off`, "
433
476
  "`%llm --resume FILE.py`, `%llm --chain-limit N`, "
434
- "`%llm --config`, `%llm --reset`."
477
+ "`%llm --config`, `%llm --tokens`, `%llm --save-config [FILE]`, `%llm --reset`."
435
478
  )
436
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
+
437
551
  def _discover_skills(self) -> SkillCatalog:
438
552
  return discover_skills(self.skill_paths)
439
553
 
@@ -497,10 +611,23 @@ class IpyllmMagics(Magics):
497
611
  self.execute_code,
498
612
  ],
499
613
  before_call=self._before_tool_call,
614
+ after_call=_display_tool_result,
500
615
  chain_limit=self.chain_limit,
501
616
  )
502
617
  return self._conversation
503
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
+
504
631
  def _current_approval_policy(self) -> bool:
505
632
  if self._approval_override is not None:
506
633
  return self._approval_override
@@ -603,4 +730,4 @@ class IpyllmMagics(Magics):
603
730
 
604
731
  def reset(self) -> None:
605
732
  """Clear conversation state without changing model or approval settings."""
606
- 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
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes