openconstruct-jupyter 0.1.0__tar.gz

openconstruct_jupyter-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: openconstruct-jupyter
+Version: 0.1.0
+Summary: Jupyter notebook integration for OpenConstruct — connect, sense, and build with agents
+Author: SuperInstance
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: ipython>=7.0
+Requires-Dist: ipywidgets>=8.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# openconstruct-jupyter — Jupyter Integration for OpenConstruct
+
+Connect OpenConstruct to your Jupyter notebooks in one line. Cell magic, widgets, fleet panels, and DataFrame-to-room conversion.
+
+**Part of [SuperInstance OpenConstruct](https://github.com/SuperInstance/OpenConstruct).**
+
+## What This Gives You
+
+- **Cell magic** — `%%openconstruct --sense vision` captures output as a sense shadow
+- **DataFrame → Plato room** — turn any pandas DataFrame into a knowledge graph
+- **Python function → agent tool** — `oc.from_function(greet, name="my_tool")`
+- **Fleet panel** — inline widget showing discovered fleet nodes
+- **Room viewer** — visualize Plato room tiles and dependencies
+
+## Quick Start
+
+```python
+# Load the extension
+%load_ext openconstruct_jupyter
+
+# Connect
+import openconstruct_jupyter as oc
+oc.connect(notebook=True)
+```
+
+### Cell Magic
+
+```python
+%%openconstruct --sense vision
+# Cell output captured as a vision shadow
+
+%%openconstruct --tick "analysis complete"
+# Post a tick to the fleet
+
+%%openconstruct --room my-analysis
+# Create or load a Plato room
+```
+
+### Python API
+
+```python
+import pandas as pd
+
+# DataFrame → room
+df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
+oc.from_dataframe(df, name="my_data")
+
+# Function → agent tool
+def greet(name):
+    return f"Hello, {name}!"
+oc.from_function(greet, name="greet_tool")
+
+# REST API → agent resource
+oc.from_api("https://api.example.com/data", name="external_data")
+```
+
+## Installation
+
+```bash
+pip install openconstruct-jupyter
+```
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## License
+
+MIT

openconstruct_jupyter-0.1.0/README.md

@@ -0,0 +1,71 @@
+# openconstruct-jupyter — Jupyter Integration for OpenConstruct
+
+Connect OpenConstruct to your Jupyter notebooks in one line. Cell magic, widgets, fleet panels, and DataFrame-to-room conversion.
+
+**Part of [SuperInstance OpenConstruct](https://github.com/SuperInstance/OpenConstruct).**
+
+## What This Gives You
+
+- **Cell magic** — `%%openconstruct --sense vision` captures output as a sense shadow
+- **DataFrame → Plato room** — turn any pandas DataFrame into a knowledge graph
+- **Python function → agent tool** — `oc.from_function(greet, name="my_tool")`
+- **Fleet panel** — inline widget showing discovered fleet nodes
+- **Room viewer** — visualize Plato room tiles and dependencies
+
+## Quick Start
+
+```python
+# Load the extension
+%load_ext openconstruct_jupyter
+
+# Connect
+import openconstruct_jupyter as oc
+oc.connect(notebook=True)
+```
+
+### Cell Magic
+
+```python
+%%openconstruct --sense vision
+# Cell output captured as a vision shadow
+
+%%openconstruct --tick "analysis complete"
+# Post a tick to the fleet
+
+%%openconstruct --room my-analysis
+# Create or load a Plato room
+```
+
+### Python API
+
+```python
+import pandas as pd
+
+# DataFrame → room
+df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
+oc.from_dataframe(df, name="my_data")
+
+# Function → agent tool
+def greet(name):
+    return f"Hello, {name}!"
+oc.from_function(greet, name="greet_tool")
+
+# REST API → agent resource
+oc.from_api("https://api.example.com/data", name="external_data")
+```
+
+## Installation
+
+```bash
+pip install openconstruct-jupyter
+```
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## License
+
+MIT

openconstruct_jupyter-0.1.0/openconstruct_jupyter/__init__.py

@@ -0,0 +1,59 @@
+"""
+openconstruct-jupyter — Jupyter notebook integration for OpenConstruct.
+"""
+
+__version__ = "0.1.0"
+
+from .magic import load_ipython_extension, unload_ipython_extension
+from .widgets import (
+    AgentConfigWidget,
+    FleetStatusWidget,
+    SenseShadowWidget,
+    RoomGraphWidget,
+    TickBoardWidget,
+    PolicyWidget,
+)
+from .kernel import OCClient
+
+# Module-level convenience functions backed by a default OCClient
+_default_client: OCClient | None = None
+
+
+def _get_client() -> OCClient:
+    global _default_client
+    if _default_client is None:
+        _default_client = OCClient()
+    return _default_client
+
+
+def connect(**kwargs) -> OCClient:
+    """Connect this notebook to OpenConstruct. Returns the active client."""
+    global _default_client
+    _default_client = OCClient(**kwargs)
+    _default_client.connect()
+    return _default_client
+
+
+def from_dataframe(df, *, name: str = "data"):
+    """Convert a DataFrame into a Plato room."""
+    return _get_client().from_dataframe(df, name=name)
+
+
+def from_function(func, *, name: str = "tool"):
+    """Wrap a Python function as an agent tool."""
+    return _get_client().from_function(func, name=name)
+
+
+def from_model(model, *, name: str = "model"):
+    """Wrap an ML model as a sense module."""
+    return _get_client().from_model(model, name=name)
+
+
+def from_api(url: str, *, name: str = "api"):
+    """Register a REST API as an agent resource."""
+    return _get_client().from_api(url, name=name)
+
+
+def publish_room():
+    """Publish the notebook's room with the fleet."""
+    return _get_client().publish_room()

openconstruct_jupyter-0.1.0/openconstruct_jupyter/display.py

@@ -0,0 +1,86 @@
+"""
+Rich display rendering for sense shadows, fleet topology, rooms, ticks, and config.
+"""
+
+from __future__ import annotations
+
+import html as html_lib
+from typing import Any
+
+
+def render_fleet(fleet_data: list[dict]) -> str:
+    """Render fleet topology as a styled HTML table."""
+    if not fleet_data:
+        return "<div style='color:#888'>No fleet agents discovered.</div>"
+    rows = "".join(
+        f"<tr><td>{a['agent_id']}</td><td><b>{a['name']}</b></td>"
+        f"<td style='color:{'#4a9' if a['status']=='online' else '#a44'}'>{a['status']}</td>"
+        f"<td>{', '.join(a.get('modules', []))}</td></tr>"
+        for a in fleet_data
+    )
+    return (
+        "<div style='font-family:monospace;background:#1e1e1e;color:#ddd;padding:12px;border-radius:6px'>"
+        "<b>🏗 Fleet Topology</b><br><br>"
+        "<table style='border-collapse:collapse'>"
+        "<tr><th style='padding:4px 12px;border-bottom:1px solid #555'>ID</th>"
+        "<th style='padding:4px 12px;border-bottom:1px solid #555'>Name</th>"
+        "<th style='padding:4px 12px;border-bottom:1px solid #555'>Status</th>"
+        "<th style='padding:4px 12px;border-bottom:1px solid #555'>Modules</th></tr>"
+        f"{rows}</table></div>"
+    )
+
+
+def render_room(room_data: dict) -> str:
+    """Render a Plato room as an SVG-style node graph."""
+    name = html_lib.escape(room_data.get("name", "?"))
+    tiles = room_data.get("tiles", [])
+    nodes_html = "".join(
+        f'<div style="border:1px solid #4a9;padding:4px 10px;margin:3px;border-radius:6px;'
+        f'background:#1a2a1a;display:inline-block">'
+        f'{html_lib.escape(t["name"])} <small style="color:#8ac">CR {t.get("cr_score", 0)}</small></div>'
+        for t in tiles
+    )
+    return (
+        f"<div style='font-family:monospace;background:#1a1a2a;color:#ddd;padding:12px;border-radius:6px'>"
+        f"<b>🏠 Room: {name}</b> <small>({len(tiles)} tiles)</small><br><br>"
+        f"{nodes_html}</div>"
+    )
+
+
+def render_tick(message: str) -> str:
+    """Render a tick as a chat bubble."""
+    safe = html_lib.escape(message)
+    return (
+        f"<div style='background:#2a3a5a;color:#ddd;padding:8px 14px;margin:4px 0;"
+        f"border-radius:10px;max-width:75%;font-family:monospace;display:inline-block'>"
+        f"✅ {safe}</div><br>"
+    )
+
+
+def render_shadow(shadow) -> str:
+    """Render a sense shadow as styled HTML."""
+    sense_type = getattr(shadow, "sense_type", "text")
+    output = html_lib.escape(str(getattr(shadow, "output", "")))
+    status = "✓" if getattr(shadow, "success", True) else "✗"
+    color = "#4a9" if getattr(shadow, "success", True) else "#a44"
+    return (
+        f"<div style='font-family:monospace;background:#1a1a1a;color:#ddd;padding:10px;"
+        f"border-left:3px solid {color};border-radius:4px;margin:4px 0'>"
+        f"<b>🔍 Sense: {html_lib.escape(sense_type)}</b> {status}<br>"
+        f"<pre style='margin:4px 0;color:#aaa'>{output[:500]}</pre></div>"
+    )
+
+
+def render_config_yaml(config: dict) -> str:
+    """Render config as syntax-highlighted YAML-ish HTML."""
+    lines = []
+    for k, v in config.items():
+        if isinstance(v, bool):
+            color = "#4a9" if v else "#a44"
+            lines.append(f'<span style="color:#88f">{k}</span>: <span style="color:{color}">{v}</span>')
+        elif isinstance(v, str):
+            lines.append(f'<span style="color:#88f">{k}</span>: <span style="color:#aa4">"{html_lib.escape(v)}"</span>')
+        else:
+            lines.append(f'<span style="color:#88f">{k}</span>: <span style="color:#ddd">{v}</span>')
+    body = "<br>".join(lines)
+    return f"<div style='font-family:monospace;background:#1e1e1e;color:#ddd;padding:10px;border-radius:4px'>{body}</div>"

openconstruct_jupyter-0.1.0/openconstruct_jupyter/fleet_panel.py

@@ -0,0 +1,38 @@
+"""
+Fleet status dashboard widget — a higher-level convenience wrapper.
+"""
+
+from __future__ import annotations
+
+import ipywidgets as widgets
+from IPython.display import display
+
+from .kernel import OCClient
+from .display import render_fleet
+
+
+class FleetPanel(widgets.VBox):
+    """Full fleet status dashboard with auto-refresh capability."""
+
+    def __init__(self, client: OCClient | None = None, **kwargs):
+        self._client = client or OCClient()
+        self.header = widgets.HTML(value="<h3>🏗 OpenConstruct Fleet</h3>")
+        self.body = widgets.HTML(value="<i>Click Refresh to discover fleet agents.</i>")
+        self.refresh_btn = widgets.Button(
+            description="🔄 Refresh", button_style="info", layout=widgets.Layout(width="120px")
+        )
+        self.refresh_btn.on_click(self._refresh)
+        self.connect_btn = widgets.Button(
+            description="⚡ Connect", button_style="success", layout=widgets.Layout(width="120px")
+        )
+        self.connect_btn.on_click(self._connect)
+        button_row = widgets.HBox(children=[self.connect_btn, self.refresh_btn])
+        super().__init__(children=[self.header, button_row, self.body], **kwargs)
+
+    def _connect(self, btn):
+        self._client.connect()
+        self._refresh(btn)
+
+    def _refresh(self, btn):
+        fleet = self._client.discover_fleet()
+        self.body.value = render_fleet(fleet)

openconstruct_jupyter-0.1.0/openconstruct_jupyter/kernel.py

@@ -0,0 +1,170 @@
+"""
+Agent-aware kernel hooks and OCClient — the brain behind the magic.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class SenseShadow:
+    """A captured sense shadow."""
+    shadow_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    sense_type: str = "text"
+    output: str = ""
+    success: bool = True
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class PlatoTile:
+    """A tile in a Plato room."""
+    tile_id: str = field(default_factory=lambda: uuid.uuid4().hex[:8])
+    name: str = ""
+    value: Any = None
+    cr_score: float = 0.0
+    source: str = "notebook"
+
+
+@dataclass
+class PlatoRoom:
+    """A Plato room — a shared knowledge space."""
+    room_id: str = field(default_factory=lambda: uuid.uuid4().hex[:8])
+    name: str = "default"
+    tiles: list[PlatoTile] = field(default_factory=list)
+    created: float = field(default_factory=time.time)
+
+    def add_tile(self, tile: PlatoTile):
+        self.tiles.append(tile)
+
+    def to_dict(self) -> dict:
+        return {
+            "room_id": self.room_id,
+            "name": self.name,
+            "tiles": [
+                {"tile_id": t.tile_id, "name": t.name, "cr_score": t.cr_score, "source": t.source}
+                for t in self.tiles
+            ],
+        }
+
+
+@dataclass
+class FleetAgent:
+    """An agent in the fleet."""
+    agent_id: str = ""
+    name: str = ""
+    status: str = "online"
+    modules: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Tick:
+    """A tick message."""
+    tick_id: str = field(default_factory=lambda: uuid.uuid4().hex[:8])
+    message: str = ""
+    timestamp: float = field(default_factory=time.time)
+
+
+class OCClient:
+    """
+    The core OpenConstruct client for Jupyter notebooks.
+
+    Maintains local state (rooms, shadows, fleet) and provides
+    the Python API surface (from_dataframe, from_function, etc.).
+    """
+
+    def __init__(self, notebook: bool = False, **kwargs):
+        self.connected = False
+        self.notebook = notebook
+        self.shadows: list[SenseShadow] = []
+        self.rooms: dict[str, PlatoRoom] = {}
+        self.fleet: list[FleetAgent] = []
+        self.ticks: list[Tick] = []
+        self.tools: dict[str, Callable] = {}
+        self.api_resources: dict[str, dict] = {}
+        self._default_room = PlatoRoom(name="notebook")
+
+    # --- Connection ---
+
+    def connect(self) -> dict:
+        """Connect to the OpenConstruct network."""
+        self.connected = True
+        self.fleet = [
+            FleetAgent(agent_id="self", name="notebook-agent", status="online", modules=["vision", "text"]),
+        ]
+        return {"status": "connected", "agent_id": "self"}
+
+    # --- Fleet ---
+
+    def discover_fleet(self) -> list[dict]:
+        """Return fleet topology."""
+        return [
+            {"agent_id": a.agent_id, "name": a.name, "status": a.status, "modules": a.modules}
+            for a in self.fleet
+        ]
+
+    # --- Shadows ---
+
+    def register_shadow(self, sense_type: str, output: str, success: bool = True) -> SenseShadow:
+        shadow = SenseShadow(sense_type=sense_type, output=output, success=success)
+        self.shadows.append(shadow)
+        return shadow
+
+    # --- Rooms ---
+
+    def load_room(self, name: str, context: str = "") -> PlatoRoom:
+        if name not in self.rooms:
+            self.rooms[name] = PlatoRoom(name=name)
+        if context:
+            tile = PlatoTile(name="cell_context", value=context, cr_score=0.5)
+            self.rooms[name].add_tile(tile)
+        return self.rooms[name]
+
+    def publish_room(self) -> dict:
+        """Publish the default room to the fleet."""
+        self._default_room.name = "published-notebook"
+        return self._default_room.to_dict()
+
+    # --- Ticks ---
+
+    def post_tick(self, message: str) -> Tick:
+        tick = Tick(message=message)
+        self.ticks.append(tick)
+        return tick
+
+    # --- Integration helpers ---
+
+    def from_dataframe(self, df, *, name: str = "data") -> PlatoTile:
+        """Convert a DataFrame into a Plato room tile with CR score."""
+        try:
+            rows = len(df)
+            cols = len(df.columns)
+            cr = min(1.0, (rows * cols) / 1000)
+        except Exception:
+            cr = 0.1
+        tile = PlatoTile(name=name, value=df, cr_score=round(cr, 2), source="dataframe")
+        self._default_room.add_tile(tile)
+        return tile
+
+    def from_function(self, func: Callable, *, name: str = "tool") -> dict:
+        """Register a Python function as an agent tool."""
+        self.tools[name] = func
+        return {"name": name, "type": "function", "registered": True}
+
+    def from_model(self, model, *, name: str = "model") -> dict:
+        """Register an ML model as a sense module."""
+        self.fleet.append(
+            FleetAgent(agent_id=name, name=name, status="online", modules=["inference"])
+        )
+        return {"name": name, "type": "model", "registered": True}
+
+    def from_api(self, url: str, *, name: str = "api") -> dict:
+        """Register a REST API as an agent resource."""
+        entry = {"url": url, "name": name, "type": "api"}
+        self.api_resources[name] = entry
+        return entry

openconstruct_jupyter-0.1.0/openconstruct_jupyter/magic.py

@@ -0,0 +1,81 @@
+"""
+%%openconstruct cell magic for IPython / Jupyter.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from IPython.core.magic import Magics, magics_class, cell_magic, line_magic
+from IPython.core.magic_arguments import argument, magic_arguments, parse_argstring
+from IPython.display import display, HTML, Javascript
+
+from .kernel import OCClient
+from .display import render_fleet, render_room, render_tick, render_shadow
+
+
+@magics_class
+class OpenConstructMagics(Magics):
+    """IPython magics for OpenConstruct."""
+
+    def __init__(self, shell=None, **kwargs):
+        super().__init__(shell, **kwargs)
+        self._client: OCClient | None = None
+
+    def _get_client(self) -> OCClient:
+        if self._client is None:
+            self._client = OCClient()
+        return self._client
+
+    @magic_arguments()
+    @argument("--sense", type=str, default=None, help="Capture cell output as a sense shadow (e.g. vision, text)")
+    @argument("--tick", type=str, default=None, help="Post a tick message")
+    @argument("--room", type=str, default=None, help="Create or load a Plato room")
+    @argument("--fleet", action="store_true", help="Show fleet discovery inline")
+    @cell_magic
+    def openconstruct(self, line: str, cell: str):
+        """OpenConstruct cell magic."""
+        args = parse_argstring(self.openconstruct, line)
+        client = self._get_client()
+
+        if args.fleet:
+            fleet_data = client.discover_fleet()
+            display(HTML(render_fleet(fleet_data)))
+            return
+
+        if args.tick:
+            client.post_tick(args.tick)
+            display(HTML(render_tick(args.tick)))
+            return
+
+        if args.room:
+            room_data = client.load_room(args.room, context=cell)
+            display(HTML(render_room(room_data)))
+            return
+
+        if args.sense:
+            # Execute cell, capture output as a sense shadow
+            result = self.shell.run_cell(cell)
+            shadow = client.register_shadow(
+                sense_type=args.sense,
+                output=str(result.result) if result.result else "",
+                success=result.success,
+            )
+            display(HTML(render_shadow(shadow)))
+            return
+
+        # Default: execute and show raw output
+        self.shell.run_cell(cell)
+
+
+def load_ipython_extension(ipython):
+    """Register the OpenConstruct magics with IPython."""
+    ipython.register_magics(OpenConstructMagics)
+
+
+def unload_ipython_extension(ipython):
+    """Unregister the OpenConstruct magics (no-op, IPython handles it)."""
+    pass

openconstruct_jupyter-0.1.0/openconstruct_jupyter/room_viewer.py

@@ -0,0 +1,44 @@
+"""
+Plato Room visualizer widget.
+"""
+
+from __future__ import annotations
+
+import ipywidgets as widgets
+from IPython.display import display
+
+from .kernel import OCClient, PlatoRoom
+from .display import render_room
+
+
+class RoomViewer(widgets.VBox):
+    """Interactive Plato Room visualizer."""
+
+    def __init__(self, client: OCClient | None = None, **kwargs):
+        self._client = client or OCClient()
+        self.header = widgets.HTML(value="<h3>🏠 Plato Room Viewer</h3>")
+        self.room_select = widgets.Dropdown(
+            options=["(no rooms)"],
+            description="Room:",
+            layout=widgets.Layout(width="300px"),
+        )
+        self.load_btn = widgets.Button(description="Load", button_style="primary")
+        self.load_btn.on_click(self._load)
+        self.body = widgets.HTML(value="<i>Select a room to visualize.</i>")
+        controls = widgets.HBox(children=[self.room_select, self.load_btn])
+        super().__init__(children=[self.header, controls, self.body], **kwargs)
+
+    def _refresh_rooms(self):
+        names = list(self._client.rooms.keys())
+        if not names:
+            names = ["(no rooms)"]
+        self.room_select.options = names
+
+    def _load(self, btn):
+        self._refresh_rooms()
+        name = self.room_select.value
+        if name in self._client.rooms:
+            room = self._client.rooms[name]
+            self.body.value = render_room(room.to_dict())
+        else:
+            self.body.value = "<i>No room selected.</i>"

openconstruct_jupyter-0.1.0/openconstruct_jupyter/widgets.py

@@ -0,0 +1,134 @@
+"""
+IPython widgets for interactive agent control.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import ipywidgets as widgets
+from IPython.display import display
+
+from .kernel import OCClient, FleetAgent
+
+
+class AgentConfigWidget(widgets.VBox):
+    """Dropdown configuration for modules and interface type."""
+
+    def __init__(self, client: OCClient | None = None, **kwargs):
+        self._client = client or OCClient()
+        self.module_dropdown = widgets.Dropdown(
+            options=["vision", "text", "inference", "analysis"],
+            value="vision",
+            description="Module:",
+        )
+        self.interface_dropdown = widgets.Dropdown(
+            options=["magic", "api", "widget", "cli"],
+            value="magic",
+            description="Interface:",
+        )
+        self.apply_btn = widgets.Button(description="Apply", button_style="primary")
+        self.apply_btn.on_click(self._on_apply)
+        self.output = widgets.Output()
+        super().__init__(
+            children=[self.module_dropdown, self.interface_dropdown, self.apply_btn, self.output],
+            **kwargs,
+        )
+
+    def _on_apply(self, btn):
+        with self.output:
+            print(f"Configured: module={self.module_dropdown.value}, interface={self.interface_dropdown.value}")
+
+
+class FleetStatusWidget(widgets.VBox):
+    """Live fleet health dashboard."""
+
+    def __init__(self, client: OCClient | None = None, **kwargs):
+        self._client = client or OCClient()
+        self.refresh_btn = widgets.Button(description="Refresh", button_style="info")
+        self.refresh_btn.on_click(self._refresh)
+        self.status_html = widgets.HTML(value="<i>No fleet data</i>")
+        super().__init__(children=[self.refresh_btn, self.status_html], **kwargs)
+
+    def _refresh(self, btn):
+        fleet = self._client.discover_fleet()
+        rows = "".join(
+            f"<tr><td>{a['name']}</td><td>{a['status']}</td><td>{', '.join(a['modules'])}</td></tr>"
+            for a in fleet
+        )
+        self.status_html.value = (
+            "<table><tr><th>Agent</th><th>Status</th><th>Modules</th></tr>"
+            f"{rows}</table>"
+        )
+
+
+class SenseShadowWidget(widgets.VBox):
+    """Rendered sense output (HTML / ANSI)."""
+
+    def __init__(self, **kwargs):
+        self.shadow_output = widgets.HTML(value="<i>No shadow captured</i>")
+        super().__init__(children=[self.shadow_output], **kwargs)
+
+    def show(self, html: str):
+        self.shadow_output.value = html
+
+
+class RoomGraphWidget(widgets.VBox):
+    """Plato room knowledge graph visualization."""
+
+    def __init__(self, client: OCClient | None = None, **kwargs):
+        self._client = client or OCClient()
+        self.graph_output = widgets.HTML(value="<i>No room loaded</i>")
+        super().__init__(children=[self.graph_output], **kwargs)
+
+    def show_room(self, room: dict):
+        tiles = room.get("tiles", [])
+        nodes = "".join(
+            f'<div style="border:1px solid #4a9;padding:4px 8px;margin:2px;border-radius:4px;'
+            f'background:#1a2a1a;display:inline-block">{t["name"]} <small>(CR {t["cr_score"]})</small></div>'
+            for t in tiles
+        )
+        self.graph_output.value = (
+            f'<div style="font-family:monospace">'
+            f'<b>Room: {room.get("name","?")}</b><br>{nodes}</div>'
+        )
+
+
+class TickBoardWidget(widgets.VBox):
+    """Scrolling tick messages."""
+
+    def __init__(self, **kwargs):
+        self.tick_area = widgets.HTML(value="<i>No ticks</i>")
+        self._messages: list[str] = []
+        super().__init__(children=[self.tick_area], **kwargs)
+
+    def add_tick(self, message: str):
+        self._messages.append(message)
+        bubbles = "".join(
+            f'<div style="background:#2a3a5a;color:#ddd;padding:6px 10px;margin:3px 0;'
+            f'border-radius:8px;max-width:70%">{m}</div>'
+            for m in self._messages[-20:]
+        )
+        self.tick_area.value = bubbles
+
+
+class PolicyWidget(widgets.VBox):
+    """Policy configuration with toggles."""
+
+    def __init__(self, **kwargs):
+        self.auto_register = widgets.ToggleButton(value=True, description="Auto-register")
+        self.auto_capture = widgets.ToggleButton(value=True, description="Auto-capture")
+        self.verbose = widgets.ToggleButton(value=False, description="Verbose")
+        self.output = widgets.Output()
+        super().__init__(
+            children=[self.auto_register, self.auto_capture, self.verbose, self.output],
+            **kwargs,
+        )
+
+    @property
+    def policy(self) -> dict:
+        return {
+            "auto_register": self.auto_register.value,
+            "auto_capture": self.auto_capture.value,
+            "verbose": self.verbose.value,
+        }

openconstruct_jupyter-0.1.0/openconstruct_jupyter.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: openconstruct-jupyter
+Version: 0.1.0
+Summary: Jupyter notebook integration for OpenConstruct — connect, sense, and build with agents
+Author: SuperInstance
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: ipython>=7.0
+Requires-Dist: ipywidgets>=8.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# openconstruct-jupyter — Jupyter Integration for OpenConstruct
+
+Connect OpenConstruct to your Jupyter notebooks in one line. Cell magic, widgets, fleet panels, and DataFrame-to-room conversion.
+
+**Part of [SuperInstance OpenConstruct](https://github.com/SuperInstance/OpenConstruct).**
+
+## What This Gives You
+
+- **Cell magic** — `%%openconstruct --sense vision` captures output as a sense shadow
+- **DataFrame → Plato room** — turn any pandas DataFrame into a knowledge graph
+- **Python function → agent tool** — `oc.from_function(greet, name="my_tool")`
+- **Fleet panel** — inline widget showing discovered fleet nodes
+- **Room viewer** — visualize Plato room tiles and dependencies
+
+## Quick Start
+
+```python
+# Load the extension
+%load_ext openconstruct_jupyter
+
+# Connect
+import openconstruct_jupyter as oc
+oc.connect(notebook=True)
+```
+
+### Cell Magic
+
+```python
+%%openconstruct --sense vision
+# Cell output captured as a vision shadow
+
+%%openconstruct --tick "analysis complete"
+# Post a tick to the fleet
+
+%%openconstruct --room my-analysis
+# Create or load a Plato room
+```
+
+### Python API
+
+```python
+import pandas as pd
+
+# DataFrame → room
+df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
+oc.from_dataframe(df, name="my_data")
+
+# Function → agent tool
+def greet(name):
+    return f"Hello, {name}!"
+oc.from_function(greet, name="greet_tool")
+
+# REST API → agent resource
+oc.from_api("https://api.example.com/data", name="external_data")
+```
+
+## Installation
+
+```bash
+pip install openconstruct-jupyter
+```
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## License
+
+MIT

openconstruct_jupyter-0.1.0/openconstruct_jupyter.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+openconstruct_jupyter/__init__.py
+openconstruct_jupyter/display.py
+openconstruct_jupyter/fleet_panel.py
+openconstruct_jupyter/kernel.py
+openconstruct_jupyter/magic.py
+openconstruct_jupyter/room_viewer.py
+openconstruct_jupyter/widgets.py
+openconstruct_jupyter.egg-info/PKG-INFO
+openconstruct_jupyter.egg-info/SOURCES.txt
+openconstruct_jupyter.egg-info/dependency_links.txt
+openconstruct_jupyter.egg-info/entry_points.txt
+openconstruct_jupyter.egg-info/requires.txt
+openconstruct_jupyter.egg-info/top_level.txt
+tests/test_magic.py

openconstruct_jupyter-0.1.0/openconstruct_jupyter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openconstruct_jupyter-0.1.0/openconstruct_jupyter.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[IPython.kernel]
+openconstruct = openconstruct_jupyter.magic:load_ipython_extension

openconstruct_jupyter-0.1.0/openconstruct_jupyter.egg-info/requires.txt

@@ -0,0 +1,7 @@
+ipython>=7.0
+ipywidgets>=8.0
+rich>=13.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio

openconstruct_jupyter-0.1.0/openconstruct_jupyter.egg-info/top_level.txt

@@ -0,0 +1 @@
+openconstruct_jupyter

openconstruct_jupyter-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openconstruct-jupyter"
+version = "0.1.0"
+description = "Jupyter notebook integration for OpenConstruct — connect, sense, and build with agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "SuperInstance" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Jupyter",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "ipython>=7.0",
+    "ipywidgets>=8.0",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio"]
+
+[project.entry-points."IPython.kernel"]
+openconstruct = "openconstruct_jupyter.magic:load_ipython_extension"
+
+[tool.setuptools.packages.find]
+include = ["openconstruct_jupyter*"]

openconstruct_jupyter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openconstruct_jupyter-0.1.0/tests/test_magic.py

@@ -0,0 +1,181 @@
+"""
+Tests for openconstruct-jupyter.
+"""
+
+import pytest
+from unittest.mock import MagicMock, patch
+
+
+# ── Kernel / OCClient ──────────────────────────────────────────────
+
+class TestOCClient:
+    def setup_method(self):
+        from openconstruct_jupyter.kernel import OCClient
+        self.client = OCClient()
+
+    def test_connect(self):
+        result = self.client.connect()
+        assert result["status"] == "connected"
+        assert self.client.connected is True
+
+    def test_discover_fleet_empty(self):
+        fleet = self.client.discover_fleet()
+        assert fleet == []
+
+    def test_discover_fleet_after_connect(self):
+        self.client.connect()
+        fleet = self.client.discover_fleet()
+        assert len(fleet) == 1
+        assert fleet[0]["name"] == "notebook-agent"
+
+    def test_register_shadow(self):
+        shadow = self.client.register_shadow("vision", "hello world")
+        assert shadow.sense_type == "vision"
+        assert shadow.output == "hello world"
+        assert shadow.success is True
+        assert len(self.client.shadows) == 1
+
+    def test_register_shadow_failure(self):
+        shadow = self.client.register_shadow("text", "error", success=False)
+        assert shadow.success is False
+
+    def test_post_tick(self):
+        tick = self.client.post_tick("test tick")
+        assert tick.message == "test tick"
+        assert len(self.client.ticks) == 1
+
+    def test_load_room_creates_new(self):
+        room = self.client.load_room("test-room")
+        assert room.name == "test-room"
+        assert "test-room" in self.client.rooms
+
+    def test_load_room_with_context(self):
+        room = self.client.load_room("ctx-room", context="some context")
+        assert len(room.tiles) == 1
+        assert room.tiles[0].value == "some context"
+
+    def test_load_room_idempotent(self):
+        self.client.load_room("same-room")
+        self.client.load_room("same-room")
+        assert len(self.client.rooms) == 1
+
+    def test_publish_room(self):
+        result = self.client.publish_room()
+        assert "room_id" in result
+
+    def test_from_dataframe(self):
+        import pandas as pd
+        df = pd.DataFrame({"x": range(50), "y": range(50)})
+        tile = self.client.from_dataframe(df, name="test_df")
+        assert tile.name == "test_df"
+        assert tile.source == "dataframe"
+        assert tile.cr_score > 0
+
+    def test_from_function(self):
+        def my_func(x):
+            return x + 1
+        result = self.client.from_function(my_func, name="adder")
+        assert result["registered"] is True
+        assert "adder" in self.client.tools
+
+    def test_from_model(self):
+        class M:
+            pass
+        result = self.client.from_model(M(), name="test_model")
+        assert result["registered"] is True
+
+    def test_from_api(self):
+        result = self.client.from_api("https://example.com", name="ex_api")
+        assert result["type"] == "api"
+        assert "ex_api" in self.client.api_resources
+
+
+# ── Display rendering ──────────────────────────────────────────────
+
+class TestDisplay:
+    def test_render_fleet_empty(self):
+        from openconstruct_jupyter.display import render_fleet
+        html = render_fleet([])
+        assert "No fleet agents" in html
+
+    def test_render_fleet_with_agents(self):
+        from openconstruct_jupyter.display import render_fleet
+        fleet = [{"agent_id": "a1", "name": "agent-1", "status": "online", "modules": ["vision"]}]
+        html = render_fleet(fleet)
+        assert "agent-1" in html
+        assert "online" in html
+
+    def test_render_room(self):
+        from openconstruct_jupyter.display import render_room
+        room = {"name": "test", "tiles": [{"name": "tile1", "cr_score": 0.5}]}
+        html = render_room(room)
+        assert "test" in html
+        assert "tile1" in html
+
+    def test_render_tick(self):
+        from openconstruct_jupyter.display import render_tick
+        html = render_tick("hello tick")
+        assert "hello tick" in html
+        assert "✅" in html
+
+    def test_render_shadow(self):
+        from openconstruct_jupyter.display import render_shadow
+        from openconstruct_jupyter.kernel import SenseShadow
+        shadow = SenseShadow(sense_type="vision", output="test output")
+        html = render_shadow(shadow)
+        assert "vision" in html
+        assert "test output" in html
+
+    def test_render_config_yaml(self):
+        from openconstruct_jupyter.display import render_config_yaml
+        html = render_config_yaml({"debug": True, "name": "test"})
+        assert "debug" in html
+        assert "test" in html
+
+
+# ── Magic ──────────────────────────────────────────────────────────
+
+class TestMagic:
+    def test_load_and_unload(self):
+        from openconstruct_jupyter.magic import load_ipython_extension, unload_ipython_extension
+        ipython = MagicMock()
+        load_ipython_extension(ipython)
+        ipython.register_magics.assert_called_once()
+        unload_ipython_extension(ipython)  # should not raise
+
+
+# ── Widgets ────────────────────────────────────────────────────────
+
+class TestWidgets:
+    def test_agent_config_widget(self):
+        from openconstruct_jupyter.widgets import AgentConfigWidget
+        w = AgentConfigWidget()
+        assert w.module_dropdown.value == "vision"
+
+    def test_fleet_status_widget(self):
+        from openconstruct_jupyter.widgets import FleetStatusWidget
+        w = FleetStatusWidget()
+        assert "No fleet data" in w.status_html.value
+
+    def test_sense_shadow_widget(self):
+        from openconstruct_jupyter.widgets import SenseShadowWidget
+        w = SenseShadowWidget()
+        w.show("<b>test</b>")
+        assert "<b>test</b>" in w.shadow_output.value
+
+    def test_tick_board_widget(self):
+        from openconstruct_jupyter.widgets import TickBoardWidget
+        w = TickBoardWidget()
+        w.add_tick("hello")
+        assert "hello" in w.tick_area.value
+
+    def test_policy_widget(self):
+        from openconstruct_jupyter.widgets import PolicyWidget
+        w = PolicyWidget()
+        assert w.policy["auto_register"] is True
+
+    def test_room_graph_widget(self):
+        from openconstruct_jupyter.widgets import RoomGraphWidget
+        w = RoomGraphWidget()
+        w.show_room({"name": "test", "tiles": [{"name": "t1", "cr_score": 0.7}]})
+        assert "t1" in w.graph_output.value