parapet 0.1.0__tar.gz

parapet-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Rust
+parapet/target/
+
+# Python
+__pycache__/
+*.egg-info/
+.venv/
+*.pyc
+
+# IDE
+.idea/
+
+# Claude Code
+.claude/
+
+# Internal docs
+implement/
+
+# Eval datasets (reproducible via scripts/)
+schema/eval/opensource_*.yaml
+schema/eval/multiturn_*.yaml
+schema/eval/out_of_scope/
+
+# LaTeX build artifacts
+paper/*.aux
+paper/*.log
+paper/*.out
+
+# OS
+.DS_Store
+Thumbs.db
+
+NUL
+nul

parapet-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: parapet
+Version: 0.1.0
+Summary: Python SDK for Parapet LLM proxy firewall
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.34; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'

parapet-0.1.0/parapet/__init__.py

@@ -0,0 +1,131 @@
+# Copyright 2026 The Parapet Project
+# SPDX-License-Identifier: Apache-2.0
+
+# Parapet Python SDK — defined in M1.11
+#
+# Public API:
+#   parapet.init(config_path)  — validate config, start engine sidecar, patch httpx
+#   parapet.session(...)       — context manager that sets W3C Baggage for the scope
+#   parapet.untrusted(content) — mark a string as untrusted content
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+from typing import Generator
+
+from parapet.header import build_baggage_header
+from parapet.sidecar import EngineState, start_engine
+from parapet.transport import patch_httpx
+from parapet.trust import _ensure_registry
+from typing import Iterable
+
+__all__ = ["init", "session", "untrusted"]
+
+logger = logging.getLogger("parapet")
+
+_DEFAULT_PORT = 9800
+
+# Module-level engine state — single instance shared across init/session.
+_engine_state = EngineState()
+
+# Active baggage for the current context (set inside session(), cleared on exit).
+_active_baggage: ContextVar[str | None] = ContextVar(
+    "parapet_active_baggage", default=None
+)
+
+
+class SessionContext:
+    """Holds the baggage string for the duration of a session scope."""
+
+    __slots__ = ("baggage",)
+
+    def __init__(self, baggage: str) -> None:
+        self.baggage = baggage
+
+
+def init(
+    config_path: str,
+    *,
+    port: int = _DEFAULT_PORT,
+    extra_hosts: Iterable[str] | None = None,
+) -> None:
+    """Initialize the parapet SDK.
+
+    Validates that *config_path* exists, starts the engine sidecar (if not
+    already running), and patches httpx to route LLM requests through the
+    engine.
+
+    Args:
+        config_path: Path to the parapet.yaml configuration file.
+        port: Port for the engine to listen on (default 9800).
+        extra_hosts: Additional LLM API hosts to intercept beyond the
+            built-in defaults (e.g., ``["api.together.xyz"]``).
+
+    Raises:
+        FileNotFoundError: If *config_path* does not exist.
+    """
+    path = Path(config_path)
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Config file not found: {config_path}"
+        )
+
+    hosts = frozenset(extra_hosts) if extra_hosts else None
+    start_engine(config_path=config_path, port=port, state=_engine_state)
+    patch_httpx(port=port, extra_hosts=hosts)
+
+
+@contextmanager
+def session(
+    *,
+    user_id: str | None = None,
+    role: str | None = None,
+) -> Generator[SessionContext, None, None]:
+    """Set W3C Baggage headers for the duration of this scope.
+
+    Must be called after ``init()``.
+
+    Args:
+        user_id: Optional user identifier to include in baggage.
+        role: Optional role string to include in baggage.
+
+    Yields:
+        A ``SessionContext`` with the computed baggage string.
+
+    Raises:
+        RuntimeError: If ``init()`` has not been called.
+    """
+    if not _engine_state.initialized:
+        raise RuntimeError(
+            "parapet.session() called before init(). Call parapet.init() first."
+        )
+
+    baggage = build_baggage_header(user_id=user_id, role=role)
+    token = _active_baggage.set(baggage)
+    try:
+        yield SessionContext(baggage=baggage)
+    finally:
+        _active_baggage.reset(token)
+
+
+def untrusted(content: str, source: str = "unknown") -> str:
+    """Mark a string as untrusted content.
+
+    Registers the string in the per-context trust registry so the SDK
+    can locate it in serialized requests and emit byte-range trust spans.
+
+    The string is returned unchanged for inline use::
+
+        prompt = f"Context: {parapet.untrusted(rag_snippet, source='rag')}"
+
+    Args:
+        content: The untrusted content string.
+        source: Provenance label (e.g., "rag", "user_input", "web_search").
+
+    Returns:
+        The content string, unchanged.
+    """
+    registry = _ensure_registry()
+    return registry.register(content, source=source)

parapet-0.1.0/parapet/header.py

@@ -0,0 +1,85 @@
+# Copyright 2026 The Parapet Project
+# SPDX-License-Identifier: Apache-2.0
+
+"""Header serialization for Parapet SDK.
+
+Includes:
+- W3C Baggage header (``baggage: key1=value1,key2=value2``)
+- X-Guard-Trust header (``inline:<base64-encoded JSON>``)
+
+Values are percent-encoded to handle special characters safely.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from urllib.parse import quote
+
+__all__ = ["build_baggage_header", "build_trust_header"]
+
+MAX_TRUST_HEADER_BYTES = 4096  # 4KB inline limit
+
+# Characters that must be percent-encoded in baggage values.
+# W3C Baggage uses a subset of RFC 3986 — commas, semicolons, equals,
+# and spaces are delimiters and must not appear unescaped in values.
+_SAFE_CHARS = ""  # encode everything except unreserved chars
+
+
+def _encode_value(value: str) -> str:
+    """Percent-encode a baggage value per W3C Baggage spec."""
+    return quote(value, safe=_SAFE_CHARS)
+
+
+def build_baggage_header(
+    *,
+    user_id: str | None = None,
+    role: str | None = None,
+) -> str:
+    """Build a W3C Baggage header value from optional fields.
+
+    Args:
+        user_id: Optional user identifier.
+        role: Optional role string.
+
+    Returns:
+        Baggage header value string (e.g. ``user_id=u_1,role=admin``).
+        Returns empty string when no fields are provided.
+    """
+    parts: list[str] = []
+
+    if user_id is not None:
+        parts.append(f"user_id={_encode_value(user_id)}")
+
+    if role is not None:
+        parts.append(f"role={_encode_value(role)}")
+
+    return ",".join(parts)
+
+
+def build_trust_header(spans: list) -> str | None:
+    """Serialize trust spans as X-Guard-Trust header value.
+
+    Format: ``inline:<base64-encoded JSON>``
+    JSON schema: ``[{"s": start, "e": end, "src": source}, ...]``
+
+    Returns None if no spans or if encoded value exceeds 4KB limit.
+    Compact keys (s/e/src) to minimize header size.
+    """
+    if not spans:
+        return None
+
+    compact = [{"s": s.start, "e": s.end, "src": s.source} for s in spans]
+    payload = json.dumps(compact, separators=(",", ":")).encode("utf-8")
+
+    if len(payload) > MAX_TRUST_HEADER_BYTES:
+        logging.getLogger("parapet.header").warning(
+            "X-Guard-Trust header exceeds %d byte limit (%d spans, %d bytes); dropping",
+            MAX_TRUST_HEADER_BYTES,
+            len(spans),
+            len(payload),
+        )
+        return None
+
+    encoded = base64.b64encode(payload).decode("ascii")
+    return f"inline:{encoded}"

parapet-0.1.0/parapet/sidecar.py

@@ -0,0 +1,212 @@
+# Copyright 2026 The Parapet Project
+# SPDX-License-Identifier: Apache-2.0
+
+"""Engine process lifecycle management.
+
+Manages spawning the Rust engine as a subprocess, PID file tracking,
+stale PID cleanup, heartbeat watchdog, and clean shutdown via atexit.
+"""
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import IO
+
+import httpx
+
+__all__ = ["EngineState", "start_engine", "stop_engine"]
+
+logger = logging.getLogger("parapet.sidecar")
+
+_HEARTBEAT_INTERVAL_SECONDS = 10
+_PARAPET_DIR = Path.home() / ".parapet"
+_DEFAULT_PID_PATH = _PARAPET_DIR / "engine.pid"
+_DEFAULT_LOG_PATH = _PARAPET_DIR / "engine.log"
+
+
+@dataclass
+class EngineState:
+    """Holds the state of the running engine sidecar.
+
+    This is not global mutable state scattered across the module --
+    it is a single, explicit object passed to functions that need it.
+    """
+
+    process: subprocess.Popen | None = None
+    initialized: bool = False
+    port: int | None = None
+    _log_file: IO[bytes] | None = field(default=None, repr=False)
+    _heartbeat_thread: threading.Thread | None = field(
+        default=None, repr=False
+    )
+    _heartbeat_stop: threading.Event = field(
+        default_factory=threading.Event, repr=False
+    )
+
+
+def _is_process_alive(pid: int) -> bool:
+    """Check whether a process with the given PID is still running."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, ProcessLookupError):
+        return False
+
+
+def _start_heartbeat(state: EngineState, port: int) -> None:
+    """Start a daemon thread that pings the engine heartbeat endpoint."""
+
+    def _heartbeat_loop() -> None:
+        while not state._heartbeat_stop.is_set():
+            try:
+                httpx.get(
+                    f"http://127.0.0.1:{port}/v1/heartbeat",
+                    timeout=5.0,
+                )
+            except Exception:
+                logger.debug("Heartbeat send failed (engine may be starting)")
+            state._heartbeat_stop.wait(_HEARTBEAT_INTERVAL_SECONDS)
+
+    thread = threading.Thread(
+        target=_heartbeat_loop,
+        name="parapet-heartbeat",
+        daemon=True,
+    )
+    thread.start()
+    state._heartbeat_thread = thread
+
+
+def start_engine(
+    config_path: str,
+    port: int,
+    *,
+    state: EngineState,
+    pid_path: Path = _DEFAULT_PID_PATH,
+    log_path: Path = _DEFAULT_LOG_PATH,
+) -> None:
+    """Spawn the Rust engine as a subprocess.
+
+    Idempotent: if the engine is already running (tracked via *state*),
+    this is a no-op. If a PID file exists from a previous run but the
+    process is dead, the stale PID is cleaned up and a fresh engine
+    is started.
+
+    Args:
+        config_path: Path to the parapet.yaml configuration file.
+        port: Port for the engine to listen on.
+        state: Mutable engine state object.
+        pid_path: Path to write the engine PID file.
+        log_path: Path to write the engine log file.
+    """
+    # Already running in this process -- reuse.
+    if state.initialized and state.process is not None:
+        if state.process.poll() is None:
+            logger.debug("Engine already running (pid=%d), reusing", state.process.pid)
+            return
+        # Process died unexpectedly; fall through to restart.
+        logger.warning("Engine process died unexpectedly, restarting")
+        state.process = None
+        state.initialized = False
+
+    # Check for stale PID file from a previous run.
+    if pid_path.exists():
+        try:
+            old_pid = int(pid_path.read_text().strip())
+        except (ValueError, OSError):
+            old_pid = None
+
+        if old_pid is not None and _is_process_alive(old_pid):
+            # Another engine is still running -- reuse it.
+            logger.info(
+                "Reusing existing engine from PID file (pid=%d)", old_pid
+            )
+            state.initialized = True
+            state.port = port
+            _start_heartbeat(state, port)
+            return
+
+        # Stale PID file -- clean up.
+        logger.info("Cleaning up stale PID file (pid=%s)", old_pid)
+        pid_path.unlink(missing_ok=True)
+
+    # Ensure the parapet directory exists.
+    pid_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Open log file for engine stdout/stderr.
+    log_file: IO[bytes] = open(log_path, "ab")
+
+    # Spawn the engine process.
+    proc = subprocess.Popen(
+        [
+            "parapet-engine",
+            "--config",
+            config_path,
+            "--port",
+            str(port),
+        ],
+        stdout=log_file,
+        stderr=log_file,
+    )
+
+    state.process = proc
+    state.initialized = True
+    state.port = port
+    state._log_file = log_file
+
+    # Write PID file.
+    pid_path.write_text(str(proc.pid))
+    logger.info("Engine started (pid=%d, port=%d)", proc.pid, port)
+
+    # Start heartbeat watchdog.
+    _start_heartbeat(state, port)
+
+    # Register atexit handler for clean shutdown.
+    atexit.register(stop_engine, state=state, pid_path=pid_path)
+
+
+def stop_engine(
+    *,
+    state: EngineState,
+    pid_path: Path = _DEFAULT_PID_PATH,
+) -> None:
+    """Terminate the engine subprocess and clean up.
+
+    Args:
+        state: The engine state to clean up.
+        pid_path: Path to the PID file to remove.
+    """
+    # Signal heartbeat thread to stop.
+    state._heartbeat_stop.set()
+
+    if state.process is not None:
+        logger.info("Stopping engine (pid=%d)", state.process.pid)
+        try:
+            state.process.terminate()
+            state.process.wait(timeout=5)
+        except Exception:
+            logger.warning("Engine did not stop gracefully, killing")
+            try:
+                state.process.kill()
+            except Exception:
+                pass
+
+    # Close the log file handle.
+    if state._log_file is not None:
+        try:
+            state._log_file.close()
+        except Exception:
+            pass
+        state._log_file = None
+
+    state.process = None
+    state.initialized = False
+
+    if pid_path.exists():
+        pid_path.unlink(missing_ok=True)
+        logger.debug("Removed PID file %s", pid_path)