semurg 0.1.0__py3-none-any.whl

semurg/__init__.py

@@ -0,0 +1,43 @@
+"""Semurg Python client.
+
+Connect to your own self-hosted Semurg node over HTTP (working today), WebSocket (interface,
+roadmap wire) or Semurg ATP (frame codec live, wire roadmap).
+
+    from semurg import Client
+    c = Client("http://127.0.0.1:4000", token="...")
+    print(c.health())
+"""
+
+from . import frame
+from .client import Client, __version__
+from .errors import (
+    SemurgAuthError,
+    SemurgConnectionError,
+    SemurgError,
+    SemurgHTTPError,
+    SemurgNotFound,
+    SemurgRateLimited,
+    SemurgRoadmapError,
+    SemurgServerError,
+    SemurgTimeout,
+)
+from .transports import AtpTransport, HttpTransport, Transport, WsTransport
+
+__all__ = [
+    "Client",
+    "__version__",
+    "frame",
+    "Transport",
+    "HttpTransport",
+    "WsTransport",
+    "AtpTransport",
+    "SemurgError",
+    "SemurgHTTPError",
+    "SemurgAuthError",
+    "SemurgNotFound",
+    "SemurgRateLimited",
+    "SemurgServerError",
+    "SemurgTimeout",
+    "SemurgConnectionError",
+    "SemurgRoadmapError",
+]

semurg/client.py

@@ -0,0 +1,331 @@
+"""The Semurg client.
+
+Point it at your OWN Semurg node (a self-hosted instance on your own hardware) and call the
+same methods you would against any Semurg box. HTTP is the working transport today; ``ws`` and
+``atp`` are pluggable interfaces whose live wires are on the roadmap (see clients/CONNECTING.md).
+
+    from semurg import Client
+
+    with Client("http://127.0.0.1:4000") as c:
+        print(c.health())
+        print(c.query("search", {"needle": "hello"}))
+"""
+
+from __future__ import annotations
+
+import base64
+import struct
+from typing import Any, Optional
+from urllib.parse import quote
+
+from . import frame as _frame
+from .errors import SemurgError
+from .transports import Transport, build_transport
+
+__version__ = "0.1.0"
+
+
+class Client:
+    """A Semurg node client with a pluggable transport.
+
+    Args:
+        base_url: your node's base URL, for example ``http://127.0.0.1:4000`` or
+            ``https://one.semurg.io``. The SDK appends ``/api/...`` and ``/v1/...``.
+        token: optional API token, sent as ``Authorization: Bearer <token>``. A node that has
+            no token provisioned is open (read-only public build); a node with a token rejects
+            unauthenticated ``/v1`` calls with 401.
+        timeout: per-request timeout in seconds.
+        transport: ``"http"`` (default, working), ``"ws"`` or ``"atp"`` (interfaces, roadmap wire).
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: Optional[str] = None,
+        timeout: float = 30.0,
+        transport: str = "http",
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.transport: Transport = build_transport(transport, self.base_url, token, timeout)
+
+    # -- lifecycle ---------------------------------------------------------------------------
+
+    def close(self) -> None:
+        self.transport.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # -- benchmark / meta API (/api) ---------------------------------------------------------
+
+    def health(self) -> dict:
+        """GET /api/health -- liveness, engine state, dataset readiness."""
+        return self.transport.request("GET", "/api/health")
+
+    def version(self) -> dict:
+        """Client + server identity. Semurg exposes no dedicated version route; this summarizes
+        /api/health (service) alongside the SDK version."""
+        h = self.health()
+        return {
+            "client": __version__,
+            "service": h.get("service") if isinstance(h, dict) else None,
+            "ok": h.get("ok") if isinstance(h, dict) else None,
+        }
+
+    # -- data plane (/v1) --------------------------------------------------------------------
+
+    def status(self) -> dict:
+        """GET /v1/status -- instance identity, licence, writability, store state."""
+        return self.transport.request("GET", "/v1/status")
+
+    # -- whole-cluster (five surfaces, one capability) --------------------------------------------
+
+    def cluster_util(self, window_ms: Optional[int] = None) -> dict:
+        """GET /v1/cluster/util -- live whole-cluster utilisation (per-pipe GB/s, per-core %, memBW)."""
+        path = "/v1/cluster/util"
+        if window_ms is not None:
+            path += "?window_ms=" + str(int(window_ms))
+        return self.transport.request("GET", path)
+
+    def conveyor_report(self) -> dict:
+        """GET /v1/cluster/conveyor -- the node's process-global conveyor counters: the belt
+        (odirect_open_ok, odirect_open_fallback, buffered_preads, sqes_submitted, uring_completions,
+        fifo_*, hugepage_*), the graph prefetch (prefetch_sqes_ahead, prefetch_used,
+        prefetch_evicted_unused) and the janitor (janitor_epochs, relocated_containers, pages_before,
+        pages_after) witnesses. Returns {ok, conveyor}; operator detail, so an anonymous caller gets
+        conveyor = {disclosed: false}. The same map the authenticated /api/health carries under
+        conveyor.counters and the ATP CONVEYOR_REPORT op (10) returns."""
+        return self.transport.request("GET", "/v1/cluster/conveyor")
+
+    def licence(self) -> dict:
+        """GET /v1/licence -- the full licence status (licensee, cluster?, node_count, used, headroom)."""
+        return self.transport.request("GET", "/v1/licence")
+
+    def nodes(self) -> dict:
+        """GET /v1/cluster/nodes -- the whole-cluster membership."""
+        return self.transport.request("GET", "/v1/cluster/nodes")
+
+    def node_status(self, fp: str) -> dict:
+        """GET /v1/cluster/nodes/<fp> -- one node's status by fingerprint."""
+        return self.transport.request("GET", "/v1/cluster/nodes/" + str(fp))
+
+    def query(self, op: str, args: Optional[dict] = None, **kwargs: Any) -> dict:
+        """POST /v1/query -- batch read. ``op`` is fetch | resolve | search | histogram."""
+        body = {"op": op}
+        if args:
+            body.update(args)
+        if kwargs:
+            body.update(kwargs)
+        return self.transport.request("POST", "/v1/query", json_body=body)
+
+    def fetch(self, ids: list[int]) -> dict:
+        """/v1/query op=fetch -- resolve a batch of container ids (base64 containers in the result)."""
+        return self.query("fetch", {"ids": list(ids)})
+
+    def resolve(self, id: int) -> dict:
+        """/v1/query op=resolve -- resolve a single container id."""
+        return self.query("resolve", {"id": id})
+
+    def search(self, needle: str) -> dict:
+        """/v1/query op=search -- index-free pattern scan for ``needle``."""
+        return self.query("search", {"needle": needle})
+
+    def histogram(self, field_offset: int = 8, buckets: int = 16) -> dict:
+        """/v1/query op=histogram -- one-pass histogram over a byte field (offset 0..63)."""
+        return self.query("histogram", {"field_offset": field_offset, "buckets": buckets})
+
+    def vector_top_k(self, queries: list[list[float]], k: int = 10, ef: Optional[int] = None) -> dict:
+        """/v1/query op=vector_top_k -- exact nearest neighbours for a batch of float vectors.
+
+        ``queries`` is a list of equal-length vectors. They travel as one row-major little-endian
+        float32 matrix, base64 encoded, because JSON carries no raw bytes and a second encoding is a
+        second thing for the two ends to disagree about. The answer is one list per query, in input
+        order, each ``[distance, id]`` ascending. The distance is squared, so it is comparable and not
+        a metre; take its square root if a reader needs one.
+        """
+        import base64
+        import struct
+
+        if not queries:
+            raise ValueError("vector_top_k needs at least one query")
+        d = len(queries[0])
+        if any(len(q) != d for q in queries):
+            raise ValueError("every query must have the same number of dimensions")
+        flat = [float(x) for q in queries for x in q]
+        raw = struct.pack("<%df" % len(flat), *flat)
+        body = {"queries_b64": base64.b64encode(raw).decode("ascii"), "q": len(queries), "d": d, "k": k}
+        # ``ef`` (V-INDEX, r11.47+) asks for the INDEXED answer: a best-first search of the store's k-NN graph on disk
+        # with ``ef`` candidates per shard, every distance still exact; the reply says which board answered ("answer")
+        # and the ef the node applied ("ef"). A node that predates the index answers exact with no "answer" key: that
+        # reply is refused by name, never returned as an indexed one.
+        if ef is not None:
+            body["ef"] = ef
+        res = self.query("vector_top_k", body)
+        if ef is not None and not (isinstance(res, dict) and res.get("answer") == "indexed"):
+            raise SemurgError(
+                "the node answered exact: it predates the k-NN index (ef needs r11.47+); drop ef or upgrade the node"
+            )
+        return res
+
+    def vector_search(self, query: str, k: int = 10) -> dict:
+        """/v1/query op=vector_search -- exact top-k over the in-store SimHash codes of ``query``'s embedding.
+
+        The node embeds ``query`` with its own model, so the codes compare with the passages written through
+        ``ingest(passages=...)``. Rows are ``{id, hamming, similarity, passage}``; the envelope's ``note`` states the
+        recall framing (recall@1 exact, recall@k a quantisation of float-cosine NN)."""
+        return self.query("vector_search", {"query": query, "k": k})
+
+    def similar(self, id: int, k: int = 10) -> dict:
+        """/v1/query op=similar -- the ``k`` nodes nearest to stored node ``id`` by its own code (no re-embed)."""
+        return self.query("similar", {"id": id, "k": k})
+
+    def ingest_vectors(self, vectors: list[list[float]], ids: list[int]) -> dict:
+        """POST /v1/ingest ``vectors_b64`` -- store float vectors under your own ids (a WRITE).
+
+        ``vectors`` are equal-length (1..176 components), ``ids`` one per vector, distinct, ``1 <= id < 2**60``.
+        They travel as one row-major little-endian float32 matrix, base64 encoded, the same encoding
+        ``vector_top_k`` sends its queries in, and ``vector_top_k`` answers with these ids. One store holds one
+        vector width; a query of another width is refused by name."""
+        if not vectors:
+            raise ValueError("ingest_vectors needs at least one vector")
+        d = len(vectors[0])
+        if any(len(v) != d for v in vectors):
+            raise ValueError("every vector must have the same number of components")
+        if len(ids) != len(vectors):
+            raise ValueError("one id per vector")
+        flat = [float(x) for v in vectors for x in v]
+        raw = struct.pack("<%df" % len(flat), *flat)
+        body = {"vectors_b64": base64.b64encode(raw).decode("ascii"), "d": d, "ids": [int(i) for i in ids]}
+        return self.transport.request("POST", "/v1/ingest", json_body=body)
+
+    def fetch_batch(self, ids: list[int]) -> list[bytes]:
+        """POST /v1/query {"op":"fetch"} with Accept: application/octet-stream -- the BINARY fast path
+        (fetch has one door; the encoding is the Accept header). Returns one frame per id in request
+        order (a zero-filled frame for an absent id)."""
+        body = {"op": "fetch", "ids": [int(i) & 0xFFFFFFFFFFFFFFFF for i in ids]}
+        blob = self.transport.request("POST", "/v1/query", json_body=body, accept="bin")
+        return _frame.unpack(blob)
+
+    # -- memory (/v1/memory): the AI memory verbs, the same bodies the REST routes take -------
+
+    def memory_status(self, user_id: Optional[str] = None) -> dict:
+        """GET /v1/memory/status -- is the capability on, and what scopes exist. With ``user_id`` (an end-user
+        partition inside your identity) it lists that partition's scopes."""
+        path = "/v1/memory/status"
+        if user_id is not None:
+            path += "?user_id=" + quote(user_id, safe="")
+        return self.transport.request("GET", path)
+
+    def remember(
+        self,
+        scope: str,
+        content: str | None = None,
+        facts: dict | None = None,
+        passages: list | None = None,
+        user_id: str | None = None,
+        **kw: Any,
+    ) -> dict:
+        """POST /v1/memory/remember -- store pre-extracted facts and/or passages in ``scope`` (a WRITE).
+
+        ``user_id`` (optional) names an END-USER partition inside your identity: the memory is kept apart per
+        user_id and ``delete_user`` removes it whole. The node validates it (no ``:``, at most 256 bytes) and
+        refuses a bad one by name; the SDK sends it as is.
+
+        ``facts`` takes either the full shape ``{"entities": [...], "relations": [...]}`` or the short
+        form ``{"subject": "Paris", "kind": "city"}``. A facts map that names nothing storable is
+        refused by the node rather than acknowledged.
+
+        ``passages`` stores text now, with no model: ``[{"text": "Lena works at Acme.", "mentions":
+        ["Lena", "Acme"], "key": "memo-1"}]`` (``key`` optional). Each mention must appear in its text
+        (letter case aside), or the node refuses the passage by name. ``memory_context`` returns the
+        passage whole when it reaches a mentioned entity. Raw ``content`` needs a text extractor the
+        node may not have."""
+        body: dict = {"scope": scope, **kw}
+        if content is not None:
+            body["content"] = content
+        if facts is not None:
+            body["facts"] = facts
+        if passages is not None:
+            body["passages"] = passages
+        if user_id is not None:
+            body["user_id"] = user_id
+        return self.transport.request("POST", "/v1/memory/remember", json_body=body)
+
+    def recall(self, scope: str, subject: str | None = None, query: str | None = None, k: int | None = None,
+               user_id: str | None = None) -> dict:
+        """POST /v1/memory/recall -- walk outward from an exact entity and answer WITH provenance. ``user_id``
+        (optional) reads that end-user partition only."""
+        body: dict = {"scope": scope}
+        if user_id is not None:
+            body["user_id"] = user_id
+        if subject is not None:
+            body["subject"] = subject
+        if query is not None:
+            body["query"] = query
+        if k is not None:
+            body["k"] = int(k)
+        return self.transport.request("POST", "/v1/memory/recall", json_body=body)
+
+    def context(
+        self, scope: str, query: str, k: int | None = None, hops: int | None = None, user_id: str | None = None
+    ) -> dict:
+        """POST /v1/memory/context -- the ranked, cited facts of a scope relevant to a question (GraphRAG retrieval; no model is called). ``user_id`` (optional) reads that end-user partition only."""
+        body: dict = {"scope": scope, "query": query}
+        if user_id is not None:
+            body["user_id"] = user_id
+        if k is not None:
+            body["k"] = int(k)
+        if hops is not None:
+            body["hops"] = int(hops)
+        return self.transport.request("POST", "/v1/memory/context", json_body=body)
+
+    def relate(self, scope: str, frm: str, to: str, type: str = "RELATED_TO", user_id: str | None = None) -> dict:
+        """POST /v1/memory/relate -- one typed edge between two entities in ``scope`` (a WRITE). ``user_id``
+        (optional) writes into that end-user partition."""
+        body: dict = {"scope": scope, "from": frm, "to": to, "type": type}
+        if user_id is not None:
+            body["user_id"] = user_id
+        return self.transport.request("POST", "/v1/memory/relate", json_body=body)
+
+    def forget(self, scope: str, subject: str, reason: str | None = None, user_id: str | None = None) -> dict:
+        """POST /v1/memory/forget -- supersede an entity in ``scope`` (a WRITE; nothing is erased). ``user_id``
+        (optional) forgets inside that end-user partition."""
+        body: dict = {"scope": scope, "subject": subject}
+        if reason is not None:
+            body["reason"] = reason
+        if user_id is not None:
+            body["user_id"] = user_id
+        return self.transport.request("POST", "/v1/memory/forget", json_body=body)
+
+    def delete_user(self, user_id: str) -> dict:
+        """POST /v1/memory/delete_user -- delete one END USER's whole memory partition (a WRITE; the owner's right to erasure).
+
+        The reply says what left: ``state`` (``"deleted"`` or ``"already_deleted"``), ``scopes``, ``entities``,
+        ``documents``, ``tombstoned_nodes``, ``tombstoned_edges``, ``reads``, ``written_during_delete``,
+        ``keyword_postings``. A user_id the node does not know is a 404 (``SemurgError``), a missing one 422, and a
+        public sandbox refuses it (403)."""
+        return self.transport.request("POST", "/v1/memory/delete_user", json_body={"user_id": user_id})
+
+    def ingest(self, containers: Any, stamp_edges: bool = False) -> dict:
+        """POST /v1/ingest -- append a batch of frames (needs the write capability).
+
+        ``containers`` is either a single packed ``bytes`` (a whole multiple of the frame size)
+        or a list of frames (as returned by :func:`semurg.frame.encode`). ``stamp_edges=True`` asks the
+        node to write the content address of every edge sent with its id left at 0 (a node that does not
+        know the flag refuses such an edge by name, so nothing is stored wrong)."""
+        if isinstance(containers, (bytes, bytearray)):
+            packed = bytes(containers)
+        else:
+            packed = _frame.pack(list(containers))
+        if not packed or len(packed) % _frame.CONTAINER_BYTES != 0:
+            raise ValueError("ingest expects a whole number of frames")
+        b64 = base64.b64encode(packed).decode("ascii")
+        body: dict = {"containers_b64": b64}
+        if stamp_edges:
+            body["stamp_edges"] = True
+        return self.transport.request("POST", "/v1/ingest", json_body=body)

semurg/errors.py

@@ -0,0 +1,66 @@
+"""Typed errors for the Semurg client.
+
+Every failure the SDK raises is a subclass of :class:`SemurgError`, so a caller can
+catch one thing and still branch on the specific case. HTTP status codes map to the
+subclasses below exactly as the Semurg node returns them (see clients/CONNECTING.md).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class SemurgError(Exception):
+    """Base class for every error this client raises."""
+
+
+class SemurgTimeout(SemurgError):
+    """The request did not complete within the client timeout."""
+
+
+class SemurgConnectionError(SemurgError):
+    """The node could not be reached at all (DNS, refused, TLS, reset)."""
+
+
+class SemurgHTTPError(SemurgError):
+    """A non-2xx HTTP response. Carries the status and the decoded body when present."""
+
+    def __init__(self, status: int, message: str, body: Any = None) -> None:
+        self.status = status
+        self.message = message
+        self.body = body
+        super().__init__(f"HTTP {status}: {message}")
+
+
+class SemurgAuthError(SemurgHTTPError):
+    """401 (token required / wrong token) or 403 (instance is read-only / missing capability)."""
+
+
+class SemurgNotFound(SemurgHTTPError):
+    """404 (unknown benchmark key, or route not present on this node)."""
+
+
+class SemurgRateLimited(SemurgHTTPError):
+    """429 (rate/concurrency limit) or a 503 warming response, both carrying Retry-After.
+
+    ``retry_after`` is the number of seconds the node asks the caller to wait, parsed from
+    the ``Retry-After`` header (falling back to a ``retry_after`` field in the JSON body).
+    """
+
+    def __init__(self, status: int, message: str, retry_after: Optional[float] = None, body: Any = None) -> None:
+        self.retry_after = retry_after
+        super().__init__(status, message, body)
+
+
+class SemurgServerError(SemurgHTTPError):
+    """5xx other than a warming 503 (for example a 500 from a failed append)."""
+
+
+class SemurgRoadmapError(SemurgError):
+    """The selected transport's live wire is not shipped yet.
+
+    Raised by the WebSocket and ATP transports for request/response operations whose
+    external wire is on the roadmap. The message names the working alternative (HTTP)
+    and the real functionality the transport still provides (frame codec, message
+    builders). The SDK never fakes a live wire.
+    """

semurg/frame.py

@@ -0,0 +1,187 @@
+"""Semurg ATP Overdrive-64 frame codec.
+
+A frame is the fixed-size record the Semurg wire moves (see the byte layout below). This module
+encodes and decodes it in pure Python, byte-for-byte identical to the node's frame codec (same
+CRC-32C, same little-endian field layout), so a frame you build here is the exact wire unit the
+ATP transport will send once the external ATP wire ships (see clients/CONNECTING.md, ATP is
+ROADMAP for the live wire; this codec is live today and unit-tested offline).
+
+Header layout (little-endian):
+
+    byte 0        type (high nibble) | flags (low nibble)
+    byte 1        flags_ext / nonce-lo
+    bytes 2..5    generation (u32, ABA-safe handle stamp)
+    bytes 6..7    schema (u16)
+    bytes 8..15   logical_id (u64)   -- Node ENTITY-ID / Edge SRC-ID / Chunk CHUNK-ID
+    bytes 16..23  edge_dst_id (u64)  -- meaningful for edges (type 0x2)
+    bytes 24..59  body (36 bytes, form-specific)
+    bytes 60..63  CRC-32C over bytes 0..59
+
+ID performance: keep ``logical_id`` <= ``DENSE_ID_MAX`` (~4.29e9) for the engine's O(1) arithmetic
+id-locate -- flat throughput and flat memory at any scale. A larger (sparse) id spills into a
+disk-resident extendible hash: still correct, but with a gentler per-insert decay as the index grows.
+Use :func:`dense_ids` (or :func:`dense_id` for multi-model) to assign bulk unique keys; do NOT high-bit-pack
+a model prefix (e.g. ``model_id<<40``), which forces EVERY id onto the slower sparse arm.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+CONTAINER_BYTES = 64
+BODY_OFFSET = 24
+BODY_MAX = 60 - BODY_OFFSET  # 36 bytes free before the CRC
+
+TYPE_TOMBSTONE = 0x0
+TYPE_NODE = 0x1
+TYPE_EDGE = 0x2
+TYPE_CHUNK = 0x3
+
+# ID PERFORMANCE BOUNDARY -- matches the engine's DENSE_ID_LIMIT (== u32::MAX). A logical_id at or below
+# DENSE_ID_MAX resolves via the engine's O(1) arithmetic id-locate (flat throughput + memory at any scale);
+# a larger (sparse) id spills into a disk-resident extendible hash (correct, gentler per-insert cost). For
+# bulk UNIQUE-key ingest assign DENSE sequential ids (see `dense_ids`); do NOT high-bit-pack a model prefix
+# (model_id<<40), which forces every id onto the sparse arm (measured ~22x slower on a single-shard ramp).
+DENSE_ID_MAX = (1 << 32) - 1  # 4_294_967_295
+
+_CRC32C_POLY = 0x82F63B78  # Castagnoli, reflected -- matches the node's CRC-32C
+
+
+def _make_table() -> list[int]:
+    table = []
+    for i in range(256):
+        c = i
+        for _ in range(8):
+            c = (_CRC32C_POLY ^ (c >> 1)) if (c & 1) else (c >> 1)
+        table.append(c & 0xFFFFFFFF)
+    return table
+
+
+_TABLE = _make_table()
+
+
+def crc32c(data: bytes) -> int:
+    """CRC-32C (Castagnoli) over ``data`` -- the canonical Semurg container checksum."""
+    crc = 0xFFFFFFFF
+    for b in data:
+        crc = _TABLE[(crc ^ b) & 0xFF] ^ (crc >> 8)
+    return crc ^ 0xFFFFFFFF
+
+
+@dataclass
+class Frame:
+    """A decoded frame."""
+
+    type: int
+    flags: int
+    flags_ext: int
+    generation: int
+    schema: int
+    logical_id: int
+    edge_dst_id: int
+    body: bytes
+    crc_stored: int
+    crc_computed: int
+
+    @property
+    def crc_valid(self) -> bool:
+        return self.crc_stored == self.crc_computed
+
+
+def encode(
+    type: int,
+    *,
+    flags: int = 0,
+    flags_ext: int = 0,
+    generation: int = 0,
+    schema: int = 0,
+    logical_id: int = 0,
+    edge_dst_id: int = 0,
+    body: bytes = b"",
+) -> bytes:
+    """Encode a frame with a correct CRC-32C in bytes 60..63."""
+    if not 0 <= type <= 0xF:
+        raise ValueError("type must be a 4-bit nibble 0..15")
+    if not 0 <= flags <= 0xF:
+        raise ValueError("flags must be a 4-bit nibble 0..15")
+    if not 0 <= flags_ext <= 0xFF:
+        raise ValueError("flags_ext must be a byte 0..255")
+    body = bytes(body)
+    if len(body) > BODY_MAX:
+        raise ValueError(f"body is {len(body)} bytes; max {BODY_MAX} (offsets 24..59)")
+
+    head = bytearray(60)
+    head[0] = ((type & 0xF) << 4) | (flags & 0xF)
+    head[1] = flags_ext & 0xFF
+    head[2:6] = (generation & 0xFFFFFFFF).to_bytes(4, "little")
+    head[6:8] = (schema & 0xFFFF).to_bytes(2, "little")
+    head[8:16] = (logical_id & 0xFFFFFFFFFFFFFFFF).to_bytes(8, "little")
+    head[16:24] = (edge_dst_id & 0xFFFFFFFFFFFFFFFF).to_bytes(8, "little")
+    head[BODY_OFFSET:BODY_OFFSET + len(body)] = body
+    crc = crc32c(bytes(head))
+    return bytes(head) + crc.to_bytes(4, "little")
+
+
+def decode(frame: bytes) -> Frame:
+    """Decode a frame into a :class:`Frame` (with ``crc_valid``)."""
+    if len(frame) != CONTAINER_BYTES:
+        raise ValueError(f"a frame is exactly {CONTAINER_BYTES} bytes, got {len(frame)}")
+    b0 = frame[0]
+    return Frame(
+        type=b0 >> 4,
+        flags=b0 & 0x0F,
+        flags_ext=frame[1],
+        generation=int.from_bytes(frame[2:6], "little"),
+        schema=int.from_bytes(frame[6:8], "little"),
+        logical_id=int.from_bytes(frame[8:16], "little"),
+        edge_dst_id=int.from_bytes(frame[16:24], "little"),
+        body=frame[BODY_OFFSET:60],
+        crc_stored=int.from_bytes(frame[60:64], "little"),
+        crc_computed=crc32c(frame[:60]),
+    )
+
+
+def dense_ids(count: int, start: int = 0) -> range:
+    """A block of ``count`` DENSE sequential logical ids from ``start`` (the O(1) fast id-locate path).
+
+    Assign these to your frames' ``logical_id`` for FLAT-throughput bulk unique-key ingest. Raises if the
+    block would cross ``DENSE_ID_MAX`` (which would spill onto the slower disk-resident sparse hash).
+    """
+    if start < 0 or count < 0:
+        raise ValueError("start and count must be non-negative")
+    if count and start + count - 1 > DENSE_ID_MAX:
+        raise ValueError(
+            f"dense id block [{start}, {start + count}) exceeds DENSE_ID_MAX ({DENSE_ID_MAX}); "
+            "split across shards/stores to keep every id on the O(1) arm"
+        )
+    return range(start, start + count)
+
+
+def dense_id(model: int, index: int, model_bits: int = 8) -> int:
+    """Pack a (model, index) pair into ONE dense logical id (<= DENSE_ID_MAX) for multi-model stores.
+
+    Interleaves ``model_bits`` low bits of ``model`` under the index, so many models share a store with
+    unique ids WITHOUT the ``model_id<<40`` sparse blow-up. Default 8 model bits => up to 256 models and
+    ~16.7M indices/model stay dense. Raises if the packed id would exceed DENSE_ID_MAX.
+    """
+    if model < 0 or index < 0 or model >= (1 << model_bits):
+        raise ValueError(f"model must be 0..{(1 << model_bits) - 1} and index non-negative")
+    packed = (index << model_bits) | model
+    if packed > DENSE_ID_MAX:
+        raise ValueError(f"packed id {packed} exceeds DENSE_ID_MAX ({DENSE_ID_MAX}); reduce indices or model_bits")
+    return packed
+
+
+def pack(frames: list[bytes]) -> bytes:
+    """Concatenate encoded frames into the packed batch the /v1 endpoints accept."""
+    for f in frames:
+        if len(f) != CONTAINER_BYTES:
+            raise ValueError(f"every frame must be exactly {CONTAINER_BYTES} bytes")
+    return b"".join(frames)
+
+
+def unpack(blob: bytes) -> list[bytes]:
+    """Split a packed blob (for example a binary fetch reply) into frames."""
+    if len(blob) % CONTAINER_BYTES != 0:
+        raise ValueError(f"blob length must be a whole multiple of {CONTAINER_BYTES} bytes")
+    return [blob[i:i + CONTAINER_BYTES] for i in range(0, len(blob), CONTAINER_BYTES)]

semurg/transports.py

@@ -0,0 +1,404 @@
+"""Pluggable transports for the Semurg client.
+
+Three wires, one interface:
+
+* :class:`HttpTransport` -- the working default. Every SDK method rides it today, over ONE
+  persistent connection per caller (HTTP/1.1 keep-alive): a call is one round trip, not a TCP
+  (and TLS) handshake each.
+* :class:`WsTransport`   -- WebSocket. The node runs a Phoenix socket for its LiveView UI;
+  a programmatic data-stream topic is ROADMAP. This transport builds the correct socket URL
+  and Phoenix join frames (real, offline-testable) and raises :class:`SemurgRoadmapError`
+  for request/response ops, pointing the caller at HTTP. It never fakes a live data wire.
+* :class:`AtpTransport` -- Semurg ATP (Overdrive-64 frames). The frame codec is live
+  (see :mod:`semurg.frame`); ATP-over-TCP is ROADMAP. Unary ops raise :class:`SemurgRoadmapError`.
+
+Only the HTTP transport is required to use the node's HTTP + /v1 API. The other two exist so a
+caller can write transport-agnostic code today and flip the wire when it ships.
+"""
+
+from __future__ import annotations
+
+import base64
+import http.client
+import json
+import select
+import socket
+import ssl
+import threading
+import time
+import urllib.request
+from typing import Any, Optional
+from urllib.parse import unquote, urlsplit, urlunsplit
+
+from . import frame as _frame
+from .errors import (
+    SemurgAuthError,
+    SemurgConnectionError,
+    SemurgHTTPError,
+    SemurgNotFound,
+    SemurgRateLimited,
+    SemurgRoadmapError,
+    SemurgServerError,
+    SemurgTimeout,
+)
+
+
+def _retry_after(headers: Any, body: Any) -> Optional[float]:
+    ra = None
+    if headers is not None:
+        raw = headers.get("Retry-After") or headers.get("retry-after")
+        if raw:
+            try:
+                ra = float(raw)
+            except ValueError:
+                ra = None
+    if ra is None and isinstance(body, dict) and "retry_after" in body:
+        try:
+            ra = float(body["retry_after"])
+        except (TypeError, ValueError):
+            ra = None
+    return ra
+
+
+def _raise_for_status(status: int, headers: Any, body: Any) -> None:
+    msg = _err_message(body, default=f"request failed ({status})")
+    if status in (401, 403):
+        raise SemurgAuthError(status, msg, body)
+    if status == 404:
+        raise SemurgNotFound(status, msg, body)
+    if status == 429:
+        raise SemurgRateLimited(status, msg, _retry_after(headers, body), body)
+    if status == 503:
+        # A warming dataset or an unavailable store: retryable, may carry Retry-After.
+        raise SemurgRateLimited(status, msg, _retry_after(headers, body), body)
+    if 500 <= status < 600:
+        raise SemurgServerError(status, msg, body)
+    if 400 <= status < 500:
+        raise SemurgHTTPError(status, msg, body)
+
+
+def _err_message(body: Any, default: str) -> str:
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, str):
+            detail = body.get("detail") or body.get("reason")
+            return f"{err}: {detail}" if detail else err
+        if err is not None:
+            return json.dumps(err)
+    return default
+
+
+class Transport:
+    """Common transport interface. Subclasses implement :meth:`request`."""
+
+    name = "base"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        raw_body: Optional[bytes] = None,
+        accept: str = "json",
+    ) -> Any:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        pass
+
+
+# A socket idle this long is closed, never reused: it stays below the node's own keep-alive (Bandit closes an idle
+# connection after 60 s), so the client does not send a request into a socket the node is about to drop.
+_IDLE_MAX_S = 30.0
+# Idle connections kept per client: one per caller thread that is active at once, most recently used first.
+_POOL_MAX = 8
+# A REUSED idle socket the node had closed: a reset or EOF before any byte of the answer (the node dropping an idle
+# connection as the request was sent). Retried once on a fresh connection; a fresh connection is never retried.
+_STALE = (ConnectionResetError, ConnectionAbortedError, BrokenPipeError)  # http.client.RemoteDisconnected is a ConnectionResetError
+
+
+def _dropped(conn: http.client.HTTPConnection) -> bool:
+    """True when an idle pooled socket is no longer usable: closed, or readable while idle (EOF, a reset, a TLS
+    close_notify or stray bytes: nothing is owed on an idle HTTP/1.1 connection). poll, not select, so a process with
+    more than 1024 descriptors is judged too."""
+    s = conn.sock
+    if s is None:
+        return True
+    try:
+        if hasattr(select, "poll"):
+            p = select.poll()
+            p.register(s, select.POLLIN | select.POLLPRI)
+            return bool(p.poll(0))
+        return bool(select.select([s], [], [], 0)[0])
+    except (OSError, ValueError):
+        return True
+
+
+class HttpTransport(Transport):
+    """HTTP/1.1 over the standard library (no third-party dependency), ONE PERSISTENT CONNECTION PER CALLER.
+
+    Connections are kept alive between calls in a small pool (most recently used first, at most 8 idle, a socket
+    idle for 30 s is closed and never reused), so a call costs one round trip instead of a TCP (+ TLS) handshake.
+    Thread-safe: every call in flight holds its own connection. A REUSED connection the node had already closed
+    (it answers nothing: a reset or EOF before the first byte of the reply) is retried ONCE on a fresh connection;
+    a fresh connection is never retried. Every Semurg write is idempotent by content (the same content is the same id,
+    reported "already"), so that one resend cannot store anything twice.
+
+    Proxies from the environment (``HTTPS_PROXY`` / ``HTTP_PROXY`` / ``NO_PROXY``) are honoured as urllib does,
+    through a CONNECT tunnel for an https node. Redirects are NOT followed: a 3xx raises :class:`SemurgHTTPError`
+    naming the new address, so the API token is never resent to a host the caller did not name.
+    ``connections_opened`` counts every connection this client opened (the keep-alive witness).
+    """
+
+    name = "http"
+
+    def __init__(self, base_url: str, token: Optional[str] = None, timeout: float = 30.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        parts = urlsplit(self.base_url)
+        if parts.scheme not in ("http", "https") or not parts.hostname:
+            raise ValueError(f"base_url must be an http:// or https:// URL, got {base_url!r}")
+        self._https = parts.scheme == "https"
+        self._host = parts.hostname
+        self._port = parts.port or (443 if self._https else 80)
+        self._netloc = parts.netloc.rpartition("@")[2]
+        self._prefix = parts.path  # a node mounted under a path (behind a reverse proxy) keeps its prefix
+        self._proxy = self._env_proxy()
+        self._ssl = ssl.create_default_context() if self._https else None
+        self._idle: list[tuple[http.client.HTTPConnection, float]] = []
+        self._lock = threading.Lock()
+        self.connections_opened = 0
+
+    def _env_proxy(self) -> Optional[tuple[str, int, Optional[str]]]:
+        """(host, port, Proxy-Authorization) of the environment's proxy for this node, by urllib's own rules."""
+        url = urllib.request.getproxies().get("https" if self._https else "http")
+        if not url or urllib.request.proxy_bypass(self._host):
+            return None
+        p = urlsplit(url if "://" in url else "http://" + url)
+        if not p.hostname:
+            return None
+        auth = None
+        if p.username is not None:
+            cred = f"{unquote(p.username)}:{unquote(p.password or '')}".encode("utf-8")
+            auth = "Basic " + base64.b64encode(cred).decode("ascii")
+        return (p.hostname, p.port or (443 if p.scheme == "https" else 80), auth)
+
+    def _connect(self) -> http.client.HTTPConnection:
+        px = self._proxy
+        if self._https:
+            if px:
+                conn: http.client.HTTPConnection = http.client.HTTPSConnection(px[0], px[1], timeout=self.timeout, context=self._ssl)
+                conn.set_tunnel(self._host, self._port, headers={"Proxy-Authorization": px[2]} if px[2] else None)
+            else:
+                conn = http.client.HTTPSConnection(self._host, self._port, timeout=self.timeout, context=self._ssl)
+        else:
+            conn = http.client.HTTPConnection(px[0] if px else self._host, px[1] if px else self._port, timeout=self.timeout)
+        conn.connect()
+        with self._lock:
+            self.connections_opened += 1
+        return conn
+
+    def _take(self) -> Optional[http.client.HTTPConnection]:
+        now = time.monotonic()
+        stale = []
+        conn = None
+        with self._lock:
+            while self._idle:
+                c, used = self._idle.pop()
+                if now - used <= _IDLE_MAX_S and not _dropped(c):
+                    conn = c
+                    break
+                stale.append(c)
+        for c in stale:
+            c.close()
+        return conn
+
+    def _put(self, conn: http.client.HTTPConnection) -> None:
+        with self._lock:
+            if len(self._idle) < _POOL_MAX:
+                self._idle.append((conn, time.monotonic()))
+                return
+        conn.close()
+
+    def close(self) -> None:
+        """Close every idle connection. The client stays usable: a later call opens a new one."""
+        with self._lock:
+            idle, self._idle = self._idle, []
+        for c, _ in idle:
+            c.close()
+
+    def _headers(self, accept: str, content_type: Optional[str]) -> dict[str, str]:
+        h = {"Accept": "application/octet-stream" if accept == "bin" else "application/json"}
+        if content_type:
+            h["Content-Type"] = content_type
+        if self.token:
+            h["Authorization"] = f"Bearer {self.token}"
+        h["User-Agent"] = "semurg-python/0.1.0"
+        return h
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        raw_body: Optional[bytes] = None,
+        accept: str = "json",
+    ) -> Any:
+        url = self.base_url + path
+        data: Optional[bytes] = None
+        content_type: Optional[str] = None
+        if raw_body is not None:
+            data = raw_body
+            content_type = "application/octet-stream"
+        elif json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            content_type = "application/json"
+
+        headers = self._headers(accept, content_type)
+        target = self._prefix + path
+        if self._proxy and not self._https:
+            target = f"http://{self._netloc}{target}"  # absolute form through a plain-http proxy
+            if self._proxy[2]:
+                headers["Proxy-Authorization"] = self._proxy[2]
+
+        for attempt in (0, 1):
+            conn = self._take() if attempt == 0 else None
+            reused = conn is not None
+            try:
+                if conn is None:
+                    conn = self._connect()
+                conn.request(method, target, body=data, headers=headers)
+                resp = conn.getresponse()
+                payload = resp.read()
+            except _STALE as e:
+                if conn is not None:
+                    conn.close()
+                if reused:
+                    self.close()  # one idle socket the node dropped means the others went with it (a node restart)
+                    continue
+                raise SemurgConnectionError(f"could not reach {url}: {e}") from e
+            except socket.timeout as e:  # TimeoutError on 3.10+
+                if conn is not None:
+                    conn.close()
+                raise SemurgTimeout(f"request to {url} timed out after {self.timeout}s") from e
+            except (OSError, http.client.HTTPException) as e:
+                if conn is not None:
+                    conn.close()
+                raise SemurgConnectionError(f"could not reach {url}: {e}") from e
+            break
+
+        if resp.will_close:
+            conn.close()
+        else:
+            self._put(conn)
+        status = resp.status
+        if 200 <= status < 300:
+            return self._parse(status, resp.headers, payload, accept)
+        body = self._decode_error_body(resp.headers, payload)
+        if 300 <= status < 400:
+            where = resp.headers.get("Location") or "an address it did not name"
+            raise SemurgHTTPError(status, f"the node redirected to {where}: use that address as base_url (redirects are not followed, so the token never goes to another host)", body)
+        _raise_for_status(status, resp.headers, body)
+        raise SemurgHTTPError(status, _err_message(body, "request failed"), body)
+
+    @staticmethod
+    def _parse(status: int, headers: Any, payload: bytes, accept: str) -> Any:
+        ctype = (headers.get("Content-Type") or "").lower()
+        if accept == "bin" or "octet-stream" in ctype:
+            return payload
+        if not payload:
+            return None
+        try:
+            return json.loads(payload.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return payload
+
+    @staticmethod
+    def _decode_error_body(headers: Any, payload: bytes) -> Any:
+        ctype = (headers.get("Content-Type") or "").lower() if headers else ""
+        if "json" in ctype:
+            try:
+                return json.loads(payload.decode("utf-8"))
+            except (ValueError, UnicodeDecodeError):
+                pass
+        try:
+            return payload.decode("utf-8")
+        except UnicodeDecodeError:
+            return payload
+
+
+class WsTransport(Transport):
+    """WebSocket transport. Live data-stream wire is ROADMAP; URL + Phoenix helpers are live."""
+
+    name = "ws"
+
+    def __init__(self, base_url: str, token: Optional[str] = None, timeout: float = 30.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+
+    def socket_url(self, path: str = "/live/websocket", vsn: str = "2.0.0") -> str:
+        """The Phoenix socket URL for this node (ws:// or wss:// to match the base scheme)."""
+        parts = urlsplit(self.base_url)
+        scheme = "wss" if parts.scheme == "https" else "ws"
+        query = f"vsn={vsn}"
+        if self.token:
+            query += f"&token={self.token}"
+        return urlunsplit((scheme, parts.netloc, path, query, ""))
+
+    @staticmethod
+    def join_message(topic: str, payload: Optional[dict] = None, ref: str = "1", join_ref: str = "1") -> str:
+        """A Phoenix v2 join frame: [join_ref, ref, topic, "phx_join", payload] as JSON."""
+        return json.dumps([join_ref, ref, topic, "phx_join", payload or {}])
+
+    def request(self, *args: Any, **kwargs: Any) -> Any:
+        raise SemurgRoadmapError(
+            "the programmatic WebSocket data wire is ROADMAP. The node's Phoenix socket "
+            f"({self.socket_url()}) currently serves the LiveView UI only. Use transport='http' "
+            "for data operations; use socket_url()/join_message() to wire a browser UI today."
+        )
+
+
+class AtpTransport(Transport):
+    """Semurg ATP transport. Frame codec is live; ATP-over-TCP wire is ROADMAP."""
+
+    name = "atp"
+
+    # Real, offline: the frame codec (also exported as semurg.frame).
+    encode_frame = staticmethod(_frame.encode)
+    decode_frame = staticmethod(_frame.decode)
+    pack = staticmethod(_frame.pack)
+    unpack = staticmethod(_frame.unpack)
+    crc32c = staticmethod(_frame.crc32c)
+
+    def __init__(self, base_url: str, token: Optional[str] = None, timeout: float = 30.0, port: int = 6464) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.port = port
+
+    def endpoint(self) -> str:
+        """The planned ATP-over-TCP endpoint (host from base_url, ATP port). ROADMAP wire."""
+        host = urlsplit(self.base_url).hostname or "127.0.0.1"
+        return f"atp://{host}:{self.port}"
+
+    def request(self, *args: Any, **kwargs: Any) -> Any:
+        raise SemurgRoadmapError(
+            "ATP-over-TCP is ROADMAP: the Overdrive-64 frame codec is live "
+            "(encode_frame/decode_frame/pack/unpack, unit-tested offline) but the external wire "
+            f"at {self.endpoint()} is not shipped. Use transport='http' for data operations."
+        )
+
+
+def build_transport(kind: str, base_url: str, token: Optional[str], timeout: float) -> Transport:
+    kind = (kind or "http").lower()
+    if kind == "http":
+        return HttpTransport(base_url, token, timeout)
+    if kind == "ws":
+        return WsTransport(base_url, token, timeout)
+    if kind == "atp":
+        return AtpTransport(base_url, token, timeout)
+    raise ValueError(f"unknown transport {kind!r}; use 'http', 'ws' or 'atp'")

semurg-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: semurg
+Version: 0.1.0
+Summary: Python client for Semurg: memory for AI agents (knowledge graph + vector search) on your own hardware
+Author: Semurg
+License: Apache-2.0
+Project-URL: Homepage, https://one.semurg.io
+Project-URL: Documentation, https://one.semurg.io/develop
+Project-URL: Agent frameworks, https://one.semurg.io/agents
+Keywords: semurg,ai-memory,agent-memory,knowledge-graph,vector-search,graph-rag,mcp,llm
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# semurg
+
+The Python client for [Semurg](https://one.semurg.io): memory for AI agents (a knowledge graph and vector search in one engine) that
+runs on your own hardware. Zero dependencies: it uses only the standard library.
+
+## 1. Start a node
+
+With Docker on an Intel or AMD x86_64 machine (Linux, or Windows with Docker Desktop or WSL2):
+
+```sh
+docker run -d --name semurg -p 127.0.0.1:4000:4000 \
+  --ulimit memlock=-1 --ulimit nofile=1048576:1048576 --security-opt seccomp=unconfined \
+  -v semurg-data:/var/lib/semurg one.semurg.io/semurg
+until docker logs semurg 2>&1 | grep -q 'Your API token'; do sleep 1; done
+export SEMURG_API_TOKEN=$(docker exec semurg cat /var/lib/semurg/.api_token)
+```
+
+Or install a node on Ubuntu 24.04: `curl -fsSL https://one.semurg.io/install | sudo bash` ([what it needs](https://one.semurg.io/install)).
+The first node is free.
+
+## 2. Install
+
+```sh
+pip install semurg
+```
+
+## 3. Remember and recall
+
+```python
+import os
+from semurg import Client
+
+with Client("http://127.0.0.1:4000", token=os.environ["SEMURG_API_TOKEN"]) as mem:
+    mem.remember(scope="demo", content="Ada Lovelace works at Acme on the analytics team.")
+    print(mem.recall(scope="demo", subject="Ada Lovelace"))          # what is stored about one entity, with its source
+    print(mem.context(scope="demo", query="Where does Ada work?"))  # passages and facts for a question
+```
+
+A `scope` is a separate, named memory. Send `user_id` to keep each of your end users' memories apart.
+
+Your agent can also send the entities and relations it found, so they are stored as a graph at once:
+
+```python
+mem.remember(
+    scope="demo",
+    facts={"entities": [{"name": "Acme", "type": "Company"}, {"name": "Dana", "type": "Person"}],
+           "relations": [{"source": "Dana", "target": "Acme", "type": "WORKS_AT"}]},
+    passages=[{"text": "Dana works at Acme.", "mentions": ["Dana", "Acme"]}],
+)
+```
+
+## The memory calls
+
+`memory_status`, `remember`, `recall`, `context`, `relate`, `forget` and `delete_user`, over HTTP. The same seven tools are served
+over MCP for agent frameworks: see [one.semurg.io/agents](https://one.semurg.io/agents).
+
+## Links
+
+- Developer guide: https://one.semurg.io/develop
+- Agent frameworks and MCP: https://one.semurg.io/agents
+- Benchmarks: https://one.semurg.io/benchmark
+
+Licence: Apache-2.0 (this client). The Semurg engine is licensed separately; the first node is free.

semurg-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+semurg/__init__.py,sha256=cREdA1fgZC-hr175mOs7L5HGKGk4j1WH2dyR4dyLXkI,998
+semurg/client.py,sha256=T74p_OXhzfNSRYesV0Y5bTBRhBfd2Tl2HyCAPfESf-0,16900
+semurg/errors.py,sha256=XviWi-hcZwCLdki3-EURpPKqOpRnvf8C6JGBefDZaYk,2342
+semurg/frame.py,sha256=90XLs6mE1X2wHJ-LHcuOxv4K-nTviIcVlbWU7b1RSMM,7377
+semurg/transports.py,sha256=OSSOlAyrxETATS2gKvffCVVDPOz2MegkeGOW3kJGpgk,16823
+semurg-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+semurg-0.1.0.dist-info/METADATA,sha256=mGpPLQHWHhkhNvvbl8bwYYjpVQQb035cXKjkj3GLoa4,3224
+semurg-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+semurg-0.1.0.dist-info/top_level.txt,sha256=LRCUgk-clKV46CK6bBWXs5Ag89mDdWFaFCqE5M5Rx7E,7
+semurg-0.1.0.dist-info/RECORD,,

semurg-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

semurg-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

semurg-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+semurg