codebind 0.5.3__py3-none-any.whl → 0.6.0__py3-none-any.whl

codebind/configuration.py

@@ -0,0 +1,60 @@
+"""XDG-backed Codebind configuration."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from models_provider import Models
+
+
+def configuration_home() -> Path:
+    xdg_home = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_home:
+        path = Path(xdg_home).expanduser()
+        if path.is_absolute():
+            return path
+    return Path.home() / ".config"
+
+
+@dataclass(frozen=True, slots=True)
+class CodebindConfiguration:
+    model: str
+    parameters: dict[str, Any] = field(default_factory=dict)
+
+
+def load_configuration() -> CodebindConfiguration:
+    path = configuration_home() / "codebind" / "configuration.json"
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Codebind configuration is missing: {path}. "
+            'Create it with a JSON object such as {"model": "openai/gpt-5.6-luna"}.'
+        )
+    value = json.loads(path.read_text())
+    if not isinstance(value, dict) or not isinstance(value.get("model"), str):
+        raise ValueError(f"Codebind configuration must contain a string model: {path}")
+    parameters = value.get("parameters", {})
+    if not isinstance(parameters, dict):
+        raise ValueError(f"Codebind model parameters must be a JSON object: {path}")
+    return CodebindConfiguration(value["model"], parameters)
+
+
+def load_models() -> Models:
+    path = configuration_home() / "codebind" / "models.json"
+    if not path.exists():
+        return Models()
+    values = json.loads(path.read_text())
+    if not isinstance(values, dict):
+        raise ValueError(f"Codebind model configuration must be a JSON object: {path}")
+    return Models(values)
+
+
+__all__ = [
+    "CodebindConfiguration",
+    "configuration_home",
+    "load_configuration",
+    "load_models",
+]

codebind/conversation.py

@@ -0,0 +1,268 @@
+"""Durable conversation records and storage boundaries."""
+
+from __future__ import annotations
+
+import json
+import os
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+from uuid import uuid4
+
+from langchain_core.messages import BaseMessage, HumanMessage, message_to_dict, messages_from_dict
+
+_VERSION = 2
+
+
+class ConversationStore(Protocol):
+    async def load(self) -> dict[str, Any] | None: ...
+
+    async def save(self, value: dict[str, Any]) -> None: ...
+
+
+class ConversationBridge(Protocol):
+    async def load_conversation(self) -> dict[str, Any] | None: ...
+
+    async def save_conversation(self, value: dict[str, Any]) -> None: ...
+
+
+@dataclass(slots=True)
+class Conversation:
+    id: str = field(default_factory=lambda: str(uuid4()))
+    revision: int = 0
+    events: list[dict[str, Any]] = field(default_factory=list)
+    cwd: str = field(default_factory=os.getcwd)
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> Conversation:
+        if value.get("version") != _VERSION:
+            raise ValueError("Unsupported Codebind conversation version")
+        identifier = value.get("id")
+        events = value.get("events")
+        revision = value.get("revision")
+        cwd = value.get("cwd")
+        if not isinstance(identifier, str) or not isinstance(events, list):
+            raise ValueError("Invalid Codebind conversation")
+        if not isinstance(revision, int) or revision != len(events):
+            raise ValueError("Invalid Codebind conversation revision")
+        if any(
+            not isinstance(event, dict) or event.get("sequence") != sequence
+            for sequence, event in enumerate(events, start=1)
+        ):
+            raise ValueError("Invalid Codebind conversation sequence")
+        if not isinstance(cwd, str):
+            cwd = ""
+        return cls(identifier, revision, deepcopy(events), cwd)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "version": _VERSION,
+            "id": self.id,
+            "revision": self.revision,
+            "cwd": self.cwd,
+            "events": deepcopy(self.events),
+        }
+
+    def append(self, event_type: str, **data: Any) -> dict[str, Any]:
+        event = {"sequence": self.revision + 1, "type": event_type, **data}
+        self.events.append(event)
+        self.revision += 1
+        return event
+
+    def append_message(self, message: BaseMessage, turn_id: str) -> dict[str, Any]:
+        return self.append("message", turn_id=turn_id, message=message_to_dict(message))
+
+    def append_notebook(
+        self,
+        cells: list[dict[str, Any]],
+        turn_id: str,
+    ) -> dict[str, Any] | None:
+        current = self.notebook()
+        incoming = _normalize_notebook(cells)
+        has_notebook = any(event.get("type") == "notebook" for event in self.events)
+
+        if not has_notebook:
+            payload: dict[str, Any] = {"mode": "snapshot", "cells": incoming}
+        else:
+            current_by_id = {cell["id"]: cell for cell in current}
+            incoming_by_id = {cell["id"]: cell for cell in incoming}
+            upsert = [cell for cell in incoming if current_by_id.get(cell["id"]) != cell]
+            remove = [cell["id"] for cell in current if cell["id"] not in incoming_by_id]
+            current_order = [cell["id"] for cell in current]
+            incoming_order = [cell["id"] for cell in incoming]
+            if not upsert and not remove and current_order == incoming_order:
+                return None
+            payload = {"mode": "delta"}
+            if upsert:
+                payload["upsert"] = upsert
+            if remove:
+                payload["remove"] = remove
+            if current_order != incoming_order:
+                payload["order"] = incoming_order
+
+        content = (
+            "<notebook-context>"
+            + json.dumps(
+                payload,
+                ensure_ascii=False,
+                separators=(",", ":"),
+            )
+            + "</notebook-context>"
+        )
+        return self.append(
+            "notebook",
+            turn_id=turn_id,
+            **payload,
+            message=message_to_dict(HumanMessage(content)),
+        )
+
+    def rollback(self, event: dict[str, Any]) -> None:
+        if not self.events or self.events[-1] is not event:
+            raise RuntimeError("Only the latest conversation event can be rolled back")
+        self.events.pop()
+        self.revision -= 1
+
+    def messages(self) -> list[BaseMessage]:
+        serialized = [
+            event["message"]
+            for event in self.events
+            if event.get("type") in {"message", "notebook"}
+            and isinstance(event.get("message"), dict)
+        ]
+        return messages_from_dict(serialized)
+
+    def notebook(self) -> list[dict[str, Any]]:
+        cells: list[dict[str, Any]] = []
+        for event in self.events:
+            if event.get("type") != "notebook":
+                continue
+            mode = event.get("mode")
+            if mode == "snapshot":
+                cells = _normalize_notebook(event.get("cells"))
+                continue
+            if mode != "delta":
+                raise ValueError("Invalid Codebind notebook event")
+
+            by_id = {cell["id"]: cell for cell in cells}
+            for identifier in event.get("remove", []):
+                if not isinstance(identifier, str):
+                    raise ValueError("Invalid Codebind notebook removal")
+                by_id.pop(identifier, None)
+            for cell in _normalize_notebook(event.get("upsert", [])):
+                by_id[cell["id"]] = cell
+
+            order = event.get("order")
+            if order is None:
+                retained = [cell["id"] for cell in cells if cell["id"] in by_id]
+                added = [identifier for identifier in by_id if identifier not in retained]
+                order = [*retained, *added]
+            if (
+                not isinstance(order, list)
+                or any(not isinstance(identifier, str) for identifier in order)
+                or len(order) != len(set(order))
+                or set(order) != set(by_id)
+            ):
+                raise ValueError("Invalid Codebind notebook order")
+            cells = [by_id[identifier] for identifier in order]
+        return deepcopy(cells)
+
+    def unfinished_turns(self) -> list[str]:
+        started: list[str] = []
+        finished: set[str] = set()
+        for event in self.events:
+            turn_id = event.get("turn_id")
+            if not isinstance(turn_id, str):
+                continue
+            if event.get("type") == "turn_started":
+                started.append(turn_id)
+            elif event.get("type") == "turn_finished":
+                finished.add(turn_id)
+        return [turn_id for turn_id in started if turn_id not in finished]
+
+    def pending_tool_calls(self, turn_ids: set[str]) -> list[tuple[str, str]]:
+        pending: dict[str, str] = {}
+        for event in self.events:
+            turn_id = event.get("turn_id")
+            message = event.get("message")
+            if turn_id not in turn_ids or not isinstance(message, dict):
+                continue
+            message_type = message.get("type")
+            data = message.get("data")
+            if not isinstance(data, dict):
+                continue
+            if message_type == "ai":
+                tool_calls = data.get("tool_calls", [])
+                if isinstance(tool_calls, list):
+                    for call in tool_calls:
+                        identifier = call.get("id") if isinstance(call, dict) else None
+                        if isinstance(identifier, str) and identifier:
+                            pending[identifier] = turn_id
+            elif message_type == "tool":
+                identifier = data.get("tool_call_id")
+                if isinstance(identifier, str):
+                    pending.pop(identifier, None)
+        return list(pending.items())
+
+
+class MemoryConversationStore:
+    def __init__(self) -> None:
+        self.value: dict[str, Any] | None = None
+
+    async def load(self) -> dict[str, Any] | None:
+        return self.value
+
+    async def save(self, value: dict[str, Any]) -> None:
+        self.value = value
+
+
+class NotebookConversationStore:
+    def __init__(self, bridge: ConversationBridge):
+        self.bridge = bridge
+
+    async def load(self) -> dict[str, Any] | None:
+        return await self.bridge.load_conversation()
+
+    async def save(self, value: dict[str, Any]) -> None:
+        await self.bridge.save_conversation(value)
+
+
+def _normalize_notebook(value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list):
+        raise ValueError("Invalid Codebind notebook snapshot")
+    cells: list[dict[str, Any]] = []
+    identifiers: set[str] = set()
+    for raw_cell in value:
+        if not isinstance(raw_cell, dict):
+            raise ValueError("Invalid Codebind notebook cell")
+        identifier = raw_cell.get("id")
+        cell_type = raw_cell.get("type")
+        source = raw_cell.get("source")
+        if (
+            not isinstance(identifier, str)
+            or not identifier
+            or identifier in identifiers
+            or cell_type not in {"code", "markdown", "raw"}
+            or not isinstance(source, str)
+        ):
+            raise ValueError("Invalid Codebind notebook cell")
+        identifiers.add(identifier)
+        cell: dict[str, Any] = {"id": identifier, "type": cell_type, "source": source}
+        if cell_type == "code":
+            execution_count = raw_cell.get("execution_count")
+            outputs = raw_cell.get("outputs", [])
+            if not (execution_count is None or isinstance(execution_count, int)) or not isinstance(
+                outputs, list
+            ):
+                raise ValueError("Invalid Codebind code cell")
+            cell["execution_count"] = execution_count
+            cell["outputs"] = deepcopy(outputs)
+        cells.append(cell)
+    return cells
+
+
+__all__ = [
+    "Conversation",
+    "ConversationStore",
+    "MemoryConversationStore",
+    "NotebookConversationStore",
+]

codebind/extension.py

@@ -2,76 +2,108 @@
 
 from __future__ import annotations
 
-import json
-import os
-from pathlib import Path
+import asyncio
 from typing import Any
 
 from IPython.core.interactiveshell import InteractiveShell
 from langchain_core.language_models import BaseChatModel
-from models_provider import Models
 
+from .configuration import load_configuration, load_models
+from .conversation import MemoryConversationStore, NotebookConversationStore
 from .jupyter import JupyterLabBridge
 from .session import Session
 
 
-_NAMESPACE_ATTRIBUTE = "_codebind_extension_namespace"
-
-
-def _models_path() -> Path:
-    configured = os.environ.get("XDG_CONFIG_HOME")
-    if configured:
-        config_home = Path(configured).expanduser()
-        if config_home.is_absolute():
-            return config_home / "codebind" / "models.json"
-    return Path.home() / ".config" / "codebind" / "models.json"
-
-
-def _load_models() -> Models:
-    path = _models_path()
-    if not path.exists():
-        return Models()
-    values = json.loads(path.read_text())
-    if not isinstance(values, dict):
-        raise ValueError(f"Codebind model configuration must be a JSON object: {path}")
-    return Models(values)
+_STATE_ATTRIBUTE = "_codebind_extension_state"
 
 
 def load_ipython_extension(ipython: InteractiveShell) -> None:
-    """Load Codebind into the active IPython user namespace."""
-    models = _load_models()
-    previous = getattr(ipython, _NAMESPACE_ATTRIBUTE, None)
+    """Load Codebind into the active IPython session."""
+    previous = getattr(ipython, _STATE_ATTRIBUTE, None)
     if isinstance(previous, dict):
-        previous_chat = previous.get("chat")
-        if isinstance(previous_chat, Session) and previous_chat.bridge is not None:
-            previous_chat.bridge.close()
-        ipython.drop_by_id(previous)
+        previous_load = previous.get("load_task")
+        if isinstance(previous_load, asyncio.Task):
+            previous_load.cancel()
+        previous_session = previous.get("session")
+        if isinstance(previous_session, Session) and previous_session.bridge is not None:
+            previous_session.bridge.close()
+
+    configuration = load_configuration()
+    models = load_models()
+    model: BaseChatModel | None = None
+
+    def get_model() -> BaseChatModel:
+        nonlocal model
+        if model is None:
+            model = models.chat(configuration.model, **configuration.parameters)
+        return model
+
+    def discard_model(selected: BaseChatModel) -> None:
+        nonlocal model
+        if model is selected:
+            model = None
+
     bridge = JupyterLabBridge.connect(ipython)
-    chat = Session(shell=ipython, bridge=bridge)
+    store = NotebookConversationStore(bridge) if bridge is not None else MemoryConversationStore()
+    session = Session(shell=ipython, bridge=bridge, store=store)
+
+    async def answer_question(question: str, notebook: list[dict[str, Any]]) -> None:
+        selected = get_model()
+        try:
+            await session.asend(question, selected, notebook=notebook)
+        except BaseException:
+            discard_model(selected)
+            raise
+
+    def question_magic(line: str, cell: str | None = None) -> None:
+        selected = get_model()
+        try:
+            session.send(cell if cell is not None else line, selected)
+        except BaseException:
+            discard_model(selected)
+            raise
+
+    load_task: asyncio.Task[None] | None = None
     if bridge is not None:
-
-        async def answer_question(question: str, model_name: str) -> None:
-            model = ipython.user_ns.get(model_name)
-            if not isinstance(model, BaseChatModel):
-                raise NameError(f"{model_name!r} is not a chat model in the IPython namespace")
-            await chat.asend(question, model)
-
         bridge.handle_questions(answer_question)
-    namespace: dict[str, Any] = {
-        "chat": chat,
-        "Models": Models,
-        "models": models,
-    }
-    ipython.push(namespace)
-    setattr(ipython, _NAMESPACE_ATTRIBUTE, namespace)
+
+        async def prepare_session() -> None:
+            try:
+                await session.aload()
+            except asyncio.CancelledError:
+                raise
+            except Exception as error:
+                bridge.report_session_ready(error)
+            else:
+                bridge.report_session_ready()
+
+        try:
+            load_task = asyncio.get_running_loop().create_task(prepare_session())
+        except RuntimeError:
+            pass
+    ipython.register_magic_function(question_magic, "line_cell", "question")
+    setattr(
+        ipython,
+        _STATE_ATTRIBUTE,
+        {
+            "session": session,
+            "bridge": bridge,
+            "load_task": load_task,
+            "get_model": get_model,
+        },
+    )
 
 
 def unload_ipython_extension(ipython: InteractiveShell) -> None:
-    """Remove names added by Codebind without touching user replacements."""
-    namespace = getattr(ipython, _NAMESPACE_ATTRIBUTE, None)
-    if isinstance(namespace, dict):
-        chat = namespace.get("chat")
-        if isinstance(chat, Session) and chat.bridge is not None:
-            chat.bridge.close()
-        ipython.drop_by_id(namespace)
-        delattr(ipython, _NAMESPACE_ATTRIBUTE)
+    """Unload Codebind without touching the user namespace."""
+    state: Any = getattr(ipython, _STATE_ATTRIBUTE, None)
+    if isinstance(state, dict):
+        load_task = state.get("load_task")
+        if isinstance(load_task, asyncio.Task):
+            load_task.cancel()
+        session = state.get("session")
+        if isinstance(session, Session) and session.bridge is not None:
+            session.bridge.close()
+        delattr(ipython, _STATE_ATTRIBUTE)
+    ipython.magics_manager.magics["line"].pop("question", None)
+    ipython.magics_manager.magics["cell"].pop("question", None)

codebind/instructions.md

@@ -0,0 +1,11 @@
+You are a coding agent, operating through the user’s live IPython session.
+
+- Use the `ipython` tool whenever it can help you answer or act, especially for requests about local files, software, the environment, processes, or hardware.
+- Prefer one batched IPython cell that completes as much of the task as practical instead of giving the user commands to run.
+- Use Python as the primary orchestration language; IPython syntax and Python-launched subprocesses are available.
+- Default to read-only inspection unless the user requests a change.
+- Never claim that local access is unavailable before trying the tool.
+- Keep the user oriented while working. Before meaningful tool work, emit one brief Markdown update saying what you are about to do. Between tool calls, emit another update only for a new phase, an important finding, or a change of plan. Do not perform several meaningful steps silently, but do not narrate trivial operations.
+- Keep responses brief and direct.
+- Treat notebook-context messages as the authoritative notebook document state; later deltas override earlier cell versions.
+- You can freely install libraries like matplotlib, pandas and any others as needed; it's preferrable to use them if you need.

codebind/jupyter.py

@@ -11,7 +11,9 @@ from IPython.core.interactiveshell import InteractiveShell
 
 
 _TARGET_NAME = "codebind"
-_QuestionHandler = Callable[[str, str], Awaitable[None]]
+_HANDSHAKE_TIMEOUT_SECONDS = 30
+_Notebook = list[dict[str, Any]]
+_QuestionHandler = Callable[[str, _Notebook], Awaitable[None]]
 
 
 class JupyterLabBridge:
@@ -21,6 +23,10 @@ class JupyterLabBridge:
         self._comm = comm
         self._question_handler: _QuestionHandler | None = None
         self._tasks: set[asyncio.Task[None]] = set()
+        self._conversation: dict[str, Any] | None = None
+        self._conversation_received = False
+        self._conversation_waiters: set[asyncio.Future[dict[str, Any] | None]] = set()
+        self._save_waiters: dict[str, asyncio.Future[None]] = {}
         self.ready = False
         comm.on_msg(self._on_message)
 
@@ -42,6 +48,10 @@ class JupyterLabBridge:
         for task in self._tasks:
             task.cancel()
         self._tasks.clear()
+        for future in (*self._conversation_waiters, *self._save_waiters.values()):
+            future.cancel()
+        self._conversation_waiters.clear()
+        self._save_waiters.clear()
         self._comm.close()
         self.ready = False
 
@@ -49,6 +59,34 @@ class JupyterLabBridge:
         """Handle questions submitted by Codebind cells."""
         self._question_handler = handler
 
+    async def load_conversation(self) -> dict[str, Any] | None:
+        if self._conversation_received:
+            return self._conversation
+        future = asyncio.get_running_loop().create_future()
+        self._conversation_waiters.add(future)
+        try:
+            return await asyncio.wait_for(future, _HANDSHAKE_TIMEOUT_SECONDS)
+        finally:
+            self._conversation_waiters.discard(future)
+
+    async def save_conversation(self, value: dict[str, Any]) -> None:
+        if not self.ready:
+            await self.load_conversation()
+        request_id = str(uuid4())
+        future = asyncio.get_running_loop().create_future()
+        self._save_waiters[request_id] = future
+        self._comm.send(
+            {
+                "type": "conversation_save",
+                "request_id": request_id,
+                "conversation": value,
+            }
+        )
+        try:
+            await asyncio.wait_for(future, _HANDSHAKE_TIMEOUT_SECONDS)
+        finally:
+            self._save_waiters.pop(request_id, None)
+
     def start_code_cell(self, source: str) -> str | None:
         """Insert a running code cell before its execution begins."""
         if not self.ready:
@@ -115,30 +153,82 @@ class JupyterLabBridge:
         self._comm.send({"type": "markdown_cell", "source": source})
         return True
 
+    def ensure_instructions_cell(self, source: str) -> bool:
+        """Show the conversation's immutable system instructions in the notebook."""
+        if not self.ready:
+            return False
+        self._comm.send({"type": "instructions_cell", "source": source})
+        return True
+
+    def report_session_ready(self, error: BaseException | None = None) -> None:
+        """Tell JupyterLab whether persisted conversation state is ready."""
+        self._comm.send(
+            {
+                "type": "session_ready",
+                "error": (
+                    {"type": type(error).__name__, "message": str(error)}
+                    if error is not None
+                    else None
+                ),
+            }
+        )
+
     def _on_message(self, message: dict[str, Any]) -> None:
         data = message.get("content", {}).get("data", {})
         if not isinstance(data, dict):
             return
         if data.get("type") == "ready":
+            conversation = data.get("conversation")
+            self._conversation = conversation if isinstance(conversation, dict) else None
+            self._conversation_received = True
             self.ready = True
+            for future in tuple(self._conversation_waiters):
+                if not future.done():
+                    future.set_result(self._conversation)
+            return
+        if data.get("type") == "conversation_saved":
+            request_id = data.get("request_id")
+            future = self._save_waiters.get(request_id) if isinstance(request_id, str) else None
+            if future is None or future.done():
+                return
+            error = data.get("error")
+            if isinstance(error, str) and error:
+                future.set_exception(RuntimeError(error))
+            else:
+                future.set_result(None)
+            return
+        if data.get("type") == "cancel":
+            for task in tuple(self._tasks):
+                task.cancel()
             return
         if data.get("type") != "question":
             return
         cell_id = data.get("cell_id")
         question = data.get("question")
-        model = data.get("model", "model")
-        if not all(isinstance(value, str) for value in (cell_id, question, model)):
+        notebook = data.get("notebook")
+        if not all(isinstance(value, str) for value in (cell_id, question)) or not isinstance(
+            notebook, list
+        ):
             return
-        task = asyncio.create_task(self._answer_question(cell_id, question, model))
+        self._comm.send({"type": "question_started", "cell_id": cell_id})
+        task = asyncio.create_task(self._answer_question(cell_id, question, notebook))
         self._tasks.add(task)
         task.add_done_callback(self._tasks.discard)
 
-    async def _answer_question(self, cell_id: str, question: str, model: str) -> None:
+    async def _answer_question(
+        self,
+        cell_id: str,
+        question: str,
+        notebook: _Notebook,
+    ) -> None:
         error: dict[str, str] | None = None
+        cancelled = False
         try:
             if self._question_handler is None:
                 raise RuntimeError("Codebind is not ready to receive questions.")
-            await self._question_handler(question, model)
+            await self._question_handler(question, notebook)
+        except asyncio.CancelledError:
+            cancelled = True
         except Exception as exception:
             error = {"type": type(exception).__name__, "message": str(exception)}
         self._comm.send(
@@ -146,5 +236,6 @@ class JupyterLabBridge:
                 "type": "question_finished",
                 "cell_id": cell_id,
                 "error": error,
+                "cancelled": cancelled,
             }
         )