llama-index-tools-pastdotdev 0.1.0__tar.gz

llama_index_tools_pastdotdev-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store

llama_index_tools_pastdotdev-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 past.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llama_index_tools_pastdotdev-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: llama-index-tools-pastdotdev
+Version: 0.1.0
+Summary: past dev tools for LlamaIndex agents: recall and ingest with the past dev Memory API
+Project-URL: Homepage, https://past.dev
+Project-URL: Documentation, https://past.dev/docs/memory-api/quickstart
+Project-URL: API reference, https://past.dev/docs/memory-api/api-reference
+Project-URL: Repository, https://github.com/pastdotdev/llama-index-pastdotdev
+Author-email: "past.dev" <louis@past.dev>
+Maintainer-email: "past.dev" <louis@past.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent tools,llama-index,llamaindex,memory,past dev,past.dev,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: llama-index-core<0.15,>=0.13.0
+Description-Content-Type: text/markdown
+
+# LlamaIndex Tools Integration: past dev
+
+past dev is a memory API for AI agents. This package gives a LlamaIndex agent
+two tools over [past dev](https://past.dev):
+
+- **`recall`**: a past dev **Recall**. The agent asks a question and gets the
+  ranked memory of the current user, with the date, the kind and the quoted
+  evidence of each entry.
+- **`ingest`**: a past dev **Ingest**. The agent keeps one piece of information
+  as a data point, so that a later recall can find it.
+
+## Install
+
+```bash
+pip install llama-index-tools-pastdotdev
+```
+
+## Get a key
+
+1. Sign up at [past.dev](https://past.dev) and open a project.
+2. Make a project API key. It starts with `past_sk_`.
+3. Set it in the environment as `PAST_API_KEY`, or give it to the spec as `api_key`.
+
+## Use
+
+```python
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.openai import OpenAI
+from llama_index.tools.pastdotdev import PastDevToolSpec
+
+past_dev = PastDevToolSpec(
+    identity=current_user.id,  # your id for the end user, from your own user record
+)
+
+agent = FunctionAgent(
+    tools=past_dev.to_tool_list(),
+    llm=OpenAI(model="gpt-4.1-mini"),
+    system_prompt="Recall what you know about the user before you answer.",
+)
+response = await agent.run("What did I decide about the launch date?")
+```
+
+### The identity
+
+past dev keeps memory per identity: your id for the end user. Recall needs an
+identity, and the first ingest for an identity creates it.
+
+Set `identity` in the `PastDevToolSpec` constructor, from your trigger or your
+user record. It is not a tool argument: the model cannot see it or change it.
+The same applies to `audience` and to the recall budget. Make one spec for
+each user.
+
+## The tools
+
+| Tool | Arguments the model gives | API call |
+| --- | --- | --- |
+| `recall` | `query` (required), `occurredFrom`, `occurredTo`, `sort` (`relevance` or `chronological`) | `POST /api/v1/recall` |
+| `ingest` | `content` (required), `timestamp` | `POST /api/v1/ingest` |
+
+The argument names are the API's own field names.
+
+## Parameters
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `identity` | (required) | Your id for the end user. |
+| `api_key` | `PAST_API_KEY` | A past dev project API key (`past_sk_...`). |
+| `api_host` | `PAST_API_HOST`, else `https://api.past.dev` | The API base URL. Change it only if you run past dev in your own cloud. |
+| `audience` | none | The audience slug for ingested memory. Without it, the memory is visible to the project. |
+| `level` | `low` (on the server) | The recall evidence budget: `low`, `medium`, `high` or `extra-high`. |
+| `max_tokens` | none | An explicit recall evidence budget in tokens. Use `level` or `max_tokens`, not both. |
+| `limit` | 100 (on the server) | The maximum number of recalled documents. |
+| `label` | `Saved by a LlamaIndex agent` | The label of each data point that the model ingests. |
+| `timeout` | `30` | The HTTP timeout in seconds. |
+| `http_client` | none | An `httpx.Client` to use, for example with a proxy. |
+
+## Credits
+
+Each recall and each ingest spends credits on your past dev plan. The agent
+decides when to call the tools, so tell it in the system prompt when to use them.
+
+## Errors
+
+An API error raises `PastDevError`, with the error `code`, the HTTP `status`,
+the message and the `X-Request-Id` of the request. The LlamaIndex agent gives
+the error to the model as the tool output. The spec retries a `429` once, after
+its `Retry-After` delay. It does not retry other errors, for example
+`402 out-of-credits` or a `400`.
+
+## Links
+
+- [Quickstart](https://past.dev/docs/memory-api/quickstart)
+- [API reference](https://past.dev/docs/memory-api/api-reference)
+- [LlamaIndex tools guide](https://developers.llamaindex.ai/python/framework/module_guides/deploying/agents/tools/)
+- A memory block for the same API: [`llama-index-memory-pastdotdev`](https://pypi.org/project/llama-index-memory-pastdotdev/)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

llama_index_tools_pastdotdev-0.1.0/README.md

@@ -0,0 +1,99 @@
+# LlamaIndex Tools Integration: past dev
+
+past dev is a memory API for AI agents. This package gives a LlamaIndex agent
+two tools over [past dev](https://past.dev):
+
+- **`recall`**: a past dev **Recall**. The agent asks a question and gets the
+  ranked memory of the current user, with the date, the kind and the quoted
+  evidence of each entry.
+- **`ingest`**: a past dev **Ingest**. The agent keeps one piece of information
+  as a data point, so that a later recall can find it.
+
+## Install
+
+```bash
+pip install llama-index-tools-pastdotdev
+```
+
+## Get a key
+
+1. Sign up at [past.dev](https://past.dev) and open a project.
+2. Make a project API key. It starts with `past_sk_`.
+3. Set it in the environment as `PAST_API_KEY`, or give it to the spec as `api_key`.
+
+## Use
+
+```python
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.openai import OpenAI
+from llama_index.tools.pastdotdev import PastDevToolSpec
+
+past_dev = PastDevToolSpec(
+    identity=current_user.id,  # your id for the end user, from your own user record
+)
+
+agent = FunctionAgent(
+    tools=past_dev.to_tool_list(),
+    llm=OpenAI(model="gpt-4.1-mini"),
+    system_prompt="Recall what you know about the user before you answer.",
+)
+response = await agent.run("What did I decide about the launch date?")
+```
+
+### The identity
+
+past dev keeps memory per identity: your id for the end user. Recall needs an
+identity, and the first ingest for an identity creates it.
+
+Set `identity` in the `PastDevToolSpec` constructor, from your trigger or your
+user record. It is not a tool argument: the model cannot see it or change it.
+The same applies to `audience` and to the recall budget. Make one spec for
+each user.
+
+## The tools
+
+| Tool | Arguments the model gives | API call |
+| --- | --- | --- |
+| `recall` | `query` (required), `occurredFrom`, `occurredTo`, `sort` (`relevance` or `chronological`) | `POST /api/v1/recall` |
+| `ingest` | `content` (required), `timestamp` | `POST /api/v1/ingest` |
+
+The argument names are the API's own field names.
+
+## Parameters
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `identity` | (required) | Your id for the end user. |
+| `api_key` | `PAST_API_KEY` | A past dev project API key (`past_sk_...`). |
+| `api_host` | `PAST_API_HOST`, else `https://api.past.dev` | The API base URL. Change it only if you run past dev in your own cloud. |
+| `audience` | none | The audience slug for ingested memory. Without it, the memory is visible to the project. |
+| `level` | `low` (on the server) | The recall evidence budget: `low`, `medium`, `high` or `extra-high`. |
+| `max_tokens` | none | An explicit recall evidence budget in tokens. Use `level` or `max_tokens`, not both. |
+| `limit` | 100 (on the server) | The maximum number of recalled documents. |
+| `label` | `Saved by a LlamaIndex agent` | The label of each data point that the model ingests. |
+| `timeout` | `30` | The HTTP timeout in seconds. |
+| `http_client` | none | An `httpx.Client` to use, for example with a proxy. |
+
+## Credits
+
+Each recall and each ingest spends credits on your past dev plan. The agent
+decides when to call the tools, so tell it in the system prompt when to use them.
+
+## Errors
+
+An API error raises `PastDevError`, with the error `code`, the HTTP `status`,
+the message and the `X-Request-Id` of the request. The LlamaIndex agent gives
+the error to the model as the tool output. The spec retries a `429` once, after
+its `Retry-After` delay. It does not retry other errors, for example
+`402 out-of-credits` or a `400`.
+
+## Links
+
+- [Quickstart](https://past.dev/docs/memory-api/quickstart)
+- [API reference](https://past.dev/docs/memory-api/api-reference)
+- [LlamaIndex tools guide](https://developers.llamaindex.ai/python/framework/module_guides/deploying/agents/tools/)
+- A memory block for the same API: [`llama-index-memory-pastdotdev`](https://pypi.org/project/llama-index-memory-pastdotdev/)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

llama_index_tools_pastdotdev-0.1.0/llama_index/tools/pastdotdev/__init__.py

@@ -0,0 +1,4 @@
+from llama_index.tools.pastdotdev.base import PastDevToolSpec
+from llama_index.tools.pastdotdev.client import PastDevError
+
+__all__ = ["PastDevToolSpec", "PastDevError"]

llama_index_tools_pastdotdev-0.1.0/llama_index/tools/pastdotdev/base.py

@@ -0,0 +1,128 @@
+"""past dev tool spec: Recall and Ingest as agent tools."""
+
+from typing import Literal, Optional
+
+import httpx
+from llama_index.core.tools.tool_spec.base import BaseToolSpec
+
+from llama_index.tools.pastdotdev.client import (
+    PastDevClient,
+    format_recall,
+    now_iso,
+)
+
+__version__ = "0.1.0"
+
+
+class PastDevToolSpec(BaseToolSpec):
+    """
+    past dev tools: recall and ingest.
+
+    The identity, the audience and the recall budget are fixed when you make
+    the spec, from your own user record. The model never sees them and cannot
+    change them: the tools take only the query or the content.
+
+    Args:
+        identity: Your id for the end user. The tools read and write as this identity.
+        api_key: A past dev project API key (past_sk_...). Defaults to PAST_API_KEY.
+        api_host: The API base URL. Defaults to PAST_API_HOST, else https://api.past.dev.
+        audience: The audience slug for ingested memory. Omit it for project-visible memory.
+        level: The recall evidence budget: low, medium, high or extra-high.
+        max_tokens: An explicit recall evidence budget in tokens. Send level or max_tokens, not both.
+        limit: The maximum number of recalled documents.
+        label: The label of each data point the model ingests.
+        timeout: The HTTP timeout in seconds.
+        http_client: An httpx.Client to use, for example with a proxy.
+
+    """
+
+    spec_functions = ["recall", "ingest"]
+
+    def __init__(
+        self,
+        identity: str,
+        api_key: Optional[str] = None,
+        api_host: Optional[str] = None,
+        audience: Optional[str] = None,
+        level: Optional[Literal["low", "medium", "high", "extra-high"]] = None,
+        max_tokens: Optional[int] = None,
+        limit: Optional[int] = None,
+        label: Optional[str] = "Saved by a LlamaIndex agent",
+        timeout: float = 30.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not identity or not identity.strip():
+            raise ValueError("identity is required: set it from your user record.")
+        if level is not None and max_tokens is not None:
+            raise ValueError("Set level or max_tokens, never both.")
+        self.identity = identity
+        self.audience = audience
+        self.level = level
+        self.max_tokens = max_tokens
+        self.limit = limit
+        self.label = label
+        self._client = PastDevClient(
+            api_key=api_key,
+            api_host=api_host,
+            timeout=timeout,
+            user_agent=f"llama-index-tools-pastdotdev/{__version__}",
+            http_client=http_client,
+        )
+
+    def recall(
+        self,
+        query: str,
+        occurredFrom: Optional[str] = None,
+        occurredTo: Optional[str] = None,
+        sort: Optional[Literal["relevance", "chronological"]] = None,
+    ) -> str:
+        """
+        Recall what past dev remembers about the current user: earlier conversations, facts, preferences and decisions.
+
+        Use it before you answer a question that may depend on what happened before.
+        Each result has a rank, a date and a kind; evidence lines quote the original source.
+
+        Args:
+            query (str): A natural-language question, for example "What did the user decide about the launch date?".
+            occurredFrom (Optional[str]): Only memory that occurred at or after this ISO 8601 date-time.
+            occurredTo (Optional[str]): Only memory that occurred at or before this ISO 8601 date-time.
+            sort (Optional[str]): "relevance" (the default) or "chronological" (oldest first).
+
+        """
+        response = self._client.recall(
+            query=query,
+            identity=self.identity,
+            limit=self.limit,
+            level=self.level,
+            max_tokens=self.max_tokens,
+            occurred_from=occurredFrom,
+            occurred_to=occurredTo,
+            sort=sort,
+        )
+        return format_recall(response) or "past dev has no memory that matches this query."
+
+    def ingest(self, content: str, timestamp: Optional[str] = None) -> str:
+        """
+        Ingest one piece of information into past dev, so that a later recall can find it.
+
+        Use it when the user tells you something worth keeping: a fact, a preference or a decision.
+        Write the content as a complete, self-contained statement.
+
+        Args:
+            content (str): The text to keep, for example "The user prefers email to phone calls.".
+            timestamp (Optional[str]): When it occurred, as an ISO 8601 date-time. Defaults to now.
+
+        """
+        result = self._client.ingest(
+            content=content,
+            identity=self.identity,
+            timestamp=timestamp or now_iso(),
+            audience=self.audience,
+            label=self.label,
+            metadata={"source": "llama-index"},
+        )
+        result = result or {}
+        source_id = result.get("sourceId")
+        if result.get("unchanged"):
+            return f"past dev already had this data point (source id {source_id})."
+        return f"past dev accepted the data point (source id {source_id}, {result.get('status', 'queued')})."

llama_index_tools_pastdotdev-0.1.0/llama_index/tools/pastdotdev/client.py

@@ -0,0 +1,311 @@
+"""A small HTTP client for the past dev Memory API.
+
+This file is the same in llama-index-memory-pastdotdev and
+llama-index-tools-pastdotdev, so that each package installs without the other.
+"""
+
+import asyncio
+import os
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+DEFAULT_API_HOST = "https://api.past.dev"
+API_KEY_ENV = "PAST_API_KEY"
+API_HOST_ENV = "PAST_API_HOST"
+RECALL_LEVELS = ("low", "medium", "high", "extra-high")
+RECALL_SORTS = ("relevance", "chronological")
+
+# A 429 is retried once, after the Retry-After delay, when that delay is short.
+MAX_RETRY_AFTER_SECONDS = 30.0
+
+
+class PastDevError(Exception):
+    """An error response from the past dev Memory API."""
+
+    def __init__(
+        self,
+        code: str,
+        status: int,
+        message: Optional[str] = None,
+        request_id: Optional[str] = None,
+        data: Any = None,
+    ) -> None:
+        self.code = code
+        self.status = status
+        self.message = message
+        self.request_id = request_id
+        self.data = data
+        text = f"past dev error {code} (HTTP {status})"
+        if message:
+            text += f": {message}"
+        if request_id:
+            text += f" [request id {request_id}]"
+        super().__init__(text)
+
+
+def resolve_api_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get(API_KEY_ENV)
+    if not key:
+        raise ValueError(
+            "past dev needs a project API key: pass api_key or set the "
+            f"{API_KEY_ENV} environment variable."
+        )
+    return key
+
+
+def resolve_api_host(api_host: Optional[str]) -> str:
+    host = api_host or os.environ.get(API_HOST_ENV) or DEFAULT_API_HOST
+    return host.rstrip("/")
+
+
+def to_iso(value: Any) -> Optional[str]:
+    """Return an ISO 8601 string for a datetime or a string, else None."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value.isoformat()
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def build_recall_body(
+    query: str,
+    identity: str,
+    limit: Optional[int] = None,
+    level: Optional[str] = None,
+    max_tokens: Optional[int] = None,
+    query_timestamp: Optional[str] = None,
+    occurred_from: Optional[str] = None,
+    occurred_to: Optional[str] = None,
+    sort: Optional[str] = None,
+) -> Dict[str, Any]:
+    if level is not None and max_tokens is not None:
+        raise ValueError("Send level or max_tokens to recall, never both.")
+    if level is not None and level not in RECALL_LEVELS:
+        raise ValueError(f"level must be one of {', '.join(RECALL_LEVELS)}.")
+    if sort is not None and sort not in RECALL_SORTS:
+        raise ValueError(f"sort must be one of {', '.join(RECALL_SORTS)}.")
+    body: Dict[str, Any] = {"query": query, "identity": identity}
+    optional = {
+        "limit": limit,
+        "level": level,
+        "maxTokens": max_tokens,
+        "queryTimestamp": query_timestamp,
+        "occurredFrom": occurred_from,
+        "occurredTo": occurred_to,
+        "sort": sort,
+    }
+    body.update({key: value for key, value in optional.items() if value is not None})
+    return body
+
+
+def build_ingest_body(
+    content: str,
+    identity: str,
+    timestamp: Optional[str] = None,
+    source_id: Optional[str] = None,
+    audience: Optional[str] = None,
+    label: Optional[str] = None,
+    metadata: Any = None,
+    idempotency_key: Optional[str] = None,
+) -> Dict[str, Any]:
+    if not content or not content.strip():
+        raise ValueError("past dev refuses empty content: send some text to ingest.")
+    body: Dict[str, Any] = {"content": content, "identity": identity}
+    optional = {
+        "timestamp": timestamp,
+        "id": source_id,
+        "audience": audience,
+        "label": label,
+        "metadata": metadata,
+        "idempotencyKey": idempotency_key,
+    }
+    body.update({key: value for key, value in optional.items() if value is not None})
+    return body
+
+
+def format_recall(response: Dict[str, Any]) -> str:
+    """Render a recall response as plain text for a model to read."""
+    results = response.get("results") or []
+    return "\n\n".join(format_recall_results(results))
+
+
+def format_recall_results(results: List[Dict[str, Any]]) -> List[str]:
+    rendered = []
+    for result in results:
+        content = (result.get("content") or "").strip()
+        if not content:
+            continue
+        artifact = result.get("artifact") or {}
+        kind = artifact.get("kind") or "memory"
+        head = (
+            f"[{result.get('rank', len(rendered) + 1)}] {_date(result.get('occurredAt'))} · {kind}"
+        )
+        superseded = artifact.get("supersededAt")
+        if superseded:
+            head += f" · superseded {_date(superseded)}"
+        lines = [head, content]
+        for source in result.get("sources") or []:
+            where = source.get("label") or source.get("sourceId") or "source"
+            when = _date(source.get("occurredAt"))
+            for excerpt in source.get("excerpts") or []:
+                lines.append(f'  evidence ({where}, {when}): "{excerpt}"')
+        rendered.append("\n".join(lines))
+    return rendered
+
+
+def _date(value: Optional[str]) -> str:
+    return value[:10] if isinstance(value, str) else "undated"
+
+
+class _Base:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_host: Optional[str] = None,
+        timeout: float = 30.0,
+        user_agent: str = "llama-index-pastdotdev",
+    ) -> None:
+        self.api_host = resolve_api_host(api_host)
+        self._headers = {
+            "Authorization": f"Bearer {resolve_api_key(api_key)}",
+            "Accept": "application/json",
+            "User-Agent": user_agent,
+        }
+        self.timeout = timeout
+
+    def _url(self, path: str) -> str:
+        return f"{self.api_host}{path}"
+
+    @staticmethod
+    def _retry_delay(response: httpx.Response) -> Optional[float]:
+        if response.status_code != 429:
+            return None
+        header = response.headers.get("Retry-After", "1")
+        try:
+            delay = float(header)
+        except ValueError:
+            return None
+        return delay if 0 <= delay <= MAX_RETRY_AFTER_SECONDS else None
+
+    @staticmethod
+    def _result(response: httpx.Response) -> Any:
+        if response.is_success:
+            return response.json() if response.content else None
+        request_id = response.headers.get("X-Request-Id")
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        if isinstance(body, dict) and body.get("code"):
+            raise PastDevError(
+                code=str(body["code"]),
+                status=int(body.get("status") or response.status_code),
+                message=body.get("debugMessage"),
+                request_id=request_id,
+                data=body.get("data"),
+            )
+        raise PastDevError(
+            code="http-error",
+            status=response.status_code,
+            message=response.text[:200] or None,
+            request_id=request_id,
+        )
+
+
+class PastDevClient(_Base):
+    """Synchronous client."""
+
+    def __init__(
+        self, *args: Any, http_client: Optional[httpx.Client] = None, **kwargs: Any
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._http = http_client or httpx.Client(timeout=self.timeout)
+
+    def request(self, method: str, path: str, json: Any = None, params: Any = None) -> Any:
+        for attempt in range(2):
+            response = self._http.request(
+                method, self._url(path), json=json, params=params, headers=self._headers
+            )
+            delay = self._retry_delay(response)
+            if delay is None or attempt == 1:
+                return self._result(response)
+            time.sleep(delay)
+        return None  # pragma: no cover
+
+    def ingest(self, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("POST", "/api/v1/ingest", json=build_ingest_body(**kwargs))
+
+    def recall(self, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("POST", "/api/v1/recall", json=build_recall_body(**kwargs))
+
+    def delete_data_point(self, source_id: str) -> Dict[str, Any]:
+        return self.request("DELETE", f"/api/v1/data-points/{_path(source_id)}")
+
+    def list_audiences(self) -> Dict[str, Any]:
+        """List the project's audiences. It costs no credits, so it also tests a key."""
+        return self.request("GET", "/api/v1/audiences")
+
+    def list_identities(self, after: Optional[str] = None) -> Dict[str, Any]:
+        return self.request("GET", "/api/v1/identities", params={"after": after} if after else None)
+
+    def close(self) -> None:
+        self._http.close()
+
+
+class AsyncPastDevClient(_Base):
+    """Asynchronous client."""
+
+    def __init__(
+        self, *args: Any, http_client: Optional[httpx.AsyncClient] = None, **kwargs: Any
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._http = http_client or httpx.AsyncClient(timeout=self.timeout)
+
+    async def request(self, method: str, path: str, json: Any = None, params: Any = None) -> Any:
+        for attempt in range(2):
+            response = await self._http.request(
+                method, self._url(path), json=json, params=params, headers=self._headers
+            )
+            delay = self._retry_delay(response)
+            if delay is None or attempt == 1:
+                return self._result(response)
+            await asyncio.sleep(delay)
+        return None  # pragma: no cover
+
+    async def ingest(self, **kwargs: Any) -> Dict[str, Any]:
+        return await self.request("POST", "/api/v1/ingest", json=build_ingest_body(**kwargs))
+
+    async def recall(self, **kwargs: Any) -> Dict[str, Any]:
+        return await self.request("POST", "/api/v1/recall", json=build_recall_body(**kwargs))
+
+    async def delete_data_point(self, source_id: str) -> Dict[str, Any]:
+        return await self.request("DELETE", f"/api/v1/data-points/{_path(source_id)}")
+
+    async def list_audiences(self) -> Dict[str, Any]:
+        """List the project's audiences. It costs no credits, so it also tests a key."""
+        return await self.request("GET", "/api/v1/audiences")
+
+    async def list_identities(self, after: Optional[str] = None) -> Dict[str, Any]:
+        return await self.request(
+            "GET", "/api/v1/identities", params={"after": after} if after else None
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+
+def _path(segment: str) -> str:
+    from urllib.parse import quote
+
+    return quote(segment, safe="")

llama_index_tools_pastdotdev-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=6.1.1",
+    "ruff>=0.11",
+]
+
+[project]
+name = "llama-index-tools-pastdotdev"
+version = "0.1.0"
+description = "past dev tools for LlamaIndex agents: recall and ingest with the past dev Memory API"
+authors = [{name = "past.dev", email = "louis@past.dev"}]
+maintainers = [{name = "past.dev", email = "louis@past.dev"}]
+requires-python = ">=3.10,<4.0"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["llama-index", "llamaindex", "past dev", "past.dev", "tools", "agent tools", "memory"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "llama-index-core>=0.13.0,<0.15",
+    "httpx>=0.27,<1",
+]
+
+[project.urls]
+Homepage = "https://past.dev"
+Documentation = "https://past.dev/docs/memory-api/quickstart"
+"API reference" = "https://past.dev/docs/memory-api/api-reference"
+Repository = "https://github.com/pastdotdev/llama-index-pastdotdev"
+
+[tool.hatch.build.targets.sdist]
+include = ["llama_index/", "tests/", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+include = ["llama_index/"]
+
+[tool.llamahub]
+contains_example = false
+import_path = "llama_index.tools.pastdotdev"
+
+[tool.llamahub.class_authors]
+PastDevToolSpec = "pastdotdev"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["live: calls the real past dev API; skipped unless PAST_API_KEY is set"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+# The formatter wraps code; long lines left are docstrings, which the model reads.
+ignore = ["E501"]

llama_index_tools_pastdotdev-0.1.0/tests/test_client.py

@@ -0,0 +1,78 @@
+import json
+from typing import List
+
+import httpx
+import pytest
+
+from llama_index.tools.pastdotdev.client import (
+    AsyncPastDevClient,
+    PastDevClient,
+    build_recall_body,
+)
+
+
+def recorder(requests: List[httpx.Request]) -> httpx.MockTransport:
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.method == "DELETE":
+            return httpx.Response(202, json={"operationId": "op-1", "ids": ["chat/1"]})
+        if request.url.path == "/api/v1/identities":
+            return httpx.Response(200, json={"identities": [], "hasMore": False, "endCursor": None})
+        return httpx.Response(200, json={"audiences": []})
+
+    return httpx.MockTransport(handler)
+
+
+def test_sync_client_paths() -> None:
+    requests: List[httpx.Request] = []
+    client = PastDevClient(
+        api_key="past_sk_test", http_client=httpx.Client(transport=recorder(requests))
+    )
+    assert client.delete_data_point("chat/1")["ids"] == ["chat/1"]
+    assert client.list_audiences() == {"audiences": []}
+    assert client.list_identities(after="cursor-1")["hasMore"] is False
+    client.close()
+    assert [(r.method, r.url.raw_path.decode()) for r in requests] == [
+        ("DELETE", "/api/v1/data-points/chat%2F1"),
+        ("GET", "/api/v1/audiences"),
+        ("GET", "/api/v1/identities?after=cursor-1"),
+    ]
+
+
+async def test_async_client_paths() -> None:
+    requests: List[httpx.Request] = []
+    client = AsyncPastDevClient(
+        api_key="past_sk_test", http_client=httpx.AsyncClient(transport=recorder(requests))
+    )
+    await client.delete_data_point("chat/1")
+    await client.list_audiences()
+    await client.list_identities()
+    await client.aclose()
+    assert [(r.method, r.url.raw_path.decode()) for r in requests] == [
+        ("DELETE", "/api/v1/data-points/chat%2F1"),
+        ("GET", "/api/v1/audiences"),
+        ("GET", "/api/v1/identities"),
+    ]
+
+
+def test_recall_body_uses_api_keys() -> None:
+    body = build_recall_body(
+        query="q",
+        identity="u",
+        max_tokens=500,
+        query_timestamp="2026-10-01T00:00:00Z",
+        occurred_to="2026-09-01T00:00:00Z",
+        sort="chronological",
+    )
+    assert json.loads(json.dumps(body)) == {
+        "query": "q",
+        "identity": "u",
+        "maxTokens": 500,
+        "queryTimestamp": "2026-10-01T00:00:00Z",
+        "occurredTo": "2026-09-01T00:00:00Z",
+        "sort": "chronological",
+    }
+    with pytest.raises(ValueError):
+        build_recall_body(query="q", identity="u", level="huge")
+    with pytest.raises(ValueError):
+        build_recall_body(query="q", identity="u", sort="random")

llama_index_tools_pastdotdev-0.1.0/tests/test_live.py

@@ -0,0 +1,25 @@
+"""One smoke test against the real past dev API.
+
+It is skipped unless PAST_API_KEY is set. It spends a few credits: one recall.
+"""
+
+import os
+
+import pytest
+
+from llama_index.tools.pastdotdev import PastDevToolSpec
+
+pytestmark = [
+    pytest.mark.live,
+    pytest.mark.skipif(not os.environ.get("PAST_API_KEY"), reason="PAST_API_KEY is not set"),
+]
+
+
+def test_live_recall_tool() -> None:
+    spec = PastDevToolSpec(identity="llama-index-smoke-test")
+    # The connection test: listing audiences costs no credits.
+    assert isinstance(spec._client.list_audiences()["audiences"], list)
+
+    tools = {tool.metadata.name: tool for tool in spec.to_tool_list()}
+    output = tools["recall"](query="What is my favourite colour?")
+    assert isinstance(output.content, str) and output.content

llama_index_tools_pastdotdev-0.1.0/tests/test_tools_pastdotdev.py

@@ -0,0 +1,209 @@
+import json
+from typing import Any, Callable, Dict, List
+
+import httpx
+import pytest
+from llama_index.core.tools.tool_spec.base import BaseToolSpec
+
+from llama_index.tools.pastdotdev import PastDevError, PastDevToolSpec
+
+KEY = "past_sk_test"
+
+RECALL_RESPONSE = {
+    "asOf": "2026-10-16T12:00:00Z",
+    "usedEvidenceTokens": 42,
+    "results": [
+        {
+            "id": "7f1c3a4e-0000-4000-8000-000000000001",
+            "rank": 1,
+            "occurredAt": "2026-10-01T09:00:00Z",
+            "content": "Ada prefers email to phone calls.",
+            "artifact": {
+                "id": "7f1c3a4e-0000-4000-8000-000000000001",
+                "kind": "observation",
+                "occurredAt": "2026-10-01T09:00:00Z",
+            },
+            "sources": [
+                {
+                    "sourceId": "chat-1",
+                    "occurredAt": "2026-10-01T09:00:00Z",
+                    "excerpts": ["please email me, never call"],
+                }
+            ],
+        }
+    ],
+}
+
+INGEST_RESPONSE = {
+    "projectId": 1,
+    "ingestionId": "7f1c3a4e-0000-4000-8000-0000000000aa",
+    "sourceId": "abc",
+    "status": "queued",
+}
+
+
+class FakeApi:
+    def __init__(self, handler: Callable[[httpx.Request], httpx.Response]) -> None:
+        self.handler = handler
+        self.requests: List[httpx.Request] = []
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        return self.handler(request)
+
+    def bodies(self, path: str) -> List[Dict[str, Any]]:
+        return [json.loads(r.content) for r in self.requests if r.url.path == path]
+
+
+def default_handler(request: httpx.Request) -> httpx.Response:
+    if request.url.path == "/api/v1/recall":
+        return httpx.Response(200, json=RECALL_RESPONSE)
+    if request.url.path == "/api/v1/ingest":
+        return httpx.Response(202, json=INGEST_RESPONSE)
+    return httpx.Response(404, json={"code": "not-found", "status": 404})
+
+
+def make_spec(api: FakeApi, **kwargs: Any) -> PastDevToolSpec:
+    kwargs.setdefault("api_key", KEY)
+    kwargs.setdefault("identity", "user-ada")
+    return PastDevToolSpec(http_client=httpx.Client(transport=httpx.MockTransport(api)), **kwargs)
+
+
+def test_is_a_tool_spec() -> None:
+    names = [b.__name__ for b in PastDevToolSpec.__mro__]
+    assert BaseToolSpec.__name__ in names
+    assert PastDevToolSpec.spec_functions == ["recall", "ingest"]
+
+
+def test_requires_identity() -> None:
+    with pytest.raises(ValueError):
+        make_spec(FakeApi(default_handler), identity="")
+
+
+def test_requires_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("PAST_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="PAST_API_KEY"):
+        PastDevToolSpec(identity="user-ada")
+
+
+def test_refuses_level_and_max_tokens_together() -> None:
+    with pytest.raises(ValueError):
+        make_spec(FakeApi(default_handler), level="low", max_tokens=100)
+
+
+def test_model_cannot_choose_identity_or_audience() -> None:
+    tools = make_spec(FakeApi(default_handler)).to_tool_list()
+    assert [tool.metadata.name for tool in tools] == ["recall", "ingest"]
+    for tool in tools:
+        properties = tool.metadata.get_parameters_dict()["properties"]
+        assert "identity" not in properties
+        assert "audience" not in properties
+    recall, ingest = tools
+    assert set(recall.metadata.get_parameters_dict()["properties"]) == {
+        "query",
+        "occurredFrom",
+        "occurredTo",
+        "sort",
+    }
+    assert recall.metadata.get_parameters_dict()["required"] == ["query"]
+    assert set(ingest.metadata.get_parameters_dict()["properties"]) == {"content", "timestamp"}
+
+
+def test_recall_tool_sends_fixed_identity_and_renders_results() -> None:
+    api = FakeApi(default_handler)
+    spec = make_spec(api, identity="user-ada", level="high", limit=10)
+    recall = spec.to_tool_list()[0]
+    output = recall(query="How should I contact Ada?", occurredFrom="2026-01-01T00:00:00Z")
+    assert api.bodies("/api/v1/recall") == [
+        {
+            "query": "How should I contact Ada?",
+            "identity": "user-ada",
+            "limit": 10,
+            "level": "high",
+            "occurredFrom": "2026-01-01T00:00:00Z",
+        }
+    ]
+    assert api.requests[0].headers["Authorization"] == f"Bearer {KEY}"
+    assert "Ada prefers email to phone calls." in output.content
+    assert '"please email me, never call"' in output.content
+
+
+def test_recall_with_no_results_says_so() -> None:
+    api = FakeApi(
+        lambda request: httpx.Response(
+            200, json={"asOf": "2026-10-16T12:00:00Z", "usedEvidenceTokens": 0, "results": []}
+        )
+    )
+    assert "no memory" in make_spec(api).recall(query="Anything?")
+
+
+def test_ingest_tool_sends_content_with_fixed_identity_and_audience() -> None:
+    api = FakeApi(default_handler)
+    spec = make_spec(api, audience="support-team", api_host="https://memory.example.com/")
+    result = spec.ingest(content="Ada prefers email.", timestamp="2026-10-01T09:00:00Z")
+    assert api.requests[0].url.host == "memory.example.com"
+    assert api.bodies("/api/v1/ingest") == [
+        {
+            "content": "Ada prefers email.",
+            "identity": "user-ada",
+            "timestamp": "2026-10-01T09:00:00Z",
+            "audience": "support-team",
+            "label": "Saved by a LlamaIndex agent",
+            "metadata": {"source": "llama-index"},
+        }
+    ]
+    assert "source id abc" in result
+
+
+def test_ingest_unchanged_says_so() -> None:
+    api = FakeApi(lambda request: httpx.Response(200, json={**INGEST_RESPONSE, "unchanged": True}))
+    assert "already had" in make_spec(api).ingest(content="Ada prefers email.")
+
+
+def test_ingest_refuses_empty_content() -> None:
+    api = FakeApi(default_handler)
+    with pytest.raises(ValueError):
+        make_spec(api).ingest(content="   ")
+    assert api.requests == []
+
+
+def test_bad_request_is_raised_and_not_retried() -> None:
+    api = FakeApi(
+        lambda request: httpx.Response(
+            400,
+            json={
+                "code": "recall-range-invalid",
+                "status": 400,
+                "debugMessage": "Start after end.",
+            },
+            headers={"X-Request-Id": "req-9"},
+        )
+    )
+    with pytest.raises(PastDevError) as caught:
+        make_spec(api).recall(query="x", occurredFrom="2026-02-01", occurredTo="2026-01-01")
+    assert caught.value.code == "recall-range-invalid"
+    assert "req-9" in str(caught.value)
+    assert len(api.requests) == 1
+
+
+def test_rate_limit_is_retried_once() -> None:
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(
+                429, json={"code": "rate-limited", "status": 429}, headers={"Retry-After": "0"}
+            )
+        return httpx.Response(202, json=INGEST_RESPONSE)
+
+    api = FakeApi(handler)
+    assert "accepted" in make_spec(api).ingest(content="Ada prefers email.")
+    assert len(api.requests) == 2
+
+
+async def test_tools_work_async() -> None:
+    api = FakeApi(default_handler)
+    recall = make_spec(api).to_tool_list()[0]
+    output = await recall.acall(query="How should I contact Ada?")
+    assert "Ada prefers email" in output.content