needlesearchai 2.1.0__tar.gz

needlesearchai-2.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: needlesearchai
+Version: 2.1.0
+Summary: Python SDK for the NeedleSearch AI legal document search API
+License: MIT
+Project-URL: Homepage, https://needlesearch.ai
+Project-URL: Documentation, https://needlesearch.ai/docs
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+Requires-Dist: httpx>=0.27
+Provides-Extra: http
+Requires-Dist: httpx>=0.27; extra == "http"
+
+NeedleSearch Python SDK
+=======================
+
+Client for the NeedleSearch API — semantic search, grounded chat and deep
+research over your own document corpus.
+
+Install
+-------
+
+Not on PyPI yet. Install from the repository:
+
+.. code-block:: bash
+
+    pip install "git+https://github.com/Legal-Analytics-Inc/AI-LegalSearch#subdirectory=sdk/python"
+
+Once released the command becomes ``pip install needlesearchai``. Note the
+name: plain ``needlesearch`` on PyPI is an abandoned registration with no files
+behind it — it is not us, and installing it fails.
+
+Quick start
+-----------
+
+.. code-block:: python
+
+    from needlesearchai import NeedleSearch
+
+    ns = NeedleSearch(api_key="nsk_...", base_url="https://your-instance.com/v1")
+
+    # Is it us or is it you? Needs no key.
+    print(ns.status().status)
+
+    # Semantic search, optionally with an AI overview over the matches
+    results = ns.search("termination clauses")
+    answer = ns.search("How long is the notice period?", include_overview=True)
+
+    # Browse. Prefer iterate() over offset paging: it follows the cursor, which
+    # is stable while other people are uploading.
+    for item in ns.items.iterate():
+        print(item.name, item.status)
+
+    # Deep research. The async form survives proxies that cut long connections.
+    job = ns.jobs.create("What are the risks in this contract?", item_ids=[doc_id])
+    print(ns.jobs.wait(job.id).answer)
+
+Document status
+---------------
+
+``item.status`` is the published lifecycle — ``queued``, ``processing``,
+``ready``, ``failed``, ``cancelled`` — and is the one to branch on.
+``item.status_detail`` carries the pipeline's internal stage; it is useful in a
+log or a support ticket and carries no compatibility promise.
+
+.. code-block:: python
+
+    item = ns.items.get(doc_id)
+    if item.is_ready:
+        text = ns.items.content(doc_id)["markdown"]
+    elif item.is_terminal:
+        print("gave up:", item.error)
+
+Errors
+------
+
+Every failure raises a subclass of ``NeedleSearchError`` carrying the API's
+machine-readable code:
+
+.. code-block:: python
+
+    from needlesearchai import NeedleSearchError, RateLimitError
+
+    try:
+        ns.search("...")
+    except RateLimitError as e:
+        time.sleep(e.retry_after)
+    except NeedleSearchError as e:
+        print(e.error_code, e.status_code)  # e.g. "insufficient_scope", 403
+
+Webhooks
+--------
+
+Verify every delivery before trusting it. ``verify_signature`` does the two
+things a hand-rolled check usually gets wrong — a constant-time comparison, and
+rejecting a replayed capture by its timestamp:
+
+.. code-block:: python
+
+    from needlesearchai import verify_signature
+
+    # `raw_body` must be the bytes as received; re-serializing the parsed JSON
+    # changes them and the signature will not match.
+    if not verify_signature(secret, raw_body, request.headers["X-NeedleSearch-Signature"]):
+        return 400
+
+Retries
+-------
+
+Send an ``Idempotency-Key`` on anything you might retry — research runs and
+webhook registrations both cost something you do not want to pay twice:
+
+.. code-block:: python
+
+    job = ns.jobs.create("...", idempotency_key="batch-2026-02-01-run-7")
+    hook = ns.webhooks.create("https://example.com/hook", idempotency_key="hook-v1")
+
+License
+-------
+
+MIT

needlesearchai-2.1.0/README.rst

@@ -0,0 +1,108 @@
+NeedleSearch Python SDK
+=======================
+
+Client for the NeedleSearch API — semantic search, grounded chat and deep
+research over your own document corpus.
+
+Install
+-------
+
+Not on PyPI yet. Install from the repository:
+
+.. code-block:: bash
+
+    pip install "git+https://github.com/Legal-Analytics-Inc/AI-LegalSearch#subdirectory=sdk/python"
+
+Once released the command becomes ``pip install needlesearchai``. Note the
+name: plain ``needlesearch`` on PyPI is an abandoned registration with no files
+behind it — it is not us, and installing it fails.
+
+Quick start
+-----------
+
+.. code-block:: python
+
+    from needlesearchai import NeedleSearch
+
+    ns = NeedleSearch(api_key="nsk_...", base_url="https://your-instance.com/v1")
+
+    # Is it us or is it you? Needs no key.
+    print(ns.status().status)
+
+    # Semantic search, optionally with an AI overview over the matches
+    results = ns.search("termination clauses")
+    answer = ns.search("How long is the notice period?", include_overview=True)
+
+    # Browse. Prefer iterate() over offset paging: it follows the cursor, which
+    # is stable while other people are uploading.
+    for item in ns.items.iterate():
+        print(item.name, item.status)
+
+    # Deep research. The async form survives proxies that cut long connections.
+    job = ns.jobs.create("What are the risks in this contract?", item_ids=[doc_id])
+    print(ns.jobs.wait(job.id).answer)
+
+Document status
+---------------
+
+``item.status`` is the published lifecycle — ``queued``, ``processing``,
+``ready``, ``failed``, ``cancelled`` — and is the one to branch on.
+``item.status_detail`` carries the pipeline's internal stage; it is useful in a
+log or a support ticket and carries no compatibility promise.
+
+.. code-block:: python
+
+    item = ns.items.get(doc_id)
+    if item.is_ready:
+        text = ns.items.content(doc_id)["markdown"]
+    elif item.is_terminal:
+        print("gave up:", item.error)
+
+Errors
+------
+
+Every failure raises a subclass of ``NeedleSearchError`` carrying the API's
+machine-readable code:
+
+.. code-block:: python
+
+    from needlesearchai import NeedleSearchError, RateLimitError
+
+    try:
+        ns.search("...")
+    except RateLimitError as e:
+        time.sleep(e.retry_after)
+    except NeedleSearchError as e:
+        print(e.error_code, e.status_code)  # e.g. "insufficient_scope", 403
+
+Webhooks
+--------
+
+Verify every delivery before trusting it. ``verify_signature`` does the two
+things a hand-rolled check usually gets wrong — a constant-time comparison, and
+rejecting a replayed capture by its timestamp:
+
+.. code-block:: python
+
+    from needlesearchai import verify_signature
+
+    # `raw_body` must be the bytes as received; re-serializing the parsed JSON
+    # changes them and the signature will not match.
+    if not verify_signature(secret, raw_body, request.headers["X-NeedleSearch-Signature"]):
+        return 400
+
+Retries
+-------
+
+Send an ``Idempotency-Key`` on anything you might retry — research runs and
+webhook registrations both cost something you do not want to pay twice:
+
+.. code-block:: python
+
+    job = ns.jobs.create("...", idempotency_key="batch-2026-02-01-run-7")
+    hook = ns.webhooks.create("https://example.com/hook", idempotency_key="hook-v1")
+
+License
+-------
+
+MIT

needlesearchai-2.1.0/needlesearchai/__init__.py

@@ -0,0 +1,78 @@
+"""NeedleSearch Python SDK.
+
+Quick start:
+    from needlesearchai import NeedleSearch
+
+    ns = NeedleSearch(api_key="nsk_...")
+    results = ns.search("termination clauses")                      # vector search
+    overview = ns.search("notice period?", include_overview=True)   # search + AI answer
+    for chunk in ns.chat.stream("Explain promissory estoppel"):     # plain chat (no docs)
+        print(chunk.text, end="", flush=True)
+
+    for item in ns.items.iterate():                                 # browse, cursor-paged
+        print(item.name, item.status)
+
+    job = ns.jobs.create("Summarise the risks", item_ids=[doc_id])  # async research
+    print(ns.jobs.wait(job.id).answer)
+"""
+from needlesearchai.client import NeedleSearch
+from needlesearchai.exceptions import (
+    AuthError,
+    DocumentNotReadyError,
+    InsufficientScopeError,
+    NeedleSearchError,
+    NotFoundError,
+    QuotaError,
+    RateLimitError,
+    ServerError,
+)
+from needlesearchai.types import (
+    ChatChunk,
+    FileRecord,
+    Item,
+    ItemPage,
+    MeInfo,
+    QuotaInfo,
+    ResearchJob,
+    ResearchResult,
+    SearchResponse,
+    SearchResult,
+    ServiceStatus,
+    UploadJob,
+    UploadJobPage,
+    UploadResult,
+    Webhook,
+    WebhookDelivery,
+)
+from needlesearchai.webhooks import verify_signature
+
+__all__ = [
+    "NeedleSearch",
+    "NeedleSearchError",
+    "AuthError",
+    "InsufficientScopeError",
+    "RateLimitError",
+    "QuotaError",
+    "NotFoundError",
+    "ServerError",
+    "DocumentNotReadyError",
+    "SearchResult",
+    "SearchResponse",
+    "ChatChunk",
+    "FileRecord",
+    "UploadResult",
+    "QuotaInfo",
+    "MeInfo",
+    "ResearchResult",
+    "Item",
+    "ItemPage",
+    "ResearchJob",
+    "ServiceStatus",
+    "UploadJob",
+    "UploadJobPage",
+    "Webhook",
+    "WebhookDelivery",
+    "verify_signature",
+]
+
+__version__ = "2.1.0"

needlesearchai-2.1.0/needlesearchai/_http.py

@@ -0,0 +1,138 @@
+"""HTTP client wrapper with auth, retry, and error handling."""
+from __future__ import annotations
+
+import time
+from typing import Any, Generator
+
+try:
+    import httpx
+except ImportError as e:
+    raise ImportError("needlesearchai requires httpx. Install with: pip install needlesearchai[http]") from e
+
+from needlesearchai.exceptions import (
+    AuthError,
+    DocumentNotReadyError,
+    InsufficientScopeError,
+    NeedleSearchError,
+    NotFoundError,
+    QuotaError,
+    RateLimitError,
+    ServerError,
+)
+
+_DEFAULT_TIMEOUT = 30.0
+_STREAM_TIMEOUT  = 300.0
+_MAX_RETRIES     = 3
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        body = {}
+
+    error_code = body.get("error", "")
+    try:
+        raw_text = response.text[:300]
+    except Exception:
+        raw_text = ""
+    message = body.get("message", body.get("detail", raw_text))
+    status     = response.status_code
+
+    if status == 401:
+        raise AuthError(message or "Invalid or missing API key", status_code=status, error_code=error_code)
+    if status == 403:
+        if error_code == "insufficient_scope":
+            raise InsufficientScopeError(message, status_code=status, error_code=error_code)
+        raise AuthError(message, status_code=status, error_code=error_code)
+    if status == 404:
+        raise NotFoundError(message, status_code=status, error_code=error_code)
+    if status == 429:
+        if error_code == "monthly_quota_exceeded":
+            raise QuotaError(message, used=body.get("used"), limit=body.get("limit"))
+        retry_after = int(response.headers.get("Retry-After", 60))
+        raise RateLimitError(message, retry_after=retry_after)
+    if status == 400:
+        if error_code == "document_not_ready":
+            raise DocumentNotReadyError(message, status_code=status, error_code=error_code)
+        raise NeedleSearchError(message, status_code=status, error_code=error_code)
+    if status >= 500:
+        raise ServerError(message or f"Server error {status}", status_code=status)
+
+    raise NeedleSearchError(message or f"HTTP {status}", status_code=status, error_code=error_code)
+
+
+class HttpClient:
+    """Synchronous HTTP client with exponential backoff retry."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float = _DEFAULT_TIMEOUT):
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}", "User-Agent": "needlesearchai-python/1.0"},
+            timeout=timeout,
+        )
+
+    def get(self, path: str, **params) -> Any:
+        return self._request("GET", path, params=params or None)
+
+    def post(self, path: str, json: Any = None, *, idempotency_key: str | None = None) -> Any:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._request("POST", path, json=json, headers=headers)
+
+    def patch(self, path: str, json: Any = None) -> Any:
+        return self._request("PATCH", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self._request("DELETE", path)
+
+    def _request(self, method: str, path: str, **kwargs) -> Any:
+        for attempt in range(_MAX_RETRIES):
+            try:
+                # Drop unset optionals so httpx does not send empty headers.
+                call = {k: v for k, v in kwargs.items() if v is not None}
+                r = self._client.request(method, path, **call)
+                _raise_for_status(r)
+                return r.json() if r.content else None
+            except RateLimitError as e:
+                if attempt == _MAX_RETRIES - 1:
+                    raise
+                wait = min(e.retry_after, 30)
+                time.sleep(wait)
+            except (httpx.TimeoutException, httpx.NetworkError) as e:
+                if attempt == _MAX_RETRIES - 1:
+                    raise NeedleSearchError(f"Network error: {e}") from e
+                time.sleep(2 ** attempt)
+
+    def raw(self, method: str, path: str, **kwargs):
+        """A checked response with its body intact — for endpoints that return
+        bytes rather than JSON (file downloads)."""
+        r = self._client.request(method, path, **kwargs)
+        _raise_for_status(r)
+        return r
+
+    def stream(self, path: str, json: Any = None) -> Generator[str, None, None]:
+        """Yield raw SSE data lines from a streaming endpoint."""
+        with self._client.stream("POST", path, json=json, timeout=_STREAM_TIMEOUT) as r:
+            _raise_for_status(r)
+            parts: list[str] = []
+            for line in r.iter_lines():
+                if line.startswith("data:"):
+                    raw = line[5:]
+                    parts.append(raw[1:] if raw.startswith(" ") else raw)
+                elif line == "" and parts:
+                    yield "\n".join(parts)
+                    parts = []
+            if parts:
+                yield "\n".join(parts)
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

needlesearchai-2.1.0/needlesearchai/chat.py

@@ -0,0 +1,69 @@
+"""NeedleSearch SDK — Chat API with streaming support."""
+from __future__ import annotations
+import json
+from typing import Generator
+
+from needlesearchai.types import ChatChunk
+
+
+class ChatAPI:
+    """Wrapper for POST /v1/chat."""
+
+    def __init__(self, http):
+        self._http = http
+
+    def stream(
+        self,
+        message: str,
+        *,
+        provider: str | None = None,
+    ) -> Generator[ChatChunk, None, None]:
+        """Stream a plain chat response from the AI.
+
+        Conversational chat only — it does NOT read your documents. For
+        document-grounded answers use ``client.search(..., include_overview=True)``
+        or the research API.
+
+        Args:
+            message:   User question or instruction
+            provider:  LLM provider override ('deepseek', 'openai', 'anthropic')
+
+        Yields:
+            ChatChunk with .text containing the streaming text
+
+        Example:
+            for chunk in ns.chat.stream("Explain promissory estoppel"):
+                print(chunk.text, end="", flush=True)
+        """
+        body = {"message": message}
+        if provider:
+            body["provider"] = provider
+
+        for data_line in self._http.stream("/chat", json=body):
+            if not data_line:
+                continue
+            try:
+                payload = json.loads(data_line)
+                # Only yield actual text delta events
+                if isinstance(payload, str):
+                    yield ChatChunk(text=payload)
+                elif isinstance(payload, dict) and "text" in payload:
+                    yield ChatChunk(text=payload["text"])
+                elif isinstance(payload, dict) and payload.get("event") == "done":
+                    break
+            except (json.JSONDecodeError, TypeError):
+                # Plain text delta
+                if data_line and not data_line.startswith("{"):
+                    yield ChatChunk(text=data_line)
+
+    def complete(self, message: str, **kwargs) -> str:
+        """Non-streaming chat — collects all chunks and returns the full text.
+
+        Args:
+            message: User question or instruction
+            **kwargs: Same keyword arguments as stream()
+
+        Returns:
+            Complete AI response as a string
+        """
+        return "".join(chunk.text for chunk in self.stream(message, **kwargs))

needlesearchai-2.1.0/needlesearchai/client.py

@@ -0,0 +1,114 @@
+"""NeedleSearch Python SDK — main client."""
+from __future__ import annotations
+
+from needlesearchai._http import HttpClient
+from needlesearchai.chat import ChatAPI
+from needlesearchai.files import FilesAPI
+from needlesearchai.folders import FoldersAPI
+from needlesearchai.items import ItemsAPI
+from needlesearchai.jobs import ResearchJobsAPI
+from needlesearchai.research import ResearchAPI
+from needlesearchai.search import SearchAPI
+from needlesearchai.types import MeInfo, QuotaInfo, ServiceStatus
+from needlesearchai.uploads import UploadsAPI
+from needlesearchai.webhooks import WebhooksAPI
+
+_DEFAULT_BASE_URL = "https://your-instance.com/v1"
+
+
+class NeedleSearch:
+    """NeedleSearch API client.
+
+    Usage:
+        from needlesearchai import NeedleSearch
+
+        ns = NeedleSearch(api_key="nsk_...")
+
+        # Semantic search (optionally with an AI overview over your documents)
+        results = ns.search("What are the termination clauses?")
+        overview = ns.search("How long is the notice period?", include_overview=True)
+
+        # Streaming chat — plain conversation, does NOT read your documents
+        for chunk in ns.chat.stream("Explain promissory estoppel"):
+            print(chunk.text, end="", flush=True)
+
+        # Deep research over your documents (Starter+ plan)
+        answer = ns.research.complete("What are the risks in this contract?", document_ids=["..."])
+    """
+
+    def __init__(self, api_key: str, base_url: str = _DEFAULT_BASE_URL, timeout: float = 30.0):
+        """Create a NeedleSearch client.
+
+        Args:
+            api_key:  Your API key (starts with 'nsk_')
+            base_url: API base URL (default: https://your-instance.com/v1)
+            timeout:  Request timeout in seconds
+        """
+        if not api_key:
+            raise ValueError("api_key is required")
+        if not api_key.startswith("nsk_"):
+            raise ValueError("api_key must start with 'nsk_'")
+
+        self._http = HttpClient(api_key=api_key, base_url=base_url.rstrip("/"), timeout=timeout)
+
+        self.search   = SearchAPI(self._http)
+        self.chat     = ChatAPI(self._http)
+        self.research = ResearchAPI(self._http)
+        self.files    = FilesAPI(self._http)
+        self.items    = ItemsAPI(self._http)
+        self.folders  = FoldersAPI(self._http)
+        self.webhooks = WebhooksAPI(self._http)
+        self.jobs     = ResearchJobsAPI(self._http)
+        self.uploads  = UploadsAPI(self._http)
+
+    def status(self) -> ServiceStatus:
+        """Whether the API can currently serve each class of operation.
+
+        The one call that needs no key — so it still answers when the key itself
+        is the suspect. `down` means retry with backoff rather than debugging
+        your integration.
+        """
+        data = self._http.get("/status")
+        return ServiceStatus(
+            status=data.get("status", "unknown"),
+            services=data.get("services", {}),
+            api_version=data.get("api_version", "v1"),
+            checked_at=data.get("checked_at"),
+        )
+
+    def me(self) -> MeInfo:
+        """Return identity and plan information for this API key."""
+        data = self._http.get("/me")
+        return MeInfo(
+            key_prefix=data.get("key_prefix", ""),
+            name=data.get("name", ""),
+            plan=data.get("plan", "free"),
+            scopes=data.get("scopes", []),
+            organization_id=data.get("organization_id", ""),
+            features=data.get("features", {}),
+            created_at=data.get("created_at"),
+        )
+
+    def quota(self) -> QuotaInfo:
+        """Return current quota and plan status."""
+        data = self._http.get("/quota")
+        monthly = data.get("monthly_requests", {})
+        return QuotaInfo(
+            plan=data.get("plan", "free"),
+            monthly_limit=monthly.get("limit"),
+            monthly_used=monthly.get("used", 0),
+            monthly_remaining=monthly.get("remaining"),
+            rate_limit_rpm=data.get("rate_limit_rpm", 0),
+            features=data.get("features", {}),
+            reset_at=data.get("reset_at"),
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

needlesearchai-2.1.0/needlesearchai/exceptions.py

@@ -0,0 +1,47 @@
+"""NeedleSearch SDK exceptions."""
+
+
+class NeedleSearchError(Exception):
+    """Base exception for all NeedleSearch errors."""
+    def __init__(self, message: str, status_code: int | None = None, error_code: str | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({self.args[0]!r}, status_code={self.status_code})"
+
+
+class AuthError(NeedleSearchError):
+    """API key missing, invalid, revoked, or expired."""
+
+
+class InsufficientScopeError(NeedleSearchError):
+    """API key lacks the required scope for this operation."""
+
+
+class RateLimitError(NeedleSearchError):
+    """Rate limit exceeded. Check retry_after for seconds to wait."""
+    def __init__(self, message: str, retry_after: int = 60):
+        super().__init__(message, status_code=429, error_code="rate_limit_exceeded")
+        self.retry_after = retry_after
+
+
+class QuotaError(NeedleSearchError):
+    """Monthly request quota exceeded."""
+    def __init__(self, message: str, used: int | None = None, limit: int | None = None):
+        super().__init__(message, status_code=429, error_code="monthly_quota_exceeded")
+        self.used = used
+        self.limit = limit
+
+
+class NotFoundError(NeedleSearchError):
+    """Requested resource not found."""
+
+
+class ServerError(NeedleSearchError):
+    """Internal server error."""
+
+
+class DocumentNotReadyError(NeedleSearchError):
+    """Document is still being processed."""