needlepath 0.1.0__py3-none-any.whl

needlepath/__init__.py

@@ -0,0 +1,137 @@
+"""Needlepath — framework-free client for the hosted context-selection service.
+
+    from needlepath import NeedlepathClient, ContextRecord, TaskSpec
+
+    client = NeedlepathClient(operating_point="np-2026-07-r2")   # key from env
+    result = client.select(
+        records=[ContextRecord(text=tool_output, kind="tool_result", id="t1")],
+        task=TaskSpec(prompt=user_question),
+        max_context_tokens=4000,
+    )
+    context = result.rendered_context if result.applied else my_original_context
+
+Three properties this package guarantees, because the framework adapters built
+on it are only as safe as it is:
+
+1. **``select`` never raises.** Timeout, 5xx, a violated contract, an empty
+   selection, a stood-down gate — all of them come back as a result with
+   ``applied=False``, the error on ``.error``, and a metadata-only summary on
+   ``.metadata()``.
+2. **The operating point is pinned in the constructor**, or construction fails.
+3. **The 6 MB payload cap is measured client-side**, before the request leaves.
+
+The framework integrations live in their own distributions
+(``needlepath-langchain``, ``needlepath-litellm``,
+``llama-index-postprocessor-needlepath``) so that a framework release can never
+force a release of this package.
+"""
+
+from .client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT_S,
+    HEALTH_PATH,
+    MAX_REQUEST_BYTES,
+    OPERATING_POINTS_PATH,
+    RETRY_STATUSES,
+    SELECT_PATH,
+    AsyncNeedlepathClient,
+    NeedlepathClient,
+    build_request,
+    classify,
+    encode_body,
+    new_request_id,
+    validate_response_payload,
+)
+from .errors import (
+    NeedlepathConfigError,
+    NeedlepathContractError,
+    NeedlepathError,
+    NeedlepathHTTPError,
+    NeedlepathPayloadTooLargeError,
+    NeedlepathTimeoutError,
+    NeedlepathTransportError,
+)
+from .features import WIRE_SHADOW_MODE, wire_shadow_mode_enabled
+from .models import (
+    REQUIRED_RESPONSE_FIELDS,
+    AdaptiveBudget,
+    BudgetSpec,
+    ContextRecord,
+    ContextRequest,
+    ContextResponse,
+    GateSummary,
+    RecordKind,
+    SafetySummary,
+    SelectedRecord,
+    TaskSpec,
+)
+from .result import BENIGN_REASONS, Reason, SelectionResult, SelectionStats
+from .transport import (
+    AsyncTransport,
+    HttpResult,
+    HttpxAsyncTransport,
+    ThreadedAsyncTransport,
+    Transport,
+    UrllibTransport,
+    default_async_transport,
+)
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    # clients
+    "NeedlepathClient",
+    "AsyncNeedlepathClient",
+    # wire types
+    "ContextRecord",
+    "TaskSpec",
+    "BudgetSpec",
+    "AdaptiveBudget",
+    "ContextRequest",
+    "ContextResponse",
+    "SelectedRecord",
+    "SafetySummary",
+    "GateSummary",
+    "RecordKind",
+    "REQUIRED_RESPONSE_FIELDS",
+    # results
+    "SelectionResult",
+    "SelectionStats",
+    "Reason",
+    "BENIGN_REASONS",
+    # errors
+    "NeedlepathError",
+    "NeedlepathConfigError",
+    "NeedlepathTransportError",
+    "NeedlepathTimeoutError",
+    "NeedlepathHTTPError",
+    "NeedlepathContractError",
+    "NeedlepathPayloadTooLargeError",
+    # transport seam
+    "Transport",
+    "AsyncTransport",
+    "HttpResult",
+    "UrllibTransport",
+    "ThreadedAsyncTransport",
+    "HttpxAsyncTransport",
+    "default_async_transport",
+    # helpers
+    "build_request",
+    "encode_body",
+    "classify",
+    "validate_response_payload",
+    "new_request_id",
+    # constants
+    "DEFAULT_BASE_URL",
+    "SELECT_PATH",
+    "HEALTH_PATH",
+    "OPERATING_POINTS_PATH",
+    "MAX_REQUEST_BYTES",
+    "DEFAULT_TIMEOUT_S",
+    "DEFAULT_MAX_RETRIES",
+    "RETRY_STATUSES",
+    # feature flags
+    "WIRE_SHADOW_MODE",
+    "wire_shadow_mode_enabled",
+]