parcle 0.1.0__py3-none-any.whl

parcle/__init__.py

@@ -0,0 +1,79 @@
+"""Parcle — long-term memory for AI agents.
+
+Ingest conversations and files into a per-user memory, then ask questions in
+natural language and get cited answers back.
+
+    from parcle import Parcle
+
+    client = Parcle(api_key="pk_live_...")
+    client.ingest_dialog(user_id="ada", messages=[{"role": "user", "content": "..."}])
+    result = client.search(user_id="ada", query="What food should I avoid?")
+    print(result.answer, result.confidence, result.citations)
+"""
+
+from __future__ import annotations
+
+from .client import Parcle
+from .exceptions import (
+    AuthenticationError,
+    FileTooLargeError,
+    InternalServerError,
+    InvalidRequestError,
+    NotFoundError,
+    ParcleAPIError,
+    ParcleConfigError,
+    ParcleConnectionError,
+    ParcleError,
+    ParcleTimeoutError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UnsupportedFileTypeError,
+    ValidationError,
+)
+from .models import (
+    Citation,
+    DeleteResult,
+    Event,
+    IngestDialogResult,
+    IngestFileResult,
+    Message,
+    SearchResult,
+    Session,
+    Source,
+    SourcesPage,
+    User,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Parcle",
+    "__version__",
+    # models
+    "Citation",
+    "DeleteResult",
+    "Event",
+    "IngestDialogResult",
+    "IngestFileResult",
+    "Message",
+    "SearchResult",
+    "Session",
+    "Source",
+    "SourcesPage",
+    "User",
+    # exceptions
+    "ParcleError",
+    "ParcleConfigError",
+    "ParcleConnectionError",
+    "ParcleTimeoutError",
+    "ParcleAPIError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "NotFoundError",
+    "FileTooLargeError",
+    "UnsupportedFileTypeError",
+    "ValidationError",
+    "RateLimitError",
+    "InternalServerError",
+    "ServiceUnavailableError",
+]

parcle/client.py

@@ -0,0 +1,527 @@
+"""Synchronous client for the Parcle Memory API."""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, IO, List, Mapping, Optional, Sequence, Tuple, Union
+
+import httpx
+
+from .exceptions import (
+    ParcleAPIError,
+    ParcleConfigError,
+    ParcleConnectionError,
+    ParcleTimeoutError,
+    error_from_response,
+)
+from .models import (
+    DeleteResult,
+    Event,
+    IngestDialogResult,
+    IngestFileResult,
+    Message,
+    SearchResult,
+    Session,
+    Source,
+    SourcesPage,
+    User,
+)
+
+__all__ = ["Parcle"]
+
+DEFAULT_BASE_URL = "https://api.parcle.ai"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+# Statuses worth retrying with backoff: rate limit, server error, unavailable.
+_RETRY_STATUS = frozenset({429, 500, 503})
+
+# Content types for the supported upload extensions, filling gaps left by the
+# stdlib's ``mimetypes`` (which does not know markdown, for example).
+_EXTRA_CONTENT_TYPES = {
+    ".md": "text/markdown",
+    ".markdown": "text/markdown",
+    ".msg": "application/vnd.ms-outlook",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".xlsm": "application/vnd.ms-excel.sheet.macroEnabled.12",
+    ".tsv": "text/tab-separated-values",
+}
+
+# What ``ingest_file`` accepts for ``file``: a path, a binary stream, raw bytes,
+# or a ``(filename, content[, content_type])`` tuple.
+FileInput = Union[
+    str,
+    os.PathLike,
+    IO[bytes],
+    bytes,
+    Tuple[str, Union[bytes, IO[bytes]]],
+    Tuple[str, Union[bytes, IO[bytes]], Optional[str]],
+]
+
+# A message passed to ``ingest_dialog``: a plain dict or a ``Message``.
+MessageInput = Union[Mapping[str, Any], Message]
+
+# A tag / tag_filter mapping.
+TagFilter = Mapping[str, Any]
+
+
+class Parcle:
+    """Client for the Parcle Memory API.
+
+    Parameters
+    ----------
+    api_key:
+        Your Parcle API key. If omitted, the ``PARCLE_API_KEY`` environment
+        variable is used.
+    base_url:
+        Override the API base URL (e.g. for a staging environment).
+    timeout:
+        Per-request timeout in seconds.
+    max_retries:
+        How many times to retry a request that fails with a retryable status
+        (429/500/503) or a connection error, using exponential backoff.
+    http_client:
+        Bring your own configured :class:`httpx.Client` (proxies, custom
+        transport, …). Its lifetime is then yours to manage.
+
+    The client may be used as a context manager to ensure the underlying
+    connection pool is closed::
+
+        with Parcle() as client:
+            client.search(user_id="ada", query="...")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        key = api_key or os.environ.get("PARCLE_API_KEY")
+        if not key:
+            raise ParcleConfigError(
+                "No API key provided. Pass api_key=... or set the "
+                "PARCLE_API_KEY environment variable."
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max(0, int(max_retries))
+
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+
+    # -- lifecycle -------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP client, if this instance owns it."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "Parcle":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # -- users -----------------------------------------------------------------
+
+    def create_user(
+        self,
+        user_id: Optional[str] = None,
+        *,
+        name: Optional[str] = None,
+        timezone: Optional[str] = None,
+    ) -> User:
+        """Create or update a user.
+
+        Omit ``user_id`` to let Parcle generate one. ``timezone`` is an IANA
+        zone used only to interpret relative time in searches.
+        """
+        payload = _drop_none(
+            {"user_id": user_id, "name": name, "timezone": timezone}
+        )
+        data = self._request("POST", "/v1/users", json_body=payload)
+        return User.from_dict(data)
+
+    # -- ingestion -------------------------------------------------------------
+
+    def ingest_dialog(
+        self,
+        user_id: str,
+        messages: Sequence[MessageInput],
+        *,
+        session_id: Optional[str] = None,
+        tag: Optional[TagFilter] = None,
+    ) -> IngestDialogResult:
+        """Append dialog messages to a user's memory.
+
+        Omit ``session_id`` to start a new session; pass one to append. ``tag``
+        applies only when a new session is created.
+        """
+        payload: Dict[str, Any] = {
+            "user_id": user_id,
+            "session_id": session_id,
+            "messages": [_message_to_dict(m) for m in messages],
+        }
+        if tag is not None:
+            payload["tag"] = dict(tag)
+        data = self._request(
+            "POST", "/v1/memories/ingest_dialog", json_body=payload
+        )
+        return IngestDialogResult.from_dict(data)
+
+    def ingest_file(
+        self,
+        user_id: str,
+        file: FileInput,
+        *,
+        updated_at: Optional[str] = None,
+        tag: Optional[TagFilter] = None,
+    ) -> IngestFileResult:
+        """Upload a file into a user's memory.
+
+        ``file`` may be a path, an open binary stream, raw ``bytes``, or a
+        ``(filename, content[, content_type])`` tuple. For streams and bytes a
+        filename is required either via the stream's ``.name`` or the tuple form.
+        """
+        filename, content, content_type = _prepare_file(file)
+        files = {"file": (filename, content, content_type)}
+        form: Dict[str, Any] = {"user_id": user_id}
+        if updated_at is not None:
+            form["updated_at"] = updated_at
+        if tag is not None:
+            form["tag"] = json.dumps(tag)
+        data = self._request(
+            "POST", "/v1/memories/ingest_files", files=files, data=form
+        )
+        return IngestFileResult.from_dict(data)
+
+    # -- events ----------------------------------------------------------------
+
+    def get_event(self, user_id: str, event_id: str) -> Event:
+        """Fetch the ingestion status for a single write."""
+        data = self._request(
+            "POST",
+            "/v1/memories/events",
+            json_body={"user_id": user_id, "event_id": event_id},
+        )
+        return Event.from_dict(data)
+
+    def wait_until_ready(
+        self,
+        user_id: str,
+        event_id: str,
+        *,
+        poll_interval: float = 2.0,
+        timeout: Optional[float] = 120.0,
+        raise_on_failed: bool = True,
+    ) -> Event:
+        """Poll :meth:`get_event` until the event is ready or failed.
+
+        Returns the terminal :class:`~parcle.models.Event`. Raises
+        :class:`~parcle.exceptions.ParcleTimeoutError` if ``timeout`` seconds
+        pass first, and (by default) :class:`~parcle.exceptions.ParcleAPIError`
+        if ingestion failed.
+        """
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            event = self.get_event(user_id, event_id)
+            if event.is_terminal:
+                if event.is_failed and raise_on_failed:
+                    raise ParcleAPIError(
+                        event.error or "Ingestion failed.",
+                        code="ingestion_failed",
+                    )
+                return event
+            if deadline is not None and time.monotonic() >= deadline:
+                raise ParcleTimeoutError(
+                    f"Event {event_id!r} not ready after {timeout}s "
+                    f"(last status: {event.status})."
+                )
+            time.sleep(poll_interval)
+
+    # -- search ----------------------------------------------------------------
+
+    def search(
+        self,
+        user_id: str,
+        query: str,
+        *,
+        tag_filter: Optional[TagFilter] = None,
+        timezone: Optional[str] = None,
+    ) -> SearchResult:
+        """Ask a natural-language question over a user's memory.
+
+        Returns an ``answer`` grounded in source ``citations``, with a
+        ``confidence`` in ``[0, 1]``.
+        """
+        payload = _drop_none(
+            {
+                "user_id": user_id,
+                "query": query,
+                "tag_filter": dict(tag_filter) if tag_filter is not None else None,
+                "timezone": timezone,
+            }
+        )
+        data = self._request("POST", "/v1/memories/search", json_body=payload)
+        return SearchResult.from_dict(data)
+
+    # -- sources & sessions ----------------------------------------------------
+
+    def list_sources(
+        self,
+        user_id: str,
+        *,
+        type: Optional[str] = None,
+        tag_filter: Optional[TagFilter] = None,
+        page: int = 1,
+        limit: int = 50,
+        order: str = "desc",
+    ) -> SourcesPage:
+        """List a user's sources (dialog sessions and files), page by page.
+
+        ``type`` is ``"session"`` or ``"file"``; omit for both.
+        """
+        payload = _drop_none(
+            {
+                "user_id": user_id,
+                "type": type,
+                "tag_filter": dict(tag_filter) if tag_filter is not None else None,
+                "page": page,
+                "limit": limit,
+                "order": order,
+            }
+        )
+        data = self._request("POST", "/v1/memories/sources", json_body=payload)
+        return SourcesPage.from_dict(data)
+
+    def iter_sources(
+        self,
+        user_id: str,
+        *,
+        type: Optional[str] = None,
+        tag_filter: Optional[TagFilter] = None,
+        limit: int = 50,
+        order: str = "desc",
+    ):
+        """Yield every source across all pages, fetching lazily."""
+        page = 1
+        while True:
+            result = self.list_sources(
+                user_id,
+                type=type,
+                tag_filter=tag_filter,
+                page=page,
+                limit=limit,
+                order=order,
+            )
+            for source in result.sources:
+                yield source
+            if page >= result.total_pages or not result.sources:
+                return
+            page += 1
+
+    def get_session(self, user_id: str, session_id: str) -> Session:
+        """Read a dialog session's original messages in chronological order."""
+        data = self._request(
+            "POST",
+            "/v1/memories/sessions",
+            json_body={"user_id": user_id, "session_id": session_id},
+        )
+        return Session.from_dict(data)
+
+    # -- deletion --------------------------------------------------------------
+
+    def delete_by_session(self, user_id: str, session_id: str) -> DeleteResult:
+        """Delete all memory derived from a dialog session."""
+        return self._delete(
+            "/v1/memories/by_session",
+            {"user_id": user_id, "session_id": session_id},
+        )
+
+    def delete_by_file(self, user_id: str, file_id: str) -> DeleteResult:
+        """Delete all memory derived from a file."""
+        return self._delete(
+            "/v1/memories/by_file",
+            {"user_id": user_id, "file_id": file_id},
+        )
+
+    def delete_by_tag(self, user_id: str, tag_filter: TagFilter) -> DeleteResult:
+        """Delete all memory whose source tags match ``tag_filter``.
+
+        ``tag_filter`` must be non-empty.
+        """
+        if not tag_filter:
+            raise ParcleConfigError("delete_by_tag requires a non-empty tag_filter.")
+        return self._delete(
+            "/v1/memories/by_tag",
+            {"user_id": user_id, "tag_filter": dict(tag_filter)},
+        )
+
+    def _delete(self, path: str, body: Dict[str, Any]) -> DeleteResult:
+        data = self._request("DELETE", path, json_body=body)
+        return DeleteResult.from_dict(data)
+
+    # -- transport -------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+        }
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    url,
+                    headers=headers,
+                    json=json_body,
+                    data=data,
+                    files=files,
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = ParcleConnectionError(f"Request to {url} timed out.")
+                last_exc.__cause__ = exc
+            except httpx.HTTPError as exc:
+                last_exc = ParcleConnectionError(f"Request to {url} failed: {exc}")
+                last_exc.__cause__ = exc
+            else:
+                if response.status_code in _RETRY_STATUS and attempt < self.max_retries:
+                    self._sleep_for_retry(response, attempt)
+                    continue
+                return self._parse_response(response)
+
+            # Reached only on a connection-level failure; back off and retry.
+            if attempt < self.max_retries:
+                time.sleep(_backoff_seconds(attempt))
+                continue
+            assert last_exc is not None
+            raise last_exc
+
+        # Unreachable, but keeps type-checkers happy.
+        assert last_exc is not None
+        raise last_exc
+
+    def _parse_response(self, response: httpx.Response) -> Dict[str, Any]:
+        body: Any
+        try:
+            body = response.json() if response.content else None
+        except (json.JSONDecodeError, ValueError):
+            body = None
+
+        if response.is_success:
+            return body if isinstance(body, dict) else {}
+
+        raise error_from_response(
+            response.status_code,
+            body,
+            fallback_message=(
+                response.text or f"Request failed with status {response.status_code}."
+            ),
+        )
+
+    @staticmethod
+    def _sleep_for_retry(response: httpx.Response, attempt: int) -> None:
+        retry_after = response.headers.get("Retry-After")
+        if retry_after:
+            try:
+                time.sleep(float(retry_after))
+                return
+            except ValueError:
+                pass
+        time.sleep(_backoff_seconds(attempt))
+
+
+# -- module-level helpers ------------------------------------------------------
+
+
+def _drop_none(d: Dict[str, Any]) -> Dict[str, Any]:
+    """Drop keys whose value is None so they are omitted from the request."""
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _backoff_seconds(attempt: int) -> float:
+    """Exponential backoff: 0.5s, 1s, 2s, … capped at 8s."""
+    return min(0.5 * (2 ** attempt), 8.0)
+
+
+def _message_to_dict(message: MessageInput) -> Dict[str, Any]:
+    if isinstance(message, Message):
+        return message.to_dict()
+    if isinstance(message, Mapping):
+        if "role" not in message or "content" not in message:
+            raise ParcleConfigError(
+                "Each message requires 'role' and 'content' keys."
+            )
+        return _drop_none(dict(message))
+    raise TypeError(
+        f"Message must be a dict or Message, got {type(message).__name__}."
+    )
+
+
+def _guess_content_type(filename: str) -> str:
+    suffix = Path(filename).suffix.lower()
+    if suffix in _EXTRA_CONTENT_TYPES:
+        return _EXTRA_CONTENT_TYPES[suffix]
+    guessed, _ = mimetypes.guess_type(filename)
+    return guessed or "application/octet-stream"
+
+
+def _prepare_file(
+    file: FileInput,
+) -> Tuple[str, Union[bytes, IO[bytes]], str]:
+    """Normalise the ``file`` argument into ``(filename, content, content_type)``."""
+    # (filename, content) or (filename, content, content_type)
+    if isinstance(file, tuple):
+        if len(file) == 2:
+            filename, content = file
+            content_type = None
+        elif len(file) == 3:
+            filename, content, content_type = file
+        else:
+            raise ParcleConfigError(
+                "file tuple must be (filename, content[, content_type])."
+            )
+        return filename, content, content_type or _guess_content_type(filename)
+
+    # Path-like → open and read.
+    if isinstance(file, (str, os.PathLike)):
+        path = Path(file)
+        if not path.is_file():
+            raise ParcleConfigError(f"File not found: {path}")
+        return path.name, path.read_bytes(), _guess_content_type(path.name)
+
+    # Raw bytes with no filename — we can't infer one.
+    if isinstance(file, (bytes, bytearray)):
+        raise ParcleConfigError(
+            "Raw bytes need a filename; pass a (filename, bytes) tuple instead."
+        )
+
+    # Assume a binary stream; derive the filename from .name if present.
+    name = getattr(file, "name", None)
+    if not name:
+        raise ParcleConfigError(
+            "Could not determine a filename for the file stream; pass a "
+            "(filename, stream) tuple instead."
+        )
+    filename = os.path.basename(name)
+    return filename, file, _guess_content_type(filename)

parcle/exceptions.py

@@ -0,0 +1,151 @@
+"""Exception hierarchy for the Parcle client.
+
+Every non-2xx API response is translated into a :class:`ParcleAPIError`
+subclass chosen by HTTP status. The server's stable ``error.code`` string and
+human-readable ``error.message`` are preserved on the exception, along with the
+``request_id`` for support correlation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class ParcleError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class ParcleConfigError(ParcleError):
+    """Raised for misconfiguration, e.g. a missing API key."""
+
+
+class ParcleConnectionError(ParcleError):
+    """Raised when the request never produced an HTTP response.
+
+    Covers connection failures, DNS errors, and timeouts.
+    """
+
+
+class ParcleTimeoutError(ParcleError):
+    """Raised when a polling helper exceeds its deadline."""
+
+
+class ParcleAPIError(ParcleError):
+    """Raised when the API returns a non-2xx response.
+
+    Attributes
+    ----------
+    status_code:
+        The HTTP status code of the response.
+    code:
+        The stable ``error.code`` string for programmatic handling.
+    message:
+        The human-readable ``error.message``.
+    request_id:
+        The server-assigned request id, useful for support.
+    body:
+        The raw decoded response body, when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.body = body
+
+    def __str__(self) -> str:
+        parts = []
+        if self.status_code is not None:
+            parts.append(f"HTTP {self.status_code}")
+        if self.code:
+            parts.append(self.code)
+        prefix = f"[{' '.join(parts)}] " if parts else ""
+        suffix = f" (request_id={self.request_id})" if self.request_id else ""
+        return f"{prefix}{self.message}{suffix}"
+
+
+# -- Status-specific subclasses ------------------------------------------------
+
+
+class InvalidRequestError(ParcleAPIError):
+    """HTTP 400 — malformed JSON, wrong field type, or missing required field."""
+
+
+class AuthenticationError(ParcleAPIError):
+    """HTTP 401 — missing or invalid bearer key."""
+
+
+class NotFoundError(ParcleAPIError):
+    """HTTP 404 — unknown user, session, file, or event."""
+
+
+class FileTooLargeError(ParcleAPIError):
+    """HTTP 413 — uploaded file exceeds the size limit."""
+
+
+class UnsupportedFileTypeError(ParcleAPIError):
+    """HTTP 415 — unsupported extension or database-like file."""
+
+
+class ValidationError(ParcleAPIError):
+    """HTTP 422 — well-formed request that breaks a rule."""
+
+
+class RateLimitError(ParcleAPIError):
+    """HTTP 429 — too many requests."""
+
+
+class InternalServerError(ParcleAPIError):
+    """HTTP 500 — unexpected server failure."""
+
+
+class ServiceUnavailableError(ParcleAPIError):
+    """HTTP 503 — temporarily overloaded or down."""
+
+
+_STATUS_TO_EXCEPTION: Dict[int, type] = {
+    400: InvalidRequestError,
+    401: AuthenticationError,
+    404: NotFoundError,
+    413: FileTooLargeError,
+    415: UnsupportedFileTypeError,
+    422: ValidationError,
+    429: RateLimitError,
+    500: InternalServerError,
+    503: ServiceUnavailableError,
+}
+
+
+def error_from_response(
+    status_code: int, body: Optional[Any], *, fallback_message: str
+) -> ParcleAPIError:
+    """Build the appropriate :class:`ParcleAPIError` for a failed response."""
+    code: Optional[str] = None
+    message = fallback_message
+    request_id: Optional[str] = None
+
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):
+            code = err.get("code")
+            message = err.get("message") or message
+            request_id = err.get("request_id")
+
+    exc_cls = _STATUS_TO_EXCEPTION.get(status_code, ParcleAPIError)
+    return exc_cls(
+        message,
+        status_code=status_code,
+        code=code,
+        request_id=request_id,
+        body=body,
+    )

parcle/models.py

@@ -0,0 +1,222 @@
+"""Typed response models returned by the Parcle client.
+
+These are lightweight dataclasses parsed from the API's JSON responses. Unknown
+fields are ignored, so the models stay forward-compatible as the API grows.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+# A free-form tag attached to a source: a flat mapping of string keys to scalar
+# values used for grouping and filtering memory within one user.
+Tag = Dict[str, Any]
+
+
+@dataclass
+class User:
+    """A memory namespace returned by :meth:`Parcle.create_user`."""
+
+    user_id: str
+    name: Optional[str] = None
+    timezone: str = "UTC"
+    is_new: bool = False
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "User":
+        return cls(
+            user_id=data["user_id"],
+            name=data.get("name"),
+            timezone=data.get("timezone", "UTC"),
+            is_new=bool(data.get("is_new", False)),
+        )
+
+
+@dataclass
+class Message:
+    """A single dialog message, in or out."""
+
+    role: str
+    content: str
+    speaker: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Message":
+        return cls(
+            role=data["role"],
+            content=data["content"],
+            speaker=data.get("speaker"),
+            updated_at=data.get("updated_at"),
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"role": self.role, "content": self.content}
+        if self.speaker is not None:
+            out["speaker"] = self.speaker
+        if self.updated_at is not None:
+            out["updated_at"] = self.updated_at
+        return out
+
+
+@dataclass
+class IngestDialogResult:
+    """Result of :meth:`Parcle.ingest_dialog`."""
+
+    session_id: str
+    event_id: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "IngestDialogResult":
+        return cls(session_id=data["session_id"], event_id=data["event_id"])
+
+
+@dataclass
+class IngestFileResult:
+    """Result of :meth:`Parcle.ingest_file`."""
+
+    file_id: str
+    event_id: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "IngestFileResult":
+        return cls(file_id=data["file_id"], event_id=data["event_id"])
+
+
+@dataclass
+class Event:
+    """Ingestion status for a single write, from :meth:`Parcle.get_event`."""
+
+    event_id: str
+    status: str
+    error: Optional[str] = None
+
+    @property
+    def is_ready(self) -> bool:
+        """True once the ingested content is searchable."""
+        return self.status == "ready"
+
+    @property
+    def is_failed(self) -> bool:
+        return self.status == "failed"
+
+    @property
+    def is_terminal(self) -> bool:
+        """True once the event will not change state again."""
+        return self.status in ("ready", "failed")
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Event":
+        return cls(
+            event_id=data["event_id"],
+            status=data["status"],
+            error=data.get("error"),
+        )
+
+
+@dataclass
+class Citation:
+    """A source the search answer draws on."""
+
+    type: str  # "session" | "file"
+    id: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Citation":
+        return cls(type=data["type"], id=data["id"])
+
+
+@dataclass
+class SearchResult:
+    """Result of :meth:`Parcle.search` — an answer grounded in citations."""
+
+    answer: str
+    confidence: float
+    citations: List[Citation] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SearchResult":
+        return cls(
+            answer=data["answer"],
+            confidence=float(data["confidence"]),
+            citations=[Citation.from_dict(c) for c in data.get("citations", [])],
+        )
+
+
+@dataclass
+class Source:
+    """A dialog session or file in a user's memory."""
+
+    id: str
+    type: str  # "session" | "file"
+    updated_at: Optional[str] = None
+    tag: Optional[Tag] = None
+    name: Optional[str] = None  # filename, files only
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Source":
+        return cls(
+            id=data["id"],
+            type=data["type"],
+            updated_at=data.get("updated_at"),
+            tag=data.get("tag"),
+            name=data.get("name"),
+        )
+
+
+@dataclass
+class SourcesPage:
+    """One page of :meth:`Parcle.list_sources`."""
+
+    sources: List[Source]
+    page: int
+    total_pages: int
+    total: int
+
+    def __iter__(self):
+        return iter(self.sources)
+
+    def __len__(self) -> int:
+        return len(self.sources)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SourcesPage":
+        return cls(
+            sources=[Source.from_dict(s) for s in data.get("sources", [])],
+            page=int(data.get("page", 1)),
+            total_pages=int(data.get("total_pages", 1)),
+            total=int(data.get("total", 0)),
+        )
+
+
+@dataclass
+class Session:
+    """A dialog session's original messages, from :meth:`Parcle.get_session`."""
+
+    session_id: str
+    messages: List[Message]
+    tag: Optional[Tag] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Session":
+        return cls(
+            session_id=data["session_id"],
+            messages=[Message.from_dict(m) for m in data.get("messages", [])],
+            tag=data.get("tag"),
+        )
+
+
+@dataclass
+class DeleteResult:
+    """Result of any ``delete_by_*`` call."""
+
+    deleted: bool
+    deleted_count: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DeleteResult":
+        return cls(
+            deleted=bool(data["deleted"]),
+            deleted_count=int(data["deleted_count"]),
+        )

parcle-0.1.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: parcle
+Version: 0.1.0
+Summary: Long-term memory for AI agents — a Python client for the Parcle Memory API.
+Project-URL: Homepage, https://parcle.ai
+Project-URL: Documentation, https://api.parcle.ai
+Author: Parcle
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,llm,memory,parcle,rag
+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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Parcle
+
+**Long-term memory for AI agents**
+
+Ingest conversations and files, then ask questions in natural language and get
+cited answers back. Give every user a private, persistent agent memory.
+
+</div>
+
+---
+
+## Why Parcle?
+
+LLMs forget everything between calls. Parcle gives every user a private memory you
+can write to and search:
+
+- 🧠 **Per-user memory** — scope everything to a `user_id`.
+- 💬 **Ingest anything** — chat transcripts and files (PDF, Markdown, text, …) go in the same place.
+- 🔎 **Ask, don't query** — search returns a synthesized **answer** with **citations**, not just raw chunks.
+
+## Installation
+
+```bash
+pip install parcle
+```
+
+## Quickstart
+
+```python
+from parcle import Parcle
+
+# Reads PARCLE_API_KEY from the environment if api_key is omitted.
+client = Parcle(api_key="pk_live_...")
+
+# 1. Write a conversation into a user's memory.
+#    Ingestion is incremental: omit session_id to start a new session, then
+#    pass the returned session_id back to append more turns to the same one.
+result = client.ingest_dialog(
+    user_id="ada",
+    messages=[
+        {"role": "user", "content": "I'm allergic to peanuts."},
+        {"role": "assistant", "content": "Got it — I'll avoid peanuts in suggestions."},
+    ],
+)
+client.ingest_dialog(
+    user_id="ada",
+    session_id=result.session_id,  # append to the same session
+    messages=[
+        {"role": "user", "content": "Also, I don't eat shellfish."},
+    ],
+)
+
+# 2. ...or ingest a file (PDF, Markdown, text, …).
+client.ingest_file(user_id="ada", file="diet-notes.pdf")
+
+# 3. Ask a question. You get an answer with confidence and citations.
+result = client.search(user_id="ada", query="What food should I avoid?")
+
+print(result.answer)      # "You're allergic to peanuts, so avoid them."
+print(result.confidence)  # 0.92
+print(result.citations)   # [Citation(type="session", id="...")]
+```

parcle-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+parcle/__init__.py,sha256=KHPp1LaiZJYHKEyS4rrxKmafIPIzgzZ3TrSBBQNorrQ,1741
+parcle/client.py,sha256=Bd5BmUN8RDEg6BJXCrggq-DEshWKMUCKYBt_9LuuEAM,17870
+parcle/exceptions.py,sha256=PPyhyna7VHhR4JtgDP8ZrvsIqOQxpisBJvSN0fvUIBY,4226
+parcle/models.py,sha256=Csq3tsCYONdUYDPscYZ14qgsPIiTtgWUniS2QSlew_s,5748
+parcle/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+parcle-0.1.0.dist-info/METADATA,sha256=BUOzK3xp6-6tqz8it2AR-vBwA4JktHpGEZbTAOTR9fU,2893
+parcle-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+parcle-0.1.0.dist-info/licenses/LICENSE,sha256=cEfzkpOGKfxoc-4jVvIUb9uIBejC__tKqou_kcOmYAs,1063
+parcle-0.1.0.dist-info/RECORD,,

parcle-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

parcle-0.1.0.dist-info/licenses/LICENSE

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