semble-api 0.0.1__py3-none-any.whl

semble/types.py

@@ -0,0 +1,268 @@
+"""response models and shared types for the semble api.
+
+field names are snake_case in python and map to the api's camelCase via
+pydantic aliases. enum-ish request parameters are typed as `Literal` aliases;
+the same fields on response models are plain `str` so new server-side values
+never break parsing.
+"""
+
+from datetime import datetime
+from typing import Any, Generic, Literal, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic.alias_generators import to_camel
+
+URLType = Literal[
+    "article",
+    "link",
+    "book",
+    "research",
+    "audio",
+    "video",
+    "social",
+    "event",
+    "software",
+]
+
+AccessType = Literal["OPEN", "CLOSED"]
+
+TargetType = Literal["USER", "COLLECTION"]
+
+ConnectionType = Literal[
+    "SUPPORTS",
+    "OPPOSES",
+    "ADDRESSES",
+    "HELPFUL",
+    "LEADS_TO",
+    "RELATED",
+    "SUPPLEMENT",
+    "EXPLAINER",
+]
+
+SortOrder = Literal["asc", "desc"]
+
+
+class Model(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        extra="allow",
+    )
+
+
+class Pagination(Model):
+    current_page: int | None = None
+    total_pages: int | None = None
+    total_count: int | None = None
+    has_more: bool | None = None
+    limit: int | None = None
+    next_cursor: str | None = None
+
+
+class User(Model):
+    id: str | None = None
+    name: str | None = None
+    handle: str | None = None
+    avatar_url: str | None = None
+    banner_url: str | None = None
+    description: str | None = None
+    is_following: bool | None = None
+    follows_you: bool | None = None
+    follower_count: int | None = None
+    following_count: int | None = None
+    followed_collections_count: int | None = None
+    url_card_count: int | None = None
+    collection_count: int | None = None
+    connection_count: int | None = None
+    connections_by_type: dict[str, int] | None = None
+    labels: list[Any] | None = None
+
+
+class URLMetadata(Model):
+    url: str | None = None
+    title: str | None = None
+    description: str | None = None
+    author: str | None = None
+    published_date: str | None = None
+    site_name: str | None = None
+    image_url: str | None = None
+    type: str | None = None
+    retrieved_at: str | None = None
+    doi: str | None = None
+    isbn: str | None = None
+
+
+class URLView(Model):
+    url: str | None = None
+    metadata: URLMetadata | None = None
+    url_library_count: int | None = None
+    url_connection_count: int | None = None
+    url_in_library: bool | None = None
+    url_is_connected: bool | None = None
+
+
+class CardNote(Model):
+    id: str | None = None
+    text: str | None = None
+
+
+class Collection(Model):
+    id: str | None = None
+    uri: str | None = None
+    name: str | None = None
+    author: User | None = None
+    description: str | None = None
+    access_type: str | None = None
+    card_count: int | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    is_following: bool | None = None
+    follower_count: int | None = None
+
+
+class URLCard(Model):
+    type: str | None = None
+    id: str | None = None
+    url: str | None = None
+    uri: str | None = None
+    card_content: Any = None
+    library_count: int | None = None
+    url_library_count: int | None = None
+    url_in_library: bool | None = None
+    url_is_connected: bool | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    author: User | None = None
+    note: CardNote | None = None
+    collections: list[Collection] | None = None
+    libraries: list[User] | None = None
+
+
+class Connection(Model):
+    id: str | None = None
+    type: str | None = None
+    note: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    curator: User | None = None
+
+
+class ConnectionView(Model):
+    connection: Connection
+    source: URLView | None = None
+    target: URLView | None = None
+
+
+class Activity(Model):
+    id: str | None = None
+    activity_type: str | None = None
+    created_at: datetime | None = None
+    user: User | None = None
+    card: URLCard | None = None
+    collections: list[Collection] | None = None
+    connection: ConnectionView | None = None
+
+
+class Notification(Model):
+    id: str | None = None
+    type: str | None = None
+    created_at: datetime | None = None
+    read: bool | None = None
+    user: User | None = None
+    card: URLCard | None = None
+    collections: list[Collection] | None = None
+    connection: ConnectionView | None = None
+    follow_target_type: str | None = None
+    follow_target_id: str | None = None
+
+
+class NoteCard(Model):
+    id: str | None = None
+    note: str | None = None
+    author: User | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class LibraryEntry(Model):
+    user: User
+    card: URLCard | None = None
+
+
+class URLStats(Model):
+    library_count: int | None = None
+    note_count: int | None = None
+    collection_count: int | None = None
+    connections: dict[str, dict[str, int]] | None = None
+
+
+class URLMetadataResponse(Model):
+    metadata: URLMetadata
+    stats: URLStats | None = None
+
+
+class AddURLResponse(Model):
+    url_card_id: str
+    note_card_id: str | None = None
+
+
+class IDResponse(Model):
+    card_id: str | None = None
+    collection_id: str | None = None
+    connection_id: str | None = None
+    follow_id: str | None = None
+    success: bool | None = None
+    marked_count: int | None = None
+
+
+class CountResponse(Model):
+    count: int | None = None
+    unread_count: int | None = None
+
+
+ItemT = TypeVar("ItemT")
+
+# the api names its result array differently per endpoint (cards, users,
+# activities, ...). collect whichever is present into `items` so every
+# paginated response has one stable shape.
+_ITEM_KEYS = (
+    "items",
+    "cards",
+    "collections",
+    "users",
+    "urls",
+    "libraries",
+    "notes",
+    "activities",
+    "actors",
+    "connections",
+    "notifications",
+)
+
+
+class Page(Model, Generic[ItemT]):
+    items: list[ItemT] = Field(default_factory=list)
+    pagination: Pagination | None = None
+    sorting: Any = None
+    unread_count: int | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _collect_items(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "items" not in data:
+            for key in _ITEM_KEYS:
+                if isinstance(data.get(key), list):
+                    return {**data, "items": data[key]}
+        return data
+
+    def __iter__(self) -> Any:
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+
+class CollectionDetail(Collection):
+    url_cards: list[URLCard] | None = None
+    pagination: Pagination | None = None
+    sorting: Any = None

semble_api-0.0.1.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: semble-api
+Version: 0.0.1
+Summary: python client for the semble api
+Author-email: zzstoatzz <thrast36@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: atproto,bookmarks,curation,knowledge-graph,semble
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx2>=2.3.0
+Requires-Dist: pydantic-settings>=2.14.1
+Requires-Dist: pydantic>=2.7
+Provides-Extra: cli
+Requires-Dist: cyclopts>=4.17.0; extra == 'cli'
+Provides-Extra: mcp
+Requires-Dist: fastmcp[code-mode]>=3.4.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# semble-api
+
+python client for the [semble](https://semble.so) api — collaborative bookmarking and knowledge curation on [atproto](https://atproto.com).
+
+built on [httpx2](https://github.com/pydantic/httpx2) and [pydantic](https://docs.pydantic.dev), with sync and async clients.
+
+## installation
+
+```bash
+uv add semble-api
+```
+
+## quick start
+
+create an api key at [semble.so/settings/api-keys](https://semble.so/settings/api-keys), then:
+
+```python
+from semble import Semble
+
+client = Semble()  # reads SEMBLE_API_KEY from the environment or a local .env
+
+# add a url to your library
+result = client.cards.add_url("https://example.com", note="worth a read")
+
+# search your cards
+for card in client.cards.search("durable execution"):
+    print(card.url)
+
+# semantic search across semble
+for hit in client.search.semantic("agent memory", threshold=0.7):
+    print(hit.metadata.title, hit.url)
+```
+
+async is the same surface:
+
+```python
+from semble import AsyncSemble
+
+async with AsyncSemble() as client:
+    profile = await client.actors.get_my_profile(include_stats=True)
+    feed = await client.feeds.get_following(limit=25)
+```
+
+## api surface
+
+resources mirror the `network.cosmik.*` xrpc namespaces:
+
+| namespace             | what's there                                                       |
+| --------------------- | ------------------------------------------------------------------ |
+| `client.cards`        | add/search/list urls and notes, metadata, library status            |
+| `client.collections`  | create/update/delete collections, followers, contributors           |
+| `client.connections`  | typed links between urls (supports, opposes, explains, ...)         |
+| `client.feeds`        | global and following activity feeds                                 |
+| `client.notifications`| list, unread count, mark read                                       |
+| `client.search`       | semantic search, similar urls, account search                       |
+| `client.actors`       | profiles                                                            |
+| `client.graph`        | follow/unfollow users and collections                               |
+
+every endpoint not yet wrapped is reachable via the escape hatch:
+
+```python
+client.get("network.cosmik.card.getLibraryStatus", {"url": "https://example.com"})
+```
+
+`semble.records` has pydantic models for the raw `network.cosmik.*` pds records, if you're reading or writing them directly (e.g. with [pdsx](https://github.com/zzstoatzz/pdsx)).
+
+## configuration
+
+settings come from explicit kwargs, then `SEMBLE_*` environment variables, then a local `.env` file (via [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)):
+
+| setting           | kwarg      | default                       |
+| ----------------- | ---------- | ----------------------------- |
+| `SEMBLE_API_KEY`  | `api_key`  | unauthenticated (public reads work) |
+| `SEMBLE_BASE_URL` | `base_url` | `https://api.semble.so/xrpc`  |
+| `SEMBLE_TIMEOUT`  | `timeout`  | `30.0`                        |
+
+the api key is held as a pydantic `SecretStr`, so it won't leak into logs or reprs.
+
+## cli
+
+a small [cyclopts](https://github.com/BrianPugh/cyclopts) cli ships as an extra:
+
+```bash
+uv add 'semble-api[cli]'
+# or run without installing
+uvx --from 'semble-api[cli]' semble --help
+
+semble whoami                          # auth sanity check
+semble feed 10 --following             # activity feeds
+semble search "durable execution"      # semantic search
+semble library pdewey.com              # anyone's library (or yours, with no handle)
+semble add https://example.com --note "worth a read"
+semble rm <card-id>
+```
+
+output is machine-readable by default — lists are ndjson, single results are one json object, keys match the api's camelCase — so it pipes straight into jq or an agent. add `--pretty` to any command for human-formatted output:
+
+```bash
+semble feed 25 | jq -r '.card.url'
+semble search "agent memory" | jq -r '.metadata.title'
+semble feed --pretty
+```
+
+## mcp server
+
+the `mcp` extra ships a `semble-mcp` entry point that exposes this sdk to mcp clients via [fastmcp code mode](https://gofastmcp.com/servers/transforms/code-mode): three meta-tools (`search` / `get_schema` / `execute`) instead of one tool per endpoint, with model-written python composing sdk calls in a [monty](https://github.com/pydantic/monty) sandbox. intermediate results stay in the sandbox; only the final answer returns to the model's context.
+
+```bash
+claude mcp add semble -- uvx --from 'semble-api[mcp]' semble-mcp
+# or from a checkout
+claude mcp add semble -- uv run --directory /path/to/this/repo semble-mcp
+```
+
+auth comes from `SEMBLE_API_KEY` (environment or `.env`); without a key the server is limited to public reads.
+
+## examples
+
+`scripts/roundtrip.py` exercises the write paths end to end (add url → note → collection → cleanup). it mutates your real account, so run it deliberately:
+
+```bash
+uv run scripts/roundtrip.py
+```
+
+## development
+
+```bash
+just test   # pytest
+just fmt    # ruff format + check
+just check  # ty
+```
+
+## see also
+
+- [semble api docs](https://docs.cosmik.network/semble-api)
+- [@semble.so/api](https://npmx.dev/package/@semble.so/api) — official typescript client
+- [tangled.org/pdewey.com/semble](https://tangled.org/pdewey.com/semble) — go client

semble_api-0.0.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+semble/__init__.py,sha256=vdaWtbrTsHA6GjhS7ovDBApf_6aX4W2OM-cwKJxIaCg,723
+semble/_client.py,sha256=MZCS804_EF4SQ8jMigAN1akjgFnSG0f7OofeljTk9y0,6649
+semble/_exceptions.py,sha256=z8Yg5bm0M7Dmu1R6184mGXxgsEXT3-kGItNhixb62dA,1550
+semble/_utils.py,sha256=MoykBw6yrguVHafJPbQiQJ9Vp01Blw25FG24cXHCbmA,256
+semble/cli.py,sha256=fcJ69ZysdamzIDUWuCg5l3OxqTe4vAv-YOpppzctU00,4881
+semble/mcp.py,sha256=UyMELBL55kOfXH423A_fbu-GAaFCYvfRLMz_5qiq4aY,1339
+semble/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+semble/records.py,sha256=VaqiG2WfWLo0MjAYCF9MNB8B_wq6I1tGlmBCJMRdLcs,2371
+semble/settings.py,sha256=Wrn1zXgwsML1v8FfvOLPvnvkYupxP6FUR84Ylx5DdCY,895
+semble/types.py,sha256=YFioU0N_Gy5cHeZczrQV8Z8wAWSDFchtJx7npQmLYDE,6750
+semble/resources/__init__.py,sha256=3B0TbddYUJ9cjajrwS1tS7YbVMHYMOcOr48wj5crmQY,490
+semble/resources/_base.py,sha256=dL6UNtRMT4C42sR9S24Qgcp6UEJPTE8Hk_N61JUQmas,313
+semble/resources/actors.py,sha256=JbIVXZc3mk4bDPCcwRZvriLi4E8Hn2uEAlHMCKf2irI,1322
+semble/resources/cards.py,sha256=G18KfJY8m396bTN28SM5mPrJFUvwZoOeXA99VaMOR8Y,10870
+semble/resources/collections.py,sha256=4gAiuhV69NjQ02C7sEmpHXFvv2a2jWko9pPxP2Hblx8,13129
+semble/resources/connections.py,sha256=0TqfYyj4hNcvXBKpNIPcz2t8B1P90Kl_9r1zBpO6gp0,6139
+semble/resources/feeds.py,sha256=bmjxYD9oZXnJgRBjG43k8_Fh-2_uCGIUiSB0bycRxfE,3939
+semble/resources/graph.py,sha256=XQgeRc2hgOt-fWPaHGd3pJAE4fBrrM6tsoKbpAHKFJY,5211
+semble/resources/notifications.py,sha256=k0d-InWsQukYQwVLwk213VnQawcrcIo14maOYA1iBkk,2837
+semble/resources/search.py,sha256=6rqq1CR0ZnapEDex9GkUI-6F5FkJmlq81l1gJ6Sxpls,3965
+semble_api-0.0.1.dist-info/METADATA,sha256=YagApeDOY1YARFir8MQCp3K7m18HHiTGbigZ0Zf83dU,6453
+semble_api-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+semble_api-0.0.1.dist-info/entry_points.txt,sha256=zF40iigk3IDcjMCOwurMf_B4iK_Zh0nzplrrCz5YobY,72
+semble_api-0.0.1.dist-info/licenses/LICENSE,sha256=GCaBhyWUE9SeLzklZVA9BKgh424EOjDzofeP-9_OB-8,1066
+semble_api-0.0.1.dist-info/RECORD,,

semble_api-0.0.1.dist-info/WHEEL

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

semble_api-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+semble = semble.cli:main
+semble-mcp = semble.mcp:main

semble_api-0.0.1.dist-info/licenses/LICENSE

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