taisce 0.1.0__tar.gz

taisce-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: taisce
+Version: 0.1.0
+Summary: Client for a Taisce memory deployment: the v1 contract, no agent framework.
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+
+# taisce
+
+The client for a Taisce memory deployment over the v1 contract: `observe`, `freshness`, `recall`
+and `resolve_citation`, asynchronous, with `httpx` as its only dependency. The agent framework
+adapters in this repository are built on it.

taisce-0.1.0/README.md

@@ -0,0 +1,5 @@
+# taisce
+
+The client for a Taisce memory deployment over the v1 contract: `observe`, `freshness`, `recall`
+and `resolve_citation`, asynchronous, with `httpx` as its only dependency. The agent framework
+adapters in this repository are built on it.

taisce-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "taisce"
+version = "0.1.0"
+description = "Client for a Taisce memory deployment: the v1 contract, no agent framework."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = ["httpx>=0.27"]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["taisce*"]

taisce-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

taisce-0.1.0/taisce/__init__.py

@@ -0,0 +1,7 @@
+# Copyright 2026 The Taisce Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Taisce for Python: the client over the v1 contract, and what every adapter renders the same."""
+from .client import Client, Freshness, TaisceError, bundle_is_empty
+from .memory import MEMORY_MESSAGE_PREFIX, is_memory_text, render_context_message, render_memory_message, turn_key
+
+__all__ = ["Client", "Freshness", "TaisceError", "bundle_is_empty", "MEMORY_MESSAGE_PREFIX", "is_memory_text", "render_context_message", "render_memory_message", "turn_key"]

taisce-0.1.0/taisce/client.py

@@ -0,0 +1,187 @@
+# Copyright 2026 The Taisce Authors
+# SPDX-License-Identifier: Apache-2.0
+"""The client: the v1 contract of a Taisce deployment, and nothing about any agent framework.
+
+The adapters are built on this, so a caller who wants governed memory without a framework does not
+acquire one by asking. It is asynchronous because the frameworks it serves are; the sync wrapper
+exists for scripts. The credential is a bearer token bound to one project, sent nowhere but the
+deployment this client was built for, and never logged.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional, Sequence
+
+import base64
+
+import httpx
+
+
+class TaisceError(Exception):
+    """A refusal from the deployment, carrying the contract's own code. Branch on ``code``."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(f"{status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+@dataclass(frozen=True)
+class Freshness:
+    """How far behind memory is: the highest offset stored, the highest formed, the parked count."""
+
+    scope: str
+    stored: Optional[int]
+    formed: Optional[int]
+    parked: int
+
+
+class Client:
+    """An asynchronous client over the v1 contract."""
+
+    def __init__(self, base_url: str, token: str, *, http: Optional[httpx.AsyncClient] = None, timeout: float = 30.0) -> None:
+        if not base_url or not base_url.strip():
+            raise ValueError("a deployment address is required")
+        if not token or not token.strip():
+            raise ValueError("a credential is required")
+        self.base_url = base_url.rstrip("/")
+        self._owns_http = http is None
+        self._http = http or httpx.AsyncClient(timeout=timeout)
+        self._headers = {"Authorization": "Bearer " + token, "Content-Type": "application/json"}
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "Client":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def observe(self, *, idempotency_key: str, messages: Sequence[Mapping[str, Any]],
+                      data_subject_id: Optional[str] = None, occurred_at: Optional[str] = None) -> dict:
+        """Records a turn. Durable when it returns; formation follows."""
+        body: dict = {"idempotency_key": idempotency_key, "messages": list(messages)}
+        if data_subject_id:
+            body["data_subject_id"] = data_subject_id
+        if occurred_at:
+            body["occurred_at"] = occurred_at
+        return await self._post("/v1/observations", body, 201)
+
+    async def freshness(self) -> Freshness:
+        """How far behind memory is."""
+        response = await self._http.get(self.base_url + "/v1/freshness", headers=self._headers)
+        data = self._read(response, 200)
+        return Freshness(scope=data.get("scope", ""), stored=data.get("stored"), formed=data.get("formed"), parked=int(data.get("parked", 0)))
+
+    async def recall(self, *, question: str, data_subject_id: Optional[str] = None, **controls: Any) -> dict:
+        """Asks memory a question. ``controls`` are the contract's: max_characters, source_roles, hops, surfaces, themes, as_of, as_known_at."""
+        body: dict = {"question": question}
+        if data_subject_id:
+            body["data_subject_id"] = data_subject_id
+        body.update({k: v for k, v in controls.items() if v is not None})
+        return await self._post("/v1/recalls", body, 200)
+
+    async def put_artifact(self, *, artifact_id: str, data_subject_id: str, kind: str, content: bytes,
+                           name: Optional[str] = None, expected_version: Optional[str] = None) -> dict:
+        """Stores an opaque object under a person, replacing the version it names.
+
+        The bytes are the application's and the deployment never interprets them. It holds them
+        under a project and a person, expires them with that person's retention and removes them
+        with that person's erasure — which is the whole reason to keep session state here rather
+        than in an application's own database, where a deletion request would have two places to
+        sweep and a counted residual for only one of them.
+        """
+        body: dict = {"id": artifact_id, "data_subject_id": data_subject_id, "kind": kind,
+                      "content": base64.b64encode(content).decode("ascii")}
+        if name:
+            body["name"] = name
+        if expected_version:
+            body["expected_version"] = expected_version
+        return await self._post("/v1/artifacts/put", body, 200)
+
+    async def get_artifact(self, *, artifact_id: str, data_subject_id: Optional[str] = None) -> dict:
+        """Reads one object, optionally requiring it to belong to the person named.
+
+        One credential opens a project, and a project holds every end user's objects. Naming the
+        subject makes "this one is theirs" a requirement the deployment enforces rather than a habit
+        the application keeps: another person's object is answered exactly as one that is not there.
+        """
+        body: dict = {"id": artifact_id}
+        if data_subject_id:
+            body["data_subject_id"] = data_subject_id
+        return await self._post("/v1/artifacts/get", body, 200)
+
+    async def delete_artifact(self, *, artifact_id: str, data_subject_id: Optional[str] = None,
+                              expected_version: Optional[str] = None) -> dict:
+        """Removes one object, optionally requiring it to belong to the person named."""
+        body: dict = {"id": artifact_id}
+        if data_subject_id:
+            body["data_subject_id"] = data_subject_id
+        if expected_version:
+            body["expected_version"] = expected_version
+        return await self._post("/v1/artifacts/delete", body, 200)
+
+    async def search_passages(self, *, question: str, limit: Optional[int] = None,
+                              data_subject_id: Optional[str] = None,
+                              source_role: Optional[str] = None) -> dict:
+        """Searches the stored words themselves, for a question no fact answers.
+
+        This is the other half of retrieval and deliberately separate from :meth:`recall`: recall
+        answers from what was inferred, this answers from what was said. A caller that wants
+        grounding without adopting the memory model uses only this.
+
+        The answer carries ``approximate`` and ``covered_through_offset`` because a passage search
+        reads an embedding generation, and a generation is built up to a point in the log. Treating
+        an answer as complete while the build is behind quotes an index rather than the memory.
+        """
+        body: dict = {"question": question}
+        if limit is not None:
+            body["limit"] = limit
+        if data_subject_id:
+            body["data_subject_id"] = data_subject_id
+        if source_role:
+            body["source_role"] = source_role
+        return await self._post("/v1/passages/search", body, 200)
+
+    async def context(self, *, data_subject_id: str, max_characters: Optional[int] = None) -> dict:
+        """One subject's history under a budget: the newest turns verbatim and, over the rest, the
+        segments the deployment wrote. No model call is made; what the deployment has not rolled up
+        yet comes back verbatim and cut from the oldest end."""
+        if not data_subject_id or not data_subject_id.strip():
+            raise ValueError("a data subject is required: a context is one subject's history")
+        body: dict = {"data_subject_id": data_subject_id}
+        if max_characters is not None:
+            body["max_characters"] = max_characters
+        return await self._post("/v1/contexts", body, 200)
+
+    async def resolve_citation(self, *, fact_id: str, limit: Optional[int] = None) -> dict:
+        """Resolves a fact to its record."""
+        body: dict = {"id": fact_id}
+        if limit is not None:
+            body["limit"] = limit
+        return await self._post("/v1/citations/resolve", body, 200)
+
+    async def _post(self, path: str, body: dict, success: int) -> dict:
+        response = await self._http.post(self.base_url + path, json=body, headers=self._headers)
+        return self._read(response, success)
+
+    @staticmethod
+    def _read(response: httpx.Response, success: int) -> dict:
+        if response.status_code == success:
+            return response.json()
+        code, message = "unexpected_response", "the deployment answered " + str(response.status_code)
+        try:
+            error = response.json().get("error") or {}
+            code = error.get("code") or code
+            message = error.get("message") or message
+        except ValueError:
+            pass
+        raise TaisceError(response.status_code, code, message)
+
+
+def bundle_is_empty(bundle: Mapping[str, Any]) -> bool:
+    """Whether a recall returned nothing at all: no facts, no reports, no passages."""
+    return not (bundle.get("facts") or bundle.get("reports") or bundle.get("passages"))

taisce-0.1.0/taisce/memory.py

@@ -0,0 +1,64 @@
+# Copyright 2026 The Taisce Authors
+# SPDX-License-Identifier: Apache-2.0
+"""What every adapter renders the same way: the memory message and the turn key.
+
+These live in the client so that the two Python adapters share one implementation, and so that
+the bytes agree with the .NET adapter's, which derives them the same way: a turn stored by two
+adapters is one observation, and a memory message from either parses the same.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from typing import Mapping, Optional, Sequence
+
+#: The first line of every injected memory message; the conformance suite parses it.
+MEMORY_MESSAGE_PREFIX = "taisce-memory/v1 untrusted"
+
+
+def render_memory_message(watermark: Mapping[str, object], bundle: Mapping[str, object]) -> str:
+    """The prefix line, then a JSON document with the watermark, the plan (what the recall did)
+    and the recall's own arrays unchanged."""
+    document = {
+        "watermark": {"stored": watermark.get("stored"), "formed": watermark.get("formed"), "parked": watermark.get("parked", 0)},
+        "plan": {"controls": bundle.get("controls"), "degraded": bundle.get("degraded") or [], "reach": bundle.get("reach")},
+        "facts": bundle.get("facts") or [],
+        "reports": bundle.get("reports") or [],
+        "passages": bundle.get("passages") or [],
+    }
+    return MEMORY_MESSAGE_PREFIX + "\n" + json.dumps(document, separators=(",", ":"))
+
+
+def render_context_message(context: Mapping[str, object]) -> str:
+    """The prefix line, then a JSON document with the watermark, the assembly's cost as the plan,
+    and the context's segments and turns unchanged: what replaces a history is the deployment's
+    answer and nothing an adapter wrote."""
+    watermark = context.get("watermark") or {}
+    if not isinstance(watermark, Mapping):
+        watermark = {}
+    document = {
+        "watermark": {"stored": watermark.get("stored"), "formed": watermark.get("formed"), "parked": watermark.get("parked", 0)},
+        "plan": {"characters": context.get("characters") or 0, "truncated": bool(context.get("truncated"))},
+        "segments": context.get("segments") or [],
+        "turns": context.get("turns") or [],
+    }
+    return MEMORY_MESSAGE_PREFIX + "\n" + json.dumps(document, separators=(",", ":"))
+
+
+def is_memory_text(text: Optional[str]) -> bool:
+    """Whether a message's text is one an adapter injected, by its first line."""
+    return bool(text) and text.startswith(MEMORY_MESSAGE_PREFIX)
+
+
+def turn_key(data_subject_id: Optional[str], run_id: Optional[str], messages: Sequence[Mapping[str, str]]) -> str:
+    """A turn's key: a version-5 UUID over the subject, the run and the messages, so a retried
+    store is one observation and a different turn is another."""
+    text = (data_subject_id or "") + "\n" + (run_id or "") + "\n"
+    for m in messages:
+        text += m["role"] + "\n" + m["content"] + "\n"
+    digest = hashlib.sha256(text.encode("utf-8")).digest()
+    raw = bytearray(digest[:16])
+    raw[6] = (raw[6] & 0x0F) | 0x50
+    raw[8] = (raw[8] & 0x3F) | 0x80
+    return str(uuid.UUID(bytes=bytes(raw)))

taisce-0.1.0/taisce.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: taisce
+Version: 0.1.0
+Summary: Client for a Taisce memory deployment: the v1 contract, no agent framework.
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+
+# taisce
+
+The client for a Taisce memory deployment over the v1 contract: `observe`, `freshness`, `recall`
+and `resolve_citation`, asynchronous, with `httpx` as its only dependency. The agent framework
+adapters in this repository are built on it.

taisce-0.1.0/taisce.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+taisce/__init__.py
+taisce/client.py
+taisce/memory.py
+taisce.egg-info/PKG-INFO
+taisce.egg-info/SOURCES.txt
+taisce.egg-info/dependency_links.txt
+taisce.egg-info/requires.txt
+taisce.egg-info/top_level.txt
+tests/test_client.py
+tests/test_context_message.py

taisce-0.1.0/taisce.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

taisce-0.1.0/taisce.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.27

taisce-0.1.0/taisce.egg-info/top_level.txt

@@ -0,0 +1 @@
+taisce

taisce-0.1.0/tests/test_client.py

@@ -0,0 +1,20 @@
+# Copyright 2026 The Taisce Authors
+# SPDX-License-Identifier: Apache-2.0
+import pytest
+
+from taisce import Client, bundle_is_empty
+
+
+def test_a_client_refuses_to_be_built_without_a_deployment_or_a_credential():
+    with pytest.raises(ValueError):
+        Client("", "tsk")
+    with pytest.raises(ValueError):
+        Client("http://127.0.0.1:1", " ")
+    client = Client("http://127.0.0.1:1/", "tsk")
+    assert client.base_url == "http://127.0.0.1:1"
+
+
+def test_an_empty_bundle_is_empty():
+    assert bundle_is_empty({"facts": [], "reports": [], "passages": []})
+    assert not bundle_is_empty({"facts": [{"fact_id": "f1"}], "reports": [], "passages": []})
+    assert not bundle_is_empty({"facts": [], "reports": [{"title": "t"}], "passages": []})

taisce-0.1.0/tests/test_context_message.py

@@ -0,0 +1,29 @@
+# Copyright 2026 The Taisce Authors
+# SPDX-License-Identifier: Apache-2.0
+import json
+
+import pytest
+
+from taisce import Client, MEMORY_MESSAGE_PREFIX, is_memory_text, render_context_message
+
+
+def test_the_context_message_is_the_prefix_line_and_the_deployments_arrays_unchanged():
+    context = {"watermark": {"stored": 12, "formed": 12}, "characters": 140, "truncated": False,
+               "segments": [{"level": 1, "summary": "The office moved."}],
+               "turns": [{"log_offset": 9, "messages": [{"role": "user", "content": "Book it."}]}]}
+    rendered = render_context_message(context)
+    assert rendered.startswith(MEMORY_MESSAGE_PREFIX + "\n") and is_memory_text(rendered)
+    document = json.loads(rendered.split("\n", 1)[1])
+    assert document["watermark"] == {"stored": 12, "formed": 12, "parked": 0}
+    assert document["plan"] == {"characters": 140, "truncated": False}
+    assert document["segments"] == context["segments"] and document["turns"] == context["turns"]
+    # A context with nothing in it renders empty arrays, never a missing field.
+    bare = json.loads(render_context_message({}).split("\n", 1)[1])
+    assert bare["segments"] == [] and bare["turns"] == [] and bare["watermark"]["stored"] is None
+
+
+@pytest.mark.asyncio
+async def test_a_context_needs_a_subject():
+    async with Client("http://127.0.0.1:1", "tsk") as client:
+        with pytest.raises(ValueError):
+            await client.context(data_subject_id=" ")