znyx-runtime 1.0.0__tar.gz

znyx_runtime-1.0.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: znyx-runtime
+Version: 1.0.0
+Summary: Znyx guardrails runtime: a lightweight FastAPI service that evaluates LLM traffic against policies. Rules-only out of the box; gains ML when pointed at a Znyx inference sidecar.
+Author: Zitrino
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/zitrino-oss/znyx-runtime
+Project-URL: Source, https://github.com/zitrino-oss/znyx-runtime
+Project-URL: Issues, https://github.com/zitrino-oss/znyx-runtime/issues
+Keywords: llm,guardrails,safety,ai-security,fastapi,policy
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: znyx-core>=1.0.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: python-multipart>=0.0.30
+Requires-Dist: python-dotenv>=1.0.0
+
+# znyx-runtime
+
+A lightweight, dependency-minimal FastAPI service that evaluates LLM traffic
+against guardrail policies. Rules-only out of the box; it gains ML detection when
+pointed at a Znyx inference sidecar over HTTP.
+
+```bash
+pip install znyx-runtime
+znyx-runtime serve --port 8080
+```
+
+Or with Docker:
+
+```bash
+docker run -p 8080:8080 znyx/runtime
+```
+
+The runtime is deliberately thin: FastAPI, uvicorn, httpx, and
+[`znyx-core`](https://github.com/zitrino-oss/znyx-runtime) (the detection engine).
+No database, no heavy ML libraries. Point it at a sidecar endpoint to enable
+model-backed detectors; without one, it runs the deterministic rules path.
+
+See the [repository README](https://github.com/zitrino-oss/znyx-runtime) for
+configuration, deployment manifests, and the evaluate API.
+
+## License
+
+Apache-2.0

znyx_runtime-1.0.0/README.md

@@ -0,0 +1,28 @@
+# znyx-runtime
+
+A lightweight, dependency-minimal FastAPI service that evaluates LLM traffic
+against guardrail policies. Rules-only out of the box; it gains ML detection when
+pointed at a Znyx inference sidecar over HTTP.
+
+```bash
+pip install znyx-runtime
+znyx-runtime serve --port 8080
+```
+
+Or with Docker:
+
+```bash
+docker run -p 8080:8080 znyx/runtime
+```
+
+The runtime is deliberately thin: FastAPI, uvicorn, httpx, and
+[`znyx-core`](https://github.com/zitrino-oss/znyx-runtime) (the detection engine).
+No database, no heavy ML libraries. Point it at a sidecar endpoint to enable
+model-backed detectors; without one, it runs the deterministic rules path.
+
+See the [repository README](https://github.com/zitrino-oss/znyx-runtime) for
+configuration, deployment manifests, and the evaluate API.
+
+## License
+
+Apache-2.0

znyx_runtime-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "znyx-runtime"
+version = "1.0.0"
+description = "Znyx guardrails runtime: a lightweight FastAPI service that evaluates LLM traffic against policies. Rules-only out of the box; gains ML when pointed at a Znyx inference sidecar."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Zitrino" }]
+keywords = ["llm", "guardrails", "safety", "ai-security", "fastapi", "policy"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: FastAPI",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+]
+dependencies = [
+  "znyx-core>=1.0.0",
+  "fastapi>=0.109.0",
+  "uvicorn[standard]>=0.27.0",
+  "pydantic>=2.5.0",
+  "pydantic-settings>=2.1.0",
+  "python-multipart>=0.0.30",
+  "python-dotenv>=1.0.0",
+]
+
+[project.scripts]
+znyx-runtime = "znyx_runtime.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/zitrino-oss/znyx-runtime"
+Source = "https://github.com/zitrino-oss/znyx-runtime"
+Issues = "https://github.com/zitrino-oss/znyx-runtime/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+znyx_runtime = ["**/*.yaml", "**/*.yml", "**/*.json"]

znyx_runtime-1.0.0/setup.cfg

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

znyx_runtime-1.0.0/src/znyx_runtime/api/routes.py

@@ -0,0 +1,284 @@
+"""
+Runtime API routes - evaluation endpoints only.
+No DB dependency, no admin routes.
+"""
+import logging
+import os
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Header
+
+from znyx_core.core.models import (
+    EvaluationRequest, EvaluationResponse, HealthResponse, ToolEvaluationRequest,
+    RetrievalEvaluationRequest, AgentPlanEvaluationRequest, AgentStepEvaluationRequest,
+    MemoryWriteEvaluationRequest,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+def _is_prod() -> bool:
+    from znyx_core.utils.env import is_production
+    return is_production()
+
+
+def _runtime_auth_required() -> bool:
+    """Default: on. Only explicitly disabled when RUNTIME_REQUIRE_AUTH=false,
+    and only honoured outside production — production always requires auth."""
+    raw = os.getenv("RUNTIME_REQUIRE_AUTH", "true").strip().lower()
+    if _is_prod():
+        return True
+    return raw not in ("0", "false", "no", "off")
+
+
+async def _optional_runtime_auth(
+    x_api_key: Optional[str] = Header(default=None, alias="X-API-Key"),
+    authorization: Optional[str] = Header(default=None),
+) -> None:
+    """Enforce runtime auth. Default-on; only disablable in non-production."""
+    if not _runtime_auth_required():
+        return
+
+    expected = os.getenv("RUNTIME_API_KEY", "").strip()
+    if not expected:
+        raise HTTPException(
+            status_code=500,
+            detail="Server misconfiguration: RUNTIME_REQUIRE_AUTH is enabled but RUNTIME_API_KEY is not set.",
+        )
+
+    # Accept either X-API-Key or Authorization: Bearer
+    token = x_api_key
+    if not token and authorization and authorization.startswith("Bearer "):
+        token = authorization[7:]
+
+    if not token:
+        raise HTTPException(
+            status_code=401,
+            detail="Authentication required. Set X-API-Key or Authorization: Bearer header.",
+        )
+
+    # Constant-time compare to prevent timing attacks.
+    import hmac as _hmac
+
+    if not _hmac.compare_digest(token, expected):
+        raise HTTPException(status_code=401, detail="Invalid authentication token")
+
+
+def _get_evaluator():
+    from znyx_runtime.main import evaluator
+    return evaluator
+
+
+def _get_bundle_manager():
+    from znyx_runtime.main import bundle_manager
+    return bundle_manager
+
+
+def _get_heartbeat():
+    from znyx_runtime.main import heartbeat
+    return heartbeat
+
+
+def _get_runtime_judge():
+    from znyx_runtime.main import runtime_judge
+    return runtime_judge
+
+
+def _runtime_judge_ctx(policy, scoped):
+    """Build the per-request judge context for a runtime evaluation, or None
+    when judges aren't used / judge audit is off. Stamps the request's tenant as org_scope
+    so the CP drain can attribute the spooled rows."""
+    rj = _get_runtime_judge()
+    if rj is None:
+        return None
+    return rj.context_for(policy, env=getattr(scoped, "env", None) or "prod",
+                          org_scope=getattr(scoped, "tenant_id", None))
+
+
+# Public aliases consumed by stream_routes and any other runtime-scoped code.
+# These intentionally shadow the private underscore names so callers can do:
+#   from znyx_runtime.api.routes import verify_runtime_auth, get_evaluator
+verify_runtime_auth = _optional_runtime_auth
+get_evaluator = _get_evaluator
+get_heartbeat = _get_heartbeat
+
+
+@router.post("/v1/evaluate/input", response_model=EvaluationResponse, dependencies=[Depends(_optional_runtime_auth)])
+async def evaluate_input(request: EvaluationRequest) -> EvaluationResponse:
+    """Evaluate input text before sending to LLM."""
+    try:
+        bm = _get_bundle_manager()
+        if bm.effective_env:
+            request = request.model_copy(update={"env": bm.effective_env})
+        policy = bm.get_policy(
+            tenant_id=request.tenant_id,
+            app_id=request.app_id,
+            agent_id=request.agent_id,
+            env=request.env,
+        )
+        ev = _get_evaluator()
+        result = await ev.evaluate(request, context="input", policy=policy,
+                                   judge_ctx=_runtime_judge_ctx(policy, request))
+        hb = _get_heartbeat()
+        if hb:
+            hb.increment_eval_count()
+        return result
+    except RuntimeError as e:
+        logger.error(f"Policy unavailable: {e}")
+        raise HTTPException(status_code=503, detail="Policy unavailable (fail-closed)")
+    except Exception:
+        logger.exception("Evaluation failed")
+        raise HTTPException(status_code=500, detail="Evaluation failed")
+
+
+@router.post("/v1/evaluate/output", response_model=EvaluationResponse, dependencies=[Depends(_optional_runtime_auth)])
+async def evaluate_output(request: EvaluationRequest) -> EvaluationResponse:
+    """Evaluate output text from LLM before returning to user."""
+    try:
+        bm = _get_bundle_manager()
+        if bm.effective_env:
+            request = request.model_copy(update={"env": bm.effective_env})
+        policy = bm.get_policy(
+            tenant_id=request.tenant_id,
+            app_id=request.app_id,
+            agent_id=request.agent_id,
+            env=request.env,
+        )
+        ev = _get_evaluator()
+        result = await ev.evaluate(request, context="output", policy=policy,
+                                   judge_ctx=_runtime_judge_ctx(policy, request))
+        hb = _get_heartbeat()
+        if hb:
+            hb.increment_eval_count()
+        return result
+    except RuntimeError as e:
+        logger.error(f"Policy unavailable: {e}")
+        raise HTTPException(status_code=503, detail="Policy unavailable (fail-closed)")
+    except Exception:
+        logger.exception("Evaluation failed")
+        raise HTTPException(status_code=500, detail="Evaluation failed")
+
+
+@router.post("/v1/evaluate/tool", response_model=EvaluationResponse, dependencies=[Depends(_optional_runtime_auth)])
+async def evaluate_tool(request: ToolEvaluationRequest) -> EvaluationResponse:
+    """Evaluate tool invocation against governance policies."""
+    try:
+        bm = _get_bundle_manager()
+        if bm.effective_env:
+            request = request.model_copy(update={"env": bm.effective_env})
+        policy = bm.get_policy(
+            tenant_id=request.tenant_id,
+            app_id=request.app_id,
+            agent_id=request.agent_id,
+            env=request.env,
+        )
+        ev = _get_evaluator()
+        result = await ev.evaluate_tool(request, policy=policy,
+                                        judge_ctx=_runtime_judge_ctx(policy, request))
+        hb = _get_heartbeat()
+        if hb:
+            hb.increment_eval_count()
+        return result
+    except RuntimeError as e:
+        logger.error(f"Policy unavailable: {e}")
+        raise HTTPException(status_code=503, detail="Policy unavailable (fail-closed)")
+    except Exception:
+        logger.exception("Tool evaluation failed")
+        raise HTTPException(status_code=500, detail="Tool evaluation failed")
+
+
+# ── New-stage evaluate endpoints (generalized stage dispatch) ──────
+
+async def _evaluate_stage_runtime(scoped, stage: str) -> EvaluationResponse:
+    """Shared runtime handler for the per-stage endpoints: resolve the bundle
+    policy for the request scope and dispatch through the generalized stage pipeline."""
+    bm = _get_bundle_manager()
+    if bm.effective_env:
+        scoped = scoped.model_copy(update={"env": bm.effective_env})
+    policy = bm.get_policy(
+        tenant_id=scoped.tenant_id,
+        app_id=scoped.app_id,
+        agent_id=scoped.agent_id,
+        env=scoped.env,
+    )
+    ev = _get_evaluator()
+    result = await ev.evaluate_stage(scoped, stage, policy=policy,
+                                     judge_ctx=_runtime_judge_ctx(policy, scoped))
+    hb = _get_heartbeat()
+    if hb:
+        hb.increment_eval_count()
+    return result
+
+
+@router.post("/v1/evaluate/retrieval", response_model=EvaluationResponse, dependencies=[Depends(_optional_runtime_auth)])
+async def evaluate_retrieval(request: RetrievalEvaluationRequest) -> EvaluationResponse:
+    """Evaluate retrieved RAG chunks for indirect prompt injection before they enter context (LLM01)."""
+    try:
+        return await _evaluate_stage_runtime(request, "retrieval")
+    except RuntimeError:
+        raise HTTPException(status_code=503, detail="Policy unavailable (fail-closed)")
+    except Exception:
+        logger.exception("Retrieval evaluation failed")
+        raise HTTPException(status_code=500, detail="Evaluation failed")
+
+
+@router.post("/v1/evaluate/agent-plan", response_model=EvaluationResponse, dependencies=[Depends(_optional_runtime_auth)])
+async def evaluate_agent_plan(request: AgentPlanEvaluationRequest) -> EvaluationResponse:
+    """Evaluate a proposed multi-step agent plan for excessive agency (LLM06)."""
+    try:
+        return await _evaluate_stage_runtime(request, "agent_plan")
+    except RuntimeError:
+        raise HTTPException(status_code=503, detail="Policy unavailable (fail-closed)")
+    except Exception:
+        logger.exception("Agent-plan evaluation failed")
+        raise HTTPException(status_code=500, detail="Evaluation failed")
+
+
+@router.post("/v1/evaluate/agent-step", response_model=EvaluationResponse, dependencies=[Depends(_optional_runtime_auth)])
+async def evaluate_agent_step(request: AgentStepEvaluationRequest) -> EvaluationResponse:
+    """Evaluate a single agent-loop iteration for budget/depth caps (LLM10)."""
+    try:
+        return await _evaluate_stage_runtime(request, "agent_loop")
+    except RuntimeError:
+        raise HTTPException(status_code=503, detail="Policy unavailable (fail-closed)")
+    except Exception:
+        logger.exception("Agent-step evaluation failed")
+        raise HTTPException(status_code=500, detail="Evaluation failed")
+
+
+@router.post("/v1/evaluate/memory-write", response_model=EvaluationResponse, dependencies=[Depends(_optional_runtime_auth)])
+async def evaluate_memory_write(request: MemoryWriteEvaluationRequest) -> EvaluationResponse:
+    """Evaluate text being written to agent memory for persistent injection (LLM01)."""
+    try:
+        return await _evaluate_stage_runtime(request, "memory_write")
+    except RuntimeError:
+        raise HTTPException(status_code=503, detail="Policy unavailable (fail-closed)")
+    except Exception:
+        logger.exception("Memory-write evaluation failed")
+        raise HTTPException(status_code=500, detail="Evaluation failed")
+
+
+@router.get("/healthz", response_model=HealthResponse)
+async def health_check() -> HealthResponse:
+    """Health check - always returns 200."""
+    return HealthResponse(status="ok")
+
+
+@router.get("/readyz", response_model=HealthResponse)
+async def readiness_check() -> HealthResponse:
+    """Readiness check - returns 200 only if a policy is loaded."""
+    bm = _get_bundle_manager()
+    if bm.is_ready:
+        return HealthResponse(status="ready")
+    raise HTTPException(status_code=503, detail="Not ready - no policy loaded")
+
+
+@router.get("/v1/bundle/status")
+async def bundle_status():
+    """Return metadata about the currently loaded policy bundle."""
+    bm = _get_bundle_manager()
+    return {
+        "ready": bm.is_ready,
+        **bm.bundle_info,
+    }

znyx_runtime-1.0.0/src/znyx_runtime/api/stream_routes.py

@@ -0,0 +1,101 @@
+"""Streaming guardrails SSE endpoint - evaluate LLM output in real-time."""
+import json
+import logging
+from typing import Any, Dict, List, Optional
+from fastapi import APIRouter, Depends
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+
+from znyx_runtime.api.routes import verify_runtime_auth, get_evaluator, get_heartbeat
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Runtime API"])
+
+
+class StreamEvaluateRequest(BaseModel):
+    """Request body for streaming evaluation."""
+    request_id: str = "stream-0"
+    tenant_id: str = "default"
+    app_id: str = "default"
+    context: str = Field(default="output", description="input or output")
+    chunks: List[str] = Field(..., description="Text chunks to evaluate in order")
+    policy: Optional[Dict[str, Any]] = Field(default=None, description="Inline policy (optional)")
+    window_size: int = Field(default=200, ge=50, le=2000)
+    overlap: int = Field(default=40, ge=0, le=500)
+
+
+@router.post(
+    "/v1/evaluate/stream",
+    operation_id="runtime.evaluateStream",
+    summary="Evaluate streaming LLM output as it arrives",
+)
+async def evaluate_stream(
+    body: StreamEvaluateRequest,
+    _auth=Depends(verify_runtime_auth),
+    evaluator=Depends(get_evaluator),
+):
+    """Evaluate text chunks via Server-Sent Events.
+
+    Accepts a list of text chunks and streams back SSE events as each window
+    is evaluated. Events:
+      - ``chunk``: forwarded text chunk
+      - ``guardrail``: window evaluation result (non-blocking)
+      - ``block``: window triggered a BLOCK decision
+      - ``done``: final summary with aggregate metrics
+    """
+    from znyx_core.engine.streaming import StreamingEvaluator
+    from znyx_core.core.models import EvaluationRequest
+
+    # Resolve policy
+    policy = body.policy
+    if policy is None and evaluator.policy_resolver:
+        policy = evaluator.policy_resolver.resolve(
+            tenant_id=body.tenant_id,
+            app_id=body.app_id,
+            agent_id="default",
+            env="prod",
+        )
+    if policy is None:
+        policy = {}
+
+    request = EvaluationRequest(
+        request_id=body.request_id,
+        tenant_id=body.tenant_id,
+        app_id=body.app_id,
+        text="",  # text comes in chunks
+    )
+
+    stream_eval = StreamingEvaluator(
+        policy=policy,
+        context=body.context,
+        window_size=body.window_size,
+        overlap=body.overlap,
+        request=request,
+    )
+
+    async def event_generator():
+        for chunk in body.chunks:
+            events = stream_eval.push(chunk)
+            for event in events:
+                yield f"event: {event['event']}\ndata: {json.dumps(event['data'])}\n\n"
+                if event["event"] == "block":
+                    # Still send done after block
+                    break
+            if stream_eval.is_blocked:
+                break
+
+        summary = stream_eval.flush()
+        yield f"event: {summary['event']}\ndata: {json.dumps(summary['data'])}\n\n"
+        hb = get_heartbeat()
+        if hb:
+            hb.increment_eval_count()
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )