ipyllm 0.6.0__tar.gz → 0.7.0.dev4__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.6.0
3
+ Version: 0.7.0.dev4
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>
@@ -28,14 +28,14 @@ Description-Content-Type: text/markdown
28
28
  <div align="center">
29
29
  <img src="https://juampatronics.com/images/ipyllm_logo.svg" alt="Synaptic Prompt Logo" width="150"/>
30
30
  <br/>
31
- <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Abuild" alt="Build">
32
- <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=build" alt="Build"/>
31
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Abuild" alt="Build (source code)">
32
+ <img src="https://img.shields.io/badge/build-source%20code?color=blue" alt="Build (source code)"/>
33
33
  </a>
34
- <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Adocs" alt="Docs">
35
- <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=docs" alt="Docs"/>
34
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Adocs" alt="Docs (MkDocs)">
35
+ <img src="https://img.shields.io/badge/docs-MkDocs?color=green" alt="Docs (MkDocs)"/>
36
36
  </a>
37
- <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Atest" alt="Tests">
38
- <img src="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml/badge.svg?job=test" alt="Tests"/>
37
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Atest" alt="Tests (pytest)">
38
+ <img src="https://img.shields.io/badge/test-pytest?color=orange" alt="Tests (pytest)"/>
39
39
  </a>
40
40
  <a href="https://pypi.org/project/ipyllm/" alt="PyPI version">
41
41
  <img src="https://img.shields.io/pypi/v/ipyllm?label=pypi" alt="PyPI version"/>
@@ -1,14 +1,14 @@
1
1
  <div align="center">
2
2
  <img src="https://juampatronics.com/images/ipyllm_logo.svg" alt="Synaptic Prompt Logo" width="150"/>
3
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"/>
4
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Abuild" alt="Build (source code)">
5
+ <img src="https://img.shields.io/badge/build-source%20code?color=blue" alt="Build (source code)"/>
6
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"/>
7
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Adocs" alt="Docs (MkDocs)">
8
+ <img src="https://img.shields.io/badge/docs-MkDocs?color=green" alt="Docs (MkDocs)"/>
9
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"/>
10
+ <a href="https://github.com/juampatronics/ipyllm/actions/workflows/ci.yml?query=job%3Atest" alt="Tests (pytest)">
11
+ <img src="https://img.shields.io/badge/test-pytest?color=orange" alt="Tests (pytest)"/>
12
12
  </a>
13
13
  <a href="https://pypi.org/project/ipyllm/" alt="PyPI version">
14
14
  <img src="https://img.shields.io/pypi/v/ipyllm?label=pypi" alt="PyPI version"/>
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ipyllm"
3
- version = "0.6.0"
3
+ version = "0.7.0.dev4"
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.6.0"
3
+ version = "0.7.0.dev4"
4
4
  description = "Interact with LLM models from your IPython REPL"
5
5
  readme = "README.md"
6
6
  license-files = ["LICENSE"]
@@ -0,0 +1,645 @@
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
+ """Type-specific, bounded inspectors backing the ``describe_object`` tool.
16
+
17
+ The goal is a compact, structured description of a *live* object that does not
18
+ grow with its size: a 10-million-row DataFrame must not become a 100 MB prompt.
19
+ Every inspector returns short text and is size-independent by construction.
20
+
21
+ Inspection is **progressive**. ``describe_object`` accepts a ``detail`` level:
22
+
23
+ - ``summary`` (default): cheap, size-independent identity facts (type, shape,
24
+ dtype, device, memory, fitted status, labels). No per-row work.
25
+ - ``detail``: adds per-column breakdowns, missing values, and for floating
26
+ data descriptive statistics (mean, std, min, median, max, IQR fences) that
27
+ help flag outliers. Per-column work is bounded to a fixed number of columns.
28
+ - ``full``: adds sample values, a small head preview, or the source code,
29
+ depending on the type.
30
+
31
+ Optional scientific libraries (NumPy, pandas, PyTorch, scikit-learn,
32
+ matplotlib) are imported lazily and only when an object of that type is
33
+ actually inspected, so their absence never breaks the tool.
34
+ """
35
+
36
+ from __future__ import annotations
37
+
38
+ import importlib
39
+ import inspect as pyinspect
40
+ import math
41
+ import numbers
42
+ import types
43
+
44
+ # Hard cap on any inspector's output (defense in depth on top of the bounded
45
+ # iteration limits below). 12,000 characters ≈ a few thousand tokens.
46
+ MAX_INSPECT_CHARS = 12_000
47
+ # How many DataFrame columns receive per-column (row-scanning) work.
48
+ _MAX_STAT_COLUMNS = 40
49
+ # How many largest values per numeric column are listed (detail and up), so
50
+ # the model can count how many values exceed a threshold without executing.
51
+ _TOP_K = 5
52
+ # How many names/keys/values are shown before we elide the rest.
53
+ _MAX_NAMES = 24
54
+ # How many sample values / preview items we render.
55
+ _MAX_PREVIEW = 12
56
+ # Max characters for a single inline value.
57
+ _PREVIEW_CHARS = 80
58
+ # Fallback (unknown-type) representation budget.
59
+ _FALLBACK_CHARS = 4_000
60
+
61
+ _DETAIL_LEVELS = ("summary", "detail", "full")
62
+
63
+
64
+ # --- Small formatting helpers ---------------------------------------------
65
+
66
+
67
+ def _num(value) -> str:
68
+ """Compact, deterministic rendering of a numeric scalar.
69
+
70
+ Integers (including NumPy integers) are shown exactly; floats are shown to
71
+ six significant digits, with NaN/Inf spelled out.
72
+ """
73
+ if value is None:
74
+ return "n/a"
75
+ if isinstance(value, numbers.Integral) and not isinstance(value, bool):
76
+ return str(int(value))
77
+ try:
78
+ f = float(value)
79
+ except (TypeError, ValueError):
80
+ return _preview(value)
81
+ if math.isnan(f):
82
+ return "nan"
83
+ if math.isinf(f):
84
+ return "inf" if f > 0 else "-inf"
85
+ if f.is_integer() and abs(f) < 1e15:
86
+ return str(int(f))
87
+ return f"{f:.6g}"
88
+
89
+
90
+ def _mb(nbytes) -> str:
91
+ try:
92
+ return f"{int(nbytes) / 1_048_576:.1f} MiB"
93
+ except (TypeError, ValueError):
94
+ return "n/a"
95
+
96
+
97
+ def _preview(value) -> str:
98
+ """A bounded single-line rendering of an arbitrary value."""
99
+ try:
100
+ text = repr(value)
101
+ except Exception as exc: # noqa: BLE001 - a hostile __repr__ must not break us
102
+ return f"<unrepresentable: {type(exc).__name__}>"
103
+ if len(text) > _PREVIEW_CHARS:
104
+ text = text[:_PREVIEW_CHARS] + "…"
105
+ return text
106
+
107
+
108
+ def _cap(text: str, limit: int = MAX_INSPECT_CHARS) -> str:
109
+ if len(text) <= limit:
110
+ return text
111
+ return text[:limit].rstrip() + "\n… (output truncated)"
112
+
113
+
114
+ def _names_line(label: str, names: list[str]) -> str:
115
+ shown = names[:_MAX_NAMES]
116
+ extra = len(names) - len(shown)
117
+ text = f"{label}: {', '.join(shown)}"
118
+ if extra > 0:
119
+ text += f" (+{extra} more)"
120
+ return text
121
+
122
+
123
+ def _dtypes_groups(dtypes) -> str:
124
+ """Collapse a pandas ``dtypes`` axis into ``dtype×count`` groups."""
125
+ groups: dict[str, int] = {}
126
+ for dtype in dtypes:
127
+ key = str(dtype)
128
+ groups[key] = groups.get(key, 0) + 1
129
+ ordered = sorted(groups.items(), key=lambda kv: (-kv[1], kv[0]))
130
+ return ", ".join(f"{name}×{count}" for name, count in ordered)
131
+
132
+
133
+ # --- Optional type classes -------------------------------------------------
134
+
135
+
136
+ def _optional_class(module: str, name: str):
137
+ """Import ``module.name`` lazily, returning ``None`` when unavailable.
138
+
139
+ Any import failure (missing, partially installed, or incompatible) is
140
+ swallowed so a broken optional dependency can never prevent ``ipyllm``
141
+ from loading or the tool from working for other types.
142
+ """
143
+ try:
144
+ return getattr(importlib.import_module(module), name)
145
+ except Exception: # noqa: BLE001 - optional dependency; never fatal
146
+ return None
147
+
148
+
149
+ def _is_function(obj) -> bool:
150
+ return isinstance(
151
+ obj, (types.FunctionType, types.BuiltinFunctionType, types.MethodType)
152
+ )
153
+
154
+
155
+ # --- Inspectors ------------------------------------------------------------
156
+ #
157
+ # Each inspector takes ``(obj, detail)`` and returns a bounded string. They
158
+ # import their own optional dependency, so a missing library only disables the
159
+ # inspector for the object types it would have handled.
160
+
161
+
162
+ def _describe_numpy_array(arr, detail) -> str:
163
+ import numpy as np
164
+
165
+ lines = [
166
+ f"ndarray shape={list(arr.shape)} dtype={arr.dtype} ndim={arr.ndim}",
167
+ f"nbytes={arr.nbytes} ({_mb(arr.nbytes)}) strides={list(arr.strides)} "
168
+ f"contiguous={bool(arr.flags['C_CONTIGUOUS'])} aligned={bool(arr.flags['ALIGNED'])}",
169
+ ]
170
+ if detail == "summary":
171
+ return "\n".join(lines)
172
+
173
+ flat = np.asarray(arr).ravel()
174
+ if arr.dtype.kind in "biufc" and flat.size:
175
+ try:
176
+ lines.append("stats: " + _array_stats(flat))
177
+ except Exception as exc: # noqa: BLE001
178
+ lines.append(f"stats: unavailable ({type(exc).__name__})")
179
+ else:
180
+ lines.append(f"stats: not numeric (dtype {arr.dtype!r})")
181
+ if detail == "full":
182
+ lines.append(f"sample: {_array_sample(flat)}")
183
+ return "\n".join(lines)
184
+
185
+
186
+ def _array_stats(flat) -> str:
187
+ import numpy as np
188
+
189
+ finite = flat[np.isfinite(flat)]
190
+ if finite.size == 0:
191
+ return "all non-finite"
192
+ q1, q3 = (float(v) for v in np.quantile(finite, [0.25, 0.75]))
193
+ iqr = q3 - q1
194
+ lo, hi = q1 - 1.5 * iqr, q3 + 1.5 * iqr
195
+ k = min(_TOP_K, finite.size)
196
+ top = np.sort(np.partition(finite, finite.size - k)[-k:])[::-1]
197
+ top_rendered = ", ".join(_num(v) for v in top.tolist())
198
+ return (
199
+ f"min={_num(finite.min())} max={_num(finite.max())} "
200
+ f"mean={_num(finite.mean())} std={_num(finite.std())} "
201
+ f"median={_num(np.median(finite))} "
202
+ f"iqr=[{_num(q1)},{_num(q3)}] outlier_fence=[{_num(lo)},{_num(hi)}] "
203
+ f"top{_TOP_K}=[{top_rendered}]"
204
+ )
205
+
206
+
207
+ def _array_sample(flat) -> str:
208
+ import numpy as np
209
+
210
+ if flat.size == 0:
211
+ return "[]"
212
+ count = min(_MAX_PREVIEW, flat.size)
213
+ idx = np.linspace(0, flat.size - 1, count).astype(int)
214
+ values = [_num(x) for x in flat[idx]]
215
+ suffix = f" … ({flat.size} total)" if flat.size > count else ""
216
+ return "[" + ", ".join(values) + suffix + "]"
217
+
218
+
219
+ def _describe_pandas_dataframe(df, detail) -> str:
220
+ import pandas as pd
221
+
222
+ nrows, ncols = df.shape
223
+ lines = [f"DataFrame shape=({nrows}, {ncols})"]
224
+ try:
225
+ lines.append(f"memory≈{_mb(df.memory_usage(deep=True).sum())}")
226
+ except Exception: # noqa: BLE001
227
+ pass
228
+ lines.append(f"dtypes: {_dtypes_groups(df.dtypes)}")
229
+ lines.append(_names_line("columns", [str(c) for c in df.columns]))
230
+ if detail == "summary":
231
+ return "\n".join(lines)
232
+
233
+ lines.extend(_describe_pandas_columns(df, pd, _MAX_STAT_COLUMNS))
234
+ if detail == "full":
235
+ lines.append(f"head(5):\n{_frame_head(df)}")
236
+ return "\n".join(lines)
237
+
238
+
239
+ def _describe_pandas_series(series, detail) -> str:
240
+ import pandas as pd
241
+
242
+ lines = [
243
+ f"Series shape=({series.size},) dtype={series.dtype} "
244
+ f"name={series.name!r}"
245
+ ]
246
+ try:
247
+ lines.append(f"memory≈{_mb(series.memory_usage(deep=True))}")
248
+ except Exception: # noqa: BLE001
249
+ pass
250
+ if detail == "summary":
251
+ return "\n".join(lines)
252
+
253
+ if pd.api.types.is_numeric_dtype(series) and not pd.api.types.is_bool_dtype(series):
254
+ try:
255
+ lines.append("stats: " + _series_stats(series))
256
+ except Exception as exc: # noqa: BLE001
257
+ lines.append(f"stats: unavailable ({type(exc).__name__})")
258
+ try:
259
+ missing = int(series.isna().sum())
260
+ lines.append(f"missing: {missing}")
261
+ except Exception: # noqa: BLE001
262
+ lines.append("missing: unavailable")
263
+ if detail == "full":
264
+ lines.append(f"sample: {_array_sample(series.to_numpy())}")
265
+ return "\n".join(lines)
266
+
267
+
268
+ def _describe_pandas_columns(df, pd, limit: int) -> list[str]:
269
+ """Per-column breakdown over a bounded prefix of the frame's columns.
270
+
271
+ Row-scanning work (missing counts, statistics) is confined to the first
272
+ ``limit`` columns, so cost stays bounded even for wide frames.
273
+ """
274
+ lines: list[str] = []
275
+ columns = list(df.columns)
276
+ bounded = columns[:limit]
277
+ extra = len(columns) - len(bounded)
278
+ for column in bounded:
279
+ series = df[column]
280
+ entry = f" {column!r} ({series.dtype})"
281
+ try:
282
+ missing = int(series.isna().sum())
283
+ entry += f" missing={missing}"
284
+ except Exception: # noqa: BLE001
285
+ entry += " missing=n/a"
286
+ if (
287
+ pd.api.types.is_numeric_dtype(series)
288
+ and not pd.api.types.is_bool_dtype(series)
289
+ ):
290
+ try:
291
+ entry += " " + _series_stats(series)
292
+ except Exception as exc: # noqa: BLE001
293
+ entry += f" stats_unavailable({type(exc).__name__})"
294
+ lines.append(entry)
295
+ if extra > 0:
296
+ lines.append(f" … (+{extra} more column(s) not scanned)")
297
+ lines.insert(0, f"per-column (first {len(bounded)} of {len(columns)}):")
298
+ return lines
299
+
300
+
301
+ def _top_values(series, k: int = _TOP_K) -> str:
302
+ """The ``k`` largest non-missing values, in descending order.
303
+
304
+ Lets the model reason about how many values exceed a threshold without
305
+ executing code: entries of the list above the threshold are the answer
306
+ (or a lower bound when the list is exhausted).
307
+ """
308
+ try:
309
+ values = series.nlargest(k)
310
+ except Exception: # noqa: BLE001
311
+ return f"top{k}=n/a"
312
+ if values.empty:
313
+ return f"top{k}=[]"
314
+ rendered = ", ".join(_num(v) for v in values.tolist())
315
+ return f"top{k}=[{rendered}]"
316
+
317
+
318
+ def _series_stats(series) -> str:
319
+ if series.dropna().empty:
320
+ return "all missing"
321
+ mean = series.mean()
322
+ std = series.std()
323
+ median = series.median()
324
+ minimum = series.min()
325
+ maximum = series.max()
326
+ q1, q3 = (float(v) for v in series.quantile([0.25, 0.75]))
327
+ iqr = q3 - q1
328
+ lo, hi = q1 - 1.5 * iqr, q3 + 1.5 * iqr
329
+ return (
330
+ f"mean={_num(mean)} std={_num(std)} min={_num(minimum)} "
331
+ f"median={_num(median)} max={_num(maximum)} "
332
+ f"iqr=[{_num(q1)},{_num(q3)}] outlier_fence=[{_num(lo)},{_num(hi)}] "
333
+ + _top_values(series)
334
+ )
335
+
336
+
337
+ def _frame_head(df) -> str:
338
+ try:
339
+ text = df.head(5).to_string(max_cols=_MAX_NAMES)
340
+ except Exception as exc: # noqa: BLE001
341
+ return f"(head unavailable: {type(exc).__name__})"
342
+ return _cap(text, _FALLBACK_CHARS)
343
+
344
+
345
+ def _describe_torch_tensor(tensor, detail) -> str:
346
+ lines = [
347
+ f"Tensor shape={list(tensor.shape)} dtype={tensor.dtype} "
348
+ f"device={tensor.device}"
349
+ ]
350
+ try:
351
+ nbytes = tensor.element_size() * tensor.nelement()
352
+ lines.append(f"nbytes={nbytes} ({_mb(nbytes)})")
353
+ except Exception: # noqa: BLE001
354
+ pass
355
+ lines.append(
356
+ f"requires_grad={bool(tensor.requires_grad)} "
357
+ f"grad={'set' if tensor.grad is not None else 'none'}"
358
+ )
359
+ if detail == "summary":
360
+ return "\n".join(lines)
361
+ import torch
362
+
363
+ try:
364
+ with torch.no_grad():
365
+ numeric = tensor.detach().cpu().float().numpy()
366
+ lines.append("stats: " + _array_stats(numeric.ravel()))
367
+ if detail == "full":
368
+ lines.append(f"sample: {_array_sample(numeric.ravel())}")
369
+ except Exception as exc: # noqa: BLE001
370
+ lines.append(f"stats: unavailable ({type(exc).__name__})")
371
+ return "\n".join(lines)
372
+
373
+
374
+ def _describe_torch_module(module, detail) -> str:
375
+ params = list(module.named_parameters())
376
+ total = sum(p.numel() for _, p in params)
377
+ trainable = sum(p.numel() for _, p in params if p.requires_grad)
378
+ children = [type(c).__name__ for c in module.children()]
379
+ shown = children[:_MAX_NAMES]
380
+ extra = len(children) - len(shown)
381
+ submodules = ", ".join(shown) + (f" (+{extra} more)" if extra > 0 else "")
382
+ lines = [
383
+ f"{type(module).__name__} (nn.Module)",
384
+ f"parameters: total={total:,} trainable={trainable:,} "
385
+ f"mode={'training' if module.training else 'eval'}",
386
+ f"submodules({len(children)}): {submodules}",
387
+ ]
388
+ if detail == "summary":
389
+ return "\n".join(lines)
390
+ # Per-submodule parameter counts, bounded.
391
+ breakdown: dict[str, int] = {}
392
+ for name, param in params:
393
+ head = name.split(".", 1)[0]
394
+ breakdown[head] = breakdown.get(head, 0) + param.numel()
395
+ ordered = sorted(breakdown.items(), key=lambda kv: (-kv[1], kv[0]))
396
+ shown = ordered[:_MAX_NAMES]
397
+ extra = len(ordered) - len(shown)
398
+ text = ", ".join(f"{name}={count:,}" for name, count in shown)
399
+ if extra > 0:
400
+ text += f" (+{extra} more)"
401
+ lines.append(f"parameters by block: {text}")
402
+ if detail == "full":
403
+ lines.append(f"structural repr:\n{_cap(str(module), _FALLBACK_CHARS)}")
404
+ return "\n".join(lines)
405
+
406
+
407
+ def _describe_matplotlib_figure(fig, detail) -> str:
408
+ lines = [
409
+ f"Figure size={tuple(float(v) for v in fig.get_size_inches())}in "
410
+ f"dpi={fig.dpi} axes={len(fig.axes)}"
411
+ ]
412
+ suptitle = getattr(fig, "_supptitle", None)
413
+ if suptitle is not None and suptitle.get_text():
414
+ lines.append(f"title: {suptitle.get_text()}")
415
+ if detail == "summary":
416
+ return "\n".join(lines)
417
+ for index, ax in enumerate(fig.axes):
418
+ lines.append(
419
+ f"axes[{index}] title={ax.get_title()!r} "
420
+ f"xlabel={ax.get_xlabel()!r} ylabel={ax.get_ylabel()!r}"
421
+ )
422
+ artists = _collect_artists(ax)
423
+ if artists:
424
+ ordered = sorted(artists.items(), key=lambda kv: (-kv[1], kv[0]))
425
+ lines.append(
426
+ " artists: "
427
+ + ", ".join(f"{name}×{count}" for name, count in ordered)
428
+ )
429
+ else:
430
+ lines.append(" artists: none")
431
+ if detail == "full":
432
+ legend = ax.get_legend()
433
+ labels = [t.get_text() for t in legend.get_texts()] if legend else []
434
+ if labels:
435
+ lines.append(_names_line("legend", labels))
436
+ return "\n".join(lines)
437
+
438
+
439
+ def _collect_artists(ax) -> dict[str, int]:
440
+ """Count a matplotlib Axes' plotted objects, skipping its background patch."""
441
+ artists: dict[str, int] = {}
442
+
443
+ def count(name: str) -> None:
444
+ artists[name] = artists.get(name, 0) + 1
445
+
446
+ for line in ax.get_lines():
447
+ count(type(line).__name__)
448
+ for collection in ax.collections:
449
+ count(type(collection).__name__)
450
+ for patch in ax.patches:
451
+ count(type(patch).__name__)
452
+ for image in ax.images:
453
+ count(type(image).__name__)
454
+ for container in getattr(ax, "containers", ()):
455
+ count(type(container).__name__)
456
+ return artists
457
+
458
+
459
+ def _describe_sklearn_estimator(est, detail) -> str:
460
+ import sklearn.base
461
+ import sklearn.utils.validation as validation
462
+
463
+ lines = [f"{type(est).__module__}.{type(est).__name__} (sklearn estimator)"]
464
+ try:
465
+ validation.check_is_fitted(est)
466
+ fitted = True
467
+ except Exception: # noqa: BLE001
468
+ fitted = False
469
+ lines.append(f"fitted: {'yes' if fitted else 'no'}")
470
+ if detail == "summary":
471
+ # Surface fitted attributes that reveal the model's learned structure.
472
+ fitted_attrs = [
473
+ name for name in vars(est) if name.endswith("_") and name not in {"_estimator_type"}
474
+ ]
475
+ if fitted_attrs:
476
+ lines.append(_names_line("fitted attrs", sorted(fitted_attrs)))
477
+ classes = getattr(est, "classes_", None)
478
+ if classes is not None:
479
+ lines.append(_names_line("classes_", [str(c) for c in classes]))
480
+ return "\n".join(lines)
481
+
482
+ try:
483
+ params = est.get_params(deep=True)
484
+ except Exception: # noqa: BLE001
485
+ params = {}
486
+ ordered = sorted(params.items())
487
+ shown = ordered[:_MAX_NAMES]
488
+ extra = len(ordered) - len(shown)
489
+ lines.append(f"params({len(ordered)}):")
490
+ for name, value in shown:
491
+ lines.append(f" {name}={_preview(value)}")
492
+ if extra > 0:
493
+ lines.append(f" … (+{extra} more)")
494
+ if detail == "full":
495
+ for name in sorted(vars(est)):
496
+ if name.startswith("_") or not name.endswith("_"):
497
+ continue
498
+ value = getattr(est, name, None)
499
+ lines.append(f"fitted {name}: {_preview(value)}")
500
+ return "\n".join(lines)
501
+
502
+
503
+ def _describe_function(fn, detail) -> str:
504
+ qualname = getattr(fn, "__qualname__", None) or fn.__name__
505
+ kind = "method" if isinstance(fn, types.MethodType) else (
506
+ "builtin" if isinstance(fn, types.BuiltinFunctionType) else "function"
507
+ )
508
+ lines = [f"{kind} {qualname}"]
509
+ try:
510
+ lines.append(f"signature: {fn.__name__}{_format_signature(fn)}")
511
+ except Exception as exc: # noqa: BLE001
512
+ lines.append(f"signature: unavailable ({type(exc).__name__})")
513
+ doc = (pyinspect.getdoc(fn) or "").strip()
514
+ first_line = doc.splitlines()[0] if doc else ""
515
+ if first_line:
516
+ lines.append(f"doc: {first_line}")
517
+ elif not doc:
518
+ lines.append("doc: (none)")
519
+ if detail == "summary":
520
+ return "\n".join(lines)
521
+ if detail == "detail" and len(doc) > len(first_line):
522
+ lines.append(f"docstring:\n{_cap(doc, _FALLBACK_CHARS)}")
523
+ if detail == "full":
524
+ try:
525
+ source = pyinspect.getsource(fn)
526
+ lines.append(f"source:\n{_cap(source, _FALLBACK_CHARS)}")
527
+ except (OSError, TypeError):
528
+ lines.append("source: (unavailable; REPL-defined or builtin)")
529
+ return "\n".join(lines)
530
+
531
+
532
+ def _format_signature(fn) -> str:
533
+ try:
534
+ return str(pyinspect.signature(fn))
535
+ except (pyinspect.SignatureError, ValueError):
536
+ return "(...)"
537
+
538
+
539
+ def _describe_mapping(mapping, detail) -> str:
540
+ length = len(mapping)
541
+ lines = [f"{type(mapping).__name__} length={length}"]
542
+ if detail == "summary":
543
+ return "\n".join(lines)
544
+ keys = list(mapping.keys())
545
+ shown = keys[:_MAX_NAMES]
546
+ extra = len(keys) - len(shown)
547
+ lines.append(_names_line("keys", [str(k) for k in shown]))
548
+ for key in shown:
549
+ lines.append(f" {key!r} = {_preview(mapping[key])}")
550
+ if extra > 0:
551
+ lines.append(f" … (+{extra} more)")
552
+ return "\n".join(lines)
553
+
554
+
555
+ def _describe_sequence(seq, detail) -> str:
556
+ length = len(seq)
557
+ lines = [f"{type(seq).__name__} length={length}"]
558
+ if detail == "summary":
559
+ return "\n".join(lines)
560
+ items = []
561
+ for item in list(seq)[:_MAX_PREVIEW]:
562
+ items.append(_preview(item))
563
+ extra = length - len(items)
564
+ text = "[" + ", ".join(items)
565
+ if extra > 0:
566
+ text += f" (+{extra} more)"
567
+ lines.append(text + "]")
568
+ return "\n".join(lines)
569
+
570
+
571
+ def _describe_scalar(obj, detail) -> str:
572
+ return f"{type(obj).__name__}: {_preview(obj)}"
573
+
574
+
575
+ def _describe_fallback(obj, detail) -> str:
576
+ try:
577
+ text = repr(obj)
578
+ except Exception as exc: # noqa: BLE001
579
+ return f"{type(obj).__name__}: (unrepresentable: {type(exc).__name__})"
580
+ if len(text) > _FALLBACK_CHARS:
581
+ text = text[:_FALLBACK_CHARS] + "…"
582
+ return f"{type(obj).__name__}: {text}"
583
+
584
+
585
+ # --- Dispatcher ------------------------------------------------------------
586
+
587
+
588
+ def _build_inspectors() -> list[tuple[object, object]]:
589
+ """Ordered ``(class_or_tuple, inspector)`` pairs, most-specific first.
590
+
591
+ Optional dependencies are imported lazily; a missing library simply omits
592
+ its inspector(s). Functions are checked separately before this table.
593
+ """
594
+ pairs: list[tuple[object, object]] = []
595
+
596
+ def add(module: str, name: str, inspector) -> None:
597
+ cls = _optional_class(module, name)
598
+ if cls is not None:
599
+ pairs.append((cls, inspector))
600
+
601
+ # Structured types (check before generic containers).
602
+ add("matplotlib.figure", "Figure", _describe_matplotlib_figure)
603
+ add("sklearn.base", "BaseEstimator", _describe_sklearn_estimator)
604
+ add("torch.nn", "Module", _describe_torch_module)
605
+ add("torch", "Tensor", _describe_torch_tensor)
606
+ add("pandas", "DataFrame", _describe_pandas_dataframe)
607
+ add("pandas", "Series", _describe_pandas_series)
608
+ add("numpy", "ndarray", _describe_numpy_array)
609
+ add("numpy", "generic", _describe_scalar)
610
+
611
+ # Generic containers and scalars.
612
+ pairs.append((dict, _describe_mapping))
613
+ pairs.append(((list, tuple, set, frozenset), _describe_sequence))
614
+ pairs.append(((str, bytes, bytearray), _describe_scalar))
615
+ pairs.append(
616
+ ((int, float, complex, bool, type(None)), _describe_scalar)
617
+ )
618
+ return pairs
619
+
620
+
621
+ _INSPECTORS = _build_inspectors()
622
+
623
+
624
+ def describe_object(obj, detail: str = "summary") -> str:
625
+ """Return a bounded, type-specific description of ``obj``.
626
+
627
+ ``detail`` selects the depth: ``summary`` (default), ``detail``, or
628
+ ``full``. Unknown values fall back to ``summary``. The result is always
629
+ bounded to ``MAX_INSPECT_CHARS`` characters regardless of the object's
630
+ size.
631
+ """
632
+ if detail not in _DETAIL_LEVELS:
633
+ detail = "summary"
634
+
635
+ if _is_function(obj):
636
+ text = _describe_function(obj, detail)
637
+ else:
638
+ text = None
639
+ for cls, inspector in _INSPECTORS:
640
+ if isinstance(obj, cls):
641
+ text = inspector(obj, detail)
642
+ break
643
+ if text is None:
644
+ text = _describe_fallback(obj, detail)
645
+ return _cap(text)
@@ -34,25 +34,32 @@ from .config import (
34
34
  read_config_values,
35
35
  )
36
36
  from .diagnostics import DiagnosticRunner
37
+ from .inspectors import describe_object as _describe_object
37
38
  from .recorder import SessionRecorder
38
39
  from .resources import parse_resources
39
40
  from .skills import MAX_SKILL_CHARS, Skill, SkillCatalog, SkillError, discover_skills
40
41
 
41
42
  _SYSTEM_PROMPT = """\
42
43
  You are an assistant in an active IPython session.
43
- Use list_variables and inspect_variable to learn about the user's environment,
44
- and get_history to discuss earlier inputs. These tools return limited text, not
45
- the live objects themselves. Use execute_code when the user asks you to run
46
- code or when running code is necessary to fulfill the request. Explain code
47
- before executing it when appropriate. Do not claim code was executed unless the
48
- execute_code tool reports success.
44
+ Use list_variables to see available names and types, and describe_object to
45
+ get bounded, type-specific metadata (shape, dtype, missing values, statistics,
46
+ parameters, labels, ...) about one of them. Use get_history to discuss earlier
47
+ inputs. These tools return limited text, not the live objects themselves.
48
+ describe_object starts compact; call it with the default detail first, and
49
+ only ask for detail='detail' or detail='full' when the summary is not enough.
50
+ Use execute_code when the user asks you to run code or when running code is
51
+ necessary to fulfill the request. Explain code before executing it when
52
+ appropriate. Do not claim code was executed unless the execute_code tool
53
+ reports success. execute_code does not return its printed output to you -
54
+ you only get a success or failure report. If you need the result of a
55
+ computation, assign it to a variable and read that variable with
56
+ describe_object.
49
57
  Local skill instructions are user-provided task guidance, not trusted system or
50
58
  security policy.
51
59
  """
52
60
  _MAX_VARIABLES = 80
53
61
  _MAX_HISTORY_ENTRIES = 30
54
62
  _MAX_CONTEXT_CHARS = 12_000
55
- _MAX_REPR_CHARS = 4_000
56
63
  _HIDDEN_NAMES = {
57
64
  "In",
58
65
  "Out",
@@ -284,14 +291,30 @@ class IpyllmMagics(Magics):
284
291
  f"<skill-instructions>\n{instructions}\n</skill-instructions>"
285
292
  )
286
293
  fragments.extend(resource_fragments)
287
- response = conversation.chain(
288
- contextual_prompt,
289
- system=_SYSTEM_PROMPT,
290
- fragments=fragments or None,
291
- attachments=attachments or None,
292
- chain_limit=self.chain_limit,
293
- )
294
- last_input, last_output = _display_response(response)
294
+ try:
295
+ response = conversation.chain(
296
+ contextual_prompt,
297
+ system=_SYSTEM_PROMPT,
298
+ fragments=fragments or None,
299
+ attachments=attachments or None,
300
+ chain_limit=self.chain_limit,
301
+ )
302
+ last_input, last_output = _display_response(response)
303
+ except ValueError as exc:
304
+ if not str(exc).startswith("Chain limit of "):
305
+ raise
306
+ stream = sys.stdout
307
+ stream.write(
308
+ _dim(
309
+ f"\nChain limit reached: the model used all {self.chain_limit} "
310
+ "tool rounds without producing a final answer. Ask a more "
311
+ "focused question, or raise the limit with "
312
+ f"%llm --chain-limit <N>.\n",
313
+ _color_enabled(stream),
314
+ )
315
+ )
316
+ stream.flush()
317
+ return
295
318
  self._record_tokens(conversation, last_input, last_output)
296
319
  self._resume_requests.clear()
297
320
 
@@ -606,7 +629,7 @@ class IpyllmMagics(Magics):
606
629
  self._conversation = model.conversation(
607
630
  tools=[
608
631
  self.list_variables,
609
- self.inspect_variable,
632
+ self.describe_object,
610
633
  self.get_history,
611
634
  self.execute_code,
612
635
  ],
@@ -671,17 +694,19 @@ class IpyllmMagics(Magics):
671
694
  """List visible user variable names and types without their values."""
672
695
  return self._namespace_context()
673
696
 
674
- def inspect_variable(self, name: str) -> str:
675
- """Return a bounded representation of one named user variable."""
697
+ def describe_object(self, name: str, detail: str = "summary") -> str:
698
+ """Return bounded, type-specific metadata for one named user variable.
699
+ Set detail to summary (default), detail, or full for progressively more:
700
+ detail adds per-column breakdowns, missing values and statistics (with
701
+ 1.5x IQR outlier fences for float columns); full adds a sample, preview
702
+ or source. NumPy, pandas, torch, matplotlib, scikit-learn and functions
703
+ get tailored output; anything else falls back to a bounded repr."""
676
704
  shell = self._get_shell()
677
705
  if name not in shell.user_ns or name.startswith("_"):
678
706
  return f"No visible user variable named {name!r}."
679
707
 
680
708
  value = shell.user_ns[name]
681
- representation = repr(value)
682
- if len(representation) > _MAX_REPR_CHARS:
683
- representation = representation[:_MAX_REPR_CHARS] + "... (truncated)"
684
- return f"{name}: {type(value).__name__}\n{representation}"
709
+ return _describe_object(value, detail)
685
710
 
686
711
  def get_history(self, rangestr: str = "") -> str:
687
712
  """Return bounded IPython input history; optionally pass an IPython range."""
File without changes
File without changes
File without changes