ipyllm 0.1.0__tar.gz → 0.3.1__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.1.0
3
+ Version: 0.3.1
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>
@@ -26,6 +26,19 @@ Description-Content-Type: text/markdown
26
26
 
27
27
  <div align="center">
28
28
  <img src="docs/ipyllm_logo.svg" alt="Synaptic Prompt Logo" width="150"/>
29
+ <br/>
30
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Abuild" alt="Build">
31
+ <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=build" alt="Build"/>
32
+ </a>
33
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Adocs" alt="Docs">
34
+ <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=docs" alt="Docs"/>
35
+ </a>
36
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Atest" alt="Tests">
37
+ <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=test" alt="Tests"/>
38
+ </a>
39
+ <a href="https://pypi.org/project/ipyllm/" alt="PyPI version">
40
+ <img src="https://img.shields.io/pypi/v/ipyllm?label=pypi" alt="PyPI version"/>
41
+ </a>
29
42
  </div>
30
43
 
31
44
  # ipyllm
@@ -35,7 +48,13 @@ supported by the [`llm`](https://llm.datasette.io/) Python package.
35
48
 
36
49
  ## Install and load
37
50
 
38
- Install the package in the Python environment used by IPython:
51
+ Install `ipyllm` from PyPI into the Python environment used by IPython:
52
+
53
+ ```console
54
+ python -m pip install ipyllm
55
+ ```
56
+
57
+ Or install from a local checkout:
39
58
 
40
59
  ```console
41
60
  python -m pip install .
ipyllm-0.3.1/README.md ADDED
@@ -0,0 +1,57 @@
1
+ <div align="center">
2
+ <img src="docs/ipyllm_logo.svg" alt="Synaptic Prompt Logo" width="150"/>
3
+ <br/>
4
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Abuild" alt="Build">
5
+ <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=build" alt="Build"/>
6
+ </a>
7
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Adocs" alt="Docs">
8
+ <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=docs" alt="Docs"/>
9
+ </a>
10
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Atest" alt="Tests">
11
+ <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=test" alt="Tests"/>
12
+ </a>
13
+ <a href="https://pypi.org/project/ipyllm/" alt="PyPI version">
14
+ <img src="https://img.shields.io/pypi/v/ipyllm?label=pypi" alt="PyPI version"/>
15
+ </a>
16
+ </div>
17
+
18
+ # ipyllm
19
+
20
+ An IPython extension for discussing your interactive Python session with models
21
+ supported by the [`llm`](https://llm.datasette.io/) Python package.
22
+
23
+ ## Install and load
24
+
25
+ Install `ipyllm` from PyPI into the Python environment used by IPython:
26
+
27
+ ```console
28
+ python -m pip install ipyllm
29
+ ```
30
+
31
+ Or install from a local checkout:
32
+
33
+ ```console
34
+ python -m pip install .
35
+ ```
36
+
37
+ Then load it in IPython or a Jupyter IPython kernel:
38
+
39
+ ```ipython
40
+ %load_ext ipyllm
41
+ ```
42
+
43
+ The extension uses the model and API-key configuration already managed by
44
+ `llm`. For example, choose a default model with `llm models default MODEL` and
45
+ configure provider keys using `llm keys set PROVIDER`.
46
+
47
+ ## Documentation
48
+
49
+ The [MkDocs documentation](docs/index.md) covers installation, model
50
+ configuration, prompts, command-output diagnosis, debugging with
51
+ `ipyllm.embed`, available tools, Agent Skills, approval settings, and
52
+ safety. Preview or build the site with:
53
+
54
+ ```console
55
+ uv run mkdocs serve
56
+ uv run mkdocs build
57
+ ```
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ipyllm"
3
- version = "0.1.0"
3
+ version = "0.3.1"
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.1.0"
3
+ version = "0.3.1"
4
4
  description = "Interact with LLM models from your IPython REPL"
5
5
  readme = "README.md"
6
6
  license-files = ["LICENSE"]
@@ -39,10 +39,7 @@ build-backend = "uv_build"
39
39
 
40
40
  [dependency-groups]
41
41
  dev = [{ include-group = "test" }, { include-group = "providers" }]
42
- doc = [
43
- "mkdocs>=1.6.1",
44
- "mkdocs-material>=9.7.7",
45
- ]
42
+ doc = ["mkdocs>=1.6.1", "mkdocs-material>=9.7.7"]
46
43
  providers = [
47
44
  "llm-anthropic>=0.30",
48
45
  "llm-deepseek>=0.1.6",
@@ -12,11 +12,14 @@
12
12
  # See the License for the specific language governing permissions and
13
13
  # limitations under the License.
14
14
 
15
+ import ast
15
16
  import builtins
16
17
  import re
17
18
  import shlex
18
19
  import subprocess
20
+ import sys
19
21
  from itertools import islice
22
+ from pathlib import Path
20
23
 
21
24
  import llm
22
25
  from IPython.core.error import UsageError
@@ -68,6 +71,11 @@ class IpyllmMagics(Magics):
68
71
  config=True,
69
72
  help="Ask before executing code requested by the model.",
70
73
  )
74
+ debug = Bool(
75
+ default_value=False,
76
+ config=True,
77
+ help="Show IPython tracebacks for errors in model-executed code.",
78
+ )
71
79
  skill_paths = List(
72
80
  Unicode(),
73
81
  default_value=[],
@@ -80,22 +88,30 @@ class IpyllmMagics(Magics):
80
88
  config=True,
81
89
  help="Maximum seconds to wait for a command run with %%llm --run.",
82
90
  )
91
+ chain_limit = Integer(
92
+ default_value=10,
93
+ min=1,
94
+ config=True,
95
+ help="Maximum number of model/tool call rounds per prompt.",
96
+ )
83
97
 
84
98
  def __init__(self, shell):
85
99
  super().__init__(shell)
86
100
  self._model_id: str | None = None
87
101
  self._approval_override: bool | None = None
88
102
  self._conversation = None
103
+ self._save_path: Path | None = None
104
+ self._resume_requests: list[str] = []
89
105
 
90
106
  @line_cell_magic
91
107
  def llm(self, line: str, cell: str | None = None) -> None:
92
108
  """Ask the configured model a question, optionally as a cell magic.
93
109
 
94
110
  Use ``%llm --model MODEL``, ``%llm --approval on|off``,
95
- ``%llm --skills``, ``%llm --config``, and ``%llm --reset`` to manage
96
- this session. In cell mode use ``%%llm --run`` to capture a shell
97
- command for diagnosis. Start a prompt with ``/skill-name`` to load a
98
- local skill.
111
+ ``%llm --debug on|off``, ``%llm --skills``, ``%llm --config``, and
112
+ ``%llm --reset`` to manage this session. In cell mode use
113
+ ``%%llm --run`` to capture a shell command for diagnosis. Start a
114
+ prompt with ``/skill-name`` to load a local skill.
99
115
  """
100
116
  if cell is not None and (
101
117
  line.strip() == "--run" or line.strip().startswith("--run ")
@@ -112,11 +128,13 @@ class IpyllmMagics(Magics):
112
128
  self._ask(prompt)
113
129
 
114
130
  def _ask(self, prompt: str) -> None:
131
+ self._record_request(prompt)
115
132
  skill, instructions, prompt = self._select_skill(prompt)
116
133
  conversation = self._get_conversation()
117
134
  contextual_prompt = (
118
135
  "Available user variables (names and Python types only):\n"
119
136
  f"{self._namespace_context()}\n\n"
137
+ f"{self._resume_request_context()}"
120
138
  f"User request:\n{prompt}"
121
139
  )
122
140
  fragments = None
@@ -133,8 +151,26 @@ class IpyllmMagics(Magics):
133
151
  contextual_prompt,
134
152
  system=_SYSTEM_PROMPT,
135
153
  fragments=fragments,
154
+ chain_limit=self.chain_limit,
136
155
  )
137
156
  print(response.text())
157
+ self._resume_requests.clear()
158
+
159
+ def _resume_request_context(self) -> str:
160
+ if not self._resume_requests:
161
+ return ""
162
+ requests = "\n\n".join(
163
+ f"Request {index}:\n{request}"
164
+ for index, request in enumerate(self._resume_requests, start=1)
165
+ )
166
+ if len(requests) > _MAX_CONTEXT_CHARS:
167
+ requests = requests[-_MAX_CONTEXT_CHARS:]
168
+ requests = "(Earlier requests truncated.)\n" + requests
169
+ return (
170
+ "Requests recorded in the resumed Python script follow. "
171
+ "They are context only; previous model responses were not saved:\n"
172
+ f"{requests}\n\n"
173
+ )
138
174
 
139
175
  def _run_diagnostic_command(self, line: str, command: str) -> None:
140
176
  try:
@@ -230,7 +266,11 @@ class IpyllmMagics(Magics):
230
266
  "%%llm --run [diagnostic request]\n"
231
267
  "%llm --model MODEL\n"
232
268
  "%llm --approval on|off\n"
269
+ "%llm --debug on|off\n"
233
270
  "%llm --skills\n"
271
+ "%llm --save FILE.py|off\n"
272
+ "%llm --resume FILE.py\n"
273
+ "%llm --chain-limit N\n"
234
274
  "%llm --config\n"
235
275
  "%llm --reset"
236
276
  )
@@ -238,6 +278,26 @@ class IpyllmMagics(Magics):
238
278
  if command == "--skills" and len(args) == 1:
239
279
  self._print_skills()
240
280
  return True
281
+ if command == "--save" and len(args) == 2:
282
+ if args[1].lower() == "off":
283
+ self._save_path = None
284
+ print("Session recording disabled.")
285
+ else:
286
+ self._enable_session_save(args[1])
287
+ return True
288
+ if command == "--resume" and len(args) == 2:
289
+ self._resume_session(args[1])
290
+ return True
291
+ if command == "--chain-limit" and len(args) == 2:
292
+ try:
293
+ chain_limit = int(args[1])
294
+ except ValueError as exc:
295
+ raise UsageError("Chain limit must be a positive integer.") from exc
296
+ if chain_limit < 1:
297
+ raise UsageError("Chain limit must be a positive integer.")
298
+ self.chain_limit = chain_limit
299
+ print(f"Chain limit set to {self.chain_limit}.")
300
+ return True
241
301
  if command == "--reset" and len(args) == 1:
242
302
  self.reset()
243
303
  print("LLM conversation reset.")
@@ -245,7 +305,14 @@ class IpyllmMagics(Magics):
245
305
  if command == "--config" and len(args) == 1:
246
306
  model_id = self._model_id or self.model or "llm default"
247
307
  approval = self._current_approval_policy()
248
- print(f"Model: {model_id}\nRequire execution approval: {approval}")
308
+ save_path = self._save_path or "off"
309
+ print(
310
+ f"Model: {model_id}\n"
311
+ f"Require execution approval: {approval}\n"
312
+ f"Show execution tracebacks: {self.debug}\n"
313
+ f"Save session to: {save_path}\n"
314
+ f"Chain limit: {self.chain_limit}"
315
+ )
249
316
  return True
250
317
  if command == "--model" and len(args) == 2:
251
318
  llm.get_model(args[1])
@@ -260,11 +327,157 @@ class IpyllmMagics(Magics):
260
327
  self._approval_override = value == "on"
261
328
  print(f"Require execution approval: {self._approval_override}")
262
329
  return True
330
+ if command == "--debug" and len(args) == 2:
331
+ value = args[1].lower()
332
+ if value not in {"on", "off"}:
333
+ raise UsageError("Use `%llm --debug on` or `%llm --debug off`.")
334
+ self.debug = value == "on"
335
+ print(f"Show execution tracebacks: {self.debug}")
336
+ return True
263
337
  raise UsageError(
264
338
  "Commands: `%llm --model MODEL`, `%llm --approval on|off`, "
265
- "`%llm --skills`, `%llm --config`, `%llm --reset`."
339
+ "`%llm --debug on|off`, "
340
+ "`%llm --skills`, `%llm --save FILE.py|off`, "
341
+ "`%llm --resume FILE.py`, `%llm --chain-limit N`, "
342
+ "`%llm --config`, `%llm --reset`."
343
+ )
344
+
345
+ def _resume_session(self, filename: str) -> None:
346
+ if self._save_path is not None:
347
+ raise UsageError(
348
+ f"Stop recording to {self._save_path} with `%llm --save off` "
349
+ "before resuming another session."
350
+ )
351
+ path = Path(filename).expanduser()
352
+ if path.suffix.lower() != ".py":
353
+ raise UsageError("The session file must have a `.py` extension.")
354
+ path = path.resolve()
355
+ try:
356
+ source = path.read_text(encoding="utf-8")
357
+ except (OSError, UnicodeError) as exc:
358
+ raise UsageError(f"Cannot read session file {path}: {exc}") from exc
359
+ try:
360
+ compile(source, str(path), "exec")
361
+ except SyntaxError as exc:
362
+ raise UsageError(f"Session file is not valid Python: {exc}") from exc
363
+
364
+ try:
365
+ with path.open("a", encoding="utf-8"):
366
+ pass
367
+ except OSError as exc:
368
+ raise UsageError(f"Cannot append to session file {path}: {exc}") from exc
369
+
370
+ self._execute_session_script(path)
371
+ self._resume_requests = self._read_saved_requests(source)
372
+ self._save_path = path
373
+ self._conversation = None
374
+ print(
375
+ f"Resumed Python state from {path}. New requests and executed code "
376
+ "will be appended to this file."
266
377
  )
267
378
 
379
+ def _execute_session_script(self, path: Path) -> None:
380
+ shell = self._get_shell()
381
+ namespace = shell.user_ns
382
+ missing = object()
383
+ previous_name = namespace.get("__name__", missing)
384
+ previous_argv = sys.argv
385
+ namespace["__name__"] = path.stem
386
+ namespace["__file__"] = str(path)
387
+ sys.argv = [str(path)]
388
+ try:
389
+ shell.safe_execfile(
390
+ str(path),
391
+ namespace,
392
+ namespace,
393
+ raise_exceptions=True,
394
+ shell_futures=True,
395
+ )
396
+ finally:
397
+ sys.argv = previous_argv
398
+ if previous_name is missing:
399
+ namespace.pop("__name__", None)
400
+ else:
401
+ namespace["__name__"] = previous_name
402
+
403
+ @staticmethod
404
+ def _read_saved_requests(source: str) -> list[str]:
405
+ requests = []
406
+ lines = source.splitlines()
407
+ index = 0
408
+ while index < len(lines):
409
+ if lines[index] != "# Request:":
410
+ index += 1
411
+ continue
412
+ index += 1
413
+ request_lines = []
414
+ while index < len(lines) and lines[index].startswith("#"):
415
+ line = lines[index][1:]
416
+ request_lines.append(line[1:] if line.startswith(" ") else line)
417
+ index += 1
418
+ request = "\n".join(request_lines).strip()
419
+ if request:
420
+ requests.append(request)
421
+ return requests
422
+
423
+ def _enable_session_save(self, filename: str) -> None:
424
+ path = Path(filename).expanduser()
425
+ if path.suffix.lower() != ".py":
426
+ raise UsageError("The session file must have a `.py` extension.")
427
+ path = path.resolve()
428
+ try:
429
+ with path.open("x", encoding="utf-8") as session_file:
430
+ session_file.write(
431
+ "#!/usr/bin/env python3\n"
432
+ "# -*- coding: utf-8 -*-\n"
433
+ "# Recorded by ipyllm. Prompts are comments; executed Python "
434
+ "follows.\n\n"
435
+ )
436
+ except FileExistsError as exc:
437
+ raise UsageError(
438
+ f"Refusing to overwrite existing session file: {path}"
439
+ ) from exc
440
+ except OSError as exc:
441
+ raise UsageError(f"Cannot create session file {path}: {exc}") from exc
442
+
443
+ self._save_path = path
444
+ print(f"Recording new prompts and executed Python to {path}.")
445
+
446
+ def _record_request(self, request: str) -> None:
447
+ if self._save_path is None:
448
+ return
449
+ lines = ["# Request:"]
450
+ lines.extend(f"# {line}" if line else "#" for line in request.splitlines())
451
+ self._append_session_text("\n".join(lines) + "\n\n")
452
+
453
+ def _record_executed_code(self, code: str) -> None:
454
+ if self._save_path is None:
455
+ return
456
+ try:
457
+ ast.parse(code)
458
+ except SyntaxError:
459
+ lines = [
460
+ "# IPython-only input (not executable as a standalone Python script):"
461
+ ]
462
+ lines.extend(f"# {line}" if line else "#" for line in code.splitlines())
463
+ print(
464
+ "The executed input uses IPython syntax and is saved as comments, "
465
+ "so the session file remains valid Python."
466
+ )
467
+ self._append_session_text("\n".join(lines) + "\n\n")
468
+ return
469
+ self._append_session_text(code.rstrip() + "\n\n")
470
+
471
+ def _append_session_text(self, text: str) -> None:
472
+ assert self._save_path is not None
473
+ try:
474
+ with self._save_path.open("a", encoding="utf-8") as session_file:
475
+ session_file.write(text)
476
+ except OSError as exc:
477
+ raise RuntimeError(
478
+ f"Cannot append to session file {self._save_path}: {exc}"
479
+ ) from exc
480
+
268
481
  def _discover_skills(self) -> SkillCatalog:
269
482
  return discover_skills(self.skill_paths)
270
483
 
@@ -328,7 +541,7 @@ class IpyllmMagics(Magics):
328
541
  self.execute_code,
329
542
  ],
330
543
  before_call=self._before_tool_call,
331
- chain_limit=10,
544
+ chain_limit=self.chain_limit,
332
545
  )
333
546
  return self._conversation
334
547
 
@@ -416,7 +629,17 @@ class IpyllmMagics(Magics):
416
629
 
417
630
  def execute_code(self, code: str) -> str:
418
631
  """Execute Python code in the currently running IPython session."""
419
- result = self._get_shell().run_cell(code, store_history=True)
632
+ self._record_executed_code(code)
633
+ shell = self._get_shell()
634
+ if self.debug:
635
+ result = shell.run_cell(code, store_history=True)
636
+ else:
637
+ showtraceback = shell.showtraceback
638
+ shell.showtraceback = lambda *args, **kwargs: None
639
+ try:
640
+ result = shell.run_cell(code, store_history=True)
641
+ finally:
642
+ shell.showtraceback = showtraceback
420
643
  error = result.error_before_exec or result.error_in_exec
421
644
  if error is not None:
422
645
  return f"Execution failed: {type(error).__name__}: {error}"
ipyllm-0.1.0/README.md DELETED
@@ -1,38 +0,0 @@
1
- <div align="center">
2
- <img src="docs/ipyllm_logo.svg" alt="Synaptic Prompt Logo" width="150"/>
3
- </div>
4
-
5
- # ipyllm
6
-
7
- An IPython extension for discussing your interactive Python session with models
8
- supported by the [`llm`](https://llm.datasette.io/) Python package.
9
-
10
- ## Install and load
11
-
12
- Install the package in the Python environment used by IPython:
13
-
14
- ```console
15
- python -m pip install .
16
- ```
17
-
18
- Then load it in IPython or a Jupyter IPython kernel:
19
-
20
- ```ipython
21
- %load_ext ipyllm
22
- ```
23
-
24
- The extension uses the model and API-key configuration already managed by
25
- `llm`. For example, choose a default model with `llm models default MODEL` and
26
- configure provider keys using `llm keys set PROVIDER`.
27
-
28
- ## Documentation
29
-
30
- The [MkDocs documentation](docs/index.md) covers installation, model
31
- configuration, prompts, command-output diagnosis, debugging with
32
- `ipyllm.embed`, available tools, Agent Skills, approval settings, and
33
- safety. Preview or build the site with:
34
-
35
- ```console
36
- uv run mkdocs serve
37
- uv run mkdocs build
38
- ```
File without changes
File without changes
File without changes