threadlessai 0.1.0__tar.gz

threadlessai-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules
+dist
+.next
+.vercel
+.env
+.env.*
+!.env.example
+.DS_Store
+plans
+*.tsbuildinfo
+.claude/*
+!.claude/skills
+packages/sdk-ts/dist
+.venv
+__pycache__
+.pytest_cache
+deploy/hetzner/threadlessai.env
+apps/bench/data
+apps/bench/results
+packages/*/src/**/*.d.ts
+
+# Next.js generates this on build and dev
+next-env.d.ts

threadlessai-0.1.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Threadless AI. All rights reserved.
+
+This software is licensed, not sold. You may install and use it only to call
+the Threadless AI service (threadlessai.com) under its Terms of Service. You
+may not copy, modify, distribute, sublicense or reverse engineer it, or use it
+with any other service, except as those Terms allow.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

threadlessai-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: threadlessai
+Version: 0.1.0
+Summary: Threadless AI: memory for agents. Decorate every model call, report every reply.
+Project-URL: Homepage, https://threadlessai.com
+License: Copyright (c) 2026 Threadless AI. All rights reserved.
+        
+        This software is licensed, not sold. You may install and use it only to call
+        the Threadless AI service (threadlessai.com) under its Terms of Service. You
+        may not copy, modify, distribute, sublicense or reverse engineer it, or use it
+        with any other service, except as those Terms allow.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+License-File: LICENSE
+Keywords: agents,context,llm,long-term memory,memory,openai
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.23
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# threadlessai
+
+Threadless AI: memory for agents. Decorate every model call, report every reply.
+
+```
+pip install threadlessai
+```
+
+Set `THREADLESS_API_KEY` (a `tl_live_…` or `tl_test_…` project key), or pass `api_key=`.
+
+## Chat Completions
+
+```python
+from openai import OpenAI
+from threadlessai import NOTE_RESULT, Threadless, is_note_call
+
+openai = OpenAI()
+threadless = Threadless()
+memory = threadless.memories.create()  # one per conversation
+
+new_messages = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "Hi, I'm planning a launch."},
+]
+while True:
+    request = threadless.chat.decorate(
+        memory["id"],
+        new_messages,
+        {"model": "gpt-5", "tools": [threadless.chat.note_tool]},
+    )
+    completion = openai.chat.completions.create(**request)
+    threadless.chat.report(memory["id"], completion)  # background, never raises
+
+    message = completion.choices[0].message
+    calls = message.tool_calls or []
+    if not calls:
+        print(message.content)
+        break
+    # Hand over only what is new since the last decorate: the reply and the tool results.
+    new_messages = [message]
+    for call in calls:
+        output = NOTE_RESULT if is_note_call(call.function.name) else run_tool(call)
+        new_messages.append({"role": "tool", "tool_call_id": call.id, "content": output})
+```
+
+## Responses
+
+```python
+from openai import OpenAI
+from threadlessai import NOTE_RESULT, Threadless, is_note_call
+
+openai = OpenAI()
+threadless = Threadless()
+memory = threadless.memories.create()
+
+new_items = [{"role": "user", "content": "Hi, I'm planning a launch."}]
+while True:
+    request = threadless.responses.decorate(
+        memory["id"],
+        new_items,
+        {"model": "gpt-5", "tools": [threadless.responses.note_tool]},
+    )
+    response = openai.responses.create(**request)
+    threadless.responses.report(memory["id"], response)
+
+    calls = [item for item in response.output if item.type == "function_call"]
+    if not calls:
+        print(response.output_text)
+        break
+    new_items = [item.model_dump(mode="json", exclude_none=True) for item in response.output]
+    for call in calls:
+        output = NOTE_RESULT if is_note_call(call.name) else run_tool(call)
+        new_items.append({"type": "function_call_output", "call_id": call.call_id, "output": output})
+```
+
+## Notes
+
+- **Decorate never fails your model call** on a network error, a timeout, a 5xx, 429 or 408: it builds the request from a local tail of recent turns and tells `on_error`. Any other 4xx raises `ThreadlessError` (`status`, `code`, `message`, `hint`).
+- **Report runs in the background** and never raises. The next decorate for the same memory waits up to 2 seconds for it. Call `threadless.close()` (or use `with Threadless() as threadless:`) to wait for reports still in flight.
+- **Async:** `AsyncThreadless` has the same surface; `await client.chat.decorate(...)`, and `client.chat.report(...)` schedules a task. Close it with `await client.aclose()`.
+- `client.memories.get(id)`, `.delete(id)` and `.export(id)` manage a memory.

threadlessai-0.1.0/README.md

@@ -0,0 +1,81 @@
+# threadlessai
+
+Threadless AI: memory for agents. Decorate every model call, report every reply.
+
+```
+pip install threadlessai
+```
+
+Set `THREADLESS_API_KEY` (a `tl_live_…` or `tl_test_…` project key), or pass `api_key=`.
+
+## Chat Completions
+
+```python
+from openai import OpenAI
+from threadlessai import NOTE_RESULT, Threadless, is_note_call
+
+openai = OpenAI()
+threadless = Threadless()
+memory = threadless.memories.create()  # one per conversation
+
+new_messages = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "Hi, I'm planning a launch."},
+]
+while True:
+    request = threadless.chat.decorate(
+        memory["id"],
+        new_messages,
+        {"model": "gpt-5", "tools": [threadless.chat.note_tool]},
+    )
+    completion = openai.chat.completions.create(**request)
+    threadless.chat.report(memory["id"], completion)  # background, never raises
+
+    message = completion.choices[0].message
+    calls = message.tool_calls or []
+    if not calls:
+        print(message.content)
+        break
+    # Hand over only what is new since the last decorate: the reply and the tool results.
+    new_messages = [message]
+    for call in calls:
+        output = NOTE_RESULT if is_note_call(call.function.name) else run_tool(call)
+        new_messages.append({"role": "tool", "tool_call_id": call.id, "content": output})
+```
+
+## Responses
+
+```python
+from openai import OpenAI
+from threadlessai import NOTE_RESULT, Threadless, is_note_call
+
+openai = OpenAI()
+threadless = Threadless()
+memory = threadless.memories.create()
+
+new_items = [{"role": "user", "content": "Hi, I'm planning a launch."}]
+while True:
+    request = threadless.responses.decorate(
+        memory["id"],
+        new_items,
+        {"model": "gpt-5", "tools": [threadless.responses.note_tool]},
+    )
+    response = openai.responses.create(**request)
+    threadless.responses.report(memory["id"], response)
+
+    calls = [item for item in response.output if item.type == "function_call"]
+    if not calls:
+        print(response.output_text)
+        break
+    new_items = [item.model_dump(mode="json", exclude_none=True) for item in response.output]
+    for call in calls:
+        output = NOTE_RESULT if is_note_call(call.name) else run_tool(call)
+        new_items.append({"type": "function_call_output", "call_id": call.call_id, "output": output})
+```
+
+## Notes
+
+- **Decorate never fails your model call** on a network error, a timeout, a 5xx, 429 or 408: it builds the request from a local tail of recent turns and tells `on_error`. Any other 4xx raises `ThreadlessError` (`status`, `code`, `message`, `hint`).
+- **Report runs in the background** and never raises. The next decorate for the same memory waits up to 2 seconds for it. Call `threadless.close()` (or use `with Threadless() as threadless:`) to wait for reports still in flight.
+- **Async:** `AsyncThreadless` has the same surface; `await client.chat.decorate(...)`, and `client.chat.report(...)` schedules a task. Close it with `await client.aclose()`.
+- `client.memories.get(id)`, `.delete(id)` and `.export(id)` manage a memory.

threadlessai-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "threadlessai"
+version = "0.1.0"
+description = "Threadless AI: memory for agents. Decorate every model call, report every reply."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.23"]
+keywords = ["memory", "agents", "llm", "openai", "context", "long-term memory"]
+classifiers = [
+  "License :: Other/Proprietary License",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://threadlessai.com"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threadlessai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "LICENSE", "README.md"]

threadlessai-0.1.0/src/threadlessai/__init__.py

@@ -0,0 +1,37 @@
+"""Threadless AI: memory for agents. Decorate every model call, report every reply."""
+
+from ._async_client import AsyncSurface, AsyncThreadless
+from ._client import Surface, Threadless
+from ._core import ErrorContext, ThreadlessError, trim_tail
+from ._note_tool import (
+    NOTE_RESULT,
+    NOTE_TOOL_DESCRIPTION,
+    NOTE_TOOL_NAME,
+    NOTE_TOOL_PARAMETERS,
+    Format,
+    NoteFact,
+    is_note_call,
+    note_tool_definition,
+    read_note_facts,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncSurface",
+    "AsyncThreadless",
+    "ErrorContext",
+    "Format",
+    "NOTE_RESULT",
+    "NOTE_TOOL_DESCRIPTION",
+    "NOTE_TOOL_NAME",
+    "NOTE_TOOL_PARAMETERS",
+    "NoteFact",
+    "Surface",
+    "Threadless",
+    "ThreadlessError",
+    "is_note_call",
+    "note_tool_definition",
+    "read_note_facts",
+    "trim_tail",
+]

threadlessai-0.1.0/src/threadlessai/_async_client.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional, Set
+
+import httpx
+
+from ._core import (
+    DEFAULT_TAIL_TOKENS,
+    DEFAULT_TIMEOUT,
+    REPORT_WAIT,
+    BaseClient,
+    OnError,
+    Raw,
+    falls_back,
+    items_of,
+    plain,
+    quote_id,
+)
+from ._note_tool import Format, note_tool_definition
+
+
+class AsyncMemories:
+    def __init__(self, client: "AsyncThreadless") -> None:
+        self._client = client
+
+    async def create(self, metadata: Optional[Dict[str, str]] = None) -> Raw:
+        body: Raw = {} if metadata is None else {"metadata": metadata}
+        return await self._client._call("POST", "/memories", body)
+
+    async def get(self, memory_id: str) -> Raw:
+        return await self._client._call("GET", f"/memories/{quote_id(memory_id)}")
+
+    async def delete(self, memory_id: str) -> None:
+        await self._client._call("DELETE", f"/memories/{quote_id(memory_id)}")
+        self._client._forget_tail(memory_id)
+
+    async def export(self, memory_id: str) -> Raw:
+        return await self._client._call("GET", f"/memories/{quote_id(memory_id)}/export")
+
+
+class AsyncSurface:
+    """One OpenAI API: `client.chat` (Chat Completions) or `client.responses`."""
+
+    def __init__(self, client: "AsyncThreadless", format: Format) -> None:
+        self._client = client
+        self._format = format
+        #: The note tool for this API: add it to your tools once.
+        self.note_tool: Raw = note_tool_definition(format)
+
+    async def decorate(self, memory_id: str, new_messages: List[Any], request: Raw) -> Raw:
+        """Before every model call: hand over what is new since the last call and get
+        back the request to submit. When we cannot be reached it never fails the
+        call: the request is built from the local tail of recent turns instead."""
+        client = self._client
+        pending = client._reports.get(memory_id)
+        if pending is not None:
+            await asyncio.wait({pending}, timeout=REPORT_WAIT)
+        messages: List[Raw] = [plain(item) for item in new_messages]
+        try:
+            out = await client._call(
+                "POST",
+                f"/memories/{quote_id(memory_id)}/decorate",
+                {"format": self._format, "messages": messages, "request": request},
+            )
+            decorated = out.get("request") if isinstance(out, dict) else None
+            client._remember_tail(memory_id, items_of(self._format, decorated))
+            return decorated  # type: ignore[return-value]
+        except Exception as error:
+            if not falls_back(error):
+                raise
+            client._notify(error, "decorate", memory_id)
+            return client._fallback(self._format, memory_id, messages, request)
+
+    def report(self, memory_id: str, reply: Any) -> None:
+        """After the model replies: hand over the reply. Schedules a task on the
+        running loop and never raises."""
+        client = self._client
+        try:
+            body = {"format": self._format, "reply": plain(reply)}
+            task = asyncio.get_running_loop().create_task(client._send_report(memory_id, body))
+        except Exception as error:
+            client._notify_quietly(error, memory_id)
+            return
+        client._reports[memory_id] = task
+        client._tasks.add(task)
+        task.add_done_callback(lambda done: client._report_done(memory_id, done))
+
+
+class AsyncThreadless(BaseClient):
+    """The Threadless AI client for asyncio."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        tail_tokens: int = DEFAULT_TAIL_TOKENS,
+        on_error: Optional[OnError] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, tail_tokens, on_error)
+        self._owns_http = http_client is None
+        self._http = http_client if http_client is not None else httpx.AsyncClient()
+        #: Per memory: a report still in flight.
+        self._reports: Dict[str, "asyncio.Task[None]"] = {}
+        #: Every report task, held so none is garbage-collected mid-flight.
+        self._tasks: Set["asyncio.Task[None]"] = set()
+        self.memories = AsyncMemories(self)
+        self.chat = AsyncSurface(self, "chat.completions")
+        self.responses = AsyncSurface(self, "responses")
+
+    async def _call(self, method: str, path: str, body: Any = None) -> Any:
+        """One request to the runtime API. Raises ThreadlessError on an error response."""
+        response = await self._http.request(**self._request(method, path, body))
+        return self._parse(response)
+
+    async def _send_report(self, memory_id: str, body: Raw) -> None:
+        try:
+            await self._call("POST", f"/memories/{quote_id(memory_id)}/report", body)
+        except Exception as error:
+            self._notify_quietly(error, memory_id)
+
+    def _notify_quietly(self, error: BaseException, memory_id: str) -> None:
+        try:
+            self._notify(error, "report", memory_id)
+        except Exception:
+            pass
+
+    def _report_done(self, memory_id: str, task: "asyncio.Task[None]") -> None:
+        self._tasks.discard(task)
+        if self._reports.get(memory_id) is task:
+            del self._reports[memory_id]
+
+    async def aclose(self) -> None:
+        """Waits for reports still in flight, then closes the HTTP client."""
+        if self._tasks:
+            await asyncio.gather(*self._tasks, return_exceptions=True)
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncThreadless":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()

threadlessai-0.1.0/src/threadlessai/_client.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import concurrent.futures
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from ._core import (
+    DEFAULT_TAIL_TOKENS,
+    DEFAULT_TIMEOUT,
+    REPORT_WAIT,
+    BaseClient,
+    OnError,
+    Raw,
+    falls_back,
+    items_of,
+    plain,
+    quote_id,
+)
+from ._note_tool import Format, note_tool_definition
+
+REPORT_WORKERS = 4
+
+
+class Memories:
+    def __init__(self, client: "Threadless") -> None:
+        self._client = client
+
+    def create(self, metadata: Optional[Dict[str, str]] = None) -> Raw:
+        body: Raw = {} if metadata is None else {"metadata": metadata}
+        return self._client._call("POST", "/memories", body)
+
+    def get(self, memory_id: str) -> Raw:
+        return self._client._call("GET", f"/memories/{quote_id(memory_id)}")
+
+    def delete(self, memory_id: str) -> None:
+        self._client._call("DELETE", f"/memories/{quote_id(memory_id)}")
+        self._client._forget_tail(memory_id)
+
+    def export(self, memory_id: str) -> Raw:
+        return self._client._call("GET", f"/memories/{quote_id(memory_id)}/export")
+
+
+class Surface:
+    """One OpenAI API: `client.chat` (Chat Completions) or `client.responses`."""
+
+    def __init__(self, client: "Threadless", format: Format) -> None:
+        self._client = client
+        self._format = format
+        #: The note tool for this API: add it to your tools once.
+        self.note_tool: Raw = note_tool_definition(format)
+
+    def decorate(self, memory_id: str, new_messages: List[Any], request: Raw) -> Raw:
+        """Before every model call: hand over what is new since the last call and get
+        back the request to submit. When we cannot be reached it never fails the
+        call: the request is built from the local tail of recent turns instead."""
+        client = self._client
+        client._wait_for_report(memory_id)
+        messages: List[Raw] = [plain(item) for item in new_messages]
+        try:
+            out = client._call(
+                "POST",
+                f"/memories/{quote_id(memory_id)}/decorate",
+                {"format": self._format, "messages": messages, "request": request},
+            )
+            decorated = out.get("request") if isinstance(out, dict) else None
+            client._remember_tail(memory_id, items_of(self._format, decorated))
+            return decorated  # type: ignore[return-value]
+        except Exception as error:
+            if not falls_back(error):
+                raise
+            client._notify(error, "decorate", memory_id)
+            return client._fallback(self._format, memory_id, messages, request)
+
+    def report(self, memory_id: str, reply: Any) -> None:
+        """After the model replies: hand over the reply. Runs in the background and
+        never raises."""
+        client = self._client
+        try:
+            body = {"format": self._format, "reply": plain(reply)}
+            future = client._executor.submit(client._send_report, memory_id, body)
+        except Exception as error:
+            client._notify_quietly(error, memory_id)
+            return
+        with client._lock:
+            client._reports[memory_id] = future
+        future.add_done_callback(lambda done: client._report_done(memory_id, done))
+
+
+class Threadless(BaseClient):
+    """The Threadless AI client. Reports run on a small background thread pool."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        tail_tokens: int = DEFAULT_TAIL_TOKENS,
+        on_error: Optional[OnError] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, tail_tokens, on_error)
+        self._owns_http = http_client is None
+        self._http = http_client if http_client is not None else httpx.Client()
+        self._executor = concurrent.futures.ThreadPoolExecutor(
+            max_workers=REPORT_WORKERS, thread_name_prefix="threadless-report"
+        )
+        #: Per memory: a report still in flight.
+        self._reports: Dict[str, "concurrent.futures.Future[None]"] = {}
+        self.memories = Memories(self)
+        self.chat = Surface(self, "chat.completions")
+        self.responses = Surface(self, "responses")
+
+    def _call(self, method: str, path: str, body: Any = None) -> Any:
+        """One request to the runtime API. Raises ThreadlessError on an error response."""
+        response = self._http.request(**self._request(method, path, body))
+        return self._parse(response)
+
+    def _send_report(self, memory_id: str, body: Raw) -> None:
+        try:
+            self._call("POST", f"/memories/{quote_id(memory_id)}/report", body)
+        except Exception as error:
+            self._notify_quietly(error, memory_id)
+
+    def _notify_quietly(self, error: BaseException, memory_id: str) -> None:
+        try:
+            self._notify(error, "report", memory_id)
+        except Exception:
+            pass
+
+    def _report_done(self, memory_id: str, future: "concurrent.futures.Future[None]") -> None:
+        with self._lock:
+            if self._reports.get(memory_id) is future:
+                del self._reports[memory_id]
+
+    def _wait_for_report(self, memory_id: str) -> None:
+        with self._lock:
+            pending = self._reports.get(memory_id)
+        if pending is not None:
+            concurrent.futures.wait([pending], timeout=REPORT_WAIT)
+
+    def close(self) -> None:
+        """Waits for reports still in flight, then closes the HTTP client."""
+        self._executor.shutdown(wait=True)
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "Threadless":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

threadlessai-0.1.0/src/threadlessai/_core.py

@@ -0,0 +1,217 @@
+"""What the sync and async clients share: errors, the local tail, the HTTP shape."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import threading
+from collections import OrderedDict
+from typing import Any, Callable, Dict, List, Optional, TypedDict
+from urllib.parse import quote
+
+import httpx
+
+from ._note_tool import Format
+
+Raw = Dict[str, Any]
+
+DEFAULT_BASE_URL = "https://api.threadlessai.com/v1"
+DEFAULT_TIMEOUT = 15.0
+DEFAULT_TAIL_TOKENS = 60_000
+#: A report still in flight holds the memory's next decorate this long at most (seconds).
+REPORT_WAIT = 2.0
+TAILS_KEPT = 200
+
+
+class ErrorContext(TypedDict):
+    operation: str  # "decorate" | "report"
+    memory_id: str
+
+
+OnError = Callable[[BaseException, ErrorContext], None]
+
+
+class ThreadlessError(Exception):
+    """An error response from the Threadless API."""
+
+    def __init__(self, status: int, code: str, message: str, hint: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.hint = hint
+
+    def __repr__(self) -> str:
+        return (
+            f"ThreadlessError(status={self.status!r}, code={self.code!r}, "
+            f"message={self.message!r}, hint={self.hint!r})"
+        )
+
+
+def _json_length(value: Any) -> int:
+    """The length of JSON.stringify(value) in UTF-16 code units, as JavaScript counts it."""
+    text = json.dumps(value, separators=(",", ":"), ensure_ascii=False, default=str)
+    return len(text.encode("utf-16-le")) // 2
+
+
+def estimate_tokens(item: Any) -> int:
+    return math.ceil(_json_length(item if item is not None else "") / 4) + 4
+
+
+def _get(item: Any, key: str) -> Any:
+    return item.get(key) if isinstance(item, dict) else None
+
+
+def is_instruction(item: Any) -> bool:
+    return _get(item, "role") in ("system", "developer") and _get(item, "type") in (None, "message")
+
+
+def is_user_message(item: Any) -> bool:
+    return _get(item, "role") == "user" and _get(item, "type") in (None, "message")
+
+
+def trim_tail(items: List[Raw], budget: int) -> List[Raw]:
+    """The local tail: the instructions, then the newest history that fits, cut at
+    a user message so a tool call is never separated from its output."""
+    instructions = [item for item in items if is_instruction(item)]
+    history = [item for item in items if not is_instruction(item)]
+    used = sum(estimate_tokens(item) for item in instructions)
+    start = len(history)
+    for index in range(len(history) - 1, -1, -1):
+        used += estimate_tokens(history[index])
+        if used > budget:
+            break
+        if is_user_message(history[index]):
+            start = index
+    if start == len(history) and history:
+        # Not even one turn fits: keep the newest user message onward.
+        users = [index for index, item in enumerate(history) if is_user_message(item)]
+        start = users[-1] if users else len(history) - 1
+    return instructions + history[start:]
+
+
+def _or(value: Any, default: Any) -> Any:
+    """JavaScript's `??`."""
+    return default if value is None else value
+
+
+def quote_id(memory_id: str) -> str:
+    """encodeURIComponent."""
+    return quote(memory_id, safe="!~*'()")
+
+
+def items_of(format: Format, request: Any) -> List[Raw]:
+    if request is None:
+        raise TypeError("decorate returned no request")
+    items = _get(request, "input" if format == "responses" else "messages")
+    return items if isinstance(items, list) else []
+
+
+def plain(value: Any, **dump: Any) -> Any:
+    """An openai SDK object as plain JSON data, with the API's own field names
+    (`async`, not the Python `async_`) and no empty fields; anything else as it is."""
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        return model_dump(mode="json", by_alias=True, exclude_none=True, **dump)
+    return value
+
+
+def falls_back(error: BaseException) -> bool:
+    """Whether decorate goes ahead on the local tail rather than raising.
+    A request we sent wrong is ours to see, not a reason to go on without memory."""
+    if isinstance(error, ThreadlessError):
+        return error.status >= 500 or error.status in (429, 408)
+    return isinstance(error, Exception)
+
+
+class BaseClient:
+    def __init__(
+        self,
+        api_key: Optional[str],
+        base_url: Optional[str],
+        timeout: float,
+        tail_tokens: int,
+        on_error: Optional[OnError],
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("THREADLESS_API_KEY")
+        if not key:
+            raise ValueError("Threadless: pass api_key or set THREADLESS_API_KEY.")
+        self._api_key = key
+        url = base_url if base_url is not None else os.environ.get("THREADLESS_BASE_URL")
+        url = url if url is not None else DEFAULT_BASE_URL
+        self.base_url = url[:-1] if url.endswith("/") else url
+        self.timeout = timeout
+        self.tail_tokens = tail_tokens
+        self._on_error = on_error
+        #: Per memory: the last request's items, for when we cannot be reached.
+        self.tails: "OrderedDict[str, List[Raw]]" = OrderedDict()
+        self._lock = threading.Lock()
+
+    def _request(self, method: str, path: str, body: Any) -> Dict[str, Any]:
+        headers = {"authorization": f"Bearer {self._api_key}"}
+        kwargs: Dict[str, Any] = {
+            "method": method,
+            "url": f"{self.base_url}{path}",
+            "headers": headers,
+            "timeout": self.timeout,
+        }
+        if body is not None:
+            headers["content-type"] = "application/json"
+            kwargs["content"] = json.dumps(body, separators=(",", ":")).encode("utf-8")
+        return kwargs
+
+    @staticmethod
+    def _parse(response: httpx.Response) -> Any:
+        if response.status_code == 204:
+            return None
+        text = response.text
+        data = json.loads(text) if text else {}
+        if not response.is_success:
+            error = data.get("error") if isinstance(data, dict) else None
+            error = error if isinstance(error, dict) else {}
+            raise ThreadlessError(
+                response.status_code,
+                _or(error.get("code"), "internal"),
+                _or(error.get("message"), f"HTTP {response.status_code}"),
+                error.get("hint"),
+            )
+        return data
+
+    def _notify(self, error: BaseException, operation: str, memory_id: str) -> None:
+        if self._on_error is not None:
+            self._on_error(error, {"operation": operation, "memory_id": memory_id})
+
+    def _remember_tail(self, memory_id: str, items: List[Raw]) -> None:
+        trimmed = trim_tail(items, self.tail_tokens)
+        with self._lock:
+            self.tails.pop(memory_id, None)
+            self.tails[memory_id] = trimmed
+            while len(self.tails) > TAILS_KEPT:
+                self.tails.popitem(last=False)
+
+    def _forget_tail(self, memory_id: str) -> None:
+        with self._lock:
+            self.tails.pop(memory_id, None)
+
+    def _fallback(
+        self, format: Format, memory_id: str, new_messages: List[Raw], request: Raw
+    ) -> Raw:
+        """The request built from the local tail of recent turns."""
+        with self._lock:
+            tail = list(self.tails.get(memory_id, []))
+        instructions = [item for item in new_messages if is_instruction(item)]
+        items = trim_tail(
+            (instructions or [item for item in tail if is_instruction(item)])
+            + [item for item in tail if not is_instruction(item)]
+            + [item for item in new_messages if not is_instruction(item)],
+            self.tail_tokens,
+        )
+        self._remember_tail(memory_id, items)
+        rest = {
+            key: value
+            for key, value in request.items()
+            if key not in ("messages", "input", "previous_response_id", "store")
+        }
+        rest["input" if format == "responses" else "messages"] = items
+        return rest

threadlessai-0.1.0/src/threadlessai/_note_tool.py

@@ -0,0 +1,147 @@
+"""The note tool: the customer registers it like any tool. Nothing runs; the
+call is the note. When part of the history is leaving live context the
+request asks the model for its facts, and the model answers with one call.
+The facts reach us in the reply, so the handler only returns NOTE_RESULT.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, List, Literal, Optional, TypedDict
+
+Format = Literal["chat.completions", "responses"]
+
+NOTE_TOOL_NAME = "memory_note"
+
+NOTE_RESULT = "noted"
+
+NOTE_TOOL_DESCRIPTION = (
+    "Writes facts into this conversation's long-term memory. Nothing runs: the call itself is "
+    "the note. When the system asks for facts from history that is leaving live context, answer "
+    "with one call holding every fact: one entry per fact, a knowledge-graph triple readable on "
+    "its own, identifiers and the source's own terms verbatim. Once those turns leave, these "
+    "facts are what stays in view of them. When they hold nothing needed later, one entry with "
+    "an empty note."
+)
+
+NOTE_TOOL_PARAMETERS: Dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "notes": {
+            "type": "array",
+            "description": "Every fact being written, one entry each.",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "note": {
+                        "type": "string",
+                        "description": (
+                            "One fact, as a sentence readable on its own. Empty when the history "
+                            "leaving holds nothing needed later."
+                        ),
+                    },
+                    "subject": {
+                        "type": "string",
+                        "description": (
+                            "The triple's subject entity, resolved to its canonical name (entity "
+                            "resolution): the name earlier facts already use, else the most "
+                            "specific name in the conversation."
+                        ),
+                    },
+                    "object": {
+                        "type": "string",
+                        "description": (
+                            "The triple's object entity, resolved to its canonical name (entity "
+                            "resolution). The fact becomes the edge between subject and object "
+                            "in a knowledge graph."
+                        ),
+                    },
+                    "milestone": {
+                        "type": "boolean",
+                        "description": (
+                            "True when the fact says where the work stands (a milestone reached, "
+                            "a point of alignment, what is next or blocked)."
+                        ),
+                    },
+                },
+                "required": ["note", "subject", "object", "milestone"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    "required": ["notes"],
+    "additionalProperties": False,
+}
+
+
+def note_tool_definition(format: Format) -> Dict[str, Any]:
+    """The note tool as a tool definition for the given API."""
+    if format == "responses":
+        return {
+            "type": "function",
+            "name": NOTE_TOOL_NAME,
+            "description": NOTE_TOOL_DESCRIPTION,
+            "parameters": NOTE_TOOL_PARAMETERS,
+            "strict": True,
+        }
+    return {
+        "type": "function",
+        "function": {
+            "name": NOTE_TOOL_NAME,
+            "description": NOTE_TOOL_DESCRIPTION,
+            "parameters": NOTE_TOOL_PARAMETERS,
+            "strict": True,
+        },
+    }
+
+
+class NoteFact(TypedDict):
+    text: str
+    # Subject then object, as the model resolved them.
+    entities: List[str]
+    milestone: bool
+
+
+_WHITESPACE = re.compile(r"\s+")
+_BULLET = re.compile(r"^(?:[-*•]|[0-9]+[.)])\s+")
+
+
+def read_note_facts(args: Any) -> Optional[List[NoteFact]]:
+    """The facts one note call carries. Malformed entries are left out; None when it
+    carries no notes list."""
+    parsed = args
+    if isinstance(parsed, str):
+        try:
+            parsed = json.loads(parsed or "{}")
+        except ValueError:
+            return None
+    notes = parsed.get("notes") if isinstance(parsed, dict) else None
+    if not isinstance(notes, list):
+        return None
+    facts: List[NoteFact] = []
+    for entry in notes:
+        if not isinstance(entry, dict):
+            continue
+        note = entry.get("note")
+        if not isinstance(note, str):
+            continue
+        # The fact's two entities, subject then object; a note of several lines is several
+        # facts that share them.
+        cleaned = (
+            _WHITESPACE.sub(" ", entity).strip()
+            for entity in (entry.get("subject"), entry.get("object"))
+            if isinstance(entity, str)
+        )
+        entities: List[str] = list(dict.fromkeys(entity for entity in cleaned if entity))
+        milestone = entry.get("milestone") is True
+        for line in note.split("\n"):
+            text = _WHITESPACE.sub(" ", _BULLET.sub("", line.strip())).strip()
+            if text:
+                facts.append({"text": text, "entities": list(entities), "milestone": milestone})
+    return facts
+
+
+def is_note_call(name: Optional[str]) -> bool:
+    """Whether a tool call is to the note tool. Answer it with NOTE_RESULT."""
+    return name == NOTE_TOOL_NAME