korasafe-sdk 0.2.0__tar.gz

korasafe_sdk-0.2.0/.gitignore

@@ -0,0 +1,60 @@
+.vercel
+.env
+.env.*
+!.env.example
+node_modules
+.DS_Store
+*.log
+*.docx
+reference/plans/
+mockups/
+proto-*.html
+__pycache__/
+*.pyc
+audit-runs/
+.env*.local
+*.vsix
+screenshots-extracted/
+.claude/worktrees/
+.claude/scheduled_tasks.lock
+.codex-memory.md
+.claude2-memory.md
+# local agent tooling (Codex CLI, Claude Code scratch, etc.)
+.agents/
+.~lock.*
+*.tmp
+KoraSafe_*.pdf
+dist/
+.vite/
+public/_app/
+screenshots/
+playwright-report/
+test-results/
+.debug/
+fonts/
+korasafe-fonts.zip
+ziwIH6Qf
+tmp/
+public/images/app/_archive-pre-v2/
+
+# SDK build artifacts (Java, .NET, Go, Python)
+target/
+bin/
+obj/
+*.class
+*.dll
+*.exe
+*.so
+*.dylib
+*.jar
+*.nupkg
+*.whl
+go.sum.backup
+.pytest_cache/
+.mypy_cache/
+.coverage
+.claude/launch.json
+
+# Build-generated API route registry (#4535). Generated by
+# scripts/generate-hono-routes.mjs via postinstall/prebuild/pretest.
+src/api/_routes.js

korasafe_sdk-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,102 @@
+# 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/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_sdk-0.2.0/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_sdk-0.2.0/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_sdk-0.2.0/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_sdk-0.2.0/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