korasafe-sdk 0.2.0__py3-none-any.whl

korasafe/__init__.py

@@ -0,0 +1,37 @@
+from .client import KoraSafeAPIError, KoraSafeClient
+from .decorators import KoraSafeBlockedError, withKoraSafeScan
+from .langchain import KoraSafeCallback
+from .llamaindex import KoraSafeLlamaIndexMiddleware
+from .models import (
+    FindingSubmission,
+    GateDecision,
+    GateResult,
+    GuardianFinding,
+    ScanContext,
+    ScanInput,
+    ScanResult,
+    SubmittedFinding,
+)
+from .trace import KoraTrace, init_trace, kora_trace
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "FindingSubmission",
+    "GateDecision",
+    "GateResult",
+    "GuardianFinding",
+    "KoraSafeAPIError",
+    "KoraSafeBlockedError",
+    "KoraSafeCallback",
+    "KoraSafeClient",
+    "KoraSafeLlamaIndexMiddleware",
+    "KoraTrace",
+    "ScanContext",
+    "ScanInput",
+    "ScanResult",
+    "SubmittedFinding",
+    "init_trace",
+    "kora_trace",
+    "withKoraSafeScan",
+]

korasafe/client.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import os
+from typing import Any, cast
+
+import httpx
+
+from .models import (
+    FindingSubmission,
+    GateDecision,
+    GateResult,
+    ScanContext,
+    ScanInput,
+    ScanResult,
+    SubmittedFinding,
+)
+
+
+class KoraSafeAPIError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int = 0, code: str = "UNKNOWN") -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+
+
+class KoraSafeClient:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        http_client: httpx.Client | None = None,
+        async_http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        resolved_key = api_key or os.getenv("KORASAFE_API_KEY")
+        if not resolved_key:
+            raise ValueError("KoraSafe API key required; pass api_key or set KORASAFE_API_KEY")
+        self.api_key = resolved_key
+        self.base_url = (
+            base_url or os.getenv("KORASAFE_BASE_URL") or "https://korasafe.app"
+        ).rstrip("/")
+        self.timeout = timeout
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._async_client = async_http_client or httpx.AsyncClient(timeout=timeout)
+
+    def scan(
+        self,
+        input: str | bytes | dict[str, Any] | ScanInput,
+        context: dict[str, Any] | ScanContext | None = None,
+    ) -> ScanResult:
+        payload = self._scan_payload(input, context)
+        return ScanResult.model_validate(self._request("POST", "/api/guardian-scan", json=payload))
+
+    async def async_scan(
+        self,
+        input: str | bytes | dict[str, Any] | ScanInput,
+        context: dict[str, Any] | ScanContext | None = None,
+    ) -> ScanResult:
+        payload = self._scan_payload(input, context)
+        return ScanResult.model_validate(
+            await self._async_request("POST", "/api/guardian-scan", json=payload)
+        )
+
+    def gate(
+        self,
+        decision: dict[str, Any] | GateDecision,
+        action: str | None = None,
+    ) -> GateResult:
+        payload = self._gate_payload(decision, action)
+        return GateResult.model_validate(self._request("POST", "/api/guardian-gate", json=payload))
+
+    async def async_gate(
+        self,
+        decision: dict[str, Any] | GateDecision,
+        action: str | None = None,
+    ) -> GateResult:
+        payload = self._gate_payload(decision, action)
+        return GateResult.model_validate(
+            await self._async_request("POST", "/api/guardian-gate", json=payload)
+        )
+
+    def submit_finding(
+        self,
+        finding: dict[str, Any] | FindingSubmission,
+        **kwargs: Any,
+    ) -> SubmittedFinding:
+        payload = self._finding_payload(finding, kwargs)
+        return SubmittedFinding.model_validate(self._request("POST", "/api/findings", json=payload))
+
+    async def async_submit_finding(
+        self,
+        finding: dict[str, Any] | FindingSubmission,
+        **kwargs: Any,
+    ) -> SubmittedFinding:
+        payload = self._finding_payload(finding, kwargs)
+        return SubmittedFinding.model_validate(
+            await self._async_request("POST", "/api/findings", json=payload)
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    async def aclose(self) -> None:
+        await self._async_client.aclose()
+
+    def _scan_payload(
+        self,
+        input: str | bytes | dict[str, Any] | ScanInput,
+        context: dict[str, Any] | ScanContext | None,
+    ) -> dict[str, Any]:
+        scan_input = ScanInput.from_value(input)
+        scan_context = context if isinstance(context, ScanContext) else ScanContext.model_validate(
+            context or {}
+        )
+        return {
+            "input": scan_input.model_dump(mode="json"),
+            "context": scan_context.model_dump(mode="json"),
+        }
+
+    def _gate_payload(
+        self,
+        decision: dict[str, Any] | GateDecision,
+        action: str | None,
+    ) -> dict[str, Any]:
+        if isinstance(decision, GateDecision):
+            gate_decision = decision
+        else:
+            payload = dict(decision)
+            if action is not None:
+                payload.setdefault("action", action)
+            gate_decision = GateDecision.model_validate(payload)
+        return gate_decision.model_dump(mode="json")
+
+    def _finding_payload(
+        self,
+        finding: dict[str, Any] | FindingSubmission,
+        kwargs: dict[str, Any],
+    ) -> dict[str, Any]:
+        payload = (
+            finding
+            if isinstance(finding, FindingSubmission)
+            else FindingSubmission.model_validate({**finding, **kwargs})
+        )
+        return payload.model_dump(mode="json")
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+
+    def _request(self, method: str, path: str, *, json: dict[str, Any]) -> dict[str, Any]:
+        response = self._client.request(
+            method,
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            json=json,
+        )
+        return self._decode(response)
+
+    async def _async_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any],
+    ) -> dict[str, Any]:
+        response = await self._async_client.request(
+            method,
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            json=json,
+        )
+        return self._decode(response)
+
+    def _decode(self, response: httpx.Response) -> dict[str, Any]:
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise KoraSafeAPIError(
+                f"Non-JSON response from KoraSafe: HTTP {response.status_code}",
+                status_code=response.status_code,
+            ) from exc
+        if response.is_error:
+            error = data.get("error", {}) if isinstance(data, dict) else {}
+            message = error.get("message") or f"HTTP {response.status_code}"
+            code = error.get("code") or "UNKNOWN"
+            raise KoraSafeAPIError(message, status_code=response.status_code, code=code)
+        if not isinstance(data, dict):
+            raise KoraSafeAPIError(
+                "KoraSafe response must be a JSON object",
+                status_code=response.status_code,
+            )
+        return cast(dict[str, Any], data)

korasafe/decorators.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any, ParamSpec, TypeVar, cast, overload
+
+from .client import KoraSafeClient
+from .models import ScanContext
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class KoraSafeBlockedError(RuntimeError):
+    pass
+
+
+@overload
+def withKoraSafeScan(handler: Callable[P, R]) -> Callable[P, R]: ...
+
+
+@overload
+def withKoraSafeScan(
+    handler: None = None,
+    *,
+    client: KoraSafeClient | None = None,
+    context: ScanContext | dict[str, Any] | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+
+def withKoraSafeScan(
+    handler: Callable[P, R] | None = None,
+    *,
+    client: KoraSafeClient | None = None,
+    context: ScanContext | dict[str, Any] | None = None,
+) -> Callable[P, R] | Callable[[Callable[P, R]], Callable[P, R]]:
+    def decorate(func: Callable[P, R]) -> Callable[P, R]:
+        scanner = client or KoraSafeClient()
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
+                result = await scanner.async_scan(_input_summary(args, kwargs), context)
+                if not result.allowed:
+                    raise KoraSafeBlockedError(result.action or "KoraSafe blocked this call")
+                return await func(*args, **kwargs)
+
+            return cast(Callable[P, R], async_wrapper)
+
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            result = scanner.scan(_input_summary(args, kwargs), context)
+            if not result.allowed:
+                raise KoraSafeBlockedError(result.action or "KoraSafe blocked this call")
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    if handler is not None:
+        return decorate(handler)
+    return decorate
+
+
+def _input_summary(args: tuple[Any, ...], kwargs: dict[str, Any]) -> dict[str, Any]:
+    text = repr({"args": args, "kwargs": kwargs})
+    return {
+        "content": text,
+        "surface": "python-sdk",
+        "metadata": {"arg_count": len(args), "kwarg_keys": sorted(kwargs)},
+    }

korasafe/langchain.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .client import KoraSafeClient
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler  # type: ignore[import-not-found]
+except Exception:  # pragma: no cover - optional dependency
+    BaseCallbackHandler = object
+
+
+class KoraSafeCallback(BaseCallbackHandler):  # type: ignore[misc]
+    def __init__(
+        self,
+        client: KoraSafeClient | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__()
+        self.client = client or KoraSafeClient()
+        self.context = context or {}
+
+    def on_llm_start(self, serialized: dict[str, Any], prompts: list[str], **kwargs: Any) -> None:
+        for prompt in prompts:
+            self.client.scan(
+                {
+                    "content": prompt,
+                    "direction": "prompt",
+                    "surface": "langchain",
+                    "metadata": {"serialized": serialized},
+                },
+                {**self.context, "metadata": {"run_id": str(kwargs.get("run_id", ""))}},
+            )
+
+    def on_llm_end(self, response: Any, **kwargs: Any) -> None:
+        self.client.scan(
+            {"content": repr(response), "direction": "response", "surface": "langchain"},
+            {**self.context, "metadata": {"run_id": str(kwargs.get("run_id", ""))}},
+        )

korasafe/llamaindex.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from .client import KoraSafeClient
+
+R = TypeVar("R")
+
+
+class KoraSafeLlamaIndexMiddleware:
+    def __init__(
+        self,
+        client: KoraSafeClient | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        self.client = client or KoraSafeClient()
+        self.context = context or {}
+
+    def wrap_query_engine(self, query_engine: Any) -> Any:
+        original = query_engine.query
+
+        def query(prompt: str, *args: Any, **kwargs: Any) -> Any:
+            self.client.scan(
+                {"content": prompt, "surface": "llamaindex", "direction": "prompt"},
+                self.context,
+            )
+            result = original(prompt, *args, **kwargs)
+            self.client.scan(
+                {"content": repr(result), "surface": "llamaindex", "direction": "response"},
+                self.context,
+            )
+            return result
+
+        query_engine.query = query
+        return query_engine
+
+    def wrap_callable(self, handler: Callable[..., R]) -> Callable[..., R]:
+        def wrapped(*args: Any, **kwargs: Any) -> R:
+            self.client.scan(
+                {"content": repr({"args": args, "kwargs": kwargs}), "surface": "llamaindex"},
+                self.context,
+            )
+            return handler(*args, **kwargs)
+
+        return wrapped

korasafe/models.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from hashlib import sha256
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+Metadata = dict[str, Any]
+
+
+class KoraSafeModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class ScanInput(KoraSafeModel):
+    content_hash: str = Field(min_length=16)
+    content_length: int = Field(ge=0)
+    content_type: str = "text/plain"
+    direction: Literal["prompt", "response", "tool_input", "tool_output"] = "prompt"
+    surface: str = "agent"
+    content_ref: str | None = None
+    labels: list[str] = Field(default_factory=list)
+    metadata: Metadata = Field(default_factory=dict)
+
+    @classmethod
+    def from_value(cls, value: str | bytes | dict[str, Any] | ScanInput) -> ScanInput:
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, bytes):
+            return cls(content_hash=sha256(value).hexdigest(), content_length=len(value))
+        if isinstance(value, str):
+            encoded = value.encode("utf-8")
+            return cls(content_hash=sha256(encoded).hexdigest(), content_length=len(encoded))
+        payload = dict(value)
+        raw = payload.pop("content", None)
+        if raw is not None and "content_hash" not in payload:
+            encoded = raw.encode("utf-8") if isinstance(raw, str) else bytes(raw)
+            payload["content_hash"] = sha256(encoded).hexdigest()
+            payload["content_length"] = len(encoded)
+        return cls.model_validate(payload)
+
+
+class ScanContext(KoraSafeModel):
+    system_id: str | None = None
+    trace_id: str | None = None
+    session_id: str | None = None
+    user_id: str | None = None
+    org_id: str | None = None
+    metadata: Metadata = Field(default_factory=dict)
+
+
+class GuardianFinding(KoraSafeModel):
+    guardian_id: str
+    severity: Literal["critical", "high", "medium", "low", "info"] = "info"
+    title: str
+    confidence: float = Field(ge=0, le=1, default=1)
+    evidence_ref: str | None = None
+    rule_id: str | None = None
+    metadata: Metadata = Field(default_factory=dict)
+
+
+class ScanResult(KoraSafeModel):
+    verdict: Literal["pass", "flag", "block"] = "pass"
+    allowed: bool = True
+    findings: list[GuardianFinding] = Field(default_factory=list)
+    action: str | None = None
+    request_id: str | None = None
+    metadata: Metadata = Field(default_factory=dict)
+
+    @field_validator("allowed")
+    @classmethod
+    def block_verdict_disallows(cls, allowed: bool, info: Any) -> bool:
+        verdict = info.data.get("verdict")
+        if verdict == "block" and allowed:
+            return False
+        return allowed
+
+
+class GateDecision(KoraSafeModel):
+    decision_id: str | None = None
+    action: str
+    risk_tier: Literal["low", "medium", "high", "critical"] = "low"
+    metadata: Metadata = Field(default_factory=dict)
+
+
+class GateResult(KoraSafeModel):
+    allowed: bool
+    action: Literal["allow", "flag", "block", "require_approval"] = "allow"
+    reason: str | None = None
+    request_id: str | None = None
+    metadata: Metadata = Field(default_factory=dict)
+
+
+class FindingSubmission(KoraSafeModel):
+    guardian_id: str
+    title: str
+    severity: Literal["critical", "high", "medium", "low", "info"] = "info"
+    evidence_ref: str | None = None
+    context: ScanContext = Field(default_factory=ScanContext)
+    metadata: Metadata = Field(default_factory=dict)
+
+
+class SubmittedFinding(KoraSafeModel):
+    id: str
+    status: str = "open"
+    request_id: str | None = None
+    metadata: Metadata = Field(default_factory=dict)

korasafe/py.typed

@@ -0,0 +1 @@
+

korasafe/trace.py

@@ -0,0 +1,455 @@
+from __future__ import annotations
+
+import functools
+import inspect
+import os
+import threading
+import time
+import uuid
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+
+DEFAULT_ENDPOINT = "https://app.korasafe.ai/api/ingest"
+RETRY_BASE_S = 0.25
+RETRY_CAP_S = 5.0
+
+
+@dataclass
+class _TraceContext:
+    trace_id: str
+    task_name: str | None
+    started_at_monotonic: float
+
+
+_current_trace: ContextVar[_TraceContext | None] = ContextVar(
+    "korasafe_current_trace", default=None
+)
+
+Logger = Callable[[str, str], None]
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _new_id() -> str:
+    return str(uuid.uuid4())
+
+
+def _silent_logger(_level: str, _message: str) -> None:
+    return None
+
+
+class KoraTrace:
+    """Capture agent chain-of-thought (plan, LLM calls, tool calls, reasoning, human approvals)
+    and ship them to the KoraSafe audit log.
+
+    Configure via env vars (KORASAFE_API_KEY, KORASAFE_INGEST_URL) or by passing args.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        endpoint: str | None = None,
+        batch_size: int = 10,
+        flush_interval_s: float = 5.0,
+        timeout_s: float = 10.0,
+        max_retries: int = 3,
+        disabled: bool = False,
+        logger: Logger | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        resolved_key = api_key if api_key is not None else os.getenv("KORASAFE_API_KEY", "")
+        self.api_key = resolved_key or ""
+        self.endpoint = (
+            endpoint or os.getenv("KORASAFE_INGEST_URL") or DEFAULT_ENDPOINT
+        )
+        self.batch_size = max(1, batch_size)
+        self.flush_interval_s = max(0.1, flush_interval_s)
+        self.timeout_s = timeout_s
+        self.max_retries = max(0, max_retries)
+        self.logger: Logger = logger or _silent_logger
+        self._client = http_client or httpx.Client(timeout=timeout_s)
+        self._owned_client = http_client is None
+        self._buffer: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._timer: threading.Timer | None = None
+        self._closed = False
+
+        if disabled:
+            self.disabled = True
+        elif not self.api_key:
+            self.disabled = True
+            self.logger(
+                "warn",
+                "korasafe-trace: no API key configured; events will be dropped. "
+                "Set KORASAFE_API_KEY or pass api_key.",
+            )
+        else:
+            self.disabled = False
+
+    @contextmanager
+    def run(self, task_name: str) -> Iterator[_TraceContext]:
+        """Open a trace context. Use as a `with` block. Emits run_start + run_end events
+        with a shared trace_id. Nested plan/llm_call/tool_call/human_approval calls
+        auto-attach to this trace via contextvars.
+        """
+        context = _TraceContext(
+            trace_id=_new_id(),
+            task_name=task_name,
+            started_at_monotonic=time.monotonic(),
+        )
+        token: Token[_TraceContext | None] = _current_trace.set(context)
+        self._emit(
+            {
+                "event_id": _new_id(),
+                "event_type": "run_start",
+                "trace_id": context.trace_id,
+                "span_id": _new_id(),
+                "timestamp": _now_iso(),
+                "name": task_name,
+                "status": "ok",
+            }
+        )
+        try:
+            yield context
+        except BaseException as exc:
+            self._emit(
+                {
+                    "event_id": _new_id(),
+                    "event_type": "run_end",
+                    "trace_id": context.trace_id,
+                    "span_id": _new_id(),
+                    "timestamp": _now_iso(),
+                    "name": task_name,
+                    "status": "error",
+                    "duration_ms": int(
+                        (time.monotonic() - context.started_at_monotonic) * 1000
+                    ),
+                    "error": str(exc),
+                }
+            )
+            raise
+        else:
+            self._emit(
+                {
+                    "event_id": _new_id(),
+                    "event_type": "run_end",
+                    "trace_id": context.trace_id,
+                    "span_id": _new_id(),
+                    "timestamp": _now_iso(),
+                    "name": task_name,
+                    "status": "ok",
+                    "duration_ms": int(
+                        (time.monotonic() - context.started_at_monotonic) * 1000
+                    ),
+                }
+            )
+        finally:
+            _current_trace.reset(token)
+
+    def trace(self, task_name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Decorator form. Wraps a function so each call runs inside a fresh trace context."""
+
+        def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+            if inspect.iscoroutinefunction(fn):
+
+                @functools.wraps(fn)
+                async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                    with self.run(task_name):
+                        return await fn(*args, **kwargs)
+
+                return async_wrapper
+
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                with self.run(task_name):
+                    return fn(*args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+    def plan(
+        self,
+        steps: Sequence[str | dict[str, Any]],
+        *,
+        reasoning: str | None = None,
+    ) -> None:
+        ctx = self._require_trace()
+        normalized: list[dict[str, Any]] = []
+        for index, step in enumerate(steps):
+            if isinstance(step, str):
+                normalized.append({"step": index + 1, "description": step})
+            else:
+                normalized.append(dict(step))
+        plan_payload: dict[str, Any] = {"steps": normalized}
+        if reasoning:
+            plan_payload["reasoning"] = reasoning
+        self._emit(
+            {
+                "event_id": _new_id(),
+                "event_type": "plan",
+                "trace_id": ctx.trace_id,
+                "span_id": _new_id(),
+                "timestamp": _now_iso(),
+                "name": "plan",
+                "plan": plan_payload,
+            }
+        )
+
+    def llm_call(
+        self,
+        *,
+        provider: str,
+        model: str,
+        input: Any,
+        output: Any,
+        input_tokens: int | None = None,
+        output_tokens: int | None = None,
+        total_tokens: int | None = None,
+        cost_usd: float | None = None,
+        duration_ms: int | None = None,
+        status: str | None = None,
+        error: str | None = None,
+    ) -> None:
+        ctx = self._require_trace()
+        tt = total_tokens
+        if tt is None and (input_tokens is not None or output_tokens is not None):
+            tt = (input_tokens or 0) + (output_tokens or 0)
+        self._emit(
+            {
+                "event_id": _new_id(),
+                "event_type": "llm_call",
+                "trace_id": ctx.trace_id,
+                "span_id": _new_id(),
+                "timestamp": _now_iso(),
+                "name": f"{provider}:{model}",
+                "provider": provider,
+                "model": model,
+                "status": status or ("error" if error else "ok"),
+                "duration_ms": duration_ms,
+                "input_tokens": input_tokens,
+                "output_tokens": output_tokens,
+                "total_tokens": tt,
+                "cost_usd": cost_usd,
+                "metadata": {"llm_input": input, "llm_output": output},
+                "error": error,
+            }
+        )
+
+    def tool_call(
+        self,
+        *,
+        name: str,
+        parameters: dict[str, Any] | None = None,
+        response: Any | None = None,
+        status: str | None = None,
+        duration_ms: int | None = None,
+        error: str | None = None,
+    ) -> None:
+        ctx = self._require_trace()
+        self._emit(
+            {
+                "event_id": _new_id(),
+                "event_type": "tool_call",
+                "trace_id": ctx.trace_id,
+                "span_id": _new_id(),
+                "timestamp": _now_iso(),
+                "name": name,
+                "status": status or ("error" if error else "ok"),
+                "duration_ms": duration_ms,
+                "tool_calls": [
+                    {
+                        "name": name,
+                        "parameters": parameters,
+                        "response": response,
+                        "status": status,
+                        "duration_ms": duration_ms,
+                        "error": error,
+                    }
+                ],
+                "error": error,
+            }
+        )
+
+    def human_approval(
+        self,
+        *,
+        reviewer_id: str,
+        decision: str,
+        notes: str | None = None,
+        approval_chain: str | None = None,
+    ) -> None:
+        ctx = self._require_trace()
+        timestamp = _now_iso()
+        self._emit(
+            {
+                "event_id": _new_id(),
+                "event_type": "human_approval",
+                "trace_id": ctx.trace_id,
+                "span_id": _new_id(),
+                "timestamp": timestamp,
+                "name": "human_approval",
+                "status": "ok",
+                "approvals": [
+                    {
+                        "reviewer_id": reviewer_id,
+                        "decision": decision,
+                        "notes": notes,
+                        "timestamp": timestamp,
+                    }
+                ],
+                "metadata": {"approval_chain": approval_chain} if approval_chain else None,
+            }
+        )
+
+    def flush(self) -> None:
+        with self._lock:
+            if not self._buffer:
+                self._cancel_timer_locked()
+                return
+            batch = self._buffer
+            self._buffer = []
+            self._cancel_timer_locked()
+        self._post(batch)
+
+    def close(self) -> None:
+        with self._lock:
+            self._closed = True
+        self.flush()
+        if self._owned_client:
+            self._client.close()
+
+    def pending_count(self) -> int:
+        with self._lock:
+            return len(self._buffer)
+
+    def _require_trace(self) -> _TraceContext:
+        ctx = _current_trace.get()
+        if ctx is None:
+            raise RuntimeError(
+                "korasafe-trace: no active trace context; wrap calls in "
+                "`with kora_trace.run(name):` (or use the @kora_trace.trace(name) decorator) "
+                "before emitting events"
+            )
+        return ctx
+
+    def _emit(self, event: dict[str, Any]) -> None:
+        cleaned = {k: v for k, v in event.items() if v is not None}
+        if self.disabled:
+            self.logger(
+                "info",
+                f"korasafe-trace: event dropped (disabled): {cleaned.get('event_type')}",
+            )
+            return
+        batch: list[dict[str, Any]] | None = None
+        with self._lock:
+            if self._closed:
+                return
+            self._buffer.append(cleaned)
+            if len(self._buffer) >= self.batch_size:
+                batch = self._buffer
+                self._buffer = []
+                self._cancel_timer_locked()
+            else:
+                self._schedule_timer_locked()
+        if batch is not None:
+            self._post(batch)
+
+    def _schedule_timer_locked(self) -> None:
+        if self._timer is not None:
+            return
+        timer = threading.Timer(self.flush_interval_s, self._on_timer)
+        timer.daemon = True
+        self._timer = timer
+        timer.start()
+
+    def _cancel_timer_locked(self) -> None:
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+    def _on_timer(self) -> None:
+        try:
+            self.flush()
+        except Exception as exc:
+            self.logger("error", f"korasafe-trace: scheduled flush failed: {exc}")
+
+    def _post(self, events: list[dict[str, Any]]) -> None:
+        if not events:
+            return
+        payload = {"type": "agent_trace_events", "events": events}
+        headers = {
+            "authorization": f"Bearer {self.api_key}",
+            "x-korasafe-sdk": "korasafe-sdk-python",
+        }
+        last_error: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.post(
+                    self.endpoint,
+                    json=payload,
+                    headers=headers,
+                    timeout=self.timeout_s,
+                )
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt == self.max_retries:
+                    self.logger(
+                        "error", f"korasafe-trace: ingest failed after retries: {exc}"
+                    )
+                    return
+                backoff = min(RETRY_CAP_S, RETRY_BASE_S * (2**attempt))
+                self.logger(
+                    "warn", f"korasafe-trace: ingest retry {attempt + 1}: {exc}"
+                )
+                time.sleep(backoff)
+                continue
+
+            if response.status_code >= 500:
+                last_error = httpx.HTTPStatusError(
+                    f"HTTP {response.status_code}", request=response.request, response=response
+                )
+                if attempt == self.max_retries:
+                    self.logger(
+                        "error",
+                        f"korasafe-trace: ingest failed after retries: HTTP {response.status_code}",
+                    )
+                    return
+                backoff = min(RETRY_CAP_S, RETRY_BASE_S * (2**attempt))
+                self.logger(
+                    "warn",
+                    f"korasafe-trace: ingest retry {attempt + 1}: HTTP {response.status_code}",
+                )
+                time.sleep(backoff)
+                continue
+            if response.status_code >= 400:
+                body_preview = response.text[:500] if response.text else ""
+                self.logger(
+                    "error",
+                    f"korasafe-trace: ingest rejected HTTP {response.status_code}: {body_preview}",
+                )
+                return
+            return
+        if last_error is not None:
+            self.logger(
+                "error", f"korasafe-trace: ingest exhausted retries: {last_error}"
+            )
+
+
+kora_trace = KoraTrace()
+
+
+def init_trace(**kwargs: Any) -> KoraTrace:
+    """Reinitialize the module-level singleton `kora_trace`."""
+    global kora_trace
+    kora_trace = KoraTrace(**kwargs)
+    return kora_trace

korasafe_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: korasafe-sdk
+Version: 0.2.0
+Summary: KoraSafe Python SDK — inline guardian scans + chain-of-thought trace capture for Python agents
+Project-URL: Homepage, https://korasafe.app
+Project-URL: Repository, https://github.com/korasafe/platform
+Project-URL: Documentation, https://github.com/korasafe/platform/tree/main/docs/sdk/python.md
+Author: KoraSafe
+License: MIT
+Keywords: agents,ai-governance,guardrails,korasafe,langchain,llamaindex
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.5; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == 'llamaindex'
+Description-Content-Type: text/markdown
+
+# KoraSafe Python SDK
+
+Two surfaces in one package:
+
+- `KoraSafeClient` — inline guardian inspection (scan, gate, submit findings). Metadata-only transport.
+- `kora_trace` — capture agent chain-of-thought (plan, LLM calls, tool calls, reasoning, human approvals) and ship to the KoraSafe audit log.
+
+```bash
+pip install korasafe-sdk
+export KORASAFE_API_KEY=ks_live_...
+```
+
+## kora_trace — chain-of-thought capture
+
+10-line FastAPI example:
+
+```python
+from fastapi import FastAPI
+from korasafe import init_trace, kora_trace
+
+init_trace()
+app = FastAPI()
+
+@app.post("/classify")
+def classify(text: str) -> dict[str, str]:
+    with kora_trace.run("classify_claim"):
+        kora_trace.plan(["look up policy", "score risk", "route"])
+        kora_trace.llm_call(provider="openai", model="gpt-4o", input=text, output="tier=gold", input_tokens=120, output_tokens=30)
+        kora_trace.tool_call(name="policy_lookup", parameters={"id": "pol-7"}, response={"tier": "gold"}, status="ok")
+        kora_trace.human_approval(reviewer_id="user-42", decision="approved")
+        return {"tier": "gold"}
+```
+
+Events appear in the KoraSafe audit log within 5 seconds.
+
+### API
+
+| Method | Purpose |
+|---|---|
+| `kora_trace.run(task_name)` | Context manager. Opens a trace; `run_start` + `run_end` events bracket the block. Nested method calls auto-attach via contextvars. |
+| `@kora_trace.trace(task_name)` | Decorator equivalent of `run`. Works on sync and async functions. |
+| `kora_trace.plan(steps, reasoning=None)` | Log initial plan. `steps` can be strings or `{step, description}` dicts. |
+| `kora_trace.llm_call(provider, model, input, output, input_tokens=, output_tokens=, total_tokens=, cost_usd=, duration_ms=, status=, error=)` | Log an LLM invocation. Tokens auto-sum if `total_tokens` omitted. |
+| `kora_trace.tool_call(name, parameters=, response=, status=, duration_ms=, error=)` | Log a tool or external API call. |
+| `kora_trace.human_approval(reviewer_id, decision, notes=, approval_chain=)` | Log a HITL decision. |
+| `kora_trace.flush()` | Force-flush buffered events. |
+| `kora_trace.close()` | Drain buffer + close HTTP client. |
+
+`init_trace(**kwargs)` reinitializes the singleton with overrides (`api_key`, `endpoint`, `batch_size=10`, `flush_interval_s=5`, `timeout_s=10`, `max_retries=3`, `disabled=False`, `logger=`, `http_client=`).
+
+Calling `plan` / `llm_call` / `tool_call` / `human_approval` outside a `run()` context raises `RuntimeError` — wrap your agent loop first.
+
+## KoraSafeClient — guardian inspection
+
+```python
+from korasafe import KoraSafeClient, withKoraSafeScan
+
+client = KoraSafeClient()
+
+
+@withKoraSafeScan(client=client, context={"system_id": "claims-agent"})
+def answer_claim(prompt: str) -> str:
+    return "approved"
+
+result = client.scan("Does this contain PII?", {"system_id": "claims-agent"})
+gate = client.gate({"action": "payment_approval", "risk_tier": "high"})
+finding = client.submit_finding({"guardian_id": "pii", "title": "PII found", "severity": "high"})
+```
+
+Raw strings passed to `scan()` or the decorator are hashed locally. The SDK sends content hash, byte length, direction, surface, labels, and caller metadata rather than prompt or response bodies.
+
+## Frameworks
+
+LangChain:
+
+```python
+from korasafe import KoraSafeCallback, KoraSafeClient
+
+callbacks = [KoraSafeCallback(client=KoraSafeClient(), context={"system_id": "claims-agent"})]
+```
+
+LlamaIndex:
+
+```python
+from korasafe import KoraSafeClient, KoraSafeLlamaIndexMiddleware
+
+query_engine = KoraSafeLlamaIndexMiddleware(KoraSafeClient()).wrap_query_engine(query_engine)
+```
+
+## Development
+
+```bash
+cd packages/sdk-python
+python -m pip install -e ".[dev]"
+ruff check .
+mypy .
+coverage run -m pytest
+coverage report
+python -m build
+```
+
+Publishing uses GitHub OIDC trusted publishing to PyPI from `sdk-python-v*` tags.

korasafe_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+korasafe/__init__.py,sha256=N62zs32NeFAtPutx8WmDotGptqE1FCutgDVgqHB1RHs,847
+korasafe/client.py,sha256=hOd5Kct0paiWNfv0TIcONcHT6SS6Ny_Nk3DeIHLpQy4,6471
+korasafe/decorators.py,sha256=Jg6yqVNlKr0YI1Mhdw8dSzWbVpRjxkZLX6waCadlp-o,2182
+korasafe/langchain.py,sha256=f5Nz1ENAa6Ff8YpL85x9AlVjSvvlGypS483_F8p2GsQ,1374
+korasafe/llamaindex.py,sha256=dVeYsNehtgyp9xrN6EizqUXfPGqvBLvwuW2bo8WYAMI,1425
+korasafe/models.py,sha256=rxlpc9k5Rzl6LhXN2w4g0ZWf8lrim-2sx7AXvs8wbIQ,3586
+korasafe/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+korasafe/trace.py,sha256=fdkr4Q2V9EwI2_oTyMdxEpsyF1yK6GnOcHQ4SaupAss,14949
+korasafe_sdk-0.2.0.dist-info/METADATA,sha256=qOq-TpzfmK8zLGnmNpxUjWzjWtGMjApgumceaTvETE0,5020
+korasafe_sdk-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+korasafe_sdk-0.2.0.dist-info/RECORD,,

korasafe_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any