cmdop 0.1.15__py3-none-any.whl → 0.1.16__py3-none-any.whl

cmdop/__init__.py

@@ -116,14 +116,15 @@ from cmdop.discovery import (
     get_online_agents,
     list_agents,
 )
-from cmdop.helpers import (
-    JSONFormatter,
-    flatten_json,
-    json_to_yaml,
-    json_to_text,
+from cmdop.helpers import json_to_toon, JsonCleaner
+from cmdop.logging import (
+    get_logger,
+    setup_logging,
+    find_project_root,
+    get_log_dir,
 )
 
-__version__ = "0.1.15"
+__version__ = "0.1.16"
 
 __all__ = [
     # Version
@@ -217,8 +218,11 @@ __all__ = [
     "BrowserNavigationError",
     "BrowserElementNotFoundError",
     # Helpers
-    "JSONFormatter",
-    "flatten_json",
-    "json_to_yaml",
-    "json_to_text",
+    "json_to_toon",
+    "JsonCleaner",
+    # Logging
+    "get_logger",
+    "setup_logging",
+    "find_project_root",
+    "get_log_dir",
 ]

cmdop/helpers/__init__.py

@@ -1,15 +1,9 @@
 """CMDOP SDK helpers."""
 
-from cmdop.helpers.formatting import (
-    JSONFormatter,
-    flatten_json,
-    json_to_yaml,
-    json_to_text,
-)
+from cmdop.helpers.formatting import json_to_toon
+from cmdop.helpers.cleaner import JsonCleaner
 
 __all__ = [
-    "JSONFormatter",
-    "flatten_json",
-    "json_to_yaml",
-    "json_to_text",
+    "json_to_toon",
+    "JsonCleaner",
 ]

cmdop/helpers/cleaner.py

@@ -0,0 +1,53 @@
+"""JSON cleaning utilities for LLM consumption."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from toon_python import encode as toon_encode
+
+
+class JsonCleaner:
+    """
+    Clean JSON and convert to TOON format for LLM.
+
+    Usage:
+        cleaner = JsonCleaner(noise_keys={"Photos", "images"})
+        toon_text = cleaner.to_toon(data)
+    """
+
+    DEFAULT_NOISE_KEYS = frozenset({
+        "statusItemTypes",
+        "attributes",
+        "ordering",
+        "updatedDate",
+    })
+
+    def __init__(self, noise_keys: set[str] | None = None):
+        self.noise_keys = self.DEFAULT_NOISE_KEYS | (noise_keys or set())
+
+    def compact(self, data: Any) -> Any:
+        """Remove nulls, empty values, noise keys. Simplify {code,title}->title."""
+        def _process(obj: Any) -> Any:
+            if isinstance(obj, dict):
+                # Simplify {code, title} pattern
+                keys = set(obj.keys())
+                if keys <= {"code", "title", "description"} and "title" in keys:
+                    return obj.get("title") or obj.get("code")
+                # Clean dict
+                result = {}
+                for k, v in obj.items():
+                    if k in self.noise_keys:
+                        continue
+                    cleaned = _process(v)
+                    if cleaned is not None and cleaned != "" and cleaned != [] and cleaned != {}:
+                        result[k] = cleaned
+                return result
+            elif isinstance(obj, list):
+                return [_process(item) for item in obj if _process(item) not in (None, "", [], {})]
+            return obj
+        return _process(data)
+
+    def to_toon(self, data: Any) -> str:
+        """Compact and convert to TOON format."""
+        return toon_encode(self.compact(data))

cmdop/helpers/formatting.py

@@ -1,70 +1,15 @@
 """JSON formatting utilities."""
 
-import json
+from __future__ import annotations
 
-import yaml
-from flatten_json import flatten
+from toon_python import encode as toon_encode
 
 
-class JSONFormatter:
+def json_to_toon(data: dict | list) -> str:
     """
-    JSON to various formats converter.
+    Convert JSON to TOON format (saves 30-50% tokens).
 
-    Usage:
-        fmt = JSONFormatter()
-
-        flat = fmt.flatten({"a": {"b": 1}})  # {"a.b": 1}
-        yaml_str = fmt.to_yaml(data)
-        text = fmt.to_text(data)  # key: value lines
+    Example:
+        {"name": "Alice", "age": 25} → "name: Alice\\nage: 25"
     """
-
-    def __init__(self, separator: str = "."):
-        self.separator = separator
-
-    def flatten(self, data: dict | list) -> dict:
-        """
-        Flatten nested JSON to flat dict with dot notation.
-
-        {"a": {"b": 1}} -> {"a.b": 1}
-        """
-        if isinstance(data, list):
-            data = {"items": data}
-        return flatten(data, self.separator)
-
-    def to_yaml(self, data: dict | list) -> str:
-        """Convert to YAML string."""
-        return yaml.dump(
-            data,
-            allow_unicode=True,
-            default_flow_style=False,
-            sort_keys=False,
-            indent=2,
-        )
-
-    def to_text(self, data: dict | list) -> str:
-        """Convert to flat text (key: value per line)."""
-        flat = self.flatten(data)
-        lines = []
-        for key, value in flat.items():
-            if isinstance(value, str):
-                val_str = value
-            elif value is None:
-                val_str = "null"
-            elif isinstance(value, bool):
-                val_str = "true" if value else "false"
-            else:
-                val_str = str(value)
-            lines.append(f"{key}: {val_str}")
-        return "\n".join(lines)
-
-    def to_json(self, data: dict | list, indent: int = 2) -> str:
-        """Convert to formatted JSON string."""
-        return json.dumps(data, indent=indent, ensure_ascii=False)
-
-
-# Default instance
-_fmt = JSONFormatter()
-
-flatten_json = _fmt.flatten
-json_to_yaml = _fmt.to_yaml
-json_to_text = _fmt.to_text
+    return toon_encode(data)

cmdop/logging.py

@@ -0,0 +1,252 @@
+"""
+Universal Python logger with Rich console output and file persistence.
+
+Auto-detects project root by looking for Python project markers:
+- pyproject.toml
+- setup.py
+- requirements.txt
+- .git
+
+Usage:
+    from cmdop.logging import get_logger
+
+    log = get_logger(__name__)
+    log.info("Hello world")
+    log.error("Something failed", exc_info=True)
+
+    # Or with custom settings
+    log = get_logger(__name__, level="DEBUG", log_to_file=True)
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Literal
+
+# Try to import Rich, fallback to standard logging if not available
+try:
+    from rich.console import Console
+    from rich.logging import RichHandler
+    from rich.traceback import install as install_rich_traceback
+
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+
+__all__ = [
+    "get_logger",
+    "setup_logging",
+    "find_project_root",
+    "get_log_dir",
+]
+
+# Project markers to search for (in priority order)
+PROJECT_MARKERS = [
+    "pyproject.toml",
+    "setup.py",
+    "setup.cfg",
+    "requirements.txt",
+    "Pipfile",
+    ".git",
+]
+
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+# Cache for project root
+_project_root_cache: Path | None = None
+_logging_configured: bool = False
+
+
+def find_project_root(start_path: Path | None = None) -> Path | None:
+    """
+    Find Python project root by searching for project markers.
+
+    Searches upward from start_path (default: cwd) looking for:
+    - pyproject.toml
+    - setup.py
+    - requirements.txt
+    - .git
+
+    Returns:
+        Path to project root, or None if not found
+    """
+    global _project_root_cache
+
+    if _project_root_cache is not None:
+        return _project_root_cache
+
+    if start_path is None:
+        start_path = Path.cwd()
+
+    path = start_path.resolve()
+
+    for current in [path] + list(path.parents):
+        for marker in PROJECT_MARKERS:
+            if (current / marker).exists():
+                _project_root_cache = current
+                return current
+
+    return None
+
+
+def get_log_dir(app_name: str = "app") -> Path:
+    """
+    Get log directory path.
+
+    Priority:
+    1. Project root / logs (if project root found)
+    2. ~/.local/logs/{app_name} (Linux/macOS)
+    3. Current working directory / logs
+
+    Creates directory if it doesn't exist.
+
+    Args:
+        app_name: Application name for fallback directory
+
+    Returns:
+        Path to log directory
+    """
+    # Try project root first
+    project_root = find_project_root()
+    if project_root:
+        log_dir = project_root / "logs"
+    else:
+        # Fallback to home directory
+        home = Path.home()
+        if sys.platform == "darwin":
+            log_dir = home / "Library" / "Logs" / app_name
+        elif sys.platform == "win32":
+            log_dir = home / "AppData" / "Local" / app_name / "logs"
+        else:  # Linux and others
+            log_dir = home / ".local" / "logs" / app_name
+
+    # Create directory if needed
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir
+
+
+def setup_logging(
+    level: LogLevel = "INFO",
+    log_to_file: bool = True,
+    log_to_console: bool = True,
+    app_name: str = "app",
+    rich_tracebacks: bool = True,
+) -> None:
+    """
+    Configure root logger with Rich console and file handlers.
+
+    Args:
+        level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        log_to_file: Whether to write logs to file
+        log_to_console: Whether to output to console
+        app_name: Application name for log file naming
+        rich_tracebacks: Install Rich traceback handler for exceptions
+    """
+    global _logging_configured
+
+    if _logging_configured:
+        return
+
+    root_logger = logging.getLogger()
+    root_logger.setLevel(getattr(logging, level))
+
+    # Clear existing handlers
+    root_logger.handlers.clear()
+
+    # Console handler with Rich (if available)
+    if log_to_console:
+        if RICH_AVAILABLE:
+            console = Console(stderr=True)
+            console_handler = RichHandler(
+                console=console,
+                show_time=True,
+                show_path=True,
+                rich_tracebacks=True,
+                tracebacks_show_locals=True,
+                markup=True,
+            )
+            console_handler.setFormatter(logging.Formatter("%(message)s"))
+        else:
+            console_handler = logging.StreamHandler(sys.stderr)
+            console_handler.setFormatter(
+                logging.Formatter(
+                    "%(asctime)s | %(levelname)-8s | %(name)s - %(message)s",
+                    datefmt="%H:%M:%S",
+                )
+            )
+        root_logger.addHandler(console_handler)
+
+    # File handler
+    if log_to_file:
+        log_dir = get_log_dir(app_name)
+        date_str = datetime.now().strftime("%Y-%m-%d")
+        log_file = log_dir / f"{app_name}_{date_str}.log"
+
+        file_handler = logging.FileHandler(log_file, encoding="utf-8")
+        file_handler.setFormatter(
+            logging.Formatter(
+                "%(asctime)s | %(levelname)-8s | %(name)s:%(lineno)d - %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        )
+        root_logger.addHandler(file_handler)
+
+    # Install Rich tracebacks globally
+    if rich_tracebacks and RICH_AVAILABLE:
+        install_rich_traceback(show_locals=True, suppress=[])
+
+    _logging_configured = True
+
+
+def get_logger(
+    name: str | None = None,
+    level: LogLevel | None = None,
+    log_to_file: bool = True,
+    app_name: str = "app",
+) -> logging.Logger:
+    """
+    Get a configured logger instance.
+
+    On first call, sets up the logging system with Rich console output
+    and file persistence.
+
+    Args:
+        name: Logger name (typically __name__)
+        level: Override log level (default: INFO)
+        log_to_file: Whether to write to log file
+        app_name: Application name for log file
+
+    Returns:
+        Configured logger instance
+
+    Example:
+        log = get_logger(__name__)
+        log.info("Starting process")
+        log.debug("Debug details: %s", data)
+        log.error("Failed!", exc_info=True)
+    """
+    # Setup logging system on first call
+    setup_logging(
+        level=level or "INFO",
+        log_to_file=log_to_file,
+        app_name=app_name,
+    )
+
+    logger = logging.getLogger(name)
+
+    # Override level if specified
+    if level:
+        logger.setLevel(getattr(logging, level))
+
+    return logger
+
+
+# Convenience aliases
+debug = lambda msg, *args, **kw: get_logger().debug(msg, *args, **kw)
+info = lambda msg, *args, **kw: get_logger().info(msg, *args, **kw)
+warning = lambda msg, *args, **kw: get_logger().warning(msg, *args, **kw)
+error = lambda msg, *args, **kw: get_logger().error(msg, *args, **kw)
+critical = lambda msg, *args, **kw: get_logger().critical(msg, *args, **kw)

cmdop/services/browser/__init__.py

@@ -1,17 +1,44 @@
-"""Browser service module."""
+"""Browser automation service.
+
+Structure:
+    browser/
+        models.py       - Data models (BrowserCookie, BrowserState)
+        js.py           - JavaScript code builders
+        base/           - Base classes (BaseSession, BaseServiceMixin)
+        sync/           - Sync implementation (BrowserSession, BrowserService)
+        aio/            - Async implementation (AsyncBrowserSession, AsyncBrowserService)
+
+Usage:
+    # Sync
+    with client.browser.create_session() as session:
+        session.navigate("https://example.com")
+        data = session.fetch_all(urls, headers={"Accept": "application/json"})
+
+    # Async
+    async with client.browser.create_session() as session:
+        await session.navigate("https://example.com")
+        data = await session.fetch_all(urls, headers={"Accept": "application/json"})
+"""
 
 from cmdop.services.browser.models import BrowserCookie, BrowserState, raise_browser_error
-from cmdop.services.browser.session import BrowserSession
-from cmdop.services.browser.service import BrowserService
-from cmdop.services.browser.async_session import AsyncBrowserSession
-from cmdop.services.browser.async_service import AsyncBrowserService
+
+# Sync
+from cmdop.services.browser.sync.session import BrowserSession
+from cmdop.services.browser.sync.service import BrowserService
+
+# Async
+from cmdop.services.browser.aio.session import AsyncBrowserSession
+from cmdop.services.browser.aio.service import AsyncBrowserService
 
 __all__ = [
+    # Models
     "BrowserCookie",
     "BrowserState",
+    "raise_browser_error",
+    # Sync
     "BrowserSession",
     "BrowserService",
+    # Async
     "AsyncBrowserSession",
     "AsyncBrowserService",
-    "raise_browser_error",
 ]

cmdop/services/browser/aio/__init__.py

@@ -0,0 +1,6 @@
+"""Asynchronous browser session and service."""
+
+from cmdop.services.browser.aio.session import AsyncBrowserSession
+from cmdop.services.browser.aio.service import AsyncBrowserService
+
+__all__ = ["AsyncBrowserSession", "AsyncBrowserService"]

cmdop/services/browser/{async_service.py → aio/service.py}

@@ -1,4 +1,4 @@
-"""Browser service (async)."""
+"""Asynchronous browser service."""
 
 from __future__ import annotations
 
@@ -6,17 +6,16 @@ import json
 from typing import TYPE_CHECKING, Any
 
 from cmdop.services.base import BaseService
+from cmdop.services.browser.base.service import BaseServiceMixin, cookie_to_pb, pb_to_cookie
 from cmdop.services.browser.models import BrowserCookie, BrowserState, raise_browser_error
-from cmdop.services.browser.async_session import AsyncBrowserSession
-from cmdop.services.browser._base import cookie_to_pb, pb_to_cookie
 
 if TYPE_CHECKING:
     from cmdop.transport.base import BaseTransport
 
 
-class AsyncBrowserService(BaseService):
+class AsyncBrowserService(BaseService, BaseServiceMixin):
     """
-    Async browser service.
+    Asynchronous browser service.
 
     Example:
         async with client.browser.create_session() as session:
@@ -36,6 +35,8 @@ class AsyncBrowserService(BaseService):
             self._stub = TerminalStreamingServiceStub(self._async_channel)
         return self._stub
 
+    # === Session Management ===
+
     async def create_session(
         self,
         start_url: str | None = None,
@@ -44,8 +45,9 @@ class AsyncBrowserService(BaseService):
         headless: bool = False,
         width: int = 1280,
         height: int = 800,
-    ) -> AsyncBrowserSession:
+    ) -> "AsyncBrowserSession":
         from cmdop._generated.rpc_messages.browser_pb2 import BrowserCreateSessionRequest
+        from cmdop.services.browser.aio.session import AsyncBrowserSession
 
         request = BrowserCreateSessionRequest(
             provider=provider,
@@ -71,6 +73,8 @@ class AsyncBrowserService(BaseService):
         if not response.success:
             raise RuntimeError(f"Failed to close browser session: {response.error}")
 
+    # === Navigation & Interaction ===
+
     async def navigate(self, session_id: str, url: str, timeout_ms: int = 30000) -> str:
         from cmdop._generated.rpc_messages.browser_pb2 import BrowserNavigateRequest
 
@@ -132,6 +136,8 @@ class AsyncBrowserService(BaseService):
 
         return response.found
 
+    # === Extraction ===
+
     async def extract(
         self, session_id: str, selector: str, attr: str | None = None, limit: int = 100
     ) -> list[str]:
@@ -194,6 +200,8 @@ class AsyncBrowserService(BaseService):
 
         return response.text
 
+    # === JavaScript ===
+
     async def execute_script(self, session_id: str, script: str) -> str:
         from cmdop._generated.rpc_messages.browser_pb2 import BrowserExecuteScriptRequest
 
@@ -209,6 +217,8 @@ class AsyncBrowserService(BaseService):
 
         return response.result
 
+    # === State & Cookies ===
+
     async def screenshot(self, session_id: str, full_page: bool = False) -> bytes:
         from cmdop._generated.rpc_messages.browser_pb2 import BrowserScreenshotRequest
 
@@ -265,6 +275,8 @@ class AsyncBrowserService(BaseService):
 
         return [pb_to_cookie(c) for c in response.cookies]
 
+    # === Parser helpers ===
+
     async def validate_selectors(
         self, session_id: str, item: str, fields: dict[str, str]
     ) -> dict: