Metadata-Version: 2.4
Name: codebind
Version: 0.6.3
Summary: A frontend-neutral model loop for persistent IPython sessions.
Keywords: ai,ipython,llm,repl,agents
Author: Giovanni Gravili
Author-email: Giovanni Gravili <ghovax@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: ipython>=9.0
Requires-Dist: langchain-core>=1.0
Requires-Dist: models-provider>=0.1.2
Requires-Dist: pillow>=11
Requires-Dist: resvg-py>=0.5
Requires-Python: >=3.13
Project-URL: Repository, https://github.com/ghovax/codebind
Project-URL: Issues, https://github.com/ghovax/codebind/issues
Description-Content-Type: text/markdown

# Codebind

Codebind turns an ordinary IPython session into a durable model harness with one tool: an IPython cell executed in the active session. IPython owns execution, namespace, history, magics, tracebacks, and rich display; Codebind owns conversation state and model orchestration.

## Installation

```console
uvx codebind
```

Or install it with any Python package installer:

```console
pip install codebind
```

## Configuration

Codebind reads its private model choice from `$XDG_CONFIG_HOME/codebind/configuration.json`, or `~/.config/codebind/configuration.json` when `XDG_CONFIG_HOME` is unset:

```json
{
  "model": "openai/gpt-5.6-luna",
  "parameters": {
    "reasoning_effort": "medium"
  }
}
```

Provider credentials use the same XDG directory in `models.json`. Keep both files readable only by their owner. Loading Codebind does not add `chat`, `model`, `models`, `Models`, or any other variable to the IPython namespace.

## Terminal IPython

Start a new conversation:

```console
uvx codebind
```

Ask through ordinary IPython magic syntax:

```python
%%question
Inspect this project and tell me what to implement first.
```

Terminal conversations remain live for the current IPython process. Durable automatic resumption belongs to notebooks, where the notebook file provides an unambiguous conversation identity.

## JupyterLab

```console
uvx --from jupyterlab --with codebind --with 'nbconvert[webpdf]' jupyter lab
```

When running an unpublished local checkout, expose both its editable Python source and its current prebuilt frontend:

```console
JUPYTER_PATH=/path/to/codebind/data/share/jupyter \
uvx --refresh --from jupyterlab --with-editable /path/to/codebind \
  --with 'nbconvert[webpdf]' jupyter-lab
```

Load Codebind in a notebook:

```python
%load_ext codebind
```

That is the complete setup. **Question** is a native toolbar toggle. Turning it on converts the selected cell into a Question and automatically makes each newly created user cell a Question until the toggle is turned off. Codebind-generated instruction, tool, and answer cells are never converted. Write ordinary Markdown and press `Shift+Enter`.

Loading the extension adds a locked Markdown cell containing Codebind's packaged instructions. That exact text becomes the conversation's immutable system message and remains stable when the server or kernel restarts.

The whole notebook is model context. Before each Question, Codebind takes a canonical snapshot of ordinary Markdown, raw, and code cells, including visible text and image outputs but never the live Python namespace. Images displayed by the model's IPython tool are included in that tool's result as well. PNG, JPEG, WebP, GIF, and SVG renditions are prepared as model-visible images; unsupported or oversized images are reported as omissions rather than silently discarded. The first turn records the snapshot; later turns append only new, changed, removed, or reordered cells. Questions, tool calls, tool results, and answers already present in the conversation ledger are not duplicated. Image bytes are carried in the relevant message, while notebook snapshots contain only stable image descriptors. This append-only representation keeps the prior model prefix unchanged for provider caching.

Codebind stores the complete LangChain message, notebook-context, and turn ledger in notebook metadata. Reopening the notebook, restarting its kernel, and loading the extension restores the exact accumulated context automatically. Each assistant Markdown segment is buffered and inserted as one complete native cell as soon as that segment finishes, before a following tool call is complete. Tool executions and assistant answers are always appended to the notebook end without changing the user's current selection or scroll position. Tool outputs are collapsed by default and remain expandable through JupyterLab's native output control.

The conversation ledger validates its structure and every assistant tool call against its single matching result, without a version gate. Interrupted saves finish before a turn is cancelled, so a restart cannot turn a partial write into an orphan tool result. Temporary model transport failures retry the same Question with a fresh connection; repeated WebSocket failures use HTTP. Invalid requests and authentication failures remain visible errors.

An interrupted tool call is closed with an explicit interrupted result before the turn ends. If a provider stream is cancelled or fails, Codebind discards that provider session before the next Question while retaining the notebook conversation and its stable prompt-cache identity.

The instruction cell, sent Question cells, model-authored tool cells, and assistant Markdown cells are non-editable and non-deletable. Draft Question cells remain editable until they are sent. Jupyter's standard interrupt button cancels an active Codebind question.

Question and assistant Markdown supports `$...$`, `$$...$$`, `\(...\)`, and `\[...\]` through JupyterLab's native MathJax renderer.

Other IPython frontends retain standard MIME display, syntax-highlighted code, Markdown, stdout, tracebacks, rich results, and native IPython history.

## ChatGPT account access

Models Provider owns OpenAI account authorization and token refresh. Save the resulting provider-values object in Codebind's XDG `models.json`; Codebind loads it privately when the extension starts. ChatGPT subscription access is separate from the public, pay-as-you-go OpenAI API and may require compatibility updates when the account protocol changes.
