detecte 0.1.1__tar.gz

detecte-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,18 @@
+name: Release to PyPI
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

detecte-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,15 @@
+name: Test
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix: { python-version: ["3.9", "3.10", "3.11", "3.12"] }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: ${{ matrix.python-version }} }
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest -q

detecte-0.1.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.eggs/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.swp
+.DS_Store

detecte-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Detecte, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

detecte-0.1.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: detecte
+Version: 0.1.1
+Summary: Runtime security for AI agents — Python SDK for detecte.xyz
+Project-URL: Homepage, https://detecte.xyz
+Project-URL: Documentation, https://docs.detecte.xyz
+Project-URL: Repository, https://github.com/detecte-xyz/detecte-python
+Project-URL: Issues, https://github.com/detecte-xyz/detecte-python/issues
+Author: Detecte
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,kya,llm,policy,runtime,security
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typing-extensions>=4.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# detecte (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/detecte.svg)](https://pypi.org/project/detecte/)
+[![Python](https://img.shields.io/pypi/pyversions/detecte.svg)](https://pypi.org/project/detecte/)
+
+Runtime security for AI agents. The Python SDK for [detecte.xyz](https://detecte.xyz) — a one-to-one
+companion to [`@detecte/sdk`](https://www.npmjs.com/package/@detecte/sdk).
+
+## Install
+
+```bash
+pip install detecte
+```
+
+## Quickstart
+
+```python
+import os
+from detecte import Detecte
+
+detecte = Detecte(api_key=os.environ["DETECTE_API_KEY"])
+
+decision = detecte.verify(
+    agent="support_bot",
+    action="refund_order",
+    params={"order_id": "ord_8821", "amount": 49.99},
+)
+
+if not decision.allowed:
+    raise RuntimeError(f"Blocked: {decision.reason}")
+```
+
+## Async
+
+```python
+from detecte import AsyncDetecte
+
+async def main():
+    detecte = AsyncDetecte(api_key="sk_test_...")
+    decision = await detecte.verify(agent="bot", action="x")
+    print(decision.allowed)
+```
+
+## Resources
+
+- `detecte.agents.list() / .get(id) / .create(...)`
+- `detecte.policies.list() / .create(...) / .dry_run(policy=..., sample_size=1000)`
+- `detecte.incidents.list() / .resolve(id)`
+- `detecte.audit.list(...)`
+- `detecte.approvals.get(decision_id) / .wait(decision_id)`
+- `detecte.scans.run(agent=..., system_prompt=...)`
+
+## Webhooks
+
+```python
+from detecte import verify_webhook, WebhookVerificationError
+
+try:
+    verify_webhook(
+        payload=raw_body,
+        signature=request.headers["Detecte-Signature"],
+        secret=os.environ["DETECTE_WEBHOOK_SECRET"],
+    )
+except WebhookVerificationError:
+    return Response(status=401)
+```
+
+## LangChain integration
+
+```python
+from detecte import Detecte
+from detecte.integrations.langchain import DetecteCallbackHandler
+
+detecte = Detecte()
+handler = DetecteCallbackHandler(detecte=detecte, agent_id="agent_xxx")
+executor = AgentExecutor.from_agent_and_tools(
+    agent=...,
+    tools=...,
+    callbacks=[handler],
+)
+```
+
+## License
+
+MIT — copyright Detecte, Inc.

detecte-0.1.1/README.md

@@ -0,0 +1,85 @@
+# detecte (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/detecte.svg)](https://pypi.org/project/detecte/)
+[![Python](https://img.shields.io/pypi/pyversions/detecte.svg)](https://pypi.org/project/detecte/)
+
+Runtime security for AI agents. The Python SDK for [detecte.xyz](https://detecte.xyz) — a one-to-one
+companion to [`@detecte/sdk`](https://www.npmjs.com/package/@detecte/sdk).
+
+## Install
+
+```bash
+pip install detecte
+```
+
+## Quickstart
+
+```python
+import os
+from detecte import Detecte
+
+detecte = Detecte(api_key=os.environ["DETECTE_API_KEY"])
+
+decision = detecte.verify(
+    agent="support_bot",
+    action="refund_order",
+    params={"order_id": "ord_8821", "amount": 49.99},
+)
+
+if not decision.allowed:
+    raise RuntimeError(f"Blocked: {decision.reason}")
+```
+
+## Async
+
+```python
+from detecte import AsyncDetecte
+
+async def main():
+    detecte = AsyncDetecte(api_key="sk_test_...")
+    decision = await detecte.verify(agent="bot", action="x")
+    print(decision.allowed)
+```
+
+## Resources
+
+- `detecte.agents.list() / .get(id) / .create(...)`
+- `detecte.policies.list() / .create(...) / .dry_run(policy=..., sample_size=1000)`
+- `detecte.incidents.list() / .resolve(id)`
+- `detecte.audit.list(...)`
+- `detecte.approvals.get(decision_id) / .wait(decision_id)`
+- `detecte.scans.run(agent=..., system_prompt=...)`
+
+## Webhooks
+
+```python
+from detecte import verify_webhook, WebhookVerificationError
+
+try:
+    verify_webhook(
+        payload=raw_body,
+        signature=request.headers["Detecte-Signature"],
+        secret=os.environ["DETECTE_WEBHOOK_SECRET"],
+    )
+except WebhookVerificationError:
+    return Response(status=401)
+```
+
+## LangChain integration
+
+```python
+from detecte import Detecte
+from detecte.integrations.langchain import DetecteCallbackHandler
+
+detecte = Detecte()
+handler = DetecteCallbackHandler(detecte=detecte, agent_id="agent_xxx")
+executor = AgentExecutor.from_agent_and_tools(
+    agent=...,
+    tools=...,
+    callbacks=[handler],
+)
+```
+
+## License
+
+MIT — copyright Detecte, Inc.

detecte-0.1.1/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "detecte"
+version = "0.1.1"
+description = "Runtime security for AI agents — Python SDK for detecte.xyz"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Detecte" }]
+keywords = ["ai", "agents", "security", "runtime", "policy", "kya", "llm"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Security",
+]
+dependencies = [
+  "httpx>=0.25",
+  "pydantic>=2.0",
+  "typing_extensions>=4.5",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "respx>=0.21", "ruff>=0.5", "mypy>=1.10"]
+
+[project.urls]
+Homepage = "https://detecte.xyz"
+Documentation = "https://docs.detecte.xyz"
+Repository = "https://github.com/detecte-xyz/detecte-python"
+Issues = "https://github.com/detecte-xyz/detecte-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/detecte"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

detecte-0.1.1/src/detecte/__init__.py

@@ -0,0 +1,62 @@
+"""Detecte — runtime security for AI agents.
+
+Quickstart::
+
+    from detecte import Detecte
+
+    detecte = Detecte(api_key=os.environ["DETECTE_API_KEY"])
+
+    decision = detecte.verify(
+        agent="support_bot",
+        action="refund_order",
+        params={"order_id": "ord_8821", "amount": 49.99},
+    )
+
+    if not decision.allowed:
+        raise RuntimeError(f"Blocked: {decision.reason}")
+"""
+
+from .client import Detecte, AsyncDetecte
+from .errors import (
+    DetecteError,
+    DetecteApiError,
+    DetecteAuthError,
+    DetecteValidationError,
+    DetecteRateLimitError,
+    DetecteNetworkError,
+    DetecteTimeoutError,
+)
+from .types import (
+    Decision,
+    Agent,
+    Policy,
+    Incident,
+    AuditEntry,
+    Approval,
+    PolicyEvaluation,
+)
+from .webhooks import verify_webhook, WebhookVerificationError
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "Detecte",
+    "AsyncDetecte",
+    "DetecteError",
+    "DetecteApiError",
+    "DetecteAuthError",
+    "DetecteValidationError",
+    "DetecteRateLimitError",
+    "DetecteNetworkError",
+    "DetecteTimeoutError",
+    "Decision",
+    "Agent",
+    "Policy",
+    "Incident",
+    "AuditEntry",
+    "Approval",
+    "PolicyEvaluation",
+    "verify_webhook",
+    "WebhookVerificationError",
+    "__version__",
+]

detecte-0.1.1/src/detecte/client.py

@@ -0,0 +1,332 @@
+"""Top-level Detecte client (sync + async)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Literal, Optional
+
+from .http import SyncHttp, AsyncHttp, DEFAULT_BASE_URL
+from .errors import DetecteApiError, DetecteNetworkError
+from .types import Decision, Agent, Policy, Incident, AuditEntry, Approval
+
+Failsafe = Literal["fail_open", "fail_closed", "fail_silent"]
+
+
+def _resolve_key(api_key: Optional[str]) -> str:
+    k = api_key or os.environ.get("DETECTE_API_KEY")
+    if not k:
+        raise ValueError("api_key not provided and DETECTE_API_KEY not set")
+    return k
+
+
+def _fallback_decision(reason: str) -> Decision:
+    return Decision.model_validate(
+        {
+            "id": "dec_fallback",
+            "allowed": True,
+            "status": "allowed",
+            "reason": reason,
+            "policies_evaluated": [],
+            "risk_delta": 0,
+            "approval_url": None,
+            "metadata": {"latency_ms": 0},
+        }
+    )
+
+
+class Detecte:
+    """Synchronous Detecte client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 5.0,
+        retries: int = 2,
+        failsafe: Failsafe = "fail_open",
+    ):
+        self._http = SyncHttp(_resolve_key(api_key), base_url, timeout, retries)
+        self._failsafe = failsafe
+        self.agents = _AgentsResource(self._http)
+        self.policies = _PoliciesResource(self._http)
+        self.incidents = _IncidentsResource(self._http)
+        self.audit = _AuditResource(self._http)
+        self.approvals = _ApprovalsResource(self._http)
+        self.scans = _ScansResource(self._http)
+
+    def verify(
+        self,
+        *,
+        agent: str,
+        action: str,
+        params: Optional[dict[str, Any]] = None,
+        context: Optional[dict[str, Any]] = None,
+        sensitive: Optional[list[str]] = None,
+        session_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Decision:
+        body = {
+            "agent": agent,
+            "action": action,
+            "params": params or {},
+            "context": context or {},
+        }
+        if sensitive:
+            body["sensitive"] = sensitive
+        if session_id:
+            body["sessionId"] = session_id
+        if idempotency_key:
+            body["idempotencyKey"] = idempotency_key
+        try:
+            data = self._http.request("POST", "/v1/verify", json=body)
+            return Decision.model_validate(data)
+        except DetecteNetworkError:
+            if self._failsafe == "fail_open":
+                return _fallback_decision("Detecte unreachable; fail_open")
+            if self._failsafe == "fail_closed":
+                return Decision.model_validate(
+                    {
+                        "id": "dec_fallback",
+                        "allowed": False,
+                        "status": "blocked",
+                        "reason": "Detecte unreachable; fail_closed",
+                        "policies_evaluated": [],
+                        "risk_delta": 0,
+                        "approval_url": None,
+                        "metadata": {"latency_ms": 0},
+                    }
+                )
+            raise
+
+
+class AsyncDetecte:
+    """Asynchronous Detecte client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 5.0,
+        retries: int = 2,
+        failsafe: Failsafe = "fail_open",
+    ):
+        self._http = AsyncHttp(_resolve_key(api_key), base_url, timeout, retries)
+        self._failsafe = failsafe
+        self.agents = _AsyncAgentsResource(self._http)
+        self.policies = _AsyncPoliciesResource(self._http)
+        self.incidents = _AsyncIncidentsResource(self._http)
+        self.audit = _AsyncAuditResource(self._http)
+        self.approvals = _AsyncApprovalsResource(self._http)
+        self.scans = _AsyncScansResource(self._http)
+
+    async def verify(
+        self,
+        *,
+        agent: str,
+        action: str,
+        params: Optional[dict[str, Any]] = None,
+        context: Optional[dict[str, Any]] = None,
+        sensitive: Optional[list[str]] = None,
+        session_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Decision:
+        body = {
+            "agent": agent,
+            "action": action,
+            "params": params or {},
+            "context": context or {},
+        }
+        if sensitive:
+            body["sensitive"] = sensitive
+        if session_id:
+            body["sessionId"] = session_id
+        if idempotency_key:
+            body["idempotencyKey"] = idempotency_key
+        try:
+            data = await self._http.request("POST", "/v1/verify", json=body)
+            return Decision.model_validate(data)
+        except DetecteNetworkError:
+            if self._failsafe == "fail_open":
+                return _fallback_decision("Detecte unreachable; fail_open")
+            if self._failsafe == "fail_closed":
+                return Decision.model_validate(
+                    {
+                        "id": "dec_fallback",
+                        "allowed": False,
+                        "status": "blocked",
+                        "reason": "Detecte unreachable; fail_closed",
+                        "policies_evaluated": [],
+                        "risk_delta": 0,
+                        "approval_url": None,
+                        "metadata": {"latency_ms": 0},
+                    }
+                )
+            raise
+
+
+# ── Sync resources ──
+
+class _AgentsResource:
+    def __init__(self, http: SyncHttp):
+        self._h = http
+
+    def list(self, limit: int = 50) -> list[Agent]:
+        data = self._h.request("GET", f"/v1/agents?limit={limit}") or {}
+        return [Agent.model_validate(a) for a in data.get("data", [])]
+
+    def get(self, agent_id: str) -> Agent:
+        return Agent.model_validate(self._h.request("GET", f"/v1/agents/{agent_id}"))
+
+    def create(self, **fields: Any) -> Agent:
+        return Agent.model_validate(self._h.request("POST", "/v1/agents", json=fields))
+
+    def update(self, agent_id: str, **fields: Any) -> Agent:
+        return Agent.model_validate(self._h.request("PATCH", f"/v1/agents/{agent_id}", json=fields))
+
+
+class _PoliciesResource:
+    def __init__(self, http: SyncHttp):
+        self._h = http
+
+    def list(self, limit: int = 100) -> list[Policy]:
+        data = self._h.request("GET", f"/v1/policies?limit={limit}") or {}
+        return [Policy.model_validate(p) for p in data.get("data", [])]
+
+    def create(self, **fields: Any) -> Policy:
+        return Policy.model_validate(self._h.request("POST", "/v1/policies", json=fields))
+
+    def dry_run(self, *, policy: dict[str, Any], sample_size: int = 1000) -> dict[str, Any]:
+        return self._h.request(
+            "POST",
+            "/v1/policies/dry-run",
+            json={"policy": policy, "sample_size": sample_size},
+        )
+
+    def update(self, policy_id: str, **fields: Any) -> Policy:
+        return Policy.model_validate(self._h.request("PATCH", f"/v1/policies/{policy_id}", json=fields))
+
+    def delete(self, policy_id: str) -> None:
+        self._h.request("DELETE", f"/v1/policies/{policy_id}")
+
+
+class _IncidentsResource:
+    def __init__(self, http: SyncHttp):
+        self._h = http
+
+    def list(self, limit: int = 50) -> list[Incident]:
+        data = self._h.request("GET", f"/v1/incidents?limit={limit}") or {}
+        return [Incident.model_validate(i) for i in data.get("data", [])]
+
+    def resolve(self, incident_id: str) -> Incident:
+        return Incident.model_validate(self._h.request("POST", f"/v1/incidents/{incident_id}/resolve"))
+
+
+class _AuditResource:
+    def __init__(self, http: SyncHttp):
+        self._h = http
+
+    def list(self, **params: Any) -> list[AuditEntry]:
+        from urllib.parse import urlencode
+        qs = urlencode({k: v for k, v in params.items() if v is not None})
+        data = self._h.request("GET", f"/v1/audit?{qs}" if qs else "/v1/audit") or {}
+        return [AuditEntry.model_validate(a) for a in data.get("data", [])]
+
+
+class _ApprovalsResource:
+    def __init__(self, http: SyncHttp):
+        self._h = http
+
+    def get(self, decision_id: str) -> Approval:
+        return Approval.model_validate(self._h.request("GET", f"/v1/approvals/{decision_id}"))
+
+    def wait(self, decision_id: str, *, timeout_ms: int = 5 * 60_000, poll_ms: int = 2000) -> Approval:
+        import time as _time
+        deadline = _time.time() + timeout_ms / 1000
+        while True:
+            a = self.get(decision_id)
+            if a.approved is not None:
+                return a
+            if _time.time() >= deadline:
+                return a
+            _time.sleep(poll_ms / 1000)
+
+
+class _ScansResource:
+    def __init__(self, http: SyncHttp):
+        self._h = http
+
+    def run(self, agent: str, *, system_prompt: Optional[str] = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"agent": agent}
+        if system_prompt is not None:
+            body["system_prompt"] = system_prompt
+        return self._h.request("POST", "/v1/scans", json=body)
+
+
+# ── Async resources (wrappers) ──
+
+class _AsyncAgentsResource:
+    def __init__(self, http: AsyncHttp):
+        self._h = http
+
+    async def list(self, limit: int = 50) -> list[Agent]:
+        data = (await self._h.request("GET", f"/v1/agents?limit={limit}")) or {}
+        return [Agent.model_validate(a) for a in data.get("data", [])]
+
+    async def get(self, agent_id: str) -> Agent:
+        return Agent.model_validate(await self._h.request("GET", f"/v1/agents/{agent_id}"))
+
+    async def create(self, **fields: Any) -> Agent:
+        return Agent.model_validate(await self._h.request("POST", "/v1/agents", json=fields))
+
+
+class _AsyncPoliciesResource:
+    def __init__(self, http: AsyncHttp):
+        self._h = http
+
+    async def list(self, limit: int = 100) -> list[Policy]:
+        data = (await self._h.request("GET", f"/v1/policies?limit={limit}")) or {}
+        return [Policy.model_validate(p) for p in data.get("data", [])]
+
+    async def create(self, **fields: Any) -> Policy:
+        return Policy.model_validate(await self._h.request("POST", "/v1/policies", json=fields))
+
+
+class _AsyncIncidentsResource:
+    def __init__(self, http: AsyncHttp):
+        self._h = http
+
+    async def list(self, limit: int = 50) -> list[Incident]:
+        data = (await self._h.request("GET", f"/v1/incidents?limit={limit}")) or {}
+        return [Incident.model_validate(i) for i in data.get("data", [])]
+
+
+class _AsyncAuditResource:
+    def __init__(self, http: AsyncHttp):
+        self._h = http
+
+    async def list(self, **params: Any) -> list[AuditEntry]:
+        from urllib.parse import urlencode
+        qs = urlencode({k: v for k, v in params.items() if v is not None})
+        data = (await self._h.request("GET", f"/v1/audit?{qs}" if qs else "/v1/audit")) or {}
+        return [AuditEntry.model_validate(a) for a in data.get("data", [])]
+
+
+class _AsyncApprovalsResource:
+    def __init__(self, http: AsyncHttp):
+        self._h = http
+
+    async def get(self, decision_id: str) -> Approval:
+        return Approval.model_validate(await self._h.request("GET", f"/v1/approvals/{decision_id}"))
+
+
+class _AsyncScansResource:
+    def __init__(self, http: AsyncHttp):
+        self._h = http
+
+    async def run(self, agent: str, *, system_prompt: Optional[str] = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"agent": agent}
+        if system_prompt is not None:
+            body["system_prompt"] = system_prompt
+        return await self._h.request("POST", "/v1/scans", json=body)

detecte-0.1.1/src/detecte/errors.py

@@ -0,0 +1,65 @@
+"""Detecte SDK error hierarchy. Mirrors @detecte/sdk."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class DetecteError(Exception):
+    """Base class for all Detecte errors."""
+
+    code: str = "detecte_error"
+
+    def __init__(self, message: str, *, code: str | None = None):
+        super().__init__(message)
+        if code is not None:
+            self.code = code
+
+
+class DetecteApiError(DetecteError):
+    """A non-2xx HTTP response from the API."""
+
+    code = "api_error"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        body: Any = None,
+        code: str | None = None,
+    ):
+        super().__init__(message, code=code or "api_error")
+        self.status = status
+        self.body = body
+
+
+class DetecteAuthError(DetecteApiError):
+    code = "auth_error"
+
+
+class DetecteValidationError(DetecteApiError):
+    code = "validation_error"
+
+
+class DetecteRateLimitError(DetecteApiError):
+    code = "rate_limit_exceeded"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 429,
+        retry_after_ms: int | None = None,
+        body: Any = None,
+    ):
+        super().__init__(message, status=status, body=body, code="rate_limit_exceeded")
+        self.retry_after_ms = retry_after_ms
+
+
+class DetecteNetworkError(DetecteError):
+    code = "network_error"
+
+
+class DetecteTimeoutError(DetecteNetworkError):
+    code = "timeout"

detecte-0.1.1/src/detecte/http.py

@@ -0,0 +1,156 @@
+"""Sync + async HTTP client with retries, timeouts, and Detecte-specific error mapping."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Optional
+
+import httpx
+
+from .errors import (
+    DetecteApiError,
+    DetecteAuthError,
+    DetecteNetworkError,
+    DetecteRateLimitError,
+    DetecteTimeoutError,
+    DetecteValidationError,
+)
+
+__VERSION__ = "0.1.1"
+USER_AGENT = f"detecte-python/{__VERSION__}"
+DEFAULT_BASE_URL = "https://api.detecte.xyz"
+
+
+def _map_status(status: int, body: Any) -> type[DetecteApiError]:
+    if status == 401 or status == 403:
+        return DetecteAuthError
+    if status == 422:
+        return DetecteValidationError
+    if status == 429:
+        return DetecteRateLimitError
+    return DetecteApiError
+
+
+def _retry_after_ms(response: httpx.Response) -> Optional[int]:
+    ra = response.headers.get("retry-after")
+    if not ra:
+        return None
+    try:
+        return int(float(ra) * 1000)
+    except (TypeError, ValueError):
+        return None
+
+
+def _backoff(attempt: int) -> float:
+    return min(0.25 * (2 ** attempt) + 0.05 * attempt, 5.0)
+
+
+class _BaseHttp:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_s: float = 5.0,
+        retries: int = 2,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout_s = timeout_s
+        self.retries = retries
+
+    def _headers(self, extra: Optional[dict[str, str]] = None) -> dict[str, str]:
+        h = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+            "Accept": "application/json",
+        }
+        if extra:
+            h.update(extra)
+        return h
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if 200 <= response.status_code < 300:
+            return
+        try:
+            body = response.json()
+        except Exception:
+            body = response.text
+        message = (
+            (body.get("message") if isinstance(body, dict) else None)
+            or (body if isinstance(body, str) else f"HTTP {response.status_code}")
+        )
+        cls = _map_status(response.status_code, body)
+        if cls is DetecteRateLimitError:
+            raise DetecteRateLimitError(
+                message,
+                status=response.status_code,
+                retry_after_ms=_retry_after_ms(response),
+                body=body,
+            )
+        raise cls(message, status=response.status_code, body=body)
+
+
+class SyncHttp(_BaseHttp):
+    def request(self, method: str, path: str, *, json: Any = None, headers: Optional[dict[str, str]] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        last_err: Optional[BaseException] = None
+        for attempt in range(self.retries + 1):
+            try:
+                with httpx.Client(timeout=self.timeout_s) as client:
+                    response = client.request(method, url, json=json, headers=self._headers(headers))
+                if response.status_code == 429 and attempt < self.retries:
+                    time.sleep((_retry_after_ms(response) or 1000) / 1000)
+                    continue
+                if 500 <= response.status_code < 600 and attempt < self.retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                self._raise_for_status(response)
+                return response.json() if response.content else None
+            except httpx.TimeoutException as e:
+                last_err = e
+                if attempt < self.retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise DetecteTimeoutError(f"Timed out after {self.timeout_s}s")
+            except httpx.HTTPError as e:
+                last_err = e
+                if attempt < self.retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise DetecteNetworkError(str(e))
+        if last_err:
+            raise DetecteNetworkError(str(last_err))
+
+
+class AsyncHttp(_BaseHttp):
+    async def request(self, method: str, path: str, *, json: Any = None, headers: Optional[dict[str, str]] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        last_err: Optional[BaseException] = None
+        for attempt in range(self.retries + 1):
+            try:
+                async with httpx.AsyncClient(timeout=self.timeout_s) as client:
+                    response = await client.request(method, url, json=json, headers=self._headers(headers))
+                if response.status_code == 429 and attempt < self.retries:
+                    await asyncio.sleep((_retry_after_ms(response) or 1000) / 1000)
+                    continue
+                if 500 <= response.status_code < 600 and attempt < self.retries:
+                    await asyncio.sleep(_backoff(attempt))
+                    continue
+                self._raise_for_status(response)
+                return response.json() if response.content else None
+            except httpx.TimeoutException as e:
+                last_err = e
+                if attempt < self.retries:
+                    await asyncio.sleep(_backoff(attempt))
+                    continue
+                raise DetecteTimeoutError(f"Timed out after {self.timeout_s}s")
+            except httpx.HTTPError as e:
+                last_err = e
+                if attempt < self.retries:
+                    await asyncio.sleep(_backoff(attempt))
+                    continue
+                raise DetecteNetworkError(str(e))
+        if last_err:
+            raise DetecteNetworkError(str(last_err))

detecte-0.1.1/src/detecte/integrations/langchain.py

@@ -0,0 +1,68 @@
+"""LangChain integration: a callback handler that verifies every tool call.
+
+Usage::
+
+    from langchain.agents import AgentExecutor
+    from detecte import Detecte
+    from detecte.integrations.langchain import DetecteCallbackHandler
+
+    detecte = Detecte(api_key=...)
+    executor = AgentExecutor.from_agent_and_tools(
+        agent=...,
+        tools=...,
+        callbacks=[DetecteCallbackHandler(detecte=detecte, agent_id="agent_xxx")],
+    )
+
+When a blocked decision is encountered the handler raises a
+``DetecteToolBlocked`` so the executor's standard error path will surface the
+refusal back into the agent loop.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class DetecteToolBlocked(RuntimeError):
+    """Raised by the callback when Detecte blocks a tool call."""
+
+
+def _import_base_callback_handler() -> type:
+    try:
+        from langchain_core.callbacks.base import BaseCallbackHandler  # type: ignore
+    except ImportError:
+        try:
+            from langchain.callbacks.base import BaseCallbackHandler  # type: ignore
+        except ImportError as e:
+            raise ImportError(
+                "langchain (>=0.1) is required for DetecteCallbackHandler"
+            ) from e
+    return BaseCallbackHandler
+
+
+def DetecteCallbackHandler(detecte: Any, agent_id: str) -> Any:  # noqa: N802 — public name
+    """Construct a LangChain callback handler tied to a Detecte client + agent_id."""
+    Base = _import_base_callback_handler()
+
+    class _Handler(Base):  # type: ignore[misc, valid-type]
+        def on_tool_start(
+            self,
+            serialized: dict[str, Any],
+            input_str: str,
+            *,
+            run_id: Optional[str] = None,
+            **kwargs: Any,
+        ) -> None:
+            tool_name = serialized.get("name") or "unknown"
+            decision = detecte.verify(
+                agent=agent_id,
+                action=tool_name,
+                params={"input": input_str},
+                context={"run_id": str(run_id) if run_id else None},
+            )
+            if not decision.allowed:
+                raise DetecteToolBlocked(
+                    decision.reason or f"Detecte blocked tool {tool_name}"
+                )
+
+    return _Handler()

detecte-0.1.1/src/detecte/types.py

@@ -0,0 +1,86 @@
+"""Pydantic models mirroring @detecte/sdk's Zod schemas."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Tier = Literal["low", "medium", "high", "restricted"]
+DecisionStatus = Literal["allowed", "blocked", "escalated", "pending_approval"]
+
+
+class _Base(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+
+class PolicyEvaluation(_Base):
+    id: str
+    name: str
+    result: str
+
+
+class DecisionMetadata(_Base):
+    latency_ms: int = 0
+
+
+class Decision(_Base):
+    id: str
+    allowed: bool
+    status: DecisionStatus
+    reason: Optional[str] = None
+    policies_evaluated: list[PolicyEvaluation] = Field(default_factory=list)
+    risk_delta: float = 0
+    approval_url: Optional[str] = None
+    expires_at: Optional[str] = None
+    metadata: DecisionMetadata = Field(default_factory=DecisionMetadata)
+
+
+class Agent(_Base):
+    id: str
+    name: str
+    description: Optional[str] = None
+    tier: Tier = "medium"
+    declared_capabilities: list[str] = Field(default_factory=list)
+    risk_score: int = 0
+    created_at: Optional[str] = None
+
+
+class Policy(_Base):
+    id: str
+    name: str
+    agents: list[str] = Field(default_factory=list)
+    when: dict[str, Any] = Field(default_factory=dict)
+    then: dict[str, Any] = Field(default_factory=dict)
+    enabled: bool = True
+    created_at: Optional[str] = None
+
+
+class Incident(_Base):
+    id: str
+    agent: Optional[str] = None
+    decision_id: Optional[str] = None
+    severity: Literal["low", "medium", "high", "critical"] = "medium"
+    status: Literal["open", "acknowledged", "resolved"] = "open"
+    summary: str
+    created_at: str
+    resolved_at: Optional[str] = None
+
+
+class AuditEntry(_Base):
+    id: str
+    ts: str
+    agent: Optional[str] = None
+    action: Optional[str] = None
+    decision_id: Optional[str] = None
+    status: Optional[DecisionStatus] = None
+    actor: Optional[str] = None
+
+
+class Approval(_Base):
+    id: str
+    decision_id: str
+    approved: Optional[bool] = None
+    reason: Optional[str] = None
+    approver: Optional[str] = None
+    approval_url: Optional[str] = None

detecte-0.1.1/src/detecte/webhooks.py

@@ -0,0 +1,64 @@
+"""Webhook signature verification (Stripe-style HMAC-SHA256)."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Optional
+
+
+class WebhookVerificationError(Exception):
+    """Raised when a webhook signature can't be verified."""
+
+
+def verify_webhook(
+    *,
+    payload: str | bytes,
+    signature: str,
+    secret: str,
+    tolerance_s: int = 5 * 60,
+) -> None:
+    """Raise WebhookVerificationError unless the signature is valid.
+
+    `signature` is the `Detecte-Signature` header value, formatted as
+    ``t=<unix>,v1=<hex>``.
+    """
+
+    parts = dict(p.split("=", 1) for p in signature.split(",") if "=" in p)
+    ts = parts.get("t")
+    v1 = parts.get("v1")
+    if not ts or not v1:
+        raise WebhookVerificationError("malformed signature header")
+
+    try:
+        ts_int = int(ts)
+    except ValueError:
+        raise WebhookVerificationError("invalid timestamp")
+
+    if abs(time.time() - ts_int) > tolerance_s:
+        raise WebhookVerificationError("timestamp outside tolerance")
+
+    if isinstance(payload, str):
+        payload_bytes = payload.encode("utf-8")
+    else:
+        payload_bytes = payload
+    signed = f"{ts}.".encode("utf-8") + payload_bytes
+    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, v1):
+        raise WebhookVerificationError("bad signature")
+
+
+def is_valid_webhook(
+    *,
+    payload: str | bytes,
+    signature: str,
+    secret: str,
+    tolerance_s: int = 5 * 60,
+) -> bool:
+    """Convenience wrapper that returns a bool instead of raising."""
+    try:
+        verify_webhook(payload=payload, signature=signature, secret=secret, tolerance_s=tolerance_s)
+        return True
+    except WebhookVerificationError:
+        return False

detecte-0.1.1/tests/test_client.py

@@ -0,0 +1,80 @@
+import httpx
+import pytest
+import respx
+
+from detecte import Detecte, AsyncDetecte
+
+
+@respx.mock
+def test_verify_allowed():
+    respx.post("https://api.detecte.xyz/v1/verify").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "id": "dec_1",
+                "allowed": True,
+                "status": "allowed",
+                "reason": None,
+                "policies_evaluated": [],
+                "risk_delta": 1,
+                "metadata": {"latency_ms": 12},
+            },
+        )
+    )
+    d = Detecte(api_key="sk_test_x")
+    decision = d.verify(agent="bot", action="x")
+    assert decision.allowed
+    assert decision.id == "dec_1"
+
+
+@respx.mock
+def test_verify_blocked():
+    respx.post("https://api.detecte.xyz/v1/verify").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "id": "dec_2",
+                "allowed": False,
+                "status": "blocked",
+                "reason": "policy violation",
+                "policies_evaluated": [{"id": "pol_1", "name": "amount_cap", "result": "blocked"}],
+                "risk_delta": 0,
+                "metadata": {"latency_ms": 8},
+            },
+        )
+    )
+    d = Detecte(api_key="sk_test_x")
+    decision = d.verify(agent="bot", action="refund", params={"amount": 9999})
+    assert not decision.allowed
+    assert decision.policies_evaluated[0].name == "amount_cap"
+
+
+@respx.mock
+def test_failsafe_open_on_network_error():
+    respx.post("https://api.detecte.xyz/v1/verify").mock(side_effect=httpx.ConnectError("boom"))
+    d = Detecte(api_key="sk_test_x", retries=0, failsafe="fail_open")
+    decision = d.verify(agent="bot", action="x")
+    assert decision.allowed is True
+    assert "fail_open" in (decision.reason or "")
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_client_verify():
+    respx.post("https://api.detecte.xyz/v1/verify").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "id": "dec_3",
+                "allowed": True,
+                "status": "allowed",
+                "reason": None,
+                "policies_evaluated": [],
+                "risk_delta": 0,
+                "metadata": {"latency_ms": 5},
+            },
+        )
+    )
+    d = AsyncDetecte(api_key="sk_test_x")
+    decision = await d.verify(agent="bot", action="x")
+    assert decision.allowed

detecte-0.1.1/tests/test_webhooks.py

@@ -0,0 +1,53 @@
+import hashlib
+import hmac
+import time
+
+import pytest
+
+from detecte.webhooks import (
+    WebhookVerificationError,
+    is_valid_webhook,
+    verify_webhook,
+)
+
+
+def _sign(payload: str, secret: str, ts: int) -> str:
+    signed = f"{ts}.{payload}".encode("utf-8")
+    sig = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
+    return f"t={ts},v1={sig}"
+
+
+def test_valid_signature_passes():
+    ts = int(time.time())
+    payload = '{"hi":1}'
+    secret = "whsec_test"
+    verify_webhook(payload=payload, signature=_sign(payload, secret, ts), secret=secret)
+
+
+def test_tampered_payload_fails():
+    ts = int(time.time())
+    secret = "whsec_test"
+    sig = _sign('{"hi":1}', secret, ts)
+    with pytest.raises(WebhookVerificationError):
+        verify_webhook(payload='{"hi":2}', signature=sig, secret=secret)
+
+
+def test_old_timestamp_fails():
+    secret = "whsec_test"
+    payload = '{"hi":1}'
+    ts = int(time.time()) - 1000
+    with pytest.raises(WebhookVerificationError, match="tolerance"):
+        verify_webhook(payload=payload, signature=_sign(payload, secret, ts), secret=secret)
+
+
+def test_is_valid_webhook_returns_bool():
+    ts = int(time.time())
+    payload = "abc"
+    secret = "whsec_test"
+    assert is_valid_webhook(payload=payload, signature=_sign(payload, secret, ts), secret=secret)
+    assert not is_valid_webhook(payload="abd", signature=_sign(payload, secret, ts), secret=secret)
+
+
+def test_malformed_header_fails():
+    with pytest.raises(WebhookVerificationError):
+        verify_webhook(payload="x", signature="not-a-valid-header", secret="s")