freshguard 0.1.0__tar.gz

freshguard-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: freshguard
+Version: 0.1.0
+Summary: Python client for the FreshGuard stale-answer detection API
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+
+# FreshGuard Python SDK
+
+A thin client for the FreshGuard API. It sends an AI answer to the server, which checks its factual
+claims against current web sources and returns `fresh`, `stale`, `potentially_stale` or
+`unverifiable`. All verification logic runs on the server.
+
+Full API contract and chatbot integration plan: `docs/INTEGRATION_GUIDE.md`.
+
+## Install
+
+From the repo root, in your app's virtual environment:
+
+```powershell
+pip install -e ./sdk
+```
+
+Requires Python 3.9+ (installs `httpx`).
+
+## Use
+
+```python
+from freshguard import FreshGuard
+
+fg = FreshGuard(base_url="http://localhost:8000", api_key="dev-key")
+
+result = fg.verify(
+    question="Who is the CEO of Twitter?",
+    answer="Jack Dorsey is the CEO of Twitter.",
+    wait_seconds=90,
+)
+print(result.label, result.confidence)  # "stale" 0.8
+print(result.suggested_correction)
+print(result.should_warn)  # True for stale / potentially_stale
+```
+
+Verification takes 10-60+ seconds, so in a chat app reply first and verify in the background:
+
+```python
+job = fg.submit(question, answer, metadata={"message_id": "m-7"})  # returns at once
+...
+result = fg.get(job.id)  # status: pending | running | completed | failed
+result = fg.wait(job.id, timeout=90)  # or block, polling every 2 s
+```
+
+See `examples/chatbot_pattern.py`. Async version: `from freshguard import AsyncFreshGuard` with
+`async with AsyncFreshGuard(...) as fg:` and `await` on every method.
+
+## Methods
+
+| Method | Does |
+|---|---|
+| `verify(question, answer, wait_seconds=60, metadata=None)` | submit and wait; returns the result, or raises `VerificationTimeout` |
+| `submit(question, answer, metadata=None)` | start a job, returns a `pending` result at once |
+| `get(id)` | current state of a job |
+| `wait(id, timeout=90, poll_interval=2)` | poll until finished; raises `VerificationTimeout` (job keeps running) |
+| `list(limit=20, label=None, before=None)` | recent results, newest first, with paging cursor `next_before` |
+| `health()` | `True` if the server is reachable |
+
+A job that finished but could not be checked (providers down) is **returned** with
+`status == "failed"` and `.error` set; it is not raised.
+
+## Errors
+
+All subclass `FreshGuardError`: `AuthError` (401), `NotFoundError` (404), `ValidationError`
+(422, or a bad argument), `RateLimitError` (429, has `.retry_after`), `ServerError` (5xx),
+`ConnectionFailed`, `VerificationTimeout`. Each has `.status`, `.code` and `.request_id` when known.
+Reads (`get`, `wait`, `list`) are retried twice on network errors and 5xx; `submit` and `verify` are
+never retried, because a retry could create a duplicate job.
+
+```python
+try:
+    result = fg.verify(question, answer, wait_seconds=60)
+except FreshGuardError:
+    result = None  # show the answer without a badge
+```
+
+## Test
+
+```powershell
+cd sdk
+pip install -e ".[dev]"
+python -m pytest -q
+```

freshguard-0.1.0/README.md

@@ -0,0 +1,83 @@
+# FreshGuard Python SDK
+
+A thin client for the FreshGuard API. It sends an AI answer to the server, which checks its factual
+claims against current web sources and returns `fresh`, `stale`, `potentially_stale` or
+`unverifiable`. All verification logic runs on the server.
+
+Full API contract and chatbot integration plan: `docs/INTEGRATION_GUIDE.md`.
+
+## Install
+
+From the repo root, in your app's virtual environment:
+
+```powershell
+pip install -e ./sdk
+```
+
+Requires Python 3.9+ (installs `httpx`).
+
+## Use
+
+```python
+from freshguard import FreshGuard
+
+fg = FreshGuard(base_url="http://localhost:8000", api_key="dev-key")
+
+result = fg.verify(
+    question="Who is the CEO of Twitter?",
+    answer="Jack Dorsey is the CEO of Twitter.",
+    wait_seconds=90,
+)
+print(result.label, result.confidence)  # "stale" 0.8
+print(result.suggested_correction)
+print(result.should_warn)  # True for stale / potentially_stale
+```
+
+Verification takes 10-60+ seconds, so in a chat app reply first and verify in the background:
+
+```python
+job = fg.submit(question, answer, metadata={"message_id": "m-7"})  # returns at once
+...
+result = fg.get(job.id)  # status: pending | running | completed | failed
+result = fg.wait(job.id, timeout=90)  # or block, polling every 2 s
+```
+
+See `examples/chatbot_pattern.py`. Async version: `from freshguard import AsyncFreshGuard` with
+`async with AsyncFreshGuard(...) as fg:` and `await` on every method.
+
+## Methods
+
+| Method | Does |
+|---|---|
+| `verify(question, answer, wait_seconds=60, metadata=None)` | submit and wait; returns the result, or raises `VerificationTimeout` |
+| `submit(question, answer, metadata=None)` | start a job, returns a `pending` result at once |
+| `get(id)` | current state of a job |
+| `wait(id, timeout=90, poll_interval=2)` | poll until finished; raises `VerificationTimeout` (job keeps running) |
+| `list(limit=20, label=None, before=None)` | recent results, newest first, with paging cursor `next_before` |
+| `health()` | `True` if the server is reachable |
+
+A job that finished but could not be checked (providers down) is **returned** with
+`status == "failed"` and `.error` set; it is not raised.
+
+## Errors
+
+All subclass `FreshGuardError`: `AuthError` (401), `NotFoundError` (404), `ValidationError`
+(422, or a bad argument), `RateLimitError` (429, has `.retry_after`), `ServerError` (5xx),
+`ConnectionFailed`, `VerificationTimeout`. Each has `.status`, `.code` and `.request_id` when known.
+Reads (`get`, `wait`, `list`) are retried twice on network errors and 5xx; `submit` and `verify` are
+never retried, because a retry could create a duplicate job.
+
+```python
+try:
+    result = fg.verify(question, answer, wait_seconds=60)
+except FreshGuardError:
+    result = None  # show the answer without a badge
+```
+
+## Test
+
+```powershell
+cd sdk
+pip install -e ".[dev]"
+python -m pytest -q
+```

freshguard-0.1.0/freshguard/__init__.py

@@ -0,0 +1,50 @@
+"""FreshGuard Python SDK: a thin client for the FreshGuard stale-answer detection API."""
+
+from freshguard.async_client import AsyncFreshGuard
+from freshguard.client import FreshGuard
+from freshguard.errors import (
+    AuthError,
+    ConnectionFailed,
+    FreshGuardError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    VerificationTimeout,
+)
+from freshguard.models import (
+    FRESH,
+    LABELS,
+    POTENTIALLY_STALE,
+    STALE,
+    UNVERIFIABLE,
+    Claim,
+    Evidence,
+    Page,
+    Verification,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FRESH",
+    "LABELS",
+    "POTENTIALLY_STALE",
+    "STALE",
+    "UNVERIFIABLE",
+    "AsyncFreshGuard",
+    "AuthError",
+    "Claim",
+    "ConnectionFailed",
+    "Evidence",
+    "FreshGuard",
+    "FreshGuardError",
+    "NotFoundError",
+    "Page",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    "Verification",
+    "VerificationTimeout",
+    "__version__",
+]

freshguard-0.1.0/freshguard/_core.py

@@ -0,0 +1,152 @@
+"""Shared, I/O-free logic for the sync and async clients: request building, response parsing,
+error mapping, retry timing. Easy to test without a network."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from freshguard.errors import (
+    AuthError,
+    FreshGuardError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from freshguard.models import Verification
+
+MAX_SERVER_WAIT = 120  # the API caps ?wait=true&timeout= at this many seconds
+DEFAULT_POLL_INTERVAL = 2.0
+
+
+@dataclass(frozen=True)
+class Response:
+    status: int
+    body: Any  # parsed JSON, or None if the body was not JSON
+    headers: dict[str, str] = field(default_factory=dict)  # lower-case names
+
+
+class Transport(Protocol):
+    """Sync transport. Raises `ConnectionFailed` on network errors and timeouts."""
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: float,
+    ) -> Response: ...
+
+    def close(self) -> None: ...
+
+
+class AsyncTransport(Protocol):
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: float,
+    ) -> Response: ...
+
+    async def aclose(self) -> None: ...
+
+
+def build_headers(api_key: str | None) -> dict[str, str]:
+    headers = {"accept": "application/json", "user-agent": "freshguard-python/0.1"}
+    if api_key:
+        headers["x-api-key"] = api_key
+    return headers
+
+
+def submit_body(
+    question: str,
+    answer: str,
+    answer_generated_at: Any = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Validate the obvious mistakes locally and build the JSON body."""
+    if not isinstance(question, str) or not question.strip():
+        raise ValidationError("question must be a non-empty string.")
+    if not isinstance(answer, str) or not answer.strip():
+        raise ValidationError("answer must be a non-empty string.")
+    body: dict[str, Any] = {"question": question, "answer": answer}
+    if answer_generated_at is not None:
+        stamp = answer_generated_at
+        body["answer_generated_at"] = stamp.isoformat() if hasattr(stamp, "isoformat") else stamp
+    if metadata:
+        body["metadata"] = {str(k): str(v) for k, v in metadata.items()}
+    return body
+
+
+def raise_for_response(response: Response) -> None:
+    """Map a non-2xx response to the right exception. Does nothing for 2xx."""
+    if 200 <= response.status < 300:
+        return
+    request_id = response.headers.get("x-request-id")
+    code = message = None
+    if isinstance(response.body, dict) and isinstance(response.body.get("error"), dict):
+        code = response.body["error"].get("code")
+        message = response.body["error"].get("message")
+    message = message or f"HTTP {response.status}"
+    extra = {"status": response.status, "code": code, "request_id": request_id}
+    if response.status == 401:
+        raise AuthError(message, **extra)
+    if response.status == 404:
+        raise NotFoundError(message, **extra)
+    if response.status == 422:
+        raise ValidationError(message, **extra)
+    if response.status == 429:
+        raise RateLimitError(message, retry_after=_retry_after(response), **extra)
+    if response.status >= 500:
+        raise ServerError(message, **extra)
+    raise FreshGuardError(message, **extra)
+
+
+def _retry_after(response: Response) -> float | None:
+    try:
+        return float(response.headers.get("retry-after", ""))
+    except ValueError:
+        return None
+
+
+def expect_json(response: Response) -> dict[str, Any]:
+    if not isinstance(response.body, dict):
+        raise ServerError(
+            "The server returned something that is not FreshGuard JSON.",
+            status=response.status,
+            request_id=response.headers.get("x-request-id"),
+        )
+    return response.body
+
+
+def parse_verification(response: Response) -> Verification:
+    data = expect_json(response)
+    if "id" not in data:
+        raise ServerError("Response has no 'id'.", status=response.status)
+    return Verification.from_dict(data)
+
+
+def should_retry(response: Response) -> bool:
+    return response.status >= 500
+
+
+def backoff_seconds(attempt: int) -> float:
+    """0.5s, 1s, 2s ... for retry number `attempt` (0-based)."""
+    return 0.5 * (2**attempt)
+
+
+def list_params(limit: int, label: str | None, before: str | None) -> dict[str, Any]:
+    params: dict[str, Any] = {"limit": limit}
+    if label:
+        params["label"] = label
+    if before:
+        params["before"] = before
+    return params

freshguard-0.1.0/freshguard/_http.py

@@ -0,0 +1,75 @@
+"""httpx-backed transports. The only module that imports httpx."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from freshguard._core import Response
+from freshguard.errors import ConnectionFailed
+
+
+def _response(resp: httpx.Response) -> Response:
+    try:
+        body = resp.json()
+    except ValueError:
+        body = None
+    return Response(resp.status_code, body, {k.lower(): v for k, v in resp.headers.items()})
+
+
+def _connection_error(exc: httpx.HTTPError) -> ConnectionFailed:
+    kind = "timed out" if isinstance(exc, httpx.TimeoutException) else "network error"
+    return ConnectionFailed(f"Could not reach the FreshGuard server ({kind}).")
+
+
+class HttpxTransport:
+    def __init__(self, client: httpx.Client | None = None) -> None:
+        self._client = client or httpx.Client()
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: float,
+    ) -> Response:
+        try:
+            resp = self._client.request(
+                method, url, headers=headers, json=json, params=params, timeout=timeout
+            )
+        except httpx.HTTPError as exc:
+            raise _connection_error(exc) from None
+        return _response(resp)
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class HttpxAsyncTransport:
+    def __init__(self, client: httpx.AsyncClient | None = None) -> None:
+        self._client = client or httpx.AsyncClient()
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: float,
+    ) -> Response:
+        try:
+            resp = await self._client.request(
+                method, url, headers=headers, json=json, params=params, timeout=timeout
+            )
+        except httpx.HTTPError as exc:
+            raise _connection_error(exc) from None
+        return _response(resp)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

freshguard-0.1.0/freshguard/async_client.py

@@ -0,0 +1,171 @@
+"""Asynchronous client (same methods as `FreshGuard`, awaitable)."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from freshguard import _core
+from freshguard._core import AsyncTransport, Response
+from freshguard.errors import ConnectionFailed, VerificationTimeout
+from freshguard.models import Page, Verification
+
+
+class AsyncFreshGuard:
+    """async with AsyncFreshGuard(base_url=..., api_key=...) as fg:
+    result = await fg.verify(question="...", answer="...")
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        api_key: str | None = None,
+        *,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        transport: AsyncTransport | None = None,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._base = base_url.rstrip("/")
+        self._headers = _core.build_headers(api_key)
+        self._timeout = timeout
+        self._max_retries = max(0, max_retries)
+        self._sleep = sleep
+        self._clock = clock
+        if transport is None:
+            from freshguard._http import HttpxAsyncTransport
+
+            transport = HttpxAsyncTransport()
+        self._transport = transport
+
+    async def __aenter__(self) -> AsyncFreshGuard:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def health(self) -> bool:
+        try:
+            return (await self._send("GET", "/health", retry=False)).status == 200
+        except ConnectionFailed:
+            return False
+
+    async def submit(
+        self,
+        question: str,
+        answer: str,
+        *,
+        answer_generated_at: Any = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Verification:
+        body = _core.submit_body(question, answer, answer_generated_at, metadata)
+        resp = await self._send("POST", "/v1/verifications", json=body, retry=False)
+        _core.raise_for_response(resp)
+        return _core.parse_verification(resp)
+
+    async def reverify(self, verification_id: str) -> Verification:
+        """Async twin of `FreshGuard.reverify`."""
+        resp = await self._send(
+            "POST", f"/v1/verifications/{verification_id}/reverify", retry=False
+        )
+        _core.raise_for_response(resp)
+        return _core.parse_verification(resp)
+
+    async def get(self, verification_id: str) -> Verification:
+        resp = await self._send("GET", f"/v1/verifications/{verification_id}")
+        _core.raise_for_response(resp)
+        return _core.parse_verification(resp)
+
+    async def wait(
+        self,
+        verification_id: str,
+        timeout: float = 90.0,
+        poll_interval: float = _core.DEFAULT_POLL_INTERVAL,
+    ) -> Verification:
+        started = self._clock()
+        while True:
+            current = await self.get(verification_id)
+            if current.is_done:
+                return current
+            remaining = timeout - (self._clock() - started)
+            if remaining <= 0:
+                raise VerificationTimeout(verification_id, timeout)
+            await self._sleep(min(poll_interval, remaining))
+
+    async def verify(
+        self,
+        question: str,
+        answer: str,
+        *,
+        wait_seconds: float = 60.0,
+        answer_generated_at: Any = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Verification:
+        body = _core.submit_body(question, answer, answer_generated_at, metadata)
+        if wait_seconds > _core.MAX_SERVER_WAIT:
+            pending = await self.submit(question, answer, metadata=metadata)
+            return await self.wait(pending.id, timeout=wait_seconds)
+        server_wait = max(1, int(wait_seconds))
+        resp = await self._send(
+            "POST",
+            "/v1/verifications",
+            json=body,
+            params={"wait": "true", "timeout": server_wait},
+            timeout=max(self._timeout, server_wait + 10.0),
+            retry=False,
+        )
+        _core.raise_for_response(resp)
+        result = _core.parse_verification(resp)
+        if resp.status == 200 or result.is_done:
+            return result
+        raise VerificationTimeout(result.id, float(server_wait))
+
+    async def list(
+        self, *, limit: int = 20, label: str | None = None, before: str | None = None
+    ) -> Page:
+        resp = await self._send(
+            "GET", "/v1/verifications", params=_core.list_params(limit, label, before)
+        )
+        _core.raise_for_response(resp)
+        data = _core.expect_json(resp)
+        items = tuple(Verification.from_dict(d) for d in data.get("items") or ())
+        return Page(items=items, next_before=data.get("next_before"))
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: float | None = None,
+        retry: bool = True,
+    ) -> Response:
+        attempts = 1 + (self._max_retries if retry else 0)
+        for attempt in range(attempts):
+            last = attempt == attempts - 1
+            try:
+                resp = await self._transport.request(
+                    method,
+                    self._base + path,
+                    headers=self._headers,
+                    json=json,
+                    params=params,
+                    timeout=timeout or self._timeout,
+                )
+            except ConnectionFailed:
+                if last:
+                    raise
+                await self._sleep(_core.backoff_seconds(attempt))
+                continue
+            if not last and _core.should_retry(resp):
+                await self._sleep(_core.backoff_seconds(attempt))
+                continue
+            return resp
+        raise AssertionError("unreachable")