karakeep-python-api 1.8.0__tar.gz → 1.9.0__tar.gz

{karakeep_python_api-1.8.0/karakeep_python_api.egg-info → karakeep_python_api-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 1.8.0
+Version: 1.9.0
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 Keywords: rss,karakeep,hoarder,data-hoarding,python,api,feeds,openapi
@@ -82,6 +82,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `get_a_single_bookmark`          |   ✅   |  ❌  |  |
 | `delete_a_bookmark`              |   ✅   |  ❌  |  |
 | `update_a_bookmark`              |   ✅   |  ✅  | Tested for title updates.                    |
+| `get_bookmark_readable_content`  |   ✅   |  ❌  | Chunk merging tested offline; live test reads a text bookmark. |
 | `summarize_a_bookmark`           |   ❌   |  ❌  |                                              |
 | `attach_tags_to_a_bookmark`      |   ✅   |  ❌  |  |
 | `detach_tags_from_a_bookmark`    |   ✅   |  ❌  |  |
@@ -110,6 +111,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `update_a_highlight`             |   ❌   |  ❌  |                                              |
 | `upload_a_new_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
 | `get_a_single_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
+| `get_asset_signed_url`           |   ✅   |  ❌  | Tested in PDF asset lifecycle test (downloads without an API key). |
 | `get_current_user_info`          |   ✅   |  ❌  | Pytest: Tested indirectly during client init. CLI not directly tested. |
 | `get_current_user_stats`         |   ✅   |  ✅  |                                              |
 | `update_user`                    |   ❌   |  ❌  |                                              |
@@ -118,6 +120,9 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `get_a_single_backup`            |   ✅   |  ❌  | Tested in backup lifecycle test.            |
 | `delete_a_backup`                |   ✅   |  ❌  | Tested in backup lifecycle test.            |
 | `download_a_backup`              |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `admin_trigger_recrawl`          |   ❌   |  ❌  | Request body construction tested offline only. |
+| `admin_trigger_reindex`          |   ❌   |  ❌  | Request body construction tested offline only. |
+| `admin_trigger_inference`        |   ❌   |  ❌  | Request body construction tested offline only. |
 
 ## Installation
 
@@ -281,4 +286,4 @@ They can be found in the [./community_scripts](https://github.com/thiswillbeyour
 
 ---
 
-*This README was generated with assistance from [aider.chat](https://aider.chat).*
+*This README was generated with assistance from [aider.chat](https://aider.chat), and later kept up to date with [Claude Code](https://claude.com/claude-code).*

{karakeep_python_api-1.8.0 → karakeep_python_api-1.9.0}/README.md

@@ -50,6 +50,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `get_a_single_bookmark`          |   ✅   |  ❌  |  |
 | `delete_a_bookmark`              |   ✅   |  ❌  |  |
 | `update_a_bookmark`              |   ✅   |  ✅  | Tested for title updates.                    |
+| `get_bookmark_readable_content`  |   ✅   |  ❌  | Chunk merging tested offline; live test reads a text bookmark. |
 | `summarize_a_bookmark`           |   ❌   |  ❌  |                                              |
 | `attach_tags_to_a_bookmark`      |   ✅   |  ❌  |  |
 | `detach_tags_from_a_bookmark`    |   ✅   |  ❌  |  |
@@ -78,6 +79,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `update_a_highlight`             |   ❌   |  ❌  |                                              |
 | `upload_a_new_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
 | `get_a_single_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
+| `get_asset_signed_url`           |   ✅   |  ❌  | Tested in PDF asset lifecycle test (downloads without an API key). |
 | `get_current_user_info`          |   ✅   |  ❌  | Pytest: Tested indirectly during client init. CLI not directly tested. |
 | `get_current_user_stats`         |   ✅   |  ✅  |                                              |
 | `update_user`                    |   ❌   |  ❌  |                                              |
@@ -86,6 +88,9 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `get_a_single_backup`            |   ✅   |  ❌  | Tested in backup lifecycle test.            |
 | `delete_a_backup`                |   ✅   |  ❌  | Tested in backup lifecycle test.            |
 | `download_a_backup`              |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `admin_trigger_recrawl`          |   ❌   |  ❌  | Request body construction tested offline only. |
+| `admin_trigger_reindex`          |   ❌   |  ❌  | Request body construction tested offline only. |
+| `admin_trigger_inference`        |   ❌   |  ❌  | Request body construction tested offline only. |
 
 ## Installation
 
@@ -249,4 +254,4 @@ They can be found in the [./community_scripts](https://github.com/thiswillbeyour
 
 ---
 
-*This README was generated with assistance from [aider.chat](https://aider.chat).*
+*This README was generated with assistance from [aider.chat](https://aider.chat), and later kept up to date with [Claude Code](https://claude.com/claude-code).*

{karakeep_python_api-1.8.0 → karakeep_python_api-1.9.0}/karakeep_python_api/__main__.py

@@ -538,7 +538,23 @@ def create_click_command(
                     ctx.exit(1)
 
                 # Serialize and print the result
-                if result is not None:
+                if isinstance(result, (bytes, bytearray)):
+                    # Binary payloads (e.g. download_a_backup, get_a_single_asset)
+                    # cannot be JSON encoded: write them raw to stdout so the
+                    # output can be redirected straight into a file.
+                    logger.debug(f"Writing {len(result)} raw bytes to stdout.")
+                    stdout_buffer = getattr(sys.stdout, "buffer", None)
+                    if stdout_buffer is not None:
+                        stdout_buffer.write(result)
+                        stdout_buffer.flush()
+                    else:
+                        # Some test/capture harnesses replace sys.stdout with a
+                        # text-only stream that has no .buffer attribute.
+                        sys.stdout.write(
+                            bytes(result).decode("utf-8", errors="surrogateescape")
+                        )
+                        sys.stdout.flush()
+                elif result is not None:
                     output_data = serialize_output(result)
                     # Use ensure_ascii_output flag to control JSON encoding
                     click.echo(

{karakeep_python_api-1.8.0 → karakeep_python_api-1.9.0}/karakeep_python_api/datatypes.py

@@ -53,6 +53,15 @@ class ContentTypeLink(BaseModel):
     favicon: Optional[str] = None
     htmlContent: Optional[str] = None
     contentAssetId: Optional[str] = None
+    # Reader-view triage produced by the crawler: readerViewStatus says whether a
+    # distraction-free rendering could be extracted, readerViewScore (0-100) how
+    # confident that extraction is, and preferredPreview which of the available
+    # renderings the UI should show by default.
+    readerViewStatus: Optional[
+        Literal["readable", "not_readable", "uncertain", "unavailable"]
+    ] = None
+    readerViewScore: Optional[int] = None
+    preferredPreview: Optional[Literal["reader_view", "screenshot", "overview"]] = None
     crawledAt: Optional[str] = None
     crawlStatus: Optional[Literal["success", "failure", "pending"]] = None
     author: Optional[str] = None
@@ -112,8 +121,20 @@ class UploadedAsset(BaseModel):
 Asset = UploadedAsset
 
 
+class SignedAssetUrl(BaseModel):
+    assetId: str
+    # Temporary download URL that carries its own signature, so it works without
+    # the Authorization header and can be handed to a browser or media player.
+    signedUrl: str
+    expiresAt: str
+
+
 class Bookmark(BaseModel):
     id: str
+    # firstCreatedAt records the original creation time when a bookmark is
+    # recreated/re-imported, so it can predate createdAt. Optional in the spec
+    # and absent on Karakeep servers older than the one that introduced it.
+    firstCreatedAt: Optional[str] = None
     createdAt: str
     modifiedAt: Optional[str]
     title: Optional[str] = None
@@ -121,6 +142,10 @@ class Bookmark(BaseModel):
     favourited: bool
     taggingStatus: Optional[Literal["success", "failure", "pending"]] = None
     summarizationStatus: Optional[Literal["success", "failure", "pending"]] = None
+    # Status of the vector-embedding job used by semantic/hybrid search. The
+    # spec marks it required-but-nullable, so no default is given here: a
+    # missing key is a genuine mismatch with the documented server response.
+    embeddingStatus: Optional[Literal["success", "failure", "pending"]]
     note: Optional[str] = None
     summary: Optional[str] = None
     source: Optional[
@@ -136,6 +161,28 @@ class Bookmark(BaseModel):
     assets: List[BookmarkAsset]
 
 
+class ReadableContentRange(BaseModel):
+    # Offsets are in Unicode characters over the *rendered* content, not bytes:
+    # start is inclusive, end is exclusive, and total is the full rendered length.
+    start: int
+    end: int
+    total: int
+
+
+class BookmarkReadableContent(BaseModel):
+    bookmarkId: str
+    bookmarkType: Literal["link", "text", "asset"]
+    format: Literal["markdown", "text"]
+    content: str
+    # Hash of the rendered content the cursor was issued against. The server
+    # answers 409 if the bookmark changed between two chunks, so this value must
+    # not be mixed across a paginated read.
+    contentVersion: str
+    range: ReadableContentRange
+    nextCursor: Optional[str]
+    truncated: bool
+
+
 class PaginatedBookmarks(BaseModel):
     bookmarks: List[Bookmark]
     nextCursor: Optional[str] = ""

{karakeep_python_api-1.8.0 → karakeep_python_api-1.9.0}/karakeep_python_api/karakeep_api.py

@@ -85,7 +85,7 @@ class KarakeepAPI:
     """
 
     # Version reflects the client library version, updated by bumpver
-    VERSION: str = "1.8.0"
+    VERSION: str = "1.9.0"
 
     def __init__(
         self,
@@ -891,16 +891,25 @@ class KarakeepAPI:
     def search_bookmarks(
         self,
         q: str,  # Search query is required
+        search_mode: Optional[Literal["fts", "semantic", "hybrid"]] = None,
         sort_order: Optional[Literal["asc", "desc", "relevance"]] = None,
         limit: Optional[int] = None,
         cursor: Optional[str] = None,
         include_content: bool = True,  # Default from spec
     ) -> Union[datatypes.PaginatedBookmarks, Dict[str, Any], List[Any]]:
         """
-        Search bookmarks. Corresponds to GET /bookmarks/search.
+        Search bookmarks using full-text, semantic or hybrid ranking.
+        Corresponds to GET /bookmarks/search.
 
         Args:
             q: The search query string.
+            search_mode: Search strategy (optional). "fts" is full-text search (API default),
+                         "semantic" ranks with bookmark embeddings, and "hybrid" fuses both.
+                         Hybrid falls back to full-text search when the query has no free-text
+                         terms or when embedding infrastructure is unavailable. Semantic hits
+                         below a minimum similarity are dropped, so "semantic" and "hybrid" may
+                         return fewer results than `limit`. Note that the semantic modes only
+                         support sort_order="relevance".
             sort_order: Sort order for results ("asc", "desc", "relevance"). Default from API is "relevance" (optional).
             limit: Maximum number of bookmarks to return (optional).
             cursor: Pagination cursor for the next page (optional).
@@ -916,6 +925,7 @@ class KarakeepAPI:
         """
         params = {
             "q": q,
+            "searchMode": search_mode,
             "sortOrder": sort_order,
             "limit": limit,
             "cursor": cursor,
@@ -1051,6 +1061,101 @@ class KarakeepAPI:
         # No Pydantic validation applied here as the spec defines a partial response (dict)
         return response_data
 
+    @optional_typecheck
+    def get_bookmark_readable_content(
+        self,
+        bookmark_id: str,
+        format: Optional[Literal["markdown", "text"]] = None,
+        max_chars: Optional[int] = None,
+        cursor: Optional[str] = None,
+        fetch_all: bool = False,
+    ) -> Union[datatypes.BookmarkReadableContent, Dict[str, Any], List[Any]]:
+        """
+        Get an agent-readable rendering of a bookmark's content.
+        Corresponds to GET /bookmarks/{bookmarkId}/content.
+
+        Link content is rendered from the extracted HTML; text and asset bookmarks use
+        their stored or extracted text. The endpoint returns a bounded chunk plus an
+        opaque `nextCursor`; pass that cursor back to continue reading, or set
+        `fetch_all=True` to let this method walk the cursors and return the whole
+        document as a single object.
+
+        Args:
+            bookmark_id: The ID (string) of the bookmark to read.
+            format: Readable representation, "markdown" or "text" (optional). If omitted
+                    together with a cursor, the cursor's own format is reused; otherwise
+                    the API defaults to "markdown".
+            max_chars: Maximum number of Unicode characters per chunk, 1 to 50000
+                       (optional, API default 12000). A chunk may end earlier, at a
+                       paragraph or line boundary.
+            cursor: Opaque continuation cursor returned as `nextCursor` by a previous
+                    response (optional).
+            fetch_all: If True, keep following `nextCursor` until the document is
+                       exhausted and return one merged object whose `content` is the
+                       concatenation of every chunk, with `nextCursor=None` and
+                       `truncated=False` (default: False).
+
+        Returns:
+            datatypes.BookmarkReadableContent: A chunk of readable content (or the whole
+            document when fetch_all is True).
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails (e.g. 404 bookmark not found, or 409 if
+                      the bookmark content changed after the supplied cursor was issued).
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        endpoint = f"bookmarks/{bookmark_id}/content"
+        params = {
+            "format": format,
+            "maxChars": max_chars,
+            "cursor": cursor,
+        }
+        response_data = self._call("GET", endpoint, params=params)
+
+        if fetch_all:
+            # Walk the cursor chain and merge the chunks. The raw dicts are merged
+            # rather than the validated models so that the loop behaves identically
+            # whether or not response validation is enabled.
+            if not isinstance(response_data, dict):
+                raise APIError(
+                    f"Unexpected response format for get_bookmark_readable_content: {response_data}"
+                )
+            merged = dict(response_data)
+            chunks = [merged.get("content", "")]
+            next_cursor = merged.get("nextCursor")
+            while next_cursor:
+                params["cursor"] = next_cursor
+                # The format is carried by the cursor itself, so it is left as passed.
+                page = self._call("GET", endpoint, params=params)
+                if not isinstance(page, dict):
+                    raise APIError(
+                        f"Unexpected response format for get_bookmark_readable_content: {page}"
+                    )
+                chunks.append(page.get("content", ""))
+                # Keep the latest range end/total: the server may only know the true
+                # total once it has rendered further into the document.
+                if "range" in page and "range" in merged:
+                    merged["range"] = {
+                        **page["range"],
+                        "start": merged["range"].get("start", 0),
+                    }
+                merged["contentVersion"] = page.get(
+                    "contentVersion", merged.get("contentVersion")
+                )
+                next_cursor = page.get("nextCursor")
+            merged["content"] = "".join(chunks)
+            merged["nextCursor"] = None
+            merged["truncated"] = False
+            response_data = merged
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        else:
+            # Response should match BookmarkReadableContent schema
+            return datatypes.BookmarkReadableContent.model_validate(response_data)
+
     @optional_typecheck
     def summarize_a_bookmark(self, bookmark_id: str) -> Dict[str, Any]:
         """
@@ -2481,6 +2586,44 @@ class KarakeepAPI:
             logger.error(error_msg)
             raise APIError(error_msg)
 
+    @optional_typecheck
+    def get_asset_signed_url(
+        self, asset_id: str
+    ) -> Union[datatypes.SignedAssetUrl, Dict[str, Any], List[Any]]:
+        """
+        Get a temporary signed URL for downloading an asset.
+        Corresponds to GET /assets/{assetId}/signed-url.
+
+        The returned URL embeds its own signature and expiry, so it can be fetched
+        without an API key. This is the way to hand an asset to something that cannot
+        send the Authorization header (a browser tab, a media player, an <img> tag)
+        without proxying the bytes through get_a_single_asset.
+
+        Args:
+            asset_id: The ID (string) of the asset to sign.
+
+        Returns:
+            datatypes.SignedAssetUrl: The asset id, the temporary URL and its expiry.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails.
+            ValueError: If asset_id is empty.
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        if not asset_id or not asset_id.strip():
+            raise ValueError("asset_id cannot be empty")
+
+        endpoint = f"assets/{asset_id.strip()}/signed-url"
+        response_data = self._call("GET", endpoint)
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        else:
+            # Response should match SignedAssetUrl schema
+            return datatypes.SignedAssetUrl.model_validate(response_data)
+
     # --- Admin: Job Triggers ---
 
     @optional_typecheck
@@ -2488,6 +2631,7 @@ class KarakeepAPI:
         self,
         crawl_status: Literal["success", "failure", "pending", "all"] = "all",
         run_inference: bool = False,
+        modified_within_seconds: Optional[int] = None,
     ) -> Dict[str, Any]:
         """
         Trigger a recrawl of link bookmarks. Admin only.
@@ -2497,6 +2641,9 @@ class KarakeepAPI:
             crawl_status: Filter bookmarks by their current crawl status.
                           Use "failure" to retry only failed crawls. Default: "all".
             run_inference: Whether to run AI inference after crawling. Default: False.
+            modified_within_seconds: Only process bookmarks modified within this many
+                                     seconds. Must be > 0. Omit to process all matching
+                                     bookmarks (optional).
 
         Returns:
             dict: A dictionary with a "success" boolean field.
@@ -2504,16 +2651,34 @@ class KarakeepAPI:
         Raises:
             APIError: If the API request fails (e.g., 403 admin access required).
         """
-        body = {"crawlStatus": crawl_status, "runInference": run_inference}
+        body: Dict[str, Any] = {
+            "crawlStatus": crawl_status,
+            "runInference": run_inference,
+        }
+        # Omitted rather than sent as null: the spec has no null case and the
+        # absence of the key is what means "no time window".
+        if modified_within_seconds is not None:
+            body["modifiedWithinSeconds"] = modified_within_seconds
         return self._call("POST", "admin/jobs/trigger/recrawl", data=body)
 
     @optional_typecheck
-    def admin_trigger_reindex(self) -> Dict[str, Any]:
+    def admin_trigger_reindex(
+        self,
+        modified_within_seconds: Optional[int] = None,
+    ) -> Dict[str, Any]:
         """
-        Trigger a reindex of all bookmarks in the search engine. Admin only.
+        Trigger a reindex of bookmarks in the search engine. Admin only.
         Corresponds to POST /admin/jobs/trigger/reindex.
 
-        Clears the existing index and re-queues all bookmarks for indexing.
+        Without modified_within_seconds this clears the existing index and re-queues
+        every bookmark. With it, only bookmarks modified within that window are
+        re-queued and the existing index is left in place, which makes it usable as a
+        cheap catch-up job rather than a full rebuild.
+
+        Args:
+            modified_within_seconds: Only process bookmarks modified within this many
+                                     seconds. Must be > 0. Omit to reindex everything
+                                     from scratch (optional).
 
         Returns:
             dict: A dictionary with a "success" boolean field.
@@ -2521,13 +2686,22 @@ class KarakeepAPI:
         Raises:
             APIError: If the API request fails (e.g., 403 admin access required).
         """
-        return self._call("POST", "admin/jobs/trigger/reindex")
+        # The request body is optional in the spec, so nothing is sent when no window
+        # is given; that keeps the "clear and rebuild" behaviour byte-identical to
+        # what older servers expect.
+        body = (
+            None
+            if modified_within_seconds is None
+            else {"modifiedWithinSeconds": modified_within_seconds}
+        )
+        return self._call("POST", "admin/jobs/trigger/reindex", data=body)
 
     @optional_typecheck
     def admin_trigger_inference(
         self,
         type: Literal["tag", "summarize"],
         status: Literal["success", "failure", "pending", "all"] = "all",
+        modified_within_seconds: Optional[int] = None,
     ) -> Dict[str, Any]:
         """
         Trigger AI inference (tagging or summarization) on bookmarks. Admin only.
@@ -2538,6 +2712,9 @@ class KarakeepAPI:
                   "summarize" for AI summarization.
             status: Filter bookmarks by their current inference status.
                     Use "failure" to retry only failed ones. Default: "all".
+            modified_within_seconds: Only process bookmarks modified within this many
+                                     seconds. Must be > 0. Omit to process all matching
+                                     bookmarks (optional).
 
         Returns:
             dict: A dictionary with a "success" boolean field.
@@ -2545,7 +2722,10 @@ class KarakeepAPI:
         Raises:
             APIError: If the API request fails (e.g., 403 admin access required).
         """
-        body = {"type": type, "status": status}
+        body: Dict[str, Any] = {"type": type, "status": status}
+        # See admin_trigger_recrawl: the key is omitted rather than sent as null.
+        if modified_within_seconds is not None:
+            body["modifiedWithinSeconds"] = modified_within_seconds
         return self._call("POST", "admin/jobs/trigger/inference", data=body)
 
     # --- Feeds ---