Skip to content

Library

Source code in superme_sdk/services/_library.py 
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
class LibraryMixin:
    def get_learnings(
        self,
        *,
        limit: Optional[int] = None,
        offset: int = 0,
        collection: Optional[str] = None,
        platform: Optional[str] = None,
        title_keyword: Optional[str] = None,
        privacy_filter: Optional[str] = None,
        unread_only: bool = False,
        date_from: Optional[str] = None,
        date_to: Optional[str] = None,
    ) -> dict:
        """List knowledge items in the authenticated user's library.

        Example:
            ```python
            page = client.get_learnings(limit=20)
            for item in page["items"]:
                print(item["learning_id"], item["title"])

            # filter to external content only
            page = client.get_learnings(collection="external", limit=10)
            ```

        Args:
            limit: Maximum items to return. Omit for backend default.
            offset: Pagination offset (default 0).
            collection: Filter by type — ``"internal"``, ``"external"``,
                or ``"social"``.
            platform: Filter by source platform (e.g. ``"medium"``).
            title_keyword: Substring search on item title.
            privacy_filter: One of ``"public"``, ``"network"``, ``"private"``.
            unread_only: Return only unread items.
            date_from: ISO-8601 lower bound on ``content_published_at``.
            date_to: ISO-8601 upper bound on ``content_published_at``.

        Returns:
            Dict with ``items`` list and pagination info.
        """
        uid = self.user_id
        if not uid:
            raise ValueError("Cannot extract user_id from token")

        params: dict[str, Any] = {"user_id": uid, "offset": offset}
        if limit is not None:
            params["limit"] = limit
        if collection is not None:
            params["collection"] = collection
        if platform is not None:
            params["platform"] = platform
        if title_keyword is not None:
            params["title_keyword"] = title_keyword
        if privacy_filter is not None:
            params["privacy_filter"] = privacy_filter
        if unread_only:
            params["unread_only"] = True
        if date_from is not None:
            params["date_from"] = date_from
        if date_to is not None:
            params["date_to"] = date_to

        resp = self._rest_http.get("/api/v3/library", params=params)
        self._check_rest_response(resp)
        return resp.json()

    def get_learning(self, learning_id: str) -> dict:
        """Fetch a single library item by ID.

        Example:
            ```python
            item = client.get_learning("learning_abc123")
            print(item["title"], item["summary"])
            ```

        Args:
            learning_id: The learning ID (from :meth:`get_learnings`).

        Returns:
            Dict with full learning metadata and content.
        """
        resp = self._rest_http.get(
            "/api/v3/library/getlearning", params={"learning_id": learning_id}
        )
        self._check_rest_response(resp)
        return resp.json()

    def get_ingestion_status(self) -> dict:
        """Check the ingestion status of the authenticated user's library.

        Returns a summary of how many items are pending, processing, done,
        or failed. Useful to poll after :meth:`add_external_content` to know
        when URLs finish processing.

        Example:
            ```python
            status = client.get_ingestion_status()
            print(status)
            ```

        Returns:
            Dict with ingestion counts and status breakdown.
        """
        uid = self.user_id
        if not uid:
            raise ValueError("Cannot extract user_id from token")

        resp = self._rest_http.get("/api/v3/library/ingestion", params={"user_id": uid})
        self._check_rest_response(resp)
        return resp.json()

get_learnings 

get_learnings(
    *,
    limit: Optional[int] = None,
    offset: int = 0,
    collection: Optional[str] = None,
    platform: Optional[str] = None,
    title_keyword: Optional[str] = None,
    privacy_filter: Optional[str] = None,
    unread_only: bool = False,
    date_from: Optional[str] = None,
    date_to: Optional[str] = None,
) -> dict

List knowledge items in the authenticated user's library.

Example 
page = client.get_learnings(limit=20)
for item in page["items"]:
    print(item["learning_id"], item["title"])

# filter to external content only
page = client.get_learnings(collection="external", limit=10)

Parameters:

Name Type Description Default
limit Optional[int]

Maximum items to return. Omit for backend default.

 None
offset int

Pagination offset (default 0).

 0
collection Optional[str]

Filter by type — "internal", "external", or "social".

 None
platform Optional[str]

Filter by source platform (e.g. "medium").

 None
title_keyword Optional[str]

Substring search on item title.

 None
privacy_filter Optional[str]

One of "public", "network", "private".

 None
unread_only bool

Return only unread items.

 False
date_from Optional[str]

ISO-8601 lower bound on content_published_at.

 None
date_to Optional[str]

ISO-8601 upper bound on content_published_at.

 None

Returns:

Type Description
dict

Dict with items list and pagination info.
Source code in superme_sdk/services/_library.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def get_learnings(
    self,
    *,
    limit: Optional[int] = None,
    offset: int = 0,
    collection: Optional[str] = None,
    platform: Optional[str] = None,
    title_keyword: Optional[str] = None,
    privacy_filter: Optional[str] = None,
    unread_only: bool = False,
    date_from: Optional[str] = None,
    date_to: Optional[str] = None,
) -> dict:
    """List knowledge items in the authenticated user's library.

    Example:
        ```python
        page = client.get_learnings(limit=20)
        for item in page["items"]:
            print(item["learning_id"], item["title"])

        # filter to external content only
        page = client.get_learnings(collection="external", limit=10)
        ```

    Args:
        limit: Maximum items to return. Omit for backend default.
        offset: Pagination offset (default 0).
        collection: Filter by type — ``"internal"``, ``"external"``,
            or ``"social"``.
        platform: Filter by source platform (e.g. ``"medium"``).
        title_keyword: Substring search on item title.
        privacy_filter: One of ``"public"``, ``"network"``, ``"private"``.
        unread_only: Return only unread items.
        date_from: ISO-8601 lower bound on ``content_published_at``.
        date_to: ISO-8601 upper bound on ``content_published_at``.

    Returns:
        Dict with ``items`` list and pagination info.
    """
    uid = self.user_id
    if not uid:
        raise ValueError("Cannot extract user_id from token")

    params: dict[str, Any] = {"user_id": uid, "offset": offset}
    if limit is not None:
        params["limit"] = limit
    if collection is not None:
        params["collection"] = collection
    if platform is not None:
        params["platform"] = platform
    if title_keyword is not None:
        params["title_keyword"] = title_keyword
    if privacy_filter is not None:
        params["privacy_filter"] = privacy_filter
    if unread_only:
        params["unread_only"] = True
    if date_from is not None:
        params["date_from"] = date_from
    if date_to is not None:
        params["date_to"] = date_to

    resp = self._rest_http.get("/api/v3/library", params=params)
    self._check_rest_response(resp)
    return resp.json()

get_learning 

get_learning(learning_id: str) -> dict

Fetch a single library item by ID.

Example 
item = client.get_learning("learning_abc123")
print(item["title"], item["summary"])

Parameters:

Name Type Description Default
learning_id str

The learning ID (from :meth:get_learnings).

 required

Returns:

Type Description
dict

Dict with full learning metadata and content.
Source code in superme_sdk/services/_library.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def get_learning(self, learning_id: str) -> dict:
    """Fetch a single library item by ID.

    Example:
        ```python
        item = client.get_learning("learning_abc123")
        print(item["title"], item["summary"])
        ```

    Args:
        learning_id: The learning ID (from :meth:`get_learnings`).

    Returns:
        Dict with full learning metadata and content.
    """
    resp = self._rest_http.get(
        "/api/v3/library/getlearning", params={"learning_id": learning_id}
    )
    self._check_rest_response(resp)
    return resp.json()

get_ingestion_status 

get_ingestion_status() -> dict

Check the ingestion status of the authenticated user's library.

Returns a summary of how many items are pending, processing, done, or failed. Useful to poll after :meth:add_external_content to know when URLs finish processing.

Example 
status = client.get_ingestion_status()
print(status)

Returns:

Type Description
dict

Dict with ingestion counts and status breakdown.
Source code in superme_sdk/services/_library.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def get_ingestion_status(self) -> dict:
    """Check the ingestion status of the authenticated user's library.

    Returns a summary of how many items are pending, processing, done,
    or failed. Useful to poll after :meth:`add_external_content` to know
    when URLs finish processing.

    Example:
        ```python
        status = client.get_ingestion_status()
        print(status)
        ```

    Returns:
        Dict with ingestion counts and status breakdown.
    """
    uid = self.user_id
    if not uid:
        raise ValueError("Cannot extract user_id from token")

    resp = self._rest_http.get("/api/v3/library/ingestion", params={"user_id": uid})
    self._check_rest_response(resp)
    return resp.json()