peteos 0.0.2__tar.gz

peteos-0.0.2/LICENSE

@@ -0,0 +1,60 @@
+LICENSE
+-------
+
+Copyright (c) 2026 Schäfer List Systems GmbH
+
+This software is dual-licensed.
+
+1. NON-COMMERCIAL LICENSE (FREE)
+
+   1.1 Grant of License
+   Subject to the terms of this Section 1, you are granted a non-exclusive,
+   non-transferable, worldwide, royalty-free license to use, copy, modify,
+   and distribute this software, solely for non-commercial purposes.
+
+   1.2 Definition of Non-Commercial Use
+   "Non-commercial use" means any use that is not primarily intended for or
+   directed towards commercial advantage or monetary compensation, including
+   but not limited to:
+     - personal projects,
+     - academic research,
+     - internal evaluation and testing,
+     - evaluation of potential commercial use cases within your organization.
+
+   1.3 Evaluation of Commercial Use Cases
+   You may use this software under this non-commercial license to evaluate
+   its suitability for a commercial use case within your organization.
+   However, any actual deployment, production use, or integration into a
+   product or service that is offered commercially requires a separate
+   commercial license from Your Company.
+
+   1.4 Restrictions
+   Under this non-commercial license you may NOT:
+     - use the software in any product or service offered for sale, license,
+       or subscription;
+     - use the software to provide any commercial hosting, SaaS, or managed
+       service;
+     - remove or alter copyright notices or license texts.
+
+   1.5 No Warranty
+   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.
+
+2. COMMERCIAL LICENSE
+
+   If you wish to use this software for any commercial purpose, including but
+   not limited to production deployment, integration into a commercial product,
+   or offering any service based on this software, you must obtain a commercial
+   license from Your Company.
+
+   For commercial licensing, please contact:
+     Email: info@schaeferlist.de
+     Web:  https://www.schaeferlist.de
+
+3. GENERAL
+
+   This dual-licensing model is permissible because the Schaefer List Systems GmbH
+   owns all copyrights in this software. By using this software, you agree to comply
+   with either the non-commercial license (Section 1) or a valid commercial
+   license (Section 2), as applicable to your use case.

peteos-0.0.2/MANIFEST.in

@@ -0,0 +1,2 @@
+global-exclude *.c
+global-exclude __pycache__

peteos-0.0.2/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: peteos
+Version: 0.0.2
+Summary: Agentic application framework
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: json5>=0.15.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: tiktoken>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Requires-Dist: cython>=3.0; extra == "dev"
+Provides-Extra: camera
+Requires-Dist: opencv-python>=4.8.0; extra == "camera"
+Requires-Dist: numpy>=1.24.0; extra == "camera"
+Provides-Extra: web
+Requires-Dist: beautifulsoup4; extra == "web"
+Requires-Dist: lxml; extra == "web"
+Dynamic: license-file

peteos-0.0.2/README.md

@@ -0,0 +1,112 @@
+# Peteos
+
+Simple Object-Agentic Programming (sOAP) — an agentic application framework that brings together object-oriented programming and AI agents.
+The easiest way to build reliable and powerful multi-agent systems.
+
+Peteos lets you build **agentic objects**: ordinary Python objects that can think, decide, and act on their own.
+No external memory stores or bolt-on intelligence — the object itself is the center of persistence and agency.
+
+## Quick Start
+
+After installing and configuring Peteos, you can build and use agentic objects like the following. 
+
+```python
+class Example(AgenticObject):
+    """You are Pete, a concise assistant."""
+    def __init__(self, job: str):
+        super().__init__()
+        self._job = job
+    
+    @tool
+    def get_job(self) -> str:
+        return self._job
+
+pete = Example("demonstrator")
+result = await pete.invoke_agent("Hello, what's your name and job?", output_schema=list[str])
+print(result)  # ['Pete', 'demonstrator']
+```
+
+## Key Features
+
+The documentation and the examples cover more complex agentic objects with the following key features. 
+
+- **Agentic objects** — derive from `AgenticObject` and get a thinking agent behind every instance.
+- **Inheritance** — inherit from agentic objects to refine the system prompt and extend its toolset.
+- **Multi-inheritance composition** — combine agentic classes to compose behavior.
+- **Structured output** — declare `output_schema` and get typed results back.
+- **Sandboxed code execution** — let agents run Python in a restricted sandbox.
+- **Persistent sessions** — threads, memory, and sub-agent coordination via `persistent_thread_id`.
+- **Test-driven development** — it's OOP, so test your agents as you test any other software.
+- **Debuggable agents** — it's plain Python, so debug your agents with a standard debugger.
+
+
+## Installation
+
+### From source
+
+```bash
+git clone --recurse-submodules https://github.com/yourusername/peteos.git
+cd peteos
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### From a distribution package
+
+Download a `.tar.gz` archive and extract it, then install the wheel inside:
+
+```bash
+tar xzf peteos-0.0.1.tar.gz
+cd peteos-0.0.1
+python -m venv .venv
+source .venv/bin/activate
+pip install peteos-0.0.1-cp312-cp312-linux_x86_64.whl
+```
+
+### From a Python package (PyPI / direct install)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install peteos
+```
+
+## Configuration
+
+Copy `peteos.json.example` to `peteos.json` and adapt it to your environment:
+
+```bash
+cp peteos.json.example peteos.json
+```
+
+The configuration file defines chatbot backends (LLM providers) that Peteos uses for agent reasoning:
+
+- **name** — a descriptive label for the backend
+- **url** — the API endpoint for the provider
+- **api_type** — `anthropic`, `gemini`, or omitted for OpenAI-compatible endpoints
+- **api_key** — environment variable name holding the API key (never hardcode keys)
+- **model_priorities** — maps model names to priority scores (higher = preferred)
+
+To verify that your configuration is functional run `python3 examples/00_hello_pete.py`.
+
+## Resources
+
+- [Getting Started](docs/getting-started.md) — installation and first example
+- [Introduction](docs/introduction.md) — the sOAP paradigm
+- [Concepts](docs/concepts/index.md) — composition, invocation, state, testing
+- [Reference](docs/reference/index.md) — API docs, agentic objects
+- [Best Practices](docs/best-practices/index.md) — Best practices when using PeteOS
+- [Examples](docs/examples/) — Examples show-casing some features
+
+## Licensing
+
+This project is dual-licensed:
+
+- **Non-commercial use** (including evaluation of commercial use cases) is free
+  under the license in the `LICENSE` file.
+- **Commercial use** (production, products, services, SaaS, etc.) requires a
+  commercial license from the Schäfer List Systems GmbH.
+
+If you intend to use this software commercially, please contact us at
+<info@schaeferlist.de> or visit <https://www.schaeferlist.de>.

peteos-0.0.2/peteos/__init__.py

@@ -0,0 +1,28 @@
+# Peteos - Agentic application framework
+
+import asyncio
+
+from peteos.config import ConfigManager
+
+# OAP primitives
+from peteos.oap import (
+    AgenticObject,
+    AdaptiveObject,
+    Error,
+    agentic_object,
+    tool,
+)
+
+__all__ = [
+    "AgenticObject",
+    "AdaptiveObject",
+    "Error",
+    "agentic_object",
+    "tool",
+]
+
+# Bootstrap backends and roles from peteos.json at import time.
+try:
+    asyncio.get_running_loop()
+except RuntimeError:
+    asyncio.run(ConfigManager.init())

peteos-0.0.2/peteos/agentic_objects/__init__.py

@@ -0,0 +1,20 @@
+"""Agentic Objects - concrete implementations using the OAP framework."""
+
+from peteos.agentic_objects.camera_driver import CameraDriver, CV2CameraDriver
+from peteos.agentic_objects.camera_observer import CameraObserver
+from peteos.agentic_objects.multi_camera_observer import MultiCameraObserver
+from peteos.agentic_objects.pdf_transcriber import PdfTranscriber
+from peteos.agentic_objects.bash_workspace import BashWorkspace
+from peteos.agentic_objects.string_comparator import AgenticStringComparator
+from peteos.agentic_objects.text_editor import TextEditor
+
+__all__ = [
+    "AgenticStringComparator",
+    "BashWorkspace",
+    "CameraDriver",
+    "CV2CameraDriver",
+    "CameraObserver",
+    "MultiCameraObserver",
+    "PdfTranscriber",
+    "TextEditor",
+]

peteos-0.0.2/peteos/agentic_objects/bash_workspace.py

@@ -0,0 +1,219 @@
+"""BashWorkspace - secure bash execution agentic object."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from peteos.oap.agentic_object import AgenticObject
+from peteos.oap.decorators import tool
+from peteos.utils import get_logger
+
+_logger = get_logger(__name__)
+
+if TYPE_CHECKING:
+    from peteos.engine import Runner
+
+# Safe POSIX utilities available in the sandbox.
+# No network tools (curl, wget, nc), no shells (bash -c via env vars), no
+# process control (kill, top), no system introspection (ps, whoami).
+_SAFE_COMMANDS: set[str] = {
+    "cat", "echo", "grep", "egrep", "sed", "awk", "sort", "uniq", "wc",
+    "head", "tail", "cut", "tr", "mkdir", "cp", "mv", "rm", "ln", "chmod",
+    "touch", "find", "basename", "dirname", "test", "date", "sleep",
+    "tee", "xargs", "shuf", "paste", "join", "diff", "comm", "uniq",
+    "base64", "md5sum", "sha256sum", "stat", "du", "file", "ls",
+    # Bash builtins — executed via /bin/sh -c, so not listed here directly.
+}
+
+# Strictly minimal POSIX environment: no PATH leaks, no secrets, no user config.
+_MINIMAL_ENV: dict[str, str] = {
+    "PATH": "/usr/bin:/bin",
+    "HOME": "/tmp/bash_workspace_home",
+    "LANG": "C",
+    "LC_ALL": "C",
+    "TERM": "dumb",
+    "TMPDIR": "/tmp",
+}
+
+
+class BashWorkspace(AgenticObject):
+    """You are a secure bash workspace for executing shell commands.
+
+    You can run bash commands on files placed in your workspace. You have
+    NO access to the rest of the filesystem beyond your workspace directory.
+    The environment is minimal: no network tools, no secrets, no user data.
+
+    Your workspace is created fresh for each invocation and destroyed
+    afterward. Files must be provided to you — you cannot access anything
+    outside your workspace directory.
+
+    Available commands: cat, echo, grep, sed, awk, sort, uniq, wc, head,
+    tail, cut, tr, mkdir, cp, mv, rm, ln, chmod, touch, find, basename,
+    dirname, test, date, sleep, tee, xargs, shuf, paste, join, diff, comm,
+    base64, md5sum, sha256sum, stat, du, file, ls.
+
+    No network tools (curl, wget, nc) or shell escapes are available.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._workspace_dir: Path | None = None
+
+    @property
+    def workspace_dir(self) -> Path | None:
+        """The current workspace directory, or None if not active."""
+        return self._workspace_dir
+
+    def _setup_workspace(self) -> Path:
+        """Create or return the workspace directory.
+
+        Uses an existing workspace if available, otherwise creates a new
+        temporary directory.
+        """
+        if self._workspace_dir is None or not self._workspace_dir.is_dir():
+            self._workspace_dir = Path(tempfile.mkdtemp(prefix="bash_workspace_"))
+            # Create HOME dir so tools like `ssh` (if it slipped through)
+            # don't error on missing ~/.ssh — this is a defense-in-depth.
+            (self._workspace_dir / "home").mkdir(exist_ok=True)
+            os.environ["HOME"] = str(self._workspace_dir / "home")
+        return self._workspace_dir
+
+    def _teardown_workspace(self) -> None:
+        """Remove the workspace directory."""
+        if self._workspace_dir and self._workspace_dir.is_dir():
+            import shutil
+            shutil.rmtree(self._workspace_dir, ignore_errors=True)
+        self._workspace_dir = None
+
+    @property
+    def _env(self) -> dict[str, str]:
+        """Build the sandbox environment with the workspace HOME."""
+        env = {**_MINIMAL_ENV}
+        if self._workspace_dir:
+            env["HOME"] = str(self._workspace_dir / "home")
+        # Inherit only a few safe env vars from the parent process.
+        for key in ("TERM", "LANG", "LC_ALL"):
+            val = os.environ.get(key)
+            if val:
+                env[key] = val
+        return env
+
+    def _is_safe_command(self, command: str) -> bool:
+        """Check if the command (first word) is in the allowlist."""
+        first = command.strip().split()[0] if command.strip() else ""
+        # Handle built-in /bin/sh -c wrapper
+        if first == "/bin/sh" or first == "sh":
+            return True
+        # Extract basename for /usr/bin/foo paths
+        base = os.path.basename(first)
+        return base in _SAFE_COMMANDS
+
+    @tool
+    def bash_exec(self, command: str, timeout: int = 30) -> str:
+        """Execute a bash command in the sandboxed workspace.
+
+        Args:
+            command: The bash command to execute.
+
+        Returns:
+            A string containing exit code, stdout, and stderr information.
+        """
+        ws = self._setup_workspace()
+
+        if not command.strip():
+            return "Error: Empty command."
+
+        # Block path traversal patterns in the raw command text before
+        # we even spawn a shell. This catches ../ escape attempts early.
+        if ".." in command:
+            return "Error: Path traversal is not allowed."
+
+        # Block command substitution and backticks that could bypass
+        # the allowlist via subshell execution.
+        _BLOCKED_CHARS = ("`", "$(")
+        for bad in _BLOCKED_CHARS:
+            if bad in command:
+                return f"Error: The character or sequence '{bad}' is not allowed."
+
+        # Quick allowlist check on the first token to catch obviously
+        # dangerous commands before we even spawn a shell.
+        if not self._is_safe_command(command):
+            base = os.path.basename(command.strip().split()[0])
+            return f"Error: Command '{base}' is not allowed in the sandbox."
+
+        _logger.debug("[bash_exec] ws=%s, command=%r", ws, command)
+        try:
+            result = subprocess.run(
+                ["/bin/sh", "-c", command],
+                cwd=ws,
+                env=self._env,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+            _logger.debug("[bash_exec] stdout=%r, stderr=%r, returncode=%d", result.stdout, result.stderr, result.returncode)
+            output = f"exit_code: {result.returncode}"
+            if result.stdout:
+                output += f"\nstdout:\n{result.stdout}"
+            if result.stderr:
+                output += f"\nstderr:\n{result.stderr}"
+            if not result.stdout and not result.stderr:
+                output = "(no output)"
+            return output
+        except subprocess.TimeoutExpired:
+            return "Error: Command timed out after 30 seconds."
+        except Exception as e:
+            return f"Error: {type(e).__name__}: {e}"
+
+    @tool
+    def put_file(self, name: str, content: str) -> str:
+        """Place a file into the workspace.
+
+        Args:
+            name: The filename to create in the workspace.
+            content: The file contents as a string.
+
+        Returns:
+            Confirmation message.
+        """
+        ws = self._setup_workspace()
+        filepath = (ws / name).resolve()
+        # Guard: prevent directory traversal outside workspace.
+        # resolve() normalizes .. so this is a proper containment check.
+        try:
+            filepath.relative_to(ws.resolve())
+        except ValueError:
+            return f"Error: File name '{name}' is not allowed."
+        try:
+            filepath.write_text(content)
+            return f"OK: File '{name}' successfully written."
+        except Exception as e:
+            return f"Error: Failed to write '{name}': {e}"
+
+    @tool
+    def get_file(self, name: str) -> str:
+        """Read the content of a file from the workspace.
+
+        Args:
+            name: The filename to read from the workspace.
+
+        Returns:
+            The file contents as a string.
+        """
+        ws = self._setup_workspace()
+        filepath = (ws / name).resolve()
+        # resolve() normalizes .. so this is a proper containment check.
+        try:
+            filepath.relative_to(ws.resolve())
+        except ValueError:
+            return f"Error: File name '{name}' is not allowed."
+        if not filepath.is_file():
+            return f"Error: File '{name}' not found in workspace."
+        try:
+            return filepath.read_text()
+        except Exception as e:
+            return f"Error: Failed to read '{name}': {e}"

peteos-0.0.2/peteos/agentic_objects/camera_driver/__init__.py

@@ -0,0 +1,8 @@
+"""CameraDriver - abstract interface for camera backends."""
+
+from __future__ import annotations
+
+from peteos.agentic_objects.camera_driver.camera_driver import CameraDriver
+from peteos.agentic_objects.camera_driver.cv2_camera_driver import CV2CameraDriver
+
+__all__ = ["CameraDriver", "CV2CameraDriver"]

peteos-0.0.2/peteos/agentic_objects/camera_driver/camera_driver.py

@@ -0,0 +1,50 @@
+"""CameraDriver - abstract interface for camera backends."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+
+class CameraDriver(ABC):
+    """Interface for camera backends.
+
+    A driver is responsible for listing, opening, closing, and grabbing
+    frames from a specific camera subsystem (e.g. V4L2, USB, RTSP).
+    The driver returns raw numpy arrays; encoding/scaling is handled
+    by the observer.
+    """
+
+    driver_name: str = ""
+
+    @abstractmethod
+    def list_cameras(self) -> list[tuple[int, str]]:
+        """List available cameras.
+
+        Returns:
+            List of (camera_id, description) tuples.
+        """
+
+    @abstractmethod
+    def open(self, camera_id: int) -> bool:
+        """Open a camera for capturing.
+
+        Args:
+            camera_id: The camera ID from ``list_cameras``.
+
+        Returns:
+            True if the camera was opened successfully.
+        """
+
+    @abstractmethod
+    def close(self) -> None:
+        """Close the currently open camera."""
+
+    @abstractmethod
+    def grab_frame(self) -> tuple[bool, np.ndarray, tuple[int, int]]:
+        """Grab a single raw frame.
+
+        Returns:
+            Tuple of (success, numpy array, (width, height)).
+        """

peteos-0.0.2/peteos/agentic_objects/camera_driver/cv2_camera_driver.py

@@ -0,0 +1,53 @@
+"""CV2CameraDriver - portable V4L2 camera driver via OpenCV.
+
+Unlike OpenCVCameraDriver, this driver does not shell out to
+v4l2-ctl. It simply tests indices 0-9 with OpenCV, making it
+portable across Linux, Windows, and macOS.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import cv2
+import numpy as np
+
+from peteos.agentic_objects.camera_driver import CameraDriver
+
+if TYPE_CHECKING:
+    pass
+
+
+class CV2CameraDriver(CameraDriver):
+    """Portable V4L2 driver backed by OpenCV only."""
+
+    driver_name = "opencv-cv2"
+
+    def list_cameras(self) -> list[tuple[int, str]]:
+        cameras: list[tuple[int, str]] = []
+        for i in range(10):
+            cap = cv2.VideoCapture(i)
+            if cap.isOpened():
+                cameras.append((i, ""))
+                cap.release()
+        return cameras
+
+    def open(self, camera_id: int) -> bool:
+        cap = cv2.VideoCapture(camera_id)
+        if not cap.isOpened():
+            return False
+        self._cap = cap
+        return True
+
+    def close(self) -> None:
+        if hasattr(self, "_cap"):
+            self._cap.release()
+            del self._cap
+
+    def grab_frame(self) -> tuple[bool, np.ndarray, tuple[int, int]]:
+        if not hasattr(self, "_cap"):
+            return False, np.empty((0, 0, 3)), (0, 0)
+        ret, frame = self._cap.read()
+        if not ret or frame is None:
+            return False, np.empty((0, 0, 3)), (0, 0)
+        return True, frame, (frame.shape[1], frame.shape[0])