semble-api 0.0.1__py3-none-any.whl

semble/__init__.py

@@ -0,0 +1,33 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from semble._client import AsyncSemble, Semble
+from semble.settings import DEFAULT_BASE_URL, SembleSettings
+from semble._exceptions import (
+    APIStatusError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SembleError,
+    ServerError,
+)
+
+try:
+    __version__ = version("semble-api")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "APIStatusError",
+    "AsyncSemble",
+    "AuthenticationError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "Semble",
+    "SembleError",
+    "SembleSettings",
+    "ServerError",
+    "__version__",
+]

semble/_client.py

@@ -0,0 +1,204 @@
+from types import TracebackType
+from typing import Any
+
+import httpx2 as httpx
+from pydantic import SecretStr
+
+from semble._exceptions import status_error
+from semble.resources.actors import Actors, AsyncActors
+from semble.resources.cards import AsyncCards, Cards
+from semble.resources.collections import AsyncCollections, Collections
+from semble.resources.connections import AsyncConnections, Connections
+from semble.resources.feeds import AsyncFeeds, Feeds
+from semble.resources.graph import AsyncGraph, Graph
+from semble.resources.notifications import AsyncNotifications, Notifications
+from semble.resources.search import AsyncSearch, Search
+from semble.settings import SembleSettings
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        api_key: str | SecretStr | None,
+        base_url: str | None,
+        timeout: float | None,
+    ) -> None:
+        settings = SembleSettings()
+        if api_key is None:
+            self.api_key = settings.api_key
+        elif isinstance(api_key, str):
+            self.api_key = SecretStr(api_key) if api_key else None
+        else:
+            self.api_key = api_key
+        self.base_url = (base_url or settings.base_url).rstrip("/")
+        self.timeout = timeout if timeout is not None else settings.timeout
+
+    def _url(self, nsid: str) -> str:
+        return f"{self.base_url}/{nsid}"
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"accept": "application/json"}
+        if self.api_key is not None:
+            headers["x-api-key"] = self.api_key.get_secret_value()
+        return headers
+
+    @staticmethod
+    def _parse(response: httpx.Response, cast_to: Any) -> Any:
+        if not response.is_success:
+            raise status_error(response)
+        if not response.content:
+            return None
+        data = response.json()
+        if cast_to is None:
+            return data
+        return cast_to.model_validate(data)
+
+
+class Semble(_BaseClient):
+    """synchronous client for the semble api.
+
+    configuration not passed explicitly comes from `SembleSettings`
+    (`SEMBLE_*` environment variables, then a local `.env` file). create
+    keys at https://semble.so/settings/api-keys.
+
+    usable directly or as a context manager. `close()` only closes the
+    underlying http client if this client created it — a borrowed
+    `http_client` stays open and its lifecycle (including its timeout)
+    remains the caller's.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | SecretStr | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(timeout=self.timeout)
+
+        self.actors = Actors(self)
+        self.cards = Cards(self)
+        self.collections = Collections(self)
+        self.connections = Connections(self)
+        self.feeds = Feeds(self)
+        self.graph = Graph(self)
+        self.notifications = Notifications(self)
+        self.search = Search(self)
+
+    def get(
+        self,
+        nsid: str,
+        params: dict[str, Any] | None = None,
+        *,
+        cast_to: Any = None,
+    ) -> Any:
+        """GET an xrpc query by nsid. escape hatch for unwrapped endpoints."""
+        response = self._http.get(
+            self._url(nsid), params=params, headers=self._headers()
+        )
+        return self._parse(response, cast_to)
+
+    def post(
+        self,
+        nsid: str,
+        json: dict[str, Any] | None = None,
+        *,
+        cast_to: Any = None,
+    ) -> Any:
+        """POST an xrpc procedure by nsid. escape hatch for unwrapped endpoints."""
+        response = self._http.post(self._url(nsid), json=json, headers=self._headers())
+        return self._parse(response, cast_to)
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "Semble":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncSemble(_BaseClient):
+    """asynchronous client for the semble api.
+
+    configuration not passed explicitly comes from `SembleSettings`
+    (`SEMBLE_*` environment variables, then a local `.env` file). create
+    keys at https://semble.so/settings/api-keys.
+
+    usable directly or as a context manager. `close()` only closes the
+    underlying http client if this client created it — a borrowed
+    `http_client` stays open and its lifecycle (including its timeout)
+    remains the caller's.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | SecretStr | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=self.timeout)
+
+        self.actors = AsyncActors(self)
+        self.cards = AsyncCards(self)
+        self.collections = AsyncCollections(self)
+        self.connections = AsyncConnections(self)
+        self.feeds = AsyncFeeds(self)
+        self.graph = AsyncGraph(self)
+        self.notifications = AsyncNotifications(self)
+        self.search = AsyncSearch(self)
+
+    async def get(
+        self,
+        nsid: str,
+        params: dict[str, Any] | None = None,
+        *,
+        cast_to: Any = None,
+    ) -> Any:
+        """GET an xrpc query by nsid. escape hatch for unwrapped endpoints."""
+        response = await self._http.get(
+            self._url(nsid), params=params, headers=self._headers()
+        )
+        return self._parse(response, cast_to)
+
+    async def post(
+        self,
+        nsid: str,
+        json: dict[str, Any] | None = None,
+        *,
+        cast_to: Any = None,
+    ) -> Any:
+        """POST an xrpc procedure by nsid. escape hatch for unwrapped endpoints."""
+        response = await self._http.post(
+            self._url(nsid), json=json, headers=self._headers()
+        )
+        return self._parse(response, cast_to)
+
+    async def close(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncSemble":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()

semble/_exceptions.py

@@ -0,0 +1,60 @@
+import httpx2 as httpx
+
+
+class SembleError(Exception):
+    """base for all errors raised by this library."""
+
+
+class APIStatusError(SembleError):
+    """a non-2xx response from the semble api."""
+
+    def __init__(self, message: str, *, response: httpx.Response) -> None:
+        super().__init__(message)
+        self.message = message
+        self.response = response
+        self.status_code = response.status_code
+
+
+class AuthenticationError(APIStatusError):
+    """401 — missing or invalid api key."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """403 — authenticated but not allowed."""
+
+
+class NotFoundError(APIStatusError):
+    """404 — no such resource."""
+
+
+class RateLimitError(APIStatusError):
+    """429 — slow down."""
+
+
+class ServerError(APIStatusError):
+    """5xx — something broke on semble's end."""
+
+
+_STATUS_ERRORS: dict[int, type[APIStatusError]] = {
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+def status_error(response: httpx.Response) -> APIStatusError:
+    message = ""
+    try:
+        data = response.json()
+    except ValueError:
+        data = None
+    if isinstance(data, dict):
+        message = data.get("message") or data.get("error") or ""
+    if not message:
+        message = response.text.strip() or f"HTTP {response.status_code}"
+
+    cls = _STATUS_ERRORS.get(response.status_code)
+    if cls is None:
+        cls = ServerError if response.status_code >= 500 else APIStatusError
+    return cls(message, response=response)

semble/_utils.py

@@ -0,0 +1,9 @@
+from typing import Any
+
+
+def drop_none(**kwargs: Any) -> dict[str, Any]:
+    """build a params/body dict, omitting unset values.
+
+    keys are passed in api casing (camelCase) directly.
+    """
+    return {k: v for k, v in kwargs.items() if v is not None}

semble/cli.py

@@ -0,0 +1,158 @@
+"""command-line interface for semble.
+
+machine-readable by default: lists are ndjson (one json object per line,
+api-cased keys) and single results are one json object, so output pipes
+straight into jq or an agent. pass --pretty for human-formatted output.
+
+requires the `cli` extra: `uv add 'semble-api[cli]'`.
+"""
+
+import json
+from typing import Any
+
+try:
+    import cyclopts
+except ImportError as exc:  # pragma: no cover
+    raise SystemExit(
+        "the semble cli requires the `cli` extra: uv add 'semble-api[cli]'"
+    ) from exc
+
+from pydantic import BaseModel
+
+import semble
+from semble import Semble, SembleError
+
+app = cyclopts.App(
+    name="semble",
+    help="interact with semble (semble.so) from the terminal",
+    version=semble.__version__,
+)
+
+
+def _dump(model: BaseModel) -> dict[str, Any]:
+    return model.model_dump(by_alias=True, exclude_none=True, mode="json")
+
+
+def _emit(data: BaseModel | dict[str, Any]) -> None:
+    if isinstance(data, BaseModel):
+        data = _dump(data)
+    print(json.dumps(data))
+
+
+@app.command
+def whoami(*, pretty: bool = False) -> None:
+    """show my profile and unread notification count."""
+    with Semble() as client:
+        me = client.actors.get_my_profile(include_stats=True)
+        unread = client.notifications.get_unread_count()
+        count = unread.unread_count if unread.unread_count is not None else unread.count
+
+        if not pretty:
+            _emit({"profile": _dump(me), "unreadNotifications": count})
+            return
+
+        print(f"@{me.handle} ({me.name})")
+        print(f"  cards: {me.url_card_count}")
+        print(f"  collections: {me.collection_count}")
+        print(f"  connections: {me.connection_count}")
+        print(f"  followers: {me.follower_count} / following: {me.following_count}")
+        print(f"  unread notifications: {count}")
+
+
+@app.command
+def feed(limit: int = 10, *, following: bool = False, pretty: bool = False) -> None:
+    """show recent activity from the global (or following) feed."""
+    with Semble() as client:
+        get = client.feeds.get_following if following else client.feeds.get_global
+        for activity in get(limit=limit):
+            if not pretty:
+                _emit(activity)
+                continue
+            when = f"{activity.created_at:%m-%d %H:%M}" if activity.created_at else "?"
+            who = f"@{activity.user.handle}" if activity.user else "?"
+            what = activity.card.url if activity.card else ""
+            print(f"{when}  {activity.activity_type:<22} {who:<24} {what}")
+
+
+@app.command
+def search(query: str, limit: int = 10, *, pretty: bool = False) -> None:
+    """semantic search across semble."""
+    with Semble() as client:
+        for hit in client.search.semantic(query, limit=limit):
+            if not pretty:
+                _emit(hit)
+                continue
+            title = (
+                hit.metadata.title
+                if hit.metadata and hit.metadata.title
+                else "(untitled)"
+            )
+            print(f"{title}\n  {hit.url}\n")
+
+
+@app.command
+def library(
+    handle: str | None = None, limit: int = 10, *, pretty: bool = False
+) -> None:
+    """list cards in a library — mine by default, or any user's."""
+    with Semble() as client:
+        if handle:
+            page = client.cards.list_by_user(handle, limit=limit)
+        else:
+            page = client.cards.list_mine(limit=limit)
+
+        for card in page:
+            if not pretty:
+                _emit(card)
+                continue
+            note = f"  [note: {card.note.text}]" if card.note and card.note.text else ""
+            print(f"{card.id}  {card.url}{note}")
+
+        if pretty and page.pagination and page.pagination.total_count is not None:
+            print(f"\n{len(page)} of {page.pagination.total_count} cards")
+
+
+@app.command
+def add(
+    url: str,
+    *,
+    note: str | None = None,
+    collection: list[str] | None = None,
+    pretty: bool = False,
+) -> None:
+    """add a url to my library, optionally with a note and collection ids."""
+    with Semble() as client:
+        added = client.cards.add_url(url, note=note, collection_ids=collection)
+
+        if not pretty:
+            _emit(added)
+            return
+
+        print(f"added {url}")
+        print(f"  url card: {added.url_card_id}")
+        if added.note_card_id:
+            print(f"  note card: {added.note_card_id}")
+
+
+@app.command
+def rm(card_id: str, *, pretty: bool = False) -> None:
+    """remove a card from my library."""
+    with Semble() as client:
+        client.cards.remove_from_library(card_id)
+
+        if not pretty:
+            _emit({"cardId": card_id, "removed": True})
+            return
+
+        print(f"removed {card_id}")
+
+
+def main() -> None:
+    try:
+        app()
+    except SembleError as exc:
+        raise SystemExit(f"error: {exc}") from exc
+
+
+if __name__ == "__main__":
+    main()

semble/mcp.py

@@ -0,0 +1,42 @@
+"""code-mode mcp server over the semble sdk.
+
+instead of one mcp tool per endpoint, the full sdk surface is registered
+host-side and hidden behind fastmcp's CodeMode transform — clients see only
+`search` / `get_schema` / `execute`, and compose sdk calls as python running
+in a monty sandbox.
+
+requires the `mcp` extra: `uv add 'semble-api[mcp]'`.
+"""
+
+import inspect
+
+try:
+    from fastmcp import FastMCP
+    from fastmcp.experimental.transforms.code_mode import CodeMode
+except ImportError as exc:  # pragma: no cover
+    raise SystemExit(
+        "the semble mcp server requires the `mcp` extra: uv add 'semble-api[mcp]'"
+    ) from exc
+
+from semble import Semble
+from semble.resources._base import SyncResource
+
+
+def build_server(client: Semble | None = None) -> FastMCP:
+    client = client or Semble()
+    mcp = FastMCP("semble", transforms=[CodeMode()])
+    resources = {
+        name: attr
+        for name, attr in vars(client).items()
+        if isinstance(attr, SyncResource)
+    }
+    for resource_name, resource in sorted(resources.items()):
+        for name, method in inspect.getmembers(resource, inspect.ismethod):
+            if name.startswith("_"):
+                continue
+            mcp.tool(method, name=f"{resource_name}_{name}", tags={resource_name})
+    return mcp
+
+
+def main() -> None:
+    build_server().run()

semble/records.py

@@ -0,0 +1,82 @@
+"""atproto record shapes for the network.cosmik.* lexicons.
+
+these model the records as they live on a pds, separate from the app-view
+dtos in `semble.types`. useful when reading or writing semble records
+directly (e.g. with pdsx or the atproto sdk) instead of going through the
+api.
+"""
+
+from typing import Any
+
+from pydantic import Field
+
+from semble.types import Model
+
+RECORD_TYPE_CARD = "network.cosmik.card"
+RECORD_TYPE_URL_CONTENT = "network.cosmik.card#urlContent"
+RECORD_TYPE_NOTE_CONTENT = "network.cosmik.card#noteContent"
+RECORD_TYPE_COLLECTION = "network.cosmik.collection"
+RECORD_TYPE_COLLECTION_LINK = "network.cosmik.collectionLink"
+RECORD_TYPE_PROVENANCE = "network.cosmik.defs#provenance"
+
+CARD_TYPE_URL = "URL"
+CARD_TYPE_NOTE = "NOTE"
+
+
+class StrongRef(Model):
+    """an atproto strong reference: an at-uri plus the record cid."""
+
+    uri: str
+    cid: str
+
+
+class URLMetadataRecord(Model):
+    record_type: str | None = Field(default=None, alias="$type")
+    content_type: str | None = Field(default=None, alias="type")
+    title: str | None = None
+    description: str | None = None
+    author: str | None = None
+    site_name: str | None = None
+    image_url: str | None = None
+    published_date: str | None = None
+    retrieved_at: str | None = None
+
+
+class URLContentRecord(Model):
+    record_type: str = Field(default=RECORD_TYPE_URL_CONTENT, alias="$type")
+    url: str
+    metadata: URLMetadataRecord | None = None
+
+
+class NoteContentRecord(Model):
+    record_type: str = Field(default=RECORD_TYPE_NOTE_CONTENT, alias="$type")
+    text: str
+
+
+class ProvenanceRecord(Model):
+    record_type: str = Field(default=RECORD_TYPE_PROVENANCE, alias="$type")
+    via: StrongRef | None = None
+
+
+class CardRecord(Model):
+    record_type: str = Field(default=RECORD_TYPE_CARD, alias="$type")
+    card_type: str = Field(alias="type")
+    content: Any = None
+    url: str | None = None
+    parent_card: StrongRef | None = None
+    created_at: str
+    provenance: ProvenanceRecord | None = None
+
+
+class CollectionRecord(Model):
+    record_type: str = Field(default=RECORD_TYPE_COLLECTION, alias="$type")
+    name: str
+    description: str | None = None
+    created_at: str
+
+
+class CollectionLinkRecord(Model):
+    record_type: str = Field(default=RECORD_TYPE_COLLECTION_LINK, alias="$type")
+    card: StrongRef
+    collection: StrongRef
+    created_at: str

semble/resources/__init__.py

@@ -0,0 +1,8 @@
+from semble.resources.actors import Actors, AsyncActors
+from semble.resources.cards import AsyncCards, Cards
+from semble.resources.collections import AsyncCollections, Collections
+from semble.resources.connections import AsyncConnections, Connections
+from semble.resources.feeds import AsyncFeeds, Feeds
+from semble.resources.graph import AsyncGraph, Graph
+from semble.resources.notifications import AsyncNotifications, Notifications
+from semble.resources.search import AsyncSearch, Search

semble/resources/_base.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from semble._client import AsyncSemble, Semble
+
+
+class SyncResource:
+    def __init__(self, client: "Semble") -> None:
+        self._client = client
+
+
+class AsyncResource:
+    def __init__(self, client: "AsyncSemble") -> None:
+        self._client = client

semble/resources/actors.py

@@ -0,0 +1,35 @@
+"""network.cosmik.actor.* — user profiles."""
+
+from semble._utils import drop_none
+from semble.resources._base import AsyncResource, SyncResource
+from semble.types import User
+
+
+class Actors(SyncResource):
+    def get_my_profile(self, *, include_stats: bool | None = None) -> User:
+        params = drop_none(includeStats=include_stats)
+        return self._client.get(
+            "network.cosmik.actor.getMyProfile", params, cast_to=User
+        )
+
+    def get_profile(
+        self, identifier: str, *, include_stats: bool | None = None
+    ) -> User:
+        params = drop_none(identifier=identifier, includeStats=include_stats)
+        return self._client.get("network.cosmik.actor.getProfile", params, cast_to=User)
+
+
+class AsyncActors(AsyncResource):
+    async def get_my_profile(self, *, include_stats: bool | None = None) -> User:
+        params = drop_none(includeStats=include_stats)
+        return await self._client.get(
+            "network.cosmik.actor.getMyProfile", params, cast_to=User
+        )
+
+    async def get_profile(
+        self, identifier: str, *, include_stats: bool | None = None
+    ) -> User:
+        params = drop_none(identifier=identifier, includeStats=include_stats)
+        return await self._client.get(
+            "network.cosmik.actor.getProfile", params, cast_to=User
+        )