aipython-shell 0.2.0__py3-none-any.whl
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.
- aipython/__init__.py +28 -0
- aipython/cli.py +17 -0
- aipython/config.py +82 -0
- aipython/context.py +198 -0
- aipython/detect.py +81 -0
- aipython/llm.py +238 -0
- aipython/log.py +72 -0
- aipython/shell.py +208 -0
- aipython_shell-0.2.0.dist-info/METADATA +256 -0
- aipython_shell-0.2.0.dist-info/RECORD +13 -0
- aipython_shell-0.2.0.dist-info/WHEEL +4 -0
- aipython_shell-0.2.0.dist-info/entry_points.txt +2 -0
- aipython_shell-0.2.0.dist-info/licenses/LICENSE +373 -0
aipython/log.py
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# This Source Code Form is subject to the terms of the Mozilla Public
|
|
2
|
+
# License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
3
|
+
# file, You can obtain one at https://mozilla.org/MPL/2.0/.
|
|
4
|
+
|
|
5
|
+
"""Session logs.
|
|
6
|
+
|
|
7
|
+
With logging on (it is off by default), a session is written as a .py file: each cell's code
|
|
8
|
+
in order, with what the user typed as a comment above any code the model wrote. It reads as
|
|
9
|
+
the Python the session became, and `ipython <file>` replays it. With debug on, a .jsonl file
|
|
10
|
+
next to it holds the full exchange with the model for each translation.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
import datetime
|
|
14
|
+
import json
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _comment(text):
|
|
18
|
+
return "\n".join(f"# {line}".rstrip() for line in text.splitlines())
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class SessionLog:
|
|
22
|
+
def __init__(self, directory, enabled=False, debug=False):
|
|
23
|
+
self.directory = directory
|
|
24
|
+
self.enabled = enabled
|
|
25
|
+
self.debug = debug
|
|
26
|
+
stamp = datetime.datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
|
|
27
|
+
self.path = directory / f"{stamp}.py"
|
|
28
|
+
self.debug_path = directory / f"{stamp}.jsonl"
|
|
29
|
+
|
|
30
|
+
def _append(self, path, text):
|
|
31
|
+
new = not path.exists()
|
|
32
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
33
|
+
with open(path, "a", encoding="utf-8") as f:
|
|
34
|
+
if new and path == self.path:
|
|
35
|
+
f.write(f"# aipython session {datetime.datetime.now():%Y-%m-%d %H:%M}\n"
|
|
36
|
+
f"# replay with: ipython {path.name}\n\n")
|
|
37
|
+
f.write(text)
|
|
38
|
+
|
|
39
|
+
def cell(self, number, raw, code, translation=None, error=None):
|
|
40
|
+
"""Record one executed cell: `code` is what ran, `raw` what was typed."""
|
|
41
|
+
if not self.enabled:
|
|
42
|
+
return
|
|
43
|
+
raw, code = raw.strip(), (code or "").strip()
|
|
44
|
+
if translation:
|
|
45
|
+
header = (f"# [{number}] " + _comment(raw)[2:] + "\n"
|
|
46
|
+
f"# ✨ {translation.model} · {translation.usage_text()}")
|
|
47
|
+
elif code != raw: # IPython syntax such as %magic or !shell
|
|
48
|
+
header = f"# [{number}] " + _comment(raw)[2:]
|
|
49
|
+
else:
|
|
50
|
+
header = f"# [{number}]"
|
|
51
|
+
text = f"{header}\n{code}\n"
|
|
52
|
+
if error:
|
|
53
|
+
text += f"# ! {error.splitlines()[0][:200]}\n"
|
|
54
|
+
self._append(self.path, text + "\n")
|
|
55
|
+
|
|
56
|
+
def exchange(self, number, request, translation):
|
|
57
|
+
"""With debug on, record the full model exchange for one translation."""
|
|
58
|
+
if not self.debug:
|
|
59
|
+
return
|
|
60
|
+
entry = {
|
|
61
|
+
"cell": number,
|
|
62
|
+
"time": datetime.datetime.now().isoformat(timespec="seconds"),
|
|
63
|
+
"request": request,
|
|
64
|
+
"model": translation.model,
|
|
65
|
+
"input_tokens": translation.input_tokens,
|
|
66
|
+
"output_tokens": translation.output_tokens,
|
|
67
|
+
"cost": translation.cost,
|
|
68
|
+
"seconds": round(translation.seconds, 2),
|
|
69
|
+
"code": translation.code,
|
|
70
|
+
"messages": translation.messages,
|
|
71
|
+
}
|
|
72
|
+
self._append(self.debug_path, json.dumps(entry, default=str) + "\n")
|
aipython/shell.py
ADDED
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
# This Source Code Form is subject to the terms of the Mozilla Public
|
|
2
|
+
# License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
3
|
+
# file, You can obtain one at https://mozilla.org/MPL/2.0/.
|
|
4
|
+
|
|
5
|
+
"""Hook the AI into IPython's input pipeline.
|
|
6
|
+
|
|
7
|
+
Every cell first goes through IPython's own transforms (magics, !shell, x?). If the result
|
|
8
|
+
is Python whose names all resolve, it runs untouched. Otherwise the cell is sent to the model
|
|
9
|
+
and the code it returns runs in its place. `In[n]` holds the code that ran; the prompt
|
|
10
|
+
history (up-arrow) keeps what the user typed.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
import atexit
|
|
14
|
+
import collections
|
|
15
|
+
import sys
|
|
16
|
+
from dataclasses import dataclass
|
|
17
|
+
|
|
18
|
+
from IPython.core.magic import Magics, line_magic, magics_class
|
|
19
|
+
|
|
20
|
+
from . import config, context, detect
|
|
21
|
+
from .llm import MODELS, Translator, format_cost, provider
|
|
22
|
+
from .log import SessionLog
|
|
23
|
+
|
|
24
|
+
HISTORY_CELLS = 8
|
|
25
|
+
HELP = """\
|
|
26
|
+
%ai show status
|
|
27
|
+
%ai on | off turn automatic translation on or off
|
|
28
|
+
%ai model <name> haiku, sonnet, opus, or any litellm model, e.g. openai/gpt-5.4,
|
|
29
|
+
ollama_chat/qwen2.5-coder
|
|
30
|
+
%ai config show settings and where they come from
|
|
31
|
+
%ai context show the namespace summary the model sees
|
|
32
|
+
%ai log [on | off] log this session as a .py file (off by default), show where
|
|
33
|
+
%ai debug on | off also log the full exchange with the model (.jsonl)
|
|
34
|
+
%ai last show the last generated code
|
|
35
|
+
%ai <anything> translate even if it already looks like Python"""
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass
|
|
39
|
+
class Totals:
|
|
40
|
+
translations: int = 0
|
|
41
|
+
input_tokens: int = 0
|
|
42
|
+
output_tokens: int = 0
|
|
43
|
+
cost: float = 0.0
|
|
44
|
+
|
|
45
|
+
def add(self, translation):
|
|
46
|
+
self.translations += 1
|
|
47
|
+
self.input_tokens += translation.input_tokens
|
|
48
|
+
self.output_tokens += translation.output_tokens
|
|
49
|
+
self.cost += translation.cost or 0
|
|
50
|
+
|
|
51
|
+
def text(self):
|
|
52
|
+
s = "" if self.translations == 1 else "s"
|
|
53
|
+
text = (f"{self.translations} translation{s} · {self.input_tokens:,} in / "
|
|
54
|
+
f"{self.output_tokens:,} out tokens")
|
|
55
|
+
return text + (f" · {format_cost(self.cost)}" if self.cost else "")
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
class AIShell:
|
|
59
|
+
def __init__(self, shell, translator=None, log=None):
|
|
60
|
+
self.shell = shell
|
|
61
|
+
self.translator = translator or Translator(config.load())
|
|
62
|
+
settings = self.translator.settings
|
|
63
|
+
self.log = log or SessionLog(settings.log_dir, settings.log, settings.debug)
|
|
64
|
+
self.enabled = True
|
|
65
|
+
self.totals = Totals()
|
|
66
|
+
self.history = collections.deque(maxlen=HISTORY_CELLS)
|
|
67
|
+
self.last_error = None
|
|
68
|
+
self.last_code = None
|
|
69
|
+
self._raw = ""
|
|
70
|
+
self._code = None
|
|
71
|
+
self._translation = None
|
|
72
|
+
|
|
73
|
+
# -- IPython hooks -------------------------------------------------------
|
|
74
|
+
|
|
75
|
+
def capture_raw(self, lines):
|
|
76
|
+
"""Cleanup transformer: remember the cell exactly as typed."""
|
|
77
|
+
self._raw = "".join(lines)
|
|
78
|
+
self._code = self._translation = None
|
|
79
|
+
return lines
|
|
80
|
+
|
|
81
|
+
def transform(self, lines):
|
|
82
|
+
"""Post transformer: swap non-Python cells for generated code."""
|
|
83
|
+
code = self._code = "".join(lines)
|
|
84
|
+
forced = (detect.ai_magic_text(code) or "").split()
|
|
85
|
+
if forced and forced[0] not in Magic.SUBCOMMANDS:
|
|
86
|
+
request = " ".join(forced)
|
|
87
|
+
elif self.enabled and not detect.classify(self._raw, code, self.known_names())[0]:
|
|
88
|
+
request = self._raw.strip()
|
|
89
|
+
else:
|
|
90
|
+
return lines
|
|
91
|
+
|
|
92
|
+
try:
|
|
93
|
+
translation = self.translator.translate(
|
|
94
|
+
self.shell, request, list(self.history), self.last_error)
|
|
95
|
+
except KeyboardInterrupt:
|
|
96
|
+
print("(cancelled)")
|
|
97
|
+
return []
|
|
98
|
+
except Exception as e:
|
|
99
|
+
print(f"🤖 AI unavailable ({type(e).__name__}: {e}); running the cell as typed",
|
|
100
|
+
file=sys.stderr)
|
|
101
|
+
return lines
|
|
102
|
+
self._translation = translation
|
|
103
|
+
self.last_code = translation.code
|
|
104
|
+
self.totals.add(translation)
|
|
105
|
+
try:
|
|
106
|
+
self.log.exchange(self.shell.execution_count, request, translation)
|
|
107
|
+
except OSError as e:
|
|
108
|
+
print(f"aipython: debug log turned off ({e})", file=sys.stderr)
|
|
109
|
+
self.log.debug = False
|
|
110
|
+
return translation.code.splitlines(keepends=True) + ["\n"]
|
|
111
|
+
|
|
112
|
+
def post_run_cell(self, result):
|
|
113
|
+
raw = result.info.raw_cell if result.info else self._raw
|
|
114
|
+
error = result.error_before_exec or result.error_in_exec
|
|
115
|
+
self.last_error = f"{type(error).__name__}: {error}" if error is not None else None
|
|
116
|
+
if not raw.strip():
|
|
117
|
+
return
|
|
118
|
+
generated = self._translation.code if self._translation else None
|
|
119
|
+
self.history.append({"raw": raw.strip(), "code": generated, "error": self.last_error})
|
|
120
|
+
is_control = not self._translation and raw.lstrip().startswith("%ai")
|
|
121
|
+
if not is_control:
|
|
122
|
+
try:
|
|
123
|
+
self.log.cell(result.execution_count, raw, generated or self._code or raw,
|
|
124
|
+
self._translation, self.last_error)
|
|
125
|
+
except OSError as e:
|
|
126
|
+
print(f"aipython: session log turned off ({e})", file=sys.stderr)
|
|
127
|
+
self.log.enabled = False
|
|
128
|
+
|
|
129
|
+
def print_totals(self):
|
|
130
|
+
if self.totals.translations:
|
|
131
|
+
print(f"aipython: {self.totals.text()}")
|
|
132
|
+
|
|
133
|
+
def known_names(self):
|
|
134
|
+
magics = self.shell.magics_manager.magics
|
|
135
|
+
return set(self.shell.user_ns) | set(magics["line"]) | set(magics["cell"])
|
|
136
|
+
|
|
137
|
+
# -- install -------------------------------------------------------------
|
|
138
|
+
|
|
139
|
+
def install(self):
|
|
140
|
+
self.shell.input_transformers_cleanup.insert(0, self.capture_raw)
|
|
141
|
+
self.shell.input_transformers_post.append(self.transform)
|
|
142
|
+
self.shell.events.register("post_run_cell", self.post_run_cell)
|
|
143
|
+
self.shell.register_magics(Magic(self.shell, self))
|
|
144
|
+
atexit.register(self.print_totals)
|
|
145
|
+
|
|
146
|
+
def uninstall(self):
|
|
147
|
+
self.shell.input_transformers_cleanup.remove(self.capture_raw)
|
|
148
|
+
self.shell.input_transformers_post.remove(self.transform)
|
|
149
|
+
self.shell.events.unregister("post_run_cell", self.post_run_cell)
|
|
150
|
+
atexit.unregister(self.print_totals)
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
@magics_class
|
|
154
|
+
class Magic(Magics):
|
|
155
|
+
SUBCOMMANDS = {"on", "off", "model", "config", "context", "last", "log", "debug", "help"}
|
|
156
|
+
|
|
157
|
+
def __init__(self, shell, ai):
|
|
158
|
+
super().__init__(shell)
|
|
159
|
+
self.ai = ai
|
|
160
|
+
|
|
161
|
+
@line_magic
|
|
162
|
+
def ai(self, line):
|
|
163
|
+
"""Control aipython. `%ai help` lists the subcommands."""
|
|
164
|
+
cmd, _, arg = line.strip().partition(" ")
|
|
165
|
+
if cmd in ("on", "off"):
|
|
166
|
+
self.ai.enabled = cmd == "on"
|
|
167
|
+
elif cmd == "model" and arg:
|
|
168
|
+
self.ai.translator.model = MODELS.get(arg.strip(), arg.strip())
|
|
169
|
+
elif cmd == "config":
|
|
170
|
+
self.show_config()
|
|
171
|
+
return
|
|
172
|
+
elif cmd == "context":
|
|
173
|
+
print(context.namespace_summary(self.shell))
|
|
174
|
+
return
|
|
175
|
+
elif cmd == "last":
|
|
176
|
+
print(self.ai.last_code or "(nothing generated yet)")
|
|
177
|
+
return
|
|
178
|
+
elif cmd in ("log", "debug"):
|
|
179
|
+
if arg in ("on", "off"):
|
|
180
|
+
setattr(self.ai.log, "enabled" if cmd == "log" else "debug", arg == "on")
|
|
181
|
+
self.show_log()
|
|
182
|
+
return
|
|
183
|
+
elif cmd == "help":
|
|
184
|
+
print(HELP)
|
|
185
|
+
return
|
|
186
|
+
state = "on" if self.ai.enabled else "off"
|
|
187
|
+
print(f"aipython {state}, model {self.ai.translator.model}")
|
|
188
|
+
if self.ai.totals.translations:
|
|
189
|
+
print(f"this session: {self.ai.totals.text()}")
|
|
190
|
+
|
|
191
|
+
def show_log(self):
|
|
192
|
+
log = self.ai.log
|
|
193
|
+
print(f"session log: {log.path}" if log.enabled else "session log: off (%ai log on)")
|
|
194
|
+
print(f"debug log: {log.debug_path}" if log.debug else "debug log: off (%ai debug on)")
|
|
195
|
+
|
|
196
|
+
def show_config(self):
|
|
197
|
+
settings = self.ai.translator.settings
|
|
198
|
+
found = "" if settings.path and settings.path.exists() else " (not found)"
|
|
199
|
+
print(f"config file: {settings.path}{found}")
|
|
200
|
+
print(f"model: {self.ai.translator.model}")
|
|
201
|
+
if settings.api_base:
|
|
202
|
+
print(f"api_base: {settings.api_base}")
|
|
203
|
+
current = provider(self.ai.translator.model)
|
|
204
|
+
for name, key in settings.keys.items():
|
|
205
|
+
used = " <- in use" if name == current else ""
|
|
206
|
+
print(f"key {name}: {config.mask(key)}{used}")
|
|
207
|
+
if current not in settings.keys:
|
|
208
|
+
print(f"key {current}: from the environment, if set")
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: aipython-shell
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: IPython that understands what you meant: non-Python cells are turned into Python by an LLM and run.
|
|
5
|
+
Author: Claus Dahl
|
|
6
|
+
License-Expression: MPL-2.0
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Keywords: ai,claude,data science,ipython,llm,natural language,ollama,openai,repl
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Framework :: IPython
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering
|
|
17
|
+
Classifier: Topic :: Software Development :: Interpreters
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Requires-Dist: ipython>=8.0
|
|
20
|
+
Requires-Dist: litellm>=1.109
|
|
21
|
+
Requires-Dist: pyflakes>=3.0
|
|
22
|
+
Requires-Dist: tomli>=2.0; python_version < '3.11'
|
|
23
|
+
Provides-Extra: test
|
|
24
|
+
Requires-Dist: pandas; extra == 'test'
|
|
25
|
+
Requires-Dist: pytest; extra == 'test'
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# aipython
|
|
29
|
+
|
|
30
|
+
**IPython that understands what you meant.**
|
|
31
|
+
|
|
32
|
+
[](https://github.com/clausd/aipython/actions/workflows/ci.yml)
|
|
33
|
+
[](https://pypi.org/project/aipython-shell/)
|
|
34
|
+
[](LICENSE)
|
|
35
|
+
|
|
36
|
+
`aipython` is a plain IPython shell with one difference: when a cell isn't valid Python, an LLM
|
|
37
|
+
turns it into Python and runs it. Type code when you know the code, type what you want when you
|
|
38
|
+
don't, and mix the two freely. Real Python never touches the model and runs with no delay.
|
|
39
|
+
|
|
40
|
+
## A real session
|
|
41
|
+
|
|
42
|
+
An excerpt from an actual session: the lines after `In [n]:` are what was typed, the dimmed
|
|
43
|
+
`✨` lines are the code the model wrote, streamed in as it was generated and then run.
|
|
44
|
+
Outputs are left out.
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
In [1]: Find the most recent csv in ~/Downloads and load it as a pandas df
|
|
48
|
+
✨ import glob, os
|
|
49
|
+
import pandas as pd
|
|
50
|
+
|
|
51
|
+
latest_csv = max(glob.glob(os.path.expanduser("~/Downloads/*.csv")), key=os.path.getmtime)
|
|
52
|
+
df = pd.read_csv(latest_csv)
|
|
53
|
+
print(latest_csv)
|
|
54
|
+
df.head()
|
|
55
|
+
|
|
56
|
+
In [2]: list the column names
|
|
57
|
+
✨ df.columns.tolist()
|
|
58
|
+
|
|
59
|
+
In [6]: df.date.min()
|
|
60
|
+
|
|
61
|
+
In [8]: convert the date column to actual dates
|
|
62
|
+
✨ df['date'] = pd.to_datetime(df['date'], errors='coerce')
|
|
63
|
+
df['date'].dtype
|
|
64
|
+
|
|
65
|
+
In [9]: df.date.min()
|
|
66
|
+
|
|
67
|
+
In [13]: list all unique dates
|
|
68
|
+
✨ sorted(df['date'].dt.date.unique())
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Cells 6 and 9 are ordinary Python, so they ran directly without a model call.
|
|
72
|
+
|
|
73
|
+
## Install
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pipx install aipython-shell # or: uv tool install aipython-shell / pip install aipython-shell
|
|
77
|
+
export ANTHROPIC_API_KEY=... # the default model is Claude Haiku
|
|
78
|
+
aipython
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Or load it into any IPython session with `%load_ext aipython`.
|
|
82
|
+
|
|
83
|
+
If you work with pandas and friends, install aipython into the same environment as them
|
|
84
|
+
(`pip install aipython-shell`) so the generated code can import them. A `pipx` install lives in its own
|
|
85
|
+
environment.
|
|
86
|
+
|
|
87
|
+
## How it works
|
|
88
|
+
|
|
89
|
+
Every cell goes through the same steps:
|
|
90
|
+
|
|
91
|
+
1. **IPython first.** IPython's own transforms run as usual, so `%magics`, `!shell` commands and
|
|
92
|
+
`obj?` help all behave normally.
|
|
93
|
+
2. **Is it Python?** The cell is parsed and checked with pyflakes against your live variables.
|
|
94
|
+
If it parses and every name it uses exists, it runs untouched. This check is local and instant.
|
|
95
|
+
3. **If not, ask the model.** Syntax errors, unknown names (`describe`, `prnt(x)`), and English
|
|
96
|
+
that IPython would mistake for a magic or help request (`reset the index of df`,
|
|
97
|
+
`what is x?`) go to the model. The model writes Python, which streams to your terminal and runs.
|
|
98
|
+
|
|
99
|
+
The model gets enough context to write code that fits your session:
|
|
100
|
+
|
|
101
|
+
- a summary of your variables: types, shapes, DataFrame columns and dtypes, imported modules,
|
|
102
|
+
function signatures
|
|
103
|
+
- your last few cells, the code generated for them, and any errors, so "fix that" and
|
|
104
|
+
"try again" work
|
|
105
|
+
- tools to look closer when the summary isn't enough: `inspect_variable` (dtypes, null counts,
|
|
106
|
+
first rows), `column_values` (exact category spellings) and `search_namespace`
|
|
107
|
+
|
|
108
|
+
`In[n]` holds the code that actually ran. Up-arrow brings back what you typed.
|
|
109
|
+
|
|
110
|
+
## Token use
|
|
111
|
+
|
|
112
|
+
Each translation ends with one dim line showing what it cost:
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
In [2]: list the column names
|
|
116
|
+
✨ df.columns.tolist()
|
|
117
|
+
↳ 1,204 in · 14 out · $0.0001 · 0.8s
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`%ai` shows the running total for the session, and it is printed when you exit:
|
|
121
|
+
|
|
122
|
+
```
|
|
123
|
+
aipython: 12 translations · 15,880 in / 702 out tokens · $0.0019
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Costs come from litellm's price list. They are left out for models without a known price, and
|
|
127
|
+
for free local models; token counts are always shown.
|
|
128
|
+
|
|
129
|
+
## Session logs
|
|
130
|
+
|
|
131
|
+
Off by default. Turn on with `%ai log on`, or `log = true` in the config file, and the session
|
|
132
|
+
is written as a Python file: every cell in order, with what you typed as a comment above the
|
|
133
|
+
code the model wrote for it.
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
# [1] Find the most recent csv in ~/Downloads and load it as a pandas df
|
|
137
|
+
# ✨ anthropic/claude-haiku-5-5 · 1,204 in · 61 out · $0.0002 · 1.1s
|
|
138
|
+
import glob, os
|
|
139
|
+
import pandas as pd
|
|
140
|
+
...
|
|
141
|
+
|
|
142
|
+
# [6]
|
|
143
|
+
df.date.min()
|
|
144
|
+
|
|
145
|
+
# [11]
|
|
146
|
+
df.date.uniq()
|
|
147
|
+
# ! AttributeError: 'Series' object has no attribute 'uniq'
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
It reads as the Python your session became, and `ipython <file>` replays it. Logs go to
|
|
151
|
+
`~/.local/share/aipython/sessions/` (or `$XDG_DATA_HOME/aipython/sessions/`, or `log_dir` in the
|
|
152
|
+
config), one file per session, named by start time. `%ai log` shows the current file.
|
|
153
|
+
|
|
154
|
+
To see everything the model was given and did (the variable summary, recent cells, tool calls
|
|
155
|
+
and their results, token counts), turn on the debug log with `%ai debug on` or `debug = true`.
|
|
156
|
+
It writes one JSON line per translation to a `.jsonl` file next to the session log. The two
|
|
157
|
+
logs are independent.
|
|
158
|
+
|
|
159
|
+
Even with both off, IPython's own history keeps both versions of every cell: `%history` lists
|
|
160
|
+
the code that ran, `%history -r` what you typed.
|
|
161
|
+
|
|
162
|
+
## What is sent to the model
|
|
163
|
+
|
|
164
|
+
Only cells that aren't Python are sent. With each one goes the variable summary above,
|
|
165
|
+
including short previews of small values (up to 80 characters each), plus your recent cells.
|
|
166
|
+
More is sent only if the model asks for it through a tool: the first 5 rows of a DataFrame,
|
|
167
|
+
the first 10 values of a Series, the most common values of one column, or a longer preview
|
|
168
|
+
(up to 1500 characters) of another object. If that is too much for your data, use a
|
|
169
|
+
local model (see below) or `%ai off`.
|
|
170
|
+
|
|
171
|
+
## Commands
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
%ai status and tokens used this session
|
|
175
|
+
%ai on | off turn automatic translation on or off
|
|
176
|
+
%ai model <name> haiku (default), sonnet, opus, or any litellm model
|
|
177
|
+
%ai config settings, config file location, which key is in use
|
|
178
|
+
%ai context the variable summary the model sees
|
|
179
|
+
%ai last the last generated code
|
|
180
|
+
%ai log [on | off] write this session as a .py file (off by default); show where
|
|
181
|
+
%ai debug on | off also log the full exchange with the model (.jsonl)
|
|
182
|
+
%ai <anything> send this to the model even if it looks like Python
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## Models
|
|
186
|
+
|
|
187
|
+
Models are reached through [litellm](https://docs.litellm.ai/docs/providers), so any provider it
|
|
188
|
+
supports works. Choose one with `%ai model <name>` or the `AIPYTHON_MODEL` environment variable,
|
|
189
|
+
and set that provider's usual API key:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
AIPYTHON_MODEL=anthropic/claude-sonnet-5-5 # ANTHROPIC_API_KEY
|
|
193
|
+
AIPYTHON_MODEL=openai/gpt-5.4 # OPENAI_API_KEY
|
|
194
|
+
AIPYTHON_MODEL=ollama_chat/qwen2.5-coder # local Ollama, no key
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
For any OpenAI-compatible server (LM Studio, vLLM, llama.cpp), use `openai/<model>` and set
|
|
198
|
+
`AIPYTHON_API_BASE`, e.g. `http://localhost:1234/v1`.
|
|
199
|
+
|
|
200
|
+
Models without tool calling still work, with only the variable summary to go on. Small local
|
|
201
|
+
models are noticeably worse at this than hosted ones.
|
|
202
|
+
|
|
203
|
+
## Configuration
|
|
204
|
+
|
|
205
|
+
Without a config file, aipython uses your environment: the provider's usual API key variable and
|
|
206
|
+
the default model. To keep settings and keys in one place, create
|
|
207
|
+
`~/.config/aipython/config.toml`:
|
|
208
|
+
|
|
209
|
+
```toml
|
|
210
|
+
model = "anthropic/claude-sonnet-5-5"
|
|
211
|
+
# api_base = "http://localhost:1234/v1"
|
|
212
|
+
# log = true # write each session as a .py file (default false)
|
|
213
|
+
# debug = true # also log the full exchange with the model (default false)
|
|
214
|
+
# log_dir = "~/notes/aipython"
|
|
215
|
+
|
|
216
|
+
[keys] # one per provider, used when that provider's model is selected
|
|
217
|
+
anthropic = "sk-ant-..."
|
|
218
|
+
openai = "sk-..."
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
- Keys are passed directly to the model call and never put into the environment, so code you
|
|
222
|
+
run in the session can't read them.
|
|
223
|
+
- A provider without a key in the file falls back to its environment variable.
|
|
224
|
+
- `AIPYTHON_MODEL` and `AIPYTHON_API_BASE` override the file; `AIPYTHON_CONFIG` points to a
|
|
225
|
+
different file, and `$XDG_CONFIG_HOME` is respected.
|
|
226
|
+
- aipython warns at startup if the file is readable by other users (`chmod 600` it).
|
|
227
|
+
|
|
228
|
+
## Limitations
|
|
229
|
+
|
|
230
|
+
- **Valid Python is trusted as Python.** `df.date.uniq()` parses and `df` exists, so it runs and
|
|
231
|
+
fails with an `AttributeError` instead of being fixed. Typing `fix that` afterwards works,
|
|
232
|
+
because the error is passed to the model.
|
|
233
|
+
- **Generated code runs without asking.** It streams to the screen as it runs, so you see what
|
|
234
|
+
happened, but there is no confirmation step. Use `%ai off` when that matters.
|
|
235
|
+
- A line of English ending in `:` makes IPython wait for more input, as it would for a `for`
|
|
236
|
+
loop. Press Enter again.
|
|
237
|
+
|
|
238
|
+
## Development
|
|
239
|
+
|
|
240
|
+
```bash
|
|
241
|
+
uv run --extra test pytest
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Releases go to PyPI through GitHub Actions with
|
|
245
|
+
[Trusted Publishing](https://docs.pypi.org/trusted-publishers/). To release, bump `__version__`
|
|
246
|
+
in `aipython/__init__.py`, push, and run `gh release create vX.Y.Z --generate-notes`.
|
|
247
|
+
|
|
248
|
+
The PyPI project is `aipython-shell` (`aipython` is taken by its similarity to `ai-python`); the
|
|
249
|
+
package, the command and `%load_ext` are all `aipython`.
|
|
250
|
+
|
|
251
|
+
One-time setup on PyPI: add a pending publisher for project `aipython-shell`, owner `clausd`,
|
|
252
|
+
repository `aipython`, workflow `publish.yml`, environment `pypi`.
|
|
253
|
+
|
|
254
|
+
## License
|
|
255
|
+
|
|
256
|
+
[Mozilla Public License 2.0](LICENSE).
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
aipython/__init__.py,sha256=UbNK8Kg-8MR5BYJ_vR8qlpuMFE--bXY7SwUk55MU_bw,803
|
|
2
|
+
aipython/cli.py,sha256=dSyfhR6A7bT8FWPu1S-6kBwbdT0myQEiM8FGZE1yhKQ,427
|
|
3
|
+
aipython/config.py,sha256=UwqjDojM10T8e1GwcJuVUF3fgJ-yw15S3RSidn8aj9I,2963
|
|
4
|
+
aipython/context.py,sha256=hieBarYhAgZnnawMXDjXE_OZCEq_W4xVzVdoXnHvMkk,7674
|
|
5
|
+
aipython/detect.py,sha256=a3H1ZUoU1uoRt3QGU86vxXuY7e1Zo6Amer-hcpgKWBo,2784
|
|
6
|
+
aipython/llm.py,sha256=esmz10aYzDYP33Yol9vufcXkRju8Yn5X4itQLCA3yUw,8753
|
|
7
|
+
aipython/log.py,sha256=hJly6OWe64MdZvhS9fitpyyDvKw00WMVbMUgc1-EhKs,2959
|
|
8
|
+
aipython/shell.py,sha256=HyZDbPxjbW9-2WvTHj5X9sWH01SCTco2KMeQA0WivhU,8462
|
|
9
|
+
aipython_shell-0.2.0.dist-info/METADATA,sha256=P_sSaZEnUaT4sXKtDf1qcxNkKl2uTuVOqNxvE6M6r8M,10180
|
|
10
|
+
aipython_shell-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
11
|
+
aipython_shell-0.2.0.dist-info/entry_points.txt,sha256=doj1XbjFi83KbhYzG5ND2BcvX_sexrSzughJ73I4dZM,47
|
|
12
|
+
aipython_shell-0.2.0.dist-info/licenses/LICENSE,sha256=Pz2eACSxkhsGfW9_iN60pgy-enjnbGTj8df8O3ebnQQ,16726
|
|
13
|
+
aipython_shell-0.2.0.dist-info/RECORD,,
|