semble-api 0.0.1__tar.gz → 0.0.2__tar.gz

{semble_api-0.0.1 → semble_api-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: semble-api
-Version: 0.0.1
+Version: 0.0.2
 Summary: python client for the semble api
 Author-email: zzstoatzz <thrast36@gmail.com>
 License-Expression: MIT
@@ -10,14 +10,12 @@ 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-Python: >=3.12
 Requires-Dist: httpx2>=2.3.0
 Requires-Dist: pydantic-settings>=2.14.1
 Requires-Dist: pydantic>=2.7
@@ -134,13 +132,27 @@ semble feed --pretty
 
 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.
 
+create an api key at [semble.so/settings/api-keys](https://semble.so/settings/api-keys), then:
+
 ```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
+claude mcp add semble -e SEMBLE_API_KEY=your-key -- uvx --from 'semble-api[mcp]' semble-mcp
+```
+
+for other mcp clients (claude desktop, cursor, ...), the equivalent json config:
+
+```json
+{
+  "mcpServers": {
+    "semble": {
+      "command": "uvx",
+      "args": ["--from", "semble-api[mcp]", "semble-mcp"],
+      "env": { "SEMBLE_API_KEY": "your-key" }
+    }
+  }
+}
 ```
 
-auth comes from `SEMBLE_API_KEY` (environment or `.env`); without a key the server is limited to public reads.
+the key is optional — without it the server is limited to public reads. the server also picks up `SEMBLE_API_KEY` from the environment or a `.env` in the working directory, so inside a checkout of this repo a plain `claude mcp add semble -- uv run --directory /path/to/this/repo semble-mcp` works too.
 
 ## examples
 
@@ -160,6 +172,7 @@ just check  # ty
 
 ## see also
 
+- [semble for agents](docs/agent-surfaces.md) — choosing between the sdk, cli, and mcp surfaces when wiring up agents
 - [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 → semble_api-0.0.2}/README.md

@@ -105,13 +105,27 @@ semble feed --pretty
 
 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.
 
+create an api key at [semble.so/settings/api-keys](https://semble.so/settings/api-keys), then:
+
 ```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
+claude mcp add semble -e SEMBLE_API_KEY=your-key -- uvx --from 'semble-api[mcp]' semble-mcp
+```
+
+for other mcp clients (claude desktop, cursor, ...), the equivalent json config:
+
+```json
+{
+  "mcpServers": {
+    "semble": {
+      "command": "uvx",
+      "args": ["--from", "semble-api[mcp]", "semble-mcp"],
+      "env": { "SEMBLE_API_KEY": "your-key" }
+    }
+  }
+}
 ```
 
-auth comes from `SEMBLE_API_KEY` (environment or `.env`); without a key the server is limited to public reads.
+the key is optional — without it the server is limited to public reads. the server also picks up `SEMBLE_API_KEY` from the environment or a `.env` in the working directory, so inside a checkout of this repo a plain `claude mcp add semble -- uv run --directory /path/to/this/repo semble-mcp` works too.
 
 ## examples
 
@@ -131,6 +145,7 @@ just check  # ty
 
 ## see also
 
+- [semble for agents](docs/agent-surfaces.md) — choosing between the sdk, cli, and mcp surfaces when wiring up agents
 - [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.2/docs/agent-surfaces.md

@@ -0,0 +1,74 @@
+# semble for agents
+
+this package ships three surfaces for the same api: a python sdk, a cli, and an mcp server. they share one auth story (`SEMBLE_API_KEY` from the environment or a `.env`; without it, public reads only) and one underlying client — the differences are about *where your agent runs and what it can touch*. this doc is for people wiring semble into agents, not for people developing this repo.
+
+## at a glance
+
+| surface | install | the agent is... |
+| ------- | ------- | --------------- |
+| sdk     | `uv add semble-api` | python you're writing (scripts, pydantic-ai tools, pipelines) |
+| cli     | `uv add 'semble-api[cli]'` / `uvx` | something with a shell (claude code, codex, a cron job) |
+| mcp     | `claude mcp add semble -e SEMBLE_API_KEY=... -- uvx --from 'semble-api[mcp]' semble-mcp` | an mcp client, especially one without a shell (claude desktop, cursor) |
+
+## the sdk
+
+the substrate everything else is built on. typed sync/async clients over all ~50 `network.cosmik.*` endpoints, pydantic models on every response, snake_case in / camelCase on the wire, and an escape hatch (`client.get(nsid, params)`) for anything unwrapped.
+
+```python
+from semble import Semble
+
+with Semble() as client:
+    for hit in client.search.semantic("agent memory", limit=5):
+        print(hit.url)
+```
+
+use it when the agent *is* your code: tool functions in an agent framework, batch curation jobs, anything where you want validation errors before the network and real types after it. this is also the surface to build new surfaces from — the mcp server below is ~40 lines over it.
+
+## the cli
+
+`semble` is machine-readable by default, which makes it an agent tool as much as a human one: lists are ndjson, single results are one json object, keys are the api's camelCase. no flags needed to make it parseable — `--pretty` is the opt-in for humans, not the other way around.
+
+```bash
+semble search "durable execution" | jq -r '.url'
+semble add https://example.com --note "worth a read"
+semble library pdewey.com
+```
+
+if your agent already has shell access, this is usually the right surface: zero integration work, composes with `jq`/`xargs`/everything, and each invocation is a fresh process with no session to manage. an agent that can run bash needs nothing else to read and write semble.
+
+## the mcp server
+
+`semble-mcp` exposes the sdk to mcp clients via [fastmcp code mode](https://gofastmcp.com/servers/transforms/code-mode). instead of one tool per endpoint (which puts ~50 schemas in the model's context before any work happens), clients see three meta-tools:
+
+- `search` — find sdk methods by keyword
+- `get_schema` — fetch parameter schemas for chosen methods
+- `execute` — run model-written python in a [monty](https://github.com/pydantic/monty) sandbox, composing methods via `await call_tool("cards_search", {...})`
+
+the payoff is composition without context cost: a workflow like "semantic search, then fetch who saved each hit, then summarize" is one `execute` block and one result in context, instead of n tool round-trips each hauling intermediate json through the model. params use the sdk's snake_case names (discover them via `get_schema` — don't guess), and mistakes come back as precise pydantic validation errors the model can fix in-loop, before anything hits the network.
+
+prefer it when:
+
+- the client has no shell (claude desktop, cursor, most hosted agents) — mcp is the only door, and three tools beat fifty
+- workflows are composition-heavy and context economy matters, even if a shell exists
+- you want the tool surface to track the sdk automatically — the server reflects over the client, so new sdk methods appear without anyone maintaining tool definitions
+
+know the caveats: mcp client quality varies a lot in practice (see [mcpval](https://dev-log.prefect.io/mcpval/) — judge a server by what your client can actually accomplish with it, not by what it exposes), and the server is stdio + env-var auth today, launched per-user by the client rather than hosted.
+
+## choosing
+
+the short version: **shell → cli, your own python → sdk, neither → mcp.** code mode is the exception that can earn its place alongside a shell, when multi-call composition would otherwise drag intermediate results through context.
+
+one thing that is *not* a differentiator: capability. all three surfaces carry the full read/write power of the api key behind them. pick by runtime fit, not by trying to use the surface as a permission boundary — if you want an agent restricted to reads, give it no key (public reads work) rather than a narrower surface.
+
+## writes are public
+
+semble is a social knowledge graph on atproto: cards, notes, collections, and connections your agent creates are real records, visible to the network and attributed to the account behind the key. that's the point — shared curation trails are what make the graph worth reading — but it means an agent writing to semble is publishing, not journaling.
+
+a few norms keep the graph high-signal:
+
+- write with intent: a url with a note saying *why* beats ten bare urls
+- curate into collections rather than dumping into the library root
+- connections (`supports`, `opposes`, `explains`, ...) are claims — make them when the relationship is real, not to inflate linkage
+- cleanup is part of write access: `remove_from_library`, `collections.delete`, and friends work the same as the adds
+
+for the wider picture of agents as curators, see [semble + agents](https://nate.leaflet.pub/3mnxnia4lvk2n).

{semble_api-0.0.1 → semble_api-0.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ dynamic = ["version"]
 description = "python client for the semble api"
 readme = "README.md"
 authors = [{ name = "zzstoatzz", email = "thrast36@gmail.com" }]
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 license = "MIT"
 
 keywords = ["semble", "atproto", "bookmarks", "curation", "knowledge-graph"]
@@ -14,8 +14,6 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
@@ -111,4 +109,4 @@ exclude = [
 ]
 
 [tool.ty.environment]
-python-version = "3.10"
+python-version = "3.12"

{semble_api-0.0.1 → semble_api-0.0.2}/src/semble/_client.py

@@ -1,10 +1,10 @@
 from types import TracebackType
-from typing import Any
+from typing import Any, overload
 
 import httpx2 as httpx
-from pydantic import SecretStr
+from pydantic import BaseModel, SecretStr
 
-from semble._exceptions import status_error
+from semble._exceptions import SembleError, status_error
 from semble.resources.actors import Actors, AsyncActors
 from semble.resources.cards import AsyncCards, Cards
 from semble.resources.collections import AsyncCollections, Collections
@@ -16,6 +16,25 @@ from semble.resources.search import AsyncSearch, Search
 from semble.settings import SembleSettings
 
 
+@overload
+def _parse[T: BaseModel](response: httpx.Response, cast_to: type[T]) -> T: ...
+@overload
+def _parse(response: httpx.Response, cast_to: None) -> Any: ...
+def _parse[T: BaseModel](response: httpx.Response, cast_to: type[T] | None) -> Any:
+    if not response.is_success:
+        raise status_error(response)
+    if not response.content:
+        if cast_to is not None:
+            raise SembleError(
+                f"expected a json body from {response.request.url}, got an empty response"
+            )
+        return None
+    data = response.json()
+    if cast_to is None:
+        return data
+    return cast_to.model_validate(data)
+
+
 class _BaseClient:
     def __init__(
         self,
@@ -42,17 +61,6 @@ class _BaseClient:
             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.
@@ -88,29 +96,45 @@ class Semble(_BaseClient):
         self.notifications = Notifications(self)
         self.search = Search(self)
 
+    @overload
+    def get[T: BaseModel](
+        self, nsid: str, params: dict[str, Any] | None = None, *, cast_to: type[T]
+    ) -> T: ...
+    @overload
     def get(
+        self, nsid: str, params: dict[str, Any] | None = None, *, cast_to: None = None
+    ) -> Any: ...
+    def get[T: BaseModel](
         self,
         nsid: str,
         params: dict[str, Any] | None = None,
         *,
-        cast_to: Any = None,
+        cast_to: type[T] | None = 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)
+        return _parse(response, cast_to)
 
+    @overload
+    def post[T: BaseModel](
+        self, nsid: str, json: dict[str, Any] | None = None, *, cast_to: type[T]
+    ) -> T: ...
+    @overload
     def post(
+        self, nsid: str, json: dict[str, Any] | None = None, *, cast_to: None = None
+    ) -> Any: ...
+    def post[T: BaseModel](
         self,
         nsid: str,
         json: dict[str, Any] | None = None,
         *,
-        cast_to: Any = None,
+        cast_to: type[T] | None = 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)
+        return _parse(response, cast_to)
 
     def close(self) -> None:
         if self._owns_http:
@@ -162,31 +186,47 @@ class AsyncSemble(_BaseClient):
         self.notifications = AsyncNotifications(self)
         self.search = AsyncSearch(self)
 
+    @overload
+    async def get[T: BaseModel](
+        self, nsid: str, params: dict[str, Any] | None = None, *, cast_to: type[T]
+    ) -> T: ...
+    @overload
     async def get(
+        self, nsid: str, params: dict[str, Any] | None = None, *, cast_to: None = None
+    ) -> Any: ...
+    async def get[T: BaseModel](
         self,
         nsid: str,
         params: dict[str, Any] | None = None,
         *,
-        cast_to: Any = None,
+        cast_to: type[T] | None = 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)
+        return _parse(response, cast_to)
 
+    @overload
+    async def post[T: BaseModel](
+        self, nsid: str, json: dict[str, Any] | None = None, *, cast_to: type[T]
+    ) -> T: ...
+    @overload
     async def post(
+        self, nsid: str, json: dict[str, Any] | None = None, *, cast_to: None = None
+    ) -> Any: ...
+    async def post[T: BaseModel](
         self,
         nsid: str,
         json: dict[str, Any] | None = None,
         *,
-        cast_to: Any = None,
+        cast_to: type[T] | None = 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)
+        return _parse(response, cast_to)
 
     async def close(self) -> None:
         if self._owns_http:

{semble_api-0.0.1 → semble_api-0.0.2}/src/semble/types.py

@@ -7,7 +7,7 @@ never break parsing.
 """
 
 from datetime import datetime
-from typing import Any, Generic, Literal, TypeVar
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 from pydantic.alias_generators import to_camel
@@ -220,8 +220,6 @@ class CountResponse(Model):
     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.
@@ -240,7 +238,7 @@ _ITEM_KEYS = (
 )
 
 
-class Page(Model, Generic[ItemT]):
+class Page[ItemT](Model):
     items: list[ItemT] = Field(default_factory=list)
     pagination: Pagination | None = None
     sorting: Any = None

{semble_api-0.0.1 → semble_api-0.0.2}/tests/test_client.py

@@ -9,11 +9,34 @@ from semble import (
     NotFoundError,
     RateLimitError,
     Semble,
+    SembleError,
     ServerError,
 )
+from semble.types import CountResponse
 from tests.conftest import AsyncClientFactory, SyncClientFactory
 
 
+def empty_response_client() -> Semble:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200)
+
+    return Semble(
+        api_key="sk_test",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+
+def test_empty_body_without_cast_to_returns_none() -> None:
+    assert empty_response_client().post("network.cosmik.card.updateNote", {}) is None
+
+
+def test_empty_body_with_cast_to_raises() -> None:
+    with pytest.raises(SembleError, match="expected a json body"):
+        empty_response_client().get(
+            "network.cosmik.notification.getUnreadCount", cast_to=CountResponse
+        )
+
+
 def test_api_key_header(sync_client: SyncClientFactory) -> None:
     client, recorder = sync_client({"count": 0})
     client.notifications.get_unread_count()