petekit 0.1.0a0__tar.gz

petekit-0.1.0a0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+---------
+
+Copyright (c) 2026 Schäfer List Systems GmbH
+
+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.

petekit-0.1.0a0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: petekit
+Version: 0.1.0a0
+Summary: PeteOS Kit — agentic building blocks for streams, text, and images
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: peteos
+Requires-Dist: diff-match-patch
+Provides-Extra: image
+Requires-Dist: opencv-python>=4.8.0; extra == "image"
+Requires-Dist: numpy>=1.24.0; extra == "image"
+Requires-Dist: mss; extra == "image"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Dynamic: license-file

petekit-0.1.0a0/README.md

@@ -0,0 +1,155 @@
+# PeteOS Kit
+
+A collection of PeteOS agentic building blocks for streams, text, and images.
+
+PeteOS Kit provides ready-to-use agentic objects you can inherit, compose, and deploy without building from scratch.
+
+## Subpackages
+
+- **`peteos_kit.stream`** — stream buffering, pattern matching, shell execution, and network connections
+- **`peteos_kit.text`** — buffer management, text editing, and web navigation
+- **`peteos_kit.image`** — image buffers, camera observation, and screen capture
+
+## Quick Start
+
+```python
+from peteos import AgenticObject
+from peteos_kit import RegexStreamObserver, StreamForwarder
+
+# Create a composed agent
+class LogMonitor(RegexStreamObserver, StreamForwarder, AgenticObject):
+    """You monitor log streams for patterns and forward interesting entries."""
+
+# Use it
+monitor = LogMonitor()
+result = await monitor.invoke_agent("Set up a pattern for ERROR messages in my syslog stream.")
+print(result)
+```
+
+## Key Components
+
+```mermaid
+---
+title: PeteOS Kit — Agentic Class Inheritance Hierarchy
+---
+classDiagram
+    direction TB
+
+    class BufferManager {
+        <<AgenticObject>>
+    }
+
+    class StreamBufferManager {
+        <<AgenticObject>>
+    }
+
+    class StreamObserver {
+        <<AgenticObject>>
+    }
+
+    class StreamForwarder {
+        <<AgenticObject>>
+    }
+
+    class RegexStreamObserver {
+        <<AgenticObject>>
+    }
+
+    class Basher {
+        <<AgenticObject>>
+    }
+
+    class SandboxedBasher {
+        <<AgenticObject>>
+    }
+
+    class Connector {
+        <<AgenticObject>>
+    }
+
+    class TextEditor {
+        <<AgenticObject>>
+    }
+
+    class WebNavigator {
+        <<AgenticObject>>
+    }
+
+    class NumPyBufferManager {
+        <<AgenticObject>>
+    }
+
+    class ImageBufferManager {
+        <<AgenticObject>>
+    }
+
+    class CameraObserver {
+        <<AgenticObject>>
+    }
+
+    class Screenshooter {
+        <<AgenticObject>>
+    }
+
+    %% Base hierarchy
+    BufferManager <|-- StreamBufferManager
+    StreamBufferManager <|-- StreamObserver
+
+    %% Action & shell agents on streams
+    StreamBufferManager <|-- StreamForwarder
+    StreamBufferManager <|-- Basher
+    StreamBufferManager <|-- Connector
+    Basher <|-- SandboxedBasher
+
+    %% Pattern matchers
+    StreamObserver <|-- RegexStreamObserver
+
+    %% Text agents
+    BufferManager <|-- TextEditor
+    BufferManager <|-- WebNavigator
+
+    %% Image agents
+    NumPyBufferManager <|-- ImageBufferManager
+    ImageBufferManager <|-- CameraObserver
+    ImageBufferManager <|-- Screenshooter
+```
+
+- **`BufferManager`** — in-memory text buffers with search, diff, and edit
+- **`StreamBufferManager`** — rolling, append-only stream buffers with rule-based routing
+- **`StreamObserver`** — observes streams and surfaces unexpected entries to the agent
+- **`RegexStreamObserver`** — regex-based pattern matchers as conditions for stream rules
+- **`TextEditor`** — file editing backed by a multi-file buffer
+- **`WebNavigator`** — web navigation backed by a buffer
+- **`ImageBufferManager`** — numpy-backed image buffers
+- **`CameraObserver`** — multi-camera observation with buffer management
+- **`Screenshooter`** — screen capture into image buffers
+- **`Basher`** / **`SandboxedBasher`** — shell execution with buffer integration
+
+## Installation
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install peteos_kit
+```
+
+For image processing support:
+
+```bash
+pip install peteos_kit[image]
+```
+
+## Configuration
+
+PeteOS Kit requires a working `peteos.json` in your project root or config directory. See the [PeteOS configuration docs](https://docs.peteos.ai/0.3.x/docs/config/) for details.
+
+## Resources
+
+- [PeteOS](https://peteos.ai) — the underlying framework
+- [PeteOS on GitHub](https://github.com/Schafer-List-Systems/peteos) — PeteOS framework source
+- [PeteOS Docs](https://docs.peteos.ai/0.3.x/docs/) — concepts, reference, and best practices
+- [PeteOS Kit on GitHub](https://github.com/Schafer-List-Systems/peteos_kit) — source and issues
+
+## Licensing
+
+This project is MIT-licensed. See the [LICENSE](LICENSE) file for details.

petekit-0.1.0a0/petekit/image/__init__.py

@@ -0,0 +1,9 @@
+from petekit.image.image_buffer_manager import ImageBufferManager
+from petekit.image.camera_observer import CameraObserver
+from petekit.image.screenshooter import Screenshooter
+
+__all__ = [
+    "ImageBufferManager",
+    "CameraObserver",
+    "Screenshooter",
+]

petekit-0.1.0a0/petekit/image/camera_observer.py

@@ -0,0 +1,96 @@
+"""CameraObserver - webcam access via a CameraDriver, backed by ImageBufferManager."""
+
+from __future__ import annotations
+
+import cv2
+
+from peteos import AgenticObject
+from peteos.oap.decorators import tool
+
+from petekit.utils.camera_driver import V4L2CameraDriver
+from .image_buffer_manager import ImageBufferManager
+
+
+class CameraObserver(ImageBufferManager, AgenticObject):
+    """You are an observer with access to cameras.
+
+    Only one camera can be open at a time. grab_image stores frames in ImageBufferManager.
+    Use read_np_buffer to send a captured frame to the LLM for reasoning.
+    """
+
+    def __init__(
+        self,
+        driver: CameraDriver | None = None,
+        scaling: int | None = None,
+    ) -> None:
+        super().__init__()
+        self._driver: CameraDriver = driver or V4L2CameraDriver()
+        self._scaling: int | None = scaling
+        self._active_camera_id: int | None = None
+
+    def _resize_if_needed(self, frame: cv2.Mat) -> cv2.Mat:
+        """Resize frame if scaling is configured."""
+        if self._scaling is None or self._scaling <= 0:
+            return frame
+        h, w = frame.shape[:2]
+        if w > h:
+            new_w = self._scaling
+            new_h = round(h * self._scaling / w)
+        else:
+            new_h = self._scaling
+            new_w = round(w * self._scaling / h)
+        return cv2.resize(frame, (new_w, new_h))
+
+    @tool(description="List all available cameras.")
+    def list_cameras(self) -> str:
+        cameras = self._driver.list_cameras()
+        if not cameras:
+            return "No cameras found."
+        return "Available cameras:\n" + "\n".join(
+            f"  Camera ID: {cid}, Driver: {self._driver.driver_name}, Description: {name}"
+            for cid, name in cameras
+        )
+
+    @tool(description="Open a camera by ID. Must be called before grab_image.")
+    def open_camera(self, camera_id: int) -> str:
+        if self._active_camera_id is not None:
+            return "ERROR: A camera is already open. Call close_camera first."
+
+        ok = self._driver.open(camera_id)
+        if not ok:
+            return f"ERROR: Camera {camera_id} could not be opened."
+
+        self._active_camera_id = camera_id
+
+        ok, frame, _ = self._driver.grab_frame()
+        if not ok or frame is None:
+            self._driver.close()
+            self._active_camera_id = None
+            return f"ERROR: Camera {camera_id} warm-up failed."
+
+        return f"OK: Camera {camera_id} (driver: {self._driver.driver_name}) opened."
+
+    @tool(description="Close the currently open camera.")
+    def close_camera(self) -> str:
+        if self._active_camera_id is None:
+            return "No camera is currently open."
+
+        self._driver.close()
+        self._active_camera_id = None
+        return "OK: Camera closed."
+
+    @tool(description="Capture a single image from the open camera and store it in the ImageBufferManager. Pass buffer_name to override the default name 'image:camera:<id>'.")
+    def grab_image(self, buffer_name: str | None = None) -> str:
+        if self._active_camera_id is None:
+            return "ERROR: No camera is open."
+
+        ok, frame, _ = self._driver.grab_frame()
+        if not ok or frame is None:
+            return "ERROR: Failed to capture image."
+
+        frame = self._resize_if_needed(frame)
+
+        name = buffer_name if buffer_name is not None else f"image:camera:{self._active_camera_id}"
+        self._store_np_buffer(name, frame)
+
+        return f"OK: Image captured ({frame.shape[1]}x{frame.shape[0]}), stored as '{name}'."

petekit-0.1.0a0/petekit/image/image_buffer_manager.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import cv2
+
+from peteos import AgenticObject, tool
+
+from petekit.numpy_buffer_manager import NumPyBufferManager
+
+
+@dataclass
+class ImageRegion:
+    """Pixel-based region of an image. Coordinates are 0-based and inclusive. (x1, y1) is the top-left corner, (x2, y2) is the bottom-right corner."""
+    x1: int
+    y1: int
+    x2: int
+    y2: int
+
+
+class ImageBufferManager(NumPyBufferManager, AgenticObject):
+    """
+    - For image-like numpy buffers, you can call read_np_buffer to have a look at them.
+    - The read_np_buffer tool will transform image coordinates into numpy coordinates for you.
+    - Image-like buffer names are usually prefixed with "image:"
+    """
+
+    @tool(description="Read a NumPy buffer as an image and send it to the LLM for reasoning. Pass an ImageRegion for pixel-based region cropping (0-based, inclusive): (x1, y1) is the top-left corner, (x2, y2) is the bottom-right corner. Omit the region to read the full image.")
+    async def read_np_buffer(self, name: str, runner, region: ImageRegion | None = None) -> str:
+        """Read a buffer (or region) and send it to the LLM. Returns a hint; the LLM sees the image directly."""
+        if name not in self._buffers:
+            return f"Error: no buffer named '{name}'. Use copy_np_buffer or an inheriting agent to create it."
+        buf = self._buffers[name]
+        array = buf.array
+
+        if region is None:
+            region_array = array
+        else:
+            x1, y1, x2, y2 = region.x1, region.y1, region.x2, region.y2
+            if x1 > x2 or y1 > y2:
+                return f"Error: region x1={x1} > x2={x2} or y1={y1} > y2={y2}. Buffer shape is {array.shape}."
+            if x2 >= array.shape[1] or y2 >= array.shape[0]:
+                return f"Error: x2={x2} or y2={y2} exceeds buffer shape {array.shape}."
+            region_array = array[y1:y2+1, x1:x2+1]
+
+        total_pixels = region_array.shape[0] * region_array.shape[1]
+        if total_pixels > NumPyBufferManager._MAX_PIXELS:
+            actual_w, actual_h = array.shape[1], array.shape[0]
+            return (
+                f"Requested region for buffer '{name}' has {total_pixels} pixels, exceeding the {NumPyBufferManager._MAX_PIXELS}-pixel limit "
+                f"(image is {actual_w}x{actual_h}={actual_w*actual_h} pixels). "
+                f"Use a smaller ImageRegion to stay under the limit."
+            )
+
+        encode_ok, png_bytes = cv2.imencode(".png", region_array)
+        if not encode_ok:
+            return f"Error: cv2.imencode failed for buffer '{name}'."
+        image_data = png_bytes.tobytes()
+
+        await self._send_media(
+            data=image_data,
+            mime_type="image/png",
+            runner=runner,
+        )
+        return f"Buffer '{name}' ({region_array.shape}) sent to LLM for reasoning."

petekit-0.1.0a0/petekit/image/multi_camera_observer.py

@@ -0,0 +1,133 @@
+"""MultiCameraObserver - manages multiple camera drivers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import cv2
+
+from peteos.agentic_objects.camera_driver import CameraDriver
+from peteos.oap.agentic_object import AgenticObject
+from peteos.oap.decorators import tool
+
+if TYPE_CHECKING:
+    from peteos.session import Session
+
+
+class MultiCameraObserver(AgenticObject):
+    """Observer with access to multiple camera drivers.
+
+    Registers drivers by name. When listing cameras, returns
+    the driver name, camera ID, and description for all drivers.
+    Only one camera (from any driver) can be open at a time.
+    """
+
+    def __init__(self, scaling: int | None = None) -> None:
+        super().__init__()
+        self._drivers: dict[str, CameraDriver] = {}
+        self._scaling: int | None = scaling
+        self._active_driver: CameraDriver | None = None
+        self._active_camera_id: int | None = None
+        self._cached_frame: bytes | None = None
+        self._cached_shape: tuple[int, int] | None = None
+
+    def register_driver(self, driver: CameraDriver) -> None:
+        """Register a camera driver by name."""
+        self._drivers[driver.driver_name] = driver
+
+    @tool(description="List all available cameras across all registered drivers.")
+    def list_cameras(self) -> str:
+        cameras: list[tuple[str, int, str]] = []
+        for driver in self._drivers.values():
+            for cid, desc in driver.list_cameras():
+                cameras.append((driver.driver_name, cid, desc))
+        if not cameras:
+            return "No cameras found."
+        lines = []
+        for driver_name, cid, desc in cameras:
+            lines.append(
+                f"  Driver: {driver_name}, Camera ID: {cid}, Description: {desc}"
+            )
+        return "Available cameras:\n" + "\n".join(lines)
+
+    @tool(description="Open a camera from a specific driver.")
+    def open_camera(self, driver_name: str, camera_id: int) -> str:
+        if self._active_driver is not None:
+            return "ERROR: A camera is already open. Call close_camera first."
+
+        driver = self._drivers.get(driver_name)
+        if driver is None:
+            return f"ERROR: Unknown driver '{driver_name}'. Register it first."
+
+        if not driver.open(camera_id):
+            return f"ERROR: Camera {camera_id} on driver '{driver_name}' could not be opened."
+
+        self._active_driver = driver
+        self._active_camera_id = camera_id
+        self._cached_frame = None
+        self._cached_shape = None
+
+        # Warm up: grab a frame.
+        ok, frame, _ = driver.grab_frame()
+        if not ok or frame is None:
+            driver.close()
+            self._active_driver = None
+            self._active_camera_id = None
+            self._cached_frame = None
+            self._cached_shape = None
+            return f"ERROR: Camera warm-up failed on '{driver_name}'."
+
+        return f"OK: Camera {camera_id} opened (driver: {driver_name})."
+
+    @tool(description="Close the currently open camera.")
+    def close_camera(self) -> str:
+        if self._active_driver is None:
+            return "No camera is currently open."
+
+        self._active_driver.close()
+        self._active_driver = None
+        self._active_camera_id = None
+        self._cached_frame = None
+        self._cached_shape = None
+        return "OK: Camera closed."
+
+    @tool(description="Capture a single image from the open camera. Caches the frame in memory.")
+    def grab_image(self) -> str:
+        if self._active_driver is None:
+            return "ERROR: No camera is open."
+
+        ok, frame, (raw_w, raw_h) = self._active_driver.grab_frame()
+        if not ok or frame is None:
+            return "ERROR: Failed to capture image."
+
+        # Resize if scaling is configured.
+        if self._scaling is not None and self._scaling > 0:
+            h, w = frame.shape[:2]
+            if w > h:
+                new_w = self._scaling
+                new_h = round(h * self._scaling / w)
+            else:
+                new_h = self._scaling
+                new_w = round(w * self._scaling / h)
+            frame = cv2.resize(frame, (new_w, new_h))
+
+        # Encode as PNG.
+        _, encoded = cv2.imencode(".png", frame)
+        self._cached_frame = encoded.tobytes()
+        self._cached_shape = (frame.shape[1], frame.shape[0])
+        return f"OK: Image captured ({self._cached_shape[0]}x{self._cached_shape[1]}), cached in memory."
+
+    @tool(description="Read the cached image from the last grab_image call and send it to the session.")
+    async def read_cached_image(self, session: "Session | None" = None) -> str:
+        if self._cached_frame is None:
+            return "ERROR: No image has been captured yet. Call grab_image first."
+
+        if session is None:
+            return "ERROR: Session not available."
+
+        await self._send_media(
+            data=self._cached_frame,
+            mime_type="image/png",
+            session=session,
+        )
+        return "OK: Image sent to session."

petekit-0.1.0a0/petekit/image/screenshooter.py

@@ -0,0 +1,40 @@
+"""Screenshooter - capture the screen and store images in the ImageBufferManager."""
+
+from __future__ import annotations
+
+import cv2
+import mss
+import numpy as np
+
+from peteos import AgenticObject, tool
+
+from .image_buffer_manager import ImageBufferManager, ImageRegion
+
+
+class Screenshooter(ImageBufferManager, AgenticObject):
+    """
+    - You can call the take_screenshoot tool to take a screenshoot and store it into a numby buffer.
+    """
+
+    @tool(description="")
+    def take_screenshot(self, name: str, region: ImageRegion | None = None) -> str:
+        """
+        Take a screenshot and store it into a numby buffer.
+        Pass region as a dict with keys x1, y1 (top-left corner) and x2, y2 (bottom-right corner) to capture only that pixel region.
+        Omit region entirely to capture the full screen.
+        When calling read_np_buffer, use the exact buffer name from the return message.
+        """
+        with mss.MSS() as s:
+            if region is None:
+                monitor = s.monitors[0]
+            else:
+                monitor = (region.x1, region.y1, region.x2, region.y2)
+            screenshot = s.grab(monitor)
+
+        array_bgr = cv2.cvtColor(np.asarray(screenshot), cv2.COLOR_BGRA2BGR)
+
+        buffer_name = name if name.startswith("image:") else f"image:{name}"
+        self._store_np_buffer(buffer_name, array_bgr)
+
+        h, w = array_bgr.shape[:2]
+        return f"Screenshot stored in buffer '{buffer_name}' ({w}x{h} pixels). Use read_np_buffer to send it to the LLM."

petekit-0.1.0a0/petekit/petekit.egg-info/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: petekit
+Version: 0.1.0a0
+Summary: PeteOS Kit — agentic building blocks for streams, text, and images
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: peteos
+Requires-Dist: diff-match-patch
+Provides-Extra: image
+Requires-Dist: opencv-python>=4.8.0; extra == "image"
+Requires-Dist: numpy>=1.24.0; extra == "image"
+Requires-Dist: mss; extra == "image"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Dynamic: license-file

petekit-0.1.0a0/petekit/petekit.egg-info/SOURCES.txt

@@ -0,0 +1,37 @@
+LICENSE
+README.md
+pyproject.toml
+petekit/image/__init__.py
+petekit/image/camera_observer.py
+petekit/image/image_buffer_manager.py
+petekit/image/multi_camera_observer.py
+petekit/image/screenshooter.py
+petekit/petekit.egg-info/PKG-INFO
+petekit/petekit.egg-info/SOURCES.txt
+petekit/petekit.egg-info/dependency_links.txt
+petekit/petekit.egg-info/requires.txt
+petekit/petekit.egg-info/top_level.txt
+petekit/stream/__init__.py
+petekit/stream/basher.py
+petekit/stream/connector.py
+petekit/stream/sandboxed_basher.py
+petekit/stream/stream_buffer_manager.py
+petekit/stream/stream_forwarder.py
+petekit/stream/stream_observer.py
+petekit/stream/pattern_matchers/fsa_stream.py
+petekit/stream/pattern_matchers/grammar_stream.py
+petekit/stream/pattern_matchers/heavy_hitter_stream.py
+petekit/stream/pattern_matchers/multiline_regex_stream.py
+petekit/stream/pattern_matchers/regex_stream.py
+petekit/text/__init__.py
+petekit/text/buffer_manager.py
+petekit/text/text_editor.py
+petekit/text/web_navigator.py
+petekit/tools/__init__.py
+petekit/tools/psh.py
+petekit/utils/__init__.py
+petekit/utils/three_merge.py
+petekit/utils/camera_driver/__init__.py
+petekit/utils/camera_driver/camera_driver.py
+petekit/utils/camera_driver/cv2_camera_driver.py
+petekit/utils/camera_driver/v4l2_camera_driver.py

petekit-0.1.0a0/petekit/petekit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

petekit-0.1.0a0/petekit/petekit.egg-info/requires.txt

@@ -0,0 +1,11 @@
+peteos
+diff-match-patch
+
+[dev]
+pytest
+pytest-asyncio
+
+[image]
+opencv-python>=4.8.0
+numpy>=1.24.0
+mss

petekit-0.1.0a0/petekit/petekit.egg-info/top_level.txt

@@ -0,0 +1,5 @@
+image
+stream
+text
+tools
+utils

petekit-0.1.0a0/petekit/stream/__init__.py

@@ -0,0 +1,22 @@
+from petekit.stream.stream_buffer_manager import StreamBufferManager, StreamBufferRules, Rule
+from petekit.stream.stream_observer import StreamObserver
+from petekit.stream.stream_forwarder import StreamForwarder
+from petekit.stream.pattern_matchers.regex_stream import RegexStreamObserver, RegexPattern
+from petekit.stream.basher import Basher, BashHandle
+from petekit.stream.connector import Connector, ConnectionHandle
+from petekit.stream.sandboxed_basher import SandboxedBasher
+
+__all__ = [
+    "StreamBufferManager",
+    "StreamBufferRules",
+    "Rule",
+    "StreamObserver",
+    "StreamForwarder",
+    "RegexStreamObserver",
+    "RegexPattern",
+    "Basher",
+    "BashHandle",
+    "Connector",
+    "ConnectionHandle",
+    "SandboxedBasher",
+]