codebind 0.1.0__tar.gz

codebind-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Giovanni Gravili
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codebind-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: codebind
+Version: 0.1.0
+Summary: A minimal model loop over a persistent IPython session.
+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: 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.0
+Requires-Dist: rich>=14.0
+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 runs a model with one tool: an IPython cell executed in the session shared with the user. Conversation history belongs to a `Session`; the model is selected independently for every call.
+
+## Installation
+
+Run Codebind without installing it permanently:
+
+```console
+uvx codebind
+```
+
+Or install it with any Python package installer:
+
+```console
+pip install codebind
+```
+
+After installation, start the preconfigured shell from any directory:
+
+```console
+codebind
+```
+
+It opens IPython with `chat` and `Models` already available and renders a short Markdown usage guide in the terminal. It does not modify the user's global IPython profile.
+
+```python
+models = Models({"openai": "OPENAI_API_KEY"})
+
+chat.ask(
+    "Inspect this project and tell me what to implement first.",
+    models.chat("openai/gpt-5", reasoning_effort="medium"),
+)
+```
+
+Codebind does not load files or construct a project prompt automatically. The user states what should be loaded as context. Pass `instructions=` to `Session` only when an application needs its own system instructions.
+
+## ChatGPT account login
+
+Models Provider can start its OpenAI browser sign-in flow directly from IPython:
+
+```python
+import webbrowser
+
+models = Models()
+authorization = await models.sign_in("openai")
+webbrowser.open(authorization.url)
+await authorization.complete()
+
+chat.ask(
+    "Inspect this project.",
+    models.chat("openai/gpt-5", authorization=authorization),
+)
+```
+
+The authorization remains in memory for this session. Persistent credential storage belongs to the host application.
+
+OpenAI officially supports ChatGPT subscription sign-in for Codex clients. Models Provider reproduces that account-access boundary for this library; it is separate from the public, pay-as-you-go OpenAI API and may require compatibility updates when the Codex account protocol changes.

codebind-0.1.0/README.md

@@ -0,0 +1,58 @@
+# Codebind
+
+Codebind runs a model with one tool: an IPython cell executed in the session shared with the user. Conversation history belongs to a `Session`; the model is selected independently for every call.
+
+## Installation
+
+Run Codebind without installing it permanently:
+
+```console
+uvx codebind
+```
+
+Or install it with any Python package installer:
+
+```console
+pip install codebind
+```
+
+After installation, start the preconfigured shell from any directory:
+
+```console
+codebind
+```
+
+It opens IPython with `chat` and `Models` already available and renders a short Markdown usage guide in the terminal. It does not modify the user's global IPython profile.
+
+```python
+models = Models({"openai": "OPENAI_API_KEY"})
+
+chat.ask(
+    "Inspect this project and tell me what to implement first.",
+    models.chat("openai/gpt-5", reasoning_effort="medium"),
+)
+```
+
+Codebind does not load files or construct a project prompt automatically. The user states what should be loaded as context. Pass `instructions=` to `Session` only when an application needs its own system instructions.
+
+## ChatGPT account login
+
+Models Provider can start its OpenAI browser sign-in flow directly from IPython:
+
+```python
+import webbrowser
+
+models = Models()
+authorization = await models.sign_in("openai")
+webbrowser.open(authorization.url)
+await authorization.complete()
+
+chat.ask(
+    "Inspect this project.",
+    models.chat("openai/gpt-5", authorization=authorization),
+)
+```
+
+The authorization remains in memory for this session. Persistent credential storage belongs to the host application.
+
+OpenAI officially supports ChatGPT subscription sign-in for Codex clients. Models Provider reproduces that account-access boundary for this library; it is separate from the public, pay-as-you-go OpenAI API and may require compatibility updates when the Codex account protocol changes.

codebind-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "codebind"
+version = "0.1.0"
+description = "A minimal model loop over a persistent IPython session."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "ai",
+    "ipython",
+    "llm",
+    "repl",
+    "agents",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "ipython>=9.0",
+    "langchain-core>=1.0",
+    "models-provider>=0.1.0",
+    "rich>=14.0",
+]
+
+[[project.authors]]
+name = "Giovanni Gravili"
+email = "ghovax@users.noreply.github.com"
+
+[project.urls]
+Repository = "https://github.com/ghovax/codebind"
+Issues = "https://github.com/ghovax/codebind/issues"
+
+[project.scripts]
+codebind = "codebind.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4",
+    "ruff>=0.13",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "B",
+    "RUF",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"

codebind-0.1.0/pyproject.toml.orig

@@ -0,0 +1,51 @@
+[project]
+name = "codebind"
+version = "0.1.0"
+description = "A minimal model loop over a persistent IPython session."
+readme = "README.md"
+authors = [
+    { name = "Giovanni Gravili", email = "ghovax@users.noreply.github.com" }
+]
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["ai", "ipython", "llm", "repl", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "ipython>=9.0",
+    "langchain-core>=1.0",
+    "models-provider>=0.1.0",
+    "rich>=14.0",
+]
+
+[project.urls]
+Repository = "https://github.com/ghovax/codebind"
+Issues = "https://github.com/ghovax/codebind/issues"
+
+[project.scripts]
+codebind = "codebind.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4",
+    "ruff>=0.13",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "B", "RUF"]
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"

codebind-0.1.0/src/codebind/__init__.py

@@ -0,0 +1,16 @@
+"""A minimal model loop over the current IPython session."""
+
+from importlib.metadata import version
+
+from .execution import ExecutionReport, IPythonExecutor
+from .session import Session
+
+
+__version__ = version("codebind")
+
+__all__ = [
+    "ExecutionReport",
+    "IPythonExecutor",
+    "Session",
+    "__version__",
+]

codebind-0.1.0/src/codebind/cli.py

@@ -0,0 +1,45 @@
+"""Project-local IPython launcher with Codebind conveniences preloaded."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from IPython.core.interactiveshell import InteractiveShell
+from IPython.terminal.ipapp import TerminalIPythonApp
+from models_provider import Models
+from rich.console import Console
+from rich.markdown import Markdown
+
+from . import __version__
+from .session import Session
+
+
+BANNER = """\
+- `models = Models({...})`
+- `chat.ask("...", models.chat("provider/model"))`
+"""
+
+
+def namespace(shell: InteractiveShell) -> dict[str, Any]:
+    """Build the small namespace exposed by the Codebind shell."""
+    return {
+        "chat": Session(shell=shell),
+        "Models": Models,
+    }
+
+
+def main() -> None:
+    """Start IPython in the current directory with Codebind preloaded."""
+    parser = argparse.ArgumentParser(description="Start a model-enabled IPython session.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.parse_args()
+
+    Console().print(Markdown(BANNER))
+    application = TerminalIPythonApp.instance()
+    application.display_banner = False
+    application.initialize([])
+    shell = application.shell
+    shell.enable_tip = False
+    shell.push(namespace(shell))
+    application.start()

codebind-0.1.0/src/codebind/execution.py

@@ -0,0 +1,67 @@
+"""Execution of model-authored cells in a shared IPython namespace."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+from IPython.core.interactiveshell import InteractiveShell
+from IPython.utils.capture import capture_output
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionReport:
+    """The model-facing result of one IPython cell."""
+
+    ok: bool
+    stdout: str
+    stderr: str
+    result: str | None
+    displays: tuple[str, ...]
+    error: dict[str, str] | None
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable representation."""
+        return asdict(self)
+
+
+class IPythonExecutor:
+    """Run cells through one existing IPython shell."""
+
+    def __init__(self, shell: InteractiveShell) -> None:
+        self.shell = shell
+
+    def execute(self, cell: str) -> ExecutionReport:
+        """Execute a cell, replay its visible output, and capture a structured result."""
+        if not isinstance(cell, str) or not cell.strip():
+            raise ValueError("cell must be a non-empty string")
+
+        displayhook = self.shell.displayhook
+        original_prompt = displayhook.write_output_prompt
+        displayhook.write_output_prompt = lambda: None
+        try:
+            with capture_output() as captured:
+                result = self.shell.run_cell(cell, store_history=False)
+        finally:
+            displayhook.write_output_prompt = original_prompt
+
+        displays: list[str] = []
+        for output in captured.outputs:
+            data = getattr(output, "data", None)
+            if isinstance(data, dict) and "text/plain" in data:
+                displays.append(str(data["text/plain"]))
+
+        exception = result.error_before_exec or result.error_in_exec
+        error = (
+            {"type": type(exception).__name__, "message": str(exception)}
+            if exception is not None
+            else None
+        )
+        return ExecutionReport(
+            ok=result.success,
+            stdout=captured.stdout,
+            stderr=captured.stderr,
+            result=repr(result.result) if result.result is not None else None,
+            displays=tuple(displays),
+            error=error,
+        )

codebind-0.1.0/src/codebind/rendering.py

@@ -0,0 +1,54 @@
+"""Terminal rendering for model responses and IPython tool output."""
+
+from __future__ import annotations
+
+from itertools import chain
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.segment import Segments
+from rich.text import Text
+
+from .execution import ExecutionReport
+
+
+_MAX_OUTPUT_LINES = 10
+
+
+def _visible_output(report: ExecutionReport) -> str:
+    parts = [part for part in (report.stdout, report.stderr) if part]
+    if report.displays:
+        parts.extend(report.displays)
+    elif not parts and report.result is not None:
+        parts.append(report.result)
+    if not parts and report.error is not None:
+        parts.append(f"{report.error['type']}: {report.error['message']}")
+    return "\n".join(part.rstrip("\n") for part in parts if part).strip("\n")
+
+
+class TerminalRenderer:
+    """Render concise tool previews and Markdown answers to the active terminal."""
+
+    def __init__(self) -> None:
+        self.console = Console()
+
+    def tool_output(self, report: ExecutionReport) -> None:
+        """Show a bounded preview while leaving the report itself intact for the model."""
+        visible = _visible_output(report)
+        if not visible:
+            return
+        output = Text.from_ansi(visible)
+        options = self.console.options
+        complete = self.console.render_lines(output, options, pad=False, new_lines=True)
+        preview = complete[:_MAX_OUTPUT_LINES]
+        self.console.print(Segments(chain.from_iterable(preview)), end="")
+        if len(complete) > len(preview):
+            self.console.print(
+                f"[dim]{len(preview)} of {len(complete)} lines shown; "
+                "the complete result was returned to the model.[/dim]"
+            )
+
+    def assistant(self, text: str) -> None:
+        """Render the final model response as terminal Markdown."""
+        self.console.print()
+        self.console.print(Markdown(text))

codebind-0.1.0/src/codebind/session.py

@@ -0,0 +1,151 @@
+"""Conversation state and the single IPython-tool model loop."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from IPython import get_ipython
+from IPython.core.interactiveshell import InteractiveShell
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage
+from langchain_core.runnables import Runnable
+
+from .execution import ExecutionReport, IPythonExecutor
+from .rendering import TerminalRenderer
+
+
+IPYTHON_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "ipython",
+        "description": (
+            "Execute an IPython cell in the state-persistent session shared with the user."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "cell": {
+                    "type": "string",
+                    "description": "A complete IPython cell to execute.",
+                }
+            },
+            "required": ["cell"],
+            "additionalProperties": False,
+        },
+    },
+}
+
+
+def _message_text(message: AIMessage) -> str:
+    content = message.content
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, Sequence) or isinstance(content, (bytes, bytearray, str)):
+        return str(content)
+    parts: list[str] = []
+    for block in content:
+        if isinstance(block, str):
+            parts.append(block)
+        elif isinstance(block, Mapping) and isinstance(block.get("text"), str):
+            parts.append(block["text"])
+    return "".join(parts)
+
+
+def _tool_error(error_type: str, message: str) -> ExecutionReport:
+    return ExecutionReport(False, "", "", None, (), {"type": error_type, "message": message})
+
+
+class Session:
+    """Keep conversation history while choosing the model independently for every turn."""
+
+    def __init__(
+        self,
+        *,
+        shell: InteractiveShell | None = None,
+        instructions: str | None = None,
+    ) -> None:
+        resolved_shell = shell or get_ipython()
+        if resolved_shell is None:
+            raise RuntimeError("Session must be created inside IPython or given an IPython shell.")
+
+        self.shell = resolved_shell
+        self.executor = IPythonExecutor(resolved_shell)
+        self.renderer = TerminalRenderer()
+        self.instructions = instructions.strip() if instructions else None
+        self.messages: list[BaseMessage] = []
+        self.last_response: AIMessage | None = None
+        if self.instructions:
+            self.messages.append(SystemMessage(self.instructions))
+
+    def clear(self) -> None:
+        """Clear conversation history without clearing the shared Python namespace."""
+        self.messages.clear()
+        self.last_response = None
+        if self.instructions:
+            self.messages.append(SystemMessage(self.instructions))
+
+    def ask(self, prompt: str, model: BaseChatModel) -> None:
+        """Run one user turn with the explicitly supplied model."""
+        text = prompt.strip()
+        if not text:
+            raise ValueError("prompt cannot be empty")
+
+        bound_model = self._bind(model)
+        self.messages.append(HumanMessage(text))
+
+        while True:
+            response = bound_model.invoke(tuple(self.messages))
+            if not isinstance(response, AIMessage):
+                raise TypeError("model must return an AIMessage")
+            self.messages.append(response)
+            self.last_response = response
+
+            if not response.tool_calls:
+                answer = _message_text(response)
+                if answer:
+                    self.renderer.assistant(answer)
+                return
+
+            for call in response.tool_calls:
+                report = self._execute_call(call)
+                identifier = str(call.get("id") or f"ipython-{len(self.messages)}")
+                self.messages.append(
+                    ToolMessage(
+                        json.dumps(report.as_dict(), ensure_ascii=False),
+                        tool_call_id=identifier,
+                    )
+                )
+
+    @staticmethod
+    def _bind(model: BaseChatModel) -> Runnable[Any, BaseMessage]:
+        try:
+            return model.bind_tools([IPYTHON_TOOL], parallel_tool_calls=False)
+        except NotImplementedError:
+            return model.bind(tools=[IPYTHON_TOOL], parallel_tool_calls=False)
+
+    def _execute_call(self, call: Mapping[str, Any]) -> ExecutionReport:
+        if call.get("name") != "ipython":
+            return _tool_error("UnknownTool", f"unknown tool: {call.get('name')!r}")
+        arguments = call.get("args")
+        if not isinstance(arguments, Mapping) or not isinstance(arguments.get("cell"), str):
+            return _tool_error("InvalidArguments", "ipython requires a string cell argument")
+
+        cell = arguments["cell"]
+        self._show_call(cell)
+        try:
+            report = self.executor.execute(cell)
+        except Exception as error:  # The failure must be returned to the model, not end the session.
+            report = _tool_error(type(error).__name__, str(error))
+        self.renderer.tool_output(report)
+        return report
+
+    def _show_call(self, cell: str) -> None:
+        highlighted = self.shell.pycolorize(cell.rstrip())
+        sys.stdout.write("\n")
+        sys.stdout.write(highlighted)
+        if not highlighted.endswith("\n"):
+            sys.stdout.write("\n")
+        sys.stdout.flush()