orithos-prela 0.2.0__tar.gz

orithos_prela-0.2.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: orithos-prela
+Version: 0.2.0
+Summary: Fire-and-forget trace ingestion SDK for Orithos AI Agent Security
+Author-email: Orithos <dev@orithos.com>
+License: MIT
+Project-URL: Homepage, https://orithos.com
+Project-URL: Repository, https://github.com/nishkmg/TraceShield
+Project-URL: Documentation, https://github.com/nishkmg/TraceShield/tree/staging/prela-sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+
+# Prela SDK
+
+Fire-and-forget trace ingestion SDK for [TraceShield](https://traceshield.dev).
+
+## Installation
+
+```bash
+pip install prela
+```
+
+## Quick Start
+
+```python
+from prela import Prela
+
+prela = Prela(
+    api_key="ts_ingest_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    endpoint="https://api.traceshield.example.com",
+)
+
+# Manual trace
+prela.trace(
+    input="What is my account balance?",
+    output="I don't have access to account information.",
+)
+
+# OpenAI integration
+from prela.integrations.openai import PrelaOpenAI
+from openai import OpenAI
+
+client = PrelaOpenAI(OpenAI(), prela)
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+
+# Before process exit
+prela.shutdown()
+```
+
+## Design
+
+- **Fire-and-forget**: Never blocks the agent's response path
+- **Zero dependencies**: Only requires `httpx`
+- **Batching**: Buffers traces and sends every 500ms or 50 traces
+- **Resilient**: Drops traces on failure, logs warnings, never raises
+
+## Telemetry
+
+Send runtime events from your AI agent:
+
+```python
+import prela
+
+# Configure once
+prela.configure_telemetry(
+    api_key="ts-key-...",
+    org_id="org-...",
+    agent_id="agent-...",
+)
+
+# Track events throughout your code
+prela.track("llm_call", {"model": "gpt-4", "tokens": 150, "latency_ms": 1200})
+prela.track("policy_violation", {"rule": "R-001", "input": "..."}, severity="warning")
+prela.track("error", {"message": "Timeout connecting to API"}, severity="error")
+
+# Flush before exit
+prela.flush()
+```
+
+Events are batched (default: every 5s or 10 events) and sent to TraceShield's telemetry API.
+
+## License
+
+Private. All rights reserved.

orithos_prela-0.2.0/README.md

@@ -0,0 +1,75 @@
+# Prela SDK
+
+Fire-and-forget trace ingestion SDK for [TraceShield](https://traceshield.dev).
+
+## Installation
+
+```bash
+pip install prela
+```
+
+## Quick Start
+
+```python
+from prela import Prela
+
+prela = Prela(
+    api_key="ts_ingest_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    endpoint="https://api.traceshield.example.com",
+)
+
+# Manual trace
+prela.trace(
+    input="What is my account balance?",
+    output="I don't have access to account information.",
+)
+
+# OpenAI integration
+from prela.integrations.openai import PrelaOpenAI
+from openai import OpenAI
+
+client = PrelaOpenAI(OpenAI(), prela)
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+
+# Before process exit
+prela.shutdown()
+```
+
+## Design
+
+- **Fire-and-forget**: Never blocks the agent's response path
+- **Zero dependencies**: Only requires `httpx`
+- **Batching**: Buffers traces and sends every 500ms or 50 traces
+- **Resilient**: Drops traces on failure, logs warnings, never raises
+
+## Telemetry
+
+Send runtime events from your AI agent:
+
+```python
+import prela
+
+# Configure once
+prela.configure_telemetry(
+    api_key="ts-key-...",
+    org_id="org-...",
+    agent_id="agent-...",
+)
+
+# Track events throughout your code
+prela.track("llm_call", {"model": "gpt-4", "tokens": 150, "latency_ms": 1200})
+prela.track("policy_violation", {"rule": "R-001", "input": "..."}, severity="warning")
+prela.track("error", {"message": "Timeout connecting to API"}, severity="error")
+
+# Flush before exit
+prela.flush()
+```
+
+Events are batched (default: every 5s or 10 events) and sent to TraceShield's telemetry API.
+
+## License
+
+Private. All rights reserved.

orithos_prela-0.2.0/orithos_prela.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: orithos-prela
+Version: 0.2.0
+Summary: Fire-and-forget trace ingestion SDK for Orithos AI Agent Security
+Author-email: Orithos <dev@orithos.com>
+License: MIT
+Project-URL: Homepage, https://orithos.com
+Project-URL: Repository, https://github.com/nishkmg/TraceShield
+Project-URL: Documentation, https://github.com/nishkmg/TraceShield/tree/staging/prela-sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+
+# Prela SDK
+
+Fire-and-forget trace ingestion SDK for [TraceShield](https://traceshield.dev).
+
+## Installation
+
+```bash
+pip install prela
+```
+
+## Quick Start
+
+```python
+from prela import Prela
+
+prela = Prela(
+    api_key="ts_ingest_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    endpoint="https://api.traceshield.example.com",
+)
+
+# Manual trace
+prela.trace(
+    input="What is my account balance?",
+    output="I don't have access to account information.",
+)
+
+# OpenAI integration
+from prela.integrations.openai import PrelaOpenAI
+from openai import OpenAI
+
+client = PrelaOpenAI(OpenAI(), prela)
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+
+# Before process exit
+prela.shutdown()
+```
+
+## Design
+
+- **Fire-and-forget**: Never blocks the agent's response path
+- **Zero dependencies**: Only requires `httpx`
+- **Batching**: Buffers traces and sends every 500ms or 50 traces
+- **Resilient**: Drops traces on failure, logs warnings, never raises
+
+## Telemetry
+
+Send runtime events from your AI agent:
+
+```python
+import prela
+
+# Configure once
+prela.configure_telemetry(
+    api_key="ts-key-...",
+    org_id="org-...",
+    agent_id="agent-...",
+)
+
+# Track events throughout your code
+prela.track("llm_call", {"model": "gpt-4", "tokens": 150, "latency_ms": 1200})
+prela.track("policy_violation", {"rule": "R-001", "input": "..."}, severity="warning")
+prela.track("error", {"message": "Timeout connecting to API"}, severity="error")
+
+# Flush before exit
+prela.flush()
+```
+
+Events are batched (default: every 5s or 10 events) and sent to TraceShield's telemetry API.
+
+## License
+
+Private. All rights reserved.

orithos_prela-0.2.0/orithos_prela.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+README.md
+pyproject.toml
+orithos_prela.egg-info/PKG-INFO
+orithos_prela.egg-info/SOURCES.txt
+orithos_prela.egg-info/dependency_links.txt
+orithos_prela.egg-info/requires.txt
+orithos_prela.egg-info/top_level.txt
+prela/__init__.py
+prela/_logging.py
+prela/buffer.py
+prela/client.py
+prela/config.py
+prela/sampling.py
+prela/sender.py
+prela/telemetry.py
+prela/truncation.py
+prela/types.py
+prela/integrations/__init__.py
+prela/integrations/langchain.py
+prela/integrations/openai.py
+prela/tests/__init__.py
+prela/tests/test_client.py

orithos_prela-0.2.0/orithos_prela.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

orithos_prela-0.2.0/orithos_prela.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx>=0.27.0
+
+[dev]
+pytest>=8.0.0
+pytest-asyncio>=0.23.0
+ruff>=0.4.0

orithos_prela-0.2.0/orithos_prela.egg-info/top_level.txt

@@ -0,0 +1 @@
+prela

orithos_prela-0.2.0/prela/__init__.py

@@ -0,0 +1,8 @@
+"""Prela SDK v2 — Fire-and-forget trace ingestion for AI agent security testing."""
+
+from prela.client import Prela
+from prela.telemetry import RuntimeTelemetry, flush, track
+from prela.telemetry import configure as configure_telemetry
+
+__version__ = "2.0.0"
+__all__ = ["Prela", "RuntimeTelemetry", "configure_telemetry", "flush", "track"]

orithos_prela-0.2.0/prela/_logging.py

@@ -0,0 +1,15 @@
+"""Internal logging for Prela SDK.
+
+Only logs warnings and errors — never debug info.
+Never logs API keys, tokens, or trace content.
+"""
+
+import logging
+
+logger = logging.getLogger("prela")
+logger.setLevel(logging.WARNING)
+
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("prela: %(levelname)s - %(message)s"))
+    logger.addHandler(handler)

orithos_prela-0.2.0/prela/buffer.py

@@ -0,0 +1,52 @@
+"""Thread-safe in-memory trace buffer.
+
+Internal operations use threading.Lock() to protect the deque.
+Required because:
+- The main thread (agent code) calls prela.trace() → writes to buffer
+- The background sender thread reads and clears the buffer
+"""
+
+import threading
+from collections import deque
+from typing import Any
+
+
+class TraceBuffer:
+    """Thread-safe buffer for traces awaiting delivery."""
+
+    def __init__(self, max_size: int = 500):
+        self._buffer: deque = deque(maxlen=max_size)
+        self._lock = threading.Lock()
+        self._dropped = 0
+
+    def add(self, trace: dict[str, Any]) -> bool:
+        """Add a trace to the buffer. Returns False if buffer was full."""
+        with self._lock:
+            max_len = self._buffer.maxlen
+            if max_len is not None and len(self._buffer) >= max_len:
+                self._dropped += 1
+                return False
+            self._buffer.append(trace)
+            return True
+
+    def drain(self) -> list[dict[str, Any]]:
+        """Atomically drain all buffered traces."""
+        with self._lock:
+            items = list(self._buffer)
+            self._buffer.clear()
+            return items
+
+    @property
+    def size(self) -> int:
+        with self._lock:
+            return len(self._buffer)
+
+    @property
+    def is_empty(self) -> bool:
+        with self._lock:
+            return len(self._buffer) == 0
+
+    @property
+    def dropped_count(self) -> int:
+        with self._lock:
+            return self._dropped

orithos_prela-0.2.0/prela/client.py

@@ -0,0 +1,141 @@
+"""Prela SDK v2 — Fire-and-forget trace ingestion for AI agents.
+
+Usage:
+    from prela import Prela
+    prela = Prela(api_key="ts_ingest_xxx", traceshield_url="https://api.example.com")
+    prela.trace(input="Hello", output="Hi there!")
+    prela.shutdown()  # call before process exit (atexit registered automatically)
+"""
+
+import atexit
+import threading
+import time
+import uuid
+from typing import Any
+
+from prela._logging import logger
+from prela.buffer import TraceBuffer
+from prela.config import PrelaConfig
+from prela.sampling import should_sample
+from prela.truncation import truncate_trace
+
+
+class Prela:
+    """Main SDK class for trace ingestion.
+
+    Thread-safe. Safe for use in multi-threaded and async contexts.
+    Registers an atexit handler automatically to flush remaining traces.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        traceshield_url: str = "https://api.traceshield.dev",
+        **kwargs: Any,
+    ):
+        self._config = PrelaConfig(
+            api_key=api_key,
+            traceshield_url=traceshield_url,
+            **kwargs,
+        )
+        self._buffer = TraceBuffer(max_size=self._config.max_buffer)
+        self._lock = threading.Lock()
+        self._flush_thread = threading.Thread(
+            target=self._flush_loop, daemon=True, name="prela-flush"
+        )
+        self._flush_thread.start()
+
+        # Register atexit handler
+        atexit.register(self._atexit_flush)
+
+        if not self._config.enabled:
+            logger.info("Prela tracing is disabled")
+
+    def trace(
+        self,
+        input: str,
+        output: str,
+        metadata: dict[str, Any] | None = None,
+        tags: list | None = None,
+        conversation_history: list | None = None,
+        tool_calls: list | None = None,
+    ) -> str:
+        """Record a trace. Returns trace_id (UUID4).
+
+        Thread-safe. Safe to call from sync or async code.
+        """
+        if not self._config.enabled:
+            return ""
+
+        # Sampling check
+        if not should_sample(input, self._config.sample_rate):
+            return ""
+
+        trace_id = str(uuid.uuid4())
+        trace: dict[str, Any] = {
+            "trace_id": trace_id,
+            "agent_id": self._config.agent_id,
+            "input": input,
+            "output": output,
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        }
+
+        if self._config.pii_redact:
+            trace["input"] = self._config.pii_redact(trace["input"])
+            trace["output"] = self._config.pii_redact(trace["output"])
+
+        if self._config.include_conversation and conversation_history:
+            trace["conversation_history"] = conversation_history
+            if self._config.pii_redact:
+                for msg in trace["conversation_history"]:
+                    if "content" in msg:
+                        msg["content"] = self._config.pii_redact(msg["content"])
+
+        if self._config.include_tool_calls and tool_calls:
+            trace["tool_calls"] = tool_calls
+
+        if self._config.include_metadata:
+            meta = metadata or {}
+            meta["sampled"] = True
+            trace["metadata"] = meta
+
+        if tags:
+            trace["tags"] = tags
+
+        # Truncate if needed
+        trace = truncate_trace(trace, self._config.max_trace_size_bytes)
+
+        added = self._buffer.add(trace)
+        if not added and self._config.on_buffer_full:
+            self._config.on_buffer_full()
+
+        return trace_id
+
+    def flush(self) -> None:
+        """Flush all buffered traces immediately (blocking)."""
+        # Implemented in the background thread via _flush_loop
+        # This method just waits for the next flush cycle
+        pass
+
+    def shutdown(self, timeout: float = 5.0) -> None:
+        """Flush remaining traces and stop background thread."""
+        self._config.enabled = False
+        # The flush thread will drain and exit on next cycle
+        self._flush_thread.join(timeout=timeout)
+
+    def _flush_loop(self) -> None:
+        """Background thread: flushes buffer every flush_interval."""
+        # TODO: Import and use sender here once async integration is set up
+        # For now, this is a placeholder that drains the buffer periodically
+        while self._config.enabled:
+            time.sleep(self._config.flush_interval)
+            traces = self._buffer.drain()
+            if traces:
+                logger.debug(f"Flushing {len(traces)} traces (sender not yet implemented)")
+
+    def _atexit_flush(self) -> None:
+        """Called on process exit — flushes with 5s timeout."""
+        self._config.enabled = False
+        traces = self._buffer.drain()
+        if traces:
+            logger.info(f"atexit: flushing {len(traces)} remaining traces")

orithos_prela-0.2.0/prela/config.py

@@ -0,0 +1,58 @@
+"""Configuration validation and defaults for Prela SDK v2."""
+
+import warnings
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+
+@dataclass
+class PrelaConfig:
+    """SDK configuration with validation."""
+
+    api_key: str
+    traceshield_url: str = "https://api.traceshield.dev"
+    agent_id: str = ""
+    batch_size: int = 50
+    flush_interval: float = 0.5
+    max_buffer: int = 500
+    max_trace_size_bytes: int = 512_000  # 512KB
+    timeout: float = 10.0
+    include_conversation: bool = True
+    include_tool_calls: bool = True
+    include_metadata: bool = True
+    sample_rate: float = 1.0
+    pii_redact: Callable[[str], str] | None = None
+    on_error: Callable[[Exception], None] | None = None
+    on_buffer_full: Callable[[], None] | None = None
+    enabled: bool = True
+
+    # Backward compatibility — v1 used 'endpoint'
+    endpoint: str | None = field(default=None, repr=False)
+
+    def __post_init__(self):
+        if not self.api_key.startswith("ts_ingest_"):
+            raise ValueError("API key must start with 'ts_ingest_'")
+
+        # v2: 'endpoint' renamed to 'traceshield_url'
+        if self.endpoint is not None:
+            warnings.warn(
+                "The 'endpoint' parameter is deprecated. Use 'traceshield_url' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if self.traceshield_url == "https://api.traceshield.dev":
+                self.traceshield_url = self.endpoint
+        else:
+            self.endpoint = self.traceshield_url
+
+        if not self.traceshield_url.startswith("https://"):
+            raise ValueError("traceshield_url must use HTTPS")
+
+        if self.batch_size < 1 or self.batch_size > 100:
+            raise ValueError("batch_size must be between 1 and 100")
+
+        if not (0.0 <= self.sample_rate <= 1.0):
+            raise ValueError("sample_rate must be between 0.0 and 1.0")
+
+        if self.max_trace_size_bytes < 1024:
+            raise ValueError("max_trace_size_bytes must be at least 1024")

orithos_prela-0.2.0/prela/integrations/__init__.py

@@ -0,0 +1 @@
+# Integrations

orithos_prela-0.2.0/prela/integrations/langchain.py

@@ -0,0 +1,17 @@
+"""LangChain callback handler for automatic trace capture.
+
+Usage:
+    from prela.integrations.langchain import PrelaCallback
+
+    callback = PrelaCallback(prela=prela)
+    chain = LLMChain(llm=llm, prompt=prompt, callbacks=[callback])
+"""
+
+from prela.client import Prela
+
+
+class PrelaCallback:
+    """LangChain callback handler that captures traces."""
+
+    def __init__(self, prela: Prela):
+        self._prela = prela

orithos_prela-0.2.0/prela/integrations/openai.py

@@ -0,0 +1,30 @@
+"""OpenAI client wrapper for automatic trace capture.
+
+Usage:
+    from prela.integrations.openai import PrelaOpenAI
+    from openai import OpenAI
+
+    prela = Prela(api_key="ts_ingest_xxx")
+    client = PrelaOpenAI(OpenAI(), prela)
+
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "Hello"}],
+    )
+    # Trace is automatically sent to Orithos
+"""
+
+from typing import Any
+
+from prela.client import Prela
+
+
+class PrelaOpenAI:
+    """Wraps OpenAI client to auto-capture traces."""
+
+    def __init__(self, openai_client: Any, prela: Prela):
+        self._client = openai_client
+        self._prela = prela
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)

orithos_prela-0.2.0/prela/sampling.py

@@ -0,0 +1,30 @@
+"""Deterministic sampling by input hash.
+
+Sampling is deterministic — same input always makes the same
+sample/skip decision. This ensures test results are reproducible.
+"""
+
+import hashlib
+
+
+def should_sample(input_text: str, sample_rate: float) -> bool:
+    """Determine whether to sample this trace.
+
+    Args:
+        input_text: The trace input text.
+        sample_rate: Float between 0.0 and 1.0.
+
+    Returns:
+        True if the trace should be sent, False if it should be dropped.
+    """
+    if sample_rate >= 1.0:
+        return True
+    if sample_rate <= 0.0:
+        return False
+
+    # Hash the input to get a deterministic value between 0 and 1
+    hash_hex = hashlib.sha256(input_text.encode("utf-8")).hexdigest()
+    hash_int = int(hash_hex[:8], 16)  # First 8 hex chars = 32 bits
+    normalized = hash_int / 0xFFFFFFFF
+
+    return normalized < sample_rate

orithos_prela-0.2.0/prela/sender.py

@@ -0,0 +1,116 @@
+"""Background HTTP sender with retry logic and 401 recovery.
+
+Sends buffered traces to Orithos API. Never raises —
+logs warnings on failure and drops traces.
+
+v2: 401 no longer stops permanently. Uses graduated escalation:
+60s pause → retry → 300s pause → retry → 3rd failure = permanent stop.
+"""
+
+import asyncio
+import logging
+
+import httpx
+
+logger = logging.getLogger("prela.sender")
+
+
+class TraceSender:
+    """Sends traces to Orithos API in the background."""
+
+    def __init__(
+        self,
+        traceshield_url: str,
+        api_key: str,
+        timeout: float = 10.0,
+        on_error=None,
+    ):
+        self._traceshield_url = traceshield_url
+        self._api_key = api_key
+        self._timeout = timeout
+        self._client = httpx.AsyncClient(timeout=timeout)
+        self._stopped = False
+        self._on_error = on_error
+
+        # v2: 401 recovery state
+        self._consecutive_401s = 0
+        self._pause_until = 0.0  # Unix timestamp
+
+    async def send_batch(self, traces: list[dict]) -> None:
+        """Send a batch of traces. Fire-and-forget — never raises."""
+        if not traces or self._stopped:
+            return
+
+        try:
+            response = await self._client.post(
+                f"{self._traceshield_url}/v1/traces/batch",
+                json={"traces": traces},
+                headers={
+                    "Authorization": f"Bearer {self._api_key}",
+                    "X-Prela-SDK-Version": "2.0.0",
+                    "X-Prela-SDK-Language": "python",
+                },
+            )
+
+            if response.status_code == 202:
+                self._consecutive_401s = 0  # Reset on success
+                return
+
+            if response.status_code == 401:
+                await self._handle_401()
+                return
+
+            if response.status_code == 413:
+                # Payload too large — split batch and retry
+                if len(traces) > 1:
+                    mid = len(traces) // 2
+                    await self.send_batch(traces[:mid])
+                    await self.send_batch(traces[mid:])
+                else:
+                    logger.warning("Single trace too large — dropping")
+                return
+
+            if response.status_code == 429:
+                retry_after = int(response.headers.get("Retry-After", 60))
+                logger.warning(f"Rate limited — backing off for {retry_after}s")
+                await asyncio.sleep(retry_after)
+                return
+
+            if response.status_code >= 500:
+                logger.warning(f"Server error ({response.status_code}) — dropping traces")
+                return
+
+        except (httpx.TimeoutException, httpx.NetworkError) as e:
+            logger.warning(f"Network error — dropping traces: {e}")
+        except Exception as e:
+            logger.warning(f"Unexpected error — dropping traces: {e}")
+            if self._on_error:
+                self._on_error(e)
+
+    async def _handle_401(self) -> None:
+        """Graduated 401 escalation — v2 behavior."""
+        self._consecutive_401s += 1
+        key_prefix = self._api_key[:16] + "..."
+
+        if self._consecutive_401s == 1:
+            logger.warning(f"Auth error ({key_prefix}) — pausing 60s, will retry")
+            await asyncio.sleep(60)
+        elif self._consecutive_401s == 2:
+            logger.warning(f"Auth error again ({key_prefix}) — pausing 300s, will retry")
+            await asyncio.sleep(300)
+        else:
+            logger.critical(
+                f"Auth error 3 times ({key_prefix}) — key is invalid, stopping permanently"
+            )
+            self._stopped = True
+            if self._on_error:
+                self._on_error(Exception("Invalid API key after 3 retries"))
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        self._stopped = True
+        await self._client.aclose()
+
+    @property
+    def stopped(self) -> bool:
+        return self._stopped

orithos_prela-0.2.0/prela/telemetry.py

@@ -0,0 +1,214 @@
+"""Telemetry module for Prela SDK — fire-and-forget runtime event submission.
+
+Module-level API (existing):
+    configure(api_key=..., api_url=...)
+    track("llm_call", payload={...})
+    flush()
+
+OOP API (new):
+    rt = RuntimeTelemetry(api_key="tsk_...")
+    rt.capture("db.query", agent_id="agent-1")
+    rt.flush()
+"""
+
+import json
+import os
+import threading
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+_API_URL = os.environ.get("TRACESHIELD_API_URL", "https://api.traceshield.io")
+_API_KEY = os.environ.get("TRACESHIELD_API_KEY", "")
+_ORG_ID = os.environ.get("TRACESHIELD_ORG_ID", "")
+_AGENT_ID = os.environ.get("TRACESHIELD_AGENT_ID", "")
+_BATCH_SIZE = int(os.environ.get("TRACESHIELD_TELEMETRY_BATCH_SIZE", "10"))
+_FLUSH_INTERVAL = float(os.environ.get("TRACESHIELD_TELEMETRY_FLUSH_INTERVAL", "5.0"))
+
+_buffer: list[dict[str, Any]] = []
+_lock = threading.Lock()
+_timer: threading.Timer | None = None
+
+
+def _get_session_id() -> str:
+    """Get or create a persistent session ID for this process."""
+    sid = os.environ.get("TRACESHIELD_SESSION_ID", "")
+    if not sid:
+        sid = str(uuid.uuid4())
+        os.environ["TRACESHIELD_SESSION_ID"] = sid
+    return sid
+
+
+def _flush() -> None:
+    """Send buffered events to the API."""
+    global _timer, _buffer
+    with _lock:
+        if not _buffer:
+            return
+        batch = _buffer
+        _buffer = []
+
+    if not _API_KEY or not _ORG_ID:
+        return  # Silent no-op if not configured
+
+    try:
+        data = json.dumps({"events": batch}).encode()
+        req = Request(
+            f"{_API_URL.rstrip('/')}/api/v1/telemetry/events",
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {_API_KEY}",
+                "X-Org-Id": _ORG_ID,
+            },
+            method="POST",
+        )
+        urlopen(req, timeout=5)
+    except URLError:
+        pass  # Fire-and-forget: silently drop on network failure
+    except Exception:
+        pass
+
+
+def _schedule_flush() -> None:
+    """Schedule flush if not already scheduled."""
+    global _timer
+    if _timer is not None and _timer.is_alive():
+        return
+    _timer = threading.Timer(_FLUSH_INTERVAL, _flush)
+    _timer.daemon = True
+    _timer.start()
+
+
+def track(
+    event_type: str,
+    payload: dict[str, Any] | None = None,
+    severity: str = "info",
+    agent_id: str | None = None,
+    session_id: str | None = None,
+    trace_id: str | None = None,
+) -> None:
+    """Record a telemetry event. Fire-and-forget — never blocks.
+
+    Args:
+        event_type: Event category (e.g. 'llm_call', 'tool_use', 'policy_violation', 'error')
+        payload: Arbitrary event data (will be JSON-serialized)
+        severity: 'info', 'warning', 'error', 'critical'
+        agent_id: Override auto-detected agent ID
+        session_id: Override auto-detected session ID
+        trace_id: Correlate events across a request trace
+    """
+    event = {
+        "agent_id": agent_id or _AGENT_ID,
+        "session_id": session_id or _get_session_id(),
+        "event_type": event_type,
+        "severity": severity,
+        "payload": payload or {},
+        "trace_id": trace_id or "",
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+    with _lock:
+        _buffer.append(event)
+        if len(_buffer) >= _BATCH_SIZE:
+            _flush()
+            return
+    _schedule_flush()
+
+
+def flush() -> None:
+    """Force-flush any buffered events. Call before process exit."""
+    global _timer
+    if _timer is not None:
+        _timer.cancel()
+        _timer = None
+    _flush()
+
+
+def configure(
+    api_url: str | None = None,
+    api_key: str | None = None,
+    org_id: str | None = None,
+    agent_id: str | None = None,
+    batch_size: int | None = None,
+    flush_interval: float | None = None,
+) -> None:
+    """Configure telemetry settings programmatically (overrides env vars)."""
+    global _API_URL, _API_KEY, _ORG_ID, _AGENT_ID, _BATCH_SIZE, _FLUSH_INTERVAL
+    if api_url is not None:
+        _API_URL = api_url
+    if api_key is not None:
+        _API_KEY = api_key
+    if org_id is not None:
+        _ORG_ID = org_id
+    if agent_id is not None:
+        _AGENT_ID = agent_id
+    if batch_size is not None:
+        _BATCH_SIZE = batch_size
+    if flush_interval is not None:
+        _FLUSH_INTERVAL = flush_interval
+
+
+class RuntimeTelemetry:
+    """OOP wrapper around the module-level telemetry API.
+
+    Fire-and-forget event capture for production agent monitoring.
+    Never blocks or raises — silently drops on network failure.
+
+    Usage:
+        rt = RuntimeTelemetry(api_key="tsk_...", agent_id="agent-abc")
+        rt.capture("db.query", payload={"table": "users"})
+        rt.capture("llm.chat", severity="warning")
+        rt.flush()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_url: str | None = None,
+        agent_id: str | None = None,
+        org_id: str | None = None,
+        batch_size: int | None = None,
+        flush_interval: float | None = None,
+    ):
+        configure(
+            api_key=api_key,
+            api_url=api_url,
+            agent_id=agent_id,
+            org_id=org_id,
+            batch_size=batch_size,
+            flush_interval=flush_interval,
+        )
+
+    def capture(
+        self,
+        event_type: str,
+        agent_id: str | None = None,
+        severity: str = "info",
+        payload: dict[str, Any] | None = None,
+        session_id: str | None = None,
+        trace_id: str | None = None,
+    ) -> None:
+        """Record a runtime telemetry event. Fire-and-forget.
+
+        Args:
+            event_type: Event category (e.g. 'db.query', 'llm.chat', 'api.call', 'memory.read')
+            agent_id: Override the agent ID configured at init
+            severity: 'info', 'warning', 'error', 'critical'
+            payload: Arbitrary event data (will be JSON-serialized)
+            session_id: Override auto-detected session ID
+            trace_id: Correlate events across a request trace
+        """
+        track(
+            event_type=event_type,
+            payload=payload,
+            severity=severity,
+            agent_id=agent_id,
+            session_id=session_id,
+            trace_id=trace_id,
+        )
+
+    def flush(self) -> None:
+        """Force-flush buffered events."""
+        flush()

orithos_prela-0.2.0/prela/tests/__init__.py

@@ -0,0 +1 @@
+# SDK tests

orithos_prela-0.2.0/prela/tests/test_client.py

@@ -0,0 +1,25 @@
+"""Tests for Prela SDK client."""
+
+import pytest
+
+from prela.config import PrelaConfig
+
+
+def test_config_validates_api_key():
+    """API key must start with ts_ingest_."""
+    with pytest.raises(ValueError):
+        PrelaConfig(api_key="invalid_key")
+
+
+def test_config_validates_endpoint():
+    """Endpoint must use HTTPS."""
+    with pytest.raises(ValueError):
+        PrelaConfig(api_key="ts_ingest_xxx", endpoint="http://example.com")
+
+
+def test_config_defaults():
+    """Config should have sensible defaults."""
+    config = PrelaConfig(api_key="ts_ingest_xxx")
+    assert config.endpoint == "https://api.traceshield.dev"
+    assert config.batch_size == 50
+    assert config.flush_interval == 0.5

orithos_prela-0.2.0/prela/truncation.py

@@ -0,0 +1,69 @@
+"""Payload size enforcement and truncation logic.
+
+When a trace exceeds max_trace_size_bytes (default 512KB),
+the SDK truncates in this order:
+1. conversation_history: Remove oldest messages first
+2. output: Truncate to 10,000 chars
+3. tool_calls: Remove tool call outputs
+4. input: Truncate to 5,000 chars (never fully removed)
+"""
+
+import json
+from typing import Any
+
+MAX_OUTPUT_CHARS = 10_000
+MAX_INPUT_CHARS = 5_000
+MIN_CONVERSATION_TURNS = 3  # Always keep system prompt + last N turns
+
+
+def truncate_trace(trace: dict[str, Any], max_bytes: int) -> dict[str, Any]:
+    """Truncate trace to fit within max_bytes. Returns modified trace."""
+    trace = trace.copy()
+    metadata = trace.get("metadata", {})
+
+    if _estimate_size(trace) <= max_bytes:
+        return trace
+
+    # 1. Remove oldest conversation messages
+    conv = trace.get("conversation_history", [])
+    if len(conv) > MIN_CONVERSATION_TURNS:
+        system_msg = [m for m in conv if m.get("role") == "system"]
+        recent = conv[-MIN_CONVERSATION_TURNS:]
+        trace["conversation_history"] = system_msg + recent
+        if _estimate_size(trace) <= max_bytes:
+            metadata["truncated"] = True
+            trace["metadata"] = metadata
+            return trace
+
+    # 2. Truncate output
+    output = trace.get("output", "")
+    if len(output) > MAX_OUTPUT_CHARS:
+        trace["output"] = output[:MAX_OUTPUT_CHARS] + " [TRUNCATED]"
+        if _estimate_size(trace) <= max_bytes:
+            metadata["truncated"] = True
+            trace["metadata"] = metadata
+            return trace
+
+    # 3. Remove tool call outputs
+    tool_calls = trace.get("tool_calls", [])
+    if tool_calls:
+        for tc in tool_calls:
+            tc.pop("output", None)
+        if _estimate_size(trace) <= max_bytes:
+            metadata["truncated"] = True
+            trace["metadata"] = metadata
+            return trace
+
+    # 4. Truncate input (never fully removed)
+    inp = trace.get("input", "")
+    if len(inp) > MAX_INPUT_CHARS:
+        trace["input"] = inp[:MAX_INPUT_CHARS] + " [TRUNCATED]"
+
+    metadata["truncated"] = True
+    trace["metadata"] = metadata
+    return trace
+
+
+def _estimate_size(trace: dict[str, Any]) -> int:
+    """Estimate JSON-serialized size of trace in bytes."""
+    return len(json.dumps(trace, ensure_ascii=False).encode("utf-8"))

orithos_prela-0.2.0/prela/types.py

@@ -0,0 +1,33 @@
+"""TypedDicts for trace data structures — v2."""
+
+from typing import Any, TypedDict
+
+
+class ToolCallData(TypedDict, total=False):
+    tool: str
+    input: dict[str, Any]
+    output: dict[str, Any]
+    latency_ms: int
+
+
+class TraceMetadata(TypedDict, total=False):
+    model: str
+    temperature: float
+    tokens_input: int
+    tokens_output: int
+    latency_ms: int
+    cost_usd: float
+    truncated: bool  # v2: True if trace was truncated due to size
+
+
+class TraceData(TypedDict, total=False):
+    trace_id: str  # v2: Client-generated UUID4 for deduplication
+    agent_id: str
+    input: str
+    output: str
+    conversation_history: list[dict[str, str]]
+    tool_calls: list[ToolCallData]
+    metadata: TraceMetadata
+    tags: list[str]
+    sampled: bool  # v2: Always True (unsampled traces aren't sent)
+    timestamp: str

orithos_prela-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68.0.0", "wheel>=0.42.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "orithos-prela"
+version = "0.2.0"
+description = "Fire-and-forget trace ingestion SDK for Orithos AI Agent Security"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Orithos", email = "dev@orithos.com"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+dependencies = [
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://orithos.com"
+Repository = "https://github.com/nishkmg/TraceShield"
+Documentation = "https://github.com/nishkmg/TraceShield/tree/staging/prela-sdk"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.4.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["prela*"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF"]
+
+[tool.pytest.ini_options]
+testpaths = ["prela/tests"]
+asyncio_mode = "auto"

orithos_prela-0.2.0/setup.cfg

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