classifinder 0.1.0__tar.gz

classifinder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClassiFinder
+
+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.

classifinder-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: classifinder
+Version: 0.1.0
+Summary: Python SDK for the ClassiFinder secret detection API
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# ClassiFinder
+
+Python SDK for the ClassiFinder secret detection API.
+
+Scan text for leaked secrets and credentials, get structured findings, and redact
+sensitive values -- all in a few lines of Python.
+
+## Installation
+
+```bash
+pip install classifinder
+```
+
+## Quick Start
+
+```python
+from classifinder import ClassiFinder
+
+client = ClassiFinder(api_key="ss_live_...")
+# or set the CLASSIFINDER_API_KEY environment variable
+
+result = client.scan("My AWS key is AKIAIOSFODNN7EXAMPLE")
+
+for finding in result.findings:
+    print(f"{finding.type_name} (severity={finding.severity}, confidence={finding.confidence})")
+    print(f"  Preview: {finding.value_preview}")
+```
+
+## Redact Secrets
+
+The `/v1/redact` endpoint replaces secrets in-place so you can safely pass text
+downstream to LLMs or logging systems.
+
+```python
+result = client.redact("DB password is SuperSecret123!")
+
+print(result.redacted_text)
+# "DB password is [DATABASE_PASSWORD]!"
+
+print(f"Redacted {result.findings_count} secret(s)")
+```
+
+## Async Support
+
+```python
+from classifinder import AsyncClassiFinder
+
+async def main():
+    client = AsyncClassiFinder(api_key="ss_live_...")
+    result = await client.scan("AKIA...")
+    await client.close()
+```
+
+## LangChain Integration
+
+Guard your LLM chains against secret leakage.
+
+```bash
+pip install classifinder[langchain]
+```
+
+```python
+from classifinder.integrations.langchain import ClassiFinderGuard
+
+guard = ClassiFinderGuard(api_key="ss_live_...", mode="redact")
+
+# Use as a standalone runnable
+clean_text = guard.invoke("My token is ghp_abc123secret")
+
+# Chain with other LangChain runnables
+chain = guard | your_llm | output_parser
+```
+
+Set `mode="block"` to raise `SecretsDetectedError` instead of redacting.
+
+## Error Handling
+
+```python
+from classifinder import ClassiFinder, AuthenticationError, RateLimitError, ClassiFinderError
+
+client = ClassiFinder(api_key="ss_live_...")
+
+try:
+    result = client.scan("check this text")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except ClassiFinderError as e:
+    print(f"API error ({e.status_code}): {e.message}")
+```
+
+## Documentation
+
+Full API documentation: [https://classifinder.tech](https://classifinder.tech)
+
+## License
+
+MIT

classifinder-0.1.0/README.md

@@ -0,0 +1,99 @@
+# ClassiFinder
+
+Python SDK for the ClassiFinder secret detection API.
+
+Scan text for leaked secrets and credentials, get structured findings, and redact
+sensitive values -- all in a few lines of Python.
+
+## Installation
+
+```bash
+pip install classifinder
+```
+
+## Quick Start
+
+```python
+from classifinder import ClassiFinder
+
+client = ClassiFinder(api_key="ss_live_...")
+# or set the CLASSIFINDER_API_KEY environment variable
+
+result = client.scan("My AWS key is AKIAIOSFODNN7EXAMPLE")
+
+for finding in result.findings:
+    print(f"{finding.type_name} (severity={finding.severity}, confidence={finding.confidence})")
+    print(f"  Preview: {finding.value_preview}")
+```
+
+## Redact Secrets
+
+The `/v1/redact` endpoint replaces secrets in-place so you can safely pass text
+downstream to LLMs or logging systems.
+
+```python
+result = client.redact("DB password is SuperSecret123!")
+
+print(result.redacted_text)
+# "DB password is [DATABASE_PASSWORD]!"
+
+print(f"Redacted {result.findings_count} secret(s)")
+```
+
+## Async Support
+
+```python
+from classifinder import AsyncClassiFinder
+
+async def main():
+    client = AsyncClassiFinder(api_key="ss_live_...")
+    result = await client.scan("AKIA...")
+    await client.close()
+```
+
+## LangChain Integration
+
+Guard your LLM chains against secret leakage.
+
+```bash
+pip install classifinder[langchain]
+```
+
+```python
+from classifinder.integrations.langchain import ClassiFinderGuard
+
+guard = ClassiFinderGuard(api_key="ss_live_...", mode="redact")
+
+# Use as a standalone runnable
+clean_text = guard.invoke("My token is ghp_abc123secret")
+
+# Chain with other LangChain runnables
+chain = guard | your_llm | output_parser
+```
+
+Set `mode="block"` to raise `SecretsDetectedError` instead of redacting.
+
+## Error Handling
+
+```python
+from classifinder import ClassiFinder, AuthenticationError, RateLimitError, ClassiFinderError
+
+client = ClassiFinder(api_key="ss_live_...")
+
+try:
+    result = client.scan("check this text")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except ClassiFinderError as e:
+    print(f"API error ({e.status_code}): {e.message}")
+```
+
+## Documentation
+
+Full API documentation: [https://classifinder.tech](https://classifinder.tech)
+
+## License
+
+MIT

classifinder-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "classifinder"
+version = "0.1.0"
+description = "Python SDK for the ClassiFinder secret detection API"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.7.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3.0"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "respx>=0.22.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/classifinder"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

classifinder-0.1.0/src/classifinder/__init__.py

@@ -0,0 +1,49 @@
+"""ClassiFinder Python SDK — scan and redact secrets from text."""
+
+from ._client import ClassiFinder
+from ._async_client import AsyncClassiFinder
+from ._exceptions import (
+    ClassiFinderError,
+    AuthenticationError,
+    RateLimitError,
+    InvalidRequestError,
+    ForbiddenError,
+    ServerError,
+    APIConnectionError,
+    SecretsDetectedError,
+)
+from ._models import (
+    ScanResult,
+    RedactResult,
+    TypesResult,
+    HealthResult,
+    FeedbackResult,
+    Finding,
+    RedactFinding,
+    Span,
+    SeveritySummary,
+    TypeInfo,
+)
+
+__all__ = [
+    "ClassiFinder",
+    "AsyncClassiFinder",
+    "ClassiFinderError",
+    "AuthenticationError",
+    "RateLimitError",
+    "InvalidRequestError",
+    "ForbiddenError",
+    "ServerError",
+    "APIConnectionError",
+    "SecretsDetectedError",
+    "ScanResult",
+    "RedactResult",
+    "TypesResult",
+    "HealthResult",
+    "FeedbackResult",
+    "Finding",
+    "RedactFinding",
+    "Span",
+    "SeveritySummary",
+    "TypeInfo",
+]

classifinder-0.1.0/src/classifinder/_async_client.py

@@ -0,0 +1,139 @@
+"""Asynchronous ClassiFinder client."""
+
+from typing import List, Optional
+
+import httpx
+
+from ._base import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    async_sleep_for_retry,
+    build_headers,
+    is_retryable,
+    raise_for_status,
+    resolve_api_key,
+)
+from ._exceptions import APIConnectionError
+from ._models import (
+    FeedbackResult,
+    HealthResult,
+    RedactResult,
+    ScanResult,
+    TypesResult,
+)
+
+
+class AsyncClassiFinder:
+    """Asynchronous client for the ClassiFinder API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = resolve_api_key(api_key)
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._client = httpx.AsyncClient(
+            headers=build_headers(self._api_key),
+            timeout=timeout,
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncClassiFinder":
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()
+
+    async def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        """Make an HTTP request with retry logic."""
+        url = f"{self._base_url}{path}"
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._client.request(method, url, **kwargs)
+                raise_for_status(response)
+                return response
+            except (httpx.TimeoutException, httpx.ConnectError, httpx.NetworkError) as exc:
+                api_exc = APIConnectionError(str(exc))
+                last_exc = api_exc
+                if attempt >= self._max_retries:
+                    raise api_exc from exc
+                await async_sleep_for_retry(attempt, api_exc)
+            except Exception as exc:
+                last_exc = exc
+                if not is_retryable(exc) or attempt >= self._max_retries:
+                    raise
+                await async_sleep_for_retry(attempt, exc)
+
+        raise last_exc  # pragma: no cover
+
+    async def scan(
+        self,
+        text: str,
+        types: Optional[List[str]] = None,
+        min_confidence: float = 0.5,
+        include_context: bool = True,
+    ) -> ScanResult:
+        """Scan text for secrets."""
+        body = {
+            "text": text,
+            "types": types or ["all"],
+            "min_confidence": min_confidence,
+            "include_context": include_context,
+        }
+        response = await self._request("POST", "/v1/scan", json=body)
+        return ScanResult.model_validate(response.json())
+
+    async def redact(
+        self,
+        text: str,
+        types: Optional[List[str]] = None,
+        min_confidence: float = 0.5,
+        redaction_style: str = "label",
+    ) -> RedactResult:
+        """Scan and redact secrets from text."""
+        body = {
+            "text": text,
+            "types": types or ["all"],
+            "min_confidence": min_confidence,
+            "redaction_style": redaction_style,
+        }
+        response = await self._request("POST", "/v1/redact", json=body)
+        return RedactResult.model_validate(response.json())
+
+    async def get_types(self) -> TypesResult:
+        """List all detectable secret types."""
+        response = await self._request("GET", "/v1/types")
+        return TypesResult.model_validate(response.json())
+
+    async def health(self) -> HealthResult:
+        """Check API health."""
+        response = await self._request("GET", "/v1/health")
+        return HealthResult.model_validate(response.json())
+
+    async def feedback(
+        self,
+        request_id: str,
+        finding_id: str,
+        feedback_type: str,
+        comment: Optional[str] = None,
+    ) -> FeedbackResult:
+        """Report a false positive or false negative."""
+        body = {
+            "request_id": request_id,
+            "finding_id": finding_id,
+            "feedback_type": feedback_type,
+        }
+        if comment is not None:
+            body["comment"] = comment
+        response = await self._request("POST", "/v1/feedback", json=body)
+        return FeedbackResult.model_validate(response.json())

classifinder-0.1.0/src/classifinder/_base.py

@@ -0,0 +1,104 @@
+"""Shared logic for sync and async clients: error mapping, retry, request building."""
+
+import os
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._exceptions import (
+    AuthenticationError,
+    RateLimitError,
+    InvalidRequestError,
+    ForbiddenError,
+    ServerError,
+    APIConnectionError,
+    ClassiFinderError,
+)
+
+DEFAULT_BASE_URL = "https://api.classifinder.tech"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+_RETRYABLE_STATUS_CODES = {429, 500}
+
+
+def resolve_api_key(api_key: Optional[str]) -> str:
+    """Resolve API key from argument or CLASSIFINDER_API_KEY env var."""
+    key = api_key or os.environ.get("CLASSIFINDER_API_KEY")
+    if not key:
+        raise AuthenticationError(
+            "No API key provided. Pass api_key= or set the CLASSIFINDER_API_KEY environment variable."
+        )
+    return key
+
+
+def build_headers(api_key: str) -> Dict[str, str]:
+    """Build default request headers."""
+    return {
+        "X-API-Key": api_key,
+        "Content-Type": "application/json",
+    }
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Raise the appropriate ClassiFinderError for non-2xx responses."""
+    if response.status_code < 400:
+        return
+
+    try:
+        body = response.json()
+        error = body.get("error", {})
+        message = error.get("message", response.text)
+        code = error.get("code", "")
+        retry_after = error.get("retry_after")
+    except Exception:
+        message = response.text or f"HTTP {response.status_code}"
+        code = ""
+        retry_after = None
+
+    status = response.status_code
+
+    if status == 401:
+        raise AuthenticationError(message)
+    elif status == 400:
+        raise InvalidRequestError(message, code=code)
+    elif status == 403:
+        raise ForbiddenError(message, code=code)
+    elif status == 429:
+        raise RateLimitError(message, retry_after=retry_after or 0)
+    elif status >= 500:
+        raise ServerError(message)
+    else:
+        raise ClassiFinderError(message, status_code=status)
+
+
+def is_retryable(exc: Exception) -> bool:
+    """Check if an exception is retryable."""
+    if isinstance(exc, RateLimitError):
+        return True
+    if isinstance(exc, ServerError):
+        return True
+    if isinstance(exc, APIConnectionError):
+        return True
+    return False
+
+
+def get_retry_delay(attempt: int, exc: Exception) -> float:
+    """Calculate delay before next retry attempt."""
+    if isinstance(exc, RateLimitError) and exc.retry_after > 0:
+        return float(exc.retry_after)
+    return float(2**attempt)
+
+
+def sleep_for_retry(attempt: int, exc: Exception) -> None:
+    """Sleep before a sync retry."""
+    delay = get_retry_delay(attempt, exc)
+    time.sleep(delay)
+
+
+async def async_sleep_for_retry(attempt: int, exc: Exception) -> None:
+    """Sleep before an async retry."""
+    import asyncio
+    delay = get_retry_delay(attempt, exc)
+    await asyncio.sleep(delay)

classifinder-0.1.0/src/classifinder/_client.py

@@ -0,0 +1,139 @@
+"""Synchronous ClassiFinder client."""
+
+from typing import List, Optional
+
+import httpx
+
+from ._base import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    build_headers,
+    is_retryable,
+    raise_for_status,
+    resolve_api_key,
+    sleep_for_retry,
+)
+from ._exceptions import APIConnectionError
+from ._models import (
+    FeedbackResult,
+    HealthResult,
+    RedactResult,
+    ScanResult,
+    TypesResult,
+)
+
+
+class ClassiFinder:
+    """Synchronous client for the ClassiFinder API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = resolve_api_key(api_key)
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._client = httpx.Client(
+            headers=build_headers(self._api_key),
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._client.close()
+
+    def __enter__(self) -> "ClassiFinder":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        """Make an HTTP request with retry logic."""
+        url = f"{self._base_url}{path}"
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.request(method, url, **kwargs)
+                raise_for_status(response)
+                return response
+            except (httpx.TimeoutException, httpx.ConnectError, httpx.NetworkError) as exc:
+                api_exc = APIConnectionError(str(exc))
+                last_exc = api_exc
+                if attempt >= self._max_retries:
+                    raise api_exc from exc
+                sleep_for_retry(attempt, api_exc)
+            except Exception as exc:
+                last_exc = exc
+                if not is_retryable(exc) or attempt >= self._max_retries:
+                    raise
+                sleep_for_retry(attempt, exc)
+
+        raise last_exc  # pragma: no cover
+
+    def scan(
+        self,
+        text: str,
+        types: Optional[List[str]] = None,
+        min_confidence: float = 0.5,
+        include_context: bool = True,
+    ) -> ScanResult:
+        """Scan text for secrets."""
+        body = {
+            "text": text,
+            "types": types or ["all"],
+            "min_confidence": min_confidence,
+            "include_context": include_context,
+        }
+        response = self._request("POST", "/v1/scan", json=body)
+        return ScanResult.model_validate(response.json())
+
+    def redact(
+        self,
+        text: str,
+        types: Optional[List[str]] = None,
+        min_confidence: float = 0.5,
+        redaction_style: str = "label",
+    ) -> RedactResult:
+        """Scan and redact secrets from text."""
+        body = {
+            "text": text,
+            "types": types or ["all"],
+            "min_confidence": min_confidence,
+            "redaction_style": redaction_style,
+        }
+        response = self._request("POST", "/v1/redact", json=body)
+        return RedactResult.model_validate(response.json())
+
+    def get_types(self) -> TypesResult:
+        """List all detectable secret types."""
+        response = self._request("GET", "/v1/types")
+        return TypesResult.model_validate(response.json())
+
+    def health(self) -> HealthResult:
+        """Check API health."""
+        response = self._request("GET", "/v1/health")
+        return HealthResult.model_validate(response.json())
+
+    def feedback(
+        self,
+        request_id: str,
+        finding_id: str,
+        feedback_type: str,
+        comment: Optional[str] = None,
+    ) -> FeedbackResult:
+        """Report a false positive or false negative."""
+        body = {
+            "request_id": request_id,
+            "finding_id": finding_id,
+            "feedback_type": feedback_type,
+        }
+        if comment is not None:
+            body["comment"] = comment
+        response = self._request("POST", "/v1/feedback", json=body)
+        return FeedbackResult.model_validate(response.json())