semble-api 0.0.1__tar.gz

semble_api-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment variables
+.env

semble_api-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+fail_fast: false
+
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.24.1
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.1
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: type-check
+        name: type check
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false

semble_api-0.0.1/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.

semble_api-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,136 @@
+# 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/justfile

@@ -0,0 +1,12 @@
+# run tests
+test:
+    uv run pytest tests/ -x
+
+# format and lint
+fmt:
+    uv run ruff format src/ tests/
+    uv run ruff check src/ tests/ --fix
+
+# type check
+check:
+    uv run ty check

semble_api-0.0.1/pyproject.toml

@@ -0,0 +1,114 @@
+[project]
+name = "semble-api"
+dynamic = ["version"]
+description = "python client for the semble api"
+readme = "README.md"
+authors = [{ name = "zzstoatzz", email = "thrast36@gmail.com" }]
+requires-python = ">=3.10"
+license = "MIT"
+
+keywords = ["semble", "atproto", "bookmarks", "curation", "knowledge-graph"]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "httpx2>=2.3.0",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.14.1",
+]
+
+[project.optional-dependencies]
+cli = [
+    "cyclopts>=4.17.0",
+]
+mcp = [
+    "fastmcp[code-mode]>=3.4.2",
+]
+
+[project.scripts]
+semble = "semble.cli:main"
+semble-mcp = "semble.mcp:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-asyncio>=0.25.0",
+    "pytest-sugar",
+    "ruff>=0.12.0",
+    "prek>=0.2.0",
+    "ty>=0.0.1a25",
+    "cyclopts>=4.17.0",
+    "fastmcp[code-mode]>=3.4.2",
+]
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/semble"]
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+fallback-version = "0.0.0"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+ignore = [
+    "COM812",
+    "PLR0913", # Too many arguments
+    "SIM102",  # Dont require combining if statements
+    "ANN401",  # Any is allowed where it's the honest type (escape hatches)
+]
+extend-select = [
+    "ANN", # flake8-annotations: require complete signatures
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "I",   # isort
+    "PIE", # flake8-pie
+    "RUF", # Ruff-specific
+    "SIM", # flake8-simplify
+    "UP",  # pyupgrade
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "I001"]
+"tests/**/*.py" = ["S101"]       # Allow assert in tests
+
+[tool.ty.src]
+include = ["src", "tests"]
+exclude = [
+    "**/node_modules",
+    "**/__pycache__",
+    ".venv",
+    ".git",
+    "dist",
+]
+
+[tool.ty.environment]
+python-version = "3.10"

semble_api-0.0.1/scripts/roundtrip.py

@@ -0,0 +1,43 @@
+"""exercise the write paths end to end, cleaning up after itself.
+
+WARNING: this writes real records to your semble account (and pds) before
+removing them. run it deliberately:
+
+    uv run scripts/roundtrip.py
+"""
+
+from semble import Semble
+
+URL = "https://example.com"
+
+with Semble() as client:
+    print("adding url to library...")
+    added = client.cards.add_url(URL, note="semble-api roundtrip test")
+    print(f"  url card: {added.url_card_id}, note card: {added.note_card_id}")
+
+    card = client.cards.get(added.url_card_id)
+    print(f"  fetched: {card.url} (in library: {card.url_in_library})")
+
+    print("creating collection...")
+    created = client.collections.create(
+        "semble-api roundtrip",
+        description="temporary — created by scripts/roundtrip.py",
+    )
+    collection_id = created.collection_id
+    print(f"  collection: {collection_id}")
+
+    print("adding card to collection...")
+    client.cards.update_url_associations(
+        added.url_card_id, add_to_collections=[collection_id]
+    )
+    detail = client.collections.get(collection_id)
+    in_collection = [c.id for c in detail.url_cards or []]
+    print(f"  collection now has: {in_collection}")
+
+    print("updating note...")
+    client.cards.update_note(added.note_card_id, "updated by roundtrip")
+
+    print("cleaning up...")
+    client.collections.delete(collection_id)
+    client.cards.remove_from_library(added.url_card_id)
+    print("done — collection deleted, card removed")

semble_api-0.0.1/src/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__",
+]